agent-relay-server 0.62.3 → 0.63.1

package/src/mcp.ts

@@ -1,1319 +1 @@
-import { Buffer } from "node:buffer";
-import { getArtifactStorage, maxArtifactBytes, normalizeDigest } from "./artifact-storage";
-import { spawnAgent, type SpawnAgentInput } from "./services/spawn-agent";
-import { authContextFromMcp } from "./services/auth-context";
-import { isPathWithinBase } from "./utils";
-import { optionalEnum } from "./validation";
-import { bytesToStream, readBodyBytes } from "./http-body";
-import { MAX_BODY_BYTES, VERSION } from "./config";
-import { getManagedAgentState, getSpawnPolicy, listSpawnPolicies } from "./config-store";
-import { buildSpawnTargets, selectSpawnOrchestrator, spawnCapablePrimer } from "./spawn-targets";
-import { McpAuthError, McpNotFoundError } from "./mcp-errors";
-import {
-  createArtifact,
-  createActivityEvent,
-  getAgent,
-  getArtifact,
-  getMessage,
-  getOrchestrator,
-  getRepoSteward,
-  getTask,
-  getThread,
-  getWorkspace,
-  linkArtifact,
-  listAgents,
-  listWorkspaces,
-  ownedIsolatedWorkspace,
-  searchContinuationArchives,
-  searchAgents,
-  type AgentSearchFilter,
-  type AgentSearchSort,
-  listArtifactsForEntity,
-  listOrchestrators,
-  upsertArtifactBlob,
-  ValidationError,
-} from "./db";
-import { resolveCallerAgentId, type DeliveryReceipt } from "./agent-ref";
-import { ShutdownAuthError, ShutdownTargetError, shutdownAgent } from "./services/shutdown-agent";
-import { emitRelayEvent } from "./events";
-import { compactAndResume } from "./self-resume";
-import {
-  getComponentAuth,
-  getIntegrationAuth,
-  hasComponentScope,
-  hasIntegrationScope,
-  isComponentAuthorizedFor,
-} from "./security";
-import { sendMessageService } from "./services/send-message";
-import { ServiceAuthError } from "./services/errors";
-import { PLAN_TOOLS, relayPlanTool } from "./mcp-plan-tools";
-import { TEAM_TOOLS, relayTeamTool } from "./mcp-team-tools";
-import { BLACKBOARD_TOOLS, relayBlackboardTool } from "./mcp-blackboard-tools";
-import { PROJECT_TOOLS, relayProjectTool } from "./mcp-project-tools"; import { ISSUE_REF_TOOLS, relayIssueRefTool } from "./mcp-issue-ref-tools"; import { ISSUE_ASSOCIATION_TOOLS, relayIssueAssociationTool } from "./mcp-issue-association-tools"; import { ISSUE_ACTIVITY_TOOLS, relayIssueActivityTool } from "./mcp-issue-activity-tools"; import { ISSUE_LIFECYCLE_TOOLS, relayIssueLifecycleTool } from "./mcp-issue-lifecycle-tools";
-import { NOTIFICATION_SUBSCRIPTION_TOOLS, relayNotificationSubscriptionTool } from "./mcp-notification-subscription-tools"; import { MERGE_TOOLS, relayMergeTool } from "./mcp-merge-tools";
-import { PROJECT_INSTRUCTION_POLICY_NAMES, parseProjectInstructions } from "./project-instructions";
-import { AGENT_ACTION_TOOL, relayAgentAction } from "./mcp-agent-action"; import { providerCatalogToolInputSchema } from "./mcp-provider-catalog";
-import type { ActivityKind, AgentLifecycle, ArtifactKind, ArtifactSensitivity, AttachmentRef, Command, SendMessageInput, Message, SpawnApprovalMode, SpawnProvider, WorkspaceAutoMergePolicy, WorkspaceMergeStrategy, WorkspaceMode, WorkspaceRecord } from "./types";
-import { LAND_STRATEGIES, applyWorkspaceAction, waitForWorkspaceStatus, type WorkspaceAction } from "./workspace-actions";
-import { AUTO_MERGE_POLICIES } from "./workspace-merge";
-import { describeWorkspacePhase, landReceipt, readyContract, worktreeMcpInstructions } from "./workspace-phase";
-import { type ProviderEffort } from "agent-relay-sdk/provider-catalog";
-import { errMessage, isRecord, stringValue, SPAWN_PROVIDERS, APPROVAL_MODES, VALID_AGENT_LIFECYCLES, VALID_EFFORTS, VALID_WORKSPACE_MODES } from "agent-relay-sdk";
-
-type JsonRpcId = string | number | null;
-
-type JsonRpcRequest = { jsonrpc?: "2.0"; id?: JsonRpcId; method?: string; params?: unknown };
-
-type McpAuthContext = {
-  actor: string;
-  kind: "component" | "integration" | "server";
-  scopes: string[];
-  component?: NonNullable<ReturnType<typeof getComponentAuth>>;
-  integration?: NonNullable<ReturnType<typeof getIntegrationAuth>>;
-};
-
-type ToolDefinition = {
-  name: string;
-  description: string;
-  requiredScopes: string[];
-  inputSchema: Record<string, unknown>;
-  // Emit `_meta: { "anthropic/alwaysLoad": true }` in tools/list so Claude Code
-  // (v2.1.121+) loads this tool's schema EAGERLY instead of deferring it behind a
-  // ToolSearch round-trip. Reserve for the few verbs most agents use every session
-  // (the doc warns each one costs context every turn). Verified convention; same
-  // mechanism callmux's per-tool alwaysLoad uses.
-  alwaysLoad?: boolean;
-};
-
-const MCP_PROTOCOL_VERSION = "2024-11-05";
-const MCP_BODY_OVERHEAD_BYTES = 16 * 1024;
-const VALID_ARTIFACT_KINDS = ["image", "audio", "video", "document", "archive", "other"] as const;
-const VALID_ARTIFACT_SENSITIVITIES = ["public", "normal", "sensitive", "secret"] as const;
-const VALID_ARTIFACT_ROLES = ["media", "patch", "report", "log", "output", "input"] as const;
-const VALID_ARTIFACT_ENTITY_TYPES = ["message", "task", "recipeRun", "recipeStep", "channelEvent"] as const;
-const TOOLS: ToolDefinition[] = [
-  {
-    name: "relay_send_message",
-    description: "Send an Agent Relay message. Returns a delivery receipt (delivered/expectReply/recipients): if expectReply is false, no live recipient exists — don't wait for a reply. An ambiguous target is rejected up front. An unknown target is stored for delivery once that id registers (the receipt reports delivered:false with empty recipients and a reason) — never silently dropped.",
-    requiredScopes: ["messages:write", "message:send"],
-    inputSchema: {
-      type: "object",
-      properties: {
-        from: { type: "string", description: "Deprecated/optional. Your identity is taken from your auth token; ignored for managed agents. You never need to set this." },
-        to: { type: "string", description: "Target: an agent id, label, name, or a unique id segment (e.g. the number part) — resolved automatically. Or a fan-out selector: tag:, cap:, label:, team:, policy:, or broadcast." },
-        body: { type: "string" },
-        subject: { type: "string" },
-        channel: { type: "string" },
-        claimable: { type: "boolean" },
-        idempotencyKey: { type: "string" },
-        attachments: { type: "array", items: { type: "object" } },
-        payload: { type: "object" },
-        meta: { type: "object" },
-      },
-      required: ["to", "body"],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: "relay_reply",
-    description: "Reply to an Agent Relay message by id, preserving reply/thread/channel context. Returns a delivery receipt; expectReply:false means the original sender is no longer reachable.",
-    requiredScopes: ["messages:write", "message:send"],
-    inputSchema: {
-      type: "object",
-      properties: {
-        from: { type: "string", description: "Deprecated/optional. Your identity is taken from your auth token; ignored for managed agents. You never need to set this." },
-        messageId: { type: "integer", minimum: 1 },
-        body: { type: "string" },
-        subject: { type: "string" },
-        format: { type: "string", enum: ["text", "markdown", "markdownv2"] },
-        attachments: { type: "array", items: { type: "object" } },
-        payload: { type: "object" },
-        meta: { type: "object" },
-      },
-      required: ["messageId", "body"],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: "relay_get_message",
-    description: "Fetch a full Agent Relay message body with optional attachments and thread context.",
-    requiredScopes: ["messages:read", "message:read"],
-    inputSchema: {
-      type: "object",
-      properties: {
-        messageId: { type: "integer", minimum: 1 },
-        includeArtifacts: { type: "boolean", default: true },
-        includeThread: { type: "boolean", default: true },
-      },
-      required: ["messageId"],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: "relay_get_thread",
-    description: "Fetch the full Agent Relay thread containing a message.",
-    requiredScopes: ["messages:read", "message:read"],
-    inputSchema: {
-      type: "object",
-      properties: {
-        messageId: { type: "integer", minimum: 1 },
-      },
-      required: ["messageId"],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: "relay_upload_artifact",
-    description: "Upload long text or base64 content as an Agent Relay artifact.",
-    requiredScopes: ["artifact:write"],
-    inputSchema: {
-      type: "object",
-      properties: {
-        content: { type: "string", description: "UTF-8 text content to store." },
-        base64: { type: "string", description: "Base64-encoded binary content to store." },
-        filename: { type: "string" },
-        mediaType: { type: "string" },
-        kind: { type: "string", enum: VALID_ARTIFACT_KINDS },
-        sensitivity: { type: "string", enum: VALID_ARTIFACT_SENSITIVITIES },
-        role: { type: "string", enum: VALID_ARTIFACT_ROLES },
-        title: { type: "string" },
-        metadata: { type: "object" },
-        expiresAt: { type: "integer", minimum: 1 },
-        digest: { type: "string", description: "Optional sha256 digest for integrity verification." },
-      },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: "relay_attach_artifact",
-    description: "Attach an existing Relay artifact to a message, task, recipe run, recipe step, or channel event.",
-    requiredScopes: ["artifact:write"],
-    inputSchema: {
-      type: "object",
-      properties: {
-        artifactId: { type: "string" },
-        entityType: { type: "string", enum: VALID_ARTIFACT_ENTITY_TYPES },
-        entityId: { oneOf: [{ type: "string" }, { type: "integer", minimum: 1 }] },
-        role: { type: "string", enum: VALID_ARTIFACT_ROLES },
-        title: { type: "string" },
-      },
-      required: ["artifactId", "entityType", "entityId"],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: "relay_agent_status",
-    description: "Inspect Relay agent, orchestrator, and managed spawn-policy status. The default agent list shows only RUNNING agents (the ones you can actually message/reply/pair with); pass includeOffline:true for the full roster.",
-    requiredScopes: ["agents:read", "agent:read"],
-    inputSchema: {
-      type: "object",
-      properties: {
-        agentId: { type: "string" },
-        policyName: { type: "string" },
-        orchestratorId: { type: "string" },
-        includeOffline: { type: "boolean", description: "Include offline/stale agents in the default list (default false)." },
-      },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: "relay_find_agents",
-    description: "Search the fleet for agents by label, capability, provider, tag, machine, status, or kind, sorted by last-active/created/label. Defaults to running agents only. Use this to find a reachable, capable peer before messaging or pairing — instead of dumping the whole roster.",
-    requiredScopes: ["agents:read", "agent:read"],
-    inputSchema: {
-      type: "object",
-      properties: {
-        label: { type: "string", description: "Substring match on label or name." },
-        capability: { type: ["string", "array"], items: { type: "string" }, description: "One or more capabilities (OR within)." },
-        provider: { type: ["string", "array"], items: { type: "string" }, description: "Model provider, e.g. claude or codex." },
-        tag: { type: ["string", "array"], items: { type: "string" } },
-        machine: { type: ["string", "array"], items: { type: "string" } },
-        kind: { type: ["string", "array"], items: { type: "string" } },
-        status: { type: ["string", "array"], items: { type: "string" }, description: "online/idle/busy/offline/stale, the 'running' shorthand, or 'all'. Default 'running'." },
-        spawnedBy: { type: "string", description: "Parent agent id, or 'me' for your own spawned children (#221)." },
-        teamId: { type: "string", description: "Durable team id for roster filtering." },
-        sortBy: { type: "string", enum: ["lastActive", "created", "label"] },
-        order: { type: "string", enum: ["asc", "desc"] },
-        limit: { type: "integer", minimum: 1, maximum: 200 },
-      },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: "relay_whoami",
-    description: "Return your own Relay identity and agent card (id, label, status, tags, capabilities). Your identity comes from your auth token — you do NOT need this to send, reply, or pair; use it only when you need to reason about yourself.",
-    requiredScopes: ["mcp:use"],
-    inputSchema: {
-      type: "object",
-      properties: {},
-      additionalProperties: false,
-    },
-  },
-  {
-    name: "relay_compact_and_resume",
-    description: "Self-resume this same agent in place: Relay stores the continuation envelope, compacts or clears context, then resumes with the relay-built continuation. Use at a clean seam after a context advisory.",
-    requiredScopes: ["command:write"],
-    inputSchema: {
-      type: "object",
-      properties: {
-        workingState: { type: "string", description: "Current replaceable working state for the next generation." },
-        ruledOut: {
-          type: "array",
-          items: {
-            oneOf: [
-              { type: "string" },
-              {
-                type: "object",
-                properties: {
-                  ruledOut: { type: "string" },
-                  why: { type: "string" },
-                },
-                required: ["ruledOut"],
-                additionalProperties: false,
-              },
-            ],
-          },
-        },
-        mode: { type: "string", enum: ["clear-inject", "native"] },
-        objective: { type: "string", description: "Seed-only objective. Used only on the first call when no spawn prompt seeded the envelope." },
-      },
-      required: ["workingState"],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: "relay_recall",
-    description: "Recall this same agent's archived pre-compaction transcript segments by keyword/BM25 search. Self-only: caller identity comes from the MCP token; no agentId parameter is accepted.",
-    requiredScopes: ["memory:read"],
-    inputSchema: {
-      type: "object",
-      properties: {
-        query: { type: "string", description: "Keyword query over archived compact/clear segments." },
-        limit: { type: "integer", minimum: 1, maximum: 20 },
-      },
-      required: ["query"],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: "relay_spawn_agent",
-    description: "Spawn a long-living provider agent through Relay's orchestrator, optionally handing it its first task via `prompt` in the same call. Defaults to your own host (override with orchestratorId) and returns the resolved agent id once it registers. Gated: requires the command:spawn scope, granted only to agents whose profile sets maxSpawnedAgents>0, up to that live-children quota. Spawned agents cannot themselves spawn (no grandchildren).",
-    requiredScopes: ["command:spawn"],
-    inputSchema: {
-      type: "object",
-      properties: {
-        provider: { type: "string", enum: SPAWN_PROVIDERS },
-        orchestratorId: { type: "string", description: "Target host. Defaults to the host that owns cwd, else YOUR OWN host — only set it to spawn onto a different machine." },
-        cwd: { type: "string", description: "Working directory for the agent. Defaults to YOUR OWN cwd (the repo you're working in) when omitted, else the orchestrator's base dir. Must resolve within the target orchestrator's base directory (enforced server-side). NOTE: workspaceMode `isolated` requires a git repo — the resolved cwd must be inside one or the spawn is rejected." },
-        label: { type: "string" },
-        model: { type: "string" },
-        effort: { type: "string", enum: VALID_EFFORTS },
-        approvalMode: { type: "string", enum: APPROVAL_MODES, description: "Permission posture for the worker. Defaults to YOUR OWN approval mode when omitted (a headless `guarded` worker wedges on the first approval prompt), so a coordinator running `open` spawns workers that can act autonomously. Pass an explicit value to narrow a child (e.g. `read-only` reviewer)." },
-        prompt: { type: "string", description: "Initial task/message delivered to the agent on launch — spawn and hand it its first instruction in one call (no separate follow-up message needed)." },
-        expectReply: { type: "boolean", description: "Require the worker to report back: it gets a pending reply obligation to you and CANNOT go idle until it delivers its result (which routes to your inbox and wakes you). Defaults true when you pass a prompt — set false for a true fire-and-forget worker that needn't report (e.g. one that only lands a branch)." },
-        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 },
-        profile: { type: "string", description: "Agent profile name to apply (env, instructions, permissions, MCP/skills, spawn quota)." },
-        tags: { type: "array", items: { type: "string" } },
-        capabilities: { type: "array", items: { type: "string" } },
-        providerArgs: { type: "array", items: { type: "string" } },
-        policyName: { type: "string" },
-        spawnRequestId: { type: "string" },
-        lifecycle: { type: "string", enum: VALID_AGENT_LIFECYCLES, description: "Lifecycle mode. `persistent` keeps the agent until explicitly stopped. `transient` lets Relay auto-shutdown the child after it is idle and, for isolated workers, after its branch has landed. Default: persistent." },
-        workspaceMode: { type: "string", enum: VALID_WORKSPACE_MODES, description: "Git workspace for the worker. `isolated` = its own worktree on an `agent/session-*` branch off main that auto-lands when ready (delegate a unit of work, get a branch worker). `shared` = edits your live checkout (a sidecar). `inherit` = let the orchestrator decide. DEFAULT for agent-initiated spawns is `isolated` so a delegated worker lands to main instead of editing your tree; pass `shared`/`inherit` to override." },
-        waitForRegistrationMs: { type: "integer", minimum: 0, maximum: 30000, description: "How long to wait for the spawned agent to register before returning, so the response carries its resolved agent id (default 8000; 0 = return immediately with just spawnRequestId)." },
-      },
-      required: ["provider"],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: "relay_spawn_targets",
-    description: "Return the LIVE spawn capability matrix before you spawn: which orchestrators/hosts are online, which providers actually run on each (orchestrator-probed, not a static guess), each provider's models with per-model effort levels + defaults, your own host (isSelf) and remaining spawn quota, and named profiles you can spawn by role. Call this first whenever you decide to spawn — it removes the guesswork that otherwise only surfaces as a runtime rejection. Requires the command:spawn scope.",
-    requiredScopes: ["command:spawn"],
-    inputSchema: {
-      type: "object",
-      properties: {},
-      additionalProperties: false,
-    },
-  },
-  {
-    name: "relay_shutdown_agent",
-    description: "Shut down an agent through Relay's orchestrator. Gated: requires the command:shutdown scope; an agent caller may only target its OWN live spawned children, addressed by agentId or spawnRequestId (policyName/tmuxSession are admin-only broad targets). Admin tokens keep full reach.",
-    requiredScopes: ["command:shutdown"],
-    inputSchema: {
-      type: "object",
-      properties: {
-        agentId: { type: "string", description: "Target child by agent id. For an agent caller, agentId or spawnRequestId identifies your spawned child." },
-        policyName: { type: "string", description: "Broad target by managed-agent policy — admin/full-reach callers only." },
-        spawnRequestId: { type: "string", description: "Target child by the idempotency key relay_spawn_agent returned — resolved to your spawned child server-side." },
-        tmuxSession: { type: "string", description: "Broad target by tmux session — admin/full-reach callers only." },
-        orchestratorId: { type: "string" },
-        reason: { type: "string" },
-        timeoutMs: { type: "integer", minimum: 1 },
-      },
-      additionalProperties: false,
-    },
-  },
-  AGENT_ACTION_TOOL,
-  {
-    name: "relay_workspace_status",
-    description: "Get your isolated workspace's lifecycle status (active/ready/conflict/review_requested/merged/...). With wait:true this BLOCKS until the status changes — use it after relay_workspace_ready to wait for the auto-merge to land your branch on main (status leaves 'ready' → merged/recycled-to-active with a fresh rebased branch) or to surface a conflict/review_requested the steward couldn't auto-resolve. Defaults to the workspace you own; pass workspaceId to target another.",
-    requiredScopes: ["agents:read", "agent:read", "agent:write"],
-    alwaysLoad: true,
-    inputSchema: {
-      type: "object",
-      properties: {
-        workspaceId: { type: "string", description: "Defaults to your own isolated workspace (resolved from your identity)." },
-        wait: { type: "boolean", description: "Block until the workspace status changes (the actionable signal), or until the timeout." },
-        timeoutSeconds: { type: "integer", minimum: 1, maximum: 600, description: "Max seconds to wait when wait:true (default 300, max 600). Returns early on any transition." },
-      },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: "relay_workspace_ready",
-    description: "Signal that your branch work is finished and ready to merge back to main. This kicks off the auto-merge-back: a clean merge lands immediately; on conflict a steward agent reconciles and lands it (escalating if it can't). After this, poll relay_workspace_status with wait:true until it lands and you get a fresh rebased branch to continue on. Defaults to your own workspace.",
-    requiredScopes: ["agent:write"],
-    alwaysLoad: true,
-    inputSchema: {
-      type: "object",
-      properties: {
-        workspaceId: { type: "string", description: "Defaults to your own isolated workspace." },
-        detail: { type: "string", description: "Optional note recorded on the activity feed." },
-      },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: "relay_workspace_deps",
-    description: "Re-provision your worktree's dependencies when the shared symlinked node_modules has gone stale (e.g. typecheck reports a missing module). checkOnly:true just reports staleness without changing anything. Self-service — acts only on your own worktree.",
-    requiredScopes: ["agent:write"],
-    inputSchema: {
-      type: "object",
-      properties: {
-        workspaceId: { type: "string", description: "Defaults to your own isolated workspace." },
-        checkOnly: { type: "boolean", description: "Report staleness only; do not re-provision." },
-        detail: { type: "string" },
-      },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: "relay_workspace_list",
-    description: "List the isolated workspaces you own (id, branch, status, repo). Use it when you're unsure which workspace is yours or to see a workspace's current state. Admin/server tokens may pass all:true to list every workspace.",
-    requiredScopes: ["agents:read", "agent:read", "agent:write"],
-    inputSchema: {
-      type: "object",
-      properties: {
-        all: { type: "boolean", description: "Admin/server only: list all workspaces, not just your own." },
-        ownerAgentId: { type: "string", description: "Admin/server + all:true: filter to one owner." },
-        repoRoot: { type: "string", description: "Filter to one repository root." },
-      },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: "relay_workspace_claim",
-    description: "Take a TTL'd steward claim on a workspace so the deterministic auto-merge yields to you while you reconcile a conflict. Renew/hold while validating; relay_workspace_release frees it. Owner or assigned steward only.",
-    requiredScopes: ["agent:write"],
-    inputSchema: {
-      type: "object",
-      properties: {
-        workspaceId: { type: "string", description: "Defaults to your own isolated workspace." },
-        purpose: { type: "string", description: "Why you're claiming (shown in the activity feed)." },
-        detail: { type: "string" },
-      },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: "relay_workspace_release",
-    description: "Release a steward claim taken with relay_workspace_claim, letting the auto-merge resume. Owner or assigned steward only.",
-    requiredScopes: ["agent:write"],
-    inputSchema: {
-      type: "object",
-      properties: {
-        workspaceId: { type: "string", description: "Defaults to your own isolated workspace." },
-        purpose: { type: "string" },
-        detail: { type: "string" },
-      },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: "relay_workspace_land",
-    description: "Dispatch a base merge for your workspace directly (lease-serialized per repo, same path the auto-merge job uses). Most branch agents should use relay_workspace_ready instead and let the relay land it; this is the explicit/steward path and requires the command:write scope.",
-    requiredScopes: ["command:write"],
-    inputSchema: {
-      type: "object",
-      properties: {
-        workspaceId: { type: "string", description: "Defaults to your own isolated workspace." },
-        strategy: { type: "string", enum: ["pr", "rebase-ff", "auto"], description: "Merge strategy (default auto). Falls back to the instance landing.strategy config when unset." },
-        deleteBranch: { type: "boolean", description: "Delete the branch after a successful merge (default true)." },
-        prTitle: { type: "string" },
-        prBody: { type: "string" },
-        autoMerge: { type: "string", enum: AUTO_MERGE_POLICIES, description: "Auto-merge policy for PR-strategy lands. Defaults to 'on-green' when strategy resolves to 'pr'. Ignored for rebase-ff/auto strategies." },
-        reviewer: { type: "string", description: "GitHub login or team slug to request as a reviewer on the opened PR (pr strategy only)." },
-        detail: { type: "string" },
-      },
-      additionalProperties: false,
-    },
-  },
-  ...MERGE_TOOLS, ...TEAM_TOOLS,
-  ...PLAN_TOOLS, ...ISSUE_REF_TOOLS, ...ISSUE_ASSOCIATION_TOOLS, ...ISSUE_ACTIVITY_TOOLS, ...ISSUE_LIFECYCLE_TOOLS,
-  ...BLACKBOARD_TOOLS,
-  ...PROJECT_TOOLS,
-  ...NOTIFICATION_SUBSCRIPTION_TOOLS,
-];
-
-export async function postMcp(req: Request): Promise<Response> {
-  const parsed = await parseJsonRpcRequest(req);
-  if (!parsed.ok) return Response.json(jsonRpcError(null, -32700, parsed.error), { status: parsed.status });
-  const request = parsed.request;
-  const id = request.id ?? null;
-  const method = request.method;
-  if (typeof method !== "string") return Response.json(jsonRpcError(id, -32600, "method required"));
-
-  try {
-    const auth = mcpAuthContext(req);
-    if (!hasAnyScope(auth, ["mcp:use"])) {
-      return Response.json(jsonRpcError(id, -32001, "MCP token missing mcp:use scope", { status: 403 }));
-    }
-
-    if (method === "initialize") {
-      // Mode-tailored primer (#214 §3): surface the worktree merge-back map only
-      // to callers that own an isolated worktree; shared-workspace agents omit it.
-      // #308: append the spawn primer only when the token actually grants command:spawn —
-      // authoritative scope-gating, eager + thin, so non-spawn agents get nothing.
-      const worktree = callerIsolatedWorkspace(auth);
-      const instructions = [
-        worktree ? worktreeMcpInstructions(worktree) : "",
-        spawnCapablePrimer({ canSpawn: hasAnyScope(auth, ["command:spawn"]), quota: auth.component?.constraints?.maxSpawnedAgents }),
-      ].filter(Boolean).join("\n\n");
-      return Response.json(jsonRpcResult(id, {
-        protocolVersion: MCP_PROTOCOL_VERSION,
-        capabilities: { tools: {} },
-        serverInfo: { name: "agent-relay", title: "Agent Relay", version: VERSION },
-        ...(instructions ? { instructions } : {}),
-      }));
-    }
-    if (method === "notifications/initialized") {
-      return new Response(null, { status: 202 });
-    }
-    if (method === "tools/list") {
-      return Response.json(jsonRpcResult(id, { tools: visibleTools(auth) }));
-    }
-    if (method === "tools/call") {
-      const result = await callTool(auth, request.params);
-      return Response.json(jsonRpcResult(id, result));
-    }
-    return Response.json(jsonRpcError(id, -32601, `unknown MCP method: ${method}`));
-  } catch (error) {
-    const message = errMessage(error);
-    const status = error instanceof McpAuthError ? 403 : error instanceof McpNotFoundError ? 404 : 400;
-    const code = error instanceof McpAuthError ? -32001 : error instanceof McpNotFoundError ? -32004 : -32602;
-    return Response.json(jsonRpcError(id, code, message, { status }));
-  }
-}
-
-async function parseJsonRpcRequest(req: Request): Promise<
-  | { ok: true; request: JsonRpcRequest }
-  | { ok: false; status: number; error: string }
-> {
-  if (!req.body) return { ok: false, status: 400, error: "JSON-RPC body required" };
-  const maxBodyBytes = Math.max(MAX_BODY_BYTES, maxArtifactBytes() + MCP_BODY_OVERHEAD_BYTES);
-  const read = await readBodyBytes(req.body, maxBodyBytes);
-  if (!read.ok) return read;
-  try {
-    const body = JSON.parse(new TextDecoder().decode(read.bytes)) as unknown;
-    if (!isRecord(body)) return { ok: false, status: 400, error: "JSON-RPC body must be an object" };
-    return { ok: true, request: body as JsonRpcRequest };
-  } catch {
-    return { ok: false, status: 400, error: "invalid JSON-RPC body" };
-  }
-}
-
-function mcpAuthContext(req: Request): McpAuthContext {
-  const component = getComponentAuth(req);
-  if (component) return { actor: component.sub, kind: "component", scopes: component.scope, component };
-  const integration = getIntegrationAuth(req);
-  if (integration) return { actor: integration.name, kind: "integration", scopes: integration.scopes, integration };
-  return { actor: "server", kind: "server", scopes: ["*"] };
-}
-
-async function callTool(auth: McpAuthContext, params: unknown): Promise<Record<string, unknown>> {
-  if (!isRecord(params)) throw new ValidationError("tools/call params must be an object");
-  const name = stringField(params.name, "name", { required: true });
-  const args = recordField(params.arguments ?? {}, "arguments");
-  const tool = TOOLS.find((item) => item.name === name);
-  if (!tool) throw new ValidationError(`unknown tool: ${name}`);
-  if (!hasAnyScope(auth, tool.requiredScopes)) {
-    auditToolCall(auth, name, "denied", undefined, `missing scope: ${tool.requiredScopes.join(" or ")}`);
-    throw new McpAuthError(`tool ${name} requires ${tool.requiredScopes.join(" or ")}`);
-  }
-
-  try {
-    let result: unknown;
-    if (name === "relay_send_message") result = relaySendMessage(auth, args);
-    else if (name === "relay_reply") result = relayReply(auth, args);
-    else if (name === "relay_get_message") result = relayGetMessage(args);
-    else if (name === "relay_get_thread") result = relayGetThread(args);
-    else if (name === "relay_upload_artifact") result = await relayUploadArtifact(auth, args);
-    else if (name === "relay_attach_artifact") result = relayAttachArtifact(auth, args);
-    else if (name === "relay_agent_status") result = relayAgentStatus(args);
-    else if (name === "relay_find_agents") result = relayFindAgents(auth, args);
-    else if (name === "relay_whoami") result = relayWhoami(auth);
-    else if (name === "relay_compact_and_resume") result = relayCompactAndResume(auth, args);
-    else if (name === "relay_recall") result = relayRecall(auth, args);
-    else if (name === "relay_spawn_agent") result = await relaySpawnAgent(auth, args);
-    else if (name === "relay_spawn_targets") result = relaySpawnTargets(auth);
-    else if (name === "relay_shutdown_agent") result = relayShutdownAgent(auth, args);
-    else if (name === "relay_agent_action") result = relayAgentAction(auth, args);
-    else if (name === "relay_workspace_status") result = await relayWorkspaceStatus(auth, args);
-    else if (name === "relay_workspace_list") result = relayWorkspaceList(auth, args);
-    else if (name === "relay_workspace_ready") result = relayWorkspaceMutation(auth, "ready", args);
-    else if (name === "relay_workspace_deps") result = relayWorkspaceMutation(auth, "deps-refresh", args);
-    else if (name === "relay_workspace_claim") result = relayWorkspaceMutation(auth, "claim", args);
-    else if (name === "relay_workspace_release") result = relayWorkspaceMutation(auth, "release-claim", args);
-    else if (name === "relay_workspace_land") result = relayWorkspaceMutation(auth, "merge", args);
-    else if (name.startsWith("relay_merge_")) result = relayMergeTool(auth, name, args); else if (name.startsWith("relay_team_")) result = await relayTeamTool(auth, name, args);
-    else if (name.startsWith("relay_plan_")) result = relayPlanTool(auth, name, args);
-    else if (name.startsWith("relay_blackboard_")) result = relayBlackboardTool(auth, name, args);
-    else if (name.startsWith("relay_project_")) result = relayProjectTool(auth, name, args); else if (name.startsWith("relay_issue_ref_")) result = relayIssueRefTool(auth, name, args); else if (name.startsWith("relay_issue_association_")) result = relayIssueAssociationTool(auth, name, args); else if (name.startsWith("relay_issue_activity_")) result = relayIssueActivityTool(auth, name, args); else if (name.startsWith("relay_issue_lifecycle_")) result = await relayIssueLifecycleTool(auth, name, args);
-    else if (name === "relay_subscribe" || name === "relay_unsubscribe" || name === "relay_list_subscriptions") result = relayNotificationSubscriptionTool(auth, name, args);
-    else throw new ValidationError(`unknown tool: ${name}`);
-
-    auditToolCall(auth, name, "ok", result);
-    return toolResult(result);
-  } catch (error) {
-    const message = errMessage(error);
-    auditToolCall(auth, name, error instanceof McpAuthError ? "denied" : "error", undefined, message);
-    throw error;
-  }
-}
-
-// A managed/runtime MCP token is minted with `constraints.agents = [its own agent id]`
-// (see issueMcpRuntimeToken). That single allowed agent IS the caller's identity, and the
-// security layer already treats it as the only `from` this token may use. Derive it so
-// agents never need to know — or type — their own id.
-// THE caller-identity resolver for MCP: the agent id behind this token, for `from`-autofill,
-// relay_whoami, and spawn/shutdown gating (#221, #243). Delegates to the shared
-// `resolveCallerAgentId` (one home, src/agent-ref.ts) so the bus/HTTP/MCP transports resolve
-// caller identity identically — managed agents (runner token carrying spawnRequestId/policy,
-// no `agents` constraint) resolve back to their registered card; server/admin/multi-agent
-// tokens return undefined. Keep `relay_whoami` + the spawn/shutdown gates on THIS, not a
-// narrower check, or managed agents silently lose implicit identity again (the #243 drift).
-// (The send/reply `from`-autofill now flows through the shared send service's `ctx.callerAgentId`,
-// populated by `authContextFromMcp` from this same resolver — one home across all transports.)
-function callerAgentId(auth: McpAuthContext): string | undefined {
-  if (auth.kind !== "component") return undefined;
-  return resolveCallerAgentId(auth.component?.constraints, listAgents);
-}
-
-function relayWhoami(auth: McpAuthContext): Record<string, unknown> {
-  const agentId = callerAgentId(auth);
-  const agent = agentId ? getAgent(agentId) : null;
-  return {
-    agentId: agentId ?? null,
-    actor: auth.actor,
-    kind: auth.kind,
-    scopes: auth.scopes,
-    agent: agent ?? null,
-  };
-}
-
-function relayCompactAndResume(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
-  const agentId = callerAgentId(auth);
-  if (!agentId) throw new McpAuthError("relay_compact_and_resume requires a single caller agent identity");
-  return compactAndResume({
-    agentId,
-    workingState: stringField(args.workingState, "workingState", { required: true, maxBytes: MAX_BODY_BYTES }),
-    ruledOut: args.ruledOut,
-    mode: optionalEnum(args.mode, "mode", ["clear-inject", "native"] as const),
-    objective: optionalString(args.objective, "objective", 64_000),
-  }) as unknown as Record<string, unknown>;
-}
-
-function relayRecall(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
-  const agentId = callerAgentId(auth);
-  if (!agentId) throw new McpAuthError("relay_recall requires a single caller agent identity");
-  const matches = searchContinuationArchives({
-    agentId,
-    query: stringField(args.query, "query", { required: true, max: 1000 }),
-    limit: optionalPositiveInt(args.limit, "limit"),
-  });
-  return {
-    query: stringField(args.query, "query", { required: true, max: 1000 }),
-    matches,
-    count: matches.length,
-  };
-}
-
-// MCP transport adapter over the shared send service (epic #342). The service owns from-resolution
-// (token identity via ctx.callerAgentId), reply routing, target resolution + the converged
-// store-ahead policy, authorization, persistence, and emit. This adapter only builds the input,
-// the AuthContext (carrying the integration token separately, per the lean-AuthContext contract),
-// and maps the service's typed ServiceAuthError onto the MCP wire error (McpAuthError → 403).
-function runMcpSend(auth: McpAuthContext, input: SendMessageInput): Message & { delivery: DeliveryReceipt } {
-  try {
-    const result = sendMessageService(
-      input,
-      authContextFromMcp({ kind: auth.kind, actor: auth.actor, scopes: auth.scopes, component: auth.component }),
-      { integration: auth.integration },
-    );
-    return { ...result.message, delivery: result.receipt };
-  } catch (e) {
-    if (e instanceof ServiceAuthError) throw new McpAuthError(e.message);
-    throw e; // AmbiguousTargetError/ValidationError → invalid-params via the central JSON-RPC map.
-  }
-}
-
-function relaySendMessage(auth: McpAuthContext, args: Record<string, unknown>): Message & { delivery: DeliveryReceipt } {
-  const attachments = optionalAttachments(args.attachments);
-  const payload = payloadWithAttachments(optionalRecord(args.payload, "payload"), attachments);
-  const input: SendMessageInput = {
-    // `from` is resolved by the service from the token identity (callerAgentId wins); the wire
-    // value is only a fallback for identity-less tokens.
-    from: optionalString(args.from, "from", 200) ?? "",
-    to: stringField(args.to, "to", { required: true, max: 200 }),
-    body: stringField(args.body, "body", { required: true, maxBytes: MAX_BODY_BYTES }),
-    subject: optionalString(args.subject, "subject", 200),
-    channel: optionalString(args.channel, "channel", 120),
-    claimable: optionalBoolean(args.claimable, "claimable"),
-    idempotencyKey: optionalString(args.idempotencyKey, "idempotencyKey", 240),
-    attachments,
-    payload,
-    meta: optionalRecord(args.meta, "meta"),
-  };
-  return runMcpSend(auth, input);
-}
-
-function relayReply(auth: McpAuthContext, args: Record<string, unknown>): Message & { delivery: DeliveryReceipt } {
-  const messageId = positiveId(args.messageId, "messageId");
-  const parent = getMessage(messageId);
-  if (!parent) throw new McpNotFoundError(`message ${messageId} not found`);
-  const attachments = optionalAttachments(args.attachments);
-  const payload = optionalRecord(args.payload, "payload") ?? {};
-  const format = optionalEnum(args.format, "format", ["text", "markdown", "markdownv2"] as const);
-  const replyPayload = payloadWithAttachments({
-    ...payload,
-    ...(format ? { message: { ...(isRecord(payload.message) ? payload.message : {}), format } } : {}),
-  }, attachments);
-  const input: SendMessageInput = {
-    from: optionalString(args.from, "from", 200) ?? "",
-    // Empty `to` + replyTo lets the service auto-route to the parent's sender, inherit its
-    // channel, and propagate channel replyContext — identical to the HTTP reply path.
-    to: "",
-    body: stringField(args.body, "body", { required: true, maxBytes: MAX_BODY_BYTES }),
-    subject: optionalString(args.subject, "subject", 200),
-    replyTo: parent.id,
-    attachments,
-    payload: replyPayload,
-    meta: optionalRecord(args.meta, "meta"),
-  };
-  return runMcpSend(auth, input);
-}
-
-function relayGetMessage(args: Record<string, unknown>): Record<string, unknown> {
-  const messageId = positiveId(args.messageId, "messageId");
-  const message = getMessage(messageId);
-  if (!message) throw new McpNotFoundError(`message ${messageId} not found`);
-  const includeArtifacts = args.includeArtifacts !== false;
-  const includeThread = args.includeThread !== false;
-  return {
-    message,
-    ...(includeArtifacts ? { artifacts: listArtifactsForEntity("message", message.id) } : {}),
-    ...(includeThread ? { thread: getThread(message.id) } : {}),
-  };
-}
-
-function relayGetThread(args: Record<string, unknown>): Record<string, unknown> {
-  const messageId = positiveId(args.messageId, "messageId");
-  const thread = getThread(messageId);
-  if (!thread.length) throw new McpNotFoundError(`message ${messageId} not found`);
-  return { thread };
-}
-
-async function relayUploadArtifact(auth: McpAuthContext, args: Record<string, unknown>): Promise<Record<string, unknown>> {
-  const bytes = artifactBytes(args);
-  const maxBytes = maxArtifactBytes();
-  if (bytes.byteLength > maxBytes) throw new ValidationError(`artifact exceeds ${maxBytes} bytes`);
-  const filename = optionalString(args.filename, "filename", 240);
-  const hintedMediaType = optionalString(args.mediaType, "mediaType", 160);
-  const mediaType = sniffMediaType(bytes, hintedMediaType, filename);
-  const storage = getArtifactStorage();
-  const digest = optionalString(args.digest, "digest", 80);
-  const stored = await storage.store(bytesToStream(bytes), {
-    mediaType,
-    size: bytes.byteLength,
-    digest: digest ? normalizeDigest(digest) : undefined,
-  });
-  upsertArtifactBlob({
-    digest: stored.digest,
-    storageUri: stored.storageUri,
-    mediaType,
-    size: stored.size,
-  });
-  const artifact = createArtifact({
-    blobDigest: stored.digest,
-    mediaType,
-    kind: (optionalEnum(args.kind, "kind", VALID_ARTIFACT_KINDS) as ArtifactKind | undefined) ?? inferArtifactKind(mediaType, filename),
-    filename,
-    size: stored.size,
-    sensitivity: optionalEnum(args.sensitivity, "sensitivity", VALID_ARTIFACT_SENSITIVITIES) as ArtifactSensitivity | undefined,
-    createdBy: auth.actor,
-    expiresAt: optionalFutureTimestamp(args.expiresAt, "expiresAt"),
-    metadata: optionalRecord(args.metadata, "metadata"),
-  });
-  emitRelayEvent({ type: "artifact.created", source: "mcp", subject: artifact.id, data: { artifact, actor: auth.actor } });
-  return {
-    artifact,
-    attachment: {
-      artifactId: artifact.id,
-      kind: artifact.kind,
-      role: optionalEnum(args.role, "role", VALID_ARTIFACT_ROLES),
-      title: optionalString(args.title, "title", 240) ?? artifact.filename,
-    },
-  };
-}
-
-function relayAttachArtifact(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
-  const artifactId = stringField(args.artifactId, "artifactId", { required: true, max: 120 });
-  const artifact = getArtifact(artifactId);
-  if (!artifact) throw new McpNotFoundError(`artifact ${artifactId} not found`);
-  const entityType = enumField(args.entityType, "entityType", VALID_ARTIFACT_ENTITY_TYPES);
-  const rawEntityId = args.entityId;
-  if (typeof rawEntityId !== "string" && typeof rawEntityId !== "number") throw new ValidationError("entityId must be a string or integer");
-  const entityId = typeof rawEntityId === "number" ? positiveId(rawEntityId, "entityId") : stringField(rawEntityId, "entityId", { required: true, max: 200 });
-  assertArtifactEntityExists(entityType, entityId);
-  const link = linkArtifact({
-    artifactId,
-    entityType,
-    entityId,
-    role: optionalEnum(args.role, "role", VALID_ARTIFACT_ROLES),
-    title: optionalString(args.title, "title", 240),
-    createdBy: auth.actor,
-  });
-  return { artifact: getArtifact(artifactId) ?? artifact, link };
-}
-
-function relayAgentStatus(args: Record<string, unknown>): Record<string, unknown> {
-  const agentId = optionalString(args.agentId, "agentId", 240);
-  if (agentId) {
-    const agent = getAgent(agentId);
-    if (!agent) throw new McpNotFoundError(`agent ${agentId} not found`);
-    return { agent };
-  }
-  const policyName = optionalString(args.policyName, "policyName", 120);
-  if (policyName) return policyStatus(policyName);
-  const orchestratorId = optionalString(args.orchestratorId, "orchestratorId", 200);
-  if (orchestratorId) {
-    const orchestrator = getOrchestrator(orchestratorId);
-    if (!orchestrator) throw new McpNotFoundError(`orchestrator ${orchestratorId} not found`);
-    return { orchestrator };
-  }
-  // Default to running agents only — offline/stale rows are pure noise (you can only
-  // message/reply/pair with a live agent) and bloat the payload. includeOffline opts back in.
-  const includeOffline = optionalBoolean(args.includeOffline, "includeOffline") === true;
-  return {
-    agents: searchAgents({ status: includeOffline ? "all" : "running" }),
-    spawnPolicies: listSpawnPolicies().map((entry) => policyStatusPayload(entry.value)),
-    orchestrators: listOrchestrators(),
-  };
-}
-
-function optionalStringOrArray(value: unknown, field: string): string | string[] | undefined {
-  if (value === undefined || value === null) return undefined;
-  if (typeof value === "string") return value;
-  if (Array.isArray(value)) {
-    return value.map((item, i) => stringField(item, `${field}[${i}]`, { required: true, max: 200 }));
-  }
-  throw new ValidationError(`${field} must be a string or string array`);
-}
-
-function relayFindAgents(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
-  // `spawnedBy: "me"` resolves to the caller's own id — list the children you spawned (#221).
-  const spawnedByArg = optionalString(args.spawnedBy, "spawnedBy", 240);
-  const spawnedBy = spawnedByArg === "me" ? callerAgentId(auth) ?? "\0unresolved" : spawnedByArg;
-  const filter: AgentSearchFilter = {
-    label: optionalString(args.label, "label", 200),
-    capability: optionalStringOrArray(args.capability, "capability"),
-    provider: optionalStringOrArray(args.provider, "provider"),
-    tag: optionalStringOrArray(args.tag, "tag"),
-    machine: optionalStringOrArray(args.machine, "machine"),
-    kind: optionalStringOrArray(args.kind, "kind"),
-    spawnedBy,
-    teamId: optionalString(args.teamId, "teamId", 120),
-    // Default to running — you can only act on a live agent (consistent with #218).
-    status: optionalStringOrArray(args.status, "status") ?? "running",
-  };
-  const sort: AgentSearchSort = {
-    sortBy: optionalEnum(args.sortBy, "sortBy", ["lastActive", "created", "label"] as const),
-    order: optionalEnum(args.order, "order", ["asc", "desc"] as const),
-    limit: optionalPositiveInt(args.limit, "limit"),
-  };
-  const agents = searchAgents(filter, sort);
-  return { agents, count: agents.length };
-}
-
-async function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknown>): Promise<Record<string, unknown>> {
-  // Thin transport: parse wire → build AuthContext → call the spawnAgent service → serialize.
-  // ALL policy + side effects (caller-context inheritance, the #221 no-grandchild + quota gate,
-  // the #323 resource gate, the command:spawn scope assert, authoritative lineage stamping, the
-  // command payload + emit + audit) live in src/services/spawn-agent.ts so the MCP and HTTP spawn
-  // paths cannot drift (epic #342). `waitForRegistrationMs` defaults to a short wait here because
-  // isolated-worktree spawns register near-instantly (symlinked deps); 0 opts out.
-  const input: SpawnAgentInput = {
-    provider: enumField(args.provider, "provider", SPAWN_PROVIDERS) as SpawnProvider,
-    orchestratorId: optionalString(args.orchestratorId, "orchestratorId", 200),
-    cwd: optionalString(args.cwd, "cwd", 500),
-    model: optionalString(args.model, "model", 120),
-    effort: optionalString(args.effort, "effort", 120) as ProviderEffort | undefined,
-    approvalMode: optionalEnum(args.approvalMode, "approvalMode", APPROVAL_MODES) as SpawnApprovalMode | undefined,
-    workspaceMode: optionalEnum(args.workspaceMode, "workspaceMode", VALID_WORKSPACE_MODES) as WorkspaceMode | undefined,
-    lifecycle: (optionalEnum(args.lifecycle, "lifecycle", VALID_AGENT_LIFECYCLES) as AgentLifecycle | undefined) ?? "persistent",
-    label: optionalString(args.label, "label", 120),
-    policyName: optionalString(args.policyName, "policyName", 120),
-    profile: optionalString(args.profile, "profile", 120),
-    prompt: optionalString(args.prompt, "prompt", 16_000),
-    expectReply: typeof args.expectReply === "boolean" ? args.expectReply : undefined,
-    systemPromptAppend: optionalString(args.systemPromptAppend, "systemPromptAppend", 64_000),
-    projectInstructions: parseProjectInstructions(args.projectInstructions, (m) => new ValidationError(m)),
-    tags: optionalStringArray(args.tags, "tags"),
-    capabilities: optionalStringArray(args.capabilities, "capabilities"),
-    providerArgs: optionalStringArray(args.providerArgs, "providerArgs"),
-    spawnRequestId: optionalString(args.spawnRequestId, "spawnRequestId", 160),
-    requestedVia: "mcp",
-    waitForRegistrationMs: optionalNonNegativeInt(args.waitForRegistrationMs, "waitForRegistrationMs") ?? 8000,
-  };
-  const result = await spawnAgent(input, authContextFromMcp(auth));
-  return { ...result };
-}
-
-function relayShutdownAgent(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
-  const agentId = optionalString(args.agentId, "agentId", 240);
-  const policyName = optionalString(args.policyName, "policyName", 120);
-  const spawnRequestId = optionalString(args.spawnRequestId, "spawnRequestId", 160);
-  const tmuxSession = optionalString(args.tmuxSession, "tmuxSession", 200);
-  if (!agentId && !policyName && !spawnRequestId && !tmuxSession) {
-    throw new ValidationError("agentId, policyName, spawnRequestId, or tmuxSession required");
-  }
-
-  // The #221 parent→child gate, control-orchestrator resolution, and the canonical
-  // agent.shutdown payload + side-effects all live in the shutdownAgent service now —
-  // shared byte-for-byte with the HTTP route and the bus command frame (epic #342, #347).
-  // Map the service's transport-neutral errors back to MCP's JSON-RPC error codes.
-  try {
-    const result = shutdownAgent(
-      {
-        agentId,
-        policyName,
-        spawnRequestId,
-        tmuxSession,
-        orchestratorId: optionalString(args.orchestratorId, "orchestratorId", 200),
-        graceful: true,
-        timeoutMs: optionalPositiveInt(args.timeoutMs, "timeoutMs") ?? 10_000,
-        reason: optionalString(args.reason, "reason", 200) ?? "mcp-shutdown",
-        requestedVia: "mcp",
-        requestedBy: auth.actor,
-      },
-      authContextFromMcp(auth),
-    );
-    return { ok: true, action: "shutdown", orchestratorId: result.orchestratorId, command: result.command };
-  } catch (e) {
-    if (e instanceof ShutdownAuthError) throw new McpAuthError(e.message);
-    if (e instanceof ShutdownTargetError) throw new McpNotFoundError(e.message);
-    throw e;
-  }
-}
-
-// --- Workspace lifecycle tools (#215) -------------------------------------
-// Thin MCP surface over the shared applyWorkspaceAction core. Coarse scope is
-// enforced in callTool; here we add the resource check the routes' authorizeRoute
-// does: an agent may only act on a workspace it OWNS or stewards (server/wildcard
-// tokens keep full reach). Defaults the target to the caller's own workspace so a
-// branch agent never has to hunt for its workspace id.
-
-function isWorkspaceAdmin(auth: McpAuthContext): boolean {
-  return auth.kind === "server" || hasScope(auth, "*");
-}
-
-function assertWorkspaceAccess(auth: McpAuthContext, ws: WorkspaceRecord, caller: string | undefined): void {
-  if (isWorkspaceAdmin(auth)) return;
-  if (!caller) throw new McpAuthError(`not authorized for workspace ${ws.id} (its owner or assigned steward only)`);
-  if (caller === ws.ownerAgentId) return;
-  // The repo's elected steward (authoritative repo_stewards record, not the mirrored
-  // workspace column which only updates on steward change) may reconcile any
-  // workspace in its repo — the conflict-landing flow it exists for.
-  if (caller === getRepoSteward(ws.repoRoot)?.stewardAgentId) return;
-  throw new McpAuthError(`not authorized for workspace ${ws.id} (its owner or assigned steward only)`);
-}
-
-function resolveWorkspaceForCaller(auth: McpAuthContext, args: Record<string, unknown>): WorkspaceRecord {
-  const explicitId = optionalString(args.workspaceId, "workspaceId", 240);
-  const caller = callerAgentId(auth);
-  if (explicitId) {
-    const ws = getWorkspace(explicitId);
-    if (!ws) throw new McpNotFoundError(`workspace ${explicitId} not found`);
-    assertWorkspaceAccess(auth, ws, caller);
-    return ws;
-  }
-  if (!caller) throw new ValidationError("workspaceId is required: no caller agent identity to resolve your own workspace");
-  const first = callerIsolatedWorkspace(auth);
-  if (!first) throw new McpNotFoundError("you don't own an isolated workspace; pass workspaceId");
-  return first;
-}
-
-// Non-throwing variant for the initialize primer: the caller's most recently
-// active isolated worktree, or undefined (no caller identity / shared-only).
-// listWorkspaces is ORDER BY updated_at DESC → most recent worktree first.
-function callerIsolatedWorkspace(auth: McpAuthContext): WorkspaceRecord | undefined {
-  const caller = callerAgentId(auth);
-  if (!caller) return undefined;
-  return ownedIsolatedWorkspace(caller);
-}
-
-async function relayWorkspaceStatus(auth: McpAuthContext, args: Record<string, unknown>): Promise<Record<string, unknown>> {
-  const ws = resolveWorkspaceForCaller(auth, args);
-  if (optionalBoolean(args.wait, "wait") !== true) {
-    return { workspace: ws, guidance: describeWorkspacePhase(ws), transitioned: false, timedOut: false };
-  }
-  const timeoutSeconds = optionalPositiveInt(args.timeoutSeconds, "timeoutSeconds");
-  const result = await waitForWorkspaceStatus(ws.id, timeoutSeconds ? { timeoutMs: timeoutSeconds * 1000 } : {});
-  if (!result.workspace) throw new McpNotFoundError(`workspace ${ws.id} not found`);
-  const landed = result.transitioned ? landReceipt(result.fromStatus, result.workspace) : null;
-  return {
-    workspace: result.workspace,
-    guidance: describeWorkspacePhase(result.workspace),
-    ...(landed ? { landed } : {}),
-    fromStatus: result.fromStatus,
-    transitioned: result.transitioned,
-    timedOut: result.timedOut,
-  };
-}
-
-function relayWorkspaceList(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
-  const filter: { ownerAgentId?: string; repoRoot?: string } = {};
-  const repoRoot = optionalString(args.repoRoot, "repoRoot", 1024);
-  if (repoRoot) filter.repoRoot = repoRoot;
-  if (isWorkspaceAdmin(auth) && optionalBoolean(args.all, "all") === true) {
-    const owner = optionalString(args.ownerAgentId, "ownerAgentId", 240);
-    if (owner) filter.ownerAgentId = owner;
-  } else {
-    const caller = callerAgentId(auth);
-    if (!caller) throw new ValidationError("no caller agent identity to list your workspaces");
-    filter.ownerAgentId = caller;
-  }
-  const workspaces = listWorkspaces(filter);
-  return { workspaces, count: workspaces.length };
-}
-
-function relayWorkspaceMutation(auth: McpAuthContext, action: WorkspaceAction, args: Record<string, unknown>): Record<string, unknown> {
-  const ws = resolveWorkspaceForCaller(auth, args);
-  const result = applyWorkspaceAction(ws, {
-    action,
-    agentId: callerAgentId(auth) ?? auth.actor,
-    detail: optionalString(args.detail, "detail", 4000),
-    strategy: action === "merge" ? (optionalEnum(args.strategy, "strategy", LAND_STRATEGIES) as WorkspaceMergeStrategy | undefined) : undefined,
-    deleteBranch: action === "merge" ? optionalBoolean(args.deleteBranch, "deleteBranch") : undefined,
-    prTitle: optionalString(args.prTitle, "prTitle", 240),
-    prBody: optionalString(args.prBody, "prBody", 8000),
-    autoMerge: action === "merge" ? (optionalEnum(args.autoMerge, "autoMerge", AUTO_MERGE_POLICIES) as WorkspaceAutoMergePolicy | undefined) : undefined,
-    reviewer: action === "merge" ? optionalString(args.reviewer, "reviewer", 240) : undefined,
-    purpose: optionalString(args.purpose, "purpose", 120),
-    checkOnly: action === "deps-refresh" ? optionalBoolean(args.checkOnly, "checkOnly") === true : undefined,
-    auditMetadata: { via: "mcp", actor: auth.actor },
-  });
-  if (!result.ok) {
-    if (result.httpStatus === 404) throw new McpNotFoundError(result.error);
-    if (result.httpStatus === 403) throw new McpAuthError(result.error);
-    throw new ValidationError(result.error);
-  }
-  if (result.command) emitCommand(result.command);
-  const payload: Record<string, unknown> = { workspace: result.workspace };
-  if (result.command) payload.command = result.command;
-  if (result.claim !== undefined) payload.claim = result.claim;
-  // After a `ready` hand-off, state the whole contract up front + the directive
-  // next-step, so the agent doesn't decode status enums over the next minutes (#235).
-  if (action === "ready") {
-    payload.contract = readyContract(result.workspace);
-    payload.guidance = describeWorkspacePhase(result.workspace);
-  }
-  return payload;
-}
-
-function payloadWithAttachments(
-  payload: Record<string, unknown> | undefined,
-  attachments: AttachmentRef[] | undefined,
-): Record<string, unknown> | undefined {
-  if (!attachments) return payload;
-  if (payload?.attachments !== undefined) throw new ValidationError("attachments must be provided either top-level or in payload.attachments, not both");
-  return { ...(payload ?? {}), attachments };
-}
-
-function emitCommand(command: Command): void {
-  emitRelayEvent({
-    type: command.status === "pending" ? "command.requested" : `command.${command.status}`,
-    source: command.source,
-    subject: command.id,
-    data: { command },
-  });
-}
-
-function policyStatus(policyName: string): Record<string, unknown> {
-  const entry = getSpawnPolicy(policyName);
-  if (!entry) throw new McpNotFoundError(`spawn policy ${policyName} not found`);
-  return policyStatusPayload(entry.value);
-}
-
-function policyStatusPayload(policy: NonNullable<ReturnType<typeof getSpawnPolicy>>["value"]): Record<string, unknown> {
-  return {
-    policy,
-    state: getManagedAgentState(policy.name) ?? {
-      policyName: policy.name,
-      status: "stopped",
-      orchestratorId: policy.orchestratorId,
-      provider: policy.provider,
-      restartCount: 0,
-      consecutiveFailures: 0,
-      updatedAt: 0,
-    },
-  };
-}
-
-// #308 — thin auth wrapper over the spawn capability matrix (src/spawn-targets.ts owns the build).
-function relaySpawnTargets(auth: McpAuthContext): Record<string, unknown> {
-  return buildSpawnTargets({
-    callerId: callerAgentId(auth),
-    quota: auth.component?.constraints?.maxSpawnedAgents ?? 0,
-  });
-}
-
-function artifactBytes(args: Record<string, unknown>): Uint8Array {
-  const hasContent = args.content !== undefined && args.content !== null;
-  const hasBase64 = args.base64 !== undefined && args.base64 !== null;
-  if (hasContent === hasBase64) throw new ValidationError("provide exactly one of content or base64");
-  if (hasContent) {
-    if (typeof args.content !== "string" || args.content.length === 0) throw new ValidationError("content required");
-    return new TextEncoder().encode(args.content);
-  }
-  const encoded = stringField(args.base64, "base64", { required: true }).replace(/\s+/g, "");
-  if (encoded.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(encoded)) throw new ValidationError("base64 must be valid base64 content");
-  return new Uint8Array(Buffer.from(encoded, "base64"));
-}
-
-function assertArtifactEntityExists(entityType: string, entityId: string | number): void {
-  if (entityType === "message" && !getMessage(Number(entityId))) throw new McpNotFoundError(`message ${entityId} not found`);
-  if (entityType === "task" && !getTask(Number(entityId))) throw new McpNotFoundError(`task ${entityId} not found`);
-}
-
-function inferArtifactKind(mediaType: string, filename?: string): ArtifactKind {
-  const lowerName = filename?.toLowerCase() ?? "";
-  if (mediaType.startsWith("image/")) return "image";
-  if (mediaType.startsWith("audio/")) return "audio";
-  if (mediaType.startsWith("video/")) return "video";
-  if (["application/zip", "application/gzip", "application/x-tar"].includes(mediaType) || /\.(zip|tgz|tar|gz)$/.test(lowerName)) return "archive";
-  if (
-    mediaType.startsWith("text/") ||
-    ["application/pdf", "application/json", "application/xml"].includes(mediaType) ||
-    /\.(pdf|txt|md|json|csv|diff|patch)$/.test(lowerName)
-  ) return "document";
-  return "other";
-}
-
-function sniffMediaType(bytes: Uint8Array, hinted?: string, filename?: string): string {
-  if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return "image/jpeg";
-  if (bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47) return "image/png";
-  if (bytes[0] === 0x47 && bytes[1] === 0x49 && bytes[2] === 0x46) return "image/gif";
-  if (bytes[0] === 0x25 && bytes[1] === 0x50 && bytes[2] === 0x44 && bytes[3] === 0x46) return "application/pdf";
-  if (bytes[0] === 0x50 && bytes[1] === 0x4b) return "application/zip";
-  const lower = filename?.toLowerCase() ?? "";
-  if (lower.endsWith(".svg")) return "image/svg+xml";
-  if (lower.endsWith(".md")) return "text/markdown";
-  if (lower.endsWith(".json")) return "application/json";
-  if (lower.endsWith(".csv")) return "text/csv";
-  if (lower.endsWith(".diff") || lower.endsWith(".patch")) return "text/x-diff";
-  return hinted || "text/plain";
-}
-
-function visibleTools(auth: McpAuthContext): Array<Record<string, unknown>> {
-  return TOOLS
-    .filter((tool) => hasAnyScope(auth, tool.requiredScopes))
-    .map(({ name, description, alwaysLoad, ...tool }) => ({
-      name,
-      description,
-      inputSchema: providerCatalogToolInputSchema(name, tool.inputSchema),
-      ...(alwaysLoad ? { _meta: { "anthropic/alwaysLoad": true } } : {}),
-    }));
-}
-
-function toolResult(result: unknown): Record<string, unknown> {
-  return {
-    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-    structuredContent: result,
-  };
-}
-
-function jsonRpcResult(id: JsonRpcId, result: unknown): Record<string, unknown> {
-  return { jsonrpc: "2.0", id, result };
-}
-
-function jsonRpcError(id: JsonRpcId, code: number, message: string, data?: unknown): Record<string, unknown> {
-  return { jsonrpc: "2.0", id, error: { code, message, ...(data ? { data } : {}) } };
-}
-
-function assertComponentResourceAllowed(
-  auth: McpAuthContext,
-  check: Parameters<typeof isComponentAuthorizedFor>[1],
-): void {
-  if (auth.component && !isComponentAuthorizedFor(auth.component, check)) {
-    throw new McpAuthError("component token cannot access this resource");
-  }
-}
-
-function hasAnyScope(auth: McpAuthContext, required: string[]): boolean {
-  if (auth.scopes.includes("*") || auth.scopes.includes("admin:*")) return true;
-  return required.some((scope) => hasScope(auth, scope));
-}
-
-function hasScope(auth: McpAuthContext, scope: string): boolean {
-  if (auth.kind === "component") {
-    return hasComponentScope({ sub: auth.actor, role: "provider", scope: auth.scopes, iat: 0 }, scope);
-  }
-  if (auth.kind === "integration" && auth.integration) {
-    if (hasIntegrationScope(auth.integration, scope)) return true;
-    const [category] = scope.split(":");
-    return Boolean(category && hasIntegrationScope(auth.integration, `${category}:*`));
-  }
-  const [category] = scope.split(":");
-  return auth.scopes.includes(scope) || Boolean(category && auth.scopes.includes(`${category}:*`));
-}
-
-function auditToolCall(
-  auth: McpAuthContext,
-  tool: string,
-  status: "ok" | "denied" | "error",
-  result?: unknown,
-  error?: string,
-): void {
-  try {
-    const messageId = isRecord(result) && isRecord(result.message)
-      ? positiveIdOrUndefined(result.message.id)
-      : isRecord(result) ? positiveIdOrUndefined(result.id) : undefined;
-    const kind: ActivityKind = tool.includes("reply") ? "reply" : tool.includes("send") ? "message" : "state";
-    createActivityEvent({
-      kind,
-      title: `MCP ${tool}`,
-      body: error ?? status,
-      meta: auth.actor,
-      icon: status === "ok" ? "ti-plug-connected" : status === "denied" ? "ti-shield-x" : "ti-alert-triangle",
-      view: "messages",
-      messageId,
-      agentId: auth.actor,
-      metadata: { source: "mcp", tool, actor: auth.actor, authKind: auth.kind, status },
-    });
-  } catch {
-    // Audit writes must not block tool calls.
-  }
-}
-
-function recordField(value: unknown, field: string): Record<string, unknown> {
-  if (!isRecord(value)) throw new ValidationError(`${field} must be an object`);
-  return value;
-}
-
-function optionalRecord(value: unknown, field: string): Record<string, unknown> | undefined {
-  if (value === undefined || value === null) return undefined;
-  return recordField(value, field);
-}
-
-function stringField(
-  value: unknown,
-  field: string,
-  opts: { required?: boolean; max?: number; maxBytes?: number } = {},
-): string {
-  if (value === undefined || value === null) {
-    if (opts.required) throw new ValidationError(`${field} required`);
-    return "";
-  }
-  if (typeof value !== "string") throw new ValidationError(`${field} must be a string`);
-  const trimmed = value.trim();
-  if (opts.required && !trimmed) throw new ValidationError(`${field} required`);
-  if (opts.max && trimmed.length > opts.max) throw new ValidationError(`${field} must be ${opts.max} characters or fewer`);
-  if (opts.maxBytes && encodedLength(trimmed) > opts.maxBytes) throw new ValidationError(`${field} exceeds ${opts.maxBytes} bytes`);
-  return trimmed;
-}
-
-function optionalString(value: unknown, field: string, max: number): string | undefined {
-  if (value === undefined || value === null) return undefined;
-  const cleaned = stringField(value, field, { max });
-  return cleaned || undefined;
-}
-
-function optionalBoolean(value: unknown, field: string): boolean | undefined {
-  if (value === undefined || value === null) return undefined;
-  if (typeof value !== "boolean") throw new ValidationError(`${field} must be a boolean`);
-  return value;
-}
-
-function enumField<T extends readonly string[]>(value: unknown, field: string, valid: T): T[number] {
-  const cleaned = optionalEnum(value, field, valid);
-  if (!cleaned) throw new ValidationError(`${field} required`);
-  return cleaned;
-}
-
-function optionalStringArray(value: unknown, field: string): string[] | undefined {
-  if (value === undefined || value === null) return undefined;
-  if (!Array.isArray(value)) throw new ValidationError(`${field} must be an array of strings`);
-  const cleaned = value.map((item, index) => stringField(item, `${field}[${index}]`, { required: true, max: 120 }));
-  if (cleaned.length > 50) throw new ValidationError(`${field} can contain at most 50 values`);
-  return [...new Set(cleaned)];
-}
-
-function positiveId(value: unknown, field: string): number {
-  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) throw new ValidationError(`${field} must be a positive integer`);
-  return value;
-}
-
-function positiveIdOrUndefined(value: unknown): number | undefined {
-  return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : undefined;
-}
-
-function optionalPositiveInt(value: unknown, field: string): number | undefined {
-  if (value === undefined || value === null) return undefined;
-  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) throw new ValidationError(`${field} must be a positive integer`);
-  return value;
-}
-
-function optionalNonNegativeInt(value: unknown, field: string): number | undefined {
-  if (value === undefined || value === null) return undefined;
-  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new ValidationError(`${field} must be a non-negative integer`);
-  return value;
-}
-
-function optionalFutureTimestamp(value: unknown, field: string): number | undefined {
-  const timestamp = optionalPositiveInt(value, field);
-  if (timestamp !== undefined && timestamp <= Date.now()) throw new ValidationError(`${field} must be a future unix timestamp in milliseconds`);
-  return timestamp;
-}
-
-function optionalAttachments(value: unknown): AttachmentRef[] | undefined {
-  if (value === undefined || value === null) return undefined;
-  if (!Array.isArray(value)) throw new ValidationError("attachments must be an array");
-  return value.map((item, index) => {
-    const record = recordField(item, `attachments[${index}]`);
-    return {
-      artifactId: stringField(record.artifactId, `attachments[${index}].artifactId`, { required: true, max: 120 }),
-      kind: optionalString(record.kind, `attachments[${index}].kind`, 40) as AttachmentRef["kind"],
-      role: optionalString(record.role, `attachments[${index}].role`, 40) as AttachmentRef["role"],
-      title: optionalString(record.title, `attachments[${index}].title`, 240),
-      ref: optionalRecord(record.ref, `attachments[${index}].ref`) as AttachmentRef["ref"],
-      metadata: optionalRecord(record.metadata, `attachments[${index}].metadata`),
-    };
-  });
-}
-
-function encodedLength(value: string): number {
-  return new TextEncoder().encode(value).byteLength;
-}
+export * from "./mcp/index.js";