agent-relay-server 0.36.2 → 0.37.0

package/src/mcp.ts

@@ -1,17 +1,15 @@
 import { Buffer } from "node:buffer";
 import { getArtifactStorage, maxArtifactBytes, normalizeDigest } from "./artifact-storage";
-import { createCommand } from "./commands-db";
-import { buildSpawnCommand, generateSpawnRequestId, resolveSpawnModelParams, type SpawnModelParams } from "./spawn-command";
+import { spawnAgent, type SpawnAgentInput } from "./services/spawn-agent";
+import { authContextFromMcp } from "./services/auth-context";
 import { isPathWithinBase } from "./utils";
 import { optionalEnum } from "./validation";
-import { listManagedOrchestratorsForAgent } from "./orchestrator-lookup";
 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 {
-  countLiveSpawnedAgents,
   createArtifact,
   createActivityEvent,
   getAgent,
@@ -31,27 +29,26 @@ import {
   type AgentSearchSort,
   listArtifactsForEntity,
   listOrchestrators,
-  sendMessageWithResult,
   upsertArtifactBlob,
   ValidationError,
 } from "./db";
-import { planSend, type DeliveryReceipt } from "./agent-ref";
+import { resolveCallerAgentId, type DeliveryReceipt } from "./agent-ref";
+import { ShutdownAuthError, ShutdownTargetError, shutdownAgent } from "./services/shutdown-agent";
 import { emitRelayEvent } from "./events";
-import { emitMessageQueued, emitNewMessage } from "./sse";
 import {
   getComponentAuth,
   getIntegrationAuth,
   hasComponentScope,
   hasIntegrationScope,
   isComponentAuthorizedFor,
-  isIntegrationAllowed,
 } from "./security";
-import type { ActivityKind, AgentCard, ArtifactKind, ArtifactSensitivity, AttachmentRef, Command, SendMessageInput, Message, SpawnApprovalMode, SpawnProvider, WorkspaceMergeStrategy, WorkspaceMode, WorkspaceRecord } from "./types";
+import { sendMessageService } from "./services/send-message";
+import { ServiceAuthError } from "./services/errors";
+import type { ActivityKind, ArtifactKind, ArtifactSensitivity, AttachmentRef, Command, SendMessageInput, Message, SpawnApprovalMode, SpawnProvider, WorkspaceMergeStrategy, WorkspaceMode, WorkspaceRecord } from "./types";
 import { LAND_STRATEGIES, applyWorkspaceAction, waitForWorkspaceStatus, type WorkspaceAction } from "./workspace-actions";
 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_EFFORTS, VALID_WORKSPACE_MODES } from "agent-relay-sdk";
-import { runnerRuntimeTokenEnv } from "./runtime-tokens";
 
 type JsonRpcId = string | number | null;
 
@@ -94,7 +91,7 @@ const VALID_ARTIFACT_ENTITY_TYPES = ["message", "task", "recipeRun", "recipeStep
 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. Unknown or ambiguous targets are rejected up front, never silently dropped.",
+    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",
@@ -531,41 +528,18 @@ async function callTool(auth: McpAuthContext, params: unknown): Promise<Record<s
 // (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.
-function senderIdentity(auth: McpAuthContext): string | undefined {
-  if (auth.kind !== "component") return undefined;
-  const agents = auth.component?.constraints?.agents;
-  return agents?.length === 1 ? agents[0] : undefined;
-}
-
-// THE caller-identity resolver: the agent id behind this token, for `from`-autofill,
-// relay_whoami, and spawn/shutdown gating (#221, #243). `senderIdentity` covers
-// identity-bearing tokens (interactive/mcp, constraints.agents). Managed agents spawned by
-// the orchestrator authenticate with a runner token that carries no `agents` constraint but
-// DOES carry its spawnRequestId/policy — resolve those back to the registered agent card so
-// they never need to pass `from`. Returns undefined for server/admin tokens (unrestricted by
-// design) and multi-agent tokens. Keep `resolveSender`/`relayWhoami` on THIS, not the narrower
-// `senderIdentity`, or managed agents silently lose implicit identity again (the #243 drift).
+// 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 {
-  const direct = senderIdentity(auth);
-  if (direct) return direct;
   if (auth.kind !== "component") return undefined;
-  const c = auth.component?.constraints;
-  const spawnRequestId = c?.spawnRequestIds?.length === 1 ? c.spawnRequestIds[0] : undefined;
-  const policyName = c?.policies?.length === 1 ? c.policies[0] : undefined;
-  if (!spawnRequestId && !policyName) return undefined;
-  const match = listAgents().find((a) =>
-    (spawnRequestId !== undefined && a.meta?.spawnRequestId === spawnRequestId) ||
-    (policyName !== undefined && a.meta?.policyName === policyName));
-  return match?.id;
-}
-
-function resolveSender(auth: McpAuthContext, rawFrom: unknown): string {
-  // Token identity wins and cannot be spoofed; any provided `from` is ignored when known.
-  // Resolves both constraints.agents tokens AND spawn/policy-managed agents (#243).
-  const identity = callerAgentId(auth);
-  if (identity) return identity;
-  // Server/integration/multi-agent tokens carry no single identity — keep requiring `from`.
-  return stringField(rawFrom, "from", { required: true, max: 200 });
+  return resolveCallerAgentId(auth.component?.constraints, listAgents);
 }
 
 function relayWhoami(auth: McpAuthContext): Record<string, unknown> {
@@ -580,20 +554,33 @@ function relayWhoami(auth: McpAuthContext): Record<string, unknown> {
   };
 }
 
+// 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 requestedTo = stringField(args.to, "to", { required: true, max: 200 });
-  const sender = resolveSender(auth, args.from);
-  // Resolve the target to a canonical agent id (so poll-time matching works) and refuse
-  // up front when it's unknown or ambiguous — never store a message no one will receive.
-  // Exclude the sender so a bare ref can't loop back to its own author (#290).
-  const plan = planSend(requestedTo, listAgents(), { excludeId: sender });
-  if (plan.kind === "not_found") throw new McpNotFoundError(plan.message);
-  if (plan.kind === "ambiguous") throw new ValidationError(plan.message);
   const input: SendMessageInput = {
-    from: sender,
-    to: plan.to,
+    // `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),
@@ -603,11 +590,7 @@ function relaySendMessage(auth: McpAuthContext, args: Record<string, unknown>):
     payload,
     meta: optionalRecord(args.meta, "meta"),
   };
-  assertIntegrationTargetAllowed(auth, input.to, input.channel);
-  assertComponentResourceAllowed(auth, { scope: "message:send", resource: { target: input.to, channel: input.channel, agentId: input.from } });
-  const result = sendMessageWithResult(input);
-  emitMessage(result.message, result.created);
-  return { ...result.message, delivery: plan.receipt };
+  return runMcpSend(auth, input);
 }
 
 function relayReply(auth: McpAuthContext, args: Record<string, unknown>): Message & { delivery: DeliveryReceipt } {
@@ -620,30 +603,20 @@ function relayReply(auth: McpAuthContext, args: Record<string, unknown>): Messag
   const replyPayload = payloadWithAttachments({
     ...payload,
     ...(format ? { message: { ...(isRecord(payload.message) ? payload.message : {}), format } } : {}),
-    ...replyContext(parent),
   }, attachments);
   const input: SendMessageInput = {
-    from: resolveSender(auth, args.from),
-    to: parent.from,
+    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),
-    channel: parent.channel,
     replyTo: parent.id,
     attachments,
     payload: replyPayload,
     meta: optionalRecord(args.meta, "meta"),
   };
-  assertIntegrationTargetAllowed(auth, input.to, input.channel);
-  assertComponentResourceAllowed(auth, { scope: "message:send", resource: { target: input.to, channel: input.channel, agentId: input.from } });
-  const result = sendMessageWithResult(input);
-  emitMessage(result.message, result.created);
-  // Reply routing is fixed to the parent's sender — never reject, but report whether
-  // that original sender is still reachable so the agent doesn't wait forever.
-  const plan = planSend(input.to, listAgents(), { excludeId: input.from });
-  const delivery: DeliveryReceipt = plan.kind === "not_found" || plan.kind === "ambiguous"
-    ? { delivered: false, expectReply: false, recipients: [], reason: "original sender no longer reachable" }
-    : plan.receipt;
-  return { ...result.message, delivery };
+  return runMcpSend(auth, input);
 }
 
 function relayGetMessage(args: Record<string, unknown>): Record<string, unknown> {
@@ -788,136 +761,34 @@ function relayFindAgents(auth: McpAuthContext, args: Record<string, unknown>): R
 }
 
 async function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknown>): Promise<Record<string, unknown>> {
-  const provider = enumField(args.provider, "provider", SPAWN_PROVIDERS) as SpawnProvider;
-  const cwd = optionalString(args.cwd, "cwd", 500);
-  const callerId = callerAgentId(auth);
-  // One caller-record lookup, reused for host preference (#221), the cwd default (#328) and the
-  // approvalMode default (#331) — an agent spawning a helper inherits its own context instead of
-  // falling back to hardcoded values.
-  const caller = callerId ? getAgent(callerId) : undefined;
-  const preferHost = caller?.machine;
-  const orchestrator = selectSpawnOrchestrator(provider, optionalString(args.orchestratorId, "orchestratorId", 200), cwd, preferHost);
-  // #328 — default cwd to the caller's OWN cwd (the repo it's working in), not the orchestrator
-  // base dir, so "agent spawns a helper for its current task" Just Works — especially isolated mode,
-  // which needs a git repo (the base dir usually isn't one, so it silently downgraded to shared).
-  // Only adopt the caller's cwd when it resolves within the TARGET host's base dir (preferHost
-  // already biases the target to the caller's host; a cross-host path may not exist there). Non-agent
-  // callers (no caller record) keep the base-dir fallback. Precedence: explicit cwd > caller cwd > base dir.
-  const callerCwd = stringValue(caller?.meta?.cwd);
-  const inheritedCwd = callerCwd && isPathWithinBase(callerCwd, orchestrator.baseDir) ? callerCwd : undefined;
-  const resolvedCwd = cwd || inheritedCwd || orchestrator.baseDir;
-  // #308 §3 — cwd must resolve within the TARGET host's base dir. A path valid on your own host
-  // may not exist on a different orchestrator, so validate against the chosen host and say which.
-  if (cwd && !isPathWithinBase(cwd, orchestrator.baseDir)) {
-    throw new ValidationError(`cwd '${cwd}' is not within ${orchestrator.id} (host ${orchestrator.hostname})'s base dir '${orchestrator.baseDir}' — a path valid on your host may not exist on the target. Pass a cwd under that base dir, or omit cwd to default to it.`);
-  }
-  const selection = providerSelection(provider, args);
-  // #331 — default the child's approval mode to the CALLER's, not a hardcoded `guarded`. A headless
-  // `guarded` child wedges on the first tool-call approval prompt (no human at the TUI — it can't even
-  // read its own spawn message). A trusted coordinator running `open` spawns workers that can actually
-  // work in their isolated worktrees; an explicit arg always wins and can NARROW a child (e.g. a
-  // read-only reviewer); non-agent/admin callers (no caller record) keep the safe `guarded` default.
-  // Precedence: explicit approvalMode > caller mode > guarded.
-  const callerApprovalMode = optionalEnum(stringValue(caller?.meta?.approvalMode), "approvalMode", APPROVAL_MODES) as SpawnApprovalMode | undefined;
-  const approvalMode = (optionalEnum(args.approvalMode, "approvalMode", APPROVAL_MODES) as SpawnApprovalMode | undefined)
-    ?? callerApprovalMode
-    ?? "guarded";
-  const spawnRequestId = optionalString(args.spawnRequestId, "spawnRequestId", 160) ?? generateSpawnRequestId();
-  const label = optionalString(args.label, "label", 120);
-  const policyName = optionalString(args.policyName, "policyName", 120);
-  const profile = optionalString(args.profile, "profile", 120);
-  // #324 — expose the workspace knob on the MCP spawn surface (payload home always supported it; the
-  // handler just never passed it → orchestrator fell back to `inherit`→`shared`, so a worker edited the
-  // CALLER's live tree). Agent-initiated spawns (real caller behind the token) default to `isolated` (a
-  // branch worker that auto-lands); non-agent callers (admin/server) keep `inherit`. Explicit wins.
-  const workspaceMode = (optionalEnum(args.workspaceMode, "workspaceMode", VALID_WORKSPACE_MODES) as WorkspaceMode | undefined) ?? (callerId ? "isolated" : undefined);
-
-  // #221 runtime gate (belt; the coarse `command:spawn` scope is enforced in callTool, and is
-  // granted only to agents whose profile sets maxSpawnedAgents>0 and never to children).
-  // Server/admin tokens have no caller identity → unrestricted by design.
-  if (callerId) {
-    if (caller?.spawnedBy) {
-      throw new McpAuthError("spawned agents cannot spawn further agents (no grandchildren)");
-    }
-    const quota = auth.component?.constraints?.maxSpawnedAgents ?? 0;
-    const live = countLiveSpawnedAgents(callerId);
-    if (live >= quota) {
-      throw new ValidationError(`spawn quota reached (${live}/${quota} live children) — shut one down or wait for one to exit`);
-    }
-  }
-
-  // #323 — gate child spawn only on `orchestrators` (the parent's legit bound), NOT its self-scoping
-  // spawnRequestIds/cwdPrefixes/policies: those describe the child, not parent-owned resources, so
-  // gating on them makes maxSpawnedAgents unreachable for every component token (cwd checked above).
-  assertComponentResourceAllowed(auth, { scope: "agent:write", resource: { orchestratorId: orchestrator.id } });
-
-  // Child runner token: a normal long-living agent that is NOT itself spawn-capable
-  // (canSpawn:false → no grandchildren), stamped with authoritative lineage so it registers
-  // with spawnedBy = caller (the child can't forge it; it's read from the signed token).
-  const env = runnerRuntimeTokenEnv({
-    orchestratorId: orchestrator.id,
-    cwd: resolvedCwd,
-    provider,
-    label,
-    policyName,
-    spawnRequestId,
-    createdBy: callerId ?? auth.actor,
-    agentInitiated: true,
-    ...(callerId ? { spawnedBy: callerId } : {}),
-  });
-  const command = createCommand({
-    type: "agent.spawn",
-    source: "system",
-    target: orchestrator.agentId,
-    correlationId: spawnRequestId,
-    params: buildSpawnCommand({
-      provider,
-      modelParams: selection,
-      cwd: resolvedCwd,
-      ...(workspaceMode ? { workspaceMode } : {}),
-      label,
-      profile: profile || undefined,
-      tags: optionalStringArray(args.tags, "tags") ?? [],
-      capabilities: optionalStringArray(args.capabilities, "capabilities") ?? [],
-      approvalMode,
-      permissionMode: approvalMode,
-      providerArgs: optionalStringArray(args.providerArgs, "providerArgs") ?? [],
-      prompt: optionalString(args.prompt, "prompt", 16_000),
-      systemPromptAppend: optionalString(args.systemPromptAppend, "systemPromptAppend", 64_000),
-      policyName,
-      spawnRequestId,
-      env,
-      requestedBy: auth.actor,
-      requestedVia: "mcp",
-      requestedAt: Date.now(),
-      orchestratorId: orchestrator.id,
-      // #308 — stamp the spawning parent so a failed agent.spawn command can be routed back to
-      // it (the child never registers, so there's no agent record to resolve `spawnedBy` from).
-      ...(callerId ? { extra: { spawnedBy: callerId } } : {}),
-    }),
-  });
-  emitCommand(command);
-
-  // #255: resolve the spawned agent id once it registers. Spawn is a fire-and-forget command
-  // over the bus; the child registers back to THIS relay (same DB) with meta.spawnRequestId set,
-  // so a bounded poll links the request to the agent without a separate relay_find_agents round
-  // trip. waitForRegistrationMs:0 opts out (pure fire-and-forget); the default is short because
-  // isolated-worktree spawns register near-instantly (symlinked deps).
-  const waitMs = Math.min(optionalNonNegativeInt(args.waitForRegistrationMs, "waitForRegistrationMs") ?? 8000, 30000);
-  const agentId = waitMs > 0 ? await waitForSpawnedAgent(spawnRequestId, waitMs) : null;
-  return { ok: true, spawnRequestId, orchestratorId: orchestrator.id, provider, agentId, registered: agentId !== null, command };
-}
-
-// Poll the agents table for the child that registers with this spawnRequestId (#255). Returns
-// the resolved agent id, or null on timeout (the caller still has spawnRequestId to poll later).
-async function waitForSpawnedAgent(spawnRequestId: string, timeoutMs: number, pollMs = 300): Promise<string | null> {
-  const deadline = Date.now() + timeoutMs;
-  for (;;) {
-    const match = listAgents().find((a) => a.meta?.spawnRequestId === spawnRequestId);
-    if (match) return match.id;
-    if (Date.now() >= deadline) return null;
-    await new Promise<void>((resolve) => setTimeout(resolve, Math.min(pollMs, Math.max(0, deadline - Date.now()))));
-  }
+  // 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: optionalEnum(args.effort, "effort", VALID_EFFORTS) as ProviderEffort | undefined,
+    approvalMode: optionalEnum(args.approvalMode, "approvalMode", APPROVAL_MODES) as SpawnApprovalMode | undefined,
+    workspaceMode: optionalEnum(args.workspaceMode, "workspaceMode", VALID_WORKSPACE_MODES) as WorkspaceMode | undefined,
+    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),
+    systemPromptAppend: optionalString(args.systemPromptAppend, "systemPromptAppend", 64_000),
+    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> {
@@ -929,50 +800,32 @@ function relayShutdownAgent(auth: McpAuthContext, args: Record<string, unknown>)
     throw new ValidationError("agentId, policyName, spawnRequestId, or tmuxSession required");
   }
 
-  // #221: an agent caller may only shut down its OWN live spawned children, addressed by
-  // agentId. Broad targeting (policy/spawnRequestId/tmux) and cross-agent kills stay admin-only
-  // — otherwise spawn permission silently becomes kill-anyone permission. Server/admin tokens
-  // (no caller identity) keep full reach.
-  const callerId = callerAgentId(auth);
-  if (callerId) {
-    if (!agentId || policyName || spawnRequestId || tmuxSession) {
-      throw new McpAuthError("agents may only shut down their own spawned children, addressed by agentId");
-    }
-    const target = getAgent(agentId);
-    if (!target || target.spawnedBy !== callerId) {
-      throw new McpAuthError(`agent ${agentId} is not one of your spawned children`);
-    }
+  // 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;
   }
-  const orchestrator = selectControlOrchestrator({
-    orchestratorId: optionalString(args.orchestratorId, "orchestratorId", 200),
-    agentId,
-    policyName,
-    spawnRequestId,
-    tmuxSession,
-  });
-  const timeoutMs = optionalPositiveInt(args.timeoutMs, "timeoutMs") ?? 10_000;
-  const command = createCommand({
-    type: "agent.shutdown",
-    source: "system",
-    target: orchestrator.agentId,
-    correlationId: spawnRequestId,
-    params: {
-      action: "shutdown",
-      agentId,
-      policyName,
-      spawnRequestId,
-      tmuxSession,
-      graceful: true,
-      timeoutMs,
-      reason: optionalString(args.reason, "reason", 200) ?? "mcp-shutdown",
-      requestedBy: auth.actor,
-      requestedVia: "mcp",
-      requestedAt: Date.now(),
-      orchestratorId: orchestrator.id,
-    },
-  });
-  emitCommand(command);
-  return { ok: true, action: "shutdown", orchestratorId: orchestrator.id, command };
 }
 
 // --- Workspace lifecycle tools (#215) -------------------------------------
@@ -1088,16 +941,6 @@ function relayWorkspaceMutation(auth: McpAuthContext, action: WorkspaceAction, a
   return payload;
 }
 
-function replyContext(parent: Message): Record<string, unknown> {
-  const parentPayload = parent.payload ?? {};
-  if (parentPayload.schema !== "agent-relay.channel.v1" && !parentPayload.conversation) return {};
-  const context: Record<string, unknown> = {};
-  if (parent.channel) context.channelId = parent.channel;
-  if (isRecord(parentPayload.conversation)) context.conversationId = parentPayload.conversation.id;
-  if (isRecord(parentPayload.event)) context.parentEventId = parentPayload.event.id;
-  if (parentPayload.source) context.source = parentPayload.source;
-  return { replyContext: context };
-}
 
 function payloadWithAttachments(
   payload: Record<string, unknown> | undefined,
@@ -1146,45 +989,6 @@ function relaySpawnTargets(auth: McpAuthContext): Record<string, unknown> {
   });
 }
 
-function selectControlOrchestrator(input: {
-  orchestratorId?: string;
-  agentId?: string;
-  policyName?: string;
-  spawnRequestId?: string;
-  tmuxSession?: string;
-}): NonNullable<ReturnType<typeof getOrchestrator>> {
-  if (input.orchestratorId) {
-    const orchestrator = getOrchestrator(input.orchestratorId);
-    if (!orchestrator) throw new McpNotFoundError(`orchestrator ${input.orchestratorId} not found`);
-    if (orchestrator.status !== "online") throw new ValidationError("orchestrator is offline");
-    return orchestrator;
-  }
-  const agent = input.agentId ? getAgent(input.agentId) : null;
-  const orchestrator = agent ? managedControlOrchestrator(agent, input) : (listManagedOrchestratorsForAgent(input)[0] ?? null);
-  if (!orchestrator) throw new McpNotFoundError("no orchestrator found for agent control target");
-  if (orchestrator.status !== "online") throw new ValidationError("orchestrator is offline");
-  return orchestrator;
-}
-
-function managedControlOrchestrator(
-  agent: AgentCard,
-  input: { policyName?: string; spawnRequestId?: string; tmuxSession?: string },
-): NonNullable<ReturnType<typeof getOrchestrator>> | null {
-  const str = (v: unknown): string | undefined => (typeof v === "string" ? v : undefined);
-  return listManagedOrchestratorsForAgent({
-    agentId: agent.id,
-    policyName: input.policyName ?? str(agent.meta?.policyName),
-    spawnRequestId: input.spawnRequestId ?? str(agent.meta?.spawnRequestId),
-    tmuxSession: input.tmuxSession ?? str(agent.meta?.tmuxSession),
-  })[0] ?? (agent.machine ? getOrchestrator(agent.machine) : null);
-}
-
-function providerSelection(provider: SpawnProvider, args: Record<string, unknown>): SpawnModelParams {
-  const model = optionalString(args.model, "model", 120);
-  const effort = optionalEnum(args.effort, "effort", VALID_EFFORTS) as ProviderEffort | undefined;
-  return resolveSpawnModelParams(provider, model, effort);
-}
-
 function artifactBytes(args: Record<string, unknown>): Uint8Array {
   const hasContent = args.content !== undefined && args.content !== null;
   const hasBase64 = args.base64 !== undefined && args.base64 !== null;
@@ -1232,12 +1036,6 @@ function sniffMediaType(bytes: Uint8Array, hinted?: string, filename?: string):
   return hinted || "text/plain";
 }
 
-function emitMessage(message: Message, created: boolean): void {
-  if (!created) return;
-  if (message.deliveryStatus === "queued") emitMessageQueued(message);
-  else emitNewMessage(message);
-}
-
 function visibleTools(auth: McpAuthContext): Array<Record<string, unknown>> {
   return TOOLS
     .filter((tool) => hasAnyScope(auth, tool.requiredScopes))
@@ -1264,12 +1062,6 @@ function jsonRpcError(id: JsonRpcId, code: number, message: string, data?: unkno
   return { jsonrpc: "2.0", id, error: { code, message, ...(data ? { data } : {}) } };
 }
 
-function assertIntegrationTargetAllowed(auth: McpAuthContext, target?: string, channel?: string): void {
-  if (auth.integration && !isIntegrationAllowed(auth.integration, { target, channel })) {
-    throw new McpAuthError("integration token cannot target this message");
-  }
-}
-
 function assertComponentResourceAllowed(
   auth: McpAuthContext,
   check: Parameters<typeof isComponentAuthorizedFor>[1],

package/src/routes/agent-sessions.ts

@@ -10,6 +10,8 @@ import { emitAgentStatus, emitNewMessage } from "../sse";
 import { getAgentProfile, getSpawnPolicy } from "../config-store";
 import { listManagedOrchestratorsForAgent } from "../orchestrator-lookup";
 import { runnerRuntimeTokenEnv } from "../runtime-tokens";
+import { authContextFromRequest } from "../services/auth-context";
+import { ShutdownAuthError, ShutdownTargetError, shutdownAgent } from "../services/shutdown-agent";
 import { type AgentCard, type SpawnApprovalMode } from "../types";
 import { type ProviderEffort } from "agent-relay-sdk/provider-catalog";
 
@@ -207,7 +209,40 @@ export const postAgentAction: Handler = async (req, params) => {
     if (!agent) return error("agent not found", 404);
     if (!agentCanReceiveControlAction(agent, action)) return error(`agent does not support ${action}`, 400);
 
-    const orchestrator = (action === "restart" || action === "shutdown" || action === "resume") ? managedControlOrchestrator(agent) : null;
+    // Shutdown converges on the shutdownAgent service (epic #342, #347): one #221
+    // parent→child gate + canonical orchestrator resolution + payload, shared with the
+    // bus + MCP surfaces. The route still enforces the coarse `agent:write` scope +
+    // constraint-list; the service adds the fine parent→child gate.
+    if (action === "shutdown") {
+      const denied = authorizeRoute(req, {
+        scope: "agent:write",
+        resource: {
+          agentId: agent.id,
+          policyName: typeof agent.meta?.policyName === "string" ? agent.meta.policyName : undefined,
+          spawnRequestId: typeof agent.meta?.spawnRequestId === "string" ? agent.meta.spawnRequestId : undefined,
+        },
+      });
+      if (denied) return denied;
+      try {
+        const result = shutdownAgent(
+          {
+            agentId: agent.id,
+            requestedVia: "http",
+            requestedBy: "dashboard",
+            auditMetadata: { ...authAuditMetadata(req), ...dashboardAttribution(req, parsed.body.surface) },
+          },
+          authContextFromRequest(req),
+        );
+        return json({ ok: true, action, command: result.command }, 202);
+      } catch (e) {
+        if (e instanceof ShutdownAuthError) return error(e.message, 403);
+        if (e instanceof ShutdownTargetError) return error(e.message, 404);
+        throw e;
+      }
+    }
+
+    // "shutdown" is handled above by the shutdownAgent service and returns early.
+    const orchestrator = (action === "restart" || action === "resume") ? managedControlOrchestrator(agent) : null;
     const metaSessionName = typeof agent.meta?.sessionName === "string" ? agent.meta.sessionName : undefined;
     const metaTmuxSession = typeof agent.meta?.tmuxSession === "string" ? agent.meta.tmuxSession : undefined;
     const metaPolicyName = typeof agent.meta?.policyName === "string" ? agent.meta.policyName : undefined;
@@ -240,8 +275,8 @@ export const postAgentAction: Handler = async (req, params) => {
         requestedAt: Date.now(),
       },
     });
-    if (action === "shutdown" || action === "restart" || action === "resume") {
-      const lifecycleAction = action === "shutdown" ? "shutting-down" : action === "resume" ? "resuming" : "restarting";
+    if (action === "restart" || action === "resume") {
+      const lifecycleAction = action === "resume" ? "resuming" : "restarting";
       markReady(agent.id, false);
       mergeAgentMeta(agent.id, { lifecycleAction, lifecycleActionAt: Date.now(), lifecycleCommandId: command.id });
       emitAgentStatus(agent.id);