@avocadostudio-ai/orchestrator-core 0.3.2 → 0.4.0

package/dist/durable/in-memory-durable-store.d.ts

@@ -0,0 +1,203 @@
+import type { CheckRunInput, CheckRunPatch, CorrectionInput, CorrectionQuery, DurableStore, FindingInput, FindingQuery, FindingSeverity, FindingStatus, MemoryInput, MemoryQuery, MemoryStatus, ProposalInput, ProposalQuery, ProposalStatus } from "./types.ts";
+export type InMemoryDurableStoreOptions = {
+    now?: () => number;
+};
+export declare class InMemoryDurableStore implements DurableStore {
+    private readonly findings;
+    /** (scopeKey, fingerprint) → finding id. Mirrors the SQLite unique index. */
+    private readonly byFingerprint;
+    private readonly runs;
+    private readonly memory;
+    private readonly corrections;
+    private readonly proposals;
+    private readonly now;
+    constructor(options?: InMemoryDurableStoreOptions);
+    /** Keep the newest `cap` rows per scope, matching the SQLite store's trim. */
+    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<{
+        fingerprint: string;
+        scopeKey: string;
+        slug: string;
+        ruleId: string;
+        agent: string;
+        severity: FindingSeverity;
+        impact: number;
+        title: string;
+        detail?: string;
+        evidence?: import("./types.ts").FindingEvidence;
+        proposedOps?: import("@avocadostudio-ai/shared").Operation[];
+        id: string;
+        status: FindingStatus;
+        lastRunId: string;
+        firstSeenAt: number;
+        lastSeenAt: number;
+        resolvedAt?: number;
+        snoozedUntil?: number;
+    }[]>;
+    getFinding(id: string): Promise<{
+        fingerprint: string;
+        scopeKey: string;
+        slug: string;
+        ruleId: string;
+        agent: string;
+        severity: FindingSeverity;
+        impact: number;
+        title: string;
+        detail?: string;
+        evidence?: import("./types.ts").FindingEvidence;
+        proposedOps?: import("@avocadostudio-ai/shared").Operation[];
+        id: string;
+        status: FindingStatus;
+        lastRunId: string;
+        firstSeenAt: number;
+        lastSeenAt: number;
+        resolvedAt?: number;
+        snoozedUntil?: number;
+    } | null>;
+    setFindingStatus(id: string, status: FindingStatus, at?: number): Promise<void>;
+    wakeSnoozedFindings(scopeKey: string, now?: number): Promise<{
+        woken: number;
+    }>;
+    startCheckRun(run: CheckRunInput): Promise<{
+        id: string;
+        scopeKey: string;
+        agent: string;
+        trigger: import("./types.ts").CheckRunTrigger;
+        startedAt: number;
+        finishedAt?: number;
+        pagesScanned: number;
+        findingsOpened: number;
+        findingsClosed: number;
+        costUsd: number;
+        error?: string;
+    }>;
+    finishCheckRun(id: string, patch: CheckRunPatch): Promise<void>;
+    listCheckRuns(scopeKey: string, limit?: number): Promise<{
+        id: string;
+        scopeKey: string;
+        agent: string;
+        trigger: import("./types.ts").CheckRunTrigger;
+        startedAt: number;
+        finishedAt?: number;
+        pagesScanned: number;
+        findingsOpened: number;
+        findingsClosed: number;
+        costUsd: number;
+        error?: string;
+    }[]>;
+    putMemory(input: MemoryInput, at?: number): Promise<{
+        confidence: number;
+        scope: import("./types.ts").MemoryScope;
+        scopeKey: string;
+        kind: import("./types.ts").MemoryKind;
+        key: string;
+        value: string;
+        source: import("./types.ts").MemorySource;
+        sourceRef?: string;
+        id: string;
+        status: MemoryStatus;
+        supersedesId?: string;
+        createdAt: number;
+        lastUsedAt?: number;
+        useCount: number;
+    }>;
+    listMemory(query?: MemoryQuery): Promise<{
+        confidence: number;
+        scope: import("./types.ts").MemoryScope;
+        scopeKey: string;
+        kind: import("./types.ts").MemoryKind;
+        key: string;
+        value: string;
+        source: import("./types.ts").MemorySource;
+        sourceRef?: string;
+        id: string;
+        status: MemoryStatus;
+        supersedesId?: string;
+        createdAt: number;
+        lastUsedAt?: number;
+        useCount: number;
+    }[]>;
+    touchMemory(ids: string[], at?: number): Promise<void>;
+    setMemoryStatus(id: string, status: MemoryStatus): Promise<void>;
+    recordCorrection(input: CorrectionInput, at?: number): Promise<{
+        traceId: string;
+        scopeKey: string;
+        slug?: string;
+        request: string;
+        proposed: import("@avocadostudio-ai/shared").Operation[];
+        outcome: import("./types.ts").CorrectionOutcome;
+        applied?: import("@avocadostudio-ai/shared").Operation[];
+        id: string;
+        at: number;
+    }>;
+    listCorrections(query?: CorrectionQuery): Promise<{
+        traceId: string;
+        scopeKey: string;
+        slug?: string;
+        request: string;
+        proposed: import("@avocadostudio-ai/shared").Operation[];
+        outcome: import("./types.ts").CorrectionOutcome;
+        applied?: import("@avocadostudio-ai/shared").Operation[];
+        id: string;
+        at: number;
+    }[]>;
+    putProposal(input: ProposalInput): Promise<{
+        id: string;
+        scopeKey: string;
+        origin: string;
+        summary: string;
+        ops: import("@avocadostudio-ai/shared").Operation[];
+        slugs: string[];
+        findingId?: string;
+        payload?: Record<string, unknown>;
+        createdAt: number;
+        expiresAt?: number;
+        status: ProposalStatus;
+        resolvedAt?: number;
+    }>;
+    getProposal(id: string): Promise<{
+        id: string;
+        scopeKey: string;
+        origin: string;
+        summary: string;
+        ops: import("@avocadostudio-ai/shared").Operation[];
+        slugs: string[];
+        findingId?: string;
+        payload?: Record<string, unknown>;
+        createdAt: number;
+        expiresAt?: number;
+        status: ProposalStatus;
+        resolvedAt?: number;
+    } | null>;
+    listProposals(query: ProposalQuery): Promise<{
+        id: string;
+        scopeKey: string;
+        origin: string;
+        summary: string;
+        ops: import("@avocadostudio-ai/shared").Operation[];
+        slugs: string[];
+        findingId?: string;
+        payload?: Record<string, unknown>;
+        createdAt: number;
+        expiresAt?: number;
+        status: ProposalStatus;
+        resolvedAt?: number;
+    }[]>;
+    setProposalStatus(id: string, status: ProposalStatus, at?: number): Promise<void>;
+    expireProposals(now?: number): Promise<{
+        expired: number;
+    }>;
+}

package/dist/durable/in-memory-durable-store.js

@@ -0,0 +1,363 @@
+import { randomUUID } from "node:crypto";
+import { CHECK_RUN_CAP, CORRECTION_CAP, PROPOSAL_CAP, SNOOZE_WINDOW_MS } from "./sqlite-durable-store.js";
+import { fallbackImpact } from "./finding-impact.js";
+/*
+ * In-memory `DurableStore`. Two jobs, both real.
+ *
+ * 1. It is the reference semantics. `durable-store.test.ts` runs one conformance
+ *    suite against this and the SQLite store, so a behaviour that drifts between
+ *    them fails rather than being discovered by whoever swaps implementations.
+ *
+ * 2. It is the honest fallback. `createOrchestrator()` already degrades to
+ *    memory-only when `better-sqlite3` cannot be loaded, and reports it through
+ *    `persistence: { ok: false, reason }`. Findings and memory should degrade
+ *    the same way and report the same thing — not throw, and not pretend.
+ *
+ * Nothing here is durable. The name describes the interface, not this class.
+ */
+const SEVERITY_ORDER = { error: 0, warning: 1, info: 2 };
+/** A fingerprint is unique per scope, never globally. See the SQLite index. */
+function fingerprintKey(scopeKey, fingerprint) {
+    return `${scopeKey}\u0000${fingerprint}`;
+}
+export class InMemoryDurableStore {
+    findings = new Map();
+    /** (scopeKey, fingerprint) → finding id. Mirrors the SQLite unique index. */
+    byFingerprint = new Map();
+    runs = new Map();
+    memory = new Map();
+    corrections = [];
+    proposals = new Map();
+    now;
+    constructor(options = {}) {
+        this.now = options.now ?? Date.now;
+    }
+    /** Keep the newest `cap` rows per scope, matching the SQLite store's trim. */
+    trim(map, scopeKey, cap, order) {
+        const forScope = [...map.values()].filter((row) => row.scopeKey === scopeKey);
+        if (forScope.length <= cap)
+            return;
+        forScope
+            .sort((a, b) => order(a) - order(b))
+            .slice(0, forScope.length - cap)
+            .forEach((row) => map.delete(row.id));
+    }
+    // Findings ---------------------------------------------------------------
+    async recordFindings(runId, findings) {
+        const at = this.now();
+        let opened = 0;
+        let updated = 0;
+        for (const f of findings) {
+            const fpKey = fingerprintKey(f.scopeKey, f.fingerprint);
+            const existingId = this.byFingerprint.get(fpKey);
+            const existing = existingId ? this.findings.get(existingId) : undefined;
+            if (!existing) {
+                const id = randomUUID();
+                this.findings.set(id, {
+                    ...f,
+                    id,
+                    impact: f.impact ?? fallbackImpact(f.severity),
+                    status: "open",
+                    lastRunId: runId,
+                    firstSeenAt: at,
+                    lastSeenAt: at
+                });
+                this.byFingerprint.set(fpKey, id);
+                opened += 1;
+                continue;
+            }
+            // `status` and `firstSeenAt` deliberately survive — see the SQLite store.
+            const next = {
+                ...existing,
+                slug: f.slug,
+                ruleId: f.ruleId,
+                agent: f.agent,
+                severity: f.severity,
+                // Recomputed every run — the page's weight moves even when the finding
+                // does not. See the SQLite store.
+                impact: f.impact ?? fallbackImpact(f.severity),
+                title: f.title,
+                lastRunId: runId,
+                lastSeenAt: at
+            };
+            if (f.detail === undefined)
+                delete next.detail;
+            else
+                next.detail = f.detail;
+            if (f.evidence === undefined)
+                delete next.evidence;
+            else
+                next.evidence = f.evidence;
+            if (f.proposedOps === undefined)
+                delete next.proposedOps;
+            else
+                next.proposedOps = f.proposedOps;
+            if (existing.status === "fixed") {
+                next.status = "open";
+                delete next.resolvedAt;
+                opened += 1;
+            }
+            else {
+                updated += 1;
+            }
+            this.findings.set(existing.id, next);
+        }
+        return { opened, updated };
+    }
+    async reconcileFindings(args) {
+        if (args.slugs.length === 0)
+            return { closed: 0 };
+        const at = args.at ?? this.now();
+        const inScope = new Set(args.slugs);
+        let closed = 0;
+        for (const record of this.findings.values()) {
+            if (record.scopeKey !== args.scopeKey)
+                continue;
+            // `snoozed` closes too — see the SQLite store. A snooze defers the
+            // report, not the problem.
+            if (record.status !== "open" && record.status !== "snoozed")
+                continue;
+            if (record.lastRunId === args.runId)
+                continue;
+            if (!inScope.has(record.slug))
+                continue;
+            if (args.agent && record.agent !== args.agent)
+                continue;
+            const next = { ...record, status: "fixed", resolvedAt: at };
+            delete next.snoozedUntil;
+            this.findings.set(record.id, next);
+            closed += 1;
+        }
+        return { closed };
+    }
+    async listFindings(query) {
+        const statuses = query.status
+            ? new Set(Array.isArray(query.status) ? query.status : [query.status])
+            : null;
+        if (statuses && statuses.size === 0)
+            return [];
+        const limit = Math.max(1, Math.min(query.limit ?? 500, 5000));
+        return [...this.findings.values()]
+            .filter((f) => f.scopeKey === query.scopeKey)
+            .filter((f) => (query.slug ? f.slug === query.slug : true))
+            .filter((f) => (query.agent ? f.agent === query.agent : true))
+            .filter((f) => (query.severity ? f.severity === query.severity : true))
+            .filter((f) => (statuses ? statuses.has(f.status) : true))
+            // Impact leads, severity breaks its ties — mirroring the SQLite ORDER BY.
+            .sort((a, b) => b.impact - a.impact ||
+            SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity] ||
+            b.lastSeenAt - a.lastSeenAt)
+            .slice(0, limit)
+            .map((f) => ({ ...f }));
+    }
+    async getFinding(id) {
+        const record = this.findings.get(id);
+        return record ? { ...record } : null;
+    }
+    async setFindingStatus(id, status, at) {
+        const record = this.findings.get(id);
+        if (!record)
+            return;
+        const when = at ?? this.now();
+        const next = { ...record, status };
+        // Deferred is not resolved, so `snoozed` clears `resolvedAt` like `open`.
+        if (status === "open" || status === "snoozed")
+            delete next.resolvedAt;
+        else
+            next.resolvedAt = when;
+        if (status === "snoozed")
+            next.snoozedUntil = when + SNOOZE_WINDOW_MS;
+        else
+            delete next.snoozedUntil;
+        this.findings.set(id, next);
+    }
+    async wakeSnoozedFindings(scopeKey, now) {
+        const at = now ?? this.now();
+        let woken = 0;
+        for (const record of this.findings.values()) {
+            if (record.scopeKey !== scopeKey || record.status !== "snoozed")
+                continue;
+            if (record.snoozedUntil == null || record.snoozedUntil > at)
+                continue;
+            const next = { ...record, status: "open" };
+            delete next.snoozedUntil;
+            delete next.resolvedAt;
+            this.findings.set(record.id, next);
+            woken += 1;
+        }
+        return { woken };
+    }
+    // Check runs -------------------------------------------------------------
+    async startCheckRun(run) {
+        const record = {
+            ...run,
+            pagesScanned: 0,
+            findingsOpened: 0,
+            findingsClosed: 0,
+            costUsd: 0
+        };
+        this.runs.set(run.id, record);
+        this.trim(this.runs, run.scopeKey, CHECK_RUN_CAP, (r) => r.startedAt);
+        return { ...record };
+    }
+    async finishCheckRun(id, patch) {
+        const record = this.runs.get(id);
+        if (!record)
+            return;
+        this.runs.set(id, { ...record, ...patch });
+    }
+    async listCheckRuns(scopeKey, limit = 50) {
+        return [...this.runs.values()]
+            .filter((r) => r.scopeKey === scopeKey)
+            .sort((a, b) => b.startedAt - a.startedAt)
+            .slice(0, Math.max(1, Math.min(limit, 1000)))
+            .map((r) => ({ ...r }));
+    }
+    // Memory -----------------------------------------------------------------
+    async putMemory(input, at) {
+        const createdAt = at ?? this.now();
+        const previous = [...this.memory.values()].find((m) => m.status === "active" &&
+            m.scope === input.scope &&
+            m.scopeKey === input.scopeKey &&
+            m.kind === input.kind &&
+            m.key === input.key);
+        if (previous)
+            this.memory.set(previous.id, { ...previous, status: "superseded" });
+        const record = {
+            ...input,
+            id: randomUUID(),
+            confidence: input.confidence ?? 1,
+            status: "active",
+            ...(previous ? { supersedesId: previous.id } : {}),
+            createdAt,
+            useCount: 0
+        };
+        this.memory.set(record.id, record);
+        return { ...record };
+    }
+    async listMemory(query = {}) {
+        const kinds = query.kind
+            ? new Set(Array.isArray(query.kind) ? query.kind : [query.kind])
+            : null;
+        if (kinds && kinds.size === 0)
+            return [];
+        const status = query.status ?? "active";
+        const limit = Math.max(1, Math.min(query.limit ?? 500, 5000));
+        return [...this.memory.values()]
+            .filter((m) => (query.scopeKey ? m.scopeKey === query.scopeKey : true))
+            .filter((m) => (query.scope ? m.scope === query.scope : true))
+            .filter((m) => (kinds ? kinds.has(m.kind) : true))
+            .filter((m) => m.status === status)
+            .sort((a, b) => b.createdAt - a.createdAt)
+            .slice(0, limit)
+            .map((m) => ({ ...m }));
+    }
+    async touchMemory(ids, at) {
+        const when = at ?? this.now();
+        for (const id of ids) {
+            const record = this.memory.get(id);
+            if (!record)
+                continue;
+            this.memory.set(id, { ...record, lastUsedAt: when, useCount: record.useCount + 1 });
+        }
+    }
+    async setMemoryStatus(id, status) {
+        const record = this.memory.get(id);
+        if (!record)
+            return;
+        // Reactivating demotes whatever is active for that key — otherwise this
+        // store would hold two active records for one key and hand a planner two
+        // contradicting facts, while SQLite refused the same write outright.
+        if (status === "active") {
+            for (const other of this.memory.values()) {
+                if (other.id === id)
+                    continue;
+                if (other.status !== "active")
+                    continue;
+                if (other.scope !== record.scope ||
+                    other.scopeKey !== record.scopeKey ||
+                    other.kind !== record.kind ||
+                    other.key !== record.key) {
+                    continue;
+                }
+                this.memory.set(other.id, { ...other, status: "superseded" });
+            }
+        }
+        this.memory.set(id, { ...record, status });
+    }
+    // Corrections ------------------------------------------------------------
+    async recordCorrection(input, at) {
+        const record = { ...input, id: randomUUID(), at: at ?? this.now() };
+        this.corrections.push(record);
+        const forScope = this.corrections.filter((c) => c.scopeKey === record.scopeKey);
+        if (forScope.length > CORRECTION_CAP) {
+            const drop = new Set(forScope.sort((a, b) => a.at - b.at).slice(0, forScope.length - CORRECTION_CAP).map((c) => c.id));
+            for (let i = this.corrections.length - 1; i >= 0; i -= 1) {
+                if (drop.has(this.corrections[i].id))
+                    this.corrections.splice(i, 1);
+            }
+        }
+        return { ...record };
+    }
+    async listCorrections(query = {}) {
+        const limit = Math.max(1, Math.min(query.limit ?? 200, 5000));
+        return this.corrections
+            .filter((c) => (query.scopeKey ? c.scopeKey === query.scopeKey : true))
+            .filter((c) => (query.outcome ? c.outcome === query.outcome : true))
+            .filter((c) => (query.since != null ? c.at >= query.since : true))
+            .slice()
+            .sort((a, b) => b.at - a.at)
+            .slice(0, limit)
+            .map((c) => ({ ...c }));
+    }
+    // Proposals --------------------------------------------------------------
+    async putProposal(input) {
+        const existing = this.proposals.get(input.id);
+        const record = {
+            ...input,
+            status: existing?.status ?? "pending",
+            ...(existing?.resolvedAt != null ? { resolvedAt: existing.resolvedAt } : {}),
+            createdAt: existing?.createdAt ?? input.createdAt
+        };
+        this.proposals.set(record.id, record);
+        this.trim(this.proposals, record.scopeKey, PROPOSAL_CAP, (p) => p.createdAt);
+        return { ...record };
+    }
+    async getProposal(id) {
+        const record = this.proposals.get(id);
+        return record ? { ...record } : null;
+    }
+    async listProposals(query) {
+        const limit = Math.max(1, Math.min(query.limit ?? 100, 1000));
+        return [...this.proposals.values()]
+            .filter((p) => p.scopeKey === query.scopeKey)
+            .filter((p) => (query.status ? p.status === query.status : true))
+            .sort((a, b) => b.createdAt - a.createdAt)
+            .slice(0, limit)
+            .map((p) => ({ ...p }));
+    }
+    async setProposalStatus(id, status, at) {
+        const record = this.proposals.get(id);
+        if (!record)
+            return;
+        const next = { ...record, status };
+        if (status === "pending")
+            delete next.resolvedAt;
+        else
+            next.resolvedAt = at ?? this.now();
+        this.proposals.set(id, next);
+    }
+    async expireProposals(now) {
+        const at = now ?? this.now();
+        let expired = 0;
+        for (const record of this.proposals.values()) {
+            if (record.status !== "pending")
+                continue;
+            if (record.expiresAt == null || record.expiresAt > at)
+                continue;
+            this.proposals.set(record.id, { ...record, status: "expired", resolvedAt: at });
+            expired += 1;
+        }
+        return { expired };
+    }
+}

package/dist/durable/index.d.ts

@@ -0,0 +1,5 @@
+export { getDurableStore, resetDurableStore, setDurableStore, durableStoreIsEphemeral, discardPendingProposalsForSession, sweepExpiredProposals } from "./durable-store-singleton.ts";
+export { loadPendingPlan, savePendingPlan, clearPendingPlan, peekPendingPlan } from "./pending-plan-store.ts";
+export { SqliteDurableStore, type SqliteDurableStoreOptions } from "./sqlite-durable-store.ts";
+export { InMemoryDurableStore, type InMemoryDurableStoreOptions } from "./in-memory-durable-store.ts";
+export type { DurableStore, FindingInput, FindingRecord, FindingQuery, FindingSeverity, FindingStatus, FindingEvidence, CheckRunInput, CheckRunRecord, CheckRunPatch, CheckRunTrigger, MemoryInput, MemoryRecord, MemoryQuery, MemoryScope, MemoryKind, MemorySource, MemoryStatus, CorrectionInput, CorrectionRecord, CorrectionQuery, CorrectionOutcome, ProposalInput, ProposalRecord, ProposalQuery, ProposalStatus } from "./types.ts";

package/dist/durable/index.js

@@ -0,0 +1,4 @@
+export { getDurableStore, resetDurableStore, setDurableStore, durableStoreIsEphemeral, discardPendingProposalsForSession, sweepExpiredProposals } from "./durable-store-singleton.js";
+export { loadPendingPlan, savePendingPlan, clearPendingPlan, peekPendingPlan } from "./pending-plan-store.js";
+export { SqliteDurableStore } from "./sqlite-durable-store.js";
+export { InMemoryDurableStore } from "./in-memory-durable-store.js";

package/dist/durable/pending-plan-store.d.ts

@@ -0,0 +1,28 @@
+import { type PendingApprovalPlan } from "../state/session-state.ts";
+/**
+ * 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 declare function peekPendingPlan(session: string): PendingApprovalPlan | undefined;
+/**
+ * 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 declare function loadPendingPlan(session: string): Promise<PendingApprovalPlan | undefined>;
+/** Set the plan in memory and mirror it to the durable store. */
+export declare function savePendingPlan(session: string, plan: PendingApprovalPlan): Promise<void>;
+/**
+ * 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 declare function clearPendingPlan(session: string, outcome: "approved" | "discarded", expectedId?: string): Promise<void>;