agent-sh 0.4.0 → 0.5.0

package/dist/index.js

@@ -8,16 +8,13 @@ import tuiRenderer from "./extensions/tui-renderer.js";
 import slashCommands from "./extensions/slash-commands.js";
 import fileAutocomplete from "./extensions/file-autocomplete.js";
 import shellRecall from "./extensions/shell-recall.js";
-import shellExec from "./extensions/shell-exec.js";
+import commandSuggest from "./extensions/command-suggest.js";
 import { loadExtensions } from "./extension-loader.js";
+import { getSettings } from "./settings.js";
 /**
  * Capture the user's full shell environment.
  * This picks up env vars exported in .zshrc/.bashrc that the
  * Node.js process doesn't have (e.g. when launched from an IDE).
- *
- * Uses -l (login shell) to get .zprofile/.bash_profile vars, then
- * explicitly sources the interactive rc file (.zshrc/.bashrc) which
- * -l alone doesn't load (that requires -i, which blocks on TTY).
  */
 async function captureShellEnvAsync(shell) {
     return new Promise((resolve) => {
@@ -37,7 +34,7 @@ async function captureShellEnvAsync(shell) {
             });
             child.on("close", (code) => {
                 if (code !== 0 || !output) {
-                    resolve({}); // Return empty to trigger fallback
+                    resolve({});
                     return;
                 }
                 const env = {};
@@ -49,9 +46,8 @@ async function captureShellEnvAsync(shell) {
                 resolve(env);
             });
             child.on("error", () => {
-                resolve({}); // Return empty to trigger fallback
+                resolve({});
             });
-            // Safety timeout
             setTimeout(() => {
                 child.kill("SIGTERM");
                 resolve({});
@@ -62,14 +58,9 @@ async function captureShellEnvAsync(shell) {
         }
     });
 }
-/**
- * Merge captured shell env into base env, only adding keys that don't exist.
- * This preserves any runtime modifications while adding missing shell vars.
- */
 function mergeShellEnv(baseEnv, shellEnv) {
     const merged = { ...baseEnv };
     for (const [key, value] of Object.entries(shellEnv)) {
-        // Only add if key doesn't exist or is empty in base env
         if (!(key in merged) || !merged[key]) {
             merged[key] = value;
         }
@@ -77,113 +68,96 @@ function mergeShellEnv(baseEnv, shellEnv) {
     return merged;
 }
 function parseArgs(argv) {
-    // Priority: CLI args > Environment variables > Config file > Defaults
-    const defaultAgent = process.env.AGENT_SH_AGENT || "pi-acp";
-    let agentCommand = defaultAgent;
-    let agentArgs = [];
     let model;
     let extensions;
+    let provider;
     const shell = process.env.SHELL || "/bin/bash";
+    let apiKey = process.env.OPENAI_API_KEY;
+    let baseURL = process.env.OPENAI_BASE_URL;
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
-        if (arg === "--agent" && argv[i + 1]) {
-            agentCommand = argv[++i];
+        if (arg === "--model" && argv[i + 1]) {
+            model = argv[++i];
         }
-        else if (arg === "--agent-args" && argv[i + 1]) {
-            const argsString = argv[++i];
-            agentArgs = argsString.split(" ");
-            // Extract model from agent args if provided
-            const modelArgIndex = agentArgs.findIndex(a => a === "--model" || a === "-m");
-            if (modelArgIndex !== -1 && agentArgs[modelArgIndex + 1]) {
-                model = agentArgs[modelArgIndex + 1];
-            }
+        else if (arg === "--api-key" && argv[i + 1]) {
+            apiKey = argv[++i];
+        }
+        else if (arg === "--base-url" && argv[i + 1]) {
+            baseURL = argv[++i];
+        }
+        else if (arg === "--provider" && argv[i + 1]) {
+            provider = argv[++i];
         }
         else if (arg === "--shell" && argv[i + 1]) {
-            return { agentCommand, agentArgs, shell: argv[++i], model, extensions };
+            return { shell: argv[++i], model, extensions, apiKey, baseURL, provider };
         }
         else if ((arg === "--extensions" || arg === "-e") && argv[i + 1]) {
             const exts = argv[++i].split(",").map(s => s.trim());
             extensions = extensions ? [...extensions, ...exts] : exts;
         }
         else if (arg === "--help" || arg === "-h") {
-            console.log(`agent-sh — a shell-first terminal with ACP agent access
+            console.log(`agent-sh — a shell-first terminal where AI is one keystroke away
 
 Usage: agent-sh [options]
 
-Quick Start:
-  npm start           Start with default agent (pi-acp)
-  npm run pi          Start with pi-acp agent
-  npm run claude      Start with Claude agent
+Provider Profiles:
+  --provider <name>   Use a provider from ~/.agent-sh/settings.json
+  --model <name>      Override default model
+
+Direct LLM API:
+  --api-key <key>     API key for OpenAI-compatible provider (or set OPENAI_API_KEY)
+  --base-url <url>    Base URL for API (or set OPENAI_BASE_URL)
 
-Options:
-  --agent <cmd>       Agent command to launch (default: $AGENT_SH_AGENT or "pi-acp")
-  --agent-args <args> Arguments for the agent (space-separated, quoted)
+General Options:
   --shell <path>      Shell to use (default: $SHELL or /bin/bash)
   -e, --extensions    Extensions to load (comma-separated, repeatable)
   -h, --help          Show this help
 
-Extensions:
-  Extensions are loaded from (in order):
-    1. -e flags:  npm packages or file paths
-    2. settings:  ~/.agent-sh/settings.json → "extensions": [...]
-    3. directory:  ~/.agent-sh/extensions/ (files or dirs with index.ts)
-
 Environment Variables:
-  AGENT_SH_AGENT   Default agent to use (e.g., "pi-acp", "claude")
+  OPENAI_API_KEY     API key for LLM provider
+  OPENAI_BASE_URL    Base URL override (e.g., http://localhost:11434/v1 for Ollama)
 
 Examples:
-  npm start --agent pi-acp
-  npm start -- -e my-extension-package
-  npm start -- -e ./local-ext.ts -e another-package
+  # Use a configured provider
+  agent-sh --provider openai
+
+  # Direct API access
+  agent-sh --api-key "$KEY" --model gpt-4o
+
+  # Local model via Ollama
+  agent-sh --base-url http://localhost:11434/v1 --model llama3
 
 Inside the shell:
   Type normally        Commands run in your real shell
-  > <query>           Send query to the AI agent
+  > <query>           Ask the AI agent a question (execute mode)
+  ? <command>         Have the agent run a command in your shell (help mode)
   > /help             Show available slash commands
   Ctrl-C              Cancel agent response (or signal shell as usual)
 `);
             process.exit(0);
         }
     }
-    return { agentCommand, agentArgs, shell, model, extensions };
-}
-function formatAgentInfo(agentInfo, model, thoughtLevel) {
-    const name = agentInfo.name.replace(/-acp$/, "").replace(/-/g, " ");
-    let infoStr = `${p.dim}${name}${p.reset}`;
-    if (model) {
-        const cleanModel = model
-            .replace(/^openai\//i, "")
-            .replace(/^anthropic\//i, "")
-            .replace(/^google\//i, "");
-        infoStr += ` ${p.dim}(${cleanModel})${p.reset}`;
-    }
-    if (thoughtLevel) {
-        // Clean up verbose mode names like "Thinking: medium" → "medium"
-        const label = thoughtLevel.replace(/^Thinking:\s*/i, "");
-        infoStr += ` ${p.dim}[${label}]${p.reset}`;
-    }
-    return infoStr;
+    return { shell, model, extensions, apiKey, baseURL, provider };
 }
 async function main() {
-    // Set up signal handlers before any terminal operations.
-    // Ignore SIGTTOU to prevent suspension when modifying terminal settings.
+    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", () => { });
-    // Also ignore SIGTTIN which can occur when reading from terminal while backgrounded.
     process.on("SIGTTIN", () => { });
     const config = parseArgs(process.argv.slice(2));
-    // Capture user's full shell environment (from .zshrc/.bashrc etc.)
-    // This must complete before spawning the agent so it sees all env vars.
+    // Capture user's full shell environment
     const baseEnv = {};
     for (const [k, v] of Object.entries(process.env)) {
         if (v !== undefined)
             baseEnv[k] = v;
     }
-    config.shellEnv = baseEnv;
     const shellPath = config.shell || process.env.SHELL || "/bin/bash";
     try {
         const shellEnv = await captureShellEnvAsync(shellPath);
         if (Object.keys(shellEnv).length > 0) {
-            config.shellEnv = mergeShellEnv(config.shellEnv, shellEnv);
+            Object.assign(baseEnv, mergeShellEnv(baseEnv, shellEnv));
             if (process.env.DEBUG) {
                 console.error('[agent-sh] Shell environment captured');
             }
@@ -194,7 +168,10 @@ async function main() {
     }
     // ── Core (frontend-agnostic) ──────────────────────────────────
     const core = createCore(config);
-    const { bus, client } = core;
+    const { bus } = core;
+    // Track agent info from bus events (populated by extension backends)
+    let agentInfo = null;
+    bus.on("agent:info", (info) => { agentInfo = info; });
     // ── Interactive frontend ──────────────────────────────────────
     if (process.env.DEBUG) {
         console.error('[agent-sh] Setting up interactive frontend...');
@@ -213,8 +190,6 @@ async function main() {
     if (process.env.DEBUG) {
         console.error('[agent-sh] Creating Shell...');
     }
-    // Small delay on macOS to ensure we're fully in the foreground process group
-    // before spawning the PTY. This prevents SIGTTOU suspension.
     await new Promise(resolve => setTimeout(resolve, 100));
     const shell = new Shell({
         bus,
@@ -223,13 +198,11 @@ async function main() {
         shell: config.shell || process.env.SHELL || "/bin/bash",
         cwd: process.cwd(),
         onShowAgentInfo: () => {
-            if (client.isConnected()) {
-                const agentInfo = client.getAgentInfo();
-                const model = client.getModel();
-                if (agentInfo) {
-                    const mode = client.getCurrentMode();
-                    return { info: formatAgentInfo(agentInfo, model, mode?.name ?? null) };
-                }
+            if (agentInfo) {
+                return { info: `${p.dim}${agentInfo.name}${agentInfo.model ? ` (${agentInfo.model})` : ""}${p.reset}` };
+            }
+            if (core.llmClient) {
+                return { info: `${p.dim}agent-sh (${core.llmClient.model})${p.reset}` };
             }
             return { info: "" };
         },
@@ -239,24 +212,35 @@ async function main() {
     }
     // ── Input modes ──────────────────────────────────────────────
     bus.emit("input-mode:register", {
-        id: "query",
-        trigger: "?",
-        label: "query",
+        id: "execute",
+        trigger: ">",
+        label: "execute",
         promptIcon: "❯",
-        indicator: "❓",
+        indicator: "●",
         onSubmit(query, b) {
-            b.emit("agent:submit", { query, modeLabel: "Query", modeInstruction: "[mode: query]" });
+            b.emit("agent:submit", { query, modeLabel: "Execute", modeInstruction: "[mode: execute]" });
         },
         returnToSelf: true,
     });
     bus.emit("input-mode:register", {
-        id: "execute",
-        trigger: ">",
-        label: "execute",
-        promptIcon: "⟩",
-        indicator: "●",
+        id: "help",
+        trigger: "?",
+        label: "help",
+        promptIcon: "❯",
+        indicator: "❓",
         onSubmit(query, b) {
-            b.emit("agent:submit", { query, modeLabel: "Execute", modeInstruction: "[mode: execute]" });
+            const onToolDone = (e) => {
+                if (e.kind === "execute") {
+                    b.emit("agent:cancel-request", { silent: true });
+                }
+            };
+            const cleanup = () => {
+                b.off("agent:tool-completed", onToolDone);
+                b.off("agent:processing-done", cleanup);
+            };
+            b.on("agent:tool-completed", onToolDone);
+            b.on("agent:processing-done", cleanup);
+            b.emit("agent:submit", { query, modeLabel: "Help", modeInstruction: "[mode: help]" });
         },
         returnToSelf: false,
     });
@@ -269,20 +253,12 @@ async function main() {
     slashCommands(extCtx);
     fileAutocomplete(extCtx);
     shellRecall(extCtx);
-    // Shell-exec: start the Unix domain socket bridge so agent extensions
-    // and MCP servers can route tool calls to the PTY via the EventBus.
-    const tmpDir = shell.getTmpDir();
-    if (tmpDir) {
-        if (process.env.DEBUG) {
-            console.error('[agent-sh] Starting shell-exec socket server...');
-        }
-        shellExec(extCtx, { socketPath: `${tmpDir}/shell.sock` });
-    }
-    // Load extensions with timeout to prevent blocking startup
+    commandSuggest(extCtx);
+    // Load user extensions (may register alternative agent backends)
     if (process.env.DEBUG) {
         console.error('[agent-sh] Loading extensions...');
     }
-    const loadExtensionsTimeoutMs = 10000; // 10 seconds
+    const loadExtensionsTimeoutMs = 10000;
     await Promise.race([
         loadExtensions(extCtx, config.extensions),
         new Promise((_, reject) => setTimeout(() => reject(new Error(`Extension loading timeout after ${loadExtensionsTimeoutMs}ms`)), loadExtensionsTimeoutMs)),
@@ -292,21 +268,28 @@ async function main() {
     if (process.env.DEBUG) {
         console.error('[agent-sh] Extensions loaded');
     }
-    // ── Agent connection (async — don't block shell startup) ──────
-    const agentStartTimeoutMs = 35000; // 35 seconds (slightly longer than internal timeouts)
-    Promise.race([
-        core.start(),
-        new Promise((_, reject) => setTimeout(() => reject(new Error(`Agent connection timeout`)), agentStartTimeoutMs)),
-    ]).catch((err) => {
-        console.error(`Failed to connect to ${config.agentCommand}:`, err);
-    });
+    // ── Activate agent backend ────────────────────────────────────
+    // Extensions had their chance to register via agent:register-backend.
+    // If none did, the built-in AgentLoop gets wired to bus events.
+    core.activateBackend();
+    // ── Startup banner ───────────────────────────────────────────
+    const settings = getSettings();
+    if (settings.startupBanner !== false) {
+        const title = core.llmClient
+            ? `${p.accent}${p.bold}agent-sh${p.reset}${p.dim} · ${core.llmClient.model}${p.reset}`
+            : `${p.accent}${p.bold}agent-sh${p.reset}`;
+        const hint = `${p.muted}Type ${p.warning}>${p.muted} to ask AI · ${p.warning}?${p.muted} to run in shell · ${p.warning}/help${p.muted} for commands${p.reset}`;
+        const termW = process.stdout.columns || 80;
+        const borderLine = `${p.muted}${"─".repeat(Math.min(termW, 60))}${p.reset}`;
+        process.stdout.write("\n" + borderLine + "\n" +
+            "  " + title + "\n" +
+            "  " + hint + "\n" +
+            borderLine + "\n\n");
+    }
     // ── Terminal lifecycle ────────────────────────────────────────
     process.on("SIGTERM", cleanup);
     process.on("SIGHUP", cleanup);
-    // Handle terminal stop/resume signals properly
     process.on("SIGTSTP", () => {
-        // Handle Ctrl+Z - suspend the entire process group
-        // Restore terminal state before suspending
         if (process.stdin.isTTY) {
             try {
                 process.stdin.setRawMode(false);
@@ -315,14 +298,11 @@ async function main() {
                 // Ignore
             }
         }
-        // Re-send SIGSTOP to actually suspend
         process.kill(process.pid, "SIGSTOP");
     });
     process.on("SIGCONT", () => {
-        // Re-acquire terminal when brought back to foreground
         if (process.stdin.isTTY) {
             try {
-                // Ensure we reacquire controlling terminal
                 process.stdin.setRawMode(true);
             }
             catch {
@@ -340,17 +320,14 @@ async function main() {
         }
         process.exit(e.exitCode);
     });
-    // Set up stdin - resume after all event listeners are in place
     if (process.env.DEBUG) {
         console.error('[agent-sh] Resuming stdin...');
     }
     process.stdin.resume();
-    // Set raw mode after resume to avoid SIGTTOU issues
     if (process.stdin.isTTY) {
         if (process.env.DEBUG) {
             console.error('[agent-sh] Setting raw mode...');
         }
-        // Use setImmediate to ensure we're in the next tick
         setImmediate(() => {
             try {
                 process.stdin.setRawMode(true);
@@ -362,7 +339,6 @@ async function main() {
                 if (process.env.DEBUG) {
                     console.error(`[agent-sh] Failed to set raw mode: ${err}`);
                 }
-                // May fail if process is in background; SIGTTOU handler prevents suspension
             }
         });
     }

package/dist/input-handler.js

@@ -187,8 +187,44 @@ export class InputHandler {
                 this.lineBuffer = "";
                 this.ctx.writeToPty(ch);
             }
+            else if (ch === "\x1b") {
+                // Escape sequence — forward the entire sequence to the PTY but
+                // don't let it corrupt lineBuffer.  Skip CSI (ESC [ ... final)
+                // and SS3 (ESC O <char>) sequences; anything else: just ESC.
+                let seq = ch;
+                if (i + 1 < data.length) {
+                    const next = data[i + 1];
+                    if (next === "[") {
+                        // CSI: ESC [ (params) (intermediates) final_byte
+                        seq += next;
+                        i++;
+                        while (i + 1 < data.length && data[i + 1].charCodeAt(0) < 0x40) {
+                            i++;
+                            seq += data[i];
+                        }
+                        if (i + 1 < data.length) {
+                            i++;
+                            seq += data[i];
+                        } // final byte
+                    }
+                    else if (next === "O") {
+                        // SS3: ESC O <char>
+                        seq += next;
+                        i++;
+                        if (i + 1 < data.length) {
+                            i++;
+                            seq += data[i];
+                        }
+                    }
+                    else {
+                        // ESC + single char (alt-key, etc.)
+                        seq += next;
+                        i++;
+                    }
+                }
+                this.ctx.writeToPty(seq);
+            }
             else if (ch.charCodeAt(0) < 32 && ch !== "\t") {
-                this.lineBuffer = "";
                 this.ctx.writeToPty(ch);
             }
             else {
@@ -253,8 +289,20 @@ export class InputHandler {
         this.updateAutocomplete();
     }
     updateAutocomplete() {
+        const buf = this.editor.buffer;
+        let command = null;
+        let commandArgs = null;
+        if (buf.startsWith("/")) {
+            const spaceIdx = buf.indexOf(" ");
+            if (spaceIdx !== -1) {
+                command = buf.slice(0, spaceIdx);
+                commandArgs = buf.slice(spaceIdx + 1);
+            }
+        }
         const { items } = this.bus.emitPipe("autocomplete:request", {
-            buffer: this.editor.buffer,
+            buffer: buf,
+            command,
+            commandArgs,
             items: [],
         });
         if (items.length > 0) {
@@ -289,10 +337,15 @@ export class InputHandler {
         if (this.autocompleteLines > 0) {
             process.stdout.write(`\x1b[${this.autocompleteLines}A`);
         }
+        // Reposition cursor: must match the layout in writeModePromptLine()
         const agentInfo = this.onShowAgentInfo();
-        const infoLength = visibleLen(agentInfo.info);
+        const indicator = this.activeMode?.indicator ?? "●";
+        const infoPrefix = agentInfo.info
+            ? `${agentInfo.info} ${indicator} `
+            : `${indicator} `;
         const icon = this.activeMode?.promptIcon ?? "❯";
-        const col = infoLength + visibleLen(icon) + 1 + this.editor.cursor;
+        const promptVisLen = visibleLen(infoPrefix) + visibleLen(icon) + 1;
+        const col = promptVisLen + this.editor.cursor;
         process.stdout.write(`\r\x1b[${col}C`);
     }
     applyAutocomplete() {
@@ -359,16 +412,30 @@ export class InputHandler {
     processModeActions(actions) {
         for (const act of actions) {
             switch (act.action) {
-                case "changed":
+                case "changed": {
+                    // If the buffer is exactly a trigger char for a different mode, switch to it
+                    const switchMode = this.modes.get(this.editor.buffer);
+                    if (this.editor.buffer.length === 1 && switchMode && switchMode !== this.activeMode) {
+                        this.dismissAutocomplete();
+                        this.clearPromptArea();
+                        this.activeMode = switchMode;
+                        this.editor.clear();
+                        this.writeModePromptLine(false);
+                        break;
+                    }
                     this.historyIndex = -1;
                     this.autocompleteIndex = 0;
                     this.renderModeInput();
                     break;
+                }
                 case "submit": {
                     if (this.autocompleteActive) {
                         this.applyAutocomplete();
                     }
-                    const query = act.buffer.trim();
+                    // Use editor.buffer (not act.buffer) so autocomplete selections
+                    // take effect — act.buffer is a stale snapshot from before
+                    // applyAutocomplete() updated the buffer.
+                    const query = this.editor.buffer.trim();
                     if (query) {
                         // Add to history (avoid consecutive duplicates)
                         if (this.history.length === 0 || this.history[this.history.length - 1] !== query) {
@@ -390,7 +457,7 @@ export class InputHandler {
                         const name = spaceIdx === -1 ? query : query.slice(0, spaceIdx);
                         const args = spaceIdx === -1 ? "" : query.slice(spaceIdx + 1).trim();
                         this.bus.emit("command:execute", { name, args });
-                        this.ctx.redrawPrompt();
+                        this.ctx.freshPrompt();
                     }
                     else if (query) {
                         this.pendingReturnMode = currentMode.returnToSelf ? currentMode.id : null;

package/dist/output-parser.d.ts

@@ -19,6 +19,13 @@ export declare class OutputParser {
     isPromptReady(): boolean;
     isForegroundBusy(): boolean;
     getCwd(): string;
+    /**
+     * Detect preexec marker (OSC 9997) emitted by the shell's preexec hook.
+     * This carries the actual command text from the shell — more reliable than
+     * the InputHandler's lineBuffer which can't track history recall or tab
+     * completion. Returns data with the OSC stripped out.
+     */
+    private handlePreexec;
     private parseOSC7;
     /**
      * Detect our custom prompt marker (OSC 9999) in the PTY stream.

package/dist/output-parser.js

@@ -17,6 +17,7 @@ export class OutputParser {
     /** Process a chunk of PTY output data. */
     processData(data) {
         this.parseOSC7(data);
+        data = this.handlePreexec(data);
         this.parsePromptMarker(data);
         this.parsePromptEnd(data);
     }
@@ -41,6 +42,32 @@ export class OutputParser {
         return this.cwd;
     }
     // ── Parsing ─────────────────────────────────────────────────
+    /**
+     * Detect preexec marker (OSC 9997) emitted by the shell's preexec hook.
+     * This carries the actual command text from the shell — more reliable than
+     * the InputHandler's lineBuffer which can't track history recall or tab
+     * completion. Returns data with the OSC stripped out.
+     */
+    handlePreexec(data) {
+        const marker = "\x1b]9997;";
+        const idx = data.indexOf(marker);
+        if (idx === -1)
+            return data;
+        const endIdx = data.indexOf("\x07", idx + marker.length);
+        if (endIdx === -1)
+            return data; // incomplete OSC, wait for next chunk
+        const command = data.slice(idx + marker.length, endIdx);
+        // Authoritative command from the shell — override any lineBuffer guess
+        this.lastCommand = command;
+        this.currentOutputCapture = ""; // discard echoed text accumulated before preexec
+        if (!this.foregroundBusy) {
+            this.foregroundBusy = true;
+            this.bus.emit("shell:foreground-busy", { busy: true });
+        }
+        this.bus.emit("shell:command-start", { command, cwd: this.cwd });
+        // Return only data after the OSC — everything before was the echo
+        return data.slice(endIdx + 1);
+    }
     parseOSC7(data) {
         const match = data.match(/\x1b\]7;file:\/\/[^/]*(\/[^\x07\x1b]*)/);
         if (match?.[1]) {

package/dist/settings.d.ts

@@ -1,9 +1,28 @@
 export declare const CONFIG_DIR: string;
+/** Provider profile — a named LLM configuration. */
+export interface ProviderConfig {
+    /** API key (supports $ENV_VAR syntax for runtime expansion). */
+    apiKey?: string;
+    /** Base URL for OpenAI-compatible API. */
+    baseURL?: string;
+    /** Default model to use. Falls back to first entry in models list. */
+    defaultModel?: string;
+    /** Models available for cycling. */
+    models?: string[];
+    /** Context window size in tokens (e.g. 128000). Used for usage display. */
+    contextWindow?: number;
+}
 export interface Settings {
     /** Extensions to load (npm packages or file paths). */
     extensions?: string[];
     /** Max agent query history entries to keep. */
     historySize?: number;
+    /** Named provider configurations. */
+    providers?: Record<string, ProviderConfig>;
+    /** Which provider to use by default. */
+    defaultProvider?: string;
+    /** Preferred agent backend (extension name, e.g. "pi", "claude-code"). */
+    defaultBackend?: string;
     /** Recent exchanges included in agent context window. */
     contextWindowSize?: number;
     /** Context budget in bytes (~4 chars per token). */
@@ -22,8 +41,12 @@ export interface Settings {
     readOutputMaxLines?: number;
     /** Max diff lines shown before "ctrl+o to expand". */
     diffMaxLines?: number;
-    /** Register MCP server for bridge tools (shell_cwd, user_shell, shell_recall). Default true. */
-    enableMcp?: boolean;
+    /** Additional directories to scan for skills (supports ~ expansion). */
+    skillPaths?: string[];
+    /** Show a startup banner when agent-sh launches. */
+    startupBanner?: boolean;
+    /** Show a subtle agent-sh indicator in the shell prompt. */
+    promptIndicator?: boolean;
 }
 declare const DEFAULTS: Required<Settings>;
 /** Load settings from disk (cached after first call). */
@@ -41,4 +64,32 @@ export declare function getSettings(): Settings & typeof DEFAULTS;
 export declare function getExtensionSettings<T extends Record<string, unknown>>(namespace: string, defaults: T): T;
 /** Reset cached settings (for testing or after external edit). */
 export declare function reloadSettings(): void;
+/**
+ * Expand $ENV_VAR references in a string.
+ * Supports $VAR and ${VAR} syntax.
+ */
+export declare function expandEnvVars(value: string): string;
+/** Resolved provider ready for use (env vars expanded, defaults applied). */
+export interface ResolvedProvider {
+    id: string;
+    apiKey?: string;
+    baseURL?: string;
+    defaultModel?: string;
+    models: string[];
+    contextWindow?: number;
+    /** Provider supports the reasoning_effort parameter. Default: true. */
+    supportsReasoningEffort?: boolean;
+    /** Per-model capabilities, keyed by model id. */
+    modelCapabilities?: Map<string, {
+        reasoning?: boolean;
+        contextWindow?: number;
+    }>;
+}
+/**
+ * Resolve a provider config by name from settings.
+ * Returns null if provider not found.
+ */
+export declare function resolveProvider(name: string): ResolvedProvider | null;
+/** Get all configured provider names. */
+export declare function getProviderNames(): string[];
 export {};