agent-relay-runner 0.129.11 → 0.129.13

package/src/relay-mcp.ts

@@ -85,7 +85,7 @@ export function tomlString(value: string): string {
 // project-cwd `.mcp.json` is never discovered (its enable modal can't wedge a headless
 // agent). Whatever the assembler decides host mode should keep is injected here explicitly;
 // strict then preserves exactly that set and nothing else.
-import { existsSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
 import { SHARED_CALLMUX_TOOL_CALL_TIMEOUT_MS, type ProvisioningMcpServer } from "agent-relay-sdk";
@@ -120,7 +120,106 @@ export function sharedMcpBridgeServer(url: string, cwd: string): ProvisioningMcp
   };
 }
 
-function mergedConfigEnv(server: ProvisioningMcpServer): ProvisioningMcpServer {
+// #1575 — the per-agent metaOnly callmux for Codex workers. The header callmux reads to scope
+// session-cwd stdio downstreams (tokenlean) per worktree; the shared bridge injects it dynamically,
+// and here we pin it statically because a stdio callmux has no incoming request headers to forward.
+const CALLMUX_CWD_HEADER = "x-callmux-cwd";
+// The filename the per-agent metaOnly config is materialized under, inside the agent's relay-owned
+// provisioning home. Shared by the assembler (points `callmux --config <path>` at it) and the
+// materializer (writes it) so disk == launch.
+export const SHARED_MCP_METAONLY_CONFIG_FILENAME = "callmux-metaonly.json";
+
+// #1450 — the request header the per-agent metaOnly callmux sets on its relay downstream. The runner
+// proxy reads it to decide which relay tools/list view to serve: WITHOUT it (the agent's DIRECT relay
+// client) the proxy hides the on-demand set so only the eager hot-path set boots; WITH it (this
+// callmux, fronting the on-demand set) the proxy serves the FULL set the relay already returned so
+// callmux can route callmux_call to any of them. It can only ever widen the LIST back to that
+// relay-returned set — never authorization: tools/call stays scope-gated regardless (#215 / capability
+// neutrality). Kept out of `forward` so the relay itself never sees it.
+export const RELAY_MCP_ONDEMAND_SURFACE_HEADER = "x-agent-relay-ondemand-front";
+export const RELAY_MCP_ONDEMAND_SURFACE_VALUE = "1";
+
+// #1450 — a Codex worker's relay downstream inside the per-agent metaOnly callmux. It points at the
+// runner-LOCAL proxy (never the relay directly): the proxy injects the live relay token, so identity
+// rides through and the agent/callmux never hold the real token on disk (#215). `authSecret` is the
+// per-session PROXY secret (which the agent already holds in AGENT_RELAY_SESSION_TOKEN — writing it to
+// this 0600 config adds no exposure, and it is NOT the relay token). cachePolicy denies every tool:
+// relay ops are identity-bearing/mutating and must never be served from cache.
+export interface MetaOnlyRelayDownstream {
+  /** The runner-local proxy MCP endpoint (config.relayMcpEndpoint when the proxy is active). */
+  endpoint: string;
+  /** The per-session proxy secret the agent authenticates to the local proxy with. */
+  authSecret: string;
+}
+
+function metaOnlyRelayServerConfig(relay: MetaOnlyRelayDownstream): Record<string, unknown> {
+  return {
+    url: relay.endpoint,
+    transport: "streamable-http",
+    headers: {
+      Authorization: `Bearer ${relay.authSecret}`,
+      [RELAY_MCP_ONDEMAND_SURFACE_HEADER]: RELAY_MCP_ONDEMAND_SURFACE_VALUE,
+    },
+    // #1450 — never cache relay ops (identity-bearing/mutating). Wildcard-deny is explicit belt-and-
+    // suspenders on top of the config's disabled global cache TTL.
+    cachePolicy: { denyTools: ["*"] },
+    callTimeoutMs: SHARED_CALLMUX_TOOL_CALL_TIMEOUT_MS,
+  };
+}
+
+// The per-agent metaOnly callmux config: streamable-http downstreams exposing ONLY the callmux
+// meta-tools (callmux_search_tools/callmux_call/…). A Codex worker boots with ~11 meta-tool schemas
+// instead of the flat downstream schemas (#1570 dominant lever) and reaches the real tools on demand
+// through callmux_call.
+//   • The shared listener (SHARED_MCP_SERVER_NAME): the worktree cwd is a STATIC downstream header —
+//     the per-agent callmux runs over stdio (no incoming headers to forwardHeaders) and the worktree
+//     is fixed per agent, so a fixed x-callmux-cwd routes the shared listener's session-cwd tools to
+//     this worktree exactly as the dynamic bridge header did.
+//   • #1450 — when `relay` is given, the identity-bearing relay endpoint is added as a SECOND
+//     downstream (via the runner-local proxy) so the on-demand relay set loads through callmux_call.
+// Timeouts mirror the bridge's SHARED_CALLMUX_TOOL_CALL_TIMEOUT_MS floor so nested calls keep the same
+// call-timeout budget.
+export function sharedMcpMetaOnlyConfig(url: string, cwd: string, relay?: MetaOnlyRelayDownstream): Record<string, unknown> {
+  return {
+    $schema: "callmux/schema.json",
+    metaOnly: true,
+    exposeMetaTools: true,
+    callTimeoutMs: SHARED_CALLMUX_TOOL_CALL_TIMEOUT_MS,
+    servers: {
+      [SHARED_MCP_SERVER_NAME]: {
+        url,
+        transport: "streamable-http",
+        headers: { [CALLMUX_CWD_HEADER]: cwd },
+        callTimeoutMs: SHARED_CALLMUX_TOOL_CALL_TIMEOUT_MS,
+      },
+      ...(relay ? { [RELAY_MCP_SERVER_NAME]: metaOnlyRelayServerConfig(relay) } : {}),
+    },
+  };
+}
+
+// The per-agent metaOnly callmux as a provider-neutral stdio server descriptor: a `callmux --config
+// <path>` child running the config above. Rides the SAME claude/codex stdio injection as the plain
+// bridge. The config path is non-secret (a relay-owned scratch file), so it is safe in argv/config.
+export function sharedMcpMetaOnlyServer(configPath: string): ProvisioningMcpServer {
+  return {
+    command: resolveCallmuxBin(),
+    args: ["--config", configPath],
+  };
+}
+
+// Materialize the per-agent metaOnly config `sharedMcpMetaOnlyServer(configPath)` points at. The
+// shared-listener URL is non-secret. #1450 — when a `relay` downstream is given, the config carries
+// the per-session PROXY secret (NOT the relay token — the proxy injects that; #215). The agent
+// already holds the proxy secret in AGENT_RELAY_SESSION_TOKEN, so the 0600 file adds no exposure.
+export function writeSharedMcpMetaOnlyConfig(configPath: string, url: string, cwd: string, relay?: MetaOnlyRelayDownstream): void {
+  mkdirSync(dirname(configPath), { recursive: true });
+  writeFileSync(configPath, JSON.stringify(sharedMcpMetaOnlyConfig(url, cwd, relay), null, 2) + "\n", { mode: 0o600 });
+}
+
+// #1292 — shared by the Claude JSON payload builder and the Codex TOML materializer, so
+// both projections merge `configEnv` (non-secret, allowlisted literals) into `env` the
+// same way instead of re-deriving the merge twice.
+export function mergedConfigEnv(server: ProvisioningMcpServer): ProvisioningMcpServer {
   if (!server.configEnv || Object.keys(server.configEnv).length === 0) return server;
   return {
     ...server,
@@ -140,7 +239,7 @@ function claudeMcpServerEntry(server: ProvisioningMcpServer): Record<string, unk
   return entry;
 }
 
-export function claudeMcpLaunchArgs(opts: {
+export interface ClaudeMcpConfigOpts {
   relayUrl: string;
   endpoint?: string;
   includeRelay: boolean;
@@ -150,8 +249,12 @@ export function claudeMcpLaunchArgs(opts: {
    *  ambient host MCP a host-base agent loaded before strict. Lowest precedence: the relay
    *  endpoint and relay-provisioned servers win on a name collision (relay decides). */
   hostServers?: Record<string, ProvisioningMcpServer>;
-  strict?: boolean;
-}): string[] {
+}
+
+// #1292 — the `{ mcpServers: {...} }` object Claude parses, extracted so both the launch
+// assembler (decides whether it's written to argv or a file) and the materializer (writes
+// the file) build the IDENTICAL payload from the same inputs.
+export function claudeMcpConfigPayload(opts: ClaudeMcpConfigOpts): Record<string, unknown> {
   const mcpServers: Record<string, unknown> = {};
   // Host user-scope servers go in first so relay endpoint + provisioned servers below can
   // override them by name (relay-owned config is authoritative over ambient host MCP).
@@ -173,13 +276,35 @@ export function claudeMcpLaunchArgs(opts: {
     const entry = claudeMcpServerEntry(server);
     if (Object.keys(entry).length) mcpServers[name] = entry;
   }
+  return mcpServers;
+}
+
+export function claudeMcpLaunchArgs(opts: ClaudeMcpConfigOpts & {
+  strict?: boolean;
+  /** #1292 — when set, `--mcp-config` points at this path instead of carrying the JSON
+   *  inline. Inline JSON lands verbatim in argv, which is world-readable via `ps`/
+   *  `/proc/<pid>/cmdline`; a provisioned server's `env`/`headers` can carry a literal
+   *  secret, so any launch with a relay-owned scratch dir to write into (see
+   *  `providerProvisioningHomePathFor`) MUST use this instead. The caller is responsible
+   *  for actually writing the file (the launch assembler is pure) — see
+   *  `materializeLaunchAssembly` / `claudeMcpConfigPayload`. */
+  configFilePath?: string;
+}): string[] {
+  const mcpServers = claudeMcpConfigPayload(opts);
   // Nothing to inject and not enforcing strict isolation → don't pass an empty config.
   if (Object.keys(mcpServers).length === 0 && !opts.strict) return [];
-  return ["--mcp-config", JSON.stringify({ mcpServers }), ...(opts.strict ? ["--strict-mcp-config"] : [])];
+  const configArg = opts.configFilePath ?? JSON.stringify({ mcpServers });
+  return ["--mcp-config", configArg, ...(opts.strict ? ["--strict-mcp-config"] : [])];
 }
 
-// #555 (Codex) — `-c mcp_servers.<name>.*` overrides for each relay-provisioned
-// server, the same shape relayMcpCodexConfigArgs uses for the relay endpoint.
+// #555 (Codex) — `-c mcp_servers.<name>.*` overrides for each relay-provisioned server, the
+// same shape relayMcpCodexConfigArgs uses for the relay endpoint. #1292 — this puts a
+// provisioned server's literal `env`/`headers` secret material in argv (world-readable via
+// `ps`/`/proc/<pid>/cmdline`), so it's ONLY safe to use when there is no isolated CODEX_HOME
+// to materialize `codexProvisionedMcpToml` into instead (host-base Codex reuses the real
+// `~/.codex`, which relay must not write provisioned secrets into — see
+// `providerHomePathFor`). Callers with an isolated CODEX_HOME must use
+// `codexProvisionedMcpTimeoutArgs` + `codexProvisionedMcpToml` instead.
 export function codexProvisionedMcpArgs(servers?: Record<string, ProvisioningMcpServer>): string[] {
   const args: string[] = [];
   for (const [name, rawServer] of Object.entries(servers ?? {})) {
@@ -196,3 +321,87 @@ export function codexProvisionedMcpArgs(servers?: Record<string, ProvisioningMcp
   }
   return args;
 }
+
+// #1292 — the non-secret half of the provisioned-server `-c` overrides (per-server
+// tool/startup timeouts only). Pairs with `codexProvisionedMcpToml`, which carries
+// command/args/url/env into CODEX_HOME/config.toml instead of argv.
+export function codexProvisionedMcpTimeoutArgs(servers?: Record<string, ProvisioningMcpServer>): string[] {
+  const args: string[] = [];
+  for (const name of Object.keys(servers ?? {})) {
+    if (name === RELAY_MCP_SERVER_NAME) continue;
+    args.push(...codexTimeoutConfigArgs(`mcp_servers.${name}`));
+  }
+  return args;
+}
+
+// #1292 — renders provisioned servers as `[mcp_servers.<name>]` / `[mcp_servers.<name>.env]`
+// TOML tables for CODEX_HOME/config.toml, mirroring the `-c mcp_servers.<name>.*` dotted-key
+// shape `codexProvisionedMcpArgs` uses, so command/args/url/env never touch argv. Table/key
+// names are always TOML-quoted (server + env-var names aren't guaranteed bare-key safe).
+export function codexProvisionedMcpToml(servers?: Record<string, ProvisioningMcpServer>): string {
+  const blocks: string[] = [];
+  for (const [name, rawServer] of Object.entries(servers ?? {})) {
+    if (name === RELAY_MCP_SERVER_NAME) continue;
+    const server = mergedConfigEnv(rawServer);
+    const tableKey = `mcp_servers.${tomlString(name)}`;
+    const lines: string[] = [`[${tableKey}]`];
+    if (server.command) lines.push(`command = ${tomlString(server.command)}`);
+    if (server.args?.length) lines.push(`args = [${server.args.map(tomlString).join(", ")}]`);
+    if (server.url) lines.push(`url = ${tomlString(server.url)}`);
+    if (lines.length > 1) blocks.push(lines.join("\n"));
+    const envEntries = Object.entries(server.env ?? {});
+    if (envEntries.length) {
+      blocks.push([`[${tableKey}.env]`, ...envEntries.map(([k, v]) => `${tomlString(k)} = ${tomlString(v)}`)].join("\n"));
+    }
+  }
+  return blocks.length ? `${blocks.join("\n\n")}\n` : "";
+}
+
+// Replace a `[header]` TOML table's body in-place (or append it if absent). Used to keep
+// repeated materialize calls for the same instance idempotent — a changed server env
+// replaces the old table body instead of duplicating it.
+export function upsertTomlTable(config: string, header: string, bodyLines: string[]): string {
+  const headerLine = `[${header}]`;
+  const lines = config.length ? config.split("\n") : [];
+  const headerIndex = lines.findIndex((line) => line.trim() === headerLine);
+  if (headerIndex < 0) {
+    const prefix = config.length ? (config.endsWith("\n") ? config : `${config}\n`) : "";
+    return `${prefix}${prefix.length ? "\n" : ""}${headerLine}\n${bodyLines.join("\n")}${bodyLines.length ? "\n" : ""}`;
+  }
+  let nextHeaderIndex = lines.length;
+  for (let i = headerIndex + 1; i < lines.length; i += 1) {
+    if (/^\s*\[[^\]]+\]\s*(?:#.*)?$/.test(lines[i] ?? "")) {
+      nextHeaderIndex = i;
+      break;
+    }
+  }
+  lines.splice(headerIndex + 1, nextHeaderIndex - (headerIndex + 1), ...bodyLines);
+  return lines.join("\n");
+}
+
+// #1292 — idempotently upsert provisioned MCP servers' command/args/url/env into
+// CODEX_HOME/config.toml, the isolated per-instance home Codex actually reads. Pairs with
+// `codexProvisionedMcpTimeoutArgs` (the non-secret `-c` overrides that stay in argv). Only
+// safe to call for an ISOLATED CODEX_HOME (host-base reuses the real `~/.codex`, which relay
+// must never write provisioned secrets into) — callers gate on `providerHomePathFor`.
+export function writeCodexMcpServersToml(codexHome: string, servers: Record<string, ProvisioningMcpServer> | undefined): void {
+  const relevant = Object.entries(servers ?? {}).filter(([name]) => name !== RELAY_MCP_SERVER_NAME);
+  if (!relevant.length) return;
+  mkdirSync(codexHome, { recursive: true });
+  const configPath = join(codexHome, "config.toml");
+  let config = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
+  for (const [name, rawServer] of relevant) {
+    const server = mergedConfigEnv(rawServer);
+    const tableKey = `mcp_servers.${tomlString(name)}`;
+    const bodyLines: string[] = [];
+    if (server.command) bodyLines.push(`command = ${tomlString(server.command)}`);
+    if (server.args?.length) bodyLines.push(`args = [${server.args.map(tomlString).join(", ")}]`);
+    if (server.url) bodyLines.push(`url = ${tomlString(server.url)}`);
+    config = upsertTomlTable(config, tableKey, bodyLines);
+    const envEntries = Object.entries(server.env ?? {});
+    if (envEntries.length) {
+      config = upsertTomlTable(config, `${tableKey}.env`, envEntries.map(([k, v]) => `${tomlString(k)} = ${tomlString(v)}`));
+    }
+  }
+  writeFileSync(configPath, config, { mode: 0o600 });
+}