agent-relay-server 0.62.3 → 0.63.0

package/src/automations/reconcile.ts

@@ -0,0 +1,245 @@
+import { createCommand } from "../commands-db";
+import { getAgent, getTask, listOrchestrators, sendMessage, updateTaskStatus } from "../db";
+import { CLOSED_TASK_STATUS } from "./constants";
+import {
+  ensureAutomationTables,
+  getAutomation,
+  getAutomationRun,
+  rowToAutomationRun,
+  updateRun,
+  db,
+} from "./storage";
+import type { AutomationReconcileResult } from "./types";
+import type { AutomationRun, AutomationRunStatus, AutomationRuntimeBudget, Command, Message, Task } from "../types";
+
+export function reconcileAutomationRuns(now = Date.now()): AutomationReconcileResult[] {
+  ensureAutomationTables();
+  const rows = db().query(`
+    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;
+
+    const runtimeMeta = automationRunRuntimeMeta(run, task);
+    const hasRuntimeMetaChange = hasMetaChanges(run.meta, runtimeMeta);
+    const nextOpenStatus: AutomationRunStatus = task.status === "open" ? "waiting_agent" : "running";
+    if ((task.claimedBy && task.claimedBy !== run.targetAgentId) || run.status !== nextOpenStatus || hasRuntimeMetaChange) {
+      updateRun(run.id, {
+        status: nextOpenStatus,
+        targetAgentId: task.claimedBy ?? run.targetAgentId,
+        spawnedAgentId: run.spawnedAgentId ?? task.claimedBy,
+        meta: hasRuntimeMetaChange ? { ...run.meta, ...runtimeMeta } : undefined,
+      }, now);
+    }
+
+    if (!CLOSED_TASK_STATUS.has(task.status)) {
+      const updated = getAutomationRun(run.id);
+      if (!updated) continue;
+      const timedOut = maybeTimeoutRuntimeBudget(updated, task, now);
+      if (timedOut) {
+        results.push(timedOut);
+        continue;
+      }
+      const warning = maybeWarnRuntimeBudget(updated, task, now);
+      results.push({ run: getAutomationRun(run.id) ?? updated, task, message: warning });
+      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,
+      meta: hasMetaChanges(run.meta, runtimeMeta) ? { ...run.meta, ...runtimeMeta } : undefined,
+    }, now);
+    const updated = getAutomationRun(run.id)!;
+    const command = maybeShutdownOnDemandAgent(updated, task, now);
+    results.push({ run: getAutomationRun(run.id)!, task, command });
+  }
+  return results;
+}
+
+function automationRunRuntimeMeta(run: AutomationRun, task: Task): Record<string, unknown> {
+  const agentId = task.claimedBy ?? run.targetAgentId ?? run.spawnedAgentId;
+  if (!agentId) return {};
+  const agent = getAgent(agentId);
+  const managed = listOrchestrators()
+    .flatMap((orchestrator) => orchestrator.managedAgents.map((managedAgent) => ({ orchestrator, managedAgent })))
+    .find(({ managedAgent }) => managedAgent.agentId === agentId);
+  const agentMeta = agent?.meta;
+  return compactMeta({
+    runtimeAgentId: agentId,
+    runtimeAgentStatus: agent?.status,
+    runtimeAgentReady: agent?.ready,
+    provider: stringMeta(agentMeta, "provider") ?? managed?.managedAgent.provider,
+    profile: stringMeta(agentMeta, "profile") ?? managed?.managedAgent.profile,
+    cwd: stringMeta(agentMeta, "cwd") ?? managed?.managedAgent.cwd,
+    label: agent?.label ?? stringMeta(agentMeta, "label") ?? managed?.managedAgent.label,
+    sessionName: stringMeta(agentMeta, "sessionName") ?? managed?.managedAgent.sessionName,
+    tmuxSession: stringMeta(agentMeta, "tmuxSession") ?? managed?.managedAgent.tmuxSession,
+    terminalSession: stringMeta(agentMeta, "terminalSession") ?? managed?.managedAgent.terminalSession,
+    orchestratorId: managed?.orchestrator.id ?? run.orchestratorId,
+  });
+}
+
+function compactMeta(input: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined && value !== null && value !== ""));
+}
+
+function stringMeta(meta: Record<string, unknown> | undefined, key: string): string | undefined {
+  const value = meta?.[key];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function hasMetaChanges(current: Record<string, unknown>, patch: Record<string, unknown>): boolean {
+  return Object.entries(patch).some(([key, value]) => current[key] !== value);
+}
+
+function runtimeBudgetForRun(run: AutomationRun): AutomationRuntimeBudget | undefined {
+  const automation = getAutomation(run.automationId);
+  if (!automation || automation.targetPolicy.mode !== "on_demand_agent") return undefined;
+  return automation.targetPolicy.runtimeBudget;
+}
+
+function runtimeDeadline(run: AutomationRun, budget: AutomationRuntimeBudget): number | undefined {
+  return run.startedAt ? run.startedAt + budget.maxRuntimeMs : undefined;
+}
+
+function runtimeWarningAt(run: AutomationRun, budget: AutomationRuntimeBudget): number | undefined {
+  if (budget.warnAtMs === undefined || !run.startedAt) return undefined;
+  return run.startedAt + budget.warnAtMs;
+}
+
+function maybeWarnRuntimeBudget(run: AutomationRun, task: Task, now: number): Message | undefined {
+  if (run.meta.runtimeBudgetWarnedAt) return undefined;
+  const budget = runtimeBudgetForRun(run);
+  if (!budget) return undefined;
+  const warnAt = runtimeWarningAt(run, budget);
+  const deadline = runtimeDeadline(run, budget);
+  if (warnAt === undefined || deadline === undefined || now < warnAt || now >= deadline) return undefined;
+  const target = runtimeBudgetMessageTarget(run, task);
+  if (!target) return undefined;
+  const remainingMinutes = Math.max(1, Math.ceil((deadline - now) / 60_000));
+  const message = sendMessage({
+    from: "system",
+    to: target,
+    kind: "control",
+    subject: "Automation runtime budget warning",
+    body: budget.warningMessage ?? `Runtime budget warning: this automation run will be shut down in about ${remainingMinutes} minute${remainingMinutes === 1 ? "" : "s"}. Finish current work, commit and push anything worth keeping, then stop cleanly before the deadline.`,
+    payload: {
+      automationId: run.automationId,
+      automationRunId: run.id,
+      taskId: task.id,
+      runtimeBudgetWarning: true,
+      maxRuntimeMs: budget.maxRuntimeMs,
+      warnAtMs: budget.warnAtMs,
+      deadlineAt: deadline,
+    },
+    meta: {
+      source: "automation",
+      automationId: run.automationId,
+      automationRunId: run.id,
+      runtimeBudgetWarning: true,
+    },
+  });
+  updateRun(run.id, {
+    meta: {
+      ...run.meta,
+      runtimeBudgetWarnedAt: now,
+      runtimeBudgetWarningMessageId: message.id,
+      runtimeBudgetDeadlineAt: deadline,
+    },
+  }, now);
+  return message;
+}
+
+function maybeTimeoutRuntimeBudget(run: AutomationRun, task: Task, now: number): AutomationReconcileResult | undefined {
+  const budget = runtimeBudgetForRun(run);
+  if (!budget) return undefined;
+  const deadline = runtimeDeadline(run, budget);
+  if (deadline === undefined || now < deadline) return undefined;
+
+  const agentId = task.claimedBy ?? run.targetAgentId ?? run.spawnedAgentId;
+  const taskResult = updateTaskStatus(task.id, {
+    status: "canceled",
+    agentId,
+    result: "Automation runtime budget elapsed",
+    body: "Automation runtime budget elapsed",
+    metadata: {
+      automationId: run.automationId,
+      automationRunId: run.id,
+      runtimeBudgetElapsed: true,
+      runtimeBudgetTimedOut: true,
+      maxRuntimeMs: budget.maxRuntimeMs,
+      deadlineAt: deadline,
+    },
+  });
+  const updatedTask = taskResult.task ?? getTask(task.id) ?? task;
+  const command = requestOnDemandAgentShutdown(run, updatedTask, now, "runtime-budget-timeout");
+  updateRun(run.id, {
+    status: "timed_out",
+    finishedAt: now,
+    error: "Automation runtime budget elapsed",
+    result: {
+      taskStatus: updatedTask.status,
+      runtimeBudgetElapsed: true,
+      runtimeBudgetTimedOut: true,
+      maxRuntimeMs: budget.maxRuntimeMs,
+      deadlineAt: deadline,
+    },
+    targetAgentId: agentId,
+    spawnedAgentId: run.spawnedAgentId ?? agentId,
+    shutdownRequestedAt: command ? now : undefined,
+    meta: {
+      ...run.meta,
+      runtimeBudgetElapsedAt: now,
+      runtimeBudgetTimedOutAt: now,
+      runtimeBudgetDeadlineAt: deadline,
+      ...(command ? { shutdownCommandId: command.id } : {}),
+    },
+  }, now);
+  return { run: getAutomationRun(run.id)!, task: getTask(task.id) ?? updatedTask, command };
+}
+
+function runtimeBudgetMessageTarget(run: AutomationRun, task: Task): string | undefined {
+  if (task.claimedBy) return task.claimedBy;
+  if (run.targetAgentId) return run.targetAgentId;
+  if (run.spawnedAgentId) return run.spawnedAgentId;
+  if (typeof run.meta.onDemandLabel === "string" && run.meta.onDemandLabel) return `label:${run.meta.onDemandLabel}`;
+  return undefined;
+}
+
+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 command = requestOnDemandAgentShutdown(run, task, now, "task-complete");
+  if (command) updateRun(run.id, { shutdownRequestedAt: now, meta: { ...run.meta, shutdownCommandId: command.id } }, now);
+  return command;
+}
+
+function requestOnDemandAgentShutdown(run: AutomationRun, task: Task, now: number, reason: string): Command | undefined {
+  const agentId = task.claimedBy ?? run.targetAgentId ?? run.spawnedAgentId;
+  if (!agentId) return undefined;
+  return createCommand({
+    type: "agent.shutdown",
+    source: "automation",
+    target: agentId,
+    params: {
+      action: "shutdown",
+      agentId,
+      requestedBy: "automation",
+      requestedAt: now,
+      automationId: run.automationId,
+      automationRunId: run.id,
+      reason,
+    },
+  });
+}

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),
+  };
+}