@humwick/runner 0.130.5 → 0.130.6

package/src/relay-mcp-proxy.ts

@@ -1,5 +1,5 @@
-import { registryToolName, mcpServerInfo, parseToolGeneration } from "@humwick/sdk";
-import { relayHeader, relayHeaderConflict, errMessage, isRecord, resendOnRotatedToken } from "@humwick/sdk";
+import { MCP_SERVER_INFO } from "@humwick/sdk";
+import { relayHeader, errMessage, isRecord, resendOnRotatedToken } from "@humwick/sdk";
 import { forwardSharedMcp, type WebToolLogOptions } from "./web-tool-call-proxy";
 import { materializeArtifactPathUpload } from "./artifact-path-materialize";
 import { logger } from "./logger";
@@ -10,12 +10,12 @@ import { RELAY_MCP_ONDEMAND_SURFACE_VALUE } from "./relay-mcp";
 // member; the real global `fetch` satisfies it.
 export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 
-// #2429 — Bun accepts a non-standard `timeout` member on the fetch init (ms, or `false` to disable
+// Bun accepts a non-standard `timeout` member on the fetch init (ms, or `false` to disable
 // its native HTTP idle watchdog), but bun-types@1.3.14 don't declare it, so a bare literal fails
-// typecheck. Widen locally (mirrors the #2428 Phase-1 pattern) instead of casting to `any`.
+// typecheck. Widen locally (mirrors the Phase-1 pattern) instead of casting to `any`.
 export type RelayForwardRequestInit = RequestInit & { timeout?: number | false };
 
-// Stage 2 of #213/#215 — the Runner becomes the MCP endpoint the agent connects to,
+// Stage 2 of — the Runner becomes the MCP endpoint the agent connects to,
 // fronting the relay. The agent's MCP client points at this localhost server instead of
 // directly at the relay, so the Runner owns the relay connection, reconnect/backoff, and a
 // durable buffer. A relay restart/crash becomes invisible to the agent.
@@ -27,7 +27,7 @@ export type RelayForwardRequestInit = RequestInit & { timeout?: number | false }
 //                       the live-tool-set capability the relay's static endpoint can't.
 //   2. `tools/list`   — forward (the relay already scope-filters per token), then context-
 //                       NARROW: hide tools that don't apply to this agent's workspace mode/
-//                       state (e.g. `relay_workspace_*` for a non-worktree agent). Strictly
+//                       state (e.g. `humwick_workspace_*` for a non-worktree agent). Strictly
 //                       a subset — never widens. Served from a last-known cache during a blip.
 //   3. `tools/call`   — forward with the runner's LIVE token; for bufferable writes during a
 //                       relay outage, enqueue durably + return a synthetic "queued" ok so the
@@ -41,7 +41,7 @@ export type RelayForwardRequestInit = RequestInit & { timeout?: number | false }
 // already returned, so a proxy bug can never become an auth bypass — the relay owns the lock at
 // `tools/call`, the proxy owns the menu.
 //
-// #1450 (the #1570 unify) adds a SECOND narrowing dimension for Codex lean workers: the on-demand
+// adds a SECOND narrowing dimension for Codex lean workers: the on-demand
 // relay set. The agent's DIRECT relay client has its on-demand tools hidden here so only the eager
 // hot-path set boots; the SAME tools are simultaneously fronted by the per-agent metaOnly callmux
 // (a second relay downstream over THIS proxy), reachable via callmux_call. callmux's requests carry
@@ -55,7 +55,7 @@ const PROXY_PATH = "/mcp";
 // Relay-side failures we treat as "relay down" (buffer/serve-cache), as opposed to a real 4xx
 // rejection that must be surfaced to the agent verbatim.
 const GATEWAY_STATUSES = new Set([502, 503, 504]);
-// #2089 — gateway sub-classes for the connect-retry safety boundary. A 502/503 means the reverse
+// gateway sub-classes for the connect-retry safety boundary. A 502/503 means the reverse
 // proxy could not reach the relay at all → the request never executed → safe to retry any tool
 // (connect-phase). A 504 means the proxy DID forward and the relay's response was lost → the outcome
 // is ambiguous → only safe to retry an idempotent call (same rule as a mid-flight socket reset).
@@ -63,15 +63,15 @@ const CONNECT_PHASE_GATEWAY_STATUSES = new Set([502, 503]);
 const AMBIGUOUS_GATEWAY_STATUSES = new Set([504]);
 const SSE_KEEPALIVE_MS = 25_000;
 
-// #1790/#2089 — relay_spawn_agent is IDEMPOTENT by spawnRequestId: the server dedupes a repeat of the
+// humwick_spawn_agent is IDEMPOTENT by spawnRequestId: the server dedupes a repeat of the
 // same id to the existing spawn instead of creating a second agent (see src/services/spawn-agent.ts).
 // The proxy stabilizes that id up-front (below) so a retry across a restart can't double-create. This
-// name is used only for that id-stabilization; the connect-retry itself (#2089) is GENERIC across every
+// name is used only for that id-stabilization; the connect-retry itself is GENERIC across every
 // tool and keys "safe to resend an ambiguous failure" off the presence of an idempotency key, never a
 // tool name.
-const SPAWN_TOOL = "relay_spawn_agent";
+const SPAWN_TOOL = "humwick_spawn_agent";
 
-// #2089 — bounded connect-retry defaults. A CD deploy restarts the fleet relay on every green
+// bounded connect-retry defaults. A CD deploy restarts the fleet relay on every green
 // origin/main SHA (systemctl restart, no drain/quiesce); tool calls in that ~1-2 min window otherwise
 // fail hard with "-32002 relay unreachable" and require a manual retry. The window (~75s) rides out
 // the restart; backoff climbs 0.5→1→2→4s (capped) with jitter to avoid a thundering-herd reconnect.
@@ -84,12 +84,12 @@ const DEFAULT_CONNECT_RETRY_MAX_BACKOFF_MS = 4_000;
 const DEFAULT_CONNECT_RETRY_WINDOW_MS = 75_000;
 const RELAY_MCP_METADATA_FORWARD_TIMEOUT_MS = 10_000;
 // A tool call can legitimately block in Relay: workspace status alone permits a
-// 600-second wait, and spawn/artifact operations can also take time. relay_run
-// separately caps its wait at 10s (#2790): this proxy budget cannot extend a
+// 600-second wait, and spawn/artifact operations can also take time. humwick_run
+// separately caps its wait at 10s: this proxy budget cannot extend a
 // provider client's shorter timeout. Keep the deadline for the other tools.
 const RELAY_MCP_TOOL_CALL_FORWARD_TIMEOUT_MS = 610_000;
 
-// #2089 — the connect-retry safety boundary rests on distinguishing WHEN in a request's lifecycle the
+// the connect-retry safety boundary rests on distinguishing WHEN in a request's lifecycle the
 // transport failed. A failure is one of three classes:
 //
 //   "connect"   — the request provably NEVER reached the relay app: connection refused, DNS failure,
@@ -117,8 +117,8 @@ function classifyGatewayStatus(status: number): TransportErrorClass {
   return "fatal";
 }
 
-// #2089 — a tool call is idempotent (safe to resend after an ambiguous failure) iff it carries a key the
-// server dedupes on: spawnRequestId (relay_spawn_agent) or idempotencyKey (buffered writes, task deliver).
+// a tool call is idempotent (safe to resend after an ambiguous failure) iff it carries a key the
+// server dedupes on: spawnRequestId (humwick_spawn_agent) or idempotencyKey (buffered writes, task deliver).
 // Generic — no tool names — so any tool gaining such a key qualifies automatically.
 function isIdempotentCall(args: Record<string, unknown>): boolean {
   const spawnRequestId = typeof args.spawnRequestId === "string" ? args.spawnRequestId.trim() : "";
@@ -130,37 +130,37 @@ function isIdempotentCall(args: Record<string, unknown>): boolean {
 // does not need synchronously — safe to queue durably and replay on reconnect. Reads, claims
 // (409 contention), spawn/shutdown (need a real ack) are deliberately NOT bufferable.
 const DEFAULT_BUFFERABLE_TOOLS = new Set<string>([
-  "relay_send_message",
-  "relay_reply",
-  "relay_task_deliver",
+  "humwick_send_message",
+  "humwick_reply",
+  "humwick_task_deliver",
 ]);
 
 // Tools surfaced ONLY to an agent that owns a live isolated worktree. For any other agent the
 // proxy narrows them out of `tools/list` even though the token scope permits them (the relay
-// would return them). This is the context the coarse token scope can't express (#214/#215).
+// would return them). This is the context the coarse token scope can't express.
 const WORKTREE_ONLY_TOOLS = new Set<string>([
-  "relay_workspace_status",
-  "relay_workspace_deps",
-  "relay_workspace_list",
-  "relay_workspace_claim",
-  "relay_workspace_release",
+  "humwick_workspace_status",
+  "humwick_workspace_deps",
+  "humwick_workspace_list",
+  "humwick_workspace_claim",
+  "humwick_workspace_release",
 ]);
 
 interface ProxyContext {
   // The agent owns a live (non-terminal) isolated git worktree → workspace tools apply.
   isolatedWorktree: boolean;
-  // #1502 — this worktree agent's own workspace descriptor (from AGENT_RELAY_WORKSPACE_JSON). The
+  // this worktree agent's own workspace descriptor (from HUMWICK_WORKSPACE_JSON). The
   // relay writes the workspace ROW lazily via the orchestrator's managed-agents report, so a worker
   // that delivers before that write (or whose registration was lost under concurrent-spawn load)
-  // would 404. We inject this descriptor into `relay_task_deliver` so the relay can self-heal the
+  // would 404. We inject this descriptor into `humwick_task_deliver` so the relay can self-heal the
   // missing registration from the worker's own truth instead of stranding the delivery.
   workspaceDescriptor?: Record<string, unknown>;
 }
 
-// #1502 — tool calls the proxy augments with the agent's workspace descriptor for self-heal.
-const WORKSPACE_SELF_HEAL_TOOLS = new Set(["relay_task_deliver"]);
+// tool calls the proxy augments with the agent's workspace descriptor for self-heal.
+const WORKSPACE_SELF_HEAL_TOOLS = new Set(["humwick_task_deliver"]);
 
-// #1502 — the minimal descriptor the relay needs to (re)register a dropped workspace row, distilled
+// the minimal descriptor the relay needs to (re)register a dropped workspace row, distilled
 // from the agent's WorkspaceMetadata. Undefined unless this agent owns a live isolated worktree with
 // the required id/repo/worktree present, so a shared/non-worktree agent never sends one.
 export function isolatedWorkspaceDescriptor(
@@ -200,7 +200,7 @@ export interface RelayMcpProxyOptions {
   enqueueBuffered(call: BufferedToolCall): void;
   initialContext?: ProxyContext;
   bufferableTools?: Set<string>;
-  // #1450 — the Codex-worker on-demand relay set to hide from the agent's DIRECT relay client so
+  // the Codex-worker on-demand relay set to hide from the agent's DIRECT relay client so
   // only the eager hot-path set boots. Undefined for every agent that isn't a lean Codex worker with
   // callmux simultaneously fronting these tools (Claude, coordinators, reviewers, proxy-off) → no
   // hiding, full surface. callmux's own relay downstream opts out via RELAY_MCP_ONDEMAND_SURFACE_HEADER.
@@ -209,14 +209,14 @@ export interface RelayMcpProxyOptions {
   fetchImpl?: FetchLike;
   // Test seam for inspecting the deadline selected for each relay forward.
   abortSignal?: (timeoutMs: number) => AbortSignal;
-  // #2089 — bounded connect-retry across a relay restart, GENERIC over every tool. Overridable for tests
+  // bounded connect-retry across a relay restart, GENERIC over every tool. Overridable for tests
   // (fast/deterministic backoff + attempt cap); defaults ride out a CD-deploy's brief unreachable window.
   //   attempts     — hard cap on forward attempts (safety bound; the window is the real bound in prod)
   //   backoffMs    — base (first-retry) delay; doubles each retry up to maxBackoffMs
   //   maxBackoffMs — per-delay ceiling
   //   maxWindowMs  — total retry budget (sum of backoffs) before the original error is surfaced
   connectRetry?: { attempts?: number; backoffMs?: number; maxBackoffMs?: number; maxWindowMs?: number };
-  // #1790 — deprecated alias for connectRetry (attempts/backoffMs only). `connectRetry` wins if both set.
+  // deprecated alias for connectRetry (attempts/backoffMs only). `connectRetry` wins if both set.
   spawnRetry?: { attempts?: number; backoffMs?: number };
   // Test seam so the retry backoff doesn't sleep real wall-clock time in unit tests.
   sleep?: (ms: number) => Promise<void>;
@@ -236,7 +236,7 @@ interface SseClient {
   keepalive: ReturnType<typeof setInterval>;
 }
 
-export class RelayMcpProxy {
+export class HumwickMcpProxy {
   private readonly redactToolResponse?: RelayMcpProxyOptions["redactToolResponse"];
   private readonly relayMcpEndpoint: string;
   private readonly getToken: () => string | undefined;
@@ -270,8 +270,8 @@ export class RelayMcpProxy {
     this.getToken = options.getToken;
     this.authSecret = options.authSecret;
     this.enqueueBuffered = options.enqueueBuffered;
-    this.bufferableTools = options.bufferableTools ?? DEFAULT_BUFFERABLE_TOOLS;
-    this.onDemandTools = options.onDemandTools;
+    this.bufferableTools = options.bufferableTools ? new Set(options.bufferableTools) : DEFAULT_BUFFERABLE_TOOLS;
+    this.onDemandTools = options.onDemandTools ? new Set(options.onDemandTools) : undefined;
     this.fetchImpl = options.fetchImpl ?? fetch;
     this.abortSignal = options.abortSignal ?? AbortSignal.timeout;
     const retry = options.connectRetry ?? options.spawnRetry;
@@ -323,7 +323,7 @@ export class RelayMcpProxy {
   }
 
   // The runner calls this after a token re-mint (scope may change, e.g. command:spawn) and on every
-  // bus re-register, since a deploy restarts the relay with new tools or schemas (#2973). Re-fetch
+  // bus re-register, since a deploy restarts the relay with new tools or schemas. Re-fetch
   // the tool list with the live token and emit list_changed if the visible set changed; setContext
   // covers the workspace mode/state path. Best-effort: a failed refresh keeps the last-known list.
   async refreshTools(): Promise<void> {
@@ -337,8 +337,6 @@ export class RelayMcpProxy {
   }
 
   private async handle(req: Request): Promise<Response> {
-    const conflict = relayHeaderConflict(req.headers);
-    if (conflict) return Response.json({ error: conflict }, { status: 400 });
     const url = new URL(req.url);
     if (this.options.webToolLog && url.pathname === `/web/${this.options.authSecret}`) return forwardSharedMcp(req, this.options.webToolLog);
     if (url.pathname !== PROXY_PATH) return new Response("not found", { status: 404 });
@@ -359,7 +357,7 @@ export class RelayMcpProxy {
   }
 
   private async handleRpc(req: Request): Promise<Response> {
-    // #1450 — read the on-demand-front header BEFORE consuming the body. The per-agent metaOnly
+    // read the on-demand-front header BEFORE consuming the body. The per-agent metaOnly
     // callmux's relay downstream sets it to opt OUT of the on-demand hiding (it fronts those tools);
     // the agent's direct relay client never sets it, so it gets the eager hot-path set only.
     const frontsOnDemand = relayHeader(req.headers, "ondemand-front") === RELAY_MCP_ONDEMAND_SURFACE_VALUE;
@@ -395,7 +393,7 @@ export class RelayMcpProxy {
     // usable initialize result advertising the proxy's capabilities.
     const result: Record<string, unknown> = isRecord(relay?.body?.result) ? { ...(relay!.body!.result as Record<string, unknown>) } : {
       protocolVersion: "2024-11-05",
-      serverInfo: { ...mcpServerInfo(parseToolGeneration(new URL(this.relayMcpEndpoint).searchParams.get("tools"))), version: "proxy" },
+      serverInfo: { ...MCP_SERVER_INFO, version: "proxy" },
     };
     const caps = isRecord(result.capabilities) ? { ...result.capabilities } : {};
     // The capability the relay's static endpoint doesn't advertise: live tool sets.
@@ -413,7 +411,7 @@ export class RelayMcpProxy {
     // If the relay is down and we have no cache yet, surface an empty list rather than erroring —
     // the agent can still operate (writes buffer; tools/list refreshes on the next call).
     const base = tools ?? this.lastRelayTools;
-    // #1450 — callmux's relay downstream (frontsOnDemand) sees the full set so it can route
+    // callmux's relay downstream (frontsOnDemand) sees the full set so it can route
     // callmux_call to any of it; the direct client has the on-demand set hidden.
     const narrowed = this.narrow(base, frontsOnDemand);
     this.lastFingerprints[frontsOnDemand ? "front" : "direct"] = toolsFingerprint(narrowed);
@@ -421,14 +419,14 @@ export class RelayMcpProxy {
   }
 
   // Strict subset of the relay's already-scope-filtered list. Only removes — never adds. Narrowing
-  // rules: (1) workspace tools apply only to an agent that owns a live worktree; (2) #1450 — the
+  // rules: (1) workspace tools apply only to an agent that owns a live worktree; (2) — the
   // on-demand relay set is hidden from the agent's DIRECT client (only when `hideOnDemand`), since
   // the per-agent metaOnly callmux fronts those tools on demand. `frontsOnDemand` (callmux's own
   // request) skips rule 2 so callmux sees the full relay set.
   private narrow(tools: Array<Record<string, unknown>>, frontsOnDemand = false): Array<Record<string, unknown>> {
     const hideOnDemand = !frontsOnDemand && this.onDemandTools !== undefined && this.onDemandTools.size > 0;
     return tools.filter((tool) => {
-      const name = registryToolName(typeof tool.name === "string" ? tool.name : "");
+      const name = typeof tool.name === "string" ? tool.name : "";
       if (WORKTREE_ONLY_TOOLS.has(name) && !this.context.isolatedWorktree) return false;
       if (hideOnDemand && this.onDemandTools!.has(name)) return false;
       return true;
@@ -437,10 +435,11 @@ export class RelayMcpProxy {
 
   private async handleToolsCall(id: string | number | null, message: JsonRpcMessage): Promise<Response> {
     const params = isRecord(message.params) ? message.params : {};
-    const toolName = registryToolName(typeof params.name === "string" ? params.name : "");
+    const wireName = typeof params.name === "string" ? params.name : "";
+    const toolName = wireName;
     let args = isRecord(params.arguments) ? params.arguments : {};
 
-    // #1502 — inject this agent's workspace descriptor so the relay can self-heal a missing/dropped
+    // inject this agent's workspace descriptor so the relay can self-heal a missing/dropped
     // workspace registration during delivery. Only for worktree agents, only when the agent didn't
     // already supply one, and the augmented args are forwarded (not just used locally).
     if (
@@ -453,7 +452,7 @@ export class RelayMcpProxy {
       message = { ...message, params: { ...params, arguments: args } };
     }
 
-    // #1790 — stabilize the spawn correlation id BEFORE the first attempt so a retry across a relay
+    // stabilize the spawn correlation id BEFORE the first attempt so a retry across a relay
     // restart reuses it and the server dedupes to the SAME spawn (never a second agent). The caller's
     // own id wins if supplied; otherwise mint an fs-safe `sp_<uuid>` here, because the relay would
     // otherwise mint a FRESH id on each attempt and a retry would double-create. This is id-provisioning,
@@ -466,10 +465,10 @@ export class RelayMcpProxy {
       }
     }
 
-    // #2857 — a `path` upload names a file on THIS host, but the relay reads it from
+    // a `path` upload names a file on THIS host, but the relay reads it from
     // its own filesystem, so remote agents always got "path not found". Materialize the
     // file here and forward bytes; rejections mirror the relay's own messages verbatim.
-    if (toolName === "relay_upload_artifact") {
+    if (toolName === "humwick_upload_artifact") {
       const materialized = await materializeArtifactPathUpload(args, this.getToken);
       if (materialized.error !== undefined) return Response.json(jsonRpcError(id, -32602, materialized.error));
       if (materialized.args !== undefined) {
@@ -478,14 +477,14 @@ export class RelayMcpProxy {
       }
     }
 
-    // #2089 — the call is safe to resend after an AMBIGUOUS (sent-then-response-lost) failure only if it
+    // the call is safe to resend after an AMBIGUOUS (sent-then-response-lost) failure only if it
     // carries an idempotency key the server dedupes on. Read generically off the args (spawnRequestId or
     // idempotencyKey) — never off the tool name — so every idempotent tool qualifies and no other does.
     const idempotent = isIdempotentCall(args);
 
     const relay = await this.forwardWithConnectionRetry(message, toolName, idempotent).catch((error) => {
       // A thrown fetch = transport failure (relay unreachable / DNS / connection refused / socket closed).
-      // The generic connect-retry (#2089) has already exhausted its bounded window by here.
+      // The generic connect-retry has already exhausted its bounded window by here.
       return { ok: false, status: 0, body: null, transportError: errMessage(error) } as ForwardResult;
     });
 
@@ -495,17 +494,17 @@ export class RelayMcpProxy {
       const idempotencyKey = typeof args.idempotencyKey === "string" && args.idempotencyKey
         ? args.idempotencyKey
         : `mcp-${toolName}-${crypto.randomUUID()}`;
-      this.enqueueBuffered({ tool: toolName, arguments: { ...args, idempotencyKey }, idempotencyKey });
+      this.enqueueBuffered({ tool: wireName, arguments: { ...args, idempotencyKey }, idempotencyKey });
       logger.info("mcp-proxy", `relay unreachable — buffered ${toolName} (idempotencyKey=${idempotencyKey})`);
       return Response.json(jsonRpcResult(id, toolResult({
         queued: true,
-        tool: toolName,
+        tool: wireName,
         idempotencyKey,
         note: "Relay was unreachable; your call was queued durably and will be delivered automatically when the relay comes back. It is not lost.",
       })));
     }
 
-    // #1418: propagate the relay's actual status (e.g. 413 payload-too-large, 400 validation,
+    // propagate the relay's actual status (e.g. 413 payload-too-large, 400 validation,
     // 403 auth) instead of the default 200 `Response.json` gives an untouched status option —
     // a hard rejection silently reads as a normal 200 response to anything downstream that
     // branches on HTTP status rather than parsing the JSON-RPC `error` field, masking a large
@@ -542,7 +541,7 @@ export class RelayMcpProxy {
     const payload: Record<string, unknown> = { jsonrpc: "2.0", method: message.method };
     if (message.id !== undefined) payload.id = message.id;
     if (message.params !== undefined) payload.params = message.params;
-    // #2429 — Bun 1.3.x's native HTTP idle watchdog aborts any fetch that sees no response bytes
+    // Bun 1.3.x's native HTTP idle watchdog aborts any fetch that sees no response bytes
     // for ~300s, and an AbortSignal does NOT govern it: the server awaits the WHOLE tool call
     // before its first response byte (src/mcp/index.ts `tools/call` → Response.json, no streaming),
     // so a legitimate >~300s tool call was killed client-side at ~300s despite the 610s budget.
@@ -561,7 +560,7 @@ export class RelayMcpProxy {
     return { ok: response.ok, status: response.status, body: parsed };
   }
 
-  // #2089 — GENERIC bounded connect-retry so a relay restart (CD deploy, no drain) is invisible to the
+  // GENERIC bounded connect-retry so a relay restart (CD deploy, no drain) is invisible to the
   // agent for EVERY tool, not just spawn. One chokepoint, uniform across the tool suite. The retry
   // decision is driven purely by the failure CLASS (connect / ambiguous / fatal) and the call's
   // idempotency — never by tool name:
@@ -650,7 +649,7 @@ export class RelayMcpProxy {
   }
 
   private maybeEmitListChanged(): void {
-    // Definitions, not names: a new parameter on an existing tool is a change too (#2973). A view
+    // Definitions, not names: a new parameter on an existing tool is a change too. A view
     // nobody has listed yet needs no notification; its first list is current.
     let changed = false;
     for (const view of ["direct", "front"] as const) {