agent-sh 0.15.5 → 0.15.7

package/dist/utils/floating-panel.js

@@ -637,6 +637,13 @@ export class FloatingPanel {
         this.autocompleteItems = [];
         this.autocompleteIndex = 0;
     }
+    moveAutocomplete(delta) {
+        const n = this.autocompleteItems.length;
+        if (n === 0)
+            return;
+        this.autocompleteIndex = (this.autocompleteIndex + delta + n) % n;
+        this.render();
+    }
     // ── Input handling ──────────────────────────────────────────
     handleIntercept(payload) {
         const consumed = { ...payload, consumed: true };
@@ -746,6 +753,16 @@ export class FloatingPanel {
         }
         if (this.handleScroll(data, false))
             return;
+        if (data === "\x10" || data === "\x0e") {
+            const forward = data === "\x0e";
+            if (this.autocompleteActive) {
+                this.moveAutocomplete(forward ? 1 : -1);
+            }
+            else if (forward ? this.editor.historyForward() : this.editor.historyBack()) {
+                this.render();
+            }
+            return;
+        }
         const actions = this.editor.feed(data);
         for (const action of actions) {
             switch (action.action) {
@@ -760,6 +777,7 @@ export class FloatingPanel {
                     this.editor.pushHistory(query);
                     this.editor.clear();
                     this.clearAutocomplete();
+                    this.userScrolled = false;
                     // Phase change is the submit handler's call — sync slash commands
                     // (e.g. /model, /help) keep the user in input mode.
                     this.handlers.call(`${this.prefix}:submit`, query);
@@ -782,34 +800,18 @@ export class FloatingPanel {
                 case "shift+tab":
                     this.render();
                     break;
-                case "arrow-up": {
-                    if (this.autocompleteActive) {
-                        this.autocompleteIndex = this.autocompleteIndex === 0
-                            ? this.autocompleteItems.length - 1
-                            : this.autocompleteIndex - 1;
-                        this.render();
-                    }
-                    else {
-                        const hist = this.editor.historyBack();
-                        if (hist)
-                            this.render();
-                    }
+                case "arrow-up":
+                    if (this.autocompleteActive)
+                        this.moveAutocomplete(-1);
+                    else
+                        this.scrollUp(1);
                     break;
-                }
-                case "arrow-down": {
-                    if (this.autocompleteActive) {
-                        this.autocompleteIndex = this.autocompleteIndex === this.autocompleteItems.length - 1
-                            ? 0
-                            : this.autocompleteIndex + 1;
-                        this.render();
-                    }
-                    else {
-                        const hist = this.editor.historyForward();
-                        if (hist)
-                            this.render();
-                    }
+                case "arrow-down":
+                    if (this.autocompleteActive)
+                        this.moveAutocomplete(1);
+                    else
+                        this.scrollDown(1);
                     break;
-                }
                 case "changed":
                 case "delete-empty":
                     this.updateAutocomplete();

package/dist/utils/markdown.js

@@ -78,6 +78,34 @@ export function wrapLine(text, maxWidth) {
         lineWidth = 0;
         lastVisibleIdx = -1;
     };
+    const hardBreak = (token) => {
+        let remaining = token;
+        while (remaining.length > 0) {
+            let fitLen = 0, fitWidth = 0;
+            for (const ch of remaining) {
+                const cw = charWidth(ch.codePointAt(0) ?? 0);
+                if (fitWidth + cw > maxWidth - lineWidth)
+                    break;
+                fitWidth += cw;
+                fitLen += ch.length;
+            }
+            if (fitLen === 0) {
+                // Force one char on an empty line so an over-wide char can't loop forever.
+                if (lineWidth > 0) {
+                    commit();
+                    continue;
+                }
+                fitLen = remaining[0]?.length ?? 1;
+            }
+            const chunk = remaining.slice(0, fitLen);
+            remaining = remaining.slice(fitLen);
+            lineTokens.push(chunk);
+            lineWidth += visibleLen(chunk);
+            lastVisibleIdx = lineTokens.length - 1;
+            if (remaining.length > 0)
+                commit();
+        }
+    };
     for (const seg of segments) {
         if (seg.startsWith("\x1b[")) {
             lineTokens.push(seg);
@@ -102,26 +130,7 @@ export function wrapLine(text, maxWidth) {
                 continue; // spaces at wrap points are dropped
             if (lineWidth === 0) {
                 // Token longer than the entire line — hard-break by char width.
-                let remaining = token;
-                while (remaining.length > 0) {
-                    let fitLen = 0, fitWidth = 0;
-                    for (const ch of remaining) {
-                        const cw = charWidth(ch.codePointAt(0) ?? 0);
-                        if (fitWidth + cw > maxWidth)
-                            break;
-                        fitWidth += cw;
-                        fitLen += ch.length;
-                    }
-                    if (fitLen === 0)
-                        fitLen = remaining[0]?.length ?? 1;
-                    const chunk = remaining.slice(0, fitLen);
-                    remaining = remaining.slice(fitLen);
-                    lineTokens.push(chunk);
-                    lineWidth += visibleLen(chunk);
-                    lastVisibleIdx = lineTokens.length - 1;
-                    if (remaining.length > 0)
-                        commit();
-                }
+                hardBreak(token);
                 continue;
             }
             // Rule (a): closing punctuation must not start a line. Allow up to 2
@@ -146,9 +155,14 @@ export function wrapLine(text, maxWidth) {
                 lineTokens.push(t);
                 lineWidth += visibleLen(t);
             }
-            lineTokens.push(token);
-            lineWidth += tokenWidth;
-            lastVisibleIdx = lineTokens.length - 1;
+            if (lineWidth + tokenWidth <= maxWidth) {
+                lineTokens.push(token);
+                lineWidth += tokenWidth;
+                lastVisibleIdx = lineTokens.length - 1;
+            }
+            else {
+                hardBreak(token);
+            }
         }
     }
     if (lineWidth > 0) {
@@ -318,27 +332,25 @@ export class MarkdownRenderer {
     renderLine(line) {
         if (line.trim() === "")
             return "";
-        // Headings
-        const h1 = line.match(/^# (.+)/);
-        if (h1)
-            return `${p.bold}${p.warning}${h1[1]}${p.reset}`;
-        const h2 = line.match(/^## (.+)/);
-        if (h2)
-            return `${p.bold}${p.accent}${h2[1]}${p.reset}`;
-        const h3 = line.match(/^### (.+)/);
-        if (h3)
-            return `${p.bold}${h3[1]}${p.reset}`;
-        const h4 = line.match(/^#{4,} (.+)/);
-        if (h4)
-            return `${p.bold}${h4[1]}${p.reset}`;
-        // Horizontal rule — subtle short separator, not full-width
+        // Headings — H3+ keep the `###` marker; H1/H2 don't
+        const heading = line.match(/^(#{1,6}) (.+)/);
+        if (heading) {
+            const level = heading[1].length;
+            const text = heading[2];
+            if (level === 1)
+                return `${p.bold}${p.underline}${p.mdHeading}${text}${p.reset}`;
+            if (level === 2)
+                return `${p.bold}${p.mdHeading}${text}${p.reset}`;
+            return `${p.bold}${p.mdHeading}${"#".repeat(level)} ${text}${p.reset}`;
+        }
+        // Horizontal rule
         if (/^(-{3,}|_{3,}|\*{3,})\s*$/.test(line)) {
-            return "";
+            return `${p.mdHr}${"─".repeat(Math.min(this.contentWidth, 80))}${p.reset}`;
         }
         // Blockquote
         const bq = line.match(/^>\s?(.*)/);
         if (bq)
-            return `${p.muted}│${p.reset} ${p.dim}${p.italic}${this.renderInline(bq[1] || "")}${p.reset}`;
+            return `${p.mdQuoteBorder}│${p.reset} ${p.mdQuote}${p.italic}${this.renderInline(bq[1] || "")}${p.reset}`;
         // Task list (checkbox items) — must come before generic unordered list
         const task = line.match(/^(\s*)[*\-+]\s+\[([ xX])\]\s+(.*)/);
         if (task) {
@@ -353,21 +365,21 @@ export class MarkdownRenderer {
         const ul = line.match(/^(\s*)[*\-+]\s+(.*)/);
         if (ul) {
             const indent = ul[1] || "";
-            return `${indent}  ${p.accent}*${p.reset} ${this.renderInline(ul[2] || "")}`;
+            return `${indent}  ${p.mdListBullet}-${p.reset} ${this.renderInline(ul[2] || "")}`;
         }
         // Ordered list
         const ol = line.match(/^(\s*)(\d+)[.)]\s+(.*)/);
         if (ol) {
             const indent = ol[1] || "";
-            return `${indent}  ${p.accent}${ol[2]}.${p.reset} ${this.renderInline(ol[3] || "")}`;
+            return `${indent}  ${p.mdListBullet}${ol[2]}.${p.reset} ${this.renderInline(ol[3] || "")}`;
         }
         return this.renderInline(line);
     }
     renderInline(text) {
         // Links first — later subs inject `\x1b[…m` whose `[` would be eaten here.
-        text = text.replace(/\[([^\]]+)\]\(([^)]+)\)/g, `$1 ${p.muted}${p.underline}($2)${p.reset}`);
+        text = text.replace(/\[([^\]]+)\]\(([^)]+)\)/g, `${p.mdLink}${p.underline}$1${p.reset} ${p.mdLinkUrl}($2)${p.reset}`);
         // Inline code
-        text = text.replace(/`([^`]+)`/g, `${p.accent}$1${p.reset}`);
+        text = text.replace(/`([^`]+)`/g, `${p.mdCode}$1${p.reset}`);
         // Bold + italic
         text = text.replace(/\*\*\*(.+?)\*\*\*/g, `${p.bold}${p.italic}$1${p.reset}`);
         // Bold
@@ -377,7 +389,7 @@ export class MarkdownRenderer {
         text = text.replace(/\*(.+?)\*/g, `${p.italic}$1${p.reset}`);
         text = text.replace(/(?<!\w)_(.+?)_(?!\w)/g, `${p.italic}$1${p.reset}`);
         // Strikethrough
-        text = text.replace(/~~(.+?)~~/g, `${p.dim}$1${p.reset}`);
+        text = text.replace(/~~(.+?)~~/g, `${p.strikethrough}$1${p.reset}`);
         return text;
     }
     /**

package/dist/utils/palette.d.ts

@@ -23,7 +23,18 @@ export interface ColorPalette {
     dim: string;
     italic: string;
     underline: string;
+    strikethrough: string;
     reset: string;
+    mdHeading: string;
+    mdLink: string;
+    mdLinkUrl: string;
+    mdCode: string;
+    mdCodeBlock: string;
+    mdCodeBlockBorder: string;
+    mdQuote: string;
+    mdQuoteBorder: string;
+    mdHr: string;
+    mdListBullet: string;
 }
 /** Active palette — import and use directly in components. */
 export declare const palette: ColorPalette;

package/dist/utils/palette.js

@@ -23,7 +23,18 @@ const defaultPalette = {
     dim: "\x1b[2m",
     italic: "\x1b[3m",
     underline: "\x1b[4m",
+    strikethrough: "\x1b[9m",
     reset: "\x1b[0m",
+    mdHeading: "\x1b[38;2;240;198;116m", // #f0c674 gold
+    mdLink: "\x1b[38;2;129;162;190m", // #81a2be blue
+    mdLinkUrl: "\x1b[38;2;102;102;102m", // #666666 dim gray
+    mdCode: "\x1b[38;2;138;190;183m", // #8abeb7 teal
+    mdCodeBlock: "\x1b[38;2;181;189;104m", // #b5bd68 green
+    mdCodeBlockBorder: "\x1b[38;2;128;128;128m", // #808080 gray
+    mdQuote: "\x1b[38;2;128;128;128m", // #808080 gray
+    mdQuoteBorder: "\x1b[38;2;128;128;128m", // #808080 gray
+    mdHr: "\x1b[38;2;128;128;128m", // #808080 gray
+    mdListBullet: "\x1b[38;2;138;190;183m", // #8abeb7 teal
 };
 /** Active palette — import and use directly in components. */
 export const palette = { ...defaultPalette };

package/docs/agent.md

@@ -43,14 +43,16 @@ Compaction is pluggable: the `conversation:compact` handler is advisable, so ext
 
 The system prompt is assembled once per `cwd` and cached (invalidated when the working directory changes), so the prefix is stable for provider-side prompt caching. It includes:
 
-1. **Identity** — "You are an AI coding assistant running inside agent-sh..."
-2. **Tool decision guide** — when to use which built-in tool
-3. **Tool usage guidelines** — read before editing, prefer edit over write, use grep/glob to find files, etc.
-4. **Project conventions** — `CLAUDE.md`/`AGENT.md` walked from cwd to root (cwd-stable; see next section)
-5. **Skills** — discovered project/global skills (cwd-stable)
-6. **Extension instructions** — blocks registered by extensions via `registerInstruction()` (e.g. proactive recall guidance)
-7. **Available tools** — name + description of every registered tool
-8. **Extension-appended content** — extensions can advise `system-prompt:build` to append additional context (instance IDs, memory files, etc.)
+1. **Identity** — "You are ash, an AI coding assistant running inside agent-sh..." (advisable via `system-prompt:identity`)
+2. **Frontend surface** — the active frontend's self-description, placed right after the identity (advisable via `system-prompt:frontend`; omitted when none)
+3. **Static guide** — agent-sh's own code map (paths to `docs/`, `src/`, `examples/extensions/`), generic tool guidance, and the `<query_context>`/`<dynamic_context>` envelope contract
+4. **Global memory** — `~/.agent-sh/AGENTS.md`, if present
+5. **Global skills** — discovered global skills (cwd-stable)
+6. **Project conventions + skills** — `CLAUDE.md`/`AGENT.md` walked from cwd to root, plus discovered project skills (cwd-stable; see next section)
+7. **Extension instructions** — blocks registered by extensions via `registerInstruction()` (e.g. proactive recall guidance)
+8. **Image support** — appended when the active model accepts image input
+
+Built-in tools are not inlined here — they're passed to the provider via the API `tools` parameter. Extensions can advise `system-prompt:build` directly to append further context (instance IDs, memory files, etc.).
 
 Per-turn signals live in two symmetric handlers, both empty by default:
 
@@ -218,7 +220,7 @@ When the LLM requests multiple tool calls in a single response, the agent groups
 
 2. **Parallel execution** — side-effect-free tools (`modifiesFiles` unset) run in parallel via `Promise.all`. Side-effecting tools run sequentially.
 
-3. **Output truncation** — tool results over 16KB (~4K tokens) are head+tail truncated before being added to the conversation, preventing a single tool call from blowing through the context window.
+3. **Output truncation** — tool results over the tool's `maxResultBytes` (default 100KB, ~25K tokens) are head+tail truncated (60/40 split) before being added to the conversation, preventing a single tool call from blowing through the context window.
 
 ### Structured result display
 
@@ -260,7 +262,7 @@ For OpenRouter, the flag is set automatically: model ids matching the built-in p
       "echoReasoningPatterns": ["my-custom-deepseek-fork"],
       "models": [
         { "id": "deepseek/deepseek-v3.2", "echoReasoning": false },
-        { "id": "openai/gpt-5.5",         "reasoning": true }
+        { "id": "z-ai/glm-5.1",           "reasoning": true }
       ]
     }
   }
@@ -367,7 +369,7 @@ Each entry is a `(provider, model)` target — a serializable identity plus capa
 
 ```typescript
 interface Model {
-  id: string;               // model id, e.g. "openai/gpt-5"
+  id: string;               // model id, e.g. "deepseek/deepseek-v4-flash"
   provider: string;         // identity is the (provider, id) pair
   contextWindow?: number;   // per-model override for the auto-compact threshold
   maxTokens?: number;

package/docs/architecture.md

@@ -20,7 +20,7 @@ index.ts — interactive terminal frontend:
   ├── Agent host (always activated via activateAgent(ctx) before built-ins load):
   │     ash backend       — provider resolution, LlmClient, lazy AgentLoop
   │     core tools        — bash/read/write/edit/grep/glob/ls/list_skills registered at activate time
-  │     built-in providers — openrouter, openai, openai-compatible, deepseek (unconditional)
+  │     built-in providers — openrouter, openai, deepseek, ollama, zai-coding-plan, opencode (unconditional); openai-compatible when OPENAI_BASE_URL is set
   │
   ├── Backend registry (owned by core; backends register via `agent:register-backend`):
   │     core.activateBackend() — picks the named/persisted/first backend and calls its start()
@@ -28,7 +28,7 @@ index.ts — interactive terminal frontend:
   ├── Built-in extensions (loaded via declarative manifest, individually disableable):
   │     shell-context     — PTY exchange tracking, cwd advisor, <cwd>/<shell_events> producer
   │     tui-renderer      — markdown rendering, inline diffs, thinking display, spinner
-  │     slash-commands    — /help, /model, /backend, /thinking, /compact, /context, /reload
+  │     slash-commands    — /help, /model, /thinking, /backend, /reload (the ash backend adds /compact, /context)
   │     file-autocomplete — @ file path completion
   │
   ├── Shared utilities:
@@ -36,7 +36,6 @@ index.ts — interactive terminal frontend:
   │     diff-renderer     — syntax-highlighted diffs (split/unified/summary)
   │     box-frame         — bordered TUI panels
   │     tool-display      — width-adaptive tool call rendering + pure spinner
-  │     output-writer     — OutputWriter interface (StdoutWriter, BufferWriter for tests)
   │     stream-transform  — content block transforms for response pipeline
   │
   └── User extensions (opt-in, loaded from -e flag / settings.json / extensions dir):
@@ -147,7 +146,7 @@ agent-sh/
 │   │   ├── types.ts          # AgentBackend, ToolDefinition, ToolResult
 │   │   ├── agent-loop.ts     # ash AgentLoop (constructed lazily in start())
 │   │   ├── llm-client.ts, llm-facade.ts  # ash LLM transport + ctx.agent.llm facade
-│   │   ├── providers/        # openai, openrouter, deepseek, openai-compatible
+│   │   ├── providers/        # openai, openrouter, deepseek, openai-compatible, ollama, zai-coding-plan, opencode
 │   │   ├── token-budget.ts   # Shared constants (RESPONSE_RESERVE, DEFAULT_CONTEXT_WINDOW)
 │   │   ├── tool-registry.ts, tool-protocol.ts
 │   │   ├── live-view.ts       # In-memory messages array + compaction + recall archive
@@ -185,7 +184,6 @@ agent-sh/
 │       ├── solarized-theme.ts   # Theme example
 │       ├── secret-guard.ts      # Secret redaction
 │       ├── latex-images.ts      # LaTeX equation rendering
-│       ├── ollama.ts            # Ollama provider (local + cloud)
 │       ├── claude-code-bridge/  # Claude Code SDK backend
 │       ├── pi-bridge/           # Pi agent backend
 │       ├── ash-mcp-bridge/      # MCP server bridge

package/docs/extensions.md

@@ -468,17 +468,17 @@ Per-request producers (`mode: "per-request"`) only fire under backends that expo
 
 ## Custom Providers
 
-Providers describe the OpenAI-compatible endpoints the `ash` backend can talk to. The built-ins (openrouter, openai, openai-compatible, deepseek) register from `src/agent/providers/`; extensions can register their own — local daemons, hosted gateways, fine-tuned model catalogs — and they show up under `agent-sh auth list` and `/model`.
+Providers describe the OpenAI-compatible endpoints the `ash` backend can talk to. The built-ins (openrouter, openai, openai-compatible, deepseek, ollama, zai-coding-plan, opencode) register from `src/agent/providers/`; extensions can register their own — local daemons, hosted gateways, fine-tuned model catalogs — and they show up under `agent-sh auth list` and `/model`.
 
 ```typescript
 import type { AgentContext } from "agent-sh/types";
 
 export default function activate(ctx: AgentContext): void {
   ctx.agent.providers.register({
-    id: "ollama",
-    baseURL: "http://localhost:11434/v1",
-    defaultModel: "llama3.2",
-    models: ["llama3.2", "qwen2.5-coder"],
+    id: "llama-cpp",
+    baseURL: "http://localhost:8080/v1",
+    defaultModel: "gemma4",
+    models: ["gemma4"],
     noAuth: true,
   });
 }
@@ -549,9 +549,6 @@ These are registered by AgentLoop (constructed when the ash backend's `start()`
 | `conversation:estimate-tokens` | `() → number` | Local chars/4 estimate of the conversation size. |
 | `conversation:estimate-prompt-tokens` | `() → number` | API-grounded estimate (last `prompt_tokens` + local delta since). Used by the auto-compact trigger. |
 | `conversation:inject-note` | `(text) → void` | Inject a `role:"user"` note mid-loop — how extensions deliver async results (subagent output, peer messages) into the next iteration. |
-| `conversation:nucleate-user` / `-agent` / `-tool` | `(msg) → NuclearEntry` | Turn a message into its one-line summary. Advise to extract extra metadata (e.g. `[why: ...]` annotations). |
-| `conversation:format-prior-history` | `(entries) → string` | Render prior-session history into a preamble. Advise for session-grouped output. |
-| `history:append` / `:search` / `:find-by-seq` / `:read-recent` | — | Shell-history-style persistent log at `~/.agent-sh/history`. Advise to add indexing, filtering, or external stores. |
 | `tool:execute` | `(ctx) → ToolResult` | Wrap the full tool lifecycle: permission → execute → emit events. |
 
 **`dynamic-context:build`** — Each advisor appends its own context. Multiple extensions compose independently:
@@ -717,7 +714,7 @@ agent-sh -e ./examples/extensions/latex-images.ts
 
 Input modes change what happens when the user types and presses Enter. Each mode binds a trigger character (typed at the start of an empty line) to a custom `onSubmit` handler. The built-in mode (`>` for agent) is registered this way — it's not special.
 
-The flow: user types trigger → prompt changes to show the mode → user types their input → presses Enter → `onSubmit` fires → your handler emits `agent:submit`. You can optionally include a `modeInstruction` that gets prepended to the user message.
+The flow: user types trigger → prompt changes to show the mode → user types their input → presses Enter → `onSubmit` fires → your handler emits `agent:submit`. To steer the agent for this mode, build your instruction into the `query` string before emitting — `agent:submit` carries only `query` (and optional `images`).
 
 ```typescript
 bus.emit("input-mode:register", {
@@ -728,8 +725,8 @@ bus.emit("input-mode:register", {
   indicator: "🌐",           // status indicator before the icon
   onSubmit(query, bus) {
     bus.emit("agent:submit", {
-      query,                 // what the user typed
-      modeInstruction: "[mode: translate] Translate the following to Spanish.",
+      // prepend the mode instruction to what the user typed
+      query: `[mode: translate] Translate the following to Spanish.\n\n${query}`,
     });
   },
   returnToSelf: true,        // re-enter this mode after agent finishes
@@ -743,7 +740,7 @@ bus.emit("input-mode:register", {
 | `label` | `string` | Shown in the prompt area |
 | `promptIcon` | `string` | Chevron/icon character in the prompt |
 | `indicator` | `string` | Status indicator before the icon |
-| `onSubmit` | `(query, bus) => void` | Called on Enter. Emits `agent:submit` with `query` + optional `modeInstruction` |
+| `onSubmit` | `(query, bus) => void` | Called on Enter. Emits `agent:submit` with `query` (build any mode instruction into the `query` string yourself) |
 | `returnToSelf` | `boolean` | Re-enter this mode after the agent finishes |
 
 Each trigger character can only be claimed by one mode. Slash commands and readline keybindings work in every mode.
@@ -826,7 +823,7 @@ If your extension wants to signal "this session is interactive — read the scre
 Internally, a remote session:
 
 1. **Redirects render streams** — `"agent"`, `"query"`, `"status"` all route to the provided surface
-2. **Keeps the shell interactive** — advises `shell:on-processing-start` and `shell:on-processing-done` to skip pause/unpause
+2. **Keeps the shell interactive** — advises `shell:on-processing-start` and `shell:on-processing-redraw` to skip pause/redraw (it deliberately leaves `shell:on-processing-done` alone so the agent-turn state cleanup always runs)
 3. **Suppresses chrome** — advises `tui:response-border`, `tui:render-user-query`, `tui:render-usage` based on options
 
 Calling `session.close()` removes all advisors and restores all compositor routing in one call.
@@ -860,11 +857,11 @@ session.close();
 
 ## Shell Lifecycle Handlers
 
-The shell's behavior during agent processing is controlled by two advisable handlers. Extensions advise these to change how the shell responds when the agent starts and stops working.
+The shell's behavior during agent processing is controlled by three handlers. Two are advisable; the third runs unconditional cleanup and should not be suppressed.
 
 ### `shell:on-processing-start`
 
-Default: pauses the shell (blocks PTY output and input) while the agent works. This is correct when agent output shares stdout with the terminal.
+Default: pauses the shell (blocks PTY output and input) and acquires the agent-turn mute scope while the agent works. This is correct when agent output shares stdout with the terminal.
 
 ```typescript
 // Skip pause — agent output goes to a separate surface
@@ -874,19 +871,23 @@ ctx.advise("shell:on-processing-start", (next) => {
 });
 ```
 
-### `shell:on-processing-done`
+### `shell:on-processing-redraw`
 
-Default: unpauses the shell, re-enters agent input mode or redraws the shell prompt.
+Default: re-enters agent input mode or redraws the shell prompt. This is the advisable half of "agent finished" — advise it to skip the redraw when your extension already owns the screen.
 
 ```typescript
 // Skip prompt redraw — already handled by the extension
-ctx.advise("shell:on-processing-done", (next) => {
+ctx.advise("shell:on-processing-redraw", (next) => {
   if (mySessionActive) return;  // skip
-  return next();                // default: unpause + redraw
+  return next();                // default: redraw / re-enter input mode
 });
 ```
 
-> **Note:** `createRemoteSession()` advises both of these automatically. You only need to advise them directly if you're building custom lifecycle behavior without using remote sessions.
+### `shell:on-processing-done`
+
+Runs when the agent turn ends: it releases the agent-turn mute scope (unconditional state cleanup) and then calls `shell:on-processing-redraw`. **Don't advise this to return early** — skipping it would strand the mute scope past the end of the turn. Suppress the redraw via `shell:on-processing-redraw` instead.
+
+> **Note:** `createRemoteSession()` advises `shell:on-processing-start` and `shell:on-processing-redraw` automatically. You only need to advise them directly if you're building custom lifecycle behavior without using remote sessions.
 
 ## Rendering Architecture
 

package/docs/library.md

@@ -23,8 +23,9 @@ import { activateAgent } from "agent-sh/agent";
 import { loadBuiltinExtensions } from "agent-sh/extensions";
 
 const core = createCore({
-  apiKey: process.env.OPENAI_API_KEY,
-  model: "gpt-4o",
+  // These are ash-backend config, not kernel config — see note below.
+  provider: "deepseek",                 // built-in provider → DeepSeek endpoint + deepseek-v4-flash default
+  apiKey: process.env.DEEPSEEK_API_KEY,
 });
 
 const ctx = core.extensionContext({ quit: () => process.exit(0) });
@@ -44,6 +45,8 @@ core.bus.emit("agent:submit", { query: "explain this codebase" });
 
 `createCore()` returns a headless kernel — the event bus and handler registry, with no terminal, shell, LLM, or agent attached. `activateAgent(ctx)` attaches the agent surface (tools, LLM client, providers) and registers the built-in `ash` backend; `loadBuiltinExtensions(ctx)` adds the abstract backend registry, slash commands, and file autocomplete. `core:extensions-loaded` triggers provider resolution; `activateBackend()` then starts ash (or whichever backend is configured). Send queries by emitting `agent:submit` and consume responses by listening to bus events.
 
+> **The LLM fields are backend config, not kernel config.** `createCore()` doesn't read `provider`/`apiKey`/`model`/`baseURL` — it stores the config object opaquely and re-exposes it through the `config:get-app-config` handler. The **ash** backend is the only consumer (`src/agent/index.ts`); it resolves the provider, key, and model from those fields. Under a different backend they're inert: `pi` reads `~/.pi/agent/settings.json`, `claude-code` uses its own SDK config — for those you pass `{ backend: "pi" }` (a real kernel field) and configure the model the backend's own way. The `AppConfig` type bundles kernel + agent + shell config into one object for convenience; the kernel only owns the `extensions` and `backend` keys (`CoreConfig`).
+
 Tools run without confirmation by default; to gate them, register tool advisors via `ctx.agent.adviseTool` (see examples/extensions/interactive-prompts.ts).
 
 ## AgentShellCore API
@@ -68,7 +71,7 @@ import { activateAgent } from "agent-sh/agent";
 import { loadBuiltinExtensions } from "agent-sh/extensions";
 import myTheme from "./my-theme";
 
-const core = createCore({ apiKey: "...", model: "gpt-4o" });
+const core = createCore({ provider: "deepseek", apiKey: process.env.DEEPSEEK_API_KEY });
 const ctx = core.extensionContext({ quit: () => process.exit(0) });
 
 activateAgent(ctx);

package/docs/troubleshooting.md

@@ -18,7 +18,7 @@
 
 **Problem**: Tool calls not working (agent responds but doesn't use tools)
 
-**Solution**: Some models have limited or no tool/function calling support. Try a more capable model (e.g., gpt-4o, claude-sonnet-4-6 via OpenRouter).
+**Solution**: Some models have limited or no tool/function calling support. Try a more capable model (e.g., deepseek-v4-flash, or a larger model via OpenRouter).
 
 **Problem**: Garbled output, startup banner overwritten, or messy prompt rendering
 
@@ -54,7 +54,7 @@ Your normal p10k prompt still works — only the "flash cached prompt then redra
 Enable debug mode for detailed protocol logging:
 
 ```bash
-DEBUG=1 agent-sh --api-key "$KEY" --model gpt-4o
+DEBUG=1 DEEPSEEK_API_KEY="$KEY" agent-sh
 ```
 
 ## Getting Help

package/docs/tui-composition.md

@@ -43,9 +43,11 @@ A `RenderSurface` is anything that can accept rendered output:
 
 ```typescript
 interface RenderSurface {
-  write(text: string): void;    // raw — supports \r, escape codes
+  write(text: string): void;     // raw — supports \r, escape codes
   writeLine(line: string): void; // line + newline
   readonly columns: number;      // available width
+  readonly rows: number;         // available height
+  onResize(cb: (cols: number, rows: number) => void): () => void; // subscribe; returns unsubscribe
 }
 ```
 
@@ -71,6 +73,12 @@ const panelSurface: RenderSurface = {
   },
   writeLine(line) { panel.appendLine(line); },
   get columns() { return panel.computeGeometry().contentW; },
+  get rows() { return panel.computeGeometry().contentH; },
+  onResize(cb) {
+    const handler = () => { const g = panel.computeGeometry(); cb(g.contentW, g.contentH); };
+    process.stdout.on("resize", handler);
+    return () => process.stdout.off("resize", handler);
+  },
 };
 ```
 
@@ -94,7 +102,7 @@ interface Compositor {
 | `"query"` | User query display (the bordered input box) |
 | `"status"` | Info messages, errors, suggestions |
 
-The shell frontend (`src/shell/`) sets all three to `StdoutSurface` during `activateShell`. A library or web consumer that doesn't load the shell frontend has no defaults — it must call `compositor.setDefault(...)` itself.
+The shell frontend (`src/shell/`) sets all three to a `surfaceFromTerminal(terminal)` surface (which writes through the host `Terminal`, ultimately stdout) during `activateShell`. A library or web consumer that doesn't load the shell frontend has no defaults — it must call `compositor.setDefault(...)` itself.
 
 ### Redirecting a stream
 
@@ -155,7 +163,7 @@ export default function activate(ctx: ExtensionContext): void {
     bus.emit("agent:submit", { query });
   });
 
-  panel.handlers.advise("panel:dismiss", (next) => {
+  panel.handlers.advise("panel:hide", (next) => {
     next();
     restoreAgent?.(); restoreAgent = null;
     restoreQuery?.(); restoreQuery = null;