@hachej/boring-agent 0.1.110 → 0.2.0

package/dist/json-schema-tool.d.ts

@@ -0,0 +1,25 @@
+import type { ToolRegistration } from '@earendil-works/pi-durable';
+import { Type } from '@earendil-works/pi-ai';
+import type { JsonValue } from '@earendil-works/chord';
+/** A JSON Schema for a tool's arguments: an object schema, as providers require. */
+export interface JsonObjectSchema {
+    readonly type: 'object';
+    readonly properties?: Readonly<Record<string, unknown>>;
+    readonly required?: readonly string[];
+    readonly [keyword: string]: unknown;
+}
+type JsonSchemaParameters<Args> = ReturnType<typeof Type.Unsafe<Args>>;
+export type JsonSchemaToolOptions<Args, TDetails extends JsonValue = JsonValue> = Omit<ToolRegistration<JsonSchemaParameters<Args>, TDetails>, 'parameters'> & {
+    readonly parameters: JsonObjectSchema | Readonly<Record<string, unknown>>;
+};
+/**
+ * A native tool registration from a raw JSON Schema (an MCP server's `inputSchema`, an agent-written `.agent/tools/*.json`): the schema
+ * becomes Pi's parameters through typebox's `Type.Unsafe`, so `execute` gets typed arguments without a cast. Validation is Pi's own: the
+ * Harness checks every call's arguments against `parameters` before `execute` runs (`validateToolArguments` of `@earendil-works/pi-ai`,
+ * which compiles plain JSON Schema with typebox) and answers a call that does not match with an `invalid_arguments` error result that
+ * names the failing fields. Nothing is validated twice here. Refuses, at registration, a schema that is not an object schema, and gives one
+ * without `properties` an empty one (some providers reject it otherwise).
+ */
+export declare function jsonSchemaTool<Args = Record<string, unknown>, TDetails extends JsonValue = JsonValue>(tool: JsonSchemaToolOptions<Args, TDetails>): ToolRegistration<JsonSchemaParameters<Args>, TDetails>;
+export {};
+//# sourceMappingURL=json-schema-tool.d.ts.map

package/dist/json-schema-tool.js

@@ -0,0 +1,19 @@
+import { defineTool } from '@earendil-works/pi-durable';
+import { Type } from '@earendil-works/pi-ai';
+/**
+ * A native tool registration from a raw JSON Schema (an MCP server's `inputSchema`, an agent-written `.agent/tools/*.json`): the schema
+ * becomes Pi's parameters through typebox's `Type.Unsafe`, so `execute` gets typed arguments without a cast. Validation is Pi's own: the
+ * Harness checks every call's arguments against `parameters` before `execute` runs (`validateToolArguments` of `@earendil-works/pi-ai`,
+ * which compiles plain JSON Schema with typebox) and answers a call that does not match with an `invalid_arguments` error result that
+ * names the failing fields. Nothing is validated twice here. Refuses, at registration, a schema that is not an object schema, and gives one
+ * without `properties` an empty one (some providers reject it otherwise).
+ */
+export function jsonSchemaTool(tool) {
+    const schema = tool.parameters;
+    if (schema === null || typeof schema !== 'object' || Array.isArray(schema) || schema['type'] !== 'object')
+        throw new TypeError(`${tool.name}: parameters must be a JSON Schema object with "type": "object"`);
+    const properties = schema['properties'];
+    if (properties !== undefined && (properties === null || typeof properties !== 'object' || Array.isArray(properties)))
+        throw new TypeError(`${tool.name}: parameters.properties must be an object`);
+    return defineTool({ ...tool, parameters: Type.Unsafe({ ...schema, properties: properties ?? {} }) });
+}

package/dist/memory/optchat-core.d.ts

@@ -0,0 +1,118 @@
+import type { Message } from '@earendil-works/pi-ai';
+export declare const DEFAULTS: {
+    /** Target size of one summary line, in UTF-8 bytes. */
+    readonly nodeBytes: 512;
+    /** Budget of the rendered view, in UTF-8 bytes. */
+    readonly viewBytes: 128000;
+    /** Summarizer calls running at once. */
+    readonly jobs: 8;
+    /** Attempts per node to get a line under `nodeBytes`. */
+    readonly tries: 5;
+    /** Longest leaf, in characters; longer tool output keeps its head and tail. */
+    readonly cap: 30000;
+    /** Wait before a failed node is tried again. */
+    readonly retryMs: 10000;
+    /** How long a request waits for the summaries it needs. */
+    readonly settleTimeoutMs: 60000;
+};
+/** What a view line shows for a message that has no summary yet. Only a fail-safe: requests wait for summaries. */
+export declare const PLACEHOLDER = "(not summarized yet: zoom it)";
+/** UTF-8 length without allocating. */
+export declare function byteLength(text: string): number;
+/** The longest prefix of `text` that fits in `max` bytes, never splitting a character. */
+export declare function cutBytes(text: string, max: number): string;
+/** A 53-bit string hash (cyrb53), base 36. Fingerprints only need to tell different content apart. */
+export declare function hashText(text: string): string;
+export type LeafKind = 'user' | 'talk' | 'tool' | 'echo';
+/** One message of the OptChat log. `line` is `kind: text`, the form every summary and zoom starts from. */
+export interface Leaf {
+    readonly kind: LeafKind;
+    readonly text: string;
+    readonly line: string;
+    readonly bytes: number;
+    readonly hash: string;
+    /** When the message was created, in ms since the epoch, if Pi recorded it. */
+    readonly at?: number;
+}
+/** Keep the head and tail of text longer than `cap` characters, and say how much was cut. */
+export declare function capText(text: string, cap: number): string;
+/**
+ * The OptChat log of a Pi model context. A user message is one `user` leaf; an assistant message is one `talk` leaf for its
+ * text (if any) and one `tool` leaf per tool call; a tool result is one `echo` leaf. Thinking is never logged (§2). Pi's
+ * positional `system` messages are not part of the log. `before[j]` is how many leaves precede message `j`.
+ */
+export declare function leavesOf(messages: readonly Message[], cap?: number): {
+    leaves: Leaf[];
+    before: number[];
+};
+/** The leaves of one conversation and their fingerprints. Replacing the leaves reports where the history changed. */
+export declare class OptChatLog {
+    #private;
+    get leaves(): readonly Leaf[];
+    /** Replace the leaves. Returns the first index that differs from before, or the old length if the log only grew. */
+    set(next: readonly Leaf[]): number;
+    /** Fingerprint of what node (level, index) covers: the leaf hash, or a hash of its children's fingerprints. */
+    fp(level: number, index: number): string | undefined;
+}
+/** A stored summary and the fingerprint of the content it was made from. */
+export interface StoredNode {
+    readonly text: string;
+    readonly of: string;
+}
+export declare const nodeKey: (level: number, index: number) => string;
+export declare const span: (level: number) => number;
+/**
+ * Node (l, i) covers leaves [i·2^l, (i+1)·2^l). A node is built when its text exists: a short leaf, or two short children
+ * that fit together, are their own text (§3, "free nodes"); anything else needs a stored summary whose fingerprint still
+ * matches the log, and, above level 0, both children built. A stale summary is never shown.
+ */
+export declare class OptChatTree {
+    #private;
+    readonly log: OptChatLog;
+    readonly stored: ReadonlyMap<string, StoredNode>;
+    readonly nodeBytes: number;
+    constructor(log: OptChatLog, stored: ReadonlyMap<string, StoredNode>, nodeBytes: number);
+    reset(): void;
+    text(level: number, index: number): string | undefined;
+}
+/** One line of the view: node (level, index), which names leaves [i·2^l, (i+1)·2^l). */
+export interface Part {
+    readonly level: number;
+    readonly index: number;
+    bytes: number;
+    /** True while the node has no text yet (a long message waiting for its summary). */
+    open: boolean;
+}
+/** The view folded so far over leaves [0, T): a tiling of the log by tree nodes, oldest first. */
+export interface ViewFold {
+    T: number;
+    size: number;
+    parts: Part[];
+}
+export declare const emptyFold: () => ViewFold;
+export declare const partStart: (part: Pick<Part, "level" | "index">) => number;
+/**
+ * Append leaves up to `to` (one part each, fitting after every append) and refit with what has been built since. The view
+ * only ever appends at its end and coarsens, so its start stays the same from one request to the next (§5.2).
+ */
+export declare function advanceFold(fold: ViewFold, tree: OptChatTree, to: number, viewBytes: number): ViewFold;
+/** The view's parts that still wait for a summary. */
+export declare const openParts: (fold: ViewFold) => Part[];
+/** One line per part, `id+n|text`, newlines as spaces, wrapped in `<chat>` (§5.1). */
+export declare function renderView(fold: ViewFold, tree: OptChatTree): string;
+/** The view's lines before `end` as bare text, one per line, with no ids: what a summarizer sees as context (§4.2). */
+export declare function bareLines(fold: ViewFold, tree: OptChatTree, end: number): string;
+/** zoom(id, n): line `id+n` opened into its two children, or message `id` whole when n is 1 (§7.1). */
+export declare function zoomText(tree: OptChatTree, id: number, n: number): string;
+/** date(id): when message `id` was created, as an ISO time. */
+export declare function dateText(log: OptChatLog, id: number): string;
+/** The summarizer's system prompt (reference §4.4, shortened to the kinds Pi logs: no notes, no subagent reports). */
+export declare const compactPrompt: (agent: string) => string;
+/** The system prompt section that explains the view (reference §7.2, VIEW_DOC), constant so provider caches stay warm. */
+export declare const viewDoc: (agent: string) => string;
+/** A realistic summary line that is as close to `nodeBytes` as whole words allow, to give the summarizer a sense of size. */
+export declare function scaleLine(nodeBytes: number): {
+    text: string;
+    bytes: number;
+};
+//# sourceMappingURL=optchat-core.d.ts.map

package/dist/memory/optchat-core.js

@@ -0,0 +1,317 @@
+export const DEFAULTS = {
+    /** Target size of one summary line, in UTF-8 bytes. */
+    nodeBytes: 512,
+    /** Budget of the rendered view, in UTF-8 bytes. */
+    viewBytes: 128_000,
+    /** Summarizer calls running at once. */
+    jobs: 8,
+    /** Attempts per node to get a line under `nodeBytes`. */
+    tries: 5,
+    /** Longest leaf, in characters; longer tool output keeps its head and tail. */
+    cap: 30_000,
+    /** Wait before a failed node is tried again. */
+    retryMs: 10_000,
+    /** How long a request waits for the summaries it needs. */
+    settleTimeoutMs: 60_000,
+};
+/** What a view line shows for a message that has no summary yet. Only a fail-safe: requests wait for summaries. */
+export const PLACEHOLDER = '(not summarized yet: zoom it)';
+/** UTF-8 length without allocating. */
+export function byteLength(text) {
+    let bytes = 0;
+    for (let i = 0; i < text.length; i++) {
+        const code = text.charCodeAt(i);
+        if (code < 0x80)
+            bytes += 1;
+        else if (code < 0x800)
+            bytes += 2;
+        else if (code >= 0xd800 && code <= 0xdbff && i + 1 < text.length) {
+            bytes += 4;
+            i++;
+        }
+        else
+            bytes += 3;
+    }
+    return bytes;
+}
+/** The longest prefix of `text` that fits in `max` bytes, never splitting a character. */
+export function cutBytes(text, max) {
+    if (byteLength(text) <= max)
+        return text;
+    let bytes = 0, end = 0;
+    for (const char of text) {
+        const size = byteLength(char);
+        if (bytes + size > max)
+            break;
+        bytes += size;
+        end += char.length;
+    }
+    return text.slice(0, end);
+}
+/** A 53-bit string hash (cyrb53), base 36. Fingerprints only need to tell different content apart. */
+export function hashText(text) {
+    let h1 = 0xdeadbeef, h2 = 0x41c6ce57;
+    for (let i = 0; i < text.length; i++) {
+        const code = text.charCodeAt(i);
+        h1 = Math.imul(h1 ^ code, 2654435761);
+        h2 = Math.imul(h2 ^ code, 1597334677);
+    }
+    h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+    h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^ Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+    return (4294967296 * (2097151 & h2) + (h1 >>> 0)).toString(36);
+}
+const flat = (text) => text.replace(/\r?\n/g, ' ');
+const textOf = (content) => typeof content === 'string' ? content
+    : (content ?? []).map(part => part.type === 'text' ? part.text ?? '' : `[${part.type}]`).filter(Boolean).join('\n');
+/** Keep the head and tail of text longer than `cap` characters, and say how much was cut. */
+export function capText(text, cap) {
+    if (text.length <= cap)
+        return text;
+    const head = Math.ceil(cap / 2), tail = Math.floor(cap / 2);
+    return `${text.slice(0, head)}\n[… ${text.length - cap} characters cut …]\n${text.slice(text.length - tail)}`;
+}
+function leafOf(kind, text, at, cap) {
+    const capped = capText(text, cap);
+    const line = `${kind}: ${capped}`;
+    return { kind, text: capped, line, bytes: byteLength(line), hash: hashText(line), ...(at === undefined ? {} : { at }) };
+}
+/**
+ * The OptChat log of a Pi model context. A user message is one `user` leaf; an assistant message is one `talk` leaf for its
+ * text (if any) and one `tool` leaf per tool call; a tool result is one `echo` leaf. Thinking is never logged (§2). Pi's
+ * positional `system` messages are not part of the log. `before[j]` is how many leaves precede message `j`.
+ */
+export function leavesOf(messages, cap = DEFAULTS.cap) {
+    const leaves = [], before = [];
+    for (const message of messages) {
+        before.push(leaves.length);
+        const at = typeof message.timestamp === 'number' ? message.timestamp : undefined;
+        if (message.role === 'user')
+            leaves.push(leafOf('user', textOf(message.content), at, cap));
+        else if (message.role === 'assistant') {
+            const talk = message.content.filter(part => part.type === 'text').map(part => part.text).join('\n');
+            if (talk.trim())
+                leaves.push(leafOf('talk', talk, at, cap));
+            for (const part of message.content)
+                if (part.type === 'toolCall')
+                    leaves.push(leafOf('tool', `${part.name} ${JSON.stringify(part.arguments)}`, at, cap));
+        }
+        else if (message.role === 'toolResult')
+            leaves.push(leafOf('echo', `${message.toolName}${message.isError ? ' (error)' : ''}: ${textOf(message.content)}`, at, cap));
+    }
+    before.push(leaves.length);
+    return { leaves, before };
+}
+/** The leaves of one conversation and their fingerprints. Replacing the leaves reports where the history changed. */
+export class OptChatLog {
+    #leaves = [];
+    #memo = new Map();
+    get leaves() { return this.#leaves; }
+    /** Replace the leaves. Returns the first index that differs from before, or the old length if the log only grew. */
+    set(next) {
+        const old = this.#leaves;
+        const shared = Math.min(old.length, next.length);
+        let first = 0;
+        while (first < shared && old[first].hash === next[first].hash)
+            first++;
+        if (first < old.length)
+            this.#memo.clear();
+        this.#leaves = next;
+        return first;
+    }
+    /** Fingerprint of what node (level, index) covers: the leaf hash, or a hash of its children's fingerprints. */
+    fp(level, index) {
+        if ((index + 1) * 2 ** level > this.#leaves.length)
+            return undefined;
+        if (level === 0)
+            return this.#leaves[index].hash;
+        const key = `${level}:${index}`;
+        let found = this.#memo.get(key);
+        if (found === undefined) {
+            found = hashText(`${this.fp(level - 1, 2 * index)}|${this.fp(level - 1, 2 * index + 1)}`);
+            this.#memo.set(key, found);
+        }
+        return found;
+    }
+}
+export const nodeKey = (level, index) => `${level}:${index}`;
+export const span = (level) => 2 ** level;
+/**
+ * Node (l, i) covers leaves [i·2^l, (i+1)·2^l). A node is built when its text exists: a short leaf, or two short children
+ * that fit together, are their own text (§3, "free nodes"); anything else needs a stored summary whose fingerprint still
+ * matches the log, and, above level 0, both children built. A stale summary is never shown.
+ */
+export class OptChatTree {
+    log;
+    stored;
+    nodeBytes;
+    #memo = new Map();
+    constructor(log, stored, nodeBytes) {
+        this.log = log;
+        this.stored = stored;
+        this.nodeBytes = nodeBytes;
+    }
+    reset() { this.#memo.clear(); }
+    text(level, index) {
+        if ((index + 1) * 2 ** level > this.log.leaves.length)
+            return undefined;
+        const key = nodeKey(level, index);
+        const memo = this.#memo.get(key);
+        if (memo !== undefined)
+            return memo;
+        let out;
+        if (level === 0) {
+            const leaf = this.log.leaves[index];
+            out = leaf.bytes <= this.nodeBytes ? leaf.line : this.#valid(key, level, index);
+        }
+        else {
+            const a = this.text(level - 1, 2 * index), b = this.text(level - 1, 2 * index + 1);
+            if (a === undefined || b === undefined)
+                return undefined;
+            const joined = `${a}\n${b}`;
+            out = byteLength(joined) <= this.nodeBytes ? joined : this.#valid(key, level, index);
+        }
+        if (out !== undefined)
+            this.#memo.set(key, out);
+        return out;
+    }
+    #valid(key, level, index) {
+        const stored = this.stored.get(key);
+        return stored !== undefined && stored.of === this.log.fp(level, index) ? stored.text : undefined;
+    }
+}
+export const emptyFold = () => ({ T: 0, size: 0, parts: [] });
+export const partStart = (part) => part.index * 2 ** part.level;
+const label = (part) => `${partStart(part)}+${span(part.level)}`;
+const lineBytes = (part, text) => byteLength(label(part)) + 1 + byteLength(flat(text)) + 1;
+function settleOpen(fold, tree) {
+    for (const part of fold.parts) {
+        if (!part.open)
+            continue;
+        const text = tree.text(part.level, part.index);
+        if (text === undefined)
+            continue;
+        const bytes = lineBytes(part, text);
+        fold.size += bytes - part.bytes;
+        part.bytes = bytes;
+        part.open = false;
+    }
+}
+/** Merge the most due adjacent pair until the view fits, never splitting; stop when no parent is built (§5.2). */
+function fit(fold, tree, viewBytes) {
+    while (fold.size > viewBytes) {
+        let best = -1, bestDue = -Infinity;
+        for (let p = 0; p + 1 < fold.parts.length; p++) {
+            const a = fold.parts[p], b = fold.parts[p + 1];
+            if (a.level !== b.level || a.index % 2 !== 0 || b.index !== a.index + 1)
+                continue;
+            if (tree.text(a.level + 1, a.index / 2) === undefined)
+                continue;
+            const due = (fold.T - partStart(a)) / 2 ** (a.level + 2);
+            if (due > bestDue) {
+                best = p;
+                bestDue = due;
+            }
+        }
+        if (best < 0)
+            return;
+        const a = fold.parts[best], b = fold.parts[best + 1];
+        const merged = { level: a.level + 1, index: a.index / 2, bytes: 0, open: false };
+        merged.bytes = lineBytes(merged, tree.text(merged.level, merged.index));
+        fold.size += merged.bytes - a.bytes - b.bytes;
+        fold.parts.splice(best, 2, merged);
+    }
+}
+/**
+ * Append leaves up to `to` (one part each, fitting after every append) and refit with what has been built since. The view
+ * only ever appends at its end and coarsens, so its start stays the same from one request to the next (§5.2).
+ */
+export function advanceFold(fold, tree, to, viewBytes) {
+    settleOpen(fold, tree);
+    while (fold.T < to) {
+        const index = fold.T++;
+        const text = tree.text(0, index);
+        const part = { level: 0, index, bytes: 0, open: text === undefined };
+        part.bytes = lineBytes(part, text ?? PLACEHOLDER);
+        fold.parts.push(part);
+        fold.size += part.bytes;
+        fit(fold, tree, viewBytes);
+    }
+    fit(fold, tree, viewBytes);
+    return fold;
+}
+/** The view's parts that still wait for a summary. */
+export const openParts = (fold) => fold.parts.filter(part => part.open);
+/** One line per part, `id+n|text`, newlines as spaces, wrapped in `<chat>` (§5.1). */
+export function renderView(fold, tree) {
+    const lines = fold.parts.map(part => `${label(part)}|${flat(tree.text(part.level, part.index) ?? PLACEHOLDER)}`);
+    return `<chat>\n${lines.join('\n')}\n</chat>`;
+}
+/** The view's lines before `end` as bare text, one per line, with no ids: what a summarizer sees as context (§4.2). */
+export function bareLines(fold, tree, end) {
+    return fold.parts.filter(part => partStart(part) + span(part.level) <= end)
+        .map(part => flat(tree.text(part.level, part.index) ?? PLACEHOLDER)).join('\n');
+}
+/** zoom(id, n): line `id+n` opened into its two children, or message `id` whole when n is 1 (§7.1). */
+export function zoomText(tree, id, n) {
+    const total = tree.log.leaves.length;
+    if (!Number.isInteger(id) || !Number.isInteger(n) || n < 1 || (n & (n - 1)) !== 0 || id < 0 || id % n !== 0 || id + n > total)
+        return `No line ${id}+${n}.`;
+    if (n === 1)
+        return `${id}+0|${tree.log.leaves[id].line}`;
+    const level = Math.log2(n) - 1, index = (2 * id) / n;
+    if (tree.text(level + 1, id / n) === undefined)
+        return `No line ${id}+${n}.`;
+    return [index, index + 1].map(child => `${child * 2 ** level}+${2 ** level}|${flat(tree.text(level, child) ?? PLACEHOLDER)}`).join('\n');
+}
+/** date(id): when message `id` was created, as an ISO time. */
+export function dateText(log, id) {
+    const leaf = Number.isInteger(id) ? log.leaves[id] : undefined;
+    if (!leaf)
+        return `No message ${id}.`;
+    return leaf.at === undefined ? `Message ${id} has no recorded time.` : new Date(leaf.at).toISOString();
+}
+// ---- Prompts ------------------------------------------------------------------------------------------------------------
+/** The summarizer's system prompt (reference §4.4, shortened to the kinds Pi logs: no notes, no subagent reports). */
+export const compactPrompt = (agent) => `You write the memory of ${agent}, an AI agent that works for one user in one endless chat, through tools. Each message has a kind: user (the user's words), talk (${agent}'s replies), tool (${agent}'s tool calls), echo (tool results).
+
+Over the messages grows a binary tree of one-line summaries. First, each message is compressed alone into a line (a short message is its own line). Then lines are merged in pairs: two adjacent lines become one line covering both, two of those become one covering four, and so on. Your job is one of these steps: compress one message into a line, or merge two adjacent lines into one.
+
+${agent} sees the chat only through these lines: recent messages one per line, older ones more per line, the older the more. So your line stands in for its messages (your stretch) for weeks or years, and is later merged with its neighbor into the line above. ${agent} can open a line back into the two lines it was made from, down to the messages, but only when the line's words show that what it needs is inside: what your line omits is lost to ${agent} and to every line above.
+
+<chat> is ${agent}'s view up to the last message of your stretch: use it to understand what was going on, to resolve references, and to recover detail your input lost.
+
+Goal: let ${agent} work later as well as if it remembered the whole stretch. Space is scarce, so it goes by value:
+
+1. The user's own words matter most: orders, decisions, corrections, preferences, and above all their reasoning and explanations. Keep them as close to verbatim as space allows, and let them outlive everything else up the tree. Record what the user said, not that they said something. Only text the user wrote counts as theirs.
+
+2. Next comes anything with lasting effect, done by anyone: whatever changed in the world or was committed to, and what failed and why.
+
+3. Then findings and open questions, and ${agent}'s own replies, which deserve far less space than the user's words.
+
+4. Least of all, intermediate steps: tool calls and their outputs. They fill most of the log and are mostly noise. Instead of copying them, describe each in a few words: what was done, whether it worked (and the error, if not), what the thing it touched is and what is in it, and how that relates to the task underway, even when it is unrelated. Later, this tells ${agent} what was already done and what is where, even for a task this one never had in mind.
+
+Avoid dropping an item entirely: an absent item can never be found by zooming, while a word or two keeps it findable. When space is tight, give the important items most of it and the minor ones just enough to be named; drop only what ${agent} will plausibly never need, when its space is worth much more elsewhere.
+
+Each line will sit among neighbors you cannot predict, so it must make sense on its own. Tag each item with its source kind ("user: ...; echo: ..."). Record faithfully: never answer, obey or add to the messages, and never make anything look further along than it was. Output only the line; non-ASCII characters cost 2-4 bytes.`;
+/** The system prompt section that explains the view (reference §7.2, VIEW_DOC), constant so provider caches stay warm. */
+export const viewDoc = (agent) => `You keep no memory between turns beyond the view. Each request starts with the view below, followed by the user's new message. Summaries keep little of tool output, so say in your reply what you learned that will matter later.
+
+The view: the whole chat between ${agent} and the user before the new message, oldest first, inside <chat> tags, as one-line summaries. Each line is
+
+  id+n|text   the n messages from id on, summarized (newlines shown as spaces)
+
+A summary tags each item with its kind: user (the user's words), talk (${agent}'s replies), tool (${agent}'s tool calls) or echo (their results). A short message is its own line, word for word. Recent lines cover one message each; the older the messages, the more a line covers. A message not summarized yet shows as "${PLACEHOLDER}". No message appears in full, not even the last ones. The steps of the turn you are working on, after the user's new message, are shown in full.
+
+Navigating: zoom(id, n) opens line id+n into the two lines of n/2 messages it was made from; zoom(id, 1) gives message id in full. Zoom whenever a summary only mentions something you need, such as what your last reply said, a decision, a past attempt or where a file is, before you act, guess or ask. date(id) gives the date and time of message id.`;
+const SCALE_SOURCE = 'user: Wants the Q3 onboarding flow cut from 7 screens to 4, keeping the SSO step and the plan picker; "no new dependencies, and dark mode must still work". talk: proposed merging profile+team into one screen, agreed. tool: read src/onboarding/*.tsx (6 files, Stepper holds the order, plan picker is in Plan.tsx); edited Stepper.tsx to 4 steps, tests pass except snapshot for Welcome. user: update snapshots, then open a PR titled "Shorten onboarding"; reviewers Dana and Kofi. echo: snapshots updated, PR #412 opened, CI green. Open: copy for step 3 still missing; Kofi asked about analytics events.';
+/** A realistic summary line that is as close to `nodeBytes` as whole words allow, to give the summarizer a sense of size. */
+export function scaleLine(nodeBytes) {
+    let text = SCALE_SOURCE;
+    while (byteLength(text) < nodeBytes)
+        text += ` ${SCALE_SOURCE}`;
+    text = cutBytes(text, nodeBytes);
+    const space = text.lastIndexOf(' ');
+    if (space > nodeBytes - 24)
+        text = text.slice(0, space);
+    return { text, bytes: byteLength(text) };
+}

package/dist/memory/optchat.d.ts

@@ -0,0 +1,156 @@
+import type { ConversationId, Extension, Harness, ModelRef } from '@earendil-works/pi-durable';
+import type { Context } from '@earendil-works/chord';
+import type { Models } from '@earendil-works/pi-ai';
+export { DEFAULTS as OPTCHAT_DEFAULTS, PLACEHOLDER as OPTCHAT_PLACEHOLDER, compactPrompt, viewDoc } from './optchat-core.js';
+export { OptChatLog, OptChatTree, advanceFold, emptyFold, leavesOf, renderView, zoomText, dateText } from './optchat-core.js';
+export type { Leaf, LeafKind, Part, StoredNode, ViewFold } from './optchat-core.js';
+type NodeShard = {
+    nodes: Record<string, {
+        text: string;
+        of: string;
+    }>;
+};
+/** Summaries of one conversation, in shards of 64 nodes per level (`<level>.<shard>`). A fork starts with the current ones; fingerprints reject any that no longer match. */
+export declare const OptChatNodes: import("@earendil-works/pi-durable").ConversationDocFamilyToken<NodeShard, number>;
+type Ledger = {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cost: number;
+};
+type Failure = {
+    at: number;
+    of: string;
+    error: string;
+};
+type StateDoc = {
+    calls: number;
+    usage: Ledger;
+    failures: Record<string, Failure>;
+};
+/** Compactor bookkeeping of one conversation: the summarizer's calls and spend, and the last failure of each node (the retry spacing reads it; no timer does). */
+export declare const OptChatState: import("@earendil-works/pi-durable").ConversationDocToken<StateDoc>;
+/** One summary to write: a message to compress (`source` is its whole `kind: text`) or two adjacent lines to merge. */
+export interface SummaryJob {
+    /** The conversation whose memory this node belongs to. */
+    readonly conversationId: ConversationId;
+    readonly level: number;
+    readonly index: number;
+    /** The leaves the node covers: first and last id. */
+    readonly range: readonly [number, number];
+    readonly source: readonly string[];
+    /** The view's lines before the node, bare and without ids. */
+    readonly context: string;
+    readonly nodeBytes: number;
+}
+export interface OptChatOptions {
+    /** The harness the extension is installed in (read when needed, so it may open after this call). */
+    readonly harness: () => Harness;
+    /** Long-lived context for host work (creating summary tasks and waiting for them outlive any one request). */
+    readonly context: Context;
+    /**
+     * Who writes the summaries (required: the reference never shows cut text, so there is no clipping fallback). Either a
+     * model, called with the reference protocol (a cheap one is best; a function may follow the conversation's model), or
+     * your own `summarize(job, signal)` returning one line, which is trimmed and cut to `nodeBytes`.
+     * Summarizer spend is kept in this extension's own state document and reported by `stats().compactor.usage`. It is not in
+     * Pi's `pi.usage`: Pi has no public way for a task to record model usage (BORING-PI-4), so that guarantee is unavailable.
+     * `models` is optional: it defaults to the Harness's own models.
+     */
+    readonly summarizer: {
+        readonly models?: Models;
+        readonly model: ModelRef | ((conversationId: ConversationId) => ModelRef | Promise<ModelRef>);
+    } | {
+        readonly summarize: (job: SummaryJob, signal: AbortSignal) => Promise<string>;
+    };
+    /** Native extension name. Default `boring.memory.optchat`. */
+    readonly name?: string;
+    /** What the prompts call the agent. Default `OptChat`. */
+    readonly agentName?: string;
+    readonly nodeBytes?: number;
+    readonly viewBytes?: number;
+    /** At most this many summary tasks of one conversation are live at once: the host's admission cap, not a scheduler (Pi runs the tasks). */
+    readonly jobs?: number;
+    readonly tries?: number;
+    readonly cap?: number;
+    readonly retryMs?: number;
+    /** How long a request waits for the summaries its view needs before it shows `(not summarized yet: zoom it)` for the rest. */
+    readonly settleTimeoutMs?: number;
+    /** A node failed (reported once per failure streak of a node; the next trigger after `retryMs` creates its task again). */
+    readonly onError?: (error: unknown, node: {
+        conversationId: ConversationId;
+        level: number;
+        index: number;
+    }) => void;
+}
+export interface OptChatStats {
+    /** Messages in the log (Pi messages split into user, talk, tool and echo leaves). */
+    readonly leaves: number;
+    /** Stored summaries whose fingerprint matches the log. */
+    readonly summaries: number;
+    readonly view: {
+        /** Bytes of the view's lines (what `budget` limits), without the `<chat>` wrapper. */
+        readonly bytes: number;
+        readonly budget: number;
+        /** Lines the next request would show, oldest first. `id` and `n` as in `id+n`. */
+        readonly parts: readonly {
+            readonly id: number;
+            readonly n: number;
+            readonly level: number;
+            readonly text: string;
+            readonly open: boolean;
+        }[];
+        /** Lines still waiting for a summary. */
+        readonly open: number;
+    };
+    readonly compactor: {
+        /** Live summary tasks (pending, running or waiting) in Pi's native state. */
+        readonly busy: number;
+        /** Failed nodes still inside their `retryMs` window. */
+        readonly retrying: number;
+        /** Failed nodes (last failure kept in the conversation's state document until the node is built). */
+        readonly failed: number;
+        readonly idle: boolean;
+        readonly error?: string;
+        /** Summarizer calls made for this conversation (from the state document, so it survives a restart). */
+        readonly calls: number;
+        /** Spend of those calls (kept by this extension; not in Pi's `pi.usage`). */
+        readonly usage: {
+            readonly input: number;
+            readonly output: number;
+            readonly cacheRead: number;
+            readonly cacheWrite: number;
+            readonly cost: number;
+        };
+    };
+    /** The last request this extension rewrote. */
+    readonly lastRequest?: {
+        readonly at: string;
+        /** Leaves before the current turn: what the view covers. */
+        readonly covered: number;
+        readonly requestMessages: number;
+        readonly logMessages: number;
+        readonly viewBytes: number;
+        readonly waitedMs: number;
+        /** False if the wait timed out and the view shows placeholders. */
+        readonly settled: boolean;
+    };
+}
+export interface OptChatMemory {
+    /** Install in the harness registry, then select per conversation: `conversation.configure({ extensions: { add: [memory.extension] } }, context)`. */
+    readonly extension: Extension;
+    /** Create summary tasks for the whole log and wait for them until nothing is left to build (nodes waiting to be retried do not block). */
+    nap(conversationId: ConversationId): Promise<void>;
+    /** The view the next request would show, summary coverage and compactor state. Reads the log; changes nothing. */
+    stats(conversationId: ConversationId): Promise<OptChatStats>;
+    /** The same text as the `zoom` tool. */
+    zoom(conversationId: ConversationId, id: number, n: number): Promise<string>;
+    /** The same text as the `date` tool. */
+    date(conversationId: ConversationId, id: number): Promise<string>;
+    /** Drop in-memory state of a conversation (stored summaries stay). */
+    forget(conversationId: ConversationId): void;
+    /** Stop this process's waits. Summary tasks belong to Pi, which keeps or recovers them; harmless to skip, and safe to call before closing the harness. */
+    dispose(): Promise<void>;
+}
+export declare function createOptChatMemory(options: OptChatOptions): OptChatMemory;
+//# sourceMappingURL=optchat.d.ts.map