agent-sh 0.7.0 → 0.9.0

package/dist/agent/agent-loop.js

@@ -4,7 +4,12 @@ import * as path from "node:path";
 import { computeDiff } from "../utils/diff.js";
 import { ToolRegistry } from "./tool-registry.js";
 import { ConversationState } from "./conversation-state.js";
+import { HistoryFile } from "./history-file.js";
 import { STATIC_SYSTEM_PROMPT, buildDynamicContext } from "./system-prompt.js";
+import { createToolUI } from "../utils/tool-interactive.js";
+import { TokenBudget } from "./token-budget.js";
+import { getSettings } from "../settings.js";
+import { createToolProtocol } from "./tool-protocol.js";
 // Core tool factories
 import { createBashTool } from "./tools/bash.js";
 import { createReadFileTool } from "./tools/read-file.js";
@@ -18,34 +23,61 @@ import { createDisplayTool } from "./tools/display.js";
 import { createListSkillsTool } from "./tools/list-skills.js";
 import { discoverProjectSkills } from "./skills.js";
 export class AgentLoop {
-    bus;
-    contextManager;
-    llmClient;
-    handlers;
     abortController = null;
     toolRegistry = new ToolRegistry();
-    conversation = new ConversationState();
+    historyFile = new HistoryFile();
+    conversation = new ConversationState(this.historyFile);
     fileReadCache = new Map();
+    tokenBudget;
     modes;
     currentModeIndex = 0;
     boundListeners = [];
+    ctorListeners = [];
+    ctorPipeListeners = [];
     lastProjectSkillNames = new Set();
     static THINKING_LEVELS = ["off", "low", "medium", "high"];
+    bus;
+    contextManager;
+    llmClient;
+    handlers;
     thinkingLevel = "off";
-    constructor(bus, contextManager, llmClient, handlers, modeConfig, initialModeIndex) {
-        this.bus = bus;
-        this.contextManager = contextManager;
-        this.llmClient = llmClient;
-        this.handlers = handlers;
+    compositor = null;
+    toolProtocol;
+    constructor(config) {
+        this.bus = config.bus;
+        this.contextManager = config.contextManager;
+        this.llmClient = config.llmClient;
+        this.handlers = config.handlers;
+        this.compositor = config.compositor ?? null;
         // Default modes: just the configured model
-        this.modes = modeConfig ?? [
-            { model: llmClient.model },
+        this.modes = config.modes ?? [
+            { model: config.llmClient.model },
         ];
-        this.currentModeIndex = initialModeIndex ?? 0;
+        this.currentModeIndex = config.initialModeIndex ?? 0;
+        // Unified token budget — adapts to current model's context window
+        this.tokenBudget = new TokenBudget(this.currentMode.contextWindow);
+        // Tool protocol — controls how tools are presented to the LLM
+        this.toolProtocol = createToolProtocol(getSettings().toolMode ?? "api");
         // Register core tools
         this.registerCoreTools();
+        // Update token budget with tool count
+        this.tokenBudget.update(undefined, this.toolRegistry.all().length);
         // Register handlers — extensions can advise these
         this.registerHandlers();
+        // Subscribe to bus-based tool/instruction registration from extensions.
+        // These must be in the constructor (not wire()) because extensions call
+        // registerTool() during activate(), before activateBackend() calls wire().
+        const onCtor = (event, fn) => {
+            this.bus.on(event, fn);
+            this.ctorListeners.push({ event, fn });
+        };
+        onCtor("agent:register-tool", ({ tool }) => this.registerTool(tool));
+        onCtor("agent:unregister-tool", ({ name }) => this.unregisterTool(name));
+        onCtor("agent:register-instruction", ({ name, text }) => this.registerInstruction(name, text));
+        onCtor("agent:remove-instruction", ({ name }) => this.removeInstruction(name));
+        const getToolsPipe = () => ({ tools: this.getTools() });
+        this.bus.onPipe("agent:get-tools", getToolsPipe);
+        this.ctorPipeListeners.push({ event: "agent:get-tools", fn: getToolsPipe });
     }
     /** Subscribe to bus events — activates this backend. */
     wire() {
@@ -74,8 +106,9 @@ export class AgentLoop {
             else {
                 this.llmClient.model = m.model;
             }
+            this.tokenBudget.update(m.contextWindow, this.toolRegistry.all().length);
             const label = m.provider ? `${m.provider}: ${m.model}` : m.model;
-            this.bus.emit("agent:info", { name: "agent-sh", version: "0.4", model: m.model, provider: m.provider, contextWindow: m.contextWindow });
+            this.bus.emit("agent:info", { name: "ash", version: "0.4", model: m.model, provider: m.provider, contextWindow: m.contextWindow });
             this.bus.emit("ui:info", { message: `Model: ${label}` });
             this.bus.emit("config:changed", {});
         });
@@ -117,13 +150,50 @@ export class AgentLoop {
             else {
                 this.llmClient.model = m.model;
             }
+            this.tokenBudget.update(m.contextWindow, this.toolRegistry.all().length);
+            this.bus.emit("config:changed", {});
+        });
+        on("config:add-modes", ({ modes: extra }) => {
+            // Remove any existing modes for the same provider, then append
+            const providers = new Set(extra.map((m) => m.provider).filter(Boolean));
+            this.modes = [
+                ...this.modes.filter((m) => !m.provider || !providers.has(m.provider)),
+                ...extra,
+            ];
             this.bus.emit("config:changed", {});
         });
         on("agent:reset-session", () => {
             this.cancel();
-            this.conversation = new ConversationState();
+            this.conversation = new ConversationState(this.historyFile);
             this.lastProjectSkillNames.clear();
         });
+        on("agent:compact-request", () => {
+            // Force compaction: use target of 0 so every non-pinned turn is evicted
+            const stats = this.conversation.compact(0, 10, true);
+            this.conversation.flush().catch(() => { });
+            if (stats) {
+                this.bus.emit("ui:info", {
+                    message: `(compacted: ~${stats.before.toLocaleString()} → ~${stats.after.toLocaleString()} tokens)`,
+                });
+            }
+            else {
+                this.bus.emit("ui:info", { message: "(nothing to compact)" });
+            }
+        });
+        this.bus.onPipe("context:get-stats", () => {
+            return {
+                activeTokens: this.conversation.estimateTokens(),
+                nuclearEntries: this.conversation.getNuclearEntryCount(),
+                recallArchiveSize: this.conversation.getRecallArchiveSize(),
+                budgetTokens: this.tokenBudget.conversationBudgetTokens,
+            };
+        });
+        // Load prior history from disk (non-blocking)
+        this.historyFile.readRecent().then((entries) => {
+            if (entries.length > 0) {
+                this.conversation.loadPriorHistory(entries);
+            }
+        }).catch(() => { });
         on("shell:cwd-change", ({ cwd }) => {
             const projectSkills = discoverProjectSkills(cwd);
             const newNames = new Set(projectSkills.map(s => s.name));
@@ -150,12 +220,44 @@ export class AgentLoop {
     registerTool(tool) {
         this.toolRegistry.register(tool);
     }
+    /** Unregister a tool by name. */
+    unregisterTool(name) {
+        this.toolRegistry.unregister(name);
+    }
     /** Get all registered tools. */
     getTools() {
         return this.toolRegistry.all();
     }
+    // ── Extension instructions & tool tracking ──────────────────────
+    instructions = new Map();
+    /** Register a named instruction block for the system prompt. */
+    registerInstruction(name, text) {
+        this.instructions.set(name, text);
+    }
+    /** Remove a named instruction block. */
+    removeInstruction(name) {
+        this.instructions.delete(name);
+    }
+    /** Get instruction blocks registered by extensions. */
+    getInstructionSections() {
+        const sections = [];
+        for (const [name, text] of this.instructions) {
+            sections.push(`## ${name}\n${text}`);
+        }
+        return sections;
+    }
     kill() {
         this.cancel();
+        this.unwire();
+        // Clean up constructor-level bus subscriptions
+        for (const { event, fn } of this.ctorListeners) {
+            this.bus.off(event, fn);
+        }
+        this.ctorListeners = [];
+        for (const { event, fn } of this.ctorPipeListeners) {
+            this.bus.offPipe(event, fn);
+        }
+        this.ctorPipeListeners = [];
     }
     cancel() {
         this.abortController?.abort();
@@ -187,10 +289,11 @@ export class AgentLoop {
         else {
             this.llmClient.model = newMode.model;
         }
+        this.tokenBudget.update(newMode.contextWindow, this.toolRegistry.all().length);
         const label = newMode.provider
             ? `${newMode.provider}: ${newMode.model}`
             : newMode.model;
-        this.bus.emit("agent:info", { name: "agent-sh", version: "0.4", model: newMode.model, provider: newMode.provider, contextWindow: newMode.contextWindow });
+        this.bus.emit("agent:info", { name: "ash", version: "0.4", model: newMode.model, provider: newMode.provider, contextWindow: newMode.contextWindow });
         this.bus.emit("ui:info", { message: `Model: ${label}` });
         this.bus.emit("config:changed", {});
     }
@@ -289,6 +392,46 @@ export class AgentLoop {
         this.toolRegistry.register(createUserShellTool({ getCwd, bus: this.bus }));
         this.toolRegistry.register(createDisplayTool({ getCwd, bus: this.bus }));
         this.toolRegistry.register(createListSkillsTool(getCwd));
+        // conversation_recall — search/expand evicted conversation turns
+        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.",
+            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 };
+            },
+        });
     }
     /**
      * Register named handlers that extensions can advise.
@@ -296,8 +439,17 @@ export class AgentLoop {
      */
     registerHandlers() {
         const h = this.handlers;
+        // System prompt: static identity + behavioral instructions.
+        // Extensions can use registerInstruction() for a managed section,
+        // or advise this handler directly for full control.
+        h.define("system-prompt:build", () => {
+            const instructions = this.getInstructionSections();
+            if (instructions.length === 0)
+                return STATIC_SYSTEM_PROMPT;
+            return STATIC_SYSTEM_PROMPT + "\n\n# Extension Instructions\n\n" + instructions.join("\n\n");
+        });
         // Extensions compose additional context (git info, project rules, etc.)
-        h.define("dynamic-context:build", () => buildDynamicContext(this.toolRegistry.all(), this.contextManager));
+        h.define("dynamic-context:build", () => buildDynamicContext(this.contextManager, this.tokenBudget.shellBudgetTokens));
         // Full control over what the LLM sees: takes messages[], returns messages[].
         // Default: pass through. Extensions can advise to compact, summarize,
         // filter, reorder, inject — whatever strategy fits.
@@ -331,7 +483,7 @@ export class AgentLoop {
                             // write_file
                             newContent = args.content;
                         }
-                        else if (typeof args.old_text === "string" && typeof args.new_text === "string" && oldContent) {
+                        else if (typeof args.old_text === "string" && typeof args.new_text === "string" && oldContent !== null) {
                             // edit_file
                             newContent = oldContent.replace(args.old_text.replace(/\r\n/g, "\n"), args.new_text.replace(/\r\n/g, "\n"));
                         }
@@ -355,10 +507,14 @@ export class AgentLoop {
                     }
                     catch { /* fall back to generic permission */ }
                 }
+                const ui = this.compositor
+                    ? createToolUI(this.bus, this.compositor.surface("agent"))
+                    : undefined;
                 const perm = await this.bus.emitPipeAsync("permission:request", {
                     kind: permKind,
                     title: permTitle,
                     metadata,
+                    ui,
                     decision: { outcome: "approved" },
                 });
                 if (perm.decision.outcome !== "approved") {
@@ -380,7 +536,10 @@ export class AgentLoop {
             const onChunk = (tool.showOutput !== false && !diffShown)
                 ? ctx.onChunk
                 : undefined;
-            const result = await tool.execute(args, onChunk);
+            const toolCtx = this.compositor
+                ? { ui: createToolUI(this.bus, this.compositor.surface("agent")) }
+                : undefined;
+            const result = await tool.execute(args, onChunk, toolCtx);
             // Invalidate read cache when a file is modified
             if (tool.modifiesFiles && typeof args.path === "string" && !result.isError) {
                 const absPath = path.resolve(process.cwd(), args.path);
@@ -408,8 +567,8 @@ export class AgentLoop {
         this.abortController = new AbortController();
         const signal = this.abortController.signal;
         // Each loop iteration adds an abort listener (via OpenAI SDK stream);
-        // raise the limit to avoid spurious warnings on multi-tool queries.
-        setMaxListeners(50, signal);
+        // disable the limit — long-running tool loops can easily exceed any cap.
+        setMaxListeners(0, signal);
         this.bus.emit("agent:query", { query });
         this.bus.emit("agent:processing-start", {});
         let responseText = "";
@@ -441,8 +600,6 @@ export class AgentLoop {
             this.abortController = null;
         }
     }
-    /** Max tokens before auto-compaction (conservative default). */
-    maxContextTokens = 60_000;
     /**
      * Core agent loop: stream LLM response → execute tools → repeat.
      * Returns the final accumulated response text.
@@ -450,22 +607,31 @@ export class AgentLoop {
     async executeLoop(signal) {
         let fullResponseText = "";
         while (!signal.aborted) {
-            // Auto-compact if conversation is getting large
-            const estimatedTokens = Math.ceil(JSON.stringify(this.conversation.getMessages()).length / 4);
-            if (estimatedTokens > this.maxContextTokens) {
-                this.conversation.compact(10);
-                this.bus.emit("ui:info", { message: "(conversation compacted)" });
-            }
-            // System prompt is static (cacheable); dynamic context uses handler
-            // so extensions can compose additional context via advise()
-            const systemPrompt = STATIC_SYSTEM_PROMPT;
+            // Auto-compact when conversation exceeds threshold fraction of budget
+            const budgetTokens = this.tokenBudget.conversationBudgetTokens;
+            const autoCompactThreshold = Math.floor(budgetTokens * getSettings().autoCompactThreshold);
+            if (this.conversation.estimateTokens() > autoCompactThreshold) {
+                const stats = this.conversation.compact(autoCompactThreshold);
+                await this.conversation.flush();
+                if (stats) {
+                    this.bus.emit("ui:info", {
+                        message: `(compacted: ~${stats.before.toLocaleString()} → ~${stats.after.toLocaleString()} tokens)`,
+                    });
+                }
+            }
+            // System prompt uses handler so extensions can append instructions (cacheable);
+            // dynamic context uses handler for per-query state via advise()
+            const systemPrompt = this.handlers.call("system-prompt:build");
             const dynamicContext = this.handlers.call("dynamic-context:build");
             // Stream LLM response with retry
             const result = await this.streamWithRetry(systemPrompt, dynamicContext, signal);
-            const { text, toolCalls, assistantContent, assistantToolCalls } = result;
+            const { text, toolCalls: streamedToolCalls } = result;
+            // Extract tool calls via protocol (API mode uses streamed calls,
+            // inline mode parses XML from text)
+            const toolCalls = this.toolProtocol.extractToolCalls(text, streamedToolCalls);
             fullResponseText += text;
-            // Record the assistant message in conversation
-            this.conversation.addAssistantMessage(assistantContent, assistantToolCalls);
+            // Record the assistant message via protocol
+            this.toolProtocol.recordAssistant(this.conversation, text, toolCalls);
             // No tool calls → agent is done
             if (toolCalls.length === 0)
                 break;
@@ -496,10 +662,28 @@ export class AgentLoop {
             // Execute tool calls — run read-only tools in parallel, permission-
             // requiring tools sequentially (to avoid overlapping permission prompts).
             const batchTotal = toolCalls.length;
+            const collectedResults = [];
             const executeSingle = async (tc, batchIndex) => {
+                // Rewrite meta-tool calls (e.g., use_extension → actual tool)
+                tc = this.toolProtocol.rewriteToolCall(tc);
+                // Check for validation errors from rewrite (e.g., wrong extension params)
+                try {
+                    const maybeError = JSON.parse(tc.argumentsJson);
+                    if (maybeError._error) {
+                        collectedResults.push({
+                            callId: tc.id, toolName: tc.name,
+                            content: maybeError._error, isError: true,
+                        });
+                        return;
+                    }
+                }
+                catch { /* not an error payload, continue */ }
                 const tool = this.toolRegistry.get(tc.name);
                 if (!tool) {
-                    this.conversation.addToolResult(tc.id, `Error: Unknown tool "${tc.name}"`);
+                    collectedResults.push({
+                        callId: tc.id, toolName: tc.name,
+                        content: `Unknown tool "${tc.name}"`, isError: true,
+                    });
                     return;
                 }
                 let args;
@@ -507,7 +691,10 @@ export class AgentLoop {
                     args = JSON.parse(tc.argumentsJson);
                 }
                 catch {
-                    this.conversation.addToolResult(tc.id, `Error: Invalid JSON arguments for ${tc.name}`);
+                    collectedResults.push({
+                        callId: tc.id, toolName: tc.name,
+                        content: `Invalid JSON arguments for ${tc.name}`, isError: true,
+                    });
                     return;
                 }
                 // Execute via handler — extensions can advise to add safe-mode,
@@ -517,11 +704,8 @@ export class AgentLoop {
                 };
                 const result = await this.handlers.call("tool:execute", { name: tc.name, id: tc.id, args, tool, onChunk: defaultOnChunk,
                     batchIndex, batchTotal: batchTotal > 1 ? batchTotal : undefined });
-                // Add tool result to conversation (truncate large outputs to avoid
-                // blowing through the context window on a single tool call)
-                let content = result.isError
-                    ? `Error: ${result.content}`
-                    : result.content;
+                // Truncate large outputs to avoid blowing context
+                let content = result.content;
                 const maxBytes = 16_384; // ~4k tokens
                 if (content.length > maxBytes) {
                     const headBytes = Math.floor(maxBytes * 0.6);
@@ -544,7 +728,10 @@ export class AgentLoop {
                         ...lines.slice(tailStart),
                     ].join("\n");
                 }
-                this.conversation.addToolResult(tc.id, content);
+                collectedResults.push({
+                    callId: tc.id, toolName: tc.name,
+                    content, isError: result.isError,
+                });
             };
             // Partition into parallel-safe (read-only) and sequential (needs permission)
             const parallel = [];
@@ -572,6 +759,8 @@ export class AgentLoop {
                     break;
                 await executeSingle(tc, ++batchIdx);
             }
+            // Record all tool results via protocol
+            this.toolProtocol.recordResults(this.conversation, collectedResults);
             // Loop back — LLM sees tool results
         }
         return fullResponseText;
@@ -591,10 +780,14 @@ export class AgentLoop {
             catch (e) {
                 if (signal.aborted)
                     throw e;
-                // Context overflow — compact and retry (no backoff needed)
+                // Context overflow — aggressively compact and retry
                 if (this.isContextOverflow(e)) {
-                    this.conversation.compact(6);
-                    this.bus.emit("ui:info", { message: "(context overflow — compacted, retrying)" });
+                    // Use 60% of the budget to leave headroom
+                    const aggressiveBudget = Math.floor(this.tokenBudget.conversationBudgetTokens * 0.6);
+                    const stats = this.conversation.compact(aggressiveBudget, 6);
+                    await this.conversation.flush();
+                    const detail = stats ? ` ~${stats.before.toLocaleString()} → ~${stats.after.toLocaleString()} tokens` : "";
+                    this.bus.emit("ui:info", { message: `(context overflow — compacted${detail}, retrying)` });
                     continue;
                 }
                 // Retryable transient error — backoff
@@ -633,9 +826,21 @@ export class AgentLoop {
         ];
         // Let extensions transform the message array (compact, summarize, filter, etc.)
         const messages = this.handlers.call("conversation:prepare", rawMessages);
+        // Tool protocol controls what goes in the API tools param vs dynamic context
+        const apiTools = this.toolProtocol.getApiTools(this.toolRegistry.all());
+        const toolPrompt = this.toolProtocol.getToolPrompt(this.toolRegistry.all());
+        // Append tool catalog to dynamic context (closer to user query = better followed)
+        if (toolPrompt) {
+            const ctxMsg = messages[1]; // dynamic context user message
+            if (ctxMsg && typeof ctxMsg.content === "string") {
+                ctxMsg.content += "\n" + toolPrompt;
+            }
+        }
+        // Stream filter strips tool tags from display (inline mode only)
+        const streamFilter = this.toolProtocol.createStreamFilter(this.toolRegistry.all().map((t) => t.name));
         const stream = await this.llmClient.stream({
             messages,
-            tools: this.toolRegistry.toAPITools(),
+            tools: apiTools,
             model: this.currentModel,
             reasoning_effort: this.shouldSendReasoningEffort() ? this.thinkingLevel : undefined,
             signal,
@@ -643,6 +848,15 @@ export class AgentLoop {
         for await (const chunk of stream) {
             if (signal.aborted)
                 break;
+            // Token usage (may arrive in a chunk with empty choices)
+            if (chunk.usage) {
+                const u = chunk.usage;
+                this.bus.emit("agent:usage", {
+                    prompt_tokens: u.prompt_tokens ?? 0,
+                    completion_tokens: u.completion_tokens ?? 0,
+                    total_tokens: u.total_tokens ?? 0,
+                });
+            }
             const choice = chunk.choices[0];
             if (!choice)
                 continue;
@@ -650,9 +864,15 @@ export class AgentLoop {
             // Text content
             if (delta?.content) {
                 text += delta.content;
-                this.bus.emitTransform("agent:response-chunk", {
-                    blocks: [{ type: "text", text: delta.content }],
-                });
+                // Filter tool tags from display output (inline mode)
+                const displayText = streamFilter
+                    ? streamFilter.feed(delta.content)
+                    : delta.content;
+                if (displayText) {
+                    this.bus.emitTransform("agent:response-chunk", {
+                        blocks: [{ type: "text", text: displayText }],
+                    });
+                }
             }
             // Reasoning/thinking tokens (non-standard, e.g. DeepSeek)
             if (delta?.reasoning_content) {
@@ -677,28 +897,19 @@ export class AgentLoop {
                     }
                 }
             }
-            // Token usage (final chunk from providers that support it)
-            if (chunk.usage) {
-                const u = chunk.usage;
-                this.bus.emit("agent:usage", {
-                    prompt_tokens: u.prompt_tokens ?? 0,
-                    completion_tokens: u.completion_tokens ?? 0,
-                    total_tokens: u.total_tokens ?? 0,
+        }
+        // Flush any buffered content from the stream filter
+        if (streamFilter) {
+            const remaining = streamFilter.flush();
+            if (remaining) {
+                this.bus.emitTransform("agent:response-chunk", {
+                    blocks: [{ type: "text", text: remaining }],
                 });
             }
         }
-        // Build assistant tool calls for conversation recording
-        const assistantToolCalls = pendingToolCalls.length
-            ? pendingToolCalls.map((tc) => ({
-                id: tc.id,
-                function: { name: tc.name, arguments: tc.argumentsJson },
-            }))
-            : undefined;
         return {
             text,
             toolCalls: pendingToolCalls,
-            assistantContent: text || null,
-            assistantToolCalls,
         };
     }
 }

package/dist/agent/conversation-state.d.ts

@@ -1,11 +1,14 @@
 import type { ChatCompletionMessageParam } from "../utils/llm-client.js";
-/**
- * Manages the OpenAI chat messages array for the agent loop.
- * Separate from ContextManager — this is the LLM conversation,
- * not the shell history.
- */
+import { type NuclearEntry } from "./nuclear-form.js";
+import type { HistoryFile } from "./history-file.js";
 export declare class ConversationState {
     private messages;
+    private nuclearEntries;
+    private recallArchive;
+    private historyFile;
+    private nextSeq;
+    constructor(historyFile?: HistoryFile);
+    get instanceId(): string;
     addUserMessage(text: string): void;
     addAssistantMessage(content: string | null, toolCalls?: {
         id: string;
@@ -15,13 +18,42 @@ export declare class ConversationState {
         };
     }[]): void;
     addToolResult(toolCallId: string, content: string): void;
-    /** Inject a system-level note into the conversation (e.g. context change). */
+    /** Add tool results as a user message (for inline tool protocol). */
+    addToolResultInline(content: string): void;
     addSystemNote(text: string): void;
     getMessages(): ChatCompletionMessageParam[];
+    estimateTokens(): number;
     /**
-     * Simple compaction — drop oldest turns, keeping the first user message
-     * (original task context) and the most recent turns.
+     * Priority-based compaction. Evicts lowest-priority turns, replacing
+     * them with nuclear one-liner summaries that stay in the conversation.
+     * Read-only tool results are dropped entirely.
      */
-    compact(maxTurns: number): void;
+    compact(targetTokens: number, recentTurnsToKeep?: number, force?: boolean): {
+        before: number;
+        after: number;
+    } | null;
+    /**
+     * Flush oldest nuclear entries to the history file when the
+     * in-context nuclear block grows too large.
+     */
+    flush(): Promise<void>;
+    /**
+     * Inject prior session history from the history file as a context note.
+     */
+    loadPriorHistory(entries: NuclearEntry[]): void;
+    /** Search Tier 2 archive + Tier 3 history file. */
+    search(query: string): Promise<string>;
+    /** Expand full content of a nuclear entry by seq number. */
+    expand(seq: number): Promise<string>;
+    /** Browse nuclear entries (Tier 2) + recent history (Tier 3). */
+    browse(): Promise<string>;
+    getNuclearEntryCount(): number;
+    getRecallArchiveSize(): number;
     clear(): void;
+    private buildNuclearBlock;
+    private updateNuclearBlockInMessages;
+    private parseTurns;
+    private inferPriority;
+    private searchArchive;
+    private turnToText;
 }