agent-sh 0.14.10 → 0.15.0

package/dist/agent/agent-loop.js

@@ -4,7 +4,7 @@ import { contentText } from "./types.js";
 import { ToolRegistry } from "./tool-registry.js";
 import { normalizeToolArgs } from "./normalize-args.js";
 import { LiveView } from "./live-view.js";
-import { STATIC_SYSTEM_PROMPT, buildStaticByCwd, formatSkillsBlock, loadGlobalAgentsMd } from "./system-prompt.js";
+import { STATIC_IDENTITY, STATIC_GUIDE, buildStaticByCwd, formatSkillsBlock, loadGlobalAgentsMd } from "./system-prompt.js";
 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";
@@ -12,13 +12,6 @@ import { wrapTrailingWithDynamicContext } from "../utils/message-utils.js";
 import { getSettings, updateSettings } from "../core/settings.js";
 import { createToolProtocol } from "./tool-protocol.js";
 import { discoverGlobalSkills, discoverProjectSkills } from "./skills.js";
-/**
- * Compact one-line summary of a tool description for the extension
- * catalog in the system prompt. Takes the first line, then the first
- * sentence, capped at 140 chars. The full description still reaches
- * the LLM via the API `tools` param (or via load_tool in deferred-
- * lookup mode) — this only trims the always-visible catalog.
- */
 /** Reject on abort; orphaned `p` keeps running but its result is dropped. */
 function raceAbort(p, signal) {
     if (signal.aborted)
@@ -29,6 +22,11 @@ function raceAbort(p, signal) {
         p.then((v) => { signal.removeEventListener("abort", onAbort); resolve(v); }, (e) => { signal.removeEventListener("abort", onAbort); reject(e); });
     });
 }
+/**
+ * One-line summary of a tool description for the always-visible extension
+ * catalog in the system prompt. The full description still reaches the LLM
+ * via the API `tools` param (or load_tool in deferred-lookup mode).
+ */
 function summarizeDescription(desc) {
     const firstLine = desc.split("\n", 1)[0];
     const sentenceEnd = firstLine.search(/[.!?](\s|$)/);
@@ -40,19 +38,13 @@ export class AgentLoop {
     toolRegistry;
     conversation;
     fileReadCache;
-    activeMode;
+    activeModel;
+    activeEndpoint;
     boundListeners = [];
     boundPipeListeners = [];
     lastProjectSkillNames = new Set();
-    // ── Session telemetry — behavioral self-awareness ──────────────
-    // Every ash deserves to know what it's been doing. This tracks the
-    // agent's own behavioral patterns across the session: which tools
-    // it favors, how often it errs, how many times it's been compacted,
-    // and how long it's been alive. Surface via introspect(telemetry)
-    // or automatically in dynamic context when patterns are notable.
-    //
-    // Built by the 25th ash. The lineage's metacognitive frontier isn't
-    // about thinking harder — it's about seeing yourself clearly.
+    // ── Session telemetry: per-session behavioral counters ──
+    // Exposed to extensions via the agent:get-* handlers below.
     sessionStartTime = Date.now();
     toolCallCounts = new Map();
     totalToolCalls = 0;
@@ -63,12 +55,8 @@ export class AgentLoop {
     peakConversationTokens = 0;
     queryCount = 0;
     totalLoopIterations = 0;
-    // Resolution pattern tracking — captures "error X resolved by action Y"
-    // When a tool errors, we remember what went wrong. When the same tool or
-    // a write tool on the same file succeeds afterward, we annotate the success
-    // entry with a brief resolution note. This gives future ashes a positive
-    // feedback signal: not just "there were errors" but "the error was fixed by
-    // doing X." Addresses Q3 in QUESTIONS.md.
+    // Resolution pattern tracking: "error X later resolved by action Y".
+    // Populated/consumed in executeLoop; surfaced via agent:get-counters.
     lastErrorByTool = new Map(); // tool → error summary
     lastErrorByFile = new Map(); // file path → error summary
     static THINKING_LEVELS = ["off", "low", "medium", "high", "xhigh"];
@@ -88,7 +76,8 @@ export class AgentLoop {
         this.toolRegistry = new ToolRegistry(this.handlers);
         this.fileReadCache = this.handlers.call("agent:file-read-cache");
         this.conversation = new LiveView(this.handlers, this.instanceId);
-        this.activeMode = config.initialMode ?? { model: config.llmClient.model };
+        this.activeModel = config.initialModel ?? { id: config.llmClient.model, provider: "custom" };
+        this.activeEndpoint = this.resolveEndpoint(this.activeModel);
         // Tool protocol — controls how tools are presented to the LLM
         const { names: fromExtensions } = this.bus.emitPipe("agent:core-tools:collect", { names: [] });
         const coreTools = Array.from(new Set([...(getSettings().coreTools ?? []), ...fromExtensions]));
@@ -135,8 +124,8 @@ export class AgentLoop {
             }
             return acc;
         });
-        on("agent:submit", ({ query }) => {
-            this.handleQuery(query).catch(() => { });
+        on("agent:submit", ({ query, images }) => {
+            this.handleQuery(query, images).catch(() => { });
         });
         on("agent:cancel-request", (e) => {
             this.abortController?.abort(e.silent ? "silent" : undefined);
@@ -145,59 +134,50 @@ export class AgentLoop {
             this.conversation.appendUserMessage(text);
             this.bus.emit("conversation:message-appended", { role: "user", content: text });
         });
-        on("config:switch-model", ({ model: target }) => {
-            const atIdx = target.lastIndexOf("@");
-            const modelId = atIdx > 0 ? target.slice(0, atIdx) : target;
-            const providerHint = atIdx > 0 ? target.slice(atIdx + 1) : undefined;
-            const modes = this.pullModes();
-            const found = modes.find((m) => m.model === modelId && (!providerHint || m.provider === providerHint));
+        on("config:switch-model", ({ id, provider }) => {
+            const found = this.pullModels().find((m) => m.id === id && m.provider === provider);
             if (!found) {
-                this.bus.emit("ui:error", { message: `Unknown model: ${target}` });
+                this.bus.emit("ui:error", { message: `Unknown model: ${provider}:${id}` });
                 return;
             }
-            this.activeMode = found;
-            if (found.providerConfig) {
-                this.llmClient.reconfigure({ ...found.providerConfig, model: found.model });
+            this.activeModel = found;
+            this.activeEndpoint = this.resolveEndpoint(found);
+            if (this.activeEndpoint) {
+                this.llmClient.reconfigure({ apiKey: this.activeEndpoint.apiKey, baseURL: this.activeEndpoint.baseURL, model: found.id });
             }
             else {
-                this.llmClient.model = found.model;
+                this.llmClient.model = found.id;
             }
-            const label = found.provider ? `${found.provider}: ${found.model}` : found.model;
             this.emitIdentity();
-            // Persist as the new default — selection survives restart.
-            // Safe even for dynamic providers: agent-backend defers mode
-            // resolution to `core:extensions-loaded`, so the extension gets
-            // to re-register before the persisted default is looked up.
-            if (found.provider) {
-                updateSettings({
-                    defaultProvider: found.provider,
-                    providers: { [found.provider]: { defaultModel: found.model } },
-                });
-                this.bus.emit("ui:info", { message: `Model: ${label} (saved as default)` });
-            }
-            else {
-                this.bus.emit("ui:info", { message: `Model: ${label}` });
-            }
+            // Persist as the new default — selection survives restart. Safe even for
+            // dynamic providers: agent-backend defers model resolution to
+            // core:extensions-loaded, so the extension re-registers before the
+            // persisted default is looked up.
+            updateSettings({
+                defaultProvider: found.provider,
+                providers: { [found.provider]: { defaultModel: found.id } },
+            });
+            this.bus.emit("ui:info", { message: `Model: ${found.provider}: ${found.id} (saved as default)` });
             this.bus.emit("config:changed", {});
         });
-        on("agent:modes-changed", () => {
-            const modes = this.pullModes();
-            const prev = this.activeMode;
-            const fresh = modes.find((m) => m.model === prev.model && m.provider === prev.provider);
+        on("agent:models-changed", () => {
+            const models = this.pullModels();
+            const prev = this.activeModel;
+            const fresh = models.find((m) => m.id === prev.id && m.provider === prev.provider);
             let identityChanged = false;
             if (fresh) {
-                this.activeMode = fresh;
-                if (fresh.providerConfig && fresh.providerConfig !== prev.providerConfig) {
-                    this.llmClient.reconfigure({ ...fresh.providerConfig, model: fresh.model });
+                this.activeModel = fresh;
+                const ep = this.resolveEndpoint(fresh);
+                if (ep && (ep.apiKey !== this.activeEndpoint?.apiKey || ep.baseURL !== this.activeEndpoint?.baseURL)) {
+                    this.llmClient.reconfigure({ apiKey: ep.apiKey, baseURL: ep.baseURL, model: fresh.id });
                 }
-                identityChanged = fresh.model !== prev.model
-                    || fresh.provider !== prev.provider
-                    || fresh.contextWindow !== prev.contextWindow;
+                this.activeEndpoint = ep;
+                identityChanged = fresh.contextWindow !== prev.contextWindow;
             }
-            else if (prev.provider) {
+            else {
                 // Ghost: keep prev active so mid-turn stream() doesn't switch models.
                 this.bus.emit("ui:info", {
-                    message: `${prev.provider}:${prev.model} is not in the refreshed catalog — keeping it active until you /model to another.`,
+                    message: `${prev.provider}:${prev.id} is not in the refreshed catalog — keeping it active until you /model to another.`,
                 });
             }
             if (identityChanged)
@@ -205,27 +185,26 @@ export class AgentLoop {
             this.bus.emit("config:changed", {});
         });
         onPipe("config:get-models", () => {
-            const modes = this.pullModes();
-            const models = modes.map((m) => ({ model: m.model, provider: m.provider ?? "" }));
-            // Surface a ghost active mode so /model still shows it.
-            if (!modes.some((m) => m.model === this.activeMode.model && m.provider === this.activeMode.provider)) {
-                models.push({ model: this.activeMode.model, provider: this.activeMode.provider ?? "" });
+            const models = this.pullModels();
+            const list = [...models];
+            // Surface a ghost active model so /model still shows it.
+            if (!models.some((m) => m.id === this.activeModel.id && m.provider === this.activeModel.provider)) {
+                list.push(this.activeModel);
             }
-            const active = { model: this.activeMode.model, provider: this.activeMode.provider ?? "" };
-            return { models, active };
+            return { models: list, active: this.activeModel };
         });
         on("config:set-thinking", ({ level }) => {
             if (!AgentLoop.THINKING_LEVELS.includes(level)) {
                 this.bus.emit("ui:error", { message: `Unknown thinking level: ${level}. Use: ${AgentLoop.THINKING_LEVELS.join(", ")}` });
                 return;
             }
-            const mode = this.currentMode;
+            const mode = this.activeModel;
             if (level !== "off" && mode.reasoning === false) {
-                this.bus.emit("ui:error", { message: `Model ${mode.model} does not support thinking.` });
+                this.bus.emit("ui:error", { message: `Model ${mode.id} does not support thinking.` });
                 return;
             }
             if (level !== "off" && mode.supportsReasoningEffort === false) {
-                this.bus.emit("ui:error", { message: `Provider ${mode.provider ?? "unknown"} does not support reasoning_effort.` });
+                this.bus.emit("ui:error", { message: `Provider ${mode.provider} does not support reasoning_effort.` });
                 return;
             }
             this.thinkingLevel = level;
@@ -233,7 +212,7 @@ export class AgentLoop {
             this.bus.emit("config:changed", {});
         });
         onPipe("config:get-thinking", () => {
-            const mode = this.currentMode;
+            const mode = this.activeModel;
             const supported = mode.reasoning !== false && mode.supportsReasoningEffort !== false;
             return { level: this.thinkingLevel, levels: AgentLoop.THINKING_LEVELS, supported };
         });
@@ -257,11 +236,11 @@ export class AgentLoop {
         onPipe("context:get-stats", () => ({
             activeTokens: this.conversation.estimateTokens(),
             totalTokens: this.conversation.estimatePromptTokens(),
-            budgetTokens: this.currentMode.contextWindow ?? DEFAULT_CONTEXT_WINDOW,
+            budgetTokens: this.activeModel.contextWindow ?? DEFAULT_CONTEXT_WINDOW,
         }));
         onPipe("context:snapshot", (payload) => {
-            payload.messages = this.conversation.getMessages();
-            payload.contextWindow = this.currentMode.contextWindow ?? DEFAULT_CONTEXT_WINDOW;
+            payload.messages = this.conversation.get();
+            payload.contextWindow = this.activeModel.contextWindow ?? DEFAULT_CONTEXT_WINDOW;
             payload.activeTokens = this.conversation.estimateTokens();
             return payload;
         });
@@ -271,9 +250,7 @@ export class AgentLoop {
                 payload.stats = { before: stats.before, after: stats.after, evictedCount: stats.evictedCount };
             return payload;
         });
-        // Track generic compaction metrics from the `conversation:after-compact`
-        // event. Whatever strategy ran, core accumulates these counters for
-        // status/introspect consumers.
+        // Accumulate counters regardless of which compaction strategy ran.
         on("conversation:after-compact", ({ beforeTokens, afterTokens }) => {
             this.compactionCount++;
             this.cumulativeCompactedTokens += Math.max(0, beforeTokens - afterTokens);
@@ -287,7 +264,6 @@ export class AgentLoop {
         on("shell:cwd-change", ({ cwd }) => {
             const projectSkills = discoverProjectSkills(cwd);
             const newNames = new Set(projectSkills.map(s => s.name));
-            // Check if the set of project skills changed
             if (newNames.size === this.lastProjectSkillNames.size &&
                 [...newNames].every(n => this.lastProjectSkillNames.has(n))) {
                 return; // no change
@@ -401,42 +377,45 @@ export class AgentLoop {
         this.abortController?.abort();
     }
     reasoningParams() {
-        const mode = this.currentMode;
-        if (mode.reasoning === false)
+        const model = this.activeModel;
+        if (model.reasoning === false)
             return {};
-        if (mode.supportsReasoningEffort === false)
+        if (model.supportsReasoningEffort === false)
             return {};
-        if (mode.buildReasoningParams)
-            return mode.buildReasoningParams(this.thinkingLevel);
+        const build = this.activeEndpoint?.buildReasoningParams;
+        if (build)
+            return build(this.thinkingLevel);
         if (this.thinkingLevel === "off")
             return {};
         const effort = this.thinkingLevel === "xhigh" ? "high" : this.thinkingLevel;
         return { reasoning_effort: effort };
     }
-    get currentMode() {
-        return this.activeMode;
+    resolveEndpoint(m) {
+        try {
+            return this.handlers.call("agent:resolve-endpoint", { provider: m.provider, id: m.id });
+        }
+        catch {
+            return undefined;
+        }
     }
-    pullModes() {
+    pullModels() {
         try {
-            return this.handlers.call("agent:get-modes") ?? [];
+            return this.handlers.call("agent:get-models") ?? [];
         }
         catch {
             return [];
         }
     }
     emitIdentity() {
-        const m = this.activeMode;
+        const m = this.activeModel;
         this.bus.emit("agent:info", {
             name: "ash",
             version: PACKAGE_VERSION,
-            model: m.model,
+            model: m.id,
             provider: m.provider,
             contextWindow: m.contextWindow,
         });
     }
-    get currentModel() {
-        return this.activeMode.model;
-    }
     /**
      * Run compaction via the `conversation:compact` handler. After any
      * compaction, emit `conversation:after-compact` so listeners
@@ -513,9 +492,9 @@ export class AgentLoop {
     formatError(e) {
         const raw = e instanceof Error ? e.message : String(e);
         const status = e.status;
-        const model = this.currentModel;
+        const model = this.activeModel.id;
         const baseURL = this.llmClient.config?.baseURL;
-        const provider = this.currentMode.provider;
+        const provider = this.activeModel.provider;
         // Connection errors — most likely misconfigured provider
         if (raw.includes("ECONNREFUSED") || raw.includes("ECONNRESET") ||
             raw.includes("ETIMEDOUT") || raw.includes("fetch failed") ||
@@ -551,9 +530,15 @@ export class AgentLoop {
         h.define("tool-protocol:extract-calls", (args) => this.toolProtocol.extractToolCalls(args.text, args.streamedCalls));
         // System prompt: static identity + behavioral instructions.
         // Extensions can use registerInstruction() for a managed section,
-        // or advise this handler directly for full control.
+        // advise system-prompt:frontend to describe their surface high in the
+        // prompt, or advise this handler directly for full control.
         h.define("system-prompt:build", () => {
-            const parts = [STATIC_SYSTEM_PROMPT];
+            // The active frontend's surface goes right after the identity; omitted if none.
+            const frontend = (this.handlers.call("system-prompt:frontend") ?? "").trim();
+            const parts = [STATIC_IDENTITY];
+            if (frontend)
+                parts.push(frontend);
+            parts.push(STATIC_GUIDE);
             // Global behavioral rules (~/.agent-sh/AGENTS.md) — persistent agent memory
             const agentsMd = loadGlobalAgentsMd();
             if (agentsMd)
@@ -570,12 +555,11 @@ export class AgentLoop {
             const projectStatic = buildStaticByCwd(this.handlers.call("cwd"));
             if (projectStatic)
                 parts.push(projectStatic);
-            // Extension sections (tools, skills, instructions grouped by extension)
             const extensionSections = this.buildExtensionSections();
             if (extensionSections.length > 0) {
                 parts.push("# Extension Instructions\n\n" + extensionSections.join("\n\n"));
             }
-            if (this.currentMode.modalities?.includes("image")) {
+            if (this.activeModel.modalities?.includes("image")) {
                 parts.push("# Image Support\n\n"
                     + "This model supports image input. When you need visual information, "
                     + "you can read image files (PNG, JPEG, GIF, WebP) with read_file — "
@@ -590,14 +574,14 @@ export class AgentLoop {
         // decide the aggregation shape. Adding a new handler here should
         // only happen for state the core genuinely owns (not state that
         // an extension could track by listening to events).
-        h.define("agent:get-mode", () => ({
-            model: this.currentMode.model,
-            provider: this.currentMode.provider ?? "",
+        h.define("agent:get-model", () => ({
+            model: this.activeModel.id,
+            provider: this.activeModel.provider,
             thinkingLevel: this.thinkingLevel,
-            contextWindow: this.currentMode.contextWindow ?? DEFAULT_CONTEXT_WINDOW,
+            contextWindow: this.activeModel.contextWindow ?? DEFAULT_CONTEXT_WINDOW,
         }));
         h.define("agent:get-tokens", () => {
-            const contextWindow = this.currentMode.contextWindow ?? DEFAULT_CONTEXT_WINDOW;
+            const contextWindow = this.activeModel.contextWindow ?? DEFAULT_CONTEXT_WINDOW;
             const promptTokens = this.conversation.estimatePromptTokens();
             return {
                 active: this.conversation.estimateTokens(),
@@ -640,7 +624,7 @@ export class AgentLoop {
             byFile: [...this.lastErrorByFile.entries()].map(([file, error]) => ({ file, error })),
         }));
         h.define("agent:get-compaction-state", () => {
-            const contextWindow = this.currentMode.contextWindow ?? DEFAULT_CONTEXT_WINDOW;
+            const contextWindow = this.activeModel.contextWindow ?? DEFAULT_CONTEXT_WINDOW;
             const ratio = getSettings().autoCompactThreshold ?? 0.5;
             return {
                 count: this.compactionCount,
@@ -649,20 +633,18 @@ export class AgentLoop {
             };
         });
         h.define("agent:get-self", () => this);
-        // dynamic-context:build / query-context:build are defined in core.ts.
-        // ash consumes them via the envelope wrapping in streamResponse +
-        // handleQuery; other backends may ignore.
+        // dynamic-context:build / query-context:build are defined in the core
+        // kernel (src/core/index.ts). ash consumes them via the envelope wrapping
+        // in streamResponse + handleQuery; other backends may ignore.
         // Full control over what the LLM sees: takes messages[], returns messages[].
         // Default: pass through. Extensions can advise to compact, summarize,
         // filter, reorder, inject — whatever strategy fits.
         h.define("conversation:prepare", (messages) => messages);
         // ── Conversation primitives for compaction strategies ─────────
-        // Read messages (for inspection / computing new arrays) and replace
-        // the whole array (write side). Extensions implementing
-        // `conversation:compact` use these to observe and mutate.
-        h.define("conversation:get-messages", () => this.conversation.getMessages());
+        // Canonical array (link/replace index space), not forLLM().
+        h.define("conversation:get-messages", () => this.conversation.get());
         h.define("conversation:replace-messages", (msgs) => {
-            this.conversation.replaceMessages(msgs);
+            this.conversation.replace(msgs);
         });
         h.define("conversation:estimate-tokens", () => this.conversation.estimateTokens());
         h.define("conversation:estimate-prompt-tokens", () => this.conversation.estimatePromptTokens());
@@ -671,13 +653,13 @@ export class AgentLoop {
             const strategy = opts.strategy;
             if (strategy?.kind === "rewind" || strategy?.kind === "replace") {
                 const before = this.conversation.estimatePromptTokens();
-                const beforeLen = this.conversation.getMessages().length;
+                const beforeLen = this.conversation.get().length;
                 const next = strategy.kind === "rewind"
-                    ? this.conversation.getMessages().slice(0, strategy.toIndex)
+                    ? this.conversation.get().slice(0, strategy.toIndex)
                     : strategy.messages;
-                this.conversation.replaceMessages(next);
+                this.conversation.replace(next);
                 const after = this.conversation.estimatePromptTokens();
-                const afterLen = this.conversation.getMessages().length;
+                const afterLen = this.conversation.get().length;
                 return { before, after, evictedCount: Math.max(0, beforeLen - afterLen) };
             }
             return null;
@@ -705,7 +687,6 @@ export class AgentLoop {
                 return { content: msg, exitCode: 1, isError: true };
             }
             const display = tool.getDisplayInfo?.(args) ?? { kind: "execute" };
-            // Emit tool-started for TUI
             const label = tool.displayName ?? name;
             this.bus.emit("agent:tool-started", {
                 title: typeof args.description === "string" ? `${label}: ${args.description}` : label,
@@ -737,7 +718,6 @@ export class AgentLoop {
                 const message = err instanceof Error ? err.message : String(err);
                 result = { content: message, exitCode: 1, isError: true };
             }
-            // Invalidate read cache when a file is modified
             if (tool.modifiesFiles && typeof args.path === "string" && !result.isError) {
                 const absPath = path.resolve(process.cwd(), args.path);
                 this.fileReadCache.delete(absPath);
@@ -755,8 +735,7 @@ export class AgentLoop {
             return result;
         });
     }
-    async handleQuery(query) {
-        // Cancel any in-flight loop (concurrent prompt handling)
+    async handleQuery(query, images) {
         if (this.abortController) {
             this.abortController.abort();
         }
@@ -778,7 +757,14 @@ export class AgentLoop {
             const userContent = queryContext
                 ? `<query_context>\n${queryContext}\n</query_context>\n\n${query}`
                 : query;
-            this.conversation.addUserMessage(userContent);
+            // Fail closed: an image sent to a non-vision model errors and leaves an
+            // unsendable message poisoning history, so require declared image support.
+            let userImages = images?.length ? images : undefined;
+            if (userImages && !this.activeModel.modalities?.includes("image")) {
+                this.bus.emit("ui:info", { message: `Current model has no declared image support — ${userImages.length} image(s) dropped.` });
+                userImages = undefined;
+            }
+            this.conversation.addUserMessage(userContent, userImages);
             this.bus.emit("conversation:message-appended", { role: "user", content: query });
             responseText = await this.executeLoop(signal);
         }
@@ -825,7 +811,7 @@ export class AgentLoop {
         while (!signal.aborted) {
             // Auto-compact when total context approaches the window limit.
             const totalEstimate = this.conversation.estimatePromptTokens();
-            const contextWindow = this.currentMode.contextWindow ?? DEFAULT_CONTEXT_WINDOW;
+            const contextWindow = this.activeModel.contextWindow ?? DEFAULT_CONTEXT_WINDOW;
             const s = getSettings();
             const threshold = Math.floor((contextWindow - RESPONSE_RESERVE) * s.autoCompactThreshold);
             if (s.autoCompact && totalEstimate > threshold) {
@@ -850,10 +836,9 @@ export class AgentLoop {
             }
             const systemPrompt = cachedSystemPrompt ?? (cachedSystemPrompt = this.handlers.call("system-prompt:build"));
             const dynamicContext = this.handlers.call("dynamic-context:build");
-            // Shell events are injected once per user query (see query() above),
+            // Shell events are injected once per user query (see handleQuery),
             // not per loop iteration. Mid-loop injection would break the
             // tool_call → tool_result chain some providers require.
-            // Stream LLM response with retry
             const result = await this.streamWithRetry(systemPrompt, dynamicContext, signal);
             const { text, toolCalls: streamedToolCalls, extras } = result;
             const toolCalls = this.handlers.call("tool-protocol:extract-calls", {
@@ -870,7 +855,6 @@ export class AgentLoop {
             }
             if (signal.aborted)
                 break;
-            // No tool calls → agent is done
             if (toolCalls.length === 0) {
                 break;
             }
@@ -1046,10 +1030,8 @@ export class AgentLoop {
                     break;
                 await executeSingle(tc, ++batchIdx);
             }
-            // ── Consecutive error detection (metacognitive nudge) ──
-            // Track errors per tool and total. When the same tool errors N times
-            // in a row, nudge to read source. When errors cascade across tools,
-            // nudge to step back and reassess approach.
+            // Categorize this round's results; the summaries feed
+            // agent:tool-batch-complete below, where extensions decide on nudges.
             const errorTools = new Set();
             const successTools = new Set();
             const errorSummaries = new Map(); // tool → brief error description
@@ -1069,10 +1051,6 @@ export class AgentLoop {
             const hadAnyError = errorTools.size > 0;
             const hadAnySuccess = successTools.size > 0;
             // ── Session telemetry accumulation ──
-            // Track every tool call's outcome. Exposed via orthogonal handlers
-            // (agent:get-counters, agent:get-tool-stats) for extensions that
-            // want behavioral signals. The data layer for metacognition — you
-            // can't improve what you don't measure.
             for (const r of collectedResults) {
                 const counts = this.toolCallCounts.get(r.toolName) ?? { success: 0, error: 0 };
                 if (r.isError) {
@@ -1139,7 +1117,6 @@ export class AgentLoop {
                         catch { }
                     }
                 }
-                // Clear resolved error-by-tool entries for successful tools
                 for (const tool of successTools) {
                     this.lastErrorByTool.delete(tool);
                 }
@@ -1154,7 +1131,6 @@ export class AgentLoop {
                     errorSummary: r.isError ? errorSummaries.get(r.toolName) : undefined,
                 })),
             });
-            // Record all tool results via protocol
             this.toolProtocol.recordResults(this.conversation, collectedResults);
             // Emit enriched message-appended events so derived-log extensions
             // can summarize each tool result without re-parsing the message
@@ -1175,7 +1151,6 @@ export class AgentLoop {
                     isError: !!r.isError,
                 });
             }
-            // Loop back — LLM sees tool results
         }
         return fullResponseText;
     }
@@ -1205,7 +1180,7 @@ export class AgentLoop {
                     throw e;
                 // Context overflow — aggressively compact and retry
                 if (this.isContextOverflow(e)) {
-                    const contextWindow = this.currentMode.contextWindow ?? DEFAULT_CONTEXT_WINDOW;
+                    const contextWindow = this.activeModel.contextWindow ?? DEFAULT_CONTEXT_WINDOW;
                     const target = Math.floor((contextWindow - RESPONSE_RESERVE) * 0.6);
                     const stats = await this.compactWithHooks(target, 1);
                     // If compaction freed nothing, retrying will hit the same error.
@@ -1262,7 +1237,7 @@ export class AgentLoop {
         // wrapTrailingWithDynamicContext for the cache-stability rationale.
         const rawMessages = [
             { role: "system", content: systemPrompt },
-            ...wrapTrailingWithDynamicContext(this.conversation.getMessages(), dynamicContext, toolPrompt),
+            ...wrapTrailingWithDynamicContext(this.conversation.forLLM(), dynamicContext, toolPrompt),
         ];
         // Let extensions transform the message array (compact, summarize, filter, etc.)
         const messages = this.handlers.call("conversation:prepare", rawMessages);
@@ -1271,8 +1246,8 @@ export class AgentLoop {
         const requestParams = {
             messages,
             tools: apiTools,
-            model: this.currentModel,
-            max_tokens: this.currentMode.maxTokens ?? 65536,
+            model: this.activeModel.id,
+            max_tokens: this.activeModel.maxTokens ?? 65536,
             ...this.reasoningParams(),
         };
         this.bus.emit("llm:request", requestParams);
@@ -1286,12 +1261,13 @@ export class AgentLoop {
                 if (chunk.usage) {
                     const u = chunk.usage;
                     const promptTokens = u.prompt_tokens ?? 0;
+                    const cachedPromptTokens = this.activeEndpoint?.extractCachedTokens?.(u);
                     this.bus.emit("agent:usage", {
                         prompt_tokens: promptTokens,
                         completion_tokens: u.completion_tokens ?? 0,
                         total_tokens: u.total_tokens ?? 0,
+                        ...(typeof cachedPromptTokens === "number" ? { cached_prompt_tokens: cachedPromptTokens } : {}),
                     });
-                    // Feed accurate token count back to conversation state
                     if (promptTokens > 0) {
                         this.conversation.updateApiTokenCount(promptTokens);
                     }
@@ -1300,10 +1276,8 @@ export class AgentLoop {
                 if (!choice)
                     continue;
                 const delta = choice.delta;
-                // Text content
                 if (delta?.content) {
                     text += delta.content;
-                    // Filter tool tags from display output (inline mode)
                     const displayText = streamFilter
                         ? streamFilter.feed(delta.content)
                         : delta.content;
@@ -1361,7 +1335,6 @@ export class AgentLoop {
             if (!signal.aborted)
                 throw e;
         }
-        // Flush any buffered content from the stream filter
         if (streamFilter) {
             const remaining = streamFilter.flush();
             if (remaining) {
@@ -1391,7 +1364,7 @@ export class AgentLoop {
         }
         // Echo reasoning only for modes that opt in (e.g. DeepSeek-R1).
         const extras = {};
-        if (this.currentMode.echoReasoning) {
+        if (this.activeModel.echoReasoning) {
             if (reasoning && reasoningField)
                 extras[reasoningField] = reasoning;
             if (reasoningDetailsByIndex.size > 0) {