agent-sh 0.10.3 → 0.11.0

package/README.md

@@ -22,18 +22,45 @@ agent-sh flips this. It's your shell first — full PTY, your rc config, your al
 
 ## Quick Start
 
+Install and launch:
+
 ```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
 ```
 
-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).
+**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
+```
+
+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+.
 

package/dist/agent/agent-loop.js

@@ -619,58 +619,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.

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),

package/dist/event-bus.d.ts

@@ -275,7 +275,9 @@ export interface ShellEvents {
         id: string;
         apiKey?: string;
         baseURL?: string;
-        defaultModel: string;
+        /** Optional — providers for custom endpoints may not know the catalog
+         *  at registration time. Falls back to models[0] when absent. */
+        defaultModel?: string;
         models?: (string | {
             id: string;
             reasoning?: boolean;

package/dist/extensions/agent-backend.js

@@ -42,6 +42,12 @@ export default function agentBackend(ctx) {
     // wire the loop until we've resolved, so users never hit that path.
     const llmClient = new LlmClient({ apiKey: "not-configured", model: "not-configured" });
     ctx.define("llm:get-client", () => llmClient);
+    ctx.define("llm:invoke", (messages, opts) => {
+        return llmClient.complete({
+            messages: messages,
+            max_tokens: opts?.maxTokens,
+        });
+    });
     let modes = [];
     let initialModeIndex = 0;
     let resolved = false;
@@ -81,7 +87,10 @@ export default function agentBackend(ctx) {
     });
     bus.on("core:extensions-loaded", () => {
         const settings = getSettings();
-        const providerName = config.provider ?? settings.defaultProvider;
+        // If the user didn't pick a default, fall back to the first registered
+        // provider (built-in load order biases to openrouter → openai).
+        const providerName = config.provider ?? settings.defaultProvider
+            ?? (providerRegistry.size > 0 ? providerRegistry.keys().next().value : undefined);
         const activeProvider = providerName ? providerRegistry.get(providerName) ?? null : null;
         // User's persisted defaultModel wins over the provider's declared
         // default. Dynamic providers (openrouter) re-register with their
@@ -91,7 +100,7 @@ export default function agentBackend(ctx) {
         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. Set --api-key, configure a provider in ~/.agent-sh/settings.json, or load a provider extension (e.g. openrouter) that sets OPENROUTER_API_KEY." });
+            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) {

package/dist/extensions/index.d.ts

@@ -9,11 +9,13 @@ import type { ExtensionContext } from "../types.js";
 type ActivateFn = (ctx: ExtensionContext) => void;
 export declare const BUILTIN_EXTENSIONS: Array<{
     name: string;
+    when?: () => boolean;
     load: () => Promise<ActivateFn>;
 }>;
 /**
- * Load built-in extensions sequentially, skipping any in the disabled list.
- * Returns the names of extensions that were loaded.
+ * Load built-in extensions sequentially, skipping any in the disabled list
+ * or whose `when` predicate returns false. Returns the names of extensions
+ * that were loaded.
  */
 export declare function loadBuiltinExtensions(ctx: ExtensionContext, disabled?: string[]): Promise<string[]>;
 export {};

package/dist/extensions/index.js

@@ -1,13 +1,19 @@
 export const BUILTIN_EXTENSIONS = [
     { name: "agent-backend", load: () => import("./agent-backend.js").then(m => m.default) },
+    { name: "openrouter",
+        when: () => !!process.env.OPENROUTER_API_KEY,
+        load: () => import("./openrouter.js").then(m => m.default) },
+    { name: "openai",
+        when: () => !!process.env.OPENAI_API_KEY,
+        load: () => import("./openai.js").then(m => m.default) },
     { name: "tui-renderer", load: () => import("./tui-renderer.js").then(m => m.default) },
     { name: "slash-commands", load: () => import("./slash-commands.js").then(m => m.default) },
     { name: "file-autocomplete", load: () => import("./file-autocomplete.js").then(m => m.default) },
-    { name: "command-suggest", load: () => import("./command-suggest.js").then(m => m.default) },
 ];
 /**
- * Load built-in extensions sequentially, skipping any in the disabled list.
- * Returns the names of extensions that were loaded.
+ * Load built-in extensions sequentially, skipping any in the disabled list
+ * or whose `when` predicate returns false. Returns the names of extensions
+ * that were loaded.
  */
 export async function loadBuiltinExtensions(ctx, disabled = []) {
     const disabledSet = new Set(disabled);
@@ -15,6 +21,8 @@ export async function loadBuiltinExtensions(ctx, disabled = []) {
     for (const ext of BUILTIN_EXTENSIONS) {
         if (disabledSet.has(ext.name))
             continue;
+        if (ext.when && !ext.when())
+            continue;
         const activate = await ext.load();
         activate(ctx);
         loaded.push(ext.name);

package/dist/extensions/openai.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Built-in OpenAI-compatible provider — auto-activates when OPENAI_API_KEY
+ * is set. OPENAI_BASE_URL redirects to local servers (Ollama, LM Studio,
+ * vLLM, llama.cpp) which then get their catalog via /models.
+ */
+import type { ExtensionContext } from "../types.js";
+export default function activate(ctx: ExtensionContext): void;

package/dist/extensions/openai.js

@@ -0,0 +1,46 @@
+const DEFAULT_MODELS = [
+    "gpt-5",
+    "gpt-4.1",
+    "gpt-4o",
+    "gpt-4o-mini",
+    "o3",
+    "o3-mini",
+];
+export default function activate(ctx) {
+    const apiKey = process.env.OPENAI_API_KEY;
+    if (!apiKey)
+        return;
+    const baseURL = process.env.OPENAI_BASE_URL;
+    const id = baseURL ? "openai-compatible" : "openai";
+    if (!baseURL) {
+        ctx.bus.emit("provider:register", {
+            id,
+            apiKey,
+            defaultModel: DEFAULT_MODELS[0],
+            models: DEFAULT_MODELS,
+        });
+        return;
+    }
+    // Register empty immediately so the provider resolves; refill from /models.
+    ctx.bus.emit("provider:register", { id, apiKey, baseURL, models: [] });
+    fetchModels(baseURL, apiKey).then((models) => {
+        if (models.length === 0)
+            return;
+        ctx.bus.emit("provider:register", {
+            id,
+            apiKey,
+            baseURL,
+            defaultModel: models[0],
+            models,
+        });
+    }).catch(() => { });
+}
+async function fetchModels(baseURL, apiKey) {
+    const res = await fetch(`${baseURL.replace(/\/$/, "")}/models`, {
+        headers: { Authorization: `Bearer ${apiKey}` },
+    });
+    if (!res.ok)
+        return [];
+    const data = await res.json();
+    return (data.data ?? []).map((m) => m.id);
+}

package/dist/extensions/openrouter.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Built-in OpenRouter provider — auto-activates when OPENROUTER_API_KEY is set.
+ * Registers curated defaults synchronously so the first query works, then
+ * fetches the full catalog to populate /model autocomplete.
+ */
+import type { ExtensionContext } from "../types.js";
+export default function activate(ctx: ExtensionContext): void;

package/dist/extensions/openrouter.js

@@ -0,0 +1,44 @@
+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",
+];
+export default function activate(ctx) {
+    const apiKey = process.env.OPENROUTER_API_KEY;
+    if (!apiKey)
+        return;
+    ctx.bus.emit("provider:register", {
+        id: "openrouter",
+        apiKey,
+        baseURL: BASE_URL,
+        defaultModel: DEFAULT_MODELS[0],
+        models: DEFAULT_MODELS,
+    });
+    fetchModels(apiKey).then((models) => {
+        if (models.length === 0)
+            return;
+        ctx.bus.emit("provider:register", {
+            id: "openrouter",
+            apiKey,
+            baseURL: BASE_URL,
+            defaultModel: DEFAULT_MODELS[0],
+            supportsReasoningEffort: true,
+            models: models.map((m) => ({
+                id: m.id,
+                reasoning: m.supported_parameters?.includes("reasoning") ?? false,
+                contextWindow: m.context_length,
+            })),
+        });
+    }).catch(() => { });
+}
+async function fetchModels(apiKey) {
+    const res = await fetch(`${BASE_URL}/models`, {
+        headers: { Authorization: `Bearer ${apiKey}` },
+    });
+    if (!res.ok)
+        return [];
+    const data = await res.json();
+    return data.data ?? [];
+}

package/dist/index.js

@@ -8,6 +8,7 @@ import { loadBuiltinExtensions } from "./extensions/index.js";
 import { loadExtensions } from "./extension-loader.js";
 import { getSettings } from "./settings.js";
 import { discoverSkills } from "./agent/skills.js";
+import { runInit } from "./init.js";
 /**
  * Capture the user's full shell environment.
  * This picks up env vars exported in .zshrc/.bashrc that the
@@ -105,6 +106,7 @@ function parseArgs(argv) {
             console.log(`agent-sh — a shell-first terminal where AI is one keystroke away
 
 Usage: agent-sh [options]
+       agent-sh init [--force]    Scaffold ~/.agent-sh/ (settings, examples, AGENTS.md)
 
 Provider Profiles:
   --provider <name>   Use a provider from ~/.agent-sh/settings.json
@@ -145,13 +147,19 @@ Inside the shell:
     return { shell, model, extensions, apiKey, baseURL, provider };
 }
 async function main() {
+    // Subcommands — handled before the shell-launch path.
+    const rawArgs = process.argv.slice(2);
+    if (rawArgs[0] === "init") {
+        runInit({ force: rawArgs.includes("--force") });
+        return;
+    }
     if (process.env.AGENT_SH) {
         console.error("agent-sh: already running inside an agent-sh session (nested sessions are not supported).");
         process.exit(1);
     }
     process.on("SIGTTOU", () => { });
     process.on("SIGTTIN", () => { });
-    const config = parseArgs(process.argv.slice(2));
+    const config = parseArgs(rawArgs);
     // Capture user's full shell environment
     const baseEnv = {};
     for (const [k, v] of Object.entries(process.env)) {
@@ -270,6 +278,7 @@ async function main() {
         const bannerW = Math.min(termW, 60);
         const productName = `${p.accent}${p.bold}agent-sh${p.reset}`;
         const info = agentInfo;
+        const backendReady = !!info?.model;
         const backendName = info?.name ?? "ash";
         const model = info?.model;
         const provider = info?.provider;
@@ -277,7 +286,7 @@ async function main() {
             ? provider ? `${model} [${provider}]` : model
             : null;
         let sections = "";
-        sections += `\n\n  ${p.muted}Backend:${p.reset} ${p.dim}${backendName}${p.reset}`;
+        sections += `\n\n  ${p.muted}Backend:${p.reset} ${p.dim}${backendName}${backendReady ? "" : " (not configured)"}${p.reset}`;
         if (modelValue) {
             sections += `\n  ${p.muted}Model:${p.reset} ${p.dim}${modelValue}${p.reset}`;
         }
@@ -300,7 +309,9 @@ async function main() {
                 sections += `\n    ${p.dim}${item}${p.reset}`;
             }
         }
-        const hint = `${p.muted}Type ${p.warning}>${p.muted} to ask AI · ${p.warning}>/help${p.muted} for commands${p.reset}`;
+        const hint = backendReady
+            ? `${p.muted}Type ${p.warning}>${p.muted} to ask AI · ${p.warning}>/help${p.muted} for commands${p.reset}`
+            : `${p.muted}Set ${p.warning}OPENROUTER_API_KEY${p.muted} or ${p.warning}OPENAI_API_KEY${p.muted} and restart to enable AI${p.reset}`;
         const borderLine = `${p.muted}${"─".repeat(bannerW)}${p.reset}`;
         process.stdout.write("\n" + borderLine + "\n" +
             "  " + productName +

package/dist/init.d.ts

@@ -0,0 +1,3 @@
+export declare function runInit(opts: {
+    force: boolean;
+}): void;

package/dist/init.js

@@ -0,0 +1,72 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+const CONFIG_DIR = path.join(os.homedir(), ".agent-sh");
+const EXTENSIONS_DIR = path.join(CONFIG_DIR, "extensions");
+const SETTINGS_PATH = path.join(CONFIG_DIR, "settings.json");
+const EXAMPLE_PATH = path.join(CONFIG_DIR, "settings.example.json");
+const AGENTS_PATH = path.join(CONFIG_DIR, "AGENTS.md");
+// Shape-discoverable stub — all fields present, none filled in.
+const STARTER_SETTINGS = {
+    defaultProvider: null,
+    providers: {},
+    extensions: [],
+    disabledBuiltins: [],
+    disabledExtensions: [],
+};
+// Not loaded at runtime — users copy blocks from here into settings.json.
+const EXAMPLE_SETTINGS = {
+    defaultProvider: "openrouter",
+    providers: {
+        openrouter: {
+            apiKey: "$OPENROUTER_API_KEY",
+            baseURL: "https://openrouter.ai/api/v1",
+            defaultModel: "anthropic/claude-sonnet-4.6",
+        },
+        openai: {
+            apiKey: "$OPENAI_API_KEY",
+            defaultModel: "gpt-5",
+        },
+        anthropic: {
+            apiKey: "$ANTHROPIC_API_KEY",
+            baseURL: "https://api.anthropic.com/v1",
+            defaultModel: "claude-sonnet-4-5",
+        },
+        ollama: {
+            apiKey: "ollama",
+            baseURL: "http://localhost:11434/v1",
+            defaultModel: "llama3.3",
+        },
+    },
+    extensions: [
+        "./examples/extensions/openrouter.ts",
+    ],
+    disabledBuiltins: [],
+    disabledExtensions: [],
+};
+function writeIfMissing(filePath, content, force) {
+    if (!force && fs.existsSync(filePath))
+        return "kept";
+    fs.writeFileSync(filePath, content);
+    return "written";
+}
+export function runInit(opts) {
+    fs.mkdirSync(EXTENSIONS_DIR, { recursive: true });
+    const settingsResult = writeIfMissing(SETTINGS_PATH, JSON.stringify(STARTER_SETTINGS, null, 2) + "\n", opts.force);
+    // Always refreshed — reference material, not user state.
+    fs.writeFileSync(EXAMPLE_PATH, JSON.stringify(EXAMPLE_SETTINGS, null, 2) + "\n");
+    console.log(`agent-sh initialized at ${CONFIG_DIR}`);
+    console.log();
+    console.log(`  settings.json         ${settingsResult}${opts.force ? "" : settingsResult === "kept" ? " (exists — pass --force to overwrite)" : ""}`);
+    console.log(`  settings.example.json refreshed`);
+    console.log(`  extensions/           ready`);
+    console.log();
+    console.log("Next steps:");
+    console.log(`  1. Open ${SETTINGS_PATH}`);
+    console.log(`  2. Copy a provider block from settings.example.json into \`providers\` and set \`defaultProvider\`.`);
+    console.log(`  3. Export the referenced env var (e.g. \`export OPENROUTER_API_KEY=...\`).`);
+    console.log(`  4. Run \`agent-sh\`.`);
+    console.log();
+    console.log(`Optional: create ${AGENTS_PATH} with standing instructions`);
+    console.log(`(code style, commands to avoid, etc.) to load them into every session.`);
+}

package/dist/shell/shell.d.ts

@@ -34,11 +34,8 @@ export declare class Shell implements InputContext {
     isAgentActive(): boolean;
     writeToPty(data: string): void;
     /**
-     * Lightweight redraw: ask the shell to redraw its own prompt via a hidden
-     * ZLE widget (zsh) bound to \e[9999~. The shell knows how to draw its
-     * prompt correctly — we don't try to replay captured bytes.
-     *
-     * For bash, falls back to sending \n for a fresh prompt cycle.
+     * Ask the shell to redraw its own prompt in place via \e[9999~, which both
+     * zsh (ZLE widget) and bash (readline redraw-current-line) bind to repaint.
      */
     redrawPrompt(): void;
     /**

package/dist/shell/shell.js

@@ -87,7 +87,15 @@ export class Shell {
                 `[ -f "${userHome}/.bashrc" ] && source "${userHome}/.bashrc"`,
                 "",
                 "# agent-sh hooks (invisible OSC sequences for cwd + prompt detection)",
-                `PROMPT_COMMAND="\${PROMPT_COMMAND:+\$PROMPT_COMMAND;}__agent_sh_preexec_ran=0; ${osc7Cmd}; ${promptMarker}${showIndicator ? `; ${titleCmd}` : ""}"`,
+                "# Wrapped in a function because inlining printf \"...\" into",
+                "# PROMPT_COMMAND=\"...\" breaks the outer quoting.",
+                "__agent_sh_precmd() {",
+                `  ${osc7Cmd}`,
+                `  ${promptMarker}`,
+                ...(showIndicator ? [`  ${titleCmd}`] : []),
+                "  __agent_sh_preexec_ran=0",
+                "}",
+                `PROMPT_COMMAND="\${PROMPT_COMMAND:+\$PROMPT_COMMAND;}__agent_sh_precmd"`,
                 "",
                 "# Preexec hook via DEBUG trap: emit actual command text so agent-sh",
                 "# can track history-recalled and tab-completed commands accurately",
@@ -104,6 +112,12 @@ export class Shell {
                 "",
                 "# End-of-prompt marker: append to PS1 (\\[...\\] marks it zero-width)",
                 'case "$PS1" in *9998*) ;; *) PS1="${PS1}\\[\\e]9998;READY\\a\\]";; esac',
+                "",
+                "# Mirrors the zsh \\e[9999~ reset-prompt widget — used by agent-sh",
+                "# to repaint the prompt in place. All keymaps so `set -o vi` works.",
+                `bind -m emacs '"\\e[9999~":redraw-current-line' 2>/dev/null`,
+                `bind -m vi-insert '"\\e[9999~":redraw-current-line' 2>/dev/null`,
+                `bind -m vi-command '"\\e[9999~":redraw-current-line' 2>/dev/null`,
             ];
             fs.writeFileSync(path.join(this.tmpDir, ".bashrc"), bashrcLines.join("\n") + "\n");
             shellArgs = ["--rcfile", path.join(this.tmpDir, ".bashrc")];
@@ -190,16 +204,12 @@ export class Shell {
         this.ptyProcess.write(data);
     }
     /**
-     * Lightweight redraw: ask the shell to redraw its own prompt via a hidden
-     * ZLE widget (zsh) bound to \e[9999~. The shell knows how to draw its
-     * prompt correctly — we don't try to replay captured bytes.
-     *
-     * For bash, falls back to sending \n for a fresh prompt cycle.
+     * Ask the shell to redraw its own prompt in place via \e[9999~, which both
+     * zsh (ZLE widget) and bash (readline redraw-current-line) bind to repaint.
      */
     redrawPrompt() {
-        // A stale echoSkip or paused flag (left over from handleProcessingDone
-        // re-entering a mode) would swallow the redrawn prompt and make the
-        // terminal appear frozen. Reset both before emitting.
+        // Stale echoSkip/paused from handleProcessingDone re-entering a mode
+        // would swallow the redraw and freeze the terminal visually.
         this.echoSkip = false;
         this.paused = false;
         const result = this.bus.emitPipe("shell:redraw-prompt", {
@@ -207,14 +217,7 @@ export class Shell {
             handled: false,
         });
         if (!result.handled) {
-            if (this.isZsh) {
-                // Trigger the hidden ZLE widget — zle reset-prompt redraws cleanly
-                this.ptyProcess.write("\x1b[9999~");
-            }
-            else {
-                // Bash: no zle reset-prompt equivalent, use fresh prompt cycle
-                this.ptyProcess.write("\n");
-            }
+            this.ptyProcess.write("\x1b[9999~");
         }
     }
     /**

package/dist/types.d.ts

@@ -49,6 +49,31 @@ export interface AgentMode {
     /** Provider supports the reasoning_effort parameter. */
     supportsReasoningEffort?: boolean;
 }
+/**
+ * Backend-agnostic LLM interface exposed via `ctx.llm`. Backends fulfill it
+ * by defining an `llm:invoke` handler; those without an LLM leave
+ * `available` false and calls reject.
+ */
+export interface LlmMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+export interface LlmSession {
+    send(message: string): Promise<string>;
+    history(): ReadonlyArray<LlmMessage>;
+}
+export interface LlmInterface {
+    readonly available: boolean;
+    ask(opts: {
+        query: string;
+        system?: string;
+        maxTokens?: number;
+    }): Promise<string>;
+    session(opts?: {
+        system?: string;
+        maxTokens?: number;
+    }): LlmSession;
+}
 export interface AgentShellConfig {
     shell?: string;
     model?: string;
@@ -102,6 +127,7 @@ export interface ExtensionContext {
     registerSkill: (name: string, description: string, filePath: string) => void;
     /** Remove a registered skill by name. */
     removeSkill: (name: string) => void;
+    llm: LlmInterface;
     /** Register a named handler. */
     define: (name: string, fn: (...args: any[]) => any) => void;
     /** Wrap a named handler. Receives `next` (original) + args. Returns an unadvise function. */

package/dist/utils/llm-facade.d.ts

@@ -0,0 +1,7 @@
+/**
+ * ctx.llm facade — delegates to an `llm:invoke` handler registered by the
+ * active backend. No handler → `available` is false and calls reject.
+ */
+import type { HandlerRegistry } from "./handler-registry.js";
+import type { LlmInterface } from "../types.js";
+export declare function createLlmFacade(handlers: HandlerRegistry): LlmInterface;

package/dist/utils/llm-facade.js

@@ -0,0 +1,33 @@
+export function createLlmFacade(handlers) {
+    const invoke = (messages, maxTokens) => {
+        const result = handlers.call("llm:invoke", messages, { maxTokens });
+        if (result === undefined)
+            return Promise.reject(new Error("ctx.llm: no LLM backend available"));
+        return result;
+    };
+    return {
+        get available() { return handlers.list().includes("llm:invoke"); },
+        ask: ({ query, system, maxTokens }) => {
+            const messages = [];
+            if (system)
+                messages.push({ role: "system", content: system });
+            messages.push({ role: "user", content: query });
+            return invoke(messages, maxTokens);
+        },
+        session: (opts = {}) => {
+            const messages = [];
+            if (opts.system)
+                messages.push({ role: "system", content: opts.system });
+            const session = {
+                async send(message) {
+                    messages.push({ role: "user", content: message });
+                    const reply = await invoke(messages, opts.maxTokens);
+                    messages.push({ role: "assistant", content: reply });
+                    return reply;
+                },
+                history: () => messages.slice(),
+            };
+            return session;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sh",
-  "version": "0.10.3",
+  "version": "0.11.0",
   "description": "A shell-first terminal where AI is one keystroke away",
   "type": "module",
   "main": "dist/core.js",

package/dist/extensions/command-suggest.d.ts

@@ -1,10 +0,0 @@
-/**
- * Command suggestion extension (fast-path LLM feature).
- *
- * After a shell command fails (non-zero exit), uses LlmClient.complete()
- * to suggest a fix. Shows the suggestion below the prompt.
- *
- * Only active when an LLM client is available (registered by agent-backend).
- */
-import type { ExtensionContext } from "../types.js";
-export default function activate({ bus, call }: ExtensionContext): void;

package/dist/extensions/command-suggest.js

@@ -1,42 +0,0 @@
-export default function activate({ bus, call }) {
-    let suggesting = false;
-    bus.on("shell:command-done", ({ command, output, exitCode, cwd }) => {
-        if (exitCode === null || exitCode === 0)
-            return;
-        if (!command.trim())
-            return;
-        if (suggesting)
-            return; // don't stack suggestions
-        const llmClient = call("llm:get-client");
-        if (!llmClient)
-            return;
-        suggesting = true;
-        // Truncate output to avoid blowing up the prompt
-        const truncated = output.length > 1000
-            ? output.slice(-1000)
-            : output;
-        llmClient.complete({
-            messages: [
-                {
-                    role: "system",
-                    content: "You are a shell assistant. The user's command failed. " +
-                        "Suggest a fix as a single command. Just the command, no explanation, no backticks, no prefix. " +
-                        "If you can't suggest anything useful, reply with an empty string.",
-                },
-                {
-                    role: "user",
-                    content: `cwd: ${cwd}\n$ ${command}\n${truncated}\nexit code: ${exitCode}`,
-                },
-            ],
-            max_tokens: 150,
-        }).then((suggestion) => {
-            suggesting = false;
-            const trimmed = suggestion.trim().replace(/^`+|`+$/g, ""); // strip backticks
-            if (trimmed && trimmed.length < 500) {
-                bus.emit("ui:suggestion", { text: trimmed });
-            }
-        }).catch(() => {
-            suggesting = false;
-        });
-    });
-}