zcode-acp-server 0.2.0 → 0.3.0

package/dist/remote/broadcast.js

@@ -0,0 +1,121 @@
+/**
+ * Multi-client broadcast layer for remote access.
+ *
+ * The bridge historically served ONE ACP client (the editor over stdio). With
+ * remote access enabled, additional clients attach over WebSocket; every
+ * agent-originated message must reach all of them. This module owns the client
+ * registry and a stable proxy that quacks like an `AgentContext`:
+ *
+ * - `notify` fans out to every client; a single dead/slow client is warned
+ *   about and never fails the others.
+ * - `request` (permission / elicitation) is sent to every client and the FIRST
+ *   response wins. Losers are aborted via `cancellationSignal`, which makes
+ *   the SDK emit `$/cancel_request` so the losing editor dismisses its dialog
+ *   (verified against Zed's ACP client).
+ *
+ * Loser promises settle late (the peer answers the cancellation eventually) —
+ * every raced promise carries a no-op catch so late settlements can't surface
+ * as unhandledRejection (Node ≥15 crashes on those by default).
+ */
+import { warn } from "../utils.js";
+/**
+ * Track every connection opened on the app (stdio editor + remote WebSocket)
+ * in the registry, removing each on close. Wired once by the entry point
+ * BEFORE `connect()` so the stdio connection is captured too.
+ */
+export function trackConnections(app, clients) {
+    app.onConnect((conn) => {
+        clients.add(conn.client);
+        void conn.closed.then(() => clients.remove(conn.client));
+    });
+}
+/**
+ * Registry of connected ACP clients (stdio editor + remote WebSocket clients).
+ * Membership is managed by the entry point via the SDK's per-connection
+ * lifecycle; the broadcast proxy reads membership live on every call.
+ */
+export class ClientRegistry {
+    clients = new Set();
+    proxy = null;
+    add(cx) {
+        this.clients.add(cx);
+    }
+    remove(cx) {
+        this.clients.delete(cx);
+    }
+    get size() {
+        return this.clients.size;
+    }
+    /** Stable broadcast proxy satisfying the `AgentContext` call surface. */
+    broadcast() {
+        if (!this.proxy)
+            this.proxy = createBroadcastProxy(this);
+        return this.proxy;
+    }
+    snapshot() {
+        return Array.from(this.clients);
+    }
+}
+/** Build the stable proxy once per registry (module factory: no `this` alias). */
+function createBroadcastProxy(registry) {
+    const proxy = Object.create(null);
+    proxy.notify = (method, params) => notifyAll(registry, method, params);
+    proxy.request = (method, params, options) => requestAny(registry, method, params, options);
+    return proxy;
+}
+async function notifyAll(registry, method, params) {
+    const results = await Promise.allSettled(registry.snapshot().map((cx) => cx.notify(method, params)));
+    for (const r of results) {
+        if (r.status === "rejected") {
+            warn(`broadcast: notify ${method} failed on one client: ` +
+                `${r.reason instanceof Error ? r.reason.message : String(r.reason)}`);
+        }
+    }
+}
+async function requestAny(registry, method, params, options) {
+    const clients = registry.snapshot();
+    if (clients.length === 0) {
+        throw new Error(`broadcast: no connected clients (${method})`);
+    }
+    const controllers = clients.map(() => new AbortController());
+    // Link a caller-provided signal: aborting it cancels EVERY inner request.
+    const outerSignal = options?.cancellationSignal;
+    const onOuterAbort = () => {
+        for (const c of controllers)
+            c.abort();
+    };
+    if (outerSignal) {
+        if (outerSignal.aborted)
+            onOuterAbort();
+        else
+            outerSignal.addEventListener("abort", onOuterAbort, { once: true });
+    }
+    const attempts = clients.map((cx, i) => {
+        const promise = cx.request(method, params, {
+            ...options,
+            cancellationSignal: controllers[i].signal,
+        });
+        // Mark handled: losing promises settle AFTER Promise.any is done.
+        promise.catch(() => undefined);
+        return promise.then((value) => ({ value, index: i }));
+    });
+    try {
+        const winner = await Promise.any(attempts);
+        for (let i = 0; i < controllers.length; i++) {
+            if (i !== winner.index)
+                controllers[i].abort();
+        }
+        return winner.value;
+    }
+    catch (e) {
+        // All clients failed — surface the first error like a single client would.
+        if (e instanceof AggregateError)
+            throw e.errors[0] ?? e;
+        throw e;
+    }
+    finally {
+        if (outerSignal)
+            outerSignal.removeEventListener("abort", onOuterAbort);
+    }
+}
+//# sourceMappingURL=broadcast.js.map

package/dist/remote/broadcast.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"broadcast.js","sourceRoot":"","sources":["../../src/remote/broadcast.ts"],"names":[],"mappings":"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"}

package/dist/remote/config.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Remote access configuration from environment variables.
+ *
+ * Remote access is opt-in via ZCODE_ACP_REMOTE=1 and REQUIRES a token — the
+ * endpoint is expected to sit behind a public tunnel (Cloudflare Tunnel, frp),
+ * so "loopback-only" is never a safe assumption here. A missing token disables
+ * the feature with a warning instead of failing the bridge: the stdio link to
+ * the editor must keep working no matter what.
+ *
+ * Variables:
+ *   ZCODE_ACP_REMOTE=1            enable the remote endpoint (gate)
+ *   ZCODE_ACP_REMOTE_TOKEN=<s>    auth token (mandatory when enabled)
+ *   ZCODE_ACP_HUB_PORT=8377       hub's fixed port (the one a tunnel maps)
+ *   ZCODE_ACP_HUB_HOST=127.0.0.1  hub bind address (e.g. 0.0.0.0 for a
+ *                                 containerized tunnel agent)
+ *   ZCODE_ACP_REMOTE_PORT=8378    bridge endpoint start port (auto-increment
+ *                                 when taken; loopback only)
+ */
+export interface RemoteConfig {
+    token: string;
+    hubPort: number;
+    hubHost: string;
+    bridgePort: number;
+}
+export declare const DEFAULT_HUB_PORT = 8377;
+export declare const DEFAULT_BRIDGE_PORT = 8378;
+export declare const DEFAULT_HUB_HOST = "127.0.0.1";
+/** Parse remote config; null = disabled (or misconfigured → warned). */
+export declare function parseRemoteConfig(env?: NodeJS.ProcessEnv): RemoteConfig | null;
+/** Parse hub-side config for the standalone `zcode-acp-hub` bin. */
+export declare function parseHubConfig(env?: NodeJS.ProcessEnv): RemoteConfig | null;
+//# sourceMappingURL=config.d.ts.map

package/dist/remote/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/remote/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,gBAAgB,OAAO,CAAC;AACrC,eAAO,MAAM,mBAAmB,OAAO,CAAC;AACxC,eAAO,MAAM,gBAAgB,cAAc,CAAC;AAY5C,wEAAwE;AACxE,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,YAAY,GAAG,IAAI,CAiB3F;AAED,oEAAoE;AACpE,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,YAAY,GAAG,IAAI,CAYxF"}

package/dist/remote/config.js

@@ -0,0 +1,65 @@
+/**
+ * Remote access configuration from environment variables.
+ *
+ * Remote access is opt-in via ZCODE_ACP_REMOTE=1 and REQUIRES a token — the
+ * endpoint is expected to sit behind a public tunnel (Cloudflare Tunnel, frp),
+ * so "loopback-only" is never a safe assumption here. A missing token disables
+ * the feature with a warning instead of failing the bridge: the stdio link to
+ * the editor must keep working no matter what.
+ *
+ * Variables:
+ *   ZCODE_ACP_REMOTE=1            enable the remote endpoint (gate)
+ *   ZCODE_ACP_REMOTE_TOKEN=<s>    auth token (mandatory when enabled)
+ *   ZCODE_ACP_HUB_PORT=8377       hub's fixed port (the one a tunnel maps)
+ *   ZCODE_ACP_HUB_HOST=127.0.0.1  hub bind address (e.g. 0.0.0.0 for a
+ *                                 containerized tunnel agent)
+ *   ZCODE_ACP_REMOTE_PORT=8378    bridge endpoint start port (auto-increment
+ *                                 when taken; loopback only)
+ */
+import { warn } from "../utils.js";
+export const DEFAULT_HUB_PORT = 8377;
+export const DEFAULT_BRIDGE_PORT = 8378;
+export const DEFAULT_HUB_HOST = "127.0.0.1";
+function parsePort(raw, fallback, envName) {
+    if (!raw)
+        return fallback;
+    const port = Number.parseInt(raw, 10);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        warn(`remote: invalid ${envName}="${raw}", falling back to ${fallback}`);
+        return fallback;
+    }
+    return port;
+}
+/** Parse remote config; null = disabled (or misconfigured → warned). */
+export function parseRemoteConfig(env = process.env) {
+    const gate = (env.ZCODE_ACP_REMOTE ?? "").trim().toLowerCase();
+    if (!["1", "true", "yes", "on"].includes(gate))
+        return null;
+    const token = (env.ZCODE_ACP_REMOTE_TOKEN ?? "").trim();
+    if (!token) {
+        warn("remote: ZCODE_ACP_REMOTE is enabled but ZCODE_ACP_REMOTE_TOKEN is missing — " +
+            "remote access disabled (stdio unaffected)");
+        return null;
+    }
+    return {
+        token,
+        hubPort: parsePort(env.ZCODE_ACP_HUB_PORT, DEFAULT_HUB_PORT, "ZCODE_ACP_HUB_PORT"),
+        hubHost: (env.ZCODE_ACP_HUB_HOST ?? "").trim() || DEFAULT_HUB_HOST,
+        bridgePort: parsePort(env.ZCODE_ACP_REMOTE_PORT, DEFAULT_BRIDGE_PORT, "ZCODE_ACP_REMOTE_PORT"),
+    };
+}
+/** Parse hub-side config for the standalone `zcode-acp-hub` bin. */
+export function parseHubConfig(env = process.env) {
+    const token = (env.ZCODE_ACP_REMOTE_TOKEN ?? "").trim();
+    if (!token) {
+        warn("hub: ZCODE_ACP_REMOTE_TOKEN is required — refusing to start without auth");
+        return null;
+    }
+    return {
+        token,
+        hubPort: parsePort(env.ZCODE_ACP_HUB_PORT, DEFAULT_HUB_PORT, "ZCODE_ACP_HUB_PORT"),
+        hubHost: (env.ZCODE_ACP_HUB_HOST ?? "").trim() || DEFAULT_HUB_HOST,
+        bridgePort: parsePort(env.ZCODE_ACP_REMOTE_PORT, DEFAULT_BRIDGE_PORT, "ZCODE_ACP_REMOTE_PORT"),
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/remote/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/remote/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AASnC,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC;AACrC,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,CAAC;AACxC,MAAM,CAAC,MAAM,gBAAgB,GAAG,WAAW,CAAC;AAE5C,SAAS,SAAS,CAAC,GAAuB,EAAE,QAAgB,EAAE,OAAe;IAC3E,IAAI,CAAC,GAAG;QAAE,OAAO,QAAQ,CAAC;IAC1B,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACtC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,KAAK,EAAE,CAAC;QACxD,IAAI,CAAC,mBAAmB,OAAO,KAAK,GAAG,sBAAsB,QAAQ,EAAE,CAAC,CAAC;QACzE,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,iBAAiB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACpE,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,gBAAgB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC/D,IAAI,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5D,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,sBAAsB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACxD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,IAAI,CACF,8EAA8E;YAC5E,2CAA2C,CAC9C,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO;QACL,KAAK;QACL,OAAO,EAAE,SAAS,CAAC,GAAG,CAAC,kBAAkB,EAAE,gBAAgB,EAAE,oBAAoB,CAAC;QAClF,OAAO,EAAE,CAAC,GAAG,CAAC,kBAAkB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,gBAAgB;QAClE,UAAU,EAAE,SAAS,CAAC,GAAG,CAAC,qBAAqB,EAAE,mBAAmB,EAAE,uBAAuB,CAAC;KAC/F,CAAC;AACJ,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,cAAc,CAAC,MAAyB,OAAO,CAAC,GAAG;IACjE,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,sBAAsB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACxD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,IAAI,CAAC,0EAA0E,CAAC,CAAC;QACjF,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO;QACL,KAAK;QACL,OAAO,EAAE,SAAS,CAAC,GAAG,CAAC,kBAAkB,EAAE,gBAAgB,EAAE,oBAAoB,CAAC;QAClF,OAAO,EAAE,CAAC,GAAG,CAAC,kBAAkB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,gBAAgB;QAClE,UAAU,EAAE,SAAS,CAAC,GAAG,CAAC,qBAAqB,EAAE,mBAAmB,EAAE,uBAAuB,CAAC;KAC/F,CAAC;AACJ,CAAC"}

package/dist/remote/endpoint.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Loopback ACP endpoint + hub registration for remote access.
+ *
+ * When ZCODE_ACP_REMOTE is enabled, the bridge serves the SAME AgentApp that
+ * handles the stdio editor connection on a loopback HTTP/WebSocket endpoint
+ * (SDK AcpServer transport). Each remote connection gets its own JSON-RPC id
+ * space; fan-out to all clients is handled by the broadcast registry, not
+ * here. This endpoint is intentionally NOT exposed to the network — the hub
+ * (`zcode-acp-hub`) is the single public entry and proxies into it.
+ *
+ * The bridge also registers itself with the hub (spawning one if none is
+ * listening) and re-registers every 10s as a heartbeat carrying fresh session
+ * summaries. Everything here is best-effort: any failure warns and disables
+ * the remote side without touching the stdio link.
+ */
+import type * as acp from "@agentclientprotocol/sdk";
+import type { ZcodeAcpServer } from "../server.js";
+import type { RemoteConfig } from "./config.js";
+export interface RemoteEndpointHandle {
+    /** Actual loopback port the endpoint bound (may differ from config). */
+    port: number;
+    /** Stop the endpoint and unregister from the hub (best-effort). */
+    stop(): Promise<void>;
+}
+/**
+ * Start the loopback endpoint and hub registration. Never throws — failures
+ * warn and leave the bridge running stdio-only.
+ */
+export declare function startRemoteEndpoint(server: ZcodeAcpServer, app: acp.AgentApp, config: RemoteConfig): Promise<RemoteEndpointHandle | null>;
+//# sourceMappingURL=endpoint.d.ts.map

package/dist/remote/endpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint.d.ts","sourceRoot":"","sources":["../../src/remote/endpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,OAAO,KAAK,KAAK,GAAG,MAAM,0BAA0B,CAAC;AAQrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAShD,MAAM,WAAW,oBAAoB;IACnC,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AA8BD;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,cAAc,EACtB,GAAG,EAAE,GAAG,CAAC,QAAQ,EACjB,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAiKtC"}

package/dist/remote/endpoint.js

@@ -0,0 +1,213 @@
+/**
+ * Loopback ACP endpoint + hub registration for remote access.
+ *
+ * When ZCODE_ACP_REMOTE is enabled, the bridge serves the SAME AgentApp that
+ * handles the stdio editor connection on a loopback HTTP/WebSocket endpoint
+ * (SDK AcpServer transport). Each remote connection gets its own JSON-RPC id
+ * space; fan-out to all clients is handled by the broadcast registry, not
+ * here. This endpoint is intentionally NOT exposed to the network — the hub
+ * (`zcode-acp-hub`) is the single public entry and proxies into it.
+ *
+ * The bridge also registers itself with the hub (spawning one if none is
+ * listening) and re-registers every 10s as a heartbeat carrying fresh session
+ * summaries. Everything here is best-effort: any failure warns and disables
+ * the remote side without touching the stdio link.
+ */
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import { fileURLToPath } from "node:url";
+import { AcpServer } from "@agentclientprotocol/sdk/experimental/server";
+import { createNodeHttpHandler, createNodeWebSocketUpgradeHandler, } from "@agentclientprotocol/sdk/experimental/node";
+import { WebSocketServer } from "ws";
+import { AGENT_INFO, log, warn } from "../utils.js";
+/** How often the bridge re-registers with the hub (also the heartbeat). */
+const HEARTBEAT_MS = 10_000;
+/** Minimum spacing between hub spawn attempts (avoids spawn storms). */
+const SPAWN_THROTTLE_MS = 60_000;
+/** Max ports probed above ZCODE_ACP_REMOTE_PORT before giving up. */
+const MAX_PORT_PROBES = 100;
+/** Probe one loopback port; false = taken or otherwise unusable. */
+function tryListen(server, port) {
+    return new Promise((resolve) => {
+        server.once("error", () => resolve(false));
+        server.listen(port, "127.0.0.1", () => resolve(true));
+    });
+}
+/** Session summaries for the hub's discovery API. */
+function sessionsPayload(server) {
+    return Array.from(server.sessionSummaries.entries(), ([sessionId, s]) => ({
+        sessionId,
+        ...(s.title !== undefined ? { title: s.title } : {}),
+        updatedAt: s.updatedAt,
+    }));
+}
+async function postJson(url, body, timeoutMs = 3000) {
+    return fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+}
+/**
+ * Start the loopback endpoint and hub registration. Never throws — failures
+ * warn and leave the bridge running stdio-only.
+ */
+export async function startRemoteEndpoint(server, app, config) {
+    const acpServer = new AcpServer({ agent: app });
+    const acpHttpHandler = createNodeHttpHandler(acpServer);
+    const wss = new WebSocketServer({ noServer: true });
+    const upgradeHandler = createNodeWebSocketUpgradeHandler(acpServer, wss);
+    const httpServer = createServer((req, res) => {
+        const path = new URL(req.url ?? "/", "http://127.0.0.1").pathname;
+        if (path === "/acp")
+            acpHttpHandler(req, res);
+        else {
+            res.writeHead(404, { "Content-Type": "text/plain" });
+            res.end("not found");
+        }
+    });
+    httpServer.on("upgrade", (req, socket, head) => {
+        const path = new URL(req.url ?? "/", "http://127.0.0.1").pathname;
+        if (path === "/acp")
+            upgradeHandler(req, socket, head);
+        else
+            socket.destroy();
+    });
+    // Port scan: several Zed windows spawn several bridges, each takes the next
+    // free port starting at ZCODE_ACP_REMOTE_PORT.
+    let port = 0;
+    for (let probe = 0; probe < MAX_PORT_PROBES; probe++) {
+        if (await tryListen(httpServer, config.bridgePort + probe)) {
+            port = config.bridgePort + probe;
+            break;
+        }
+    }
+    if (!port) {
+        warn(`remote: no free loopback port in ${config.bridgePort}..${config.bridgePort + MAX_PORT_PROBES - 1} — remote disabled`);
+        wss.close();
+        return null;
+    }
+    // The listener must not keep the process alive on its own (ADR-0001: the
+    // bridge's lifetime follows the stdio editor, not remote clients).
+    httpServer.unref();
+    httpServer.on("error", (e) => warn(`remote: endpoint error: ${e.message}`));
+    log(`remote: ACP endpoint listening on 127.0.0.1:${port}/acp`);
+    // ---- hub registration (heartbeat loop) ----
+    const instanceId = String(process.pid);
+    let stopped = false;
+    let authRejected = false;
+    let spawnThrottledUntil = 0;
+    const payload = () => ({
+        token: config.token,
+        id: instanceId,
+        port,
+        pid: process.pid,
+        workspace: server.workspaceLabel(),
+        sessions: sessionsPayload(server),
+        // Lets the hub detect that it is older than this bridge and restart
+        // itself (we then re-spawn it from this dist — see registerOnce).
+        version: AGENT_INFO.version,
+    });
+    const spawnHub = () => {
+        try {
+            // dist/remote/endpoint.js → dist/bin/hub.js (one level up, then bin/).
+            const hubJs = fileURLToPath(new URL("../bin/hub.js", import.meta.url));
+            const child = spawn(process.execPath, [hubJs], {
+                detached: true,
+                // Surface the daemon's stderr through the bridge's diagnostics — a
+                // detached "ignore" pipe silently eats startup failures.
+                stdio: ["ignore", "ignore", "pipe"],
+                env: {
+                    ...process.env,
+                    ZCODE_ACP_HUB_PORT: String(config.hubPort),
+                    ZCODE_ACP_HUB_HOST: config.hubHost,
+                    ZCODE_ACP_REMOTE_TOKEN: config.token,
+                },
+            });
+            child.stderr?.on("data", (d) => {
+                for (const line of d.toString().split("\n")) {
+                    if (line.trim())
+                        warn(`remote: hub: ${line}`);
+                }
+            });
+            // Spawn failures (ENOENT when run from src without a build) arrive as an
+            // async 'error' event — without a listener Node crashes the bridge.
+            child.once("error", (e) => {
+                warn(`remote: hub spawn failed: ${e.message}`);
+            });
+            child.unref();
+            log(`remote: spawned hub on port ${config.hubPort} (pid ${child.pid})`);
+        }
+        catch (e) {
+            warn(`remote: hub spawn failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    };
+    const registerOnce = async () => {
+        if (stopped || authRejected)
+            return;
+        try {
+            const res = await postJson(`http://127.0.0.1:${config.hubPort}/api/register`, payload());
+            if (res.status === 401) {
+                authRejected = true;
+                warn("remote: hub rejected the token (401) — registration stopped, check ZCODE_ACP_REMOTE_TOKEN");
+                return;
+            }
+            // Version handshake: the hub saw a newer bridge and is exiting. It is
+            // gone by now (it exits ~0.5s after replying) — re-spawn it from THIS
+            // dist (the upgraded code) and re-register. Throttled like the spawn
+            // below so a hub that keeps answering `restarting` can't loop us.
+            if (res.ok) {
+                const body = (await res.json().catch(() => null));
+                if (body?.restarting) {
+                    log("remote: hub is older than this bridge — respawning upgraded hub");
+                    const respawn = setTimeout(() => {
+                        if (stopped || authRejected)
+                            return;
+                        if (Date.now() < spawnThrottledUntil)
+                            return;
+                        spawnThrottledUntil = Date.now() + SPAWN_THROTTLE_MS;
+                        spawnHub();
+                        const retry = setTimeout(() => void registerOnce(), 1500);
+                        retry.unref();
+                    }, 2000);
+                    respawn.unref();
+                }
+            }
+        }
+        catch {
+            // Hub unreachable: (re)spawn it, throttled so a failing spawn can't
+            // storm, then retry registration shortly after the daemon warms up
+            // instead of waiting a full heartbeat cycle.
+            if (Date.now() >= spawnThrottledUntil) {
+                spawnThrottledUntil = Date.now() + SPAWN_THROTTLE_MS;
+                spawnHub();
+                const retry = setTimeout(() => void registerOnce(), 1500);
+                retry.unref();
+            }
+        }
+    };
+    void registerOnce();
+    const heartbeat = setInterval(() => void registerOnce(), HEARTBEAT_MS);
+    heartbeat.unref();
+    return {
+        port,
+        async stop() {
+            stopped = true;
+            clearInterval(heartbeat);
+            try {
+                await postJson(`http://127.0.0.1:${config.hubPort}/api/unregister`, { token: config.token, id: instanceId }, 1500);
+            }
+            catch {
+                // Hub gone or unreachable — its heartbeat TTL will drop us anyway.
+            }
+            for (const client of wss.clients)
+                client.terminate();
+            wss.close();
+            await acpServer.close().catch(() => undefined);
+            httpServer.closeAllConnections?.();
+            httpServer.close();
+        },
+    };
+}
+//# sourceMappingURL=endpoint.js.map

package/dist/remote/endpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint.js","sourceRoot":"","sources":["../../src/remote/endpoint.ts"],"names":[],"mappings":"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"}

package/dist/remote/hub-server.d.ts

@@ -0,0 +1,41 @@
+/**
+ * zcode-acp-hub — machine-level singleton for remote access.
+ *
+ * The hub is the ONLY public entry point (the port a tunnel maps). It does
+ * exactly three things (ADR-0002): token auth, instance discovery, and
+ * byte-level WebSocket proxying from a remote client to one bridge's loopback
+ * ACP endpoint. It holds no session state and understands no ACP — a proxied
+ * connection stays bound to one instance for its whole lifetime.
+ *
+ * Bridges register via POST /api/register every 10s (the registration doubles
+ * as the heartbeat; entries older than the heartbeat TTL are pruned). A client
+ * that needs an immediately-honest list (e.g. a phone app's pull-to-refresh)
+ * passes ?probe=1 to /api/instances: the hub TCP-probes each registered
+ * loopback port and prunes unreachable bridges before answering — no periodic
+ * probing, the cost is paid only when someone refreshes. When no instance is
+ * registered and no proxy is active for `idleExitMs`, the hub exits — the
+ * next bridge re-spawns it on demand.
+ */
+export interface HubOptions {
+    port: number;
+    host: string;
+    token: string;
+    /** Registration TTL before an instance is pruned (default 30s). */
+    heartbeatTimeoutMs?: number;
+    /** Idle time with zero instances and zero proxies before exit (default 10min). */
+    idleExitMs?: number;
+    /** WebSocket keepalive ping interval (default 30s; tunnels drop idle links). */
+    pingIntervalMs?: number;
+}
+export interface HubHandle {
+    port: number;
+    close(): Promise<void>;
+}
+/**
+ * Start the hub. Resolves once listening; rejects on bind failure (including
+ * EADDRINUSE when another hub already owns the port).
+ */
+export declare function startHub(options: HubOptions & {
+    onIdleExit?: () => void;
+}): Promise<HubHandle>;
+//# sourceMappingURL=hub-server.d.ts.map

package/dist/remote/hub-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hub-server.d.ts","sourceRoot":"","sources":["../../src/remote/hub-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAUH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gFAAgF;IAChF,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAqGD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,UAAU,GAAG;IAAE,UAAU,CAAC,EAAE,MAAM,IAAI,CAAA;CAAE,GAAG,OAAO,CAAC,SAAS,CAAC,CAwQ9F"}