pi-optchat 0.11.1 → 0.11.2

package/dist/durable/import.js

@@ -0,0 +1,109 @@
+import { defineExtension, defineTask, ROOT_CONVERSATION_ID } from '@earendil-works/pi-durable';
+import { chronological, deduplicate, isEntry, runImport } from '../core/index.js';
+import { attachment } from './optchat.js';
+import { importTables } from './store.js';
+/** How many new summaries the import builds between the progress it saves. Pi Durable parks a task that restarts 5 times without
+ * saving progress, which a long rebuild could otherwise do over a few deploys. */
+const CHECKPOINT = 50;
+/** Imports history into a Pi Durable agent's memory: append adds it after the log, rebuild orders everything by date and summarizes
+ * it all again. The import builds a new generation beside the live one, in a Pi Durable task that resumes after an eviction, while
+ * the chat goes on with the old one; it switches in one transaction once the new one is complete. Install `extension` beside
+ * `optchat()`'s and `attach` the opened Harness. Neither the plan nor the log's texts are held in RAM. */
+export function optchatImport({ memory, db, read, open, onActivated }) {
+    const attached = attachment('OptChat import'), tables = importTables(db, read);
+    /** The generation `memory` was opened at, read when first attached: once an import goes live, `memory` is the old one's until
+     * the object restarts. */
+    let opened;
+    /** The live tasks building `generation`'s import. */
+    const tasks = async (generation) => (await attached.get().harness.inspect(attached.get().context)).tasks
+        .filter(({ record: { kind, input } }) => kind === Import.definition.name && typeof input === 'object' && input !== null && !Array.isArray(input) && input.generation === generation);
+    const createTask = (generation) => attached.get().harness.commit(tx => tx.createTask(Import, { generation }, { ownership: { kind: 'conversation' }, conversationId: ROOT_CONVERSATION_ID, background: true }), attached.get().context);
+    const Import = defineTask({
+        name: 'optchat.import', version: 1,
+        initial: () => ({ phase: 'import', done: 0 }),
+        phases: {
+            // Cut off by an eviction, the phase runs again from the top, and `runImport` carries on from the new generation's log.
+            import: async (task, runtime, ctx) => {
+                const { job } = await tables.state();
+                let activated = false, saving = Promise.resolve();
+                // A task whose import was discarded, or went live, has nothing left to do.
+                if (job?.generation === task.input.generation)
+                    await runImport({ entry: tables.planned, total: job.total, activate: async () => { await tables.activate(job.generation); activated = true; },
+                        open: async () => {
+                            const building = await open(job.generation);
+                            // From the progress last saved, so what earlier runs built before they were cut off counts too.
+                            let done = task.state.checkpoint.done;
+                            const checkpoint = () => {
+                                if (building.tree.size < done + CHECKPOINT)
+                                    return;
+                                done = building.tree.size;
+                                saving = saving.then(() => runtime.commit(() => ({ status: 'running', checkpoint: { phase: 'import', done } }), ctx)).catch(() => { });
+                            };
+                            building.onChange(checkpoint);
+                            checkpoint();
+                            return building;
+                        } }, runtime.signal);
+                await saving;
+                // Once the switch is saved the old memory must go, even if this commit fails: nothing would call it later.
+                try {
+                    await runtime.commit(() => ({ status: 'terminal', outcome: { status: 'completed', result: null } }), ctx);
+                }
+                finally {
+                    if (activated)
+                        onActivated();
+                }
+            },
+        },
+        abort: (_task, runtime, ctx) => runtime.commit(() => ({ status: 'terminal', outcome: { status: 'aborted' } }), ctx),
+    });
+    return {
+        extension: defineExtension({ name: 'optchat.import', tasks: [Import] }),
+        /** Runs a pending import whose task is gone: it failed, or the object died before creating it. Returns a function that stops. */
+        attach(harness, ctx) {
+            attached.set(harness, ctx);
+            opened ??= tables.state().then(state => state.live);
+            void (async () => { const { job } = await tables.state(); if (job && !(await tasks(job.generation)).length)
+                await createTask(job.generation); })()
+                .catch(error => console.error(`OptChat could not resume the import: ${error instanceof Error ? error.message : String(error)}`));
+            return attached.clear;
+        },
+        /** Plans an import of `incoming` and starts building it, with its counts; undefined when nothing in it is new. Refused for an
+         * invalid entry, while another is pending, once memory failed a save, or after a switch until the object restarts. */
+        async start(incoming, mode) {
+            attached.get();
+            if (!opened)
+                throw new Error('OptChat import is not attached to a Harness yet.');
+            const live = await opened;
+            // Up front: a plan that fails later would stay pending, blocking every import after it.
+            if (!incoming.every(e => isEntry({ ...e, i: 0 })))
+                throw new Error('Imported entry is invalid.');
+            if (memory.saveError)
+                throw new Error(`Memory could not be saved: ${memory.saveError}; restart before importing.`);
+            // Planned from metadata; each text is read from memory as its plan row is written.
+            const { added, skipped } = deduplicate(memory.root, incoming);
+            if (!added.length)
+                return undefined;
+            const all = mode === 'rebuild' ? chronological([...memory.root, ...added]) : [...memory.root, ...chronological(added)];
+            const plan = function* () { for (const [i, e] of all.entries())
+                yield 'text' in e ? { ...e, i } : { ...e, i, text: memory.text(e.i) }; };
+            const job = await tables.stage(live, mode, plan(), mode === 'append' ? memory.root.length : 0);
+            await createTask(job.generation);
+            return { ...job, added: added.length, skipped };
+        },
+        /** The pending import, if any, with its task's state: running, ready, or blocked (parked after restarts: `harness.retryTask`).
+         * No task means it failed; `attach` starts it again at the next restart. */
+        async pending() {
+            const { job } = await tables.state();
+            return job && { ...job, task: (await tasks(job.generation))[0]?.state };
+        },
+        /** Stops the pending import; the live memory is left as it is. One started meanwhile is left alone. */
+        async discard() {
+            const { job } = await tables.state();
+            if (!job)
+                return;
+            for (const task of await tasks(job.generation))
+                await attached.get().harness.abortTask(task.record.id, attached.get().context);
+            await tables.discard(job.generation);
+        },
+    };
+}

package/dist/durable/index.d.ts

@@ -0,0 +1,5 @@
+/** OptChat's memory on Pi Durable, for a Cloudflare Durable Object or any other Pi Durable host: a Store over SQLite, the extension
+ * that builds each request from the view, imports, and cache marks for its models. Build the memory with `pi-optchat/core`. */
+export { SqliteStore, type Read, type SqliteStoreOptions } from './store.ts';
+export { optchat, withCacheMarks, type OptChatOptions } from './optchat.ts';
+export { optchatImport, type ImportJob, type ImportOptions } from './import.ts';

package/dist/durable/index.js

@@ -0,0 +1,5 @@
+/** OptChat's memory on Pi Durable, for a Cloudflare Durable Object or any other Pi Durable host: a Store over SQLite, the extension
+ * that builds each request from the view, imports, and cache marks for its models. Build the memory with `pi-optchat/core`. */
+export { SqliteStore } from './store.js';
+export { optchat, withCacheMarks } from './optchat.js';
+export { optchatImport } from './import.js';

package/dist/durable/optchat.d.ts

@@ -0,0 +1,42 @@
+import { type ConversationId, type Harness, type HarnessOptions } from '@earendil-works/pi-durable';
+import { type Memory } from '../core/index.ts';
+export type Context = Parameters<Harness['commit']>[1];
+type Models = Exclude<HarnessOptions['models'], () => unknown>;
+export interface OptChatOptions {
+    memory: Memory;
+    /** The conversation OptChat remembers; Pi Durable's root by default. Other conversations that select the extension are left alone. */
+    conversation?: ConversationId;
+    /** The memory part of the system prompt: VIEW_DOC (plus CONTINUITY and SEARCH_DOC as set) by default. */
+    prompt?: string;
+    /** Offers the `search` tool. Off by default, as in Pi. */
+    search?: boolean;
+    /** The previous exchange is sent in full after the view when it is at most this many bytes; 0 never sends it. */
+    previousExchangeBytes?: number;
+    /** When a run's messages since the last refresh pass this share of the model's window, they move into memory and the run goes
+     * on with a fresh view, as Pi's Turn refresh threshold (#146). 0.3 by default; 0 is off. */
+    refreshAt?: number;
+}
+/** OptChat's memory for one Pi Durable conversation. Install `extension` in the registry Harness.open gets, then `attach` the opened
+ * Harness. Each request is built as OptChat builds it in Pi: the view, the previous exchange and the current context, so the model
+ * never sees Pi's older transcript. When the conversation goes idle, OptChat resets Pi's context and a background task logs what the
+ * reset ended into memory and builds its summaries; Pi Durable runs that task, and wakes the Durable Object for it after an eviction.
+ * Turn Pi's own compaction off (`settings.compaction.enabled: false`); the extension also declines any that starts. */
+export declare function optchat({ memory, conversation: id, prompt, search, previousExchangeBytes, refreshAt }: OptChatOptions): {
+    extension: import("@earendil-works/pi-durable").Extension<import("@earendil-works/pi-durable").ToolRegistration>;
+    /** Starts following the conversation, and resets it now if a run ended before a restart. Returns a function that stops. */
+    attach(harness: Harness, ctx: Context): () => void;
+};
+/** The Harness and context an extension's `attach` was given; `get` throws before it is attached, or after `clear`. */
+export declare function attachment(name: string): {
+    set: (harness: Harness, context: Context) => void;
+    clear: () => void;
+    get: () => {
+        harness: Harness;
+        context: Context;
+    };
+};
+/** Pi Durable's `Models` with OptChat's cache marks on Anthropic requests that carry a view: in blocks of 4 lines, so a view that
+ * grows at its end is read from the cache (pi-ai's own marks miss it). A request that sets its own `onPayload` is left alone, as
+ * the compactor's are. A Proxy, since `createModels()` returns a class instance whose methods a spread would lose. */
+export declare function withCacheMarks<M extends Models>(models: M): M;
+export {};

package/dist/durable/optchat.js

@@ -0,0 +1,262 @@
+import { AssistantEntry, CompactionTask, defineExtension, defineTask, defineTool, GenerationTask, hook, InboxDoc, LiveDoc, ResetEntry, ROOT_CONVERSATION_ID, section, ToolResultEntry, UserEntry, } from '@earendil-works/pi-durable';
+import { allowSearch, boundedMessage, cachePayload, completedExchange, CONTINUITY, decode, isImage, isMime, logMessage, memoryTools, refreshBudget, refreshedRun, refreshPoint, SEARCH_DOC, searchTool, textContent, TURN_REFRESHED, VIEW_DOC, withView, } from '../core/index.js';
+/** The entries that are the chat: other kinds (system prompt changes, resets, compactions, other extensions' own) stay out of memory. */
+const CHAT = new Set([UserEntry.kind, AssistantEntry.kind, ToolResultEntry.kind]);
+const chat = (entry) => CHAT.has(entry.kind) ? entry.model ?? [] : [];
+/** What memory logs of an entry: its chat, or a reset's note (`Conversation.reset(text)`, a tool's handoff) marked as one. Pi sends
+ * the note in the context it starts, which is logged only once it ends, so the model never sees it twice. */
+const remembered = (entry) => !ResetEntry.is(entry) ? chat(entry)
+    : (entry.model ?? []).map(note => ({ role: 'user', content: `[Handoff note] ${textContent(note.content)}`, timestamp: note.timestamp }));
+/** Each message OptChat logs from a Pi entry carries the entry's id, so the log itself says how far it has read Pi's transcript. */
+const RECEIPT = 'pi:';
+/** The answer that ends a run, whether it succeeded, failed or was aborted. */
+const endsRun = (m) => m.role === 'assistant' && m.stopReason !== 'toolUse';
+const encoder = new TextEncoder();
+/** The images memory names, as Pi keeps them: a user's and a tool's, but not zoom's, which are kept already. */
+const keptImages = (message) => message.role === 'user' || message.role === 'toolResult' && !('toolName' in message && message.toolName === 'zoom')
+    ? Array.isArray(message.content) ? message.content.filter(isImage) : [] : [];
+/** Each distinct image by its base64, named as Pi's OptChat names it: the first 16 hex digits of the SHA-256 of its base64. Web
+ * Crypto is asynchronous and core's ImageRef is not, so images are named before core reads the names. */
+async function imageNames(images) {
+    const distinct = new Map(images.map(image => [image.data, image]));
+    return new Map(await Promise.all([...distinct.values()].map(async (image) => {
+        const hash = new Uint8Array(await crypto.subtle.digest('SHA-256', encoder.encode(image.data)), 0, 8);
+        return [image.data, { image, name: Array.from(hash, byte => byte.toString(16).padStart(2, '0')).join('') }];
+    })));
+}
+/** One of core's memory tools as a Pi Durable tool, its arguments typed by its own schema. */
+const durableTool = (tool) => defineTool({
+    name: tool.name, description: tool.description, parameters: tool.parameters, replay: 'safe',
+    execute: async (args, api) => ({ output: (await tool.execute(api.callId, args)).content }),
+});
+/** OptChat's memory for one Pi Durable conversation. Install `extension` in the registry Harness.open gets, then `attach` the opened
+ * Harness. Each request is built as OptChat builds it in Pi: the view, the previous exchange and the current context, so the model
+ * never sees Pi's older transcript. When the conversation goes idle, OptChat resets Pi's context and a background task logs what the
+ * reset ended into memory and builds its summaries; Pi Durable runs that task, and wakes the Durable Object for it after an eviction.
+ * Turn Pi's own compaction off (`settings.compaction.enabled: false`); the extension also declines any that starts. */
+export function optchat({ memory, conversation: id = ROOT_CONVERSATION_ID, prompt, search = false, previousExchangeBytes = 16_000, refreshAt = 0.3 }) {
+    const attached = attachment('OptChat'), opened = attached.get;
+    /** The Pi entry logging resumes after: messages before the context's head are logged, the rest are sent as they are. On open it is
+     * the one before the newest entry in memory, which is read again: a restart may have cut it off between its records (an answer
+     * with tool calls makes several), so the first `saved` records it makes, which memory has, are skipped. The newest is the highest
+     * id, not the last in the log: a rebuild orders turns by their dates, which a clock can put out of order. */
+    let logged = 0, saved = 0;
+    const newest = memory.root.reduce((max, e) => e.receipt?.startsWith(RECEIPT) ? Math.max(max, Number(e.receipt.slice(RECEIPT.length))) : max, 0);
+    if (newest) {
+        logged = newest - 1;
+        saved = memory.root.filter(e => e.receipt === `${RECEIPT}${newest}`).length;
+    }
+    const resumed = new Proxy(memory, {
+        get: (target, key) => key !== 'append' ? Reflect.get(target, key) : (...args) => saved > 0 ? void saved-- : target.append(...args),
+    });
+    let logging = Promise.resolve();
+    /** What a context's requests share, fixed when its first one is built so they read the same cached prefix. */
+    let turn;
+    const handle = async (ctx) => {
+        const conversation = await opened().harness.conversation(id, ctx);
+        if (!conversation)
+            throw new Error(`No conversation ${id}.`);
+        return conversation;
+    };
+    /** Logs Pi's entries before `head` that memory doesn't have yet, one caller at a time. A call that fails (aborted, say) leaves
+     * the next one to carry on from the last entry it logged. */
+    const logUpTo = (conversation, head, ctx) => {
+        const run = logging.then(async () => {
+            let cursor;
+            do {
+                if (logged + 1 > head - 1)
+                    return;
+                const page = await conversation.entries({ order: 'ascending', minEntryId: logged + 1, maxEntryId: head - 1 }, 256, cursor, ctx);
+                for (const entry of page.items) {
+                    const messages = remembered(entry), names = await imageNames(messages.flatMap(keptImages));
+                    // Kept before the message is logged, so the image its text names is there for zoom; one that can't be kept is only named.
+                    // An image sent again, or read again after a restart, is written again under its name.
+                    for (const { image, name } of names.values())
+                        if (isMime(image.mimeType)) {
+                            try {
+                                await memory.store.putImage(name, image.mimeType, decode(image.data));
+                            }
+                            catch (error) {
+                                console.error(`OptChat could not keep an image: ${error instanceof Error ? error.message : String(error)}`);
+                            }
+                        }
+                    // Once a save failed (also one queued before, failing during the awaits above), memory refuses appends: requests keep the
+                    // view it has, and a restart logs the rest from Pi's transcript.
+                    if (memory.saveError)
+                        return;
+                    for (const message of messages)
+                        logMessage(resumed, message, { receipt: `${RECEIPT}${entry.id}`, imageRef: image => `[image ${names.get(image.data)?.name}]` });
+                    logged = entry.id;
+                }
+                cursor = page.next;
+            } while (cursor);
+        });
+        logging = run.catch(() => { });
+        return run;
+    };
+    /** The last run before `head`, from Pi's transcript, if it was answered and is short enough to send whole. It is read from the
+     * entries, not the context's messages, which leave failed and aborted answers out and so would join a run to the one before.
+     * A text-only answer ends a run here even when steering followed it in the same Pi run. */
+    const previousBefore = async (conversation, head, ctx) => {
+        if (!previousExchangeBytes)
+            return [];
+        const [last] = (await conversation.entries({ order: 'descending', maxEntryId: head - 1 }, 1, undefined, ctx)).items;
+        if (!last)
+            return [];
+        const messages = (await conversation.context(ctx, { at: last.id })).entries.flatMap(chat);
+        const start = messages.slice(0, messages.findLastIndex(m => m.role === 'user')).findLastIndex(endsRun) + 1;
+        const run = messages.slice(start), names = await imageNames(run.filter(m => m.role === 'user').flatMap(keptImages));
+        const exchange = completedExchange(run, image => `[image ${names.get(image.data)?.name}]`);
+        const bytes = exchange.reduce((sum, m) => sum + encoder.encode(textContent(m.content)).length, 0);
+        return bytes <= previousExchangeBytes ? exchange : [];
+    };
+    const beforeRequest = async ({ messages }, api, ctx) => {
+        if (api.conversationId !== id)
+            return undefined;
+        const conversation = await handle(ctx);
+        const { head, entries } = await conversation.context(ctx);
+        if (!turn || turn.head !== head?.id) {
+            if (head)
+                await logUpTo(conversation, head.id, ctx);
+            await memory.settle(ctx.abortSignal);
+            turn = { head: head?.id, view: memory.render(), previous: head ? await previousBefore(conversation, head.id, ctx) : [] };
+        }
+        const at = messages.findIndex(m => m.role !== 'system');
+        if (at < 0)
+            return undefined;
+        // A tool result over 30K characters is sent as its head and tail, as in Pi.
+        const run = messages.slice(at).map(boundedMessage), shared = turn;
+        // `run` is the whole context, which can hold more than one run: inputs queued with no idle reset between them, or a reset's note
+        // first. The run being answered starts at its task, the last of the user messages after the newest finished answer; a refresh
+        // moves what comes before it into memory with the steps it cuts, and a steer before the cut too, as in Pi.
+        let task = run.findLastIndex(endsRun) + 1;
+        while (run[task + 1]?.role === 'user')
+            task++;
+        const own = run.slice(task);
+        /** The run's answers and their entries. Pi Durable's messages are copies of its entries', so an answer is found by its first
+         * tool call's id, or its timestamp without one. */
+        const answer = (m) => m.role === 'assistant' ? m.content.find(c => c.type === 'toolCall')?.id ?? m.timestamp : undefined;
+        const steps = entries.flatMap(entry => {
+            const sent = AssistantEntry.is(entry) && entry.model?.[0];
+            const i = sent ? own.findIndex(m => answer(m) === answer(sent)) : -1;
+            return i > 0 ? [{ entry, i }] : [];
+        });
+        /** Logs Pi's entries before `end`, rebuilding the view if that logged anything. False once a save failed: memory then lacks
+         * part of the run, so it is sent whole. */
+        const logThrough = async (end) => {
+            const count = memory.root.length;
+            await logUpTo(conversation, end, ctx);
+            if (memory.saveError)
+                return false;
+            if (memory.root.length !== count) {
+                await memory.settle(ctx.abortSignal);
+                shared.view = memory.render();
+            }
+            return true;
+        };
+        // Once a refresh has logged part of this context, an earlier run in it that has ended goes into memory whole, as the reset it
+        // missed would have done: a run queued behind a long one doesn't send it again.
+        const ended = task > 0 && logged > (head?.id ?? 0) && run[task - 1].role === 'assistant'
+            ? entries.find(entry => AssistantEntry.is(entry) && entry.model?.[0] && answer(entry.model[0]) === answer(run[task - 1])) : undefined;
+        const whole = ended && await logThrough(ended.id + 1) ? own : run;
+        // A refresh logs the run up to the answer it cuts at, so once any of its answers is in the log, the run is sent from the first
+        // answer after it, after a restart too; a restart in the middle of that logging leaves the rest of it to do.
+        let keep = 0;
+        const kept = steps.some(s => s.entry.id <= logged) ? steps.find(s => s.entry.id > logged) : undefined;
+        if (kept && await logThrough(kept.entry.id))
+            keep = kept.i;
+        const { model } = await conversation.agent(ctx);
+        const refresh = !memory.saveError && refreshPoint(own, keep, refreshBudget(model && api.models.getModel(model.provider, model.modelId)?.contextWindow, refreshAt));
+        const cut = refresh && steps.find(s => s.i === refresh.cut);
+        if (cut && await logThrough(cut.entry.id))
+            keep = cut.i;
+        const sent = keep ? refreshedRun(own, keep, TURN_REFRESHED) : whole;
+        return { messages: withView([...messages.slice(0, at), ...turn.previous, ...sent], turn.view) };
+    };
+    const Remember = defineTask({
+        name: 'optchat.remember', version: 1,
+        initial: () => ({ phase: 'remember' }),
+        phases: {
+            // Logs what the newest reset ended and waits until the next turn's view is built, or every summary owed has failed. A phase
+            // cut off by an eviction runs again from the top: logging skips what is in memory, and memory rebuilds what it owes on open.
+            remember: async (_task, runtime, ctx) => {
+                const conversation = await handle(ctx), { head } = await conversation.context(ctx);
+                if (head)
+                    await logUpTo(conversation, head.id, ctx);
+                await memory.settle(runtime.signal);
+                await runtime.commit(() => ({ status: 'terminal', outcome: { status: 'completed', result: null } }), ctx);
+            },
+        },
+        abort: (_task, runtime, ctx) => runtime.commit(() => ({ status: 'terminal', outcome: { status: 'aborted' } }), ctx),
+    });
+    /** Once the conversation is idle with a chat in its context, resets the context and starts remembering it, in one commit. */
+    const resetIfIdle = async () => {
+        const { harness, context } = opened();
+        const busy = async () => !!(await harness.snapshot(LiveDoc, id, context))?.run || !!(await harness.snapshot(InboxDoc, id, context))?.items.length;
+        if (await busy() || !(await (await handle(context)).context(context)).entries.some(e => chat(e).length))
+            return;
+        await harness.commit(async (tx) => {
+            // Checked again where it is atomic: an input that came in meanwhile keeps its context.
+            if ((await tx.doc(LiveDoc, id)).run || (await tx.doc(InboxDoc, id)).items.length)
+                return;
+            await tx.appendEntry(id, { kind: ResetEntry.kind, head: 'self' });
+            await tx.createTask(Remember, {}, { ownership: { kind: 'conversation' }, conversationId: id, background: true });
+        }, context);
+    };
+    /** Checks after commits, one check at a time; commits during a check ask for one more, however many there were. */
+    let checking = false, again = false;
+    const schedule = async () => {
+        again = true;
+        if (checking)
+            return;
+        checking = true;
+        while (again) {
+            again = false;
+            await resetIfIdle().catch(error => console.error(`OptChat could not reset the context: ${error instanceof Error ? error.message : String(error)}`));
+        }
+        checking = false;
+    };
+    const [zoom, date] = memoryTools(() => memory);
+    const tools = [durableTool(zoom), durableTool(date), ...search ? [durableTool(searchTool(() => memory))] : []];
+    const text = prompt ?? allowSearch(`${VIEW_DOC}${previousExchangeBytes ? CONTINUITY : ''}${search ? SEARCH_DOC : ''}`, search);
+    return {
+        extension: defineExtension({
+            name: 'optchat',
+            tools,
+            sections: [section('optchat', () => text, { tag: false })],
+            hooks: [hook(GenerationTask, { beforeRequest }), hook(CompactionTask, { beforeCompact: (_compaction, api) => api.conversationId === id ? { decline: true } : undefined })],
+            tasks: [Remember],
+        }),
+        /** Starts following the conversation, and resets it now if a run ended before a restart. Returns a function that stops. */
+        attach(harness, ctx) {
+            attached.set(harness, ctx);
+            const stop = harness.subscribeCommits(() => void schedule());
+            void schedule();
+            return stop;
+        },
+    };
+}
+/** The Harness and context an extension's `attach` was given; `get` throws before it is attached, or after `clear`. */
+export function attachment(name) {
+    let at;
+    return {
+        set: (harness, context) => { at = { harness, context }; },
+        clear: () => { at = undefined; },
+        get: () => { if (!at)
+            throw new Error(`${name} is not attached to a Harness yet.`); return at; },
+    };
+}
+/** Pi Durable's `Models` with OptChat's cache marks on Anthropic requests that carry a view: in blocks of 4 lines, so a view that
+ * grows at its end is read from the cache (pi-ai's own marks miss it). A request that sets its own `onPayload` is left alone, as
+ * the compactor's are. A Proxy, since `createModels()` returns a class instance whose methods a spread would lose. */
+export function withCacheMarks(models) {
+    return new Proxy(models, {
+        get(target, key) {
+            const value = Reflect.get(target, key, target);
+            if (key !== 'streamSimple')
+                return typeof value === 'function' ? value.bind(target) : value;
+            const stream = (model, request, options) => target.streamSimple(model, request, options?.onPayload || model.api !== 'anthropic-messages' ? options : { ...options, onPayload: payload => cachePayload(payload) });
+            return stream;
+        },
+    });
+}

package/dist/durable/store.d.ts

@@ -0,0 +1,65 @@
+import type { SqliteDatabase, SqliteValue } from '@earendil-works/pi-durable/storage/sqlite';
+import { type Entry, type ImageStore, type ImportMode, type Mime, type Part, type Saved, type Store, type Summary } from '../core/index.ts';
+export interface SqliteStoreOptions {
+    /** Where images are kept instead of `optchat_images`, such as an R2 bucket that keeps large binary data out of the database
+     * (its row size limit and storage cost). */
+    images?: ImageStore;
+    /** The generation to open, as `optchatImport` does for the one it builds. Default: the live one, whose load also deletes the
+     * rows of generations that are neither live nor being imported. */
+    generation?: number;
+}
+/** A synchronous query on the same database, for the texts memory reads while it builds a view, zooms or searches. In a Durable
+ * Object: `(sql, ...params) => ctx.storage.sql.exec(sql, ...params)`; on Node, node:sqlite's `(sql, ...params) => db.prepare(sql).iterate(...params)`. */
+export type Read = (sql: string, ...params: SqliteValue[]) => Iterable<Record<string, unknown>>;
+/** OptChat's memory in any Chord `SqliteDatabase`, such as Node's (`NodeSqliteDatabase`) or a Durable Object's. Give it the
+ * database Pi Durable's storage uses, so both share one queue: in a Durable Object, the `DurableObjectSqliteDatabase` over
+ * `ctx.storage` (direct `ctx.storage.sql` writes could be rolled back with a Pi transaction). `read` reads texts from the same
+ * database synchronously; it only reads rows whose writes have finished, so it needs no queue. Its tables are `optchat_*`, beside
+ * Pi's `pi_*`. Memory loads only metadata and node sizes; texts stay here. Messages are split so no row passes a Durable Object's
+ * 2 MB limit; images go to `images` when given, otherwise to `optchat_images`, one row each. */
+export declare class SqliteStore implements Store {
+    #private;
+    private readonly db;
+    private readonly read;
+    private readonly options;
+    constructor(db: SqliteDatabase, read: Read, options?: SqliteStoreOptions);
+    load(): Promise<Saved>;
+    text(i: number): string;
+    summary({ l, i }: Part): string;
+    /** The primary key refuses a second message at an index, so a store that was not the last to append writes nothing. */
+    append(entry: Entry): Promise<void>;
+    appendNode(node: Summary): Promise<void>;
+    saveView(view: string): Promise<void>;
+    putImage(name: string, mimeType: Mime, data: Uint8Array): Promise<void>;
+    image(name: string): Promise<{
+        mimeType: Mime;
+        data: Uint8Array;
+    } | undefined>;
+}
+/** A pending import: the generation it builds, and its plan's mode and length. */
+export interface ImportJob {
+    generation: number;
+    mode: ImportMode;
+    total: number;
+}
+/** The rows `optchatImport` keeps: which generation is live, the pending import and its plan. */
+export declare function importTables(db: SqliteDatabase, read: Read): {
+    state: () => Promise<{
+        live: number;
+        job: ImportJob | undefined;
+    }>;
+    /** Saves the plan, `entries` in order, made from generation `from`, and makes it the pending import of a new generation. A
+     * generation is never handed out twice, so a late call about a discarded one can't touch the next. Append's new generation starts with the live one's first `kept` messages, the nodes
+     * over them, and its view. Refused unless `from` is still live: an import went live since. */
+    stage: (from: number, mode: ImportMode, entries: Iterable<Entry>, kept: number) => Promise<{
+        generation: number;
+        mode: ImportMode;
+        total: number;
+    }>;
+    /** Planned message `i`, as saved; validated where it is used. */
+    planned(i: number): unknown;
+    /** Makes `generation` live and drops its plan, in one transaction; refused if its import was discarded meanwhile. */
+    activate: (generation: number) => Promise<void>;
+    /** Drops the pending import if it is still `generation`'s; its rows go when the live store next loads. */
+    discard: (generation: number) => Promise<void>;
+};