agent-sh 0.11.0 → 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,9 +19,17 @@ 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 and launch:
+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
@@ -62,7 +69,7 @@ Tip — add a shell alias:
 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
@@ -626,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.
@@ -894,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);
@@ -1013,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,
@@ -1408,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 },
@@ -1429,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;
@@ -1470,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) {
@@ -1522,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/event-bus.d.ts

@@ -65,6 +65,15 @@ export interface ShellEvents {
         completion_tokens: number;
         total_tokens: number;
     };
+    "llm:request": {
+        messages: unknown[];
+        tools?: unknown;
+        model?: string;
+        reasoning_effort?: string;
+    };
+    "llm:chunk": {
+        chunk: unknown;
+    };
     "agent:processing-start": Record<string, never>;
     "agent:processing-done": Record<string, never>;
     "agent:cancelled": Record<string, never>;

package/dist/extensions/agent-backend.js

@@ -67,24 +67,6 @@ export default function agentBackend(ctx) {
         compositor: ctx.compositor,
         instanceId: ctx.instanceId,
     });
-    bus.emit("agent:register-backend", {
-        name: "ash",
-        kill: () => agentLoop.kill(),
-        start: async () => {
-            if (!resolved) {
-                bus.emit("ui:error", { message: "Agent backend not started — no LLM provider available. See earlier messages." });
-                return;
-            }
-            agentLoop.wire();
-            bus.emit("agent:info", {
-                name: "ash",
-                version: PACKAGE_VERSION,
-                model: llmClient.model,
-                provider: modes[initialModeIndex]?.provider,
-                contextWindow: modes[initialModeIndex]?.contextWindow,
-            });
-        },
-    });
     bus.on("core:extensions-loaded", () => {
         const settings = getSettings();
         // If the user didn't pick a default, fall back to the first registered
@@ -99,22 +81,49 @@ export default function agentBackend(ctx) {
         const effectiveApiKey = config.apiKey ?? activeProvider?.apiKey;
         const effectiveBaseURL = config.baseURL ?? activeProvider?.baseURL;
         const effectiveModel = config.model ?? persistedModelFor(providerName) ?? activeProvider?.defaultModel;
-        if (!effectiveApiKey) {
-            bus.emit("ui:error", { message: "No LLM provider configured. Export OPENROUTER_API_KEY or OPENAI_API_KEY (built-in providers auto-activate), pass --api-key, or run `agent-sh init` for a settings.json template." });
-            return;
-        }
-        if (!effectiveModel) {
-            bus.emit("ui:error", { message: "No model specified. Use --model or configure a provider with defaultModel in ~/.agent-sh/settings.json" });
+        // No provider → don't register ash at all, so another backend (e.g.
+        // claude-code-bridge) can own activation. index.ts hard-fails only
+        // when no backend ended up registered.
+        if (!effectiveApiKey || !effectiveModel)
             return;
-        }
         modes = buildModes();
         if (modes.length === 0)
             modes = [{ model: effectiveModel }];
-        initialModeIndex = Math.max(0, modes.findIndex((m) => m.model === effectiveModel && (!activeProvider || m.provider === activeProvider.id)));
+        let foundIdx = modes.findIndex((m) => m.model === effectiveModel && (!activeProvider || m.provider === activeProvider.id));
+        // Persisted default may not be in the provider's curated list yet (e.g.
+        // openrouter's async catalog fetch hasn't returned). Prepend a stub so
+        // the initial config:set-modes activeIndex points at the real model —
+        // otherwise AgentLoop reconfigures llmClient back to modes[0].
+        if (foundIdx === -1 && activeProvider) {
+            modes = [
+                {
+                    model: effectiveModel,
+                    provider: activeProvider.id,
+                    providerConfig: { apiKey: effectiveApiKey, baseURL: effectiveBaseURL },
+                    supportsReasoningEffort: activeProvider.supportsReasoningEffort,
+                },
+                ...modes,
+            ];
+            foundIdx = 0;
+        }
+        initialModeIndex = Math.max(0, foundIdx);
         llmClient.reconfigure({ apiKey: effectiveApiKey, baseURL: effectiveBaseURL, model: effectiveModel });
         bus.emit("config:set-modes", { modes, activeIndex: initialModeIndex });
         resolved = true;
-        // start() emits agent:info after wiring.
+        bus.emit("agent:register-backend", {
+            name: "ash",
+            kill: () => agentLoop.kill(),
+            start: async () => {
+                agentLoop.wire();
+                bus.emit("agent:info", {
+                    name: "ash",
+                    version: PACKAGE_VERSION,
+                    model: llmClient.model,
+                    provider: modes[initialModeIndex]?.provider,
+                    contextWindow: modes[initialModeIndex]?.contextWindow,
+                });
+            },
+        });
     });
     bus.on("provider:register", (p) => {
         const rawModels = p.models ?? (p.defaultModel ? [p.defaultModel] : []);

package/dist/extensions/openrouter.js

@@ -1,10 +1,5 @@
 const BASE_URL = "https://openrouter.ai/api/v1";
-// First entry is the cold-start default — kept cheap so trial users don't
-// get a surprise bill. Persisted /model selection overrides this.
-const DEFAULT_MODELS = [
-    "deepseek/deepseek-v3.2",
-    "anthropic/claude-sonnet-4.6",
-];
+const DEFAULT_MODELS = ["anthropic/claude-sonnet-4.6"];
 export default function activate(ctx) {
     const apiKey = process.env.OPENROUTER_API_KEY;
     if (!apiKey)

package/dist/extensions/tui-renderer.js

@@ -50,6 +50,7 @@ function createRenderState() {
         spinnerStartTime: 0,
         openTool: null,
         pendingToolCompletes: new Map(),
+        orphanContHeaderKind: undefined,
         currentToolKind: undefined,
         toolStartTime: 0,
         toolExitCode: null,
@@ -178,11 +179,8 @@ export default function activate(ctx) {
                 stopCurrentSpinner();
                 if (!s.renderer)
                     startAgentResponse();
-                s.renderer.writeLine(`${p.dim}Thinking (ctrl+t to collapse)${p.reset}`);
-                drain();
             }
             else {
-                // Restart spinner with ctrl+t hint now that we know thinking is available
                 startThinkingSpinner();
             }
         }
@@ -256,6 +254,7 @@ export default function activate(ctx) {
             return;
         fencedTransform.flush();
         finalizeToolGroup();
+        s.orphanContHeaderKind = undefined;
         batchGroups = new Map();
         for (const group of e.groups) {
             batchGroups.set(group.kind, {
@@ -272,6 +271,7 @@ export default function activate(ctx) {
         stopCurrentSpinner();
         s.currentToolKind = e.kind;
         s.toolStartTime = Date.now();
+        s.orphanContHeaderKind = undefined;
         if (e.title === "user_shell") {
             finalizeToolGroup();
             closeToolLine();
@@ -315,10 +315,12 @@ export default function activate(ctx) {
                 showToolCall(e.title, "", { ...e, groupContinuation: true });
                 s.toolGroupRendered++;
             }
-            // Record identity so late completes (after a premature finalize
-            // from a cross-kind standalone start) can render as labeled ⎿ lines.
             if (e.toolCallId) {
-                s.pendingToolCompletes.set(e.toolCallId, { title: e.title });
+                s.pendingToolCompletes.set(e.toolCallId, {
+                    title: e.title,
+                    kind,
+                    displayDetail: e.displayDetail ?? extractDetail(e),
+                });
             }
         }
         else {
@@ -342,13 +344,25 @@ export default function activate(ctx) {
                 s.pendingToolCompletes.delete(e.toolCallId);
             s.toolGroupCompletedCount++;
             s.currentToolKind = undefined;
+            // Finalize as soon as all members return so aggregate lands right
+            // after its children, not below out-of-band renders from the next tool.
+            const batchGroup = batchGroups.get(s.toolGroupKind);
+            if (batchGroup && s.toolGroupCompletedCount >= batchGroup.total) {
+                finalizeToolGroup();
+            }
         }
         else {
-            // Route by callId — tools that lost the inline slot get a labeled ⎿ line.
+            // Tools that lost the inline slot render as a labeled ⎿. Orphans
+            // (group finalized before they returned) reroute via showOrphanedComplete.
             const pending = e.toolCallId ? s.pendingToolCompletes.get(e.toolCallId) : undefined;
             if (pending)
                 s.pendingToolCompletes.delete(e.toolCallId);
-            showToolComplete(e.exitCode, e.resultDisplay, pending?.title);
+            if (pending?.orphaned) {
+                showOrphanedComplete(e.exitCode, e.resultDisplay, pending.title, pending.kind, pending.displayDetail);
+            }
+            else {
+                showToolComplete(e.exitCode, e.resultDisplay, pending?.displayDetail ?? pending?.title);
+            }
             s.currentToolKind = undefined;
             s.spinnerStartTime = 0;
             startThinkingSpinner();
@@ -746,8 +760,14 @@ export default function activate(ctx) {
             }
             else {
                 out().write(`  ${batchPrefix}${lines[lines.length - 1]}`);
-                if (extra?.toolCallId)
-                    s.openTool = { callId: extra.toolCallId, title };
+                if (extra?.toolCallId) {
+                    s.openTool = {
+                        callId: extra.toolCallId,
+                        title,
+                        kind: extra.kind,
+                        displayDetail: extra.displayDetail ?? extractDetail(extra),
+                    };
+                }
             }
         }
         s.hadToolCalls = true;
@@ -775,6 +795,26 @@ export default function activate(ctx) {
         if (resultDisplay?.body)
             renderResultBody(resultDisplay.body);
     }
+    /** Late completion from a finalized group — re-emit the kind header
+     *  in muted "(cont.)" form so the ⎿ has a legitimate parent, then
+     *  render the completion as a normal labeled ⎿. Subsequent orphans
+     *  of the same kind reuse the existing (cont.) header. */
+    function showOrphanedComplete(exitCode, resultDisplay, title, kind, displayDetail) {
+        if (s.orphanContHeaderKind !== kind) {
+            stopCurrentSpinner();
+            closeToolLine();
+            flushCommandOutput();
+            if (!s.renderer)
+                startAgentResponse();
+            showCollapsedThinking();
+            const icon = (kind && KIND_ICONS[kind]) ?? "▶";
+            const label = kind ?? "tool";
+            s.renderer.writeLine(`${p.muted}${icon} ${label} (cont.)${p.reset}`);
+            drain();
+            s.orphanContHeaderKind = kind;
+        }
+        showToolComplete(exitCode, resultDisplay, displayDetail || title);
+    }
     function renderResultBody(body) {
         if (!s.renderer)
             return;
@@ -796,10 +836,7 @@ export default function activate(ctx) {
         stopCurrentSpinner();
         const thinking = hasThinkingMode();
         s.spinnerLabel = thinking ? "Thinking" : "Working";
-        const hint = thinking
-            ? (s.showThinkingText ? "(ctrl+t to collapse)" : "(ctrl+t to expand)")
-            : "";
-        s.spinnerOpts = { hint: hint || undefined, startTime: s.spinnerStartTime };
+        s.spinnerOpts = { startTime: s.spinnerStartTime };
         s.spinner = createSpinner({ startTime: s.spinnerStartTime });
         s.spinnerInterval = setInterval(() => {
             if (s.spinner) {
@@ -825,13 +862,25 @@ export default function activate(ctx) {
         if (s.openTool) {
             out().write("\n");
             // Stash identity so the completion renders as ⎿ labeled, not orphan ✓.
-            s.pendingToolCompletes.set(s.openTool.callId, { title: s.openTool.title });
+            s.pendingToolCompletes.set(s.openTool.callId, {
+                title: s.openTool.title,
+                kind: s.openTool.kind,
+                displayDetail: s.openTool.displayDetail,
+            });
             s.openTool = null;
         }
     }
     /** Render the group aggregate ⎿ line, or skip if no members have
      *  completed yet (late completes will render individually as ⎿ labeled). */
     function finalizeToolGroup() {
+        // Late completes from this group have lost their inline slot; mark
+        // them so showOrphanedComplete re-emits a (cont.) header for their ⎿.
+        if (s.toolGroupKind) {
+            for (const pending of s.pendingToolCompletes.values()) {
+                if (pending.kind === s.toolGroupKind)
+                    pending.orphaned = true;
+            }
+        }
         const skipAggregate = s.toolGroupCount > 1 && s.toolGroupCompletedCount === 0;
         if (s.toolGroupCount <= 1 || skipAggregate) {
             s.toolGroupKind = undefined;
@@ -842,6 +891,7 @@ export default function activate(ctx) {
             s.toolGroupSummaries = [];
             return;
         }
+        stopCurrentSpinner();
         closeToolLine();
         if (!s.renderer)
             startAgentResponse();
@@ -938,14 +988,10 @@ export default function activate(ctx) {
         if (s.spinner) {
             stopCurrentSpinner();
             if (s.showThinkingText) {
-                // Expanding: replace spinner with thinking text header
                 if (!s.renderer)
                     startAgentResponse();
-                s.renderer.writeLine(`${p.dim}Thinking (ctrl+t to collapse)${p.reset}`);
-                drain();
             }
             else {
-                // Collapsing: restart spinner with updated hint
                 startThinkingSpinner();
             }
             return;

package/dist/index.js

@@ -270,6 +270,16 @@ async function main() {
     // ── Activate agent backend ────────────────────────────────────
     // Extensions had their chance to register via agent:register-backend.
     // If none did, the built-in AgentLoop gets wired to bus events.
+    const { names: backendNames } = core.bus.emitPipe("config:get-backends", { names: [], active: null });
+    if (backendNames.length === 0) {
+        shell.kill();
+        console.error("\nagent-sh: no agent backend available.\n\n" +
+            "  Export OPENROUTER_API_KEY or OPENAI_API_KEY for zero-config launch, or\n" +
+            "  pass --api-key on the command line, or\n" +
+            "  run `agent-sh init` for a settings.json template.\n" +
+            "  Alternatively, install a bridge extension (claude-code-bridge, pi-bridge).\n");
+        process.exit(1);
+    }
     core.activateBackend();
     // ── Startup banner ───────────────────────────────────────────
     const settings = getSettings();

package/dist/shell/input-handler.js

@@ -253,6 +253,36 @@ export class InputHandler {
                             seq += data[i];
                         }
                     }
+                    else if (next === "]" || next === "P" || next === "_" || next === "^") {
+                        // String sequences terminated by BEL or ST (ESC \):
+                        //   OSC (ESC ]) — OSC 10/11 color-query responses
+                        //   DCS (ESC P) — tmux XTVERSION query response (iTerm2 etc.)
+                        //   APC (ESC _), PM (ESC ^) — rarer, same termination
+                        // Forward as a unit so the payload doesn't leak into lineBuffer
+                        // and onto the bash command line after a foreground app exits.
+                        let j = i + 2;
+                        let termEnd = -1;
+                        while (j < data.length) {
+                            const c = data[j];
+                            if (c === "\x07") {
+                                termEnd = j;
+                                break;
+                            }
+                            if (c === "\x1b" && j + 1 < data.length && data[j + 1] === "\\") {
+                                termEnd = j + 1;
+                                break;
+                            }
+                            j++;
+                        }
+                        if (termEnd !== -1) {
+                            seq = data.slice(i, termEnd + 1);
+                            i = termEnd;
+                        }
+                        else {
+                            seq += next;
+                            i++;
+                        }
+                    }
                     else {
                         // ESC + single char (alt-key, etc.)
                         seq += next;

package/examples/extensions/wire-log.ts

@@ -0,0 +1,35 @@
+/**
+ * Dumps every LLM request + streamed chunk to $AGENT_SH_WIRE_DIR
+ * (default ~/.agent-sh/wire) for offline replay via curl. Paired files
+ * per turn: <stamp>.request.json and <stamp>.chunks.jsonl.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import type { ExtensionContext } from "agent-sh/types";
+
+export default function activate(ctx: ExtensionContext): void {
+  const dir = process.env.AGENT_SH_WIRE_DIR
+    ?? path.join(os.homedir(), ".agent-sh", "wire");
+  fs.mkdirSync(dir, { recursive: true });
+
+  // llm:chunk has no back-pointer to its request, so anchor both on
+  // the timestamp set when llm:request fires.
+  let currentStamp: string | null = null;
+
+  ctx.bus.on("llm:request", (req) => {
+    currentStamp = new Date().toISOString().replace(/[:.]/g, "-");
+    fs.writeFileSync(
+      path.join(dir, `${currentStamp}.request.json`),
+      JSON.stringify(req, null, 2),
+    );
+  });
+
+  ctx.bus.on("llm:chunk", ({ chunk }) => {
+    if (!currentStamp) return;
+    fs.appendFileSync(
+      path.join(dir, `${currentStamp}.chunks.jsonl`),
+      JSON.stringify(chunk) + "\n",
+    );
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sh",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "A shell-first terminal where AI is one keystroke away",
   "type": "module",
   "main": "dist/core.js",
@@ -95,7 +95,7 @@
     "dev": "tsx src/index.ts",
     "build": "tsc",
     "start": "node dist/index.js",
-    "prepublishOnly": "npm run build"
+    "prepare": "npm run build"
   },
   "keywords": [
     "terminal",