agent-relay-server 0.62.2 → 0.63.0

package/src/automations/dispatch.ts

@@ -0,0 +1,275 @@
+import { errMessage } from "agent-relay-sdk";
+import { createCommand } from "../commands-db";
+import { getAgentProfile, getSpawnPolicy } from "../config-store";
+import { getOrchestrator, ingestIntegrationEvent, listAgents, ValidationError } from "../db";
+import { runnerRuntimeTokenEnv } from "../runtime-tokens";
+import { buildSpawnCommand, resolveSpawnModelParams } from "../spawn-command";
+import { nextScheduledAt, formatRunDate } from "./cron";
+import {
+  cancelActiveRuns,
+  db,
+  enqueueAutomationRun,
+  ensureAutomationTables,
+  getAutomation,
+  getAutomationRun,
+  hasActiveRun,
+  insertRun,
+  listAutomations,
+  rowToAutomation,
+  rowToAutomationRun,
+  updateRun,
+  rescheduleAutomation as persistNextRun,
+} from "./storage";
+import type { AutomationDispatchResult } from "./types";
+import type { AgentCard, Automation, AutomationTargetPolicy, ManagedAgent, Orchestrator } from "../types";
+
+export function runDueAutomations(now = Date.now()): AutomationDispatchResult[] {
+  ensureAutomationTables();
+  const results = dispatchQueuedAutomationRuns(now);
+  const due = (db().query("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);
+}
+
+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: ReturnType<typeof getAutomationRun> & NonNullable<unknown>, 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) {
+        const durableTarget = durableExistingAgentTarget(automation.targetPolicy);
+        return createRunTask(automation, run, durableTarget, now, { targetMode: "existing_agent", resolvedAgentId: agent.id });
+      }
+      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: errMessage(e),
+    }, now);
+    return { automation, run: getAutomationRun(run.id)! };
+  }
+}
+
+function dispatchOnDemandAutomation(
+  automation: Automation,
+  run: ReturnType<typeof getAutomationRun> & NonNullable<unknown>,
+  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 have provider available: ${policy.provider}`);
+  const agentProfile = policy.profile ? getAgentProfile(policy.profile)?.value : undefined;
+  const label = automationRunLabel(automation.id, run.id);
+  const command = createCommand({
+    type: "agent.spawn",
+    source: "automation",
+    target: orchestrator.agentId,
+    params: buildSpawnCommand({
+      provider: policy.provider,
+      modelParams: resolveSpawnModelParams(policy.provider, policy.model, policy.effort),
+      profile: policy.profile,
+      agentProfile,
+      cwd: policy.cwd || orchestrator.baseDir,
+      workspaceMode: policy.workspaceMode ?? "inherit",
+      label,
+      approvalMode: policy.approvalMode ?? "guarded",
+      requestedBy: "automation",
+      requestedAt: now,
+      automationId: automation.id,
+      automationRunId: run.id,
+      env: runnerRuntimeTokenEnv({
+        orchestratorId: orchestrator.id,
+        cwd: policy.cwd || orchestrator.baseDir,
+        provider: policy.provider,
+        label,
+        createdBy: "automation",
+        profile: policy.profile,
+      }),
+    }),
+  });
+  const result = createRunTask(automation, run, `label:${label}`, now, {
+    targetMode: "on_demand_agent",
+    provider: policy.provider,
+    label,
+    profile: policy.profile,
+    workspaceMode: policy.workspaceMode ?? "inherit",
+  });
+  updateRun(run.id, {
+    status: "waiting_agent",
+    meta: { ...result.run.meta, onDemandLabel: label, spawnCommandId: command.id, workspaceMode: policy.workspaceMode ?? "inherit" },
+  }, now);
+  return { ...result, run: getAutomationRun(run.id)!, command };
+}
+
+function createRunTask(
+  automation: Automation,
+  run: ReturnType<typeof getAutomationRun> & NonNullable<unknown>,
+  target: string,
+  now: number,
+  meta: Record<string, unknown>,
+): AutomationDispatchResult {
+  const template = automation.taskTemplate;
+  // Inject the authoritative dispatch-time run date (#480). A long-lived managed agent's
+  // session-start day awareness goes stale across midnight, so it can't be trusted to derive
+  // "today" - the briefing emitted "Monday Jun 16" when it ran on a Tuesday. The scheduled
+  // instant + timezone are authoritative here; surface them so the task never depends on the
+  // model's recollection. Templates may place it via {{runDate}}/{{runWeekday}}/{{runDateLine}};
+  // otherwise we prepend a Run date line so every scheduled task carries it.
+  const runDate = formatRunDate(run.scheduledFor, automation.timezone);
+  const tokens: Record<string, string> = { runDate: runDate.iso, runWeekday: runDate.weekday, runDateLine: runDate.line };
+  const fill = (text: string) => text.replace(/\{\{\s*(runDate|runWeekday|runDateLine)\s*\}\}/g, (_match, key) => tokens[key] ?? "");
+  const usesRunDateToken = /\{\{\s*(runDate|runWeekday|runDateLine)\s*\}\}/.test(`${template.title}\n${template.body}`);
+  const title = fill(template.title);
+  const body = usesRunDateToken ? fill(template.body) : `Run date: ${runDate.line}.\n\n${template.body}`;
+  const result = ingestIntegrationEvent({
+    source: "automation",
+    type: "scheduled_task",
+    severity: template.severity ?? "info",
+    title,
+    body,
+    target,
+    channel: "automation",
+    // #479 - automation tasks complete via the task-status lifecycle (claim -> done), never a
+    // `/reply`. A reply obligation here is unsatisfiable and re-injects the task into every
+    // successor session when a restart-prone managed agent (e.g. the daily telegram briefing)
+    // mints a new agent id, re-firing the scheduled work off-schedule. Dispatch without one.
+    replyExpected: false,
+    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,
+      runDate: runDate.iso,
+      runWeekday: runDate.weekday,
+      runTimezone: automation.timezone,
+      ...meta,
+    },
+  }, "automation");
+  updateRun(run.id, {
+    status: meta.targetMode === "on_demand_agent" ? "waiting_agent" : "running",
+    startedAt: now,
+    targetAgentId: typeof meta.resolvedAgentId === "string"
+      ? meta.resolvedAgentId
+      : target.startsWith("label:") || target.startsWith("cap:")
+        ? 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 durableExistingAgentTarget(policy: Extract<AutomationTargetPolicy, { mode: "existing_agent" }>): string {
+  const label = policy.selector.label?.trim();
+  if (label) return `label:${label}`;
+  const cap = policy.selector.capabilities?.find((item) => item.trim().length > 0)?.trim();
+  if (cap) return `cap:${cap}`;
+  throw new ValidationError("existing-agent automation target selector must include a label or capability");
+}
+
+function dispatchQueuedAutomationRuns(now: number): AutomationDispatchResult[] {
+  const queued = (db().query(`
+    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 rescheduleAutomation(automation: Automation, now: number): void {
+  const next = automation.enabled ? nextScheduledAt(automation.schedule, automation.timezone, now) : undefined;
+  persistNextRun(automation, next, now);
+}
+
+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 managedAgentsById = new Map(orchestrator.managedAgents.map((agent) => [agent.agentId, agent]));
+  const managedIds = new Set(managedAgentsById.keys());
+  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, managedAgentsById.get(agent.id)));
+  candidates.sort((a, b) => b.lastSeen - a.lastSeen);
+  return candidates[0] ?? null;
+}
+
+function automationAgentMatchesSelector(
+  agent: AgentCard,
+  selector: Extract<AutomationTargetPolicy, { mode: "existing_agent" }>["selector"],
+  managedAgent?: ManagedAgent,
+): boolean {
+  const policyName = managedAgent?.policyName ?? (typeof agent.meta?.policyName === "string" ? agent.meta.policyName : undefined);
+  const spawnPolicy = policyName ? getSpawnPolicy(policyName)?.value : undefined;
+  const tags = new Set([...agent.tags, ...stringArray((managedAgent as { tags?: unknown } | undefined)?.tags), ...(spawnPolicy?.tags ?? [])]);
+  const capabilities = new Set([
+    ...agent.capabilities,
+    ...stringArray((managedAgent as { capabilities?: unknown } | undefined)?.capabilities),
+    ...(spawnPolicy?.capabilities ?? []),
+  ]);
+  const label = agent.label ?? managedAgent?.label ?? spawnPolicy?.label;
+  const provider = typeof agent.meta?.provider === "string" ? agent.meta.provider : managedAgent?.provider ?? spawnPolicy?.provider;
+  if (selector.provider) {
+    if (provider !== selector.provider && !tags.has(selector.provider)) return false;
+  }
+  if (selector.label && label !== selector.label) return false;
+  if (selector.tags?.length && !selector.tags.every((tag) => tags.has(tag))) return false;
+  if (selector.capabilities?.length && !selector.capabilities.every((cap) => capabilities.has(cap))) return false;
+  return true;
+}
+
+function stringArray(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string" && item.length > 0) : [];
+}
+
+function automationRunLabel(automationId: string, runId: string): string {
+  return `automation-${automationId.slice(0, 8)}-${runId.slice(0, 8)}`;
+}

package/src/automations/index.ts

@@ -0,0 +1,5 @@
+export type { AutomationDispatchResult, AutomationReconcileResult } from "./types";
+export { createAutomation, deleteAutomation, updateAutomation } from "./crud";
+export { getAutomation, listAutomationRuns, listAutomations } from "./storage";
+export { runAutomationNow, runDueAutomations } from "./dispatch";
+export { reconcileAutomationRuns } from "./reconcile";

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