@humwick/runner 0.0.0-stage → 0.130.1

package/src/relay-mcp.ts

@@ -0,0 +1,583 @@
+import { mcpServerInfo, parseToolGeneration, isRelayMcpServerName, type ToolGeneration } from "@humwick/sdk";
+import { relayEnv, writeChildEnv } from "@humwick/sdk/env";
+import { codexVaultMcpEnv } from "./mcp-vault-env";
+// Single home for the relay HTTP MCP endpoint descriptor + per-provider injection
+// args. Both adapters (and Stage 2's proxy) import from here so the endpoint path,
+// server name, and token-handling rules live in exactly one place.
+//
+// Token handling: the bearer token is NEVER placed in argv (it would leak via `ps`
+// and the agent's own process inspection). Claude expands `${AGENT_RELAY_SESSION_TOKEN}`
+// from the env at MCP-config parse time; Codex reads it from the named env var.
+//
+// Why a dedicated var and NOT `AGENT_RELAY_TOKEN`: a managed session inherits the
+// runner's scoped, identity-bearing session token, but Claude Code applies a rig/user
+// `settings.json` `env` block OVER the inherited env. A rig that sets
+// `env.AGENT_RELAY_TOKEN` (e.g. to the admin token, for interactive CLI use) would
+// clobber the scoped token at parse time, so the relay MCP connection authenticates as
+// the `server` actor with no agent identity — `relay_whoami` returns null and
+// `relay_send_message` demands a `from` it can't supply (#233). The runner exports the
+// scoped token under this dedicated name that rigs don't set, so nothing on the host can
+// hijack the managed agent's identity.
+export const RELAY_MCP_SERVER_NAME = mcpServerInfo("relay").name;
+export { isRelayMcpServerName };
+export const RELAY_MCP_PATH = "/api/mcp";
+export const RELAY_MCP_TOKEN_ENV = "AGENT_RELAY_SESSION_TOKEN";
+
+// #672 — shared host-listener MCP. The agent connects to ONE orchestrator-owned shared
+// `callmux` listener via a per-agent `callmux bridge`, fronting the host's NON-IDENTITY MCP
+// (tokenlean, github). The bridge is a stdio child (auto-reconnect + retry-once on a
+// listener/downstream hiccup; `--cwd` injects `x-callmux-cwd` for per-worktree session-cwd
+// isolation), so it rides the SAME provider injection as any provisioned stdio server. The
+// identity-bearing relay endpoint is NEVER routed here — it stays per-agent on #215.
+export { SHARED_MCP_SERVER_NAME };
+// callmux's documented manual-listener endpoint (`callmux --listen 4860`, Streamable HTTP at
+// /mcp). In managed launches the orchestrator owns the real listener URL and passes it through
+// AGENT_RELAY_SHARED_MCP_URL; this fallback is for direct runner/manual-listener use.
+export const DEFAULT_SHARED_MCP_URL = "http://localhost:4860/mcp";
+export const SHARED_MCP_URL_ENV = "AGENT_RELAY_SHARED_MCP_URL";
+export { runnerManagedToolDeferralRoute } from "./mcp-tool-deferral";
+
+/** Resolve the shared-listener URL: explicit runner option → env → documented default. */
+export function resolveSharedMcpUrl(explicit?: string): string {
+  return explicit ?? relayEnv(process.env, SHARED_MCP_URL_ENV) ?? DEFAULT_SHARED_MCP_URL;
+}
+
+export function runnerMcpGeneration(env: Record<string, string | undefined>): ToolGeneration {
+  return parseToolGeneration(relayEnv(env, "AGENT_RELAY_MCP_TOOLS"));
+}
+
+function generationEndpoint(endpoint: string, generation: ToolGeneration): string {
+  const url = new URL(endpoint);
+  if (generation === "humwick") url.searchParams.set("tools", generation);
+  else url.searchParams.delete("tools");
+  return url.toString();
+}
+
+export function relayMcpEndpoint(relayUrl: string, generation: ToolGeneration = "relay"): string {
+  return generationEndpoint(`${relayUrl.replace(/\/+$/, "")}${RELAY_MCP_PATH}`, generation);
+}
+
+// #1248 — per-server Codex MCP overrides. Default `tool_timeout_sec` (60s) and
+// `startup_timeout_ms` are too short for our long-running tools (tests/releases run
+// 5+ min), forcing agents to poll/sleep instead of just waiting on the call. Verified
+// against the installed codex-cli binary (0.144.0): both fields live on the
+// per-`[mcp_servers.<name>]` McpServerConfig struct, alongside `bearer_token_env_var`.
+export const CODEX_MCP_TOOL_TIMEOUT_SEC = 900;
+export const CODEX_MCP_STARTUP_TIMEOUT_MS = 30000;
+export const OPENCODE_MCP_TIMEOUT_MS = CODEX_MCP_TOOL_TIMEOUT_SEC * 1_000;
+
+function codexTimeoutConfigArgs(key: string): string[] {
+  return [
+    "-c",
+    `${key}.tool_timeout_sec=${CODEX_MCP_TOOL_TIMEOUT_SEC}`,
+    "-c",
+    `${key}.startup_timeout_ms=${CODEX_MCP_STARTUP_TIMEOUT_MS}`,
+  ];
+}
+
+// Codex: `-c mcp_servers.<name>.*` overrides. `bearer_token_env_var` tells Codex to
+// read the token from the env var itself → transport resolves to streamable_http.
+// `endpoint` overrides the target URL (runner-local proxy, Stage 2 #215) — see above.
+export function relayMcpCodexConfigArgs(relayUrl: string, endpoint?: string, generation: ToolGeneration = "relay"): string[] {
+  const key = `mcp_servers.${mcpServerInfo(generation).name}`;
+  return [
+    "-c",
+    `${key}.url=${tomlString(generationEndpoint(endpoint ?? relayMcpEndpoint(relayUrl), generation))}`,
+    "-c",
+    `${key}.bearer_token_env_var=${tomlString(RELAY_MCP_TOKEN_ENV)}`,
+    ...codexTimeoutConfigArgs(key),
+  ];
+}
+
+// Shared TOML string escaper for Codex `-c key=value` overrides. One home; codex.ts
+// imports this rather than re-declaring it.
+export function tomlString(value: string): string {
+  return JSON.stringify(value);
+}
+
+/** A JSON-shaped value as one TOML inline value, for a structured `-c key=<value>` override. */
+export function tomlInlineValue(value: unknown): string {
+  if (typeof value === "string") return tomlString(value);
+  if (typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) return String(value);
+  if (Array.isArray(value)) return `[${value.map(tomlInlineValue).join(",")}]`;
+  const record = plainRecord(value);
+  if (!record) throw new Error(`no TOML inline form for ${value === null ? "null" : typeof value}`);
+  return `{${Object.entries(record).filter(([, item]) => item !== undefined).map(([key, item]) => `${tomlString(key)}=${tomlInlineValue(item)}`).join(",")}}`;
+}
+
+type TomlScalar = string | number | boolean;
+
+function tomlValue(value: unknown): string | undefined {
+  if (typeof value === "string") return tomlString(value);
+  if (typeof value === "boolean") return String(value);
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  if (Array.isArray(value) && value.every((item): item is TomlScalar =>
+    typeof item === "string" || typeof item === "number" && Number.isFinite(item) || typeof item === "boolean")) {
+    return `[${value.map((item) => tomlValue(item)!).join(", ")}]`;
+  }
+  return undefined;
+}
+
+function plainRecord(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined;
+}
+
+/**
+ * Keep Codex-native MCP fields when projecting a host config into an isolated home. The
+ * provider-neutral shape has historically carried only command/args/url/env; dropping the
+ * native auth/header fields makes a copied remote server look applied while removing its
+ * credentials. Nested tables are returned separately because TOML tables must follow the
+ * server table rather than being emitted as dotted keys in its body.
+ */
+function codexNativeMcpToml(server: ProvisioningMcpServer): { root: string[]; nested: Array<{ name: string; lines: string[] }> } {
+  const root: string[] = [];
+  for (const key of ["env_vars", "cwd", "bearer_token_env_var", "disabled_tools"] as const) {
+    const rendered = tomlValue(server[key]);
+    if (rendered !== undefined) root.push(`${key} = ${rendered}`);
+  }
+  const nested: Array<{ name: string; lines: string[] }> = [];
+  for (const key of ["http_headers", "env_http_headers", "auth"] as const) {
+    const record = plainRecord(server[key]);
+    if (!record) {
+      const rendered = tomlValue(server[key]);
+      if (rendered !== undefined) root.push(`${key} = ${rendered}`);
+      continue;
+    }
+    const lines = Object.entries(record).flatMap(([name, value]) => {
+      const rendered = tomlValue(value);
+      return rendered === undefined ? [] : [`${tomlString(name)} = ${rendered}`];
+    });
+    if (lines.length) nested.push({ name: key, lines });
+  }
+  return { root, nested };
+}
+
+// #555 — compose the launch MCP set from (the relay endpoint, if relay.mcp) PLUS the
+// profile's relay-provisioned servers, PLUS (#662) the host USER-scope servers for an
+// `mcp.mode:"host"` profile. One `--mcp-config` JSON carries them all. `strict` adds
+// `--strict-mcp-config` so ONLY these load — Claude reads no on-disk config, so the
+// 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, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
+import { SHARED_MCP_SERVER_NAME, sharedCallmuxToolCallTimeoutMsFromEnv, type ProvisioningMcpServer } from "@humwick/sdk";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// #1301 — a bare `command: "callmux"` resolves off PATH, which can drift from the version
+// this package pins (root/runner/orchestrator all pin the same `callmux` dependency). npm
+// (and bun/pnpm workspaces) always link a dependency's declared bin to `node_modules/.bin/<name>`
+// at whichever ancestor directory it resolves/hoists to — the same layout-agnostic-bin
+// invariant #1305/#1222 rely on for the humwick CLI itself — so walk up from this
+// module's own location to find the PINNED bridge binary instead of trusting PATH. Falls
+// back to the bare name (old behavior) only if no bundled bin is found anywhere above.
+export function resolveCallmuxBin(startDir: string = __dirname): string {
+  let dir = resolvePath(startDir);
+  while (true) {
+    const candidate = join(dir, "node_modules", ".bin", "callmux");
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) return "callmux";
+    dir = parent;
+  }
+}
+
+// The shared-listener bridge as a provider-neutral stdio server descriptor: a `callmux bridge`
+// child fronting the host's shared listener, with per-agent `--cwd "$WORKTREE"` for session-cwd
+// isolation (#672). It flows through the existing claude/codex stdio injection unchanged.
+export function sharedMcpBridgeServer(url: string, cwd: string): ProvisioningMcpServer {
+  return {
+    command: resolveCallmuxBin(),
+    args: ["bridge", "--url", url, "--cwd", cwd, "--call-timeout", String(sharedCallmuxToolCallTimeoutMsFromEnv())],
+  };
+}
+
+// #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.
+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;
+  generation?: ToolGeneration;
+}
+
+function metaOnlyRelayServerConfig(relay: MetaOnlyRelayDownstream): Record<string, unknown> {
+  return {
+    url: generationEndpoint(relay.endpoint, relay.generation ?? "relay"),
+    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: sharedCallmuxToolCallTimeoutMsFromEnv(),
+  };
+}
+
+// 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> {
+  const callTimeoutMs = sharedCallmuxToolCallTimeoutMsFromEnv();
+  return {
+    $schema: "callmux/schema.json",
+    metaOnly: true,
+    exposeMetaTools: true,
+    callTimeoutMs,
+    servers: {
+      [SHARED_MCP_SERVER_NAME]: {
+        url,
+        transport: "streamable-http",
+        headers: { [CALLMUX_CWD_HEADER]: cwd },
+        // The shared listener owns caching; a per-agent cache would bypass the call log.
+        cachePolicy: { denyTools: ["*"] },
+        callTimeoutMs,
+      },
+      ...(relay ? { [mcpServerInfo(relay.generation ?? "relay").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,
+    env: writeChildEnv({}, { ...server.configEnv, ...(server.env ?? {}) }),
+  };
+}
+
+function claudeMcpServerEntry(server: ProvisioningMcpServer): Record<string, unknown> {
+  const merged = mergedConfigEnv(server);
+  const entry: Record<string, unknown> = {};
+  if (merged.type) entry.type = merged.type;
+  if (merged.command) entry.command = merged.command;
+  if (merged.args?.length) entry.args = merged.args;
+  if (merged.env && Object.keys(merged.env).length) entry.env = merged.env;
+  if (merged.url) entry.url = merged.url;
+  if (merged.headers && Object.keys(merged.headers).length) entry.headers = merged.headers;
+  return entry;
+}
+
+export interface ClaudeMcpConfigOpts {
+  relayUrl: string;
+  endpoint?: string;
+  includeRelay: boolean;
+  generation?: ToolGeneration;
+  servers?: Record<string, ProvisioningMcpServer>;
+  /** #662 — host USER-scope MCP servers (`~/.claude.json` `mcpServers`), re-injected for
+   *  `mcp.mode:"host"` so `--strict-mcp-config` PRESERVES them instead of dropping the
+   *  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>;
+}
+
+// #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).
+  for (const [name, server] of Object.entries(opts.hostServers ?? {})) {
+    if (isRelayMcpServerName(name)) continue;
+    const entry = claudeMcpServerEntry(server);
+    if (Object.keys(entry).length) mcpServers[name] = entry;
+  }
+  if (opts.includeRelay) {
+    mcpServers[mcpServerInfo(opts.generation ?? "relay").name] = {
+      type: "http",
+      url: generationEndpoint(opts.endpoint ?? relayMcpEndpoint(opts.relayUrl), opts.generation ?? "relay"),
+      headers: { Authorization: `Bearer \${${RELAY_MCP_TOKEN_ENV}}` },
+    };
+  }
+  for (const [name, server] of Object.entries(opts.servers ?? {})) {
+    // Never let a declared server shadow the relay endpoint (identity-bearing).
+    if (isRelayMcpServerName(name)) continue;
+    const entry = claudeMcpServerEntry(server);
+    if (Object.keys(entry).length) mcpServers[name] = entry;
+  }
+  return mcpServers;
+}
+
+// OpenCode's config strings use `{env:NAME}` rather than Claude's `${NAME}` convention.
+// Translate only the provider-neutral env/header values where `${NAME}` is documented as an
+// environment reference; command arguments remain literal.
+function openCodeConfigEnvValue(value: string): string {
+  return value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, "{env:$1}");
+}
+
+function openCodeMcpServerEntry(server: ProvisioningMcpServer): Record<string, unknown> | undefined {
+  const merged = mergedConfigEnv(server);
+  if (merged.command) {
+    const environment = Object.fromEntries(
+      Object.entries(merged.env ?? {}).map(([name, value]) => [name, openCodeConfigEnvValue(value)]),
+    );
+    return {
+      type: "local",
+      command: [merged.command, ...(merged.args ?? [])],
+      ...(merged.cwd ? { cwd: merged.cwd } : {}),
+      ...(Object.keys(environment).length ? { environment } : {}),
+      timeout: OPENCODE_MCP_TIMEOUT_MS,
+    };
+  }
+  if (!merged.url) return undefined;
+  const headers = Object.fromEntries(
+    Object.entries(merged.headers ?? {}).map(([name, value]) => [name, openCodeConfigEnvValue(value)]),
+  );
+  return {
+    type: "remote",
+    url: merged.url,
+    ...(Object.keys(headers).length ? { headers } : {}),
+    // Managed agents cannot complete an interactive OAuth flow. Provisioned credentials ride
+    // headers/env instead, so fail directly rather than opening a browser prompt.
+    oauth: false,
+    timeout: OPENCODE_MCP_TIMEOUT_MS,
+  };
+}
+
+export interface OpenCodeMcpConfigOpts {
+  relayUrl: string;
+  endpoint?: string;
+  includeRelay: boolean;
+  generation?: ToolGeneration;
+  servers?: Record<string, ProvisioningMcpServer>;
+}
+
+/** Render OpenCode's native `opencode.json#mcp` map without persisting any Relay credential. */
+export function openCodeMcpConfigPayload(opts: OpenCodeMcpConfigOpts): Record<string, unknown> {
+  const mcp: Record<string, unknown> = {};
+  if (opts.includeRelay) {
+    mcp[mcpServerInfo(opts.generation ?? "relay").name] = {
+      type: "remote",
+      url: generationEndpoint(opts.endpoint ?? relayMcpEndpoint(opts.relayUrl), opts.generation ?? "relay"),
+      headers: { Authorization: `Bearer {env:${RELAY_MCP_TOKEN_ENV}}` },
+      oauth: false,
+      timeout: OPENCODE_MCP_TIMEOUT_MS,
+    };
+  }
+  for (const [name, server] of Object.entries(opts.servers ?? {})) {
+    if (isRelayMcpServerName(name)) continue;
+    const entry = openCodeMcpServerEntry(server);
+    if (entry) mcp[name] = entry;
+  }
+  return mcp;
+}
+
+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 [];
+  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. #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 ?? {})) {
+    if (isRelayMcpServerName(name)) continue;
+    const server = codexVaultMcpEnv(mergedConfigEnv(rawServer));
+    const key = `mcp_servers.${name}`;
+    if (server.command) args.push("-c", `${key}.command=${tomlString(server.command)}`);
+    if (server.args?.length) args.push("-c", `${key}.args=[${server.args.map(tomlString).join(",")}]`);
+    if (server.url) args.push("-c", `${key}.url=${tomlString(server.url)}`);
+    if (server.env_vars) args.push("-c", `${key}.env_vars=${tomlInlineValue(server.env_vars)}`);
+    for (const [envKey, envVal] of Object.entries(server.env ?? {})) {
+      args.push("-c", `${key}.env.${envKey}=${tomlString(envVal)}`);
+    }
+    if (server.disabled_tools?.length) args.push("-c", `${key}.disabled_tools=${tomlValue(server.disabled_tools)}`);
+    args.push(...codexTimeoutConfigArgs(key)); // #1248
+  }
+  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 (isRelayMcpServerName(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 (isRelayMcpServerName(name)) continue;
+    const server = codexVaultMcpEnv(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)}`);
+    const native = codexNativeMcpToml(server);
+    lines.push(...native.root);
+    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"));
+    }
+    for (const nested of native.nested) {
+      blocks.push([`[${tableKey}.${nested.name}]`, ...nested.lines].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.
+/** Remove every `[prefix…]` table (header through the line before the next header). */
+export function withoutTomlTables(config: string, prefix: string): string {
+  const lines = config.split("\n");
+  const kept: string[] = [];
+  let dropping = false;
+  for (const line of lines) {
+    const header = /^\s*\[([^\]]+)\]\s*(?:#.*)?$/.exec(line);
+    if (header) dropping = header[1]!.trim().startsWith(prefix);
+    if (!dropping) kept.push(line);
+  }
+  return kept.join("\n");
+}
+
+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]) => !isRelayMcpServerName(name));
+  const configPath = join(codexHome, "config.toml");
+  const existing = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
+  // #3387 — every mcp_servers table in a managed CODEX_HOME is Relay-written: drop the previous
+  // launch's set first, so a host MCP class switched off on reuse leaves no stale server behind.
+  let config = withoutTomlTables(existing, "mcp_servers.");
+  if (!relevant.length) {
+    if (config !== existing) writeFileSync(configPath, config, { mode: 0o600 });
+    return;
+  }
+  mkdirSync(codexHome, { recursive: true });
+  for (const [name, rawServer] of relevant) {
+    const server = codexVaultMcpEnv(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)}`);
+    const native = codexNativeMcpToml(server);
+    bodyLines.push(...native.root);
+    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)}`));
+    }
+    for (const nested of native.nested) {
+      config = upsertTomlTable(config, `${tableKey}.${nested.name}`, nested.lines);
+    }
+  }
+  writeFileSync(configPath, config, { mode: 0o600 });
+}