feat: add TCP transport (--tcp) to worker

Expose the raw Arrow-IPC TCP transport from vgi-rpc-java
(TcpSocketTransport) through the worker:

- Worker.runTcp(host, port, idleTimeoutMs) serves via
  TcpSocketTransport.serveForever and prints the TCP:<host>:<port>
  launcher discovery line once bound (actual port, so ephemeral
  port==0 binds are discoverable).
- Worker.runFromArgs and the example worker's runWorker accept
  --tcp [HOST:]PORT (host defaults to 127.0.0.1), sharing
  Worker.parseTcpAddr.

Raw TCP framing carries no auth/encryption (loopback/trusted
networks only); HTTP remains the transport for untrusted networks.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: rustyconover

needs

@@ -0,0 +1 @@
+NO - new release

vgi-example-worker/src/main/java/farm/query/vgi/example/Main.java

@@ -1100,13 +1100,15 @@ private static void runWorker(Worker w, String[] args) {
         String host = "127.0.0.1";
         int port = 0;
         String unixSocket = null;
+        String tcpAddr = null;
         long idleTimeoutMs = 0;
         for (int i = 0; i < args.length; i++) {
             switch (args[i]) {
                 case "--http" -> http = true;
                 case "--host" -> host = args[++i];
                 case "--port" -> port = Integer.parseInt(args[++i]);
                 case "--unix" -> unixSocket = args[++i];
+                case "--tcp" -> tcpAddr = args[++i];
                 case "--idle-timeout" ->
                         idleTimeoutMs = (long) (Double.parseDouble(args[++i]) * 1000.0);
                 // Launcher cache-key / fixture-parity flags. The vgi-python
@@ -1123,6 +1125,11 @@ private static void runWorker(Worker w, String[] args) {
         if (unixSocket != null) {
             try { w.runUnixSocket(java.nio.file.Path.of(unixSocket), idleTimeoutMs); }
             catch (Exception e) { e.printStackTrace(); System.exit(1); }
+        } else if (tcpAddr != null) {
+            try {
+                Worker.TcpAddr a = Worker.parseTcpAddr(tcpAddr);
+                w.runTcp(a.host(), a.port(), idleTimeoutMs);
+            } catch (Exception e) { e.printStackTrace(); System.exit(1); }
         } else if (http) {
             try { w.runHttp(buildHttpConfig(host, port)); }
             catch (Exception e) { e.printStackTrace(); System.exit(1); }

vgi/src/main/java/farm/query/vgi/Worker.java

@@ -13,6 +13,7 @@
 import farm.query.vgirpc.RpcServer;
 import farm.query.vgirpc.http.HttpServer;
 import farm.query.vgirpc.transport.StdioTransport;
+import farm.query.vgirpc.transport.TcpSocketTransport;
 import farm.query.vgirpc.transport.UnixSocketTransport;
 
 import java.io.IOException;
@@ -707,6 +708,56 @@ public void runUnixSocket(Path socketPath, long idleTimeoutMs) throws IOExceptio
         UnixSocketTransport.serveForever(socketPath, buildServer(false), idleTimeoutMs);
     }
 
+    /**
+     * Block accepting TCP connections on {@code host}:{@code port}, dispatching
+     * each client on a virtual thread, implementing the VGI launcher protocol:
+     * the worker prints {@code TCP:<host>:<port>\n} to stdout once the listener
+     * is bound (the actual port, so {@code port == 0} ephemeral binds are
+     * discoverable), then serves until killed or the idle watchdog fires.
+     *
+     * <p>Raw TCP framing carries <strong>no authentication or encryption</strong>
+     * — bind it to loopback / a trusted network only; use {@link #runHttp} for
+     * untrusted networks.
+     *
+     * @param host          bind host ({@code "127.0.0.1"} for loopback)
+     * @param port          bind port; {@code 0} selects a free port
+     * @param idleTimeoutMs idle watchdog in milliseconds; {@code <= 0} disables it
+     * @throws IOException if the socket cannot be bound or served
+     */
+    public void runTcp(String host, int port, long idleTimeoutMs) throws IOException {
+        TcpSocketTransport.serveForever(host, port, buildServer(false), idleTimeoutMs,
+                (boundHost, boundPort) -> {
+                    System.out.println("TCP:" + boundHost + ":" + boundPort);
+                    System.out.flush();
+                });
+    }
+
+    /**
+     * Parsed {@code [HOST:]PORT} TCP bind spec. Host defaults to loopback.
+     *
+     * @param host bind host
+     * @param port bind port ({@code 0} = ephemeral)
+     */
+    public record TcpAddr(String host, int port) {}
+
+    /**
+     * Parse a {@code [HOST:]PORT} TCP bind spec as accepted by {@code --tcp}.
+     * A bare {@code PORT} binds {@code 127.0.0.1}; an empty host (leading
+     * {@code ":"}) also defaults to loopback.
+     *
+     * @param spec the {@code [HOST:]PORT} string
+     * @return the parsed host/port
+     */
+    public static TcpAddr parseTcpAddr(String spec) {
+        int idx = spec.lastIndexOf(':');
+        if (idx >= 0) {
+            String h = spec.substring(0, idx);
+            return new TcpAddr(h.isEmpty() ? "127.0.0.1" : h,
+                    Integer.parseInt(spec.substring(idx + 1)));
+        }
+        return new TcpAddr("127.0.0.1", Integer.parseInt(spec));
+    }
+
     /**
      * Run as an HTTP server bound to {@code host}/{@code port}, blocking until shutdown.
      *
@@ -723,8 +774,9 @@ public void runHttp(String host, int port) throws Exception {
      * the four flags every VGI worker accepts and runs the matching transport:
      * <ul>
      *   <li>{@code --unix <path>}: AF_UNIX socket (launcher protocol)
+     *   <li>{@code --tcp [<host>:]<port>}: TCP socket (launcher protocol)
      *   <li>{@code --http} with optional {@code --host}, {@code --port}: HTTP
-     *   <li>{@code --idle-timeout <seconds>}: passed to {@code runUnixSocket}
+     *   <li>{@code --idle-timeout <seconds>}: passed to {@code runUnixSocket} / {@code runTcp}
      *   <li>(default): stdio
      * </ul>
      * Also honours {@code VGI_WORKER_STDERR}: redirects {@link System#err} to
@@ -752,13 +804,15 @@ public void runFromArgs(String[] args,
         String host = "127.0.0.1";
         int port = 0;
         String unixSocket = null;
+        String tcpAddr = null;
         long idleTimeoutMs = 0;
         for (int i = 0; i < args.length; i++) {
             switch (args[i]) {
                 case "--http" -> http = true;
                 case "--host" -> host = args[++i];
                 case "--port" -> port = Integer.parseInt(args[++i]);
                 case "--unix" -> unixSocket = args[++i];
+                case "--tcp" -> tcpAddr = args[++i];
                 case "--idle-timeout" -> idleTimeoutMs =
                         (long) (Double.parseDouble(args[++i]) * 1000.0);
                 default -> { System.err.println("unknown arg: " + args[i]); System.exit(2); }
@@ -767,6 +821,9 @@ public void runFromArgs(String[] args,
         try {
             if (unixSocket != null) {
                 runUnixSocket(Path.of(unixSocket), idleTimeoutMs);
+            } else if (tcpAddr != null) {
+                TcpAddr a = parseTcpAddr(tcpAddr);
+                runTcp(a.host(), a.port(), idleTimeoutMs);
             } else if (http) {
                 HttpServer.Config.Builder b = HttpServer.Config.builder().host(host).port(port);
                 if (httpCustomizer != null) b = httpCustomizer.apply(b);