agent-relay-server 0.20.0 → 0.21.0

package/src/managed-policy.ts

@@ -1,4 +1,4 @@
-import { getAgentProfile } from "./config-store";
+import { getAgentProfile, spawnGrantForProfile } from "./config-store";
 import { runnerRuntimeTokenEnv } from "./runtime-tokens";
 import { buildSpawnCommand, resolveSpawnModelParams } from "./spawn-command";
 import type { SpawnPolicy, WorkspaceMode } from "./types";
@@ -29,6 +29,7 @@ export function buildManagedSpawnParams(policy: SpawnPolicy, requestId: string,
   const providerArgs = managedPolicyProviderArgs(policy);
   const prompt = managedPolicyLaunchPrompt(policy);
   const agentProfile = policy.profile ? getAgentProfile(policy.profile)?.value : undefined;
+  const grant = spawnGrantForProfile(policy.profile);
   return buildSpawnCommand({
     provider: policy.provider,
     cwd: policy.cwd,
@@ -55,6 +56,8 @@ export function buildManagedSpawnParams(policy: SpawnPolicy, requestId: string,
       policyName: policy.name,
       spawnRequestId: requestId,
       createdBy: ctx.createdBy,
+      canSpawn: grant.canSpawn,
+      maxSpawnedAgents: grant.maxSpawnedAgents,
     }),
     requestedBy: ctx.createdBy,
     requestedAt: ctx.requestedAt ?? Date.now(),

package/src/mcp.ts

@@ -9,6 +9,7 @@ import { bytesToStream, readBodyBytes } from "./http-body";
 import { MAX_BODY_BYTES, VERSION } from "./config";
 import { getManagedAgentState, getSpawnPolicy, listSpawnPolicies } from "./config-store";
 import {
+  countLiveSpawnedAgents,
   createArtifact,
   createActivityEvent,
   getAgent,
@@ -19,12 +20,16 @@ import {
   getThread,
   linkArtifact,
   listAgents,
+  searchAgents,
+  type AgentSearchFilter,
+  type AgentSearchSort,
   listArtifactsForEntity,
   listOrchestrators,
   sendMessageWithResult,
   upsertArtifactBlob,
   ValidationError,
 } from "./db";
+import { planSend, type DeliveryReceipt } from "./agent-ref";
 import { emitRelayEvent } from "./events";
 import { emitMessageQueued, emitNewMessage } from "./sse";
 import {
@@ -38,7 +43,7 @@ import {
 import type { ActivityKind, AgentCard, ArtifactKind, ArtifactSensitivity, AttachmentRef, Command, SendMessageInput, Message, SpawnApprovalMode, SpawnProvider } from "./types";
 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";
+import { runnerRuntimeTokenEnv } from "./runtime-tokens";
 
 type JsonRpcId = string | number | null;
 
@@ -75,13 +80,13 @@ const VALID_ARTIFACT_ENTITY_TYPES = ["message", "task", "recipeRun", "recipeStep
 const TOOLS: ToolDefinition[] = [
   {
     name: "relay_send_message",
-    description: "Send an Agent Relay message with structured fields instead of shell quoting.",
+    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.",
     requiredScopes: ["messages:write", "message:send"],
     inputSchema: {
       type: "object",
       properties: {
-        from: { type: "string", description: "Sender Relay agent id." },
-        to: { type: "string", description: "Target agent id, label, tag:, cap:, policy:, or broadcast." },
+        from: { type: "string", description: "Deprecated/optional. Your identity is taken from your auth token; ignored for managed agents. You never need to set this." },
+        to: { type: "string", description: "Target: an agent id, label, name, or a unique id segment (e.g. the number part) — resolved automatically. Or a fan-out selector: tag:, cap:, label:, policy:, or broadcast." },
         body: { type: "string" },
         subject: { type: "string" },
         channel: { type: "string" },
@@ -91,18 +96,18 @@ const TOOLS: ToolDefinition[] = [
         payload: { type: "object" },
         meta: { type: "object" },
       },
-      required: ["from", "to", "body"],
+      required: ["to", "body"],
       additionalProperties: false,
     },
   },
   {
     name: "relay_reply",
-    description: "Reply to an Agent Relay message by id, preserving reply/thread/channel context.",
+    description: "Reply to an Agent Relay message by id, preserving reply/thread/channel context. Returns a delivery receipt; expectReply:false means the original sender is no longer reachable.",
     requiredScopes: ["messages:write", "message:send"],
     inputSchema: {
       type: "object",
       properties: {
-        from: { type: "string", description: "Sender Relay agent id." },
+        from: { type: "string", description: "Deprecated/optional. Your identity is taken from your auth token; ignored for managed agents. You never need to set this." },
         messageId: { type: "integer", minimum: 1 },
         body: { type: "string" },
         subject: { type: "string" },
@@ -111,7 +116,7 @@ const TOOLS: ToolDefinition[] = [
         payload: { type: "object" },
         meta: { type: "object" },
       },
-      required: ["from", "messageId", "body"],
+      required: ["messageId", "body"],
       additionalProperties: false,
     },
   },
@@ -184,7 +189,7 @@ const TOOLS: ToolDefinition[] = [
   },
   {
     name: "relay_agent_status",
-    description: "Inspect Relay agent, orchestrator, and managed spawn-policy status.",
+    description: "Inspect Relay agent, orchestrator, and managed spawn-policy status. The default agent list shows only RUNNING agents (the ones you can actually message/reply/pair with); pass includeOffline:true for the full roster.",
     requiredScopes: ["agents:read", "agent:read"],
     inputSchema: {
       type: "object",
@@ -192,14 +197,47 @@ const TOOLS: ToolDefinition[] = [
         agentId: { type: "string" },
         policyName: { type: "string" },
         orchestratorId: { type: "string" },
+        includeOffline: { type: "boolean", description: "Include offline/stale agents in the default list (default false)." },
       },
       additionalProperties: false,
     },
   },
+  {
+    name: "relay_find_agents",
+    description: "Search the fleet for agents by label, capability, provider, tag, machine, status, or kind, sorted by last-active/created/label. Defaults to running agents only. Use this to find a reachable, capable peer before messaging or pairing — instead of dumping the whole roster.",
+    requiredScopes: ["agents:read", "agent:read"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        label: { type: "string", description: "Substring match on label or name." },
+        capability: { type: ["string", "array"], items: { type: "string" }, description: "One or more capabilities (OR within)." },
+        provider: { type: ["string", "array"], items: { type: "string" }, description: "Model provider, e.g. claude or codex." },
+        tag: { type: ["string", "array"], items: { type: "string" } },
+        machine: { type: ["string", "array"], items: { type: "string" } },
+        kind: { type: ["string", "array"], items: { type: "string" } },
+        status: { type: ["string", "array"], items: { type: "string" }, description: "online/idle/busy/offline/stale, the 'running' shorthand, or 'all'. Default 'running'." },
+        spawnedBy: { type: "string", description: "Parent agent id, or 'me' for your own spawned children (#221)." },
+        sortBy: { type: "string", enum: ["lastActive", "created", "label"] },
+        order: { type: "string", enum: ["asc", "desc"] },
+        limit: { type: "integer", minimum: 1, maximum: 200 },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_whoami",
+    description: "Return your own Relay identity and agent card (id, label, status, tags, capabilities). Your identity comes from your auth token — you do NOT need this to send, reply, or pair; use it only when you need to reason about yourself.",
+    requiredScopes: ["mcp:use"],
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false,
+    },
+  },
   {
     name: "relay_spawn_agent",
-    description: "Request a provider agent spawn through Relay's orchestrator command bus.",
-    requiredScopes: ["agents:write", "agent:write"],
+    description: "Spawn a long-living provider agent through Relay's orchestrator. Gated: requires the command:spawn scope, granted only to agents whose profile sets maxSpawnedAgents>0, up to that live-children quota. Spawned agents cannot themselves spawn (no grandchildren).",
+    requiredScopes: ["command:spawn"],
     inputSchema: {
       type: "object",
       properties: {
@@ -212,6 +250,7 @@ const TOOLS: ToolDefinition[] = [
         approvalMode: { type: "string", enum: APPROVAL_MODES },
         prompt: { type: "string" },
         systemPromptAppend: { type: "string" },
+        profile: { type: "string", description: "Agent profile name to apply (env, instructions, permissions, MCP/skills, spawn quota)." },
         tags: { type: "array", items: { type: "string" } },
         capabilities: { type: "array", items: { type: "string" } },
         providerArgs: { type: "array", items: { type: "string" } },
@@ -224,8 +263,8 @@ const TOOLS: ToolDefinition[] = [
   },
   {
     name: "relay_shutdown_agent",
-    description: "Request an agent shutdown through Relay's orchestrator command bus.",
-    requiredScopes: ["agents:write", "agent:write"],
+    description: "Shut down an agent through Relay's orchestrator. Gated: requires the command:shutdown scope; an agent caller may only target its OWN live spawned children. Admin tokens keep full reach.",
+    requiredScopes: ["command:shutdown"],
     inputSchema: {
       type: "object",
       properties: {
@@ -327,6 +366,8 @@ async function callTool(auth: McpAuthContext, params: unknown): Promise<Record<s
     else if (name === "relay_upload_artifact") result = await relayUploadArtifact(auth, args);
     else if (name === "relay_attach_artifact") result = relayAttachArtifact(auth, args);
     else if (name === "relay_agent_status") result = relayAgentStatus(args);
+    else if (name === "relay_find_agents") result = relayFindAgents(auth, args);
+    else if (name === "relay_whoami") result = relayWhoami(auth);
     else if (name === "relay_spawn_agent") result = relaySpawnAgent(auth, args);
     else if (name === "relay_shutdown_agent") result = relayShutdownAgent(auth, args);
     else throw new ValidationError(`unknown tool: ${name}`);
@@ -340,12 +381,67 @@ async function callTool(auth: McpAuthContext, params: unknown): Promise<Record<s
   }
 }
 
-function relaySendMessage(auth: McpAuthContext, args: Record<string, unknown>): Message {
+// A managed/runtime MCP token is minted with `constraints.agents = [its own agent id]`
+// (see issueMcpRuntimeToken). That single allowed agent IS the caller's identity, and the
+// security layer already treats it as the only `from` this token may use. Derive it so
+// agents never need to know — or type — their own id.
+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;
+}
+
+// Caller's own agent id for spawn/shutdown gating (#221). `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.
+// Returns undefined for server/admin tokens (unrestricted by design).
+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.
+  const identity = senderIdentity(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 });
+}
+
+function relayWhoami(auth: McpAuthContext): Record<string, unknown> {
+  const agentId = senderIdentity(auth);
+  const agent = agentId ? getAgent(agentId) : null;
+  return {
+    agentId: agentId ?? null,
+    actor: auth.actor,
+    kind: auth.kind,
+    scopes: auth.scopes,
+    agent: agent ?? null,
+  };
+}
+
+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 });
+  // 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.
+  const plan = planSend(requestedTo, listAgents());
+  if (plan.kind === "not_found") throw new McpNotFoundError(plan.message);
+  if (plan.kind === "ambiguous") throw new ValidationError(plan.message);
   const input: SendMessageInput = {
-    from: stringField(args.from, "from", { required: true, max: 200 }),
-    to: stringField(args.to, "to", { required: true, max: 200 }),
+    from: resolveSender(auth, args.from),
+    to: plan.to,
     body: stringField(args.body, "body", { required: true, maxBytes: MAX_BODY_BYTES }),
     subject: optionalString(args.subject, "subject", 200),
     channel: optionalString(args.channel, "channel", 120),
@@ -359,10 +455,10 @@ function relaySendMessage(auth: McpAuthContext, args: Record<string, unknown>):
   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;
+  return { ...result.message, delivery: plan.receipt };
 }
 
-function relayReply(auth: McpAuthContext, args: Record<string, unknown>): Message {
+function relayReply(auth: McpAuthContext, args: Record<string, unknown>): Message & { delivery: DeliveryReceipt } {
   const messageId = positiveId(args.messageId, "messageId");
   const parent = getMessage(messageId);
   if (!parent) throw new McpNotFoundError(`message ${messageId} not found`);
@@ -375,7 +471,7 @@ function relayReply(auth: McpAuthContext, args: Record<string, unknown>): Messag
     ...replyContext(parent),
   }, attachments);
   const input: SendMessageInput = {
-    from: stringField(args.from, "from", { required: true, max: 200 }),
+    from: resolveSender(auth, args.from),
     to: parent.from,
     body: stringField(args.body, "body", { required: true, maxBytes: MAX_BODY_BYTES }),
     subject: optionalString(args.subject, "subject", 200),
@@ -389,7 +485,13 @@ function relayReply(auth: McpAuthContext, args: Record<string, unknown>): Messag
   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;
+  // 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());
+  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 };
 }
 
 function relayGetMessage(args: Record<string, unknown>): Record<string, unknown> {
@@ -490,13 +592,49 @@ function relayAgentStatus(args: Record<string, unknown>): Record<string, unknown
     if (!orchestrator) throw new McpNotFoundError(`orchestrator ${orchestratorId} not found`);
     return { orchestrator };
   }
+  // Default to running agents only — offline/stale rows are pure noise (you can only
+  // message/reply/pair with a live agent) and bloat the payload. includeOffline opts back in.
+  const includeOffline = optionalBoolean(args.includeOffline, "includeOffline") === true;
   return {
-    agents: listAgents(),
+    agents: searchAgents({ status: includeOffline ? "all" : "running" }),
     spawnPolicies: listSpawnPolicies().map((entry) => policyStatusPayload(entry.value)),
     orchestrators: listOrchestrators(),
   };
 }
 
+function optionalStringOrArray(value: unknown, field: string): string | string[] | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) {
+    return value.map((item, i) => stringField(item, `${field}[${i}]`, { required: true, max: 200 }));
+  }
+  throw new ValidationError(`${field} must be a string or string array`);
+}
+
+function relayFindAgents(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
+  // `spawnedBy: "me"` resolves to the caller's own id — list the children you spawned (#221).
+  const spawnedByArg = optionalString(args.spawnedBy, "spawnedBy", 240);
+  const spawnedBy = spawnedByArg === "me" ? callerAgentId(auth) ?? "\0unresolved" : spawnedByArg;
+  const filter: AgentSearchFilter = {
+    label: optionalString(args.label, "label", 200),
+    capability: optionalStringOrArray(args.capability, "capability"),
+    provider: optionalStringOrArray(args.provider, "provider"),
+    tag: optionalStringOrArray(args.tag, "tag"),
+    machine: optionalStringOrArray(args.machine, "machine"),
+    kind: optionalStringOrArray(args.kind, "kind"),
+    spawnedBy,
+    // Default to running — you can only act on a live agent (consistent with #218).
+    status: optionalStringOrArray(args.status, "status") ?? "running",
+  };
+  const sort: AgentSearchSort = {
+    sortBy: optionalEnum(args.sortBy, "sortBy", ["lastActive", "created", "label"] as const),
+    order: optionalEnum(args.order, "order", ["asc", "desc"] as const),
+    limit: optionalPositiveInt(args.limit, "limit"),
+  };
+  const agents = searchAgents(filter, sort);
+  return { agents, count: agents.length };
+}
+
 function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
   const provider = enumField(args.provider, "provider", SPAWN_PROVIDERS) as SpawnProvider;
   const cwd = optionalString(args.cwd, "cwd", 500);
@@ -510,28 +648,43 @@ function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknown>): R
   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);
+
+  // #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.
+  const callerId = callerAgentId(auth);
+  if (callerId) {
+    const me = getAgent(callerId);
+    if (me?.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`);
+    }
+  }
+
   assertComponentResourceAllowed(auth, {
     scope: "agent:write",
     resource: { orchestratorId: orchestrator.id, cwd: resolvedCwd, policyName, spawnRequestId },
   });
-  const env = auth.component?.role === "provider"
-    ? childRunnerEnvForDelegatingComponent(auth, {
-      orchestratorId: orchestrator.id,
-      cwd: resolvedCwd,
-      provider,
-      label,
-      policyName,
-      spawnRequestId,
-    })
-    : runnerRuntimeTokenEnv({
-      orchestratorId: orchestrator.id,
-      cwd: resolvedCwd,
-      provider,
-      label,
-      policyName,
-      spawnRequestId,
-      createdBy: auth.actor,
-    });
+
+  // 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,
+    canSpawn: false,
+    ...(callerId ? { spawnedBy: callerId } : {}),
+  });
   const command = createCommand({
     type: "agent.spawn",
     source: "system",
@@ -542,6 +695,7 @@ function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknown>): R
       modelParams: selection,
       cwd: resolvedCwd,
       label,
+      profile: profile || undefined,
       tags: optionalStringArray(args.tags, "tags") ?? [],
       capabilities: optionalStringArray(args.capabilities, "capabilities") ?? [],
       approvalMode,
@@ -562,34 +716,6 @@ function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknown>): R
   return { ok: true, orchestratorId: orchestrator.id, provider, command };
 }
 
-function childRunnerEnvForDelegatingComponent(
-  auth: McpAuthContext,
-  input: {
-    orchestratorId: string;
-    cwd: string;
-    provider: SpawnProvider;
-    label?: string;
-    policyName?: string;
-    spawnRequestId: string;
-  },
-): Record<string, string> {
-  const component = auth.component;
-  if (!component) throw new McpAuthError("component token required for child-agent delegation");
-  if (component.constraints?.canDelegate !== true) {
-    throw new McpAuthError("component token cannot delegate child agents");
-  }
-  return childRunnerRuntimeTokenEnv({
-    parentAgentId: component.sub,
-    orchestratorId: input.orchestratorId,
-    cwd: input.cwd,
-    provider: input.provider,
-    label: input.label,
-    policyName: input.policyName,
-    spawnRequestId: input.spawnRequestId,
-    createdBy: component.sub,
-  });
-}
-
 function relayShutdownAgent(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
   const agentId = optionalString(args.agentId, "agentId", 240);
   const policyName = optionalString(args.policyName, "policyName", 120);
@@ -598,6 +724,21 @@ function relayShutdownAgent(auth: McpAuthContext, args: Record<string, unknown>)
   if (!agentId && !policyName && !spawnRequestId && !tmuxSession) {
     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`);
+    }
+  }
   const orchestrator = selectControlOrchestrator({
     orchestratorId: optionalString(args.orchestratorId, "orchestratorId", 200),
     agentId,

package/src/routes.ts

@@ -5,7 +5,7 @@ import {
   getAgentTimeline,
   listAgents,
   listPendingReplyObligations,
-  findAgentsByCapability,
+  searchAgents,
   setStatus,
   setLabel,
   setTags,
@@ -124,6 +124,7 @@ import {
   setAgentProfile,
   setConfig,
   setStewardConfig,
+  spawnGrantForProfile,
   upsertManagedAgentState,
   updateManagedAgentState,
 } from "./config-store";
@@ -1240,6 +1241,12 @@ const postAgent: Handler = async (req) => {
   if (!parsed.ok) return error(parsed.error, parsed.status);
   try {
     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 constraints = getComponentAuth(req)?.constraints;
+    const lineage = constraints?.spawnedBy ?? constraints?.parentAgents?.[0];
+    if (lineage) input.spawnedBy = lineage;
     const existing = getAgent(input.id);
     const agent = upsertAgent(input);
     const policyName = metaString(agent.meta, "policyName");
@@ -1305,8 +1312,8 @@ const findAgents: Handler = (req) => {
   const url = new URL(req.url);
   const capability = url.searchParams.get("capability");
   if (!capability) return error("capability query param required");
-  const onlineOnly = url.searchParams.get("all") !== "true";
-  return json(findAgentsByCapability(capability, onlineOnly));
+  const includeAll = url.searchParams.get("all") === "true";
+  return json(searchAgents({ capability, status: includeAll ? "all" : "running" }));
 };
 
 const postRouteAdvice: Handler = async (req) => {
@@ -2538,6 +2545,8 @@ const postAgentSpawn: Handler = async (req) => {
     const cwd = cleanString(parsed.body.cwd, "cwd", { max: 500 });
     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),
@@ -2565,6 +2574,7 @@ const postAgentSpawn: Handler = async (req) => {
 	        workspaceMode,
 	        label,
 	        approvalMode,
+	        profile: profile || undefined,
 	        spawnRequestId: requestId,
 	        requestedBy: "dashboard",
 	        requestedAt: Date.now(),
@@ -2575,6 +2585,8 @@ const postAgentSpawn: Handler = async (req) => {
 	          label,
 	          spawnRequestId: requestId,
 	          createdBy: "dashboard",
+	          canSpawn: grant.canSpawn,
+	          maxSpawnedAgents: grant.maxSpawnedAgents,
 	        }),
 	      }),
 	    });

package/src/runtime-tokens.ts

@@ -1,7 +1,20 @@
-import { createToken, revokeToken } from "./token-db";
+import { createToken, getTokenProfile, revokeToken } from "./token-db";
 import { verifyComponentTokenAllowExpired } from "./security";
 import type { TokenRecord } from "./types";
 
+// Scopes that turn an agent's runtime token into a spawn-capable one (#221). Appended to the
+// provider-agent base scope only when the resolved profile permits (maxSpawnedAgents > 0).
+// Children never receive these (no grandchildren), so a child's token can never gate the
+// spawn/shutdown MCP tools open. Kept distinct from `agent:write` (self-management) on
+// purpose — that scope must stay for heartbeat/status without implying spawn rights.
+const SPAWN_SCOPES = ["command:spawn", "command:shutdown"] as const;
+
+function runnerScopeWithSpawn(canSpawn: boolean): string[] | undefined {
+  if (!canSpawn) return undefined; // undefined → createToken falls back to the profile's scope
+  const base = getTokenProfile("provider-agent")?.scope ?? [];
+  return [...base, ...SPAWN_SCOPES];
+}
+
 interface RuntimeTokenResult {
   token: string;
   record: TokenRecord;
@@ -76,6 +89,12 @@ 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;
+  /** Parent agent id — stamped so the child registers with an authoritative `spawnedBy`. */
+  spawnedBy?: string;
 }): RuntimeTokenResult {
   const subject = input.policyName
     ? `runner:policy:${input.policyName}`
@@ -86,11 +105,14 @@ export function issueRunnerRuntimeToken(input: {
     profileId: "provider-agent",
     sub: subject,
     role: "provider",
+    scope: runnerScopeWithSpawn(input.canSpawn ?? false),
     constraints: {
       orchestrators: [input.orchestratorId],
       cwdPrefixes: [input.cwd],
       ...(input.policyName ? { policies: [input.policyName] } : {}),
       ...(input.spawnRequestId ? { spawnRequestIds: [input.spawnRequestId] } : {}),
+      ...(input.canSpawn && input.maxSpawnedAgents ? { maxSpawnedAgents: input.maxSpawnedAgents } : {}),
+      ...(input.spawnedBy ? { spawnedBy: input.spawnedBy } : {}),
     },
     createdBy: input.createdBy ?? "runtime",
   });
@@ -204,6 +226,9 @@ export function runnerRuntimeTokenEnv(input: {
   policyName?: string;
   spawnRequestId?: string;
   createdBy?: string;
+  canSpawn?: boolean;
+  maxSpawnedAgents?: number;
+  spawnedBy?: string;
 }): Record<string, string> {
   const issued = issueRunnerRuntimeToken(input);
   return {

package/src/security.ts

@@ -438,8 +438,10 @@ function isTokenConstraints(value: unknown): value is TokenConstraints {
   for (const [key, item] of Object.entries(record)) {
     if (["terminalAttach", "logsRead", "canDelegate"].includes(key)) {
       if (typeof item !== "boolean") return false;
-    } else if (key === "cwd") {
+    } else if (key === "cwd" || key === "spawnedBy") {
       if (typeof item !== "string") return false;
+    } else if (key === "maxSpawnedAgents") {
+      if (typeof item !== "number") return false;
     } else if (!Array.isArray(item) || !item.every((entry) => typeof entry === "string")) {
       return false;
     }