agent-relay-server 0.32.1 → 0.32.3

package/src/routes/agents-spawn.ts

@@ -0,0 +1,274 @@
+// Auto-split from routes.ts (#299). Domain: agents-spawn.
+import { APPROVAL_MODES, SPAWN_PROVIDERS, VALID_EFFORTS, VALID_WORKSPACE_MODES, isRecord } from "agent-relay-sdk";
+import { McpNotFoundError, selectSpawnOrchestrator } from "../mcp";
+import { VALID_AGENT_STATUSES, auditEvent, authAuditMetadata, authorizeRoute, emitCommand, error, json, metaString, parseBody, spawnRequestId, type Handler } from "./_shared";
+import { ValidationError, getAgent, getOrchestrator, listAgents, resolveQueuedPolicyMessages, upsertAgent } from "../db";
+import { buildSpawnCommand, resolveSpawnModelParams, type SpawnModelParams } from "../spawn-command";
+import { cleanMeta, cleanNullableString, cleanString, cleanStringArray, optionalEnum } from "../validation";
+import { createCommand } from "../commands-db";
+import { emitAgentStatus, emitManagedAgentStateChanged, emitMessageAvailable, emitMessageDeliveryUpdated, emitNewMessage } from "../sse";
+import { getAgentProfile, getManagedAgentState, updateManagedAgentState } from "../config-store";
+import { getCompactionWatch } from "../compaction-watch";
+import { getComponentAuth } from "../security";
+import { isPathWithinBase } from "../utils";
+import { listHostDirectories } from "../agent-spawn";
+import { rankRouteCandidates, type RouteAdvisorInput } from "../context-router";
+import { runnerRuntimeTokenEnv } from "../runtime-tokens";
+import { type AgentKind, type RegisterAgentInput, type SpawnApprovalMode, type SpawnProvider, type WorkspaceMode } from "../types";
+import { type ProviderEffort } from "agent-relay-sdk/provider-catalog";
+
+const VALID_AGENT_KINDS = ["provider", "channel", "orchestrator", "system", "user"] as const;
+
+function normalizeAgentInput(body: unknown): RegisterAgentInput {
+  if (!isRecord(body)) throw new ValidationError("JSON object body required");
+  const status = cleanString(body.status, "status", { max: 20 });
+  if (status && !VALID_AGENT_STATUSES.includes(status as any)) {
+    throw new ValidationError(`status must be one of: ${VALID_AGENT_STATUSES.join(", ")}`);
+  }
+  if (body.ready !== undefined && typeof body.ready !== "boolean") {
+    throw new ValidationError("ready must be a boolean");
+  }
+
+  const input: RegisterAgentInput = {
+    id: cleanString(body.id, "id", { required: true, max: 200 })!,
+    name: cleanString(body.name, "name", { required: true, max: 200 })!,
+    kind: optionalEnum(body.kind, "kind", VALID_AGENT_KINDS) as AgentKind | undefined,
+    status: status as RegisterAgentInput["status"] | undefined,
+    ready: body.ready as boolean | undefined,
+  };
+
+  const label = cleanNullableString(body.label, "label", 120);
+  if (label !== undefined) input.label = label;
+  const tags = cleanStringArray(body.tags, "tags", { itemMax: 80, maxItems: 50 });
+  if (tags) input.tags = tags;
+  const capabilities = cleanStringArray(body.capabilities, "capabilities", { itemMax: 80, maxItems: 50 });
+  if (capabilities) input.capabilities = capabilities;
+  const machine = cleanString(body.machine, "machine", { max: 120 });
+  if (machine) input.machine = machine;
+  const rig = cleanString(body.rig, "rig", { max: 120 });
+  if (rig) input.rig = rig;
+  const instanceId = cleanString(body.instanceId, "instanceId", { max: 200 });
+  if (instanceId) input.instanceId = instanceId;
+  if (isRecord(body.providerCapabilities)) input.providerCapabilities = body.providerCapabilities as unknown as RegisterAgentInput["providerCapabilities"];
+  if (isRecord(body.context)) input.context = body.context as unknown as RegisterAgentInput["context"];
+  const meta = cleanMeta(body.meta);
+  if (meta) input.meta = meta;
+
+  return input;
+}
+
+export const postAgent: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(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");
+    const spawnRequestId = metaString(agent.meta, "spawnRequestId");
+    const tmuxSession = metaString(agent.meta, "tmuxSession");
+    if (policyName && spawnRequestId) {
+      const state = getManagedAgentState(policyName);
+      if (state?.spawnRequestId === spawnRequestId) {
+        const updatedState = updateManagedAgentState(policyName, {
+          status: "running",
+          agentId: agent.id,
+          tmuxSession: tmuxSession ?? state.tmuxSession,
+          healthySince: Date.now(),
+          lastError: undefined,
+        });
+        if (updatedState) emitManagedAgentStateChanged(policyName, updatedState as unknown as Record<string, unknown>);
+        const available = resolveQueuedPolicyMessages(policyName, agent.id);
+        if (available.length) {
+          emitMessageAvailable(policyName, agent.id, available);
+          for (const message of available) {
+            emitNewMessage(message);
+            // queued → pending flips delivery_status; the dashboard dedups message.new
+            // by id (the message already shows as "queued"), so without an explicit
+            // delivery_updated the badge stays stale until the next poll (#265).
+            emitMessageDeliveryUpdated(message);
+          }
+        }
+      }
+    }
+    emitAgentStatus(agent.id);
+    // A real PreCompact / SessionStart(clear) hook reports progress via the
+    // agent's timelineEvent — clears any pending stall watch for this agent.
+    // timelineEvent is latched, so pass its timestamp: only a fresh event
+    // (stamped after the watch armed) counts as this command's real start.
+    const timelineEvent = isRecord(agent.meta?.timelineEvent) ? agent.meta.timelineEvent : undefined;
+    const timelineStatus = metaString(timelineEvent, "status");
+    if (timelineStatus) {
+      const timelineTs = typeof timelineEvent?.timestamp === "number" ? timelineEvent.timestamp : undefined;
+      getCompactionWatch().noteTimelineStatus(agent.id, timelineStatus, timelineTs);
+    }
+    if (!existing) {
+      auditEvent({
+        clientId: "server-agent-" + agent.id + "-registered",
+        kind: "state",
+        title: "Agent registered",
+        body: agent.name,
+        meta: agent.id,
+        icon: "ti-robot",
+        view: "agents",
+        agentId: agent.id,
+      });
+    }
+    return json(agent, 201);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const postRouteAdvice: Handler = async (req) => {
+  const parsed = await parseBody<RouteAdvisorInput>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const body = isRecord(parsed.body) ? parsed.body : {};
+  const limit = typeof body.limit === "number" ? body.limit : undefined;
+  const maxUtilization = typeof body.maxUtilization === "number" ? body.maxUtilization : undefined;
+  if (limit !== undefined && (!Number.isSafeInteger(limit) || limit <= 0)) return error("limit must be a positive integer");
+  if (maxUtilization !== undefined && (maxUtilization < 0 || maxUtilization > 1)) return error("maxUtilization must be between 0 and 1");
+  return json({
+    candidates: rankRouteCandidates(listAgents(), {
+      text: typeof body.text === "string" ? body.text : undefined,
+      target: typeof body.target === "string" ? body.target : undefined,
+      capabilities: Array.isArray(body.capabilities) ? body.capabilities.filter((item): item is string => typeof item === "string") : undefined,
+      tags: Array.isArray(body.tags) ? body.tags.filter((item): item is string => typeof item === "string") : undefined,
+      maxUtilization,
+      preferWarmContext: typeof body.preferWarmContext === "boolean" ? body.preferWarmContext : undefined,
+      limit,
+    }),
+  });
+};
+
+export 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) as SpawnProvider | undefined;
+    if (!provider) return error("provider required");
+    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 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,
+        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 + "-" + 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, 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;
+  }
+};
+
+export const getHostDirectories: Handler = (req) => {
+  try {
+    const url = new URL(req.url);
+    const path = cleanString(url.searchParams.get("path") ?? undefined, "path", { max: 500 });
+    return json(listHostDirectories(path));
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    if (e instanceof Error) return error(e.message, 400);
+    throw e;
+  }
+};
+
+function cleanSpawnSelection(body: Record<string, unknown>, provider: SpawnProvider): SpawnModelParams {
+  const model = cleanString(body.model, "model", { max: 120 });
+  const effort = optionalEnum(body.effort, "effort", VALID_EFFORTS) as ProviderEffort | undefined;
+  return resolveSpawnModelParams(provider, model, effort);
+}
+
+function validateSpawnSelectionForOrchestrator(
+  orch: NonNullable<ReturnType<typeof getOrchestrator>>,
+  provider: SpawnProvider,
+  body: Record<string, unknown>,
+): SpawnModelParams | Response {
+  if (!orch.providers.includes(provider)) {
+    return error(`orchestrator does not have provider available: ${provider}`, 409);
+  }
+  try {
+    return cleanSpawnSelection(body, provider);
+  } catch (e) {
+    if (e instanceof Error) return error(e.message, 400);
+    throw e;
+  }
+}

package/src/routes/agents.ts

@@ -0,0 +1,251 @@
+// Auto-split from routes.ts (#299). Domain: agents.
+import { VALID_AGENT_STATUSES, agentSessionStatus, auditEvent, error, json, memoryContext, memoryErrorResponse, normalizeAgentSessionGuard, parseBody, parseId, type Handler } from "./_shared";
+import { ValidationError, deleteAgent, getAgent, getAgentTimeline, heartbeat, listAgents, listArtifactsForEntity, listContextSnapshots, listPendingReplyObligations, markReady, searchAgents, setLabel, setStatus, setTags, validateAgentSession } from "../db";
+import { attachBranchState, attachBranchStates } from "../agent-branch-state";
+import { cleanStringArray } from "../validation";
+import { clearActiveMemories, memoryBroker } from "../memory-service";
+import { emitAgentRemoved, emitAgentStatus } from "../sse";
+import { getCompactionWatch } from "../compaction-watch";
+import { isRecord } from "agent-relay-sdk";
+import { type AgentCard } from "../types";
+
+type AgentActivityState = {
+  key: "available" | "busy" | "not-ready" | "offline";
+  title: string;
+  icon: string;
+};
+
+function agentActivityState(agent?: Pick<AgentCard, "ready" | "status"> | null): AgentActivityState | null {
+  if (!agent) return null;
+  if (agent.status === "offline") return { key: "offline", title: "Agent offline", icon: "ti-plug-off" };
+  if (!agent.ready) return { key: "not-ready", title: "Agent not ready", icon: "ti-loader" };
+  if (agent.status === "busy") return { key: "busy", title: "Agent busy", icon: "ti-activity" };
+  return { key: "available", title: "Agent available", icon: "ti-circle-check" };
+}
+
+function auditAgentStateTransition(agentId: string, before: AgentCard | null | undefined, after: AgentCard | null | undefined): void {
+  const previous = agentActivityState(before);
+  const next = agentActivityState(after);
+  if (!next || previous?.key === next.key) return;
+  auditEvent({
+    clientId: "server-agent-" + agentId + "-state-" + next.key + "-" + Date.now(),
+    kind: "state",
+    title: next.title,
+    meta: agentId,
+    icon: next.icon,
+    view: "agents",
+    agentId,
+  });
+}
+
+export const getAgents: Handler = (req) => {
+  const url = new URL(req.url);
+  const tag = url.searchParams.get("tag") ?? undefined;
+  const machine = url.searchParams.get("machine") ?? undefined;
+  const status = url.searchParams.get("status") ?? undefined;
+  return json(attachBranchStates(listAgents({ tag, machine, status })));
+};
+
+export 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 includeAll = url.searchParams.get("all") === "true";
+  return json(searchAgents({ capability, status: includeAll ? "all" : "running" }));
+};
+
+export const getAgentById: Handler = (_req, params) => {
+  const agent = getAgent(params.id!);
+  return agent ? json(attachBranchState(agent)) : error("agent not found", 404);
+};
+
+export const getAgentReplyObligations: Handler = (_req, params) => {
+  const agent = getAgent(params.id!);
+  return agent ? json(listPendingReplyObligations(agent.id)) : error("agent not found", 404);
+};
+
+export const getAgentContextSnapshots: Handler = (req, params) => {
+  const agent = getAgent(params.id!);
+  if (!agent) return error("agent not found", 404);
+  const url = new URL(req.url);
+  const sinceRaw = url.searchParams.get("since");
+  const limitRaw = url.searchParams.get("limit");
+  const since = sinceRaw ? Number(sinceRaw) : undefined;
+  const limit = limitRaw ? Number(limitRaw) : undefined;
+  if (sinceRaw && (!Number.isFinite(since) || since! < 0)) return error("since must be a positive timestamp");
+  if (limitRaw && (!Number.isSafeInteger(limit) || limit! <= 0)) return error("limit must be a positive integer");
+  return json(listContextSnapshots(agent.id, { since, limit }));
+};
+
+export const getAgentTimelineRoute: Handler = (req, params) => {
+  // Deliberately no agent-existence check: the timeline's main value is debugging
+  // an agent that already died or was removed.
+  const url = new URL(req.url);
+  const sinceRaw = url.searchParams.get("since");
+  const limitRaw = url.searchParams.get("limit");
+  const since = sinceRaw ? Number(sinceRaw) : undefined;
+  const limit = limitRaw ? Number(limitRaw) : undefined;
+  if (sinceRaw && (!Number.isFinite(since) || since! < 0)) return error("since must be a positive timestamp");
+  if (limitRaw && (!Number.isSafeInteger(limit) || limit! <= 0)) return error("limit must be a positive integer");
+  return json(getAgentTimeline(params.id!, { since, limit }));
+};
+
+export const getAgentActiveMemories: Handler = async (req, params) => {
+  const agent = getAgent(params.id!);
+  if (!agent) return error("agent not found", 404);
+  try {
+    const capabilities = await memoryBroker.capabilities();
+    if (!capabilities.activeList || !memoryBroker.listActive) {
+      return json({ agentId: agent.id, supported: false, memories: [] });
+    }
+    const memories = await memoryBroker.listActive(agent.id, memoryContext(req));
+    return json({ agentId: agent.id, supported: true, memories, total: memories.length });
+  } catch (e) {
+    return memoryErrorResponse(e);
+  }
+};
+
+export const deleteAgentActiveMemories: Handler = async (req, params) => {
+  const agent = getAgent(params.id!);
+  if (!agent) return error("agent not found", 404);
+  try {
+    const cleared = await clearActiveMemories(agent.id, "manual", memoryContext(req));
+    return json({ agentId: agent.id, supported: cleared, cleared });
+  } catch (e) {
+    return memoryErrorResponse(e);
+  }
+};
+
+export const getMessageArtifactsRoute: Handler = (_req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid message id");
+  return json(listArtifactsForEntity("message", id));
+};
+
+export const getTaskArtifactsRoute: Handler = (_req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid task id");
+  return json(listArtifactsForEntity("task", id));
+};
+
+export const patchAgentStatus: Handler = async (req, params) => {
+  const parsed = await parseBody<{ status: string }>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const body = parsed.body;
+  if (!body?.status) return error("status required");
+  const valid = VALID_AGENT_STATUSES;
+  if (!valid.includes(body.status as any)) return error(`status must be one of: ${valid.join(", ")}`);
+  try {
+    const guard = normalizeAgentSessionGuard(req, body);
+    const session = validateAgentSession(params.id!, guard);
+    if (!session.ok) return error(session.error!, agentSessionStatus(session.error));
+    const before = getAgent(params.id!);
+    if (!setStatus(params.id!, body.status as (typeof VALID_AGENT_STATUSES)[number], guard)) return error("agent not found", 404);
+    auditAgentStateTransition(params.id!, before, getAgent(params.id!));
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+  emitAgentStatus(params.id!);
+  return json({ ok: true });
+};
+
+export const postHeartbeat: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const guard = normalizeAgentSessionGuard(req, parsed.body);
+    const session = validateAgentSession(params.id!, guard);
+    if (!session.ok) return error(session.error!, agentSessionStatus(session.error));
+    return heartbeat(params.id!, guard) ? json({ ok: true }) : error("agent not found", 404);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const patchAgentLabel: Handler = async (req, params) => {
+  const parsed = await parseBody<{ label: string | null }>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const body = parsed.body;
+  if (body === null || !("label" in body)) return error("label field required (string or null)");
+  const before = getAgent(params.id!);
+  if (!setLabel(params.id!, body.label)) return error("agent not found", 404);
+  emitAgentStatus(params.id!);
+  const after = getAgent(params.id!);
+  if ((before?.label ?? null) !== (after?.label ?? null)) {
+    auditEvent({
+      clientId: "server-agent-" + params.id! + "-label-" + Date.now(),
+      kind: "state",
+      title: after?.label ? "Agent label set" : "Agent label cleared",
+      body: after?.label ?? before?.label ?? "",
+      meta: params.id!,
+      icon: "ti-tag",
+      view: "chat",
+      agentId: params.id!,
+      metadata: { field: "label", previous: before?.label ?? null, next: after?.label ?? null },
+    });
+  }
+  return json({ ok: true });
+};
+
+export const patchAgentTags: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const tags = isRecord(parsed.body) ? cleanStringArray(parsed.body.tags, "tags", { itemMax: 80, maxItems: 50 }) : undefined;
+    if (!tags) return error("tags field required");
+    const before = getAgent(params.id!);
+    const agent = setTags(params.id!, tags);
+    if (!agent) return error("agent not found", 404);
+    emitAgentStatus(params.id!);
+    if (JSON.stringify(before?.tags ?? []) !== JSON.stringify(agent.tags ?? [])) {
+      auditEvent({
+        clientId: "server-agent-" + params.id! + "-tags-" + Date.now(),
+        kind: "state",
+        title: "Agent tags updated",
+        body: (agent.tags || []).join(", "),
+        meta: params.id!,
+        icon: "ti-tags",
+        view: "chat",
+        agentId: params.id!,
+        metadata: { field: "tags", previous: before?.tags ?? [], next: agent.tags ?? [] },
+      });
+    }
+    return json(agent);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const patchAgentReady: Handler = async (req, params) => {
+  const parsed = await parseBody<{ ready: boolean }>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const body = parsed.body;
+  if (body === null || typeof body.ready !== "boolean") return error("ready field required (boolean)");
+  try {
+    const guard = normalizeAgentSessionGuard(req, body);
+    const session = validateAgentSession(params.id!, guard);
+    if (!session.ok) return error(session.error!, agentSessionStatus(session.error));
+    const before = getAgent(params.id!);
+    if (!markReady(params.id!, body.ready, guard)) return error("agent not found", 404);
+    auditAgentStateTransition(params.id!, before, getAgent(params.id!));
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+  emitAgentStatus(params.id!);
+  return json({ ok: true });
+};
+
+export const deleteAgentById: Handler = (_req, params) => {
+  const result = deleteAgent(params.id!);
+  if (!result.ok) {
+    const status = result.error === "agent not found" ? 404 : 400;
+    return error(result.error!, status);
+  }
+  emitAgentRemoved(params.id!);
+  getCompactionWatch().forget(params.id!);
+  return json({ ok: true });
+};