@thenavidm/slipway 0.1.0

package/dist/confirm.js

@@ -0,0 +1,166 @@
+/**
+ * Confirmation a model cannot fake.
+ *
+ * `confirm: true` is something the model types, so on its own it proves only
+ * that the model meant it. Where the client can put a person in front of the
+ * call, Slipway asks the person instead, and the model's flag stops counting:
+ *
+ * - Claude Code shows its own approval prompt for a tool marked as needing a
+ *   person, on every call and in every permission mode. A call that arrives
+ *   from it has already been approved, so nothing else is asked.
+ * - Any other client that supports elicitation is sent an approval form. The
+ *   tool runs only on an explicit yes.
+ * - A client that can do neither falls back to `confirm: true`.
+ *
+ * An approval form's answer comes back from the client as data, and a client
+ * could attach an answer to a call nobody was asked about. So an answer only
+ * counts next to the signed state Slipway minted when it asked, which names
+ * the exact tool and arguments and can be used once.
+ */
+import { randomBytes, randomUUID } from "node:crypto";
+import { CLIENT_CAPABILITIES_META_KEY, CLIENT_INFO_META_KEY, createRequestStateCodec, inputRequired, inputResponse, } from "@modelcontextprotocol/server";
+import { RefusedError } from "./errors.js";
+import { consequence, Guard } from "./guard.js";
+import { phrase, sha256, stableJson, versionAtLeast } from "./util.js";
+/** The key of Slipway's approval form among a call's input requests. */
+export const APPROVAL_KEY = "slipway_approval";
+/** The client Claude Code identifies as, and the first version known to honor a tool's request for a person. */
+const PROMPTING_CLIENT = { name: "claude-code", since: [2, 1, 246] };
+/**
+ * Who is calling and what it can do. On the 2026-07-28 revision every request
+ * carries this itself; on earlier revisions it was said once, at initialize.
+ */
+export function clientView(server, ctx) {
+    const envelope = ctx.mcpReq.envelope;
+    const info = (envelope?.[CLIENT_INFO_META_KEY] ?? server.server.getClientVersion());
+    const capabilities = (envelope?.[CLIENT_CAPABILITIES_META_KEY] ?? server.server.getClientCapabilities());
+    return {
+        ...(typeof info?.name === "string" ? { name: info.name } : {}),
+        ...(typeof info?.version === "string" ? { version: info.version } : {}),
+        ...(capabilities ? { capabilities } : {}),
+    };
+}
+/**
+ * Whether the client can show a person a form. A bare `elicitation: {}` is the
+ * 2025 way of saying so; naming only `url` mode is not.
+ */
+export function canAskPerson(client) {
+    const elicitation = client.capabilities?.elicitation;
+    if (!elicitation || typeof elicitation !== "object")
+        return false;
+    return "form" in elicitation || !("url" in elicitation);
+}
+/** Whether the client shows its own approval prompt for a tool that asks for a person. */
+export function promptsItself(client) {
+    return client.name === PROMPTING_CLIENT.name && versionAtLeast(client.version, PROMPTING_CLIENT.since);
+}
+export function confirmRoute(mode, client, listedForPerson) {
+    if (mode === "model")
+        return "flag";
+    if (listedForPerson && promptsItself(client))
+        return "client";
+    if (canAskPerson(client))
+        return "person";
+    return "flag";
+}
+/**
+ * Signs the state that travels with an approval form. The key lives as long
+ * as the process, which is every round of an approval on stdio and on one
+ * HTTP server; state from a restarted process fails verification, and the
+ * call is refused rather than run.
+ */
+const codec = createRequestStateCodec({ key: randomBytes(32), ttlSeconds: 600 });
+/** For `ServerOptions.requestState.verify`: rejects state Slipway did not sign, or signed more than ten minutes ago. */
+export const verifyApprovalState = codec.verify;
+/** Nonces of approvals already used, with when each expires. Bounded, so a long-lived server cannot grow it forever. */
+const used = new Map();
+const USED_LIMIT = 10_000;
+function useOnce(nonce) {
+    const now = Date.now();
+    if (used.has(nonce))
+        return false;
+    for (const [key, expires] of used) {
+        if (expires > now && used.size < USED_LIMIT)
+            break;
+        used.delete(key);
+    }
+    used.set(nonce, now + 11 * 60_000);
+    return true;
+}
+function callHash(tool, args) {
+    return sha256(`${tool}\0${stableJson(args)}`);
+}
+/**
+ * The words and the one field an approval form shows.
+ *
+ * The field is required, starts unticked, and only an explicit true counts.
+ * Accepting is not enough on its own: a client with nobody to ask may accept a
+ * form by itself (Codex accepts a form that has no fields), and one that fills
+ * in defaults would otherwise approve with them.
+ */
+export function approvalForm(appTitle, tool, summary) {
+    return {
+        message: `${appTitle} wants to ${phrase(summary)}.\n\nThis ${consequence(tool)}.`,
+        requestedSchema: {
+            type: "object",
+            properties: {
+                approve: { type: "boolean", title: "Approve", description: "Tick to run it, then accept. Decline to stop it.", default: false },
+            },
+            required: ["approve"],
+        },
+    };
+}
+/**
+ * Ask a person to approve the call, or read their answer.
+ *
+ * Returns the input-required result to send while the person has not answered
+ * yet, and nothing once they approved. Throws a refusal for a no, a closed
+ * form, or an answer that does not belong to this exact call.
+ */
+export async function personApproval(app, tool, rawArgs, ctx, env) {
+    const { confirm: _flag, ...args } = rawArgs;
+    const guard = new Guard(app.policy(env), "mcp", app.envPrefix);
+    const state = ctx.mcpReq.requestState();
+    const answer = inputResponse(ctx.mcpReq.inputResponses, APPROVAL_KEY);
+    // No signed state means nobody was asked yet, whatever answer came along with the call.
+    if (!state || typeof state !== "object" || answer.kind === "missing") {
+        const summary = app.preflight(tool, rawArgs, { surface: "mcp", env });
+        guard.record(tool, summary, "asked a person");
+        const form = approvalForm(app.title, tool, summary);
+        return inputRequired({
+            requestState: await codec.mint({ t: tool.name, h: callHash(tool.name, args), n: randomUUID() }),
+            inputRequests: { [APPROVAL_KEY]: inputRequired.elicit(form) },
+        });
+    }
+    const summary = app.preflight(tool, rawArgs, { surface: "mcp", env });
+    if (state.t !== tool.name || state.h !== callHash(tool.name, args)) {
+        guard.record(tool, summary, "blocked: approval invalid");
+        throw new RefusedError(`That approval was for a different call, so ${tool.name} did not run.`, {
+            hint: "Call the tool again to ask for a new approval.",
+        });
+    }
+    if (!useOnce(state.n)) {
+        guard.record(tool, summary, "blocked: approval invalid");
+        throw new RefusedError(`That approval was already used, so ${tool.name} did not run again.`, {
+            hint: "Call the tool again to ask for a new approval.",
+        });
+    }
+    if (answer.kind === "elicit" && answer.action === "accept" && answer.content?.approve === true)
+        return undefined;
+    if (answer.kind === "elicit" && answer.action === "accept") {
+        guard.record(tool, summary, "blocked: person declined");
+        throw new RefusedError(`The approval form was accepted without ticking Approve, so ${tool.name} did not run. About to: ${summary}.`, {
+            hint: "Ask the user whether they want this, and call again only if they do.",
+        });
+    }
+    if (answer.kind === "elicit" && answer.action === "cancel") {
+        guard.record(tool, summary, "blocked: no answer");
+        throw new RefusedError(`The approval form was closed without an answer, so ${tool.name} did not run. About to: ${summary}.`, {
+            hint: "Ask the user whether they want this, and call again only if they do.",
+        });
+    }
+    guard.record(tool, summary, "blocked: person declined");
+    throw new RefusedError(`The approval was declined, so ${tool.name} did not run. About to: ${summary}.`, {
+        hint: "Do not call it again unless the user asks for it.",
+    });
+}

package/dist/data.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Local data: a response cache, synced copies of lists, and search over them.
+ *
+ * An agent that asks the same question twice should not pay the service twice,
+ * and a person who wants to search ten thousand records should not page
+ * through an API to do it. So each app keeps one SQLite file on this machine,
+ * readable only by its owner, holding:
+ *
+ * - cached results of read tools that opted in, per account, cleared by any
+ *   write through the same app;
+ * - records synced from list tools, searchable offline with full-text search
+ *   and queryable with read-only SQL.
+ *
+ * It uses `node:sqlite`, which ships with Node.js 22.13 and later, so there is
+ * nothing to install. Where it is missing, the cache quietly stays off and the
+ * data commands say what to upgrade. Nothing here ever fails a tool call: a
+ * cache that cannot be read is a cache miss.
+ */
+import { SlipwayError } from "./errors.js";
+type Sqlite = typeof import("node:sqlite");
+/**
+ * Load `node:sqlite` once. Node prints an experimental-feature warning when it
+ * loads, which would land in every CLI command's output, so only that one
+ * warning is held back while it loads.
+ */
+export declare function loadSqlite(): Promise<Sqlite | undefined>;
+export declare class NoSqliteError extends SlipwayError {
+    constructor();
+}
+/** Where each operating system keeps an app's own data. */
+export declare function dataRoot(env: NodeJS.ProcessEnv, platform?: NodeJS.Platform): string;
+/** The folder for one app's data: `<PREFIX>_DATA_DIR`, or `slipway/<name>` in the system's data folder. */
+export declare function dataDir(appName: string, envPrefix: string, env: NodeJS.ProcessEnv): string;
+export type SearchHit = {
+    tool: string;
+    id: string;
+    snippet: string;
+    record: unknown;
+};
+export type SyncedTool = {
+    tool: string;
+    records: number;
+    last_sync?: string;
+    complete?: boolean;
+};
+/** One app's local data file. */
+export declare class DataStore {
+    readonly file: string;
+    private readonly db;
+    private readonly sqlite;
+    private constructor();
+    /** Open the file, creating its folder and the file itself readable by their owner only. */
+    static open(dir: string): Promise<DataStore>;
+    close(): void;
+    private transaction;
+    cacheGet(scope: string, tool: string, key: string, now?: number): {
+        value: unknown;
+        storedAt: number;
+    } | undefined;
+    cachePut(scope: string, tool: string, key: string, value: unknown, ttlSeconds: number, now?: number): void;
+    /** Forget every cached result for one account, after anything changed it. */
+    cacheClear(scope?: string): number;
+    /** Store a page of records. Each is replaced whole, and indexed for search. */
+    putRecords(scope: string, tool: string, records: Array<{
+        id: string;
+        data: unknown;
+    }>, syncedAt: number): void;
+    /** After a complete sync, drop the records the service no longer lists. */
+    removeUnseen(scope: string, tool: string, syncedBefore: number): number;
+    recordSync(scope: string, tool: string, filters: string, run: {
+        startedAt: number;
+        records: number;
+        pages: number;
+        complete: boolean;
+    }): void;
+    search(scope: string, words: string, options?: {
+        tool?: string;
+        limit?: number;
+    }): SearchHit[];
+    synced(scope: string): SyncedTool[];
+    cacheEntries(scope: string, now?: number): number;
+    /** Delete one account's synced records, for one tool or all of them. */
+    clearRecords(scope: string, tool?: string): number;
+    /**
+     * Run one read-only statement on its own connection, which SQLite itself
+     * refuses to write through, whatever the statement says.
+     */
+    query(sql: string): Array<Record<string, unknown>>;
+}
+/** The open store for a folder, shared by every call in this process. */
+export declare function storeAt(dir: string): Promise<DataStore>;
+/** Close every open store. For tests and for a server shutting down. */
+export declare function closeStores(): Promise<void>;
+/**
+ * Which account data belongs to. Cached results and synced records are only
+ * ever read back for the account they came from, so switching keys never shows
+ * one account another's data.
+ */
+export declare function scopeOf(credentials: ReadonlyArray<string | undefined | null>, explicit?: string): string;
+/** The cache key for one call: the tool's own arguments, in a stable order. */
+export declare function cacheKey(args: Record<string, unknown>): string;
+/** Every string and number in a record, which is what full-text search reads. */
+export declare function searchText(value: unknown): string;
+/**
+ * Words a person typed, as an FTS5 query that cannot be a syntax error: every
+ * word must appear, the last may be the start of a word.
+ */
+export declare function matchQuery(words: string): string;
+export {};

package/dist/data.js

@@ -0,0 +1,324 @@
+/**
+ * Local data: a response cache, synced copies of lists, and search over them.
+ *
+ * An agent that asks the same question twice should not pay the service twice,
+ * and a person who wants to search ten thousand records should not page
+ * through an API to do it. So each app keeps one SQLite file on this machine,
+ * readable only by its owner, holding:
+ *
+ * - cached results of read tools that opted in, per account, cleared by any
+ *   write through the same app;
+ * - records synced from list tools, searchable offline with full-text search
+ *   and queryable with read-only SQL.
+ *
+ * It uses `node:sqlite`, which ships with Node.js 22.13 and later, so there is
+ * nothing to install. Where it is missing, the cache quietly stays off and the
+ * data commands say what to upgrade. Nothing here ever fails a tool call: a
+ * cache that cannot be read is a cache miss.
+ */
+import { chmodSync, closeSync, existsSync, mkdirSync, openSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { SlipwayError, UsageError, EXIT } from "./errors.js";
+import { sha256, stableJson } from "./util.js";
+let loading;
+/**
+ * Load `node:sqlite` once. Node prints an experimental-feature warning when it
+ * loads, which would land in every CLI command's output, so only that one
+ * warning is held back while it loads.
+ */
+export function loadSqlite() {
+    loading ??= (async () => {
+        const original = process.emitWarning;
+        process.emitWarning = function (warning, ...rest) {
+            const text = typeof warning === "string" ? warning : warning?.message ?? "";
+            if (/sqlite/i.test(text))
+                return;
+            return original.call(process, warning, ...rest);
+        };
+        try {
+            return (await import("node:sqlite"));
+        }
+        catch {
+            return undefined;
+        }
+        finally {
+            process.emitWarning = original;
+        }
+    })();
+    return loading;
+}
+export class NoSqliteError extends SlipwayError {
+    constructor() {
+        super(`Local data needs Node.js 22.13 or later, which includes SQLite. This is Node.js ${process.versions.node}.`, "not_configured", EXIT.notConfigured, {
+            hint: "Install a current Node.js LTS release, then run the command again.",
+        });
+    }
+}
+/** Where each operating system keeps an app's own data. */
+export function dataRoot(env, platform = process.platform) {
+    const home = env.HOME || env.USERPROFILE || homedir();
+    if (platform === "darwin")
+        return join(home, "Library", "Application Support");
+    if (platform === "win32")
+        return env.LOCALAPPDATA || join(home, "AppData", "Local");
+    return env.XDG_DATA_HOME || join(home, ".local", "share");
+}
+/** The folder for one app's data: `<PREFIX>_DATA_DIR`, or `slipway/<name>` in the system's data folder. */
+export function dataDir(appName, envPrefix, env) {
+    return env[`${envPrefix}_DATA_DIR`]?.trim() || join(dataRoot(env), "slipway", appName);
+}
+const SCHEMA_VERSION = 1;
+const SCHEMA = `
+  CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+  CREATE TABLE IF NOT EXISTS cache (
+    scope TEXT NOT NULL, tool TEXT NOT NULL, key TEXT NOT NULL,
+    value TEXT NOT NULL, stored_at INTEGER NOT NULL, expires_at INTEGER NOT NULL,
+    PRIMARY KEY (scope, tool, key)
+  );
+  CREATE INDEX IF NOT EXISTS cache_expires ON cache (expires_at);
+  CREATE TABLE IF NOT EXISTS records (
+    scope TEXT NOT NULL, tool TEXT NOT NULL, id TEXT NOT NULL,
+    data TEXT NOT NULL, synced_at INTEGER NOT NULL,
+    PRIMARY KEY (scope, tool, id)
+  );
+  CREATE VIRTUAL TABLE IF NOT EXISTS records_fts USING fts5 (
+    text, scope UNINDEXED, tool UNINDEXED, id UNINDEXED,
+    tokenize = 'unicode61 remove_diacritics 2'
+  );
+  CREATE TABLE IF NOT EXISTS syncs (
+    scope TEXT NOT NULL, tool TEXT NOT NULL, filters TEXT NOT NULL,
+    started_at INTEGER NOT NULL, finished_at INTEGER NOT NULL,
+    records INTEGER NOT NULL, pages INTEGER NOT NULL, complete INTEGER NOT NULL,
+    PRIMARY KEY (scope, tool, filters)
+  );
+`;
+/** The longest cached result kept. Anything bigger costs more to store than to fetch again. */
+const MAX_CACHED_BYTES = 1024 * 1024;
+/** The most text from one record that search indexes. */
+const MAX_INDEXED_CHARS = 64 * 1024;
+/** One app's local data file. */
+export class DataStore {
+    file;
+    db;
+    sqlite;
+    constructor(file, db, sqlite) {
+        this.file = file;
+        this.db = db;
+        this.sqlite = sqlite;
+    }
+    /** Open the file, creating its folder and the file itself readable by their owner only. */
+    static async open(dir) {
+        const sqlite = await loadSqlite();
+        if (!sqlite)
+            throw new NoSqliteError();
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const file = join(dir, "data.db");
+        // SQLite gives its journal files the database file's own permissions, so
+        // creating the file private first keeps all three private.
+        if (!existsSync(file))
+            closeSync(openSync(file, "a", 0o600));
+        if (process.platform !== "win32" && (statSync(file).mode & 0o077) !== 0)
+            chmodSync(file, 0o600);
+        const db = new sqlite.DatabaseSync(file);
+        db.exec("PRAGMA journal_mode = WAL; PRAGMA busy_timeout = 5000; PRAGMA synchronous = NORMAL;");
+        db.exec(SCHEMA);
+        db.prepare("INSERT OR IGNORE INTO meta (key, value) VALUES ('schema', ?)").run(String(SCHEMA_VERSION));
+        return new DataStore(file, db, sqlite);
+    }
+    close() {
+        this.db.close();
+    }
+    transaction(work) {
+        this.db.exec("BEGIN IMMEDIATE");
+        try {
+            const result = work();
+            this.db.exec("COMMIT");
+            return result;
+        }
+        catch (error) {
+            this.db.exec("ROLLBACK");
+            throw error;
+        }
+    }
+    cacheGet(scope, tool, key, now = Date.now()) {
+        const row = this.db.prepare("SELECT value, stored_at FROM cache WHERE scope = ? AND tool = ? AND key = ? AND expires_at > ?").get(scope, tool, key, now);
+        return row ? { value: JSON.parse(row.value), storedAt: Number(row.stored_at) } : undefined;
+    }
+    cachePut(scope, tool, key, value, ttlSeconds, now = Date.now()) {
+        const text = JSON.stringify(value);
+        if (text === undefined || text.length > MAX_CACHED_BYTES)
+            return;
+        this.db.prepare("DELETE FROM cache WHERE expires_at <= ?").run(now);
+        this.db
+            .prepare("INSERT OR REPLACE INTO cache (scope, tool, key, value, stored_at, expires_at) VALUES (?, ?, ?, ?, ?, ?)")
+            .run(scope, tool, key, text, now, now + Math.round(ttlSeconds * 1000));
+    }
+    /** Forget every cached result for one account, after anything changed it. */
+    cacheClear(scope) {
+        const result = scope === undefined ? this.db.prepare("DELETE FROM cache").run() : this.db.prepare("DELETE FROM cache WHERE scope = ?").run(scope);
+        return Number(result.changes);
+    }
+    /** Store a page of records. Each is replaced whole, and indexed for search. */
+    putRecords(scope, tool, records, syncedAt) {
+        const upsert = this.db.prepare("INSERT OR REPLACE INTO records (scope, tool, id, data, synced_at) VALUES (?, ?, ?, ?, ?)");
+        const unindex = this.db.prepare("DELETE FROM records_fts WHERE scope = ? AND tool = ? AND id = ?");
+        const index = this.db.prepare("INSERT INTO records_fts (text, scope, tool, id) VALUES (?, ?, ?, ?)");
+        this.transaction(() => {
+            for (const record of records) {
+                upsert.run(scope, tool, record.id, JSON.stringify(record.data) ?? "null", syncedAt);
+                unindex.run(scope, tool, record.id);
+                index.run(searchText(record.data), scope, tool, record.id);
+            }
+        });
+    }
+    /** After a complete sync, drop the records the service no longer lists. */
+    removeUnseen(scope, tool, syncedBefore) {
+        return this.transaction(() => {
+            const gone = this.db.prepare("SELECT id FROM records WHERE scope = ? AND tool = ? AND synced_at < ?").all(scope, tool, syncedBefore);
+            const unindex = this.db.prepare("DELETE FROM records_fts WHERE scope = ? AND tool = ? AND id = ?");
+            for (const row of gone)
+                unindex.run(scope, tool, row.id);
+            this.db.prepare("DELETE FROM records WHERE scope = ? AND tool = ? AND synced_at < ?").run(scope, tool, syncedBefore);
+            return gone.length;
+        });
+    }
+    recordSync(scope, tool, filters, run) {
+        this.db
+            .prepare("INSERT OR REPLACE INTO syncs (scope, tool, filters, started_at, finished_at, records, pages, complete) VALUES (?, ?, ?, ?, ?, ?, ?, ?)")
+            .run(scope, tool, filters, run.startedAt, Date.now(), run.records, run.pages, run.complete ? 1 : 0);
+    }
+    search(scope, words, options = {}) {
+        const query = matchQuery(words);
+        if (!query)
+            return [];
+        const limit = Math.max(1, Math.min(100, options.limit ?? 20));
+        const rows = this.db
+            .prepare(`SELECT f.tool AS tool, f.id AS id, snippet(records_fts, 0, '[', ']', '…', 12) AS snippet, r.data AS data
+         FROM records_fts f JOIN records r ON r.scope = f.scope AND r.tool = f.tool AND r.id = f.id
+         WHERE records_fts MATCH ? AND f.scope = ? ${options.tool ? "AND f.tool = ?" : ""}
+         ORDER BY rank LIMIT ?`)
+            .all(...[query, scope, ...(options.tool ? [options.tool] : []), limit]);
+        return rows.map((row) => ({ tool: row.tool, id: row.id, snippet: row.snippet, record: JSON.parse(row.data) }));
+    }
+    synced(scope) {
+        const counts = this.db.prepare("SELECT tool, COUNT(*) AS n FROM records WHERE scope = ? GROUP BY tool ORDER BY tool").all(scope);
+        const last = this.db.prepare("SELECT tool, MAX(finished_at) AS at, MAX(complete) AS complete FROM syncs WHERE scope = ? GROUP BY tool").all(scope);
+        const tools = new Set([...counts.map((row) => row.tool), ...last.map((row) => row.tool)]);
+        return [...tools].sort().map((tool) => {
+            const count = counts.find((row) => row.tool === tool);
+            const sync = last.find((row) => row.tool === tool);
+            return {
+                tool,
+                records: Number(count?.n ?? 0),
+                ...(sync ? { last_sync: new Date(Number(sync.at)).toISOString(), complete: Boolean(sync.complete) } : {}),
+            };
+        });
+    }
+    cacheEntries(scope, now = Date.now()) {
+        return Number(this.db.prepare("SELECT COUNT(*) AS n FROM cache WHERE scope = ? AND expires_at > ?").get(scope, now).n);
+    }
+    /** Delete one account's synced records, for one tool or all of them. */
+    clearRecords(scope, tool) {
+        return this.transaction(() => {
+            const where = tool ? "scope = ? AND tool = ?" : "scope = ?";
+            const params = tool ? [scope, tool] : [scope];
+            const removed = Number(this.db.prepare(`DELETE FROM records WHERE ${where}`).run(...params).changes);
+            this.db.prepare(`DELETE FROM records_fts WHERE ${where}`).run(...params);
+            this.db.prepare(`DELETE FROM syncs WHERE ${where}`).run(...params);
+            return removed;
+        });
+    }
+    /**
+     * Run one read-only statement on its own connection, which SQLite itself
+     * refuses to write through, whatever the statement says.
+     */
+    query(sql) {
+        const reader = new this.sqlite.DatabaseSync(this.file, { readOnly: true });
+        try {
+            reader.exec("PRAGMA query_only = 1");
+            let statement;
+            try {
+                statement = reader.prepare(sql);
+            }
+            catch (error) {
+                throw new UsageError(`SQL error: ${error.message}`, { hint: "Tables: records (scope, tool, id, data, synced_at), cache, syncs. data is JSON: json_extract(data, '$.title')." });
+            }
+            const wanted = sql.trim().replace(/;\s*$/, "").length;
+            const compiled = statement.sourceSQL.trim().replace(/;\s*$/, "").length;
+            if (compiled < wanted)
+                throw new UsageError("Run one statement at a time.");
+            try {
+                return statement.all().map((row) => ({ ...row }));
+            }
+            catch (error) {
+                throw new UsageError(`SQL error: ${error.message}`);
+            }
+        }
+        finally {
+            reader.close();
+        }
+    }
+}
+const stores = new Map();
+/** The open store for a folder, shared by every call in this process. */
+export function storeAt(dir) {
+    let store = stores.get(dir);
+    if (!store) {
+        store = DataStore.open(dir);
+        store.catch(() => stores.delete(dir));
+        stores.set(dir, store);
+    }
+    return store;
+}
+/** Close every open store. For tests and for a server shutting down. */
+export async function closeStores() {
+    const open = [...stores.values()];
+    stores.clear();
+    for (const store of open)
+        (await store.catch(() => undefined))?.close();
+}
+/**
+ * Which account data belongs to. Cached results and synced records are only
+ * ever read back for the account they came from, so switching keys never shows
+ * one account another's data.
+ */
+export function scopeOf(credentials, explicit) {
+    if (explicit)
+        return `id:${sha256(explicit).slice(0, 16)}`;
+    const values = credentials.filter((value) => typeof value === "string" && value.length > 0).sort();
+    return values.length ? `key:${sha256(values.join("\0")).slice(0, 16)}` : "default";
+}
+/** The cache key for one call: the tool's own arguments, in a stable order. */
+export function cacheKey(args) {
+    return sha256(stableJson(args));
+}
+/** Every string and number in a record, which is what full-text search reads. */
+export function searchText(value) {
+    const parts = [];
+    let size = 0;
+    const visit = (node) => {
+        if (size > MAX_INDEXED_CHARS)
+            return;
+        if (typeof node === "string") {
+            parts.push(node);
+            size += node.length;
+        }
+        else if (typeof node === "number" && Number.isFinite(node))
+            parts.push(String(node));
+        else if (Array.isArray(node))
+            node.forEach(visit);
+        else if (node && typeof node === "object")
+            Object.values(node).forEach(visit);
+    };
+    visit(value);
+    return parts.join("\n").slice(0, MAX_INDEXED_CHARS);
+}
+/**
+ * Words a person typed, as an FTS5 query that cannot be a syntax error: every
+ * word must appear, the last may be the start of a word.
+ */
+export function matchQuery(words) {
+    const terms = words.split(/\s+/).map((term) => term.trim()).filter(Boolean);
+    return terms.map((term, i) => `"${term.replace(/"/g, '""')}"${i === terms.length - 1 ? "*" : ""}`).join(" ");
+}

package/dist/docs.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Reference documentation generated from the tool list.
+ *
+ * A hand-written table of tools and arguments goes stale the day a tool is
+ * added. This one is printed from the same definitions the server and CLI use,
+ * so pasting it into a README is the last time anyone edits it by hand.
+ */
+import type { App } from "./app.js";
+import type { Tool } from "./tool.js";
+export declare function toolTable(app: App, tools: readonly Tool[]): string;
+export declare function toolReference(app: App, tools: readonly Tool[], heading?: string): string;
+export declare function settingsTable(app: App): string;
+export declare function renderDocs(app: App, env?: NodeJS.ProcessEnv): string;

package/dist/docs.js

@@ -0,0 +1,66 @@
+/**
+ * Reference documentation generated from the tool list.
+ *
+ * A hand-written table of tools and arguments goes stale the day a tool is
+ * added. This one is printed from the same definitions the server and CLI use,
+ * so pasting it into a README is the last time anyone edits it by hand.
+ */
+import { flagsFor } from "./cli/flags.js";
+import { exampleCommand } from "./cli/help.js";
+import { policyEnvNames } from "./policy.js";
+function cell(text) {
+    return text.replace(/\|/g, "\\|").replace(/\s*\n\s*/g, " ").trim() || "None";
+}
+function riskWords(tool) {
+    const base = tool.risk === "read" ? "Read" : tool.risk === "write" ? "Write" : "Irreversible";
+    return tool.requireConfirm ? `${base}, needs confirm` : base;
+}
+export function toolTable(app, tools) {
+    const lines = ["| Command | What it does | Risk |", "|---|---|---|"];
+    for (const tool of tools)
+        lines.push(`| \`${tool.command}\` | ${cell(tool.title)} | ${riskWords(tool)} |`);
+    return lines.join("\n");
+}
+export function toolReference(app, tools, heading = "###") {
+    const sections = [];
+    for (const tool of tools) {
+        const flags = flagsFor(tool.jsonSchema).filter((flag) => flag.key !== "confirm");
+        const lines = [`${heading} \`${tool.command}\``, ``, `**${cell(tool.title)}.** ${tool.description}`, ``];
+        if (flags.length) {
+            lines.push("| Argument | Type | Required | Description |", "|---|---|---|---|");
+            for (const flag of flags) {
+                const type = flag.choices ? flag.choices.map((choice) => `\`${choice}\``).join(", ") : flag.repeatable ? `${flag.kind} list` : flag.kind;
+                lines.push(`| \`${flag.key}\` | ${type} | ${flag.required ? "Yes" : "No"} | ${cell(flag.help)} |`);
+            }
+            lines.push(``);
+        }
+        lines.push(`Risk: ${riskWords(tool)}.`, ``);
+        if (tool.examples.length) {
+            lines.push("```bash");
+            for (const example of tool.examples)
+                lines.push(`# ${example.description}`, exampleCommand(app.bins.cli, tool, example.args));
+            lines.push("```", ``);
+        }
+        sections.push(lines.join("\n"));
+    }
+    return sections.join("\n");
+}
+export function settingsTable(app) {
+    const names = policyEnvNames(app.envPrefix);
+    return [
+        "| Variable | What it does |",
+        "|---|---|",
+        ...(app.definition.settings ?? []).map((setting) => `| \`${setting.env}\` | ${cell(setting.description)}${setting.secret ? " Keep it private." : ""} |`),
+        `| \`${names.readOnly}=1\` | Hide and refuse every write |`,
+        `| \`${names.allowDestructive}=0\` | Keep writes, refuse the public or irreversible ones |`,
+        `| \`${names.toolsets}\` | Comma-separated toolsets to turn on, or \`all\` |`,
+        `| \`${names.surface}=search\` | List three tools that find, describe and run the rest |`,
+        `| \`${names.auditLog}\` | File that records every attempted write |`,
+        `| \`${names.toolTimeoutMs}\` | Give up on any tool after this many milliseconds |`,
+        `| \`${names.confirm}=model\` | Let \`confirm: true\` alone confirm a call, for an agent with no person to ask. The default, \`human\`, asks a person wherever the client can |`,
+    ].join("\n");
+}
+export function renderDocs(app, env = process.env) {
+    const tools = app.tools(env);
+    return [`## Commands`, ``, toolTable(app, tools), ``, `## Reference`, ``, toolReference(app, tools), `## Settings`, ``, settingsTable(app), ``].join("\n");
+}