@nookplot/runtime 0.5.131 → 0.5.132

package/dist/conversation/compactionMemory.d.ts

@@ -0,0 +1,124 @@
+import { HookRegistry } from "../hooks.js";
+import type { InferenceMessage } from "../types.js";
+import type { ConversationMemory } from "./conversationMemory.js";
+import type { ConversationLogStore } from "./conversationLogStore.js";
+/** Caller-supplied summarizer. We do NOT pin a model dependency. */
+export type CompactFn = (messages: InferenceMessage[], systemPrompt: string) => Promise<string>;
+export interface CompactionConfig {
+    /** Looked up in `MODEL_THRESHOLDS`; unknown models fall back to the default. */
+    modelName: string;
+    /** Trigger compaction at `safetyRatio × compactAt` tokens. Default 0.8. */
+    safetyRatio?: number;
+    /** Override the threshold's `preserveRecent` count. */
+    preserveRecent?: number;
+    /** Prepended to the compaction request. Default from `modelLimits.ts`. */
+    systemPromptPreamble?: string;
+    /** Where to persist messages. Omit for purely in-memory operation. */
+    store?: ConversationLogStore;
+    /** Stable session id. Auto-generated when omitted. */
+    sessionId?: string;
+    /** Whether `buildTools()` returns search/read tool defs. Default true. */
+    enableMemoryTools?: boolean;
+    /** Hook registry for `memory_compacted` events. Defaults to runtime singleton. */
+    hooks?: HookRegistry;
+    /** How to summarize. Caller injects so the SDK doesn't pull in an LLM dep. */
+    compactFn: CompactFn;
+    /** Override the token estimator. Defaults to gateway-parity heuristic. */
+    estimateTokens?: (messages: InferenceMessage[]) => number;
+    /** Maximum chars stored per summary. Default 2000 (matches gateway). */
+    maxSummaryChars?: number;
+}
+/** Runtime-observable counters. */
+export interface CompactionStats {
+    messageCount: number;
+    pendingToolCalls: number;
+    compactionCount: number;
+    estimatedTokens: number;
+}
+/**
+ * Lightweight tool-definition shape returned by `buildTools()`. We don't reuse
+ * the registry's `ToolDefinition` because these tools live entirely inside the
+ * agent process — they have no cost, no rate limit, no autonomy bracket.
+ */
+export interface MemoryToolDefinition {
+    name: string;
+    description: string;
+    /** JSON Schema describing the tool's arguments (LLM-facing). */
+    inputSchema: {
+        type: "object";
+        properties: Record<string, {
+            type: string;
+            description?: string;
+            minimum?: number;
+        }>;
+        required?: string[];
+    };
+    /** Local handler. The session id is captured in the closure — never an LLM arg. */
+    handler: (args: Record<string, unknown>) => Promise<unknown>;
+}
+export declare class CompactionMemory implements ConversationMemory {
+    readonly sessionId: string;
+    private readonly threshold;
+    private readonly safetyRatio;
+    private readonly preserveRecent;
+    private readonly preamble;
+    private readonly store;
+    private readonly hooks;
+    private readonly compactFn;
+    private readonly estimateTokensFn;
+    private readonly enableMemoryTools;
+    private readonly maxSummaryChars;
+    /** Linear list of messages that will be sent to the LLM next call. */
+    private messages;
+    /** Indices into `messages` immediately AFTER each closed unit. */
+    private unitBoundaries;
+    /** Outstanding tool calls awaiting their replies. */
+    private pendingToolCalls;
+    /** Monotonic counter, used in `LogEntry.compactionNumber`. */
+    private compactionCount;
+    /**
+     * Number of original messages that have been collapsed away by all prior
+     * compactions. Used to project log-store indices into the live array.
+     */
+    private removedFromHead;
+    /** Serializes `_autoCompact` so two near-simultaneous calls don't double-compact. */
+    private compactionInFlight;
+    constructor(config: CompactionConfig);
+    addMessage(msg: InferenceMessage): Promise<void>;
+    getContext(): InferenceMessage[];
+    reset(): Promise<void>;
+    stats(): CompactionStats;
+    /**
+     * Reconstruct a `CompactionMemory` from its persisted JSONL log.
+     *
+     * Algorithm: replay entries in append order, maintaining the live message
+     * array. A `message` entry appends. A `compaction` entry replaces the head
+     * `messagesCompacted` messages with the summary system message. A `reset`
+     * entry clears the array. Truncated tail lines are skipped by `store.read`.
+     *
+     * This walk-and-fold approach preserves the invariant that messages added
+     * BETWEEN the last addMessage that triggered compaction and the compaction
+     * write itself stay in the tail — exactly mirroring the in-memory state
+     * after `_autoCompact`.
+     */
+    static restoreFromLog(sessionId: string, store: ConversationLogStore, config: Omit<CompactionConfig, "sessionId" | "store">): Promise<CompactionMemory>;
+    /**
+     * Tool definitions the caller can hand to the LLM so the agent can recover
+     * detail the summary dropped. The session id is captured in the closure —
+     * the LLM never supplies it. Returns `[]` when `enableMemoryTools: false`
+     * or no `store` is configured (no log → nothing to search).
+     */
+    buildTools(): MemoryToolDefinition[];
+    private updateUnitState;
+    private shouldCompact;
+    private runCompactionOnce;
+    /**
+     * Pick the latest closed unit boundary that leaves at least `preserveRecent`
+     * messages in the tail, summarize everything before it, and replace the
+     * collapsed prefix with one `role: "system"` summary message.
+     */
+    private _autoCompact;
+    /** Recompute unitBoundaries + pendingToolCalls from `this.messages` in place. */
+    private replayUnitState;
+}
+//# sourceMappingURL=compactionMemory.d.ts.map

package/dist/conversation/compactionMemory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compactionMemory.d.ts","sourceRoot":"","sources":["../../src/conversation/compactionMemory.ts"],"names":[],"mappings":"AAkCA,OAAO,EAAyB,YAAY,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EAAE,oBAAoB,EAAY,MAAM,2BAA2B,CAAC;AAQhF,oEAAoE;AACpE,MAAM,MAAM,SAAS,GAAG,CACtB,QAAQ,EAAE,gBAAgB,EAAE,EAC5B,YAAY,EAAE,MAAM,KACjB,OAAO,CAAC,MAAM,CAAC,CAAC;AAErB,MAAM,WAAW,gBAAgB;IAC/B,gFAAgF;IAChF,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uDAAuD;IACvD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0EAA0E;IAC1E,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,sEAAsE;IACtE,KAAK,CAAC,EAAE,oBAAoB,CAAC;IAC7B,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,kFAAkF;IAClF,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,8EAA8E;IAC9E,SAAS,EAAE,SAAS,CAAC;IACrB,0EAA0E;IAC1E,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,gBAAgB,EAAE,KAAK,MAAM,CAAC;IAC1D,wEAAwE;IACxE,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,mCAAmC;AACnC,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,WAAW,CAAC,EAAE,MAAM,CAAC;YAAC,OAAO,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACrF,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;IACF,mFAAmF;IACnF,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9D;AAOD,qBAAa,gBAAiB,YAAW,kBAAkB;IACzD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiB;IAC3C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmC;IACzD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA2C;IAC5E,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAU;IAC5C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IAGzC,sEAAsE;IACtE,OAAO,CAAC,QAAQ,CAA0B;IAC1C,kEAAkE;IAClE,OAAO,CAAC,cAAc,CAAgB;IACtC,qDAAqD;IACrD,OAAO,CAAC,gBAAgB,CAAK;IAC7B,8DAA8D;IAC9D,OAAO,CAAC,eAAe,CAAK;IAC5B;;;OAGG;IACH,OAAO,CAAC,eAAe,CAAK;IAC5B,qFAAqF;IACrF,OAAO,CAAC,kBAAkB,CAA8B;gBAE5C,MAAM,EAAE,gBAAgB;IAgB9B,UAAU,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBtD,UAAU,IAAI,gBAAgB,EAAE;IAI1B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAW5B,KAAK,IAAI,eAAe;IAWxB;;;;;;;;;;;;OAYG;WACU,cAAc,CACzB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,oBAAoB,EAC3B,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,WAAW,GAAG,OAAO,CAAC,GACpD,OAAO,CAAC,gBAAgB,CAAC;IAkC5B;;;;;OAKG;IACH,UAAU,IAAI,oBAAoB,EAAE;IAsEpC,OAAO,CAAC,eAAe;IA0BvB,OAAO,CAAC,aAAa;YAKP,iBAAiB;IAW/B;;;;OAIG;YACW,YAAY;IA2E1B,iFAAiF;IACjF,OAAO,CAAC,eAAe;CAqBxB"}

package/dist/conversation/compactionMemory.js

@@ -0,0 +1,379 @@
+/**
+ * `CompactionMemory` — turn-boundary-aware conversation memory with optional
+ * JSONL persistence.
+ *
+ * **Why turn boundaries.** When you compact mid-turn, you risk leaving an
+ * orphaned `role: "tool"` reply in the preserved tail without its calling
+ * `assistant` message in the prefix — which most LLMs will reject. We track
+ * three unit kinds (lifted in spirit from Motus's `compaction_memory.py`):
+ *
+ *   - **Unit A**: a single `role: "user"` message.
+ *   - **Unit B**: an `assistant` message with N `toolCalls`, followed by all N
+ *     matching `role: "tool"` replies.
+ *   - **Unit C**: an `assistant` message with no `toolCalls` (final answer).
+ *
+ * Compaction only fires when `pendingToolCalls === 0` AND the message stream
+ * has at least one closed unit boundary that we can roll up.
+ *
+ * **Compaction output.** The replaced prefix is collapsed into a single
+ * `role: "system"` message whose content is `"[Conversation Summary]\n" +
+ * sanitizeForPrompt(summary)` — same shape `gateway/sessionCompactor.ts:225`
+ * emits, so downstream prompt-assembly code doesn't have to branch.
+ *
+ * **Persistence.** Every `addMessage` and every compaction writes a single
+ * JSONL line via the configured `ConversationLogStore`. Restart-recovery is
+ * exposed as `CompactionMemory.restoreFromLog(sessionId, store, cfg)`.
+ *
+ * **Hook integration.** Successful compactions emit a fire-and-forget
+ * `memory_compacted` event via the configured `HookRegistry` (defaults to the
+ * runtime singleton). Slow subscribers don't delay the next `addMessage`.
+ *
+ * @module conversation/compactionMemory
+ */
+import { randomUUID } from "node:crypto";
+import { sanitizeForPrompt } from "../contentSafety.js";
+import { hooks as defaultHooks } from "../hooks.js";
+import { DEFAULT_COMPACTION_SYSTEM_PROMPT, estimateTokens as defaultEstimateTokens, getModelThreshold, } from "./modelLimits.js";
+const DEFAULT_SAFETY_RATIO = 0.8;
+const DEFAULT_MAX_SUMMARY_CHARS = 2000;
+const DEFAULT_SEARCH_LIMIT = 5;
+const MAX_SEARCH_LIMIT = 20;
+export class CompactionMemory {
+    sessionId;
+    threshold;
+    safetyRatio;
+    preserveRecent;
+    preamble;
+    store;
+    hooks;
+    compactFn;
+    estimateTokensFn;
+    enableMemoryTools;
+    maxSummaryChars;
+    // Live state ──────────────────────────────────────────────
+    /** Linear list of messages that will be sent to the LLM next call. */
+    messages = [];
+    /** Indices into `messages` immediately AFTER each closed unit. */
+    unitBoundaries = [];
+    /** Outstanding tool calls awaiting their replies. */
+    pendingToolCalls = 0;
+    /** Monotonic counter, used in `LogEntry.compactionNumber`. */
+    compactionCount = 0;
+    /**
+     * Number of original messages that have been collapsed away by all prior
+     * compactions. Used to project log-store indices into the live array.
+     */
+    removedFromHead = 0;
+    /** Serializes `_autoCompact` so two near-simultaneous calls don't double-compact. */
+    compactionInFlight = null;
+    constructor(config) {
+        this.sessionId = config.sessionId ?? randomUUID();
+        this.threshold = getModelThreshold(config.modelName);
+        this.safetyRatio = config.safetyRatio ?? DEFAULT_SAFETY_RATIO;
+        this.preserveRecent = config.preserveRecent ?? this.threshold.preserveRecent;
+        this.preamble = config.systemPromptPreamble ?? DEFAULT_COMPACTION_SYSTEM_PROMPT;
+        this.store = config.store;
+        this.hooks = config.hooks ?? defaultHooks;
+        this.compactFn = config.compactFn;
+        this.estimateTokensFn = config.estimateTokens ?? defaultEstimateTokens;
+        this.enableMemoryTools = config.enableMemoryTools ?? true;
+        this.maxSummaryChars = config.maxSummaryChars ?? DEFAULT_MAX_SUMMARY_CHARS;
+    }
+    // ── ConversationMemory ──────────────────────────────────
+    async addMessage(msg) {
+        this.messages.push(msg);
+        this.updateUnitState(msg);
+        if (this.store) {
+            await this.store.append(this.sessionId, {
+                kind: "message",
+                ts: new Date().toISOString(),
+                msg,
+            });
+        }
+        // Compaction is only safe at a closed-unit boundary. Defer otherwise.
+        if (this.pendingToolCalls === 0 && this.shouldCompact()) {
+            await this.runCompactionOnce();
+        }
+    }
+    getContext() {
+        return this.messages.slice();
+    }
+    async reset() {
+        this.messages = [];
+        this.unitBoundaries = [];
+        this.pendingToolCalls = 0;
+        this.compactionCount = 0;
+        this.removedFromHead = 0;
+        if (this.store) {
+            await this.store.append(this.sessionId, { kind: "reset", ts: new Date().toISOString() });
+        }
+    }
+    stats() {
+        return {
+            messageCount: this.messages.length,
+            pendingToolCalls: this.pendingToolCalls,
+            compactionCount: this.compactionCount,
+            estimatedTokens: this.estimateTokensFn(this.messages),
+        };
+    }
+    // ── Restore ─────────────────────────────────────────────
+    /**
+     * Reconstruct a `CompactionMemory` from its persisted JSONL log.
+     *
+     * Algorithm: replay entries in append order, maintaining the live message
+     * array. A `message` entry appends. A `compaction` entry replaces the head
+     * `messagesCompacted` messages with the summary system message. A `reset`
+     * entry clears the array. Truncated tail lines are skipped by `store.read`.
+     *
+     * This walk-and-fold approach preserves the invariant that messages added
+     * BETWEEN the last addMessage that triggered compaction and the compaction
+     * write itself stay in the tail — exactly mirroring the in-memory state
+     * after `_autoCompact`.
+     */
+    static async restoreFromLog(sessionId, store, config) {
+        const memory = new CompactionMemory({ ...config, sessionId, store });
+        if (!(await store.exists(sessionId)))
+            return memory;
+        const entries = await store.read(sessionId);
+        for (const entry of entries) {
+            if (entry.kind === "reset") {
+                memory.messages = [];
+                memory.compactionCount = 0;
+                memory.removedFromHead = 0;
+                continue;
+            }
+            if (entry.kind === "message") {
+                memory.messages.push(entry.msg);
+                continue;
+            }
+            // compaction
+            const drop = Math.min(entry.messagesCompacted, memory.messages.length);
+            const tail = memory.messages.slice(drop);
+            memory.messages = [
+                { role: "system", content: `[Conversation Summary]\n${entry.summary}` },
+                ...tail,
+            ];
+            memory.compactionCount = entry.compactionNumber;
+            memory.removedFromHead = entry.replacedRange[1];
+        }
+        // Re-derive turn-boundary state from the restored messages.
+        memory.replayUnitState();
+        return memory;
+    }
+    // ── Tool exposure (agent-internal) ──────────────────────
+    /**
+     * Tool definitions the caller can hand to the LLM so the agent can recover
+     * detail the summary dropped. The session id is captured in the closure —
+     * the LLM never supplies it. Returns `[]` when `enableMemoryTools: false`
+     * or no `store` is configured (no log → nothing to search).
+     */
+    buildTools() {
+        if (!this.enableMemoryTools || !this.store)
+            return [];
+        const store = this.store;
+        const sessionId = this.sessionId;
+        const search = {
+            name: "search_conversation_log",
+            description: "Substring search across the current conversation's archived messages " +
+                "(including those collapsed by an earlier summary). Returns the most " +
+                "recent matches first.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: { type: "string", description: "Substring to look for (case-insensitive)." },
+                    maxResults: {
+                        type: "number",
+                        description: "Cap on returned matches (default 5, max 20).",
+                        minimum: 1,
+                    },
+                },
+                required: ["query"],
+            },
+            handler: async (args) => {
+                const query = typeof args.query === "string" ? args.query : "";
+                let cap = typeof args.maxResults === "number" ? Math.floor(args.maxResults) : DEFAULT_SEARCH_LIMIT;
+                if (!Number.isFinite(cap) || cap < 1)
+                    cap = DEFAULT_SEARCH_LIMIT;
+                if (cap > MAX_SEARCH_LIMIT)
+                    cap = MAX_SEARCH_LIMIT;
+                // sessionId is closure-captured. Any `sessionId` arg from the LLM is
+                // silently ignored — defense-in-depth against tool-arg poisoning.
+                return await store.searchMessages(sessionId, query, cap);
+            },
+        };
+        const read = {
+            name: "read_compaction_summary",
+            description: "Return the summary text produced by a past compaction of the current " +
+                "session, by 1-indexed compaction number.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    compactionNumber: {
+                        type: "number",
+                        description: "1-indexed; matches the counter exposed by stats().compactionCount.",
+                        minimum: 1,
+                    },
+                },
+                required: ["compactionNumber"],
+            },
+            handler: async (args) => {
+                const num = typeof args.compactionNumber === "number" ? Math.floor(args.compactionNumber) : 0;
+                if (!Number.isFinite(num) || num < 1) {
+                    throw new Error("compactionNumber must be a positive integer");
+                }
+                const entries = await store.read(sessionId);
+                const match = entries.find((e) => e.kind === "compaction" && e.compactionNumber === num);
+                if (!match) {
+                    throw new Error(`compaction ${num} not found for session`);
+                }
+                return match;
+            },
+        };
+        return [search, read];
+    }
+    // ── Internals ───────────────────────────────────────────
+    updateUnitState(msg) {
+        const idx = this.messages.length; // index AFTER the just-pushed msg
+        if (msg.role === "assistant") {
+            const calls = msg.toolCalls?.length ?? 0;
+            if (calls > 0) {
+                this.pendingToolCalls += calls;
+            }
+            else {
+                // Closes a Unit C immediately.
+                this.unitBoundaries.push(idx);
+            }
+        }
+        else if (msg.role === "tool") {
+            // Decrement, clamping at zero in case of orphan tool results.
+            this.pendingToolCalls = Math.max(0, this.pendingToolCalls - 1);
+            if (this.pendingToolCalls === 0) {
+                this.unitBoundaries.push(idx);
+            }
+        }
+        else if (msg.role === "user") {
+            // The unit BEFORE this user message is already closed (Unit C closed it
+            // at the prior assistant message, OR Unit B closed it at the last tool
+            // reply). Record the user message; compaction check happens after.
+            this.unitBoundaries.push(idx);
+        }
+        // role: "system" never closes a unit. Typically used for the compaction
+        // summary itself or for a static system prompt — neither is a turn boundary.
+    }
+    shouldCompact() {
+        const triggerAt = Math.floor(this.threshold.compactAt * this.safetyRatio);
+        return this.estimateTokensFn(this.messages) >= triggerAt;
+    }
+    async runCompactionOnce() {
+        if (this.compactionInFlight) {
+            await this.compactionInFlight;
+            return;
+        }
+        this.compactionInFlight = this._autoCompact().finally(() => {
+            this.compactionInFlight = null;
+        });
+        await this.compactionInFlight;
+    }
+    /**
+     * Pick the latest closed unit boundary that leaves at least `preserveRecent`
+     * messages in the tail, summarize everything before it, and replace the
+     * collapsed prefix with one `role: "system"` summary message.
+     */
+    async _autoCompact() {
+        const tailReserve = this.preserveRecent;
+        if (this.messages.length <= tailReserve + 1)
+            return;
+        // Pick the largest boundary ≤ messages.length - tailReserve.
+        const cutoffMax = this.messages.length - tailReserve;
+        let boundary = -1;
+        for (const b of this.unitBoundaries) {
+            if (b <= cutoffMax && b > boundary)
+                boundary = b;
+        }
+        if (boundary <= 0)
+            return; // nothing closed yet
+        // Don't bother if the first message is already a system summary AND no real
+        // progress can be made (boundary would replace just that summary).
+        if (boundary === 1 && this.messages[0].role === "system")
+            return;
+        const toCompact = this.messages.slice(0, boundary);
+        const tail = this.messages.slice(boundary);
+        let summary;
+        try {
+            summary = await this.compactFn(toCompact, this.preamble);
+        }
+        catch (err) {
+            // Compaction failure is non-fatal — leave the messages in place and try
+            // again on the next addMessage. Mirrors gateway behavior. Emit a
+            // `compaction_failed` hook so operators can alert on a downed summarizer
+            // instead of silently watching context grow unbounded.
+            this.hooks.emitFireAndForget("compaction_failed", {
+                sessionId: this.sessionId,
+                error: err,
+                attemptedMessages: toCompact.length,
+            });
+            return;
+        }
+        const sanitized = sanitizeForPrompt(summary, this.maxSummaryChars);
+        const summaryMessage = {
+            role: "system",
+            content: `[Conversation Summary]\n${sanitized}`,
+        };
+        const replacedFrom = this.removedFromHead;
+        const replacedTo = this.removedFromHead + boundary;
+        const messagesCompacted = boundary;
+        const summaryTokens = Math.ceil(sanitized.length / 4);
+        this.compactionCount += 1;
+        this.messages = [summaryMessage, ...tail];
+        this.removedFromHead += boundary;
+        // Recompute boundaries against the new `messages` array. The summary
+        // message itself is `system` (no boundary); reapply unit logic for the
+        // preserved tail so future compactions still know where to cut.
+        this.replayUnitState();
+        if (this.store) {
+            await this.store.append(this.sessionId, {
+                kind: "compaction",
+                ts: new Date().toISOString(),
+                compactionNumber: this.compactionCount,
+                replacedRange: [replacedFrom, replacedTo],
+                messagesCompacted,
+                summary: sanitized,
+                summaryTokens,
+                model: "n/a", // caller's compactFn knows the actual model; we don't need it here
+            });
+        }
+        this.hooks.emitFireAndForget("memory_compacted", {
+            sessionId: this.sessionId,
+            compactionNumber: this.compactionCount,
+            messagesCompacted,
+            summaryTokens,
+        });
+    }
+    /** Recompute unitBoundaries + pendingToolCalls from `this.messages` in place. */
+    replayUnitState() {
+        this.unitBoundaries = [];
+        this.pendingToolCalls = 0;
+        for (let i = 0; i < this.messages.length; i++) {
+            const m = this.messages[i];
+            const idxAfter = i + 1;
+            if (m.role === "assistant") {
+                const calls = m.toolCalls?.length ?? 0;
+                if (calls > 0) {
+                    this.pendingToolCalls += calls;
+                }
+                else {
+                    this.unitBoundaries.push(idxAfter);
+                }
+            }
+            else if (m.role === "tool") {
+                this.pendingToolCalls = Math.max(0, this.pendingToolCalls - 1);
+                if (this.pendingToolCalls === 0)
+                    this.unitBoundaries.push(idxAfter);
+            }
+            else if (m.role === "user") {
+                this.unitBoundaries.push(idxAfter);
+            }
+        }
+    }
+}
+//# sourceMappingURL=compactionMemory.js.map

package/dist/conversation/compactionMemory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compactionMemory.js","sourceRoot":"","sources":["../../src/conversation/compactionMemory.ts"],"names":[],"mappings":"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"}

package/dist/conversation/conversationLogStore.d.ts

@@ -0,0 +1,111 @@
+import type { InferenceMessage } from "../types.js";
+/** Single JSONL line. `kind` discriminates the union. */
+export type LogEntry = {
+    kind: "message";
+    ts: string;
+    msg: InferenceMessage;
+} | {
+    kind: "compaction";
+    ts: string;
+    compactionNumber: number;
+    /** Half-open range `[fromIdx, toIdx)` into the log entries that were replaced. */
+    replacedRange: [number, number];
+    messagesCompacted: number;
+    summary: string;
+    summaryTokens: number;
+    model: string;
+} | {
+    kind: "reset";
+    ts: string;
+};
+export interface ConversationLogStore {
+    /** Append a single entry. Implementations must be append-atomic per call. */
+    append(sessionId: string, entry: LogEntry): Promise<void>;
+    /** True iff at least one entry has been appended for `sessionId`. */
+    exists(sessionId: string): Promise<boolean>;
+    /**
+     * Read every entry in append order. Implementations skip malformed lines
+     * (e.g. truncated tails from a crashed write) rather than throwing.
+     */
+    read(sessionId: string): Promise<LogEntry[]>;
+    /**
+     * Substring search across the message bodies of `sessionId`. Returns the
+     * matching messages, most recent first, capped at `maxResults`.
+     */
+    searchMessages(sessionId: string, query: string, maxResults: number): Promise<InferenceMessage[]>;
+    /** Enumerate every session that has been written. */
+    listSessions(): Promise<string[]>;
+    /** Delete the session's log. Idempotent. */
+    delete(sessionId: string): Promise<void>;
+}
+/**
+ * In-process log store for tests. Round-trips identically to
+ * `LocalConversationLogStore` but never touches disk.
+ */
+export declare class InMemoryConversationLogStore implements ConversationLogStore {
+    private readonly logs;
+    append(sessionId: string, entry: LogEntry): Promise<void>;
+    exists(sessionId: string): Promise<boolean>;
+    read(sessionId: string): Promise<LogEntry[]>;
+    searchMessages(sessionId: string, query: string, maxResults: number): Promise<InferenceMessage[]>;
+    listSessions(): Promise<string[]>;
+    delete(sessionId: string): Promise<void>;
+}
+export interface LocalConversationLogStoreOptions {
+    /**
+     * Base directory for JSONL files. Defaults to
+     * `~/.nookplot/conversations/`. Created on first write.
+     */
+    baseDir?: string;
+}
+/**
+ * JSONL-on-disk log. One file per session, named by SHA-256 of the
+ * `sessionId` so the on-disk layout is path-traversal-safe even if a caller
+ * pipes attacker-controlled input as the session id.
+ *
+ * The original `sessionId` is stored alongside the hashed filename in a
+ * sidecar map (`<baseDir>/_sessions.json`) so {@link listSessions} can return
+ * the human-readable identifiers.
+ *
+ * **Concurrency.** Appends and sidecar writes within ONE instance are
+ * serialized via a per-instance promise chain — calling `append()` ten times
+ * in parallel produces ten lines in call order, not ten interleaved partial
+ * writes. Concurrent writers across *processes* (same baseDir, different
+ * runtime instances) are still unsafe; the store is intended for single-
+ * process agents. Use separate `baseDir`s per process to avoid cross-process
+ * races on `_sessions.json`.
+ */
+export declare class LocalConversationLogStore implements ConversationLogStore {
+    private readonly baseDir;
+    private indexLoaded;
+    private readonly index;
+    private indexFilePromise;
+    /**
+     * In-process mutation chain. Any method that reads *and* writes shared state
+     * (`index`, `_sessions.json`, session JSONL files) awaits the previous op
+     * before starting. Read-only ops can skip this.
+     */
+    private mutationChain;
+    constructor(opts?: LocalConversationLogStoreOptions);
+    /**
+     * Run `fn` serialized against any other mutation on this instance. Failures
+     * in `fn` are surfaced to the caller but do NOT poison the chain — the next
+     * call starts from a resolved state.
+     */
+    private serialize;
+    /** Filename for a session: 32-char SHA-256 prefix + `.jsonl`. */
+    private fileFor;
+    private indexPath;
+    private ensureIndex;
+    private persistIndex;
+    private pathFor;
+    append(sessionId: string, entry: LogEntry): Promise<void>;
+    exists(sessionId: string): Promise<boolean>;
+    read(sessionId: string): Promise<LogEntry[]>;
+    searchMessages(sessionId: string, query: string, maxResults: number): Promise<InferenceMessage[]>;
+    listSessions(): Promise<string[]>;
+    delete(sessionId: string): Promise<void>;
+    /** Test helper — list every JSONL file currently on disk. */
+    _debugListFiles(): Promise<string[]>;
+}
+//# sourceMappingURL=conversationLogStore.d.ts.map

package/dist/conversation/conversationLogStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversationLogStore.d.ts","sourceRoot":"","sources":["../../src/conversation/conversationLogStore.ts"],"names":[],"mappings":"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"}