agent-sh 0.9.0 → 0.10.0

package/dist/extensions/agent-backend.js

@@ -1,23 +1,22 @@
 import { AgentLoop } from "../agent/agent-loop.js";
 import { LlmClient } from "../utils/llm-client.js";
 import { resolveProvider, getProviderNames, getSettings } from "../settings.js";
+/** Read the user's persisted defaultModel for a provider, if any. */
+function persistedModelFor(providerName) {
+    if (!providerName)
+        return undefined;
+    return getSettings().providers?.[providerName]?.defaultModel;
+}
 export default function agentBackend(ctx) {
     const { bus } = ctx;
-    // ── Resolve providers ──────────────────────────────────────
     const config = ctx.call("config:get-shell-config") ?? {};
-    const settings = getSettings();
-    let activeProvider = null;
+    // Seed from settings.json; runtime provider:register events add more.
     const providerRegistry = new Map();
     for (const name of getProviderNames()) {
         const p = resolveProvider(name);
         if (p)
             providerRegistry.set(name, p);
     }
-    const providerName = config.provider ?? settings.defaultProvider;
-    if (providerName) {
-        activeProvider = providerRegistry.get(providerName) ?? null;
-    }
-    // ── Build modes ────────────────────────────────────────────
     const buildModes = () => {
         const allModes = [];
         for (const [id, p] of providerRegistry) {
@@ -37,48 +36,38 @@ export default function agentBackend(ctx) {
         }
         return allModes;
     };
-    const effectiveApiKey = config.apiKey ?? activeProvider?.apiKey;
-    const effectiveBaseURL = config.baseURL ?? activeProvider?.baseURL;
-    const effectiveModel = config.model ?? activeProvider?.defaultModel;
-    let modes = buildModes();
-    if (modes.length === 0 && effectiveApiKey && effectiveModel) {
-        modes = [{ model: effectiveModel }];
-    }
-    const initialModeIndex = Math.max(0, modes.findIndex((m) => m.model === effectiveModel && (!activeProvider || m.provider === activeProvider.id)));
-    // ── Create LLM client ─────────────────────────────────────
-    if (!effectiveApiKey)
-        return; // No LLM provider configured — skip
-    if (!effectiveModel) {
-        bus.emit("ui:error", { message: "No model specified. Use --model or configure a provider with defaultModel in ~/.agent-sh/settings.json" });
-        return;
-    }
-    const llmClient = new LlmClient({
-        apiKey: effectiveApiKey,
-        baseURL: effectiveBaseURL,
-        model: effectiveModel,
-    });
-    // Expose LLM client for other extensions (e.g. command-suggest)
+    // Placeholder client — reconfigured at core:extensions-loaded. Any
+    // stream() call before then fails from the OpenAI SDK; start() won't
+    // 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);
-    // ── Initial modes (queryable via pipe) ─────────────────────
-    bus.onPipe("config:get-initial-modes", () => ({
-        modes,
-        initialModeIndex,
-    }));
-    // ── Create agent loop ──────────────────────────────────────
+    let modes = [];
+    let initialModeIndex = 0;
+    let resolved = false;
+    bus.onPipe("config:get-initial-modes", () => ({ modes, initialModeIndex }));
+    // AgentLoop must be constructed *before* user extensions activate,
+    // because its ctor defines handlers (history:append, etc.) that
+    // extensions like superash call synchronously during their own
+    // activate. Advise-before-define works for advisers, but plain calls
+    // would hit a no-op stub.
     const agentLoop = new AgentLoop({
         bus,
         contextManager: ctx.contextManager,
         llmClient,
-        handlers: { define: ctx.define, advise: ctx.advise, call: ctx.call },
+        handlers: { define: ctx.define, advise: ctx.advise, call: ctx.call, list: ctx.list },
         modes,
         initialModeIndex,
         compositor: ctx.compositor,
+        instanceId: ctx.instanceId,
     });
-    // Register as backend
     bus.emit("agent:register-backend", {
         name: "ash",
         kill: () => agentLoop.kill(),
         start: async () => {
+            if (!resolved) {
+                bus.emit("ui:error", { message: "Agent backend not started — no LLM provider available. See earlier messages." });
+                return;
+            }
             agentLoop.wire();
             bus.emit("agent:info", {
                 name: "ash",
@@ -89,7 +78,34 @@ export default function agentBackend(ctx) {
             });
         },
     });
-    // ── Runtime provider registration ──────────────────────────
+    bus.on("core:extensions-loaded", () => {
+        const settings = getSettings();
+        const providerName = config.provider ?? settings.defaultProvider;
+        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
+        // hardcoded DEFAULT_MODELS[0] each startup, which would otherwise
+        // clobber the user's /model selection.
+        const effectiveApiKey = config.apiKey ?? activeProvider?.apiKey;
+        const effectiveBaseURL = config.baseURL ?? activeProvider?.baseURL;
+        const effectiveModel = config.model ?? persistedModelFor(providerName) ?? activeProvider?.defaultModel;
+        if (!effectiveApiKey) {
+            bus.emit("ui:error", { message: "No LLM provider configured. Set --api-key, configure a provider in ~/.agent-sh/settings.json, or load a provider extension (e.g. openrouter) that sets OPENROUTER_API_KEY." });
+            return;
+        }
+        if (!effectiveModel) {
+            bus.emit("ui:error", { message: "No model specified. Use --model or configure a provider with defaultModel in ~/.agent-sh/settings.json" });
+            return;
+        }
+        modes = buildModes();
+        if (modes.length === 0)
+            modes = [{ model: effectiveModel }];
+        initialModeIndex = Math.max(0, modes.findIndex((m) => m.model === effectiveModel && (!activeProvider || m.provider === activeProvider.id)));
+        llmClient.reconfigure({ apiKey: effectiveApiKey, baseURL: effectiveBaseURL, model: effectiveModel });
+        bus.emit("config:set-modes", { modes, activeIndex: initialModeIndex });
+        resolved = true;
+        // start() emits agent:info after wiring.
+    });
     bus.on("provider:register", (p) => {
         const rawModels = p.models ?? (p.defaultModel ? [p.defaultModel] : []);
         const modelIds = [];
@@ -124,16 +140,26 @@ export default function agentBackend(ctx) {
             };
         });
         bus.emit("config:add-modes", { modes: addModes });
+        // Late-registration reconcile: if this completes the user's persisted
+        // default (openrouter's async fetch delivers the full catalog after
+        // we've already fallen back to mode 0), quietly switch to it.
+        if (!resolved)
+            return;
+        const pendingProvider = getSettings().defaultProvider;
+        if (pendingProvider !== p.id)
+            return;
+        const pendingModel = persistedModelFor(pendingProvider);
+        if (pendingModel && modelIds.includes(pendingModel) && llmClient.model !== pendingModel) {
+            bus.emit("config:switch-model", { model: pendingModel });
+        }
     });
-    // ── Runtime provider switching ─────────────────────────────
     bus.on("config:switch-provider", ({ provider: name }) => {
         const p = providerRegistry.get(name);
         if (!p) {
             bus.emit("ui:error", { message: `Unknown provider: ${name}` });
             return;
         }
-        const newApiKey = p.apiKey;
-        if (!newApiKey) {
+        if (!p.apiKey) {
             bus.emit("ui:error", { message: `Provider "${name}" has no API key configured` });
             return;
         }
@@ -142,24 +168,19 @@ export default function agentBackend(ctx) {
             bus.emit("ui:error", { message: `Provider "${name}" has no models configured` });
             return;
         }
-        llmClient.reconfigure({
-            apiKey: newApiKey,
-            baseURL: p.baseURL,
-            model: switchModel,
-        });
+        llmClient.reconfigure({ apiKey: p.apiKey, baseURL: p.baseURL, model: switchModel });
         const newModes = p.models.map((m) => {
             const mc = p.modelCapabilities?.get(m);
             return {
                 model: m,
                 provider: name,
-                providerConfig: { apiKey: newApiKey, baseURL: p.baseURL },
+                providerConfig: { apiKey: p.apiKey, baseURL: p.baseURL },
                 contextWindow: mc?.contextWindow ?? p.contextWindow,
                 reasoning: mc?.reasoning,
                 supportsReasoningEffort: p.supportsReasoningEffort,
             };
         });
         bus.emit("config:set-modes", { modes: newModes });
-        activeProvider = p;
         bus.emit("agent:info", { name: "ash", version: "0.4", model: switchModel, provider: name, contextWindow: p.contextWindow });
         bus.emit("ui:info", { message: `Switched to ${name} (${switchModel})` });
         bus.emit("config:changed", {});

package/dist/extensions/index.js

@@ -5,7 +5,6 @@ export const BUILTIN_EXTENSIONS = [
     { name: "file-autocomplete", load: () => import("./file-autocomplete.js").then(m => m.default) },
     { name: "shell-recall", load: () => import("./shell-recall.js").then(m => m.default) },
     { name: "command-suggest", load: () => import("./command-suggest.js").then(m => m.default) },
-    { name: "terminal-buffer", load: () => import("./terminal-buffer.js").then(m => m.default) },
 ];
 /**
  * Load built-in extensions sequentially, skipping any in the disabled list.

package/dist/extensions/slash-commands.js

@@ -79,7 +79,7 @@ export default function activate(ctx) {
     });
     register({
         name: "/compact",
-        description: "Compact conversation (move full content to nuclear summaries)",
+        description: "Compact conversation via the active compaction strategy",
         handler: () => {
             bus.emit("agent:compact-request", {});
         },
@@ -90,19 +90,15 @@ export default function activate(ctx) {
         handler: () => {
             const stats = bus.emitPipe("context:get-stats", {
                 activeTokens: 0,
-                nuclearEntries: 0,
-                recallArchiveSize: 0,
+                totalTokens: 0,
                 budgetTokens: 0,
             });
             const pct = stats.budgetTokens > 0
                 ? Math.round((stats.activeTokens / stats.budgetTokens) * 100)
                 : 0;
-            const lines = [
-                `Active context: ~${stats.activeTokens.toLocaleString()} tokens / ${stats.budgetTokens.toLocaleString()} budget (${pct}%)`,
-                `Nuclear entries: ${stats.nuclearEntries} in-context`,
-                `Recall archive: ${stats.recallArchiveSize} entries`,
-            ];
-            bus.emit("ui:info", { message: lines.join("\n") });
+            bus.emit("ui:info", {
+                message: `Active context: ~${stats.activeTokens.toLocaleString()} tokens / ${stats.budgetTokens.toLocaleString()} budget (${pct}%)`,
+            });
         },
     });
     register({
@@ -118,10 +114,19 @@ export default function activate(ctx) {
             }
         },
     });
+    // Handler form so extensions can trigger reload programmatically
+    // (e.g. an ash-callable reload_extensions tool in superash).
+    ctx.define("extensions:reload", async () => {
+        return await reloadExtensions(ctx);
+    });
     // ── Extension registration ────────────────────────────────────
     bus.on("command:register", (cmd) => {
         register(cmd);
     });
+    bus.on("command:unregister", ({ name }) => {
+        const key = name.startsWith("/") ? name : `/${name}`;
+        commands.delete(key);
+    });
     // ── Skill commands (/skill:<name>) ────────────────────────────
     const getSkills = () => {
         const cwd = contextManager?.getCwd() ?? process.cwd();

package/dist/extensions/tui-renderer.js

@@ -12,6 +12,7 @@
  */
 import { highlight } from "cli-highlight";
 import { MarkdownRenderer, wrapLine, MAX_CONTENT_WIDTH } from "../utils/markdown.js";
+import { DEFAULT_CONTEXT_WINDOW } from "../agent/token-budget.js";
 import { createFencedBlockTransform } from "../utils/stream-transform.js";
 import { palette as p } from "../utils/palette.js";
 import { renderToolCall, createSpinner, formatElapsed, SPINNER_FRAMES, } from "../utils/tool-display.js";
@@ -63,12 +64,14 @@ function createRenderState() {
         isThinking: false,
         showThinkingText: false,
         thinkingPending: false,
-        lastTruncatedDiff: null,
     };
 }
 export default function activate(ctx) {
     const { bus, define, compositor } = ctx;
     const s = createRenderState();
+    /** Track the shell's cwd so path shortening is relative to where the user actually is. */
+    let shellCwd = process.cwd();
+    bus.on("shell:cwd-change", (e) => { shellCwd = e.cwd; });
     /** Shorthand — get the current agent surface. */
     function out() { return compositor.surface("agent"); }
     /** Capped width for borders, tool lines, and content — keeps everything aligned. */
@@ -226,7 +229,7 @@ export default function activate(ctx) {
         s.isThinking = false;
         if (pendingUsage && s.renderer) {
             const { prompt_tokens, completion_tokens } = pendingUsage;
-            const maxTokens = backendInfo?.contextWindow ?? 128_000;
+            const maxTokens = backendInfo?.contextWindow ?? DEFAULT_CONTEXT_WINDOW;
             s.renderer.writeLine("");
             s.renderer.writeLine(ctx.call("tui:render-usage", prompt_tokens, completion_tokens, maxTokens));
             drain();
@@ -379,17 +382,37 @@ export default function activate(ctx) {
             s.renderer.flush();
             drain();
         }
+        // Diff rendering is handled in the async pipe below so it can yield
+        // to the event loop between hunks (keeping the spinner responsive).
+    });
+    // Async pipe: render diffs via the tui:render-diff handler (extensions can
+    // advise to customize).  Runs after the sync `on` handler above (which
+    // flushes state) and before shell.ts's pipe (which pauses stdout).
+    bus.onPipeAsync("permission:request", async (e) => {
+        if (!shouldRender())
+            return e;
         if (e.kind === "file-write" && e.metadata?.diff) {
             showCollapsedThinking();
-            showFileDiff(e.title, e.metadata.diff);
+            const lines = ctx.call("tui:render-diff", e.title, e.metadata.diff, cappedW());
+            if (lines.length > 0) {
+                if (!s.renderer)
+                    startAgentResponse();
+                contentGap("diff");
+                for (const line of lines)
+                    s.renderer.writeLine(line);
+                drain();
+            }
+            // The diff box IS the visual representation of the upcoming tool call.
+            // Mark lastContentKind as "tool" so the tool call line that follows
+            // doesn't inject an extra gap between the diff box and the checkmark.
+            s.lastContentKind = "tool";
         }
         // Don't endAgentResponse() here — permission requests that aren't
         // file-write diffs are handled inline (auto-approved or by extensions).
         // Closing the response prematurely causes double separator borders.
+        return e;
     });
     bus.on("input:keypress", (e) => {
-        if (e.key === "\x0f")
-            expandLastDiff(); // Ctrl+O
         if (e.key === "\x14")
             toggleThinkingDisplay(); // Ctrl+T
     });
@@ -518,9 +541,23 @@ export default function activate(ctx) {
         }
         let highlighted;
         try {
-            highlighted = language
-                ? highlight(code, { language })
-                : highlight(code); // auto-detect
+            // highlight.js warns to console.error for unsupported languages (elisp, org, etc).
+            // Suppress so it doesn't leak into the terminal.
+            const origError = console.error;
+            console.error = (...args) => {
+                const msg = args.join(" ");
+                if (msg.includes("Could not find the language"))
+                    return;
+                origError.apply(console, args);
+            };
+            try {
+                highlighted = language
+                    ? highlight(code, { language })
+                    : highlight(code); // auto-detect
+            }
+            finally {
+                console.error = origError;
+            }
         }
         catch {
             highlighted = code;
@@ -574,6 +611,17 @@ export default function activate(ctx) {
         }
         return [];
     });
+    /**
+     * Default renderer for standalone diffs (e.g. permission prompts).
+     * Extensions can advise this to customize diff rendering:
+     *
+     *   ctx.advise("tui:render-diff", (next, filePath, diff, width) => {
+     *     return myCustomDiffBox(filePath, diff, width);
+     *   });
+     */
+    define("tui:render-diff", (filePath, diff, width) => {
+        return renderDiffBody(diff, filePath, width);
+    });
     /** Render a diff as framed box lines (pure — no TUI state side effects). */
     function renderDiffBody(diff, filePath, width) {
         if (diff.isIdentical)
@@ -586,18 +634,8 @@ export default function activate(ctx) {
             maxLines: getSettings().diffMaxLines,
             trueColor: true,
         });
-        const lastLine = diffLines[diffLines.length - 1] ?? "";
-        const isTruncated = lastLine.includes("… ");
-        if (isTruncated) {
-            s.lastTruncatedDiff = { filePath, diff, expanded: false };
-        }
-        else {
-            s.lastTruncatedDiff = null;
-        }
         const body = diffLines.length > 1 ? ["", ...diffLines.slice(1), ""] : diffLines;
-        const footer = isTruncated
-            ? [`  ${p.dim}ctrl+o to expand${p.reset}`]
-            : undefined;
+        const footer = undefined;
         return renderBoxFrame(body, {
             width: boxW,
             style: "rounded",
@@ -625,11 +663,10 @@ export default function activate(ctx) {
     function extractDetail(extra) {
         if (extra.locations && extra.locations.length > 0) {
             const loc = extra.locations[0];
-            const cwd = process.cwd();
             const home = process.env.HOME;
             let fp = loc.path;
-            if (fp.startsWith(cwd + "/"))
-                fp = fp.slice(cwd.length + 1);
+            if (fp.startsWith(shellCwd + "/"))
+                fp = fp.slice(shellCwd.length + 1);
             else if (home && fp.startsWith(home + "/"))
                 fp = "~/" + fp.slice(home.length + 1);
             return loc.line ? `${fp}:${loc.line}` : fp;
@@ -642,11 +679,10 @@ export default function activate(ctx) {
         if (typeof raw.pattern === "string")
             return raw.pattern;
         if (typeof raw.path === "string") {
-            const cwd = process.cwd();
             const home = process.env.HOME;
             let fp = raw.path;
-            if (fp.startsWith(cwd + "/"))
-                fp = fp.slice(cwd.length + 1);
+            if (fp.startsWith(shellCwd + "/"))
+                fp = fp.slice(shellCwd.length + 1);
             else if (home && fp.startsWith(home + "/"))
                 fp = "~/" + fp.slice(home.length + 1);
             return fp;
@@ -674,7 +710,7 @@ export default function activate(ctx) {
             locations: extra?.locations,
             rawInput: extra?.rawInput,
             displayDetail: extra?.displayDetail,
-        }, cappedW());
+        }, cappedW(), shellCwd);
         if (extra?.groupContinuation && lines.length > 0) {
             // Swap the colored kind icon for a muted tree connector,
             // and strip the tool name prefix — show detail only.
@@ -879,58 +915,6 @@ export default function activate(ctx) {
             : `${p.success}+${diff.added}${p.reset} ${p.error}-${diff.removed}${p.reset}`;
         return `${p.dim}${filePath}${p.reset}  ${stats}`;
     }
-    function showFileDiff(filePath, diff) {
-        if (diff.isIdentical)
-            return;
-        contentGap("diff");
-        const lines = ctx.call("render:result-body", { kind: "diff", diff, filePath }, cappedW()) ?? [];
-        if (!s.renderer)
-            startAgentResponse();
-        for (const line of lines) {
-            s.renderer.writeLine(line);
-        }
-        drain();
-    }
-    function expandLastDiff() {
-        if (!s.lastTruncatedDiff)
-            return;
-        const entry = s.lastTruncatedDiff;
-        entry.expanded = !entry.expanded;
-        if (!entry.expanded) {
-            showFileDiffCached(entry);
-            return;
-        }
-        if (!entry.expandedLines) {
-            const { filePath, diff } = entry;
-            const boxW = Math.min(cappedW() - 2, out().columns - 2); // -2 for writeLine indent
-            const contentW = boxW - 4;
-            const diffLines = renderDiff(diff, {
-                width: contentW,
-                filePath,
-                maxLines: 500,
-                trueColor: true,
-            });
-            const body = diffLines.length > 1 ? ["", ...diffLines.slice(1), ""] : diffLines;
-            entry.expandedLines = renderBoxFrame(body, {
-                width: boxW,
-                style: "rounded",
-                borderColor: p.dim,
-                title: diffTitle(filePath, diff),
-                footer: [`  ${p.dim}ctrl+o to collapse${p.reset}`],
-            });
-        }
-        out().write("\n");
-        for (const line of entry.expandedLines) {
-            out().write(line + "\n");
-        }
-    }
-    function showFileDiffCached(entry) {
-        const lines = ctx.call("render:result-body", { kind: "diff", diff: entry.diff, filePath: entry.filePath }, cappedW()) ?? [];
-        out().write("\n");
-        for (const line of lines) {
-            out().write(line + "\n");
-        }
-    }
     function toggleThinkingDisplay() {
         s.showThinkingText = !s.showThinkingText;
         if (s.spinner) {

package/dist/index.js

@@ -15,6 +15,13 @@ import { discoverSkills } from "./agent/skills.js";
  */
 async function captureShellEnvAsync(shell) {
     return new Promise((resolve) => {
+        let settled = false;
+        const done = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(result);
+        };
         try {
             const shellName = path.basename(shell);
             const isZsh = shellName.includes("zsh");
@@ -30,8 +37,9 @@ async function captureShellEnvAsync(shell) {
                 output += data.toString("utf-8");
             });
             child.on("close", (code) => {
+                clearTimeout(timer);
                 if (code !== 0 || !output) {
-                    resolve({});
+                    done({});
                     return;
                 }
                 const env = {};
@@ -40,18 +48,19 @@ async function captureShellEnvAsync(shell) {
                     if (eq > 0)
                         env[entry.slice(0, eq)] = entry.slice(eq + 1);
                 }
-                resolve(env);
+                done(env);
             });
             child.on("error", () => {
-                resolve({});
+                clearTimeout(timer);
+                done({});
             });
-            setTimeout(() => {
+            const timer = setTimeout(() => {
                 child.kill("SIGTERM");
-                resolve({});
+                done({});
             }, 5000);
         }
         catch {
-            resolve({});
+            done({});
         }
     });
 }
@@ -245,6 +254,9 @@ async function main() {
     if (process.env.DEBUG) {
         console.error('[agent-sh] Extensions loaded');
     }
+    // Tell deferred-init listeners (agent-backend) that the provider
+    // registry is now complete.
+    core.bus.emit("core:extensions-loaded", {});
     // ── Discover skills ───────────────────────────────────────────
     const skills = discoverSkills(process.cwd());
     // ── Activate agent backend ────────────────────────────────────
@@ -281,6 +293,13 @@ async function main() {
                 sections += `\n    ${p.dim}${s.name}${p.reset}`;
             }
         }
+        const extSections = bus.emitPipe("banner:collect", { sections: [] }).sections;
+        for (const sec of extSections) {
+            sections += `\n\n  ${p.muted}${sec.label}:${p.reset}`;
+            for (const item of sec.items) {
+                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 borderLine = `${p.muted}${"─".repeat(bannerW)}${p.reset}`;
         process.stdout.write("\n" + borderLine + "\n" +

package/dist/settings.d.ts

@@ -50,26 +50,46 @@ export interface Settings {
     historyMaxBytes?: number;
     /** Number of prior history entries to load on startup (default: 50). */
     historyStartupEntries?: number;
-    /** Max nuclear entries kept in-context before flushing to history file (default: 200). */
-    nuclearMaxEntries?: number;
     /** Auto-compact threshold as fraction of conversation budget (0-1, default 0.5). */
     autoCompactThreshold?: number;
     /** Max command output lines shown inline in TUI. */
     maxCommandOutputLines?: number;
     /** Max read tool output lines shown inline in TUI (0 = hide). */
     readOutputMaxLines?: number;
-    /** Max diff lines shown before "ctrl+o to expand". */
+    /** Max diff lines rendered in the TUI (Infinity = no limit). */
     diffMaxLines?: number;
-    /** Tool protocol: "api" (all tools), "deferred" (extensions via meta-tool), "inline" (text). */
-    toolMode?: "api" | "deferred" | "inline";
+    /** Tool protocol:
+     *   "api" — all tools sent with full schema.
+     *   "deferred" — extensions dispatched through `use_extension(name, args)` meta-tool.
+     *   "deferred-lookup" — extensions loaded on demand via `load_tool(names[])`; once loaded, callable as first-class tools.
+     *   "inline" — tools described as text.
+     */
+    toolMode?: "api" | "deferred" | "deferred-lookup" | "inline";
     /** Additional directories to scan for skills (supports ~ expansion). */
     skillPaths?: string[];
+    /**
+     * Enable the "diagnose" tool — lets the agent evaluate JavaScript
+     * expressions against its own runtime state. Powerful for introspection
+     * (e.g. this.conversation.turns.length) but grants arbitrary code
+     * execution within the agent process. Off by default because the
+     * agent already has unrestricted bash access — this is a convenience,
+     * not a new capability.
+     */
+    diagnose?: boolean;
     /** Show a startup banner when agent-sh launches. */
     startupBanner?: boolean;
     /** Show a subtle agent-sh indicator in the shell prompt. */
     promptIndicator?: boolean;
     /** Names of built-in extensions to disable (e.g. ["command-suggest"]). */
     disabledBuiltins?: string[];
+    /**
+     * Names of user extensions in ~/.agent-sh/extensions/ to skip when
+     * auto-discovering. Match by basename without extension for files
+     * (e.g. "peer-mesh" matches peer-mesh.ts), or by directory name for
+     * directory-style extensions (e.g. "superash" matches superash/index.ts).
+     * Beats having to rename files to .disabled every time.
+     */
+    disabledExtensions?: string[];
 }
 declare const DEFAULTS: Required<Settings>;
 /** Load settings from disk (cached after first call). */
@@ -87,6 +107,17 @@ 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;
+/**
+ * Deep-merge a patch into ~/.agent-sh/settings.json on disk.
+ *
+ * Reads the raw file (preserving unknown keys), merges the patch, writes back
+ * with 2-space indentation, and clears the cache so subsequent getSettings()
+ * calls see the new values.
+ *
+ * Used by runtime controls (`/model`, `/backend`) that want their selection
+ * to persist as the default across restarts.
+ */
+export declare function updateSettings(patch: Record<string, unknown>): void;
 /**
  * Expand $ENV_VAR references in a string.
  * Supports $VAR and ${VAR} syntax.