@statelyai/agent 2.0.0-alpha.11 → 2.0.0-alpha.13

package/dist/sqlite.cjs

@@ -0,0 +1,135 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_event_log_store = require("./event-log-store-CNT_7F0V.cjs");
+//#region src/sqlite/index.ts
+function openDatabase(path) {
+	const sqlite = process.getBuiltinModule?.("node:sqlite");
+	if (!sqlite?.DatabaseSync) throw new Error("createSqlite*Store: 'node:sqlite' is unavailable in this runtime; Node >= 22.18 is required.");
+	return new sqlite.DatabaseSync(path);
+}
+function quoteIdentifier(name) {
+	if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) throw new Error(`Invalid SQLite table name '${name}': use letters, digits, and underscores only.`);
+	return `"${name}"`;
+}
+function resolveDatabase(database) {
+	return typeof database === "string" ? {
+		db: openDatabase(database),
+		owned: true
+	} : {
+		db: database,
+		owned: false
+	};
+}
+/**
+* An {@link AgentEventLogStore} on one SQLite table, keyed by
+* `(thread_id, idx)` with a unique `(thread_id, entry_id)` index. Entries are
+* stored as JSON text, so reads and writes are deep copies by construction.
+* `append` runs its length check and inserts inside one `BEGIN IMMEDIATE`
+* transaction: `node:sqlite` is synchronous, so no `await` interleaves between
+* the check and the write and racing appends resolve to exactly one winner.
+*/
+function createSqliteEventLogStore(options) {
+	const { db, owned } = resolveDatabase(options.database);
+	const table = quoteIdentifier(options.tableName ?? "agent_event_log");
+	db.exec(`
+    CREATE TABLE IF NOT EXISTS ${table} (
+      thread_id TEXT NOT NULL,
+      idx INTEGER NOT NULL,
+      entry_id TEXT NOT NULL,
+      entry TEXT NOT NULL,
+      PRIMARY KEY (thread_id, idx)
+    );
+    CREATE UNIQUE INDEX IF NOT EXISTS ${quoteIdentifier(`${options.tableName ?? "agent_event_log"}_thread_entry_id`)} ON ${table} (thread_id, entry_id);
+  `);
+	const lengthOf = (threadId) => {
+		const row = db.prepare(`SELECT COUNT(*) AS n FROM ${table} WHERE thread_id = ?`).get(threadId);
+		return Number(row?.n ?? 0);
+	};
+	const transact = (fn) => {
+		db.exec("BEGIN IMMEDIATE");
+		try {
+			const result = fn();
+			db.exec("COMMIT");
+			return result;
+		} catch (error) {
+			try {
+				db.exec("ROLLBACK");
+			} catch {}
+			throw error;
+		}
+	};
+	return {
+		async append({ threadId, expectedIndex, entries }) {
+			for (const entry of entries) require_event_log_store.assertAgentLogEntry(entry);
+			for (let i = 0; i < entries.length; i++) if (entries[i].index !== expectedIndex + i) throw new Error(`AgentEventLogStore.append: entry.index (${entries[i].index}) must be contiguous from expectedIndex (${expectedIndex}); expected ${expectedIndex + i} at position ${i} on thread "${threadId}".`);
+			transact(() => {
+				const length = lengthOf(threadId);
+				if (length !== expectedIndex) throw new require_event_log_store.AgentEventLogConflictError(threadId, expectedIndex, length);
+				const insert = db.prepare(`INSERT INTO ${table} (thread_id, idx, entry_id, entry) VALUES (?, ?, ?, ?)`);
+				for (const entry of entries) try {
+					insert.run(threadId, entry.index, entry.id, JSON.stringify(entry));
+				} catch (error) {
+					if (String(error.message).includes("UNIQUE")) throw new Error(`AgentEventLogStore.append: duplicate event id "${entry.id}" in thread "${threadId}".`);
+					throw error;
+				}
+			});
+		},
+		async read(threadId, options) {
+			const from = options?.from ?? 0;
+			return db.prepare(`SELECT entry FROM ${table} WHERE thread_id = ? AND idx >= ? ORDER BY idx ASC`).all(threadId, from).map((row) => JSON.parse(row.entry));
+		},
+		async length(threadId) {
+			return lengthOf(threadId);
+		},
+		async fork({ threadId, newThreadId, upToIndex, atEventId }) {
+			if (upToIndex !== void 0 && atEventId !== void 0) throw new Error("AgentEventLogStore.fork: pass either upToIndex or atEventId, not both.");
+			transact(() => {
+				if (lengthOf(newThreadId) > 0) throw new Error(`AgentEventLogStore.fork: newThreadId "${newThreadId}" already has entries.`);
+				const sourceLength = lengthOf(threadId);
+				if (sourceLength === 0) throw new Error(`AgentEventLogStore.fork: unknown source thread "${threadId}".`);
+				let upTo = upToIndex ?? sourceLength;
+				if (atEventId !== void 0) {
+					const row = db.prepare(`SELECT idx FROM ${table} WHERE thread_id = ? AND entry_id = ?`).get(threadId, atEventId);
+					if (!row) throw new Error(`AgentEventLogStore.fork: thread "${threadId}" has no event id "${atEventId}".`);
+					upTo = Number(row.idx) + 1;
+				}
+				if (upTo < 0 || upTo > sourceLength) throw new Error(`AgentEventLogStore.fork: thread "${threadId}" (length ${sourceLength}) has no index ${upTo} to fork up to.`);
+				db.prepare(`INSERT INTO ${table} (thread_id, idx, entry_id, entry)
+           SELECT ?, idx, entry_id, entry FROM ${table} WHERE thread_id = ? AND idx < ?`).run(newThreadId, threadId, upTo);
+			});
+		},
+		close() {
+			if (owned) db.close();
+		}
+	};
+}
+/**
+* An {@link AgentSnapshotStore} on one SQLite table: a `key -> JSON` upsert.
+* Snapshots are the compaction cache over the event log, so `save` overwrites
+* whatever the id previously held.
+*/
+function createSqliteSnapshotStore(options) {
+	const { db, owned } = resolveDatabase(options.database);
+	const table = quoteIdentifier(options.tableName ?? "agent_snapshots");
+	db.exec(`
+    CREATE TABLE IF NOT EXISTS ${table} (
+      id TEXT PRIMARY KEY,
+      snapshot TEXT NOT NULL
+    );
+  `);
+	return {
+		async load(id) {
+			const row = db.prepare(`SELECT snapshot FROM ${table} WHERE id = ?`).get(id);
+			return row === void 0 ? void 0 : JSON.parse(row.snapshot);
+		},
+		async save(id, snapshot) {
+			db.prepare(`INSERT INTO ${table} (id, snapshot) VALUES (?, ?)
+         ON CONFLICT(id) DO UPDATE SET snapshot = excluded.snapshot`).run(id, JSON.stringify(snapshot));
+		},
+		close() {
+			if (owned) db.close();
+		}
+	};
+}
+//#endregion
+exports.createSqliteEventLogStore = createSqliteEventLogStore;
+exports.createSqliteSnapshotStore = createSqliteSnapshotStore;

package/dist/sqlite.d.cts

@@ -0,0 +1,57 @@
+import { r as AgentSnapshotStore } from "./types-QbEfCVny.cjs";
+import { r as AgentEventLogStore } from "./event-log-store-Ruq18mGp.cjs";
+
+//#region src/sqlite/index.d.ts
+/** A prepared statement, structurally compatible with `node:sqlite`'s `StatementSync`. */
+interface SqliteStatement {
+  run(...params: any[]): unknown;
+  all(...params: any[]): unknown[];
+  get(...params: any[]): unknown;
+}
+/** A database handle, structurally compatible with `node:sqlite`'s `DatabaseSync`. */
+interface SqliteDatabase {
+  prepare(sql: string): SqliteStatement;
+  exec(sql: string): void;
+  close(): void;
+}
+/** A store that owns nothing unless it opened the file itself.
+ *
+ * Exported because it appears in the store factories' return types — without
+ * it, consumers' declaration emit fails with TS4058 "cannot be named". */
+interface Closable {
+  /**
+   * Closes the underlying database — but only when this store opened it from a
+   * path. When a `DatabaseSync` handle was passed in, the caller owns it and
+   * this is a no-op.
+   */
+  close(): void;
+}
+interface SqliteStoreOptions {
+  /** A file path (or `':memory:'`) to open, or an existing `node:sqlite` handle to share. */
+  database: string | SqliteDatabase;
+}
+interface SqliteEventLogStoreOptions extends SqliteStoreOptions {
+  /** Table holding the log entries. Defaults to `agent_event_log`. */
+  tableName?: string;
+}
+interface SqliteSnapshotStoreOptions extends SqliteStoreOptions {
+  /** Table holding the snapshots. Defaults to `agent_snapshots`. */
+  tableName?: string;
+}
+/**
+ * An {@link AgentEventLogStore} on one SQLite table, keyed by
+ * `(thread_id, idx)` with a unique `(thread_id, entry_id)` index. Entries are
+ * stored as JSON text, so reads and writes are deep copies by construction.
+ * `append` runs its length check and inserts inside one `BEGIN IMMEDIATE`
+ * transaction: `node:sqlite` is synchronous, so no `await` interleaves between
+ * the check and the write and racing appends resolve to exactly one winner.
+ */
+declare function createSqliteEventLogStore(options: SqliteEventLogStoreOptions): AgentEventLogStore & Closable;
+/**
+ * An {@link AgentSnapshotStore} on one SQLite table: a `key -> JSON` upsert.
+ * Snapshots are the compaction cache over the event log, so `save` overwrites
+ * whatever the id previously held.
+ */
+declare function createSqliteSnapshotStore(options: SqliteSnapshotStoreOptions): AgentSnapshotStore & Closable;
+//#endregion
+export { Closable, SqliteDatabase, SqliteEventLogStoreOptions, SqliteSnapshotStoreOptions, SqliteStatement, SqliteStoreOptions, createSqliteEventLogStore, createSqliteSnapshotStore };

package/dist/sqlite.d.mts

@@ -0,0 +1,57 @@
+import { r as AgentSnapshotStore } from "./types-_FXoFBGO.mjs";
+import { r as AgentEventLogStore } from "./event-log-store-CriMgX1D.mjs";
+
+//#region src/sqlite/index.d.ts
+/** A prepared statement, structurally compatible with `node:sqlite`'s `StatementSync`. */
+interface SqliteStatement {
+  run(...params: any[]): unknown;
+  all(...params: any[]): unknown[];
+  get(...params: any[]): unknown;
+}
+/** A database handle, structurally compatible with `node:sqlite`'s `DatabaseSync`. */
+interface SqliteDatabase {
+  prepare(sql: string): SqliteStatement;
+  exec(sql: string): void;
+  close(): void;
+}
+/** A store that owns nothing unless it opened the file itself.
+ *
+ * Exported because it appears in the store factories' return types — without
+ * it, consumers' declaration emit fails with TS4058 "cannot be named". */
+interface Closable {
+  /**
+   * Closes the underlying database — but only when this store opened it from a
+   * path. When a `DatabaseSync` handle was passed in, the caller owns it and
+   * this is a no-op.
+   */
+  close(): void;
+}
+interface SqliteStoreOptions {
+  /** A file path (or `':memory:'`) to open, or an existing `node:sqlite` handle to share. */
+  database: string | SqliteDatabase;
+}
+interface SqliteEventLogStoreOptions extends SqliteStoreOptions {
+  /** Table holding the log entries. Defaults to `agent_event_log`. */
+  tableName?: string;
+}
+interface SqliteSnapshotStoreOptions extends SqliteStoreOptions {
+  /** Table holding the snapshots. Defaults to `agent_snapshots`. */
+  tableName?: string;
+}
+/**
+ * An {@link AgentEventLogStore} on one SQLite table, keyed by
+ * `(thread_id, idx)` with a unique `(thread_id, entry_id)` index. Entries are
+ * stored as JSON text, so reads and writes are deep copies by construction.
+ * `append` runs its length check and inserts inside one `BEGIN IMMEDIATE`
+ * transaction: `node:sqlite` is synchronous, so no `await` interleaves between
+ * the check and the write and racing appends resolve to exactly one winner.
+ */
+declare function createSqliteEventLogStore(options: SqliteEventLogStoreOptions): AgentEventLogStore & Closable;
+/**
+ * An {@link AgentSnapshotStore} on one SQLite table: a `key -> JSON` upsert.
+ * Snapshots are the compaction cache over the event log, so `save` overwrites
+ * whatever the id previously held.
+ */
+declare function createSqliteSnapshotStore(options: SqliteSnapshotStoreOptions): AgentSnapshotStore & Closable;
+//#endregion
+export { Closable, SqliteDatabase, SqliteEventLogStoreOptions, SqliteSnapshotStoreOptions, SqliteStatement, SqliteStoreOptions, createSqliteEventLogStore, createSqliteSnapshotStore };

package/dist/sqlite.mjs

@@ -0,0 +1,133 @@
+import { i as assertAgentLogEntry, n as AgentEventLogConflictError } from "./event-log-store-D7pWtIhb.mjs";
+//#region src/sqlite/index.ts
+function openDatabase(path) {
+	const sqlite = process.getBuiltinModule?.("node:sqlite");
+	if (!sqlite?.DatabaseSync) throw new Error("createSqlite*Store: 'node:sqlite' is unavailable in this runtime; Node >= 22.18 is required.");
+	return new sqlite.DatabaseSync(path);
+}
+function quoteIdentifier(name) {
+	if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) throw new Error(`Invalid SQLite table name '${name}': use letters, digits, and underscores only.`);
+	return `"${name}"`;
+}
+function resolveDatabase(database) {
+	return typeof database === "string" ? {
+		db: openDatabase(database),
+		owned: true
+	} : {
+		db: database,
+		owned: false
+	};
+}
+/**
+* An {@link AgentEventLogStore} on one SQLite table, keyed by
+* `(thread_id, idx)` with a unique `(thread_id, entry_id)` index. Entries are
+* stored as JSON text, so reads and writes are deep copies by construction.
+* `append` runs its length check and inserts inside one `BEGIN IMMEDIATE`
+* transaction: `node:sqlite` is synchronous, so no `await` interleaves between
+* the check and the write and racing appends resolve to exactly one winner.
+*/
+function createSqliteEventLogStore(options) {
+	const { db, owned } = resolveDatabase(options.database);
+	const table = quoteIdentifier(options.tableName ?? "agent_event_log");
+	db.exec(`
+    CREATE TABLE IF NOT EXISTS ${table} (
+      thread_id TEXT NOT NULL,
+      idx INTEGER NOT NULL,
+      entry_id TEXT NOT NULL,
+      entry TEXT NOT NULL,
+      PRIMARY KEY (thread_id, idx)
+    );
+    CREATE UNIQUE INDEX IF NOT EXISTS ${quoteIdentifier(`${options.tableName ?? "agent_event_log"}_thread_entry_id`)} ON ${table} (thread_id, entry_id);
+  `);
+	const lengthOf = (threadId) => {
+		const row = db.prepare(`SELECT COUNT(*) AS n FROM ${table} WHERE thread_id = ?`).get(threadId);
+		return Number(row?.n ?? 0);
+	};
+	const transact = (fn) => {
+		db.exec("BEGIN IMMEDIATE");
+		try {
+			const result = fn();
+			db.exec("COMMIT");
+			return result;
+		} catch (error) {
+			try {
+				db.exec("ROLLBACK");
+			} catch {}
+			throw error;
+		}
+	};
+	return {
+		async append({ threadId, expectedIndex, entries }) {
+			for (const entry of entries) assertAgentLogEntry(entry);
+			for (let i = 0; i < entries.length; i++) if (entries[i].index !== expectedIndex + i) throw new Error(`AgentEventLogStore.append: entry.index (${entries[i].index}) must be contiguous from expectedIndex (${expectedIndex}); expected ${expectedIndex + i} at position ${i} on thread "${threadId}".`);
+			transact(() => {
+				const length = lengthOf(threadId);
+				if (length !== expectedIndex) throw new AgentEventLogConflictError(threadId, expectedIndex, length);
+				const insert = db.prepare(`INSERT INTO ${table} (thread_id, idx, entry_id, entry) VALUES (?, ?, ?, ?)`);
+				for (const entry of entries) try {
+					insert.run(threadId, entry.index, entry.id, JSON.stringify(entry));
+				} catch (error) {
+					if (String(error.message).includes("UNIQUE")) throw new Error(`AgentEventLogStore.append: duplicate event id "${entry.id}" in thread "${threadId}".`);
+					throw error;
+				}
+			});
+		},
+		async read(threadId, options) {
+			const from = options?.from ?? 0;
+			return db.prepare(`SELECT entry FROM ${table} WHERE thread_id = ? AND idx >= ? ORDER BY idx ASC`).all(threadId, from).map((row) => JSON.parse(row.entry));
+		},
+		async length(threadId) {
+			return lengthOf(threadId);
+		},
+		async fork({ threadId, newThreadId, upToIndex, atEventId }) {
+			if (upToIndex !== void 0 && atEventId !== void 0) throw new Error("AgentEventLogStore.fork: pass either upToIndex or atEventId, not both.");
+			transact(() => {
+				if (lengthOf(newThreadId) > 0) throw new Error(`AgentEventLogStore.fork: newThreadId "${newThreadId}" already has entries.`);
+				const sourceLength = lengthOf(threadId);
+				if (sourceLength === 0) throw new Error(`AgentEventLogStore.fork: unknown source thread "${threadId}".`);
+				let upTo = upToIndex ?? sourceLength;
+				if (atEventId !== void 0) {
+					const row = db.prepare(`SELECT idx FROM ${table} WHERE thread_id = ? AND entry_id = ?`).get(threadId, atEventId);
+					if (!row) throw new Error(`AgentEventLogStore.fork: thread "${threadId}" has no event id "${atEventId}".`);
+					upTo = Number(row.idx) + 1;
+				}
+				if (upTo < 0 || upTo > sourceLength) throw new Error(`AgentEventLogStore.fork: thread "${threadId}" (length ${sourceLength}) has no index ${upTo} to fork up to.`);
+				db.prepare(`INSERT INTO ${table} (thread_id, idx, entry_id, entry)
+           SELECT ?, idx, entry_id, entry FROM ${table} WHERE thread_id = ? AND idx < ?`).run(newThreadId, threadId, upTo);
+			});
+		},
+		close() {
+			if (owned) db.close();
+		}
+	};
+}
+/**
+* An {@link AgentSnapshotStore} on one SQLite table: a `key -> JSON` upsert.
+* Snapshots are the compaction cache over the event log, so `save` overwrites
+* whatever the id previously held.
+*/
+function createSqliteSnapshotStore(options) {
+	const { db, owned } = resolveDatabase(options.database);
+	const table = quoteIdentifier(options.tableName ?? "agent_snapshots");
+	db.exec(`
+    CREATE TABLE IF NOT EXISTS ${table} (
+      id TEXT PRIMARY KEY,
+      snapshot TEXT NOT NULL
+    );
+  `);
+	return {
+		async load(id) {
+			const row = db.prepare(`SELECT snapshot FROM ${table} WHERE id = ?`).get(id);
+			return row === void 0 ? void 0 : JSON.parse(row.snapshot);
+		},
+		async save(id, snapshot) {
+			db.prepare(`INSERT INTO ${table} (id, snapshot) VALUES (?, ?)
+         ON CONFLICT(id) DO UPDATE SET snapshot = excluded.snapshot`).run(id, JSON.stringify(snapshot));
+		},
+		close() {
+			if (owned) db.close();
+		}
+	};
+}
+//#endregion
+export { createSqliteEventLogStore, createSqliteSnapshotStore };