agent-relay-server 0.122.0 → 0.123.0

package/runner/src/relay-mcp.ts

@@ -0,0 +1,156 @@
+// 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 = "agent-relay";
+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 const SHARED_MCP_SERVER_NAME = "callmux";
+// 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";
+
+/** Resolve the shared-listener URL: explicit runner option → env → documented default. */
+export function resolveSharedMcpUrl(explicit?: string): string {
+  return explicit ?? process.env[SHARED_MCP_URL_ENV] ?? DEFAULT_SHARED_MCP_URL;
+}
+
+export function relayMcpEndpoint(relayUrl: string): string {
+  return `${relayUrl.replace(/\/+$/, "")}${RELAY_MCP_PATH}`;
+}
+
+// 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): string[] {
+  const key = `mcp_servers.${RELAY_MCP_SERVER_NAME}`;
+  return [
+    "-c",
+    `${key}.url=${tomlString(endpoint ?? relayMcpEndpoint(relayUrl))}`,
+    "-c",
+    `${key}.bearer_token_env_var=${tomlString(RELAY_MCP_TOKEN_ENV)}`,
+  ];
+}
+
+// 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 `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+// #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 { SHARED_CALLMUX_TOOL_CALL_TIMEOUT_MS, type ProvisioningMcpServer } from "agent-relay-sdk";
+
+// 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: "callmux",
+    args: ["bridge", "--url", url, "--cwd", cwd, "--call-timeout", String(SHARED_CALLMUX_TOOL_CALL_TIMEOUT_MS)],
+  };
+}
+
+function mergedConfigEnv(server: ProvisioningMcpServer): ProvisioningMcpServer {
+  if (!server.configEnv || Object.keys(server.configEnv).length === 0) return server;
+  return {
+    ...server,
+    env: { ...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 function claudeMcpLaunchArgs(opts: {
+  relayUrl: string;
+  endpoint?: string;
+  includeRelay: boolean;
+  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>;
+  strict?: boolean;
+}): string[] {
+  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 (name === RELAY_MCP_SERVER_NAME) continue;
+    const entry = claudeMcpServerEntry(server);
+    if (Object.keys(entry).length) mcpServers[name] = entry;
+  }
+  if (opts.includeRelay) {
+    mcpServers[RELAY_MCP_SERVER_NAME] = {
+      type: "http",
+      url: opts.endpoint ?? relayMcpEndpoint(opts.relayUrl),
+      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 (name === RELAY_MCP_SERVER_NAME) continue;
+    const entry = claudeMcpServerEntry(server);
+    if (Object.keys(entry).length) mcpServers[name] = entry;
+  }
+  // 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"] : [])];
+}
+
+// #555 (Codex) — `-c mcp_servers.<name>.*` overrides for each relay-provisioned
+// server, the same shape relayMcpCodexConfigArgs uses for the relay endpoint.
+export function codexProvisionedMcpArgs(servers?: Record<string, ProvisioningMcpServer>): string[] {
+  const args: string[] = [];
+  for (const [name, rawServer] of Object.entries(servers ?? {})) {
+    if (name === RELAY_MCP_SERVER_NAME) continue;
+    const server = 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)}`);
+    for (const [envKey, envVal] of Object.entries(server.env ?? {})) {
+      args.push("-c", `${key}.env.${envKey}=${tomlString(envVal)}`);
+    }
+  }
+  return args;
+}

package/runner/src/reply-obligation-cache.ts

@@ -0,0 +1,136 @@
+import type { ReplyObligation } from "agent-relay-sdk";
+import { errMessage } from "agent-relay-sdk";
+import { logger } from "./logger";
+
+// Phase 2 (#196) — the crux. The Claude Stop hook used to ask the server, synchronously
+// and in the hot path, "does this agent owe a reply?" before clearing the turn. A slow
+// server answer (the unindexed reply_to scan, #199) blew the hook's timeout and wedged the
+// agent in `busy` forever. The fix: the hook asks the Runner, the Runner answers instantly
+// from this local snapshot, and the snapshot is refreshed from the server only in the
+// background — never on the path that ends a turn.
+//
+// Design rules:
+// - `get()` is synchronous, never throws, never touches the network.
+// - `refresh()` is the only thing that talks to the server; it coalesces concurrent calls
+//   and, on failure, keeps the last-known snapshot (stale-but-serving beats blocking).
+// - A background interval keeps the snapshot warm; `markDirty()` requests an extra,
+//   debounced refresh when state likely just changed (a message arrived, a turn ended).
+
+// #418 — the human `user` sink is NOT delivered via an explicit relay reply: the agent's
+// turn is mirrored to the dashboard chat by the session-mirror lane (always, for managed
+// agents). So an explicit `/reply` to `user` double-delivers — the operator sees the mirrored
+// turn AND the explicit copy. Only agent↔agent / spawner obligations (#413) need an explicit
+// reply to clear and reach their recipient. This is the single home for that distinction —
+// both the Claude Stop-hook nag (control-server) and the non-claude re-injection (runner)
+// gate on it, so the rule must not drift between them.
+export function obligationRequiresExplicitReply(obligation: ReplyObligation): boolean {
+  if (obligation.source === "spawn-obligation") return false;
+  return obligation.from !== "user";
+}
+
+export function responseCaptureReplyRoute(
+  obligations: ReplyObligation[],
+  currentTurnStartedAt?: number,
+  opts: { suppressUser?: boolean } = {},
+): { replyToMessageId?: number; to: string } | null {
+  const eligible = [...obligations].reverse()
+    .filter((o) => currentTurnStartedAt === undefined || o.createdAt <= currentTurnStartedAt);
+  const explicit = eligible.find(obligationRequiresExplicitReply);
+  if (explicit) return { replyToMessageId: explicit.messageId, to: explicit.from };
+  const user = eligible.find((o) => o.from === "user");
+  if (!user) return { to: "user" };
+  return opts.suppressUser ? null : { replyToMessageId: user.messageId, to: "user" };
+}
+
+type ReplyObligationFetch = () => Promise<ReplyObligation[]>;
+
+interface ReplyObligationCacheOptions {
+  fetch: ReplyObligationFetch;
+  // Background freshness backstop. Default 10s — well under any turn cadence, cheap.
+  intervalMs?: number;
+  // Debounce window for markDirty()-triggered refreshes so a burst of events
+  // (e.g. a fan-out of messages) collapses into one server round-trip.
+  dirtyDebounceMs?: number;
+}
+
+const DEFAULT_INTERVAL_MS = 10_000;
+const DEFAULT_DIRTY_DEBOUNCE_MS = 400;
+
+export class ReplyObligationCache {
+  private readonly fetch: ReplyObligationFetch;
+  private readonly intervalMs: number;
+  private readonly dirtyDebounceMs: number;
+
+  private snapshot: ReplyObligation[] = [];
+  private lastRefreshedAt = 0;
+  private inFlight: Promise<void> | null = null;
+  private intervalTimer?: ReturnType<typeof setInterval>;
+  private dirtyTimer?: ReturnType<typeof setTimeout>;
+  private stopped = false;
+
+  constructor(options: ReplyObligationCacheOptions) {
+    this.fetch = options.fetch;
+    this.intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
+    this.dirtyDebounceMs = options.dirtyDebounceMs ?? DEFAULT_DIRTY_DEBOUNCE_MS;
+  }
+
+  // Synchronous, hot-path-safe read. Returns a copy so callers can't mutate the snapshot.
+  get(): ReplyObligation[] {
+    return this.snapshot.slice();
+  }
+
+  getLastRefreshedAt(): number {
+    return this.lastRefreshedAt;
+  }
+
+  // Begin the background freshness loop and prime the first snapshot immediately.
+  start(): void {
+    if (this.intervalTimer || this.stopped) return;
+    void this.refresh();
+    this.intervalTimer = setInterval(() => { void this.refresh(); }, this.intervalMs);
+    // Don't keep the process alive solely for cache refreshes.
+    this.intervalTimer.unref?.();
+  }
+
+  stop(): void {
+    this.stopped = true;
+    if (this.intervalTimer) clearInterval(this.intervalTimer);
+    this.intervalTimer = undefined;
+    if (this.dirtyTimer) clearTimeout(this.dirtyTimer);
+    this.dirtyTimer = undefined;
+  }
+
+  // Request a refresh because state likely changed (message arrived / turn ended).
+  // Debounced so a burst collapses into a single server round-trip.
+  markDirty(): void {
+    if (this.stopped || this.dirtyTimer) return;
+    this.dirtyTimer = setTimeout(() => {
+      this.dirtyTimer = undefined;
+      void this.refresh();
+    }, this.dirtyDebounceMs);
+    this.dirtyTimer.unref?.();
+  }
+
+  // Fetch from the server and replace the snapshot. Coalesces concurrent callers onto a
+  // single in-flight request. Never rejects — a failed fetch leaves the prior snapshot in
+  // place (the hook keeps getting an answer even while the server is down).
+  refresh(): Promise<void> {
+    if (this.stopped) return Promise.resolve();
+    if (this.inFlight) return this.inFlight;
+    this.inFlight = this.doRefresh().finally(() => { this.inFlight = null; });
+    return this.inFlight;
+  }
+
+  private async doRefresh(): Promise<void> {
+    try {
+      const obligations = await this.fetch();
+      if (this.stopped) return;
+      this.snapshot = Array.isArray(obligations) ? obligations : [];
+      this.lastRefreshedAt = Date.now();
+    } catch (error) {
+      // Server-down is a non-event: keep serving the last snapshot. Debug, not error —
+      // this is expected during outages and must not spam the log.
+      logger.debug("obligation-cache", `refresh failed, serving cached snapshot (${this.snapshot.length}): ${errMessage(error)}`);
+    }
+  }
+}

package/runner/src/response-capture-report.ts

@@ -0,0 +1,63 @@
+import type { MessageSessionMeta, SendMessageInput } from "agent-relay-sdk";
+
+interface ReportOutbox {
+  enqueue(record: { kind: string; idempotencyKey?: string; payload: SendMessageInput }): void;
+}
+
+type SessionPublisher = (input: {
+  from: string;
+  to: string;
+  body: string;
+  session: MessageSessionMeta;
+  replyTo?: number;
+}) => void | Promise<void>;
+
+function finalSession(session: MessageSessionMeta): MessageSessionMeta {
+  return { ...session, final: true };
+}
+
+export async function publishCapturedResponse(input: {
+  publishSessionEvent: SessionPublisher;
+  outbox: ReportOutbox;
+  provider: string;
+  from: string;
+  to: string;
+  body: string;
+  session: MessageSessionMeta;
+  replyTo?: number;
+}): Promise<void> {
+  await input.publishSessionEvent({
+    from: input.from,
+    to: input.to,
+    body: input.body,
+    ...(input.replyTo ? { replyTo: input.replyTo } : {}),
+    session: finalSession(input.session),
+  });
+  enqueueCapturedResponseReport(input);
+}
+
+export function enqueueCapturedResponseReport(input: {
+  outbox: ReportOutbox;
+  provider: string;
+  from: string;
+  to: string;
+  body: string;
+  session: MessageSessionMeta;
+  replyTo?: number;
+}): void {
+  if (!input.replyTo || input.to === "user") return;
+  const turnId = input.session.turnId ?? "";
+  input.outbox.enqueue({
+    kind: "session-message",
+    idempotencyKey: `response-report:${input.from}:${input.replyTo}:${turnId}`,
+    payload: {
+      from: input.from,
+      to: input.to,
+      replyTo: input.replyTo,
+      kind: "chat",
+      body: input.body,
+      replyExpected: false,
+      payload: { responseCapture: { provider: input.provider, ...finalSession(input.session) } },
+    },
+  });
+}