agent-relay-server 0.9.0 → 0.10.1

package/src/automations.ts

@@ -0,0 +1,774 @@
+import { randomUUID } from "node:crypto";
+import {
+  getAgent,
+  getDb,
+  getOrchestrator,
+  getTask,
+  ingestIntegrationEvent,
+  listAgents,
+  listOrchestrators,
+  ValidationError,
+} from "./db";
+import { createCommand } from "./commands-db";
+import type {
+  AgentCard,
+  Automation,
+  AutomationCatchUpPolicy,
+  AutomationConcurrencyPolicy,
+  AutomationRun,
+  AutomationRunStatus,
+  AutomationTargetPolicy,
+  AutomationTaskTemplate,
+  Command,
+  CreateAutomationInput,
+  ManagedAgent,
+  Message,
+  Orchestrator,
+  Task,
+  TaskSeverity,
+  UpdateAutomationInput,
+} from "./types";
+
+const AUTOMATION_KIND = "scheduled_task";
+const DEFAULT_TIMEZONE = "UTC";
+const DEFAULT_CATCH_UP: AutomationCatchUpPolicy = "skip";
+const DEFAULT_CONCURRENCY: AutomationConcurrencyPolicy = "skip";
+const BLOCKING_RUN_STATUSES = new Set<AutomationRunStatus>(["dispatching", "waiting_agent", "running"]);
+const OPEN_RUN_STATUSES = new Set<AutomationRunStatus>(["scheduled", "dispatching", "waiting_agent", "running"]);
+const CLOSED_TASK_STATUS = new Set(["done", "failed", "canceled"]);
+const MAX_CRON_SCAN_MINUTES = 366 * 24 * 60;
+
+let initializedDb: unknown = null;
+
+export interface AutomationDispatchResult {
+  automation: Automation;
+  run: AutomationRun;
+  task?: Task;
+  message?: Message;
+  command?: Command;
+}
+
+export interface AutomationReconcileResult {
+  run: AutomationRun;
+  task?: Task;
+  command?: Command;
+}
+
+function db() {
+  return getDb();
+}
+
+function ensureAutomationTables(): void {
+  const current = db();
+  if (initializedDb === current) return;
+  initializedDb = current;
+}
+
+function parseJson<T>(value: unknown, fallback: T): T {
+  if (typeof value !== "string" || !value) return fallback;
+  try {
+    return JSON.parse(value) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+function rowToAutomation(row: any): Automation {
+  return {
+    id: row.id,
+    kind: row.kind,
+    name: row.name,
+    description: row.description ?? undefined,
+    enabled: row.enabled === 1,
+    schedule: row.schedule,
+    timezone: row.timezone,
+    nextRunAt: row.next_run_at ?? undefined,
+    catchUpPolicy: row.catch_up_policy,
+    concurrencyPolicy: row.concurrency_policy,
+    orchestratorId: row.orchestrator_id,
+    targetPolicy: parseJson<AutomationTargetPolicy>(row.target_policy, { mode: "existing_agent", selector: {}, ifNoMatch: "fail" }),
+    taskTemplate: parseJson<AutomationTaskTemplate>(row.task_template, { title: row.name, body: "" }),
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+function rowToAutomationRun(row: any): AutomationRun {
+  return {
+    id: row.id,
+    automationId: row.automation_id,
+    status: row.status,
+    scheduledFor: row.scheduled_for,
+    startedAt: row.started_at ?? undefined,
+    finishedAt: row.finished_at ?? undefined,
+    orchestratorId: row.orchestrator_id,
+    targetAgentId: row.target_agent_id ?? undefined,
+    spawnedAgentId: row.spawned_agent_id ?? undefined,
+    taskId: row.task_id ?? undefined,
+    messageId: row.message_id ?? undefined,
+    error: row.error ?? undefined,
+    result: parseJson<Record<string, unknown> | undefined>(row.result, undefined),
+    meta: parseJson<Record<string, unknown>>(row.meta, {}),
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+    shutdownRequestedAt: row.shutdown_requested_at ?? undefined,
+  };
+}
+
+function cleanString(value: unknown, field: string, opts: { required?: boolean; max?: number } = {}): string | undefined {
+  if (value === undefined || value === null) {
+    if (opts.required) throw new ValidationError(`${field} required`);
+    return undefined;
+  }
+  if (typeof value !== "string") throw new ValidationError(`${field} must be a string`);
+  const trimmed = value.trim();
+  if (opts.required && !trimmed) throw new ValidationError(`${field} required`);
+  if (opts.max && trimmed.length > opts.max) throw new ValidationError(`${field} must be ${opts.max} characters or fewer`);
+  return trimmed || undefined;
+}
+
+function cleanStringArray(value: unknown, field: string): string[] | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (!Array.isArray(value)) throw new ValidationError(`${field} must be an array`);
+  return [...new Set(value.map((item) => cleanString(item, `${field} item`, { max: 100 })).filter(Boolean) as string[])];
+}
+
+function cleanBool(value: unknown, field: string): boolean | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "boolean") throw new ValidationError(`${field} must be a boolean`);
+  return value;
+}
+
+function cleanEnum<T extends readonly string[]>(value: unknown, field: string, valid: T, fallback?: T[number]): T[number] {
+  if (value === undefined || value === null) {
+    if (fallback !== undefined) return fallback;
+    throw new ValidationError(`${field} required`);
+  }
+  if (typeof value !== "string" || !valid.includes(value)) throw new ValidationError(`${field} must be one of: ${valid.join(", ")}`);
+  return value as T[number];
+}
+
+function cleanMeta(value: unknown, field = "metadata"): Record<string, unknown> | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "object" || Array.isArray(value)) throw new ValidationError(`${field} must be an object`);
+  if (JSON.stringify(value).length > 65_536) throw new ValidationError(`${field} is too large`);
+  return value as Record<string, unknown>;
+}
+
+function normalizeTaskTemplate(value: unknown): AutomationTaskTemplate {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) throw new ValidationError("taskTemplate must be an object");
+  const input = value as Record<string, unknown>;
+  return {
+    title: cleanString(input.title, "taskTemplate.title", { required: true, max: 240 })!,
+    body: cleanString(input.body, "taskTemplate.body", { required: true, max: 200_000 })!,
+    severity: cleanEnum(input.severity, "taskTemplate.severity", ["info", "warning", "critical"] as const, "info") as TaskSeverity,
+    dedupeKey: cleanString(input.dedupeKey, "taskTemplate.dedupeKey", { max: 240 }),
+    externalUrl: cleanString(input.externalUrl, "taskTemplate.externalUrl", { max: 1000 }),
+    metadata: cleanMeta(input.metadata, "taskTemplate.metadata"),
+  };
+}
+
+function normalizeTargetPolicy(value: unknown): AutomationTargetPolicy {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) throw new ValidationError("targetPolicy must be an object");
+  const input = value as Record<string, unknown>;
+  const mode = cleanEnum(input.mode, "targetPolicy.mode", ["existing_agent", "on_demand_agent"] as const);
+  if (mode === "existing_agent") {
+    const selectorInput = (typeof input.selector === "object" && input.selector !== null && !Array.isArray(input.selector))
+      ? input.selector as Record<string, unknown>
+      : {};
+    return {
+      mode,
+      selector: {
+        provider: cleanString(selectorInput.provider, "targetPolicy.selector.provider", { max: 40 }) as "claude" | "codex" | undefined,
+        label: cleanString(selectorInput.label, "targetPolicy.selector.label", { max: 120 }),
+        tags: cleanStringArray(selectorInput.tags, "targetPolicy.selector.tags"),
+        capabilities: cleanStringArray(selectorInput.capabilities, "targetPolicy.selector.capabilities"),
+      },
+      ifNoMatch: cleanEnum(input.ifNoMatch, "targetPolicy.ifNoMatch", ["fail", "spawn"] as const, "fail"),
+    };
+  }
+  return {
+    mode,
+    provider: cleanEnum(input.provider, "targetPolicy.provider", ["claude", "codex"] as const, "codex"),
+    cwd: cleanString(input.cwd, "targetPolicy.cwd", { max: 500 }),
+    profile: cleanString(input.profile, "targetPolicy.profile", { max: 120 }),
+    approvalMode: cleanEnum(input.approvalMode, "targetPolicy.approvalMode", ["open", "guarded", "read-only"] as const, "guarded"),
+    keepAlive: cleanBool(input.keepAlive, "targetPolicy.keepAlive") ?? false,
+    shutdownAfterMs: typeof input.shutdownAfterMs === "number" && Number.isSafeInteger(input.shutdownAfterMs) && input.shutdownAfterMs >= 0
+      ? input.shutdownAfterMs
+      : undefined,
+  };
+}
+
+function normalizeCreateInput(input: CreateAutomationInput): Required<Omit<CreateAutomationInput, "description">> & { description?: string } {
+  const schedule = cleanString(input.schedule, "schedule", { required: true, max: 120 })!;
+  const timezone = cleanString(input.timezone, "timezone", { max: 80 }) ?? DEFAULT_TIMEZONE;
+  validateCron(schedule, timezone);
+  return {
+    kind: AUTOMATION_KIND,
+    name: cleanString(input.name, "name", { required: true, max: 160 })!,
+    description: cleanString(input.description, "description", { max: 2000 }),
+    enabled: cleanBool(input.enabled, "enabled") ?? true,
+    schedule,
+    timezone,
+    catchUpPolicy: cleanEnum(input.catchUpPolicy, "catchUpPolicy", ["skip", "run_once", "run_all"] as const, DEFAULT_CATCH_UP),
+    concurrencyPolicy: cleanEnum(input.concurrencyPolicy, "concurrencyPolicy", ["skip", "queue", "replace"] as const, DEFAULT_CONCURRENCY),
+    orchestratorId: cleanString(input.orchestratorId, "orchestratorId", { required: true, max: 160 })!,
+    targetPolicy: normalizeTargetPolicy(input.targetPolicy),
+    taskTemplate: normalizeTaskTemplate(input.taskTemplate),
+  };
+}
+
+export function createAutomation(input: CreateAutomationInput, now = Date.now()): Automation {
+  ensureAutomationTables();
+  const normalized = normalizeCreateInput(input);
+  if (!getOrchestrator(normalized.orchestratorId)) throw new ValidationError(`orchestrator ${normalized.orchestratorId} not found`);
+  const id = randomUUID();
+  const nextRunAt = normalized.enabled ? nextScheduledAt(normalized.schedule, normalized.timezone, now) : undefined;
+  db().prepare(`
+    INSERT INTO automations (id, kind, name, description, enabled, schedule, timezone, next_run_at, catch_up_policy, concurrency_policy, orchestrator_id, target_policy, task_template, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    id,
+    AUTOMATION_KIND,
+    normalized.name,
+    normalized.description ?? null,
+    normalized.enabled ? 1 : 0,
+    normalized.schedule,
+    normalized.timezone,
+    nextRunAt ?? null,
+    normalized.catchUpPolicy,
+    normalized.concurrencyPolicy,
+    normalized.orchestratorId,
+    JSON.stringify(normalized.targetPolicy),
+    JSON.stringify(normalized.taskTemplate),
+    now,
+    now,
+  );
+  return getAutomation(id)!;
+}
+
+export function updateAutomation(id: string, input: UpdateAutomationInput, now = Date.now()): Automation | null {
+  ensureAutomationTables();
+  const existing = getAutomation(id);
+  if (!existing) return null;
+  const next: CreateAutomationInput = {
+    kind: AUTOMATION_KIND,
+    name: input.name ?? existing.name,
+    description: input.description === null ? undefined : input.description ?? existing.description,
+    enabled: input.enabled ?? existing.enabled,
+    schedule: input.schedule ?? existing.schedule,
+    timezone: input.timezone ?? existing.timezone,
+    catchUpPolicy: input.catchUpPolicy ?? existing.catchUpPolicy,
+    concurrencyPolicy: input.concurrencyPolicy ?? existing.concurrencyPolicy,
+    orchestratorId: input.orchestratorId ?? existing.orchestratorId,
+    targetPolicy: input.targetPolicy ?? existing.targetPolicy,
+    taskTemplate: input.taskTemplate ?? existing.taskTemplate,
+  };
+  const normalized = normalizeCreateInput(next);
+  if (!getOrchestrator(normalized.orchestratorId)) throw new ValidationError(`orchestrator ${normalized.orchestratorId} not found`);
+  const nextRunAt = normalized.enabled ? nextScheduledAt(normalized.schedule, normalized.timezone, now) : undefined;
+  db().prepare(`
+    UPDATE automations
+    SET name = ?, description = ?, enabled = ?, schedule = ?, timezone = ?, next_run_at = ?,
+        catch_up_policy = ?, concurrency_policy = ?, orchestrator_id = ?, target_policy = ?, task_template = ?, updated_at = ?
+    WHERE id = ?
+  `).run(
+    normalized.name,
+    normalized.description ?? null,
+    normalized.enabled ? 1 : 0,
+    normalized.schedule,
+    normalized.timezone,
+    nextRunAt ?? null,
+    normalized.catchUpPolicy,
+    normalized.concurrencyPolicy,
+    normalized.orchestratorId,
+    JSON.stringify(normalized.targetPolicy),
+    JSON.stringify(normalized.taskTemplate),
+    now,
+    id,
+  );
+  return getAutomation(id)!;
+}
+
+export function deleteAutomation(id: string): boolean {
+  ensureAutomationTables();
+  return db().prepare("DELETE FROM automations WHERE id = ?").run(id).changes > 0;
+}
+
+export function getAutomation(id: string): Automation | null {
+  ensureAutomationTables();
+  const row = db().prepare("SELECT * FROM automations WHERE id = ?").get(id) as any;
+  return row ? rowToAutomation(row) : null;
+}
+
+export function listAutomations(): Automation[] {
+  ensureAutomationTables();
+  return (db().prepare("SELECT * FROM automations ORDER BY enabled DESC, next_run_at IS NULL, next_run_at ASC, name COLLATE NOCASE").all() as any[])
+    .map(rowToAutomation);
+}
+
+export function listAutomationRuns(filter: { automationId?: string; status?: string; limit?: number } = {}): AutomationRun[] {
+  ensureAutomationTables();
+  const clauses: string[] = [];
+  const params: (string | number)[] = [];
+  if (filter.automationId) {
+    clauses.push("automation_id = ?");
+    params.push(filter.automationId);
+  }
+  if (filter.status) {
+    clauses.push("status = ?");
+    params.push(filter.status);
+  }
+  const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
+  params.push(filter.limit ?? 100);
+  return (db().prepare(`SELECT * FROM automation_runs ${where} ORDER BY created_at DESC LIMIT ?`).all(...params) as any[])
+    .map(rowToAutomationRun);
+}
+
+function getAutomationRun(id: string): AutomationRun | null {
+  ensureAutomationTables();
+  const row = db().prepare("SELECT * FROM automation_runs WHERE id = ?").get(id) as any;
+  return row ? rowToAutomationRun(row) : null;
+}
+
+export function runDueAutomations(now = Date.now()): AutomationDispatchResult[] {
+  ensureAutomationTables();
+  const results = dispatchQueuedAutomationRuns(now);
+  const due = (db().prepare("SELECT * FROM automations WHERE enabled = 1 AND next_run_at IS NOT NULL AND next_run_at <= ? ORDER BY next_run_at ASC LIMIT 25").all(now) as any[])
+    .map(rowToAutomation);
+  for (const automation of due) {
+    if (hasActiveRun(automation.id)) {
+      if (automation.concurrencyPolicy === "replace") cancelActiveRuns(automation.id, now, "Replaced by newer scheduled run");
+      else {
+        if (automation.concurrencyPolicy === "queue") enqueueAutomationRun(automation, automation.nextRunAt ?? now, now);
+        rescheduleAutomation(automation, now);
+        continue;
+      }
+    }
+    results.push(dispatchAutomation(automation, automation.nextRunAt ?? now, now));
+    rescheduleAutomation(automation, now);
+  }
+  return results;
+}
+
+export function runAutomationNow(id: string, now = Date.now()): AutomationDispatchResult | null {
+  ensureAutomationTables();
+  const automation = getAutomation(id);
+  if (!automation) return null;
+  if (hasActiveRun(automation.id)) throw new ValidationError("automation already has an active run");
+  return dispatchAutomation(automation, now, now);
+}
+
+export function reconcileAutomationRuns(now = Date.now()): AutomationReconcileResult[] {
+  ensureAutomationTables();
+  const rows = db().prepare(`
+    SELECT * FROM automation_runs
+    WHERE status IN ('scheduled', 'dispatching', 'waiting_agent', 'running') AND task_id IS NOT NULL
+    ORDER BY created_at ASC
+  `).all() as any[];
+  const results: AutomationReconcileResult[] = [];
+  for (const row of rows) {
+    const run = rowToAutomationRun(row);
+    const task = run.taskId ? getTask(run.taskId) : null;
+    if (!task) continue;
+
+    if (task.claimedBy && task.claimedBy !== run.targetAgentId) {
+      updateRun(run.id, {
+        status: task.status === "open" ? "waiting_agent" : "running",
+        targetAgentId: task.claimedBy,
+        spawnedAgentId: run.spawnedAgentId ?? task.claimedBy,
+      }, now);
+    }
+
+    if (!CLOSED_TASK_STATUS.has(task.status)) {
+      const updated = getAutomationRun(run.id);
+      if (updated) results.push({ run: updated, task });
+      continue;
+    }
+
+    const status: AutomationRunStatus = task.status === "done" ? "succeeded" : task.status === "canceled" ? "canceled" : "failed";
+    updateRun(run.id, {
+      status,
+      finishedAt: now,
+      result: { taskStatus: task.status, result: task.result ?? null },
+      targetAgentId: task.claimedBy ?? run.targetAgentId,
+      spawnedAgentId: run.spawnedAgentId ?? task.claimedBy,
+    }, now);
+    const updated = getAutomationRun(run.id)!;
+    const command = maybeShutdownOnDemandAgent(updated, task, now);
+    results.push({ run: getAutomationRun(run.id)!, task, command });
+  }
+  return results;
+}
+
+function dispatchAutomation(automation: Automation, scheduledFor: number, now: number): AutomationDispatchResult {
+  const run = insertRun(automation, scheduledFor, now);
+  return dispatchAutomationRun(automation, run, now);
+}
+
+function dispatchAutomationRun(automation: Automation, run: AutomationRun, now: number): AutomationDispatchResult {
+  updateRun(run.id, { status: "dispatching" }, now);
+  try {
+    const orchestrator = requireOnlineOrchestrator(automation.orchestratorId);
+    if (automation.targetPolicy.mode === "existing_agent") {
+      const agent = resolveExistingAgent(automation.targetPolicy, orchestrator);
+      if (!agent && automation.targetPolicy.ifNoMatch !== "spawn") throw new ValidationError("no matching managed agent for automation");
+      if (agent) return createRunTask(automation, run, agent.id, now, { targetMode: "existing_agent" });
+      const fallbackPolicy: AutomationTargetPolicy = { mode: "on_demand_agent", provider: orchestrator.providers[0] ?? "codex", keepAlive: false };
+      return dispatchOnDemandAutomation(automation, run, orchestrator, fallbackPolicy, now);
+    }
+    return dispatchOnDemandAutomation(automation, run, orchestrator, automation.targetPolicy, now);
+  } catch (e) {
+    updateRun(run.id, {
+      status: "failed",
+      finishedAt: now,
+      error: e instanceof Error ? e.message : String(e),
+    }, now);
+    return { automation, run: getAutomationRun(run.id)! };
+  }
+}
+
+function dispatchOnDemandAutomation(
+  automation: Automation,
+  run: AutomationRun,
+  orchestrator: Orchestrator,
+  policy: Extract<AutomationTargetPolicy, { mode: "on_demand_agent" }>,
+  now: number,
+): AutomationDispatchResult {
+  if (!orchestrator.providers.includes(policy.provider)) throw new ValidationError(`orchestrator ${orchestrator.id} does not support provider ${policy.provider}`);
+  const label = automationRunLabel(automation.id, run.id);
+  const command = createCommand({
+    type: "agent.spawn",
+    source: "automation",
+    target: orchestrator.agentId,
+    params: {
+      action: "spawn",
+      provider: policy.provider,
+      cwd: policy.cwd || orchestrator.baseDir,
+      label,
+      approvalMode: policy.approvalMode ?? "guarded",
+      requestedBy: "automation",
+      requestedAt: now,
+      automationId: automation.id,
+      automationRunId: run.id,
+    },
+  });
+  const result = createRunTask(automation, run, `label:${label}`, now, {
+    targetMode: "on_demand_agent",
+    provider: policy.provider,
+    label,
+  });
+  updateRun(run.id, {
+    status: "waiting_agent",
+    meta: { ...result.run.meta, onDemandLabel: label, spawnCommandId: command.id },
+  }, now);
+  return { ...result, run: getAutomationRun(run.id)!, command };
+}
+
+function createRunTask(
+  automation: Automation,
+  run: AutomationRun,
+  target: string,
+  now: number,
+  meta: Record<string, unknown>,
+): AutomationDispatchResult {
+  const template = automation.taskTemplate;
+  const result = ingestIntegrationEvent({
+    source: "automation",
+    type: "scheduled_task",
+    severity: template.severity ?? "info",
+    title: template.title,
+    body: template.body,
+    target,
+    channel: "automation",
+    dedupeKey: template.dedupeKey ? `${template.dedupeKey}:${run.id}` : `automation:${automation.id}:run:${run.id}`,
+    externalUrl: template.externalUrl,
+    metadata: {
+      ...(template.metadata ?? {}),
+      automationId: automation.id,
+      automationRunId: run.id,
+      orchestratorId: automation.orchestratorId,
+      ...meta,
+    },
+  }, "automation");
+  updateRun(run.id, {
+    status: meta.targetMode === "on_demand_agent" ? "waiting_agent" : "running",
+    startedAt: now,
+    targetAgentId: target.startsWith("label:") ? undefined : target,
+    taskId: result.task.id,
+    messageId: result.message?.id,
+    meta,
+  }, now);
+  return { automation, run: getAutomationRun(run.id)!, task: result.task, message: result.message };
+}
+
+function insertRun(automation: Automation, scheduledFor: number, now: number): AutomationRun {
+  const id = randomUUID();
+  db().prepare(`
+    INSERT INTO automation_runs (id, automation_id, status, scheduled_for, orchestrator_id, meta, created_at, updated_at)
+    VALUES (?, ?, 'dispatching', ?, ?, '{}', ?, ?)
+  `).run(id, automation.id, scheduledFor, automation.orchestratorId, now, now);
+  return getAutomationRun(id)!;
+}
+
+function enqueueAutomationRun(automation: Automation, scheduledFor: number, now: number): AutomationRun {
+  const existing = db().prepare("SELECT * FROM automation_runs WHERE automation_id = ? AND status = 'scheduled' AND scheduled_for = ?")
+    .get(automation.id, scheduledFor) as any;
+  if (existing) return rowToAutomationRun(existing);
+  const id = randomUUID();
+  db().prepare(`
+    INSERT INTO automation_runs (id, automation_id, status, scheduled_for, orchestrator_id, meta, created_at, updated_at)
+    VALUES (?, ?, 'scheduled', ?, ?, '{}', ?, ?)
+  `).run(id, automation.id, scheduledFor, automation.orchestratorId, now, now);
+  return getAutomationRun(id)!;
+}
+
+function dispatchQueuedAutomationRuns(now: number): AutomationDispatchResult[] {
+  const queued = (db().prepare(`
+    SELECT r.* FROM automation_runs r
+    JOIN automations a ON a.id = r.automation_id
+    WHERE r.status = 'scheduled' AND a.enabled = 1
+    ORDER BY r.scheduled_for ASC
+    LIMIT 25
+  `).all() as any[]).map(rowToAutomationRun);
+  const results: AutomationDispatchResult[] = [];
+  for (const run of queued) {
+    const automation = getAutomation(run.automationId);
+    if (!automation || hasActiveRun(automation.id)) continue;
+    results.push(dispatchAutomationRun(automation, run, now));
+  }
+  return results;
+}
+
+function updateRun(id: string, input: {
+  status?: AutomationRunStatus;
+  startedAt?: number;
+  finishedAt?: number;
+  targetAgentId?: string;
+  spawnedAgentId?: string;
+  taskId?: number;
+  messageId?: number;
+  error?: string;
+  result?: Record<string, unknown>;
+  meta?: Record<string, unknown>;
+  shutdownRequestedAt?: number;
+}, now: number): void {
+  const current = getAutomationRun(id);
+  const meta = input.meta !== undefined ? input.meta : current?.meta;
+  db().prepare(`
+    UPDATE automation_runs
+    SET status = COALESCE(?, status),
+        started_at = COALESCE(?, started_at),
+        finished_at = COALESCE(?, finished_at),
+        target_agent_id = COALESCE(?, target_agent_id),
+        spawned_agent_id = COALESCE(?, spawned_agent_id),
+        task_id = COALESCE(?, task_id),
+        message_id = COALESCE(?, message_id),
+        control_message_id = control_message_id,
+        error = COALESCE(?, error),
+        result = COALESCE(?, result),
+        meta = COALESCE(?, meta),
+        shutdown_requested_at = COALESCE(?, shutdown_requested_at),
+        updated_at = ?
+    WHERE id = ?
+  `).run(
+    input.status ?? null,
+    input.startedAt ?? null,
+    input.finishedAt ?? null,
+    input.targetAgentId ?? null,
+    input.spawnedAgentId ?? null,
+    input.taskId ?? null,
+    input.messageId ?? null,
+    input.error ?? null,
+    input.result ? JSON.stringify(input.result) : null,
+    meta ? JSON.stringify(meta) : null,
+    input.shutdownRequestedAt ?? null,
+    now,
+    id,
+  );
+}
+
+function hasActiveRun(automationId: string): boolean {
+  const placeholders = [...BLOCKING_RUN_STATUSES].map(() => "?").join(",");
+  const row = db().prepare(`SELECT id FROM automation_runs WHERE automation_id = ? AND status IN (${placeholders}) LIMIT 1`)
+    .get(automationId, ...BLOCKING_RUN_STATUSES) as any;
+  return Boolean(row);
+}
+
+function cancelActiveRuns(automationId: string, now: number, reason: string): void {
+  const placeholders = [...OPEN_RUN_STATUSES].map(() => "?").join(",");
+  db().prepare(`UPDATE automation_runs SET status = 'canceled', finished_at = ?, error = ?, updated_at = ? WHERE automation_id = ? AND status IN (${placeholders})`)
+    .run(now, reason, now, automationId, ...OPEN_RUN_STATUSES);
+}
+
+function rescheduleAutomation(automation: Automation, now: number): void {
+  const next = automation.enabled ? nextScheduledAt(automation.schedule, automation.timezone, now) : undefined;
+  db().prepare("UPDATE automations SET next_run_at = ?, updated_at = ? WHERE id = ?").run(next ?? null, now, automation.id);
+}
+
+function requireOnlineOrchestrator(orchestratorId: string): Orchestrator {
+  const orchestrator = getOrchestrator(orchestratorId);
+  if (!orchestrator) throw new ValidationError(`orchestrator ${orchestratorId} not found`);
+  if (orchestrator.status !== "online") throw new ValidationError(`orchestrator ${orchestratorId} is ${orchestrator.status}`);
+  return orchestrator;
+}
+
+function resolveExistingAgent(policy: Extract<AutomationTargetPolicy, { mode: "existing_agent" }>, orchestrator: Orchestrator): AgentCard | null {
+  const managedIds = new Set(orchestrator.managedAgents.map((agent) => agent.agentId).filter(Boolean));
+  const candidates = listAgents()
+    .filter((agent) => agent.id !== "user" && agent.id !== "system" && agent.kind !== "channel" && agent.kind !== "orchestrator")
+    .filter((agent) => agent.ready && agent.status !== "offline")
+    .filter((agent) => managedIds.size === 0 || managedIds.has(agent.id))
+    .filter((agent) => automationAgentMatchesSelector(agent, policy.selector));
+  candidates.sort((a, b) => b.lastSeen - a.lastSeen);
+  return candidates[0] ?? null;
+}
+
+function automationAgentMatchesSelector(agent: AgentCard, selector: Extract<AutomationTargetPolicy, { mode: "existing_agent" }>["selector"]): boolean {
+  if (selector.provider) {
+    const provider = typeof agent.meta?.provider === "string" ? agent.meta.provider : undefined;
+    if (provider !== selector.provider && !agent.tags.includes(selector.provider)) return false;
+  }
+  if (selector.label && agent.label !== selector.label) return false;
+  if (selector.tags?.length && !selector.tags.every((tag) => agent.tags.includes(tag))) return false;
+  if (selector.capabilities?.length && !selector.capabilities.every((cap) => agent.capabilities.includes(cap))) return false;
+  return true;
+}
+
+function maybeShutdownOnDemandAgent(run: AutomationRun, task: Task, now: number): Command | undefined {
+  if (run.shutdownRequestedAt) return undefined;
+  const automation = getAutomation(run.automationId);
+  if (!automation || automation.targetPolicy.mode !== "on_demand_agent" || automation.targetPolicy.keepAlive) return undefined;
+  const agentId = task.claimedBy ?? run.targetAgentId ?? run.spawnedAgentId;
+  if (!agentId) return undefined;
+  const command = createCommand({
+    type: "agent.shutdown",
+    source: "automation",
+    target: agentId,
+    params: {
+      action: "shutdown",
+      agentId,
+      requestedBy: "automation",
+      requestedAt: now,
+      automationId: automation.id,
+      automationRunId: run.id,
+    },
+  });
+  updateRun(run.id, { shutdownRequestedAt: now, meta: { ...run.meta, shutdownCommandId: command.id } }, now);
+  return command;
+}
+
+function automationRunLabel(automationId: string, runId: string): string {
+  return `automation-${automationId.slice(0, 8)}-${runId.slice(0, 8)}`;
+}
+
+function validateCron(expression: string, timezone: string): void {
+  parseCron(expression);
+  localParts(Date.now(), timezone);
+}
+
+function nextScheduledAt(expression: string, timezone: string, afterMs: number): number {
+  const cron = parseCron(expression);
+  let cursor = Math.floor(afterMs / 60_000) * 60_000 + 60_000;
+  for (let i = 0; i < MAX_CRON_SCAN_MINUTES; i += 1) {
+    const parts = localParts(cursor, timezone);
+    if (cronMatches(cron, parts)) return cursor;
+    cursor += 60_000;
+  }
+  throw new ValidationError("schedule has no matching time in the next year");
+}
+
+interface CronSpec {
+  minute: Set<number>;
+  hour: Set<number>;
+  dayOfMonth: Set<number>;
+  month: Set<number>;
+  dayOfWeek: Set<number>;
+  domAny: boolean;
+  dowAny: boolean;
+}
+
+interface LocalTimeParts {
+  minute: number;
+  hour: number;
+  dayOfMonth: number;
+  month: number;
+  dayOfWeek: number;
+}
+
+function parseCron(expression: string): CronSpec {
+  const parts = expression.trim().split(/\s+/);
+  if (parts.length !== 5) throw new ValidationError("schedule must be a 5-field cron expression");
+  const [minute, hour, dom, month, dow] = parts as [string, string, string, string, string];
+  return {
+    minute: parseCronField(minute, 0, 59, "minute"),
+    hour: parseCronField(hour, 0, 23, "hour"),
+    dayOfMonth: parseCronField(dom, 1, 31, "dayOfMonth"),
+    month: parseCronField(month, 1, 12, "month"),
+    dayOfWeek: parseCronField(dow.replace(/\b7\b/g, "0"), 0, 6, "dayOfWeek"),
+    domAny: dom === "*",
+    dowAny: dow === "*",
+  };
+}
+
+function parseCronField(field: string, min: number, max: number, name: string): Set<number> {
+  const values = new Set<number>();
+  for (const rawPart of field.split(",")) {
+    const part = rawPart.trim();
+    if (!part) throw new ValidationError(`${name} cron field is empty`);
+    const [rangePart, stepRaw] = part.split("/");
+    const step = stepRaw === undefined ? 1 : Number(stepRaw);
+    if (!Number.isInteger(step) || step <= 0) throw new ValidationError(`${name} cron step must be a positive integer`);
+    let start: number;
+    let end: number;
+    if (rangePart === "*") {
+      start = min;
+      end = max;
+    } else if (rangePart?.includes("-")) {
+      const [startRaw, endRaw] = rangePart.split("-");
+      start = Number(startRaw);
+      end = Number(endRaw);
+    } else {
+      start = Number(rangePart);
+      end = start;
+    }
+    if (!Number.isInteger(start) || !Number.isInteger(end) || start < min || end > max || start > end) {
+      throw new ValidationError(`${name} cron field is out of range`);
+    }
+    for (let value = start; value <= end; value += step) values.add(value);
+  }
+  return values;
+}
+
+function localParts(timestamp: number, timezone: string): LocalTimeParts {
+  const dtf = new Intl.DateTimeFormat("en-US", {
+    timeZone: timezone,
+    minute: "numeric",
+    hour: "numeric",
+    hourCycle: "h23",
+    day: "numeric",
+    month: "numeric",
+    weekday: "short",
+  });
+  const parts = Object.fromEntries(dtf.formatToParts(new Date(timestamp)).map((part) => [part.type, part.value]));
+  const dow = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"].indexOf(parts.weekday ?? "");
+  if (dow < 0) throw new ValidationError(`invalid timezone: ${timezone}`);
+  return {
+    minute: Number(parts.minute),
+    hour: Number(parts.hour),
+    dayOfMonth: Number(parts.day),
+    month: Number(parts.month),
+    dayOfWeek: dow,
+  };
+}
+
+function cronMatches(cron: CronSpec, parts: LocalTimeParts): boolean {
+  if (!cron.minute.has(parts.minute) || !cron.hour.has(parts.hour) || !cron.month.has(parts.month)) return false;
+  const domMatch = cron.dayOfMonth.has(parts.dayOfMonth);
+  const dowMatch = cron.dayOfWeek.has(parts.dayOfWeek);
+  if (cron.domAny && cron.dowAny) return true;
+  if (cron.domAny) return dowMatch;
+  if (cron.dowAny) return domMatch;
+  return domMatch || dowMatch;
+}