agent-relay-server 0.90.0 → 0.91.0

package/docs/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Relay API",
-    "version": "0.90.0",
+    "version": "0.91.0",
     "description": "Real-time message bus for inter-agent communication. Agent-first: this spec is designed for machine consumption — agents can self-discover the full API surface via GET /api/spec.",
     "license": {
       "name": "MIT",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-server",
-  "version": "0.90.0",
+  "version": "0.91.0",
   "description": "Lightweight HTTP message relay for inter-agent communication across machines",
   "module": "src/index.ts",
   "type": "module",
@@ -33,7 +33,7 @@
     "CONTRIBUTING.md"
   ],
   "dependencies": {
-    "agent-relay-sdk": "0.2.69",
+    "agent-relay-sdk": "0.2.70",
     "ajv": "^8.20.0"
   },
   "scripts": {

package/runner/src/adapter.ts

@@ -100,6 +100,10 @@ export interface RunnerSpawnConfig {
   // Stage 2 (#215): the MCP endpoint the agent connects to — the runner-local proxy URL when the
   // proxy is active. Undefined → the adapter targets the relay's MCP endpoint directly (Stage 1).
   relayMcpEndpoint?: string;
+  // #672: the shared host-listener URL the per-agent `callmux bridge` connects to, when the
+  // profile/spawn opted into `agentProfile.sharedMcp`. Resolved runner-side (env → default);
+  // the launch assembler only emits the bridge entry when sharedMcp is on.
+  sharedMcpUrl?: string;
   monitor?: {
     deliver(messages: Message[]): Promise<number[]>;
   };

package/src/config-store.ts

@@ -6,6 +6,7 @@ import { DEFAULT_SELF_RESUME_CONFIG, validateSelfResumeConfig } from "./self-res
 import { TEAM_TEMPLATE_NAMESPACE, validateTeamTemplate } from "./team-template-config";
 import { PROJECT_INSTRUCTION_POLICY_NAMES } from "./project-instructions";
 import { PROJECT_MCP_POLICY_NAMES } from "./project-mcp";
+import { SHARED_MCP_POLICY_NAMES } from "./shared-mcp";
 import { resolveProviderSelection, type ProviderEffort } from "agent-relay-sdk/provider-catalog";
 import { errMessage, isRecord, SPAWN_PROVIDERS, VALID_WORKSPACE_MODES } from "agent-relay-sdk"; import { effectiveProviderCatalogList } from "./provider-catalog-store";
 import type {
@@ -237,6 +238,17 @@ function cleanAgentProfileProjectMcp(value: unknown): AgentProfile["projectMcp"]
   return { policy: cleanEnum(policy, "projectMcp.policy", PROJECT_MCP_POLICY_NAMES) as NonNullable<AgentProfile["projectMcp"]>["policy"] };
 }
 
+// #672 — shared host-listener MCP projection profile default. Mirrors projectMcp:
+// boolean | { policy } → normalized { policy? } | undefined (OFF).
+function cleanAgentProfileSharedMcp(value: unknown): AgentProfile["sharedMcp"] {
+  if (value === undefined || value === null || value === false) return undefined;
+  if (value === true) return {};
+  if (!isRecord(value)) throw new ValidationError("sharedMcp must be a boolean or { policy } object");
+  const policy = value.policy;
+  if (policy === undefined || policy === null) return {};
+  return { policy: cleanEnum(policy, "sharedMcp.policy", SHARED_MCP_POLICY_NAMES) as NonNullable<AgentProfile["sharedMcp"]>["policy"] };
+}
+
 function agentProfileDefaults(input: Pick<AgentProfile, "name" | "base"> & Partial<AgentProfile>): AgentProfile {
   const isolated = input.base !== "host";
   // "vanilla" (#552) additionally suppresses the REPO instruction cascade
@@ -258,6 +270,7 @@ function agentProfileDefaults(input: Pick<AgentProfile, "name" | "base"> & Parti
     },
     ...(input.projectInstructions ? { projectInstructions: input.projectInstructions } : {}),
     ...(input.projectMcp ? { projectMcp: input.projectMcp } : {}),
+    ...(input.sharedMcp ? { sharedMcp: input.sharedMcp } : {}),
     relay: {
       context: input.relay?.context ?? !isolated,
       skills: input.relay?.skills ?? !isolated,
@@ -333,6 +346,7 @@ function validateAgentProfile(key: string, value: unknown): AgentProfile {
     },
     projectInstructions: cleanAgentProfileProjectInstructions(value.projectInstructions),
     projectMcp: cleanAgentProfileProjectMcp(value.projectMcp),
+    sharedMcp: cleanAgentProfileSharedMcp(value.sharedMcp),
     relay: {
       context: relay.context === undefined ? defaults.relay.context : cleanBoolean(relay.context, "relay.context"),
       skills: relay.skills === undefined ? defaults.relay.skills : cleanBoolean(relay.skills, "relay.skills"),

package/src/mcp/tools-spawn.ts

@@ -5,6 +5,7 @@ import { buildSpawnTargets } from "../spawn-targets";
 import { McpAuthError, McpNotFoundError } from "../mcp-errors";
 import { parseProjectInstructions, PROJECT_INSTRUCTION_POLICY_NAMES } from "../project-instructions";
 import { parseProjectMcp, PROJECT_MCP_POLICY_NAMES } from "../project-mcp";
+import { parseSharedMcp, SHARED_MCP_POLICY_NAMES } from "../shared-mcp";
 import { countLiveSpawnedAgents, listAgents, listWorkspaces, ValidationError } from "../db";
 import { listCommands } from "../commands-db";
 import { DEFAULT_SPAWN_PROFILE_NAME } from "../config-store";
@@ -36,6 +37,7 @@ export const SPAWN_TOOLS: ToolDefinition[] = [
         systemPromptAppend: { type: "string" },
         projectInstructions: { type: "object", description: "#409 — project instruction projection (default OFF). When set, relay composes a knowledge preamble from the spawn cwd's resolved project (own + inherited entries) and prepends it to systemPromptAppend, instead of relying on host CLAUDE.md. `policy: \"all\"` includes ingested host content; `\"vanilla\"` excludes it (manual+promoted only). Omit to keep current behavior.", properties: { policy: { type: "string", enum: PROJECT_INSTRUCTION_POLICY_NAMES } }, additionalProperties: false },
         projectMcp: { type: "object", description: "#667 — project `.mcp.json` MCP projection (default OFF). When set, the worker gets the MCP servers committed in the spawn cwd's `.mcp.json` (e.g. an app's playtest/manuscript servers), injected by relay through the controlled `--mcp-config` path that survives `--strict-mcp-config` — sourced from the project, not ambient host MCP, and without triggering Claude's project-trust modal. `policy: \"all\"` (the default) injects every declared server. Omit to keep current host-only behavior.", properties: { policy: { type: "string", enum: PROJECT_MCP_POLICY_NAMES } }, additionalProperties: false },
+        sharedMcp: { type: "object", description: "#672 — shared host-listener MCP (default OFF). When set, the worker's NON-IDENTITY MCP (tokenlean, github) is routed through one orchestrator-owned shared `callmux` listener via a per-agent `callmux bridge --cwd \"$WORKTREE\"`, so the MCP session survives a listener/downstream restart and each isolated worktree keeps session-cwd isolation. Rides the controlled `--mcp-config` path (composes with `--strict-mcp-config`). The identity-bearing relay endpoint stays per-agent (#215), never on the shared listener. `policy: \"all\"` (the default) routes the listener's full non-identity set. Omit to keep current per-agent injection.", properties: { policy: { type: "string", enum: SHARED_MCP_POLICY_NAMES } }, additionalProperties: false },
         profile: { type: "string", description: `Agent profile name to apply (env, instructions, permissions, MCP/skills, spawn quota). Omit to use \`${DEFAULT_SPAWN_PROFILE_NAME}\`.` },
         tags: { type: "array", items: { type: "string" } },
         capabilities: { type: "array", items: { type: "string" } },
@@ -111,6 +113,7 @@ export async function relaySpawnAgent(auth: McpAuthContext, args: Record<string,
     systemPromptAppend: optionalString(args.systemPromptAppend, "systemPromptAppend", 64_000),
     projectInstructions: parseProjectInstructions(args.projectInstructions, (m) => new ValidationError(m)),
     projectMcp: parseProjectMcp(args.projectMcp, (m) => new ValidationError(m)),
+    sharedMcp: parseSharedMcp(args.sharedMcp, (m) => new ValidationError(m)),
     tags: optionalStringArray(args.tags, "tags"),
     capabilities: optionalStringArray(args.capabilities, "capabilities"),
     providerArgs: optionalStringArray(args.providerArgs, "providerArgs"),

package/src/routes/agents-spawn.ts

@@ -8,6 +8,7 @@ import { registerAgent } from "../services/register-agent";
 import { spawnAgent, type SpawnAgentInput } from "../services/spawn-agent";
 import { parseProjectInstructions } from "../project-instructions";
 import { parseProjectMcp } from "../project-mcp";
+import { parseSharedMcp } from "../shared-mcp";
 import { authContextFromRequest } from "../services/auth-context";
 import { listHostDirectories } from "../agent-spawn";
 import { rankRouteCandidates, type RouteAdvisorInput } from "../context-router";
@@ -123,6 +124,7 @@ export const postAgentSpawn: Handler = async (req) => {
       systemPromptAppend: cleanString(parsed.body.systemPromptAppend, "systemPromptAppend", { max: 64_000 }),
       projectInstructions: parseProjectInstructions(parsed.body.projectInstructions, (m) => new ValidationError(m)),
       projectMcp: parseProjectMcp(parsed.body.projectMcp, (m) => new ValidationError(m)),
+      sharedMcp: parseSharedMcp(parsed.body.sharedMcp, (m) => new ValidationError(m)),
       tags: cleanStringArray(parsed.body.tags, "tags", { itemMax: 80, maxItems: 50 }),
       capabilities: cleanStringArray(parsed.body.capabilities, "capabilities", { itemMax: 80, maxItems: 50 }),
       providerArgs: cleanStringArray(parsed.body.providerArgs, "providerArgs", { itemMax: 80, maxItems: 50 }),

package/src/services/spawn-agent.ts

@@ -34,6 +34,7 @@ import { selectSpawnOrchestrator } from "../spawn-targets";
 import { DEFAULT_SPAWN_PROFILE_NAME, getAgentProfile } from "../config-store";
 import { composeSpawnInstructionsWithEvents, type ProjectInstructionPolicy } from "../project-instructions";
 import type { ProjectMcpPolicy } from "../project-mcp";
+import type { SharedMcpPolicy } from "../shared-mcp";
 import { autoSeedProjectForCwd } from "./project";
 import { hasComponentScope, isComponentAuthorizedFor } from "../security";
 import { isPathWithinBase } from "../utils";
@@ -84,6 +85,16 @@ export interface SpawnAgentInput {
    * to projectInstructions; carried to the runner on the in-flight `agentProfile.projectMcp`.
    */
   projectMcp?: ProjectMcpPolicy;
+  /**
+   * #672 — shared host-listener MCP. When set, the runner emits a per-agent `callmux bridge`
+   * stdio entry so the agent's NON-IDENTITY MCP (tokenlean, github) flows through the
+   * orchestrator-owned shared listener instead of per-agent server processes — the session
+   * survives a listener/downstream restart, with `--cwd "$WORKTREE"` session-cwd isolation.
+   * Additive-from-empty + opt-in: absent (undefined) = OFF → the launch is byte-identical to
+   * today. Sibling to projectMcp; carried to the runner on the in-flight `agentProfile.sharedMcp`.
+   * The identity-bearing relay endpoint stays per-agent (#215), never on the shared listener.
+   */
+  sharedMcp?: SharedMcpPolicy;
   /**
    * Legacy report-back contract flag. Spawned children now report up by lineage: their
    * turn-final response is delivered to the spawner automatically, without a reply obligation.
@@ -188,6 +199,13 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
   // turn a profile default OFF — opt-in is the trust gate, not opt-out.
   if (input.projectMcp !== undefined) agentProfile.projectMcp = input.projectMcp;
 
+  // #672 — shared host-listener MCP: a per-spawn `sharedMcp` overrides the profile default,
+  // same opt-in trust gate as projectMcp (an explicit `false` parses to undefined and so
+  // cannot turn a profile default OFF). The runner emits the bridge entry from
+  // `agentProfile.sharedMcp` (it owns the spawn cwd → `--cwd "$WORKTREE"`); thread the resolved
+  // decision onto the in-flight profile copy (a fresh object, never the cached config).
+  if (input.sharedMcp !== undefined) agentProfile.sharedMcp = input.sharedMcp;
+
   // --- THE GATE (uniform across transports) ---------------------------------
   // Coarse capability: spawning requires command:spawn. The MCP dispatcher already enforced
   // this; the HTTP route did not — asserting here makes it transport-invariant.

package/src/shared-mcp.ts

@@ -0,0 +1,57 @@
+// Shared host-listener MCP (#672, Phase 1 of epic #670) — the relay-owned, OPT-IN path that
+// routes a spawned worker's NON-IDENTITY MCP (tokenlean, github) through ONE orchestrator-owned
+// shared `callmux` listener per host, attached via a per-agent `callmux bridge` with
+// `--cwd "$WORKTREE"` for session-cwd isolation. Sibling seam to project-mcp (#667): same
+// opt-in + parse shape, default OFF.
+//
+// WHY: a shared listener turns "an MCP/listener restart kills the agent" into "the agent never
+// notices" (the bridge reconnects + retries once on the next tool call — the #659 work-loss
+// class), and collapses N per-agent server processes into one shared set (~100MB saved per
+// extra listener). The spike (#671) proved both: session survives a listener restart, and
+// session-cwd routing gives each isolated worktree its own cwd from the single shared listener.
+//
+// INVARIANT (epic #670): callmux owns transport; relay owns authz. The shared listener carries
+// ONLY non-identity servers — the identity-bearing relay endpoint stays per-agent on #215 and
+// is NEVER routed through the shared listener (the spike proved a shared listener can't carry
+// per-agent relay tokens; that's Phase 2, gated on callmux#36).
+//
+// DIVISION OF LABOR: relay carries the OPT-IN DECISION (this module + the spawn
+// param/profile field). The orchestrator owns the shared listener lifecycle/config (#673),
+// and runner owns bridge-arg emission (launch-assembly.ts → sharedMcpBridgeServer), the
+// filesystem/launch authority.
+
+export const SHARED_MCP_POLICY_NAMES = ["all"] as const;
+export type SharedMcpPolicyName = (typeof SHARED_MCP_POLICY_NAMES)[number];
+
+/** Per-spawn shared-listener request. Presence (a non-undefined value) means "route
+ * non-identity MCP through the shared listener"; absence means OFF. `policy` selects the
+ * server set (`all` = the listener's full non-identity set; the sole value today). */
+export interface SharedMcpPolicy {
+  policy?: SharedMcpPolicyName;
+}
+
+/**
+ * Parse a spawn-transport's `sharedMcp` wire value into the normalized policy (or
+ * undefined = OFF). Shared by the MCP and HTTP spawn paths so they cannot drift. Mirrors
+ * parseProjectMcp exactly:
+ *   - undefined / null / false → undefined (OFF)
+ *   - true                     → {} (ON, default policy)
+ *   - { policy }               → validated policy
+ * Throws `onInvalid(message)` for a malformed shape or unknown policy name.
+ */
+export function parseSharedMcp(
+  value: unknown,
+  onInvalid: (message: string) => Error,
+): SharedMcpPolicy | undefined {
+  if (value === undefined || value === null || value === false) return undefined;
+  if (value === true) return {};
+  if (typeof value !== "object") {
+    throw onInvalid("sharedMcp must be a boolean or { policy } object");
+  }
+  const policy = (value as Record<string, unknown>).policy;
+  if (policy === undefined || policy === null) return {};
+  if (typeof policy !== "string" || !SHARED_MCP_POLICY_NAMES.includes(policy as SharedMcpPolicyName)) {
+    throw onInvalid(`sharedMcp.policy must be one of: ${SHARED_MCP_POLICY_NAMES.join(", ")}`);
+  }
+  return { policy: policy as SharedMcpPolicyName };
+}