@capybara-hq/kernel 0.1.0-rc.23 → 0.1.0-rc.25

package/dist/schedules/calendar.js

@@ -0,0 +1,410 @@
+import { scanStep, tickerOf, ticksIn } from "./schedule-math.js";
+/**
+ * The scheduled task calendar (spec 2026-11-12-scheduled-tasks-calendar-design.md §5): recorded
+ * runs and planned occurrences between two instants, dense task-days collapsed, cut at a whole
+ * day when a limit is reached. The assembly here is pure; `ScheduledTasksService.calendar` reads
+ * the rows and decides who sees what.
+ */
+const DAY_MS = 86_400_000;
+/** Planned occurrences reach this far ahead of now (spec §5.2, "about six weeks"). */
+export const CALENDAR_HORIZON_DAYS = 42;
+/** The longest range one request may ask for: a 6-week month grid plus a DST hour (§5.1). */
+export const CALENDAR_RANGE_DAYS = 43;
+/** The longest range with `taskId` (the panel's one-day list, §5.4). */
+export const CALENDAR_TASK_RANGE_DAYS = 2;
+/** A task-day with more items than this is collapsed into one summary (§5.4). */
+export const CALENDAR_COLLAPSE_OVER = 6;
+/**
+ * Ticks taken per request after the first local day, across all tasks (§5.5). One tick costs
+ * about 150-340 µs (cron's `getNextDateFrom`, measured 2026-11-12 with a ticker built once per
+ * task), so 3,000 keeps a worst-case request near one second.
+ */
+export const CALENDAR_TICK_BUDGET = 3_000;
+/** Entries (`items` + `collapsed`) per request after the first local day (§5.5). */
+export const CALENDAR_ITEM_CAP = 3_000;
+/** Run rows read per request after the first local day (§5.5). */
+export const CALENDAR_RUN_ROW_CAP = 20_000;
+/**
+ * The first requested local day is always returned whole, outside the limits above; only these
+ * safety caps stop it (then nothing is returned, `truncated`, `horizon` = `from`).
+ */
+export const CALENDAR_FIRST_DAY_TICK_CAP = 10_000;
+export const CALENDAR_FIRST_DAY_RUN_CAP = 20_000;
+export const CALENDAR_LIMITS = {
+    horizonDays: CALENDAR_HORIZON_DAYS,
+    collapseOver: CALENDAR_COLLAPSE_OVER,
+    tickBudget: CALENDAR_TICK_BUDGET,
+    itemCap: CALENDAR_ITEM_CAP,
+    runRowCap: CALENDAR_RUN_ROW_CAP,
+    firstDayTickCap: CALENDAR_FIRST_DAY_TICK_CAP,
+    firstDayRunCap: CALENDAR_FIRST_DAY_RUN_CAP,
+};
+/** How many run rows the service reads: enough to tell where either run cap cuts. */
+export const calendarRunReadLimit = (limits) => limits.firstDayRunCap + limits.runRowCap + 1;
+/** The calendar answer from the rows (spec §5.2–§5.5). */
+export function assembleCalendar(input, limits = CALENDAR_LIMITS) {
+    const { timeZone, now } = input;
+    const horizonAt = now.getTime() + limits.horizonDays * DAY_MS;
+    const fromMs = input.from.getTime();
+    // `cut`: the exclusive end of what is returned; a limit moves it back to a local day start, and
+    // only a first-day safety cap moves it to `from` (nothing returned)
+    let cut = input.to.getTime();
+    let truncated = false;
+    // the first requested local day is returned whole, outside the budget and the caps
+    const firstDay = dayKey(fromMs, timeZone);
+    const firstDayEnd = Math.min(cut, startOfLocalDay(startOfLocalDay(fromMs, timeZone) + 26 * 3_600_000, timeZone));
+    // the run read is bounded too: past a cap, the range ends at the start of the local day of the
+    // first row over it
+    const firstDayRuns = input.runs.filter((r) => r.scheduledFor.getTime() < firstDayEnd).length;
+    const overRun = input.runs[firstDayRuns + limits.runRowCap];
+    if (firstDayRuns > limits.firstDayRunCap) {
+        cut = fromMs;
+        truncated = true;
+    }
+    else if (overRun !== undefined) {
+        cut = startOfLocalDay(overRun.scheduledFor.getTime(), timeZone);
+        truncated = true;
+    }
+    const planned = input.plan && cut > fromMs
+        ? planOccurrences(input, horizonAt, limits, firstDayEnd, cut)
+        : { ticks: new Map(), cut };
+    if (planned.cut < cut) {
+        cut = planned.cut;
+        truncated = true;
+    }
+    // a tick the scan recorded is shown as its run, never twice
+    const recorded = new Set(input.runs.filter((r) => !r.trial).map((r) => `${r.taskId}|${r.scheduledFor.getTime()}`));
+    const byId = new Map(input.tasks.map((t) => [t.id, t]));
+    const raw = [];
+    for (const r of input.runs) {
+        const own = byId.get(r.taskId)?.accountId === input.viewerAccountId;
+        raw.push({ at: r.scheduledFor.getTime(), taskId: r.taskId, item: runItem(r, own) });
+    }
+    for (const [taskId, ticks] of planned.ticks) {
+        const jitterMs = (byId.get(taskId)?.jitterSeconds ?? 0) * 1000;
+        for (const tick of ticks) {
+            if (recorded.has(`${taskId}|${tick}`))
+                continue;
+            raw.push({
+                at: tick,
+                taskId,
+                item: {
+                    kind: "occurrence",
+                    taskId,
+                    scheduledFor: new Date(tick).toISOString(),
+                    at: new Date(tick + jitterMs).toISOString(),
+                },
+            });
+        }
+    }
+    // group by local day, then by task: a task-day over the threshold becomes one summary
+    const days = new Map();
+    for (const e of raw) {
+        if (e.at >= cut)
+            continue;
+        const day = dayKey(e.at, timeZone);
+        let tasks = days.get(day);
+        if (!tasks) {
+            tasks = new Map();
+            days.set(day, tasks);
+        }
+        const list = tasks.get(e.taskId);
+        if (list)
+            list.push(e);
+        else
+            tasks.set(e.taskId, [e]);
+    }
+    // walk the days in order; a day is added whole or not at all
+    const entries = [];
+    // the first day's entries do not count against the cap (the day is always returned whole)
+    let counted = 0;
+    for (const day of [...days.keys()].sort()) {
+        const dayEntries = [];
+        for (const [taskId, list] of days.get(day) ?? []) {
+            if (input.collapse && list.length > limits.collapseOver) {
+                dayEntries.push({
+                    kind: "collapsed",
+                    at: firstAt(list),
+                    taskId,
+                    collapsed: summarize(taskId, day, list),
+                });
+            }
+            else {
+                for (const e of list)
+                    dayEntries.push({ kind: "item", ...e });
+            }
+        }
+        if (day !== firstDay && counted + dayEntries.length > limits.itemCap) {
+            const start = startOfLocalDay(dayEntries[0]?.at ?? cut, timeZone);
+            if (start < cut) {
+                cut = start;
+                truncated = true;
+            }
+            break;
+        }
+        entries.push(...dayEntries);
+        if (day !== firstDay)
+            counted += dayEntries.length;
+    }
+    const kept = entries.filter((e) => e.at < cut);
+    kept.sort((a, b) => a.at - b.at || cmp(a.taskId, b.taskId) || cmp(entryKey(a), entryKey(b)));
+    const items = [];
+    const collapsed = [];
+    const named = new Set();
+    for (const e of kept) {
+        named.add(e.taskId);
+        if (e.kind === "item")
+            items.push(e.item);
+        else
+            collapsed.push(e.collapsed);
+    }
+    return {
+        tasks: input.tasks.filter((t) => named.has(t.id)).map(calendarTask),
+        items,
+        collapsed,
+        horizon: new Date(Math.max(fromMs, truncated ? Math.min(cut, horizonAt) : horizonAt)).toISOString(),
+        truncated,
+    };
+}
+/** The stream's next tick, or null when it has no more (or its trigger cannot be evaluated). */
+function pull(s) {
+    if (s.after >= s.until)
+        return null;
+    try {
+        const tick = ticksIn(s.ticker, new Date(s.after), new Date(s.until), 1).ticks[0];
+        s.after = tick === undefined ? Number.POSITIVE_INFINITY : tick.getTime();
+        return tick === undefined ? null : s.after;
+    }
+    catch {
+        // a trigger the math cannot evaluate: the scanner pauses the task; nothing to plan
+        s.after = Number.POSITIVE_INFINITY;
+        return null;
+    }
+}
+/**
+ * Each active task's planned ticks in `[from, min(to, horizon, expires_at)]` (spec §5.2), from the
+ * scanner's own math: a task already due (`next_run_at <= now`, not scanned yet) keeps only the
+ * tick the scan will fire (the latest due one inside the catch-up window; the older ones become
+ * one `missed` run), then the ticks after it as the scan continues; a task not due starts at its
+ * due tick, `next_run_at - jitter`.
+ *
+ * The tasks' ticks are taken in time order across all tasks (a merge), each one tick evaluation
+ * on the task's ticker (built once). Ticks of the first local day count against the first day's
+ * safety cap only (past it, nothing is returned: the cut moves to `from`); the first later tick
+ * past the budget cuts the range at the start of its local day, and the ticks already taken on
+ * that day are dropped, so the days before the cut are whole (spec §5.5). The counts are ticks
+ * taken: each stream's lookahead past its `until` and `scanStep`'s doubling search for a task
+ * already due are not counted (at most about 2 × tasks evaluations more).
+ */
+function planOccurrences(input, horizonAt, limits, firstDayEnd, end) {
+    const fromMs = input.from.getTime();
+    const ticks = new Map();
+    const heap = new TickHeap();
+    for (const task of input.tasks) {
+        if (task.status !== "active" || task.nextRunAt === null)
+            continue;
+        const jitterMs = task.jitterSeconds * 1000;
+        const until = Math.min(end - 1, horizonAt, task.expiresAt?.getTime() ?? Number.POSITIVE_INFINITY);
+        if (until < fromMs)
+            continue;
+        let after = task.nextRunAt.getTime() - jitterMs - 1;
+        let first = null;
+        if (task.nextRunAt.getTime() <= input.now.getTime()) {
+            let step;
+            try {
+                step = scanStep({
+                    trigger: task.trigger,
+                    nextRunAt: task.nextRunAt,
+                    jitterSeconds: task.jitterSeconds,
+                    expiresAt: task.expiresAt,
+                }, input.now, input.catchUpWindowMinutes);
+            }
+            catch {
+                continue;
+            }
+            const fire = step.fire?.getTime();
+            if (fire !== undefined && fire >= fromMs && fire <= until)
+                first = fire;
+            after =
+                step.nextRunAt === null
+                    ? Number.POSITIVE_INFINITY
+                    : step.nextRunAt.getTime() - jitterMs - 1;
+        }
+        let ticker;
+        try {
+            ticker = tickerOf(task.trigger);
+        }
+        catch {
+            continue;
+        }
+        const stream = { task, ticker, until, after: Math.max(after, fromMs - 1) };
+        const head = first ?? pull(stream);
+        if (head === null)
+            continue;
+        ticks.set(task.id, []);
+        heap.push({ at: head, stream });
+    }
+    let cut = end;
+    // the first local day has its own safety cap; the budget counts the days after it
+    let used = 0;
+    let firstDayUsed = 0;
+    for (let top = heap.pop(); top !== undefined; top = heap.pop()) {
+        if (top.at < firstDayEnd) {
+            if (firstDayUsed >= limits.firstDayTickCap) {
+                cut = fromMs;
+                break;
+            }
+            firstDayUsed++;
+        }
+        else {
+            if (used >= limits.tickBudget) {
+                cut = startOfLocalDay(top.at, input.timeZone);
+                break;
+            }
+            used++;
+        }
+        ticks.get(top.stream.task.id)?.push(top.at);
+        const next = pull(top.stream);
+        if (next !== null)
+            heap.push({ at: next, stream: top.stream });
+    }
+    if (cut < end) {
+        for (const [id, list] of ticks)
+            ticks.set(id, list.filter((t) => t < cut));
+    }
+    return { ticks, cut };
+}
+/** A binary min-heap of stream heads by tick, then task id (a stable order). */
+class TickHeap {
+    a = [];
+    less(i, j) {
+        const x = this.a[i];
+        const y = this.a[j];
+        return x.at < y.at || (x.at === y.at && x.stream.task.id < y.stream.task.id);
+    }
+    swap(i, j) {
+        const t = this.a[i];
+        this.a[i] = this.a[j];
+        this.a[j] = t;
+    }
+    push(e) {
+        this.a.push(e);
+        for (let i = this.a.length - 1; i > 0;) {
+            const p = (i - 1) >> 1;
+            if (!this.less(i, p))
+                break;
+            this.swap(i, p);
+            i = p;
+        }
+    }
+    pop() {
+        const top = this.a[0];
+        const last = this.a.pop();
+        if (top === undefined || last === undefined || this.a.length === 0)
+            return top;
+        this.a[0] = last;
+        for (let i = 0;;) {
+            const l = 2 * i + 1;
+            const r = l + 1;
+            let m = i;
+            if (l < this.a.length && this.less(l, m))
+                m = l;
+            if (r < this.a.length && this.less(r, m))
+                m = r;
+            if (m === i)
+                break;
+            this.swap(i, m);
+            i = m;
+        }
+        return top;
+    }
+}
+function runItem(r, own) {
+    return {
+        kind: "run",
+        taskId: r.taskId,
+        id: r.id,
+        scheduledFor: r.scheduledFor.toISOString(),
+        firedAt: r.firedAt?.toISOString() ?? null,
+        status: r.status,
+        skipReason: r.skipReason,
+        trial: r.trial,
+        manual: r.manual,
+        conversationId: own ? r.conversationId : null,
+        error: own ? r.error : null,
+        missingGrants: own ? r.missingGrants.length : null,
+    };
+}
+function summarize(taskId, day, list) {
+    const c = {
+        taskId,
+        day,
+        count: list.length,
+        upcoming: 0,
+        running: 0,
+        completed: 0,
+        failed: 0,
+        skipped: 0,
+        first: new Date(firstAt(list)).toISOString(),
+        last: new Date(Math.max(...list.map((e) => e.at))).toISOString(),
+    };
+    for (const { item } of list) {
+        if (item.kind === "occurrence")
+            c.upcoming++;
+        else if (item.status === "pending" || item.status === "running")
+            c.running++;
+        else
+            c[item.status]++;
+    }
+    return c;
+}
+function calendarTask(t) {
+    return {
+        id: t.id,
+        name: t.name,
+        agentId: t.agentId,
+        accountId: t.accountId,
+        status: t.status,
+        pauseReason: t.pauseReason,
+        trigger: t.trigger,
+        mode: t.mode,
+        jitterSeconds: t.jitterSeconds,
+        nextRunAt: t.nextRunAt?.toISOString() ?? null,
+    };
+}
+const firstAt = (list) => Math.min(...list.map((e) => e.at));
+const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+const entryKey = (e) => e.kind === "collapsed" ? "~" : e.item.kind === "run" ? `r${e.item.id}` : "o";
+const dayFormats = new Map();
+/** YYYY-MM-DD of the instant (epoch ms) in `timeZone`. */
+export function dayKey(ms, timeZone) {
+    let f = dayFormats.get(timeZone);
+    if (!f) {
+        f = new Intl.DateTimeFormat("en-CA", {
+            timeZone,
+            year: "numeric",
+            month: "2-digit",
+            day: "2-digit",
+        });
+        dayFormats.set(timeZone, f);
+    }
+    const p = Object.fromEntries(f.formatToParts(new Date(ms)).map((x) => [x.type, x.value]));
+    return `${p.year}-${p.month}-${p.day}`;
+}
+/**
+ * The first instant (epoch ms) of the local day of `ms` in `timeZone`: midnight, or the end of a
+ * DST gap that swallows it. A day is at most 25 hours long, so 27 hours back is an earlier day.
+ */
+export function startOfLocalDay(ms, timeZone) {
+    const day = dayKey(ms, timeZone);
+    let lo = ms - 27 * 3_600_000;
+    let hi = ms;
+    while (lo < hi) {
+        const mid = Math.floor((lo + hi) / 2);
+        if (dayKey(mid, timeZone) < day)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo;
+}

package/dist/schedules/fire.d.ts

@@ -7,9 +7,10 @@ import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { LockService } from "../infra/lock/lock.service.js";
+import { OutboxService } from "../infra/outbox/outbox.service.js";
 import type { KernelLogger } from "../log.js";
 import { OrgLock } from "../orgs/org-lock.js";
-import { RunControl } from "../runtime/run-control.js";
+import { type SchedSettleJobData } from "./job-ids.js";
 import { ScheduledTaskRunTracker } from "./run-tracker.js";
 import { ScheduledTaskStore } from "./store.js";
 /** A task run's message client id in a conversation's queue (never read back as "the task's"). */
@@ -22,10 +23,12 @@ export declare function localTimeOf(at: Date, timeZone: string): string;
  *
  * 1. The claim, one transaction under the org row lock (which serializes the org's rate limit
  *    count), then the task run and the task rows: the checks in order (task paused since the
- *    scan, unless a person's "run now"; org disabled, creator
- *    inactive or not a member, agent gone or not visible, conversation gone, connection inactive,
+ *    scan, unless a person's "run now"; a tick fired more than 10 minutes past the org's catch-up
+ *    window, `missed`, unless a "run now"; org disabled, creator inactive or not a member, agent
+ *    gone or not visible, conversation gone, connection inactive,
  *    overlap, rate limit, device offline, queue paused), each a `skipped` run with its reason, the
- *    lasting ones also pausing the task; then `fired_at` is written, after the rate limit count.
+ *    lasting ones also pausing the task; then `fired_at` is written, after the rate limit count,
+ *    with the run's delayed settle check owed (`sched-settle`, {@link settle}).
  *    A run whose claim committed before (a retried job) goes straight to the start.
  * 2. The start, idempotent: `new` creates the conversation with its first message keyed by the
  *    task run id (`create_request_id`); `conversation` queues the prompt in the target
@@ -49,16 +52,32 @@ export declare class ScheduledTaskFirer {
     private readonly conversations;
     private readonly queue;
     private readonly connections;
-    private readonly runs;
     /** Reads a local device's connection lease (online or not). */
     private readonly locks;
     private readonly log;
-    constructor(kdb: KernelDb, txHost: TransactionHost, config: Pick<KernelConfigService, "get">, store: ScheduledTaskStore, tracker: Pick<ScheduledTaskRunTracker, "inFlightIn" | "failStartIn">, orgLock: Pick<OrgLock, "tryLock">, agents: Pick<AgentLookup, "get">, access: Pick<ConversationAccess, "isAccessible">, conversations: Pick<ConversationsService, "createWithMessage" | "create">, queue: Pick<ConversationQueue, "add">, connections: Pick<ChannelConnections, "row" | "channel">, runs: Pick<RunControl, "ensureRun">, 
+    /** The claim owes the run's settle check (ruling R26). */
+    private readonly outbox;
+    constructor(kdb: KernelDb, txHost: TransactionHost, config: Pick<KernelConfigService, "get">, store: ScheduledTaskStore, tracker: Pick<ScheduledTaskRunTracker, "inFlightIn" | "failStartIn">, orgLock: Pick<OrgLock, "tryLock">, agents: Pick<AgentLookup, "get">, access: Pick<ConversationAccess, "isAccessible">, conversations: Pick<ConversationsService, "createWithMessage" | "create">, queue: Pick<ConversationQueue, "add">, connections: Pick<ChannelConnections, "row" | "channel">, 
     /** Reads a local device's connection lease (online or not). */
-    locks: Pick<LockService, "holderOf">, log: Pick<KernelLogger, "warn" | "info">);
+    locks: Pick<LockService, "holderOf">, log: Pick<KernelLogger, "warn" | "info">, 
+    /** The claim owes the run's settle check (ruling R26). */
+    outbox: Pick<OutboxService, "add">);
     private get db();
     /** Fires task run `taskRunId` (see the class); a run not `pending` is left as it is. */
     fire(taskRunId: string): Promise<void>;
+    /**
+     * The `sched-settle` job (ruling R26; `job-ids.ts`). The claimed check: a task run claimed
+     * (`fired_at`) and still `pending` goes through the run tracker's check, which links it to its
+     * run, settles it, or releases a run that left no trace (`skipped`, `removed`), so a `once`
+     * task's last run never stays pending; one still in flight (its item queued, its message posted)
+     * owes the next check an hour on. The unfired check: a run still `pending` that no claim took
+     * (its fire job failed for good before the claim) is skipped, `missed` for a tick, `removed` for
+     * a "run now", so the overlap check never waits on it. A run claimed, started, ended or skipped
+     * since is left as it is (the claimed check follows a claimed run).
+     */
+    settle(data: SchedSettleJobData): Promise<void>;
+    /** The unfired check (see {@link settle}), task row first (the one lock order). */
+    private settleUnfired;
     /** Step 1 (see the class): a skip, the plan, or null when there is nothing to fire. */
     private claim;
     /** Step 2 (see the class). */