@avocadostudio-ai/orchestrator-core 0.3.2 → 0.4.0

package/dist/durable/pending-plan-store.js

@@ -0,0 +1,156 @@
+import { pendingApprovalPlanBySession } from "../state/session-state.js";
+import { getDurableStore, isDiscardInFlight, noteDurableFailure } from "./durable-store-singleton.js";
+/*
+ * Write-through durability for the pending approval plan.
+ *
+ * `pendingApprovalPlanBySession` stays the hot path — a Map read is what the
+ * chat pipeline wants and there is no reason to make it a query. What changes is
+ * that the Map is no longer the only copy: every plan is mirrored into the
+ * `proposals` table, and a read that misses rehydrates from there.
+ *
+ * The case this exists for is not a crash. It is the ordinary one: an agent
+ * runs at 03:00, produces a plan, and the process that produced it is gone long
+ * before anyone looks. Today that plan is in a Map that was never persisted and
+ * is evicted by age, so the morning's "approve" finds nothing and silently
+ * re-plans from the original message — at best spending tokens to reproduce
+ * work, at worst producing a different plan than the one that was reviewed.
+ *
+ * Every durable write here is best-effort. If the store is unavailable the chat
+ * path must behave exactly as it did before this module existed: in-memory, and
+ * honest about it through `durableHealth()`. A findings feature is not permitted
+ * to take chat down with it.
+ */
+/*
+ * Two different TTLs, because they answer two different questions.
+ *
+ * The Map's hour (`APPROVAL_PLAN_TTL_MS` in session-state) is "how long do we
+ * keep an abandoned approval warm in this process" — a memory-pressure answer.
+ * Reusing it for the durable row would defeat the entire point of the row: the
+ * agent that ran at 03:00 and the person who approves at 09:00 are six hours
+ * apart, so an hour-old row is expired before anybody could possibly have seen
+ * it, and `loadPendingPlan` falls straight back to the silent re-plan this
+ * module exists to prevent.
+ *
+ * A durable proposal is kept for a working week. The Map still forgets it after
+ * an hour; the next read rehydrates.
+ */
+const DURABLE_PLAN_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * Marks the proposals this module owns.
+ *
+ * `proposals` is shared with agent-authored plans by design. "The newest
+ * pending row for this session" is therefore the wrong question — once a
+ * checker writes one, it would shadow a genuinely pending chat plan behind it,
+ * and `clearPendingPlan` would resolve somebody else's proposal as approved.
+ */
+const CHAT_ORIGIN_PREFIX = "chat:";
+function createdAtMs(plan) {
+    const parsed = Date.parse(plan.createdAt);
+    return Number.isFinite(parsed) ? parsed : Date.now();
+}
+function noteFailure(err, what) {
+    noteDurableFailure(`${what}: ${err instanceof Error ? err.message : String(err)}`);
+}
+function isChatProposal(record) {
+    return record.origin.startsWith(CHAT_ORIGIN_PREFIX);
+}
+async function findChatProposal(session) {
+    const rows = await getDurableStore().listProposals({ scopeKey: session, status: "pending" });
+    return rows.find(isChatProposal);
+}
+/**
+ * Map-only read. For call sites that only need to know whether a plan is live
+ * in this process and must not pay for a query.
+ */
+export function peekPendingPlan(session) {
+    return pendingApprovalPlanBySession.get(session);
+}
+/**
+ * Read the pending plan, rehydrating from the durable store on a Map miss.
+ *
+ * An expired row is treated as absent rather than deleted: eviction is the
+ * sweeper's job, and a read is not the place to discover that a plan the user
+ * is looking at right now has just aged out mid-request.
+ */
+export async function loadPendingPlan(session) {
+    const live = pendingApprovalPlanBySession.get(session);
+    if (live)
+        return live;
+    if (isDiscardInFlight(session))
+        return undefined;
+    try {
+        const record = await findChatProposal(session);
+        if (!record?.payload)
+            return undefined;
+        if (record.expiresAt != null && record.expiresAt <= Date.now())
+            return undefined;
+        const plan = record.payload;
+        // A payload that cannot be executed is worse than none: the approval path
+        // would hand a malformed plan to the ops engine on the user's click.
+        if (!plan?.id || !plan.plan || !Array.isArray(plan.plan.ops))
+            return undefined;
+        pendingApprovalPlanBySession.set(session, plan);
+        return plan;
+    }
+    catch (err) {
+        noteFailure(err, "read pending plan");
+        return undefined;
+    }
+}
+/** Set the plan in memory and mirror it to the durable store. */
+export async function savePendingPlan(session, plan) {
+    pendingApprovalPlanBySession.set(session, plan);
+    const createdAt = createdAtMs(plan);
+    try {
+        await getDurableStore().putProposal({
+            id: plan.id,
+            scopeKey: session,
+            origin: `${CHAT_ORIGIN_PREFIX}${plan.source}`,
+            summary: plan.summary,
+            ops: plan.plan.ops,
+            slugs: plan.effectiveSlug ? [plan.effectiveSlug] : [],
+            payload: plan,
+            createdAt,
+            expiresAt: createdAt + DURABLE_PLAN_TTL_MS
+        });
+    }
+    catch (err) {
+        noteFailure(err, "save pending plan");
+    }
+}
+/**
+ * Drop the plan from memory and resolve its durable row.
+ *
+ * `outcome` is recorded rather than deleted, so "how often does a human discard
+ * what we proposed" stays answerable — which is the same signal the corrections
+ * table is for, and the reason `expectedId` matters. A turn that applies
+ * something unrelated must not record a held plan as `approved`: it was never
+ * reviewed, and writing that down poisons the one number this is here to make
+ * available. Pass the id of the plan actually acted on; omit it only where the
+ * intent really is "whatever chat plan is pending, it is over".
+ */
+export async function clearPendingPlan(session, outcome, expectedId) {
+    const plan = pendingApprovalPlanBySession.get(session);
+    if (expectedId && plan && plan.id !== expectedId) {
+        // The live plan is not the one being resolved — leave both alone.
+        return;
+    }
+    pendingApprovalPlanBySession.delete(session);
+    try {
+        const store = getDurableStore();
+        const id = expectedId ?? plan?.id;
+        if (id) {
+            const record = await store.getProposal(id);
+            if (record && isChatProposal(record))
+                await store.setProposalStatus(id, outcome);
+            return;
+        }
+        // No live plan: a durable row may still be pending from a previous process.
+        const record = await findChatProposal(session);
+        if (record)
+            await store.setProposalStatus(record.id, outcome);
+    }
+    catch (err) {
+        noteFailure(err, "clear pending plan");
+    }
+}

package/dist/durable/sqlite-durable-store.d.ts

@@ -0,0 +1,71 @@
+import type { Database as BetterSqliteDatabase } from "better-sqlite3";
+import type { CheckRunInput, CheckRunPatch, CheckRunRecord, CorrectionInput, CorrectionQuery, CorrectionRecord, DurableStore, FindingInput, FindingQuery, FindingRecord, FindingStatus, MemoryInput, MemoryQuery, MemoryRecord, MemoryStatus, ProposalInput, ProposalQuery, ProposalRecord, ProposalStatus } from "./types.ts";
+export declare const PROPOSAL_CAP = 200;
+export declare const CORRECTION_CAP = 500;
+export declare const CHECK_RUN_CAP = 200;
+/**
+ * How long a snooze lasts.
+ *
+ * Seven days, because the button competes with Dismiss and has to mean
+ * something different from it: long enough to clear a finding out of the way
+ * for the week somebody is shipping a campaign, short enough that "I'll get to
+ * it" does not quietly become "never". Exported so both implementations, and
+ * the tests that hold them to the same behaviour, derive it from one number.
+ */
+export declare const SNOOZE_WINDOW_MS: number;
+export type SqliteDurableStoreOptions = {
+    /** Injectable clock, so tests can assert on ordering without sleeping. */
+    now?: () => number;
+};
+export declare class SqliteDurableStore implements DurableStore {
+    private readonly db;
+    private readonly now;
+    constructor(db: BetterSqliteDatabase, options?: SqliteDurableStoreOptions);
+    private ensureColumns;
+    private trim;
+    recordFindings(runId: string, findings: FindingInput[]): Promise<{
+        opened: number;
+        updated: number;
+    }>;
+    reconcileFindings(args: {
+        runId: string;
+        scopeKey: string;
+        slugs: string[];
+        agent?: string;
+        at?: number;
+    }): Promise<{
+        closed: number;
+    }>;
+    listFindings(query: FindingQuery): Promise<FindingRecord[]>;
+    getFinding(id: string): Promise<FindingRecord | null>;
+    setFindingStatus(id: string, status: FindingStatus, at?: number): Promise<void>;
+    wakeSnoozedFindings(scopeKey: string, now?: number): Promise<{
+        woken: number;
+    }>;
+    startCheckRun(run: CheckRunInput): Promise<{
+        pagesScanned: number;
+        findingsOpened: number;
+        findingsClosed: number;
+        costUsd: number;
+        id: string;
+        scopeKey: string;
+        agent: string;
+        trigger: import("./types.ts").CheckRunTrigger;
+        startedAt: number;
+    }>;
+    finishCheckRun(id: string, patch: CheckRunPatch): Promise<void>;
+    listCheckRuns(scopeKey: string, limit?: number): Promise<CheckRunRecord[]>;
+    putMemory(input: MemoryInput, at?: number): Promise<MemoryRecord>;
+    listMemory(query?: MemoryQuery): Promise<MemoryRecord[]>;
+    touchMemory(ids: string[], at?: number): Promise<void>;
+    setMemoryStatus(id: string, status: MemoryStatus): Promise<void>;
+    recordCorrection(input: CorrectionInput, at?: number): Promise<CorrectionRecord>;
+    listCorrections(query?: CorrectionQuery): Promise<CorrectionRecord[]>;
+    putProposal(input: ProposalInput): Promise<ProposalRecord>;
+    getProposal(id: string): Promise<ProposalRecord | null>;
+    listProposals(query: ProposalQuery): Promise<ProposalRecord[]>;
+    setProposalStatus(id: string, status: ProposalStatus, at?: number): Promise<void>;
+    expireProposals(now?: number): Promise<{
+        expired: number;
+    }>;
+}