agent-accelerator 0.4.0 → 0.5.0

package/src/scheduler/store.ts

@@ -0,0 +1,263 @@
+/**
+ * Disk layer for scheduled actions. Everything lives under one home folder:
+ *
+ *   <home>/scheduled_actions/tasks.json         every action, one file
+ *   <home>/scheduled_actions/deliveries.json    saved results waiting for their delivery time
+ *   <home>/scheduled_actions/<id>/<date>.md     one file per run
+ *
+ * The files are the source of truth: every write re-reads first (never writes
+ * from a stale copy) and goes through `writeFileAtomic` (temp file + rename).
+ * Sync `fs`, like the session store.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { z } from "zod";
+import { writeFileAtomic } from "../session/store.ts";
+import { telemetryBus } from "../telemetry.ts";
+import { resolveHome } from "../utils/home.ts";
+export { resolveHome };
+import { ValidationError } from "../types/errors.ts";
+import type { ScheduledActionRecord, ScheduledRunStatus } from "../types/scheduler.ts";
+import { durationMs, runFileName } from "./time.ts";
+
+/** Lowercase kebab-case. */
+export const TASK_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** 48-char slug + `-` + 6 random chars. */
+export const MAX_TASK_ID_LENGTH = 55;
+
+/** A saved run waiting for its delivery time (one entry of `deliveries.json`). */
+export interface PendingDelivery {
+  id: string;
+  /** Run file path, relative to `scheduled_actions/`. */
+  file: string;
+  status: ScheduledRunStatus;
+  readyAt: string;
+  deliverAt: string;
+}
+
+/** Header written at the top of every run file. */
+export interface RunHeader {
+  id: string;
+  name: string;
+  status: ScheduledRunStatus;
+  startedAt: string;
+  finishedAt: string;
+  deliverAt: string;
+  /** The run finished after its delivery time. */
+  late: boolean;
+  model?: string;
+  tokens?: number;
+  /** `unknown` when the model has no known pricing (never a made-up 0). */
+  costUsd?: number | "unknown";
+  error?: string;
+}
+
+const baseDir = (home: string): string => path.join(home, "scheduled_actions");
+const tasksFile = (home: string): string => path.join(baseDir(home), "tasks.json");
+const deliveriesFile = (home: string): string => path.join(baseDir(home), "deliveries.json");
+
+/** Absolute path of a run file given its `scheduled_actions/`-relative path. */
+export function runPath(home: string, relativeFile: string): string {
+  return path.resolve(baseDir(home), relativeFile);
+}
+
+/** Renames the pre-0.5.0 `scheduled_tasks/` folder to `scheduled_actions/` (once, only when the new one does not exist). */
+export function migrateLegacyFolder(home: string): void {
+  const legacy = path.join(home, "scheduled_tasks");
+  try {
+    if (fs.existsSync(legacy) && !fs.existsSync(baseDir(home))) fs.renameSync(legacy, baseDir(home));
+  } catch {
+    // why: best effort; the old folder simply stays where it is.
+  }
+}
+
+type Raw = Record<string, unknown>;
+
+/** Reads a `{ version, <key>: [...] }` file. Missing = empty; corrupt = quarantined (`*.corrupt-<ts>`) + empty. */
+function readList(file: string, key: "tasks" | "pending"): Raw[] {
+  let text: string;
+  try {
+    text = fs.readFileSync(file, "utf8");
+  } catch {
+    return [];
+  }
+  try {
+    const list = (JSON.parse(text) as Raw | null)?.[key];
+    if (!Array.isArray(list)) throw new Error(`"${key}" is not an array`);
+    return list.filter((x): x is Raw => !!x && typeof x === "object" && !Array.isArray(x));
+  } catch {
+    const moved = `${file}.corrupt-${Date.now()}`;
+    try {
+      fs.renameSync(file, moved);
+    } catch {
+      // why: quarantine is best-effort; the file is ignored either way.
+    }
+    telemetryBus.emitWarning(
+      "scheduled_action.store_corrupt",
+      `[Agent Accelerator] ${path.basename(file)} is not valid; moved to ${path.basename(moved)} and starting empty.`,
+      { file: moved }
+    );
+    return [];
+  }
+}
+
+function writeList(file: string, key: "tasks" | "pending", list: Raw[]): void {
+  writeFileAtomic(file, JSON.stringify({ version: 1, [key]: list }, null, 2) + "\n");
+}
+
+/** Every record as stored. Records may be invalid: check with {@link validateRecord} before acting on one. */
+export function readTasks(home: string): ScheduledActionRecord[] {
+  return readList(tasksFile(home), "tasks") as unknown as ScheduledActionRecord[];
+}
+
+/** Re-reads `tasks.json`, applies `fn` (mutating the array/records in place) and writes it back. */
+export function updateTasks<T>(home: string, fn: (tasks: ScheduledActionRecord[]) => T): T {
+  const tasks = readTasks(home);
+  const result = fn(tasks);
+  writeList(tasksFile(home), "tasks", tasks as unknown as Raw[]);
+  return result;
+}
+
+export function readDeliveries(home: string): PendingDelivery[] {
+  return readList(deliveriesFile(home), "pending") as unknown as PendingDelivery[];
+}
+
+/** Re-reads `deliveries.json`, applies `fn` (mutating in place) and writes it back. */
+export function updateDeliveries<T>(home: string, fn: (pending: PendingDelivery[]) => T): T {
+  const pending = readDeliveries(home);
+  const result = fn(pending);
+  writeList(deliveriesFile(home), "pending", pending as unknown as Raw[]);
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Record validation (the file is hand/agent-editable, so it is untrusted)
+// ---------------------------------------------------------------------------
+
+const iso = z.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$/);
+const recordSchema = z
+  .object({
+    id: z.string().max(MAX_TASK_ID_LENGTH).regex(TASK_ID_PATTERN),
+    name: z.string().min(1),
+    agent: z.string().min(1),
+    instructions: z.string().min(1),
+    task: z.string().min(1),
+    tools: z.array(z.string()),
+    timeoutMs: z.number().optional(),
+    schedule: z.object({
+      timeToDeliver: z.string(),
+      meridiem: z.enum(["AM", "PM"]),
+      startCookingInAdvance: z.string(),
+      repeatEvery: z.string().optional(),
+      retries: z.number().int().min(0).optional(),
+    }),
+    state: z.enum(["waiting", "cooking", "missed", "done"]),
+    nextCookAt: iso.nullable(),
+    nextDeliverAt: iso.nullable(),
+    current: z.object({ cookStartedAt: iso, deliverAt: iso }).optional(),
+  })
+  .refine((r) => r.state !== "cooking" || r.current !== undefined, { message: "current: required while cooking" });
+
+/** `undefined` when the record is usable, else a one-line reason. Never throws. */
+export function validateRecord(raw: unknown): string | undefined {
+  const parsed = recordSchema.safeParse(raw);
+  if (!parsed.success) {
+    return parsed.error.issues.map((i) => `${i.path.join(".") || "record"}: ${i.message}`).join("; ");
+  }
+  const { startCookingInAdvance, repeatEvery } = parsed.data.schedule;
+  try {
+    durationMs(startCookingInAdvance, "schedule.startCookingInAdvance");
+    if (repeatEvery !== undefined && durationMs(repeatEvery, "schedule.repeatEvery") === 0) {
+      return "schedule.repeatEvery: must be greater than 00:00:00";
+    }
+  } catch (err) {
+    return err instanceof Error ? err.message : String(err);
+  }
+  return undefined;
+}
+
+const deliverySchema = z.object({
+  id: z.string().min(1),
+  file: z.string().min(1),
+  status: z.enum(["ok", "failed"]),
+  readyAt: iso,
+  deliverAt: iso,
+});
+
+/** `undefined` when a `deliveries.json` entry is usable, else a one-line reason. Never throws. */
+export function validateDelivery(raw: unknown): string | undefined {
+  const parsed = deliverySchema.safeParse(raw);
+  return parsed.success ? undefined : parsed.error.issues.map((i) => `${i.path.join(".") || "entry"}: ${i.message}`).join("; ");
+}
+
+// ---------------------------------------------------------------------------
+// Run files
+// ---------------------------------------------------------------------------
+
+function renderRun(header: RunHeader, body: string): string {
+  const lines = ["---"];
+  for (const [key, value] of Object.entries(header)) {
+    if (value !== undefined) lines.push(`${key}: ${String(value).replace(/\s+/g, " ")}`);
+  }
+  lines.push("---", "", body);
+  return lines.join("\n") + "\n";
+}
+
+/**
+ * Writes one run under its final name (`27-october-2026.md`, `-2`, `-3` on a
+ * same-day clash) and returns its path relative to `scheduled_actions/`.
+ */
+export function writeRunFile(home: string, id: string, deliverAt: Date, header: RunHeader, body: string): string {
+  const dir = path.join(baseDir(home), id);
+  const base = runFileName(deliverAt);
+  let name = `${base}.md`;
+  for (let n = 2; fs.existsSync(path.join(dir, name)); n++) name = `${base}-${n}.md`;
+  writeFileAtomic(path.join(dir, name), renderRun(header, body));
+  return `${id}/${name}`;
+}
+
+/** Reads a run file (header fields as strings + result text). `undefined` when missing or outside the folder. */
+export function readRun(home: string, relativeFile: string): { header: Record<string, string>; body: string } | undefined {
+  const file = runPath(home, relativeFile);
+  if (!file.startsWith(baseDir(home) + path.sep)) return undefined;
+  let text: string;
+  try {
+    text = fs.readFileSync(file, "utf8");
+  } catch {
+    return undefined;
+  }
+  const m = /^---\n([\s\S]*?)\n---\n\n?([\s\S]*)$/.exec(text);
+  if (!m) return undefined;
+  const header: Record<string, string> = {};
+  for (const line of m[1]!.split("\n")) {
+    const i = line.indexOf(": ");
+    if (i > 0) header[line.slice(0, i)] = line.slice(i + 2);
+  }
+  return { header, body: m[2]!.replace(/\n$/, "") };
+}
+
+/** The run file a crashed cook already wrote (matched by its `startedAt`), if any. */
+export function findRunFile(home: string, id: string, deliverAt: Date, startedAt: string): string | undefined {
+  const base = runFileName(deliverAt);
+  let names: string[];
+  try {
+    names = fs.readdirSync(path.join(baseDir(home), id));
+  } catch {
+    return undefined;
+  }
+  for (const name of names) {
+    if (!name.startsWith(base) || !name.endsWith(".md")) continue;
+    if (readRun(home, `${id}/${name}`)?.header["startedAt"] === startedAt) return `${id}/${name}`;
+  }
+  return undefined;
+}
+
+/** Deletes an action's folder (`purge`). Only ever inside `scheduled_actions/`. */
+export function removeTaskFolder(home: string, id: string): void {
+  const root = baseDir(home);
+  const dir = path.resolve(root, id);
+  if (!TASK_ID_PATTERN.test(id) || id.length > MAX_TASK_ID_LENGTH || !dir.startsWith(root + path.sep)) {
+    throw new ValidationError(`Refusing to remove ${JSON.stringify(id)}: not a scheduled action id.`);
+  }
+  fs.rmSync(dir, { recursive: true, force: true });
+}

package/src/scheduler/time.ts

@@ -0,0 +1,148 @@
+/**
+ * Pure time maths for scheduled actions. Every function takes `now` (or a
+ * date) explicitly and uses only the machine's own local clock: no timezone,
+ * no DST logic, no `Intl`. `DD:HH:MM` strings are relative (days, hours,
+ * minutes) and are resolved to local `YYYY-MM-DDTHH:mm:ss` strings for storage.
+ */
+import { ValidationError } from "../types/errors.ts";
+
+const MONTHS = [
+  "january", "february", "march", "april", "may", "june",
+  "july", "august", "september", "october", "november", "december",
+];
+const DAYS = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+
+const DDHHMM = /^(\d{2,}):(\d{2}):(\d{2})$/;
+const LOCAL_ISO = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})$/;
+
+const pad2 = (n: number): string => String(n).padStart(2, "0");
+const show = (v: unknown): string => JSON.stringify(v) ?? String(v);
+
+/** Parses `DD:HH:MM` (DD >= 2 digits, MM < 60). HH is range-checked by the caller. */
+export function parseDDHHMM(value: unknown, field: string, example = "00:07:00"): { dd: number; hh: number; mm: number } {
+  const m = typeof value === "string" ? DDHHMM.exec(value) : null;
+  if (!m || Number(m[3]) > 59) {
+    throw new ValidationError(
+      `${field}: expected "DD:HH:MM" (DD days with at least two digits, MM 00-59), e.g. "${example}"; got ${show(value)}.`
+    );
+  }
+  return { dd: Number(m[1]), hh: Number(m[2]), mm: Number(m[3]) };
+}
+
+/** Elapsed ms of a `DD:HH:MM` duration (HH 00-23): `startCookingInAdvance`, `repeatEvery`. */
+export function durationMs(value: unknown, field: string): number {
+  const { dd, hh, mm } = parseDDHHMM(value, field, "00:00:10");
+  if (hh > 23) {
+    throw new ValidationError(
+      `${field}: as a duration HH must be 00-23 (e.g. "00:00:10" = 10 minutes, "01:00:00" = 1 day); got ${show(value)}.`
+    );
+  }
+  return ((dd * 24 + hh) * 60 + mm) * 60_000;
+}
+
+/** Local `Monday, 26 October, 03:55:31 PM, 2026` (no timezone name on purpose). */
+export function formatDatetime(d: Date): string {
+  const h12 = d.getHours() % 12 || 12;
+  const ampm = d.getHours() < 12 ? "AM" : "PM";
+  const month = MONTHS[d.getMonth()]!;
+  return (
+    `${DAYS[d.getDay()]}, ${d.getDate()} ${month[0]!.toUpperCase()}${month.slice(1)}, ` +
+    `${pad2(h12)}:${pad2(d.getMinutes())}:${pad2(d.getSeconds())} ${ampm}, ${d.getFullYear()}`
+  );
+}
+
+/**
+ * Resolves `timeToDeliver` (`DD` days from today, `HH:MM` on a 12-hour clock)
+ * to a local date. Throws when the result is not in the future.
+ */
+export function resolveDelivery(now: Date, timeToDeliver: unknown, meridiem: unknown): Date {
+  // Report a bad time AND a bad meridiem together so one retry can fix both.
+  const issues: string[] = [];
+  let parts: { dd: number; hh: number; mm: number } | undefined;
+  try {
+    parts = parseDDHHMM(timeToDeliver, "scheduled_action.timeToDeliver");
+    if (parts.hh < 1 || parts.hh > 12) {
+      throw new ValidationError(
+        `scheduled_action.timeToDeliver: HH is a 12-hour clock hour 01-12 (the AM/PM goes in meridiem), e.g. "00:07:00" + "AM" = today 7:00 AM; got ${show(timeToDeliver)}.`
+      );
+    }
+  } catch (err) {
+    issues.push(err instanceof Error ? err.message : String(err));
+  }
+  if (meridiem !== "AM" && meridiem !== "PM") {
+    issues.push(`scheduled_action.meridiem: must be "AM" or "PM"; got ${show(meridiem)}.`);
+  }
+  if (!parts || issues.length > 0) throw new ValidationError(issues.join(" "));
+  const { dd, hh, mm } = parts;
+  const d = new Date(now);
+  d.setDate(d.getDate() + dd);
+  d.setHours((hh % 12) + (meridiem === "PM" ? 12 : 0), mm, 0, 0);
+  if (Number.isNaN(d.getTime())) {
+    throw new ValidationError(`scheduled_action.timeToDeliver: ${show(timeToDeliver)} is too far in the future.`);
+  }
+  if (d.getTime() <= now.getTime()) {
+    throw new ValidationError(
+      `scheduled_action.timeToDeliver: ${show(timeToDeliver)} ${meridiem} resolves to ${formatDatetime(d)}, which is already in the past ` +
+        `(now: ${formatDatetime(now)}). Use DD "01" for tomorrow, e.g. "01:${pad2(hh)}:${pad2(mm)}".`
+    );
+  }
+  return d;
+}
+
+/** Next delivery after `deliverAt`. Calendar maths (days, then hours/minutes): 7:00 AM stays 7:00 AM. */
+export function nextOccurrence(deliverAt: Date, repeatEvery: string): Date {
+  const { dd, hh, mm } = parseDDHHMM(repeatEvery, "scheduled_action.repeatEvery", "01:00:00");
+  const d = new Date(deliverAt);
+  d.setDate(d.getDate() + dd);
+  d.setHours(d.getHours() + hh, d.getMinutes() + mm);
+  return d;
+}
+
+/** First occurrence in the series (starting at `from`) that is strictly after `now`. */
+export function nextAfter(from: Date, repeatEvery: string, now: Date): Date {
+  let d = from;
+  while (d.getTime() <= now.getTime()) {
+    const next = nextOccurrence(d, repeatEvery);
+    if (next.getTime() <= d.getTime()) {
+      throw new ValidationError("scheduled_action.repeatEvery: must be greater than 00:00:00.");
+    }
+    d = next;
+  }
+  return d;
+}
+
+/** When a run must start so it can deliver at `deliverAt`. */
+export function cookTime(deliverAt: Date, cookMs: number): Date {
+  return new Date(deliverAt.getTime() - cookMs);
+}
+
+/** A run still cooking when the next is due is skipped, so the lead time must be shorter than the gap. */
+export function assertCookShorterThanRepeat(cookMs: number, repeatMs: number): void {
+  if (cookMs >= repeatMs) {
+    throw new ValidationError(
+      "scheduled_action.startCookingInAdvance: must be shorter than repeatEvery. A run still cooking when the next one is due is skipped, " +
+        "so a lead time as long as the gap loses runs. Shorten startCookingInAdvance, widen repeatEvery, or give the worker a lighter task."
+    );
+  }
+}
+
+/** Local `YYYY-MM-DDTHH:mm:ss`, the storage format (no offset). */
+export function toLocalIso(d: Date): string {
+  return (
+    `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}` +
+    `T${pad2(d.getHours())}:${pad2(d.getMinutes())}:${pad2(d.getSeconds())}`
+  );
+}
+
+/** Inverse of {@link toLocalIso}; read as local time. */
+export function parseLocalIso(value: string): Date {
+  const m = LOCAL_ISO.exec(value);
+  if (!m) throw new ValidationError(`Expected a local time like "2026-10-27T07:00:00"; got ${show(value)}.`);
+  const [y, mo, d, h, mi, s] = m.slice(1).map(Number) as [number, number, number, number, number, number];
+  return new Date(y, mo - 1, d, h, mi, s);
+}
+
+/** Run file base name for a delivery date, e.g. `27-october-2026`. */
+export function runFileName(deliverAt: Date): string {
+  return `${pad2(deliverAt.getDate())}-${MONTHS[deliverAt.getMonth()]}-${deliverAt.getFullYear()}`;
+}

package/src/scheduler/tool.ts

@@ -0,0 +1,151 @@
+/**
+ * The two model-facing tools of scheduled actions: `scheduled_actions` (one
+ * flat tool with a `command` field, a thin wrapper over the developer
+ * functions) and `get_datetime`. The tool manual lives in
+ * `scheduled-actions.md`, not in code.
+ */
+import { readFileSync } from "node:fs";
+import { z } from "zod";
+import type { Agent } from "../agent/agent.ts";
+import { tool } from "../tools/tool.ts";
+import { ToolError } from "../types/errors.ts";
+import type { ToolDefinition } from "../types/tool.ts";
+import type { ScheduledActionInput, ScheduledActionPatch } from "../types/scheduler.ts";
+import {
+  createScheduledAction,
+  getScheduler,
+  killScheduledAction,
+  listScheduledActions,
+  runScheduledAction,
+  skipScheduledAction,
+  updateScheduledAction,
+  validateInput,
+} from "./scheduler.ts";
+import { readRun } from "./store.ts";
+import { formatDatetime } from "./time.ts";
+
+const COMMANDS = ["create", "list", "get", "update", "kill", "run_now", "skip"] as const;
+
+let manual: string | undefined;
+/** Read on first use (not at import), so a program that never enables scheduling never touches the file. */
+function loadManual(): string {
+  return (manual ??= readFileSync(new URL("./scheduled-actions.md", import.meta.url), "utf8"));
+}
+
+/** Returns the machine's local date and time. Exported for any agent; auto-registered with the scheduling tools. */
+export const getDatetimeTool: ToolDefinition = tool({
+  name: "get_datetime",
+  description:
+    'Returns the machine\'s current local date and time, e.g. "Monday, 26 October, 03:55:31 PM, 2026" (no timezone). Call it before scheduling anything.',
+  input: z.object({}),
+  repeatable: true,
+  execute: () => formatDatetime(new Date()),
+});
+
+const scheduledActionSchema = z.object({
+  name: z.string().optional().describe("Human label."),
+  id: z.string().optional().describe("Lowercase kebab-case slug, max 48 chars (create only)."),
+  timeToDeliver: z.string().optional().describe('"DD:HH:MM" - DD days from today, HH:MM on a 12-hour clock.'),
+  meridiem: z.enum(["AM", "PM"]).optional(),
+  startCookingInAdvance: z.string().optional().describe('Duration "DD:HH:MM" before delivery when the run starts.'),
+  repeatEvery: z.string().optional().describe('Duration "DD:HH:MM" between deliveries. Omit to run once.'),
+  retries: z.number().optional().describe("Extra attempts if a run fails."),
+});
+
+const describedId = "Full action id including its 6-character suffix (get, update, kill, run_now, skip).";
+
+/** Builds the `scheduled_actions` tool for `agent`; its description is the manual with the worker pool filled in. */
+export function createScheduledActionsTool(agent: Agent): ToolDefinition {
+  const home = agent.home;
+  const poolTools = agent.dynamicSubagents?.tools ?? {};
+  const poolNames = Object.keys(poolTools);
+  const example = (): string =>
+    JSON.stringify({
+      command: "create",
+      instructions: "You write a short, sourced AI research brief.",
+      task: "Summarize the most important AI news of the last day in 5 bullets.",
+      ...(poolNames[0] ? { tools: [poolNames[0]] } : {}),
+      scheduled_action: {
+        name: "Daily AI Research Brief",
+        id: "daily-ai-brief",
+        timeToDeliver: "01:07:00",
+        meridiem: "AM",
+        startCookingInAdvance: "00:00:30",
+        repeatEvery: "01:00:00",
+      },
+    });
+
+  return tool({
+    name: "scheduled_actions",
+    description: loadManual().replace("{{TOOLS}}", poolNames.length > 0 ? poolNames.join(", ") : "none (omit tools)"),
+    input: z.object({
+      command: z.enum(COMMANDS),
+      id: z.string().optional().describe(describedId),
+      role: z.string().optional().describe("Short persona for the worker."),
+      instructions: z.string().optional().describe("The worker's system prompt (create, update)."),
+      task: z.string().optional().describe("The concrete assignment for every run (create, update)."),
+      tools: z.array(z.string()).optional().describe(`Worker tools to grant, from: ${poolNames.join(", ") || "none"}.`),
+      timeoutMs: z.number().optional().describe("Per-run time limit in ms (> 0)."),
+      scheduled_action: scheduledActionSchema.optional(),
+      force: z.boolean().optional().describe("kill: abort a run that is cooking. Ask the user first."),
+      purge: z.boolean().optional().describe("kill: also delete past run files."),
+    }),
+    execute: async (a) => {
+      const sa = a.scheduled_action ?? {};
+      const needId = (): string => {
+        const id = a.id ?? sa.id;
+        if (!id) {
+          throw new ToolError(`${a.command} needs "id" (the full id including its 6-character suffix; see list). Example: ${JSON.stringify({ command: a.command, id: "daily-ai-brief-d64aj2" })}`);
+        }
+        return id;
+      };
+
+      switch (a.command) {
+        case "create": {
+          const input = { role: a.role, instructions: a.instructions, task: a.task, tools: a.tools, timeoutMs: a.timeoutMs, scheduled_action: sa } as ScheduledActionInput;
+          const problems = validateInput(input, poolTools, getScheduler(home).now(), { requireLead: true });
+          if (problems.length > 0) {
+            throw new ToolError(
+              `create has ${problems.length} problem${problems.length === 1 ? "" : "s"}: ${problems.map((p, i) => `(${i + 1}) ${p}`).join(" ")} Valid example: ${example()}`
+            );
+          }
+          return createScheduledAction(agent, input);
+        }
+        case "list":
+          return listScheduledActions({ home });
+        case "get": {
+          const id = needId();
+          const rec = listScheduledActions({ home }).find((t) => t.id === id);
+          if (!rec) throw new ToolError(`No scheduled action with id "${id}". Use list to see the ids.`);
+          const run = rec.lastRun ? readRun(home, rec.lastRun.file) : undefined;
+          return { ...rec, ...(run ? { latestResult: run.body } : {}) };
+        }
+        case "update": {
+          const id = needId();
+          const { id: _ignored, ...schedule } = sa;
+          const patch: ScheduledActionPatch = {
+            role: a.role,
+            instructions: a.instructions,
+            task: a.task,
+            tools: a.tools,
+            timeoutMs: a.timeoutMs,
+            scheduled_action: schedule,
+          };
+          const changes = [a.role, a.instructions, a.task, a.tools, a.timeoutMs, ...Object.values(schedule)];
+          if (changes.every((v) => v === undefined)) {
+            throw new ToolError(`update needs at least one field to change. Example: ${JSON.stringify({ command: "update", id, task: "The new assignment." })}`);
+          }
+          return updateScheduledAction(id, patch, { home });
+        }
+        case "kill":
+          return killScheduledAction(needId(), { home, force: a.force, purge: a.purge });
+        case "run_now":
+          return runScheduledAction(needId(), { home });
+        case "skip":
+          return skipScheduledAction(needId(), { home });
+        default:
+          throw new ToolError(`Unknown command ${JSON.stringify((a as { command?: unknown }).command)}. Use one of: ${COMMANDS.join(", ")}.`);
+      }
+    },
+  });
+}