privateer-agent 0.1.1 → 0.3.0

package/src/routines/delivery.ts

@@ -0,0 +1,184 @@
+import type { Routine } from "./schema.ts";
+import { webhookName } from "./schema.ts";
+import { writeRoutineOutput, addNotice } from "./store.ts";
+
+// A relay pusher, injected by the daemon. Given the finished result it either
+// forwards it to an attached controller immediately ("live") or persists it to the
+// pending-relay queue to flush when the app next attaches ("queued"). Either way the
+// result is durably accounted for, so delivery doesn't add a notice backstop for it.
+export type RelayPusher = (routine: Routine, content: string) => "live" | "queued";
+
+// A cloud-outbox pusher, injected by the daemon. Seals the result to the account's
+// outbox public key and POSTs the ciphertext to the server (E2EE store-and-forward),
+// or buffers it durably on failure. Returns "sent" when the server accepted it,
+// "queued" when it was persisted for a later flush — either way the result is
+// durably accounted for. `status` is carried so the sealed envelope can render
+// ok/error without re-parsing the markdown body.
+export type CloudPusher = (routine: Routine, content: string, status: "ok" | "error") => Promise<"sent" | "queued">;
+
+// A named webhook endpoint from config `webhooks`.
+export interface WebhookTarget {
+  url: string;
+  format?: "slack" | "discord" | "json";
+}
+
+export interface DeliveryContext {
+  pushRelay?: RelayPusher;
+  // Seals + posts the result to the account's cloud outbox, or buffers it. Absent
+  // (e.g. not signed in) → the `cloud` channel falls back to a notice so the result
+  // isn't silently lost.
+  pushCloud?: CloudPusher;
+  // Named endpoints for "webhook:<name>" delivery entries; results POST here.
+  webhooks?: Record<string, WebhookTarget>;
+  // Scrubs secrets from anything leaving the machine. Webhook bodies always pass
+  // through this when provided (the daemon wires in redactText).
+  redact?: (text: string) => string;
+  // Injectable for tests; defaults to global fetch.
+  fetchImpl?: typeof fetch;
+}
+
+export interface DeliveryReport {
+  // Channels that actually delivered (email is handled inside the agent run, so it
+  // never appears here — see the daemon). Failed webhooks show as
+  // "webhook:<name>(failed)" and leave a notice so the result isn't silently lost.
+  delivered: string[];
+  // Absolute path to latest.md when file delivery ran.
+  filePath?: string;
+}
+
+function previewOf(content: string): string {
+  return content.replace(/\s+/g, " ").trim().slice(0, 120) || "(no output)";
+}
+
+// Message-size caps per format (Discord rejects >2000 chars of content; Slack
+// truncates around 40k; plain JSON consumers get a generous bound).
+const FORMAT_CAPS = { slack: 39_000, discord: 1_900, json: 100_000 } as const;
+
+function truncate(text: string, cap: number): string {
+  return text.length <= cap ? text : text.slice(0, cap - 12) + "\n…truncated";
+}
+
+// Wrap the result for the target service. All formats carry plain text — no
+// service-specific rich blocks, so a generic receiver can consume `json` too.
+export function webhookBody(
+  target: WebhookTarget,
+  routine: Pick<Routine, "name">,
+  content: string,
+  status: "ok" | "error",
+): string {
+  const format = target.format ?? "json";
+  const text = truncate(content, FORMAT_CAPS[format]);
+  switch (format) {
+    case "slack":
+      return JSON.stringify({ text: `*${routine.name}* (${status})\n${text}` });
+    case "discord":
+      return JSON.stringify({ content: `**${routine.name}** (${status})\n${text}` });
+    case "json":
+      return JSON.stringify({ routine: routine.name, status, at: new Date().toISOString(), content: text });
+  }
+}
+
+async function postWebhook(
+  target: WebhookTarget,
+  routine: Routine,
+  content: string,
+  status: "ok" | "error",
+  fetchImpl: typeof fetch,
+): Promise<void> {
+  const res = await fetchImpl(target.url, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: webhookBody(target, routine, content, status),
+    signal: AbortSignal.timeout(15_000),
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+}
+
+// Deliver a routine's result to its configured channels. `file` and `notice` are
+// deterministic and on-box. `relay` pushes to an attached controller in real time
+// (best-effort — the socket may be up with no controller attached), so we ALSO keep
+// a durable record when the routine has no other on-box channel, guaranteeing the
+// result is never silently lost. `webhook:<name>` POSTs the (redacted) result to a
+// named endpoint from config; a failed or unconfigured webhook leaves a notice.
+// `email` is intentionally not handled here: it is fulfilled inside the agent turn
+// (the daemon adds the Gmail tool + an instruction to the prompt) so plaintext
+// egress stays an explicit, gated action.
+export async function deliver(
+  routine: Routine,
+  content: string,
+  status: "ok" | "error",
+  ctx: DeliveryContext = {},
+): Promise<DeliveryReport> {
+  const delivered: string[] = [];
+  const wants = new Set(routine.delivery);
+  let filePath: string | undefined;
+  let noticed = false;
+
+  const leaveNotice = () => {
+    if (noticed) return;
+    addNotice({ routine: routine.name, at: new Date().toISOString(), status, preview: previewOf(content), path: filePath });
+    noticed = true;
+  };
+
+  // On-box copy.
+  if (wants.has("file")) {
+    filePath = writeRoutineOutput(routine.name, content);
+    delivered.push("file");
+  }
+
+  // Relay: pushed live to an attached controller, or queued to flush when the app
+  // next attaches (the daemon persists that queue, so it's durable either way). Only
+  // when no pusher is wired at all do we fall back to a notice so it isn't lost.
+  if (wants.has("relay")) {
+    const pushed = ctx.pushRelay?.(routine, content);
+    if (pushed === "live") delivered.push("relay");
+    else if (pushed === "queued") delivered.push("relay(queued)");
+    else if (!wants.has("file") && !wants.has("notice")) {
+      leaveNotice();
+      delivered.push("notice(backstop)");
+    }
+  }
+
+  // Cloud outbox: sealed E2EE store-and-forward. "sent" reached the server; "queued"
+  // was buffered on disk (offline / server down / app hasn't published its outbox key
+  // yet) and flushes later — both are durable. Only when no pusher is wired at all,
+  // and nothing else keeps a durable record, do we fall back to a notice.
+  if (wants.has("cloud")) {
+    const sent = ctx.pushCloud ? await ctx.pushCloud(routine, content, status) : undefined;
+    if (sent === "sent") delivered.push("cloud");
+    else if (sent === "queued") delivered.push("cloud(queued)");
+    else if (!wants.has("file") && !wants.has("notice") && !wants.has("relay")) {
+      leaveNotice();
+      delivered.push("notice(backstop)");
+    }
+  }
+
+  // Webhooks: plaintext leaves the machine, so the body is always redacted when a
+  // scrubber is wired. Any failure (unconfigured name, HTTP error, timeout) leaves
+  // a notice so the user learns the result existed and the push didn't happen.
+  for (const entry of routine.delivery) {
+    const name = webhookName(entry);
+    if (!name) continue;
+    const target = ctx.webhooks?.[name];
+    if (!target) {
+      leaveNotice();
+      delivered.push(`${entry}(unconfigured)`);
+      continue;
+    }
+    try {
+      const body = ctx.redact ? ctx.redact(content) : content;
+      await postWebhook(target, routine, body, status, ctx.fetchImpl ?? fetch);
+      delivered.push(entry);
+    } catch {
+      leaveNotice();
+      delivered.push(`${entry}(failed)`);
+    }
+  }
+
+  if (wants.has("notice")) {
+    leaveNotice();
+    delivered.push("notice");
+  }
+
+  return { delivered, filePath };
+}

package/src/routines/schema.ts

@@ -0,0 +1,84 @@
+import { z } from "zod";
+
+// Where a routine's result is delivered after it runs. `file`/`relay`/`notice` stay
+// inside the user's trust boundary. `cloud` stores an END-TO-END-ENCRYPTED copy in
+// the account's server outbox for the app to catch up on when it next opens (the
+// server only ever sees ciphertext — it can't read results — but does learn that a
+// result exists, plus its time and rough size). `email` and `webhook:<name>` cross
+// the boundary in plaintext to a third-party service, so they are opt-in and labeled
+// at approval time.
+export const DELIVERY_CHANNELS = ["file", "relay", "notice", "cloud", "email"] as const;
+export type DeliveryChannel = (typeof DELIVERY_CHANNELS)[number];
+
+// A webhook entry references a named endpoint from config `webhooks` — the routine
+// itself never carries a URL, so all egress targets stay in one reviewable place.
+const WEBHOOK_ENTRY_RE = /^webhook:[a-zA-Z0-9._-]{1,64}$/;
+
+export const DeliveryEntry = z.union([
+  z.enum(DELIVERY_CHANNELS),
+  z.string().regex(WEBHOOK_ENTRY_RE, "webhook entries look like 'webhook:<config-name>'"),
+]);
+export type DeliveryEntry = z.infer<typeof DeliveryEntry>;
+
+// The webhook name of a delivery entry, or null for the builtin channels.
+export function webhookName(entry: string): string | null {
+  return entry.startsWith("webhook:") ? entry.slice("webhook:".length) : null;
+}
+
+// A saved, unattended agent task. Persisted in routines.json and executed by the
+// daemon when its trigger comes due. A routine's trigger is EITHER recurring (a
+// cron expression) or one-off (`at`, a specific datetime) — exactly one is set.
+export const Routine = z
+  .object({
+    // Stable id ("r-" + mint time), used as the key for updates/removal.
+    id: z.string(),
+    // Human label, unique across routines; used by /routine and as the output dir.
+    name: z.string(),
+    // Recurring trigger: a standard 5-field cron expression, e.g. "0 8 * * *".
+    cron: z.string().optional(),
+    // One-off trigger: an ISO-8601 datetime, e.g. "2026-07-02T15:00:00". Fires once,
+    // then the routine disables itself.
+    at: z.string().optional(),
+    // The instruction handed to the agent each time the routine fires.
+    prompt: z.string(),
+    // Working directory the run executes in (file tools are confined here).
+    cwd: z.string(),
+    // Optional "provider:model" override; falls back to config.defaultModel.
+    model: z.string().optional(),
+    // Where to deliver the result. Defaults to on-box file output.
+    delivery: z.array(DeliveryEntry).default(["file"]),
+    // Optional tool allow-subset. Unset → the safe read/web set (see daemon). Entries
+    // may be builtin names ("read") or MCP selectors — "<server>__<tool>" exact or
+    // "<server>__*" for a whole server (see routines/toolSelect.ts). Selected MCP
+    // tools run unattended under the auto-approve gate, so grant the minimum needed.
+    tools: z.array(z.string()).optional(),
+    // Paused routines stay in the file but never fire.
+    enabled: z.boolean().default(true),
+    // Bookkeeping, updated by the daemon after each run.
+    lastRun: z.string().optional(),
+    lastStatus: z.enum(["ok", "error"]).optional(),
+    lastError: z.string().optional(),
+    nextRun: z.string().optional(),
+  })
+  // Exactly one trigger: recurring (cron) or one-off (at).
+  .refine((r) => Boolean(r.cron) !== Boolean(r.at), {
+    message: "set exactly one of `cron` (recurring) or `at` (one-off)",
+    path: ["cron"],
+  });
+export type Routine = z.infer<typeof Routine>;
+
+// True when the routine repeats (cron) rather than firing once (at).
+export function isRecurring(r: Pick<Routine, "cron" | "at">): boolean {
+  return Boolean(r.cron);
+}
+
+// The on-disk shape of routines.json.
+export const RoutineFile = z.object({
+  routines: z.array(Routine).default([]),
+});
+export type RoutineFile = z.infer<typeof RoutineFile>;
+
+// A time-ordered routine id minted once at creation.
+export function newRoutineId(): string {
+  return `r-${Date.now()}`;
+}

package/src/routines/store.ts

@@ -0,0 +1,248 @@
+import { mkdirSync, writeFileSync, readFileSync, existsSync, chmodSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { globalDir } from "../config/paths.ts";
+import { Routine, RoutineFile } from "./schema.ts";
+
+// routines.json lives alongside config.json in the global dir. It can carry the
+// prompt text and (for email delivery) recipient hints, so it is written owner-only
+// (0600) inside the owner-only global dir, mirroring saveGlobalConfig.
+export function routinesFilePath(): string {
+  return join(globalDir(), "routines.json");
+}
+
+// Per-routine output directory (dated result files + latest.md).
+export function routineOutputDir(name: string): string {
+  return join(globalDir(), "routines", slug(name));
+}
+
+function slug(name: string): string {
+  return name.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "routine";
+}
+
+// A stable relay terminal id for the daemon, persisted so it reappears as the same
+// "Privateer Routines" terminal in the app across restarts (rather than a fresh
+// random terminal each boot). Random on first use so it stays unique per install —
+// the relay routes on this id with no user namespacing, so a shared constant could
+// collide across accounts. Matches the server's isValidTermId (`[A-Za-z0-9_-]{8,64}`).
+export function routineRelayId(): string {
+  const path = join(globalDir(), "routines", "relay-id");
+  if (existsSync(path)) {
+    const existing = readFileSync(path, "utf8").trim();
+    if (/^[A-Za-z0-9_-]{8,64}$/.test(existing)) return existing;
+  }
+  const id = `routines-${randomUUID().replace(/-/g, "")}`;
+  const dir = join(globalDir(), "routines");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(path, id + "\n", { encoding: "utf8", mode: 0o600 });
+  tryChmod(path, 0o600);
+  return id;
+}
+
+function tryChmod(path: string, mode: number): void {
+  try {
+    chmodSync(path, mode);
+  } catch {
+    /* non-POSIX filesystem or insufficient perms — nothing we can do */
+  }
+}
+
+export function loadRoutines(): Routine[] {
+  const path = routinesFilePath();
+  if (!existsSync(path)) return [];
+  try {
+    return RoutineFile.parse(JSON.parse(readFileSync(path, "utf8"))).routines;
+  } catch {
+    // A corrupt or hand-edited file shouldn't crash the daemon; treat as empty.
+    return [];
+  }
+}
+
+export function saveRoutines(routines: Routine[]): void {
+  const dir = globalDir();
+  mkdirSync(dir, { recursive: true });
+  tryChmod(dir, 0o700);
+  const payload: RoutineFile = { routines };
+  writeFileSync(routinesFilePath(), JSON.stringify(payload, null, 2) + "\n", {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+  tryChmod(routinesFilePath(), 0o600);
+}
+
+// Look up by id first, then by (case-insensitive) name for CLI convenience.
+export function findRoutine(routines: Routine[], idOrName: string): Routine | undefined {
+  const needle = idOrName.trim().toLowerCase();
+  return (
+    routines.find((r) => r.id === idOrName) ??
+    routines.find((r) => r.name.toLowerCase() === needle)
+  );
+}
+
+// Insert or replace a routine (matched by id), persisting the whole file.
+export function upsertRoutine(routine: Routine): Routine[] {
+  const routines = loadRoutines();
+  const i = routines.findIndex((r) => r.id === routine.id);
+  if (i >= 0) routines[i] = routine;
+  else routines.push(routine);
+  saveRoutines(routines);
+  return routines;
+}
+
+// Remove a routine by id or name. Returns the removed routine, or null if absent.
+export function removeRoutine(idOrName: string): Routine | null {
+  const routines = loadRoutines();
+  const target = findRoutine(routines, idOrName);
+  if (!target) return null;
+  saveRoutines(routines.filter((r) => r.id !== target.id));
+  return target;
+}
+
+// Write a run's result to the routine's output dir: a dated file plus latest.md.
+// Returns the absolute path of latest.md.
+export function writeRoutineOutput(name: string, content: string): string {
+  const dir = routineOutputDir(name);
+  mkdirSync(dir, { recursive: true });
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  writeFileSync(join(dir, `${stamp}.md`), content, "utf8");
+  const latest = join(dir, "latest.md");
+  writeFileSync(latest, content, "utf8");
+  return latest;
+}
+
+// A pending routine result queued for the next interactive session ("notice"
+// delivery). The TUI drains these on startup so results surface even when no
+// terminal was attached at fire time.
+export interface RoutineNotice {
+  routine: string;
+  at: string; // ISO timestamp
+  status: "ok" | "error";
+  preview: string; // short single-line summary
+  path?: string; // latest.md, when file delivery also ran
+}
+
+function noticesPath(): string {
+  return join(globalDir(), "routines", "notices.json");
+}
+
+export function loadNotices(): RoutineNotice[] {
+  const path = noticesPath();
+  if (!existsSync(path)) return [];
+  try {
+    const data = JSON.parse(readFileSync(path, "utf8"));
+    return Array.isArray(data) ? (data as RoutineNotice[]) : [];
+  } catch {
+    return [];
+  }
+}
+
+export function addNotice(notice: RoutineNotice): void {
+  const dir = join(globalDir(), "routines");
+  mkdirSync(dir, { recursive: true });
+  const notices = loadNotices();
+  notices.push(notice);
+  // Keep the queue bounded so an offline stretch can't grow it without limit.
+  const trimmed = notices.slice(-50);
+  writeFileSync(noticesPath(), JSON.stringify(trimmed, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+  tryChmod(noticesPath(), 0o600);
+}
+
+// Read and clear the notice queue (called by the TUI on startup).
+export function drainNotices(): RoutineNotice[] {
+  const notices = loadNotices();
+  if (notices.length === 0) return [];
+  try {
+    writeFileSync(noticesPath(), "[]\n", { encoding: "utf8", mode: 0o600 });
+  } catch {
+    /* best-effort clear */
+  }
+  return notices;
+}
+
+// A relay result produced while no controller was attached, held until the app
+// next connects. Persisted (not just in-memory) so it survives a daemon restart.
+export interface PendingRelay {
+  routine: string;
+  at: string; // ISO timestamp
+  content: string;
+}
+
+function pendingRelayPath(): string {
+  return join(globalDir(), "routines", "pending-relay.json");
+}
+
+export function loadPendingRelay(): PendingRelay[] {
+  const path = pendingRelayPath();
+  if (!existsSync(path)) return [];
+  try {
+    const data = JSON.parse(readFileSync(path, "utf8"));
+    return Array.isArray(data) ? (data as PendingRelay[]) : [];
+  } catch {
+    return [];
+  }
+}
+
+export function addPendingRelay(entry: PendingRelay): void {
+  const dir = join(globalDir(), "routines");
+  mkdirSync(dir, { recursive: true });
+  const queue = loadPendingRelay();
+  queue.push(entry);
+  const trimmed = queue.slice(-50); // bound the backlog
+  writeFileSync(pendingRelayPath(), JSON.stringify(trimmed, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+  tryChmod(pendingRelayPath(), 0o600);
+}
+
+// Read and clear the pending-relay queue (called when a controller attaches).
+export function drainPendingRelay(): PendingRelay[] {
+  const queue = loadPendingRelay();
+  if (queue.length === 0) return [];
+  try {
+    writeFileSync(pendingRelayPath(), "[]\n", { encoding: "utf8", mode: 0o600 });
+  } catch {
+    /* best-effort clear */
+  }
+  return queue;
+}
+
+// A `cloud`-delivery result that couldn't be sealed+posted to the account outbox
+// yet (offline, server down, or the app hasn't published its outbox key). Held on
+// disk until a later flush succeeds. Unlike PendingRelay this carries `status`, so
+// the sealed envelope the app opens can render ok/error without re-parsing markdown.
+export interface PendingCloud {
+  routine: string;
+  at: string; // ISO timestamp
+  status: "ok" | "error";
+  content: string;
+}
+
+function pendingCloudPath(): string {
+  return join(globalDir(), "routines", "pending-cloud.json");
+}
+
+export function loadPendingCloud(): PendingCloud[] {
+  const path = pendingCloudPath();
+  if (!existsSync(path)) return [];
+  try {
+    const data = JSON.parse(readFileSync(path, "utf8"));
+    return Array.isArray(data) ? (data as PendingCloud[]) : [];
+  } catch {
+    return [];
+  }
+}
+
+export function addPendingCloud(entry: PendingCloud): void {
+  const dir = join(globalDir(), "routines");
+  mkdirSync(dir, { recursive: true });
+  const queue = loadPendingCloud();
+  queue.push(entry);
+  savePendingCloud(queue.slice(-50)); // bound the backlog
+}
+
+// Overwrite the queue wholesale — used by the flush to drop the items it managed
+// to post while keeping the ones that still failed (and their order).
+export function savePendingCloud(entries: PendingCloud[]): void {
+  const dir = join(globalDir(), "routines");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(pendingCloudPath(), JSON.stringify(entries, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+  tryChmod(pendingCloudPath(), 0o600);
+}

package/src/routines/toolSelect.ts

@@ -0,0 +1,50 @@
+// A record of tool-name → tool definition. Was `ai`'s ToolSet in 0.2; MCP tool
+// wiring is a Phase-5 concern, so a structural type suffices for the filter below.
+type ToolSet = Record<string, unknown>;
+
+// A routine's `tools` field mixes builtin tool names with MCP selectors. MCP tools
+// are namespaced "<server>__<tool>" (see adaptMcpTools), and no builtin name contains
+// "__", so the separator is unambiguous: entries with "__" are MCP selectors — an
+// exact tool name or a per-server wildcard "<server>__*" — everything else is a
+// builtin allowlist entry.
+
+export interface RoutineToolSplit {
+  // Builtin tool names (read, glob, ...). Empty → caller falls back to the safe set.
+  builtin: string[];
+  // MCP selectors: "<server>__<tool>" exact, or "<server>__*" for a whole server.
+  mcp: string[];
+  // Unique server prefixes from `mcp`, i.e. which servers need connecting at all.
+  servers: string[];
+}
+
+export function splitRoutineTools(tools?: string[]): RoutineToolSplit {
+  const builtin: string[] = [];
+  const mcp: string[] = [];
+  const servers = new Set<string>();
+  for (const t of tools ?? []) {
+    const sep = t.indexOf("__");
+    if (sep > 0) {
+      mcp.push(t);
+      servers.add(t.slice(0, sep));
+    } else {
+      builtin.push(t);
+    }
+  }
+  return { builtin, mcp, servers: [...servers] };
+}
+
+// Does a namespaced MCP tool name match a selector? Exact match, or "<server>__*"
+// matching any tool on that server.
+export function matchesSelector(name: string, selector: string): boolean {
+  if (selector.endsWith("__*")) return name.startsWith(selector.slice(0, -1));
+  return name === selector;
+}
+
+// Narrow a connected MCP toolset to the selected tools. Least privilege matters here:
+// routine runs use the auto-approve gate, so anything left in this set fires without
+// a human in the loop.
+export function filterMcpTools(tools: ToolSet, selectors: string[]): ToolSet {
+  return Object.fromEntries(
+    Object.entries(tools).filter(([name]) => selectors.some((s) => matchesSelector(name, s))),
+  );
+}

package/src/routines/trigger.ts

@@ -0,0 +1,41 @@
+import { nextRun as cronNext, cronError } from "./cron.ts";
+import { isRecurring, type Routine } from "./schema.ts";
+
+// A routine's trigger: a recurring `cron` expression or a one-off `at` datetime.
+type Trigger = Pick<Routine, "cron" | "at">;
+
+// Validate the trigger, returning an error message or null. Enforces "exactly one"
+// and that the chosen form parses.
+export function triggerError(t: Trigger): string | null {
+  const hasCron = Boolean(t.cron);
+  const hasAt = Boolean(t.at);
+  if (hasCron === hasAt) return "set exactly one of `cron` (recurring) or `at` (one-off)";
+  if (hasCron) return cronError(t.cron!);
+  return Number.isNaN(Date.parse(t.at!)) ? `invalid datetime "${t.at}"` : null;
+}
+
+// The fire time to store as `nextRun`. For cron: the next match strictly after
+// `from`. For a one-off: the fixed `at` time as-is (even if already past, so a
+// missed one-off still fires once when the daemon comes back). Null if unparseable.
+export function computeNextRun(t: Trigger, from: Date = new Date()): Date | null {
+  if (t.cron) return cronNext(t.cron, from);
+  if (t.at) {
+    const d = new Date(t.at);
+    return Number.isNaN(d.getTime()) ? null : d;
+  }
+  return null;
+}
+
+// After a run, what to persist. Recurring routines reschedule; one-offs disable
+// themselves (they've now fired).
+export function advanceAfterRun(routine: Routine, from: Date = new Date()): Partial<Routine> {
+  if (isRecurring(routine)) return { nextRun: computeNextRun(routine, from)?.toISOString() };
+  return { enabled: false, nextRun: undefined };
+}
+
+// Short human description of when a routine fires, for /routine listings.
+export function describeTrigger(t: Trigger): string {
+  if (t.cron) return t.cron;
+  if (t.at) return `once @ ${new Date(t.at).toLocaleString()}`;
+  return "(no trigger)";
+}