@open-everywhere/core 0.1.0

package/dist/agent/routines/routine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routine.d.ts","sourceRoot":"","sources":["../../../agent/routines/routine.ts"],"names":[],"mappings":"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"}

package/dist/agent/routines/routine.js

@@ -0,0 +1,385 @@
+// The Routine model — the unit of OpenEverywhere's proactivity (Phase 3). A routine is
+// a durable, surface-owned instruction that fires WITHOUT a fresh @-mention:
+// the agent does work on a schedule, on a state change, or on an external event.
+//
+// Three trigger kinds, matching the plan's "3 routine types":
+//   - cron / interval  -> a SCHEDULED JOB (run at times / every N minutes).
+//   - watch            -> a CHANNEL WATCH: re-evaluated on a cadence, but posts
+//                         only when the watched state CHANGES (post-on-diff). The
+//                         routine carries `lastStateHash`; the fired turn records
+//                         its observation via the `record_watch_state` tool, which
+//                         hashes + compares host-side (see routines/watch.ts).
+//   - event            -> an EVENT SUBSCRIPTION (a PR opened, CI failed, …),
+//                         matched against inbound events rather than the clock.
+//
+// This module is framework-free (no eve / zod imports) so the store, the pure
+// schedule logic, and the tests can use it without pulling the runtime. The zod
+// input shape lives with the `create_routine` tool; the dispatcher lives in
+// agent/schedules/. Time/scheduling math is in schedule.ts; GC in lifecycle.ts.
+// STORED trigger shapes. Note the model-facing API (tools/create_routine.ts) is
+// deliberately DIFFERENT: one "scheduled" kind with a required postPolicy
+// ("every-run" | "only-on-change"), mapped onto these three at creation — the
+// stored kinds are an implementation detail (and pre-2026-07-04 rows exist), the
+// policy choice is the API. "watch" simply means only-on-change.
+//
+// The filter TYPES come from routines/event-model.ts (the pure registry leaf), not from
+// event-match.ts (the evaluator, which imports Routine) — a leaf, not a cycle.
+import { describeFilter, storedFilter } from "./event-model.js";
+import { ROUTINE_PERMISSION_PREFIX } from "./permission-key.js";
+/**
+ * THE report/target substitution — the whole of the OPE-148 destination split, as a pure function
+ * so that {@link import("../schedules/routine-dispatch.js").resolveRoutineTarget} needs exactly one
+ * line for it.
+ *
+ * Returns the routine UNCHANGED for every row that has no `{kind:"surface"}` report — which is
+ * every pre-OPE-148 row, every silent one, and every routine that reports where it lives. A silent
+ * routine deliberately does NOT redirect: it still dispatches into its own surface to run the
+ * turn at all, and its silence is a DELIVERY gate (channels/turn-delivery.ts), not a destination.
+ */
+export function reportDestinationOf(r) {
+    const rep = r.report;
+    return rep?.kind === "surface" ? { ...r, surfaceKey: rep.surfaceKey, target: rep.target } : r;
+}
+/** Where this routine's fires POST — the report destination's surfaceKey when one is configured,
+ *  else the surface that owns it. NOT the tenancy/ownership key: use {@link Routine.surfaceKey}
+ *  for spend, GC reach, `list_routines` and the fire marker. */
+export function routineReportSurfaceKey(r) {
+    return r.report?.kind === "surface" ? r.report.surfaceKey : r.surfaceKey;
+}
+/** Hard cap on a job routine's working-state blob (OPE-55), matching OpenClaw's `trigger.state`
+ *  16 KB ceiling — a progress ledger, not a document store; oversize is rejected at the tool. */
+export const JOB_STATE_MAX_BYTES = 16 * 1024;
+/** Hard cap on a DECLARED failure reason (OPE-177, {@link Routine.lastFailureReason}). One line, not
+ *  a report: it exists to be read in an audit row next to a routine id, and it is MODEL-authored, so
+ *  it is truncated host-side rather than rejected — a declaration that fails on length would leave
+ *  the run recorded as a success, which is the exact defect the tool closes. */
+export const RUN_FAILURE_REASON_MAX_CHARS = 300;
+/** Is this a DURABLE-JOB routine (OPE-55) — one that keeps its own persistent session across
+ *  fires — as opposed to a today's-default stateless routine? */
+export function isJobRoutine(r) {
+    return r.sessionMode === "job";
+}
+/** This routine's current authority generation — see {@link Routine.promptGeneration}. Absent,
+ *  zero, negative and non-integer all read as 1, so a hand-edited or migrated row can never
+ *  produce a key that collides with a DIFFERENT generation's. */
+export function routinePermissionGeneration(r) {
+    const g = r.promptGeneration;
+    return Number.isInteger(g) && g > 0 ? g : 1;
+}
+/** The generation an EDIT moves the routine to — always strictly greater than the current one,
+ *  so no edit can ever re-enter a generation whose grants/seat are already out there. */
+export function nextPromptGeneration(r) {
+    return routinePermissionGeneration(r) + 1;
+}
+/**
+ * The namespace every {@link routinePermissionKey} carries. It is what makes a routine's permission
+ * key UNCONFUSABLE with a session/window token: `channels/window-key.ts`'s tokens are surface-native
+ * (`slack:…`, a bare provider id), never this, so no session grant can ever be read as a declared
+ * permission or vice versa even though both live in the one `SessionApprovalRow` table.
+ *
+ * Declared by `routines/permission-key.ts`, the zero-import leaf that also holds the two readers for
+ * the key. Re-exported here because this module WRITES the key, so every consumer that spells one
+ * finds the prefix beside {@link routinePermissionKey}.
+ */
+export { ROUTINE_PERMISSION_PREFIX };
+/**
+ * The key a routine's DECLARED PERMISSIONS are stored under (OPE-152). It rides the existing
+ * `SessionApprovalRow.sessionId` column — a declared permission is the same fact as a session grant
+ * with a different lifetime, so it gets the same table and the same death mechanism rather than a
+ * second approval plane.
+ *
+ * 🔴 EVERY consumer MUST derive the key through this function. Keying a permission on the bare
+ * routine id would make `edit_routine` a laundering path: approve a write for the routine, then
+ * rewrite the prompt, and the permission a human gave to one instruction is inherited by another one
+ * they never read. Because the generation is IN the key, an edit invalidates the whole declared set with no
+ * sweep, which is essential given the store seam exposes no delete for these rows. (The declared
+ * set is not the whole set since OPE-1290: a refused fire posts a permission card into the routine's
+ * room, and a click there writes another row under this SAME key — so an edit still invalidates
+ * everything at once, which is exactly why the card is keyed here rather than on the bare id.) The
+ * callers are `routines/declared-permissions.ts` (the read/write/revoke seam),
+ * `approvals/routine-permission.ts` (the card's click) and the fire stamp below, so "derive it
+ * through this function" is structural, not a convention.
+ */
+export function routinePermissionKey(r) {
+    return `${ROUTINE_PERMISSION_PREFIX}${r.id}:g${routinePermissionGeneration(r)}`;
+}
+/** Does this routine report NOTHING into its surface (OPE-149)? — see {@link RoutineReport}. */
+export function isSilentRoutine(r) {
+    return r.report?.kind === "silent";
+}
+/**
+ * REFUSE the two contradictions the (trigger, report, sessionMode) triple can express:
+ *
+ *   1. A SILENT routine whose stored trigger is `watch`. `watch` IS the only-on-change post
+ *      policy — its whole mechanism is "post when the observed state differs" (routines/watch.ts)
+ *      — so pairing it with "never post" asks the host to run a diff whose only consumer has been
+ *      removed. A silent watch is just a silent cron, so the shape is refused rather than quietly
+ *      reinterpreted.
+ *
+ *   2. A DURABLE JOB (`sessionMode: "job"`) whose stored trigger is `watch`. `renderFireMessage`
+ *      (routines/fire-message.ts) checks `isJobRoutine` FIRST and returns before the watch arm ever
+ *      runs — the job protocol supersedes the watch protocol unconditionally. So a job+watch
+ *      routine's diff step never executes, and every fire posts, no matter what `only-on-change`
+ *      told the human it would do. `describeTrigger` has no job awareness either, so the
+ *      confirmation card would read "durable job every 15 min (posts only on change)" while the
+ *      routine posts on every single fire — the confirmation string would be a lie. Refused for the
+ *      same reason as (1): the field would exist on the schema and do nothing.
+ *
+ * Called at every boundary a routine's (trigger, report, sessionMode) triple can be formed or
+ * re-enter through — the model-facing tool (tools/create_routine.ts, where the job/watch pair is
+ * refused earlier too but this is the one place the invariant is asserted rather than merely
+ * implied), the durable store write (routines/store.ts addRoutine, which a hand-built or migrated
+ * row also passes through), and the edit lifecycle (approvals/routine-lifecycle.ts routine.edit,
+ * which cannot change either field but re-asserts anyway on the standing store-boundary discipline
+ * that no caller is trusted to have checked it). The store check is the load-bearing one: a schema
+ * can be widened, a stored row can be edited, and the invariant has to hold for whatever actually
+ * reaches the dispatcher.
+ */
+export function assertReportConsistent(trigger, report, sessionMode) {
+    if (report?.kind === "silent" && trigger.kind === "watch") {
+        throw new Error("A routine can't be both `never` (posts nothing) and only-on-change — a silent watch is just a silent cron. Pick one.");
+    }
+    if (sessionMode === "job" && trigger.kind === "watch") {
+        throw new Error("A durable job can't use only-on-change — a job's fire always gets the job protocol (its own accumulated thread context), which supersedes the watch protocol entirely, so the diff step that would post only on change never runs and the job posts on EVERY fire instead. Drop `job`, or use `every-run` or `never` instead of `only-on-change`.");
+    }
+}
+/**
+ * THROWS if an `event` trigger carries a stored filter shape this build cannot read (OPE-1145) —
+ * a surviving pre-OPE-210 `filter` / `match`, or any other key a hand-edit invented.
+ *
+ * WHY IT THROWS AT THE DURABLE WRITE AND NOT AT EVERY READ. The store is where an unreadable row
+ * can still be STOPPED; a read-path throw would abort `listAllRoutines` for the whole dispatcher
+ * tick, so one hand-edited row would silence every OTHER tenant's schedules — the same fleet-wide
+ * blast radius `event-match.ts` refuses a fire-time throw for. A row already at rest is caught on
+ * the other two surfaces instead, and both are loud: `evaluateSubscription` reports it `invalid`
+ * (a `routine.skip` audit row, reason `filter_invalid`, and NO fire), and `describeFilter` renders
+ * it as unreadable wherever a human reads the subscription back.
+ *
+ * The TypeScript type already forbids the shape, which is exactly why this exists: the rows this
+ * catches are the ones that never passed through the compiler — a migrated row, a hand-edited row,
+ * a row written by an older build.
+ */
+export function assertKnownSubscription(trigger) {
+    if (trigger.kind !== "event")
+        return;
+    const f = storedFilter(trigger);
+    if (f.kind !== "unknown")
+        return;
+    throw new Error(`This event subscription carries a filter shape this build cannot read: ${f.keys.join(", ")}. ` +
+        "A subscription filter is a jq expression (`jq`) and has been since OPE-210; the retired `filter` and `match` " +
+        "languages were deleted by OPE-1145. Rewrite the filter as jq rather than storing a shape nothing can evaluate — " +
+        "a row like this can never fire.");
+}
+/** Trigger kinds the clock-driven dispatcher evaluates (vs event-driven). */
+export function isClockScheduled(t) {
+    return t.kind === "cron" || t.kind === "interval" || t.kind === "watch" || t.kind === "once";
+}
+// Auth-attribute keys the dispatcher stamps onto a fired routine's session, so a
+// session-end hook can attribute the real outcome (ok/failed) back to the routine
+// and let it self-disable. (The dispatcher advances the schedule optimistically;
+// the OUTCOME is only known when the fired session finishes — this carries the link.)
+export const ROUTINE_MARKER = {
+    id: "open_everywhere_routine_id",
+    surface: "open_everywhere_routine_surface",
+    org: "open_everywhere_routine_org",
+    /** OPE-149: this fire REPORTS NOTHING — host-set, model-unforgeable (channels/unified-window.ts
+     *  §AUTH-ATTRIBUTE PROVENANCE), stamped only by routines/fire-auth.ts off the stored
+     *  {@link RoutineReport}. hooks/routine-silence.ts turns it into the per-turn signal that drops
+     *  the turn's terminal prose. Stamped ONLY when silent — a normal fire's bag is byte-identical. */
+    silent: "open_everywhere_routine_silent",
+    /** OPE-147: this fire was asked for OFF-SCHEDULE by a human (`run_routine_now`) — host-set,
+     *  model-unforgeable (channels/unified-window.ts §AUTH-ATTRIBUTE PROVENANCE), stamped only by
+     *  routines/fire-auth.ts off the stored {@link Routine.manualRunAt}. hooks/routine-outcome.ts
+     *  reads it back so the `routine.fire` join row can carry `manual: true`. Stamped ONLY on a
+     *  manual fire — a scheduled fire's bag is byte-identical. */
+    manual: "open_everywhere_routine_manual",
+    /** OPE-152: the DECLARED-PERMISSION KEY this fire's approvals are keyed under — host-set,
+     *  model-unforgeable (channels/unified-window.ts §AUTH-ATTRIBUTE PROVENANCE), stamped only by
+     *  routines/fire-auth.ts from {@link routinePermissionKey} off the STORED row (so it carries the
+     *  row's live {@link Routine.promptGeneration}, not one the fired session could name).
+     *
+     *  It is what makes "approve for this routine" the SAME mechanism as "approve for session"
+     *  rather than a second approval plane: `identity/binding.ts` proposingSessionId returns this key
+     *  in place of the window token for a fire, so the consult site (open_pull_request's session
+     *  skip) and the click path's memo write (approvals/flow.ts, off the frozen `sessionId` arg)
+     *  land on the routine's key with NO branch of their own.
+     *
+     *  Unlike the silent/manual stamps this one is NOT positive-only — every routine fire carries it,
+     *  because a fire with no key would silently fall back to its window token and write a permission
+     *  row that outlives nothing and revokes with nothing.
+     *
+     *  🔴 THE VALUE IS A WIRE STRING AND DOES NOT MOVE (OPE-1303). It is the attribute key a live
+     *  fire's auth bag already carries, so the vocabulary sweep renamed this field and left
+     *  `"open_everywhere_routine_grant_key"` alone. Renaming the value would make an in-flight fire
+     *  fall back to its window token — exactly the failure the paragraph above rules out. */
+    permissionKey: "open_everywhere_routine_grant_key",
+    /** OPE-626: THE PER-FIRE ID — host-minted once per fire by the dispatcher (`fireWakeId`), stamped
+     *  by routines/fire-auth.ts, and carried by every turn of that fire.
+     *
+     *  It exists because `oe_wake_id` — the value hooks/routine-outcome.ts latched on — is stamped by
+     *  the UNIFIED-WINDOW divert (routines/fire-window.ts) and by nothing else. A fire that stays on
+     *  the NATIVE path carries none, so every fire in one session collapsed to the hook's shared
+     *  `no-wake` sentinel. For a per-run fire seat that is harmless (one session, one fire); for a
+     *  native-path JOB seat, which is ONE session across MANY fires, it meant the first fire latched
+     *  the sentinel and every later fire in that seat folded nothing, silently, for the life of the
+     *  seat. This stamp is on BOTH paths, so the latch has a real per-fire key on either.
+     *
+     *  Its value is the SAME uuid the divert stamps as `oe_wake_id` on the windowed path — the
+     *  dispatcher mints one id and passes it to both — so a windowed fire's latch key does not change.
+     *
+     *  It is DELIBERATELY NOT `oe_wake_id` itself, which is the other id the dispatcher already holds.
+     *  That stamp is the REPLY ADDRESS (identity/binding.ts `currentWakeId`) and the delivery nonce's
+     *  fallback (`deliveryStampOf`). A native fire registers no `wakeId → origin` row, so stamping it
+     *  there would hand the session a live-looking address that resolves to nothing, and would change
+     *  the task-wake comparison — both outside the fold this ticket is about. A routine-scoped key has
+     *  exactly one reader.
+     *
+     *  Every ROUTINE ingress stamps it: the clock dispatcher (schedules/dispatch.ts) and the event
+     *  fan-out (routines/ingress.ts). A WEBHOOK fire builds `webhookFireAttributes` instead and
+     *  carries no routine marker at all, so the outcome fold never arms for one and it needs no key. */
+    fire: "open_everywhere_routine_fire_id",
+    /** OPE-1627: the {@link ModelRole} this fire resolves instead of `primary` — host-set,
+     *  model-unforgeable (channels/unified-window.ts §AUTH-ATTRIBUTE PROVENANCE), stamped only by
+     *  routines/fire-auth.ts off the STORED {@link Routine.modelRole}.
+     *
+     *  POSITIVE-ONLY, and that is what makes inheritance the default at the wire as well as in the
+     *  type: a routine that names no role stamps nothing, so its bag is byte-identical to before this
+     *  field existed and `model/routing.ts` resolves exactly the role it always did. A fire cannot
+     *  ask for a cheaper model by talking — the value comes off the row the dispatcher read. */
+    modelRole: "open_everywhere_routine_model_role",
+};
+/** One string off an eve attribute bag, which holds either a value or a single-element array.
+ *  Exported because hooks/routine-outcome.ts reads the fire's `oe_wake_id` off the SAME bag and a
+ *  second copy of this three-line shape is a place for the two readers to drift. */
+export function oneAttrValue(v) {
+    if (typeof v === "string")
+        return v;
+    if (Array.isArray(v) && typeof v[0] === "string")
+        return v[0];
+    return undefined;
+}
+/** Extract the routine link from a session's auth attributes, or null. `org`
+ *  defaults to "default" for markers written before org was carried (back-compat). */
+export function routineMarker(attributes) {
+    const id = oneAttrValue(attributes?.[ROUTINE_MARKER.id]);
+    const surfaceKey = oneAttrValue(attributes?.[ROUTINE_MARKER.surface]);
+    const org = oneAttrValue(attributes?.[ROUTINE_MARKER.org]) ?? "default";
+    return id && surfaceKey ? { id, surfaceKey, org } : null;
+}
+/** Extract the SILENT fire stamp from a session's auth attributes (OPE-149). Positive-only: the
+ *  attribute is written only for a silent fire, so anything else — absent, empty, a different
+ *  value — reads as "this fire posts", the pre-OPE-149 behaviour. */
+export function routineSilentStamped(attributes) {
+    return oneAttrValue(attributes?.[ROUTINE_MARKER.silent]) === "true";
+}
+/** The model roles a routine may name (OPE-1627) — the routable set, and nothing else.
+ *
+ *  🔴 IT IS THE `ModelRoutes` KEY SET AND IS PINNED TO IT. A role a domain cannot route resolves
+ *  nothing, so accepting one would let a routine name a role that can never take effect and never
+ *  say so. `npm run lint:model-ids` (RULE 6) joins this list to the roles `agent/model/models.ts`
+ *  resolves, so a role added to the stack and forgotten here — or listed here and absent from the
+ *  stack — reds rather than drifting. */
+export const ROUTINE_MODEL_ROLES = ["primary", "utility", "supervisor"];
+/** Is `value` a role a routine may name? The runtime half of {@link Routine.modelRole}: the TYPE
+ *  forbids the shape, which is exactly why this exists — a migrated row, a hand-edited row, or a
+ *  row written by a newer build never passed through the compiler. */
+export function isRoutineModelRole(value) {
+    return typeof value === "string" && ROUTINE_MODEL_ROLES.includes(value);
+}
+/** Extract the MODEL-ROLE stamp from a session's auth attributes (OPE-1627), or undefined.
+ *
+ *  🔴 UNDEFINED MEANS INHERIT, and every rejection lands there. Positive-only like the silent and
+ *  manual stamps beside it, and VALIDATED on the way out: a bag carrying an unknown role reads as
+ *  "inherit" rather than being passed to the router, so the worst a broken or hand-set value can do
+ *  is leave the routine on the model it would have run anyway. */
+export function routineModelRoleStamped(attributes) {
+    const role = oneAttrValue(attributes?.[ROUTINE_MARKER.modelRole]);
+    return isRoutineModelRole(role) ? role : undefined;
+}
+/**
+ * Refuse a routine row whose {@link Routine.modelRole} is not a role anything can route.
+ *
+ * Called from `routines/store.ts addRoutine` beside {@link assertKnownSubscription}, for the same
+ * reason that one exists: the TypeScript type already forbids the shape, so the rows this catches
+ * are the ones that never passed through the compiler. It sits on the CREATE path only, exactly
+ * where its two siblings sit — `updateRoutine` takes a `Partial<Routine>` and runs none of the
+ * three, and moving one of them there without the others would be a half-invariant.
+ *
+ * 🔴 IT REFUSES AT THE WRITE, NOT AT THE FIRE. A fire that met an unknown role would have to choose
+ * between failing the run and running the wrong model, and both are worse than never storing the
+ * row. {@link routineModelRoleStamped} still degrades to inherit at the fire, because a row written
+ * by an older build must never break a deployment that rolls back.
+ */
+export function assertKnownModelRole(r) {
+    if (r.modelRole === undefined)
+        return; // absent = inherit, the default
+    if (isRoutineModelRole(r.modelRole))
+        return;
+    throw new Error(`This routine names the model role ${JSON.stringify(r.modelRole)}, which nothing can route. ` +
+        `A routine names one of: ${ROUTINE_MODEL_ROLES.join(", ")} — or names none, which inherits the deployment's model stack ` +
+        "(routines/routine.ts Routine.modelRole).");
+}
+/**
+ * Extract the DECLARED-PERMISSION KEY stamped onto a routine fire (OPE-152), or undefined off a
+ * fire. The value must carry {@link ROUTINE_PERMISSION_PREFIX} to be honoured: that is what stops a
+ * bag with a hand-set/garbage value from redirecting a permission lookup at an arbitrary session
+ * token, and it keeps the "a routine key is unconfusable with a window token" property a CHECK
+ * rather than a comment.
+ */
+export function routinePermissionKeyStamped(attributes) {
+    const key = oneAttrValue(attributes?.[ROUTINE_MARKER.permissionKey]);
+    return key !== undefined && key.startsWith(ROUTINE_PERMISSION_PREFIX) ? key : undefined;
+}
+/** Extract the MANUAL fire stamp from a session's auth attributes (OPE-147). Positive-only, for
+ *  the same reason {@link routineSilentStamped} is: the attribute is written only for a fire a
+ *  human asked for off-schedule, so anything else reads as "this was the clock", the default. */
+export function routineManualStamped(attributes) {
+    return oneAttrValue(attributes?.[ROUTINE_MARKER.manual]) === "true";
+}
+/**
+ * Extract the PER-FIRE ID stamped onto a routine fire (OPE-626, {@link ROUTINE_MARKER.fire}), or
+ * undefined when the bag carries none.
+ *
+ * `undefined` is a real answer, not a failure: a fire dispatched by a deployment older than this
+ * stamp carries no id, and hooks/routine-outcome.ts falls back to `oe_wake_id` and then to its
+ * fail-closed sentinel. An empty string reads as absent, so a blank stamp can never become a latch
+ * key every fire in a session would share.
+ */
+export function routineFireIdStamped(attributes) {
+    const id = oneAttrValue(attributes?.[ROUTINE_MARKER.fire]);
+    return id !== undefined && id.length > 0 ? id : undefined;
+}
+/** One-line human description of a trigger, for `list_routines` / the CLI.
+ *  Post policy is spelled out, never jargon ("watch").
+ *
+ *  `report` (OPE-149) is the routine's post policy where the TRIGGER can't carry it: a silent
+ *  routine's stored trigger is an ordinary `cron`/`interval`, so without this the whole list view
+ *  would claim a routine "posts every run" while it is structurally incapable of posting. That is
+ *  visibility leg 1 of three (the others: the `routine.fire` audit row, and the self-disable
+ *  announcement) — a silent routine is only legible if every surface that describes it says so. */
+export function describeTrigger(t, report) {
+    const silent = report?.kind === "silent";
+    // OPE-148 — a REDIRECTED routine names its destination in the SAME string, for the same reason a
+    // silent one names its silence: `list_routines` and the approval card both render this, and a
+    // routine that will post somewhere other than the room reading the card is exactly the fact that
+    // must not have to be inferred. Byte-identical for every row without a `surface` report.
+    const where = report?.kind === "surface" ? ` → posts into ${report.surfaceKey}` : "";
+    return describeTriggerCore(t, silent) + where;
+}
+function describeTriggerCore(t, silent) {
+    switch (t.kind) {
+        case "cron":
+            return `cron "${t.expr}" (UTC; ${silent ? "posts nothing" : "posts every run"})`;
+        case "interval":
+            return `every ${t.everyMinutes} min (${silent ? "posts nothing" : "posts every run"})`;
+        case "watch":
+            return t.expr !== undefined
+                ? `cron "${t.expr}" (UTC; posts only on change)`
+                : `every ${t.everyMinutes} min (posts only on change)`;
+        case "once":
+            return `once at ${t.at} (fires once, then disables)`;
+        case "event":
+            return describeFilter(t.source, t);
+    }
+}
+//# sourceMappingURL=routine.js.map

package/dist/agent/routines/routine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routine.js","sourceRoot":"","sources":["../../../agent/routines/routine.ts"],"names":[],"mappings":"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"}

package/dist/agent/routines/schedule.d.ts

@@ -0,0 +1,70 @@
+export interface CronField {
+    readonly star: boolean;
+    has(n: number): boolean;
+}
+export interface ParsedCron {
+    readonly minute: CronField;
+    readonly hour: CronField;
+    readonly dom: CronField;
+    readonly month: CronField;
+    readonly dow: CronField;
+}
+/**
+ * The routine dispatcher's tick cadence, in minutes — the ONE source of truth for it
+ * (schedules/dispatch.ts builds its cron from this, spend/reporting.ts floors its
+ * cadence predictions at it). A routine can be dispatched at most once per tick, so
+ * this is also the finest cadence any routine can actually achieve, whatever its
+ * trigger asks for. Changing it changes both the schedule and every prediction that
+ * reads it, together — which is the point of it living here rather than as a literal
+ * in two files that could drift.
+ */
+export declare const DISPATCH_TICK_MINUTES = 10;
+/** Parse a standard 5-field cron expression. Throws on malformed input. */
+export declare function parseCron(expr: string): ParsedCron;
+/** Does a UTC instant satisfy a parsed cron expression (to minute resolution)? */
+export declare function cronMatches(c: ParsedCron, date: Date): boolean;
+/**
+ * The first cron-matching minute strictly AFTER `from`. Scans minute-by-minute
+ * up to a bound (~13 months) to cover yearly schedules; returns null if nothing
+ * matches in range (treat as a malformed/never-firing routine).
+ */
+export declare function nextCronAfter(c: ParsedCron, from: Date): Date | null;
+type Trigger = {
+    kind: "cron";
+    expr: string;
+} | {
+    kind: "interval";
+    everyMinutes: number;
+} | {
+    kind: "watch";
+    everyMinutes?: number;
+    expr?: string;
+} | {
+    kind: "once";
+    at: string;
+} | {
+    kind: "event";
+    source: string;
+};
+/**
+ * The next instant a trigger is due, given a "from" instant and (optionally) a "not
+ * before" floor. Null for `event` triggers (not clock-scheduled), for a cron that
+ * never fires in range, for a watch with neither cadence nor cron (which
+ * create_routine refuses to store), and ALWAYS for `once` — a one-shot's due
+ * instant is fixed at creation (create_routine sets nextRunAt = `at` directly,
+ * bypassing this function) and never recomputed: there is no "next" occurrence
+ * after it fires, which is what makes the dispatcher's advance-the-schedule step
+ * naturally retire it (nextRunAt -> null) whether it fires or is declined.
+ *
+ * `from` is the schedule ANCHOR — at creation, "now"; at dispatch, the instant the
+ * routine was DUE. `notBefore` is the instant the result must be strictly after, i.e.
+ * the dispatcher's tick instant; it defaults to `from`, which is the creation-time
+ * call and leaves that path byte-identical. See {@link nextIntervalAfter} for why the
+ * two are separated. Cron is anchored to the wall clock by construction, so it simply
+ * takes the later of the two — unchanged behaviour at either call site.
+ */
+export declare function computeNextRun(trigger: Trigger, from: Date, notBefore?: Date): Date | null;
+/** Is a routine with this `nextRunAt` due at `now`? */
+export declare function isDue(nextRunAt: string | null | undefined, now: Date): boolean;
+export {};
+//# sourceMappingURL=schedule.d.ts.map

package/dist/agent/routines/schedule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule.d.ts","sourceRoot":"","sources":["../../../agent/routines/schedule.ts"],"names":[],"mappings":"AAqBA,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;CACzB;AAID;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAuCxC,2EAA2E;AAC3E,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAYlD;AAED,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAW9D;AAMD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAQpE;AAID,KAAK,OAAO,GACR;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACvD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC5B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AA8BtC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,GAAE,IAAW,GAAG,IAAI,GAAG,IAAI,CAehG;AAED,uDAAuD;AACvD,wBAAgB,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAI9E"}