toolnexus 0.21.0 → 0.22.0

package/dist/index.js

@@ -14,6 +14,7 @@ export * from "./adapters.js";
 export * from "./translate.js";
 export * from "./toolkit.js";
 export * from "./client.js";
+export * from "./store.js";
 export * from "./classifier.js";
 export * as agents from "./agents/index.js";
 // Simple judgments (§8B, add-judge-adapters). `judge.noul/choice/score` are the NAMED builders
@@ -22,3 +23,7 @@ export * as judge from "./judge.js";
 // Judge batteries (§8B "Batteries", add-judge-batteries): eight `*Classifier` values + latestUserText.
 export * from "./batteries.js";
 export { State, context, questionMap, ask, gate, decide, applyGate, applyPolicy, answersOf, staticClassifier, Tape, DEFAULT_BANDS, } from "./judge.js";
+export * from "./promptcache.js";
+export * from "./tooltiers.js";
+export * from "./models.js";
+export * from "./builtin_extras.js";

package/dist/mcp.d.ts

@@ -1,5 +1,5 @@
 import type { ElicitRequest, ElicitResult } from "@modelcontextprotocol/sdk/types.js";
-import { type JSONSchema, type Tool, type McpStatus, type Request, type Answer } from "./types.js";
+import { type JSONSchema, type Tool, type ToolHints, type McpStatus, type Request, type Answer } from "./types.js";
 import { type ContentPart } from "./content.js";
 /** Map an MCP `elicitation/create` request onto a §10 `Request`. */
 export declare function elicitationToRequest(params: ElicitRequest["params"]): Request;
@@ -50,13 +50,44 @@ export interface McpSource {
     tools: Tool[];
     status: Record<string, McpStatus>;
     close(): Promise<void>;
+    /**
+     * `list_mcp_resources` and `read_mcp_resource` bound to this source's connected servers
+     * (SPEC §4C). Both read-only. Opt-in: register them on a toolkit. They stop working once the
+     * source is closed.
+     */
+    resourceTools(): Tool[];
 }
+/** One server's outcome, reported by `loadMcp`'s `onServer` the moment that server finishes. */
+export interface McpServerResult {
+    name: string;
+    status: McpStatus;
+    /** This server's converted tools (empty unless connected). Usable until the source closes. */
+    tools: Tool[];
+    /** Why the server failed (absent when connected or disabled). */
+    error?: Error;
+}
+/**
+ * MCP tool annotations → ToolHints (SPEC §4C). No hint fields at all ⇒ undefined (unknown).
+ * Defaults follow the MCP spec: readOnlyHint false, destructiveHint and openWorldHint true.
+ */
+export declare function mcpHints(a: {
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    openWorldHint?: boolean;
+} | undefined): ToolHints | undefined;
 /** Connect to every enabled server, list + convert tools. Failures are isolated.
  *  §2 Gap 3: an optional `signal` bounds each connect/list by the server timeout and aborts the
  *  whole load promptly on parent cancellation. */
 export declare function loadMcp(input: string | object, opts?: {
     waitFor?: (request: Request) => Promise<Answer>;
     signal?: AbortSignal;
+    /**
+     * Called once per server the moment it is connected, failed or found disabled (SPEC §4C),
+     * so a host can register a fast server's tools while a slow one is still connecting.
+     * Calls are serialized (an async callback is awaited before the next one runs); the load
+     * still resolves only after every server and every callback has finished.
+     */
+    onServer?: (result: McpServerResult) => void | Promise<void>;
 }): Promise<McpSource>;
 /** §2 Gap 6. One listed tool definition (original, unprefixed name). */
 export interface ToolInfo {

package/dist/mcp.js

@@ -59,12 +59,36 @@ export function parseMcpConfig(input) {
     const raw = typeof input === "string" ? JSON.parse(readFileSync(input, "utf8")) : input;
     const wrapped = raw.mcpServers ?? raw.servers ?? raw.mcp;
     if (wrapped !== undefined)
-        return wrapped;
+        return normalizeServers(wrapped);
     // Bare map of servers — but strip sibling top-level config keys (builtins/
     // agents/a2a/mcpServer) so they are not mistaken for MCP servers when no
     // wrapper key is present.
     const { builtins: _builtins, agents: _agents, a2a: _a2a, mcpServer: _mcpServer, ...servers } = raw;
-    return servers;
+    return normalizeServers(servers);
+}
+/**
+ * §2 `command` + `args`. A local server's `command` may be a non-empty string or a non-empty
+ * string array; an optional `args` string array is appended. The result is always the argv form
+ * (`command: string[]`, no `args`). Spawned with no shell. A remote server ignores `args`.
+ */
+function normalizeServers(servers) {
+    const out = {};
+    for (const [name, cfg] of Object.entries(servers ?? {})) {
+        if (cfg === null || typeof cfg !== "object" || isRemote(cfg)) {
+            out[name] = cfg;
+            continue;
+        }
+        const { args, command, ...rest } = cfg;
+        const head = typeof command === "string" ? [command] : Array.isArray(command) ? command : undefined;
+        if (!head || head.length === 0 || head[0] === "" || head.some((c) => typeof c !== "string")) {
+            throw new Error(`mcp server "${name}": invalid command`);
+        }
+        if (args !== undefined && (!Array.isArray(args) || args.some((a) => typeof a !== "string"))) {
+            throw new Error(`mcp server "${name}": invalid args`);
+        }
+        out[name] = { ...rest, command: [...head, ...(args ?? [])] };
+    }
+    return out;
 }
 /**
  * Expand ${ENV_VAR} in header values from process.env so tokens live in the
@@ -212,9 +236,14 @@ function convertTool(server, def, client, timeout) {
         description: def.description ?? "",
         inputSchema,
         source: "mcp",
+        ...(mcpHints(def.annotations) ? { hints: mcpHints(def.annotations) } : {}),
         async execute(args, ctx) {
             try {
-                const result = await client.callTool({ name: def.name, arguments: args ?? {} }, undefined, { resetTimeoutOnProgress: true, signal: ctx?.signal, timeout: ctx?.timeout ?? timeout });
+                const result = await client.callTool({ name: def.name, arguments: args ?? {} }, undefined, 
+                // The SDK only attaches `_meta.progressToken` when `onprogress` is supplied; without it
+                // `resetTimeoutOnProgress` never fires (add-mcp-progress-timeout). Notifications for a
+                // token that matches no in-flight request are dropped by the SDK, so they never reset.
+                { onprogress: () => { }, resetTimeoutOnProgress: true, signal: ctx?.signal, timeout: ctx?.timeout ?? timeout });
                 // Parts are collected BEFORE any branch returns: the isError and structuredContent
                 // short-circuits both read `content[]` on the way past, so neither reintroduces the
                 // silent drop this mapping exists to remove (§2).
@@ -235,6 +264,120 @@ function convertTool(server, def, client, timeout) {
         },
     };
 }
+/**
+ * MCP tool annotations → ToolHints (SPEC §4C). No hint fields at all ⇒ undefined (unknown).
+ * Defaults follow the MCP spec: readOnlyHint false, destructiveHint and openWorldHint true.
+ */
+export function mcpHints(a) {
+    if (!a || (a.readOnlyHint === undefined && a.destructiveHint === undefined && a.openWorldHint === undefined))
+        return undefined;
+    const h = { readOnly: a.readOnlyHint ?? false, destructive: a.destructiveHint ?? true, openWorld: a.openWorldHint ?? true };
+    if (h.readOnly)
+        h.destructive = false;
+    return h;
+}
+function resourceTools(servers) {
+    const ro = { readOnly: true, destructive: false, openWorld: false };
+    const names = () => [...servers.keys()].sort();
+    const conn = (server) => {
+        const c = servers.get(server);
+        if (!c)
+            throw new Error(`no connected MCP server "${server}" (connected: ${names().join(", ")})`);
+        return c;
+    };
+    const list = {
+        name: "list_mcp_resources",
+        description: "List the resources MCP servers offer (uri, name, description, mimeType). Optionally for one server.",
+        inputSchema: {
+            type: "object",
+            properties: { server: { type: "string", description: "Only this server (default: all)" } },
+            additionalProperties: false,
+        },
+        source: "mcp",
+        hints: ro,
+        async execute(args, ctx) {
+            let targets = names();
+            const s = typeof args?.server === "string" ? args.server : "";
+            if (s) {
+                try {
+                    conn(s);
+                }
+                catch (e) {
+                    return { output: `list_mcp_resources: ${e.message}`, isError: true };
+                }
+                targets = [s];
+            }
+            const lines = [];
+            const items = [];
+            for (const name of targets) {
+                const c = conn(name);
+                try {
+                    const res = await c.client.listResources({}, { timeout: c.timeout, signal: ctx?.signal });
+                    for (const r of res.resources ?? []) {
+                        let line = `${name} ${r.uri}`;
+                        if (r.name)
+                            line += ` — ${r.name}`;
+                        if (r.mimeType)
+                            line += ` (${r.mimeType})`;
+                        if (r.description)
+                            line += `: ${r.description}`;
+                        lines.push(line);
+                        items.push({ server: name, uri: r.uri, name: r.name ?? "", mimeType: r.mimeType ?? "", description: r.description ?? "" });
+                    }
+                }
+                catch (e) {
+                    lines.push(`${name}: error: ${e instanceof Error ? e.message : String(e)}`);
+                }
+            }
+            if (!lines.length)
+                return { output: "No resources.", isError: false, metadata: { count: 0 } };
+            return { output: lines.join("\n"), isError: false, metadata: { count: items.length, resources: items } };
+        },
+    };
+    const read = {
+        name: "read_mcp_resource",
+        description: "Read one MCP resource by server and uri. Text comes back as text; binary content is described, not inlined.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                server: { type: "string", description: "The MCP server name" },
+                uri: { type: "string", description: "The resource uri" },
+            },
+            required: ["server", "uri"],
+            additionalProperties: false,
+        },
+        source: "mcp",
+        hints: ro,
+        async execute(args, ctx) {
+            const server = typeof args?.server === "string" ? args.server : "";
+            const uri = typeof args?.uri === "string" ? args.uri : "";
+            let c;
+            try {
+                c = conn(server);
+            }
+            catch (e) {
+                return { output: `read_mcp_resource: ${e.message}`, isError: true };
+            }
+            if (!uri)
+                return { output: "read_mcp_resource: uri is required", isError: true };
+            try {
+                const res = await c.client.readResource({ uri }, { timeout: c.timeout, signal: ctx?.signal });
+                const parts = [];
+                for (const rc of res.contents ?? []) {
+                    if (typeof rc.text === "string")
+                        parts.push(rc.text);
+                    else if (typeof rc.blob === "string")
+                        parts.push(`[binary ${rc.mimeType ?? ""}, ${rc.blob.length} base64 chars]`);
+                }
+                return { output: parts.join("\n"), isError: false, metadata: { server, uri } };
+            }
+            catch (e) {
+                return { output: `read_mcp_resource: ${e instanceof Error ? e.message : String(e)}`, isError: true };
+            }
+        },
+    };
+    return [list, read];
+}
 /** Create a fresh (not-yet-connected) client, with the elicitation bridge attached if a waitFor
  *  exists. Separated from connect so the caller ALWAYS holds a closeable reference — even if the
  *  connect is later abandoned by a timeout/abort, `client.close()` still terminates any spawned
@@ -279,11 +422,28 @@ export async function loadMcp(input, opts) {
     const tools = [];
     const status = {};
     const clients = [];
+    const servers = new Map();
     const waitFor = opts?.waitFor;
     const signal = opts?.signal;
-    await Promise.all(Object.entries(config).map(async ([name, cfg]) => {
+    const onServer = opts?.onServer;
+    let reports = Promise.resolve();
+    let reportError;
+    const report = (r) => {
+        if (!onServer)
+            return;
+        reports = reports.then(async () => {
+            try {
+                await onServer(r);
+            }
+            catch (e) {
+                reportError ??= e;
+            }
+        });
+    };
+    const loading = Promise.all(Object.entries(config).map(async ([name, cfg]) => {
         if (!isEnabled(cfg)) {
             status[name] = "disabled";
+            report({ name, status: "disabled", tools: [] });
             return;
         }
         const timeout = cfg.timeout ?? DEFAULT_TIMEOUT;
@@ -294,10 +454,12 @@ export async function loadMcp(input, opts) {
             await raceTimeout(connectTransport(client, cfg), timeout, signal);
             const defs = await raceTimeout(paginateTools(client, timeout), timeout, signal);
             const kept = applyToolsFilter(name, defs, cfg.tools);
-            for (const def of kept)
-                tools.push(convertTool(name, def, client, timeout));
+            const converted = kept.map((def) => convertTool(name, def, client, timeout));
+            tools.push(...converted);
             clients.push(client);
+            servers.set(name, { client, timeout });
             status[name] = "connected";
+            report({ name, status: "connected", tools: converted });
         }
         catch (e) {
             status[name] = "failed";
@@ -306,15 +468,31 @@ export async function loadMcp(input, opts) {
             // within budget isolates just this server.
             if (signal?.aborted)
                 throw e;
+            report({ name, status: "failed", tools: [], error: e instanceof Error ? e : new Error(String(e)) });
             console.warn(`[toolnexus] MCP server "${name}" failed: ${e instanceof Error ? e.message : String(e)}`);
         }
     }));
+    try {
+        await loading;
+    }
+    catch (e) {
+        // Parent cancellation: close every client, including ones whose tools onServer handed out.
+        await reports;
+        await Promise.all(clients.map((c) => c.close().catch(() => { })));
+        throw e;
+    }
+    await reports;
+    if (reportError) {
+        await Promise.all(clients.map((c) => c.close().catch(() => { })));
+        throw reportError;
+    }
     return {
         tools,
         status,
         async close() {
             await Promise.all(clients.map((c) => c.close().catch(() => { })));
         },
+        resourceTools: () => resourceTools(servers),
     };
 }
 /**

package/dist/models.d.ts

@@ -0,0 +1,20 @@
+/**
+ * listModels (SPEC §4C): the models a provider offers, for model switching. One GET per page,
+ * no retries. Same key rules as the client (apiKey, apiKeyEnv, or the host's own env var).
+ */
+import { type ClientOptions } from "./client.js";
+/** One model a provider lists. */
+export interface ModelInfo {
+    id: string;
+    /** The provider's display name, when it gives one. */
+    name?: string;
+    /** Context window in tokens when the provider reports it (OpenRouter does). */
+    contextLength?: number;
+}
+/**
+ * List the models at `opts.baseUrl` in `opts.style`: openai `GET {base}/models`; anthropic
+ * `GET {base}/v1/models`, following `has_more`/`last_id`. Sorted by id.
+ */
+export declare function listModels(opts: Pick<ClientOptions, "baseUrl" | "style" | "apiKey" | "apiKeyEnv" | "headers" | "fetch">, ctx?: {
+    signal?: AbortSignal;
+}): Promise<ModelInfo[]>;

package/dist/models.js

@@ -0,0 +1,46 @@
+/**
+ * listModels (SPEC §4C): the models a provider offers, for model switching. One GET per page,
+ * no retries. Same key rules as the client (apiKey, apiKeyEnv, or the host's own env var).
+ */
+import { resolveKey } from "./client.js";
+async function getJson(f, url, headers, signal) {
+    const res = await f(url, { method: "GET", headers, signal });
+    const text = await res.text();
+    if (!res.ok)
+        throw new Error(`list models: HTTP ${res.status}: ${text.slice(0, 300)}`);
+    return JSON.parse(text);
+}
+/**
+ * List the models at `opts.baseUrl` in `opts.style`: openai `GET {base}/models`; anthropic
+ * `GET {base}/v1/models`, following `has_more`/`last_id`. Sorted by id.
+ */
+export async function listModels(opts, ctx) {
+    const key = resolveKey(opts);
+    const f = opts.fetch ?? fetch;
+    const base = opts.baseUrl.replace(/\/+$/, "");
+    const out = [];
+    if (opts.style === "anthropic") {
+        const endpoint = base.endsWith("/v1") ? `${base}/models` : `${base}/v1/models`;
+        let after = "";
+        for (let page = 0; page < 100; page++) {
+            const url = `${endpoint}?limit=1000${after ? `&after_id=${encodeURIComponent(after)}` : ""}`;
+            const body = await getJson(f, url, { "x-api-key": key, "anthropic-version": "2023-06-01", ...opts.headers }, ctx?.signal);
+            for (const m of body?.data ?? [])
+                out.push({ id: m.id, ...(m.display_name ? { name: m.display_name } : {}) });
+            if (!body?.has_more || !body?.last_id)
+                break;
+            after = body.last_id;
+        }
+    }
+    else {
+        const body = await getJson(f, `${base}/models`, { Authorization: `Bearer ${key}`, ...opts.headers }, ctx?.signal);
+        for (const m of body?.data ?? []) {
+            out.push({
+                id: m.id,
+                ...(m.name ? { name: m.name } : {}),
+                ...(typeof m.context_length === "number" && m.context_length > 0 ? { contextLength: m.context_length } : {}),
+            });
+        }
+    }
+    return out.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}

package/dist/promptcache.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Prompt caching (SPEC §8 "Prompt caching", change add-prompt-cache). The engine keeps the
+ * request prefix stable and marks it for the provider's cache.
+ */
+/** `ClientOptions.promptCache`. */
+export interface PromptCacheOptions {
+    /** Groups requests that share a prefix (one per session). Sent as openai `prompt_cache_key`.
+     * Ignored by anthropic, which caches by prefix. */
+    key?: string;
+    /** Ask for the provider's longer cache lifetime where one exists (anthropic `ttl: "1h"`). */
+    longTTL?: boolean;
+}
+/**
+ * Mark the cacheable prefix in an assembled body, in place. The transcript's own objects are
+ * never mutated: every touched entry is copied.
+ *  - anthropic: `cache_control` on the last tool, the system prompt (a string becomes one text
+ *    block) and the last content block of the latest message (3 of the 4 allowed breakpoints).
+ *  - openai: `prompt_cache_key = key` when set; the prefix is cached automatically.
+ *  - gemini: nothing yet (explicit cachedContent is deferred).
+ */
+export declare function applyPromptCache(body: Record<string, any>, style: string, o: PromptCacheOptions): void;

package/dist/promptcache.js

@@ -0,0 +1,59 @@
+/**
+ * Prompt caching (SPEC §8 "Prompt caching", change add-prompt-cache). The engine keeps the
+ * request prefix stable and marks it for the provider's cache.
+ */
+function withCacheControl(v, mark) {
+    if (!v || typeof v !== "object" || Array.isArray(v))
+        return v;
+    return { ...v, cache_control: mark };
+}
+/**
+ * Mark the cacheable prefix in an assembled body, in place. The transcript's own objects are
+ * never mutated: every touched entry is copied.
+ *  - anthropic: `cache_control` on the last tool, the system prompt (a string becomes one text
+ *    block) and the last content block of the latest message (3 of the 4 allowed breakpoints).
+ *  - openai: `prompt_cache_key = key` when set; the prefix is cached automatically.
+ *  - gemini: nothing yet (explicit cachedContent is deferred).
+ */
+export function applyPromptCache(body, style, o) {
+    if (style === "anthropic") {
+        const mark = { type: "ephemeral" };
+        if (o.longTTL)
+            mark.ttl = "1h";
+        if (Array.isArray(body.tools) && body.tools.length > 0) {
+            const out = [...body.tools];
+            out[out.length - 1] = withCacheControl(out[out.length - 1], mark);
+            body.tools = out;
+        }
+        if (typeof body.system === "string") {
+            if (body.system !== "")
+                body.system = [{ type: "text", text: body.system, cache_control: mark }];
+        }
+        else if (Array.isArray(body.system) && body.system.length > 0) {
+            const out = [...body.system];
+            out[out.length - 1] = withCacheControl(out[out.length - 1], mark);
+            body.system = out;
+        }
+        if (Array.isArray(body.messages) && body.messages.length > 0) {
+            const out = [...body.messages];
+            const last = out[out.length - 1];
+            if (last && typeof last === "object" && !Array.isArray(last)) {
+                const m = { ...last };
+                if (typeof m.content === "string") {
+                    m.content = [{ type: "text", text: m.content, cache_control: mark }];
+                }
+                else if (Array.isArray(m.content) && m.content.length > 0) {
+                    const blocks = [...m.content];
+                    blocks[blocks.length - 1] = withCacheControl(blocks[blocks.length - 1], mark);
+                    m.content = blocks;
+                }
+                out[out.length - 1] = m;
+            }
+            body.messages = out;
+        }
+    }
+    else if (style === "openai") {
+        if (o.key)
+            body.prompt_cache_key = o.key;
+    }
+}

package/dist/store.d.ts

@@ -0,0 +1,32 @@
+import { type ConversationEntry, type ConversationStore } from "./client.js";
+/**
+ * Durable {@link ConversationStore}: one file `<root>/<id>.json` per conversation holding
+ * `{"version":1,"messages":[...]}`. `save` writes a temp file (0600), fsyncs and renames it over
+ * the old one, so a reader sees the old or the new transcript, never a torn one (power-loss
+ * durability of the rename is best-effort). Same-id saves are serialized in-process; across
+ * processes the last rename wins.
+ */
+/**
+ * Durability mode (SPEC §8 "Durability mode"): `full` (default) flushes the file then fsyncs the
+ * directory best-effort; `fsync` flushes the file only; `none` skips every flush. Temp-then-rename
+ * holds in every mode. (On macOS Node's `fh.sync()` is libuv's fsync, which already issues
+ * `F_FULLFSYNC`; Node exposes no plainer flush, so `fsync` differs from `full` only by the dir fsync.)
+ */
+export type FileStoreSync = "full" | "fsync" | "none";
+export interface FileStoreOptions {
+    sync?: FileStoreSync;
+}
+export declare class FileConversationStore implements ConversationStore {
+    readonly root: string;
+    readonly sync: FileStoreSync;
+    private readonly chains;
+    constructor(root: string, opts?: FileStoreOptions);
+    private file;
+    get(id: string): Promise<any[] | undefined>;
+    save(id: string, messages: any[]): Promise<void>;
+    private write;
+    /** Every stored conversation, newest first (mtime; ties by id ascending). Bodies are not parsed. */
+    list(): Promise<ConversationEntry[]>;
+    /** Remove a conversation; absent ids are not an error. */
+    delete(id: string): Promise<void>;
+}

package/dist/store.js

@@ -0,0 +1,131 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+import { sortEntries } from "./client.js";
+const ID_RE = /^[A-Za-z0-9._-]{1,128}$/;
+const VERSION = 1;
+function checkId(id) {
+    if (typeof id !== "string" || !ID_RE.test(id) || id === "." || id === "..") {
+        throw new Error(`invalid conversation id: ${JSON.stringify(id)}`);
+    }
+}
+export class FileConversationStore {
+    root;
+    sync;
+    chains = new Map();
+    constructor(root, opts = {}) {
+        if (typeof root !== "string" || root === "")
+            throw new Error("FileConversationStore: root is required");
+        const mode = opts.sync ?? "full";
+        if (mode !== "full" && mode !== "fsync" && mode !== "none") {
+            throw new Error(`FileConversationStore: unknown sync mode ${JSON.stringify(opts.sync)}`);
+        }
+        this.root = root;
+        this.sync = mode;
+    }
+    file(id) {
+        return path.join(this.root, id + ".json");
+    }
+    async get(id) {
+        checkId(id);
+        let text;
+        try {
+            text = await fsp.readFile(this.file(id), "utf8");
+        }
+        catch (e) {
+            if (e?.code === "ENOENT")
+                return undefined;
+            throw e;
+        }
+        let body;
+        try {
+            body = JSON.parse(text);
+        }
+        catch (e) {
+            throw new Error(`conversation "${id}": corrupt file: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        if (body === null || typeof body !== "object" || body.version !== VERSION) {
+            throw new Error(`conversation "${id}": unsupported version ${JSON.stringify(body?.version)}`);
+        }
+        if (!Array.isArray(body.messages))
+            throw new Error(`conversation "${id}": corrupt file: messages is not an array`);
+        return body.messages;
+    }
+    async save(id, messages) {
+        checkId(id);
+        const prev = this.chains.get(id) ?? Promise.resolve();
+        const next = prev.catch(() => { }).then(() => this.write(id, messages));
+        this.chains.set(id, next);
+        try {
+            await next;
+        }
+        finally {
+            if (this.chains.get(id) === next)
+                this.chains.delete(id);
+        }
+    }
+    async write(id, messages) {
+        await fsp.mkdir(this.root, { recursive: true, mode: 0o700 });
+        const tmp = path.join(this.root, `.${id}.${randomBytes(6).toString("hex")}.tmp`);
+        const data = JSON.stringify({ version: VERSION, messages });
+        let fh;
+        try {
+            fh = await fsp.open(tmp, "w", 0o600);
+            await fh.writeFile(data, "utf8");
+            if (this.sync !== "none")
+                await fh.sync();
+            await fh.close();
+            fh = undefined;
+            await fsp.rename(tmp, this.file(id));
+        }
+        catch (e) {
+            await fh?.close().catch(() => { });
+            await fsp.rm(tmp, { force: true }).catch(() => { });
+            throw e;
+        }
+        // Best-effort parent-dir fsync so the rename itself survives power loss where supported.
+        if (this.sync !== "full")
+            return;
+        try {
+            const dir = await fsp.open(this.root, "r");
+            await dir.sync().catch(() => { });
+            await dir.close();
+        }
+        catch { }
+    }
+    /** Every stored conversation, newest first (mtime; ties by id ascending). Bodies are not parsed. */
+    async list() {
+        let names;
+        try {
+            names = await fsp.readdir(this.root);
+        }
+        catch (e) {
+            if (e?.code === "ENOENT")
+                return [];
+            throw e;
+        }
+        const out = [];
+        for (const name of names) {
+            if (!name.endsWith(".json"))
+                continue;
+            const id = name.slice(0, -5);
+            if (!ID_RE.test(id) || id === "." || id === "..")
+                continue;
+            try {
+                const st = await fsp.stat(path.join(this.root, name));
+                if (st.isFile())
+                    out.push({ id, updatedAt: st.mtime });
+            }
+            catch (e) {
+                if (e?.code !== "ENOENT")
+                    throw e;
+            }
+        }
+        return sortEntries(out);
+    }
+    /** Remove a conversation; absent ids are not an error. */
+    async delete(id) {
+        checkId(id);
+        await fsp.rm(this.file(id), { force: true });
+    }
+}