agent-relay-server 0.36.2 → 0.37.0

package/src/routes/agents-spawn.ts

@@ -1,21 +1,14 @@
 // Auto-split from routes.ts (#299). Domain: agents-spawn.
 import { APPROVAL_MODES, SPAWN_PROVIDERS, VALID_EFFORTS, VALID_WORKSPACE_MODES, isRecord } from "agent-relay-sdk";
-import { McpNotFoundError } from "../mcp-errors";
-import { selectSpawnOrchestrator } from "../spawn-targets";
-import { VALID_AGENT_STATUSES, auditEvent, authAuditMetadata, authorizeRoute, emitCommand, error, json, metaString, parseBody, spawnRequestId, type Handler } from "./_shared";
-import { ValidationError, getAgent, getOrchestrator, listAgents, resolveQueuedPolicyMessages, upsertAgent } from "../db";
-import { buildSpawnCommand, resolveSpawnModelParams, type SpawnModelParams } from "../spawn-command";
+import { McpAuthError, McpNotFoundError } from "../mcp-errors";
+import { VALID_AGENT_STATUSES, error, json, parseBody, type Handler } from "./_shared";
+import { ValidationError, listAgents } from "../db";
 import { cleanMeta, cleanNullableString, cleanString, cleanStringArray, optionalEnum } from "../validation";
-import { createCommand } from "../commands-db";
-import { emitAgentStatus, emitManagedAgentStateChanged, emitMessageAvailable, emitMessageDeliveryUpdated, emitNewMessage } from "../sse";
-import { getAgentProfile, getManagedAgentState, updateManagedAgentState } from "../config-store";
-import { notifyAgentReady } from "../agent-lifecycle-events";
-import { getCompactionWatch } from "../compaction-watch";
-import { getComponentAuth, resolveSpawnLineage } from "../security";
-import { isPathWithinBase } from "../utils";
+import { registerAgent } from "../services/register-agent";
+import { spawnAgent, type SpawnAgentInput } from "../services/spawn-agent";
+import { authContextFromRequest } from "../services/auth-context";
 import { listHostDirectories } from "../agent-spawn";
 import { rankRouteCandidates, type RouteAdvisorInput } from "../context-router";
-import { runnerRuntimeTokenEnv } from "../runtime-tokens";
 import { type AgentKind, type RegisterAgentInput, type SpawnApprovalMode, type SpawnProvider, type WorkspaceMode } from "../types";
 import { type ProviderEffort } from "agent-relay-sdk/provider-catalog";
 
@@ -63,70 +56,12 @@ export const postAgent: Handler = async (req) => {
   const parsed = await parseBody<unknown>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
   try {
+    // Thin transport: parse wire → build AuthContext → call the registerAgent service →
+    // serialize. ALL policy + side effects (lineage, managed came-up-running, status emit,
+    // timeline note, parent-wake, audit) live in src/services/register-agent.ts so the HTTP,
+    // bus, and orchestrator-report paths cannot drift (epic #342).
     const input = normalizeAgentInput(parsed.body);
-    // Lineage is authoritative from the registering token's signed constraints — never the
-    // client-sent body (a child can't forge its own parent). Set by relay at spawn for
-    // agent-initiated spawns (`spawnedBy`) and the delegating-component path (`parentAgents`).
-    const lineage = resolveSpawnLineage(getComponentAuth(req)?.constraints);
-    if (lineage) input.spawnedBy = lineage;
-    const existing = getAgent(input.id);
-    const agent = upsertAgent(input);
-    const policyName = metaString(agent.meta, "policyName");
-    const spawnRequestId = metaString(agent.meta, "spawnRequestId");
-    const tmuxSession = metaString(agent.meta, "tmuxSession");
-    if (policyName && spawnRequestId) {
-      const state = getManagedAgentState(policyName);
-      if (state?.spawnRequestId === spawnRequestId) {
-        const updatedState = updateManagedAgentState(policyName, {
-          status: "running",
-          agentId: agent.id,
-          tmuxSession: tmuxSession ?? state.tmuxSession,
-          healthySince: Date.now(),
-          lastError: undefined,
-        });
-        if (updatedState) emitManagedAgentStateChanged(policyName, updatedState as unknown as Record<string, unknown>);
-        const available = resolveQueuedPolicyMessages(policyName, agent.id);
-        if (available.length) {
-          emitMessageAvailable(policyName, agent.id, available);
-          for (const message of available) {
-            emitNewMessage(message);
-            // queued → pending flips delivery_status; the dashboard dedups message.new
-            // by id (the message already shows as "queued"), so without an explicit
-            // delivery_updated the badge stays stale until the next poll (#265).
-            emitMessageDeliveryUpdated(message);
-          }
-        }
-      }
-    }
-    emitAgentStatus(agent.id);
-    // #308 — a spawned child registering already-ready (the common isolated-worktree case: it
-    // comes up ready+idle) is genuinely ready; wake its parent so it can stop block-polling.
-    // Fire on the first-ever ready (no prior record, or prior record wasn't ready yet) — the
-    // ready/false→true flip path is handled in patchAgentReady. notifyAgentReady no-ops for
-    // non-spawned agents and dedups repeats.
-    if (agent.ready && !existing?.ready) notifyAgentReady(agent.id);
-    // A real PreCompact / SessionStart(clear) hook reports progress via the
-    // agent's timelineEvent — clears any pending stall watch for this agent.
-    // timelineEvent is latched, so pass its timestamp: only a fresh event
-    // (stamped after the watch armed) counts as this command's real start.
-    const timelineEvent = isRecord(agent.meta?.timelineEvent) ? agent.meta.timelineEvent : undefined;
-    const timelineStatus = metaString(timelineEvent, "status");
-    if (timelineStatus) {
-      const timelineTs = typeof timelineEvent?.timestamp === "number" ? timelineEvent.timestamp : undefined;
-      getCompactionWatch().noteTimelineStatus(agent.id, timelineStatus, timelineTs);
-    }
-    if (!existing) {
-      auditEvent({
-        clientId: "server-agent-" + agent.id + "-registered",
-        kind: "state",
-        title: "Agent registered",
-        body: agent.name,
-        meta: agent.id,
-        icon: "ti-robot",
-        view: "agents",
-        agentId: agent.id,
-      });
-    }
+    const agent = registerAgent(input, authContextFromRequest(req));
     return json(agent, 201);
   } catch (e) {
     if (e instanceof ValidationError) return error(e.message, 400);
@@ -162,83 +97,39 @@ export const postAgentSpawn: Handler = async (req) => {
     if (!isRecord(parsed.body)) return error("provider required");
     const provider = optionalEnum(parsed.body.provider, "provider", SPAWN_PROVIDERS) as SpawnProvider | undefined;
     if (!provider) return error("provider required");
-    const orchestratorId = cleanString(parsed.body.orchestratorId, "orchestratorId", { max: 200 });
-    const cwd = cleanString(parsed.body.cwd, "cwd", { max: 500 });
-    // Resolves an explicit host, else the host whose baseDir contains cwd, else the lone candidate
-    // (the same resolver the MCP spawn tool uses — one home for host selection).
-    const orch = selectSpawnOrchestrator(provider, orchestratorId, cwd);
-    if (cwd && !isPathWithinBase(cwd, orch.baseDir)) {
-      return error(`cwd must be within orchestrator base directory: ${orch.baseDir}`);
-    }
-    const selection = validateSpawnSelectionForOrchestrator(orch, provider, parsed.body);
-    if (selection instanceof Response) return selection;
-    const approvalMode = optionalEnum(parsed.body.approvalMode, "approvalMode", APPROVAL_MODES, "guarded") as SpawnApprovalMode;
-    const label = cleanString(parsed.body.label, "label", { max: 120 });
-    const workspaceMode = optionalEnum(parsed.body.workspaceMode, "workspaceMode", VALID_WORKSPACE_MODES, "inherit") as WorkspaceMode;
-    const profile = cleanString(parsed.body.profile, "profile", { max: 120 });
-    const prompt = cleanString(parsed.body.prompt, "prompt", { max: 16000 });
-    const systemPromptAppend = cleanString(parsed.body.systemPromptAppend, "systemPromptAppend", { max: 64_000 });
-    const tags = cleanStringArray(parsed.body.tags, "tags", { itemMax: 80, maxItems: 50 }) ?? [];
-    const capabilities = cleanStringArray(parsed.body.capabilities, "capabilities", { itemMax: 80, maxItems: 50 }) ?? [];
-    const providerArgs = cleanStringArray(parsed.body.providerArgs, "providerArgs", { itemMax: 80, maxItems: 50 }) ?? [];
-    const agentProfile = profile ? getAgentProfile(profile)?.value : undefined;
-    if (profile && !agentProfile) return error("agent profile not found", 404);
-    const policyName = cleanString(parsed.body.policyName, "policyName", { max: 120 });
-    const requestId = cleanString(parsed.body.spawnRequestId, "spawnRequestId", { max: 160 }) ?? spawnRequestId();
-    const denied = authorizeRoute(req, {
-      scope: "agent:write",
-      resource: { orchestratorId: orch.id, cwd: cwd || orch.baseDir, policyName, spawnRequestId: requestId },
-    });
-    if (denied) return denied;
-    const command = createCommand({
-      type: "agent.spawn",
-      source: "system",
-      target: orch.agentId,
-      correlationId: requestId,
-      params: buildSpawnCommand({
-        provider,
-        modelParams: selection,
-        cwd: cwd || orch.baseDir,
-        workspaceMode,
-        label,
-        tags,
-        capabilities,
-        approvalMode,
-        permissionMode: approvalMode,
-        profile: profile || undefined,
-        agentProfile,
-        providerArgs,
-        prompt,
-        systemPromptAppend,
-        policyName,
-        spawnRequestId: requestId,
-        env: runnerRuntimeTokenEnv({
-          orchestratorId: orch.id,
-          cwd: cwd || orch.baseDir,
-          provider,
-          label,
-          policyName,
-          spawnRequestId: requestId,
-          createdBy: "dashboard",
-          profile: profile || undefined,
-        }),
-        requestedBy: "dashboard",
-        requestedAt: Date.now(),
-      }),
-    });
-    emitCommand(command);
-    auditEvent({
-      clientId: "server-agent-spawn-" + provider + "-" + command.id,
-      kind: "state",
-      title: `${provider} agent spawn requested (via ${orch.id})`,
-      body: cwd || orch.baseDir,
-      meta: orch.id,
-      icon: "ti-plus",
-      view: "agents",
-      metadata: { provider, orchestratorId: orch.id, approvalMode, workspaceMode, label, commandId: command.id, ...authAuditMetadata(req) },
-    });
-    return json({ ok: true, orchestratorId: orch.id, provider, command }, 202);
+    // Thin transport: parse wire → AuthContext → spawnAgent service → serialize. The gate
+    // (command:spawn scope, #221 no-grandchild + quota, #323 resource), caller-context
+    // inheritance (#328/#331/#324), profile validation, lineage stamping, host selection, and
+    // the command payload all live in src/services/spawn-agent.ts so HTTP and MCP cannot drift
+    // (epic #342, #349). The dashboard authenticates with an admin `*` token, so the tightened
+    // command:spawn requirement is transparent to it.
+    const input: SpawnAgentInput = {
+      provider,
+      orchestratorId: cleanString(parsed.body.orchestratorId, "orchestratorId", { max: 200 }),
+      cwd: cleanString(parsed.body.cwd, "cwd", { max: 500 }),
+      model: cleanString(parsed.body.model, "model", { max: 120 }),
+      effort: optionalEnum(parsed.body.effort, "effort", VALID_EFFORTS) as ProviderEffort | undefined,
+      approvalMode: optionalEnum(parsed.body.approvalMode, "approvalMode", APPROVAL_MODES) as SpawnApprovalMode | undefined,
+      workspaceMode: optionalEnum(parsed.body.workspaceMode, "workspaceMode", VALID_WORKSPACE_MODES) as WorkspaceMode | undefined,
+      label: cleanString(parsed.body.label, "label", { max: 120 }),
+      policyName: cleanString(parsed.body.policyName, "policyName", { max: 120 }),
+      profile: cleanString(parsed.body.profile, "profile", { max: 120 }),
+      prompt: cleanString(parsed.body.prompt, "prompt", { max: 16000 }),
+      systemPromptAppend: cleanString(parsed.body.systemPromptAppend, "systemPromptAppend", { max: 64_000 }),
+      tags: cleanStringArray(parsed.body.tags, "tags", { itemMax: 80, maxItems: 50 }),
+      capabilities: cleanStringArray(parsed.body.capabilities, "capabilities", { itemMax: 80, maxItems: 50 }),
+      providerArgs: cleanStringArray(parsed.body.providerArgs, "providerArgs", { itemMax: 80, maxItems: 50 }),
+      spawnRequestId: cleanString(parsed.body.spawnRequestId, "spawnRequestId", { max: 160 }),
+      requestedVia: "dashboard",
+      requestedBy: "dashboard",
+      // HTTP is fire-and-forget (202): the dashboard polls registration separately via the
+      // returned spawnRequestId.
+      waitForRegistrationMs: 0,
+    };
+    const result = await spawnAgent(input, authContextFromRequest(req));
+    return json({ ok: true, orchestratorId: result.orchestratorId, provider: result.provider, command: result.command }, 202);
   } catch (e) {
+    if (e instanceof McpAuthError) return error(e.message, 403);
     if (e instanceof McpNotFoundError) return error(e.message, 404);
     if (e instanceof ValidationError) return error(e.message, 400);
     if (e instanceof Error) return error(e.message, 400);
@@ -257,25 +148,3 @@ export const getHostDirectories: Handler = (req) => {
     throw e;
   }
 };
-
-function cleanSpawnSelection(body: Record<string, unknown>, provider: SpawnProvider): SpawnModelParams {
-  const model = cleanString(body.model, "model", { max: 120 });
-  const effort = optionalEnum(body.effort, "effort", VALID_EFFORTS) as ProviderEffort | undefined;
-  return resolveSpawnModelParams(provider, model, effort);
-}
-
-function validateSpawnSelectionForOrchestrator(
-  orch: NonNullable<ReturnType<typeof getOrchestrator>>,
-  provider: SpawnProvider,
-  body: Record<string, unknown>,
-): SpawnModelParams | Response {
-  if (!orch.providers.includes(provider)) {
-    return error(`orchestrator does not have provider available: ${provider}`, 409);
-  }
-  try {
-    return cleanSpawnSelection(body, provider);
-  } catch (e) {
-    if (e instanceof Error) return error(e.message, 400);
-    throw e;
-  }
-}

package/src/routes/commands.ts

@@ -5,11 +5,13 @@ import { ValidationError, deleteWorkspace, getOrchestrator, getWorkspace, patchW
 import { applyCommandToRecipe } from "../recipe-runner";
 import { claimMetadataPatch } from "../workspace-claim";
 import { clearActiveMemories, injectAlwaysReloadMemories } from "../memory-service";
-import { createCommand, getCommand, listCommands, updateCommand } from "../commands-db";
+import { getCommand, listCommands, updateCommand } from "../commands-db";
 import { emitOrchestratorStatus } from "../sse";
 import { getCompactionWatch } from "../compaction-watch";
 import { isRecord } from "agent-relay-sdk";
-import { isRequestAuthorizedFor } from "../security";
+import { authContextFromRequest } from "../services/auth-context";
+import { commandAuthorizationResource as dispatchCommandAuthorizationResource, dispatchCommand } from "../services/dispatch-command";
+import { ServiceAuthError } from "../services/errors";
 import { notifyBranchLanded } from "../branch-landed";
 import { notifyAgentSpawnFailed } from "../agent-lifecycle-events";
 import { type Command, type CommandStatus, type CreateCommandInput, type WorkspaceStatus } from "../types";
@@ -102,30 +104,16 @@ function normalizeCommandInput(body: unknown): CreateCommandInput {
   return { type, source, target, params, correlationId, ttlMs };
 }
 
-function commandAuthorizationResource(input: Pick<CreateCommandInput, "target" | "params">): Parameters<typeof isRequestAuthorizedFor>[1]["resource"] {
-  const params = isRecord(input.params) ? input.params : {};
-  return {
-    target: input.target,
-    agentId: cleanString(params.agentId, "params.agentId", { max: 240 }) ?? input.target,
-    policyName: cleanString(params.policyName, "params.policyName", { max: 120 }),
-    orchestratorId: cleanString(params.orchestratorId, "params.orchestratorId", { max: 120 }),
-    cwd: cleanString(params.cwd, "params.cwd", { max: 500 }),
-    spawnRequestId: cleanString(params.spawnRequestId, "params.spawnRequestId", { max: 160 }),
-  };
-}
-
 export const postCommand: Handler = async (req) => {
   const parsed = await parseBody<unknown>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
   try {
     const input = normalizeCommandInput(parsed.body);
-    const denied = authorizeRoute(req, { scope: "command:write", resource: commandAuthorizationResource(input) });
-    if (denied) return denied;
-    const command = createCommand(input);
-    emitCommand(command);
+    const command = dispatchCommand(input, authContextFromRequest(req));
     return json(command, 201);
   } catch (e) {
     if (e instanceof ValidationError) return error(e.message, 400);
+    if (e instanceof ServiceAuthError) return error("forbidden", 403);
     throw e;
   }
 };
@@ -161,7 +149,7 @@ export const patchCommand: Handler = async (req, params) => {
   try {
     const current = getCommand(params.id!);
     if (!current) return error("command not found", 404);
-    const denied = authorizeRoute(req, { scope: "command:write", resource: commandAuthorizationResource(current) });
+    const denied = authorizeRoute(req, { scope: "command:write", resource: dispatchCommandAuthorizationResource(current) });
     if (denied) return denied;
     const status = optionalEnum(parsed.body.status, "status", VALID_COMMAND_STATUSES);
     const result = cleanParams(parsed.body.result, "result");

package/src/routes/messages.ts

@@ -1,13 +1,14 @@
 // Auto-split from routes.ts (#299). Domain: messages.
 import { MAX_BODY_BYTES } from "../config";
-import { ValidationError, applyMessageDeliveryAction, claimMessage, deleteMessage, getAgent, getLatestMessageId, getMessage, getMessageDeliveryStatus, getThread, listAgents, listQueuedMessages, listRecentMessages, markRead, pollMessages, recordMessageDeliveryAttempt, renewMessageClaim, sendMessage, sendMessageWithResult, setMessageReaction } from "../db";
-import { auditEvent, authorizeRoute, cleanAttachmentRefs, dispatchTaskCallbacks, emitCommand, error, json, memoryContext, normalizeAgentSessionGuard, parseBody, parseId, parseQueryInt, reactionEmoji, sendReactionNotificationToAuthor, withPayloadAttachments, type Handler } from "./_shared";
+import { ValidationError, applyMessageDeliveryAction, claimMessage, deleteMessage, getAgent, getLatestMessageId, getMessage, getMessageDeliveryStatus, getThread, listQueuedMessages, listRecentMessages, markRead, pollMessages, recordMessageDeliveryAttempt, renewMessageClaim, sendMessage, sendMessageWithResult, setMessageReaction } from "../db";
+import { auditEvent, cleanAttachmentRefs, dispatchTaskCallbacks, emitCommand, error, json, memoryContext, normalizeAgentSessionGuard, parseBody, parseId, parseQueryInt, reactionEmoji, sendReactionNotificationToAuthor, withPayloadAttachments, type Handler } from "./_shared";
 import { cleanMeta, cleanPositiveId, cleanString, optionalEnum } from "../validation";
 import { emitMessageClaimed, emitMessageDeleted, emitMessageDeliveryUpdated, emitMessageQueued, emitMessageReactionUpdated, emitNewMessage, emitTaskChanged } from "../sse";
-import { errMessage, isMechanicalMessageKind, isRecord, isReservedAgentId } from "agent-relay-sdk";
-import { getLifecycleManager } from "../lifecycle-manager";
+import { errMessage, isMechanicalMessageKind, isRecord } from "agent-relay-sdk";
 import { injectMemoryForMessageDelivery } from "../memory-service";
-import { planSend } from "../agent-ref";
+import { authContextFromRequest } from "../services/auth-context";
+import { sendMessageService } from "../services/send-message";
+import { AmbiguousTargetError, ServiceAuthError } from "../services/errors";
 import { type AgentSessionGuard, type Message, type SendMessageInput } from "../types";
 
 const VALID_DELIVERY_STATUSES = ["pending", "delivered", "queued", "failed", "dead"] as const;
@@ -71,27 +72,6 @@ function isDirectTarget(to: string): boolean {
   return to !== "broadcast" && !FANOUT_PREFIXES.some((p) => to.startsWith(p));
 }
 
-function applyReplyRouting(input: SendMessageInput): void {
-  if (input.to || !input.replyTo) return;
-  const parent = getMessage(input.replyTo);
-  if (!parent) return;
-  input.to = parent.from;
-  if (!input.channel && parent.channel) input.channel = parent.channel;
-  const parentPayload = parent.payload ?? {};
-  if (parentPayload.schema === "agent-relay.channel.v1" || parentPayload.conversation) {
-    const replyContext: Record<string, unknown> = {};
-    if (parent.channel) replyContext.channelId = parent.channel;
-    if (parentPayload.conversation && typeof parentPayload.conversation === "object") {
-      replyContext.conversationId = (parentPayload.conversation as Record<string, unknown>).id;
-    }
-    if (parentPayload.event && typeof parentPayload.event === "object") {
-      replyContext.parentEventId = (parentPayload.event as Record<string, unknown>).id;
-    }
-    if (parentPayload.source) replyContext.source = parentPayload.source;
-    input.payload = { ...input.payload, replyContext };
-  }
-}
-
 const VALID_MSG_KINDS = ["chat", "channel.event", "task", "pair", "control", "system", "session"];
 
 export const getQueuedMessagesRoute: Handler = (req) => {
@@ -173,83 +153,40 @@ export const postMessage: Handler = async (req) => {
     if (!input.idempotencyKey) {
       input.idempotencyKey = cleanString(req.headers.get("Idempotency-Key") ?? undefined, "idempotencyKey", { max: 240 });
     }
-    applyReplyRouting(input);
-    if (!input.to) return error("to is required (or provide replyTo to auto-route)");
-    // Mechanical lifecycle/observability posts (system/control/session) addressed to a
-    // reserved sink ("user"/"system") are the relay's own lane, not agent-directed
-    // messaging. A managed token's recipient constraints (targets/policies/agents) gate
-    // which *agents* it may message — they must NOT gate a session-mirror capture to the
-    // reserved sink, or constrained tokens (telegram policy, codex steward) 403 → the
-    // runner's outbox retries 12× and poisons the record → the dashboard silently loses
-    // the turn (#284, same outbox-poison failure mode as #184). The message:send scope
-    // and any channel constraint still apply; we only drop the target/agentId predicate.
-    const reservedSinkPost = isMechanicalMessageKind(input.kind) && isReservedAgentId(input.to);
-    const denied = authorizeRoute(req, {
-      scope: "message:send",
-      resource: reservedSinkPost
-        ? { channel: input.channel }
-        : { target: input.to, channel: input.channel, agentId: input.from },
-    });
-    if (denied) return denied;
-    // Resolve the target through the shared planner — the SAME matcher the MCP send tool
-    // uses (planSend → matchAgents) — so a bare label / name / id-segment that matches an
-    // existing agent is rewritten to its canonical id. Poll-time matching is exact, so
-    // without this a bare label is stored verbatim and reaches no one (#234). An ambiguous
-    // direct ref can't be delivered, so reject it up front. Unknown targets are left
-    // untouched on purpose: sending to an id that isn't registered yet is a supported
-    // "store-ahead" pattern (delivered once that agent registers and polls). Fan-out and
-    // reserved/policy targets carry through unchanged (and may legitimately match zero now).
-    //
-    // "session" = observed assistant turn (Phase 1 live-session lane). It is captured
-    // from the provider transcript and stored for the dashboard chat; it must persist
-    // regardless of target liveness and never be re-delivered into a session.
-    if (!isMechanicalMessageKind(input.kind)) {
-      // excludeId: a bare ref must never resolve back to its own author — that self-loop
-      // silently swallows the message (the reddit-briefing → telegram bridge break, #290).
-      const plan = planSend(input.to, listAgents(), { excludeId: input.from });
-      if (plan.kind === "ambiguous") return error(plan.message, 409);
-      if (plan.kind !== "not_found") input.to = plan.to;
-      // Long-standing guard: refuse a direct send to a known-offline agent (now also
-      // catches a ref that resolved to an offline agent by label/segment).
-      const target = getAgent(input.to);
-      if (target && target.status === "offline") {
-        return error(`agent "${input.to}" is offline`, 422);
-      }
-    }
-    const result = sendMessageWithResult(input);
-    if (result.created) {
-      const autoMemoryTarget = automaticMemoryTarget(result.message);
+    // The shared send service owns reply-routing, target resolution + the converged store-ahead
+    // policy, authorization (incl. the reserved-sink mechanical exemption), persistence, and the
+    // emit + on-demand-policy-wake — identical across HTTP / MCP (epic #342, src/services/send-message.ts).
+    const { message, created } = sendMessageService(input, authContextFromRequest(req));
+    if (created) {
+      // Transport-edge enrichment (NOT part of the cross-transport send core): automatic memory
+      // injection needs request-derived context; the "message sent" audit is the HTTP domain row.
+      const autoMemoryTarget = automaticMemoryTarget(message);
       if (autoMemoryTarget) {
         try {
-          const memoryInjection = await injectMemoryForMessageDelivery(result.message, autoMemoryTarget, memoryContext(req));
+          const memoryInjection = await injectMemoryForMessageDelivery(message, autoMemoryTarget, memoryContext(req));
           if (memoryInjection) emitCommand(memoryInjection.command);
         } catch (e) {
           console.warn(`[memory] automatic message context assembly failed: ${errMessage(e)}`);
         }
       }
-      if (result.message.deliveryStatus === "queued") {
-        emitMessageQueued(result.message);
-        // Wake an on-demand managed policy that has no live agent attached yet.
-        if (result.message.to?.startsWith("policy:")) {
-          getLifecycleManager().onMessageForPolicy(result.message.to.slice("policy:".length));
-        }
-      } else emitNewMessage(result.message);
-      const isWork = result.message.kind === "task";
+      const isWork = message.kind === "task";
       auditEvent({
-        clientId: "server-message-" + result.message.id,
+        clientId: "server-message-" + message.id,
         kind: isWork ? "task" : "message",
         title: isWork ? "Task message sent" : "Message sent",
-        body: result.message.subject || result.message.body,
-        meta: `${result.message.from} -> ${result.message.to}`,
+        body: message.subject || message.body,
+        meta: `${message.from} -> ${message.to}`,
         icon: isWork ? "ti-hand-grab" : "ti-send",
         view: "messages",
-        messageId: result.message.id,
-        agentId: result.message.from,
+        messageId: message.id,
+        agentId: message.from,
       });
     }
-    return json(result.message, result.created ? 201 : 200);
+    return json(message, created ? 201 : 200);
   } catch (e) {
     if (e instanceof ValidationError) return error(e.message, 400);
+    if (e instanceof AmbiguousTargetError) return error(e.message, 409);
+    if (e instanceof ServiceAuthError) return error("forbidden", 403);
     throw e;
   }
 };

package/src/security.ts

@@ -185,6 +185,11 @@ export function requiredScopeFor(method: string, pathname: string): string | nul
   if (pathname.startsWith("/api/channels") || pathname.startsWith("/api/channel-bindings")) return method === "GET" ? "channel:read" : "channel:write";
   if (pathname === "/api/integrations" || pathname.startsWith("/api/integrations/")) return method === "GET" ? "integration:read" : "integration:write";
   if (pathname.startsWith("/api/automations") || pathname.startsWith("/api/automation-runs")) return method === "GET" ? "automations:read" : "automations:write";
+  // Spawning a worker requires the spawn capability, not generic agent-write — the in-service
+  // gate (src/services/spawn-agent.ts) enforces the full quota/no-grandchild rules; this coarse
+  // route gate just matches it so an `agent:write`-but-not-`command:spawn` token can't reach it
+  // (the MCP spawn tool already required command:spawn — epic #342, #349).
+  if (pathname === "/api/agents/spawn") return "command:spawn";
   if (pathname.startsWith("/api/agents")) return method === "GET" ? "agent:read" : "agent:write";
   if (pathname.startsWith("/api/activity")) return method === "GET" ? "activity:read" : "activity:write";
   if (pathname.startsWith("/api/inbox")) return method === "GET" ? "message:read" : "message:send";
@@ -264,6 +269,8 @@ export function requiredComponentScopeFor(method: string, pathname: string): str
     return "memory:write";
   }
   if (pathname === "/api/integrations" || pathname.startsWith("/api/integrations/")) return method === "GET" ? "integration:read" : "integration:write";
+  // Spawn requires the spawn capability (see requiredScopeFor above) — matches the in-service gate.
+  if (pathname === "/api/agents/spawn") return "command:spawn";
   if (pathname.startsWith("/api/agents")) return method === "GET" ? "agent:read" : "agent:write";
   if (pathname.startsWith("/api/messages") || pathname.startsWith("/api/inbox")) return method === "GET" ? "message:read" : "message:send";
   if (pathname.startsWith("/api/agent-profiles")) return method === "GET" ? "agent:read" : "agent:write";

package/src/services/auth-context.ts

@@ -0,0 +1,109 @@
+// Transport convergence (epic #342) — unified auth shape.
+//
+// Every transport (HTTP routes, WS bus, MCP, internal projections) builds ONE
+// `AuthContext` and hands it to the domain services in `src/services/`. Services
+// never see a transport-specific Request / WebSocket / frame — they read identity,
+// scopes, and signed constraints from this single shape. This kills the
+// "I forgot this path also needs the constraint" class of bug (e.g. the v0.36.2
+// `spawned_by`-NULL drift: lineage lived in the HTTP path's token read but not the
+// bus path's). Lineage now resolves uniformly from `ctx.constraints`.
+import type { AgentCard, ComponentToken, TokenConstraints } from "../types";
+import { getComponentAuth, isAuthorized } from "../security";
+import { resolveCallerAgentId } from "../agent-ref";
+import { listAgents } from "../db";
+
+export interface AuthContext {
+  /** The authenticated principal. `system` is an internal, fully-trusted caller
+   * (lifecycle tick, orchestrator-report projection) with no token. */
+  actor: { id: string; kind: "component" | "agent" | "system" | "user" | "integration" };
+  /** Capability scopes the principal holds (e.g. "agent:write", "command:spawn").
+   * Empty for `system` (internal callers bypass scope checks). Consumed by the
+   * shutdown/spawn slices; registration only needs `constraints`. */
+  scopes: string[];
+  /** Signed token constraints — the AUTHORITATIVE source for spawn lineage
+   * (`resolveSpawnLineage(ctx.constraints)`), cwd prefixes, spawn-request ids, etc.
+   * A client can never forge these; they are baked into the token at issue time. */
+  constraints?: TokenConstraints;
+  /** The resolved CALLER AGENT ID behind this token — the agent the principal *is*,
+   * NOT `actor.id` (the token `sub`). Resolved from the signed constraints via
+   * `resolveCallerAgentId` (single `agents` id, else a single spawnRequestId/policy matched
+   * to a live agent — the #243 identity family). undefined for admin/server tokens (full
+   * reach) and multi-agent tokens. THE basis for the parent→child shutdown gate and the
+   * no-grandchild spawn gate (#221) — consumed by the shutdown/spawn/send services. */
+  callerAgentId?: string;
+  /** The raw component token when the principal authenticated with one. Escape
+   * hatch for code still calling `isComponentAuthorizedFor` directly during the
+   * transport-convergence migration; new service code should prefer `scopes`/`constraints`. */
+  component?: ComponentToken;
+}
+
+function agentsSnapshot(): AgentCard[] {
+  return listAgents();
+}
+
+function fromComponent(component: ComponentToken | null | undefined): AuthContext {
+  if (!component) return { actor: { id: "anonymous", kind: "user" }, scopes: [] };
+  return {
+    actor: { id: component.sub, kind: "component" },
+    scopes: component.scope ?? [],
+    constraints: component.constraints,
+    // Lazy: resolveCallerAgentId only scans live agents when a single spawnRequestId/policy
+    // must be matched; identity-bearing (`agents`) and admin tokens pay no db cost here.
+    callerAgentId: resolveCallerAgentId(component.constraints, agentsSnapshot),
+    component,
+  };
+}
+
+/** True if the request carries any credential (so the in-handler gate should scope it, rather
+ * than trust the pipeline). Mirrors the routes layer's `hasPresentedCredential`. */
+function hasPresentedCredential(req: Request): boolean {
+  return Boolean(
+    req.headers.get("authorization") ||
+    req.headers.get("x-agent-relay-token") ||
+    new URL(req.url).searchParams.get("token"),
+  );
+}
+
+/** HTTP transport adapter: build an AuthContext from a request's auth.
+ * - A component token maps to its identity / scopes / signed constraints (the scoped path).
+ * - Everything else — the admin token (dashboard), an allow-unauth dev request, OR a
+ *   credential-less request that the auth PIPELINE already authenticated before dispatch —
+ *   maps to a full-reach system principal (`*` scope), mirroring authContextFromMcp's `server`
+ *   branch AND the routes-layer `authorizeRoute` (which no-ops when no credential is presented).
+ *   This keeps scope-gating services (spawn/shutdown) from re-rejecting a caller the request-level
+ *   authz already allowed. In production a truly unauthenticated request is stopped at the pipeline,
+ *   so the credential-less branch only covers in-process callers that bypass it. */
+export function authContextFromRequest(req: Request): AuthContext {
+  const component = getComponentAuth(req);
+  if (component) return fromComponent(component);
+  if (isAuthorized(req) || !hasPresentedCredential(req)) return { actor: { id: "system", kind: "system" }, scopes: ["*"] };
+  return fromComponent(null);
+}
+
+/** WS-bus transport adapter: build an AuthContext from a socket's component token. */
+export function authContextFromBus(component: ComponentToken | null | undefined): AuthContext {
+  return fromComponent(component);
+}
+
+/** Internal-caller adapter: a fully-trusted system principal with no token
+ * (lifecycle-manager tick, orchestrator-report projection). No lineage — these
+ * callers act on already-registered agents and never set authoritative parentage. */
+export function authContextFromSystem(): AuthContext {
+  return { actor: { id: "system", kind: "system" }, scopes: [] };
+}
+
+/** MCP transport adapter. Typed structurally (not against mcp.ts's `McpAuthContext`) so
+ * services stay below the transport layer. `server` = an internal/admin caller with no token
+ * (full reach, `*` scope); `integration` = an integration token (no caller-agent identity);
+ * `component` reuses the same component path as HTTP/bus, so the caller-agent + lineage
+ * resolution is identical across every transport. */
+export function authContextFromMcp(auth: {
+  kind: "component" | "integration" | "server";
+  actor: string;
+  scopes?: string[];
+  component?: ComponentToken;
+}): AuthContext {
+  if (auth.kind === "component") return fromComponent(auth.component);
+  if (auth.kind === "server") return { actor: { id: auth.actor, kind: "system" }, scopes: auth.scopes ?? ["*"] };
+  return { actor: { id: auth.actor, kind: "integration" }, scopes: auth.scopes ?? [] };
+}