pi-optchat 0.11.0 → 0.11.2

package/dist/core/memory.d.ts

@@ -0,0 +1,196 @@
+import type { Saved, Store } from './store.ts';
+export declare const NODE = 512;
+export declare const VIEW = 128000;
+export declare const CAP = 30000;
+/** The most characters of one message a leaf sends the compactor, so a huge paste can't overflow it; zoom still pages through all of it. */
+export declare const SOURCE = 100000;
+/** The most characters one zoom into a message returns, so a page stays under the tool output CAP instead of losing its middle. */
+export declare const PAGE = 25000;
+export declare const KINDS: readonly ['user', 'talk', 'tool', 'echo', 'note', 'work'];
+export type Kind = typeof KINDS[number];
+/** Marks an entry as imported history: the summarizer treats it as historical, not as a new request. `source` is a label the host
+ * chooses, such as "claude" or "email". */
+export interface Origin {
+    source: string;
+    conversation: string;
+    message: string;
+    title: string;
+    project?: string;
+}
+/** A message as stores save it. */
+export interface Entry {
+    i: number;
+    kind: Kind;
+    text: string;
+    date: string;
+    receipt?: string;
+    origin?: Origin;
+}
+/** A message as memory keeps it in RAM: its text stays in the store, and `Memory.text(i)` reads it. */
+export type Message = Omit<Entry, 'text'>;
+export interface Part {
+    l: number;
+    i: number;
+}
+/** A summary node as stores save it. `size` is its line's bytes in a view. */
+export interface Summary extends Part {
+    text: string;
+    size: number;
+}
+/** A summary node as memory keeps it in RAM: `Memory.summary(part)` reads its text from the store. */
+export type Node = Omit<Summary, 'text'>;
+/** `part` is the node to build: a message's leaf, or the merge of its two halves. `call` is the tool call a tool result's leaf
+ * answers, raw, since its own line is often not built yet (#153). */
+export interface Compression {
+    context: string;
+    source: string;
+    part: Part;
+    historical?: boolean;
+    call?: {
+        i: number;
+        text: string;
+    };
+}
+export type Compressor = (input: Compression, signal: AbortSignal) => Promise<string>;
+/** A compressor throws this when the model itself gives no line for an input (a refusal, an empty reply, 5 cut-off replies):
+ * asked again it fails alike, so the node keeps the start of its source instead of being retried forever (#193). */
+export declare class Refused extends Error {
+}
+export declare const start: ({ l, i }: Part) => number;
+export declare const end: (part: Part) => number;
+export declare const bytes: (s: string) => number;
+export declare const flat: (s: string) => string;
+/** The first NODE bytes, without a split character at the end. */
+export declare const cut: (s: string) => string;
+export declare const isView: (text: string) => boolean;
+export declare function cap(text: string, limit?: number): string;
+/** The index of the view's most due pair of sibling lines whose parent is built, or -1 (recipe §3.2). A pair is as due as
+ * long ago it ended, in its own line size; equal pairs go oldest first. This is the order of Taelin's rollback push. */
+export declare function mostDue(view: readonly Part[], total: number, built: (part: Part) => boolean): number;
+export declare function isEntry(value: unknown): value is Entry;
+export declare function isSummary(value: unknown): value is Summary;
+/** The log is authoritative. The tree and the view follow the recipe: the view grows a line per message and, once it passes
+ * `budget`, merges its most due pairs in one batch down to half of it, so between batches it only grows at its end.
+ * Compactions get their own view (recipe §4): the chat's merged further, to between an eighth and a quarter of the budget,
+ * and again whenever the chat's merges, so parallel compactions read it from the cache. */
+export declare class Memory {
+    private readonly compress;
+    private readonly warn;
+    readonly budget: number;
+    private readonly jobs;
+    private readonly retryMs;
+    readonly root: Message[];
+    readonly tree: Map<number, Node>;
+    /** Texts whose store write hasn't finished (a store that writes behind can't read them yet) or was skipped after a failed save,
+     * by message index and by node. */
+    private readonly unsaved;
+    private readonly listeners;
+    private readonly controller;
+    private readonly busy;
+    private readonly retryAt;
+    private readonly reported;
+    /** Messages without their node, and merges whose halves are built, oldest first, so the scheduler never scans the tree for work (recipe §4). */
+    private readonly unbuilt;
+    private readonly merges;
+    private retryTimer?;
+    /** The most summaries owed at once since none were last owed. */
+    private peak;
+    private scheduled;
+    private stopped;
+    private readonly chat;
+    private readonly compaction;
+    /** The last store write still running, if any. Once an append fails, later writes are skipped and appends throw, as after a failed file write. */
+    private writing?;
+    private failed?;
+    readonly store: Store;
+    /** Why a message's append failed in the store, if one did: from then on nothing more is saved, yet `settle` and `close` still
+     * resolve, so a host whose store writes behind checks this to learn its log lost its tail. */
+    get saveError(): string | undefined;
+    lastError?: string;
+    /** `saved` is what `store.load()` gave (see `openMemory`). `jobs`: summaries built at once, and how many unbuilt lines a new
+     * message's node waits behind. Pi's chat and imports pass the "Summaries at once" setting. */
+    constructor({ store, saved }: {
+        store: Store;
+        saved: Saved;
+    }, compress: Compressor, warn?: (s: string) => void, budget?: number, jobs?: number, retryMs?: number);
+    append(kind: Kind, text: string, date?: string, receipt?: string, origin?: Origin): Entry;
+    node(part: Part): Node | undefined;
+    /** Message `i`'s text, from the store. */
+    text(i: number): string;
+    /** Every message with its text, read from the store: for imports, which plan from the whole log. */
+    entries(): Entry[];
+    /** A built node's text, from the store. */
+    summary(part: Part): string | undefined;
+    private line;
+    /** `write`, with `text` kept in `unsaved` until the write has finished. */
+    private keeping;
+    /** Runs a store write at once when none is running, so a store that finishes its writes as it returns (FileStore) throws here
+     * as before; otherwise after the running ones, so writes land in the order Memory makes them. Returns the queued write, settled
+     * through `failed`, unless it finished at once. */
+    private enqueue;
+    /** Takes the saved views if they still tile the log from the start, and returns how many messages they cover. */
+    private load;
+    /** A saved view, `{ parts, merging }` or an older bare list of parts, if it tiles the log from the start. */
+    private tiling;
+    /** Saved when either view merges or changes batch state: a view that only grew is the saved one plus later messages, as `load`
+     * replays it. The log stays authoritative, so a failed save only warns. */
+    private save;
+    private push;
+    get view(): readonly Part[];
+    render(): string;
+    get ready(): boolean;
+    get pending(): number;
+    get active(): number;
+    get size(): number;
+    /** Summaries built out of the backlog since it was last empty, and when the next failed one is retried. */
+    progress(now?: number): {
+        done: number;
+        total: number;
+        retryIn: number | undefined;
+    };
+    private owed;
+    onChange(listener: () => void): () => void;
+    private emit;
+    /** The view line covering message `at`. */
+    covering(at: number): Part | undefined;
+    /** Returns whether either view, or its batch state, changed. */
+    private fit;
+    private schedule;
+    private pump;
+    /** Nothing is being built, nothing more can start, and something failed: only a retry can make progress. */
+    private get stalled();
+    private build;
+    /** The tool call a result answers: a run of calls is followed by their results in the same order. A result that doesn't
+     * start with the call's tool name (an `Agent error`, an odd import) has none. */
+    private callOf;
+    /** The compactions' view up to the node. A line still being built shows as a placeholder instead of ending the view: an A/B on
+     * real turns (#101) found that cutting there also hid the built lines after it, such as an echo's own tool call. */
+    private compactionView;
+    private queueParent;
+    /** A 'turn' waits until every part of the view is built, or until everything pending has failed: it then goes on with placeholders
+     * for the missing lines, `lastError` says why, and the failed nodes are still retried in the background. 'tree' waits for every
+     * node, through failures. As in the recipe, the view may run over budget until pending merges land.
+     * 'ahead' (imports) waits until a new message's node would start at once. Due merges count too: messages go first, so a steady
+     * stream of them would otherwise take every worker and the views could never merge. */
+    settle(signal?: AbortSignal, until?: 'turn' | 'tree' | 'ahead'): Promise<void>;
+    private expectedNodes;
+    /** n = 1 gives the message whole, or, when it is longer than `limit` or `offset` is given, the page of up to `limit` characters from `offset`.
+     * Paging a message that fits in one page is allowed, but the page says so. */
+    zoom(id: number, n: number, offset?: number, limit?: number): string;
+    /** The largest whole lines covering the chat, oldest first: one per power of two in the message count. */
+    private roots;
+    /** Original messages containing `text`, ignoring case, newest first, older than message `before`. Never summaries,
+     * nor the logged zoom/search calls and results, which only copy memory. */
+    search(text: string, before?: number): Message[];
+    date(id: number): string;
+    close(): Promise<void>;
+}
+/** `jobs`: summaries built at once (8). `retryMs`: how long a failed summary waits before it is tried again. */
+export interface MemoryOptions {
+    warn?: (s: string) => void;
+    budget?: number;
+    jobs?: number;
+    retryMs?: number;
+}
+/** Loads a store and opens its memory. */
+export declare function openMemory(store: Store, compress: Compressor, { warn, budget, jobs, retryMs }?: MemoryOptions): Promise<Memory>;