agent-relay-server 0.32.1 → 0.32.2

package/src/routes.ts

@@ -124,7 +124,6 @@ import {
   setAgentProfile,
   setConfig,
   setStewardConfig,
-  spawnGrantForProfile,
   upsertManagedAgentState,
   updateManagedAgentState,
 } from "./config-store";
@@ -215,7 +214,7 @@ import { rankRouteCandidates, type RouteAdvisorInput } from "./context-router";
 import { MemoryBrokerContractError } from "./memory-broker-contract";
 import { assertMemoryCreateAllowed, assertMemoryUpdateAllowed } from "./memory-security";
 import { captureTaskResultMemory, clearActiveMemories, injectAlwaysReloadMemories, injectMemoryContext, injectMemoryForMessageDelivery, injectMemoryForTaskClaim, memoryBroker, memoryBrokerConfig } from "./memory-service";
-import { postMcp } from "./mcp";
+import { postMcp, selectSpawnOrchestrator, McpNotFoundError } from "./mcp";
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { isPathWithinBase } from "./utils";
@@ -2281,6 +2280,7 @@ function restartSpawnParamsForAgent(
       policyName,
       spawnRequestId: requestId,
       createdBy: requestedBy,
+      profile: profileName || undefined,
     }),
     requestedBy,
     requestedAt: Date.now(),
@@ -2585,76 +2585,95 @@ const deleteAgentTerminalSession: Handler = async (req, params) => {
   return proxyOrchestratorDelete(req, orchestrator.id, `/api/terminal-guests/${encodeURIComponent(session)}`);
 };
 
+// Canonical spawn endpoint. The agent is the resource being created; the host is a parameter
+// (`orchestratorId`, defaulting to where the cwd lives), NOT a path segment — which is why this
+// supersedes the old `/api/orchestrators/:id/spawn`. ONE spawn path, so the spawn grant (resolved
+// from the profile inside the token mint) can't be threaded on some routes and forgotten on others.
 const postAgentSpawn: Handler = async (req) => {
   const parsed = await parseBody<unknown>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
   try {
     if (!isRecord(parsed.body)) return error("provider required");
-    const provider = optionalEnum(parsed.body.provider, "provider", SPAWN_PROVIDERS);
+    const provider = optionalEnum(parsed.body.provider, "provider", SPAWN_PROVIDERS) as SpawnProvider | undefined;
     if (!provider) return error("provider required");
-    const selection = cleanSpawnSelection(parsed.body, provider as SpawnProvider);
-    const approvalMode = optionalEnum(parsed.body.approvalMode, "approvalMode", APPROVAL_MODES, "guarded") as SpawnApprovalMode;
+    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 grant = spawnGrantForProfile(profile);
-
-    const orchestrators = listOrchestrators().filter(
-      (o) => o.status === "online" && o.providers.includes(provider as SpawnProvider),
-    );
-	    const orch = orchestrators[0];
-	    if (!orch) return error("no orchestrator available for provider: " + provider);
-	    if (cwd && !isPathWithinBase(cwd, orch.baseDir)) {
-	      return error(`cwd must be within orchestrator base directory: ${orch.baseDir}`);
-	    }
-	    const requestId = spawnRequestId();
-	    const denied = authorizeRoute(req, {
-	      scope: "agent:write",
-	      resource: { orchestratorId: orch.id, cwd: cwd || orch.baseDir },
-	    });
-	    if (denied) return denied;
+    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,
-	        approvalMode,
-	        profile: profile || undefined,
-	        spawnRequestId: requestId,
-	        requestedBy: "dashboard",
-	        requestedAt: Date.now(),
-	        env: runnerRuntimeTokenEnv({
-	          orchestratorId: orch.id,
-	          cwd: cwd || orch.baseDir,
-	          provider,
-	          label,
-	          spawnRequestId: requestId,
-	          createdBy: "dashboard",
-	          canSpawn: grant.canSpawn,
-	          maxSpawnedAgents: grant.maxSpawnedAgents,
-	        }),
-	      }),
-	    });
+      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 + "-" + Date.now(),
+      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, commandId: command.id, ...authAuditMetadata(req) },
+      metadata: { provider, orchestratorId: orch.id, approvalMode, workspaceMode, label, commandId: command.id, ...authAuditMetadata(req) },
     });
     return json({ ok: true, orchestratorId: orch.id, provider, command }, 202);
   } catch (e) {
+    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);
     throw e;
@@ -3515,94 +3534,6 @@ function cleanSafeNumber(value: unknown): number | undefined {
   return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }
 
-const postOrchestratorSpawn: Handler = async (req, params) => {
-  const parsed = await parseBody<unknown>(req);
-  if (!parsed.ok) return error(parsed.error, parsed.status);
-  try {
-    const orch = getOrchestrator(params.id!);
-    if (!orch) return error("orchestrator not found", 404);
-    if (orch.status !== "online") return error("orchestrator is offline", 409);
-
-    if (!isRecord(parsed.body)) return error("body required");
-    const provider = optionalEnum(parsed.body.provider, "provider", SPAWN_PROVIDERS)! as SpawnProvider;
-    const selection = validateSpawnSelectionForOrchestrator(orch, provider, parsed.body);
-    if (selection instanceof Response) return selection;
-    const cwd = cleanString(parsed.body.cwd, "cwd", { max: 500 });
-    if (cwd && !isPathWithinBase(cwd, orch.baseDir)) {
-      return error(`cwd must be within orchestrator base directory: ${orch.baseDir}`);
-    }
-    const label = cleanString(parsed.body.label, "label", { max: 120 });
-    const approvalMode = optionalEnum(parsed.body.approvalMode, "approvalMode", APPROVAL_MODES, "guarded") as SpawnApprovalMode;
-    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 profile = cleanString(parsed.body.profile, "profile", { max: 120 });
-    const workspaceMode = optionalEnum(parsed.body.workspaceMode, "workspaceMode", VALID_WORKSPACE_MODES, "inherit") as WorkspaceMode;
-    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: { model: selection.model, providerModel: selection.providerModel, effort: selection.effort },
-        cwd: cwd || orch.baseDir,
-        workspaceMode,
-        label,
-        tags,
-        capabilities,
-        approvalMode,
-        permissionMode: approvalMode,
-        profile,
-        agentProfile,
-        providerArgs,
-        prompt,
-        systemPromptAppend,
-	        policyName,
-	        spawnRequestId: requestId,
-	        env: runnerRuntimeTokenEnv({
-	          orchestratorId: orch.id,
-	          cwd: cwd || orch.baseDir,
-	          provider,
-	          label,
-	          policyName,
-	          spawnRequestId: requestId,
-	          createdBy: "dashboard",
-	        }),
-	        requestedBy: "dashboard",
-        requestedAt: Date.now(),
-      }),
-    });
-    emitCommand(command);
-    auditEvent({
-      clientId: "server-orchestrator-spawn-" + orch.id + "-" + command.id,
-      kind: "state",
-      title: `Spawn ${provider} agent requested`,
-      body: cwd || orch.baseDir,
-      meta: orch.id,
-      icon: "ti-plus",
-      view: "orchestrators",
-      metadata: { orchestratorId: orch.id, provider, approvalMode, workspaceMode, label, commandId: command.id, ...authAuditMetadata(req) },
-    });
-    return json({ ok: true, orchestratorId: orch.id, command }, 202);
-  } catch (e) {
-    if (e instanceof ValidationError) return error(e.message, 400);
-    throw e;
-  }
-};
-
 const ORCH_UPGRADE_DEADLINE_MS = 5 * 60_000;
 const ORCH_UPGRADE_SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
 const VALID_ORCH_UPGRADE_PROVIDERS = ["auto", "all", "codex", "claude", "orchestrator"] as const;
@@ -6698,7 +6629,6 @@ const routes: Route[] = [
   route("GET", "/api/orchestrators/:id", getOrchestratorById),
   route("POST", "/api/orchestrators/:id/heartbeat", postOrchestratorHeartbeat),
   route("PATCH", "/api/orchestrators/:id/agents", patchOrchestratorAgents),
-  route("POST", "/api/orchestrators/:id/spawn", postOrchestratorSpawn),
   route("POST", "/api/orchestrators/:id/runner-token", postOrchestratorRunnerToken),
   route("POST", "/api/orchestrators/:id/actions", postOrchestratorAction),
   route("GET", "/api/orchestrators/:id/directories", getOrchestratorDirectories),

package/src/runtime-tokens.ts

@@ -1,5 +1,6 @@
 import { createToken, getTokenProfile, revokeToken } from "./token-db";
 import { verifyComponentTokenAllowExpired } from "./security";
+import { spawnGrantForProfile } from "./config-store";
 import type { TokenRecord } from "./types";
 
 // Scopes that turn an agent's runtime token into a spawn-capable one (#221). Appended to the
@@ -89,13 +90,19 @@ export function issueRunnerRuntimeToken(input: {
   policyName?: string;
   spawnRequestId?: string;
   createdBy?: string;
-  /** Grant the spawn/shutdown scopes (resolved from the agent's profile maxSpawnedAgents>0). */
-  canSpawn?: boolean;
-  /** Live-children quota baked into the token for the runtime spawn check. */
-  maxSpawnedAgents?: number;
+  /**
+   * Agent profile name. The spawn grant (the `command:spawn`/`command:shutdown` scope + the
+   * live-children quota) is resolved from this profile's `maxSpawnedAgents` HERE, in the single
+   * mint, so capability⇒tool holds for EVERY spawn path. Callers pass the profile they already
+   * have; they cannot forget to thread the grant (the recurring bug this centralization kills).
+   */
+  profile?: string;
+  /** Agent-requested spawn → forces a non-spawn-capable child regardless of profile (no grandchildren). */
+  agentInitiated?: boolean;
   /** Parent agent id — stamped so the child registers with an authoritative `spawnedBy`. */
   spawnedBy?: string;
 }): RuntimeTokenResult {
+  const grant = spawnGrantForProfile(input.profile, input.agentInitiated);
   const subject = input.policyName
     ? `runner:policy:${input.policyName}`
     : input.spawnRequestId
@@ -105,13 +112,13 @@ export function issueRunnerRuntimeToken(input: {
     profileId: "provider-agent",
     sub: subject,
     role: "provider",
-    scope: runnerScopeWithSpawn(input.canSpawn ?? false),
+    scope: runnerScopeWithSpawn(grant.canSpawn),
     constraints: {
       orchestrators: [input.orchestratorId],
       cwdPrefixes: [input.cwd],
       ...(input.policyName ? { policies: [input.policyName] } : {}),
       ...(input.spawnRequestId ? { spawnRequestIds: [input.spawnRequestId] } : {}),
-      ...(input.canSpawn && input.maxSpawnedAgents ? { maxSpawnedAgents: input.maxSpawnedAgents } : {}),
+      ...(grant.canSpawn && grant.maxSpawnedAgents ? { maxSpawnedAgents: grant.maxSpawnedAgents } : {}),
       ...(input.spawnedBy ? { spawnedBy: input.spawnedBy } : {}),
     },
     createdBy: input.createdBy ?? "runtime",
@@ -226,8 +233,10 @@ export function runnerRuntimeTokenEnv(input: {
   policyName?: string;
   spawnRequestId?: string;
   createdBy?: string;
-  canSpawn?: boolean;
-  maxSpawnedAgents?: number;
+  /** Agent profile name — spawn grant is resolved from it in the mint (see issueRunnerRuntimeToken). */
+  profile?: string;
+  /** Agent-requested spawn → forces a non-spawn-capable child (no grandchildren). */
+  agentInitiated?: boolean;
   spawnedBy?: string;
 }): Record<string, string> {
   const issued = issueRunnerRuntimeToken(input);

package/src/security.ts

@@ -170,7 +170,6 @@ export function requiredScopeFor(method: string, pathname: string): string | nul
   if (pathname === "/api/orchestrators/bootstrap") return "token:write";
   if (pathname.match(/^\/api\/orchestrators\/[^/]+\/logs\//)) return "logs:read";
   if (pathname.match(/^\/api\/orchestrators\/[^/]+\/terminal\//)) return "terminal:attach";
-  if (pathname.match(/^\/api\/orchestrators\/[^/]+\/spawn$/)) return "agent:write";
   if (pathname.startsWith("/api/artifacts")) {
     if (method === "GET" || method === "HEAD") return "artifact:read";
     if (method === "DELETE") return "artifact:admin";
@@ -242,7 +241,6 @@ export function requiredComponentScopeFor(method: string, pathname: string): str
   if (pathname === "/api/mcp") return "mcp:use";
   if (pathname.match(/^\/api\/orchestrators\/[^/]+\/logs\//)) return "logs:read";
   if (pathname.match(/^\/api\/orchestrators\/[^/]+\/terminal\//)) return "terminal:attach";
-  if (pathname.match(/^\/api\/orchestrators\/[^/]+\/spawn$/)) return "agent:write";
   if (pathname.startsWith("/api/commands")) {
     if (method === "GET") return "command:read";
     return "command:write";