@sjawhar/opencode-legion-envoy 0.5.2 → 0.6.0

package/AGENTS.md

@@ -16,7 +16,7 @@ It is the user-facing bridge between OpenCode sessions and Envoy transport.
 | Packaging metadata  | `package.json`         | npm identity, `exports` map, scripts                               |
 | TUI: `/whoami` + sidebar | `src/tui.tsx`     | slash command + session-id/port sidebar; loaded via the `./tui` export. Ships as `.tsx` source (no build/`dist`) — Bun transpiles it natively at load, so `@opentui/core` + `@opentui/solid` MUST be `peerDependencies` (not `devDependencies`) so the `@jsxImportSource @opentui/solid` runtime resolves in the consumer's install tree |
 | Host rollout helper | `scripts/sync-host.sh` | sync packed release tarball + shim to remote host                  |
-| Dispatch MCP + auto-subscribe | `src/dispatch-mcp.ts`, `src/dispatch-subscribe.ts` | injects the dispatch MCP server (shim); `tool.execute.after` auto-subscribes the caller to the new thread's topic so answers route back (Dispatch AC#4) |
+| Dispatch MCP + auto-subscribe | `src/dispatch-mcp.ts`, `src/dispatch-subscribe.ts` | injects the shim wrapper in `bin/`; shared forwarding/token code lives in `@legion/envoy-client`. `tool.execute.after` auto-subscribes dispatch callers to new thread topics. |
 
 ## Critical conventions
 

package/bin/dispatch-mcp-shim.ts

@@ -1,75 +1,7 @@
 #!/usr/bin/env bun
-// envoy-plugin local MCP shim.
-//
-// Spawned by OpenCode as a `type: "local"` MCP transport. Reads JSON-RPC
-// messages from stdin (newline-delimited), forwards each to the remote
-// dispatch server's Streamable HTTP /mcp endpoint with a fresh GitHub
-// bearer minted via the user's `gh` shim, and writes responses to stdout.
-//
-// Token rotation is invisible to OpenCode — the shim handles 50-minute
-// refresh cycles + immediate retry on 401. This avoids the "MCP dies
-// after 1 hour" failure mode of static-header configurations.
+// envoy-plugin local MCP shim entry point. The forwarding logic is shared
+// with the other Envoy adapters in @legion/envoy-client; OpenCode spawns
+// this wrapper via the `mcp.envoy` entry injected by src/dispatch-mcp.ts.
+import { runDispatchMcpShim } from "@legion/envoy-client/dispatch-mcp-shim";
 
-import * as readline from "node:readline";
-import {
-  createBridge,
-  defaultGhTokenGetter,
-  type JsonRpcRequest,
-} from "../src/dispatch-mcp-bridge";
-
-const remoteUrl = process.env.DISPATCH_MCP_URL;
-if (!remoteUrl) {
-  process.stderr.write("envoy-dispatch shim: DISPATCH_MCP_URL is required\n");
-  process.exit(1);
-}
-
-const bridge = createBridge({
-  remoteUrl,
-  getToken: defaultGhTokenGetter,
-});
-
-const rl = readline.createInterface({ input: process.stdin });
-
-let inflight = 0;
-let closed = false;
-
-// Serialize incoming requests. MCP requires the initialize handshake to
-// complete before any tool calls are processed; running rl.on("line")
-// callbacks in parallel would race tools/call against initialize and hit
-// `invalid during session initialization` from the server. Even after
-// init, sequencing keeps the wire ordering deterministic, which is what
-// OpenCode expects for stdio MCP transports.
-let chain: Promise<void> = Promise.resolve();
-
-function maybeExit(): void {
-  if (closed && inflight === 0) process.exit(0);
-}
-
-rl.on("line", (line) => {
-  const trimmed = line.trim();
-  if (!trimmed) return;
-  inflight++;
-  chain = chain.then(async () => {
-    try {
-      const request = JSON.parse(trimmed) as JsonRpcRequest;
-      const response = await bridge.handle(request);
-      if (response !== null) {
-        process.stdout.write(`${JSON.stringify(response)}\n`);
-      }
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      process.stderr.write(`envoy-dispatch shim: ${msg}\n`);
-    } finally {
-      inflight--;
-      maybeExit();
-    }
-  });
-});
-
-rl.on("close", () => {
-  closed = true;
-  maybeExit();
-});
-
-process.on("SIGTERM", () => process.exit(0));
-process.on("SIGINT", () => process.exit(0));
+runDispatchMcpShim();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/opencode-legion-envoy",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "type": "module",
   "main": "src/server.ts",
   "exports": {

package/src/__tests__/index.test.ts

@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, mock } from "bun:test";
+import * as os from "node:os";
 
 // Suppress console.error during tests
 const originalError = console.error;
@@ -72,9 +73,7 @@ describe("envoy plugin init", () => {
 describe("envoy_whoami", () => {
   it("returns session identity when Envoy is unavailable", async () => {
     const originalEnvoyUrl = process.env.ENVOY_URL;
-    const originalHostname = process.env.HOSTNAME;
     process.env.ENVOY_URL = "http://127.0.0.1:59999";
-    process.env.HOSTNAME = "test-machine";
 
     try {
       const pluginModule = await import("../server");
@@ -91,25 +90,21 @@ describe("envoy_whoami", () => {
 
       const parsed = JSON.parse(typeof result === "string" ? result : result.output);
       expect(parsed.session_id).toBe("ses_test_whoami");
-      expect(parsed.machine_id).toBe("test-machine");
+      expect(parsed.machine_id).toBe(os.hostname());
       expect(parsed.dir).toBe("/tmp/test-workspace");
       expect(parsed).not.toHaveProperty("topics");
       expect(parsed.port === null || typeof parsed.port === "number").toBe(true);
     } finally {
       process.env.ENVOY_URL = originalEnvoyUrl;
-      if (originalHostname === undefined) {
-        delete process.env.HOSTNAME;
-      } else {
-        process.env.HOSTNAME = originalHostname;
-      }
     }
   });
 
-  it("uses 'unknown' for machine_id when HOSTNAME is not set", async () => {
+  it("reports machine_id from the real hostname, not the HOSTNAME env var", async () => {
     const originalEnvoyUrl = process.env.ENVOY_URL;
     const originalHostname = process.env.HOSTNAME;
     process.env.ENVOY_URL = "http://127.0.0.1:59999";
-    delete process.env.HOSTNAME;
+    // Same host must never report two machine IDs depending on shell env.
+    process.env.HOSTNAME = "some-other-name";
 
     try {
       const pluginModule = await import("../server");
@@ -119,13 +114,13 @@ describe("envoy_whoami", () => {
       } as never);
 
       const result = await hooks.tool.envoy_whoami.execute({}, {
-        sessionID: "ses_no_hostname",
+        sessionID: "ses_env_hostname",
         directory: "/tmp",
         metadata: mock(() => {}),
       } as never);
 
       const parsed = JSON.parse(typeof result === "string" ? result : result.output);
-      expect(parsed.machine_id).toBe("unknown");
+      expect(parsed.machine_id).toBe(os.hostname());
     } finally {
       process.env.ENVOY_URL = originalEnvoyUrl;
       if (originalHostname === undefined) {

package/src/__tests__/ss.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, test } from "bun:test";
+import { portFromSsOutput } from "../ss";
+
+const header = "State  Recv-Q Send-Q Local Address:Port  Peer Address:Port Process";
+
+function listen(local: string, pid: number): string {
+  return `LISTEN 0      511    ${local}  0.0.0.0:*  users:(("bun",pid=${pid},fd=6))`;
+}
+
+describe("portFromSsOutput", () => {
+  test("returns null when the process id has no listening socket", () => {
+    const output = [header, listen("127.0.0.1:4096", 99_999)].join("\n");
+
+    expect(portFromSsOutput(output, 12_345)).toBeNull();
+  });
+
+  test("skips matching process rows whose local address column is malformed", () => {
+    const output = [header, listen("not-a-local-address", 123)].join("\n");
+
+    expect(portFromSsOutput(output, 123)).toBeNull();
+  });
+
+  test("ignores zero and negative local ports", () => {
+    const output = [header, listen("127.0.0.1:0", 123), listen("127.0.0.1:-1", 123)].join("\n");
+
+    expect(portFromSsOutput(output, 123)).toBeNull();
+  });
+
+  test("matches the full pid token before returning a port", () => {
+    const output = [header, listen("127.0.0.1:9999", 123), listen("127.0.0.1:4444", 12)].join("\n");
+
+    expect(portFromSsOutput(output, 12)).toBe(4444);
+  });
+});

package/src/config/index.ts

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { messageFor } from "@legion/envoy-client/errors";
 import { logger } from "../log";
 import { type EnvoyConfig, EnvoyConfigSchema } from "./schema";
 
@@ -23,7 +24,7 @@ function readConfigFile(filePath: string): EnvoyConfig | null {
     }
     return parsed.data as EnvoyConfig;
   } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
+    const message = messageFor(error);
     logger.warn(`[envoy-plugin] Failed to load config at ${filePath}: ${message}`);
     return null;
   }

package/src/dispatch-subscribe.ts

@@ -1,4 +1,4 @@
-// Auto-subscription wiring for the envoy_dispatch MCP tool (Dispatch AC#4).
+// Auto-subscription wiring for the envoy_dispatch MCP tool.
 //
 // When an agent opens a Dispatch thread via the envoy_dispatch MCP tool, the
 // human answers by commenting on the resulting GitHub sub-issue. For the agent

package/src/port.ts

@@ -1,4 +1,5 @@
 import { execFile } from "node:child_process";
+import { portFromSsOutput } from "./ss";
 
 type ExecFn = (
   command: string,
@@ -33,17 +34,9 @@ export async function resolvePort(
   // Fallback: find listening port via ss(8) by PID
   try {
     const output = await exec("ss", ["-tlnp"], { encoding: "utf-8" });
-    for (const line of output.split("\n")) {
-      if (!line.includes(`pid=${process.pid}`)) continue;
-      const parts = line.trim().split(/\s+/);
-      const local = parts[3];
-      const match = local?.match(/:(\d+)$/);
-      if (!match) continue;
-      const port = Number.parseInt(match[1], 10);
-      if (Number.isFinite(port) && port > 0) return port;
-    }
+    const port = portFromSsOutput(output, process.pid);
+    if (port !== null) return port;
   } catch {}
 
   return null;
 }
-// trigger publish

package/src/server.ts

@@ -1,5 +1,6 @@
 import { agentSubject } from "@legion/contracts";
 import { envoyDefaultsFromEnvironment } from "@legion/envoy-client/defaults";
+import { machineID } from "@legion/envoy-client/machine";
 import { envoyToolSpecs } from "@legion/envoy-client/tool-contract";
 import { createEnvoyClient } from "@legion/envoy-client/transport";
 import { tool } from "@opencode-ai/plugin/tool";
@@ -41,7 +42,10 @@ export default async (input: { serverUrl: URL }) => {
     if (!port && !portWarningLogged) {
       portWarningLogged = true;
       logger.error(
-        `[envoy-plugin] Could not resolve serve port: serverUrl=${input.serverUrl.href}, pid=${process.pid}`
+        [
+          `[envoy-plugin] Could not resolve serve port: serverUrl=${input.serverUrl.href},`,
+          `pid=${process.pid}`,
+        ].join(" ")
       );
     }
     if (port) {
@@ -218,10 +222,10 @@ export default async (input: { serverUrl: URL }) => {
       input: { tool: string; sessionID: string; callID: string; args: unknown },
       output: { title: string; output: string; metadata: unknown }
     ) => {
-      // Dispatch AC#4: when this session opens a Dispatch thread via the
-      // envoy_dispatch MCP tool, auto-subscribe it to the thread's GitHub topic
-      // so the human's reply is delivered back through Envoy. Best-effort — a
-      // subscribe failure must never surface to the model or fail the tool call.
+      // When this session opens a Dispatch thread via the envoy_dispatch MCP
+      // tool, auto-subscribe it to the thread's GitHub topic so the human's
+      // reply is delivered back through Envoy. Best-effort — a subscribe
+      // failure must never surface to the model or fail the tool call.
       const topic = dispatchSubscriptionTopic(input.tool, output.output);
       if (!topic) return;
       try {
@@ -234,9 +238,8 @@ export default async (input: { serverUrl: URL }) => {
           driving: true,
         });
       } catch (err) {
-        logger.warn(
-          `[envoy-plugin] dispatch auto-subscribe failed: ${err instanceof Error ? err.message : String(err)}`
-        );
+        const message = err instanceof Error ? err.message : String(err);
+        logger.warn(`[envoy-plugin] dispatch auto-subscribe failed: ${message}`);
       }
     },
     // Cleanup hook (used by tests; production relies on process 'exit').
@@ -325,7 +328,7 @@ export default async (input: { serverUrl: URL }) => {
           return JSON.stringify(
             {
               session_id: sessionID,
-              machine_id: process.env.HOSTNAME || "unknown",
+              machine_id: machineID(),
               port,
               dir: ctx.directory,
             },

package/src/ss.ts

@@ -0,0 +1,19 @@
+/**
+ * Parse the listening TCP port for `pid` from `ss -tlnp` output.
+ *
+ * Shared by the server-side and TUI-side port resolvers, which differ only in
+ * how they discover the pid and whether they exec ss(8) sync or async.
+ */
+export function portFromSsOutput(output: string, pid: number): number | null {
+  const pidPattern = new RegExp(`\\bpid=${pid}\\b`);
+  for (const line of output.split("\n")) {
+    if (!pidPattern.test(line)) continue;
+    const parts = line.trim().split(/\s+/);
+    const local = parts[3];
+    const match = local?.match(/:(\d+)$/);
+    if (!match) continue;
+    const port = Number.parseInt(match[1], 10);
+    if (Number.isFinite(port) && port > 0) return port;
+  }
+  return null;
+}

package/src/tui-port.ts

@@ -1,4 +1,5 @@
 import { execFileSync } from "node:child_process";
+import { portFromSsOutput } from "./ss";
 
 type ExecSyncFn = (command: string, args: string[], options: { encoding: string }) => string;
 
@@ -36,19 +37,10 @@ export function resolveCurrentProcessPort(exec: ExecSyncFn = defaultExecSync): n
 
 function resolveProcessPort(pid: number, exec: ExecSyncFn = defaultExecSync): number | null {
   try {
-    const output = exec("ss", ["-tlnp"], { encoding: "utf-8" });
-    for (const line of output.split("\n")) {
-      if (!line.includes(`pid=${pid}`)) continue;
-      const parts = line.trim().split(/\s+/);
-      const local = parts[3];
-      const match = local?.match(/:(\d+)$/);
-      if (!match) continue;
-      const port = Number.parseInt(match[1], 10);
-      if (Number.isFinite(port) && port > 0) return port;
-    }
-  } catch {}
-
-  return null;
+    return portFromSsOutput(exec("ss", ["-tlnp"], { encoding: "utf-8" }), pid);
+  } catch {
+    return null;
+  }
 }
 
 export function resolveSessionProcessPort(

package/tsconfig.json

@@ -16,5 +16,5 @@
     "jsx": "preserve",
     "types": ["bun"]
   },
-  "include": ["src/**/*.ts", "src/**/*.tsx"]
+  "include": ["bin/**/*.ts", "src/**/*.ts", "src/**/*.tsx"]
 }

package/src/__tests__/dispatch-mcp-bridge.test.ts

@@ -1,339 +0,0 @@
-import { describe, expect, it, mock } from "bun:test";
-import { createBridge, type JsonRpcRequest } from "../dispatch-mcp-bridge";
-
-interface MockResponse {
-  status: number;
-  statusText?: string;
-  headers?: Record<string, string>;
-  contentType?: string;
-  body: string;
-}
-
-function fakeFetch(responses: MockResponse[]) {
-  let idx = 0;
-  const calls: Array<{ url: string; init: RequestInit }> = [];
-  const impl = (url: string, init?: RequestInit) => {
-    calls.push({ url, init: init ?? {} });
-    const next = responses[idx++];
-    if (!next) throw new Error(`no mock response for call #${idx}`);
-    const headers = new Headers({
-      "content-type": next.contentType ?? "application/json",
-      ...(next.headers ?? {}),
-    });
-    return Promise.resolve(
-      new Response(next.body, {
-        status: next.status,
-        statusText: next.statusText ?? "",
-        headers,
-      })
-    );
-  };
-  return { impl: impl as unknown as typeof fetch, calls };
-}
-
-function sseEnvelope(payload: object): string {
-  return `event: message\ndata: ${JSON.stringify(payload)}\n\n`;
-}
-
-describe("dispatch-mcp-bridge", () => {
-  it("forwards a request with a fresh bearer and returns the parsed SSE response", async () => {
-    const f = fakeFetch([
-      {
-        status: 200,
-        contentType: "text/event-stream",
-        headers: { "mcp-session-id": "S1" },
-        body: sseEnvelope({ jsonrpc: "2.0", id: 1, result: { ok: true } }),
-      },
-    ]);
-    const bridge = createBridge({
-      remoteUrl: "http://example/mcp",
-      getToken: async () => "tok-A",
-      fetchImpl: f.impl,
-    });
-
-    const req: JsonRpcRequest = { jsonrpc: "2.0", id: 1, method: "tools/list" };
-    const res = await bridge.handle(req);
-
-    expect(res).toEqual({ jsonrpc: "2.0", id: 1, result: { ok: true } });
-    expect(f.calls).toHaveLength(1);
-    expect((f.calls[0]?.init.headers as Record<string, string>).Authorization).toBe("Bearer tok-A");
-  });
-
-  it("reuses the cached token on a follow-up request and reuses the session id", async () => {
-    let tokenCalls = 0;
-    const f = fakeFetch([
-      {
-        status: 200,
-        contentType: "text/event-stream",
-        headers: { "mcp-session-id": "S2" },
-        body: sseEnvelope({ jsonrpc: "2.0", id: 1, result: { phase: "init" } }),
-      },
-      {
-        status: 200,
-        contentType: "text/event-stream",
-        body: sseEnvelope({ jsonrpc: "2.0", id: 2, result: { phase: "list" } }),
-      },
-    ]);
-    const bridge = createBridge({
-      remoteUrl: "http://example/mcp",
-      getToken: async () => {
-        tokenCalls++;
-        return "tok-cached";
-      },
-      fetchImpl: f.impl,
-    });
-
-    await bridge.handle({ jsonrpc: "2.0", id: 1, method: "initialize" });
-    await bridge.handle({ jsonrpc: "2.0", id: 2, method: "tools/list" });
-
-    expect(tokenCalls).toBe(1);
-    expect((f.calls[1]?.init.headers as Record<string, string>)["Mcp-Session-Id"]).toBe("S2");
-  });
-
-  it("refreshes the token after the cache TTL elapses", async () => {
-    const responses: MockResponse[] = [
-      {
-        status: 200,
-        contentType: "text/event-stream",
-        body: sseEnvelope({ jsonrpc: "2.0", id: 1, result: 1 }),
-      },
-      {
-        status: 200,
-        contentType: "text/event-stream",
-        body: sseEnvelope({ jsonrpc: "2.0", id: 2, result: 2 }),
-      },
-    ];
-    const f = fakeFetch(responses);
-    let issued = 0;
-    let clock = 1000;
-
-    const bridge = createBridge({
-      remoteUrl: "http://example/mcp",
-      getToken: async () => `tok-${++issued}`,
-      fetchImpl: f.impl,
-      tokenCacheTtlMs: 60_000,
-      now: () => clock,
-    });
-
-    await bridge.handle({ jsonrpc: "2.0", id: 1, method: "x" });
-    clock += 120_000; // beyond TTL
-    await bridge.handle({ jsonrpc: "2.0", id: 2, method: "x" });
-
-    expect(issued).toBe(2);
-    expect((f.calls[0]?.init.headers as Record<string, string>).Authorization).toBe("Bearer tok-1");
-    expect((f.calls[1]?.init.headers as Record<string, string>).Authorization).toBe("Bearer tok-2");
-  });
-
-  it("retries once on 401 with a forced token refresh", async () => {
-    const f = fakeFetch([
-      { status: 401, body: "unauthorized" },
-      {
-        status: 200,
-        contentType: "text/event-stream",
-        body: sseEnvelope({ jsonrpc: "2.0", id: 1, result: "after-refresh" }),
-      },
-    ]);
-    let issued = 0;
-    const bridge = createBridge({
-      remoteUrl: "http://example/mcp",
-      getToken: async () => `tok-${++issued}`,
-      fetchImpl: f.impl,
-      logError: () => {},
-    });
-
-    const res = await bridge.handle({ jsonrpc: "2.0", id: 1, method: "tools/list" });
-    expect(res).toEqual({ jsonrpc: "2.0", id: 1, result: "after-refresh" });
-    expect(issued).toBe(2); // first attempt cached tok-1, retry forced tok-2
-    expect(f.calls).toHaveLength(2);
-  });
-
-  it("retries when remote returns HTTP 200 but tool result reports upstream 401", async () => {
-    const f = fakeFetch([
-      {
-        status: 200,
-        contentType: "application/json",
-        body: JSON.stringify({
-          jsonrpc: "2.0",
-          id: 1,
-          result: {
-            isError: true,
-            content: [
-              {
-                type: "text",
-                text: "search issues: GET https://api.github.com/search/issues?q=x: 401 Bad credentials []",
-              },
-            ],
-          },
-        }),
-      },
-      {
-        status: 200,
-        contentType: "text/event-stream",
-        body: sseEnvelope({ jsonrpc: "2.0", id: 1, result: "after-refresh" }),
-      },
-    ]);
-    let issued = 0;
-    const bridge = createBridge({
-      remoteUrl: "http://example/mcp",
-      getToken: async () => `tok-${++issued}`,
-      fetchImpl: f.impl,
-      logError: () => {},
-    });
-    const res = await bridge.handle({ jsonrpc: "2.0", id: 1, method: "tools/call" });
-    expect(res).toEqual({ jsonrpc: "2.0", id: 1, result: "after-refresh" });
-    expect(issued).toBe(2);
-    expect(f.calls).toHaveLength(2);
-  });
-
-  it("retries when remote returns a JSON-RPC error whose message reports upstream 401", async () => {
-    const f = fakeFetch([
-      {
-        status: 200,
-        contentType: "application/json",
-        body: JSON.stringify({
-          jsonrpc: "2.0",
-          id: 1,
-          error: { code: -32603, message: "search issues: 401 Bad credentials" },
-        }),
-      },
-      {
-        status: 200,
-        contentType: "text/event-stream",
-        body: sseEnvelope({ jsonrpc: "2.0", id: 1, result: "after-refresh" }),
-      },
-    ]);
-    let issued = 0;
-    const bridge = createBridge({
-      remoteUrl: "http://example/mcp",
-      getToken: async () => `tok-${++issued}`,
-      fetchImpl: f.impl,
-      logError: () => {},
-    });
-    const res = await bridge.handle({ jsonrpc: "2.0", id: 1, method: "tools/call" });
-    expect(res).toEqual({ jsonrpc: "2.0", id: 1, result: "after-refresh" });
-    expect(issued).toBe(2);
-  });
-
-  it("returns a JSON-RPC error when the token getter yields null", async () => {
-    const f = fakeFetch([]);
-    const bridge = createBridge({
-      remoteUrl: "http://example/mcp",
-      getToken: async () => null,
-      fetchImpl: f.impl,
-    });
-    const res = await bridge.handle({ jsonrpc: "2.0", id: 7, method: "tools/call" });
-    expect(res?.error?.code).toBe(-32000);
-    expect(res?.error?.message).toContain("gh auth token");
-    expect(f.calls).toHaveLength(0);
-  });
-
-  it("returns null for notifications (no id) and still forwards them", async () => {
-    const f = fakeFetch([{ status: 200, contentType: "application/json", body: "{}" }]);
-    const bridge = createBridge({
-      remoteUrl: "http://example/mcp",
-      getToken: async () => "tok",
-      fetchImpl: f.impl,
-    });
-    const res = await bridge.handle({ jsonrpc: "2.0", method: "notifications/initialized" });
-    expect(res).toBeNull();
-    expect(f.calls).toHaveLength(1);
-  });
-
-  it("returns a JSON-RPC error on remote non-200 status", async () => {
-    const f = fakeFetch([{ status: 503, statusText: "Service Unavailable", body: "down" }]);
-    const bridge = createBridge({
-      remoteUrl: "http://example/mcp",
-      getToken: async () => "tok",
-      fetchImpl: f.impl,
-    });
-    const res = await bridge.handle({ jsonrpc: "2.0", id: 1, method: "x" });
-    expect(res?.error?.code).toBe(-32603);
-    expect(res?.error?.message).toContain("503");
-  });
-
-  it("returns a JSON-RPC error when fetch throws", async () => {
-    const erroringFetch = mock(async () => {
-      throw new Error("ECONNREFUSED");
-    });
-    const bridge = createBridge({
-      remoteUrl: "http://example/mcp",
-      getToken: async () => "tok",
-      fetchImpl: erroringFetch as unknown as typeof fetch,
-    });
-    const res = await bridge.handle({ jsonrpc: "2.0", id: 1, method: "x" });
-    expect(res?.error?.code).toBe(-32603);
-    expect(res?.error?.message).toContain("ECONNREFUSED");
-  });
-
-  it("normalizes union-type-null arrays in tools/list inputSchema so Gemini accepts them", async () => {
-    // Mirrors the real EnvoyDispatch schema the remote server emits: nullable arrays
-    // expressed as JSON-Schema union types { type: ["null", "array"] }, which Gemini rejects
-    // (array branch lacks items / orphaned items). The bridge must collapse these in transit.
-    const toolsList = {
-      jsonrpc: "2.0",
-      id: 1,
-      result: {
-        tools: [
-          {
-            name: "envoy_dispatch",
-            description: "Create a Dispatch thread",
-            inputSchema: {
-              type: "object",
-              required: ["parent", "subject", "body"],
-              properties: {
-                parent: { type: "string" },
-                ask: {
-                  type: ["null", "array"],
-                  items: {
-                    type: "object",
-                    required: ["question", "options"],
-                    properties: {
-                      question: { type: "string" },
-                      custom: { type: ["null", "boolean"] },
-                      options: {
-                        type: ["null", "array"],
-                        items: {
-                          type: "object",
-                          required: ["label"],
-                          properties: { label: { type: "string" } },
-                        },
-                      },
-                    },
-                  },
-                },
-              },
-            },
-          },
-        ],
-      },
-    };
-    const f = fakeFetch([
-      { status: 200, contentType: "application/json", body: JSON.stringify(toolsList) },
-    ]);
-    const bridge = createBridge({
-      remoteUrl: "http://example/mcp",
-      getToken: async () => "tok",
-      fetchImpl: f.impl,
-    });
-
-    const res = await bridge.handle({ jsonrpc: "2.0", id: 1, method: "tools/list" });
-    type SchemaNode = {
-      type?: unknown;
-      items?: SchemaNode;
-      properties?: Record<string, SchemaNode>;
-    };
-    const result = res?.result as { tools: Array<{ inputSchema: SchemaNode }> };
-    const ask = result.tools[0]?.inputSchema.properties?.ask;
-
-    // Nullable array collapses to a single-type array with items preserved.
-    expect(ask?.type).toBe("array");
-    expect(ask?.items).toBeDefined();
-    // Nested nullable array (options) collapses too.
-    expect(ask?.items?.properties?.options.type).toBe("array");
-    expect(ask?.items?.properties?.options.items).toBeDefined();
-    // Nullable boolean collapses to a single-type boolean.
-    expect(ask?.items?.properties?.custom.type).toBe("boolean");
-    // Nothing in the schema still uses a union type array (the shape Gemini rejects).
-    expect(JSON.stringify(res)).not.toContain('["null"');
-  });
-});

package/src/dispatch-mcp-bridge.ts

@@ -1,310 +0,0 @@
-// Core forwarding logic for the local MCP shim that proxies opencode's
-// stdio MCP traffic to the remote dispatch server's Streamable HTTP /mcp,
-// minting a fresh GitHub bearer per request via the user's `gh` shim.
-//
-// Exposed as a library so the bridge can be unit-tested without spawning
-// a real subprocess. The CLI wrapper in bin/dispatch-mcp-shim.ts wires
-// this to stdin/stdout.
-
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
-
-const execFileAsync = promisify(execFile);
-
-/** Refresh well before the 1h gh-app installation token expiry. */
-const DEFAULT_TOKEN_CACHE_TTL_MS = 50 * 60 * 1000;
-
-export interface JsonRpcRequest {
-  jsonrpc: "2.0";
-  id?: string | number;
-  method: string;
-  params?: unknown;
-}
-
-export interface JsonRpcResponse {
-  jsonrpc: "2.0";
-  id: string | number | null;
-  result?: unknown;
-  error?: { code: number; message: string; data?: unknown };
-}
-
-export type TokenGetter = () => Promise<string | null>;
-export type FetchImpl = typeof fetch;
-
-export interface BridgeOptions {
-  remoteUrl: string;
-  getToken: TokenGetter;
-  fetchImpl?: FetchImpl;
-  tokenCacheTtlMs?: number;
-  /** Optional logger for stderr-side diagnostics. */
-  logError?: (msg: string) => void;
-  /** Optional clock injection for tests. */
-  now?: () => number;
-}
-
-export interface Bridge {
-  handle(request: JsonRpcRequest): Promise<JsonRpcResponse | null>;
-}
-
-export const defaultGhTokenGetter: TokenGetter = async () => {
-  try {
-    const { stdout } = await execFileAsync("gh", ["auth", "token"], {
-      timeout: 5_000,
-    });
-    const value = stdout.trim();
-    return value.length > 0 ? value : null;
-  } catch {
-    return null;
-  }
-};
-
-/**
- * Parse a Streamable-HTTP SSE response and return the first `event: message`
- * payload as parsed JSON. Returns null if no message line was found.
- */
-function parseSseBody(body: string): unknown {
-  for (const line of body.split("\n")) {
-    const match = line.match(/^data:\s*(.+)$/);
-    if (match) {
-      return JSON.parse(match[1] as string);
-    }
-  }
-  return null;
-}
-
-/**
- * Detect whether a parsed JSON-RPC response indicates that the *upstream*
- * GitHub call failed with 401 (e.g. expired App-installation token).
- *
- * The Go MCP server forwards GitHub errors verbatim in the tool result
- * (`result.isError: true`, content text contains "401 Bad credentials")
- * or as a JSON-RPC error message. Either signal triggers a one-shot retry
- * with a freshly-minted token.
- */
-function hasUpstreamUnauthorized(parsed: unknown): boolean {
-  if (!parsed || typeof parsed !== "object") return false;
-  const obj = parsed as { error?: { message?: unknown }; result?: unknown };
-  if (
-    obj.error &&
-    typeof obj.error.message === "string" &&
-    containsUnauthorized(obj.error.message)
-  ) {
-    return true;
-  }
-  const result = obj.result as { isError?: unknown; content?: unknown } | undefined;
-  if (!result || result.isError !== true || !Array.isArray(result.content)) return false;
-  for (const item of result.content) {
-    if (
-      item &&
-      typeof item === "object" &&
-      "text" in item &&
-      typeof (item as { text: unknown }).text === "string"
-    ) {
-      if (containsUnauthorized((item as { text: string }).text)) return true;
-    }
-  }
-  return false;
-}
-
-function containsUnauthorized(msg: string): boolean {
-  return /\b401\b/.test(msg) && /bad credentials|unauthorized/i.test(msg);
-}
-
-/**
- * Collapse JSON-Schema union `type` arrays (e.g. { type: ["null", "array"] }) into a
- * single-type schema. Google Gemini's function-declaration validator rejects union-type
- * arrays: the array branch loses its `items` and the top-level `items` is left orphaned,
- * producing `any_of[0].items: missing field`. Remote dispatch tools express nullable fields
- * this way, so we normalize them in transit. Dropping "null" is safe — the model omits or
- * passes a real value, and `required` already governs presence.
- */
-function normalizeSchemaUnionTypes(node: unknown): unknown {
-  if (Array.isArray(node)) return node.map(normalizeSchemaUnionTypes);
-  if (!node || typeof node !== "object") return node;
-  const result: Record<string, unknown> = {};
-  for (const [key, value] of Object.entries(node)) {
-    result[key] = normalizeSchemaUnionTypes(value);
-  }
-  if (Array.isArray(result.type)) {
-    const nonNull = result.type.filter((t) => t !== "null");
-    if (nonNull.length === 1) {
-      result.type = nonNull[0];
-    } else if (nonNull.length === 0) {
-      result.type = "null";
-    } else {
-      // Multiple non-null types: express as anyOf, carrying items into the array branch
-      // so no branch is left itemless.
-      const items = result.items;
-      delete result.items;
-      result.anyOf = nonNull.map((t) =>
-        t === "array" && items != null ? { type: t, items } : { type: t }
-      );
-      delete result.type;
-    }
-  }
-  return result;
-}
-
-/**
- * Normalize tool input schemas in a `tools/list` response so downstream providers
- * (notably Gemini) accept them. No-op for any other response shape.
- */
-function normalizeToolsListResponse(response: JsonRpcResponse | null): JsonRpcResponse | null {
-  if (!response || typeof response.result !== "object" || response.result === null) return response;
-  const result = response.result as { tools?: unknown };
-  if (!Array.isArray(result.tools)) return response;
-  const tools = result.tools.map((entry) => {
-    if (!entry || typeof entry !== "object") return entry;
-    const tool = entry as Record<string, unknown>;
-    if (tool.inputSchema == null || typeof tool.inputSchema !== "object") return tool;
-    return { ...tool, inputSchema: normalizeSchemaUnionTypes(tool.inputSchema) };
-  });
-  return { ...response, result: { ...result, tools } };
-}
-
-/** Apply response normalization that depends on the request method. */
-function finalizeResponse(
-  request: JsonRpcRequest,
-  response: JsonRpcResponse | null
-): JsonRpcResponse | null {
-  return request.method === "tools/list" ? normalizeToolsListResponse(response) : response;
-}
-
-export function createBridge(opts: BridgeOptions): Bridge {
-  const remoteUrl = opts.remoteUrl;
-  const getToken = opts.getToken;
-  const fetchImpl = opts.fetchImpl ?? fetch;
-  const ttl = opts.tokenCacheTtlMs ?? DEFAULT_TOKEN_CACHE_TTL_MS;
-  const now = opts.now ?? Date.now;
-  const log = opts.logError ?? ((m) => process.stderr.write(`${m}\n`));
-
-  let cachedToken: { value: string; fetchedAt: number } | null = null;
-  let sessionId: string | null = null;
-
-  async function token(force: boolean): Promise<string | null> {
-    if (!force && cachedToken && now() - cachedToken.fetchedAt < ttl) {
-      return cachedToken.value;
-    }
-    const value = await getToken();
-    if (value) {
-      cachedToken = { value, fetchedAt: now() };
-    } else {
-      cachedToken = null;
-    }
-    return value;
-  }
-
-  function errorResponse(
-    id: string | number | null | undefined,
-    code: number,
-    message: string
-  ): JsonRpcResponse | null {
-    if (id === undefined || id === null) return null;
-    return { jsonrpc: "2.0", id, error: { code, message } };
-  }
-
-  async function attempt(
-    request: JsonRpcRequest,
-    forceRefresh: boolean
-  ): Promise<
-    | { kind: "ok"; response: JsonRpcResponse | null }
-    | { kind: "retry" }
-    | { kind: "err"; response: JsonRpcResponse | null }
-  > {
-    const bearer = await token(forceRefresh);
-    if (!bearer) {
-      return {
-        kind: "err",
-        response: errorResponse(
-          request.id,
-          -32000,
-          "envoy-dispatch shim: gh auth token returned empty — check your gh-app setup"
-        ),
-      };
-    }
-
-    const headers: Record<string, string> = {
-      Authorization: `Bearer ${bearer}`,
-      "Content-Type": "application/json",
-      Accept: "application/json, text/event-stream",
-    };
-    if (sessionId) headers["Mcp-Session-Id"] = sessionId;
-
-    let response: Response;
-    try {
-      response = await fetchImpl(remoteUrl, {
-        method: "POST",
-        headers,
-        body: JSON.stringify(request),
-      });
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      return {
-        kind: "err",
-        response: errorResponse(request.id, -32603, `envoy-dispatch shim network error: ${msg}`),
-      };
-    }
-
-    if (response.status === 401 && !forceRefresh) {
-      return { kind: "retry" };
-    }
-
-    const respSession = response.headers.get("mcp-session-id");
-    if (respSession) sessionId = respSession;
-
-    if (!response.ok) {
-      const body = await response.text().catch(() => "");
-      return {
-        kind: "err",
-        response: errorResponse(
-          request.id,
-          -32603,
-          `envoy-dispatch shim: remote ${response.status} ${response.statusText} ${body.slice(0, 200)}`
-        ),
-      };
-    }
-
-    if (request.id === undefined || request.id === null) {
-      // Notification — no response expected by JSON-RPC contract.
-      return { kind: "ok", response: null };
-    }
-
-    const body = await response.text();
-    const ct = response.headers.get("content-type") ?? "";
-    try {
-      const parsed = ct.includes("text/event-stream") ? parseSseBody(body) : JSON.parse(body);
-      if (parsed && typeof parsed === "object") {
-        if (!forceRefresh && hasUpstreamUnauthorized(parsed)) {
-          return { kind: "retry" };
-        }
-        return { kind: "ok", response: parsed as JsonRpcResponse };
-      }
-      return {
-        kind: "err",
-        response: errorResponse(
-          request.id,
-          -32603,
-          "envoy-dispatch shim: empty/invalid response body"
-        ),
-      };
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      return {
-        kind: "err",
-        response: errorResponse(request.id, -32603, `envoy-dispatch shim: parse error: ${msg}`),
-      };
-    }
-  }
-
-  return {
-    async handle(request: JsonRpcRequest): Promise<JsonRpcResponse | null> {
-      const first = await attempt(request, false);
-      if (first.kind === "ok" || first.kind === "err")
-        return finalizeResponse(request, first.response);
-      // retry once with forced refresh on 401
-      log("envoy-dispatch shim: 401 from remote, re-minting token and retrying once");
-      const second = await attempt(request, true);
-      return finalizeResponse(request, second.kind === "retry" ? null : second.response);
-    },
-  };
-}