agentfootprint 7.27.1 → 7.28.0

package/README.md

@@ -562,7 +562,7 @@ Same trick as the injection model: instead of N libraries for N patterns, we fou
 
 > 📖 Compare: [hand-rolled vs declarative](https://footprintjs.github.io/agentfootprint/docs/getting-started/why/) · [migration from LangChain / CrewAI / LangGraph](https://footprintjs.github.io/agentfootprint/docs/getting-started/vs/)
 
-### Check in with the receipts — human consent for consequential actions
+### Check in with the receipts — human-in-the-loop consent for consequential actions
 
 OpenWorker-class agents check in; agentfootprint checks in **with the receipts.** A tool declares `checkIn: 'always'` (or a `(args) => boolean` predicate). When it trips, the run pauses **before** the tool executes and hands back an evidence pack: `willDo` (plain-words claim), `read` (context the run consumed), `drivers` (which context drove the choice, ranked, zero LLM calls), and a compact `trail`. A human answers `checkInApproved({ by })` / `checkInDeclined({ by, note })`; on approve the tool runs, on decline the model sees the note and adapts.
 
@@ -811,7 +811,7 @@ The flowchart, recorders, and tests don't change between dev and prod.
 
 **Operability**
 - Provider-agnostic prompt caching — declarative per-injection, per-iteration marker recomputation
-- Pause / resume — JSON-serializable checkpoints; resume hours later on a different server
+- Human-in-the-loop pause / resume — a tool calls `pauseHere(...)` (or `askHuman(...)`); `isPaused(result)` hands you a JSON-serializable checkpoint, and `agent.resume(checkpoint, input)` continues hours later on a different server
 - Resilience primitives — `withRetry`, `withFallback`, `withCircuitBreaker`, `.outputFallback`, `agent.resumeOnError`
 - 60+ typed observability events — `agent` · `composition` · `context` · `stream` · `tools` · `skill` · `memory` · `cache` · `cost` · `permission` · `eval` · `embedding` · `pause` · `error` · `fallback` · `resilience` · `reliability` · `risk`
 

package/dist/esm/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/esm/hosting/index.js

@@ -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.
@@ -76,6 +83,7 @@
 export { nodeHost, jsonWire } from './nodeHost.js';
 export { httpHost, headerValue } from './httpHost.js';
 export { memorySessions } from './memorySessions.js';
+export { sqliteSessions, SqliteUnavailableError, UnreadableSessionFileError, } 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/esm/hosting/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/hosting/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AAEH,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGnD,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAWtD,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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/hosting/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiFG;AAEH,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGnD,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAWtD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC;AAK7B,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"}

package/dist/esm/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/esm/hosting/memorySessions.js

@@ -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.
  */
 /**
  * An in-process session store.

package/dist/esm/hosting/memorySessions.js.map

@@ -1 +1 @@
-{"version":3,"file":"memorySessions.js","sourceRoot":"","sources":["../../../src/hosting/memorySessions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH;;;;;;GAMG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,MAAM,GAAG,IAAI,GAAG,EAA8B,CAAC;IACrD,OAAO;QACL,OAAO,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC9D,OAAO,EAAE,CAAC,SAAS,EAAE,QAAQ,EAAE,EAAE;YAC/B,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;YAChC,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"memorySessions.js","sourceRoot":"","sources":["../../../src/hosting/memorySessions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH;;;;;;GAMG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,MAAM,GAAG,IAAI,GAAG,EAA8B,CAAC;IACrD,OAAO;QACL,OAAO,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC9D,OAAO,EAAE,CAAC,SAAS,EAAE,QAAQ,EAAE,EAAE;YAC/B,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;YAChC,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;KACF,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,211 @@
+/**
+ * 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;