@sigrun/ext-curator 0.0.0-stage → 0.2.0

package/dist/loop1.js

@@ -0,0 +1,262 @@
+/**
+ * Loop 1 — the post-run fork review (`src/loop1.ts`, Task B2, spec
+ * §6.2).
+ *
+ * `onRunSettled` DECIDES and ENQUEUES, then returns: runSettled
+ * handlers are abandoned at `SIGRUN_HOOK_DEADLINE` (30 s), so the
+ * review body NEVER runs on the handler's stack — it runs through the
+ * per-user `ReviewQueue`.
+ *
+ * The decision tree (the brief, verbatim authority):
+ *
+ * 1. owner present, settings enabled and not paused, not backed off —
+ *    else return (the hints are left pending, never consumed by a
+ *    review that will not run);
+ * 2. an internal conversation returns (the bus already withholds
+ *    internal settles; this read-side gate is the belt);
+ * 3. `eligibility.ownerOnly && unattributed === 0` → the fork path:
+ *    take the hints (read-and-clear) merged with any refunded batch
+ *    (`pending-hints.json` — hints a previous review consumed but
+ *    never reviewed), count `modelCallsSince(id, lastReviewedEntry)`,
+ *    and review when hints are pending (answered or not — an aborted
+ *    run's hints stay pending until the next settle) or the run
+ *    answered at/over the threshold;
+ * 4. anything else (mixed authorship, unattributed entries) → the
+ *    threshold trigger alone queues a `queueDigest` entry: never
+ *    forked, handed to loop 2 (Task B4). (Hints ride in that durable
+ *    entry — taken read-and-clear and folded into the digest run's
+ *    instruction by Task B4 — and the refund file drains into it, so
+ *    no hint can wait on both.)
+ *
+ * The review itself: the allow-list is `skill_manage` + the served
+ * targets' tools + `read` when the parent's selection carries it; the
+ * bounds are the spec's (8 tool calls, 2048 output tokens, 2 minutes);
+ * a watch on the parent aborts the run's signal the moment the parent
+ * moves. Success anchors the per-conversation cursor
+ * (`cursors.json`) at the eligibility snapshot's newest entry; a
+ * failed run steps that user's backoff ladder; any NON-completed
+ * outcome (failed, cancelled, deadline — or a thrown review) refunds
+ * its hints to `pending-hints.json`, so a consumed-but-unreviewed
+ * hint survives until some review completes with it in hand.
+ */
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { notify } from "./notices.js";
+import { enqueueLearn } from "./learn.js";
+import { reviewInstruction } from "./prompts.js";
+import { clearPendingHints, mergeHints, pendingHintsFor, queueDigest, readStateJson, refundHints, writeStateJson, } from "./queue.js";
+import { readSettings } from "./settings.js";
+/** The per-conversation cursor file under the user's state dir. */
+export const CURSORS_FILE = "cursors.json";
+/** The fork-review bounds (spec §6.2: a handful of calls, small output, ~2 minutes). */
+export const LOOP1_MAX_TOOL_CALLS = 8;
+export const LOOP1_MAX_OUTPUT_TOKENS = 2048;
+export const LOOP1_DEADLINE_MS = 120_000;
+/**
+ * Create loop 1: the `runSettled` handler the factory wires, and the
+ * `learnNow` seam `/learn` runs the same review path through. The
+ * handler owns only the decision; the queue owns the review.
+ */
+export function createLoop1(deps) {
+    const now = deps.now ?? (() => new Date());
+    const log = deps.log ?? ((message) => console.error(`curator: ${message}`));
+    const onRunSettled = async (event) => {
+        const owner = event.owner;
+        if (owner === undefined)
+            return;
+        const id = event.conversationId;
+        const settings = await readSettings(deps.host, owner);
+        if (!settings.enabled || settings.paused)
+            return;
+        if (deps.backoff.blocked(owner, now()))
+            return;
+        const eligibility = await deps.host.curation.eligibility(id);
+        if (eligibility.internal)
+            return;
+        if (eligibility.ownerOnly && eligibility.unattributed === 0) {
+            await enqueueForkReview(owner, id, event, eligibility.newestEntry, settings.threshold);
+        }
+        else {
+            // Mixed authorship: never forked, whatever triggered us — loop
+            // 2's digest step (Task B4) reviews only the owner's turns.
+            // The same trigger gates both routes: hints (taken read-and-clear,
+            // merged into the queued entry so the digest run folds them in)
+            // or an answered run at/over the threshold (the cursor never
+            // advances on this branch, so that is "ever" — what a backlog
+            // wants).
+            const hints = mergeHints(await pendingHintsFor(deps.host, owner, id), await deps.host.curation.takeHints(id));
+            if (hints.length === 0) {
+                if (event.outcome.status !== "answered")
+                    return;
+                const cursors = await readCursors(deps.host, owner);
+                const calls = await deps.host.curation.modelCallsSince(id, cursors.lastReviewedEntry[String(id)]);
+                if (calls < settings.threshold)
+                    return;
+            }
+            await queueDigest(deps.host, owner, id, hints);
+            // The digest entry is durable and owns these ids now — drain the
+            // refund file so a later owner-only settle cannot re-fire them.
+            // After the write, never before: a crash in between duplicates a
+            // hint into two durable places (queueDigest dedups by id), it
+            // never drops one.
+            await clearPendingHints(deps.host, owner, id, hints);
+        }
+    };
+    /**
+     * Trigger evaluation for one owner-only conversation: hints always
+     * fire; otherwise the run must have answered at/over the threshold.
+     */
+    async function enqueueForkReview(owner, id, event, newestEntry, threshold) {
+        // Hints first (read-and-clear), merged with anything a previous
+        // non-completed review refunded for this conversation (dedup by
+        // hint id): a hint stays pending across failures until some
+        // review actually completes with it in hand. When the merged set
+        // is empty, only the threshold can fire and nothing was consumed.
+        const hints = mergeHints(await pendingHintsFor(deps.host, owner, id), await deps.host.curation.takeHints(id));
+        if (hints.length === 0) {
+            if (event.outcome.status !== "answered")
+                return;
+            const cursors = await readCursors(deps.host, owner);
+            const calls = await deps.host.curation.modelCallsSince(id, cursors.lastReviewedEntry[String(id)]);
+            if (calls < threshold)
+                return;
+        }
+        deps.queue.enqueue({
+            user: owner,
+            work: () => runForkReview(owner, id, hints, newestEntry, undefined, `review-${randomUUID()}`).catch((error) => {
+                log(`loop 1: review of conversation ${String(id)} failed: ${error instanceof Error ? error.message : String(error)}`);
+            }),
+        });
+    }
+    /** The review body (queue-owned; never on the handler's stack). */
+    async function runForkReview(owner, id, hints, newestEntry, focus, reviewId) {
+        try {
+            await reviewBody(owner, id, hints, newestEntry, focus, reviewId);
+        }
+        catch (error) {
+            // The body threw before any outcome was recorded (a host read,
+            // the watch, the run itself): the hints were no more consumed
+            // than the run was — refund them, then let the queue's logger
+            // have the error. A refund that itself fails must not mask the
+            // original error.
+            await refundHints(deps.host, owner, id, hints).catch(() => undefined);
+            throw error;
+        }
+    }
+    /** The review proper, factored out of {@link runForkReview}'s refund guard. */
+    async function reviewBody(owner, id, hints, newestEntry, focus, reviewId) {
+        const targets = await deps.host.curation.targets(owner, id);
+        const selection = await deps.host.curation.tools(id);
+        const allow = [
+            ...new Set([
+                "skill_manage",
+                ...targets.flatMap((target) => [...target.tools]),
+                ...(selection.includes("read") ? ["read"] : []),
+            ]),
+        ];
+        const instruction = reviewInstruction({
+            hints,
+            targets: targets.map((target) => ({
+                id: target.id,
+                guidance: [...target.guidance],
+            })),
+            allow,
+            ...(focus === undefined ? {} : { focus }),
+        });
+        // The parent abort: CHURN on the parent while the review runs
+        // fires the signal — the review reviews the conversation it saw
+        // (the host-side driver re-checks the same state itself). The
+        // watch's first frame is the acquisition snapshot (the baseline),
+        // never churn; only a frame carrying MORE model entries than the
+        // baseline means the parent actually moved. A re-rendered view
+        // (a status refresh at the same entry count) is not churn and
+        // must not kill an in-flight review (the coarse-abort ruling).
+        const abort = new AbortController();
+        let baseline;
+        const stopWatch = await deps.host.conversations.watch(id, (view) => {
+            const count = view.entries.length;
+            if (baseline === undefined) {
+                baseline = count; // the snapshot is the baseline, never churn
+                return;
+            }
+            if (count > baseline)
+                abort.abort();
+        });
+        let result;
+        try {
+            result = await deps.host.curation.forkReview(id, {
+                instruction,
+                allow,
+                maxToolCalls: LOOP1_MAX_TOOL_CALLS,
+                maxOutputTokens: LOOP1_MAX_OUTPUT_TOKENS,
+                deadlineMs: LOOP1_DEADLINE_MS,
+                reviewId,
+                signal: abort.signal,
+            });
+        }
+        finally {
+            await stopWatch();
+        }
+        if (result.status === "completed") {
+            deps.backoff.success(owner);
+            // Anchor the next count at what this review covered. An absent
+            // newestEntry cannot anchor anything — the next review counts
+            // everything, an extra review at worst.
+            if (newestEntry !== undefined) {
+                await writeCursor(deps.host, owner, id, newestEntry);
+            }
+            // The review consumed these hints for good — clear their
+            // refunded ids so a later settle cannot re-fire on them.
+            await clearPendingHints(deps.host, owner, id, hints);
+            // Task B5: announce the changes (no changes → no notice). The
+            // notice is isolated: a failing setAmbient or ledger write
+            // degrades to a missing notice — never a thrown body, which the
+            // refund guard would answer with a phantom refund of an
+            // already-applied review (re-reviewing learned material).
+            await notify(deps.host, id, owner, { ...result, reviewId }).catch((error) => {
+                log(`loop 1: notice after the review of conversation ${String(id)} could not be set: ${error instanceof Error ? error.message : String(error)}`);
+            });
+        }
+        else {
+            if (result.status === "failed")
+                deps.backoff.failure(owner, now());
+            // No review happened for these hints (provider failure, the
+            // parent moving, or the deadline): refund them — the host was
+            // cleared at decision time, so the refund file is the only
+            // place they survive; the next settle merges them back in.
+            await refundHints(deps.host, owner, id, hints);
+        }
+    }
+    /** `/learn`'s seam (Task B5): the same review path minus the
+     *  threshold gate — eligibility still decides, and a mixed
+     *  conversation goes to the digest queue with the mixed-conversation
+     *  notice. The paused/enabled gates deliberately do NOT apply: the
+     *  vacation switch stops the loops, not the user's explicit ask. */
+    const learnNow = (conversationId, user, focus) => enqueueLearn(deps.host, deps.queue, conversationId, user, focus, (owner, id, hints, newestEntry, reviewFocus) => runForkReview(owner, id, hints, newestEntry, reviewFocus, `learn-${randomUUID()}`).catch((error) => {
+        log(`loop 1: /learn review of conversation ${String(id)} failed: ${error instanceof Error ? error.message : String(error)}`);
+    }));
+    return { onRunSettled, learnNow };
+}
+/** Read the per-user cursors file (absent or malformed → empty). */
+async function readCursors(host, user) {
+    const raw = await readStateJson(join(host.stores.user(user).paths.state, CURSORS_FILE), { lastReviewedEntry: {} });
+    // Harden the shape before anyone writes through it: only a plain
+    // object of conversation-id keys → integer entries is a cursor map.
+    const entries = raw?.lastReviewedEntry;
+    if (entries === null || typeof entries !== "object" || Array.isArray(entries)) {
+        return { lastReviewedEntry: {} };
+    }
+    const lastReviewedEntry = {};
+    for (const [key, value] of Object.entries(entries)) {
+        if (typeof value === "number" && Number.isInteger(value)) {
+            lastReviewedEntry[key] = value;
+        }
+    }
+    return { lastReviewedEntry };
+}
+/** Write one conversation's anchor into the cursors file. */
+async function writeCursor(host, user, id, entry) {
+    const cursors = await readCursors(host, user);
+    cursors.lastReviewedEntry[String(id)] = entry;
+    await writeStateJson(host.stores.user(user).paths.state, CURSORS_FILE, cursors);
+}

package/dist/loop2.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Loop 2 — the scheduled idle maintenance pass (`src/loop2.ts`, Task
+ * B3, spec §6.2).
+ *
+ * Clocked by the `curator-tick` job (the only time-based scheduler);
+ * each fired task runs {@link tick} once, and a tick does AT MOST one
+ * pass-fragment: every user's pass is a small resumable queue of
+ * steps with a durable cursor (`pass.json` under the user's state
+ * dir), so a tick interrupted at its self-imposed 5-minute deadline
+ * leaves the cursor pointing at the next step and the NEXT tick
+ * resumes exactly there. Nothing depends on finishing in one go.
+ *
+ * The eligibility gate ({@link eligibleUsers}, spec): a user is due
+ * when they are QUIET — the newest `lastActivityAt` across their
+ * conversations is older than the idle threshold. "No live run" rides
+ * the same clock: activity is stamped at submission admission AND at
+ * run settlement (core's activity seam), so a user with a live run is
+ * never past the idle threshold — the recency check observes it. A
+ * user with no activity at all (never used, or quiet since before the
+ * seam existed) is quiet too. Plus: settings enabled and not paused,
+ * no full pass in the last 24h, and past the install's first-run
+ * grace (the FIRST tick instant + 24h, recorded once in the
+ * extension's own state — the grace is install-wide, per spec: "no
+ * pass until one full interval after install").
+ *
+ * The cursor (`PassCursor`): `steps` is the pass's queue, `done` how
+ * many steps finished (persisted after EVERY step — that is the
+ * resume point), `dailyRunsUsed`/`day` the per-user model-run budget
+ * Task B4's model steps spend (a calendar day rollover re-arms it).
+ *
+ * The step table: B3 owns the two deterministic steps (`archive`,
+ * `overlay-detect`); the five model steps are declared in the queue
+ * and run as no-ops here — Task B4 fills them in.
+ */
+import type { SigrunHost } from "@sigrun/sigrun/extension";
+/**
+ * The idle threshold (spec §5 pins SIGRUN_IDLE_THRESHOLD's default at
+ * 10 minutes; the extension reads the semantics, not the env — the
+ * host's activity seam already carries it).
+ */
+export declare const IDLE_THRESHOLD_MS = 600000;
+/**
+ * The tick's self-imposed deadline: 5 minutes, well under the worker/
+ * job deadline, so a pass fragment always outlives its own tick.
+ */
+export declare const LOOP2_TICK_DEADLINE_MS = 300000;
+/** The first-run grace: no pass until 24h after the first tick ever. */
+export declare const FIRST_RUN_GRACE_MS: number;
+/** How long a completed pass keeps its user ineligible. */
+export declare const FULL_PASS_INTERVAL_MS: number;
+/** The per-user pass-cursor file name (under the user's state dir). */
+export declare const PASS_FILE = "pass.json";
+/**
+ * The extension-scope state file holding the install-wide first-tick
+ * instant (the grace anchor). Chosen name; recorded here as the seam.
+ */
+export declare const FIRST_TICK_FILE = "loop2-first-tick.json";
+/** One pass's step kinds, in run order (deterministic steps first). */
+export declare const PASS_STEPS: readonly ["archive", "overlay-detect", "overlay-recheck", "digests", "diet", "merge", "targets"];
+/** A pass step's kind (the cursor's queue entries). */
+export type StepId = (typeof PASS_STEPS)[number];
+/** The durable per-user pass cursor (the resume point). */
+export interface PassCursor {
+    /** When this pass started (ISO); the 24h window anchors here. */
+    readonly startedAt: string;
+    /** The step queue, in run order. */
+    readonly steps: readonly StepId[];
+    /** How many steps have finished — the next tick resumes at `steps[done]`. */
+    readonly done: number;
+    /** Model runs spent today (Task B4 decrements the budget). */
+    readonly dailyRunsUsed: number;
+    /** The UTC day the budget counts against (`YYYY-MM-DD`). */
+    readonly day: string;
+}
+/** What {@link tick} accepts (all optional). */
+export interface TickOptions {
+    /** One line per unexpected error; defaults to `console.error`. */
+    readonly log?: (message: string) => void;
+}
+/**
+ * The users due for a pass (spec §6.2): quiet, settings on, past the
+ * first-run grace, and without a completed pass in the last 24h. An
+ * INCOMPLETE pass does not block — the next tick resumes it.
+ */
+export declare function eligibleUsers(host: SigrunHost, now: () => Date): Promise<readonly string[]>;
+/** What {@link createLoop2} needs (all but `host` are optional). */
+export interface Loop2Deps {
+    /** The host the pass reads. */
+    readonly host: SigrunHost;
+    /** The clock every gate and step reads (tests fake it). */
+    readonly now?: () => Date;
+    /** One line per unexpected error; defaults to `console.error`. */
+    readonly log?: (message: string) => void;
+}
+/**
+ * Create loop 2: the tick the factory's task calls (a thin binding of
+ * {@link tick} to its deps). The durable cadence stays the job's —
+ * this creates no timers.
+ */
+export declare function createLoop2(deps: Loop2Deps): {
+    readonly tick: () => Promise<void>;
+};
+/**
+ * One tick: as many pass fragments as fit before the 5-minute
+ * self-deadline. Per-user failures are logged and never break the
+ * tick — the cursor makes every user resumable.
+ */
+export declare function tick(host: SigrunHost, now: () => Date, opts?: TickOptions): Promise<void>;