agent-relay-server 0.17.0 → 0.19.0

package/src/maintenance.ts

@@ -33,6 +33,8 @@ import {
 } from "./db";
 import type { WorkspaceMergePreview, WorkspaceRecord, WorkspaceStatus } from "./types";
 import { requestWorkspaceMerge } from "./workspace-merge";
+import { workspaceActiveClaim } from "./workspace-claim";
+import { errMessage, RELAY_TOKEN_HEADER } from "agent-relay-sdk";
 import { getStewardConfig } from "./config-store";
 import { ensureRepoSteward } from "./steward";
 import { emitRelayEvent } from "./events";
@@ -392,7 +394,7 @@ const definitions: MaintenanceJobDefinition[] = [
   {
     id: "workspace-auto-merge",
     title: "Workspace auto-merge",
-    description: "Auto-merge clean fast-forward review_requested worktrees into base under the per-repo lease; conflicts and diverged bases are left for the steward.",
+    description: "Auto-merge any non-conflicting review_requested worktree into base under the per-repo lease (rebasing when the base moved on); only real or unknown conflicts are left for the steward.",
     intervalMs: WORKSPACE_AUTO_MERGE_INTERVAL_MS,
     runOnStart: false,
     timeoutMs: 60 * 1000,
@@ -421,7 +423,7 @@ async function fetchHostMergePreview(apiUrl: string, workspace: WorkspaceRecord)
   if (workspace.baseSha) query.set("baseSha", workspace.baseSha);
   const headers: Record<string, string> = {};
   const token = process.env.AGENT_RELAY_TOKEN;
-  if (token) headers["X-Agent-Relay-Token"] = token;
+  if (token) headers[RELAY_TOKEN_HEADER] = token;
   try {
     const res = await fetch(`${apiUrl}/api/workspace/merge-preview?${query.toString()}`, { headers, signal: AbortSignal.timeout(8_000) });
     if (!res.ok) return null;
@@ -535,7 +537,7 @@ function wakeRepoSteward(ws: WorkspaceRecord, reason: string): string | null {
       to: `policy:${policyName}`,
       kind: "system",
       subject: `Steward: ${ws.status} workspace needs attention`,
-      body: `Workspace \`${ws.branch ?? ws.id}\` in ${ws.repoRoot} is ${ws.status} and could not auto-land (${reason}). cd into ${ws.worktreePath}, rebase onto ${ws.baseRef ?? "base"}, resolve, run checks, then land it via POST /api/workspaces/${ws.id}/actions {"action":"merge","strategy":"rebase-ff"} — or escalate if you can't.`,
+      body: `Workspace \`${ws.branch ?? ws.id}\` (id ${ws.id}) in ${ws.repoRoot} is ${ws.status} and could not auto-land (${reason}). Claim it first so auto-merge yields: \`agent-relay workspace claim --id ${ws.id} --purpose steward\`. Inspect: \`agent-relay steward inspect ${ws.id}\`. Then cd into ${ws.worktreePath}, rebase onto ${ws.baseRef ?? "base"}, resolve, run checks, and land: \`agent-relay workspace land --id ${ws.id} --strategy rebase-ff\` — or \`agent-relay workspace release --id ${ws.id}\` and escalate if you can't.`,
       payload: { kind: "workspace.steward-task", workspaceId: ws.id, repoRoot: ws.repoRoot, worktreePath: ws.worktreePath, branch: ws.branch, baseRef: ws.baseRef, status: ws.status, reason },
     });
     emitNewMessage(msg);
@@ -655,14 +657,12 @@ async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
   return { scanned: candidates.length, flagged, cleared, merged, notifiedStewards };
 }
 
-// Deterministic auto-land (Layer 0, issue #167). Walk the "ready to land" queue
-// (`review_requested` isolated worktrees) and, for any whose work is a strict
-// clean fast-forward (no conflict, base hasn't moved, real commits ahead), land
-// it via the shared merge helper — the same lease-serialized path the merge route
-// uses. Conflicts and diverged bases (`behind>0`, even if cleanly rebasable) are
-// deliberately left for the steward (a human or, later, the managed steward
-// agent): per the chosen "Clean FF immediate" gate, anything needing a rebase or
-// conflict reasoning is not auto-landed. No agent in the loop for the easy case.
+// Deterministic auto-land (Layer 0, issue #167 / #207). Walk the "ready to land"
+// queue (`review_requested` isolated worktrees) and land any whose merge is
+// predicted conflict-free, via the shared lease-serialized merge helper — even
+// when the base moved on (behind>0): mergeRebaseFf rebases onto the current base
+// before fast-forwarding. Only a predicted conflict or an unknown merge state is
+// left for the steward; clean parallel work lands with no agent in the loop.
 async function autoMergeCleanFastForwards(): Promise<Record<string, unknown>> {
   if (process.env.AGENT_RELAY_WORKSPACE_AUTO_MERGE === "0") return { skipped: "disabled" };
   const orchestrators = listOrchestrators().filter((orch) => orch.status === "online" && orch.apiUrl);
@@ -674,10 +674,13 @@ async function autoMergeCleanFastForwards(): Promise<Record<string, unknown>> {
   const stewardEnabled = getStewardConfig().enabled;
   const merged: string[] = [];
   const heldByLease: string[] = [];
+  const heldByClaim: string[] = [];
   const leftForSteward: string[] = [];
   const wokeStewards: string[] = [];
 
   for (const ws of candidates) {
+    // A claimed workspace is being validated by a steward — don't race it (#208).
+    if (workspaceActiveClaim(ws)) { heldByClaim.push(ws.id); continue; }
     const orch = orchestrators.find((candidate) => workspacePathWithinBase(ws.sourceCwd, candidate.baseDir));
     if (!orch?.apiUrl) continue;
     const preview = await fetchHostMergePreview(orch.apiUrl, ws);
@@ -686,14 +689,17 @@ async function autoMergeCleanFastForwards(): Promise<Record<string, unknown>> {
     if (p.error || p.missing) continue;
 
     const ahead = p.unmergedAhead ?? p.ahead ?? 0;
-    const cleanFF = p.cleanFastForward === true && p.conflict !== true && (p.behind ?? 0) === 0 && ahead > 0;
-    if (!cleanFF) {
-      // Base moved on (behind>0) or conflict — needs reasoning/rebase, which is the
-      // steward's job. Wake the managed steward when enabled (cooldown-guarded);
-      // otherwise leave it for conflict-scan's legacy ping / human review.
+    const behind = p.behind ?? 0;
+    // Land anything that won't conflict — including a base that moved on (behind>0)
+    // but rebases cleanly. The merge-tree prediction already accounts for the moved
+    // base, and mergeRebaseFf rebases then aborts-to-conflict on a real replay
+    // conflict, so a too-optimistic prediction degrades safely to review_requested.
+    // Only a predicted conflict (true) or unknown state (undefined) goes to the steward.
+    const canLand = p.conflict === false && ahead > 0;
+    if (!canLand) {
       leftForSteward.push(ws.id);
       if (stewardEnabled) {
-        const woke = wakeRepoSteward(ws, (p.behind ?? 0) > 0 ? "base moved on (behind>0)" : "conflict");
+        const woke = wakeRepoSteward(ws, p.conflict === true ? "conflict" : "merge state unknown");
         if (woke) wokeStewards.push(woke);
       }
       continue;
@@ -710,8 +716,8 @@ async function autoMergeCleanFastForwards(): Promise<Record<string, unknown>> {
     createActivityEvent({
       clientId: `workspace-auto-merge-${ws.id}-${Date.now()}`,
       kind: "state",
-      title: "Workspace auto-merging (clean fast-forward)",
-      body: `${ws.branch ?? ws.id} → ${p.baseRef ?? "base"} (${ahead} ahead, clean)`,
+      title: behind > 0 ? "Workspace auto-merging (rebase)" : "Workspace auto-merging (clean fast-forward)",
+      body: `${ws.branch ?? ws.id} → ${p.baseRef ?? "base"} (${ahead} ahead${behind > 0 ? `, ${behind} behind — rebasing` : ", clean"})`,
       meta: ws.branch ?? ws.id,
       icon: "ti-git-merge",
       view: "orchestrators",
@@ -719,7 +725,7 @@ async function autoMergeCleanFastForwards(): Promise<Record<string, unknown>> {
     });
   }
 
-  return { scanned: candidates.length, merged, heldByLease, leftForSteward, wokeStewards };
+  return { scanned: candidates.length, merged, heldByLease, heldByClaim, leftForSteward, wokeStewards };
 }
 
 // Send a system DM, swallowing failures (a stale/missing/misconfigured target
@@ -925,7 +931,7 @@ async function runDueMaintenanceJobs(): Promise<void> {
   for (const row of rows) {
     const definition = definitions.find((job) => job.id === row.id);
     if (definition) void runJob(definition).catch((error) => {
-      console.warn(`maintenance job ${definition.id} failed: ${error instanceof Error ? error.message : String(error)}`);
+      console.warn(`maintenance job ${definition.id} failed: ${errMessage(error)}`);
     });
   }
 }
@@ -993,7 +999,7 @@ async function runJob(definition: MaintenanceJobDefinition, options: { force?: b
   } catch (error) {
     const finishedAt = Date.now();
     const durationMs = finishedAt - startedAt;
-    const message = error instanceof Error ? error.message : String(error);
+    const message = errMessage(error);
     db.query(`
       UPDATE maintenance_jobs
       SET last_run_at = ?, next_run_at = ?, last_duration_ms = ?, last_status = 'failed',

package/src/managed-policy.ts

@@ -1,6 +1,6 @@
-import { resolveProviderSelection } from "agent-relay-sdk/provider-catalog";
-import { getAgentProfile, workspaceSpawnParams } from "./config-store";
+import { getAgentProfile } from "./config-store";
 import { runnerRuntimeTokenEnv } from "./runtime-tokens";
+import { buildSpawnCommand, resolveSpawnModelParams } from "./spawn-command";
 import type { SpawnPolicy, WorkspaceMode } from "./types";
 
 export function managedPolicyProviderArgs(policy: SpawnPolicy): string[] {
@@ -20,23 +20,6 @@ export function effectiveManagedPolicyWorkspaceMode(policy: SpawnPolicy): Worksp
   return policy.binding?.type === "channel" ? "shared" : "inherit";
 }
 
-function resolvedModelParams(policy: SpawnPolicy): Record<string, string> {
-  if (!policy.model && !policy.effort) return {};
-  try {
-    const selection = resolveProviderSelection({ provider: policy.provider, model: policy.model, effort: policy.effort });
-    return {
-      ...(selection.modelAlias ? { model: selection.modelAlias } : {}),
-      ...(selection.providerModel ? { providerModel: selection.providerModel } : {}),
-      ...(selection.effort ? { effort: selection.effort } : {}),
-    };
-  } catch {
-    return {
-      ...(policy.model ? { model: policy.model } : {}),
-      ...(policy.effort ? { effort: policy.effort } : {}),
-    };
-  }
-}
-
 export interface ManagedSpawnContext {
   createdBy: string;
   requestedAt?: number;
@@ -46,23 +29,21 @@ export function buildManagedSpawnParams(policy: SpawnPolicy, requestId: string,
   const providerArgs = managedPolicyProviderArgs(policy);
   const prompt = managedPolicyLaunchPrompt(policy);
   const agentProfile = policy.profile ? getAgentProfile(policy.profile)?.value : undefined;
-  return {
-    action: "spawn",
+  return buildSpawnCommand({
     provider: policy.provider,
     cwd: policy.cwd,
     workspaceMode: effectiveManagedPolicyWorkspaceMode(policy),
-    ...(policy.rig ? { rig: policy.rig } : {}),
-    ...resolvedModelParams(policy),
-    ...(policy.profile ? { profile: policy.profile } : {}),
-    ...(agentProfile ? { agentProfile } : {}),
-    ...workspaceSpawnParams(),
+    rig: policy.rig || undefined,
+    modelParams: resolveSpawnModelParams(policy.provider, policy.model, policy.effort, { onError: "passthrough", skipDefaultWhenEmpty: true }),
+    profile: policy.profile || undefined,
+    agentProfile,
     label: policy.label,
     tags: policy.tags,
     capabilities: policy.capabilities,
     approvalMode: policy.permissionMode,
     permissionMode: policy.permissionMode,
     providerArgs,
-    ...(prompt ? { prompt } : {}),
+    prompt: prompt || undefined,
     headless: true,
     policyName: policy.name,
     spawnRequestId: requestId,
@@ -77,5 +58,5 @@ export function buildManagedSpawnParams(policy: SpawnPolicy, requestId: string,
     }),
     requestedBy: ctx.createdBy,
     requestedAt: ctx.requestedAt ?? Date.now(),
-  };
+  });
 }

package/src/mcp.ts

@@ -1,8 +1,11 @@
 import { Buffer } from "node:buffer";
-import { randomUUID } from "node:crypto";
-import { isAbsolute, relative, resolve } from "node:path";
 import { getArtifactStorage, maxArtifactBytes, normalizeDigest } from "./artifact-storage";
 import { createCommand } from "./commands-db";
+import { buildSpawnCommand, generateSpawnRequestId, resolveSpawnModelParams, type SpawnModelParams } from "./spawn-command";
+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 {
@@ -33,7 +36,8 @@ import {
   isIntegrationAllowed,
 } from "./security";
 import type { ActivityKind, AgentCard, ArtifactKind, ArtifactSensitivity, AttachmentRef, Command, SendMessageInput, Message, SpawnApprovalMode, SpawnProvider } from "./types";
-import { resolveProviderSelection, type ProviderEffort } from "agent-relay-sdk/provider-catalog";
+import { type ProviderEffort } from "agent-relay-sdk/provider-catalog";
+import { errMessage, isRecord, SPAWN_PROVIDERS, APPROVAL_MODES, VALID_EFFORTS } from "agent-relay-sdk";
 import { childRunnerRuntimeTokenEnv, runnerRuntimeTokenEnv } from "./runtime-tokens";
 
 type JsonRpcId = string | number | null;
@@ -66,9 +70,7 @@ const VALID_ARTIFACT_KINDS = ["image", "audio", "video", "document", "archive",
 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 VALID_SPAWN_PROVIDERS = ["claude", "codex"] as const;
-const VALID_SPAWN_APPROVALS = ["open", "guarded", "read-only"] as const;
-const VALID_PROVIDER_EFFORTS = ["low", "medium", "high", "xhigh", "max"] as const;
+
 
 const TOOLS: ToolDefinition[] = [
   {
@@ -201,13 +203,13 @@ const TOOLS: ToolDefinition[] = [
     inputSchema: {
       type: "object",
       properties: {
-        provider: { type: "string", enum: VALID_SPAWN_PROVIDERS },
+        provider: { type: "string", enum: SPAWN_PROVIDERS },
         orchestratorId: { type: "string" },
         cwd: { type: "string" },
         label: { type: "string" },
         model: { type: "string" },
-        effort: { type: "string", enum: VALID_PROVIDER_EFFORTS },
-        approvalMode: { type: "string", enum: VALID_SPAWN_APPROVALS },
+        effort: { type: "string", enum: VALID_EFFORTS },
+        approvalMode: { type: "string", enum: APPROVAL_MODES },
         prompt: { type: "string" },
         systemPromptAppend: { type: "string" },
         tags: { type: "array", items: { type: "string" } },
@@ -273,7 +275,7 @@ export async function postMcp(req: Request): Promise<Response> {
     }
     return Response.json(jsonRpcError(id, -32601, `unknown MCP method: ${method}`));
   } catch (error) {
-    const message = error instanceof Error ? error.message : String(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 }));
@@ -285,23 +287,11 @@ async function parseJsonRpcRequest(req: Request): Promise<
   | { ok: false; status: number; error: string }
 > {
   if (!req.body) return { ok: false, status: 400, error: "JSON-RPC body required" };
-  const reader = req.body.getReader();
-  const chunks: Uint8Array[] = [];
-  let total = 0;
-  while (true) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    if (!value) continue;
-    total += value.byteLength;
-    const maxBodyBytes = Math.max(MAX_BODY_BYTES, maxArtifactBytes() + MCP_BODY_OVERHEAD_BYTES);
-    if (total > maxBodyBytes) {
-      await reader.cancel().catch(() => {});
-      return { ok: false, status: 413, error: `request body exceeds ${maxBodyBytes} bytes` };
-    }
-    chunks.push(value);
-  }
+  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(concatBytes(chunks))) as unknown;
+    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 {
@@ -309,17 +299,6 @@ async function parseJsonRpcRequest(req: Request): Promise<
   }
 }
 
-function concatBytes(chunks: Uint8Array[]): Uint8Array {
-  const total = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);
-  const output = new Uint8Array(total);
-  let offset = 0;
-  for (const chunk of chunks) {
-    output.set(chunk, offset);
-    offset += chunk.byteLength;
-  }
-  return output;
-}
-
 function mcpAuthContext(req: Request): McpAuthContext {
   const component = getComponentAuth(req);
   if (component) return { actor: component.sub, kind: "component", scopes: component.scope, component };
@@ -355,7 +334,7 @@ async function callTool(auth: McpAuthContext, params: unknown): Promise<Record<s
     auditToolCall(auth, name, "ok", result);
     return toolResult(result);
   } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
+    const message = errMessage(error);
     auditToolCall(auth, name, error instanceof McpAuthError ? "denied" : "error", undefined, message);
     throw error;
   }
@@ -519,16 +498,16 @@ function relayAgentStatus(args: Record<string, unknown>): Record<string, unknown
 }
 
 function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
-  const provider = enumField(args.provider, "provider", VALID_SPAWN_PROVIDERS) as SpawnProvider;
+  const provider = enumField(args.provider, "provider", SPAWN_PROVIDERS) as SpawnProvider;
   const cwd = optionalString(args.cwd, "cwd", 500);
   const orchestrator = selectSpawnOrchestrator(provider, optionalString(args.orchestratorId, "orchestratorId", 200), cwd);
   const resolvedCwd = cwd || orchestrator.baseDir;
-  if (cwd && !pathWithinBase(cwd, orchestrator.baseDir)) {
+  if (cwd && !isPathWithinBase(cwd, orchestrator.baseDir)) {
     throw new ValidationError(`cwd must be within orchestrator base directory: ${orchestrator.baseDir}`);
   }
   const selection = providerSelection(provider, args);
-  const approvalMode = optionalEnum(args.approvalMode, "approvalMode", VALID_SPAWN_APPROVALS) as SpawnApprovalMode | undefined ?? "guarded";
-  const spawnRequestId = optionalString(args.spawnRequestId, "spawnRequestId", 160) ?? `sp_${randomUUID()}`;
+  const approvalMode = optionalEnum(args.approvalMode, "approvalMode", APPROVAL_MODES) as SpawnApprovalMode | undefined ?? "guarded";
+  const spawnRequestId = optionalString(args.spawnRequestId, "spawnRequestId", 160) ?? generateSpawnRequestId();
   const label = optionalString(args.label, "label", 120);
   const policyName = optionalString(args.policyName, "policyName", 120);
   assertComponentResourceAllowed(auth, {
@@ -558,12 +537,9 @@ function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknown>): R
     source: "system",
     target: orchestrator.agentId,
     correlationId: spawnRequestId,
-    params: {
-      action: "spawn",
+    params: buildSpawnCommand({
       provider,
-      model: selection.model,
-      providerModel: selection.providerModel,
-      effort: selection.effort,
+      modelParams: selection,
       cwd: resolvedCwd,
       label,
       tags: optionalStringArray(args.tags, "tags") ?? [],
@@ -580,7 +556,7 @@ function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknown>): R
       requestedVia: "mcp",
       requestedAt: Date.now(),
       orchestratorId: orchestrator.id,
-    },
+    }),
   });
   emitCommand(command);
   return { ok: true, orchestratorId: orchestrator.id, provider, command };
@@ -714,7 +690,7 @@ function selectSpawnOrchestrator(provider: SpawnProvider, orchestratorId?: strin
   }
   const candidates = listOrchestrators().filter((item) => item.status === "online" && item.providers.includes(provider));
   if (cwd) {
-    const match = candidates.find((item) => pathWithinBase(cwd, item.baseDir));
+    const match = candidates.find((item) => isPathWithinBase(cwd, item.baseDir));
     if (match) return match;
   }
   const orchestrator = candidates[0];
@@ -736,7 +712,7 @@ function selectControlOrchestrator(input: {
     return orchestrator;
   }
   const agent = input.agentId ? getAgent(input.agentId) : null;
-  const orchestrator = agent ? managedControlOrchestrator(agent, input) : findManagedOrchestrator(input);
+  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;
@@ -746,60 +722,19 @@ function managedControlOrchestrator(
   agent: AgentCard,
   input: { policyName?: string; spawnRequestId?: string; tmuxSession?: string },
 ): NonNullable<ReturnType<typeof getOrchestrator>> | null {
-  const metaTmuxSession = typeof agent.meta?.tmuxSession === "string" ? agent.meta.tmuxSession : "";
-  const metaPolicyName = input.policyName ?? (typeof agent.meta?.policyName === "string" ? agent.meta.policyName : "");
-  const metaSpawnRequestId = input.spawnRequestId ?? (typeof agent.meta?.spawnRequestId === "string" ? agent.meta.spawnRequestId : "");
-  return findManagedOrchestrator({
+  const str = (v: unknown): string | undefined => (typeof v === "string" ? v : undefined);
+  return listManagedOrchestratorsForAgent({
     agentId: agent.id,
-    policyName: metaPolicyName,
-    spawnRequestId: metaSpawnRequestId,
-    tmuxSession: input.tmuxSession ?? metaTmuxSession,
-  }) ?? (agent.machine ? getOrchestrator(agent.machine) : null);
+    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 findManagedOrchestrator(input: {
-  agentId?: string;
-  policyName?: string;
-  spawnRequestId?: string;
-  tmuxSession?: string;
-}): NonNullable<ReturnType<typeof getOrchestrator>> | null {
-  return listOrchestrators().find((orchestrator) => orchestrator.managedAgents.some((managed) =>
-    (!!input.agentId && managed.agentId === input.agentId) ||
-    (!!input.tmuxSession && managed.tmuxSession === input.tmuxSession) ||
-    (!!input.policyName && managed.policyName === input.policyName) ||
-    (!!input.spawnRequestId && managed.spawnRequestId === input.spawnRequestId)
-  )) ?? null;
-}
-
-function providerSelection(provider: SpawnProvider, args: Record<string, unknown>): { model?: string; effort?: ProviderEffort; providerModel?: string } {
+function providerSelection(provider: SpawnProvider, args: Record<string, unknown>): SpawnModelParams {
   const model = optionalString(args.model, "model", 120);
-  const effort = optionalEnum(args.effort, "effort", VALID_PROVIDER_EFFORTS) as ProviderEffort | undefined;
-  try {
-    const resolved = resolveProviderSelection({ provider, model, effort });
-    return {
-      model: resolved.modelAlias,
-      providerModel: resolved.providerModel,
-      effort: resolved.effort,
-    };
-  } catch (error) {
-    throw new ValidationError(error instanceof Error ? error.message : String(error));
-  }
-}
-
-function pathWithinBase(path: string, baseDir: string): boolean {
-  const base = resolve(baseDir);
-  const target = resolve(path);
-  const rel = relative(base, target);
-  return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolute(rel));
-}
-
-function bytesToStream(bytes: Uint8Array): ReadableStream<Uint8Array> {
-  return new ReadableStream<Uint8Array>({
-    start(controller) {
-      controller.enqueue(bytes);
-      controller.close();
-    },
-  });
+  const effort = optionalEnum(args.effort, "effort", VALID_EFFORTS) as ProviderEffort | undefined;
+  return resolveSpawnModelParams(provider, model, effort);
 }
 
 function artifactBytes(args: Record<string, unknown>): Uint8Array {
@@ -937,10 +872,6 @@ function auditToolCall(
   }
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 function recordField(value: unknown, field: string): Record<string, unknown> {
   if (!isRecord(value)) throw new ValidationError(`${field} must be an object`);
   return value;
@@ -980,12 +911,6 @@ function optionalBoolean(value: unknown, field: string): boolean | undefined {
   return value;
 }
 
-function optionalEnum<T extends readonly string[]>(value: unknown, field: string, valid: T): T[number] | undefined {
-  if (value === undefined || value === null) return undefined;
-  if (typeof value !== "string" || !valid.includes(value as T[number])) throw new ValidationError(`${field} must be one of: ${valid.join(", ")}`);
-  return value as T[number];
-}
-
 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`);

package/src/memory-broker-smoke.ts

@@ -1,3 +1,5 @@
+import { errMessage, RELAY_TOKEN_HEADER } from "agent-relay-sdk";
+
 interface MemoryBrokerSmokeOptions {
   baseUrl?: string;
   token?: string;
@@ -39,7 +41,7 @@ export async function runMemoryBrokerSmoke(options: MemoryBrokerSmokeOptions = {
 
   const request = async <T>(method: string, path: string, body?: unknown): Promise<T> => {
     const headers: Record<string, string> = {};
-    if (token) headers["X-Agent-Relay-Token"] = token;
+    if (token) headers[RELAY_TOKEN_HEADER] = token;
     if (body !== undefined) headers["Content-Type"] = "application/json";
     const response = await fetchImpl(new URL(path, baseUrl), {
       method,
@@ -135,7 +137,7 @@ async function step<T>(steps: MemoryBrokerSmokeStep[], name: string, detail: str
     steps.push({ name, ok: true, detail });
     return result;
   } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
+    const message = errMessage(error);
     steps.push({ name, ok: false, detail: message });
     throw error;
   }

package/src/memory-command-broker.ts

@@ -20,6 +20,7 @@ import {
   normalizeMemorySearchResult,
 } from "./memory-broker-contract";
 import { normalizeContextPackage } from "./memory-http-broker";
+import { errMessage, isRecord } from "agent-relay-sdk";
 
 const DEFAULT_TIMEOUT_MS = 10_000;
 
@@ -104,7 +105,7 @@ export class CommandMemoryBroker implements MemoryBroker {
       return unwrapResult(parseJson(stdout, operation));
     } catch (error) {
       if (error instanceof MemoryBrokerContractError) throw error;
-      throw new MemoryBrokerContractError(`command memory broker ${operation} failed: ${error instanceof Error ? error.message : String(error)}`);
+      throw new MemoryBrokerContractError(`command memory broker ${operation} failed: ${errMessage(error)}`);
     } finally {
       clearTimeout(timer);
     }
@@ -155,7 +156,3 @@ function numberField(value: unknown, field: string): number {
   if (typeof value !== "number" || !Number.isFinite(value)) throw new MemoryBrokerContractError(`${field} must be a number`);
   return value;
 }
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}

package/src/memory-http-broker.ts

@@ -19,6 +19,7 @@ import {
   normalizeMemoryBrokerCapabilities,
   normalizeMemorySearchResult,
 } from "./memory-broker-contract";
+import { errMessage, isRecord } from "agent-relay-sdk";
 
 const DEFAULT_TIMEOUT_MS = 10_000;
 
@@ -98,7 +99,7 @@ export class HttpMemoryBroker implements MemoryBroker {
       if (error instanceof DOMException && error.name === "AbortError") {
         throw new MemoryBrokerContractError(`http memory broker ${operation} timed out after ${this.timeoutMs}ms`);
       }
-      throw new MemoryBrokerContractError(`http memory broker ${operation} failed: ${error instanceof Error ? error.message : String(error)}`);
+      throw new MemoryBrokerContractError(`http memory broker ${operation} failed: ${errMessage(error)}`);
     } finally {
       clearTimeout(timer);
     }
@@ -182,7 +183,3 @@ function requireRecord(value: unknown, field: string): Record<string, unknown> {
   if (!isRecord(value)) throw new MemoryBrokerContractError(`${field} must be an object`);
   return value;
 }
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}

package/src/memory-service.ts

@@ -1,5 +1,6 @@
 import { createCommand } from "./commands-db";
 import { getAgent, ValidationError } from "./db";
+import { isRecord } from "agent-relay-sdk";
 import { assembleContextPackage, contextBudgetForAgent, estimateMemoryTokens } from "./memory-broker";
 import { createMemoryBrokerRegistry, memoryBrokerConfigFromEnv } from "./memory-broker-registry";
 import { filterMemoriesForInjection, formatUntrustedMemoryBlock } from "./memory-broker-contract";
@@ -349,7 +350,3 @@ function stringArray(value: unknown): string[] | undefined {
 function isPositiveInteger(value: unknown): value is number {
   return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
 }
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}

package/src/memory-sqlite-broker.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import type { Database } from "bun:sqlite";
 import { getDb, ValidationError } from "./db";
+import { parseJson } from "./utils";
 import type {
   ActiveMemoryClearReason,
   ContextPackage,
@@ -327,14 +328,6 @@ function rowToMemory(row: MemoryRow): Memory {
   });
 }
 
-function parseJson<T>(raw: string, fallback: T): T {
-  try {
-    return JSON.parse(raw) as T;
-  } catch {
-    return fallback;
-  }
-}
-
 function tagOverlap(tags: string[], queryTags: Set<string>): number {
   if (queryTags.size === 0) return 0;
   const memoryTags = new Set(tags.map((tag) => tag.toLowerCase()));

package/src/orchestrator-lookup.ts

@@ -0,0 +1,29 @@
+import { listOrchestrators } from "./db";
+
+export interface ManagedAgentMatch {
+  agentId?: string;
+  sessionName?: string;
+  tmuxSession?: string;
+  policyName?: string;
+  spawnRequestId?: string;
+}
+
+/**
+ * Every orchestrator that owns a managed agent matching ANY provided identity
+ * key. Single home for the managed-agent→orchestrator lookup that routes.ts and
+ * mcp.ts each open-coded. routes also matches `sessionName`; mcp never passed it,
+ * so leaving the key undefined reproduces mcp's behavior exactly. Callers layer
+ * their own online / runner-managed / machine-fallback policy on top — routes
+ * picks the first online candidate, mcp takes the first match.
+ */
+export function listManagedOrchestratorsForAgent(match: ManagedAgentMatch): ReturnType<typeof listOrchestrators> {
+  return listOrchestrators().filter((orch) =>
+    orch.managedAgents.some((managed) =>
+      (!!match.agentId && managed.agentId === match.agentId) ||
+      (!!match.sessionName && managed.sessionName === match.sessionName) ||
+      (!!match.tmuxSession && managed.tmuxSession === match.tmuxSession) ||
+      (!!match.policyName && managed.policyName === match.policyName) ||
+      (!!match.spawnRequestId && managed.spawnRequestId === match.spawnRequestId),
+    ),
+  );
+}

package/src/provider-catalog-store.ts

@@ -3,10 +3,10 @@ import {
   type ProviderCatalogEntry,
   type ProviderModelCatalogEntry,
 } from "agent-relay-sdk/provider-catalog";
+import { SPAWN_PROVIDERS } from "agent-relay-sdk";
 import type { SpawnProvider } from "./types";
 import { getDb, ValidationError } from "./db";
-
-const VALID_PROVIDERS: SpawnProvider[] = ["claude", "codex"];
+import { parseJson } from "./utils";
 
 interface ProviderModelOverrideRow {
   provider: SpawnProvider;
@@ -111,7 +111,7 @@ export function mergeProviderCatalog(
 }
 
 function normalizeOverrideInput(input: ProviderModelOverrideInput): ProviderModelOverrideInput {
-  if (!VALID_PROVIDERS.includes(input.provider)) throw new ValidationError("provider must be claude or codex");
+  if (!SPAWN_PROVIDERS.includes(input.provider)) throw new ValidationError("provider must be claude or codex");
   const alias = input.alias.trim();
   if (!alias) throw new ValidationError("model alias is required");
   if (input.entry.alias !== alias) throw new ValidationError("model entry alias must match override alias");
@@ -154,11 +154,3 @@ function cloneProviderEntry(entry: ProviderCatalogEntry): ProviderCatalogEntry {
 function cloneModelEntry(entry: ProviderModelCatalogEntry): ProviderModelCatalogEntry {
   return JSON.parse(JSON.stringify(entry)) as ProviderModelCatalogEntry;
 }
-
-function parseJson<T>(raw: string, fallback: T): T {
-  try {
-    return JSON.parse(raw) as T;
-  } catch {
-    return fallback;
-  }
-}