agent-relay-server 0.8.1 → 0.10.0

package/src/index.ts

@@ -1,7 +1,13 @@
 #!/usr/bin/env bun
-import { initDb, reapStaleAgents, pruneOfflineAgents, pruneOldMessages, releaseExpiredClaims } from "./db";
+import { initDb, reapStaleAgents, pruneOfflineAgents, pruneOldMessages, releaseExpiredClaims, releaseOrphanedTasks, evaluatePoolBindings } from "./db";
 import { matchRoute } from "./routes";
-import { emitAgentStatus, emitAgentRemoved, emitMessageClaimReleased, emitTaskChanged } from "./sse";
+import { emitAgentStatus, emitAgentRemoved, emitMessageClaimReleased, emitNewMessage, emitTaskChanged, emitPoolBindingChanged } from "./sse";
+import { busHandleClose, busHandleMessage, busHandleOpen, expireStaleBusAgents, handleBusUpgrade } from "./bus";
+import { pruneOutbox } from "./bus-outbox";
+import { expireCommands } from "./commands-db";
+import { applyCommandToRecipe } from "./recipe-runner";
+import { emitRelayEvent } from "./events";
+import { reconcileAutomationRuns, runDueAutomations, type AutomationDispatchResult, type AutomationReconcileResult } from "./automations";
 import { resolve, sep } from "path";
 import {
   REAP_INTERVAL_MS,
@@ -15,6 +21,7 @@ import {
   assertSafeNetworkConfig,
   corsPreflight,
   forbidden,
+  getComponentAuth,
   getIntegrationAuth,
   isAuthorized,
   isScopedRequestAuthorized,
@@ -34,6 +41,9 @@ function startServer(): void {
   const HOST = process.env.HOST || "127.0.0.1";
   const DB_PATH = process.env.DB_PATH || "agent-relay.db";
   const RETENTION_DAYS = Number(process.env.RETENTION_DAYS) || 30;
+  const OUTBOX_RETENTION_MS = Number(process.env.AGENT_RELAY_OUTBOX_RETENTION_MS) || 60 * 60 * 1000;
+  const AUTOMATION_INTERVAL_MS = Number(process.env.AGENT_RELAY_AUTOMATION_INTERVAL_MS) || 30 * 1000;
+  const IDLE_TIMEOUT_SECONDS = Number(process.env.AGENT_RELAY_IDLE_TIMEOUT_SECONDS) || 255;
   const LOG_REQUESTS = process.env.AGENT_RELAY_LOG_REQUESTS === "1";
 
   assertSafeNetworkConfig(HOST);
@@ -47,6 +57,20 @@ function startServer(): void {
       for (const task of released.tasks) emitTaskChanged(task, "task.updated");
     }
 
+    const expiredCommands = expireCommands();
+    for (const command of expiredCommands) {
+      applyCommandToRecipe(command);
+      emitRelayEvent({ type: "command.timed_out", source: command.source, subject: command.id, data: { command } });
+    }
+
+    const staleExpired = expireStaleBusAgents();
+    if (staleExpired.agentIds.length > 0) {
+      console.log(`expired ${staleExpired.agentIds.length} stale bus agent(s)`);
+    }
+
+    const releasedOrphans = releaseOrphanedTasks();
+    for (const task of releasedOrphans) emitTaskChanged(task, "task.updated");
+
     const reaped = reapStaleAgents(STALE_TTL_MS);
     if (reaped.length > 0) {
       console.log(`reaped ${reaped.length} stale agent(s)`);
@@ -57,6 +81,12 @@ function startServer(): void {
       console.log(`pruned ${pruned.length} offline agent(s)`);
       for (const id of pruned) emitAgentRemoved(id);
     }
+
+    const poolChanges = evaluatePoolBindings();
+    for (const change of poolChanges) {
+      console.log(`pool binding ${change.bindingId}: ${change.previousAgentId ?? "none"} → ${change.newAgentId ?? "none"}`);
+      emitPoolBindingChanged(change.bindingId, change.channelId, change.previousAgentId, change.newAgentId);
+    }
   }, REAP_INTERVAL_MS);
 
   // Daily message prune
@@ -65,25 +95,85 @@ function startServer(): void {
     if (pruned > 0) console.log(`pruned ${pruned} old message(s)`);
   }, DAY_MS);
 
+  setInterval(() => {
+    emitAutomationReconciliations(reconcileAutomationRuns());
+    emitAutomationDispatches(runDueAutomations());
+  }, AUTOMATION_INTERVAL_MS);
+
+  setInterval(() => {
+    const pruned = pruneOutbox(OUTBOX_RETENTION_MS);
+    if (pruned > 0) console.log(`pruned ${pruned} bus outbox event(s)`);
+  }, 5 * 60 * 1000);
+
   Bun.serve({
     port: PORT,
     hostname: HOST,
+    idleTimeout: IDLE_TIMEOUT_SECONDS,
     fetch: createFetchHandler({ logRequests: LOG_REQUESTS }),
+    websocket: {
+      open: busHandleOpen,
+      message: busHandleMessage,
+      close: busHandleClose,
+    },
   });
 
   console.log(`agent-relay ${VERSION} running on http://${HOST}:${PORT}`);
 }
 
+function emitAutomationDispatches(results: AutomationDispatchResult[]): void {
+  for (const result of results) {
+    if (result.command) emitAutomationCommand(result.command);
+    if (result.message) emitNewMessage(result.message);
+    if (result.task) emitTaskChanged(result.task, "task.created");
+    emitRelayEvent({
+      type: "automation.run",
+      source: "server",
+      subject: result.run.id,
+      data: { automation: result.automation, run: result.run, task: result.task },
+    });
+  }
+}
+
+function emitAutomationReconciliations(results: AutomationReconcileResult[]): void {
+  for (const result of results) {
+    if (result.command) emitAutomationCommand(result.command);
+    if (result.task) emitTaskChanged(result.task, "task.updated");
+    emitRelayEvent({
+      type: "automation.run",
+      source: "server",
+      subject: result.run.id,
+      data: { run: result.run, task: result.task },
+    });
+  }
+}
+
+function emitAutomationCommand(command: { id: string; source: string; status: string }): void {
+  emitRelayEvent({
+    type: command.status === "pending" ? "command.requested" : `command.${command.status}`,
+    source: command.source,
+    subject: command.id,
+    data: { command },
+  });
+}
+
 export function createFetchHandler(
   opts: { publicDir?: string; logRequests?: boolean } = {},
-): (req: Request) => Promise<Response> {
-  const publicDir = opts.publicDir ?? resolve(import.meta.dir, "../public");
+): {
+  (req: Request): Promise<Response>;
+  (req: Request, server: Bun.Server<any>): Promise<Response | undefined>;
+} {
+  const publicDir = resolve(opts.publicDir ?? resolve(import.meta.dir, "../public"));
   const publicDirPrefix = publicDir + sep;
   const logRequests = opts.logRequests ?? false;
 
-  return async function fetch(req: Request): Promise<Response> {
+  return async function fetch(req: Request, server?: Bun.Server<any>): Promise<Response | undefined> {
     const url = new URL(req.url);
 
+    if (url.pathname === "/bus") {
+      if (!server) return new Response("WebSocket upgrade unavailable", { status: 400 });
+      return handleBusUpgrade(req, server);
+    }
+
     if (req.method === "OPTIONS") {
       return corsPreflight(req);
     }
@@ -95,12 +185,14 @@ export function createFetchHandler(
     const matched = matchRoute(req.method, url.pathname);
     if (matched) {
       const integrationAuth = getIntegrationAuth(req);
+      const componentAuth = getComponentAuth(req);
       if (!isAuthorized(req)) {
         if (!integrationAuth) {
           return unauthorized(req);
         }
         if (!isScopedRequestAuthorized(req)) return forbidden(req);
       }
+      if (componentAuth && !isScopedRequestAuthorized(req)) return forbidden(req);
       const response = await matched.handler(req, matched.params);
       applyCors(req, response);
       if (logRequests && url.pathname.startsWith("/api/")) {
@@ -123,6 +215,9 @@ export function createFetchHandler(
     }
 
     return Response.json({ error: "not found" }, { status: 404 });
+  } as {
+    (req: Request): Promise<Response>;
+    (req: Request, server: Bun.Server<any>): Promise<Response | undefined>;
   };
 }
 

package/src/recipe-db.ts

@@ -0,0 +1,163 @@
+import { randomUUID } from "node:crypto";
+import { getDb } from "./db";
+import type { RecipeAgentInstance, RecipeInstance } from "./types";
+
+type RecipeInstanceStatus = RecipeInstance["status"];
+type RecipeAgentStatus = RecipeAgentInstance["status"];
+
+interface RecipeInstanceRow {
+  id: string;
+  recipe_name: string;
+  recipe_source: string;
+  cwd: string;
+  orchestrator_id: string;
+  status: RecipeInstanceStatus;
+  started_by: string;
+  error: string | null;
+  started_at: number;
+  stopped_at: number | null;
+}
+
+interface RecipeAgentInstanceRow {
+  instance_id: string;
+  role: string;
+  agent_id: string;
+  provider: string;
+  status: RecipeAgentStatus;
+  idx: number | null;
+}
+
+interface CreateRecipeInstanceInput {
+  recipeName: string;
+  recipeSource: RecipeInstance["recipeSource"];
+  cwd: string;
+  orchestratorId: string;
+  startedBy: string;
+}
+
+interface UpsertRecipeAgentInstanceInput {
+  instanceId: string;
+  role: string;
+  agentId: string;
+  provider: string;
+  status: RecipeAgentStatus;
+  index?: number;
+}
+
+export function createRecipeInstance(input: CreateRecipeInstanceInput): RecipeInstance {
+  const now = Date.now();
+  const id = randomUUID();
+  getDb().prepare(`
+    INSERT INTO recipe_instances (id, recipe_name, recipe_source, cwd, orchestrator_id, status, started_by, started_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(id, input.recipeName, input.recipeSource, input.cwd, input.orchestratorId, "starting", input.startedBy, now);
+  return getRecipeInstance(id)!;
+}
+
+export function listRecipeInstances(status?: RecipeInstanceStatus): RecipeInstance[] {
+  const rows = status
+    ? getDb().prepare("SELECT * FROM recipe_instances WHERE status = ? ORDER BY started_at DESC").all(status)
+    : getDb().prepare("SELECT * FROM recipe_instances ORDER BY started_at DESC").all();
+  return (rows as RecipeInstanceRow[]).map(rowToRecipeInstance);
+}
+
+export function getRecipeInstance(id: string): RecipeInstance | null {
+  const row = getDb().prepare("SELECT * FROM recipe_instances WHERE id = ?").get(id) as RecipeInstanceRow | undefined;
+  return row ? rowToRecipeInstance(row) : null;
+}
+
+export function updateRecipeInstance(
+  id: string,
+  input: Partial<Pick<RecipeInstance, "status" | "error" | "stoppedAt">>,
+): RecipeInstance | null {
+  const existing = getRecipeInstance(id);
+  if (!existing) return null;
+  getDb().prepare(`
+    UPDATE recipe_instances
+    SET status = ?, error = ?, stopped_at = ?
+    WHERE id = ?
+  `).run(
+    input.status ?? existing.status,
+    input.error ?? existing.error ?? null,
+    input.stoppedAt ?? existing.stoppedAt ?? null,
+    id,
+  );
+  return getRecipeInstance(id);
+}
+
+export function upsertRecipeAgentInstance(input: UpsertRecipeAgentInstanceInput): RecipeAgentInstance {
+  getDb().prepare(`
+    INSERT INTO recipe_agent_instances (instance_id, role, agent_id, provider, status, idx)
+    VALUES (?, ?, ?, ?, ?, ?)
+    ON CONFLICT(instance_id, role, agent_id) DO UPDATE SET
+      provider = excluded.provider,
+      status = excluded.status,
+      idx = excluded.idx
+  `).run(input.instanceId, input.role, input.agentId, input.provider, input.status, input.index ?? null);
+  return listRecipeAgentInstances(input.instanceId)
+    .find((agent) => agent.role === input.role && agent.agentId === input.agentId)!;
+}
+
+export function updateRecipeAgentInstance(
+  instanceId: string,
+  agentId: string,
+  status: RecipeAgentStatus,
+): RecipeAgentInstance | null {
+  const changed = getDb().prepare(`
+    UPDATE recipe_agent_instances
+    SET status = ?
+    WHERE instance_id = ? AND agent_id = ?
+  `).run(status, instanceId, agentId).changes;
+  if (!changed) return null;
+  return listRecipeAgentInstances(instanceId).find((agent) => agent.agentId === agentId) ?? null;
+}
+
+export function replaceRecipeAgentInstanceAgentId(
+  instanceId: string,
+  currentAgentId: string,
+  nextAgentId: string,
+  status: RecipeAgentStatus,
+): RecipeAgentInstance | null {
+  const changed = getDb().prepare(`
+    UPDATE recipe_agent_instances
+    SET agent_id = ?, status = ?
+    WHERE instance_id = ? AND agent_id = ?
+  `).run(nextAgentId, status, instanceId, currentAgentId).changes;
+  if (!changed) return null;
+  return listRecipeAgentInstances(instanceId).find((agent) => agent.agentId === nextAgentId) ?? null;
+}
+
+function listRecipeAgentInstances(instanceId: string): RecipeAgentInstance[] {
+  const rows = getDb().prepare(`
+    SELECT * FROM recipe_agent_instances
+    WHERE instance_id = ?
+    ORDER BY role ASC, idx ASC, agent_id ASC
+  `).all(instanceId) as RecipeAgentInstanceRow[];
+  return rows.map(rowToRecipeAgentInstance);
+}
+
+function rowToRecipeInstance(row: RecipeInstanceRow): RecipeInstance {
+  return {
+    id: row.id,
+    recipeName: row.recipe_name,
+    recipeSource: row.recipe_source === "user" ? "user" : "builtin",
+    cwd: row.cwd,
+    orchestratorId: row.orchestrator_id,
+    status: row.status,
+    startedBy: row.started_by,
+    error: row.error ?? undefined,
+    startedAt: row.started_at,
+    stoppedAt: row.stopped_at ?? undefined,
+    agents: listRecipeAgentInstances(row.id),
+  };
+}
+
+function rowToRecipeAgentInstance(row: RecipeAgentInstanceRow): RecipeAgentInstance {
+  return {
+    role: row.role,
+    agentId: row.agent_id,
+    provider: row.provider,
+    status: row.status,
+    index: row.idx ?? undefined,
+  };
+}

package/src/recipe-loader.ts

@@ -0,0 +1,100 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { validateRecipe } from "./recipe-validator";
+import type { Recipe } from "./types";
+
+interface LoadedRecipe {
+  name: string;
+  source: "builtin" | "user";
+  path: string;
+  recipe: Recipe;
+  raw: string;
+}
+
+export function listRecipes(): LoadedRecipe[] {
+  const byName = new Map<string, LoadedRecipe>();
+  for (const recipe of loadRecipeDir(builtinRecipeDir(), "builtin")) byName.set(recipe.name, recipe);
+  for (const recipe of loadRecipeDir(userRecipeDir(), "user")) byName.set(recipe.name, recipe);
+  return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function getRecipe(name: string): LoadedRecipe | null {
+  return listRecipes().find((recipe) => recipe.name === name || slug(recipe.recipe.name) === name) ?? null;
+}
+
+function builtinRecipeDir(): string {
+  return resolve(import.meta.dir, "../recipes");
+}
+
+function userRecipeDir(): string {
+  return join(process.env.HOME || ".", ".agent-relay", "recipes");
+}
+
+function loadRecipeDir(dir: string, source: LoadedRecipe["source"]): LoadedRecipe[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((file) => file.endsWith(".yaml") || file.endsWith(".yml"))
+    .map((file) => loadRecipeFile(join(dir, file), source));
+}
+
+function loadRecipeFile(path: string, source: LoadedRecipe["source"]): LoadedRecipe {
+  const raw = readFileSync(path, "utf8");
+  const recipe = validateRecipe(parseSimpleYaml(raw));
+  return { name: slug(basename(path).replace(/\.ya?ml$/, "")), source, path, recipe, raw };
+}
+
+function slug(value: string): string {
+  return value.toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+
+function parseSimpleYaml(raw: string): Record<string, unknown> {
+  const root: Record<string, unknown> = {};
+  let section: string | null = null;
+  let currentAgent: Record<string, unknown> | null = null;
+
+  for (const original of raw.split(/\r?\n/)) {
+    const line = original.replace(/\s+#.*$/, "");
+    if (!line.trim()) continue;
+    if (!line.startsWith(" ")) {
+      currentAgent = null;
+      const [key, ...rest] = line.split(":");
+      section = (key ?? "").trim();
+      const value = rest.join(":").trim();
+      if (value) root[section] = parseScalar(value);
+      else if (section === "agents") root.agents = [];
+      else root[section] = {};
+      continue;
+    }
+    if (section === "agents") {
+      const trimmed = line.trim();
+      if (trimmed.startsWith("- ")) {
+        currentAgent = {};
+        (root.agents as unknown[]).push(currentAgent);
+        assign(currentAgent, trimmed.slice(2));
+      } else if (currentAgent) {
+        assign(currentAgent, trimmed);
+      }
+      continue;
+    }
+    if (section && typeof root[section] === "object" && root[section] !== null) {
+      assign(root[section] as Record<string, unknown>, line.trim());
+    }
+  }
+  return root;
+}
+
+function assign(target: Record<string, unknown>, assignment: string): void {
+  const [key, ...rest] = assignment.split(":");
+  if (!key) return;
+  target[key.trim()] = parseScalar(rest.join(":").trim());
+}
+
+function parseScalar(value: string): unknown {
+  const trimmed = value.trim();
+  if (!trimmed) return "";
+  if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
+    return trimmed.slice(1, -1).split(",").map((item) => String(parseScalar(item.trim())));
+  }
+  if (/^\d+$/.test(trimmed)) return Number(trimmed);
+  return trimmed.replace(/^["']|["']$/g, "");
+}

package/src/recipe-runner.ts

@@ -0,0 +1,206 @@
+import { createCommand } from "./commands-db";
+import { listOrchestrators } from "./db";
+import { getRecipe } from "./recipe-loader";
+import {
+  createRecipeInstance,
+  getRecipeInstance,
+  listRecipeInstances,
+  replaceRecipeAgentInstanceAgentId,
+  updateRecipeAgentInstance,
+  updateRecipeInstance,
+  upsertRecipeAgentInstance,
+} from "./recipe-db";
+import type { Command, RecipeInstance } from "./types";
+
+interface StartRecipeInput {
+  name: string;
+  cwd?: string;
+  orchestratorId?: string;
+  startedBy?: string;
+}
+
+interface StartRecipeResult {
+  instance: RecipeInstance;
+  commands: Command[];
+}
+
+interface StopRecipeResult {
+  instance: RecipeInstance;
+  commands: Command[];
+}
+
+export function startRecipe(input: StartRecipeInput): StartRecipeResult {
+  const loaded = getRecipe(input.name);
+  if (!loaded) throw new Error(`recipe not found: ${input.name}`);
+  const recipe = loaded.recipe;
+  const orchestrator = selectOrchestrator(input.orchestratorId, recipe.agents.map((agent) => agent.provider));
+  if (!orchestrator) throw new Error("no online orchestrator supports this recipe");
+  const cwd = input.cwd ?? orchestrator.baseDir;
+  const instance = createRecipeInstance({
+    recipeName: loaded.name,
+    recipeSource: loaded.source,
+    cwd,
+    orchestratorId: orchestrator.id,
+    startedBy: input.startedBy ?? "cli",
+  });
+
+  const commands: Command[] = [];
+  for (const agent of recipe.agents) {
+    const count = agent.count ?? 1;
+    for (let index = 0; index < count; index++) {
+      const label = count > 1 ? `${recipe.name}:${agent.role}:${index + 1}` : `${recipe.name}:${agent.role}`;
+      const command = createCommand({
+        type: "agent.spawn",
+        source: instance.startedBy,
+        target: orchestrator.agentId,
+        params: {
+          provider: agent.provider,
+          role: agent.role,
+          label,
+          cwd,
+          prompt: agent.prompt,
+          approvalMode: agent.approvalMode,
+          recipe: loaded.name,
+          recipeInstanceId: instance.id,
+          tags: ["recipe", `recipe:${loaded.name}`, `role:${agent.role}`],
+          env: agent.env ?? {},
+        },
+        ttlMs: 60_000,
+      });
+      commands.push(command);
+      upsertRecipeAgentInstance({
+        instanceId: instance.id,
+        role: agent.role,
+        agentId: `pending:${command.id}`,
+        provider: agent.provider,
+        status: "spawning",
+        index,
+      });
+    }
+  }
+
+  return { instance: getRecipeInstance(instance.id)!, commands };
+}
+
+export function stopRecipe(instanceId: string, stoppedBy = "cli"): StopRecipeResult {
+  const instance = getRecipeInstance(instanceId);
+  if (!instance) throw new Error("recipe instance not found");
+  if (instance.status === "stopped") return { instance, commands: [] };
+
+  updateRecipeInstance(instance.id, { status: "stopping" });
+  const commands: Command[] = [];
+  for (const agent of instance.agents) {
+    if (agent.status === "stopped") continue;
+    if (agent.agentId.startsWith("pending:")) {
+      updateRecipeAgentInstance(instance.id, agent.agentId, "stopped");
+      continue;
+    }
+    const command = createCommand({
+      type: "agent.shutdown",
+      source: stoppedBy,
+      target: agent.agentId,
+      params: { recipeInstanceId: instance.id, role: agent.role },
+      ttlMs: 30_000,
+    });
+    commands.push(command);
+    updateRecipeAgentInstance(instance.id, agent.agentId, "stopping");
+  }
+
+  const next = commands.length === 0
+    ? updateRecipeInstance(instance.id, { status: "stopped", stoppedAt: Date.now() })!
+    : getRecipeInstance(instance.id)!;
+  return { instance: next, commands };
+}
+
+export { getRecipeInstance, listRecipeInstances };
+
+export function applyCommandToRecipe(command: Command): RecipeInstance | null {
+  const instanceId = stringParam(command.params, "recipeInstanceId");
+  if (!instanceId) return null;
+  const instance = getRecipeInstance(instanceId);
+  if (!instance) return null;
+
+  if (command.type === "agent.spawn") {
+    const pendingAgentId = `pending:${command.id}`;
+    if (command.status === "succeeded") {
+      const agentId = commandResultAgentId(command.result);
+      if (!agentId) return instance;
+      replaceRecipeAgentInstanceAgentId(instance.id, pendingAgentId, agentId, "running");
+      return refreshRecipeInstanceStatus(instance.id);
+    }
+    if (isFailedCommandStatus(command.status)) {
+      updateRecipeAgentInstance(instance.id, pendingAgentId, "failed");
+      return updateRecipeInstance(instance.id, {
+        status: "failed",
+        error: command.error ?? `${command.type} ${command.status}`,
+      });
+    }
+    return instance;
+  }
+
+  if (command.type === "agent.shutdown") {
+    if (command.status === "succeeded") {
+      updateRecipeAgentInstance(instance.id, command.target, "stopped");
+      return refreshRecipeInstanceStatus(instance.id);
+    }
+    if (isFailedCommandStatus(command.status)) {
+      updateRecipeAgentInstance(instance.id, command.target, "failed");
+      return updateRecipeInstance(instance.id, {
+        status: "failed",
+        error: command.error ?? `${command.type} ${command.status}`,
+      });
+    }
+  }
+
+  return instance;
+}
+
+function selectOrchestrator(id: string | undefined, providers: string[]) {
+  const required = new Set(providers);
+  const candidates = listOrchestrators()
+    .filter((orchestrator) => orchestrator.status === "online")
+    .filter((orchestrator) => !id || orchestrator.id === id)
+    .filter((orchestrator) => [...required].every((provider) => orchestrator.providers.includes(provider as any)));
+  return candidates[0] ?? null;
+}
+
+function refreshRecipeInstanceStatus(instanceId: string): RecipeInstance | null {
+  const instance = getRecipeInstance(instanceId);
+  if (!instance) return null;
+  if (instance.agents.some((agent) => agent.status === "failed")) {
+    return updateRecipeInstance(instance.id, { status: "failed" });
+  }
+  if (instance.agents.length > 0 && instance.agents.every((agent) => agent.status === "stopped")) {
+    return updateRecipeInstance(instance.id, { status: "stopped", stoppedAt: Date.now() });
+  }
+  if (instance.agents.length > 0 && instance.agents.every((agent) => agent.status === "running")) {
+    return updateRecipeInstance(instance.id, { status: "running" });
+  }
+  if (instance.status === "stopping") return instance;
+  return updateRecipeInstance(instance.id, { status: "starting" });
+}
+
+function commandResultAgentId(result: Record<string, unknown> | undefined): string | null {
+  if (!result) return null;
+  if (typeof result.agentId === "string" && result.agentId.trim()) return result.agentId.trim();
+  const agent = result.agent;
+  if (agent && typeof agent === "object" && !Array.isArray(agent)) {
+    const id = (agent as Record<string, unknown>).id;
+    if (typeof id === "string" && id.trim()) return id.trim();
+  }
+  const managedAgent = result.managedAgent;
+  if (managedAgent && typeof managedAgent === "object" && !Array.isArray(managedAgent)) {
+    const id = (managedAgent as Record<string, unknown>).agentId;
+    if (typeof id === "string" && id.trim()) return id.trim();
+  }
+  return null;
+}
+
+function stringParam(params: Record<string, unknown>, key: string): string | null {
+  const value = params[key];
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function isFailedCommandStatus(status: Command["status"]): boolean {
+  return status === "failed" || status === "timed_out" || status === "rejected" || status === "canceled";
+}