@sjawhar/opencode-legion-envoy 0.1.10 → 0.2.0

package/src/dispatch-mcp-bridge.ts

@@ -0,0 +1,310 @@
+// 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);
+    },
+  };
+}

package/src/dispatch-mcp.ts

@@ -0,0 +1,102 @@
+import path from "node:path";
+import type { DispatchConfig } from "./config";
+
+/**
+ * OpenCode local MCP config shape that we inject into `config.mcp`. We use
+ * `type: "local"` (subprocess via stdio) instead of `type: "remote"` so we
+ * can rotate the GitHub bearer transparently — the StreamableHTTPClient
+ * transport snapshots static headers once at construction, which would
+ * break MCP calls after the gh-app installation token expires (~1h).
+ *
+ * The shim subprocess mints a fresh token via `gh auth token` per request
+ * (with a 50-minute in-memory cache), so OpenCode never sees an expired
+ * token. The user's `gh` shim handles per-CWD profile selection via the
+ * project's `.git/config` `[gh-app "<profile>"]` block.
+ */
+export interface DispatchMcpEntry {
+  type: "local";
+  command: string[];
+  environment: Record<string, string>;
+  enabled: true;
+}
+
+export interface BuildDispatchMcpEntryOptions {
+  dispatch: DispatchConfig | undefined;
+  /**
+   * Absolute path to the shim entry script. Defaults to the colocated
+   * `bin/dispatch-mcp-shim.ts` next to this module. Override in tests.
+   */
+  shimPath?: string;
+  /**
+   * Command used to launch the shim. Defaults to `bun`. Override in tests
+   * or when a different runtime is desired (e.g. `node` with a compiled
+   * shim).
+   */
+  runtime?: string;
+}
+
+const DEFAULT_SERVER_URL = "http://localhost:8766";
+
+function defaultShimPath(): string {
+  // import.meta.dir resolves to this file's directory in Bun, e.g.
+  // /home/ubuntu/legion/default/packages/envoy-plugin/src — go up one
+  // level to the package root, then into bin/.
+  return path.join(import.meta.dir, "..", "bin", "dispatch-mcp-shim.ts");
+}
+
+/**
+ * Build the OpenCode `mcp.envoy` entry. Returns null when dispatch
+ * is not enabled in envoy.json.
+ *
+ * Token availability is NOT validated here — the shim subprocess handles
+ * token fetching at request time. If `gh auth token` fails inside the
+ * shim, the affected MCP request returns a JSON-RPC error with a helpful
+ * message; other MCP servers continue to work.
+ */
+export function buildDispatchMcpEntry(opts: BuildDispatchMcpEntryOptions): DispatchMcpEntry | null {
+  if (!opts.dispatch?.enabled) return null;
+
+  const baseUrl = (opts.dispatch.serverUrl ?? DEFAULT_SERVER_URL).replace(/\/+$/, "");
+  const shimPath = opts.shimPath ?? defaultShimPath();
+  const runtime = opts.runtime ?? "bun";
+
+  return {
+    type: "local",
+    command: [runtime, shimPath],
+    environment: {
+      DISPATCH_MCP_URL: `${baseUrl}/mcp`,
+    },
+    enabled: true,
+  };
+}
+
+/**
+ * Inject the envoy MCP entry into an OpenCode `cfg` object. Returns a
+ * structured result instead of logging directly so the behavior is pure and
+ * testable; the caller forwards `warning` to the plugin logger when present.
+ *
+ * Idempotent on the plugin's own re-writes: when the existing `cfg.mcp.envoy`
+ * deep-equals the entry we'd inject, this is a silent no-op. OpenCode's
+ * InstanceState invalidation can re-run the plugin's config hook against a
+ * Config-service cfg that still carries our prior mutation; without the
+ * idempotency check that legitimate re-entry path produces a TUI stderr
+ * alarm. A warning still fires when the existing entry is genuinely
+ * different from ours (a user override the plugin must not clobber).
+ */
+export function injectEnvoyMcp(
+  cfg: { mcp?: Record<string, unknown> } & Record<string, unknown>,
+  entry: DispatchMcpEntry
+): { warning?: string } {
+  cfg.mcp = cfg.mcp ?? {};
+  const existing = (cfg.mcp as Record<string, unknown>).envoy;
+  if (existing !== undefined) {
+    if (JSON.stringify(existing) === JSON.stringify(entry)) {
+      return {};
+    }
+    return {
+      warning: "[envoy-plugin] envoy MCP entry already present in config; not overriding",
+    };
+  }
+  (cfg.mcp as Record<string, unknown>).envoy = entry;
+  return {};
+}

package/src/dispatch-subscribe.ts

@@ -0,0 +1,52 @@
+// Auto-subscription wiring for the envoy_dispatch MCP tool (Dispatch AC#4).
+//
+// 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
+// to RECEIVE that answer, its session must be subscribed to the thread's Envoy
+// topic (notifications.github.<owner>.<repo>.issue.<thread>.>). The dispatch
+// tool is served by the Go dispatch server and has no OpenCode session context,
+// so we close the loop in the plugin (which does know the session id) from the
+// tool.execute.after hook.
+//
+// This module is the pure, testable core: it turns a completed tool execution
+// into the topic the calling session should subscribe to, or null when the
+// execution isn't a successful envoy_dispatch call.
+
+// Matches a GitHub issue URL anywhere in the tool output and captures
+// owner / repo / number. The dispatch tool returns {"thread":N,"url":"…"} as
+// its text content, so the URL is always present on success.
+const ISSUE_URL_RE = /https?:\/\/github\.com\/([^/\s"]+)\/([^/\s"]+)\/issues\/(\d+)/i;
+
+// The tool is registered on the Go MCP server as "dispatch" and exposed to
+// OpenCode under the "envoy" MCP server (so commonly "envoy_dispatch"). Accept
+// any separator a client might use while still excluding unrelated tools.
+const DISPATCH_TOOL_RE = /(^|[-._])dispatch$/i;
+
+export function isDispatchTool(tool: string): boolean {
+  return DISPATCH_TOOL_RE.test(tool);
+}
+
+/** Build the Envoy topic carrying every event on a dispatch thread issue. */
+export function dispatchThreadTopic(owner: string, repo: string, thread: number): string {
+  return `notifications.github.${owner}.${repo}.issue.${thread}.>`;
+}
+
+/**
+ * Given a completed tool execution (name + textual output), return the Envoy
+ * topic the calling session should subscribe to so it receives replies on the
+ * dispatch thread — or null when this isn't a successful envoy_dispatch call.
+ *
+ * Parsing the GitHub issue URL out of the output (rather than trusting a JSON
+ * field) keeps this robust to however OpenCode surfaces the MCP result: owner,
+ * repo, and thread number all come from the canonical issue URL.
+ */
+export function dispatchSubscriptionTopic(tool: string, output: string): string | null {
+  if (!isDispatchTool(tool)) return null;
+  const match = ISSUE_URL_RE.exec(output);
+  if (!match) return null;
+  const owner = match[1] as string;
+  const repo = match[2] as string;
+  const thread = Number(match[3]);
+  if (!Number.isInteger(thread) || thread <= 0) return null;
+  return dispatchThreadTopic(owner, repo, thread);
+}

package/src/log.ts

@@ -0,0 +1,86 @@
+import { appendFile, mkdir } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+/**
+ * File-based logger for the envoy-plugin.
+ *
+ * Plugins load in-process with OpenCode, which means any byte a plugin writes
+ * to process.stderr / process.stdout goes straight to the terminal that the
+ * TUI is rendering into — corrupting the screen. console.warn / console.error
+ * therefore become a UX bug, not a diagnostic tool.
+ *
+ * This logger writes to a file instead. Default location colocates with
+ * OpenCode's own logs (~/.local/share/opencode/log/) so plugin diagnostics
+ * are discoverable next to the host's logs without leaking into the render.
+ *
+ * The API is intentionally narrow (warn / error / info) so callers can't
+ * accidentally substitute it for console (e.g. console.log is also unsafe in
+ * a TUI host).
+ */
+
+export interface LoggerOptions {
+  /** Directory the log file is written into. Created on demand. */
+  logDir?: string;
+  /** File name within logDir. Defaults to "envoy-plugin.log". */
+  fileName?: string;
+}
+
+export interface Logger {
+  warn(message: string): void;
+  error(message: string): void;
+  info(message: string): void;
+  /** Resolve after every queued write has flushed to disk. Useful in tests. */
+  flush(): Promise<void>;
+}
+
+function defaultLogDir(): string {
+  // Match OpenCode's log directory so plugin diagnostics live next to the
+  // host's structured logs. Falls back to tmpdir if HOME is somehow unset.
+  const home = os.homedir();
+  if (!home) return path.join(os.tmpdir(), "opencode-log");
+  return path.join(home, ".local", "share", "opencode", "log");
+}
+
+function format(level: "WARN" | "ERROR" | "INFO", message: string): string {
+  return `${new Date().toISOString()} ${level} ${message}\n`;
+}
+
+export function createLogger(options: LoggerOptions = {}): Logger {
+  const dir = options.logDir ?? defaultLogDir();
+  const file = path.join(dir, options.fileName ?? "envoy-plugin.log");
+
+  // Serialize writes through a promise chain so concurrent log calls don't
+  // interleave bytes mid-line and so flush() can await everything.
+  let chain: Promise<void> = Promise.resolve();
+
+  const append = (line: string) => {
+    chain = chain
+      .then(() => mkdir(dir, { recursive: true }))
+      .then(() => appendFile(file, line))
+      // Diagnostics must never crash the host. Swallow the error — there's
+      // nowhere safe to surface it (console is the very thing we're avoiding).
+      .catch(() => {});
+  };
+
+  return {
+    warn(message) {
+      append(format("WARN", message));
+    },
+    error(message) {
+      append(format("ERROR", message));
+    },
+    info(message) {
+      append(format("INFO", message));
+    },
+    async flush() {
+      await chain;
+    },
+  };
+}
+
+/**
+ * Default singleton used by the plugin internals. Tests that need an
+ * isolated log path call `createLogger({ logDir })` directly.
+ */
+export const logger: Logger = createLogger();