agentfootprint 7.27.1 → 7.28.0

package/dist/hosting/sqliteSessions.js

@@ -0,0 +1,376 @@
+"use strict";
+/**
+ * hosting/sqliteSessions — conversations in a file, so a restart is not an
+ * amnesia event.
+ *
+ * `memorySessions()` keeps conversations in a `Map` and says what that costs in
+ * its own docstring: restart the process and every conversation is gone. Until
+ * now the next step up was "bring a Redis", and the step between those two —
+ * *one machine, one file, nothing to install* — was a store every consumer had
+ * to write for themselves. This is that store.
+ *
+ * A paused run was in the same position from the other direction. `agent.run()`
+ * hands back a checkpoint that is documented as JSON you can keep anywhere, and
+ * "anywhere" was the whole of the offer: the library named a shape and left the
+ * keeping to you. Both halves land in the same table here, because
+ * {@link CheckpointEnvelope} was already a union of the two and a session store
+ * has no business caring which one it is holding.
+ *
+ * ── What this is, said plainly ──────────────────────────────────────────────
+ * **One process on one machine, writing one file.** That is the whole claim,
+ * and it is worth stating as a ceiling rather than leaving it to be discovered:
+ *
+ *   • It survives a restart, a crash, a deploy — anything that ends the process
+ *     and leaves the disk alone.
+ *   • It is NOT a distributed store. Two machines do not share a session by
+ *     both opening this file over a network filesystem, and nothing here tries
+ *     to make that work.
+ *   • WAL lets readers and one writer run at once, and **one writer at a time
+ *     is the ceiling** — a second writer waits for the lock up to
+ *     `busyTimeoutMs` and then fails loudly rather than queueing forever.
+ *     Several processes on one box is fine at that scale; a fleet is not what
+ *     this is.
+ *
+ * When you outgrow it you swap the one argument to `standingAgent`, which is
+ * the entire point of the port.
+ *
+ * ── Zero dependencies, and the version floor that buys ──────────────────────
+ * SQLite is *inside Node* — `node:sqlite`, no install, no native build, no
+ * peer dependency. The price is a version floor this package does not otherwise
+ * have: the module ships with Node 22.5 and newer. Rather than raise `engines`
+ * for one optional adapter and break every consumer on Node 20, the module is
+ * loaded when you actually construct a store, and its absence is refused by
+ * name with the version you are on and what to do about it — see
+ * {@link SqliteUnavailableError}. There is deliberately **no fallback to
+ * memory**: a store that silently forgot everything on restart is
+ * indistinguishable, from the outside, from a brand-new user.
+ *
+ * ── The two laws it inherits rather than re-implements ──────────────────────
+ * `checkEnvelope` is called on the way out AND on the way in, so an envelope
+ * whose `format` this runtime does not know is refused by name, and a stored
+ * session that is PRESENT but unreadable is refused by name too. Only a session
+ * that was never written hydrates as `undefined`. Validating on the way in as
+ * well is the cheap half of that promise: a row this store could not read back
+ * never gets written in the first place.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sqliteSessions = exports.UnreadableSessionFileError = exports.SqliteUnavailableError = void 0;
+const envelope_js_1 = require("./envelope.js");
+const errors_js_1 = require("./errors.js");
+const lazyRequire_js_1 = require("../lib/lazyRequire.js");
+// ─── The refusals ────────────────────────────────────────────────────
+/**
+ * Raised when `node:sqlite` is not available in the running Node.
+ *
+ * Node 20 does not have the module at all; Node 22.5 through 22.12 have it
+ * behind `--experimental-sqlite`; Node 22.13+ and 23.4+ have it as-is (still
+ * marked experimental by Node, which is why it prints a warning on first use).
+ *
+ * The refusal names the version you are on and the three ways out, because
+ * "cannot find module 'node:sqlite'" out of a library's guts tells you what
+ * broke and nothing about what to do.
+ */
+class SqliteUnavailableError extends Error {
+    code = 'ERR_SQLITE_UNAVAILABLE';
+    /** The Node version this process is running. */
+    nodeVersion;
+    constructor(nodeVersion, reason) {
+        super(`[hosting] sqliteSessions() needs Node's built-in 'node:sqlite' module, and this ` +
+            `process (Node ${nodeVersion}) does not have it (${reason}). ` +
+            `That module ships with Node 22.5 and newer: on Node 22.13+ (and 23.4+) it is ` +
+            `available as-is, and on Node 22.5–22.12 it is behind --experimental-sqlite. ` +
+            `So: upgrade Node, add that flag, or use memorySessions() — which keeps ` +
+            `conversations in a Map and loses them on restart, and says so in its name. ` +
+            `This refuses rather than falling back to memory on your behalf: a store that ` +
+            `silently forgot every conversation on restart looks, from the outside, exactly ` +
+            `like a brand-new user.`);
+        this.name = 'SqliteUnavailableError';
+        this.nodeVersion = nodeVersion;
+    }
+}
+exports.SqliteUnavailableError = SqliteUnavailableError;
+/**
+ * Raised when the file exists but this runtime cannot use it as a session
+ * store.
+ *
+ * The same law {@link UnreadableEnvelopeError} states for one stored value,
+ * one level up: **an unreadable store and an empty one are different facts, and
+ * only one of them is safe to answer with a fresh start.** A store that opened
+ * a corrupt file as an empty database would hand every returning user a blank
+ * slate and log nothing.
+ *
+ * `problem` is the fact to branch on — the three cases need different actions:
+ *
+ *  - `'cannot-open'` — not a SQLite database, or not readable (permissions, a
+ *    directory, a truncated file).
+ *  - `'not-our-schema'` — a database whose `agent_sessions` table is somebody
+ *    else's table of that name. Point the store at its own file.
+ *  - `'newer-schema'` — written by a newer agentfootprint than this one. Same
+ *    answer the envelope `format` field gives: refuse, never half-read.
+ */
+class UnreadableSessionFileError extends Error {
+    code = 'ERR_UNREADABLE_SESSION_FILE';
+    /** The file that was refused. */
+    file;
+    /** Which of the three cases this is. */
+    problem;
+    constructor(file, problem, detail) {
+        super(`[hosting] the session store at '${file}' cannot be used: ${detail} ` +
+            `An unreadable store and an empty one are different facts, and only one of them ` +
+            `is safe to answer with a fresh start — so this refuses rather than quietly ` +
+            `beginning every conversation again on top of a file that already exists. ` +
+            (problem === 'newer-schema'
+                ? `A store written by a newer agentfootprint needs a runtime that knows that ` +
+                    `schema; roll forward, or point this one at its own file.`
+                : problem === 'not-our-schema'
+                    ? `Give the store a file of its own rather than sharing one with tables of ` +
+                        `the same name.`
+                    : `Check the path and its permissions, or move the file aside to start a ` + `new one.`));
+        this.name = 'UnreadableSessionFileError';
+        this.file = file;
+        this.problem = problem;
+    }
+}
+exports.UnreadableSessionFileError = UnreadableSessionFileError;
+// ─── The schema ──────────────────────────────────────────────────────
+/**
+ * What this runtime writes. Bumped only for a change an older reader could not
+ * survive — and an older reader meeting a newer number refuses by name rather
+ * than reading what it half-understands, which is the same rule the envelope's
+ * `format` field follows.
+ */
+const SCHEMA_VERSION = 1;
+const SESSIONS_TABLE = 'agent_sessions';
+const META_TABLE = 'agent_store_meta';
+/**
+ * `format` and `saved_at` are COLUMNS as well as fields inside the JSON, and
+ * that redundancy is deliberate: it makes the file answer "which sessions are
+ * waiting on a person, and since when?" from the `sqlite3` command line during
+ * an incident, without a JSON parser and without this library. A store you
+ * cannot inspect with the tools already on the box is a store you debug by
+ * guessing.
+ */
+const SESSIONS_COLUMNS = ['session_id', 'format', 'saved_at', 'envelope'];
+// ─── The store ───────────────────────────────────────────────────────
+/**
+ * A session store in one SQLite file — the battery-included place to keep a
+ * conversation, or a run that stopped to ask a person something, so that a
+ * restart does not lose it.
+ *
+ * @throws SqliteUnavailableError when the running Node has no `node:sqlite`.
+ * @throws UnreadableSessionFileError when the file exists but cannot be used —
+ *   never answered with an empty store.
+ *
+ * @example  A standing agent whose conversations survive a restart
+ *   import { standingAgent, nodeHost, sqliteSessions } from 'agentfootprint/hosting';
+ *
+ *   const handle = await standingAgent({
+ *     agent,
+ *     sessions: sqliteSessions({ file: './sessions.db' }),
+ *     host: nodeHost({ port: 8080 }),
+ *   });
+ *
+ * @example  Keeping a paused run yourself, without the composer
+ *   const sessions = sqliteSessions({ file: './sessions.db' });
+ *   const out = await agent.run({ message });
+ *   if (isPaused(out)) {
+ *     await sessions.persist(sessionId, toPausedEnvelope({
+ *       checkpoint: out.checkpoint,
+ *       conversation: agent.checkpoint()!,
+ *       pending: { pauseData: out.pauseData },
+ *     }));
+ *   }
+ *   // …a deploy later, in a new process:
+ *   const paused = readPausedRun(await sessions.hydrate(sessionId));
+ *   const answer = await agent.resume(paused.checkpoint, decision);
+ */
+function sqliteSessions(options) {
+    const { file, busyTimeoutMs = 5000 } = options;
+    if (file === ':memory:' || file.trim() === '') {
+        throw new TypeError(`[hosting] sqliteSessions({ file: '${file}' }) is not a durable store. ` +
+            `':memory:' looks like a file and keeps nothing across a restart, which is the ` +
+            `one thing this adapter exists to do. Use memorySessions() when an in-process ` +
+            `store is what you want — it says so in its name — or give this one a real path.`);
+    }
+    const DatabaseSync = options._sqlite ?? loadSqlite();
+    ensureParentDirectory(file);
+    let db;
+    try {
+        db = new DatabaseSync(file);
+    }
+    catch (err) {
+        throw new UnreadableSessionFileError(file, 'cannot-open', `${describe(err)}.`);
+    }
+    let journalMode;
+    try {
+        journalMode = applyPragmas(db, busyTimeoutMs);
+        ensureSchema(db, file);
+    }
+    catch (err) {
+        db.close();
+        if (err instanceof UnreadableSessionFileError)
+            throw err;
+        throw new UnreadableSessionFileError(file, 'cannot-open', `${describe(err)}.`);
+    }
+    const insert = db.prepare(`INSERT INTO ${SESSIONS_TABLE} (session_id, format, saved_at, envelope) VALUES (?, ?, ?, ?) ` +
+        `ON CONFLICT(session_id) DO UPDATE SET format = excluded.format, ` +
+        `saved_at = excluded.saved_at, envelope = excluded.envelope`);
+    const select = db.prepare(`SELECT envelope FROM ${SESSIONS_TABLE} WHERE session_id = ?`);
+    const remove = db.prepare(`DELETE FROM ${SESSIONS_TABLE} WHERE session_id = ?`);
+    let closed = false;
+    const open = (verb) => {
+        if (closed) {
+            throw new Error(`[hosting] the sqliteSessions store at '${file}' is closed, so it cannot ${verb}. ` +
+                `close() is final by design — reopening the file behind you would hide a ` +
+                `shutdown-ordering bug rather than surface it. Build a new store if you need ` +
+                `one after closing this.`);
+        }
+    };
+    // The three port methods are `async` so that every refusal in them arrives
+    // as a REJECTION. A method that returns a promise on the happy path and
+    // throws synchronously on the sad one is a method whose callers need two
+    // error handlers, and the one they forget is the one that fires at 3am.
+    return {
+        journalMode,
+        // eslint-disable-next-line @typescript-eslint/require-await
+        async hydrate(sessionId) {
+            open('hydrate a session');
+            const row = select.get(sessionId);
+            if (row === undefined)
+                return undefined;
+            const stored = row.envelope;
+            if (typeof stored !== 'string') {
+                // A row exists and its payload is not even text. Present, unreadable —
+                // and specifically NOT `undefined`.
+                throw new errors_js_1.UnreadableEnvelopeError(stored, sessionId);
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(stored);
+            }
+            catch {
+                // Bytes written by something that was not this store. Same fact, same
+                // refusal: a conversation EXISTS here and this runtime cannot see it.
+                throw new errors_js_1.UnreadableEnvelopeError(stored, sessionId);
+            }
+            // Validate HERE as well as in the composer, so the refusal points at the
+            // store that produced the bytes rather than at whoever read them next.
+            return (0, envelope_js_1.checkEnvelope)(parsed, sessionId);
+        },
+        // eslint-disable-next-line @typescript-eslint/require-await
+        async persist(sessionId, envelope) {
+            open('persist a session');
+            // Checked on the way IN as well as out: a row this store could not read
+            // back is a row it has no business writing.
+            const checked = (0, envelope_js_1.checkEnvelope)(envelope, sessionId);
+            insert.run(sessionId, checked.format, checked.savedAt, JSON.stringify(checked));
+        },
+        // eslint-disable-next-line @typescript-eslint/require-await
+        async forget(sessionId) {
+            open('forget a session');
+            remove.run(sessionId);
+        },
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            db.close();
+        },
+    };
+}
+exports.sqliteSessions = sqliteSessions;
+// ─── Internals ───────────────────────────────────────────────────────
+/**
+ * Load `node:sqlite`, or refuse by name.
+ *
+ * `lazyRequire` keeps the specifier away from bundler static analysis, so
+ * importing `agentfootprint/hosting` costs nothing for the consumers — the vast
+ * majority — who never construct one of these.
+ */
+function loadSqlite() {
+    try {
+        const mod = (0, lazyRequire_js_1.lazyRequire)('node:sqlite');
+        if (typeof mod?.DatabaseSync !== 'function') {
+            throw new Error('the module loaded but has no DatabaseSync');
+        }
+        return mod.DatabaseSync;
+    }
+    catch (err) {
+        throw new SqliteUnavailableError(nodeVersion(), describe(err));
+    }
+}
+/** The version string, without assuming `process` exists. */
+function nodeVersion() {
+    return typeof process !== 'undefined' && typeof process.version === 'string'
+        ? process.version
+        : 'unknown';
+}
+/**
+ * Create the file's directory if it is missing — "no infrastructure" should not
+ * mean "except for one `mkdir`". A failure here is left to the open call, which
+ * reports it with the path in the same words as every other open failure.
+ */
+function ensureParentDirectory(file) {
+    try {
+        const { mkdirSync } = (0, lazyRequire_js_1.lazyRequire)('node:fs');
+        const { dirname } = (0, lazyRequire_js_1.lazyRequire)('node:path');
+        mkdirSync(dirname(file), { recursive: true });
+    }
+    catch {
+        /* Reported by the open below, with the path and the real reason. */
+    }
+}
+/**
+ * Set the file up for concurrent use and report what it actually got.
+ *
+ * `journal_mode` is the first statement executed on purpose: it is the point at
+ * which SQLite reads the file header, so "this is not a database" surfaces here,
+ * at construction, where the caller can still do something about it — rather
+ * than on the first request of the night.
+ */
+function applyPragmas(db, busyTimeoutMs) {
+    const row = db.prepare('PRAGMA journal_mode = WAL').get();
+    // A pragma takes a literal, not a bound parameter, so the number is coerced
+    // to one before it reaches the statement rather than trusted to be one.
+    const waitMs = Number.isFinite(busyTimeoutMs) ? Math.max(0, Math.floor(busyTimeoutMs)) : 5000;
+    db.exec(`PRAGMA busy_timeout = ${waitMs}`);
+    // NORMAL, not FULL: with WAL that is durable across a process crash — which
+    // is what this store promises — and it does not pay a disk sync per turn.
+    // A power cut can still cost the most recent commits; a fleet-grade store is
+    // the answer to that, not a pragma.
+    db.exec('PRAGMA synchronous = NORMAL');
+    return typeof row?.journal_mode === 'string' ? row.journal_mode : 'unknown';
+}
+/** Create the two tables if they are missing, and refuse a file that is not ours. */
+function ensureSchema(db, file) {
+    db.exec(`CREATE TABLE IF NOT EXISTS ${SESSIONS_TABLE} (` +
+        `session_id TEXT PRIMARY KEY, format TEXT NOT NULL, ` +
+        `saved_at INTEGER NOT NULL, envelope TEXT NOT NULL) STRICT`);
+    db.exec(`CREATE TABLE IF NOT EXISTS ${META_TABLE} (key TEXT PRIMARY KEY, value TEXT NOT NULL) STRICT`);
+    // `CREATE TABLE IF NOT EXISTS` succeeds against somebody else's table of the
+    // same name, and the failure would otherwise arrive as a confusing constraint
+    // error on the first write.
+    const columns = db.prepare(`PRAGMA table_info('${SESSIONS_TABLE}')`).all().map((c) => String(c.name));
+    const missing = SESSIONS_COLUMNS.filter((name) => !columns.includes(name));
+    if (missing.length > 0) {
+        throw new UnreadableSessionFileError(file, 'not-our-schema', `it has a '${SESSIONS_TABLE}' table that is not this store's ` +
+            `(missing ${missing.join(', ')}; found ${columns.join(', ') || 'nothing'}).`);
+    }
+    const stored = db
+        .prepare(`SELECT value FROM ${META_TABLE} WHERE key = 'schema_version'`)
+        .get();
+    if (stored === undefined) {
+        db.prepare(`INSERT INTO ${META_TABLE} (key, value) VALUES ('schema_version', ?)`).run(String(SCHEMA_VERSION));
+        return;
+    }
+    const found = Number(stored.value);
+    if (!Number.isFinite(found) || found > SCHEMA_VERSION) {
+        throw new UnreadableSessionFileError(file, 'newer-schema', `it was written with schema version ${String(stored.value)} and this runtime ` +
+            `reads version ${SCHEMA_VERSION}.`);
+    }
+}
+/** One sentence about a thrown thing, for a message that has to stay readable. */
+function describe(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=sqliteSessions.js.map

package/dist/hosting/sqliteSessions.js.map

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

package/dist/types/hosting/index.d.ts

@@ -50,6 +50,13 @@
  *     purpose: hiding a cap inside auto-chunking decides a protocol question
  *     for every consumer at once.
  *   • `memorySessions()` — conversations in a Map, for tests and local dev.
+ *   • `sqliteSessions({ file })` — the same port, in a file, so a restart is not
+ *     an amnesia event. Conversations AND runs paused waiting on a person, in
+ *     one table, on Node's built-in `node:sqlite` — nothing to install and no
+ *     peer dependency. One machine, one file, one writer at a time is the
+ *     stated ceiling; it is not a distributed store. Refuses BY NAME on a Node
+ *     without `node:sqlite` rather than falling back to memory, because a store
+ *     that silently forgot everything looks exactly like a new user.
  *   • `standingAgent({ agent, sessions, host, durability? })` — the composer.
  *   • `toEnvelope` / `readEnvelope` — pack a conversation, and refuse by name to
  *     unpack a format this runtime does not know.
@@ -78,6 +85,8 @@ export type { NodeHost, NodeHostHandle, NodeHostOptions } from './nodeHost.js';
 export { httpHost, headerValue } from './httpHost.js';
 export type { ConversationHandshake, HandshakeFacts, HttpHost, HttpHostHandle, HttpHostOptions, HttpRequestFacts, HttpWire, } from './httpHost.js';
 export { memorySessions } from './memorySessions.js';
+export { sqliteSessions, SqliteUnavailableError, UnreadableSessionFileError, } from './sqliteSessions.js';
+export type { SqliteSessions, SqliteSessionsOptions } from './sqliteSessions.js';
 export { toEnvelope, toPausedEnvelope, readEnvelope, readPausedRun, checkEnvelope, } from './envelope.js';
 export { standingAgent } from './standingAgent.js';
 export { requireCapability, HostClosedError, ConcurrentRunError, PauseNotCarriedError, AwaitingDecisionError, NoPendingAskError, UnreadableEnvelopeError, ConversationClosedError, FrameTooLargeError, } from './errors.js';

package/dist/types/hosting/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/hosting/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AAEH,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACnD,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAE/E,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACtD,YAAY,EACV,qBAAqB,EACrB,cAAc,EACd,QAAQ,EACR,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,QAAQ,GACT,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,uBAAuB,EACvB,uBAAuB,EACvB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,SAAS,EACT,kBAAkB,EAClB,sBAAsB,EACtB,iBAAiB,EACjB,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,WAAW,EACX,SAAS,EACT,WAAW,EACX,SAAS,EACT,iBAAiB,EACjB,UAAU,EACV,gBAAgB,EAChB,oBAAoB,EACpB,WAAW,EACX,UAAU,GACX,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/hosting/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiFG;AAEH,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACnD,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAE/E,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACtD,YAAY,EACV,qBAAqB,EACrB,cAAc,EACd,QAAQ,EACR,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,QAAQ,GACT,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC;AAI7B,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjF,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,uBAAuB,EACvB,uBAAuB,EACvB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,SAAS,EACT,kBAAkB,EAClB,sBAAsB,EACtB,iBAAiB,EACjB,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,WAAW,EACX,SAAS,EACT,WAAW,EACX,SAAS,EACT,iBAAiB,EACjB,UAAU,EACV,gBAAgB,EAChB,oBAAoB,EACpB,WAAW,EACX,UAAU,GACX,MAAM,YAAY,CAAC"}

package/dist/types/hosting/memorySessions.d.ts

@@ -10,6 +10,9 @@
  * — which is also how the "a crashed process resumes the conversation" test is
  * written: keep the store, throw away everything else, and watch the
  * conversation come back through the envelope alone.
+ *
+ * The next step up ships beside this one: `sqliteSessions({ file })` is the same
+ * port in a file, with nothing to install.
  */
 import type { SessionLifecycle } from './types.js';
 /**

package/dist/types/hosting/memorySessions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memorySessions.d.ts","sourceRoot":"","sources":["../../../src/hosting/memorySessions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEvE;;;;;;GAMG;AACH,wBAAgB,cAAc,IAAI,gBAAgB,CASjD"}
+{"version":3,"file":"memorySessions.d.ts","sourceRoot":"","sources":["../../../src/hosting/memorySessions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEvE;;;;;;GAMG;AACH,wBAAgB,cAAc,IAAI,gBAAgB,CASjD"}

package/dist/types/hosting/sqliteSessions.d.ts

@@ -0,0 +1,212 @@
+/**
+ * hosting/sqliteSessions — conversations in a file, so a restart is not an
+ * amnesia event.
+ *
+ * `memorySessions()` keeps conversations in a `Map` and says what that costs in
+ * its own docstring: restart the process and every conversation is gone. Until
+ * now the next step up was "bring a Redis", and the step between those two —
+ * *one machine, one file, nothing to install* — was a store every consumer had
+ * to write for themselves. This is that store.
+ *
+ * A paused run was in the same position from the other direction. `agent.run()`
+ * hands back a checkpoint that is documented as JSON you can keep anywhere, and
+ * "anywhere" was the whole of the offer: the library named a shape and left the
+ * keeping to you. Both halves land in the same table here, because
+ * {@link CheckpointEnvelope} was already a union of the two and a session store
+ * has no business caring which one it is holding.
+ *
+ * ── What this is, said plainly ──────────────────────────────────────────────
+ * **One process on one machine, writing one file.** That is the whole claim,
+ * and it is worth stating as a ceiling rather than leaving it to be discovered:
+ *
+ *   • It survives a restart, a crash, a deploy — anything that ends the process
+ *     and leaves the disk alone.
+ *   • It is NOT a distributed store. Two machines do not share a session by
+ *     both opening this file over a network filesystem, and nothing here tries
+ *     to make that work.
+ *   • WAL lets readers and one writer run at once, and **one writer at a time
+ *     is the ceiling** — a second writer waits for the lock up to
+ *     `busyTimeoutMs` and then fails loudly rather than queueing forever.
+ *     Several processes on one box is fine at that scale; a fleet is not what
+ *     this is.
+ *
+ * When you outgrow it you swap the one argument to `standingAgent`, which is
+ * the entire point of the port.
+ *
+ * ── Zero dependencies, and the version floor that buys ──────────────────────
+ * SQLite is *inside Node* — `node:sqlite`, no install, no native build, no
+ * peer dependency. The price is a version floor this package does not otherwise
+ * have: the module ships with Node 22.5 and newer. Rather than raise `engines`
+ * for one optional adapter and break every consumer on Node 20, the module is
+ * loaded when you actually construct a store, and its absence is refused by
+ * name with the version you are on and what to do about it — see
+ * {@link SqliteUnavailableError}. There is deliberately **no fallback to
+ * memory**: a store that silently forgot everything on restart is
+ * indistinguishable, from the outside, from a brand-new user.
+ *
+ * ── The two laws it inherits rather than re-implements ──────────────────────
+ * `checkEnvelope` is called on the way out AND on the way in, so an envelope
+ * whose `format` this runtime does not know is refused by name, and a stored
+ * session that is PRESENT but unreadable is refused by name too. Only a session
+ * that was never written hydrates as `undefined`. Validating on the way in as
+ * well is the cheap half of that promise: a row this store could not read back
+ * never gets written in the first place.
+ */
+import type { SessionLifecycle } from './types.js';
+/** One prepared statement, as this adapter calls it. */
+export interface SqliteStatementLike {
+    run(...params: readonly unknown[]): unknown;
+    get(...params: readonly unknown[]): unknown;
+    all(...params: readonly unknown[]): unknown[];
+}
+/** One open database, as this adapter calls it. */
+export interface SqliteDatabaseLike {
+    exec(sql: string): void;
+    prepare(sql: string): SqliteStatementLike;
+    close(): void;
+}
+/**
+ * The shape of `node:sqlite` this adapter needs — declared locally, the same
+ * way every other adapter here declares the slice of its backend it uses, so
+ * nothing takes a hard import on a module that does not exist on every
+ * supported Node.
+ */
+export interface SqliteModuleLike {
+    new (path: string): SqliteDatabaseLike;
+}
+/** Options for {@link sqliteSessions}. */
+export interface SqliteSessionsOptions {
+    /**
+     * The database file. Created if it does not exist, along with its parent
+     * directory — "no infrastructure" would be a thin promise if you still had to
+     * `mkdir` first.
+     *
+     * `':memory:'` is refused: it looks like a file, keeps nothing across a
+     * restart, and a store that quietly forgets is the exact failure this adapter
+     * exists to remove. Use `memorySessions()` when that is what you want — it
+     * says so in its name.
+     */
+    readonly file: string;
+    /**
+     * How long a write waits for another writer's lock before failing, in
+     * milliseconds. Default 5000.
+     *
+     * It fails rather than waits forever on purpose: a request hung on a lock
+     * looks exactly like a slow model, and the two need different fixes.
+     */
+    readonly busyTimeoutMs?: number;
+    /**
+     * @internal Test seam only — the `node:sqlite` module, injected. Lets the
+     * suite exercise the refusal path on a Node that HAS the module, and the
+     * failure paths without corrupting a real file. Not public API, not
+     * supported, and not a place to plug in another SQLite driver.
+     */
+    readonly _sqlite?: SqliteModuleLike;
+}
+/**
+ * A session store in a file.
+ *
+ * It is a {@link SessionLifecycle} plus the three things a real store owns
+ * beyond the port — closing, forgetting, and telling you what the file actually
+ * got — because the port deliberately asks for only two methods and leaves the
+ * rest to whoever implements it.
+ */
+export interface SqliteSessions extends SessionLifecycle {
+    /**
+     * The journalling mode the file **actually has**, read back from SQLite
+     * rather than assumed from what was asked for.
+     *
+     * It is normally `'wal'`. It is something else when the file lives somewhere
+     * WAL cannot work — a network filesystem is the usual reason — and that is a
+     * fact worth being able to read: the store still works, with one writer *or*
+     * one reader at a time instead of both. A silent downgrade is the kind of
+     * thing that is only ever discovered under load.
+     */
+    readonly journalMode: string;
+    /** Forget one session. No-op if there is nothing stored for it. */
+    forget(sessionId: string): Promise<void>;
+    /**
+     * Close the file. Idempotent — a shutdown hook and an explicit close can
+     * coexist. Reading or writing afterwards refuses by name rather than
+     * reopening behind your back.
+     */
+    close(): void;
+}
+/**
+ * Raised when `node:sqlite` is not available in the running Node.
+ *
+ * Node 20 does not have the module at all; Node 22.5 through 22.12 have it
+ * behind `--experimental-sqlite`; Node 22.13+ and 23.4+ have it as-is (still
+ * marked experimental by Node, which is why it prints a warning on first use).
+ *
+ * The refusal names the version you are on and the three ways out, because
+ * "cannot find module 'node:sqlite'" out of a library's guts tells you what
+ * broke and nothing about what to do.
+ */
+export declare class SqliteUnavailableError extends Error {
+    readonly code: "ERR_SQLITE_UNAVAILABLE";
+    /** The Node version this process is running. */
+    readonly nodeVersion: string;
+    constructor(nodeVersion: string, reason: string);
+}
+/**
+ * Raised when the file exists but this runtime cannot use it as a session
+ * store.
+ *
+ * The same law {@link UnreadableEnvelopeError} states for one stored value,
+ * one level up: **an unreadable store and an empty one are different facts, and
+ * only one of them is safe to answer with a fresh start.** A store that opened
+ * a corrupt file as an empty database would hand every returning user a blank
+ * slate and log nothing.
+ *
+ * `problem` is the fact to branch on — the three cases need different actions:
+ *
+ *  - `'cannot-open'` — not a SQLite database, or not readable (permissions, a
+ *    directory, a truncated file).
+ *  - `'not-our-schema'` — a database whose `agent_sessions` table is somebody
+ *    else's table of that name. Point the store at its own file.
+ *  - `'newer-schema'` — written by a newer agentfootprint than this one. Same
+ *    answer the envelope `format` field gives: refuse, never half-read.
+ */
+export declare class UnreadableSessionFileError extends Error {
+    readonly code: "ERR_UNREADABLE_SESSION_FILE";
+    /** The file that was refused. */
+    readonly file: string;
+    /** Which of the three cases this is. */
+    readonly problem: 'cannot-open' | 'not-our-schema' | 'newer-schema';
+    constructor(file: string, problem: UnreadableSessionFileError['problem'], detail: string);
+}
+/**
+ * A session store in one SQLite file — the battery-included place to keep a
+ * conversation, or a run that stopped to ask a person something, so that a
+ * restart does not lose it.
+ *
+ * @throws SqliteUnavailableError when the running Node has no `node:sqlite`.
+ * @throws UnreadableSessionFileError when the file exists but cannot be used —
+ *   never answered with an empty store.
+ *
+ * @example  A standing agent whose conversations survive a restart
+ *   import { standingAgent, nodeHost, sqliteSessions } from 'agentfootprint/hosting';
+ *
+ *   const handle = await standingAgent({
+ *     agent,
+ *     sessions: sqliteSessions({ file: './sessions.db' }),
+ *     host: nodeHost({ port: 8080 }),
+ *   });
+ *
+ * @example  Keeping a paused run yourself, without the composer
+ *   const sessions = sqliteSessions({ file: './sessions.db' });
+ *   const out = await agent.run({ message });
+ *   if (isPaused(out)) {
+ *     await sessions.persist(sessionId, toPausedEnvelope({
+ *       checkpoint: out.checkpoint,
+ *       conversation: agent.checkpoint()!,
+ *       pending: { pauseData: out.pauseData },
+ *     }));
+ *   }
+ *   // …a deploy later, in a new process:
+ *   const paused = readPausedRun(await sessions.hydrate(sessionId));
+ *   const answer = await agent.resume(paused.checkpoint, decision);
+ */
+export declare function sqliteSessions(options: SqliteSessionsOptions): SqliteSessions;
+//# sourceMappingURL=sqliteSessions.d.ts.map

package/dist/types/hosting/sqliteSessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqliteSessions.d.ts","sourceRoot":"","sources":["../../../src/hosting/sqliteSessions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAKH,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAIvE,wDAAwD;AACxD,MAAM,WAAW,mBAAmB;IAClC,GAAG,CAAC,GAAG,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC;IAC5C,GAAG,CAAC,GAAG,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC;IAC5C,GAAG,CAAC,GAAG,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC;CAC/C;AAED,mDAAmD;AACnD,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,CAAC;IAC1C,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,IAAI,EAAE,MAAM,GAAG,kBAAkB,CAAC;CACxC;AAID,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;OASG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAe,SAAQ,gBAAgB;IACtD;;;;;;;;;OASG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,mEAAmE;IACnE,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC;;;;OAIG;IACH,KAAK,IAAI,IAAI,CAAC;CACf;AAID;;;;;;;;;;GAUG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,IAAI,2BAAqC;IAClD,gDAAgD;IAChD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAEjB,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAehD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,QAAQ,CAAC,IAAI,gCAA0C;IACvD,iCAAiC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wCAAwC;IACxC,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,gBAAgB,GAAG,cAAc,CAAC;gBAExD,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,0BAA0B,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,MAAM;CAkBzF;AA2BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,cAAc,CAyG7E"}