agent-relay-server 0.9.0 → 0.10.0

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

package/src/recipe-validator.ts

@@ -0,0 +1,85 @@
+import type { Recipe, RecipeAgent } from "./types";
+
+class RecipeValidationError extends Error {}
+
+export function validateRecipe(value: unknown): Recipe {
+  if (!isRecord(value)) throw new RecipeValidationError("recipe must be an object");
+  const name = requiredString(value.name, "name");
+  const description = requiredString(value.description, "description");
+  if (!Array.isArray(value.agents) || value.agents.length === 0) {
+    throw new RecipeValidationError("agents must be a non-empty array");
+  }
+  const agents = value.agents.map(validateAgent);
+  const roles = new Set<string>();
+  for (const agent of agents) {
+    if (roles.has(agent.role)) throw new RecipeValidationError(`duplicate recipe agent role: ${agent.role}`);
+    roles.add(agent.role);
+  }
+  return {
+    name,
+    description,
+    version: optionalString(value.version, "version"),
+    author: optionalString(value.author, "author"),
+    agents,
+    workflow: isRecord(value.workflow) ? {
+      trigger: optionalString(value.workflow.trigger, "workflow.trigger"),
+      fanOut: value.workflow.fanOut === "first" ? "first" : value.workflow.fanOut === "all" ? "all" : undefined,
+      collect: optionalString(value.workflow.collect, "workflow.collect"),
+      routing: undefined,
+    } : undefined,
+    lifecycle: isRecord(value.lifecycle) ? {
+      mode: value.lifecycle.mode === "persistent" ? "persistent" : "ephemeral",
+      idleTimeoutMs: optionalPositiveInteger(value.lifecycle.idleTimeoutMs, "lifecycle.idleTimeoutMs"),
+    } : undefined,
+  };
+}
+
+function validateAgent(value: unknown): RecipeAgent {
+  if (!isRecord(value)) throw new RecipeValidationError("agent must be an object");
+  const provider = value.provider;
+  if (provider !== "claude" && provider !== "codex") throw new RecipeValidationError("agent.provider must be claude or codex");
+  const capabilities = stringArray(value.capabilities, "agent.capabilities");
+  if (capabilities.length === 0) throw new RecipeValidationError("agent.capabilities must not be empty");
+  const approvalMode = value.approvalMode;
+  if (approvalMode !== undefined && approvalMode !== "open" && approvalMode !== "guarded" && approvalMode !== "read-only") {
+    throw new RecipeValidationError("agent.approvalMode must be open, guarded, or read-only");
+  }
+  return {
+    role: requiredString(value.role, "agent.role"),
+    provider,
+    count: optionalPositiveInteger(value.count, "agent.count"),
+    capabilities,
+    label: optionalString(value.label, "agent.label"),
+    tags: value.tags === undefined ? undefined : stringArray(value.tags, "agent.tags"),
+    approvalMode,
+    prompt: optionalString(value.prompt, "agent.prompt"),
+    model: optionalString(value.model, "agent.model"),
+    env: isRecord(value.env) ? Object.fromEntries(Object.entries(value.env).filter((entry): entry is [string, string] => typeof entry[1] === "string")) : undefined,
+  };
+}
+
+function requiredString(value: unknown, field: string): string {
+  if (typeof value !== "string" || !value.trim()) throw new RecipeValidationError(`${field} required`);
+  return value.trim();
+}
+
+function optionalString(value: unknown, field: string): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "string") throw new RecipeValidationError(`${field} must be a string`);
+  return value.trim() || undefined;
+}
+
+function stringArray(value: unknown, field: string): string[] {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) throw new RecipeValidationError(`${field} must be an array of strings`);
+  return value.map((item) => item.trim()).filter(Boolean);
+}
+
+function optionalPositiveInteger(value: unknown, field: string): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) throw new RecipeValidationError(`${field} must be a positive integer`);
+  return value;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}