pi-optchat 0.11.1 → 0.11.3

package/README.md

@@ -79,7 +79,7 @@ Details, errors and join rules: [docs/connected-windows.md](docs/connected-windo
 | Subagents | Anthropic Opus 5.5, high | `/optchat agents model` |
 | Compactor (summaries, imports, fallback handoffs) | Anthropic Sonnet 5.5, medium | `/optchat model` |
 
-All three are saved per profile. The main agent's model and thinking level are saved whenever you change them in Pi and picked again when the profile opens, unless the saved model is no longer available. This includes resumed sessions: the profile's pick replaces the one the session last used. On Pi's command line, `--model` (or `--provider`) keeps that model, `--thinking` that level, and `--models` keeps a saved model only if it is in that list. Subagent and compactor settings do not follow the main model. If you use other providers, change them before chatting. Authentication uses Pi's existing provider login.
+All three are saved per profile. The main agent's model and thinking level are saved when you first open the profile and whenever you change them in Pi, then picked again when the profile opens, unless the saved model is no longer available. This includes resumed sessions: the profile's pick replaces the one the session last used. On Pi's command line, `--model` (or `--provider`) keeps that model, `--thinking` that level, and `--models` keeps a saved model only if it is in that list. Subagent and compactor settings do not follow the main model. If you use other providers, change them before chatting. Authentication uses Pi's existing provider login.
 
 Compression and subagents make extra model requests with your provider credentials.
 

package/dist/core/cache.d.ts

@@ -0,0 +1,14 @@
+export declare function record(value: unknown): value is Record<string, unknown>;
+/** The view in blocks of 4 lines counted from its start (recipe §3.3), byte for byte. While the view only grows at its end,
+ * every block but the last is the same in the next call. */
+export declare function splitView(text: string): string[];
+/** The status line's own message, in Pi's context and in Anthropic's payload alike. */
+export declare const isAtWork: (message: unknown) => boolean;
+/** Anthropic: marks on the view (see MARKS) plus a mark at the end of the request, so the next call finds the last one's entry
+ * and pays only for the lines after it. The end mark sits on the last block itself rather than as top-level automatic caching:
+ * a proxy or setting that gives block marks a 1h TTL makes Anthropic refuse a top-level mark, whose TTL defaults to 5m, on the
+ * same block ("Top-level cache_control has ttl='5m' but the target block already has cache_control with ttl='1h'").
+ * `end: false` leaves the end unmarked: a compaction's task is never sent again, so marking it would only write it at 1.25× (#197). */
+export declare function cachePayload(payload: unknown, { end: markEnd }?: {
+    end?: boolean | undefined;
+}): unknown;

package/dist/core/cache.js

@@ -0,0 +1,96 @@
+import { isView } from './memory.js';
+import { AT_WORK } from './prompts.js';
+export function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** The view in blocks of 4 lines counted from its start (recipe §3.3), byte for byte. While the view only grows at its end,
+ * every block but the last is the same in the next call. */
+export function splitView(text) {
+    const pieces = [];
+    let offset = 0;
+    for (let count = 0, at = text.indexOf('\n'); at >= 0; at = text.indexOf('\n', at + 1))
+        if (++count % 4 === 0) {
+            pieces.push(text.slice(offset, at + 1));
+            offset = at + 1;
+        }
+    pieces.push(text.slice(offset));
+    return pieces;
+}
+/** How many blocks before the view's last whole one each mark sits. Anthropic looks back only 20 blocks from a mark for an
+ * earlier entry, so the marks 20 and 40 blocks back still find the last call's entry after a turn of tool calls adds up to
+ * 60 blocks (240 lines). With the end of the request, that is Anthropic's limit of 4 marks. */
+const MARKS = [0, 20, 40];
+/** The status line's own message, in Pi's context and in Anthropic's payload alike. */
+export const isAtWork = (message) => record(message) && message.role === 'user' && Array.isArray(message.content) && message.content.length === 1
+    && record(message.content[0]) && typeof message.content[0].text === 'string' && message.content[0].text.startsWith(AT_WORK);
+function lastBlock(message) {
+    if (typeof message.content === 'string')
+        message.content = [{ type: 'text', text: message.content }];
+    const block = Array.isArray(message.content) ? message.content.at(-1) : undefined;
+    return record(block) ? block : undefined;
+}
+/** Anthropic: marks on the view (see MARKS) plus a mark at the end of the request, so the next call finds the last one's entry
+ * and pays only for the lines after it. The end mark sits on the last block itself rather than as top-level automatic caching:
+ * a proxy or setting that gives block marks a 1h TTL makes Anthropic refuse a top-level mark, whose TTL defaults to 5m, on the
+ * same block ("Top-level cache_control has ttl='5m' but the target block already has cache_control with ttl='1h'").
+ * `end: false` leaves the end unmarked: a compaction's task is never sent again, so marking it would only write it at 1.25× (#197). */
+export function cachePayload(payload, { end: markEnd = true } = {}) {
+    if (!record(payload) || !Array.isArray(payload.messages))
+        return payload;
+    const messages = payload.messages;
+    const view = new Set();
+    for (const message of messages) {
+        if (!record(message) || message.role !== 'user' || !Array.isArray(message.content))
+            continue;
+        const at = message.content.findIndex((block) => record(block) && block.type === 'text' && typeof block.text === 'string' && isView(block.text));
+        if (at < 0)
+            continue;
+        // A subagent's task follows the view in the same text. Lines never hold a newline, so the first one before </chat> ends the view;
+        // the task goes in its own block, so the view's marks fall on lines its siblings share and they can read one another's entry.
+        const text = message.content[at].text, close = text.indexOf('\n</chat>'), end = close < 0 ? text.length : close + '\n</chat>'.length;
+        const pieces = splitView(text.slice(0, end)), marked = new Set(MARKS.map(back => pieces.length - 2 - back));
+        const blocks = pieces.map((text, j) => ({ type: 'text', text, ...(marked.has(j) ? { cache_control: { type: 'ephemeral' } } : {}) }));
+        message.content.splice(at, 1, ...blocks, ...(end < text.length ? [{ type: 'text', text: text.slice(end) }] : []));
+        for (const block of blocks)
+            view.add(block);
+        break;
+    }
+    if (!view.size)
+        return payload;
+    // These marks only: Pi's own system, tool and recent-message marks are dropped.
+    for (const section of [payload.system, payload.tools]) {
+        if (Array.isArray(section))
+            for (const item of section)
+                if (record(item))
+                    delete item.cache_control;
+    }
+    for (const message of messages) {
+        if (!record(message))
+            continue;
+        delete message.cache_control;
+        if (Array.isArray(message.content))
+            for (const item of message.content)
+                if (record(item) && !view.has(item))
+                    delete item.cache_control;
+    }
+    // The status line changes between calls, so the turn's mark goes on the block before it rather than at the end of the request.
+    // Pi may end the request with an empty system message carrying settings (effort); it holds nothing to cache.
+    const [before, last] = messages.filter(message => !record(message) || message.role !== 'system').slice(-2);
+    const turn = isAtWork(last) && record(before) && before.role === 'user' ? lastBlock(before) : undefined;
+    const end = markEnd ? turn ?? endBlock(messages) : undefined;
+    if (end)
+        end.cache_control = { type: 'ephemeral' };
+    return payload;
+}
+/** The last block of the last non-system message that can carry a mark (thinking blocks can't). */
+function endBlock(messages) {
+    const message = messages.filter(m => !record(m) || m.role !== 'system').at(-1);
+    if (!record(message))
+        return undefined;
+    if (typeof message.content === 'string')
+        return lastBlock(message);
+    if (!Array.isArray(message.content))
+        return undefined;
+    const block = message.content.findLast((b) => record(b) && b.type !== 'thinking' && b.type !== 'redacted_thinking');
+    return record(block) ? block : undefined;
+}

package/dist/core/compactor.d.ts

@@ -0,0 +1,28 @@
+import type { Api, AssistantMessage, Model, Models, SimpleStreamOptions } from '@earendil-works/pi-ai';
+import { type Compressor } from './memory.ts';
+/** The longest line kept without asking again, unless the host sets its own (Pi's "Summary size tolerance"). */
+export declare const ACCEPTED_BYTES: number;
+/** Whether a failed reply is worth asking again: pi-ai's `isRetryableAssistantError`, passed in by the host. */
+export type Retryable = (reply: AssistantMessage) => boolean;
+/** Pi's agent loop retries a dropped connection itself; streamSimple doesn't, so a transient error is asked again before it surfaces. */
+export declare function retryTransient(ask: () => Promise<AssistantMessage>, onReply: (reply: AssistantMessage) => void, retryable: Retryable, delays?: readonly number[], signal?: AbortSignal): Promise<AssistantMessage>;
+/** The compactor's model for one call, as the host resolves it: `stream` is pi-ai's `Models.streamSimple`, or Pi's
+ * `ModelRegistry.streamSimple`, which has its shape. */
+export interface CompactorModel {
+    model: Model<Api>;
+    reasoning?: SimpleStreamOptions['reasoning'];
+    stream: Models['streamSimple'];
+}
+export interface CompressorOptions {
+    /** Resolves the model for each call, so a settings change applies to the next summary. Throws if it is unavailable. */
+    model: () => CompactorModel;
+    retryable: Retryable;
+    onUsage?: (reply: AssistantMessage) => void;
+    /** The longest line kept without a retry; ACCEPTED_BYTES unless the host has a setting for it. */
+    accepted?: () => number;
+    retryDelays?: readonly number[];
+    /** The compactor's system prompt: COMPACT, unless the host's chat isn't one user and OptChat. */
+    system?: string;
+}
+/** Builds summary lines with the model `model` resolves. The model is asked for 512 bytes. */
+export declare function createCompressor({ model: resolve, retryable, onUsage, accepted, retryDelays, system }: CompressorOptions): Compressor;

package/dist/core/compactor.js

@@ -0,0 +1,123 @@
+import { COMPACT, compaction, IMPORT_GUIDANCE, tooLong } from './prompts.js';
+import { bytes, cut, NODE, Refused } from './memory.js';
+import { cachePayload, splitView } from './cache.js';
+/** The longest line kept without asking again, unless the host sets its own (Pi's "Summary size tolerance"). */
+export const ACCEPTED_BYTES = NODE * 1.25;
+const WARM_MS = 4 * 60_000; // Anthropic's short cache lives 5 minutes from its last use.
+/** Parallel calls can't read a cache entry that isn't written yet, so one call primes a cold prefix and the rest wait until it answers.
+ * Parallel compactions end their views at different messages, so a call also waits for a primer of a shorter prefix of its own view. */
+function primeFirst() {
+    const warm = new Map();
+    return async (prefix, signal) => {
+        const priming = () => { for (const [k, state] of warm)
+            if (typeof state !== 'number' && prefix.startsWith(k))
+                return state; };
+        for (let state = warm.get(prefix) ?? priming(); state !== undefined; state = warm.get(prefix) ?? priming()) {
+            if (typeof state === 'number') {
+                if (Date.now() - state < WARM_MS)
+                    break;
+                warm.delete(prefix);
+                continue;
+            }
+            // A cancelled waiter leaves at once instead of waiting for someone else's primer.
+            signal.throwIfAborted();
+            let wake = () => { };
+            const aborted = new Promise(resolve => { wake = resolve; });
+            signal.addEventListener('abort', wake, { once: true });
+            await Promise.race([state, aborted]);
+            signal.removeEventListener('abort', wake);
+            signal.throwIfAborted();
+        }
+        let release = () => { };
+        const pending = warm.has(prefix) ? undefined : new Promise(resolve => { release = resolve; });
+        if (pending)
+            warm.set(prefix, pending);
+        return (ok) => {
+            if (ok) {
+                for (const [k, at] of warm)
+                    if (typeof at === 'number' && Date.now() - at >= WARM_MS)
+                        warm.delete(k);
+                warm.set(prefix, Date.now());
+            }
+            else if (warm.get(prefix) === pending)
+                warm.delete(prefix);
+            release();
+        };
+    };
+}
+const sleep = (ms, signal) => new Promise((resolve, reject) => {
+    signal?.throwIfAborted();
+    const abort = () => { clearTimeout(timer); reject(signal?.reason); };
+    const timer = setTimeout(() => { signal?.removeEventListener('abort', abort); resolve(); }, ms);
+    signal?.addEventListener('abort', abort, { once: true });
+});
+/** Pi's agent loop retries a dropped connection itself; streamSimple doesn't, so a transient error is asked again before it surfaces. */
+export async function retryTransient(ask, onReply, retryable, delays = [1000, 2000], signal) {
+    for (let retry = 0;; retry++) {
+        const reply = await ask();
+        onReply(reply);
+        if (retry >= delays.length || !retryable(reply))
+            return reply;
+        await sleep(delays[retry], signal);
+    }
+}
+/** Builds summary lines with the model `model` resolves. The model is asked for 512 bytes. */
+export function createCompressor({ model: resolve, retryable, onUsage = () => { }, accepted = () => ACCEPTED_BYTES, retryDelays, system = COMPACT }) {
+    const gate = primeFirst();
+    return async (input, signal) => {
+        const { model, reasoning: thinking, stream: streamSimple } = resolve();
+        const step = `${input.historical ? IMPORT_GUIDANCE + '\n\n' : ''}${compaction(input)}`;
+        // OpenAI joins text blocks with nothing between them, so the task starts its own paragraph after the view.
+        const messages = [{ role: 'user', content: [{ type: 'text', text: input.context }, { type: 'text', text: `\n\n${step}` }], timestamp: Date.now() }];
+        const view = splitView(input.context);
+        const prefix = model.api === 'anthropic-messages' && view.length > 1 ? `${model.provider}/${model.id}/${thinking ?? 'off'}\n${view.slice(0, -1).join('')}` : undefined;
+        const tries = [];
+        const ask = async () => {
+            const warmed = prefix ? await gate(prefix, signal) : () => { };
+            try {
+                const stream = streamSimple(model, { systemPrompt: system, messages }, {
+                    // A shared session id is the OpenAI prompt-cache key; SSE because over a websocket Codex would chain unrelated parallel calls on one cached connection.
+                    sessionId: 'optchat-compactor', transport: 'sse',
+                    reasoning: thinking, signal, cacheRetention: 'short',
+                    onPayload: payload => model.api === 'anthropic-messages' ? cachePayload(payload, { end: false }) : payload,
+                });
+                // The cache entry is usable once the model starts answering.
+                for await (const event of stream)
+                    if (event.type !== 'start') {
+                        warmed(event.type !== 'error');
+                        break;
+                    }
+                return await stream.result();
+            }
+            finally {
+                warmed(false);
+            }
+        };
+        const answer = () => retryTransient(ask, onUsage, retryable, retryDelays, signal);
+        for (let attempt = 0; attempt < 5; attempt++) {
+            const reply = await answer();
+            // A stop reason means the model answered: a refusal or a content filter, which asking again repeats.
+            // A provider's own 'error' stop (Mistral) is a failure on its side, not an answer: a plain error, tried again later.
+            if (reply.stopReason === 'error' && reply.rawStopReason !== undefined && reply.rawStopReason !== 'error' && !retryable(reply))
+                throw new Refused(reply.errorMessage ?? `Compactor stopped: ${reply.rawStopReason}`);
+            if (reply.stopReason === 'error' || reply.stopReason === 'aborted')
+                throw new Error(reply.errorMessage ?? `Compactor ${reply.stopReason}`);
+            // A reply cut off at the token limit, or one that calls a tool, is no summary: ask again.
+            if (reply.stopReason === 'length' || reply.content.some(c => c.type === 'toolCall'))
+                continue;
+            // The compactions' view shows each line under its id+n| head, which a line can copy.
+            const line = reply.content.filter(c => c.type === 'text').map(c => c.text).join('').trim().replace(/^\d+\+\d+\|\s*/, '');
+            if (!line)
+                throw new Refused('Compactor returned no text.');
+            tries.push(line);
+            // A merge of two short lines can come back nearly as big as both, so a line must also shrink what it replaces.
+            if (bytes(line) <= accepted() && bytes(line) < bytes(input.source))
+                break;
+            messages.push(reply);
+            messages.push({ role: 'user', content: tooLong(bytes(line), cut(line)), timestamp: Date.now() });
+        }
+        if (!tries.length)
+            throw new Refused('Compactor returned no whole line in 5 tries.');
+        return tries.reduce((a, b) => bytes(a) <= bytes(b) ? a : b);
+    };
+}

package/dist/core/images.d.ts

@@ -0,0 +1,7 @@
+import type { ImageContent } from '@earendil-works/pi-ai';
+import type { Store } from './store.ts';
+export declare const isImage: (part: unknown) => part is ImageContent;
+/** An image's base64 as bytes. */
+export declare const decode: (data: string) => Uint8Array<ArrayBuffer>;
+/** The kept images a text refers to, in order, each once; ones never kept are skipped. */
+export declare function loadImages(store: Store, text: string): Promise<ImageContent[]>;

package/dist/core/images.js

@@ -0,0 +1,19 @@
+/** How a message's image reads in memory: `[image <16 hex digits>]`, named by the host (Pi: a hash of the image as sent). */
+const REF = /\[image ([0-9a-f]{16})\]/g;
+export const isImage = (part) => typeof part === 'object' && part !== null
+    && 'type' in part && part.type === 'image' && 'data' in part && typeof part.data === 'string' && 'mimeType' in part && typeof part.mimeType === 'string';
+/** Base64 in chunks: one String.fromCharCode call per image would pass the engine's argument limit. */
+const base64 = (data) => {
+    let binary = '';
+    for (let i = 0; i < data.length; i += 0x8000)
+        binary += String.fromCharCode(...data.subarray(i, i + 0x8000));
+    return btoa(binary);
+};
+/** An image's base64 as bytes. */
+export const decode = (data) => Uint8Array.from(atob(data), char => char.charCodeAt(0));
+/** The kept images a text refers to, in order, each once; ones never kept are skipped. */
+export async function loadImages(store, text) {
+    const names = [...new Set(Array.from(text.matchAll(REF), match => match[1]))];
+    return (await Promise.all(names.map(name => store.image(name))))
+        .flatMap(kept => kept ? [{ type: 'image', data: base64(kept.data), mimeType: kept.mimeType }] : []);
+}

package/dist/core/import.d.ts

@@ -0,0 +1,40 @@
+import { type Entry, type Memory } from './memory.ts';
+/** What planning reads of a message: no text, so a host can plan from metadata alone. */
+type Meta = Pick<Entry, 'kind' | 'date' | 'receipt' | 'origin'>;
+/** Append keeps the existing log and its summaries and adds the new messages after them; rebuild orders everything by date and
+ * summarizes it all again. Either way the host builds the result on a staging store and switches to it only once it is complete. */
+export type ImportMode = 'append' | 'rebuild';
+/** A message to import, before memory numbers it. Its `receipt` starts with `import:` and is stable per source message, so
+ * importing the same history again adds nothing. */
+export type ImportedEntry = Omit<Entry, 'i'>;
+/** Drops what memory already has: the same receipt, or the same `copyOf` key, the host's second identity for one message
+ * (Pi: a Claude message copied into a forked session). */
+export declare function deduplicate<E extends Meta>(existing: readonly E[], incoming: readonly ImportedEntry[], copyOf?: (entry: E | ImportedEntry) => string | undefined): {
+    added: ImportedEntry[];
+    skipped: number;
+};
+/** Imported conversations remain contiguous; existing native history is grouped by user turn. An imported message without an
+ * origin stands alone: in a native turn it would move that turn, and a host's cursor in the log with it. */
+export declare function chronological<E extends Meta>(entries: readonly E[]): E[];
+/** The whole log an import builds, or undefined when nothing is new. Its first `kept` entries are the existing log as it is (append),
+ * so the host seeds the staging store with them and the existing summaries and view; rebuild keeps none. */
+export declare function planImport(existing: readonly Entry[], incoming: readonly ImportedEntry[], mode: ImportMode, copyOf?: (entry: ImportedEntry) => string | undefined): {
+    mode: ImportMode;
+    entries: Entry[];
+    kept: number;
+    added: number;
+    skipped: number;
+    inputBytes: number;
+} | undefined;
+/** Builds the staging memory `open` gives from the plan, `entry(i)` for each of its `total` messages, and calls `activate` once its
+ * whole tree is built and it is closed. It continues from what the memory already logged, so a paused or crashed import resumes. A
+ * planned message that isn't a valid entry at its index, or a memory that isn't a start of the plan, stops it before the switch;
+ * `entry` is read as needed, so a host need not hold the plan in RAM.
+ * The live memory must take no messages from `planImport` until `activate`, or the switch drops them: queue them and log them after. */
+export declare function runImport({ entry, total, open, activate }: {
+    entry: (i: number) => unknown;
+    total: number;
+    open: () => Promise<Memory>;
+    activate: () => void | Promise<void>;
+}, signal: AbortSignal): Promise<void>;
+export {};

package/dist/core/import.js

@@ -0,0 +1,90 @@
+import { bytes, isEntry } from './memory.js';
+/** Drops what memory already has: the same receipt, or the same `copyOf` key, the host's second identity for one message
+ * (Pi: a Claude message copied into a forked session). */
+export function deduplicate(existing, incoming, copyOf = () => undefined) {
+    const receipts = new Set(existing.map(e => e.receipt).filter(Boolean));
+    const copies = new Set(existing.map(copyOf).filter(Boolean));
+    const added = [];
+    let skipped = 0;
+    for (const entry of incoming) {
+        if (!entry.receipt?.startsWith('import:'))
+            throw new Error('Imported entry has no stable source identity.');
+        const copy = copyOf(entry);
+        if (receipts.has(entry.receipt) || copy && copies.has(copy)) {
+            skipped++;
+            continue;
+        }
+        receipts.add(entry.receipt);
+        if (copy)
+            copies.add(copy);
+        added.push(entry);
+    }
+    return { added, skipped };
+}
+/** Imported conversations remain contiguous; existing native history is grouped by user turn. An imported message without an
+ * origin stands alone: in a native turn it would move that turn, and a host's cursor in the log with it. */
+export function chronological(entries) {
+    const groups = new Map();
+    let native = 0;
+    for (const entry of entries) {
+        const imported = entry.receipt?.startsWith('import:') ? entry.receipt : undefined;
+        if (!entry.origin && !imported && entry.kind === 'user')
+            native++;
+        const id = entry.origin ? JSON.stringify([entry.origin.source, entry.origin.conversation]) : imported ?? `native:${native}`;
+        const group = groups.get(id) ?? { date: entry.date, entries: [] };
+        group.date = group.date < entry.date ? group.date : entry.date;
+        group.entries.push(entry);
+        groups.set(id, group);
+    }
+    return [...groups.values()].sort((a, b) => a.date.localeCompare(b.date)).flatMap(g => g.entries);
+}
+/** The whole log an import builds, or undefined when nothing is new. Its first `kept` entries are the existing log as it is (append),
+ * so the host seeds the staging store with them and the existing summaries and view; rebuild keeps none. */
+export function planImport(existing, incoming, mode, copyOf) {
+    const { added, skipped } = deduplicate(existing, incoming, copyOf);
+    if (!added.length)
+        return undefined;
+    const all = mode === 'rebuild' ? chronological([...existing, ...added]) : [...existing, ...chronological(added)];
+    const entries = all.map((e, i) => ({ ...e, i }));
+    return { mode, entries, kept: mode === 'append' ? existing.length : 0, added: added.length, skipped,
+        inputBytes: (mode === 'rebuild' ? entries : added).reduce((n, e) => n + bytes(e.text), 0) };
+}
+/** Builds the staging memory `open` gives from the plan, `entry(i)` for each of its `total` messages, and calls `activate` once its
+ * whole tree is built and it is closed. It continues from what the memory already logged, so a paused or crashed import resumes. A
+ * planned message that isn't a valid entry at its index, or a memory that isn't a start of the plan, stops it before the switch;
+ * `entry` is read as needed, so a host need not hold the plan in RAM.
+ * The live memory must take no messages from `planImport` until `activate`, or the switch drops them: queue them and log them after. */
+export async function runImport({ entry, total, open, activate }, signal) {
+    const planned = (i) => {
+        const e = entry(i);
+        if (!isEntry(e) || e.i !== i)
+            throw new Error('Import staging data is invalid; original memory remains intact.');
+        return e;
+    };
+    if (!Number.isSafeInteger(total) || total < 0)
+        throw new Error('Import staging data is invalid; original memory remains intact.');
+    const memory = await open();
+    try {
+        if (memory.root.length > total || memory.root.some((_, i) => memory.text(i) !== planned(i).text))
+            throw new Error('Import staging data does not match its log; original memory remains intact.');
+        // Recipe §10: imported messages are compressed like any other. Each is logged once its node can start, as a burst of live
+        // messages is, so up to `jobs` summaries run at once. Unlike a turn, an import waits through failures (`lastError` says why).
+        for (let i = memory.root.length; i < total; i++) {
+            await memory.settle(signal, 'ahead');
+            const e = planned(i);
+            memory.append(e.kind, e.text, e.date, e.receipt, e.origin);
+        }
+        await memory.settle(signal, 'tree');
+        signal.throwIfAborted();
+        // Close all writers before the switch. The previous memory stays intact.
+        await memory.close();
+        // A store that writes behind reports a failed write only here: switching would drop the messages it lost.
+        if (memory.saveError !== undefined)
+            throw new Error(`Import could not be saved: ${memory.saveError}; original memory remains intact.`);
+        signal.throwIfAborted();
+        await activate();
+    }
+    finally {
+        await memory.close();
+    }
+}

package/dist/core/index.d.ts

@@ -0,0 +1,13 @@
+/** OptChat's memory for any host: the log, the summary tree and its views, zoom/date/search, the compactor, cache marks and
+ * memory's prompts. It imports nothing from Pi or Node at runtime: the host gives it a `Store` and the compactor's model.
+ * Only what a host needs is exported here; Pi's own code imports the modules directly. */
+export { isEntry, Memory, openMemory, Refused, VIEW, type Compression, type Compressor, type Entry, type Kind, type MemoryOptions, type Origin, type Part, type Summary } from './memory.ts';
+export { isMime, type ImageStore, type Lease, type Mime, type Saved, type Store } from './store.ts';
+export { ACCEPTED_BYTES, createCompressor, type CompactorModel, type CompressorOptions, type Retryable } from './compactor.ts';
+export { cachePayload } from './cache.ts';
+export { allowSearch, COMPACT, CONTINUITY, SEARCH_DOC, TURN_REFRESHED, VIEW_DOC } from './prompts.ts';
+export { boundedMessage, completedExchange, logMessage, refreshBudget, refreshedRun, refreshPoint, textContent, withView, type AnyMessage, type ImageRef } from './messages.ts';
+export { memoryTools, searchTool } from './tools.ts';
+export { decode, isImage, loadImages } from './images.ts';
+export type { ImageContent } from '@earendil-works/pi-ai';
+export { chronological, deduplicate, planImport, runImport, type ImportedEntry, type ImportMode } from './import.ts';

package/dist/core/index.js

@@ -0,0 +1,12 @@
+/** OptChat's memory for any host: the log, the summary tree and its views, zoom/date/search, the compactor, cache marks and
+ * memory's prompts. It imports nothing from Pi or Node at runtime: the host gives it a `Store` and the compactor's model.
+ * Only what a host needs is exported here; Pi's own code imports the modules directly. */
+export { isEntry, Memory, openMemory, Refused, VIEW } from './memory.js';
+export { isMime } from './store.js';
+export { ACCEPTED_BYTES, createCompressor } from './compactor.js';
+export { cachePayload } from './cache.js';
+export { allowSearch, COMPACT, CONTINUITY, SEARCH_DOC, TURN_REFRESHED, VIEW_DOC } from './prompts.js';
+export { boundedMessage, completedExchange, logMessage, refreshBudget, refreshedRun, refreshPoint, textContent, withView } from './messages.js';
+export { memoryTools, searchTool } from './tools.js';
+export { decode, isImage, loadImages } from './images.js';
+export { chronological, deduplicate, planImport, runImport } from './import.js';