pi-optchat 0.10.1 → 0.11.0

package/src/core/compactor.ts

@@ -0,0 +1,119 @@
+import type { Api, AssistantMessage, Message, Model, Models, SimpleStreamOptions } from '@earendil-works/pi-ai';
+import { COMPACT, compaction, IMPORT_GUIDANCE, tooLong } from './prompts.ts';
+import { bytes, cut, NODE, Refused, type Compressor } from './memory.ts';
+import { cachePayload, splitView } from './cache.ts';
+
+/** 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<string, number | Promise<void>>();
+  return async (prefix: string, signal: AbortSignal) => {
+    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<void>(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<void>(resolve => { release = resolve; });
+    if (pending) warm.set(prefix, pending);
+    return (ok: boolean) => {
+      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: number, signal?: AbortSignal) => new Promise<void>((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 });
+});
+/** 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 async function retryTransient(ask: () => Promise<AssistantMessage>, onReply: (reply: AssistantMessage) => void, retryable: Retryable,
+  delays: readonly number[] = [1000, 2000], signal?: AbortSignal) {
+  for (let retry = 0; ; retry++) {
+    const reply = await ask();
+    onReply(reply);
+    if (retry >= delays.length || !retryable(reply)) return reply;
+    await sleep(delays[retry], signal);
+  }
+}
+
+/** 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 function createCompressor({ model: resolve, retryable, onUsage = () => {}, accepted = () => ACCEPTED_BYTES, retryDelays,
+  system = COMPACT }: CompressorOptions): Compressor {
+  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: Message[] = [{ 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: string[] = [];
+    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/src/core/images.ts

@@ -0,0 +1,24 @@
+import type { ImageContent } from '@earendil-works/pi-ai';
+import type { Store } from './store.ts';
+
+/** 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: unknown): part is ImageContent => 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: Uint8Array) => {
+  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: string) => 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: Store, text: string): Promise<ImageContent[]> {
+  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' as const, data: base64(kept.data), mimeType: kept.mimeType }] : []);
+}

package/src/core/import.ts

@@ -0,0 +1,84 @@
+import { bytes, isEntry, 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 function deduplicate<E extends Meta>(existing: readonly E[], incoming: readonly ImportedEntry[],
+  copyOf: (entry: E | ImportedEntry) => string | undefined = () => undefined) {
+  const receipts = new Set(existing.map(e => e.receipt).filter(Boolean));
+  const copies = new Set(existing.map(copyOf).filter(Boolean));
+  const added: ImportedEntry[] = []; 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<E extends Meta>(entries: readonly E[]) {
+  const groups = new Map<string, { date: string; entries: E[] }>();
+  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: readonly Entry[], incoming: readonly ImportedEntry[], mode: ImportMode,
+  copyOf?: (entry: ImportedEntry) => string | undefined) {
+  const { added, skipped } = deduplicate(existing, incoming, copyOf);
+  if (!added.length) return undefined;
+  const all = mode === 'rebuild' ? chronological([...existing, ...added]) : [...existing, ...chronological(added)];
+  const entries: Entry[] = 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 }: { entry: (i: number) => unknown; total: number;
+  open: () => Promise<Memory>; activate: () => void | Promise<void> }, signal: AbortSignal) {
+  const planned = (i: number) => {
+    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/src/core/index.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';