agent-relay-server 0.62.3 → 0.63.1

package/src/automations/storage.ts

@@ -0,0 +1,181 @@
+import { randomUUID } from "node:crypto";
+import { parseJson } from "../utils";
+import { getDb } from "../db";
+import { BLOCKING_RUN_STATUSES, OPEN_RUN_STATUSES } from "./constants";
+import type { Automation, AutomationRun, AutomationRunStatus, AutomationTargetPolicy, AutomationTaskTemplate } from "../types";
+
+let initializedDb: unknown = null;
+
+export function db() {
+  return getDb();
+}
+
+export function ensureAutomationTables(): void {
+  const current = db();
+  if (initializedDb === current) return;
+  initializedDb = current;
+}
+
+export 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,
+  };
+}
+
+export 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,
+  };
+}
+
+export function getAutomation(id: string): Automation | null {
+  ensureAutomationTables();
+  const row = db().query("SELECT * FROM automations WHERE id = ?").get(id) as any;
+  return row ? rowToAutomation(row) : null;
+}
+
+export function listAutomations(): Automation[] {
+  ensureAutomationTables();
+  return (db().query("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().query(`SELECT * FROM automation_runs ${where} ORDER BY created_at DESC LIMIT ?`).all(...params) as any[])
+    .map(rowToAutomationRun);
+}
+
+export function getAutomationRun(id: string): AutomationRun | null {
+  ensureAutomationTables();
+  const row = db().query("SELECT * FROM automation_runs WHERE id = ?").get(id) as any;
+  return row ? rowToAutomationRun(row) : null;
+}
+
+export function insertRun(automation: Automation, scheduledFor: number, now: number): AutomationRun {
+  const id = randomUUID();
+  db().query(`
+    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)!;
+}
+
+export function enqueueAutomationRun(automation: Automation, scheduledFor: number, now: number): AutomationRun {
+  const existing = db().query("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().query(`
+    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)!;
+}
+
+export 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().query(`
+    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,
+  );
+}
+
+export function hasActiveRun(automationId: string): boolean {
+  const placeholders = [...BLOCKING_RUN_STATUSES].map(() => "?").join(",");
+  const row = db().query(`SELECT id FROM automation_runs WHERE automation_id = ? AND status IN (${placeholders}) LIMIT 1`)
+    .get(automationId, ...BLOCKING_RUN_STATUSES) as any;
+  return Boolean(row);
+}
+
+export function cancelActiveRuns(automationId: string, now: number, reason: string): void {
+  const placeholders = [...OPEN_RUN_STATUSES].map(() => "?").join(",");
+  db().query(`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);
+}
+
+export function rescheduleAutomation(automation: Automation, nextRunAt: number | undefined, now: number): void {
+  db().query("UPDATE automations SET next_run_at = ?, updated_at = ? WHERE id = ?").run(nextRunAt ?? null, now, automation.id);
+}

package/src/automations/types.ts

@@ -0,0 +1,16 @@
+import type { Automation, AutomationRun, Command, Message, Task } from "../types";
+
+export interface AutomationDispatchResult {
+  automation: Automation;
+  run: AutomationRun;
+  task?: Task;
+  message?: Message;
+  command?: Command;
+}
+
+export interface AutomationReconcileResult {
+  run: AutomationRun;
+  task?: Task;
+  message?: Message;
+  command?: Command;
+}

package/src/automations/validation.ts

@@ -0,0 +1,140 @@
+import { errMessage, VALID_WORKSPACE_MODES } from "agent-relay-sdk";
+import { resolveProviderSelection, type ProviderEffort } from "agent-relay-sdk/provider-catalog";
+import { getAgentProfile } from "../config-store";
+import { ValidationError } from "../db";
+import { effectiveProviderCatalogList } from "../provider-catalog-store";
+import { cleanEnum, cleanString, cleanStringArray, optionalEnum } from "../validation";
+import { DEFAULT_CATCH_UP, DEFAULT_CONCURRENCY, DEFAULT_TIMEZONE, MAX_RUNTIME_BUDGET_MS, MIN_RUNTIME_BUDGET_MS, AUTOMATION_KIND } from "./constants";
+import { validateCron } from "./cron";
+import type {
+  AutomationRuntimeBudget,
+  AutomationTargetPolicy,
+  AutomationTaskTemplate,
+  CreateAutomationInput,
+  TaskSeverity,
+} from "../types";
+
+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 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: optionalEnum(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 normalizeRuntimeBudget(input: Record<string, unknown>): AutomationRuntimeBudget | undefined {
+  const rawBudget = input.runtimeBudget;
+  let budgetInput: Record<string, unknown> | undefined;
+  if (rawBudget !== undefined && rawBudget !== null) {
+    if (typeof rawBudget !== "object" || Array.isArray(rawBudget)) throw new ValidationError("targetPolicy.runtimeBudget must be an object");
+    budgetInput = rawBudget as Record<string, unknown>;
+  } else if (typeof input.shutdownAfterMs === "number" && input.shutdownAfterMs > 0) {
+    budgetInput = { maxRuntimeMs: input.shutdownAfterMs };
+  }
+  if (!budgetInput) return undefined;
+
+  const maxRuntimeMsRaw = budgetInput.maxRuntimeMs;
+  if (!Number.isSafeInteger(maxRuntimeMsRaw)) {
+    throw new ValidationError("targetPolicy.runtimeBudget.maxRuntimeMs must be between 60000 and 86400000");
+  }
+  const maxRuntimeMs = maxRuntimeMsRaw as number;
+  if (maxRuntimeMs < MIN_RUNTIME_BUDGET_MS || maxRuntimeMs > MAX_RUNTIME_BUDGET_MS) {
+    throw new ValidationError("targetPolicy.runtimeBudget.maxRuntimeMs must be between 60000 and 86400000");
+  }
+  const warnAtMsRaw = budgetInput.warnAtMs;
+  if (warnAtMsRaw !== undefined && !Number.isSafeInteger(warnAtMsRaw)) {
+    throw new ValidationError("targetPolicy.runtimeBudget.warnAtMs must be less than maxRuntimeMs");
+  }
+  const warnAtMs = warnAtMsRaw as number | undefined;
+  if (warnAtMs !== undefined && (warnAtMs < 0 || warnAtMs >= maxRuntimeMs)) {
+    throw new ValidationError("targetPolicy.runtimeBudget.warnAtMs must be less than maxRuntimeMs");
+  }
+  return {
+    maxRuntimeMs,
+    warnAtMs,
+    warningMessage: cleanString(budgetInput.warningMessage, "targetPolicy.runtimeBudget.warningMessage", { max: 4000 }),
+  };
+}
+
+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", { itemMax: 100 }),
+        capabilities: cleanStringArray(selectorInput.capabilities, "targetPolicy.selector.capabilities", { itemMax: 100 }),
+      },
+      ifNoMatch: optionalEnum(input.ifNoMatch, "targetPolicy.ifNoMatch", ["fail", "spawn"] as const, "fail"),
+    };
+  }
+  const provider = optionalEnum(input.provider, "targetPolicy.provider", ["claude", "codex"] as const, "codex");
+  const model = cleanString(input.model, "targetPolicy.model", { max: 120 });
+  const effort = cleanString(input.effort, "targetPolicy.effort", { max: 120 }) as ProviderEffort | undefined;
+  const profile = cleanString(input.profile, "targetPolicy.profile", { max: 120 });
+  if (profile && !getAgentProfile(profile)) throw new ValidationError("agent profile not found");
+  try {
+    resolveProviderSelection({ provider, model, effort }, effectiveProviderCatalogList());
+  } catch (error) {
+    throw new ValidationError(errMessage(error));
+  }
+  return {
+    mode,
+    provider,
+    model,
+    effort,
+    cwd: cleanString(input.cwd, "targetPolicy.cwd", { max: 500 }),
+    workspaceMode: optionalEnum(input.workspaceMode, "targetPolicy.workspaceMode", VALID_WORKSPACE_MODES, "inherit"),
+    profile,
+    approvalMode: optionalEnum(input.approvalMode, "targetPolicy.approvalMode", ["open", "guarded", "read-only"] as const, "guarded"),
+    keepAlive: cleanBool(input.keepAlive, "targetPolicy.keepAlive") ?? false,
+    runtimeBudget: normalizeRuntimeBudget(input),
+    shutdownAfterMs: typeof input.shutdownAfterMs === "number" && Number.isSafeInteger(input.shutdownAfterMs) && input.shutdownAfterMs >= 0
+      ? input.shutdownAfterMs
+      : undefined,
+  };
+}
+
+export 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: optionalEnum(input.catchUpPolicy, "catchUpPolicy", ["skip", "run_once", "run_all"] as const, DEFAULT_CATCH_UP),
+    concurrencyPolicy: optionalEnum(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),
+  };
+}