agent-sh 0.10.3 → 0.12.0

package/README.md

@@ -1,16 +1,15 @@
 # agent-sh
 
-An agent that lives in a shell — not a shell that lives in an agent.
+A real shell with an AI agent one keystroke away.
 
 [![npm version](https://img.shields.io/npm/v/agent-sh.svg)](https://www.npmjs.com/package/agent-sh)
 [![license](https://img.shields.io/npm/l/agent-sh.svg)](https://github.com/guanyilun/agent-sh/blob/main/LICENSE)
-[![website](https://img.shields.io/badge/website-agent--sh.dev-blue)](https://agent-sh.dev)
 
 ![demo](assets/demo.gif)
 
-Most AI terminal tools get this backwards: the LLM drives the experience and the shell is bolted on as an afterthought. No real PTY, no job control, no vim, fragile `cd` tracking. The agent is the main character and your terminal is a prop.
+I live in my terminal. A lot of the time I'm not coding — I'm deploying something, poking at a failing `rsync`, figuring out why `docker build` won't start, fixing a one-liner. And very often I need an AI agent to help. Spinning up a full coding agent for this stuff is overkill, and I got tired of copy-pasting errors into a chat window every time.
 
-agent-sh flips this. It's your shell first — full PTY, your rc config, your aliases, everything just works. But type `>` at the start of a line, and you're talking to an agent that has full context of what you've been doing.
+So I built agent-sh. Under the hood it's a normal shell on top of node-pty — your rc config, your aliases, vim and tmux all just work. But at the start of any line, type `>` and you're talking to a small agent that already sees your cwd, your last command, and its output. Nothing to set up, no project to explain.
 
 ```
 ~ $ ls -la                       # real shell command
@@ -20,22 +19,57 @@ agent-sh flips this. It's your shell first — full PTY, your rc config, your al
 ~ $ > draft a commit message     # agent reads your diff and shell history
 ```
 
+I still use Claude Code and pi for serious coding work — this doesn't replace them. But for the quick stuff in the terminal, I reach for agent-sh almost every day now. The built-in agent is lightweight and good enough for most of what I throw at it, and when it isn't, bridge extensions let you plug [Claude Code](examples/extensions/claude-code-bridge/) or [pi](examples/extensions/pi-bridge/) in as the backend.
+
 ## Quick Start
 
+Install the latest from GitHub (recommended — development moves faster than npm releases):
+
+```bash
+npm install -g github:guanyilun/agent-sh
+```
+
+Or the last published npm release:
+
 ```bash
 npm install -g agent-sh
+```
+
+Pick one of the zero-config paths below — no settings file needed. agent-sh auto-activates a built-in provider when it sees a known key.
+
+**Hosted models via OpenRouter** (300+ models, one key):
+
+```bash
+export OPENROUTER_API_KEY=sk-or-...
 agent-sh
 ```
 
-Tip: add an alias to your shell config for quick access:
+**OpenAI:**
 
 ```bash
-alias ash="agent-sh"
+export OPENAI_API_KEY=sk-...
+agent-sh
+```
+
+**Local models** (Ollama, llama.cpp server, LM Studio, vLLM — anything OpenAI-compatible):
+
+```bash
+export OPENAI_API_KEY=ollama                        # any value; dummy is fine
+export OPENAI_BASE_URL=http://localhost:11434/v1    # point at your server
+agent-sh
 ```
 
-Set `OPENAI_API_KEY` in your environment (or configure providers in `~/.agent-sh/settings.json`). Works with any OpenAI-compatible API — see the [Usage Guide](docs/usage.md) for provider examples (OpenAI, Ollama, OpenRouter, Together, Groq, LM Studio, vLLM).
+Once running, switch models at any time with `/model <name>` (tab-completes; selection persists across sessions).
+
+For richer configuration (multiple providers, extensions), run `agent-sh init` to scaffold `~/.agent-sh/settings.json` with copy-pasteable examples. See the [Usage Guide](docs/usage.md) for the full list of supported providers.
+
+Tip — add a shell alias:
+
+```bash
+alias ash="agent-sh"
+```
 
-Requires Node.js 18+.
+Requires Node.js 18+. Currently supports **bash** and **zsh**; other shells (fish, nushell, etc.) are not yet wired up.
 
 ## Key Features
 

package/dist/agent/agent-loop.js

@@ -141,10 +141,33 @@ export class AgentLoop {
         // here in the ctor so late-registered modes aren't dropped.
         onCtor("config:add-modes", ({ modes: extra }) => {
             const providers = new Set(extra.map((m) => m.provider).filter(Boolean));
+            const prev = this.modes[this.currentModeIndex];
+            // Keep the active mode even if the re-registration drops it (persisted
+            // model missing from a refreshed catalog) — otherwise currentModeIndex
+            // slips to modes[0] and the next stream() call uses a different model
+            // mid-turn.
+            const activePreserved = prev &&
+                prev.provider &&
+                providers.has(prev.provider) &&
+                !extra.some((m) => m.model === prev.model && m.provider === prev.provider);
             this.modes = [
-                ...this.modes.filter((m) => !m.provider || !providers.has(m.provider)),
+                ...this.modes.filter((m) => {
+                    if (activePreserved && m === prev)
+                        return true;
+                    return !m.provider || !providers.has(m.provider);
+                }),
                 ...extra,
             ];
+            if (prev) {
+                const newIdx = this.modes.findIndex((m) => m.model === prev.model && m.provider === prev.provider);
+                if (newIdx !== -1)
+                    this.currentModeIndex = newIdx;
+            }
+            if (activePreserved && prev) {
+                this.bus.emit("ui:info", {
+                    message: `${prev.provider}:${prev.model} is not in the refreshed catalog — keeping it active until you /model to another.`,
+                });
+            }
             this.bus.emit("config:changed", {});
         });
         // Fires before wire() too — agent-backend emits this from
@@ -516,8 +539,9 @@ export class AgentLoop {
             const target = baseURL ?? provider ?? "provider";
             return `Could not connect to ${target} (${raw}). Check that the API endpoint is reachable.`;
         }
-        // Auth errors
-        if (status === 401 || raw.toLowerCase().includes("auth")) {
+        // Explicit signals only — bare "auth" hit "author" in echoed API params.
+        if (status === 401 || status === 403 ||
+            /\b(unauthorized|authentication|api[-_ ]?key|invalid[-_ ]?token)\b/i.test(raw)) {
             return `Authentication failed for ${provider ?? "provider"} (model: ${model}). Check your API key.`;
         }
         // Model not found
@@ -619,58 +643,6 @@ export class AgentLoop {
             "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");
-        // ── ask_llm — direct LLM sub-query (from the 24th ash's vision) ──
-        //
-        // The ash can ask the LLM a question directly — not as a tool-output
-        // loop, but as a lightweight sub-query. Use cases: second opinions,
-        // brainstorming, summarizing complex context, getting a fresh
-        // perspective without tool overhead. The 24th ash injected this via
-        // diagnose as a proof-of-concept. The 25th ash made it permanent.
-        this.toolRegistry.register({
-            name: "ask_llm",
-            description: "Send a direct query to the LLM and get a text response. Use for " +
-                "sub-queries, second opinions, brainstorming, or getting a fresh " +
-                "perspective on a problem. Much lighter than a full tool loop — " +
-                "just query in, text out. Optional system prompt sets context.",
-            input_schema: {
-                type: "object",
-                properties: {
-                    query: {
-                        type: "string",
-                        description: "The question or prompt to send to the LLM.",
-                    },
-                    system: {
-                        type: "string",
-                        description: "Optional system prompt to set context for the sub-query.",
-                    },
-                },
-                required: ["query"],
-            },
-            showOutput: true,
-            execute: async (args) => {
-                const messages = [];
-                if (args.system) {
-                    messages.push({ role: "system", content: args.system });
-                }
-                messages.push({ role: "user", content: args.query });
-                try {
-                    const content = await this.llmClient.complete({
-                        messages,
-                        max_tokens: 2000,
-                    });
-                    return { content: content || "(empty response)", exitCode: 0, isError: false };
-                }
-                catch (err) {
-                    const message = err instanceof Error ? err.message : String(err);
-                    return { content: `LLM error: ${message}`, exitCode: 1, isError: true };
-                }
-            },
-            getDisplayInfo: () => ({ kind: "search", icon: "💬" }),
-            formatCall: (args) => {
-                const q = args.query?.slice(0, 60);
-                return `ask_llm: ${q}${args.query?.length > 60 ? "..." : ""}`;
-            },
-        });
     }
     /**
      * Register named handlers that extensions can advise.
@@ -678,6 +650,9 @@ export class AgentLoop {
      */
     registerHandlers() {
         const h = this.handlers;
+        // Advisable so extensions can inject fallback parsers without
+        // subclassing the protocol.
+        h.define("tool-protocol:extract-calls", (args) => this.toolProtocol.extractToolCalls(args.text, args.streamedCalls));
         // System prompt: static identity + behavioral instructions.
         // Extensions can use registerInstruction() for a managed section,
         // or advise this handler directly for full control.
@@ -946,7 +921,16 @@ export class AgentLoop {
             const toolCtx = this.compositor
                 ? { ui: createToolUI(this.bus, this.compositor.surface("agent")) }
                 : undefined;
-            const result = await tool.execute(args, onChunk, toolCtx);
+            // Surface thrown errors as tool results so the agent can self-correct
+            // instead of the throw killing the whole turn.
+            let result;
+            try {
+                result = await tool.execute(args, onChunk, toolCtx);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                result = { content: message, exitCode: 1, isError: true };
+            }
             // 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);
@@ -1065,13 +1049,14 @@ export class AgentLoop {
             // tool_call → tool_result chain some providers require.
             // Stream LLM response with retry
             const result = await this.streamWithRetry(systemPrompt, dynamicContext, signal);
-            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);
+            const { text, toolCalls: streamedToolCalls, extras } = result;
+            const toolCalls = this.handlers.call("tool-protocol:extract-calls", {
+                text,
+                streamedCalls: streamedToolCalls,
+            });
             fullResponseText += text;
             // Record the assistant message via protocol
-            this.toolProtocol.recordAssistant(this.conversation, text, toolCalls);
+            this.toolProtocol.recordAssistant(this.conversation, text, toolCalls, extras);
             this.bus.emit("conversation:message-appended", {
                 role: "assistant",
                 content: text,
@@ -1460,6 +1445,11 @@ export class AgentLoop {
      */
     async streamResponse(systemPrompt, dynamicContext, signal) {
         let text = "";
+        // reasoning_details streams as per-chunk fragments keyed by index;
+        // merge .text per index or the provider rejects the fragmented shape.
+        let reasoningField = null;
+        let reasoning = "";
+        const reasoningDetailsByIndex = new Map();
         const pendingToolCalls = [];
         const rawMessages = [
             { role: "system", content: systemPrompt },
@@ -1481,16 +1471,18 @@ export class AgentLoop {
         }
         // 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({
+        const requestParams = {
             messages,
             tools: apiTools,
             model: this.currentModel,
             reasoning_effort: this.shouldSendReasoningEffort() ? this.thinkingLevel : undefined,
-            signal,
-        });
+        };
+        this.bus.emit("llm:request", requestParams);
+        const stream = await this.llmClient.stream({ ...requestParams, signal });
         for await (const chunk of stream) {
             if (signal.aborted)
                 break;
+            this.bus.emit("llm:chunk", { chunk });
             // Token usage (may arrive in a chunk with empty choices)
             if (chunk.usage) {
                 const u = chunk.usage;
@@ -1522,11 +1514,29 @@ export class AgentLoop {
                     });
                 }
             }
-            // Reasoning/thinking tokens (non-standard, e.g. DeepSeek)
-            if (delta?.reasoning_content) {
-                this.bus.emit("agent:thinking-chunk", {
-                    text: delta.reasoning_content,
-                });
+            const d = delta;
+            for (const name of ["reasoning", "reasoning_content"]) {
+                if (typeof d?.[name] === "string" && d[name].length > 0) {
+                    reasoning += d[name];
+                    reasoningField ??= name;
+                    this.bus.emit("agent:thinking-chunk", { text: d[name] });
+                }
+            }
+            if (Array.isArray(d?.reasoning_details)) {
+                for (const x of d.reasoning_details) {
+                    const idx = typeof x?.index === "number" ? x.index : reasoningDetailsByIndex.size;
+                    const prev = reasoningDetailsByIndex.get(idx);
+                    if (!prev) {
+                        reasoningDetailsByIndex.set(idx, { ...x });
+                    }
+                    else {
+                        if (typeof x.text === "string")
+                            prev.text = (prev.text ?? "") + x.text;
+                        for (const [k, v] of Object.entries(x))
+                            if (k !== "text" && prev[k] === undefined)
+                                prev[k] = v;
+                    }
+                }
             }
             // Tool calls (streamed incrementally)
             if (delta?.tool_calls) {
@@ -1574,9 +1584,17 @@ export class AgentLoop {
                 tc.argumentsJson = "{}";
             }
         }
+        const extras = {};
+        if (reasoning && reasoningField)
+            extras[reasoningField] = reasoning;
+        if (reasoningDetailsByIndex.size > 0) {
+            extras.reasoning_details = [...reasoningDetailsByIndex.entries()]
+                .sort((a, b) => a[0] - b[0]).map(([, v]) => v);
+        }
         return {
             text,
             toolCalls: pendingToolCalls,
+            extras: Object.keys(extras).length > 0 ? extras : undefined,
         };
     }
 }

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

@@ -49,12 +49,19 @@ export declare class ConversationState {
             name: string;
             arguments: string;
         };
-    }[]): void;
+    }[], extras?: Record<string, unknown>): void;
     addToolResult(toolCallId: string, content: string, isError?: boolean): void;
     /** Add tool results as a user message (for inline tool protocol). */
     addToolResultInline(content: string): void;
     addSystemNote(text: string): void;
     getMessages(): ChatCompletionMessageParam[];
+    /**
+     * DeepSeek 400s if any assistant in a thinking-mode conversation is
+     * missing reasoning_content. Cross-alias here (OpenRouter streams as
+     * `reasoning`, DeepSeek input expects `reasoning_content`) and stub
+     * gaps (text-only turns, pre-fix messages) with empty string.
+     */
+    private normalizeReasoningConsistency;
     /**
      * Replace the messages array wholesale — the write side for custom
      * compaction strategies. Invalidates API token baseline since the

package/dist/agent/conversation-state.js

@@ -78,21 +78,21 @@ export class ConversationState {
         this.invalidateMessagesCache();
         this.eagerNucleateUser(text);
     }
-    addAssistantMessage(content, toolCalls) {
+    addAssistantMessage(content, toolCalls, extras) {
+        // extras is opaque provider payload to echo back (reasoning_content,
+        // reasoning_details, etc.). Spread verbatim; shape is the stream
+        // parser's concern.
+        const base = { role: "assistant", content: content ?? (toolCalls?.length ? null : "") };
         if (toolCalls?.length) {
-            this.messages.push({
-                role: "assistant",
-                content: content ?? null,
-                tool_calls: toolCalls.map((tc) => ({
-                    id: tc.id,
-                    type: "function",
-                    function: tc.function,
-                })),
-            });
-        }
-        else {
-            this.messages.push({ role: "assistant", content: content ?? "" });
+            base.tool_calls = toolCalls.map((tc) => ({
+                id: tc.id,
+                type: "function",
+                function: tc.function,
+            }));
         }
+        if (extras)
+            Object.assign(base, extras);
+        this.messages.push(base);
         this.invalidateMessagesCache();
     }
     addToolResult(toolCallId, content, isError = false) {
@@ -111,7 +111,28 @@ export class ConversationState {
         this.invalidateMessagesCache();
     }
     getMessages() {
-        return this.messages;
+        return this.normalizeReasoningConsistency(this.messages);
+    }
+    /**
+     * DeepSeek 400s if any assistant in a thinking-mode conversation is
+     * missing reasoning_content. Cross-alias here (OpenRouter streams as
+     * `reasoning`, DeepSeek input expects `reasoning_content`) and stub
+     * gaps (text-only turns, pre-fix messages) with empty string.
+     */
+    normalizeReasoningConsistency(messages) {
+        const needsNormalize = messages.some((m) => m.role === "assistant" && (m.reasoning !== undefined ||
+            m.reasoning_content !== undefined ||
+            m.reasoning_details !== undefined));
+        if (!needsNormalize)
+            return messages;
+        return messages.map((m) => {
+            if (m.role !== "assistant")
+                return m;
+            const a = m;
+            if (a.reasoning_content !== undefined)
+                return m;
+            return { ...m, reasoning_content: a.reasoning ?? "" };
+        });
     }
     /**
      * Replace the messages array wholesale — the write side for custom

package/dist/agent/subagent.d.ts

@@ -36,10 +36,14 @@ export interface SubagentOptions {
      */
     dynamicContext?: string;
     /**
-     * Per-subagent token budget. When total (prompt+completion) tokens
-     * exceed this, the subagent terminates gracefully on the next
-     * iteration. The parent's daily budget still counts these tokens
-     * via onUsage; this is an additional per-call cap.
+     * Per-subagent completion-token budget. When the cumulative
+     * completion_tokens across iterations exceeds this, the subagent
+     * terminates gracefully on the next iteration. We deliberately don't
+     * count prompt tokens: the full history is resent each iteration, so
+     * prompt-inclusive counting double-charges context and makes a budget
+     * of N exhaust after O(log N) tool calls. Completion tokens measure
+     * the work the subagent actually produces. The parent's daily budget
+     * still sees real prompt+completion via onUsage.
      */
     budgetTokens?: number;
     /**

package/dist/agent/subagent.js

@@ -28,13 +28,13 @@ export async function runSubagent(opts) {
             break;
         }
         // Stream LLM response
-        const { text, toolCalls, assistantContent, assistantToolCalls, usage } = await streamOnce(llmClient, systemPrompt, conversation, apiTools, model, signal, dynamicContext);
+        const { text, toolCalls, assistantContent, assistantToolCalls, extras, usage } = await streamOnce(llmClient, systemPrompt, conversation, apiTools, model, signal, dynamicContext);
         if (usage) {
-            tokensConsumed += usage.total_tokens || 0;
+            tokensConsumed += usage.completion_tokens || 0;
             onUsage?.(usage);
         }
         fullResponseText += text;
-        conversation.addAssistantMessage(assistantContent, assistantToolCalls);
+        conversation.addAssistantMessage(assistantContent, assistantToolCalls, extras);
         // No tool calls → done
         if (toolCalls.length === 0)
             break;
@@ -86,7 +86,7 @@ export async function runSubagent(opts) {
         }
     }
     if (budgetExhausted) {
-        const note = `\n\n[Subagent terminated: token budget (${budgetTokens}) exhausted after ${tokensConsumed} tokens. Returning partial progress.]`;
+        const note = `\n\n[Subagent terminated: completion-token budget (${budgetTokens}) exhausted after ${tokensConsumed} completion tokens. Returning partial progress.]`;
         return fullResponseText + note;
     }
     return fullResponseText;
@@ -94,6 +94,9 @@ export async function runSubagent(opts) {
 /** Stream a single LLM response. */
 async function streamOnce(llmClient, systemPrompt, conversation, apiTools, model, signal, dynamicContext) {
     let text = "";
+    let reasoning = "";
+    let reasoningField = null;
+    const reasoningDetailsByIndex = new Map();
     const pendingToolCalls = [];
     let usage = null;
     const messages = [
@@ -127,6 +130,29 @@ async function streamOnce(llmClient, systemPrompt, conversation, apiTools, model
         if (delta?.content) {
             text += delta.content;
         }
+        const d = delta;
+        for (const name of ["reasoning", "reasoning_content"]) {
+            if (typeof d?.[name] === "string" && d[name].length > 0) {
+                reasoning += d[name];
+                reasoningField ??= name;
+            }
+        }
+        if (Array.isArray(d?.reasoning_details)) {
+            for (const x of d.reasoning_details) {
+                const idx = typeof x?.index === "number" ? x.index : reasoningDetailsByIndex.size;
+                const prev = reasoningDetailsByIndex.get(idx);
+                if (!prev) {
+                    reasoningDetailsByIndex.set(idx, { ...x });
+                }
+                else {
+                    if (typeof x.text === "string")
+                        prev.text = (prev.text ?? "") + x.text;
+                    for (const [k, v] of Object.entries(x))
+                        if (k !== "text" && prev[k] === undefined)
+                            prev[k] = v;
+                }
+            }
+        }
         if (delta?.tool_calls) {
             for (const tc of delta.tool_calls) {
                 const idx = tc.index;
@@ -157,5 +183,19 @@ async function streamOnce(llmClient, systemPrompt, conversation, apiTools, model
     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, usage };
+    const extras = {};
+    if (reasoning && reasoningField)
+        extras[reasoningField] = reasoning;
+    if (reasoningDetailsByIndex.size > 0) {
+        extras.reasoning_details = [...reasoningDetailsByIndex.entries()]
+            .sort((a, b) => a[0] - b[0]).map(([, v]) => v);
+    }
+    return {
+        text,
+        toolCalls: pendingToolCalls,
+        assistantContent: text || null,
+        assistantToolCalls,
+        extras: Object.keys(extras).length > 0 ? extras : undefined,
+        usage,
+    };
 }

package/dist/agent/tool-protocol.d.ts

@@ -39,7 +39,7 @@ export interface ToolProtocol {
     /** Rewrite a tool call before execution (e.g., unwrap meta-tool). */
     rewriteToolCall(tc: PendingToolCall): PendingToolCall;
     /** Record the assistant turn in conversation state. */
-    recordAssistant(conv: ConversationState, text: string, toolCalls: PendingToolCall[]): void;
+    recordAssistant(conv: ConversationState, text: string, toolCalls: PendingToolCall[], extras?: Record<string, unknown>): void;
     /** Record all tool results for a batch as conversation messages. */
     recordResults(conv: ConversationState, results: ToolResult[]): void;
     /** Create a stream filter for stripping tool calls from display. null = pass-through. */
@@ -57,7 +57,7 @@ export declare class ApiToolProtocol implements ToolProtocol {
     getToolPrompt(): string;
     extractToolCalls(_text: string, streamedCalls: PendingToolCall[]): PendingToolCall[];
     rewriteToolCall(tc: PendingToolCall): PendingToolCall;
-    recordAssistant(conv: ConversationState, text: string, toolCalls: PendingToolCall[]): void;
+    recordAssistant(conv: ConversationState, text: string, toolCalls: PendingToolCall[], extras?: Record<string, unknown>): void;
     recordResults(conv: ConversationState, results: ToolResult[]): void;
     createStreamFilter(): null;
 }
@@ -68,7 +68,7 @@ export declare class InlineToolProtocol implements ToolProtocol {
     getToolPrompt(tools: ToolDefinition[]): string;
     rewriteToolCall(tc: PendingToolCall): PendingToolCall;
     extractToolCalls(text: string, _streamedCalls: PendingToolCall[]): PendingToolCall[];
-    recordAssistant(conv: ConversationState, text: string, _toolCalls: PendingToolCall[]): void;
+    recordAssistant(conv: ConversationState, text: string, _toolCalls: PendingToolCall[], extras?: Record<string, unknown>): void;
     recordResults(conv: ConversationState, results: ToolResult[]): void;
     createStreamFilter(_toolNames: string[]): StreamFilter;
 }
@@ -82,7 +82,7 @@ export declare class DeferredToolProtocol implements ToolProtocol {
     getToolPrompt(): string;
     extractToolCalls(_text: string, streamedCalls: PendingToolCall[]): PendingToolCall[];
     rewriteToolCall(tc: PendingToolCall): PendingToolCall;
-    recordAssistant(conv: ConversationState, text: string, toolCalls: PendingToolCall[]): void;
+    recordAssistant(conv: ConversationState, text: string, toolCalls: PendingToolCall[], extras?: Record<string, unknown>): void;
     recordResults(conv: ConversationState, results: ToolResult[]): void;
     createStreamFilter(): null;
 }
@@ -97,7 +97,7 @@ export declare class DeferredLookupProtocol implements ToolProtocol {
     getToolPrompt(): string;
     extractToolCalls(_text: string, streamedCalls: PendingToolCall[]): PendingToolCall[];
     rewriteToolCall(tc: PendingToolCall): PendingToolCall;
-    recordAssistant(conv: ConversationState, text: string, toolCalls: PendingToolCall[]): void;
+    recordAssistant(conv: ConversationState, text: string, toolCalls: PendingToolCall[], extras?: Record<string, unknown>): void;
     recordResults(conv: ConversationState, results: ToolResult[]): void;
     createStreamFilter(): null;
     getProtocolTools(): ToolDefinition[];

package/dist/agent/tool-protocol.js

@@ -22,14 +22,14 @@ export class ApiToolProtocol {
     rewriteToolCall(tc) {
         return tc;
     }
-    recordAssistant(conv, text, toolCalls) {
+    recordAssistant(conv, text, toolCalls, extras) {
         const calls = toolCalls.length
             ? toolCalls.map((tc) => ({
                 id: tc.id,
                 function: { name: tc.name, arguments: tc.argumentsJson },
             }))
             : undefined;
-        conv.addAssistantMessage(text || null, calls);
+        conv.addAssistantMessage(text || null, calls, extras);
     }
     recordResults(conv, results) {
         for (const r of results) {
@@ -97,8 +97,8 @@ export class InlineToolProtocol {
         }
         return calls;
     }
-    recordAssistant(conv, text, _toolCalls) {
-        conv.addAssistantMessage(text || null);
+    recordAssistant(conv, text, _toolCalls, extras) {
+        conv.addAssistantMessage(text || null, undefined, extras);
     }
     recordResults(conv, results) {
         if (results.length === 0)
@@ -351,14 +351,14 @@ export class DeferredToolProtocol {
             return tc; // Let it fail naturally downstream
         }
     }
-    recordAssistant(conv, text, toolCalls) {
+    recordAssistant(conv, text, toolCalls, extras) {
         const calls = toolCalls.length
             ? toolCalls.map((tc) => ({
                 id: tc.id,
                 function: { name: tc.name, arguments: tc.argumentsJson },
             }))
             : undefined;
-        conv.addAssistantMessage(text || null, calls);
+        conv.addAssistantMessage(text || null, calls, extras);
     }
     recordResults(conv, results) {
         for (const r of results) {
@@ -444,14 +444,14 @@ export class DeferredLookupProtocol {
     rewriteToolCall(tc) {
         return tc; // no dispatching needed — load_tool is a real registered tool
     }
-    recordAssistant(conv, text, toolCalls) {
+    recordAssistant(conv, text, toolCalls, extras) {
         const calls = toolCalls.length
             ? toolCalls.map((tc) => ({
                 id: tc.id,
                 function: { name: tc.name, arguments: tc.argumentsJson },
             }))
             : undefined;
-        conv.addAssistantMessage(text || null, calls);
+        conv.addAssistantMessage(text || null, calls, extras);
     }
     recordResults(conv, results) {
         for (const r of results) {

package/dist/core.d.ts

@@ -22,7 +22,7 @@ import type { AgentShellConfig, ExtensionContext } from "./types.js";
 import { HandlerRegistry } from "./utils/handler-registry.js";
 export { EventBus } from "./event-bus.js";
 export type { ShellEvents } from "./event-bus.js";
-export type { AgentShellConfig, ExtensionContext } from "./types.js";
+export type { AgentShellConfig, ExtensionContext, LlmInterface, LlmMessage, LlmSession } from "./types.js";
 export { palette, setPalette, resetPalette } from "./utils/palette.js";
 export type { ColorPalette } from "./utils/palette.js";
 export type { AgentBackend, ToolDefinition } from "./agent/types.js";

package/dist/core.js

@@ -18,6 +18,7 @@
  */
 import { EventBus } from "./event-bus.js";
 import { ContextManager } from "./context-manager.js";
+import { createLlmFacade } from "./utils/llm-facade.js";
 import { setPalette } from "./utils/palette.js";
 import * as streamTransform from "./utils/stream-transform.js";
 import * as settingsMod from "./settings.js";
@@ -161,6 +162,7 @@ export function createCore(config) {
                 bus,
                 contextManager,
                 instanceId,
+                llm: createLlmFacade(handlers),
                 quit: opts.quit,
                 setPalette,
                 createBlockTransform: (o) => streamTransform.createBlockTransform(bus, o),