agent-sh 0.14.8 → 0.14.9

package/dist/agent/agent-loop.d.ts

@@ -16,7 +16,6 @@ import type { AgentMode } from "./host-types.js";
 import type { LlmClient } from "./llm-client.js";
 import type { HandlerFunctions } from "../utils/handler-registry.js";
 import { type AgentBackend, type ToolDefinition } from "./types.js";
-import { type HistoryAdapter } from "./history-file.js";
 import type { Compositor } from "../utils/compositor.js";
 export interface AgentLoopConfig {
     bus: EventBus;
@@ -26,12 +25,10 @@ export interface AgentLoopConfig {
     compositor?: Compositor;
     /** Instance ID from core — ensures history entries match the ID in prompts. */
     instanceId?: string;
-    history?: HistoryAdapter;
 }
 export declare class AgentLoop implements AgentBackend {
     private abortController;
     private toolRegistry;
-    private history;
     private conversation;
     private fileReadCache;
     private activeMode;
@@ -111,7 +108,6 @@ export declare class AgentLoop implements AgentBackend {
     private getRetryDelay;
     /** Format an error with provider context for user-facing display. */
     private formatError;
-    private registerCoreTools;
     /**
      * Register named handlers that extensions can advise.
      * Only high-power use cases where multiple extensions compose.

package/dist/agent/agent-loop.js

@@ -3,9 +3,7 @@ import * as path from "node:path";
 import { contentText } from "./types.js";
 import { ToolRegistry } from "./tool-registry.js";
 import { normalizeToolArgs } from "./normalize-args.js";
-import { ConversationState } from "./conversation-state.js";
-import { HistoryFile } from "./history-file.js";
-import { nucleate, formatNuclearLine, isReadOnly } from "./nuclear-form.js";
+import { LiveView } from "./live-view.js";
 import { STATIC_SYSTEM_PROMPT, buildStaticByCwd, formatSkillsBlock, loadGlobalAgentsMd } from "./system-prompt.js";
 import { createToolUI } from "../utils/tool-interactive.js";
 import { RESPONSE_RESERVE, DEFAULT_CONTEXT_WINDOW } from "./token-budget.js";
@@ -40,7 +38,6 @@ function summarizeDescription(desc) {
 export class AgentLoop {
     abortController = null;
     toolRegistry;
-    history;
     conversation;
     fileReadCache;
     activeMode;
@@ -90,19 +87,12 @@ export class AgentLoop {
         this.instanceId = config.instanceId ?? "unknown";
         this.toolRegistry = new ToolRegistry(this.handlers);
         this.fileReadCache = this.handlers.call("agent:file-read-cache");
-        // Shell-history-shaped log. Default writes go through the advisable
-        // `history:append` handler registered below; extensions swap the
-        // backend without touching this wiring.
-        const filePath = process.env.AGENT_SH_HISTORY_FILE || getSettings().historyFilePath;
-        this.history = config.history ?? new HistoryFile({ instanceId: this.instanceId, filePath });
-        this.conversation = new ConversationState(this.handlers, this.instanceId);
+        this.conversation = new LiveView(this.handlers, this.instanceId);
         this.activeMode = config.initialMode ?? { model: config.llmClient.model };
         // Tool protocol — controls how tools are presented to the LLM
         const { names: fromExtensions } = this.bus.emitPipe("agent:core-tools:collect", { names: [] });
         const coreTools = Array.from(new Set([...(getSettings().coreTools ?? []), ...fromExtensions]));
         this.toolProtocol = createToolProtocol(getSettings().toolMode ?? "api", coreTools);
-        // Register core tools
-        this.registerCoreTools();
         // Register any protocol-provided tools (e.g. load_tool for deferred-lookup).
         const protocolTools = this.toolProtocol.getProtocolTools?.() ?? [];
         for (const t of protocolTools)
@@ -249,7 +239,7 @@ export class AgentLoop {
         });
         on("agent:reset-session", () => {
             this.cancel();
-            this.conversation = new ConversationState(this.handlers, this.instanceId);
+            this.conversation = new LiveView(this.handlers, this.instanceId);
             this.lastProjectSkillNames.clear();
         });
         on("agent:compact-request", async () => {
@@ -267,8 +257,6 @@ export class AgentLoop {
         onPipe("context:get-stats", () => ({
             activeTokens: this.conversation.estimateTokens(),
             totalTokens: this.conversation.estimatePromptTokens(),
-            nuclearEntries: this.conversation.getNuclearEntryCount(),
-            recallArchiveSize: this.conversation.getRecallArchiveSize(),
             budgetTokens: this.currentMode.contextWindow ?? DEFAULT_CONTEXT_WINDOW,
         }));
         onPipe("context:snapshot", (payload) => {
@@ -283,14 +271,6 @@ export class AgentLoop {
                 payload.stats = { before: stats.before, after: stats.after, evictedCount: stats.evictedCount };
             return payload;
         });
-        // Prior-session preamble (non-blocking). Both the read and the
-        // layout go through advisable handlers.
-        Promise.resolve(this.handlers.call("history:read-recent"))
-            .then((entries) => {
-            if (entries && entries.length > 0)
-                this.conversation.loadPriorHistory(entries);
-        })
-            .catch(() => { });
         // Track generic compaction metrics from the `conversation:after-compact`
         // event. Whatever strategy ran, core accumulates these counters for
         // status/introspect consumers.
@@ -560,77 +540,6 @@ export class AgentLoop {
         const context = provider ? ` (${provider}, model: ${model})` : ` (model: ${model})`;
         return `${raw}${context}`;
     }
-    registerCoreTools() {
-        // Stateless core tools register in agentBackend; conversation_recall
-        // stays here because it needs this.conversation.
-        this.toolRegistry.register({
-            name: "conversation_recall",
-            displayName: "recall",
-            description: "Browse, search, or expand evicted conversation turns. " +
-                "Use when you need context from earlier in the conversation that was compacted away. " +
-                "Search is regex-based and covers both summaries and full body text. " +
-                "If search doesn't find what you expect, try broader/shorter terms or browse to scan the timeline.",
-            input_schema: {
-                type: "object",
-                properties: {
-                    action: {
-                        type: "string",
-                        enum: ["browse", "search", "expand"],
-                        description: "browse: list evicted turns, search: regex search, expand: show full turn",
-                    },
-                    query: {
-                        type: "string",
-                        description: "Search query (for action=search)",
-                    },
-                    turn_id: {
-                        type: "number",
-                        description: "Turn ID to expand (for action=expand)",
-                    },
-                },
-                required: ["action"],
-            },
-            execute: async (args) => {
-                const action = args.action;
-                let content;
-                if (action === "search") {
-                    content = await this.conversation.search(args.query ?? "");
-                }
-                else if (action === "expand") {
-                    content = await this.conversation.expand(args.turn_id);
-                }
-                else {
-                    content = await this.conversation.browse();
-                }
-                return { content, exitCode: 0, isError: false };
-            },
-            formatResult: (args, result) => {
-                const action = args.action;
-                const text = contentText(result.content);
-                if (result.isError)
-                    return { summary: "error" };
-                if (action === "search") {
-                    if (text.startsWith("No results"))
-                        return { summary: "0 matches" };
-                    const m = text.match(/^Found (\d+)/);
-                    return { summary: m ? `${m[1]} matches` : "search done" };
-                }
-                if (action === "browse") {
-                    if (text.startsWith("No conversation"))
-                        return { summary: "empty" };
-                    return { summary: "browsed" };
-                }
-                if (text.includes("no expanded content"))
-                    return { summary: "not found" };
-                return { summary: "expanded" };
-            },
-            getDisplayInfo: () => ({ kind: "search", icon: "\u27F2" }),
-        });
-        this.registerInstruction("recall-guidance", "When starting a task that may have been discussed before (conventions, preferences, corrections, prior examples), " +
-            "use conversation_recall to search history for relevant prior entries. " +
-            "Treat recurring user guidance as standing preferences. " +
-            "If a search returns nothing useful, try: shorter queries, alternate terms, or browse to scan the full timeline. " +
-            "Recall only covers this and recent sessions — for older context, also search the filesystem (grep, glob).", "core");
-    }
     /**
      * Register named handlers that extensions can advise.
      * Only high-power use cases where multiple extensions compose.
@@ -735,7 +644,6 @@ export class AgentLoop {
             const ratio = getSettings().autoCompactThreshold ?? 0.5;
             return {
                 count: this.compactionCount,
-                nuclearEntries: this.conversation.getNuclearEntryCount(),
                 autoCompactThreshold: ratio,
                 autoCompactThresholdTokens: Math.floor((contextWindow - RESPONSE_RESERVE) * ratio),
             };
@@ -758,58 +666,9 @@ export class AgentLoop {
         });
         h.define("conversation:estimate-tokens", () => this.conversation.estimateTokens());
         h.define("conversation:estimate-prompt-tokens", () => this.conversation.estimatePromptTokens());
-        // ── Nucleation (advisable) ─────────────────────────────────────
-        // Turn a raw message into a one-line NuclearEntry. Advisors enrich
-        // (e.g. `[why: ...]` extraction, adaptive summary lengths).
-        h.define("conversation:nucleate-user", (text, iid, seq) => nucleate("user", text, iid, seq));
-        h.define("conversation:nucleate-agent", (text, iid, seq) => nucleate("agent", text, iid, seq));
-        h.define("conversation:nucleate-tool", (toolName, args, content, isError, iid, seq) => nucleate(isError ? "error" : "tool", toolName, args, content, isError, iid, seq));
-        h.define("conversation:allocate-seq", () => this.conversation.allocateSeq());
-        h.define("conversation:reset-for-session", (nextSeq) => this.conversation.resetForSession(nextSeq));
-        // Read-only views into the nuclear state, for compact strategies
-        // and introspect that read without replacing.
-        h.define("conversation:get-nuclear-entries", () => this.conversation.getNuclearEntries());
-        h.define("conversation:get-nuclear-summary", () => this.conversation.getNuclearSummary());
-        h.define("conversation:build-nuclear-block", () => {
-            const summary = this.conversation.getNuclearSummary();
-            if (!summary)
-                return null;
-            return {
-                role: "user",
-                content: `[Conversation history \u2014 use conversation_recall to expand any entry]\n${summary}`,
-            };
-        });
-        // ── History file I/O (advisable) ───────────────────────────────
-        // Default is the append-only JSONL at ~/.agent-sh/history; advisors
-        // swap the backend without touching nucleation.
-        h.define("history:append", (entries) => {
-            if (!entries || entries.length === 0)
-                return;
-            const writable = entries.filter((e) => !isReadOnly(e));
-            if (writable.length > 0)
-                this.history.append(writable).catch(() => { });
-        });
-        h.define("history:search", async (query) => this.history.search(query));
-        h.define("history:find-by-seq", async (seq) => this.history.findBySeq(seq));
-        h.define("history:read-recent", async (max) => this.history.readRecent(max));
-        h.define("history:get-branch", async (leafSeq) => this.history.getBranch ? this.history.getBranch(leafSeq) : this.history.readRecent());
-        h.define("history:get-tree", async () => this.history.getTree ? this.history.getTree() : this.history.readRecent());
-        h.define("history:set-leaf", (seq) => {
-            this.history.setLeaf?.(seq);
-        });
-        // Prior-session preamble renderer. Default: flat chronological list.
-        h.define("conversation:format-prior-history", (entries) => {
-            if (!entries || entries.length === 0)
-                return null;
-            const lines = entries.map(formatNuclearLine);
-            return `[Prior session history \u2014 loaded from ~/.agent-sh/history]\n${lines.join("\n")}`;
-        });
-        // Compaction strategy — default delegates to the two-tier pin
-        // strategy in ConversationState; advisors replace wholesale.
+        h.define("conversation:link", (index, entryId) => this.conversation.link(index, entryId));
         h.define("conversation:compact", (opts) => {
             const strategy = opts.strategy;
-            // Synthesize a CompactResult for manual edits so conversation:after-compact
-            // listeners (metrics, file-read cache, system-prompt cache) still run.
             if (strategy?.kind === "rewind" || strategy?.kind === "replace") {
                 const before = this.conversation.estimatePromptTokens();
                 const beforeLen = this.conversation.getMessages().length;
@@ -821,10 +680,7 @@ export class AgentLoop {
                 const afterLen = this.conversation.getMessages().length;
                 return { before, after, evictedCount: Math.max(0, beforeLen - afterLen) };
             }
-            const tgt = strategy?.kind === "two-tier-pin" ? strategy.target : opts.target;
-            const keep = strategy?.kind === "two-tier-pin" ? strategy.keepRecent : opts.keepRecent;
-            const force = strategy?.kind === "two-tier-pin" ? strategy.force : opts.force;
-            return this.conversation.compact(tgt, keep, force);
+            return null;
         });
         // Inject a system note mid-loop — used by extensions (subagents,
         // peer messages) to deliver async results into the next iteration.
@@ -970,8 +826,9 @@ export class AgentLoop {
             // Auto-compact when total context approaches the window limit.
             const totalEstimate = this.conversation.estimatePromptTokens();
             const contextWindow = this.currentMode.contextWindow ?? DEFAULT_CONTEXT_WINDOW;
-            const threshold = Math.floor((contextWindow - RESPONSE_RESERVE) * getSettings().autoCompactThreshold);
-            if (totalEstimate > threshold) {
+            const s = getSettings();
+            const threshold = Math.floor((contextWindow - RESPONSE_RESERVE) * s.autoCompactThreshold);
+            if (s.autoCompact && totalEstimate > threshold) {
                 // Compact deeply — shallow targets buy only 1–2 turns of runway on
                 // tool-heavy workloads.
                 const target = Math.floor(threshold * 0.25);
@@ -1015,7 +872,6 @@ export class AgentLoop {
                 break;
             // No tool calls → agent is done
             if (toolCalls.length === 0) {
-                this.conversation.eagerNucleateAgent(fullResponseText);
                 break;
             }
             // Emit batch info so the TUI can render group headers upfront
@@ -1300,20 +1156,6 @@ export class AgentLoop {
             });
             // Record all tool results via protocol
             this.toolProtocol.recordResults(this.conversation, collectedResults);
-            const tcMap = new Map();
-            for (const tc of toolCalls) {
-                if (tc.id)
-                    tcMap.set(tc.id, tc);
-            }
-            this.conversation.eagerNucleateTools(collectedResults.map((r) => {
-                const tc = tcMap.get(r.callId);
-                let args = {};
-                try {
-                    args = tc ? JSON.parse(tc.argumentsJson) : {};
-                }
-                catch { }
-                return { toolName: r.toolName, args, content: r.content, isError: !!r.isError };
-            }));
             // Emit enriched message-appended events so derived-log extensions
             // can summarize each tool result without re-parsing the message
             // structure.

package/dist/agent/entry-format.d.ts

@@ -0,0 +1,5 @@
+/** Display line for synthetic summary blocks and conversation_recall.
+ *  The leading `#${id}` is the token the LLM uses to reference an
+ *  entry when calling `recall:expand`. */
+import type { Entry } from "./store.js";
+export declare function formatEntryLine(e: Entry): string;

package/dist/agent/entry-format.js

@@ -0,0 +1,9 @@
+export function formatEntryLine(e) {
+    const d = new Date(e.ts);
+    const pad = (n) => String(n).padStart(2, "0");
+    const stamp = `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
+    const p = e.payload;
+    const sum = p.sum ?? `(${e.kind})`;
+    const whyTag = p.why ? ` {${p.why.length > 80 ? p.why.slice(0, 77) + "..." : p.why}}` : "";
+    return `#${e.id} [${stamp}] ${sum}${whyTag}`;
+}

package/dist/agent/extensions/rolling-history/constants.d.ts

@@ -0,0 +1 @@
+export declare const RECALL_CACHE_KIND = "recall-cache";

package/dist/agent/extensions/rolling-history/constants.js

@@ -0,0 +1 @@
+export const RECALL_CACHE_KIND = "recall-cache";

package/dist/agent/extensions/rolling-history/index.d.ts

@@ -0,0 +1,4 @@
+import type { ExtensionContext } from "../../../shell/host-types.js";
+/** One-time migration: old ~/.agent-sh/history → rolling-history store. */
+export declare function migrateFromLegacy(storeDir: string, legacyPath: string, ctx: Pick<ExtensionContext, "bus">): void;
+export default function activate(ctx: ExtensionContext): void;

package/dist/agent/extensions/rolling-history/index.js

@@ -0,0 +1,203 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { contentText } from "../../types.js";
+import { SharedFileStore, newEntryId } from "../../store.js";
+import { CONFIG_DIR, getSettings } from "../../../core/settings.js";
+import { deserializeEntry, isReadOnly } from "../../nuclear-form.js";
+import { activate as activateSummaryStrategy, nuclearToEntry, readSummaryLines, } from "./strategy.js";
+import { recallSearch, recallExpand, recallBrowse } from "./recall.js";
+const TOOL_NAME = "conversation_recall";
+const INSTRUCTION_NAME = "recall-guidance";
+const INSTRUCTION_TEXT = "When starting a task that may have been discussed before (conventions, preferences, corrections, prior examples), " +
+    "use conversation_recall to search history for relevant prior entries. " +
+    "Treat recurring user guidance as standing preferences. " +
+    "If a search returns nothing useful, try: shorter queries, alternate terms, or browse to scan the full timeline. " +
+    "Recall only covers this and recent sessions — for older context, also search the filesystem (grep, glob).";
+/** One-time migration: old ~/.agent-sh/history → rolling-history store. */
+export function migrateFromLegacy(storeDir, legacyPath, ctx) {
+    const sentinel = path.join(storeDir, ".migrated");
+    if (fs.existsSync(sentinel))
+        return;
+    const newFile = path.join(storeDir, "history.jsonl");
+    if (fs.existsSync(newFile) && fs.statSync(newFile).size > 0) {
+        try {
+            fs.writeFileSync(sentinel, "");
+        }
+        catch { /* ignore */ }
+        return;
+    }
+    if (!fs.existsSync(legacyPath)) {
+        try {
+            fs.writeFileSync(sentinel, "");
+        }
+        catch { /* ignore */ }
+        return;
+    }
+    let migrated = 0;
+    try {
+        const lines = fs.readFileSync(legacyPath, "utf-8").split("\n").filter(Boolean);
+        const entries = [];
+        for (const line of lines) {
+            const ne = deserializeEntry(line);
+            if (!ne)
+                continue;
+            if (isReadOnly(ne))
+                continue;
+            entries.push(nuclearToEntry(ne, newEntryId()));
+        }
+        if (entries.length > 0) {
+            fs.writeFileSync(newFile, entries.map((e) => JSON.stringify(e) + "\n").join(""));
+            migrated = entries.length;
+        }
+    }
+    catch {
+        return; // retry next start
+    }
+    try {
+        fs.writeFileSync(sentinel, "");
+    }
+    catch { /* ignore */ }
+    if (migrated > 0) {
+        ctx.bus.emit("ui:info", { message: `history: migrated ${migrated} entries from legacy ~/.agent-sh/history` });
+    }
+}
+export default function activate(ctx) {
+    const { maxBytes, prefetchEntries } = ctx.getExtensionSettings("rolling-history", {
+        maxBytes: undefined,
+        prefetchEntries: 50,
+    });
+    const storeDir = ctx.getStoragePath("rolling-history");
+    const settings = getSettings();
+    const legacyPath = settings.historyFilePath ?? path.join(CONFIG_DIR, "history");
+    migrateFromLegacy(storeDir, legacyPath, ctx);
+    const summaryStore = new SharedFileStore({
+        filePath: path.join(storeDir, "history.jsonl"),
+        maxBytes,
+    });
+    // `/history off` gates only writes — store.append and the linkMessage
+    // back-stamp. Everything else (meta.tool stamping, compact's reorg,
+    // recall reads) runs identically on both sides. Tool + instruction stay
+    // registered either way so toggling never perturbs the tools array or
+    // system prompt (LLM prompt cache is preserved).
+    let enabled = true;
+    const gatedStore = {
+        append: (entries, opts) => enabled ? summaryStore.append(entries, opts) : Promise.resolve(),
+        findById: (id) => summaryStore.findById(id),
+        readRecent: (n) => summaryStore.readRecent(n),
+        search: (q) => summaryStore.search(q),
+    };
+    const summaryCtx = {
+        store: gatedStore,
+        bus: { on: (e, f) => ctx.bus.on(e, f) },
+        advise: (op, f) => { ctx.advise(op, f); },
+        iid: ctx.instanceId,
+        getMessages: () => ctx.call("conversation:get-messages") ?? [],
+        replaceMessages: (msgs) => { ctx.call("conversation:replace-messages", msgs); },
+        estimateTokens: () => ctx.call("conversation:estimate-tokens") ?? 0,
+        estimatePromptTokens: () => ctx.call("conversation:estimate-prompt-tokens") ?? 0,
+        linkMessage: (index, entryId) => { if (enabled)
+            ctx.call("conversation:link", index, entryId); },
+    };
+    activateSummaryStrategy(summaryCtx);
+    const toolDef = {
+        name: TOOL_NAME,
+        displayName: "recall",
+        description: "Browse, search, or expand evicted conversation turns. " +
+            "Use when you need context from earlier in the conversation that was compacted away. " +
+            "Search is regex-based and covers both summaries and full body text. " +
+            "If search doesn't find what you expect, try broader/shorter terms or browse to scan the timeline.",
+        input_schema: {
+            type: "object",
+            properties: {
+                action: {
+                    type: "string",
+                    enum: ["browse", "search", "expand"],
+                    description: "browse: list evicted turns, search: regex search, expand: show full turn",
+                },
+                query: { type: "string", description: "Search query (for action=search)" },
+                turn_id: { type: "string", description: "Turn ID to expand (for action=expand)" },
+            },
+            required: ["action"],
+        },
+        execute: async (args) => {
+            const action = args.action;
+            let content;
+            if (action === "search") {
+                content = await recallSearch(summaryStore, args.query ?? "");
+            }
+            else if (action === "expand") {
+                content = await recallExpand(summaryStore, args.turn_id);
+            }
+            else {
+                content = await recallBrowse(summaryStore);
+            }
+            return { content, exitCode: 0, isError: false };
+        },
+        formatResult: (args, result) => {
+            const action = args.action;
+            const text = contentText(result.content);
+            if (result.isError)
+                return { summary: "error" };
+            if (action === "search") {
+                if (text.startsWith("No results"))
+                    return { summary: "0 matches" };
+                const m = text.match(/^Found (\d+)/);
+                return { summary: m ? `${m[1]} matches` : "search done" };
+            }
+            if (action === "browse") {
+                if (text.startsWith("No conversation"))
+                    return { summary: "empty" };
+                return { summary: "browsed" };
+            }
+            if (text.includes("no expanded content"))
+                return { summary: "not found" };
+            return { summary: "expanded" };
+        },
+        getDisplayInfo: () => ({ kind: "search", icon: "⟲" }),
+    };
+    if (ctx.agent) {
+        ctx.agent.registerTool(toolDef);
+        ctx.agent.registerInstruction(INSTRUCTION_NAME, INSTRUCTION_TEXT);
+    }
+    ctx.registerCommand("history", "Toggle conversation history writes (on / off / status).", (args) => {
+        const arg = args.trim().toLowerCase();
+        if (arg === "" || arg === "status") {
+            ctx.bus.emit("ui:info", { message: `history: writes ${enabled ? "on" : "off"} — recall remains available for prior sessions` });
+            return;
+        }
+        if (arg === "on") {
+            if (enabled) {
+                ctx.bus.emit("ui:info", { message: "history: already on" });
+                return;
+            }
+            enabled = true;
+            ctx.bus.emit("ui:info", { message: "history: on — new turns will be summarized" });
+            return;
+        }
+        if (arg === "off") {
+            if (!enabled) {
+                ctx.bus.emit("ui:info", { message: "history: already off" });
+                return;
+            }
+            enabled = false;
+            ctx.bus.emit("ui:info", { message: "history: off — new turns won't be summarized (recall still available)" });
+            return;
+        }
+        ctx.bus.emit("ui:info", { message: `history: unknown arg "${arg}" (use on / off / status)` });
+    });
+    if (prefetchEntries > 0) {
+        Promise.resolve().then(async () => {
+            const lines = await readSummaryLines(summaryStore, prefetchEntries);
+            if (lines.length === 0)
+                return;
+            const current = ctx.call("conversation:get-messages") ?? [];
+            ctx.call("conversation:replace-messages", [
+                ...current,
+                {
+                    role: "user",
+                    content: `[Prior session history — loaded from the summary store]\n${lines.join("\n")}`,
+                },
+            ]);
+        }).catch(() => { });
+    }
+}

package/dist/agent/extensions/rolling-history/recall.d.ts

@@ -0,0 +1,4 @@
+import type { Store } from "../../store.js";
+export declare function recallSearch(store: Store, query: string): Promise<string>;
+export declare function recallExpand(store: Store, id: string): Promise<string>;
+export declare function recallBrowse(store: Store, limit?: number): Promise<string>;

package/dist/agent/extensions/rolling-history/recall.js

@@ -0,0 +1,122 @@
+import { formatEntryLine } from "../../entry-format.js";
+import { RECALL_CACHE_KIND } from "./constants.js";
+import { readSummaryLines } from "./strategy.js";
+function turnToText(msgs) {
+    const lines = [];
+    for (const m of msgs) {
+        if (m.role === "user") {
+            lines.push(`[user] ${typeof m.content === "string" ? m.content : JSON.stringify(m.content)}`);
+        }
+        else if (m.role === "assistant") {
+            if (typeof m.content === "string" && m.content)
+                lines.push(`[assistant] ${m.content}`);
+            if ("tool_calls" in m && m.tool_calls) {
+                for (const tc of m.tool_calls) {
+                    if ("function" in tc)
+                        lines.push(`[tool_call] ${tc.function.name}(${tc.function.arguments})`);
+                }
+            }
+        }
+        else if (m.role === "tool") {
+            lines.push(`[tool] ${typeof m.content === "string" ? m.content : JSON.stringify(m.content)}`);
+        }
+        else {
+            lines.push(`[${m.role}] ${typeof m.content === "string" ? m.content : JSON.stringify(m.content)}`);
+        }
+    }
+    return lines.join("\n");
+}
+function firstMatchExcerpt(text, regex) {
+    const idx = text.search(regex);
+    if (idx === -1)
+        return null;
+    const lineStart = text.lastIndexOf("\n", idx) + 1;
+    const lineEnd = text.indexOf("\n", idx);
+    const line = text.slice(lineStart, lineEnd === -1 ? text.length : lineEnd).trim();
+    if (line.length > 120) {
+        const matchInLine = idx - lineStart;
+        const start = Math.max(0, matchInLine - 40);
+        const end = Math.min(line.length, matchInLine + 80);
+        return (start > 0 ? "…" : "") + line.slice(start, end) + (end < line.length ? "…" : "");
+    }
+    return line;
+}
+function buildSearchRegex(query) {
+    try {
+        return new RegExp(query, "i");
+    }
+    catch {
+        const words = query.split(/\s+/).filter((w) => w.length > 0);
+        const escaped = words.map((w) => w.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+        const lookaheads = escaped.map((w) => `(?=.*${w})`).join("");
+        return new RegExp(lookaheads, "i");
+    }
+}
+/** Cache entries are ephemeral, so this only resolves for the
+ *  current process. */
+async function findCacheChild(store, parentId) {
+    const recent = await store.readRecent();
+    for (let i = recent.length - 1; i >= 0; i--) {
+        const e = recent[i];
+        if (e.kind === RECALL_CACHE_KIND && e.parentId === parentId) {
+            return e.payload;
+        }
+    }
+    return null;
+}
+export async function recallSearch(store, query) {
+    if (!query.trim())
+        return "No query provided.";
+    const regex = buildSearchRegex(query);
+    const hits = [];
+    const seenParents = new Set();
+    const matches = await store.search(query);
+    for (const m of matches) {
+        // Cache hits surface via their parent summary; summary hits are their own parent.
+        let parentEntry = null;
+        if (m.entry.kind === RECALL_CACHE_KIND) {
+            if (!m.entry.parentId)
+                continue;
+            parentEntry = await store.findById(m.entry.parentId);
+        }
+        else {
+            parentEntry = m.entry;
+        }
+        if (!parentEntry || seenParents.has(parentEntry.id))
+            continue;
+        seenParents.add(parentEntry.id);
+        const cache = await findCacheChild(store, parentEntry.id);
+        const excerptSource = cache
+            ? turnToText([cache.fullMessage])
+            : parentEntry.payload.body ?? "";
+        const excerpt = excerptSource ? firstMatchExcerpt(excerptSource, regex) : null;
+        const header = formatEntryLine(parentEntry);
+        hits.push(excerpt ? `${header}\n  ${excerpt}` : header);
+    }
+    if (hits.length === 0)
+        return `No results found for "${query}".`;
+    const total = hits.length;
+    const summary = `Found ${total} match${total === 1 ? "" : "es"} for "${query}"`;
+    return `${summary}\n\n${hits.slice(0, 30).join("\n\n")}`;
+}
+export async function recallExpand(store, id) {
+    const entry = await store.findById(id);
+    if (!entry)
+        return `Entry ${id}: not found.`;
+    if (entry.kind === RECALL_CACHE_KIND)
+        return `Entry ${id}: not expandable.`;
+    const header = formatEntryLine(entry);
+    const cache = await findCacheChild(store, id);
+    if (cache)
+        return `${header}\n\n${turnToText([cache.fullMessage])}`;
+    const body = entry.payload.body;
+    if (body)
+        return `${header}\n\n${body}`;
+    return `${header}\n\n(no expanded content available — recall cache may have been cleared)`;
+}
+export async function recallBrowse(store, limit = 25) {
+    const lines = await readSummaryLines(store, limit);
+    if (lines.length === 0)
+        return "No conversation history.";
+    return ["Recent summary entries:", ...lines.map((l) => `  ${l}`)].join("\n");
+}