agent-relay-server 0.50.0 → 0.51.0

package/src/db/schema.ts

@@ -104,7 +104,7 @@ export function initDb(path: string = "agent-relay.db"): Database {
       epoch INTEGER NOT NULL DEFAULT 0,
       provider_capabilities TEXT,
       context_state TEXT,
-      meta TEXT NOT NULL DEFAULT '{}',
+      meta TEXT NOT NULL DEFAULT '{}', lifecycle TEXT NOT NULL DEFAULT 'persistent',
       spawned_by TEXT,
       team_id TEXT,
       last_seen INTEGER NOT NULL,

package/src/db/teams.ts

@@ -31,6 +31,46 @@ export interface TeamDissolveInput {
   landsClean?: boolean;
 }
 
+type OutcomeBucket = NonNullable<Team["outcomeStatus"]> | "unknown";
+
+interface TeamOutcomeRow {
+  id: string;
+  title: string | null;
+  outcome_status: Team["outcomeStatus"] | null;
+  outcome_summary: string | null;
+  composition: string | null;
+  wall_clock_ms: number | null;
+  dissolved_at: number | null;
+}
+
+export interface TeamOutcomeCompositionAggregate {
+  shape: string;
+  members: Array<{ provider: string; model: string }>;
+  count: number;
+  successCount: number;
+  successRate: number;
+  avgWallClockMs: number | null;
+}
+
+export interface TeamOutcomeRecent {
+  id: string;
+  title?: string;
+  outcome: Team["outcomeStatus"] | null;
+  outcomeSummary?: string;
+  durationMs: number | null;
+  memberCount: number;
+  dissolvedAt: number | null;
+}
+
+export interface TeamOutcomeAggregates {
+  totals: {
+    total: number;
+    byOutcomeStatus: Record<OutcomeBucket, number>;
+  };
+  compositionShapes: TeamOutcomeCompositionAggregate[];
+  recent: TeamOutcomeRecent[];
+}
+
 export function teamId(): string {
   return `team_${randomUUID().replace(/-/g, "").slice(0, 16)}`;
 }
@@ -153,6 +193,86 @@ function compositionForMembers(members: AgentCard[]): string {
   })));
 }
 
+function compositionShape(composition: string | null): { key: string; members: Array<{ provider: string; model: string }>; memberCount: number } {
+  if (!composition) return { key: "empty", members: [], memberCount: 0 };
+  try {
+    const parsed = JSON.parse(composition) as unknown;
+    if (!Array.isArray(parsed)) return { key: "unknown/unknown", members: [{ provider: "unknown", model: "unknown" }], memberCount: 0 };
+    const seen = new Map<string, { provider: string; model: string }>();
+    for (const raw of parsed) {
+      const member = raw && typeof raw === "object" ? raw as Record<string, unknown> : {};
+      const provider = typeof member.provider === "string" && member.provider.trim() ? member.provider.trim() : "unknown";
+      const model = typeof member.model === "string" && member.model.trim() ? member.model.trim() : "unknown";
+      seen.set(`${provider}/${model}`, { provider, model });
+    }
+    const members = [...seen.values()].sort((a, b) => a.provider.localeCompare(b.provider) || a.model.localeCompare(b.model));
+    return { key: members.length ? members.map((member) => `${member.provider}/${member.model}`).join(", ") : "empty", members, memberCount: parsed.length };
+  } catch {
+    return { key: "unknown/unknown", members: [{ provider: "unknown", model: "unknown" }], memberCount: 0 };
+  }
+}
+
+export function getTeamOutcomeAggregates(input: { recentLimit?: number } = {}): TeamOutcomeAggregates {
+  const recentLimit = Math.max(1, Math.min(50, input.recentLimit ?? 12));
+  const rows = getDb().query(`
+    SELECT id, title, outcome_status, outcome_summary, composition, wall_clock_ms, dissolved_at
+    FROM teams
+    WHERE status = 'dissolved'
+    ORDER BY dissolved_at DESC, updated_at DESC, id DESC
+  `).all() as TeamOutcomeRow[];
+
+  const byOutcomeStatus: Record<OutcomeBucket, number> = { success: 0, partial: 0, failed: 0, unknown: 0 };
+  const byShape = new Map<string, {
+    members: Array<{ provider: string; model: string }>;
+    count: number;
+    successCount: number;
+    durationTotal: number;
+    durationCount: number;
+  }>();
+  const recent: TeamOutcomeRecent[] = [];
+
+  for (const row of rows) {
+    byOutcomeStatus[row.outcome_status ?? "unknown"] += 1;
+    const shape = compositionShape(row.composition);
+    const aggregate = byShape.get(shape.key) ?? { members: shape.members, count: 0, successCount: 0, durationTotal: 0, durationCount: 0 };
+    aggregate.count += 1;
+    if (row.outcome_status === "success") aggregate.successCount += 1;
+    if (row.wall_clock_ms !== null) {
+      aggregate.durationTotal += row.wall_clock_ms;
+      aggregate.durationCount += 1;
+    }
+    byShape.set(shape.key, aggregate);
+    if (recent.length < recentLimit) {
+      recent.push({
+        id: row.id,
+        ...(row.title ? { title: row.title } : {}),
+        outcome: row.outcome_status,
+        ...(row.outcome_summary ? { outcomeSummary: row.outcome_summary } : {}),
+        durationMs: row.wall_clock_ms,
+        memberCount: shape.memberCount,
+        dissolvedAt: row.dissolved_at,
+      });
+    }
+  }
+
+  const compositionShapes = [...byShape.entries()]
+    .map(([shape, aggregate]) => ({
+      shape,
+      members: aggregate.members,
+      count: aggregate.count,
+      successCount: aggregate.successCount,
+      successRate: aggregate.count === 0 ? 0 : aggregate.successCount / aggregate.count,
+      avgWallClockMs: aggregate.durationCount === 0 ? null : Math.round(aggregate.durationTotal / aggregate.durationCount),
+    }))
+    .sort((a, b) => b.count - a.count || b.successRate - a.successRate || a.shape.localeCompare(b.shape));
+
+  return {
+    totals: { total: rows.length, byOutcomeStatus },
+    compositionShapes,
+    recent,
+  };
+}
+
 export function dissolveTeam(teamId: string, input: TeamDissolveInput = {}): Team {
   const existing = getTeam(teamId);
   if (!existing) throw new ValidationError(`team ${teamId} not found`);

package/src/index.ts

@@ -10,6 +10,7 @@ import { getLifecycleManager } from "./lifecycle-manager";
 import { getCompactionWatch } from "./compaction-watch";
 import { getConfig, setConfig } from "./config-store";
 import { startConnectorStatusPoller } from "./connectors";
+import { startPlanLiveBindings } from "./services/plan-live-bindings";
 import { resolve, sep } from "path";
 import { gzipSync, brotliCompressSync, constants as zlibConstants } from "node:zlib";
 import {
@@ -73,6 +74,7 @@ function startServer(): void {
 
   assertSafeNetworkConfig(HOST);
   initDb(DB_PATH);
+  startPlanLiveBindings();
   getLifecycleManager().start();
   getCompactionWatch().start();
   reconcileRelayVersion();

package/src/maintenance.ts

@@ -62,6 +62,7 @@ import {
 import { notifySystemMessage } from "./notify";
 import { pruneExpiredTokenRecords } from "./token-db";
 import { dissolveTeamById } from "./services/team";
+import { reapTransientAgents, resetTransientTrackerForTests } from "./services/transient-agent-reaper";
 import type { Command, MaintenanceJob, MaintenanceJobRun } from "./types";
 
 const DEFAULT_TIMEOUT_MS = 30_000;
@@ -134,9 +135,7 @@ const orphanReapEnabled = () => process.env.AGENT_RELAY_ORPHAN_REAP !== "0";
 // orchestratorId + session identity -> when we first saw it orphaned (and last reaped).
 const orphanTracker = new Map<string, { firstOrphanedAt: number; lastReapAt?: number }>();
 
-export function resetOrphanTrackerForTests(): void {
-  orphanTracker.clear();
-}
+export function resetOrphanTrackerForTests(): void { orphanTracker.clear(); resetTransientTrackerForTests(); }
 
 interface MaintenanceJobDefinition {
   id: string;
@@ -300,6 +299,7 @@ const definitions: MaintenanceJobDefinition[] = [
     runOnStart: false,
     handler: reapOrphanedSessions,
   },
+  { id: "transient-agent-reaper", title: "Transient agent reaper", description: "Cleanly shut down transient spawned agents once they are idle and any isolated branch work has landed.", intervalMs: REAP_INTERVAL_MS, runOnStart: false, handler: reapTransientAgents },
   {
     id: "team-reap",
     title: "Team lifecycle close-out",

package/src/mcp-agent-action.ts

@@ -0,0 +1,45 @@
+import { cleanEnum, cleanString } from "./validation";
+import { AgentActionTargetError, dispatchAgentAction, type AgentAction } from "./services/agent-action";
+import { authContextFromMcp } from "./services/auth-context";
+import { ShutdownAuthError, ShutdownTargetError } from "./services/shutdown-agent";
+import { McpAuthError, McpNotFoundError } from "./mcp-errors";
+
+type McpAuthLike = {
+  actor: string;
+  kind: "component" | "integration" | "server";
+  scopes?: string[];
+  component?: Parameters<typeof authContextFromMcp>[0]["component"];
+};
+
+export const AGENT_ACTION_TOOL = {
+  name: "relay_agent_action",
+  description: "Compact, clear context, or directly inject a prompt into one of your live spawned children. Gated exactly like relay_shutdown_agent: an agent caller may target only its OWN spawned children by agentId; admin tokens keep full reach.",
+  requiredScopes: ["command:shutdown"],
+  inputSchema: {
+    type: "object",
+    properties: {
+      agentId: { type: "string" },
+      action: { type: "string", enum: ["compact", "clearContext", "inject"] },
+      message: { type: "string", description: "Required when action is inject." },
+    },
+    required: ["agentId", "action"],
+    additionalProperties: false,
+  },
+};
+
+export function relayAgentAction(auth: McpAuthLike, args: Record<string, unknown>): Record<string, unknown> {
+  try {
+    const result = dispatchAgentAction({
+      agentId: cleanString(args.agentId, "agentId", { required: true, max: 240 })!,
+      action: cleanEnum(args.action, "action", ["compact", "clearContext", "inject"] as const) as AgentAction,
+      message: cleanString(args.message, "message", { max: 16_000 }),
+      requestedVia: "mcp",
+      requestedBy: auth.actor,
+    }, authContextFromMcp(auth));
+    return { ok: true, action: result.action, command: result.command };
+  } catch (e) {
+    if (e instanceof ShutdownAuthError) throw new McpAuthError(e.message);
+    if (e instanceof ShutdownTargetError || e instanceof AgentActionTargetError) throw new McpNotFoundError(e.message);
+    throw e;
+  }
+}

package/src/mcp.ts

@@ -49,21 +49,17 @@ import { ServiceAuthError } from "./services/errors";
 import { PLAN_TOOLS, relayPlanTool } from "./mcp-plan-tools";
 import { TEAM_TOOLS, relayTeamTool } from "./mcp-team-tools";
 import { BLACKBOARD_TOOLS, relayBlackboardTool } from "./mcp-blackboard-tools";
-import type { ActivityKind, ArtifactKind, ArtifactSensitivity, AttachmentRef, Command, SendMessageInput, Message, SpawnApprovalMode, SpawnProvider, WorkspaceAutoMergePolicy, WorkspaceMergeStrategy, WorkspaceMode, WorkspaceRecord } from "./types";
+import { AGENT_ACTION_TOOL, relayAgentAction } from "./mcp-agent-action";
+import type { ActivityKind, AgentLifecycle, ArtifactKind, ArtifactSensitivity, AttachmentRef, Command, SendMessageInput, Message, SpawnApprovalMode, SpawnProvider, WorkspaceAutoMergePolicy, WorkspaceMergeStrategy, WorkspaceMode, WorkspaceRecord } from "./types";
 import { LAND_STRATEGIES, applyWorkspaceAction, waitForWorkspaceStatus, type WorkspaceAction } from "./workspace-actions";
 import { AUTO_MERGE_POLICIES } from "./workspace-merge";
 import { describeWorkspacePhase, landReceipt, readyContract, worktreeMcpInstructions } from "./workspace-phase";
 import { type ProviderEffort } from "agent-relay-sdk/provider-catalog";
-import { errMessage, isRecord, stringValue, SPAWN_PROVIDERS, APPROVAL_MODES, VALID_EFFORTS, VALID_WORKSPACE_MODES } from "agent-relay-sdk";
+import { errMessage, isRecord, stringValue, SPAWN_PROVIDERS, APPROVAL_MODES, VALID_AGENT_LIFECYCLES, VALID_EFFORTS, VALID_WORKSPACE_MODES } from "agent-relay-sdk";
 
 type JsonRpcId = string | number | null;
 
-type JsonRpcRequest = {
-  jsonrpc?: "2.0";
-  id?: JsonRpcId;
-  method?: string;
-  params?: unknown;
-};
+type JsonRpcRequest = { jsonrpc?: "2.0"; id?: JsonRpcId; method?: string; params?: unknown };
 
 type McpAuthContext = {
   actor: string;
@@ -92,8 +88,6 @@ 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 TOOLS: ToolDefinition[] = [
   {
     name: "relay_send_message",
@@ -320,6 +314,7 @@ const TOOLS: ToolDefinition[] = [
         providerArgs: { type: "array", items: { type: "string" } },
         policyName: { type: "string" },
         spawnRequestId: { type: "string" },
+        lifecycle: { type: "string", enum: VALID_AGENT_LIFECYCLES, description: "Lifecycle mode. `persistent` keeps the agent until explicitly stopped. `transient` lets Relay auto-shutdown the child after it is idle and, for isolated workers, after its branch has landed. Default: persistent." },
         workspaceMode: { type: "string", enum: VALID_WORKSPACE_MODES, description: "Git workspace for the worker. `isolated` = its own worktree on an `agent/session-*` branch off main that auto-lands when ready (delegate a unit of work, get a branch worker). `shared` = edits your live checkout (a sidecar). `inherit` = let the orchestrator decide. DEFAULT for agent-initiated spawns is `isolated` so a delegated worker lands to main instead of editing your tree; pass `shared`/`inherit` to override." },
         waitForRegistrationMs: { type: "integer", minimum: 0, maximum: 30000, description: "How long to wait for the spawned agent to register before returning, so the response carries its resolved agent id (default 8000; 0 = return immediately with just spawnRequestId)." },
       },
@@ -355,6 +350,7 @@ const TOOLS: ToolDefinition[] = [
       additionalProperties: false,
     },
   },
+  AGENT_ACTION_TOOL,
   {
     name: "relay_workspace_status",
     description: "Get your isolated workspace's lifecycle status (active/ready/conflict/review_requested/merged/...). With wait:true this BLOCKS until the status changes — use it after relay_workspace_ready to wait for the auto-merge to land your branch on main (status leaves 'ready' → merged/recycled-to-active with a fresh rebased branch) or to surface a conflict/review_requested the steward couldn't auto-resolve. Defaults to the workspace you own; pass workspaceId to target another.",
@@ -566,6 +562,7 @@ async function callTool(auth: McpAuthContext, params: unknown): Promise<Record<s
     else if (name === "relay_spawn_agent") result = await relaySpawnAgent(auth, args);
     else if (name === "relay_spawn_targets") result = relaySpawnTargets(auth);
     else if (name === "relay_shutdown_agent") result = relayShutdownAgent(auth, args);
+    else if (name === "relay_agent_action") result = relayAgentAction(auth, args);
     else if (name === "relay_workspace_status") result = await relayWorkspaceStatus(auth, args);
     else if (name === "relay_workspace_list") result = relayWorkspaceList(auth, args);
     else if (name === "relay_workspace_ready") result = relayWorkspaceMutation(auth, "ready", args);
@@ -866,6 +863,7 @@ async function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknow
     effort: optionalEnum(args.effort, "effort", VALID_EFFORTS) as ProviderEffort | undefined,
     approvalMode: optionalEnum(args.approvalMode, "approvalMode", APPROVAL_MODES) as SpawnApprovalMode | undefined,
     workspaceMode: optionalEnum(args.workspaceMode, "workspaceMode", VALID_WORKSPACE_MODES) as WorkspaceMode | undefined,
+    lifecycle: (optionalEnum(args.lifecycle, "lifecycle", VALID_AGENT_LIFECYCLES) as AgentLifecycle | undefined) ?? "persistent",
     label: optionalString(args.label, "label", 120),
     policyName: optionalString(args.policyName, "policyName", 120),
     profile: optionalString(args.profile, "profile", 120),

package/src/routes/index.ts

@@ -31,7 +31,7 @@ import { getBlackboardEntryRoute, getBlackboardRoute } from "./blackboard";
 import { getRecipeByName, getRecipeInstanceArtifacts, getRecipeInstanceById, getRecipeInstances, getRecipes, postRecipeInstanceArtifacts, postRecipeStart, postRecipeStop } from "./recipes";
 import { getStewardConfigRoute, getWorkspaceConfigRoute, putStewardConfigRoute, putWorkspaceConfigRoute } from "./steward";
 import { getTaskById, getTaskEvents, getTasks, patchTaskStatus, postClaimTask, postRenewTaskClaim } from "./tasks";
-import { getMyTeamRoute, getTeamsRoute, postMyTeamDissolveRoute, putMyTeamBriefRoute } from "./teams";
+import { getMyTeamRoute, getTeamOutcomesRoute, getTeamsRoute, postMyTeamDissolveRoute, putMyTeamBriefRoute } from "./teams";
 import { postTeamDissolveByIdRoute } from "./teams";
 import { postMcp } from "../mcp";
 import { postOrchestratorBootstrap, postOrchestratorBootstrapExchange } from "./orchestrator-bootstrap";
@@ -139,6 +139,7 @@ const routes: Route[] = [
 
   route("POST", "/api/system/broadcast", postSystemBroadcast),
   route("GET", "/api/teams", getTeamsRoute),
+  route("GET", "/api/teams/outcomes", getTeamOutcomesRoute),
   route("GET", "/api/teams/me", getMyTeamRoute),
   route("PUT", "/api/teams/me/brief", putMyTeamBriefRoute),
   route("POST", "/api/teams/me/dissolve", postMyTeamDissolveRoute),

package/src/routes/teams.ts

@@ -1,9 +1,9 @@
 import { McpAuthError, McpNotFoundError } from "../mcp-errors";
 import { authContextFromRequest } from "../services/auth-context";
-import { getTeam, listAllTeams, ValidationError } from "../db";
+import { getTeam, getTeamOutcomeAggregates, listAllTeams, ValidationError } from "../db";
 import { dissolveCallerTeam, dissolveTeamById, getCallerTeam, setCallerTeamBrief, TeamAuthError, TeamNotFoundError, type TeamDissolveServiceInput } from "../services/team";
 import { cleanString, optionalEnum } from "../validation";
-import { authorizeRoute, error, json, parseBody, type Handler } from "./_shared";
+import { authorizeRoute, error, json, parseBody, parseQueryInt, type Handler } from "./_shared";
 import type { Team } from "../types";
 
 const OUTCOME_STATUSES = ["success", "partial", "failed"] as const;
@@ -50,6 +50,18 @@ export const getTeamsRoute: Handler = (req) => {
   }
 };
 
+export const getTeamOutcomesRoute: Handler = (req) => {
+  const denied = authorizeRoute(req, { scope: "system:admin" });
+  if (denied) return denied;
+  try {
+    const recentLimit = parseQueryInt(new URL(req.url).searchParams.get("recentLimit"), { min: 1, max: 50, clamp: true }) ?? undefined;
+    if (Number.isNaN(recentLimit)) return error("invalid recentLimit", 400);
+    return json(getTeamOutcomeAggregates({ recentLimit }));
+  } catch (err) {
+    return routeError(err);
+  }
+};
+
 export const putMyTeamBriefRoute: Handler = async (req) => {
   const parsed = await parseBody<Record<string, unknown>>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);

package/src/services/agent-action.ts

@@ -0,0 +1,138 @@
+import { createCommand } from "../commands-db";
+import { ValidationError, createActivityEvent, getAgent, sendMessage } from "../db";
+import { emitCommandEvent } from "../command-events";
+import { emitActivityEvent, emitNewMessage } from "../sse";
+import { authorizeShutdown, ShutdownAuthError, ShutdownTargetError } from "./shutdown-agent";
+import type { AuthContext } from "./auth-context";
+import type { AgentCard, Command } from "../types";
+
+export type AgentAction = "compact" | "clearContext" | "inject";
+
+export interface AgentActionInput {
+  agentId: string;
+  action: AgentAction;
+  message?: string;
+  requestedVia: "mcp";
+  requestedBy?: string;
+}
+
+export interface AgentActionResult {
+  action: AgentAction;
+  command: Command;
+}
+
+export class AgentActionTargetError extends Error {}
+
+function commandType(action: AgentAction): "agent.compact" | "agent.clearContext" | "prompt.inject" {
+  if (action === "compact") return "agent.compact";
+  if (action === "clearContext") return "agent.clearContext";
+  return "prompt.inject";
+}
+
+function title(action: AgentAction): string {
+  if (action === "compact") return "Agent compaction requested";
+  if (action === "clearContext") return "Agent context clear requested";
+  return "Agent prompt injected";
+}
+
+function icon(action: AgentAction): string {
+  if (action === "compact") return "ti-fold";
+  if (action === "clearContext") return "ti-clear-all";
+  return "ti-message-bolt";
+}
+
+function compactMemoryParams(agent: AgentCard): Record<string, unknown> {
+  const alwaysReload = agent.tags
+    .filter((tag) => tag.startsWith("memory-reload:"))
+    .map((tag) => tag.slice("memory-reload:".length).trim())
+    .filter(Boolean);
+  if (!alwaysReload.length) return {};
+  return { memory: { alwaysReload } };
+}
+
+function assertSupported(agent: AgentCard, action: AgentAction): void {
+  if (agent.id === "user" || agent.id === "system" || agent.meta?.kind === "channel" || agent.tags.includes("channel")) {
+    throw new ValidationError("agent cannot receive lifecycle actions");
+  }
+  if (agent.status === "offline") throw new ValidationError("agent is offline");
+  if (action === "compact" && agent.providerCapabilities?.context?.compact !== true) {
+    throw new ValidationError("agent does not support compact");
+  }
+  if (action === "clearContext" && agent.providerCapabilities?.context?.clear !== true) {
+    throw new ValidationError("agent does not support clearContext");
+  }
+  if (action === "inject" && agent.providerCapabilities?.liveSession?.inject !== true) {
+    throw new ValidationError("agent does not support inject");
+  }
+}
+
+function sessionMessageForInject(agentId: string, ctx: AuthContext, body: string) {
+  const from = ctx.callerAgentId && getAgent(ctx.callerAgentId) ? ctx.callerAgentId : "system";
+  const message = sendMessage({
+    from,
+    to: agentId,
+    kind: "session",
+    body,
+  });
+  emitNewMessage(message);
+  return message;
+}
+
+export function dispatchAgentAction(input: AgentActionInput, ctx: AuthContext): AgentActionResult {
+  const agent = getAgent(input.agentId);
+  if (!agent) throw new AgentActionTargetError(`agent ${input.agentId} not found`);
+
+  try {
+    authorizeShutdown(ctx, { agentId: input.agentId, requestedVia: input.requestedVia });
+  } catch (e) {
+    if (e instanceof ShutdownAuthError || e instanceof ShutdownTargetError) throw e;
+    throw e;
+  }
+  assertSupported(agent, input.action);
+
+  const body = input.action === "inject"
+    ? (input.message?.trim() || (() => { throw new ValidationError("message is required for inject"); })())
+    : undefined;
+  const sessionMessage = body ? sessionMessageForInject(agent.id, ctx, body) : undefined;
+  const command = createCommand({
+    type: commandType(input.action),
+    source: "system",
+    target: agent.id,
+    correlationId: typeof agent.meta?.spawnRequestId === "string" ? agent.meta.spawnRequestId : undefined,
+    params: {
+      action: input.action,
+      agentId: agent.id,
+      ...(typeof agent.meta?.sessionName === "string" ? { sessionName: agent.meta.sessionName } : {}),
+      ...(typeof agent.meta?.tmuxSession === "string" ? { tmuxSession: agent.meta.tmuxSession } : {}),
+      ...(typeof agent.meta?.policyName === "string" ? { policyName: agent.meta.policyName } : {}),
+      ...(typeof agent.meta?.spawnRequestId === "string" ? { spawnRequestId: agent.meta.spawnRequestId } : {}),
+      ...(input.action === "compact" ? compactMemoryParams(agent) : {}),
+      ...(body ? { body, messageId: sessionMessage!.id } : {}),
+      requestedBy: input.requestedBy ?? ctx.callerAgentId ?? ctx.actor.id,
+      requestedVia: input.requestedVia,
+      requestedAt: Date.now(),
+    },
+  });
+  emitCommandEvent(command, "command.requested");
+  const event = createActivityEvent({
+    clientId: `server-agent-${agent.id}-action-${input.action}-${command.id}`,
+    kind: "state",
+    title: title(input.action),
+    body: input.action,
+    meta: agent.id,
+    icon: icon(input.action),
+    view: "agents",
+    agentId: agent.id,
+    messageId: sessionMessage?.id,
+    metadata: {
+      action: input.action,
+      commandId: command.id,
+      actor: ctx.actor.id,
+      actorKind: ctx.actor.kind,
+      requestedVia: input.requestedVia,
+      source: "server",
+    },
+  });
+  emitActivityEvent(event);
+  return { action: input.action, command };
+}

package/src/services/plan-graph.ts

@@ -1,9 +1,9 @@
 import { isRecord } from "agent-relay-sdk";
-import { createPlanRow, deletePlan, getAgent, getEntry, getPlan, getPlanByTeam, getPlanByThread, planThreadExists, replacePlan, ValidationError } from "../db";
+import { createPlanRow, deletePlan, getAgent, getEntry, getPlan, getPlanByTeam, getPlanByThread, listPlansWithBoundOwner, planThreadExists, replacePlan, ValidationError } from "../db";
 import { emitRelayEvent } from "../events";
 import { cleanString, cleanStringArray, optionalEnum } from "../validation";
 import type { AuthContext } from "./auth-context";
-import type { Plan, PlanEdge, PlanNode, PlanOwnerRef, PlanStatus } from "../types";
+import type { AgentCard, Plan, PlanEdge, PlanNode, PlanOwnerRef, PlanStatus } from "../types";
 
 export const PLAN_STATUSES = ["pending", "in-progress", "landed", "blocked"] as const;
 
@@ -86,10 +86,22 @@ function cleanBlackboardRefs(value: unknown, planTeamId?: string): string[] | un
   return refs;
 }
 
-function cleanStatusSource(value: unknown): "manual" {
+function cleanStatusSource(value: unknown): PlanNode["statusSource"] {
   const statusSource = optionalEnum(value, "statusSource", ["manual", "bound"] as const, "manual");
-  if (statusSource !== "manual") throw new ValidationError("statusSource must be manual in this slice");
-  return "manual";
+  return statusSource;
+}
+
+function boundStatusForAgent(agent: Pick<AgentCard, "status"> | null | undefined): PlanStatus | undefined {
+  if (!agent) return undefined;
+  if (agent.status === "busy") return "in-progress";
+  return "pending";
+}
+
+function applyBoundStatus(node: PlanNode): PlanNode {
+  if (node.statusSource !== "bound") return node;
+  const agentId = node.ownerRef?.agentId;
+  if (!agentId) throw new ValidationError("bound plan nodes require ownerRef.agentId");
+  return { ...node, status: boundStatusForAgent(getAgent(agentId)) ?? "pending" };
 }
 
 function cleanNode(input: PlanNodeInput, planTeamId?: string): PlanNode {
@@ -99,17 +111,18 @@ function cleanNode(input: PlanNodeInput, planTeamId?: string): PlanNode {
   const lane = cleanString(input.lane, "node.lane", { max: 120 });
   const refs = cleanRefs(input.refs);
   const blackboardRefs = cleanBlackboardRefs(input.blackboardRefs, planTeamId);
-  return {
+  const statusSource = cleanStatusSource(input.statusSource);
+  return applyBoundStatus({
     id: cleanString(input.id, "node.id", { required: true, max: 120 })!,
     label: cleanString(input.label, "node.label", { required: true, max: 240 })!,
     ...(scopeBlurb ? { scopeBlurb } : {}),
     ...(ownerRef ? { ownerRef } : {}),
     ...(lane ? { lane } : {}),
     status: optionalEnum(input.status, "node.status", PLAN_STATUSES, "pending") as PlanStatus,
-    statusSource: cleanStatusSource(input.statusSource),
+    statusSource,
     ...(refs ? { refs } : {}),
     ...(blackboardRefs ? { blackboardRefs } : {}),
-  };
+  });
 }
 
 function cleanNodes(value: unknown, planTeamId?: string): PlanNode[] {
@@ -233,8 +246,8 @@ export function updatePlanNode(planId: string, nodeId: string, patch: PlanNodePa
   const plan = existingPlan(planId);
   const existing = plan.nodes.find((node) => node.id === nodeId);
   if (!existing) throw new ValidationError(`node ${nodeId} not found`);
-  if (patch.statusSource !== undefined) cleanStatusSource(patch.statusSource);
-  const next: PlanNode = {
+  const statusSource = patch.statusSource !== undefined ? cleanStatusSource(patch.statusSource) : existing.statusSource;
+  const base: PlanNode = {
     ...existing,
     ...(patch.label !== undefined ? { label: cleanString(patch.label, "label", { required: true, max: 240 })! } : {}),
     ...(patch.scopeBlurb !== undefined ? optionalProp("scopeBlurb", cleanString(patch.scopeBlurb, "scopeBlurb", { max: 2000 })) : {}),
@@ -243,8 +256,9 @@ export function updatePlanNode(planId: string, nodeId: string, patch: PlanNodePa
     ...(patch.status !== undefined ? { status: optionalEnum(patch.status, "status", PLAN_STATUSES) as PlanStatus } : {}),
     ...(patch.refs !== undefined ? optionalProp("refs", cleanRefs(patch.refs)) : {}),
     ...(patch.blackboardRefs !== undefined ? optionalProp("blackboardRefs", cleanBlackboardRefs(patch.blackboardRefs, plan.teamId)) : {}),
-    statusSource: "manual",
+    statusSource,
   };
+  const next = applyBoundStatus(base);
   const updated = replacePlan({ ...plan, nodes: plan.nodes.map((node) => node.id === nodeId ? next : node) }, actorId(ctx));
   emitPlan("plan.changed", updated, actorId(ctx));
   return updated;
@@ -294,6 +308,30 @@ export function deletePlanGraph(planId: string, ctx: AuthContext): { id: string;
   return { id: plan.id, deleted: true };
 }
 
+export function updateBoundPlanNodesForAgent(agentId: string, status: PlanStatus, actor = "server"): Plan[] {
+  const updated: Plan[] = [];
+  for (const plan of listPlansWithBoundOwner(agentId)) {
+    let changed = false;
+    const nodes = plan.nodes.map((node) => {
+      if (node.statusSource !== "bound" || node.ownerRef?.agentId !== agentId) return node;
+      if (node.status === "landed") return node;
+      if (node.status === status) return node;
+      changed = true;
+      return { ...node, status };
+    });
+    if (!changed) continue;
+    const next = replacePlan({ ...plan, nodes }, actor);
+    emitPlan("plan.changed", next, actor);
+    updated.push(next);
+  }
+  return updated;
+}
+
+export function updateBoundPlanNodesFromAgent(agentId: string, actor = "server"): Plan[] {
+  const status = boundStatusForAgent(getAgent(agentId));
+  return status ? updateBoundPlanNodesForAgent(agentId, status, actor) : [];
+}
+
 export function getPlanGraph(input: { planId?: unknown; threadId?: unknown; teamId?: unknown; channel?: unknown }): Plan | null {
   const planId = cleanString(input.planId, "planId", { max: 120 });
   if (planId) return getPlan(planId);