@terminus-ai/cli 0.0.1

package/bin/schedules.mjs

@@ -0,0 +1,664 @@
+/**
+ * Agent trigger authoring (terminus.json, kind "agent").
+ *
+ * An agent is its own orchestrator, so its triggers do not need the
+ * declarative workflow layer apps use (`workloads.automations` + steps +
+ * `$from`): a trigger on an agent means "wake the agent", and the only
+ * things worth authoring are when it wakes, what the wake says, and whether
+ * the run's result reaches the user as a notification. Agents therefore
+ * declare four top-level prompt-form sections —
+ *
+ *   "schedules": [{ "every": "day", "at": "08:30", "timezone": "…",
+ *                   "prompt": "…" }]
+ *   "webhooks":  [{ "name": "github", "prompt": "…" }]
+ *   "watches":   [{ "url": "https://…", "pattern": "…", "prompt": "…" }]
+ *   "events":    [{ "collection": "notes", "prompt": "…" }]
+ *
+ * — and this module desugars them into the platform's canonical `workloads`
+ * wire shape (the runtime is untouched; scheduling, fatigue and
+ * park-on-turn all keep working). `name` is optional while a section has one
+ * entry (the key is then "default") and required to disambiguate several.
+ * `prompt` is optional everywhere: an agent's AGENT.md already says what it
+ * does, so an unprompted wake just tells the agent why it woke.
+ *
+ * The desugared schedule automations are shared and parametrized through
+ * `input.prompt` (`scheduled-run`) rather than
+ * inlined per schedule — that is what lets the platform mint NEW schedule
+ * rows at runtime (a user asking the agent to change its own cadence)
+ * without touching the immutable release.
+ */
+
+import { CliError } from "./client.mjs";
+
+export const AGENT_TRIGGER_SECTIONS = ["schedules", "webhooks", "watches", "events"];
+
+/** Shared automation name the schedule desugar emits. */
+export const SCHEDULED_RUN = "scheduled-run";
+
+/** Mirror of the backend's notification-preview derivation: the reply's
+ * first non-empty line, unwrapped of leading markdown furniture and capped —
+ * the short text a standing run's notification card shows. */
+export function notificationSummary(text) {
+  const line = String(text ?? "")
+    .split("\n")
+    .map((candidate) => candidate.replace(/^[#>*\-\s]+/, "").trim())
+    .find(Boolean) ?? "";
+  const collapsed = line.replace(/\s+/g, " ");
+  return collapsed.length > 140 ? `${collapsed.slice(0, 139).trimEnd()}…` : collapsed;
+}
+
+/** Timezone sentinel: each installer's own timezone, resolved per
+ * installation by the platform (and locally to this machine's zone). */
+export const USER_TIMEZONE = "user";
+
+/** Shared automation name the watch desugar emits. */
+export const WATCHED_CHANGE = "watched-change";
+
+/** A watch's T0 firing condition: exactly one numeric threshold the
+ * platform's poller evaluates with no model spend — `changed_by_pct` (moved
+ * that far from the value last fired about), or `below`/`above` (crossing
+ * the level). Mirrors the backend's validate_watch_condition. */
+function validateWatchCondition(condition, key) {
+  if (!plainObject(condition)) {
+    throw new CliError(`watch '${key}' condition must be an object`);
+  }
+  const entries = Object.entries(condition);
+  if (entries.length !== 1) {
+    throw new CliError(
+      `watch '${key}' condition takes exactly one of changed_by_pct, below, above`,
+    );
+  }
+  const [field, value] = entries[0];
+  if (!["changed_by_pct", "below", "above"].includes(field)) {
+    throw new CliError(
+      `unknown watch condition field '${field}' (use changed_by_pct, below, or above)`,
+    );
+  }
+  if (typeof value !== "number" || !Number.isFinite(value)
+    || (field === "changed_by_pct" && value <= 0)) {
+    throw new CliError(
+      field === "changed_by_pct"
+        ? `watch '${key}' condition.changed_by_pct must be a positive number`
+        : `watch '${key}' condition.${field} must be a finite number`,
+    );
+  }
+}
+
+const MAX_TRIGGER_KEY = 48;
+const MAX_PROMPT = 4000;
+const WEEKDAY_INDEX = {
+  sunday: 0, monday: 1, tuesday: 2, wednesday: 3,
+  thursday: 4, friday: 5, saturday: 6,
+};
+const WEEKDAY_LABELS = [
+  "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday",
+];
+
+function plainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Minute, hour, day of month, month, weekday (Sunday is 0). */
+const CRON_FIELD_RANGES = [[0, 59], [0, 23], [1, 31], [1, 12], [0, 6]];
+
+/** How far ahead the platform looks for a schedule's next run: 527,040
+ * minutes (366 days) past the first candidate minute. A schedule with no run
+ * inside that window gets none. */
+const CRON_LOOKAHEAD_MINUTES = 527_040;
+
+/** The platform's five-field cron grammar (mirrors the backend's
+ * `valid_cron_expression`): each field is `*`, `* / N`, or one number. Answers
+ * each field's allowed values in ascending order — `* / N` allows the
+ * multiples of N, as the backend's `field_matches` reads it — or null when the
+ * expression is outside the grammar. */
+function cronFieldValues(expression) {
+  if (typeof expression !== "string" || expression.length > 100) return null;
+  const fields = expression.trim().split(/\s+/);
+  if (fields.length !== 5) return null;
+  const allowed = [];
+  for (const [index, field] of fields.entries()) {
+    const [minimum, maximum] = CRON_FIELD_RANGES[index];
+    const range = Array.from({ length: maximum - minimum + 1 }, (_, offset) => minimum + offset);
+    if (field === "*") {
+      allowed.push(range);
+    } else if (/^\*\/\d+$/.test(field)) {
+      const step = Number(field.slice(2));
+      if (step < 1 || step > maximum) return null;
+      allowed.push(range.filter((value) => value % step === 0));
+    } else if (/^\d+$/.test(field)) {
+      const value = Number(field);
+      if (value < minimum || value > maximum) return null;
+      allowed.push([value]);
+    } else {
+      return null;
+    }
+  }
+  return allowed;
+}
+
+/** Whether `expression` is in the platform's five-field cron grammar. */
+export function validUtcCron(expression) {
+  return cronFieldValues(expression) !== null;
+}
+
+/**
+ * The platform's next run for a UTC cron after `after`, as an ISO string, or
+ * null when it has none inside the platform's window — `0 0 30 2 *` never
+ * runs. The same answer as the backend's minute-by-minute search
+ * (`next_cron_after_in_timezone`, in UTC): from the next whole minute, every
+ * field matching, the day of month AND the weekday. Found field by field
+ * instead — a day at a time, then that day's first allowed hour and minute —
+ * so a schedule that never runs costs a year of days, not of minutes.
+ */
+export function nextCronAfter(expression, after = new Date()) {
+  const allowed = cronFieldValues(expression);
+  if (!allowed) return null;
+  const [minutes, hours, days, months, weekdays] = allowed;
+  const first = new Date(after);
+  first.setUTCSeconds(0, 0);
+  first.setUTCMinutes(first.getUTCMinutes() + 1);
+  const last = first.getTime() + CRON_LOOKAHEAD_MINUTES * 60_000;
+  const day = new Date(Date.UTC(first.getUTCFullYear(), first.getUTCMonth(), first.getUTCDate()));
+  let [fromHour, fromMinute] = [first.getUTCHours(), first.getUTCMinutes()];
+  while (day.getTime() <= last) {
+    if (months.includes(day.getUTCMonth() + 1)
+      && days.includes(day.getUTCDate())
+      && weekdays.includes(day.getUTCDay())) {
+      for (const hour of hours) {
+        if (hour < fromHour) continue;
+        const minute = minutes.find((candidate) => hour > fromHour || candidate >= fromMinute);
+        if (minute === undefined) continue;
+        const run = day.getTime() + (hour * 60 + minute) * 60_000;
+        return run <= last ? new Date(run).toISOString() : null;
+      }
+    }
+    day.setUTCDate(day.getUTCDate() + 1);
+    [fromHour, fromMinute] = [0, 0];
+  }
+  return null;
+}
+
+export function validTimeZone(timezone) {
+  if (typeof timezone !== "string" || !timezone || timezone.length > 100) return false;
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: timezone }).format(new Date(0));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function validKey(value) {
+  return typeof value === "string"
+    && value.length >= 1
+    && value.length <= MAX_TRIGGER_KEY
+    && /^[a-z0-9][a-z0-9_-]*$/.test(value);
+}
+
+function validPrompt(value) {
+  return typeof value === "string"
+    && value.trim().length >= 1
+    && value.length <= MAX_PROMPT
+    // Printable plus ordinary whitespace; other control characters are
+    // never part of an authored prompt.
+    && !/[\p{Cc}]/u.test(value.replaceAll(/[\n\r\t]/g, ""));
+}
+
+const parseAt = (value) => {
+  const match = /^([01]?\d|2[0-3]):([0-5]\d)$/.exec(String(value ?? ""));
+  return match ? { hour: Number(match[1]), minute: Number(match[2]) } : null;
+};
+
+/**
+ * The structured cadence: exactly one of
+ *   every: "day" | weekday | "month" | "<N>m" | "<N>h" | "hour"
+ * (with `at` for the daily shapes and `on_day` for monthly), or a raw
+ * five-field `cron` escape hatch. Returns { cron, human } or throws.
+ */
+export function cadenceToCron(entry, label) {
+  const { every, at, on_day: onDay, cron } = entry;
+  if (cron !== undefined) {
+    if (every !== undefined || at !== undefined || onDay !== undefined) {
+      throw new CliError(`${label} declares both 'cron' and a structured cadence — pick one`);
+    }
+    if (!validUtcCron(cron)) {
+      throw new CliError(
+        `${label} has an invalid cron — five fields, each *, */N, or one number`,
+      );
+    }
+    return { cron: cron.trim(), human: `cron ${cron.trim()}` };
+  }
+  if (typeof every !== "string" || !every) {
+    throw new CliError(`${label} needs a cadence: 'every' ("day", a weekday, "month", "30m", "2h") or 'cron'`);
+  }
+  const time = at !== undefined ? parseAt(at) : null;
+  if (at !== undefined && !time) {
+    throw new CliError(`${label} 'at' must be a 24h time like "08:30"`);
+  }
+  const twelve = (h, m) =>
+    `${h % 12 === 0 ? 12 : h % 12}:${String(m).padStart(2, "0")} ${h < 12 ? "AM" : "PM"}`;
+  const needsAt = () => {
+    if (!time) throw new CliError(`${label} needs 'at' ("HH:MM") with every: "${every}"`);
+    return time;
+  };
+  const noAt = () => {
+    if (at !== undefined) {
+      throw new CliError(`${label} cannot take 'at' with every: "${every}" — the interval is the time`);
+    }
+  };
+  const noDay = () => {
+    if (onDay !== undefined) {
+      throw new CliError(`${label} only takes 'on_day' with every: "month"`);
+    }
+  };
+  if (every === "day") {
+    noDay();
+    const { hour, minute } = needsAt();
+    return { cron: `${minute} ${hour} * * *`, human: `every day at ${twelve(hour, minute)}` };
+  }
+  if (every in WEEKDAY_INDEX) {
+    noDay();
+    const { hour, minute } = needsAt();
+    const dow = WEEKDAY_INDEX[every];
+    return {
+      cron: `${minute} ${hour} * * ${dow}`,
+      human: `every ${WEEKDAY_LABELS[dow]} at ${twelve(hour, minute)}`,
+    };
+  }
+  if (every === "month") {
+    const { hour, minute } = needsAt();
+    const day = onDay ?? 1;
+    if (!Number.isInteger(day) || day < 1 || day > 31) {
+      throw new CliError(`${label} 'on_day' must be 1-31`);
+    }
+    const tens = day % 100;
+    const suffix = tens >= 11 && tens <= 13 ? "th" : { 1: "st", 2: "nd", 3: "rd" }[day % 10] ?? "th";
+    return {
+      cron: `${minute} ${hour} ${day} * *`,
+      human: `on the ${day}${suffix} of each month at ${twelve(hour, minute)}`,
+    };
+  }
+  const interval = /^(\d{1,2})(m|h)$/.exec(every === "hour" ? "1h" : every);
+  if (interval) {
+    noDay();
+    noAt();
+    const n = Number(interval[1]);
+    if (interval[2] === "m") {
+      if (n < 1 || n > 59) throw new CliError(`${label} minute intervals are 1m-59m`);
+      return { cron: `*/${n} * * * *`, human: n === 1 ? "every minute" : `every ${n} minutes` };
+    }
+    if (n < 1 || n > 23) throw new CliError(`${label} hour intervals are 1h-23h`);
+    return { cron: `0 */${n} * * *`, human: n === 1 ? "every hour" : `every ${n} hours` };
+  }
+  throw new CliError(
+    `${label} 'every' must be "day", a weekday, "month", or an interval like "30m" or "2h"`,
+  );
+}
+
+/** The inverse, for sugar-up (clone/pull of a published agent): the cadence
+ * fields a cron round-trips to, or `{cron}` when it is outside the everyday
+ * shapes. */
+export function cronToCadence(cron) {
+  const fields = String(cron ?? "").trim().split(/\s+/);
+  if (fields.length !== 5) return { cron };
+  const [minute, hour, dom, month, dow] = fields;
+  const num = (field) => (/^\d+$/.test(field) ? Number(field) : null);
+  const step = (field) => (/^\*\/\d+$/.exec(field) ? Number(field.slice(2)) : null);
+  const at = num(minute) != null && num(hour) != null
+    ? `${String(num(hour)).padStart(2, "0")}:${String(num(minute)).padStart(2, "0")}`
+    : null;
+  if (month !== "*") return { cron };
+  if (step(minute) != null && hour === "*" && dom === "*" && dow === "*") {
+    return { every: `${step(minute)}m` };
+  }
+  if (num(minute) === 0 && step(hour) != null && dom === "*" && dow === "*") {
+    return { every: `${step(hour)}h` };
+  }
+  if (at == null) return { cron };
+  if (dom === "*" && dow === "*") return { every: "day", at };
+  if (dom === "*" && num(dow) != null) {
+    return { every: Object.keys(WEEKDAY_INDEX)[Object.values(WEEKDAY_INDEX).indexOf(num(dow))], at };
+  }
+  if (num(dom) != null && dow === "*") return { every: "month", on_day: num(dom), at };
+  return { cron };
+}
+
+/** What an unprompted wake says. The agent's own AGENT.md carries the WHAT;
+ * the default prompt only carries the WHY-woken. */
+export function defaultTriggerPrompt(kind, entry) {
+  const named = entry.key && entry.key !== "default" ? ` '${entry.key}'` : "";
+  switch (kind) {
+    case "schedule": {
+      const zone = entry.timezone === USER_TIMEZONE
+        ? ", the user's own timezone"
+        : entry.timezone && entry.timezone !== "UTC" ? `, ${entry.timezone}` : "";
+      return `This is your scheduled run${named} (${entry.human}${zone}). `
+        + "Do the work your instructions define for this schedule. "
+        + "Start your reply with one short line that reads well as a notification "
+        + "preview; if there is nothing worth reporting, reply with nothing.";
+    }
+    case "webhook":
+      return `Your webhook${named} received a delivery. Handle it the way your instructions describe. Start your reply with one short line that reads well as a notification preview.`;
+    case "watch":
+      return `A page you watch changed: ${entry.url}. Review the change below and act on it the way your instructions describe. Start your reply with one short line that reads well as a notification preview.`;
+    case "event":
+      return `Records changed in '${entry.collection}'. Review the changes below and act on them the way your instructions describe. Start your reply with one short line that reads well as a notification preview.`;
+    default:
+      return "You were woken by one of your triggers.";
+  }
+}
+
+function normalizeSection(manifest, section, label) {
+  const raw = manifest[section];
+  if (raw === undefined) return [];
+  if (!Array.isArray(raw)) throw new CliError(`${label} must be an array`);
+  const entries = [];
+  const keys = new Set();
+  for (const value of raw) {
+    if (!plainObject(value)) throw new CliError(`${label} entries must be objects`);
+    entries.push({ ...value });
+  }
+  for (const entry of entries) {
+    if (entry.name === undefined) {
+      if (entries.length > 1) {
+        throw new CliError(`${label} entries need unique names once there is more than one`);
+      }
+      entry.key = "default";
+    } else {
+      if (!validKey(entry.name)) {
+        throw new CliError(
+          `${label} names are 1-${MAX_TRIGGER_KEY} lowercase characters (a-z, 0-9, -, _)`,
+        );
+      }
+      entry.key = entry.name;
+    }
+    if (keys.has(entry.key)) throw new CliError(`${label} contains duplicate '${entry.key}'`);
+    keys.add(entry.key);
+    if (entry.prompt !== undefined && !validPrompt(entry.prompt)) {
+      throw new CliError(`${label} '${entry.key}' prompt must be 1-${MAX_PROMPT} printable characters`);
+    }
+    if (entry.enabled !== undefined && typeof entry.enabled !== "boolean") {
+      throw new CliError(`${label} '${entry.key}' enabled must be boolean`);
+    }
+    if (entry.description !== undefined
+      && (typeof entry.description !== "string" || entry.description.length > 300)) {
+      throw new CliError(`${label} descriptions must be at most 300 characters`);
+    }
+  }
+  return entries;
+}
+
+const allowedFields = (label, entry, allowed) => {
+  const field = Object.keys(entry).find(
+    (candidate) => candidate !== "key" && !allowed.includes(candidate),
+  );
+  if (field) throw new CliError(`unknown ${label} field '${field}'`);
+};
+
+/**
+ * Parse and validate an agent manifest's top-level trigger sections into
+ * normalized entries plus the canonical `workloads` wire shape. Pure —
+ * touches nothing on `manifest`.
+ */
+export function parseAgentTriggers(manifest, { agentName } = {}) {
+  const schedules = normalizeSection(manifest, "schedules", "schedules");
+  const webhooks = normalizeSection(manifest, "webhooks", "webhooks");
+  const watches = normalizeSection(manifest, "watches", "watches");
+  const events = normalizeSection(manifest, "events", "events");
+
+  for (const entry of schedules) {
+    allowedFields("schedules", entry, [
+      "name", "every", "at", "on_day", "cron", "timezone", "prompt", "enabled",
+    ]);
+    const { cron, human } = cadenceToCron(entry, `schedule '${entry.key}'`);
+    entry.cron = cron;
+    entry.human = human;
+    // "user" means each installer's own timezone — the platform resolves it
+    // per installation, so "every Monday morning" is THEIR Monday morning.
+    if (entry.timezone !== undefined
+      && entry.timezone !== USER_TIMEZONE
+      && !validTimeZone(entry.timezone)) {
+      throw new CliError(
+        `schedule '${entry.key}' timezone must be an IANA name or "user" (each user's own timezone)`,
+      );
+    }
+  }
+  for (const entry of webhooks) {
+    allowedFields("webhooks", entry, [
+      "name", "description", "prompt", "coalesce_seconds", "enabled",
+    ]);
+  }
+  for (const entry of watches) {
+    allowedFields("watches", entry, [
+      "name", "description", "url", "pattern", "interval_minutes", "prompt", "condition", "enabled",
+    ]);
+    entry.interval_minutes = entry.interval_minutes ?? 60;
+    if (entry.condition !== undefined) validateWatchCondition(entry.condition, entry.key);
+  }
+  for (const entry of events) {
+    allowedFields("events", entry, [
+      "name", "description", "collection", "prompt", "coalesce_seconds", "enabled",
+    ]);
+  }
+
+  // Every standing run notifies — there is no toggle. The notification is a
+  // compact card, not a transcript: its body is the run's short summary (the
+  // platform derives it from the reply's first line), and a run that
+  // produced nothing sends nothing. Zero-trigger agents only compile the
+  // notify machinery when they can mint runs later (the schedules grant).
+  const hasTriggers = Boolean(
+    schedules.length || webhooks.length || watches.length || events.length,
+  );
+  const grantedTool = (id) => (manifest.tools ?? []).some(
+    (tool) => (typeof tool === "string" ? tool : tool?.id) === id,
+  );
+  const schedulesGranted = grantedTool("schedules.manage");
+  const watchesGranted = grantedTool("watches.manage");
+  const needsNotifications = hasTriggers
+    || schedulesGranted || watchesGranted
+    || manifest.shell?.notifications === true;
+
+  const title = String(agentName ?? "Agent").slice(0, 160);
+  const notifyStep = {
+    action: "notification.create",
+    params: {
+      title,
+      body: { $from: "steps.0.result.summary" },
+      skip_if_empty: true,
+    },
+  };
+  const automations = [{
+    name: SCHEDULED_RUN,
+    steps: [
+      { action: "agent.run", params: { prompt: { $from: "input.prompt" } } },
+      ...(needsNotifications ? [structuredClone(notifyStep)] : []),
+    ],
+  }];
+  // Watches share ONE parametrized automation the way schedules do — the
+  // seam that lets the platform mint watch rows at runtime. The firing's
+  // payload is { prompt, event }: the wake text from the row, the diff
+  // fenced as untrusted data.
+  if (watches.length || watchesGranted) {
+    automations.push({
+      name: WATCHED_CHANGE,
+      steps: [
+        {
+          action: "agent.run",
+          params: { prompt: { $from: "input.prompt" }, context: { $from: "input.event" } },
+        },
+        ...(needsNotifications ? [structuredClone(notifyStep)] : []),
+      ],
+    });
+  }
+  const eventAutomation = (kind, entry) => {
+    const name = `on-${kind}-${entry.key}`;
+    automations.push({
+      name,
+      steps: [
+        {
+          action: "agent.run",
+          params: {
+            prompt: entry.prompt ?? defaultTriggerPrompt(kind, entry),
+            context: { $from: "input" },
+          },
+        },
+        structuredClone(notifyStep),
+      ],
+    });
+    return name;
+  };
+
+  const workloads = { automations };
+  if (schedules.length) {
+    workloads.schedules = schedules.map((entry) => ({
+      name: entry.key,
+      cron: entry.cron,
+      ...(entry.timezone !== undefined ? { timezone: entry.timezone } : {}),
+      automation: SCHEDULED_RUN,
+      input: { prompt: entry.prompt ?? defaultTriggerPrompt("schedule", entry) },
+      ...(entry.enabled === false ? { enabled: false } : {}),
+    }));
+  }
+  if (webhooks.length) {
+    workloads.webhooks = webhooks.map((entry) => ({
+      name: entry.key,
+      ...(entry.description !== undefined ? { description: entry.description } : {}),
+      automation: eventAutomation("webhook", entry),
+      ...(entry.coalesce_seconds !== undefined ? { coalesce_seconds: entry.coalesce_seconds } : {}),
+      ...(entry.enabled === false ? { enabled: false } : {}),
+    }));
+  }
+  if (watches.length) {
+    workloads.watches = watches.map((entry) => ({
+      name: entry.key,
+      ...(entry.description !== undefined ? { description: entry.description } : {}),
+      url: entry.url,
+      ...(entry.pattern !== undefined ? { pattern: entry.pattern } : {}),
+      interval_minutes: entry.interval_minutes,
+      automation: WATCHED_CHANGE,
+      input: { prompt: entry.prompt ?? defaultTriggerPrompt("watch", entry) },
+      ...(entry.condition !== undefined ? { condition: entry.condition } : {}),
+      ...(entry.enabled === false ? { enabled: false } : {}),
+    }));
+  }
+  if (events.length) {
+    workloads.events = events.map((entry) => ({
+      name: entry.key,
+      ...(entry.description !== undefined ? { description: entry.description } : {}),
+      collection: entry.collection,
+      automation: eventAutomation("event", entry),
+      ...(entry.coalesce_seconds !== undefined ? { coalesce_seconds: entry.coalesce_seconds } : {}),
+      ...(entry.enabled === false ? { enabled: false } : {}),
+    }));
+  }
+
+  return { schedules, webhooks, watches, events, workloads, needsNotifications };
+}
+
+/**
+ * The reverse of the desugar, for clone/pull: reconstruct the authored
+ * top-level sections from a wire `workloads` this module emitted. Returns
+ * null for a wire it did not emit rather than guess — the caller keeps that
+ * `workloads` as it is, and validation refuses it.
+ */
+export function sugarAgentTriggers(workloads, { agentName, shell, tools } = {}) {
+  if (!plainObject(workloads)) return null;
+  const automations = new Map(
+    (workloads.automations ?? []).map((automation) => [automation?.name, automation]),
+  );
+  const scheduleEntries = [];
+  for (const wire of workloads.schedules ?? []) {
+    if (wire?.automation !== SCHEDULED_RUN) return null;
+    const prompt = wire?.input?.prompt;
+    if (typeof prompt !== "string") return null;
+    const cadence = cronToCadence(wire.cron);
+    const entry = {
+      ...(wire.name !== "default" || (workloads.schedules ?? []).length > 1
+        ? { name: wire.name } : {}),
+      ...cadence,
+      ...(wire.timezone !== undefined ? { timezone: wire.timezone } : {}),
+    };
+    const bare = {
+      key: wire.name,
+      human: cadenceToCron({ ...cadence }, `schedule '${wire.name}'`).human,
+      timezone: wire.timezone,
+    };
+    if (prompt !== defaultTriggerPrompt("schedule", bare)) entry.prompt = prompt;
+    if (wire.enabled === false) entry.enabled = false;
+    scheduleEntries.push(entry);
+  }
+  const familyEntries = (kind, wires, fields) => {
+    const entries = [];
+    for (const wire of wires ?? []) {
+      const automation = automations.get(`on-${kind}-${wire?.name}`);
+      const run = automation?.steps?.[0];
+      if (run?.action !== "agent.run" || typeof run?.params?.prompt !== "string") return null;
+      const entry = {
+        ...(wire.name !== "default" || wires.length > 1 ? { name: wire.name } : {}),
+      };
+      for (const field of fields) {
+        if (wire[field] !== undefined) entry[field] = wire[field];
+      }
+      const bare = { key: wire.name, url: wire.url, collection: wire.collection };
+      if (run.params.prompt !== defaultTriggerPrompt(kind, bare)) entry.prompt = run.params.prompt;
+      if (wire.enabled === false) entry.enabled = false;
+      entries.push(entry);
+    }
+    return entries;
+  };
+  const webhooks = familyEntries("webhook", workloads.webhooks, ["description", "coalesce_seconds"]);
+  const events = familyEntries("event", workloads.events, ["description", "collection", "coalesce_seconds"]);
+  const watches = [];
+  for (const wire of workloads.watches ?? []) {
+    if (wire?.automation !== WATCHED_CHANGE) return null;
+    const prompt = wire?.input?.prompt;
+    if (typeof prompt !== "string") return null;
+    const entry = {
+      ...(wire.name !== "default" || (workloads.watches ?? []).length > 1
+        ? { name: wire.name } : {}),
+    };
+    for (const field of ["description", "url", "pattern", "interval_minutes", "condition"]) {
+      if (wire[field] !== undefined) entry[field] = wire[field];
+    }
+    const bare = { key: wire.name, url: wire.url };
+    if (prompt !== defaultTriggerPrompt("watch", bare)) entry.prompt = prompt;
+    if (wire.enabled === false) entry.enabled = false;
+    watches.push(entry);
+  }
+  if (!webhooks || !events) return null;
+  // Round-trip check: re-desugaring the reconstruction must reproduce the
+  // wire shape, or the wire carries something the sugar cannot say. The
+  // tools list rides along because the notify machinery also compiles for a
+  // zero-trigger agent holding the schedules grant.
+  const document = {
+    ...(scheduleEntries.length ? { schedules: scheduleEntries } : {}),
+    ...(webhooks.length ? { webhooks } : {}),
+    ...(watches.length ? { watches } : {}),
+    ...(events.length ? { events } : {}),
+  };
+  try {
+    const roundTrip = parseAgentTriggers(
+      {
+        ...document,
+        ...(plainObject(shell) ? { shell } : {}),
+        ...(Array.isArray(tools) ? { tools } : {}),
+      },
+      { agentName },
+    ).workloads;
+    if (JSON.stringify(normalizeForCompare(roundTrip))
+      !== JSON.stringify(normalizeForCompare(workloads))) return null;
+  } catch {
+    return null;
+  }
+  return document;
+}
+
+function normalizeForCompare(value) {
+  if (Array.isArray(value)) return value.map(normalizeForCompare);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.keys(value).sort().map((key) => [key, normalizeForCompare(value[key])]),
+    );
+  }
+  return value;
+}