@bastani/atomic 0.9.41 → 0.9.42-alpha.1

package/docs/storage.md

@@ -21,7 +21,7 @@ try {
 
 `exec`, `run`, `get`, and `all` return promises. Bind values through positional `?` parameters; `run` returns `{ changes }`, `get` returns a row or `undefined`, and `all` returns an array. Values may be null, number, bigint, string, or Uint8Array. Binary values are copied when the call is made, so reusing a buffer afterward does not change queued work. INTEGER values inside the safe integer range are returned as numbers; larger values are returned as bigints.
 
-The node adapter creates parent directories and enables WAL, full synchronization, and foreign keys. Its busy timeout defaults to 5000 ms; override it with `openNodeSqliteDatabase(path, { busyTimeoutMs: 1000 })`. Use `:memory:` for an ephemeral database.
+The node adapter creates parent directories and enables WAL, full synchronization, and foreign keys. Its busy timeout defaults to 5000 ms; override it with `openNodeSqliteDatabase(path, { busyTimeoutMs: 1000 })`. Use `:memory:` for an ephemeral database. Pass `{ readOnly: true }` to inspect an existing file without creating it or changing its journal mode.
 
 Transactions from separate `openNodeSqliteDatabase` connections to the same file queue asynchronously within one process; symlink paths refer to the same queue. Separate in-memory databases remain independent. SQLite locking and the busy timeout still govern contention from other processes. Wrap a caller-owned connection consistently: its transaction queue is shared by wrappers of that connection, not by other connections to its file.
 
@@ -33,55 +33,102 @@ Errors are exported classes with typed fields. `StorageUnavailableError` provide
 
 String bindings containing U+0000 are rejected before SQL executes with `StorageInvalidTextError`. Its `parameterIndex` is zero-based and its `reason` is `"nul-character"`. This rule applies to database calls and transaction handles. Store JSON with `JSON.stringify`, which escapes NUL characters, or use `Uint8Array` for binary data containing zero bytes. This validation does not inspect SQL source or SQL-generated values.
 
-## Bring your own driver
+## Turso and libSQL
 
-Atomic does not bundle remote database drivers. Install your chosen SQLite-compatible driver in your own project and wrap it as a `SqliteDatabase` from `@bastani/atomic/storage`. The interface consists of a diagnostic `descriptor`, async `exec`, `run`, `get`, `all`, `transaction(callback)`, and `close()` methods, with the return values and transaction-handle rules described above.
+`@bastani/atomic-storage-libsql` is the maintained adapter for Turso and other libSQL databases. It stores sessions, workflow runs, and Intercom's multi-node routing in the database. Install it once per machine, in user scope so Atomic can find it:
 
-A wrapper must queue database operations in call order, keeping unrelated calls outside active transactions. Reject NUL text with `StorageInvalidTextError`, snapshot binary parameters before queueing, and normalize returned integers and blobs. Use `StorageUnavailableError` for driver failures, preserve callback failures, and report failed rollbacks with `StorageRollbackError`. Expire transaction handles after their callback settles. On close, reject new calls, drain accepted work, and release driver resources. Do not include credentials in diagnostics or fall back to memory after an opening failure.
+```bash
+atomic install npm:@bastani/atomic-storage-libsql
+```
 
-### libSQL / Turso example
+Then select it in `~/.atomic/agent/settings.json`:
 
-Install `@libsql/client` separately. Save the complete wrapper below as `storage-libsql-wrapper.ts` in your project. It accepts caller-provided credentials only. For a local file, create its parent directory first; no network or credentials are needed.
+```json
+{
+  "storage": {
+    "adapter": "@bastani/atomic-storage-libsql",
+    "options": { "url": "libsql://<db>.turso.io" },
+    "secrets": { "authToken": { "file": "turso-token" } }
+  }
+}
+```
 
-```ts
-import type { SqliteDatabase } from "@bastani/atomic/storage";
-import { openLibsqlDatabase } from "./storage-libsql-wrapper.js";
+Save the token with `turso db tokens create <db> > turso-token` and keep it readable only by you (`chmod 600`); a trailing newline is ignored. A relative `file` resolves against Atomic home, normally `~/.atomic`. Use `{ "env": "TURSO_TOKEN" }` instead to read it from an environment variable. For a local database file, use a `file:` URL such as `file:/home/me/shared.sqlite` and omit `secrets`. Every machine that uses the same `storage` block shares the same sessions, workflow runs, and Intercom routing; add a `prefix` to keep projects or teams apart. See [Sharing storage across hosts](#sharing-storage-across-hosts).
 
-const database: SqliteDatabase = await openLibsqlDatabase({ url: "file:./data.sqlite" });
-// For Turso instead: { url: "libsql://your-database.turso.io", authToken: token }
-try {
-  await database.exec("CREATE TABLE IF NOT EXISTS notes (text TEXT)");
-  await database.transaction(async (tx) => {
-    await tx.run("INSERT INTO notes VALUES (?)", "hello");
-  });
-  const notes = await database.all("SELECT text FROM notes");
-} finally {
-  await database.close();
-}
+Like any [adapter](#selecting-an-adapter), it runs with Atomic's privileges. To use a different driver, adapt it with [Bring your own driver](#bring-your-own-driver).
+
+SDK callers can import `openLibsqlDatabase` from `@bastani/atomic-storage-libsql` directly. The package ships plain ESM JavaScript and TypeScript declarations, so supported Node versions need no TypeScript loader.
+
+### Joining a machine to a shared database
+
+Instead of editing settings by hand, install the adapter and join the database:
+
+```bash
+atomic install npm:@bastani/atomic-storage-libsql
+turso db tokens create <db> > ~/turso-token
+atomic storage join libsql://<db>.turso.io --token-file ~/turso-token
+atomic intercom restart
+atomic storage status
 ```
 
-Pass the returned facade as SDK `sessionStore: { kind: "database", database, prefix: "project_" }` or workflow `journal: { database, prefix: "project_" }`. Both can use the same facade without closing your database. To select it from settings, expose `openLibsqlDatabase` through an adapter module as described below.
+`atomic storage join <url> --token-file <path> [--prefix <prefix>]`:
+
+1. reads the token and removes surrounding whitespace; an empty token is an error;
+2. connects with `@bastani/atomic-storage-libsql` and runs `SELECT 1`. It creates no tables and changes no data; sessions, workflow runs, and Intercom brokers create their own tables when they first use the database;
+3. stores the token in a new `~/.atomic/agent/storage-token.<id>` file (in the agent directory under `ATOMIC_CODING_AGENT_DIR`), readable only by you (mode 600). Your input token file and tokens used by previous selections are left as they are;
+4. writes only the top-level `storage` key of the global settings, `~/.atomic/agent/settings.json`, with the adapter, the URL, the token file, and the prefix. Every other setting keeps its value;
+5. lists the environment variables and settings that take precedence over the new selection, and says whether the running Intercom broker still uses its previous one.
+
+Nothing is written when the token is empty or the connection fails. If saving settings fails, the new token file is removed and the previous token remains untouched. Previous token files are kept after a successful join too, so already-running sessions can continue using them; remove them only after those sessions stop and no settings reference them. When the adapter is not installed, the command prints the `atomic install` command to run first. An absolute `file:` URL, such as `file:///home/me/shared.sqlite`, needs no `--token-file`; relative file URLs are refused so another working directory cannot select a different database. The `libsql://`, `https://`, and `wss://` schemes are accepted. A URL that contains the token itself, as a user name, a password, or an `authToken` parameter, is refused: pass the token with `--token-file` so it stays out of settings and output.
+
+After storage is saved, a problem reading project settings only affects the final override report: the command warns you and still exits successfully. Fix the reported settings error, then run `atomic storage status` to inspect the effective selection.
 
-<details>
-<summary>Complete wrapper</summary>
+The running Intercom broker keeps the selection it started with. `atomic intercom restart` replaces it: connected sessions reconnect within a few seconds and start a broker that reads the new selection. See [Running Intercom across machines](/intercom/operations#running-intercom-across-machines).
+
+### Checking the selected storage
+
+`atomic storage status` shows, for sessions, workflow runs, and Intercom:
+
+- the selected storage and where the selection comes from: an environment variable, project settings, global settings (`storage`, `sessions.storage`, or `workflows.journal`), or the default. Selections that are set but outranked are listed as `overrides`. See [Selecting storage per process](#selecting-storage-per-process) for the order;
+- whether the adapter loads, and from which installed package;
+- whether the database answers a `SELECT 1`. Local SQLite files, including adapter `file:` URLs, are checked through a read-only SQLite connection instead of an adapter hook that could create the file. Missing files are reported without creating them; no journal mode or table is changed. Relative adapter `file:` URLs are not probed: use an absolute URL to identify the file unambiguously;
+- for Intercom, whether a broker started now would route across machines, and how many brokers are live in the shared database;
+- whether an Intercom broker is running, how many sessions it serves, whether it uses the current selection, and its multi-node routing state.
+
+It also notes project settings that are not applied because the project is not trusted, and a project `storage` setting, which Intercom never uses. Run it in the project directory to see that project's selection. `--json` prints the same report as JSON. The command reports settings load errors instead of silently checking defaults, and exits 1 when settings cannot load, a selection is invalid, an adapter cannot load, or a database does not answer. Adapter loading, database operations, and connection cleanup each have a 15-second wait limit, so a stalled close cannot leave the command waiting indefinitely.
+
+When the shared `storage` selection (global settings, `--storage`, or `ATOMIC_STORAGE`) names an adapter that the running Atomic cannot load, interactive and print sessions warn at startup, naming the adapter and the cause. The Intercom broker would otherwise leave multi-node routing off with only a line in its log.
+
+## Bring your own driver
+
+Atomic does not bundle remote database drivers. Install your chosen SQLite-compatible driver and turn it into a `SqliteDatabase` with `createSqliteDatabase` from `@bastani/atomic/storage`. You supply the driver calls:
+
+- `descriptor`: the diagnostic `{ adapter, location }`. The facade passes `location` through `redact`.
+- `execute(sql, params)`: runs one statement with positional parameters and returns `{ columns, rows, changes }`, where each row lists its values in column order. Return integers as `bigint` to keep large values exact.
+- `executeMultiple(sql)`: runs zero or more statements that take no parameters.
+- `beginTransaction()`: begins a write transaction and returns its own `execute` and `executeMultiple`, plus `commit()`, `rollback()`, and an optional `close()` that releases it afterward.
+- `close()`: releases the connection.
+- `redact(text)`, optional: removes credentials from diagnostic text. `redactSecrets(secrets)` builds one that also removes each secret's URI-encoded and decoded forms, longest first.
+
+Driver calls may return values or promises. The returned facade follows the rules described above: it queues operations in call order and keeps them outside active transactions, snapshots binary parameters when a call is made, rejects NUL text with `StorageInvalidTextError` before SQL runs, returns safe-range integers as numbers and blobs as `Uint8Array` copies, expires transaction handles when their callback settles, and closes the driver once after draining accepted work. A failed driver call rejects with `StorageUnavailableError`, whose `cause` is the driver error with credentials redacted. A failed rollback rejects with `StorageRollbackError`, and callback failures are preserved. Do not fall back to memory after an opening failure.
+
+You can also implement `SqliteDatabase` yourself by following the same rules. Either way, run the [conformance suite](#adapter-conformance) against it.
+
+### libSQL / Turso example
+
+This module is a complete adapter. Install `@libsql/client` where the module can import it, for example as a dependency of an [Atomic package](#adapters-from-atomic-packages). It accepts caller-provided credentials only. For a local file, create its parent directory first; no network or credentials are needed.
 
 {/* custom-driver-example */}
 ```ts
-import type { Client, ResultSet, Row, Transaction } from "@libsql/client";
+import type { Client, Transaction } from "@libsql/client";
 import {
+	createSqliteDatabase,
+	redactSecrets,
 	type SqliteDatabase,
-	type SqliteExecutor,
-	type SqliteRow,
-	type SqliteValue,
-	type StorageDescriptor,
+	type SqliteDriverExecutor,
+	type StorageAdapterModule,
 	StorageAdapterLoadError,
-	StorageError,
 	type StorageFailureCause,
-	StorageInvalidTextError,
-	StorageRollbackError,
-	StorageTransactionClosedError,
-	StorageUnavailableError,
-	StoreClosedError,
 } from "@bastani/atomic/storage";
 
 export interface LibsqlDatabaseOptions {
@@ -89,224 +136,122 @@ export interface LibsqlDatabaseOptions {
 	authToken?: string;
 }
 
-function credentialRedactor(options: LibsqlDatabaseOptions): (text: string) => string {
-	const secrets = [options.authToken ?? ""];
-	for (const match of options.url.matchAll(/[?&]([^=&#]*)=([^&#]*)/g)) {
-		const token = new URLSearchParams(match[0].slice(1)).get("authToken");
-		if (token !== null) secrets.push(match[2] ?? "", token);
+/** Credentials a libSQL URL can carry: its userinfo and every `authToken` query value. */
+function urlCredentials(url: string): string[] {
+	const secrets: string[] = [];
+	// Scan each key/value once, including malformed URLs, without retrying a growing suffix at every '?'.
+	for (let index = 0; index < url.length; index++) {
+		if (url[index] !== "?" && url[index] !== "&") continue;
+		const start = ++index;
+		while (index < url.length && !"?&=#".includes(url[index]!)) index++;
+		if (url[index] === "=") {
+			const valueStart = ++index;
+			while (index < url.length && url[index] !== "&" && url[index] !== "#") index++;
+			const token = new URLSearchParams(url.slice(start, index)).get("authToken");
+			if (token !== null) secrets.push(url.slice(valueStart, index), token);
+		}
+		index--;
 	}
-	const userinfo = options.url.match(/\/\/([^/?#]*)@/)?.[1];
+	const userinfo = url.match(/\/\/([^/?#]*)@/)?.[1];
 	if (userinfo !== undefined) secrets.push(...userinfo.split(":"));
-	try {
-		const url = new URL(options.url);
-		secrets.push(url.username, url.password, ...url.searchParams.getAll("authToken"));
-	} catch {}
-	for (const secret of [...secrets]) {
-		try {
-			secrets.push(encodeURIComponent(secret));
-			secrets.push(decodeURIComponent(secret));
-		} catch {}
-	}
-	return (text) =>
-		secrets
-			.filter(Boolean)
-			.sort((first, second) => second.length - first.length)
-			.reduce((value, secret) => value.replaceAll(secret, "[redacted]"), text);
-}
-
-function redactCause(cause: StorageFailureCause, redact: (text: string) => string): StorageFailureCause {
-	if (typeof cause === "string") return redact(cause);
-	if (!(cause instanceof Error)) return cause;
-	const nested = cause.cause as StorageFailureCause;
-	const safeCause = redactCause(nested, redact);
-	const message = redact(cause.message);
-	const stack = cause.stack === undefined ? undefined : redact(cause.stack);
-	if (message === cause.message && stack === cause.stack && safeCause === nested) return cause;
-	const safe = new StorageError(message, { cause: safeCause });
-	safe.stack = stack;
-	return safe;
+	return secrets;
 }
 
-function normalizeRow(row: Row, columns: readonly string[]): SqliteRow {
-	return Object.fromEntries(
-		columns.map((key, index) => {
-			const value = row[index];
-			return [
-				key,
-				typeof value === "bigint" &&
-				value >= -BigInt(Number.MAX_SAFE_INTEGER) &&
-				value <= BigInt(Number.MAX_SAFE_INTEGER)
-					? Number(value)
-					: value instanceof ArrayBuffer
-						? new Uint8Array(value.slice(0))
-						: value,
-			];
-		}),
-	);
+function statements(connection: () => Client | Transaction): SqliteDriverExecutor {
+	return {
+		async execute(sql, params) {
+			const result = await connection().execute({ sql, args: [...params] });
+			return { columns: result.columns, rows: result.rows, changes: result.rowsAffected };
+		},
+		executeMultiple: (sql) => connection().executeMultiple(sql),
+	};
 }
 
-class LibsqlDatabase implements SqliteDatabase {
-	readonly descriptor: StorageDescriptor;
-	private readonly client: Client;
-	private readonly redact: (text: string) => string;
-	private tail: Promise<void> = Promise.resolve();
-	private closing = false;
-	private closePromise?: Promise<void>;
-	private readonly executor: SqliteExecutor;
-
-	constructor(client: Client, descriptor: StorageDescriptor, redact: (text: string) => string) {
-		this.client = client;
-		this.descriptor = descriptor;
-		this.redact = redact;
-		this.executor = this.createExecutor(client, () => true);
-	}
-
-	private async driver<T>(operation: () => T | Promise<T>): Promise<T> {
-		try {
-			return await operation();
-		} catch (cause) {
-			throw new StorageUnavailableError(this.descriptor, redactCause(cause as StorageFailureCause, this.redact));
-		}
-	}
-
-	private createExecutor(connection: Client | Transaction, active: () => boolean): SqliteExecutor {
-		const execute = async <T>(operation: () => Promise<T>, params: readonly SqliteValue[] = []): Promise<T> => {
-			if (!active()) throw new StorageTransactionClosedError();
-			const invalidIndex = params.findIndex((value) => typeof value === "string" && value.includes("\0"));
-			if (invalidIndex !== -1) throw new StorageInvalidTextError(invalidIndex);
-			return this.driver(operation);
-		};
-		const statement = (sql: string, params: readonly SqliteValue[]): Promise<ResultSet> =>
-			connection.execute({
-				sql,
-				args: params.map((value) => (value instanceof Uint8Array ? new Uint8Array(value) : value)),
-			});
-		return {
-			exec: (sql) => execute(() => connection.executeMultiple(sql)),
-			run: (sql, ...params) =>
-				execute(async () => ({ changes: (await statement(sql, params)).rowsAffected }), params),
-			get: <T extends SqliteRow>(sql: string, ...params: readonly SqliteValue[]) =>
-				execute(async () => {
-					const result = await statement(sql, params);
-					const row = result.rows[0];
-					return row === undefined ? undefined : (normalizeRow(row, result.columns) as T);
-				}, params),
-			all: <T extends SqliteRow>(sql: string, ...params: readonly SqliteValue[]) =>
-				execute(async () => {
-					const result = await statement(sql, params);
-					return result.rows.map((row) => normalizeRow(row, result.columns) as T);
-				}, params),
-		};
-	}
-
-	private enqueue<T>(operation: () => Promise<T>): Promise<T> {
-		if (this.closing) return Promise.reject(new StoreClosedError(this.descriptor));
-		const result = this.tail.then(operation);
-		this.tail = result.then(
-			() => {},
-			() => {},
-		);
-		return result;
-	}
-
-	exec(sql: string): Promise<void> {
-		return this.enqueue(() => this.executor.exec(sql));
-	}
-
-	run(sql: string, ...params: readonly SqliteValue[]) {
-		const bound = params.map((value) => (value instanceof Uint8Array ? new Uint8Array(value) : value));
-		return this.enqueue(() => this.executor.run(sql, ...bound));
-	}
-
-	get<T extends SqliteRow>(sql: string, ...params: readonly SqliteValue[]): Promise<T | undefined> {
-		const bound = params.map((value) => (value instanceof Uint8Array ? new Uint8Array(value) : value));
-		return this.enqueue(() => this.executor.get<T>(sql, ...bound));
-	}
-
-	all<T extends SqliteRow>(sql: string, ...params: readonly SqliteValue[]): Promise<T[]> {
-		const bound = params.map((value) => (value instanceof Uint8Array ? new Uint8Array(value) : value));
-		return this.enqueue(() => this.executor.all<T>(sql, ...bound));
-	}
-
-	transaction<T>(callback: (transaction: SqliteExecutor) => Promise<T>): Promise<T> {
-		return this.enqueue(async () => {
-			const connection = await this.driver(() => this.client.transaction("write"));
-			let active = true;
-			try {
-				const result = await callback(this.createExecutor(connection, () => active));
-				active = false;
-				await this.driver(() => connection.commit());
-				return result;
-			} catch (cause) {
-				active = false;
-				try {
-					await this.driver(() => connection.rollback());
-				} catch (rollbackCause) {
-					throw new StorageRollbackError(cause as StorageFailureCause, rollbackCause as StorageFailureCause);
-				}
-				throw cause;
-			} finally {
-				await this.driver(() => connection.close());
-			}
-		});
-	}
-
-	close(): Promise<void> {
-		if (!this.closePromise) {
-			this.closing = true;
-			this.closePromise = this.tail.then(() => this.driver(() => this.client.close()));
-		}
-		return this.closePromise;
-	}
-}
-
-export async function openLibsqlDatabase(options: LibsqlDatabaseOptions): Promise<SqliteDatabase> {
-	const config = { url: options.url, authToken: options.authToken };
-	const redact = credentialRedactor(config);
-	const descriptor = { adapter: "libsql", location: redact(config.url) };
+export async function openLibsqlDatabase({ url, authToken }: LibsqlDatabaseOptions): Promise<SqliteDatabase> {
 	let createClient: typeof import("@libsql/client").createClient;
 	try {
 		({ createClient } = await import("@libsql/client"));
 	} catch (cause) {
-		throw new StorageAdapterLoadError("@libsql/client", redactCause(cause as StorageFailureCause, redact));
+		throw new StorageAdapterLoadError("@libsql/client", cause as StorageFailureCause);
 	}
 	let client: Client | undefined;
+	// Create the client inside a driver call, so the facade redacts credentials from its failures.
+	const connection = () => (client ??= createClient({ url, authToken, intMode: "bigint" }));
+	const database = createSqliteDatabase({
+		descriptor: { adapter: "libsql", location: url },
+		redact: redactSecrets([authToken ?? "", ...urlCredentials(url)]),
+		...statements(connection),
+		async beginTransaction() {
+			const transaction = await connection().transaction("write");
+			return {
+				...statements(() => transaction),
+				commit: () => transaction.commit(),
+				rollback: () => transaction.rollback(),
+				close: () => transaction.close(),
+			};
+		},
+		close: () => client?.close(),
+	});
 	try {
-		client = createClient({ ...config, intMode: "bigint" });
-		const database = new LibsqlDatabase(client, descriptor, redact);
 		await database.exec("PRAGMA foreign_keys = ON");
 		return database;
-	} catch (cause) {
-		try {
-			client?.close();
-		} catch {}
-		throw new StorageUnavailableError(descriptor, redactCause(cause as StorageFailureCause, redact));
+	} catch (error) {
+		await database.close().catch(() => {});
+		throw error;
 	}
 }
+
+export default {
+	atomicStorageAdapter: 1,
+	openDatabase: (options) =>
+		openLibsqlDatabase({
+			url: String(options.url),
+			authToken: typeof options.authToken === "string" ? options.authToken : undefined,
+		}),
+} satisfies StorageAdapterModule;
 ```
 {/* /custom-driver-example */}
 
-</details>
+Its default export lets settings select it as an [adapter](#selecting-an-adapter). From the SDK, call `openLibsqlDatabase` directly:
+
+```ts
+import { openLibsqlDatabase } from "./libsql-adapter.js";
+
+const database = await openLibsqlDatabase({ url: "file:./data.sqlite" });
+// For Turso instead: { url: "libsql://your-database.turso.io", authToken: token }
+try {
+  await database.exec("CREATE TABLE IF NOT EXISTS notes (text TEXT)");
+  await database.transaction(async (tx) => {
+    await tx.run("INSERT INTO notes VALUES (?)", "hello");
+  });
+  const notes = await database.all("SELECT text FROM notes");
+} finally {
+  await database.close();
+}
+```
+
+Pass the returned facade as SDK `sessionStore: { kind: "database", database, prefix: "project_" }` or workflow `journal: { database, prefix: "project_" }`. Both can use the same facade without closing your database.
 
 ## Selecting an adapter
 
-Install your driver separately and export a default `StorageAdapterModule` from your module:
+An adapter is a module whose default export is a `StorageAdapterModule`, like the libSQL example above:
 
 ```ts
 import type { StorageAdapterModule } from "@bastani/atomic/storage";
-import { openLibsqlDatabase } from "./storage-libsql-wrapper.js";
 
 export default {
   atomicStorageAdapter: 1,
   async openDatabase(options, context) {
-    return openLibsqlDatabase({ url: String(options.url), authToken: String(options.authToken) });
+    return openMyDatabase({ url: String(options.url), authToken: String(options.authToken) });
   },
 } satisfies StorageAdapterModule;
 ```
 
-Select it with `sessions.storage: { "adapter": "@example/atomic-sqlite" }`, `workflows.journal`, or shared top-level `storage` in [settings](/settings#workflow-storage). SDK sessions accept `sessionStore: { kind: "adapter", module, options, secrets, prefix }`; workflow runs accept `journal: { adapter, options, secrets, prefix }`. Module specifiers resolve from the agent directory, normally `~/.atomic/agent`; absolute module paths also work. Project settings follow the same trust boundary as project extensions. A module executes with Atomic's privileges.
+Select it with `sessions.storage: { "adapter": "./storage/libsql-adapter.ts" }`, `workflows.journal`, or shared top-level `storage` in [settings](/settings#workflow-storage). SDK sessions accept `sessionStore: { kind: "adapter", module, options, secrets, prefix }`; workflow runs accept `journal: { adapter, options, secrets, prefix }`. Relative module paths resolve from the agent directory, normally `~/.atomic/agent`; absolute module paths also work. A package name selects an adapter from an [installed Atomic package](#adapters-from-atomic-packages), or otherwise resolves from the agent directory. Project settings follow the same trust boundary as project extensions. A module executes with Atomic's privileges.
+
+Adapter modules import `@bastani/atomic/storage` and `@bastani/atomic` from the running Atomic, in the npm package and the standalone binary alike, exactly as extensions do. They need no installed or linked copy of Atomic, and Atomic recognizes the storage errors they throw. List `@bastani/atomic` in an adapter package's `peerDependencies`, not its `dependencies`.
 
-`options` is an object of SQLite scalar values or booleans. In JSON settings use strings, numbers, booleans, or null. `secrets` maps option names to `{ env }` or `{ file }`; resolved values override same-named options without trimming file contents. Keep credentials out of `options` and database descriptors. `context` contains `agentDir`, `domain: "sessions" | "journal" | "intercom"`, and an optional `signal`. Intercom brokers open the top-level `storage` selection with `domain: "intercom"` through `openDatabase`.
+`options` is an object of SQLite scalar values or booleans. In JSON settings use strings, numbers, booleans, or null. `secrets` maps option names to `{ env }` or `{ file }`, and resolved values override same-named options. A `{ file }` secret is read as written, except that one trailing line ending (`\n` or `\r\n`) is removed, so a token saved with `turso db tokens create <db> > token` works as is. Other whitespace is kept. Keep credentials out of `options` and database descriptors. `context` contains `agentDir`, `domain: "sessions" | "journal" | "intercom"`, and an optional `signal`. Intercom brokers open the top-level `storage` selection with `domain: "intercom"` through `openDatabase`.
 
 A SQLite adapter implements `openDatabase(options, context): Promise<SqliteDatabase>`. Atomic applies its domain schema and optional table prefix. A full adapter can instead implement `openSessionStore(options, context, storage)` or `openRunJournal(options, context, storage)`; the domain hook takes priority over `openDatabase`. The typed third argument is `{ readonly prefix?: string }`. Domain adapters must honor this prefix to isolate selected stores. A missing domain/database hook raises `StorageConfigError` with reason `"adapter-domain-unsupported"`. Load failures and invalid module contracts raise `StorageAdapterLoadError`; driver opening failures raise `StorageUnavailableError`. None selects memory as a fallback.
 
@@ -318,6 +263,33 @@ If opening storage fails and closing its owned database also fails, the original
 
 Factory-created journal headers record a credential-free `storage` descriptor for diagnostics. Full domain adapters are responsible for recording their own safe descriptor. Directly supplied journals and their caller-provided headers are not rewritten.
 
+### Adapters from Atomic packages
+
+An [Atomic package](/packages) can provide storage adapters, so `atomic install` brings an adapter together with its driver and the driver's dependencies. List the adapter modules, relative to the package root, under `storageAdapters` in the package manifest:
+
+```json
+{
+  "name": "@example/atomic-libsql",
+  "dependencies": { "@libsql/client": "0.18.0" },
+  "peerDependencies": { "@bastani/atomic": "*" },
+  "atomic": { "storageAdapters": ["./libsql-adapter.ts"] }
+}
+```
+
+Install it with `atomic install npm:@example/atomic-libsql` and select it by package name:
+
+```json
+{
+  "storage": {
+    "adapter": "@example/atomic-libsql",
+    "options": { "url": "libsql://team.example" },
+    "secrets": { "authToken": { "file": "turso-token" } }
+  }
+}
+```
+
+The package name selects the package's first listed adapter. When a package lists several, select one with `<package>/<name>`, where `<name>` is the adapter file's name without its extension, for example `@example/atomic-libsql/libsql-adapter`. Atomic searches the packages in your effective global settings, including legacy `~/.pi/agent/settings.json` settings where applicable; an explicit agent directory does not inherit packages from another home. `atomic install` writes user settings without `-l`; project packages are not searched. When no installed package lists a matching adapter, the name resolves from the agent directory as before.
+
 ## Selecting storage per process
 
 A host that starts Atomic processes, for example a supervisor that launches `atomic --mode rpc` children, can select storage for those processes alone. Each option holds the same JSON selection the settings accept, including `adapter`, `options`, `secrets`, and `prefix`:
@@ -339,7 +311,7 @@ atomic --mode rpc --storage-file /etc/atomic/storage.json
 
 Nothing is written to settings. A process started without these options keeps using its settings, so an interactive `atomic` and an RPC child started with `ATOMIC_STORAGE` in the same account each keep their own sessions and workflow runs, and `/resume` in each lists only its own store. `--storage` and `--storage-file` cannot be combined. The interactive CLI passes its `--storage` selection to its background engine process. Other processes that Atomic starts inherit the environment variables but not the flag.
 
-The Intercom broker an Atomic process starts uses the same selection for multi-node routing: `--storage`, `--storage-file`, or `ATOMIC_STORAGE` from that process outranks the top-level `storage` setting, and a broker started by a process without them reads settings. One broker serves every session in an agent directory, so it keeps the selection of the process that started it until it exits.
+The Intercom broker an Atomic process starts uses the same selection for multi-node routing: `--storage`, `--storage-file`, or `ATOMIC_STORAGE` from that process outranks the top-level `storage` setting, and a broker started by a process without them reads settings. One broker serves every session in an agent directory, so it keeps the selection of the process that started it until it exits or `atomic intercom restart` replaces it. Project settings never select the broker's storage.
 
 Precedence for each domain, highest first:
 
@@ -369,7 +341,7 @@ These options come from the process that starts Atomic, so they are not subject
 
 ## Sharing storage across hosts
 
-By default, sessions and workflow runs live in a local file that serves one machine. To share them across machines, for example several service replicas or a CI fleet, select the same remote SQLite-compatible database on every host through an [adapter](#selecting-an-adapter), such as the libSQL/Turso wrapper above. Give each project or tenant its own `prefix`. Do not put the local SQLite file on a network filesystem; use a database driver instead.
+By default, sessions and workflow runs live in a local file that serves one machine. To share them across machines, for example several service replicas or a CI fleet, select the same remote SQLite-compatible database on every host through an [adapter](#selecting-an-adapter), such as the [Turso / libSQL package](#turso-and-libsql). Installing the adapter as an [Atomic package](#adapters-from-atomic-packages) lets every host use the same `storage` block. Give each project or tenant its own `prefix`. Do not put the local SQLite file on a network filesystem; use a database driver instead.
 
 With a shared journal:
 

package/docs/usage.md

@@ -110,7 +110,7 @@ Both interrupts hold a queued message only while it is still waiting in the queu
 
 Both abort routes ask the agent to stop cooperatively. Escape waits as long as the agent needs, and neither route terminates the engine during normal cancellation.
 
-Ctrl+C also provides a recovery path. It reaches Atomic even when an extension's custom UI owns the screen, closing that UI if it does not handle the key. If the engine stops answering entirely, Ctrl+C replaces it. This also covers a replacement that hangs during startup or fails to start.
+Ctrl+C also provides a recovery path. It reaches Atomic even when an extension's custom UI owns the screen, closing that UI if it does not handle the key. If the engine stops answering, a queue clear or cancellation remains unanswered for over one second, or either operation fails, Ctrl+C replaces the engine. This includes cancelling chat, shell commands, compaction, and retries, even while engine heartbeats continue. It also covers a replacement that hangs during startup or fails to start. Recovery is explicit: a stalled control does not restart the engine on its own. Replacing the engine interrupts its running workflows and tools; inspect workflow status before resuming work.
 
 If a message could not be sent, Atomic restores it to the editor exactly as typed, including pasted content. It appears above anything typed while the send was pending, separated by a blank line, together with later queued messages in their original order. Atomic does not also show a red error. See [Keybindings](/keybindings#application).
 

package/docs/workflows/api-reference.md

@@ -1213,6 +1213,50 @@ export default workflow({
 });
 ```
 
+### `loadWorkerWorkflow(path, exportName?)`
+
+```typescript
+function loadWorkerWorkflow(path: string, exportName?: string): Promise<AnyWorkflowDefinition>;
+```
+
+Loads and records a workflow definition from an absolute module path for use as a local worker child. The export name defaults to `"default"`. Pass the returned definition to `ctx.workflow(child, ...)` and list the same path/export pair in the root's `localWorkers.definitions`. The root itself may remain an inline closure. Worker definitions must be importable; a closure cannot cross the process boundary. The saved compatibility digest covers the entry module only, not its imported modules.
+
+```ts
+import { loadWorkerWorkflow, run, workflow } from "@bastani/atomic/workflows";
+
+const research = await loadWorkerWorkflow(`${process.cwd()}/workflows/research.ts`, "research");
+const root = workflow({
+  name: "research-pool",
+  description: "Run independent research tasks on local workers.",
+  inputs: {},
+  outputs: {},
+  async run(ctx) {
+    await Promise.all(["one", "two"].map((topic) => ctx.workflow(research, { inputs: { topic } })));
+    return {};
+  },
+});
+
+await run(root, {}, {
+  cwd: process.cwd(),
+  localWorkers: { count: 2, definitions: [{ path: `${process.cwd()}/workflows/research.ts`, exportName: "research" }] },
+  admission: { limits: { session: 2, process: 4 } },
+});
+```
+
+Only first-level child workflow subtrees are placed on workers. Nested children stay on their assigned worker. Stage placement is not distributed independently. If a child is absent from the inventory or cannot be imported, the run fails before executing it; there is no local fallback.
+
+#### Local worker options
+
+`RunOpts.localWorkers` enables a local process pool for this root. `count` must be a positive integer. `definitions` lists `{ path, exportName }` entries. The definitions are loaded in each worker from the local filesystem. `RunOpts.admission` accepts `limits` for one root, `userLimits` across runs, a `userDatabase` canonical local SQLite path, and optional host thresholds `maxLoadPerCpu` and `minFreeMemoryBytes`.
+
+The option is off by default. Without it, Atomic creates no pool tables, worker processes, or polling loops. CLI users can set the same options under `workflows.localWorkers` and `workflows.admission` in settings. Settings paths resolve against the invocation working directory; SDK paths resolve against `cwd` (or the current directory). Effective settings and definition entry-module digests are persisted with the root and checked on resume. Changing them fails compatibility checks instead of silently changing placement.
+
+Workers are supported only on Linux and macOS hosts with native process identity and boot identity. Windows and hosts without those capabilities refuse activation, including when no process cap is configured. Remote hosts are not supported. Pooled SDK runs reject process-bound adapters, UI, persistence, and similar runtime overrides before worker launch. The CLI keeps its host-specific bindings at the root and gives worker sessions their own adapters.
+
+Admission limits count actual resources: a session from creation through disposal, including fallback and delegated sessions, and a managed tool process until confirmed cleanup. Yielding an observation wait does not free a process permit. Subprocesses started outside Atomic's managed APIs are not counted. Host load and free-memory thresholds are launch gates, not hard OS limits. `userLimits` are reliable only when every participating run uses the configured canonical database path; they are local-user coordination, not a tenant security boundary.
+
+Worker recovery replays unfinished child work from committed checkpoints, so external effects before the latest checkpoint may run again. Use stable logical idempotency keys where duplicate effects matter.
+
 Programmatic callers import `run` and call `run(definition, inputs)` with an exported definition and validated inputs. Use `createRegistry()` when an integration needs to register, merge, or look up several definitions before selecting one to run. The extension also registers the `/workflow` commands and the `workflow` tool for named execution, discovery, inspection, messaging, run control, and reload.
 
 ### `workflow(spec)`
@@ -1292,6 +1336,8 @@ function run<
 
 Executes a compiled definition programmatically with validated inputs. Empty-input workflows accept an empty readonly record.
 
+`run()` uses Intercom for stages that have access to the `intercom` tool. This also works in standalone scripts, including runs with `executionMode: "non_interactive"`. Atomic opens the route only when an eligible stage starts and releases it when the run settles. Nested stages use the same workflow group. To send from another local session, join `workflow:<rootRunId>` before targeting a stage or `workflow:<rootRunId>/**`. Tool restrictions such as `tools`, `excludedTools`, or `noTools: "all"` continue to disable Intercom for a stage.
+
 #### Stage sessions and adapters
 
 When `opts.adapters` supplies neither `agentSession` nor `prompt`, `run()` uses `createAgentSessionAdapter({ cwd: opts.cwd })`. Each stage then runs its own in-process Atomic `createAgentSession` session with persistent session storage by default. Use the stage's `sessionDir` to choose its session directory, or supply an explicitly selected in-memory session manager through a custom adapter for ephemeral stages. A persistent storage failure fails stage creation; it never falls back to memory. Stage sessions resolve models, credentials, settings, and resources the same way `createAgentSession` does. A `prompt` adapter on its own answers stage prompts itself, so `run()` adds no default session adapter beside it.
@@ -1362,6 +1408,8 @@ interface RunOpts {
   readonly deferWorkflowStart?: boolean;
   readonly config?: WorkflowRuntimeConfig;
   readonly journal?: RunJournalOption;
+  readonly localWorkers?: LocalWorkerOptions;
+  readonly admission?: WorkflowAdmissionOptions;
   readonly models?: WorkflowModelCatalogPort;
   readonly registry?: WorkflowRegistry;
   readonly depth?: number;
@@ -1385,6 +1433,8 @@ interface RunOpts {
 
 Supplies runtime adapters, execution policy, persistence, MCP, cancellation, graph/store integration, continuation metadata, and lifecycle callbacks to `run(...)`. Every field is optional.
 
+`LocalWorkerOptions` is `{ count: number, definitions: { path: string, exportName: string }[] }`, where `count` is a positive integer. `WorkflowAdmissionOptions` contains optional root `limits`, user-wide `userLimits`, `userDatabase`, and host thresholds. `limits` and `userLimits` accept `session` and `process` counts.
+
 `onStageSessionEvent` streams every agent-session event from each stage (for example `message_update`, `tool_execution_start`, and `tool_execution_end`), tagged with the stage's `runId` and `stageId`. `AgentSessionEvent` is exported by `@bastani/atomic`. The stream continues when a fallback model replaces a stage's session. Stages in nested `ctx.workflow(...)` runs report the child run's `runId`. Exceptions thrown by the listener, and rejections from an async listener, are ignored and do not affect the stage.
 
 The public authoring declaration intentionally excludes runtime-only executor fields such as `defaultSessionDir`, `gitWorktreeSetupCache`, `durableBackend`, `durableScope`, and `onStageSession`.