agent-relay-server 0.20.0 → 0.22.0

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";
@@ -157,6 +158,7 @@ import type { ActivityEventInput, ActivityKind, AgentCard, AgentKind, AgentProfi
 import { getIntegrationTokens, INTEGRATION_RATE_LIMIT_PER_MINUTE, MAX_BODY_BYTES, VERSION, type IntegrationTokenConfig } from "./config";
 import { CONTRACT_VERSIONS, parseRuntimeCapabilities, parseRuntimeContracts, parseRuntimePackage, type RuntimeCapabilities, type RuntimeContracts, type RuntimePackageMetadata } from "./contracts";
 import { listHostDirectories } from "./agent-spawn";
+import { planSend } from "./agent-ref";
 import { defaultProviderConfig, loadProviderConfig, providerConfigPublic, writeProviderConfig } from "../runner/src/config";
 import type { ProviderConfig } from "../runner/src/adapter";
 import { type ProviderEffort } from "agent-relay-sdk/provider-catalog";
@@ -166,6 +168,14 @@ import { buildManagedSpawnParams, effectiveManagedPolicyWorkspaceMode } from "./
 import { buildSpawnCommand, generateSpawnRequestId, resolveSpawnModelParams, type SpawnModelParams } from "./spawn-command";
 import { requestWorkspaceMerge } from "./workspace-merge";
 import { claimMetadataPatch, workspaceActiveClaim } from "./workspace-claim";
+import {
+  applyWorkspaceAction,
+  buildWorkspaceCleanupCommand,
+  buildWorkspaceDepsRefreshCommand,
+  waitForWorkspaceStatus,
+  WORKSPACE_ACTIONS,
+} from "./workspace-actions";
+import { describeWorkspacePhase, landReceipt, TERMINAL_WORKSPACE_STATUSES } from "./workspace-phase";
 import type { WorkspaceDiagnostics, WorkspaceGitState, WorkspaceRecord } from "./types";
 import {
   getComponentAuth,
@@ -1240,6 +1250,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 +1321,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 +2554,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 +2583,7 @@ const postAgentSpawn: Handler = async (req) => {
 	        workspaceMode,
 	        label,
 	        approvalMode,
+	        profile: profile || undefined,
 	        spawnRequestId: requestId,
 	        requestedBy: "dashboard",
 	        requestedAt: Date.now(),
@@ -2575,6 +2594,8 @@ const postAgentSpawn: Handler = async (req) => {
 	          label,
 	          spawnRequestId: requestId,
 	          createdBy: "dashboard",
+	          canSpawn: grant.canSpawn,
+	          maxSpawnedAgents: grant.maxSpawnedAgents,
 	        }),
 	      }),
 	    });
@@ -3855,8 +3876,6 @@ const getWorkspaceDiff: Handler = (req, params) => {
   return proxyWorkspaceHostGet(params.id!, "/api/workspace/diff", patch === "0" ? { patch: "0" } : undefined);
 };
 
-const TERMINAL_WORKSPACE_STATUSES = new Set<WorkspaceStatus>(["cleaned", "merged", "abandoned"]);
-
 // Worktrees found on disk (agent/* branches) with no live workspace row — left
 // behind by crashes or failed cleanups. Probes each known repo's owning host
 // and subtracts active DB rows. Reclaim them via POST .../orphans/reclaim.
@@ -3935,59 +3954,8 @@ const postWorkspaceOrphanReclaim: Handler = async (req) => {
   }
 };
 
-// Build a `workspace.cleanup` command for a worktree's owning orchestrator. Shared
-// by the manual cleanup action and the cleanup-stale sweep (#208) so both resolve
-// the owner and shape params identically. Queues (no TTL) when the owner is offline;
-// hard-fails only when no orchestrator owns the path (DELETE is then the escape).
-function buildWorkspaceCleanupCommand(workspace: WorkspaceRecord, requestedBy: string): { ok: true; command: Command } | { ok: false; status: number; error: string } {
-  const owners = listOrchestrators().filter((candidate) => isPathWithinBase(workspace.sourceCwd, candidate.baseDir));
-  const owner = owners.find((candidate) => candidate.status === "online") ?? owners[0];
-  if (!owner) return { ok: false, status: 409, error: "no orchestrator owns this workspace path; use DELETE /api/workspaces/:id to purge the record" };
-  const command = createCommand({
-    type: "workspace.cleanup",
-    source: "system",
-    target: owner.agentId,
-    correlationId: workspace.id,
-    params: {
-      action: "cleanup",
-      workspaceId: workspace.id,
-      repoRoot: workspace.repoRoot,
-      worktreePath: workspace.worktreePath,
-      branch: workspace.branch,
-      requestedBy,
-      requestedAt: Date.now(),
-      deleteBranch: true,
-      queued: owner.status !== "online",
-    },
-  });
-  return { ok: true, command };
-}
-
-// Build a `workspace.deps-refresh` command for a worktree's owning orchestrator
-// (issue #51). Re-provisions deps the shared symlinked node_modules has gone stale
-// on, or — checkOnly — just reports staleness. Same owner-resolution as cleanup.
-function buildWorkspaceDepsRefreshCommand(workspace: WorkspaceRecord, requestedBy: string, checkOnly: boolean): { ok: true; command: Command } | { ok: false; status: number; error: string } {
-  const owners = listOrchestrators().filter((candidate) => isPathWithinBase(workspace.sourceCwd, candidate.baseDir));
-  const owner = owners.find((candidate) => candidate.status === "online") ?? owners[0];
-  if (!owner) return { ok: false, status: 409, error: "no online orchestrator owns this workspace path" };
-  const command = createCommand({
-    type: "workspace.deps-refresh",
-    source: "system",
-    target: owner.agentId,
-    correlationId: workspace.id,
-    params: {
-      action: "deps-refresh",
-      workspaceId: workspace.id,
-      repoRoot: workspace.repoRoot,
-      worktreePath: workspace.worktreePath,
-      checkOnly,
-      requestedBy,
-      requestedAt: Date.now(),
-      queued: owner.status !== "online",
-    },
-  });
-  return { ok: true, command };
-}
+// buildWorkspaceCleanupCommand / buildWorkspaceDepsRefreshCommand now live in
+// ./workspace-actions (shared with the relay_workspace_* MCP tools) — imported above.
 
 // Fetch + parse a workspace's live git state from its owning host, or report why
 // it's unavailable. Thin typed wrapper over the same host route the proxy uses.
@@ -4025,6 +3993,13 @@ function recommendWorkspaceAction(input: { workspace: WorkspaceRecord; ownerOnli
   if ((gitState.dirtyCount ?? 0) > 0) return { action: "review", confidence: "medium", reason: `${gitState.dirtyCount} uncommitted change(s)` };
   if (ahead === 0 || landed) {
     if (!ownerOnline) return { action: "cleanup", confidence: "high", reason: landed ? "work already landed; owner offline" : "no unmerged commits; owner offline" };
+    // Owner active but the workspace is awaiting attention with nothing to land (#230):
+    // landing it is a safe no-op that resolves it to terminal `merged`, clearing the
+    // queue (the host keeps a live owner's worktree). Otherwise there's genuinely
+    // nothing to do.
+    if (workspace.status === "review_requested" || workspace.status === "conflict") {
+      return { action: "merge", confidence: "high", reason: landed ? "work already landed; resolve the no-op" : "nothing to merge; resolve the no-op" };
+    }
     return { action: "none", confidence: "medium", reason: "nothing to merge; owner active" };
   }
   if (ownerOnline && workspace.status !== "review_requested" && workspace.status !== "conflict") {
@@ -4127,129 +4102,64 @@ const postWorkspaceAction: Handler = async (req, params) => {
     if (!isRecord(parsed.body)) return error("body required");
     const workspace = getWorkspace(params.id!);
     if (!workspace) return error("workspace not found", 404);
-    const action = optionalEnum(parsed.body.action, "action", ["status", "ready", "conflict-found", "request-review", "merge-plan", "merge", "abandon", "cleanup", "claim", "release-claim", "deps-refresh"] as const);
+    const action = optionalEnum(parsed.body.action, "action", WORKSPACE_ACTIONS);
     if (!action) return error("action required", 400);
     const agentId = cleanString(parsed.body.agentId, "agentId", { max: 240 });
-    const detail = cleanString(parsed.body.detail, "detail", { max: 4000 });
-    const metadata = cleanMeta(parsed.body.metadata) ?? {};
     const requiresCommand = action === "cleanup" || action === "merge";
-    // Shared-mode rows are occupancy markers with no worktree — there is nothing
-    // on disk to merge or clean. Reject host commands against them up front.
+    // Shared-mode rows are occupancy markers with no worktree — reject host commands
+    // up front, before authz, preserving the original 422-before-auth ordering.
     if (requiresCommand && (workspace.mode !== "isolated" || !workspace.worktreePath)) {
       return error(`workspace ${workspace.id} has no worktree to ${action}`, 422);
     }
     const denied = authorizeRoute(req, { scope: requiresCommand ? "command:write" : "agent:write", resource: { agentId, cwd: workspace.worktreePath } });
     if (denied) return denied;
-    if (action === "status") return json(workspace);
-    // Steward claim/lease (#208): a TTL'd metadata lease that auto-merge yields to,
-    // so deterministic landing can't race a steward mid-validation. No status change.
-    if (action === "claim" || action === "release-claim") {
-      const release = action === "release-claim";
-      const purpose = cleanString(parsed.body.purpose, "purpose", { max: 120 });
-      const updated = patchWorkspaceMetadata(workspace.id, claimMetadataPatch(release, agentId ?? "steward", purpose));
-      if (!updated) return error("workspace not found", 404);
-      auditEvent({
-        clientId: `workspace-${action}-${workspace.id}-${Date.now()}`,
-        kind: "state",
-        title: release ? "Workspace claim released" : "Workspace claimed",
-        body: detail ?? purpose ?? workspace.worktreePath,
-        meta: workspace.branch ?? workspace.id,
-        icon: "ti-lock",
-        view: "orchestrators",
-        agentId,
-        metadata: { action, workspaceId: workspace.id, repoRoot: workspace.repoRoot, ...authAuditMetadata(req) },
-      });
-      return json({ workspace: updated, claim: workspaceActiveClaim(updated) });
-    }
-    // Base merges go through the shared helper (lease + command + bind), the same
-    // path the auto-merge job uses, so both serialize per repo (issue #157).
-    if (action === "merge") {
-      const strategy = optionalEnum(parsed.body.strategy, "strategy", ["pr", "rebase-ff", "auto"] as const, "auto") as WorkspaceMergeStrategy;
-      const result = requestWorkspaceMerge(workspace, {
-        requestedBy: agentId ?? "dashboard",
-        strategy,
-        deleteBranch: parsed.body.deleteBranch !== false,
-        prTitle: cleanString(parsed.body.prTitle, "prTitle", { max: 240 }),
-        prBody: cleanString(parsed.body.prBody, "prBody", { max: 8000 }),
-        metadata: { ...metadata, ...(detail ? { detail } : {}), ...(agentId ? { updatedByAgentId: agentId } : {}) },
-      });
-      if (!result.ok) return error(result.error, result.status);
-      emitCommand(result.command);
-      auditEvent({
-        clientId: `workspace-merge-${workspace.id}-${Date.now()}`,
-        kind: "state",
-        title: "Workspace merge",
-        body: detail ?? workspace.worktreePath,
-        meta: workspace.branch ?? workspace.id,
-        icon: "ti-git-merge",
-        view: "orchestrators",
-        agentId,
-        metadata: { action: "merge", workspaceId: workspace.id, repoRoot: workspace.repoRoot, worktreePath: workspace.worktreePath, status: result.workspace.status, commandId: result.command.id, ...authAuditMetadata(req) },
-      });
-      return json({ workspace: result.workspace, command: result.command }, 202);
-    }
-    // Deps refresh (#51): self-service for the owning agent — re-provision deps the
-    // shared symlinked node_modules has gone stale on. Emits a host command but is
-    // authorized at agent:write (it only touches the agent's own worktree), so the
-    // agent can run it themselves the moment typecheck reports a missing module.
-    if (action === "deps-refresh") {
-      if (workspace.mode !== "isolated" || !workspace.worktreePath) {
-        return error(`workspace ${workspace.id} has no isolated worktree to refresh`, 422);
+
+    // status: optionally long-poll until the workspace transitions — after a `ready`,
+    // block until the auto-merge job lands it (→ merged/recycled-to-active) or it
+    // stalls into conflict/review_requested, instead of the caller busy-polling.
+    if (action === "status") {
+      if (parsed.body.wait === true) {
+        const timeoutSeconds = typeof parsed.body.timeoutSeconds === "number" && parsed.body.timeoutSeconds > 0 ? parsed.body.timeoutSeconds : undefined;
+        const waited = await waitForWorkspaceStatus(workspace.id, timeoutSeconds ? { timeoutMs: timeoutSeconds * 1000 } : {});
+        if (!waited.workspace) return error("workspace not found", 404);
+        const landed = waited.transitioned ? landReceipt(waited.fromStatus, waited.workspace) : null;
+        // Mirror the relay_workspace_status MCP tool: bare record (legacy fields)
+        // plus the directive projection + land receipt so the CLI `--wait` and any
+        // HTTP caller get the same legible answer.
+        return json({
+          workspace: waited.workspace,
+          guidance: describeWorkspacePhase(waited.workspace),
+          ...(landed ? { landed } : {}),
+          fromStatus: waited.fromStatus,
+          transitioned: waited.transitioned,
+          timedOut: waited.timedOut,
+        });
       }
-      const checkOnly = parsed.body.checkOnly === true;
-      const built = buildWorkspaceDepsRefreshCommand(workspace, agentId ?? "agent", checkOnly);
-      if (!built.ok) return error(built.error, built.status);
-      emitCommand(built.command);
-      auditEvent({
-        clientId: `workspace-deps-refresh-${workspace.id}-${Date.now()}`,
-        kind: "state",
-        title: checkOnly ? "Workspace deps check" : "Workspace deps refresh",
-        body: detail ?? workspace.worktreePath,
-        meta: workspace.branch ?? workspace.id,
-        icon: "ti-package",
-        view: "orchestrators",
-        agentId,
-        metadata: { action, workspaceId: workspace.id, repoRoot: workspace.repoRoot, worktreePath: workspace.worktreePath, checkOnly, commandId: built.command.id, ...authAuditMetadata(req) },
-      });
-      return json({ workspace, command: built.command }, 202);
-    }
-    const statusByAction: Record<string, WorkspaceStatus | undefined> = {
-      status: undefined,
-      ready: "ready",
-      "conflict-found": "conflict",
-      "request-review": "review_requested",
-      "merge-plan": "merge_planned",
-      abandon: "abandoned",
-      cleanup: "cleanup_requested",
-    };
-    const updated = updateWorkspaceStatus(workspace.id, statusByAction[action]!, {
-      ...metadata,
-      ...(detail ? { detail } : {}),
-      ...(agentId ? { updatedByAgentId: agentId } : {}),
-      lastWorkspaceAction: action,
-      lastWorkspaceActionAt: Date.now(),
-    });
-    if (!updated) return error("workspace not found", 404);
-    let command: Command | undefined;
-    if (requiresCommand) {
-      // Only `cleanup` reaches here — `merge` returned early via the shared helper.
-      const built = buildWorkspaceCleanupCommand(workspace, agentId ?? "dashboard");
-      if (!built.ok) return error(built.error, built.status);
-      command = built.command;
-      emitCommand(command);
+      return json(workspace);
     }
-    auditEvent({
-      clientId: `workspace-${action}-${workspace.id}-${Date.now()}`,
-      kind: "state",
-      title: `Workspace ${action}`,
-      body: detail ?? workspace.worktreePath,
-      meta: workspace.branch ?? workspace.id,
-      icon: action === "cleanup" ? "ti-trash" : action === "conflict-found" ? "ti-alert-triangle" : "ti-git-branch",
-      view: "orchestrators",
+
+    // Everything else delegates to the shared core (one home, shared with the
+    // relay_workspace_* MCP tools); the core self-audits and returns any command to
+    // emit, mirroring requestWorkspaceMerge's "caller emits" contract.
+    const result = applyWorkspaceAction(workspace, {
+      action,
       agentId,
-      metadata: { action, workspaceId: workspace.id, repoRoot: workspace.repoRoot, worktreePath: workspace.worktreePath, status: updated.status, commandId: command?.id, ...authAuditMetadata(req) },
+      detail: cleanString(parsed.body.detail, "detail", { max: 4000 }),
+      metadata: cleanMeta(parsed.body.metadata) ?? {},
+      strategy: optionalEnum(parsed.body.strategy, "strategy", ["pr", "rebase-ff", "auto"] as const, "auto") as WorkspaceMergeStrategy,
+      deleteBranch: typeof parsed.body.deleteBranch === "boolean" ? parsed.body.deleteBranch : undefined,
+      prTitle: cleanString(parsed.body.prTitle, "prTitle", { max: 240 }),
+      prBody: cleanString(parsed.body.prBody, "prBody", { max: 8000 }),
+      purpose: cleanString(parsed.body.purpose, "purpose", { max: 120 }),
+      checkOnly: parsed.body.checkOnly === true,
+      auditMetadata: authAuditMetadata(req),
     });
-    return json({ workspace: updated, command }, requiresCommand ? 202 : 200);
+    if (!result.ok) return error(result.error, result.httpStatus);
+    if (result.command) emitCommand(result.command);
+    const payload: Record<string, unknown> = { workspace: result.workspace };
+    if (result.command) payload.command = result.command;
+    if (result.claim !== undefined) payload.claim = result.claim;
+    return json(payload, result.httpStatus);
   } catch (e) {
     if (e instanceof ValidationError) return error(e.message, 400);
     throw e;
@@ -5273,11 +5183,25 @@ const postMessage: Handler = async (req) => {
       resource: { 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.
     const bypassKinds = ["system", "control", "session"];
-    if (isDirectTarget(input.to) && !bypassKinds.includes(input.kind ?? "")) {
+    if (!bypassKinds.includes(input.kind ?? "")) {
+      const plan = planSend(input.to, listAgents());
+      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);

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;
     }