@peakflo/agent-harness 0.0.0-stage → 0.2.1-rc.3

package/dist/store/sqlite-store.js

@@ -0,0 +1,346 @@
+"use strict";
+/**
+ * THE HARNESS TRANSCRIPT STORE.
+ *
+ * Decision: KEEP THE SQLITE STORE. A runner that holds its working state only
+ * in memory loses a turn to its own crash, and the crash is exactly when the
+ * transcript matters. The control plane stays the source of truth via
+ * `POST /ingest`; this table is WORKING STATE — what has been produced, and
+ * what has been acknowledged — so a restarted harness can resume a lease
+ * instead of replaying a turn the user already paid for.
+ *
+ * WHY `node:sqlite` AND NOT `better-sqlite3`, which 20x uses:
+ *
+ * `pf-bootstrap` installs the harness with `--ignore-scripts` (a Phase 0
+ * hardening decision: an npm install script runs arbitrary code as the harness
+ * user before any of our code is reached). `better-sqlite3` is a NATIVE module
+ * whose binary is fetched or built by `prebuild-install` — an install script.
+ * Depending on it would therefore break the one boot path Phase 0 actually
+ * proved, and it would break it silently, at runtime, on a customer VM.
+ *
+ * `node:sqlite` ships INSIDE Node 22 (unflagged from 22.13). It costs no
+ * dependency, no native build, no install script and no prebuild matrix, and
+ * the sandbox image is already `node:22-bookworm-slim`. On an older Node the
+ * module is simply absent and `openTranscriptStore` falls back to memory, which
+ * costs crash-resumption and nothing else.
+ *
+ * THE SEVEN INVARIANTS are ported from 20x `src/main/database.ts` (schema at
+ * :1225, upsert at :2118, delta at :2179, snapshot at :2209) and each is
+ * asserted individually in the tests. They are NOT approximated: the control
+ * plane implements the same seven, and a transcript written by a runner must be
+ * byte-for-byte the transcript the desktop would have written.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryTranscriptStore = exports.SqliteTranscriptStore = void 0;
+exports.openTranscriptStore = openTranscriptStore;
+const SCHEMA = `
+  CREATE TABLE IF NOT EXISTS transcript_parts (
+    session_id TEXT NOT NULL,
+    part_id    TEXT NOT NULL,
+    seq        INTEGER NOT NULL,
+    role       TEXT NOT NULL DEFAULT 'system',
+    content    TEXT NOT NULL DEFAULT '',
+    part_type  TEXT,
+    tool       TEXT,
+    payload    TEXT,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL,
+    -- Monotonic change cursor, bumped on every insert AND every content
+    -- update, so a reader can ask for "everything changed since rev N" and
+    -- catch both new parts and streaming edits to existing ones.
+    rev        INTEGER NOT NULL DEFAULT 0,
+    PRIMARY KEY (session_id, part_id)
+  );
+  CREATE INDEX IF NOT EXISTS idx_tp_session_seq ON transcript_parts(session_id, seq);
+  CREATE INDEX IF NOT EXISTS idx_tp_session_rev ON transcript_parts(session_id, rev);
+`;
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function toStoredPart(row) {
+    return {
+        partId: row.part_id,
+        seq: row.seq,
+        role: row.role || 'system',
+        content: row.content,
+        partType: row.part_type ?? '',
+        tool: row.tool,
+        payload: row.payload ? JSON.parse(row.payload) : null,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+        rev: row.rev
+    };
+}
+/* -------------------------------------------------------------------------- */
+/* SQLite implementation                                                       */
+/* -------------------------------------------------------------------------- */
+class SqliteTranscriptStore {
+    db;
+    constructor(db) {
+        this.db = db;
+        // WAL so a reader (a health probe, a debug dump) never blocks the agent
+        // loop's writes. A transcript is written on every streaming delta.
+        try {
+            this.db.exec('PRAGMA journal_mode = WAL;');
+        }
+        catch {
+            // A filesystem that cannot do WAL (some container overlays) still works
+            // in the default rollback journal. Not worth failing a boot over.
+        }
+        this.db.exec(SCHEMA);
+    }
+    /**
+     * INVARIANTS 1-5, in one transaction.
+     *
+     * The transaction is explicit BEGIN/COMMIT because `node:sqlite` has no
+     * `db.transaction()` wrapper of the kind better-sqlite3 provides. The
+     * rollback on failure is what makes invariant 1 true: a batch that fails
+     * half-way must leave no parts behind, or a retry would see a transcript that
+     * never existed.
+     */
+    upsertParts(sessionId, parts) {
+        if (parts.length === 0) {
+            return { maxRev: this.getMaxRev(sessionId), changedPartIds: [] };
+        }
+        const nextSeqStmt = this.db.prepare('SELECT COALESCE(MAX(seq), 0) + 1 AS next FROM transcript_parts WHERE session_id = ?');
+        const globalRevStmt = this.db.prepare('SELECT COALESCE(MAX(rev), 0) AS m FROM transcript_parts');
+        // INVARIANT 2: `seq` is absent from the DO UPDATE list, so an existing part
+        // KEEPS the position it was first given. That is precisely how token
+        // streaming works — without it a growing text part would jump to the end of
+        // the transcript on every single delta.
+        //
+        // INVARIANT 3: part_type/tool/payload COALESCE against the STORED value, so
+        // a partial update (a streaming delta carries content and nothing else)
+        // cannot erase metadata that a fuller earlier update established.
+        //
+        // INVARIANT 4: created_at is likewise absent from the DO UPDATE list. The
+        // first write wins, for ever. A later reconcile pass must not restamp
+        // history with the time it happened to run.
+        const upsertStmt = this.db.prepare(`
+      INSERT INTO transcript_parts
+        (session_id, part_id, seq, role, content, part_type, tool, payload, created_at, updated_at, rev)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(session_id, part_id) DO UPDATE SET
+        content    = excluded.content,
+        part_type  = COALESCE(excluded.part_type, transcript_parts.part_type),
+        tool       = COALESCE(excluded.tool,      transcript_parts.tool),
+        payload    = COALESCE(excluded.payload,   transcript_parts.payload),
+        updated_at = excluded.updated_at,
+        rev        = excluded.rev
+    `);
+        const changedPartIds = [];
+        let maxRev = 0;
+        this.db.exec('BEGIN');
+        try {
+            let nextSeq = nextSeqStmt.get(sessionId).next;
+            // INVARIANT 5: rev is allocated from the GLOBAL maximum and bumped for
+            // every changed row, inserts and updates alike.
+            let rev = globalRevStmt.get().m;
+            const writeNow = Date.now();
+            for (const part of parts) {
+                if (!part.partId) {
+                    continue;
+                }
+                rev += 1;
+                upsertStmt.run(sessionId, part.partId, nextSeq, part.role || 'system', part.content || '', part.partType ?? null, part.tool ?? null, 
+                // `undefined` and `null` both store as NULL, which COALESCE then
+                // reads as "leave the stored value alone". The contract's
+                // payload-clear semantics live one layer up, in `isPersistablePart`
+                // and the ingest path — SQL COALESCE cannot express "explicitly
+                // null" and pretending otherwise here would be a lie in the schema.
+                part.payload === undefined || part.payload === null
+                    ? null
+                    : JSON.stringify(part.payload), 
+                // The part's ORIGINAL time when known, never the write time.
+                // Otherwise a bulk replay stamps the whole history within a
+                // millisecond of itself and destroys the transcript's chronology.
+                typeof part.createdAt === 'number' ? part.createdAt : writeNow, writeNow, rev);
+                // seq is consumed per part, matching 20x. A conflicting row ignores the
+                // value it was handed, so the counter simply skips — gaps in seq are
+                // expected and harmless, since seq is only ever a tiebreaker.
+                nextSeq += 1;
+                changedPartIds.push(part.partId);
+            }
+            maxRev = rev;
+            this.db.exec('COMMIT');
+        }
+        catch (error) {
+            try {
+                this.db.exec('ROLLBACK');
+            }
+            catch {
+                // Rolling back a transaction that already aborted is not an error.
+            }
+            throw error;
+        }
+        return { maxRev, changedPartIds };
+    }
+    /** INVARIANTS 6 and 7. */
+    getDelta(sessionId, sinceRev) {
+        const rows = this.db
+            .prepare(`SELECT * FROM transcript_parts
+         WHERE session_id = ? AND rev > ?
+         ORDER BY created_at ASC, seq ASC`)
+            .all(sessionId, sinceRev);
+        // INVARIANT 6: maxRev is PER SESSION. A global maximum would hand a client
+        // a cursor that another session had already advanced past, and the client
+        // would then never be told about its own next part.
+        const max = this.db
+            .prepare('SELECT COALESCE(MAX(rev), ?) AS m FROM transcript_parts WHERE session_id = ?')
+            .get(sinceRev, sessionId);
+        return { parts: rows.map(toStoredPart), maxRev: max.m };
+    }
+    getParts(sessionId) {
+        // INVARIANT 7: ordered by REAL event time, with seq as a stable tiebreaker.
+        // Insertion order is NOT chronological once a partial projection has older
+        // history backfilled into it.
+        const rows = this.db
+            .prepare(`SELECT * FROM transcript_parts
+         WHERE session_id = ?
+         ORDER BY created_at ASC, seq ASC`)
+            .all(sessionId);
+        return rows.map(toStoredPart);
+    }
+    getMaxRev(sessionId) {
+        const row = this.db
+            .prepare('SELECT COALESCE(MAX(rev), 0) AS m FROM transcript_parts WHERE session_id = ?')
+            .get(sessionId);
+        return row.m;
+    }
+    deleteParts(sessionId) {
+        this.db
+            .prepare('DELETE FROM transcript_parts WHERE session_id = ?')
+            .run(sessionId);
+    }
+    close() {
+        try {
+            this.db.close();
+        }
+        catch {
+            // Closing twice is not an error worth propagating out of a shutdown path.
+        }
+    }
+}
+exports.SqliteTranscriptStore = SqliteTranscriptStore;
+/* -------------------------------------------------------------------------- */
+/* In-memory fallback                                                          */
+/* -------------------------------------------------------------------------- */
+/**
+ * The same seven invariants, without durability.
+ *
+ * Used when `node:sqlite` is absent, and in tests. It is a REAL implementation
+ * rather than a stub: if the two disagreed, every test that used this would be
+ * testing something the product does not do. The tests run the same invariant
+ * suite against both.
+ */
+class MemoryTranscriptStore {
+    bySession = new Map();
+    globalRev = 0;
+    upsertParts(sessionId, parts) {
+        let session = this.bySession.get(sessionId);
+        if (!session) {
+            session = new Map();
+            this.bySession.set(sessionId, session);
+        }
+        const changedPartIds = [];
+        const writeNow = Date.now();
+        let nextSeq = Math.max(0, ...Array.from(session.values(), (p) => p.seq)) + 1;
+        for (const part of parts) {
+            if (!part.partId) {
+                continue;
+            }
+            this.globalRev += 1;
+            const existing = session.get(part.partId);
+            if (existing) {
+                // Invariants 2, 3 and 4: keep seq, keep createdAt, coalesce metadata.
+                existing.content = part.content || '';
+                existing.partType = part.partType ?? existing.partType;
+                existing.tool = part.tool ?? existing.tool;
+                existing.payload =
+                    part.payload === undefined || part.payload === null
+                        ? existing.payload
+                        : part.payload;
+                existing.updatedAt = writeNow;
+                existing.rev = this.globalRev;
+            }
+            else {
+                session.set(part.partId, {
+                    partId: part.partId,
+                    seq: nextSeq,
+                    role: part.role || 'system',
+                    content: part.content || '',
+                    partType: part.partType ?? '',
+                    tool: part.tool ?? null,
+                    payload: part.payload ?? null,
+                    createdAt: typeof part.createdAt === 'number' ? part.createdAt : writeNow,
+                    updatedAt: writeNow,
+                    rev: this.globalRev
+                });
+            }
+            nextSeq += 1;
+            changedPartIds.push(part.partId);
+        }
+        return { maxRev: this.globalRev, changedPartIds };
+    }
+    getDelta(sessionId, sinceRev) {
+        const parts = this.ordered(sessionId).filter((p) => p.rev > sinceRev);
+        const all = this.ordered(sessionId);
+        const maxRev = all.length ? Math.max(...all.map((p) => p.rev)) : sinceRev;
+        return { parts, maxRev };
+    }
+    getParts(sessionId) {
+        return this.ordered(sessionId);
+    }
+    getMaxRev(sessionId) {
+        const all = this.ordered(sessionId);
+        return all.length ? Math.max(...all.map((p) => p.rev)) : 0;
+    }
+    deleteParts(sessionId) {
+        this.bySession.delete(sessionId);
+    }
+    ordered(sessionId) {
+        const session = this.bySession.get(sessionId);
+        if (!session) {
+            return [];
+        }
+        return Array.from(session.values())
+            .map((p) => ({ ...p }))
+            .sort((a, b) => a.createdAt - b.createdAt || a.seq - b.seq);
+    }
+}
+exports.MemoryTranscriptStore = MemoryTranscriptStore;
+/**
+ * Open the durable store, or say plainly why it could not be opened.
+ *
+ * NEVER THROWS. A harness that cannot open a database is still able to run a
+ * turn and push it to the control plane, which is the source of truth; refusing
+ * to boot would trade a recoverable degradation for an outage. The caller
+ * reports `durable: false` in its health snapshot so the degradation is VISIBLE
+ * rather than silent — a fallback nobody can see is how an outage becomes a
+ * mystery.
+ */
+function openTranscriptStore(path) {
+    let sqlite;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires, global-require, @typescript-eslint/no-require-imports
+        sqlite = require('node:sqlite');
+    }
+    catch (error) {
+        return {
+            store: new MemoryTranscriptStore(),
+            durable: false,
+            reason: `node:sqlite unavailable (needs Node >= 22.13): ${errorMessage(error)}`
+        };
+    }
+    try {
+        const db = new sqlite.DatabaseSync(path);
+        return { store: new SqliteTranscriptStore(db), durable: true };
+    }
+    catch (error) {
+        return {
+            store: new MemoryTranscriptStore(),
+            durable: false,
+            reason: `could not open ${path}: ${errorMessage(error)}`
+        };
+    }
+}