agent-relay-server 0.32.1 → 0.32.3

package/src/routes/pairs.ts

@@ -0,0 +1,197 @@
+// Auto-split from routes.ts (#299). Domain: pairs.
+import { MAX_BODY_BYTES } from "../config";
+import { ValidationError, acceptPair, createPair, endPair, getPair, listPairs, rejectPair, sendPairMessage } from "../db";
+import { auditEvent, error, json, parseBody, type Handler } from "./_shared";
+import { cleanMeta, cleanString, cleanTtlMs } from "../validation";
+import { emitNewMessage } from "../sse";
+import { isRecord } from "agent-relay-sdk";
+import { type CreatePairInput, type PairActionInput, type PairMessageInput, type PairStatus } from "../types";
+
+const VALID_PAIR_STATUSES = ["pending", "active", "ended", "rejected", "expired"] as const;
+
+function normalizeCreatePairInput(body: unknown): CreatePairInput {
+  if (!isRecord(body)) throw new ValidationError("JSON object body required");
+  return {
+    from: cleanString(body.from, "from", { required: true, max: 200 })!,
+    target: cleanString(body.target, "target", { required: true, max: 200 })!,
+    objective: cleanString(body.objective, "objective", { max: 2000 }),
+    ttlMs: cleanTtlMs(body.ttlMs),
+    meta: cleanMeta(body.meta),
+  };
+}
+
+function normalizePairActionInput(body: unknown): PairActionInput {
+  if (!isRecord(body)) throw new ValidationError("JSON object body required");
+  return {
+    agentId: cleanString(body.agentId, "agentId", { required: true, max: 200 })!,
+    reason: cleanString(body.reason, "reason", { max: 1000 }),
+  };
+}
+
+function normalizePairMessageInput(body: unknown): PairMessageInput {
+  if (!isRecord(body)) throw new ValidationError("JSON object body required");
+  return {
+    from: cleanString(body.from, "from", { required: true, max: 200 })!,
+    body: cleanString(body.body, "body", { required: true, max: MAX_BODY_BYTES })!,
+    subject: cleanString(body.subject, "subject", { max: 200 }),
+  };
+}
+
+function pairErrorStatus(code: string): number {
+  if (code === "not_found") return 404;
+  if (code === "busy") return 409;
+  if (code === "ambiguous") return 409;
+  if (code === "forbidden") return 403;
+  return 400;
+}
+
+function pairError(result: { error: string; code: string; matches?: unknown[]; busy?: unknown[] }): Response {
+  return json({
+    error: result.error,
+    ...(result.matches ? { matches: result.matches } : {}),
+    ...(result.busy ? { busy: result.busy } : {}),
+  }, pairErrorStatus(result.code));
+}
+
+export const postPair: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const result = createPair(normalizeCreatePairInput(parsed.body));
+    if (!result.ok) return pairError(result);
+    emitNewMessage(result.invite);
+    auditEvent({
+      clientId: "server-pair-" + result.pair.id + "-invited",
+      kind: "pair",
+      title: "Pair invited",
+      body: result.pair.objective,
+      meta: `${result.pair.requesterId} <-> ${result.pair.targetId}`,
+      icon: "ti-link-plus",
+      view: "pairs",
+      pairId: result.pair.id,
+      agentId: result.pair.requesterId,
+    });
+    return json({ pair: result.pair, invite: result.invite }, 201);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const getPairs: Handler = (req) => {
+  const url = new URL(req.url);
+  const status = url.searchParams.get("status") ?? undefined;
+  if (status && !VALID_PAIR_STATUSES.includes(status as any)) {
+    return error(`status must be one of: ${VALID_PAIR_STATUSES.join(", ")}`);
+  }
+  return json(listPairs({
+    agentId: url.searchParams.get("agent") ?? undefined,
+    status: status as PairStatus | undefined,
+  }));
+};
+
+export const getPairById: Handler = (_req, params) => {
+  const pair = getPair(params.id!);
+  return pair ? json(pair) : error("pair not found", 404);
+};
+
+export const postAcceptPair: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const result = acceptPair(params.id!, normalizePairActionInput(parsed.body));
+    if (!result.ok) return pairError(result);
+    for (const notice of result.notices) emitNewMessage(notice);
+    auditEvent({
+      clientId: "server-pair-" + result.pair.id + "-accepted",
+      kind: "pair",
+      title: "Pair accepted",
+      body: result.pair.objective,
+      meta: `${result.pair.requesterId} <-> ${result.pair.targetId}`,
+      icon: "ti-link",
+      view: "pairs",
+      pairId: result.pair.id,
+      agentId: result.pair.targetId,
+    });
+    return json(result.pair);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const postRejectPair: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const result = rejectPair(params.id!, normalizePairActionInput(parsed.body));
+    if (!result.ok) return pairError(result);
+    emitNewMessage(result.notice);
+    auditEvent({
+      clientId: "server-pair-" + result.pair.id + "-rejected",
+      kind: "pair",
+      title: "Pair rejected",
+      body: result.pair.objective,
+      meta: `${result.pair.requesterId} <-> ${result.pair.targetId}`,
+      icon: "ti-x",
+      view: "pairs",
+      pairId: result.pair.id,
+      agentId: result.pair.targetId,
+    });
+    return json(result.pair);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const postHangupPair: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const result = endPair(params.id!, normalizePairActionInput(parsed.body));
+    if (!result.ok) return pairError(result);
+    if (result.notice) emitNewMessage(result.notice);
+    auditEvent({
+      clientId: "server-pair-" + result.pair.id + "-ended-" + Date.now(),
+      kind: "pair",
+      title: "Pair ended",
+      body: result.pair.objective,
+      meta: result.pair.endedBy ? "by " + result.pair.endedBy : `${result.pair.requesterId} <-> ${result.pair.targetId}`,
+      icon: "ti-phone-off",
+      view: "pairs",
+      pairId: result.pair.id,
+      agentId: result.pair.endedBy,
+    });
+    return json(result.pair);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const postPairMessage: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const result = sendPairMessage(params.id!, normalizePairMessageInput(parsed.body));
+    if (!result.ok) return pairError(result);
+    emitNewMessage(result.message);
+    auditEvent({
+      clientId: "server-pair-message-" + result.message.id,
+      kind: "pair",
+      title: "Pair message sent",
+      body: result.message.subject || result.message.body,
+      meta: "from " + result.message.from,
+      icon: "ti-messages",
+      view: "pairs",
+      messageId: result.message.id,
+      pairId: result.pair.id,
+      agentId: result.message.from,
+    });
+    return json({ pair: result.pair, message: result.message }, 201);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};

package/src/routes/provider-config.ts

@@ -0,0 +1,112 @@
+// Auto-split from routes.ts (#299). Domain: provider-config.
+import { ValidationError, listOrchestrators } from "../db";
+import { applyCommandToRecipe } from "../recipe-runner";
+import { cleanString, cleanStringArray, optionalEnum } from "../validation";
+import { defaultProviderConfig, loadProviderConfig, providerConfigPublic, writeProviderConfig } from "../../runner/src/config";
+import { deleteCommand, getCommand } from "../commands-db";
+import { effectiveProviderCatalogList } from "../provider-catalog-store";
+import { emitCommand, error, json, parseBody, type Handler } from "./_shared";
+import { isRecord } from "agent-relay-sdk";
+import { type ProviderConfig } from "../../runner/src/adapter";
+
+const VALID_PROVIDER_CONFIGS = ["claude", "codex"] as const;
+
+export const getProvidersRoute: Handler = () => {
+  return json({
+    catalog: effectiveProviderCatalogList(),
+    orchestrators: listOrchestrators().map((orchestrator) => ({
+      id: orchestrator.id,
+      hostname: orchestrator.hostname,
+      status: orchestrator.status,
+      providers: orchestrator.providers,
+      providerStatus: orchestrator.providerStatus ?? [],
+      checkedAt: orchestrator.providerStatus?.reduce((latest, status) => Math.max(latest, status.checkedAt), 0) ?? 0,
+    })),
+  });
+};
+
+export const getProviderConfigsRoute: Handler = () => {
+  return json(Object.fromEntries(VALID_PROVIDER_CONFIGS.map((provider) => {
+    const config = loadProviderConfig(provider);
+    return [provider, providerConfigPublic(config)];
+  })));
+};
+
+export const getProviderConfigRoute: Handler = (_req, params) => {
+  const provider = optionalEnum(params.provider, "provider", VALID_PROVIDER_CONFIGS);
+  if (!provider) return error("provider required");
+  return json(providerConfigPublic(loadProviderConfig(provider)));
+};
+
+export const putProviderConfigRoute: Handler = async (req, params) => {
+  const provider = optionalEnum(params.provider, "provider", VALID_PROVIDER_CONFIGS);
+  if (!provider) return error("provider required");
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) return error("provider config body must be an object");
+    const defaults = defaultProviderConfig(provider);
+    const headless = isRecord(parsed.body.headless) ? parsed.body.headless : {};
+    const config: ProviderConfig = {
+      command: cleanString(parsed.body.command, "command", { required: true, max: 500 })!,
+      defaultArgs: cleanStringArray(parsed.body.defaultArgs, "defaultArgs", { itemMax: 80, maxItems: 50 }) ?? defaults.defaultArgs,
+      env: cleanEnvRecord(parsed.body.env),
+      pluginDirs: cleanStringArray(parsed.body.pluginDirs, "pluginDirs", { itemMax: 80, maxItems: 50 }) ?? defaults.pluginDirs,
+      defaultCapabilities: cleanStringArray(parsed.body.defaultCapabilities, "defaultCapabilities", { itemMax: 80, maxItems: 50 }) ?? defaults.defaultCapabilities,
+      defaultApprovalMode: cleanString(parsed.body.defaultApprovalMode, "defaultApprovalMode", { max: 80 }) ?? defaults.defaultApprovalMode,
+      defaultTags: cleanStringArray(parsed.body.defaultTags, "defaultTags", { itemMax: 80, maxItems: 50 }) ?? defaults.defaultTags,
+      chatCaptureMode: (optionalEnum(parsed.body.chatCaptureMode, "chatCaptureMode", ["final", "full"]) ?? defaults.chatCaptureMode) as "final" | "full",
+      headless: {
+        tmuxPrefix: cleanString(headless.tmuxPrefix, "headless.tmuxPrefix", { max: 120 }) ?? defaults.headless.tmuxPrefix,
+        shutdownTimeoutMs: cleanPositiveInt(headless.shutdownTimeoutMs, "headless.shutdownTimeoutMs") ?? defaults.headless.shutdownTimeoutMs,
+      },
+    };
+    return json(providerConfigPublic(writeProviderConfig(provider, config)));
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const postProviderConfigTestRoute: Handler = async (_req, params) => {
+  const provider = optionalEnum(params.provider, "provider", VALID_PROVIDER_CONFIGS);
+  if (!provider) return error("provider required");
+  const config = loadProviderConfig(provider);
+  const proc = Bun.spawn(["bash", "-lc", `command -v "$1"`, "bash", config.command], {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [exitCode, stdout, stderr] = await Promise.all([
+    proc.exited,
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  return json({ ok: exitCode === 0, command: config.command, path: stdout.trim(), error: stderr.trim() }, exitCode === 0 ? 200 : 422);
+};
+
+function cleanEnvRecord(value: unknown): Record<string, string> {
+  if (value === undefined) return {};
+  if (!isRecord(value)) throw new ValidationError("env must be an object");
+  const env: Record<string, string> = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (typeof item !== "string") throw new ValidationError(`env.${key} must be a string`);
+    env[key] = item;
+  }
+  return env;
+}
+
+function cleanPositiveInt(value: unknown, field: string): number | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) throw new ValidationError(`${field} must be a positive integer`);
+  return value;
+}
+
+export const deleteCommandById: Handler = (_req, params) => {
+  if (!deleteCommand(params.id!)) return error("command not found or cannot be canceled", 404);
+  const command = getCommand(params.id!);
+  if (command) {
+    applyCommandToRecipe(command);
+    emitCommand(command);
+  }
+  return json({ ok: true });
+};

package/src/routes/recipes.ts

@@ -0,0 +1,113 @@
+// Auto-split from routes.ts (#299). Domain: recipes.
+import { ValidationError, listArtifactsForEntity } from "../db";
+import { auditEvent, cleanAttachmentRefs, emitCommand, error, json, parseBody, type Handler } from "./_shared";
+import { cleanString } from "../validation";
+import { getRecipe, listRecipes } from "../recipe-loader";
+import { getRecipeInstance, listRecipeInstances, startRecipe, stopRecipe } from "../recipe-runner";
+import { isRecord } from "agent-relay-sdk";
+import { linkRecipeArtifacts } from "../recipe-db";
+
+export const getRecipes: Handler = () => {
+  return json(listRecipes().map((loaded) => ({
+    name: loaded.name,
+    source: loaded.source,
+    path: loaded.path,
+    recipe: loaded.recipe,
+  })));
+};
+
+export const getRecipeByName: Handler = (_req, params) => {
+  const recipe = getRecipe(params.name!);
+  return recipe ? json(recipe) : error("recipe not found", 404);
+};
+
+export const getRecipeInstances: Handler = (req) => {
+  const url = new URL(req.url);
+  const status = url.searchParams.get("status") ?? undefined;
+  return json(listRecipeInstances(status as any));
+};
+
+export const getRecipeInstanceById: Handler = (_req, params) => {
+  const instance = getRecipeInstance(params.id!);
+  return instance ? json(instance) : error("recipe instance not found", 404);
+};
+
+export const postRecipeStart: 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("recipe name required");
+    const name = cleanString(parsed.body.name ?? parsed.body.recipe, "name", { required: true, max: 120 })!;
+    const cwd = cleanString(parsed.body.cwd, "cwd", { max: 500 });
+    const orchestratorId = cleanString(parsed.body.orchestratorId, "orchestratorId", { max: 120 });
+    const startedBy = cleanString(parsed.body.startedBy, "startedBy", { max: 120 }) ?? "api";
+    const attachments = cleanAttachmentRefs(parsed.body.attachments ?? parsed.body.artifacts, "attachments") ?? [];
+    const result = startRecipe({ name, cwd, orchestratorId, startedBy, attachments });
+    for (const command of result.commands) emitCommand(command);
+    auditEvent({
+      clientId: "server-recipe-start-" + result.instance.id,
+      kind: "state",
+      title: "Recipe started",
+      body: result.instance.recipeName,
+      meta: result.instance.id,
+      icon: "ti-play",
+      view: "activity",
+      metadata: { recipeInstanceId: result.instance.id, commands: result.commands.map((command) => command.id) },
+    });
+    return json(result, 202);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    if (e instanceof Error) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const getRecipeInstanceArtifacts: Handler = (_req, params) => {
+  const instance = getRecipeInstance(params.id!);
+  if (!instance) return error("recipe instance not found", 404);
+  return json(listArtifactsForEntity("recipeRun", instance.id));
+};
+
+export const postRecipeInstanceArtifacts: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) return error("attachments required");
+    const createdBy = cleanString(parsed.body.createdBy, "createdBy", { max: 120 }) ?? "api";
+    const attachments = cleanAttachmentRefs(parsed.body.attachments ?? parsed.body.artifacts, "attachments") ?? [];
+    const instance = linkRecipeArtifacts(params.id!, attachments, createdBy);
+    if (!instance) return error("recipe instance not found", 404);
+    return json({ instance, artifacts: listArtifactsForEntity("recipeRun", instance.id) }, 201);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    if (e instanceof Error) return error(e.message, e.message.includes("not found") ? 404 : 400);
+    throw e;
+  }
+};
+
+export const postRecipeStop: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const stoppedBy = isRecord(parsed.body)
+      ? cleanString(parsed.body.stoppedBy, "stoppedBy", { max: 120 }) ?? "api"
+      : "api";
+    const result = stopRecipe(params.id!, stoppedBy);
+    for (const command of result.commands) emitCommand(command);
+    auditEvent({
+      clientId: "server-recipe-stop-" + result.instance.id + "-" + Date.now(),
+      kind: "state",
+      title: "Recipe stopped",
+      body: result.instance.recipeName,
+      meta: result.instance.id,
+      icon: "ti-player-stop",
+      view: "activity",
+      metadata: { recipeInstanceId: result.instance.id, commands: result.commands.map((command) => command.id) },
+    });
+    return json(result, 202);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    if (e instanceof Error) return error(e.message, e.message.includes("not found") ? 404 : 400);
+    throw e;
+  }
+};

package/src/routes/spawn-policy.ts

@@ -0,0 +1,231 @@
+// Auto-split from routes.ts (#299). Domain: spawn-policy.
+import { ValidationError, getOrchestrator } from "../db";
+import { auditEvent, authAuditMetadata, dashboardAttribution, emitCommand, error, json, parseBody, spawnRequestId, type Handler } from "./_shared";
+import { buildManagedSpawnParams } from "../managed-policy";
+import { cleanString } from "../validation";
+import { createCommand } from "../commands-db";
+import { deleteConfig, getManagedAgentState, getSpawnPolicy, listSpawnPolicies, setConfig, upsertManagedAgentState } from "../config-store";
+import { emitConfigChanged, emitManagedAgentStateChanged } from "../sse";
+import { getLifecycleManager } from "../lifecycle-manager";
+import { isRecord } from "agent-relay-sdk";
+import { type Command, type SpawnPolicy } from "../types";
+
+function policyStatusPayload(policy: SpawnPolicy) {
+  return {
+    policy,
+    state: getManagedAgentState(policy.name) ?? {
+      policyName: policy.name,
+      status: "stopped",
+      orchestratorId: policy.orchestratorId,
+      provider: policy.provider,
+      restartCount: 0,
+      consecutiveFailures: 0,
+      updatedAt: 0,
+    },
+  };
+}
+
+function requirePolicyAndOrchestrator(name: string): { policy: SpawnPolicy; orch: NonNullable<ReturnType<typeof getOrchestrator>> } | Response {
+  const entry = getSpawnPolicy(name);
+  if (!entry) return error("spawn policy not found", 404);
+  const policy = entry.value;
+  const orch = getOrchestrator(policy.orchestratorId);
+  if (!orch) return error("orchestrator not found", 404);
+  return { policy, orch };
+}
+
+function setPolicyEnabled(policy: SpawnPolicy, enabled: boolean): SpawnPolicy {
+  if (policy.enabled === enabled || (enabled && policy.enabled === undefined)) return policy;
+  const entry = setConfig("spawn-policy", policy.name, { ...policy, enabled }, "lifecycle-control");
+  emitConfigChanged(entry.namespace, entry.key, entry.version);
+  return entry.value as SpawnPolicy;
+}
+
+function enqueuePolicyStart(policy: SpawnPolicy, reason: string): Command | Response {
+  const orch = getOrchestrator(policy.orchestratorId);
+  if (!orch) return error("orchestrator not found", 404);
+  if (orch.status !== "online") return error("orchestrator is offline", 409);
+  if (!orch.providers.includes(policy.provider)) return error(`orchestrator does not have provider available: ${policy.provider}`, 409);
+  const requestId = spawnRequestId();
+  const existing = getManagedAgentState(policy.name);
+  const state = upsertManagedAgentState({
+    policyName: policy.name,
+    status: "starting",
+    orchestratorId: policy.orchestratorId,
+    provider: policy.provider,
+    spawnRequestId: requestId,
+    lastSpawnAt: Date.now(),
+    // Preserve failure history so a manual start doesn't silently re-arm a
+    // crashlooping agent for immediate retry.
+    restartCount: existing?.restartCount ?? 0,
+    consecutiveFailures: existing?.consecutiveFailures ?? 0,
+  });
+  emitManagedAgentStateChanged(policy.name, state as unknown as Record<string, unknown>);
+  const command = createCommand({
+    type: "agent.spawn",
+    source: "system",
+    target: orch.agentId,
+    correlationId: requestId,
+    params: {
+      ...buildManagedSpawnParams(policy, requestId, { createdBy: "managed-agent" }),
+      reason,
+      orchestratorId: orch.id,
+    },
+  });
+  emitCommand(command);
+  return command;
+}
+
+function enqueuePolicyStop(policy: SpawnPolicy, action: "shutdown" | "restart", reason: string): Command | Response {
+  const orch = getOrchestrator(policy.orchestratorId);
+  if (!orch) return error("orchestrator not found", 404);
+  const state = getManagedAgentState(policy.name);
+  const restartRequestId = action === "restart" ? spawnRequestId() : undefined;
+  const restartSpawn = restartRequestId ? buildManagedSpawnParams(policy, restartRequestId, { createdBy: "managed-agent" }) : undefined;
+  const nextState = upsertManagedAgentState({
+    policyName: policy.name,
+    status: "stopping",
+    agentId: state?.agentId,
+    orchestratorId: policy.orchestratorId,
+    provider: policy.provider,
+    tmuxSession: state?.tmuxSession,
+    spawnRequestId: restartRequestId ?? state?.spawnRequestId,
+    lastSpawnAt: restartSpawn ? Date.now() : state?.lastSpawnAt,
+    lastStopAt: Date.now(),
+    restartCount: state?.restartCount ?? 0,
+    consecutiveFailures: state?.consecutiveFailures ?? 0,
+  });
+  emitManagedAgentStateChanged(policy.name, nextState as unknown as Record<string, unknown>);
+  const command = createCommand({
+    type: action === "restart" ? "agent.restart" : "agent.shutdown",
+    source: "system",
+    target: orch.agentId,
+    correlationId: state?.spawnRequestId,
+    params: {
+      action,
+      policyName: policy.name,
+      spawnRequestId: state?.spawnRequestId,
+      agentId: state?.agentId,
+      tmuxSession: state?.tmuxSession,
+      graceful: true,
+      timeoutMs: 10_000,
+      reason,
+      orchestratorId: orch.id,
+      ...(restartSpawn ? { restartSpawn } : {}),
+      requestedBy: "managed-agent",
+      requestedAt: Date.now(),
+    },
+  });
+  emitCommand(command);
+  return command;
+}
+
+const POLICY_LIFECYCLE_ICON: Record<"start" | "stop" | "restart", string> = {
+  start: "ti-player-play",
+  stop: "ti-power",
+  restart: "ti-refresh",
+};
+
+function auditPolicyLifecycle(req: Request, policyName: string, action: "start" | "stop" | "restart", command: Command, surface: unknown): void {
+  const agentId = typeof command.params?.agentId === "string" ? command.params.agentId : undefined;
+  auditEvent({
+    clientId: `server-policy-${policyName}-${action}-${command.id}`,
+    kind: "state",
+    title: `Managed agent ${action} requested`,
+    body: policyName,
+    meta: agentId ?? policyName,
+    icon: POLICY_LIFECYCLE_ICON[action],
+    view: "managed",
+    ...(agentId ? { agentId } : {}),
+    metadata: { action, policyName, commandId: command.id, ...authAuditMetadata(req), ...dashboardAttribution(req, surface) },
+  });
+}
+
+export const getSpawnPoliciesRoute: Handler = () => {
+  return json(listSpawnPolicies().map((entry) => policyStatusPayload(entry.value)));
+};
+
+export const getSpawnPolicyRoute: Handler = (_req, params) => {
+  const entry = getSpawnPolicy(params.name!);
+  return entry ? json(entry) : error("spawn policy not found", 404);
+};
+
+export const putSpawnPolicyRoute: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const value = isRecord(parsed.body) && Object.prototype.hasOwnProperty.call(parsed.body, "value")
+      ? parsed.body.value
+      : parsed.body;
+    const updatedBy = isRecord(parsed.body) ? cleanString(parsed.body.updatedBy, "updatedBy", { max: 200 }) : undefined;
+    const entry = setConfig("spawn-policy", params.name!, value, updatedBy);
+    emitConfigChanged(entry.namespace, entry.key, entry.version);
+    getLifecycleManager().onConfigChanged("spawn-policy", entry.key);
+    return json(entry, entry.version === 1 ? 201 : 200);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const deleteSpawnPolicyRoute: Handler = (req, params) => {
+  const entry = getSpawnPolicy(params.name!);
+  if (!entry) return error("spawn policy not found", 404);
+  const stop = enqueuePolicyStop(entry.value, "shutdown", "policy-deleted");
+  if (stop instanceof Response) return stop;
+  deleteConfig("spawn-policy", params.name!, new URL(req.url).searchParams.get("updatedBy") ?? undefined);
+  emitConfigChanged("spawn-policy", params.name!, entry.version + 1);
+  return json({ ok: true, command: stop }, 202);
+};
+
+async function policyLifecycleSurface(req: Request): Promise<unknown> {
+  const parsed = await parseBody<unknown>(req);
+  return parsed.ok && isRecord(parsed.body) ? parsed.body.surface : undefined;
+}
+
+export const postSpawnPolicyStart: Handler = async (req, params) => {
+  const resolved = requirePolicyAndOrchestrator(params.name!);
+  if (resolved instanceof Response) return resolved;
+  const surface = await policyLifecycleSurface(req);
+  const policy = setPolicyEnabled(resolved.policy, true);
+  const command = enqueuePolicyStart(policy, "manual-start");
+  if (command instanceof Response) return command;
+  auditPolicyLifecycle(req, policy.name, "start", command, surface);
+  return json({ ok: true, command }, 202);
+};
+
+export const postSpawnPolicyStop: Handler = async (req, params) => {
+  const resolved = requirePolicyAndOrchestrator(params.name!);
+  if (resolved instanceof Response) return resolved;
+  const surface = await policyLifecycleSurface(req);
+  const policy = setPolicyEnabled(resolved.policy, false);
+  const command = enqueuePolicyStop(policy, "shutdown", "manual-stop");
+  if (command instanceof Response) return command;
+  auditPolicyLifecycle(req, policy.name, "stop", command, surface);
+  return json({ ok: true, command }, 202);
+};
+
+export const postSpawnPolicyRestart: Handler = async (req, params) => {
+  const resolved = requirePolicyAndOrchestrator(params.name!);
+  if (resolved instanceof Response) return resolved;
+  const surface = await policyLifecycleSurface(req);
+  const policy = setPolicyEnabled(resolved.policy, true);
+  const command = enqueuePolicyStop(policy, "restart", "manual-restart");
+  if (command instanceof Response) return command;
+  auditPolicyLifecycle(req, policy.name, "restart", command, surface);
+  return json({ ok: true, command }, 202);
+};
+
+export const getSpawnPolicyStatus: Handler = (_req, params) => {
+  const entry = getSpawnPolicy(params.name!);
+  return entry ? json(policyStatusPayload(entry.value)) : error("spawn policy not found", 404);
+};
+
+export const getSpawnPoliciesHealth: Handler = () => {
+  return json(listSpawnPolicies().map((entry) => policyStatusPayload(entry.value)));
+};
+
+export const getSpawnPolicyHealth: Handler = (_req, params) => {
+  const entry = getSpawnPolicy(params.name!);
+  return entry ? json(policyStatusPayload(entry.value)) : error("spawn policy not found", 404);
+};