@gaunt-sloth/core 2.0.0-beta.4 → 2.0.0-beta.6

package/dist/history/checkpointSaver.d.ts

@@ -0,0 +1,93 @@
+import { BaseCheckpointSaver } from '@langchain/langgraph';
+import type { Checkpoint, CheckpointMetadata, CheckpointTuple } from '@langchain/langgraph';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import { type CheckpointStoreStats, type ReclaimSummary } from '#src/history/checkpointRetention.js';
+/**
+ * The abstract members' own parameter types, read off the base class rather than imported.
+ * `@langchain/langgraph` re-exports `BaseCheckpointSaver` (and `Checkpoint`, `CheckpointMetadata`,
+ * `CheckpointTuple`) but not `ChannelVersions`, `CheckpointListOptions` or `PendingWrite`, which
+ * live only in `@langchain/langgraph-checkpoint` — a package this one does not depend on. Deriving
+ * them keeps the signatures exactly the base class's without adding a dependency whose second
+ * physical copy could disagree with the one LangGraph itself loads. `put`'s fourth parameter is
+ * derived inline at its signature for the same reason, kept out of this list so the alias does not
+ * surface as an undocumented type in the rendered API reference.
+ */
+type ListOptions = NonNullable<Parameters<BaseCheckpointSaver['list']>[1]>;
+type PendingWrites = Parameters<BaseCheckpointSaver['putWrites']>[1];
+/** Options for {@link openCheckpointSaver}. */
+export interface CheckpointSaverOptions {
+    /**
+     * Called when a `put` / `putWrites` could not reach the database. The write is dropped and the
+     * turn continues; the handler's job is to tell the user and to record that this conversation can
+     * no longer be resumed. Called on EVERY failed write — the once-per-session rule belongs to the
+     * handler, which is the layer that knows what a session is.
+     */
+    onWriteFailure?: (error: unknown) => void;
+}
+/**
+ * A LangGraph `BaseCheckpointSaver` persisting to a `node:sqlite` database.
+ *
+ * Obtain one through {@link openCheckpointSaver}, which is fail-soft; the constructor is private so
+ * there is no way to hold one whose tables were never created.
+ */
+export declare class GthSqliteSaver extends BaseCheckpointSaver {
+    private db;
+    private onWriteFailure;
+    /**
+     * GS2-107 — every thread this saver has written to, which is what automatic reclamation excludes.
+     *
+     * The thread a session writes to is not fixed at open: `resetThread()` mints a fresh one on
+     * `/clear` and `resumeConversation` rebinds onto a stored one, and neither tells this object. An
+     * exclusion built from the id the session started with therefore names a thread nobody is writing
+     * and misses the one that is — which on the `/clear` path is a thread no conversation row names,
+     * i.e. exactly a reclamation candidate. Recording the ids as they arrive needs no notification at
+     * all: whatever the runner rotated onto, the write came through here.
+     */
+    private readonly writtenThreads;
+    private constructor();
+    /**
+     * Report a dropped write, and never let the reporting itself become the failure. A handler that
+     * throws here would land back inside `agent.invoke()` and end the turn — the exact outcome the
+     * degrade posture exists to avoid, arriving from the code that implements it.
+     */
+    private reportWriteFailure;
+    /**
+     * Open (and lazily initialise) the checkpoint tables at `dbPath`. Returns `null` on any failure —
+     * an unopenable, read-only or corrupt DB — so the caller can fall back to a `MemorySaver` without
+     * a try/catch of its own.
+     */
+    static open(dbPath: string, options?: CheckpointSaverOptions): GthSqliteSaver | null;
+    /** Close the underlying connection (fail-soft). */
+    close(): void;
+    /** Rebuild one stored row into the tuple LangGraph reads, pending writes and parent included. */
+    private toTuple;
+    getTuple(config: RunnableConfig): Promise<CheckpointTuple | undefined>;
+    list(config: RunnableConfig, options?: ListOptions): AsyncGenerator<CheckpointTuple>;
+    put(config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata, _newVersions: Parameters<BaseCheckpointSaver['put']>[3]): Promise<RunnableConfig>;
+    putWrites(config: RunnableConfig, writes: PendingWrites, taskId: string): Promise<void>;
+    deleteThread(threadId: string): Promise<void>;
+    /**
+     * GS2-107 — delete every thread no conversation row names, past the grace window. The retention
+     * module owns the policy and the reasoning; this is the saver's own connection lent to it, so a
+     * session that already has the store open can reclaim without opening it again.
+     *
+     * **Every thread this saver wrote is excluded, always**, on top of whatever the caller names. A
+     * caller cannot supply that set: the runner rotates threads without telling anyone, so the only
+     * place that knows which thread the session ended on is the object the writes went through. The
+     * union is the contract — `excludeThreadIds` adds to the protection and can never subtract from
+     * it.
+     */
+    reclaimUnresumableThreads(options?: {
+        now?: number;
+        graceMs?: number;
+        excludeThreadIds?: readonly string[];
+    }): ReclaimSummary;
+    /** GS2-107 — what the checkpoint tables hold, over this saver's open connection. */
+    storeStats(dbPath: string, topN?: number): CheckpointStoreStats;
+}
+/**
+ * Fail-soft open of the durable checkpoint saver. Returns `null` (never throws) when the DB cannot
+ * be opened or its tables cannot be created.
+ */
+export declare function openCheckpointSaver(dbPath: string, options?: CheckpointSaverOptions): GthSqliteSaver | null;
+export {};

package/dist/history/checkpointSaver.js

@@ -0,0 +1,464 @@
+/**
+ * @packageDocumentation
+ * GS2-20 — a **durable LangGraph checkpointer** over the same local SQLite file the session
+ * history store uses, so a past conversation can be resumed with the graph state it actually had.
+ *
+ * Resuming by replaying stored messages into a fresh agent rebuilds a transcript and discards
+ * everything the LangGraph graph was holding — pending writes, a suspended interrupt, the channel
+ * versions that make `add_messages` reconcile rather than append. What a resume has to produce is
+ * that, from the agent's side, no interruption happened, and only a saver whose checkpoints outlive
+ * the process can produce it.
+ *
+ * **Written against the built-in `node:sqlite`, deliberately.** Gaunt Sloth is installed globally
+ * with `npm i -g`, and the history store (`historyStore.ts`) states the constraint this inherits:
+ * zero native dependency, no build step. The published LangGraph SQLite savers are built on
+ * `better-sqlite3`, a native module with a compile step, which would put a node-gyp build in the
+ * path of every install of the CLI.
+ *
+ * **Storage layout.** Two tables of this module's own — `checkpoints` and `checkpoint_writes` —
+ * created idempotently on open, in the same file as the store's `sessions` / `conversations`.
+ * One file, one opt-out, one thing to delete. The store owns its tables and this owns these; there
+ * is no shared DDL, so the store's per-call open (which re-runs its own migration every time)
+ * cannot race this module's long-lived connection over the same schema.
+ *
+ * **Failure posture: degrade, loudly.** {@link openCheckpointSaver} is fail-soft — it returns `null`
+ * rather than throwing when the DB cannot be opened or the tables cannot be created, which is what
+ * lets the session fall back to a `MemorySaver` (see `openSessionCheckpointerSafe` in
+ * `sessionCheckpointer.ts`). A write that fails AFTER that — a full disk, a filesystem that went
+ * read-only under a live handle — is caught here and reported through
+ * {@link CheckpointSaverOptions.onWriteFailure} instead of propagating.
+ *
+ * Neither of the two obvious postures is right, and the reason is worth keeping. **Swallowing**
+ * would report a resumed session as empty and turn a suspended tool approval into a graph nobody
+ * can resume — silent and wrong. **Throwing** propagates out of `agent.invoke()` into the session's
+ * outer catch and ends the session, which since GS2-20 made history the default would mean a full
+ * disk takes down the live session of a user who never asked for the feature; recording a
+ * conversation must not become a new way to lose one. So the third posture: the write is dropped,
+ * the turn continues, the user is told once, and the conversation is marked **unresumable on disk**
+ * — that last part is what stops a silent drop from becoming a resume of a truncated conversation,
+ * and it is why this differs from the history RECORDER, which merely swallows. A missing turn in a
+ * listing is a gap; a half-restored graph presented as whole is a lie.
+ *
+ * Reads are still loud: nothing is degraded by a failed `getTuple`, and a resume that cannot read
+ * must not pretend the thread was empty.
+ */
+import { DatabaseSync } from 'node:sqlite';
+import { BaseCheckpointSaver, copyCheckpoint } from '@langchain/langgraph';
+import { collectCheckpointStoreStats, deleteThreads, reclaimUnresumableThreads, } from '#src/history/checkpointRetention.js';
+/**
+ * LangGraph's reserved channel names and the fixed NEGATIVE slot each takes in a task's writes.
+ *
+ * A saver's `putWrites` is insert-once for ordinary writes (a retried super-step must not duplicate
+ * them) but replace-on-write for these four, which is why they need slots that cannot collide with
+ * a positional index. `__interrupt__` and `__resume__` are the pair the tool-approval gate rides on,
+ * so getting this wrong is not academic: a stale `__interrupt__` write kept beside a fresh one is a
+ * suspended approval that resumes twice.
+ *
+ * Mirrors `WRITES_IDX_MAP` in `@langchain/langgraph-checkpoint`, which does not re-export through
+ * `@langchain/langgraph`. Copied rather than depended on — see the note on the derived types above.
+ * A reserved name added upstream and missed here degrades to a positional slot: that write becomes
+ * insert-once instead of replace, which is visible only on a resume, so re-check this list when the
+ * LangGraph major moves.
+ */
+const WRITES_IDX_MAP = Object.freeze({
+    __error__: -1,
+    __scheduled__: -2,
+    __interrupt__: -3,
+    __resume__: -4,
+});
+/**
+ * How long a statement waits for another connection's lock before giving up. The history recorder
+ * opens the same file for a moment at the end of every turn, so two writers on one file is the
+ * ordinary case here, not the exceptional one; without this a routine overlap surfaces as a
+ * `SQLITE_BUSY` that aborts a turn.
+ */
+const BUSY_TIMEOUT_MS = 5000;
+/** The checkpoint id named by a config, using LangGraph's own precedence (`thread_ts` is legacy). */
+function checkpointIdOf(config) {
+    const configurable = config.configurable;
+    const id = configurable?.checkpoint_id ?? configurable?.thread_ts;
+    return typeof id === 'string' ? id : '';
+}
+/** Read a `configurable` field as a string, or `undefined` when it is absent / not a string. */
+function stringField(config, key) {
+    const value = config.configurable?.[key];
+    return typeof value === 'string' ? value : undefined;
+}
+/**
+ * Narrow one raw SQLite row to {@link CheckpointRow}. Written out rather than cast because
+ * `node:sqlite` types every column as `SQLOutputValue`, so a blanket assertion would also hide a
+ * genuine column/shape mismatch — including the BLOB columns, which are the ones a wrong value
+ * would break silently inside the deserializer rather than here.
+ */
+function toCheckpointRow(row) {
+    return {
+        thread_id: String(row.thread_id),
+        checkpoint_ns: row.checkpoint_ns != null ? String(row.checkpoint_ns) : '',
+        checkpoint_id: String(row.checkpoint_id),
+        parent_checkpoint_id: row.parent_checkpoint_id != null ? String(row.parent_checkpoint_id) : null,
+        type: row.type != null ? String(row.type) : null,
+        checkpoint: row.checkpoint,
+        metadata: row.metadata,
+    };
+}
+/**
+ * A LangGraph `BaseCheckpointSaver` persisting to a `node:sqlite` database.
+ *
+ * Obtain one through {@link openCheckpointSaver}, which is fail-soft; the constructor is private so
+ * there is no way to hold one whose tables were never created.
+ */
+export class GthSqliteSaver extends BaseCheckpointSaver {
+    db;
+    onWriteFailure;
+    /**
+     * GS2-107 — every thread this saver has written to, which is what automatic reclamation excludes.
+     *
+     * The thread a session writes to is not fixed at open: `resetThread()` mints a fresh one on
+     * `/clear` and `resumeConversation` rebinds onto a stored one, and neither tells this object. An
+     * exclusion built from the id the session started with therefore names a thread nobody is writing
+     * and misses the one that is — which on the `/clear` path is a thread no conversation row names,
+     * i.e. exactly a reclamation candidate. Recording the ids as they arrive needs no notification at
+     * all: whatever the runner rotated onto, the write came through here.
+     */
+    writtenThreads = new Set();
+    constructor(db, onWriteFailure) {
+        super();
+        this.db = db;
+        this.onWriteFailure = onWriteFailure ?? (() => { });
+    }
+    /**
+     * Report a dropped write, and never let the reporting itself become the failure. A handler that
+     * throws here would land back inside `agent.invoke()` and end the turn — the exact outcome the
+     * degrade posture exists to avoid, arriving from the code that implements it.
+     */
+    reportWriteFailure(error) {
+        try {
+            this.onWriteFailure(error);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    /**
+     * Open (and lazily initialise) the checkpoint tables at `dbPath`. Returns `null` on any failure —
+     * an unopenable, read-only or corrupt DB — so the caller can fall back to a `MemorySaver` without
+     * a try/catch of its own.
+     */
+    static open(dbPath, options = {}) {
+        let db;
+        try {
+            db = new DatabaseSync(dbPath);
+            // GS2-42's lesson applied here too: SQLite does not validate the file header until the first
+            // statement runs, so a garbage file opens cleanly and fails on the DDL below. Everything from
+            // the constructor to the last `exec` is therefore inside one try, and the handle is closed on
+            // the way out — on win32 an unclosed handle blocks the file from being replaced or reopened
+            // until the process exits.
+            db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`);
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS checkpoints (
+          thread_id TEXT NOT NULL,
+          checkpoint_ns TEXT NOT NULL DEFAULT '',
+          checkpoint_id TEXT NOT NULL,
+          parent_checkpoint_id TEXT,
+          type TEXT,
+          checkpoint BLOB,
+          metadata BLOB,
+          PRIMARY KEY (thread_id, checkpoint_ns, checkpoint_id)
+        );
+        CREATE TABLE IF NOT EXISTS checkpoint_writes (
+          thread_id TEXT NOT NULL,
+          checkpoint_ns TEXT NOT NULL DEFAULT '',
+          checkpoint_id TEXT NOT NULL,
+          task_id TEXT NOT NULL,
+          idx INTEGER NOT NULL,
+          channel TEXT NOT NULL,
+          type TEXT,
+          value BLOB,
+          PRIMARY KEY (thread_id, checkpoint_ns, checkpoint_id, task_id, idx)
+        );
+      `);
+            return new GthSqliteSaver(db, options.onWriteFailure);
+        }
+        catch {
+            try {
+                db?.close();
+            }
+            catch {
+                /* ignore: the connection may already be in a broken state */
+            }
+            return null;
+        }
+    }
+    /** Close the underlying connection (fail-soft). */
+    close() {
+        try {
+            this.db.close();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    /** Rebuild one stored row into the tuple LangGraph reads, pending writes and parent included. */
+    async toTuple(row, config) {
+        const type = row.type ?? 'json';
+        const checkpoint = (await this.serde.loadsTyped(type, row.checkpoint));
+        const metadata = (await this.serde.loadsTyped(type, row.metadata));
+        const writeRows = this.db
+            .prepare(`SELECT task_id, channel, type, value
+           FROM checkpoint_writes
+          WHERE thread_id = ? AND checkpoint_ns = ? AND checkpoint_id = ?
+          ORDER BY task_id ASC, idx ASC`)
+            .all(row.thread_id, row.checkpoint_ns, row.checkpoint_id);
+        const pendingWrites = [];
+        for (const w of writeRows) {
+            pendingWrites.push([
+                String(w.task_id),
+                String(w.channel),
+                await this.serde.loadsTyped(String(w.type ?? 'json'), w.value),
+            ]);
+        }
+        const tuple = { config, checkpoint, metadata, pendingWrites };
+        // The parent link is part of the interface, not optional decoration:
+        // `BaseCheckpointSaver.getDeltaChannelHistory` reconstructs a DELTA channel by walking
+        // `getTuple` → `parentConfig` up the ancestor chain, and a tuple without it terminates that walk
+        // at the first checkpoint.
+        //
+        // **What that costs depends on the state schema, and on THIS graph it costs less than it looks.**
+        // The agent's `messages` channel stores a full array in `channel_values`, not a delta, so every
+        // checkpoint already carries the whole transcript and a broken walk cannot produce the
+        // "transcript present, tool result missing" shape. Dropping the link here reddens the
+        // parent-link test and nothing else — measured, not assumed. The reason to keep returning it is
+        // the conditional one: a state schema that puts any channel behind a binary operator (a reducer
+        // accumulating deltas, which `add_messages` is NOT under the current serialization) would
+        // reconstruct that channel from the ancestor chain, and then a missing parent silently seeds it
+        // empty. Correct now, and load-bearing the moment the schema changes.
+        if (row.parent_checkpoint_id != null) {
+            tuple.parentConfig = {
+                configurable: {
+                    thread_id: row.thread_id,
+                    checkpoint_ns: row.checkpoint_ns,
+                    checkpoint_id: row.parent_checkpoint_id,
+                },
+            };
+        }
+        return tuple;
+    }
+    async getTuple(config) {
+        const threadId = stringField(config, 'thread_id');
+        if (threadId === undefined)
+            return undefined;
+        const checkpointNs = stringField(config, 'checkpoint_ns') ?? '';
+        const checkpointId = checkpointIdOf(config);
+        // Checkpoint ids are uuid6, which sort lexicographically in creation order, so "the latest
+        // checkpoint on this thread" is a plain DESC on the id — the same ordering MemorySaver gets
+        // from sorting its keys.
+        const raw = (checkpointId
+            ? this.db
+                .prepare(`SELECT * FROM checkpoints
+                WHERE thread_id = ? AND checkpoint_ns = ? AND checkpoint_id = ?`)
+                .get(threadId, checkpointNs, checkpointId)
+            : this.db
+                .prepare(`SELECT * FROM checkpoints
+                WHERE thread_id = ? AND checkpoint_ns = ?
+                ORDER BY checkpoint_id DESC
+                LIMIT 1`)
+                .get(threadId, checkpointNs));
+        if (raw === undefined)
+            return undefined;
+        const row = toCheckpointRow(raw);
+        // When the caller named a checkpoint, echo their config back (they may carry other
+        // `configurable` fields); when they asked for the latest, name the one we actually found.
+        const tupleConfig = checkpointId
+            ? config
+            : {
+                configurable: {
+                    thread_id: threadId,
+                    checkpoint_ns: checkpointNs,
+                    checkpoint_id: row.checkpoint_id,
+                },
+            };
+        return this.toTuple(row, tupleConfig);
+    }
+    async *list(config, options) {
+        const { before, limit, filter } = options ?? {};
+        const clauses = [];
+        const params = [];
+        const threadId = stringField(config, 'thread_id');
+        if (threadId !== undefined) {
+            clauses.push('thread_id = ?');
+            params.push(threadId);
+        }
+        const checkpointNs = stringField(config, 'checkpoint_ns');
+        if (checkpointNs !== undefined) {
+            clauses.push('checkpoint_ns = ?');
+            params.push(checkpointNs);
+        }
+        const checkpointId = checkpointIdOf(config);
+        if (checkpointId) {
+            clauses.push('checkpoint_id = ?');
+            params.push(checkpointId);
+        }
+        const beforeId = before ? checkpointIdOf(before) : '';
+        if (beforeId) {
+            clauses.push('checkpoint_id < ?');
+            params.push(beforeId);
+        }
+        const where = clauses.length > 0 ? `WHERE ${clauses.join(' AND ')}` : '';
+        const rows = this.db
+            .prepare(`SELECT * FROM checkpoints
+         ${where}
+         ORDER BY thread_id ASC, checkpoint_ns ASC, checkpoint_id DESC`)
+            .all(...params).map(toCheckpointRow);
+        // `limit` counts rows that SURVIVE `filter`, so it is applied here rather than as SQL LIMIT —
+        // a metadata filter is evaluated on the deserialized object, which SQL cannot see.
+        let remaining = limit;
+        for (const row of rows) {
+            if (remaining !== undefined && remaining <= 0)
+                return;
+            const tuple = await this.toTuple(row, {
+                configurable: {
+                    thread_id: row.thread_id,
+                    checkpoint_ns: row.checkpoint_ns,
+                    checkpoint_id: row.checkpoint_id,
+                },
+            });
+            if (filter) {
+                const metadata = (tuple.metadata ?? {});
+                if (!Object.entries(filter).every(([key, value]) => metadata[key] === value))
+                    continue;
+            }
+            if (remaining !== undefined)
+                remaining -= 1;
+            yield tuple;
+        }
+    }
+    async put(config, checkpoint, metadata, _newVersions) {
+        const threadId = stringField(config, 'thread_id');
+        if (threadId === undefined) {
+            throw new Error('Failed to put checkpoint: the RunnableConfig is missing a "thread_id" in its ' +
+                '"configurable" property. A checkpointer needs a thread_id to know which conversation ' +
+                'to persist state for.');
+        }
+        // Recorded BEFORE the write is attempted, and kept even when it fails. A thread whose write was
+        // dropped is one the degrade path has just marked unresumable, and a live session is still
+        // sitting on it; excluding it costs a delete that the next process's pass will make anyway.
+        this.writtenThreads.add(threadId);
+        const checkpointNs = stringField(config, 'checkpoint_ns') ?? '';
+        try {
+            const [checkpointType, serializedCheckpoint] = await this.serde.dumpsTyped(copyCheckpoint(checkpoint));
+            const [metadataType, serializedMetadata] = await this.serde.dumpsTyped(metadata);
+            if (checkpointType !== metadataType) {
+                throw new Error('Failed to serialize the checkpoint and its metadata to the same type.');
+            }
+            this.db
+                .prepare(`INSERT OR REPLACE INTO checkpoints
+           (thread_id, checkpoint_ns, checkpoint_id, parent_checkpoint_id, type, checkpoint, metadata)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`)
+                .run(threadId, checkpointNs, checkpoint.id, checkpointIdOf(config) || null, checkpointType, serializedCheckpoint, serializedMetadata);
+        }
+        catch (error) {
+            this.reportWriteFailure(error);
+        }
+        // Returned whether or not the row landed, and that is not an oversight. LangGraph takes this
+        // config as the parent of the NEXT super-step, so a failure here leaves the next successful
+        // write pointing at a `parent_checkpoint_id` that was never stored — a chain with a hole in it.
+        // What makes that safe is the handler above, which marks the conversation unresumable on disk:
+        // nothing will ever walk this chain again. Returning a config that names a checkpoint we did
+        // not write is the lesser evil against throwing, which ends the user's session.
+        return {
+            configurable: {
+                thread_id: threadId,
+                checkpoint_ns: checkpointNs,
+                checkpoint_id: checkpoint.id,
+            },
+        };
+    }
+    async putWrites(config, writes, taskId) {
+        const threadId = stringField(config, 'thread_id');
+        if (threadId === undefined) {
+            throw new Error('Failed to put writes: the RunnableConfig is missing a "thread_id" in its ' +
+                '"configurable" property.');
+        }
+        const checkpointId = checkpointIdOf(config);
+        if (!checkpointId) {
+            throw new Error('Failed to put writes: the RunnableConfig is missing a "checkpoint_id" in its ' +
+                '"configurable" property.');
+        }
+        this.writtenThreads.add(threadId);
+        const checkpointNs = stringField(config, 'checkpoint_ns') ?? '';
+        try {
+            // Two statements, chosen per write by the sign of its slot, because the two halves of the
+            // contract differ: an ordinary write (idx >= 0) is insert-ONCE, so a retried super-step
+            // writing the same slot again must leave the first value alone, while a reserved channel
+            // ({@link WRITES_IDX_MAP}) is replace-on-write, so the newest error / interrupt / resume wins.
+            // One blanket `INSERT OR REPLACE` would get the ordinary case wrong and one blanket
+            // `INSERT OR IGNORE` the reserved one, and either divergence is visible only on a resume.
+            const insertOnce = this.db.prepare(`INSERT OR IGNORE INTO checkpoint_writes
+         (thread_id, checkpoint_ns, checkpoint_id, task_id, idx, channel, type, value)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
+            const replace = this.db.prepare(`INSERT OR REPLACE INTO checkpoint_writes
+         (thread_id, checkpoint_ns, checkpoint_id, task_id, idx, channel, type, value)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
+            // **Not wrapped in a transaction, deliberately.** A failure partway through this loop leaves
+            // the earlier writes of the same task committed, which LangGraph tolerates: `putWrites` is
+            // insert-once per (task, idx), so the retry that follows re-writes the same slots and the
+            // survivors are ignored rather than duplicated. A transaction would buy atomicity across the
+            // task's slots at the cost of holding a write lock across `dumpsTyped` — serialization, inside
+            // the lock, on a file the history recorder also opens every turn. That is the trade to revisit
+            // if a reserved-channel write ever has to land atomically with an ordinary one; today none
+            // does. Under the degrade posture a torn task is doubly harmless: the conversation is marked
+            // unresumable, so nothing will read these rows again.
+            for (let position = 0; position < writes.length; position++) {
+                const [channel, value] = writes[position];
+                // `Object.hasOwn`, not a plain index, because a channel name is arbitrary text arriving
+                // from the graph: `WRITES_IDX_MAP['constructor']` resolves up the PROTOTYPE CHAIN to
+                // `Object`, and `toString` / `valueOf` likewise, so a plain read would hand `idx` a function
+                // and take the reserved-vs-positional branch on it. `Object.freeze` does not help — it seals
+                // the own properties and leaves the prototype reachable. Upstream's `WRITES_IDX_MAP` has the
+                // same shape; that is a reason to keep the mirror, not to keep the defect.
+                const reserved = Object.hasOwn(WRITES_IDX_MAP, channel)
+                    ? WRITES_IDX_MAP[channel]
+                    : undefined;
+                const idx = reserved ?? position;
+                const [type, serialized] = await this.serde.dumpsTyped(value);
+                const statement = idx < 0 ? replace : insertOnce;
+                statement.run(threadId, checkpointNs, checkpointId, taskId, idx, channel, type, serialized);
+            }
+        }
+        catch (error) {
+            this.reportWriteFailure(error);
+        }
+    }
+    async deleteThread(threadId) {
+        deleteThreads(this.db, [threadId]);
+    }
+    /**
+     * GS2-107 — delete every thread no conversation row names, past the grace window. The retention
+     * module owns the policy and the reasoning; this is the saver's own connection lent to it, so a
+     * session that already has the store open can reclaim without opening it again.
+     *
+     * **Every thread this saver wrote is excluded, always**, on top of whatever the caller names. A
+     * caller cannot supply that set: the runner rotates threads without telling anyone, so the only
+     * place that knows which thread the session ended on is the object the writes went through. The
+     * union is the contract — `excludeThreadIds` adds to the protection and can never subtract from
+     * it.
+     */
+    reclaimUnresumableThreads(options = {}) {
+        return reclaimUnresumableThreads(this.db, {
+            ...options,
+            excludeThreadIds: [...this.writtenThreads, ...(options.excludeThreadIds ?? [])],
+        });
+    }
+    /** GS2-107 — what the checkpoint tables hold, over this saver's open connection. */
+    storeStats(dbPath, topN) {
+        return collectCheckpointStoreStats(this.db, dbPath, topN);
+    }
+}
+/**
+ * Fail-soft open of the durable checkpoint saver. Returns `null` (never throws) when the DB cannot
+ * be opened or its tables cannot be created.
+ */
+export function openCheckpointSaver(dbPath, options = {}) {
+    return GthSqliteSaver.open(dbPath, options);
+}
+//# sourceMappingURL=checkpointSaver.js.map

package/dist/history/checkpointSaver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpointSaver.js","sourceRoot":"","sources":["../../src/history/checkpointSaver.ts"],"names":[],"mappings":"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"}

package/dist/history/historyEnabled.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @packageDocumentation
+ * GS2-7 (B20) / GS2-20 — the ONE switch governing everything the local history feature persists:
+ * the per-turn session records and the durable LangGraph checkpoints a resume reads back.
+ *
+ * They share a switch rather than getting one each because they are two halves of one promise. A
+ * conversation listed by `gth history list` that cannot be resumed, or a resumable thread with no
+ * listing to find it from, is a state a user has no way to reason about — and a second key would
+ * make both reachable.
+ */
+/** The subset of the resolved config history reads (structural, to avoid a hard type dep). */
+export interface HistoryConfigView {
+    history?: {
+        enabled?: boolean;
+        dbPath?: string;
+    };
+}
+/**
+ * Whether this run persists history. **Absent means ON**: a default run records its turns to the
+ * local store and checkpoints its graph state, both under the user's own `~/.gsloth` dir and
+ * neither leaving the machine.
+ *
+ * `history.enabled: false` is the opt-out and is the only value that turns it off, which is why
+ * this tests against `false` rather than for truthiness — the difference between "absent" and
+ * "explicitly off" is the whole behaviour.
+ */
+export declare function isHistoryEnabled(config: HistoryConfigView | undefined): boolean;

package/dist/history/historyEnabled.js

@@ -0,0 +1,23 @@
+/**
+ * @packageDocumentation
+ * GS2-7 (B20) / GS2-20 — the ONE switch governing everything the local history feature persists:
+ * the per-turn session records and the durable LangGraph checkpoints a resume reads back.
+ *
+ * They share a switch rather than getting one each because they are two halves of one promise. A
+ * conversation listed by `gth history list` that cannot be resumed, or a resumable thread with no
+ * listing to find it from, is a state a user has no way to reason about — and a second key would
+ * make both reachable.
+ */
+/**
+ * Whether this run persists history. **Absent means ON**: a default run records its turns to the
+ * local store and checkpoints its graph state, both under the user's own `~/.gsloth` dir and
+ * neither leaving the machine.
+ *
+ * `history.enabled: false` is the opt-out and is the only value that turns it off, which is why
+ * this tests against `false` rather than for truthiness — the difference between "absent" and
+ * "explicitly off" is the whole behaviour.
+ */
+export function isHistoryEnabled(config) {
+    return config?.history?.enabled !== false;
+}
+//# sourceMappingURL=historyEnabled.js.map

package/dist/history/historyEnabled.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"historyEnabled.js","sourceRoot":"","sources":["../../src/history/historyEnabled.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAqC;IACpE,OAAO,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,KAAK,CAAC;AAC5C,CAAC"}