agent-sh 0.12.27 → 0.13.1

package/README.md

@@ -43,9 +43,9 @@ npm run build      # produces dist/
 npm link           # exposes `agent-sh` globally
 ```
 
-Requires Node.js 18+. Currently supports **bash** and **zsh**; other shells (fish, nushell, etc.) are not yet wired up.
+Requires Node.js 18+. Supports **bash**, **zsh**, and **fish**; other shells (nushell, etc.) are not yet wired up.
 
-**Windows:** the interactive shell layer is bash/zsh-only. Run agent-sh inside **WSL** for the full experience. Native Windows (cmd.exe / PowerShell) is not supported as the host shell, though headless / library / ACP-bridge usage may work — file an issue if you hit a gap.
+**Windows:** the interactive shell layer is bash/zsh/fish-only. Run agent-sh inside **WSL** for the full experience. Native Windows (cmd.exe / PowerShell) is not supported as the host shell, though headless / library / ACP-bridge usage may work — file an issue if you hit a gap.
 
 Tip — add a shell alias:
 
@@ -74,6 +74,17 @@ See [Bring your own agent](#bring-your-own-agent) below for full details and the
 
 `ash` is agent-sh's own lightweight agent. It works with any OpenAI-compatible API — 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.
 
+**Quickest path** — store a key once via the auth subcommand:
+
+```bash
+agent-sh auth login          # picks a provider interactively
+agent-sh                     # launches with the saved key
+```
+
+Keys are written to `~/.agent-sh/keys.json` (chmod 0600). Resolution order is `settings.json` → `keys.json` → env var, so an env var or settings entry will still win when present. `auth login` also accepts any provider you declare under `providers` in `settings.json` — useful for custom OpenAI-compatible endpoints where the URL is committable but the key shouldn't be.
+
+Or export the env var directly:
+
 **Hosted models via OpenRouter** (300+ models, one key):
 
 ```bash

package/dist/agent/agent-loop.d.ts

@@ -11,8 +11,8 @@
  *     agent:tool-completed, agent:tool-output
  *   - agent:thinking-chunk, agent:cancelled, agent:error
  */
-import type { EventBus } from "../event-bus.js";
-import type { AgentMode } from "../types.js";
+import type { EventBus } from "../core/event-bus.js";
+import type { AgentMode } from "./host-types.js";
 import type { LlmClient } from "../utils/llm-client.js";
 import type { HandlerFunctions } from "../utils/handler-registry.js";
 import type { AgentBackend, ToolDefinition } from "./types.js";
@@ -67,7 +67,7 @@ export declare class AgentLoop implements AgentBackend {
     wire(): void;
     /** Unsubscribe from bus events — deactivates this backend. */
     unwire(): void;
-    /** Register a tool (used by extensions via ctx.registerTool). */
+    /** Register a tool (used by extensions via ctx.agent.registerTool). */
     registerTool(tool: ToolDefinition): void;
     /** Unregister a tool by name. */
     unregisterTool(name: string): void;
@@ -81,11 +81,9 @@ export declare class AgentLoop implements AgentBackend {
     private toolExtensions;
     /** Register a named instruction block for the system prompt. */
     registerInstruction(name: string, text: string, extensionName: string): void;
-    /** Remove a named instruction block. */
     removeInstruction(name: string): void;
     /** Register a named skill (on-demand reference material). */
     registerSkill(name: string, description: string, filePath: string, extensionName: string): void;
-    /** Remove a registered skill. */
     removeSkill(name: string): void;
     /**
      * Build the system prompt grouped by extension.

package/dist/agent/agent-loop.js

@@ -1,8 +1,5 @@
 import { setMaxListeners } from "node:events";
-import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import * as os from "node:os";
-import { computeDiff, computeEditDiff, computeInputDiff } from "../utils/diff.js";
 import { ToolRegistry } from "./tool-registry.js";
 import { normalizeToolArgs } from "./normalize-args.js";
 import { ConversationState } from "./conversation-state.js";
@@ -13,12 +10,12 @@ import { createToolUI } from "../utils/tool-interactive.js";
 import { RESPONSE_RESERVE, DEFAULT_CONTEXT_WINDOW } from "./token-budget.js";
 import { PACKAGE_VERSION } from "../utils/package-version.js";
 import { wrapTrailingWithDynamicContext } from "../utils/message-utils.js";
-import { getSettings, updateSettings } from "../settings.js";
+import { getSettings, updateSettings } from "../core/settings.js";
 import { createToolProtocol } from "./tool-protocol.js";
 // Core tool factories
 import { createBashTool } from "./tools/bash.js";
 import { createPwshTool } from "./tools/pwsh.js";
-import { findBash } from "../executor.js";
+import { findBash } from "../utils/executor.js";
 import { createReadFileTool } from "./tools/read-file.js";
 import { createWriteFileTool } from "./tools/write-file.js";
 import { createEditFileTool } from "./tools/edit-file.js";
@@ -52,7 +49,7 @@ function summarizeDescription(desc) {
 }
 export class AgentLoop {
     abortController = null;
-    toolRegistry = new ToolRegistry();
+    toolRegistry;
     history;
     conversation;
     fileReadCache = new Map();
@@ -104,6 +101,7 @@ export class AgentLoop {
         this.handlers = config.handlers;
         this.compositor = config.compositor ?? null;
         this.instanceId = config.instanceId ?? "unknown";
+        this.toolRegistry = new ToolRegistry(this.handlers);
         // Shell-history-shaped log. Default writes go through the advisable
         // `history:append` handler registered below; extensions swap the
         // backend without touching this wiring.
@@ -117,7 +115,7 @@ export class AgentLoop {
             : [{ model: config.llmClient.model }];
         this.currentModeIndex = config.initialModeIndex ?? 0;
         // Tool protocol — controls how tools are presented to the LLM
-        this.toolProtocol = createToolProtocol(getSettings().toolMode ?? "api");
+        this.toolProtocol = createToolProtocol(getSettings().toolMode ?? "api", getSettings().coreTools ?? []);
         // Register core tools
         this.registerCoreTools();
         // Register any protocol-provided tools (e.g. load_tool for deferred-lookup).
@@ -291,7 +289,6 @@ export class AgentLoop {
                 return;
             }
             this.thinkingLevel = level;
-            this.bus.emit("ui:info", { message: `Thinking: ${level}` });
             this.bus.emit("config:changed", {});
         });
         onPipe("config:get-thinking", () => {
@@ -387,7 +384,7 @@ export class AgentLoop {
         }
         this.boundPipeListeners = [];
     }
-    /** Register a tool (used by extensions via ctx.registerTool). */
+    /** Register a tool (used by extensions via ctx.agent.registerTool). */
     registerTool(tool) {
         this.toolRegistry.register(tool);
     }
@@ -409,18 +406,23 @@ export class AgentLoop {
     /** Register a named instruction block for the system prompt. */
     registerInstruction(name, text, extensionName) {
         this.instructions.set(name, { text, extensionName });
+        this.handlers.define(`instruction:${name}`, () => this.instructions.get(name)?.text ?? "");
     }
-    /** Remove a named instruction block. */
     removeInstruction(name) {
         this.instructions.delete(name);
+        // Handler entry retained so external advisors survive a reload of the owner.
     }
     /** Register a named skill (on-demand reference material). */
     registerSkill(name, description, filePath, extensionName) {
         this.skills.set(name, { description, filePath, extensionName });
+        this.handlers.define(`skill:${name}:view`, () => {
+            const s = this.skills.get(name);
+            return { description: s?.description ?? "", filePath: s?.filePath ?? "" };
+        });
     }
-    /** Remove a registered skill. */
     removeSkill(name) {
         this.skills.delete(name);
+        // Handler entry retained so external advisors survive a reload of the owner.
     }
     /**
      * Build the system prompt grouped by extension.
@@ -434,13 +436,15 @@ export class AgentLoop {
     buildExtensionSections() {
         const groups = new Map();
         const ensure = (name) => groups.get(name) ?? (groups.set(name, { tools: [], skills: [], instructions: [] }).get(name));
-        // Attribute instructions
-        for (const { text, extensionName } of this.instructions.values()) {
+        // Attribute instructions — read text through the advisor chain
+        for (const [name, { extensionName }] of this.instructions) {
+            const text = this.handlers.call(`instruction:${name}`);
             ensure(extensionName).instructions.push({ text });
         }
-        // Attribute skills
-        for (const [skillName, { description, filePath, extensionName }] of this.skills) {
-            ensure(extensionName).skills.push({ name: skillName, description, filePath });
+        // Attribute skills — read description/filePath through the advisor chain
+        for (const [skillName, { extensionName }] of this.skills) {
+            const view = this.handlers.call(`skill:${skillName}:view`);
+            ensure(extensionName).skills.push({ name: skillName, description: view.description, filePath: view.filePath });
         }
         // Attribute tools (skip built-in scratchpad tools).
         // In "api" mode the full tool schemas are in the API `tools` param,
@@ -453,7 +457,7 @@ export class AgentLoop {
                 "bash", "read_file", "write_file", "edit_file", "grep", "glob", "ls",
                 "list_skills",
             ]);
-            for (const tool of this.toolRegistry.all()) {
+            for (const tool of this.toolRegistry.allView()) {
                 if (builtinTools.has(tool.name))
                     continue;
                 const extName = this.toolExtensions.get(tool.name);
@@ -832,6 +836,8 @@ export class AgentLoop {
         h.define("conversation:nucleate-user", (text, iid, seq) => nucleate("user", text, iid, seq));
         h.define("conversation:nucleate-agent", (text, iid, seq) => nucleate("agent", text, iid, seq));
         h.define("conversation:nucleate-tool", (toolName, args, content, isError, iid, seq) => nucleate(isError ? "error" : "tool", toolName, args, content, isError, iid, seq));
+        h.define("conversation:allocate-seq", () => this.conversation.allocateSeq());
+        h.define("conversation:reset-for-session", (nextSeq) => this.conversation.resetForSession(nextSeq));
         // Read-only views into the nuclear state, for compact strategies
         // and introspect that read without replacing.
         h.define("conversation:get-nuclear-entries", () => this.conversation.getNuclearEntries());
@@ -858,6 +864,11 @@ export class AgentLoop {
         h.define("history:search", async (query) => this.history.search(query));
         h.define("history:find-by-seq", async (seq) => this.history.findBySeq(seq));
         h.define("history:read-recent", async (max) => this.history.readRecent(max));
+        h.define("history:get-branch", async (leafSeq) => this.history.getBranch ? this.history.getBranch(leafSeq) : this.history.readRecent());
+        h.define("history:get-tree", async () => this.history.getTree ? this.history.getTree() : this.history.readRecent());
+        h.define("history:set-leaf", (seq) => {
+            this.history.setLeaf?.(seq);
+        });
         // Prior-session preamble renderer. Default: flat chronological list.
         h.define("conversation:format-prior-history", (entries) => {
             if (!entries || entries.length === 0)
@@ -910,74 +921,6 @@ export class AgentLoop {
                 return { content: msg, exitCode: 1, isError: true };
             }
             const display = tool.getDisplayInfo?.(args) ?? { kind: "execute" };
-            let diffShown = false;
-            // Permission gating
-            if (tool.requiresPermission) {
-                let permKind = "tool-call";
-                let permTitle = typeof args.description === "string"
-                    ? `${name}: ${args.description}`
-                    : name;
-                let metadata = { args };
-                // For file-modifying tools, pre-compute diff for display
-                if (tool.modifiesFiles && typeof args.path === "string") {
-                    try {
-                        const absPath = path.resolve(process.cwd(), args.path);
-                        let diff;
-                        if (typeof args.old_text === "string" && typeof args.new_text === "string") {
-                            // edit_file — read the file so line numbers are real (not relative to the edit region)
-                            const normalizedOld = args.old_text.replace(/\r\n/g, "\n");
-                            const normalizedNew = args.new_text.replace(/\r\n/g, "\n");
-                            try {
-                                const oldFileContent = await fs.readFile(absPath, "utf-8");
-                                diff = computeEditDiff(oldFileContent, normalizedOld, normalizedNew, args.replace_all === true);
-                            }
-                            catch {
-                                // File doesn't exist yet — fall back to input-only diff
-                                diff = computeInputDiff(normalizedOld, normalizedNew);
-                            }
-                        }
-                        else if (typeof args.content === "string") {
-                            // write_file — still need to read the old file for comparison
-                            let oldContent = null;
-                            try {
-                                oldContent = await fs.readFile(absPath, "utf-8");
-                            }
-                            catch { /* new file */ }
-                            if (oldContent !== null) {
-                                diff = computeDiff(oldContent, args.content);
-                            }
-                        }
-                        if (diff && !diff.isIdentical) {
-                            permKind = "file-write";
-                            // Shorten path for display
-                            const cwd = process.cwd();
-                            const home = process.env.HOME ?? os.homedir();
-                            let displayPath = absPath;
-                            if (absPath.startsWith(cwd + "/"))
-                                displayPath = absPath.slice(cwd.length + 1);
-                            else if (home && absPath.startsWith(home + "/"))
-                                displayPath = "~/" + absPath.slice(home.length + 1);
-                            permTitle = displayPath;
-                            metadata = { args, diff };
-                            diffShown = true;
-                        }
-                    }
-                    catch { /* fall back to generic permission */ }
-                }
-                const ui = this.compositor
-                    ? createToolUI(this.bus, this.compositor.surface("agent"))
-                    : undefined;
-                const perm = await this.bus.emitPipeAsync("permission:request", {
-                    kind: permKind,
-                    title: permTitle,
-                    metadata,
-                    ui,
-                    decision: { outcome: "approved" },
-                });
-                if (perm.decision.outcome !== "approved") {
-                    return { content: "Permission denied by user.", exitCode: 1, isError: true };
-                }
-            }
             // Emit tool-started for TUI
             const label = tool.displayName ?? name;
             this.bus.emit("agent:tool-started", {
@@ -985,21 +928,19 @@ export class AgentLoop {
                 toolCallId: id,
                 kind: display.kind, icon: display.icon, locations: display.locations, rawInput: args,
                 displayDetail: tool.formatCall?.(args),
+                sourceLanguage: display.sourceLanguage,
                 batchIndex: ctx.batchIndex, batchTotal: ctx.batchTotal,
             });
             this.bus.emit("agent:tool-call", { tool: name, args });
             // Execute — use ctx.onChunk so advisors can wrap the streaming callback.
-            // Suppress streaming output if diff was already shown.
-            const onChunk = (tool.showOutput !== false && !diffShown)
-                ? ctx.onChunk
-                : undefined;
+            const onChunk = tool.showOutput !== false ? ctx.onChunk : undefined;
             const toolCtx = { signal };
             if (this.compositor) {
                 toolCtx.ui = createToolUI(this.bus, this.compositor.surface("agent"));
             }
             let result;
             try {
-                result = await raceAbort(tool.execute(args, onChunk, toolCtx), signal);
+                result = await raceAbort(this.toolRegistry.call(name, args, onChunk, toolCtx), signal);
             }
             catch (err) {
                 if (signal.aborted) {
@@ -1192,9 +1133,11 @@ export class AgentLoop {
                 catch { /* not an error payload, continue */ }
                 const tool = this.toolRegistry.get(tc.name);
                 if (!tool) {
+                    const available = this.toolRegistry.all().map((t) => t.name).join(", ");
                     collectedResults.push({
                         callId: tc.id, toolName: tc.name,
-                        content: `Unknown tool "${tc.name}"`, isError: true,
+                        content: `Unknown tool "${tc.name}". Available tools: ${available}`,
+                        isError: true,
                     });
                     return;
                 }
@@ -1214,7 +1157,7 @@ export class AgentLoop {
                 // normalize-args.ts for the diagnostic that uncovered this.
                 args = normalizeToolArgs(args, tool.input_schema);
                 // ── Round-scoped cache for cacheable read-only tools ──
-                const cacheable = !tool.modifiesFiles && !tool.requiresPermission && tool.showOutput !== true;
+                const cacheable = !tool.modifiesFiles && tool.showOutput !== true;
                 const cacheKey = cacheable ? `${tc.name}:${JSON.stringify(args)}` : null;
                 if (cacheKey) {
                     const cached = roundCache.get(cacheKey);
@@ -1225,6 +1168,7 @@ export class AgentLoop {
                             toolCallId: tc.id,
                             kind: display.kind, icon: display.icon, locations: display.locations, rawInput: args,
                             displayDetail: tool.formatCall?.(args),
+                            sourceLanguage: display.sourceLanguage,
                             batchIndex, batchTotal: batchTotal > 1 ? batchTotal : undefined,
                         });
                         this.bus.emit("agent:tool-call", { tool: tc.name, args });
@@ -1254,9 +1198,9 @@ export class AgentLoop {
                 const result = await this.handlers.call("tool:execute", { name: tc.name, id: tc.id, args, tool, onChunk: defaultOnChunk,
                     batchIndex, batchTotal: batchTotal > 1 ? batchTotal : undefined,
                     signal });
-                // Truncate large outputs to avoid blowing context
+                // Truncate large outputs to avoid blowing context.
                 let content = result.content;
-                const maxBytes = 16_384; // ~4k tokens
+                const maxBytes = tool.maxResultBytes ?? 16_384; // ~4k tokens
                 if (content.length > maxBytes) {
                     const headBytes = Math.floor(maxBytes * 0.6);
                     const tailBytes = maxBytes - headBytes;
@@ -1287,12 +1231,11 @@ export class AgentLoop {
                 }
                 collectedResults.push(finalResult);
             };
-            // Partition into parallel-safe (read-only) and sequential (needs permission)
             const parallel = [];
             const sequential = [];
             for (const tc of toolCalls) {
                 const tool = this.toolRegistry.get(tc.name);
-                if (tool && !tool.requiresPermission && !tool.modifiesFiles) {
+                if (tool && !tool.modifiesFiles) {
                     parallel.push(tc);
                 }
                 else {
@@ -1536,8 +1479,9 @@ export class AgentLoop {
         const reasoningDetailsByIndex = new Map();
         const pendingToolCalls = [];
         // Tool protocol controls what goes in the API tools param vs dynamic context
-        const apiTools = this.toolProtocol.getApiTools(this.toolRegistry.all());
-        const toolPrompt = this.toolProtocol.getToolPrompt(this.toolRegistry.all());
+        const toolView = this.toolRegistry.allView();
+        const apiTools = this.toolProtocol.getApiTools(toolView);
+        const toolPrompt = this.toolProtocol.getToolPrompt(toolView);
         // Dynamic context rides on the trailing message — see
         // wrapTrailingWithDynamicContext for the cache-stability rationale.
         const rawMessages = [

package/dist/agent/conversation-state.d.ts

@@ -97,6 +97,15 @@ export declare class ConversationState {
     /** Track an entry in memory (nuclear list + recall archive). */
     private recordNuclearEntry;
     private appendToHistory;
+    /** Bump and return the global sequence counter. For extensions that
+     *  synthesize their own NuclearEntries (e.g. compaction summaries that
+     *  should land in the same sequence space as kernel-produced entries). */
+    allocateSeq(): number;
+    /** Clear nuclear bookkeeping and reset the seq counter. For extensions
+     *  that swap sessions (multi-session history adapters) so the in-memory
+     *  nuclear list, recall archive, and seq counter don't carry over from
+     *  the previous session's tree. */
+    resetForSession(nextSeq: number): void;
     updateApiTokenCount(promptTokens: number): void;
     estimatePromptTokens(): number;
     estimateTokens(): number;

package/dist/agent/conversation-state.js

@@ -331,6 +331,22 @@ export class ConversationState {
             return;
         this.handlers.call("history:append", entries);
     }
+    /** Bump and return the global sequence counter. For extensions that
+     *  synthesize their own NuclearEntries (e.g. compaction summaries that
+     *  should land in the same sequence space as kernel-produced entries). */
+    allocateSeq() {
+        return this.nextSeq++;
+    }
+    /** Clear nuclear bookkeeping and reset the seq counter. For extensions
+     *  that swap sessions (multi-session history adapters) so the in-memory
+     *  nuclear list, recall archive, and seq counter don't carry over from
+     *  the previous session's tree. */
+    resetForSession(nextSeq) {
+        this.nuclearEntries = [];
+        this.nuclearBySeq.clear();
+        this.recallArchive.clear();
+        this.nextSeq = nextSeq;
+    }
     // ── Token estimation ──────────────────────────────────────────
     updateApiTokenCount(promptTokens) {
         this.lastApiTokenCount = promptTokens;

package/dist/agent/history-file.d.ts

@@ -7,6 +7,12 @@ export interface HistoryAdapter {
         line: string;
     }[]>;
     findBySeq(seq: number): Promise<NuclearEntry | null>;
+    /** Walk parent pointers from a leaf back to the root. Tree-aware adapters only. */
+    getBranch?(leafSeq: number): Promise<NuclearEntry[]>;
+    /** Return every entry, including sibling branches. Tree-aware adapters only. */
+    getTree?(): Promise<NuclearEntry[]>;
+    /** Move the active leaf for the next append. Tree-aware adapters only. */
+    setLeaf?(seq: number): void;
 }
 export declare class InMemoryHistory implements HistoryAdapter {
     private entries;

package/dist/agent/history-file.js

@@ -9,7 +9,7 @@ import * as fs from "node:fs/promises";
 import * as fss from "node:fs";
 import * as path from "node:path";
 import * as crypto from "node:crypto";
-import { CONFIG_DIR, getSettings } from "../settings.js";
+import { CONFIG_DIR, getSettings } from "../core/settings.js";
 import { serializeEntry, deserializeEntry, isReadOnly, compileSearchRegex, matchEntry, } from "./nuclear-form.js";
 const HISTORY_PATH = path.join(CONFIG_DIR, "history");
 const LOCK_STALE_MS = 10_000; // consider lock stale after 10s

package/dist/agent/host-types.d.ts

@@ -0,0 +1,125 @@
+import type { CoreConfig, CoreContext } from "../core/types.js";
+import type { HistoryAdapter } from "./history-file.js";
+import type { SkillView, ToolDefinition, ToolExecutionContext, ToolSchemaView } from "./types.js";
+/**
+ * Backend-agnostic LLM interface exposed via `ctx.agent.llm`. Fulfilled
+ * by defining an `llm:invoke` handler; backends 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;
+    /** `model` overrides the globally-configured model for this call only.
+     *  Provider-specific identifier (e.g. "claude-haiku-4-5"). When omitted,
+     *  the active provider's configured default is used.
+     *
+     *  `reasoningEffort` controls thinking-model token allocation between
+     *  reasoning and final content (e.g. "low", "medium", "high", or
+     *  provider-specific). For non-reasoning models it is ignored. Set to
+     *  "low" for cheap structured-output calls so reasoning doesn't exhaust
+     *  the max-tokens budget and leave content empty. */
+    ask(opts: {
+        query: string;
+        system?: string;
+        maxTokens?: number;
+        model?: string;
+        reasoningEffort?: string;
+    }): Promise<string>;
+    session(opts?: {
+        system?: string;
+        maxTokens?: number;
+        model?: string;
+        reasoningEffort?: string;
+    }): LlmSession;
+}
+/** A model entry in the cycling list, optionally tied to a provider. */
+export interface AgentMode {
+    model: string;
+    /** Provider id — when cycling changes provider, LlmClient is reconfigured. */
+    provider?: string;
+    /** Provider-specific config for reconfiguring LlmClient on switch. */
+    providerConfig?: {
+        apiKey: string;
+        baseURL?: string;
+    };
+    /** Context window size in tokens (for usage display). */
+    contextWindow?: number;
+    /** Max output tokens for this mode. */
+    maxTokens?: number;
+    /** Model supports reasoning/thinking tokens. */
+    reasoning?: boolean;
+    /** Provider supports the reasoning_effort parameter. */
+    supportsReasoningEffort?: boolean;
+    /** Echo reasoning_content back on assistant turns. Required by DeepSeek;
+     *  default off (leaky shims may forward it to the model as OOD input). */
+    echoReasoning?: boolean;
+    buildReasoningParams?: (level: string) => Record<string, unknown>;
+}
+/**
+ * Capabilities the agent host adds on top of CoreContext. Only available
+ * when the built-in agent backend is loaded; bridge backends pass a bare
+ * CoreContext, so extensions that need these should type as AgentContext.
+ */
+export interface AgentSurface {
+    llm: LlmInterface;
+    providers: {
+        configure: (id: string, opts: {
+            reasoningParams?: (level: string, model?: string) => Record<string, unknown>;
+        }) => void;
+    };
+    registerTool: (tool: ToolDefinition) => void;
+    unregisterTool: (name: string) => void;
+    adviseTool: (name: string, advisor: (next: ToolDefinition["execute"], args: Record<string, unknown>, onChunk?: (chunk: string) => void, ctx?: ToolExecutionContext) => ReturnType<ToolDefinition["execute"]>) => () => void;
+    adviseToolSchema: (name: string, advisor: (next: () => ToolSchemaView) => ToolSchemaView) => () => void;
+    getTools: () => ToolDefinition[];
+    registerInstruction: (name: string, text: string) => void;
+    removeInstruction: (name: string) => void;
+    adviseInstruction: (name: string, advisor: (next: () => string) => string) => () => void;
+    registerSkill: (name: string, description: string, filePath: string) => void;
+    removeSkill: (name: string) => void;
+    adviseSkill: (name: string, advisor: (next: () => SkillView) => SkillView) => () => void;
+    /**
+     * Register a context producer — a function that contributes a string
+     * (or `null` to skip) into one of two lifecycles:
+     *
+     * - `mode: "per-request"` (default) — fires on every LLM request,
+     *   including each tool-loop iteration. Output is ephemerally wrapped
+     *   in `<dynamic_context>` onto the trailing message at request time;
+     *   never persisted. Use for "current state" signals.
+     *
+     * - `mode: "per-query"` — fires once at user-query start. Output is
+     *   wrapped in `<query_context>` and frozen into the user message;
+     *   persists in conversation history.
+     *
+     * Returns a dispose fn that unregisters the producer.
+     */
+    registerContextProducer: (name: string, producer: () => string | null, opts?: {
+        mode?: "per-request" | "per-query";
+    }) => () => void;
+}
+/** Substrate + agent surface. Use this when an extension only touches
+ *  agent-side features (tools, instructions, LLM) and doesn't need
+ *  shell rendering. */
+export type AgentContext = CoreContext & {
+    agent: AgentSurface;
+};
+export interface AgentConfigSurface {
+    /** API key for OpenAI-compatible provider. */
+    apiKey?: string;
+    /** Base URL for OpenAI-compatible API. */
+    baseURL?: string;
+    /** Named provider to use from settings.json. */
+    provider?: string;
+    /** Default model id. */
+    model?: string;
+    /** Conversation history backend. Defaults to the on-disk HistoryFile. */
+    history?: HistoryAdapter;
+}
+export type AgentConfig = CoreConfig & AgentConfigSurface;

package/dist/agent/index.d.ts

@@ -1,11 +1,19 @@
 /**
- * Agent backend exports.
- *
- * The default backend is AgentLoop (in-process, OpenAI-compatible API).
- * Extensions can register alternative backends via agent:register-backend.
+ * Constructs the AgentLoop synchronously with a placeholder LlmClient,
+ * so core handlers (history:append, system-prompt:build, conversation:*)
+ * are defined before user extensions activate. Mode resolution is
+ * deferred to `core:extensions-loaded`, giving runtime-registered
+ * providers (e.g. openrouter) a chance to register before we look up
+ * settings.defaultProvider. Without this deferral, a persisted
+ * `defaultProvider: "openrouter"` loses to a cold-start race and the
+ * backend bails silently.
  */
+import type { ExtensionContext } from "../shell/host-types.js";
+export default function agentBackend(ctx: ExtensionContext): void;
 export type { AgentBackend } from "./types.js";
 export type { ToolDefinition, ToolResult, ToolDisplayInfo } from "./types.js";
 export { AgentLoop } from "./agent-loop.js";
 export { ToolRegistry } from "./tool-registry.js";
 export { runSubagent, type SubagentOptions } from "./subagent.js";
+/** Activate the ash backend and any provider whose key is configured. */
+export declare function activateAgent(ctx: ExtensionContext): void;