agent-sh 0.10.2 → 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

@@ -97,7 +97,8 @@ export class AgentLoop {
         // Shell-history-shaped log. Default writes go through the advisable
         // `history:append` handler registered below; extensions swap the
         // backend without touching this wiring.
-        this.historyFile = new HistoryFile({ instanceId: this.instanceId });
+        const filePath = process.env.AGENT_SH_HISTORY_FILE || getSettings().historyFilePath;
+        this.historyFile = new HistoryFile({ instanceId: this.instanceId, filePath });
         this.conversation = new ConversationState(this.handlers, this.instanceId);
         // Fall back to a single-mode placeholder if the caller passed an
         // empty array (agent-backend does this pre-resolution).
@@ -618,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/agent/history-file.d.ts

@@ -2,6 +2,7 @@ import { type NuclearEntry } from "./nuclear-form.js";
 export declare class HistoryFile {
     readonly instanceId: string;
     private filePath;
+    private lockPath;
     constructor(opts?: {
         filePath?: string;
         instanceId?: string;

package/dist/agent/history-file.js

@@ -12,14 +12,21 @@ import * as crypto from "node:crypto";
 import { CONFIG_DIR, getSettings } from "../settings.js";
 import { serializeEntry, deserializeEntry, formatNuclearLine, isReadOnly, } from "./nuclear-form.js";
 const HISTORY_PATH = path.join(CONFIG_DIR, "history");
-const LOCK_PATH = HISTORY_PATH + ".lock";
 const LOCK_STALE_MS = 10_000; // consider lock stale after 10s
 export class HistoryFile {
     instanceId;
     filePath;
+    lockPath;
     constructor(opts) {
         this.filePath = opts?.filePath ?? HISTORY_PATH;
+        this.lockPath = this.filePath + ".lock";
         this.instanceId = opts?.instanceId ?? crypto.randomBytes(2).toString("hex");
+        // Custom paths may target a dir that doesn't exist yet; create sync so
+        // the first append() can't race with the mkdir.
+        try {
+            fss.mkdirSync(path.dirname(this.filePath), { recursive: true });
+        }
+        catch { /* ignore */ }
     }
     /**
      * Append entries atomically. Uses O_APPEND for concurrency safety.
@@ -218,16 +225,16 @@ export class HistoryFile {
         try {
             // Check for stale lock
             try {
-                const stat = await fs.stat(LOCK_PATH);
+                const stat = await fs.stat(this.lockPath);
                 if (Date.now() - stat.mtimeMs > LOCK_STALE_MS) {
-                    await fs.unlink(LOCK_PATH).catch(() => { });
+                    await fs.unlink(this.lockPath).catch(() => { });
                 }
             }
             catch {
                 // Lock doesn't exist — good
             }
             // O_EXCL ensures atomicity
-            const fd = await fs.open(LOCK_PATH, fss.constants.O_CREAT | fss.constants.O_EXCL | fss.constants.O_WRONLY);
+            const fd = await fs.open(this.lockPath, fss.constants.O_CREAT | fss.constants.O_EXCL | fss.constants.O_WRONLY);
             await fd.close();
             return true;
         }
@@ -236,6 +243,6 @@ export class HistoryFile {
         }
     }
     async releaseLock() {
-        await fs.unlink(LOCK_PATH).catch(() => { });
+        await fs.unlink(this.lockPath).catch(() => { });
     }
 }

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/settings.d.ts

@@ -42,6 +42,13 @@ export interface Settings {
     historyMaxBytes?: number;
     /** Number of prior history entries to load on startup (default: 50). */
     historyStartupEntries?: number;
+    /**
+     * Override the history file path. Defaults to `~/.agent-sh/history`.
+     * The `AGENT_SH_HISTORY_FILE` env var takes precedence over this setting.
+     * Use a per-project path to keep sessions isolated (e.g. embedding apps
+     * that boot agent-sh as a library against a specific working tree).
+     */
+    historyFilePath?: string;
     /** Auto-compact threshold as fraction of conversation budget (0-1, default 0.5). */
     autoCompactThreshold?: number;
     /** Max command output lines shown inline in TUI. */

package/dist/settings.js

@@ -21,6 +21,7 @@ const DEFAULTS = {
     shellTailLines: 10,
     historyMaxBytes: 104857600, // 100MB — history is only accessed via search/expand, never loaded wholesale
     historyStartupEntries: 100,
+    historyFilePath: undefined,
     autoCompactThreshold: 0.5,
     maxCommandOutputLines: 3,
     readOutputMaxLines: 10,

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/ansi.d.ts

@@ -7,20 +7,29 @@ export declare const GRAY = "\u001B[90m";
 export declare const BOLD = "\u001B[1m";
 export declare const RESET = "\u001B[0m";
 /**
- * Check if a Unicode code point is a wide character (CJK, fullwidth, emoji, etc.)
- * Returns 2 for wide chars, 1 for normal chars, 0 for combining chars.
+ * Width of a single Unicode code point in terminal columns.
  *
- * Based on East Asian Width and Unicode categories.
+ * For correct rendering of emoji clusters (ZWJ, flags, skin-tone, VS16)
+ * prefer `clusterWidth` or `visibleLen`, which segment graphemes first.
+ * This code-point-level primitive is kept for callers that iterate over
+ * chars for wrap-detection purposes (e.g. CJK line-break rules).
  */
 export declare function charWidth(codePoint: number): number;
+/**
+ * Width of one grapheme cluster in terminal columns. Handles ZWJ sequences,
+ * regional-indicator flags, skin-tone modifiers, and VS16 emoji presentation.
+ */
+export declare function clusterWidth(cluster: string): number;
 /**
  * Measure visible string length in terminal columns.
- * Excludes SGR (color/style) sequences and accounts for CJK double-width chars.
+ * Excludes SGR (color/style) sequences, and counts each grapheme cluster
+ * (emoji, CJK, combining marks) as one terminal-visible unit.
  */
 export declare function visibleLen(str: string): number;
 /**
  * Truncate a string to fit within `maxWidth` visible columns.
- * Accounts for CJK double-width characters. Appends `…` if truncated.
+ * Iterates by grapheme cluster so emoji sequences (ZWJ, flags, VS16) are
+ * kept intact rather than split mid-cluster. Appends `…` if truncated.
  */
 export declare function truncateToWidth(str: string, maxWidth: number): string;
 /** Truncate to visible width while preserving SGR sequences — use when
@@ -28,8 +37,10 @@ export declare function truncateToWidth(str: string, maxWidth: number): string;
 export declare function truncateAnsiToWidth(str: string, maxWidth: number): string;
 /**
  * Pad a string with spaces to fill `targetWidth` visible columns.
- * Accounts for CJK double-width characters.
  */
 export declare function padEndToWidth(str: string, targetWidth: number): string;
-/** Strip all ANSI escape sequences (SGR, OSC, CSI, private mode) and carriage returns. */
+/** Strip ANSI escape sequences and carriage returns.
+ *  Delegates escape handling to the `strip-ansi` package (covers SGR, OSC,
+ *  CSI, private-mode, 8-bit CSI, and newer variants). `\r` is not an escape
+ *  but callers rely on it being stripped alongside. */
 export declare function stripAnsi(str: string): string;

package/dist/utils/ansi.js

@@ -1,3 +1,5 @@
+import stringWidth from "string-width";
+import stripAnsiPkg from "strip-ansi";
 // ── ANSI escape code constants ────────────────────────────────
 export const CYAN = "\x1b[36m";
 export const DIM = "\x1b[2m";
@@ -8,160 +10,65 @@ export const GRAY = "\x1b[90m";
 export const BOLD = "\x1b[1m";
 export const RESET = "\x1b[0m";
 // ── ANSI utility functions ───────────────────────────────────
+// Reused across iterations. Segmenter construction is not free, and the API
+// is pure (no per-call state) so a module-level instance is safe.
+const GRAPHEME_SEGMENTER = new Intl.Segmenter(undefined, { granularity: "grapheme" });
 /**
- * Check if a Unicode code point is a wide character (CJK, fullwidth, emoji, etc.)
- * Returns 2 for wide chars, 1 for normal chars, 0 for combining chars.
+ * Width of a single Unicode code point in terminal columns.
  *
- * Based on East Asian Width and Unicode categories.
+ * For correct rendering of emoji clusters (ZWJ, flags, skin-tone, VS16)
+ * prefer `clusterWidth` or `visibleLen`, which segment graphemes first.
+ * This code-point-level primitive is kept for callers that iterate over
+ * chars for wrap-detection purposes (e.g. CJK line-break rules).
  */
 export function charWidth(codePoint) {
-    // Combining characters (zero width)
-    if (codePoint >= 0x0300 && codePoint <= 0x036f)
-        return 0; // Combining Diacritical Marks
-    if (codePoint >= 0x1ab0 && codePoint <= 0x1aff)
-        return 0; // Combining Diacritical Marks Extended
-    if (codePoint >= 0x1dc0 && codePoint <= 0x1dff)
-        return 0; // Combining Diacritical Marks Supplement
-    if (codePoint >= 0x20d0 && codePoint <= 0x20ff)
-        return 0; // Combining Diacritical Marks for Symbols
-    if (codePoint >= 0xfe20 && codePoint <= 0xfe2f)
-        return 0; // Combining Half Marks
-    if (codePoint >= 0xfe00 && codePoint <= 0xfe0f)
-        return 0; // Variation Selectors
-    if (codePoint >= 0xe0100 && codePoint <= 0xe01ef)
-        return 0; // Variation Selectors Supplement
-    // Emoji and symbols that render as wide (2 columns)
-    // Emoji presentation sequences and keycap
-    if (codePoint === 0x20e3)
-        return 2; // Combining Enclosing Keycap
-    // Emoji blocks
-    if (codePoint >= 0x1f600 && codePoint <= 0x1f64f)
-        return 2; // Emoticons
-    if (codePoint >= 0x1f300 && codePoint <= 0x1f5ff)
-        return 2; // Misc Symbols and Pictographs
-    if (codePoint >= 0x1f680 && codePoint <= 0x1f6ff)
-        return 2; // Transport and Map
-    if (codePoint >= 0x1f700 && codePoint <= 0x1f77f)
-        return 2; // Alchemical Symbols
-    if (codePoint >= 0x1f780 && codePoint <= 0x1f7ff)
-        return 2; // Geometric Shapes Extended
-    if (codePoint >= 0x1f800 && codePoint <= 0x1f8ff)
-        return 2; // Supplemental Arrows-C
-    if (codePoint >= 0x1f900 && codePoint <= 0x1f9ff)
-        return 2; // Supplemental Symbols and Pictographs
-    if (codePoint >= 0x1fa00 && codePoint <= 0x1faff)
-        return 2; // Chess Symbols, Symbols and Pictographs Extended-A
-    // NOTE: 0x2300-0x23ff (Misc Technical), 0x2600-0x26ff (Misc Symbols),
-    // and 0x2700-0x27bf (Dingbats) are mostly "Ambiguous" width — render as
-    // 1 column in non-CJK terminal locales (e.g. ❯, ⌘, ★, ♦). But a handful
-    // of dingbats have Emoji_Presentation=Yes and render as 2 cols everywhere.
-    if (codePoint === 0x2705 || // ✅ white heavy check mark
-        codePoint === 0x270a || // ✊ raised fist
-        codePoint === 0x270b || // ✋ raised hand
-        codePoint === 0x2728 || // ✨ sparkles
-        codePoint === 0x274c || // ❌ cross mark
-        codePoint === 0x274e || // ❎ negative squared cross mark
-        (codePoint >= 0x2753 && codePoint <= 0x2755) || // ❓❔❕
-        codePoint === 0x2757 || // ❗ heavy exclamation mark
-        (codePoint >= 0x2795 && codePoint <= 0x2797) || // ➕➖➗
-        codePoint === 0x27b0 || // ➰ curly loop
-        codePoint === 0x27bf // ➿ double curly loop
-    )
-        return 2;
-    // Regional indicator symbols (flag emoji components)
-    if (codePoint >= 0x1f1e6 && codePoint <= 0x1f1ff)
-        return 2;
-    // CJK Unified Ideographs
-    if (codePoint >= 0x4e00 && codePoint <= 0x9fff)
-        return 2;
-    // CJK Unified Ideographs Extension A
-    if (codePoint >= 0x3400 && codePoint <= 0x4dbf)
-        return 2;
-    // Hangul Syllables
-    if (codePoint >= 0xac00 && codePoint <= 0xd7af)
-        return 2;
-    // CJK Unified Ideographs Extension B-F and other CJK blocks
-    if (codePoint >= 0x20000 && codePoint <= 0x2ebef)
-        return 2;
-    // Fullwidth ASCII variants
-    if (codePoint >= 0xff01 && codePoint <= 0xff5e)
-        return 2;
-    // Fullwidth bracket forms
-    if (codePoint >= 0xff5f && codePoint <= 0xff60)
-        return 2;
-    // Fullwidth symbol variants
-    if (codePoint >= 0xffe0 && codePoint <= 0xffe6)
-        return 2;
-    // Japanese hiragana and katakana
-    if (codePoint >= 0x3040 && codePoint <= 0x309f)
-        return 2;
-    if (codePoint >= 0x30a0 && codePoint <= 0x30ff)
-        return 2;
-    // CJK symbols and punctuation
-    if (codePoint >= 0x3000 && codePoint <= 0x303f)
-        return 2;
-    // Enclosed CJK letters and months
-    if (codePoint >= 0x3200 && codePoint <= 0x32ff)
-        return 2;
-    // CJK compatibility
-    if (codePoint >= 0x3300 && codePoint <= 0x33ff)
-        return 2;
-    // Hangul Jamo
-    if (codePoint >= 0x1100 && codePoint <= 0x11ff)
-        return 2;
-    // Hangul compatibility Jamo
-    if (codePoint >= 0x3130 && codePoint <= 0x318f)
-        return 2;
-    return 1;
+    return stringWidth(String.fromCodePoint(codePoint));
+}
+/**
+ * Width of one grapheme cluster in terminal columns. Handles ZWJ sequences,
+ * regional-indicator flags, skin-tone modifiers, and VS16 emoji presentation.
+ */
+export function clusterWidth(cluster) {
+    return stringWidth(cluster);
+}
+/** Strip SGR (color/style) sequences from a string. */
+function stripSGR(str) {
+    return str.replace(/\x1b\[[^m]*m/g, "");
 }
 /**
  * Measure visible string length in terminal columns.
- * Excludes SGR (color/style) sequences and accounts for CJK double-width chars.
+ * Excludes SGR (color/style) sequences, and counts each grapheme cluster
+ * (emoji, CJK, combining marks) as one terminal-visible unit.
  */
 export function visibleLen(str) {
-    // First strip ANSI escape sequences
-    const cleanStr = str.replace(/\x1b\[[^m]*m/g, "");
-    let width = 0;
-    for (const char of cleanStr) {
-        width += charWidth(char.codePointAt(0) ?? 0);
-    }
-    return width;
+    return stringWidth(stripSGR(str));
 }
 /**
  * Truncate a string to fit within `maxWidth` visible columns.
- * Accounts for CJK double-width characters. Appends `…` if truncated.
+ * Iterates by grapheme cluster so emoji sequences (ZWJ, flags, VS16) are
+ * kept intact rather than split mid-cluster. Appends `…` if truncated.
  */
 export function truncateToWidth(str, maxWidth) {
-    const clean = str.replace(/\x1b\[[^m]*m/g, "");
+    const clean = stripSGR(str);
     if (maxWidth <= 0)
         return "";
-    // First check if the entire string fits
-    let fullWidth = 0;
-    for (const char of clean) {
-        fullWidth += charWidth(char.codePointAt(0) ?? 0);
-    }
-    if (fullWidth <= maxWidth)
+    if (visibleLen(clean) <= maxWidth)
         return clean;
-    // String doesn't fit — truncate with "…"
-    // At maxWidth=1 the ellipsis alone fills the budget.
     if (maxWidth === 1)
         return "…";
-    // Reserve 1 column for "…", so target content width is maxWidth - 1
     const target = maxWidth - 1;
     let width = 0;
-    let i = 0;
-    for (const char of clean) {
-        const cw = charWidth(char.codePointAt(0) ?? 0);
+    let out = "";
+    for (const { segment } of GRAPHEME_SEGMENTER.segment(clean)) {
+        const cw = clusterWidth(segment);
         if (width + cw > target)
             break;
         width += cw;
-        i += char.length;
+        out += segment;
     }
-    // If nothing fit (first char is wider than target), just show the ellipsis
-    // rather than emit a character that would overflow the budget.
-    if (i === 0)
+    if (out === "")
         return "…";
-    return clean.slice(0, i) + "…";
+    return out + "…";
 }
 /** Truncate to visible width while preserving SGR sequences — use when
  *  input carries color/bold codes. `truncateToWidth` strips them. */
@@ -173,43 +80,57 @@ export function truncateAnsiToWidth(str, maxWidth) {
     if (maxWidth === 1)
         return "…";
     const target = maxWidth - 1;
+    // Walk the string preserving SGR escapes in-place; buffer text between
+    // escapes and segment it into graphemes to count width correctly.
     let width = 0;
     let out = "";
+    let buf = "";
     let i = 0;
+    const flushBuf = () => {
+        if (!buf)
+            return false;
+        for (const { segment } of GRAPHEME_SEGMENTER.segment(buf)) {
+            const cw = clusterWidth(segment);
+            if (width + cw > target) {
+                buf = "";
+                return true; // budget exhausted
+            }
+            width += cw;
+            out += segment;
+        }
+        buf = "";
+        return false;
+    };
     while (i < str.length) {
         if (str[i] === "\x1b" && str[i + 1] === "[") {
             const end = str.indexOf("m", i);
             if (end !== -1) {
+                if (flushBuf())
+                    break;
                 out += str.slice(i, end + 1);
                 i = end + 1;
                 continue;
             }
         }
         const cp = str.codePointAt(i) ?? 0;
-        const cw = charWidth(cp);
-        if (width + cw > target)
-            break;
         const chLen = cp > 0xffff ? 2 : 1;
-        out += str.slice(i, i + chLen);
-        width += cw;
+        buf += str.slice(i, i + chLen);
         i += chLen;
     }
+    flushBuf();
     return out + "\x1b[0m…";
 }
 /**
  * Pad a string with spaces to fill `targetWidth` visible columns.
- * Accounts for CJK double-width characters.
  */
 export function padEndToWidth(str, targetWidth) {
     const gap = targetWidth - visibleLen(str);
     return gap > 0 ? str + " ".repeat(gap) : str;
 }
-/** Strip all ANSI escape sequences (SGR, OSC, CSI, private mode) and carriage returns. */
+/** Strip ANSI escape sequences and carriage returns.
+ *  Delegates escape handling to the `strip-ansi` package (covers SGR, OSC,
+ *  CSI, private-mode, 8-bit CSI, and newer variants). `\r` is not an escape
+ *  but callers rely on it being stripped alongside. */
 export function stripAnsi(str) {
-    return str
-        .replace(/\x1b\][^\x07]*\x07/g, "") // OSC sequences
-        .replace(/\x1b\[[^m]*m/g, "") // SGR (color) sequences
-        .replace(/\x1b\[\?[^a-zA-Z]*[a-zA-Z]/g, "") // private mode sequences
-        .replace(/\x1b\[[^a-zA-Z]*[a-zA-Z]/g, "") // CSI sequences
-        .replace(/\r/g, ""); // carriage returns
+    return stripAnsiPkg(str).replace(/\r/g, "");
 }

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/dist/utils/markdown.js

@@ -269,12 +269,20 @@ export class MarkdownRenderer {
         const separatorWidth = (numCols - 1) * 3;
         const tableWidth = Math.max(10, this.width - 2);
         const availableWidth = tableWidth - separatorWidth;
-        const totalWidth = colWidths.reduce((a, b) => a + b, 0);
-        if (totalWidth > availableWidth && availableWidth > numCols) {
-            const scale = availableWidth / totalWidth;
-            for (let c = 0; c < numCols; c++) {
-                colWidths[c] = Math.max(1, Math.floor(colWidths[c] * scale));
+        // Shrink the widest column one step at a time until the table fits.
+        // Preserves natural width on narrow columns — proportional scaling
+        // over-truncates when only one column is oversized.
+        let total = colWidths.reduce((a, b) => a + b, 0);
+        while (total > availableWidth && availableWidth > numCols) {
+            let maxIdx = 0;
+            for (let c = 1; c < numCols; c++) {
+                if (colWidths[c] > colWidths[maxIdx])
+                    maxIdx = c;
             }
+            if (colWidths[maxIdx] <= 1)
+                break;
+            colWidths[maxIdx]--;
+            total--;
         }
         // Render rows
         const hasHeader = sepIdx.includes(1) && dataRows.length > 1;
@@ -287,9 +295,13 @@ export class MarkdownRenderer {
             const cells = row.map((cell, c) => {
                 const w = colWidths[c];
                 const rendered = this.renderInline(cell);
-                const text = visibleLen(rendered) > w
+                // Truncation can yield width < w when a CJK double-width char
+                // won't fit the remaining budget — always re-pad to keep cells
+                // aligned with the border grid.
+                const clipped = visibleLen(rendered) > w
                     ? truncateAnsiToWidth(rendered, w)
-                    : padEndToWidth(rendered, w);
+                    : rendered;
+                const text = padEndToWidth(clipped, w);
                 return isHeader ? `${p.bold}${text}${p.reset}` : text;
             });
             this.writeLine(`${p.dim}│${p.reset} ${cells.join(` ${p.dim}│${p.reset} `)} ${p.dim}│${p.reset}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sh",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "description": "A shell-first terminal where AI is one keystroke away",
   "type": "module",
   "main": "dist/core.js",
@@ -34,6 +34,10 @@
       "types": "./dist/extensions/index.d.ts",
       "default": "./dist/extensions/index.js"
     },
+    "./shell": {
+      "types": "./dist/shell/shell.d.ts",
+      "default": "./dist/shell/shell.js"
+    },
     "./utils/stream-transform": {
       "types": "./dist/utils/stream-transform.d.ts",
       "default": "./dist/utils/stream-transform.js"
@@ -122,6 +126,8 @@
     "marked": "^17.0.6",
     "node-pty": "^1.2.0-beta.12",
     "openai": "^6.34.0",
+    "string-width": "^8.2.0",
+    "strip-ansi": "^7.2.0",
     "tsx": "^4.19.0"
   },
   "devDependencies": {

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;
-        });
-    });
-}