agent-sh 0.15.0 → 0.15.2

package/src/agent/agent-loop.ts

@@ -0,0 +1,1566 @@
+/**
+ * Internal agent backend — bus-driven and self-wiring. wire() subscribes to
+ * agent:submit (run the LLM tool loop) and agent:cancel-request (abort it),
+ * and the loop emits the agent:* progress/response/tool event stream.
+ */
+import type { EventBus, BusEvents } from "../core/event-bus.js";
+import type { Model, ModelEndpoint } from "./host-types.js";
+import type { LlmClient } from "./llm-client.js";
+import type { HandlerFunctions } from "../utils/handler-registry.js";
+import { setMaxListeners } from "node:events";
+import * as path from "node:path";
+import { contentText, type AgentBackend, type ImageContent, type SkillView, type ToolDefinition, type ToolExecutionContext } from "./types.js";
+import { ToolRegistry } from "./tool-registry.js";
+import { normalizeToolArgs } from "./normalize-args.js";
+import { LiveView, type CompactResult } from "./live-view.js";
+import { STATIC_IDENTITY, STATIC_GUIDE, buildStaticByCwd, formatSkillsBlock, loadGlobalAgentsMd } from "./system-prompt.js";
+import type { Compositor } from "../utils/compositor.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";
+import { wrapTrailingWithDynamicContext } from "../utils/message-utils.js";
+import { getSettings, updateSettings } from "../core/settings.js";
+import { createToolProtocol, type ToolProtocol, type PendingToolCall as ProtocolPendingToolCall, type ToolResult as ProtocolToolResult } from "./tool-protocol.js";
+
+import { discoverGlobalSkills, discoverProjectSkills } from "./skills.js";
+import type { FileReadCache } from "./tools/read-file.js";
+
+type PendingToolCall = ProtocolPendingToolCall;
+
+/** Reject on abort; orphaned `p` keeps running but its result is dropped. */
+function raceAbort<T>(p: Promise<T>, signal: AbortSignal): Promise<T> {
+  if (signal.aborted) return Promise.reject(new Error("cancelled"));
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => reject(new Error("cancelled"));
+    signal.addEventListener("abort", onAbort, { once: true });
+    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: string): string {
+  const firstLine = desc.split("\n", 1)[0]!;
+  const sentenceEnd = firstLine.search(/[.!?](\s|$)/);
+  const candidate = sentenceEnd > 0 ? firstLine.slice(0, sentenceEnd + 1) : firstLine;
+  return candidate.length > 140 ? candidate.slice(0, 137) + "..." : candidate;
+}
+
+export interface AgentLoopConfig {
+  bus: EventBus;
+  llmClient: LlmClient;
+  handlers: HandlerFunctions;
+  initialModel?: Model;
+  compositor?: Compositor;
+  /** Instance ID from core — ensures history entries match the ID in prompts. */
+  instanceId?: string;
+}
+
+export class AgentLoop implements AgentBackend {
+  private abortController: AbortController | null = null;
+  private toolRegistry: ToolRegistry;
+  private conversation: LiveView;
+  private fileReadCache: FileReadCache;
+  private activeModel: Model;
+  private activeEndpoint: ModelEndpoint | undefined;
+  private boundListeners: Array<{ event: string; fn: (...args: any[]) => void }> = [];
+  private boundPipeListeners: Array<{ event: string; fn: (...args: any[]) => any; async: boolean }> = [];
+  private lastProjectSkillNames = new Set<string>();
+
+  // ── Session telemetry: per-session behavioral counters ──
+  // Exposed to extensions via the agent:get-* handlers below.
+  private sessionStartTime = Date.now();
+  private toolCallCounts = new Map<string, { success: number; error: number }>();
+  private totalToolCalls = 0;
+  private totalToolErrors = 0;
+  private totalResolutions = 0;
+  private compactionCount = 0;
+  private cumulativeCompactedTokens = 0;
+  private peakConversationTokens = 0;
+  private queryCount = 0;
+  private totalLoopIterations = 0;
+
+  // Resolution pattern tracking: "error X later resolved by action Y".
+  // Populated/consumed in executeLoop; surfaced via agent:get-counters.
+  private lastErrorByTool = new Map<string, string>(); // tool → error summary
+  private lastErrorByFile = new Map<string, string>(); // file path → error summary
+
+  private static readonly THINKING_LEVELS = ["off", "low", "medium", "high", "xhigh"];
+
+  private bus: EventBus;
+  private llmClient: LlmClient;
+  private handlers: HandlerFunctions;
+  private thinkingLevel: string = getSettings().thinkingLevel ?? "off";
+  private compositor: Compositor | null = null;
+  private toolProtocol: ToolProtocol;
+  private instanceId: string;
+
+  constructor(config: AgentLoopConfig) {
+    this.bus = config.bus;
+    this.llmClient = config.llmClient;
+    this.handlers = config.handlers;
+    this.compositor = config.compositor ?? null;
+    this.instanceId = config.instanceId ?? "unknown";
+    this.toolRegistry = new ToolRegistry(this.handlers);
+    this.fileReadCache = this.handlers.call("agent:file-read-cache") as FileReadCache;
+
+    this.conversation = new LiveView(this.handlers, this.instanceId);
+
+    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]));
+    this.toolProtocol = createToolProtocol(
+      getSettings().toolMode ?? "api",
+      coreTools,
+    );
+
+    // Register any protocol-provided tools (e.g. load_tool for deferred-lookup).
+    const protocolTools = this.toolProtocol.getProtocolTools?.() ?? [];
+    for (const t of protocolTools) this.registerTool(t);
+
+    // Register handlers — extensions can advise these
+    this.registerHandlers();
+
+  }
+
+  /** Subscribe to bus events — activates this backend. */
+  wire(): void {
+    const on = <K extends keyof BusEvents>(
+      event: K,
+      fn: (payload: BusEvents[K]) => void,
+    ) => {
+      this.bus.on(event, fn);
+      this.boundListeners.push({ event, fn });
+    };
+    const onPipe = <K extends keyof BusEvents>(
+      event: K,
+      fn: (payload: BusEvents[K]) => BusEvents[K] | void,
+    ) => {
+      this.bus.onPipe(event, fn as any);
+      this.boundPipeListeners.push({ event, fn, async: false });
+    };
+    const onPipeAsync = <K extends keyof BusEvents>(
+      event: K,
+      fn: (payload: BusEvents[K]) => Promise<BusEvents[K] | void>,
+    ) => {
+      this.bus.onPipeAsync(event, fn as any);
+      this.boundPipeListeners.push({ event, fn, async: true });
+    };
+
+    onPipe("agent:tools", (acc) => {
+      // Read internal storage, NOT this.getTools() — that queries the
+      // pipe and would recurse.
+      for (const tool of this.toolRegistry.allView()) acc.tools.push(tool);
+      return acc;
+    });
+    onPipe("agent:instructions", (acc) => {
+      for (const [name] of this.instructions) {
+        const text = this.handlers.call(`instruction:${name}`) as string;
+        acc.instructions.push({ name, text });
+      }
+      return acc;
+    });
+    onPipe("agent:skills", (acc) => {
+      for (const [name] of this.skills) {
+        const view = this.handlers.call(`skill:${name}:view`) as SkillView;
+        acc.skills.push({ name, description: view.description, filePath: view.filePath });
+      }
+      return acc;
+    });
+
+
+    on("agent:submit", ({ query, images }) => {
+      this.handleQuery(query, images).catch(() => {});
+    });
+    on("agent:cancel-request", (e) => {
+      this.abortController?.abort(e.silent ? "silent" : undefined);
+    });
+    on("agent:append-user-message", ({ text }) => {
+      this.conversation.appendUserMessage(text);
+      this.bus.emit("conversation:message-appended", { role: "user", content: text });
+    });
+    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: ${provider}:${id}` });
+        return;
+      }
+      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.id;
+      }
+      this.emitIdentity();
+
+      // 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: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.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 });
+        }
+        this.activeEndpoint = ep;
+        identityChanged = fresh.contextWindow !== prev.contextWindow;
+      } else {
+        // Ghost: keep prev active so mid-turn stream() doesn't switch models.
+        this.bus.emit("ui:info", {
+          message: `${prev.provider}:${prev.id} is not in the refreshed catalog — keeping it active until you /model to another.`,
+        });
+      }
+      if (identityChanged) this.emitIdentity();
+      this.bus.emit("config:changed", {});
+    });
+    onPipe("config:get-models", () => {
+      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);
+      }
+      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.activeModel;
+      if (level !== "off" && mode.reasoning === false) {
+        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} does not support reasoning_effort.` });
+        return;
+      }
+      this.thinkingLevel = level;
+      updateSettings({ thinkingLevel: level });
+      this.bus.emit("config:changed", {});
+    });
+    onPipe("config:get-thinking", () => {
+      const mode = this.activeModel;
+      const supported = mode.reasoning !== false && mode.supportsReasoningEffort !== false;
+      return { level: this.thinkingLevel, levels: AgentLoop.THINKING_LEVELS, supported };
+    });
+    on("agent:reset-session", () => {
+      this.cancel();
+      this.conversation = new LiveView(this.handlers, this.instanceId);
+      this.lastProjectSkillNames.clear();
+    });
+    on("agent:compact-request", async () => {
+      // Force compaction. Strategy lives behind `conversation:compact`.
+      const stats = await this.compactWithHooks(0, 0, true);
+      if (stats) {
+        this.bus.emit("ui:info", {
+          message: `(compacted: ~${stats.before.toLocaleString()} → ~${stats.after.toLocaleString()} tokens)`,
+        });
+      } else {
+        this.bus.emit("ui:info", { message: "(nothing to compact)" });
+      }
+    });
+    onPipe("context:get-stats", () => ({
+      activeTokens: this.conversation.estimateTokens(),
+      totalTokens: this.conversation.estimatePromptTokens(),
+      budgetTokens: this.activeModel.contextWindow ?? DEFAULT_CONTEXT_WINDOW,
+    }));
+
+    onPipe("context:snapshot", (payload) => {
+      payload.messages = this.conversation.get();
+      payload.contextWindow = this.activeModel.contextWindow ?? DEFAULT_CONTEXT_WINDOW;
+      payload.activeTokens = this.conversation.estimateTokens();
+      return payload;
+    });
+
+    onPipeAsync("context:compact", async (payload) => {
+      const stats = await this.compactWithHooks(0, undefined, false, payload.strategy);
+      if (stats) payload.stats = { before: stats.before, after: stats.after, evictedCount: stats.evictedCount };
+      return payload;
+    });
+
+    // Accumulate counters regardless of which compaction strategy ran.
+    on("conversation:after-compact", ({ beforeTokens, afterTokens }) => {
+      this.compactionCount++;
+      this.cumulativeCompactedTokens += Math.max(0, beforeTokens - afterTokens);
+      if (beforeTokens > this.peakConversationTokens) {
+        this.peakConversationTokens = beforeTokens;
+      }
+      // The "File unchanged" stub assumes the prior read output is still
+      // in context; compaction can evict it. Clear so the next read re-emits.
+      this.fileReadCache.clear();
+    });
+
+    on("shell:cwd-change", ({ cwd }) => {
+      const projectSkills = discoverProjectSkills(cwd);
+      const newNames = new Set(projectSkills.map(s => s.name));
+
+      if (newNames.size === this.lastProjectSkillNames.size &&
+          [...newNames].every(n => this.lastProjectSkillNames.has(n))) {
+        return; // no change
+      }
+      this.lastProjectSkillNames = newNames;
+
+      if (projectSkills.length > 0) {
+        const names = projectSkills.map(s => s.name).join(", ");
+        const note = `[Project skills available: ${names}. Use list_skills for details, read_file to load.]`;
+        this.conversation.addSystemNote(note);
+        this.bus.emit("conversation:message-appended", { role: "system", content: note });
+      }
+    });
+    this.emitIdentity();
+  }
+
+  /** Unsubscribe from bus events — deactivates this backend. */
+  unwire(): void {
+    for (const { event, fn } of this.boundListeners) {
+      this.bus.off(event as any, fn);
+    }
+    this.boundListeners = [];
+    for (const { event, fn, async } of this.boundPipeListeners) {
+      if (async) this.bus.offPipeAsync(event as any, fn);
+      else this.bus.offPipe(event as any, fn);
+    }
+    this.boundPipeListeners = [];
+  }
+
+  /** Register a tool (used by extensions via ctx.agent.registerTool). */
+  registerTool(tool: ToolDefinition): void {
+    this.toolRegistry.register(tool);
+  }
+
+  /** Unregister a tool by name. */
+  unregisterTool(name: string): void {
+    this.toolRegistry.unregister(name);
+  }
+
+  /** Get all registered tools (union of builtins + extension contributions). */
+  getTools(): ToolDefinition[] {
+    return this.bus.emitPipe("agent:tools", { tools: [] }).tools;
+  }
+
+  /** Find a tool by name across the full pipe union. */
+  private findTool(name: string): ToolDefinition | undefined {
+    return this.getTools().find((t) => t.name === name);
+  }
+
+  // ── Extension instructions, skills & tool tracking ──────────────────
+
+  /** Instructions keyed by name, with extension attribution. */
+  private instructions = new Map<string, { text: string; extensionName: string }>();
+
+  /** Skills keyed by name, with extension attribution. */
+  private skills = new Map<string, { description: string; filePath: string; extensionName: string }>();
+
+  /** Tool → extension name attribution. */
+  private toolExtensions = new Map<string, string>();
+
+  /** Register a named instruction block for the system prompt. */
+  registerInstruction(name: string, text: string, extensionName: string): void {
+    this.instructions.set(name, { text, extensionName });
+    this.handlers.define(`instruction:${name}`, () => this.instructions.get(name)?.text ?? "");
+  }
+
+  removeInstruction(name: string): void {
+    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: string, description: string, filePath: string, extensionName: string): void {
+    this.skills.set(name, { description, filePath, extensionName });
+    this.handlers.define(`skill:${name}:view`, (): SkillView => {
+      const s = this.skills.get(name);
+      return { description: s?.description ?? "", filePath: s?.filePath ?? "" };
+    });
+  }
+
+  removeSkill(name: string): void {
+    this.skills.delete(name);
+    // Handler entry retained so external advisors survive a reload of the owner.
+  }
+
+  /**
+   * Build the "Extensions" section of the system prompt. Includes tools,
+   * skills, and instructions contributed by extensions (i.e. anything
+   * registered via ctx.agent.registerTool/Skill/Instruction). AgentLoop's
+   * own builtins are excluded by name — they're documented elsewhere in
+   * the prompt or in the tool API params.
+   */
+  buildExtensionSections(): string[] {
+    const BUILTIN_TOOLS = new Set([
+      "bash", "read_file", "write_file", "edit_file", "grep", "glob", "ls",
+      "list_skills",
+    ]);
+    const BUILTIN_INSTRUCTIONS = new Set(["recall-guidance"]);
+    const BUILTIN_SKILLS = new Set<string>();
+
+    const allTools = this.bus.emitPipe("agent:tools", { tools: [] }).tools;
+    const allInstructions = this.bus.emitPipe("agent:instructions", { instructions: [] }).instructions;
+    const allSkills = this.bus.emitPipe("agent:skills", { skills: [] }).skills;
+
+    const extTools = this.toolProtocol.mode === "api"
+      ? []
+      : allTools.filter((t) => !BUILTIN_TOOLS.has(t.name));
+    const extInstructions = allInstructions.filter((i) => !BUILTIN_INSTRUCTIONS.has(i.name));
+    const extSkills = allSkills.filter((s) => !BUILTIN_SKILLS.has(s.name));
+
+    if (extTools.length + extInstructions.length + extSkills.length === 0) return [];
+
+    const parts: string[] = [];
+    if (extTools.length > 0)
+      parts.push("### Tools\n" + extTools.map(t => `${t.name} — ${summarizeDescription(t.description)}`).join("\n"));
+    if (extSkills.length > 0)
+      parts.push("### Skills\n" + extSkills.map(s => `${s.name}: ${s.description}\n  → ${s.filePath}`).join("\n\n"));
+    if (extInstructions.length > 0)
+      parts.push("### Instructions\n" + extInstructions.map(i => i.text).join("\n\n"));
+    return [`## Extensions\n${parts.join("\n\n")}`];
+  }
+
+  kill(): void {
+    this.cancel();
+    this.unwire();
+  }
+
+  private cancel(): void {
+    this.abortController?.abort();
+  }
+
+  private reasoningParams(): Record<string, unknown> {
+    const model = this.activeModel;
+    if (model.reasoning === false) return {};
+    if (model.supportsReasoningEffort === false) return {};
+    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 };
+  }
+
+
+  private resolveEndpoint(m: Model): ModelEndpoint | undefined {
+    try {
+      return this.handlers.call("agent:resolve-endpoint", { provider: m.provider, id: m.id }) as ModelEndpoint | undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
+  private pullModels(): Model[] {
+    try {
+      return (this.handlers.call("agent:get-models") as Model[]) ?? [];
+    } catch {
+      return [];
+    }
+  }
+
+  private emitIdentity(): void {
+    const m = this.activeModel;
+    this.bus.emit("agent:info", {
+      name: "ash",
+      version: PACKAGE_VERSION,
+      model: m.id,
+      provider: m.provider,
+      contextWindow: m.contextWindow,
+    });
+  }
+
+  /**
+   * Run compaction via the `conversation:compact` handler. After any
+   * compaction, emit `conversation:after-compact` so listeners
+   * (metrics, UI, agent-awareness notes) can react.
+   */
+  private async compactWithHooks(
+    target: number,
+    keepRecent?: number,
+    force?: boolean,
+    strategy?: BusEvents["context:compact"]["strategy"],
+  ): Promise<CompactResult | null> {
+    const stats = (await this.handlers.call("conversation:compact", {
+      target,
+      keepRecent,
+      force: !!force,
+      strategy,
+    })) as CompactResult | null;
+    if (stats) {
+      this.bus.emit("conversation:after-compact", {
+        beforeTokens: stats.before,
+        afterTokens: stats.after,
+        evictedCount: stats.evictedCount,
+      });
+    }
+    return stats;
+  }
+
+  private isContextOverflow(e: unknown): boolean {
+    if (!(e instanceof Error)) return false;
+    // Match the specific error codes providers use, or unambiguous phrases.
+    // Bare "token"/"context" match too broadly (auth errors, model-name
+    // mismatches, etc.) and caused infinite-no-op retry loops.
+    const code = (e as any).code;
+    if (code === "context_length_exceeded" || code === "string_above_max_length") return true;
+    const msg = e.message.toLowerCase();
+    return (
+      msg.includes("context length") ||
+      msg.includes("context window") ||
+      msg.includes("maximum context") ||
+      msg.includes("prompt is too long") ||
+      msg.includes("input is too long") ||
+      msg.includes("too many tokens") ||
+      msg.includes("reduce the length")
+    );
+  }
+
+  /** Check if an error is retryable (transient). */
+  private isRetryable(e: unknown): boolean {
+    if (!(e instanceof Error)) return false;
+    const msg = e.message.toLowerCase();
+
+    // Network errors
+    if (msg.includes("econnreset") || msg.includes("econnrefused") ||
+        msg.includes("etimedout") || msg.includes("fetch failed") ||
+        msg.includes("network") || msg.includes("socket hang up")) {
+      return true;
+    }
+
+    // HTTP status-based (OpenAI SDK includes status in error)
+    const status = (e as any).status;
+    if (status === 429 || status === 500 || status === 502 || status === 503 || status === 529) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /** Extract retry delay from error headers or use exponential backoff. */
+  private getRetryDelay(e: unknown, attempt: number): number {
+    // Check for Retry-After header (OpenAI SDK exposes headers)
+    const headers = (e as any).headers;
+    if (headers) {
+      const retryAfter = headers["retry-after"] ?? headers.get?.("retry-after");
+      if (retryAfter) {
+        const seconds = parseInt(retryAfter, 10);
+        if (!isNaN(seconds)) return seconds * 1000;
+      }
+    }
+
+    // Exponential backoff: 1s, 2s, 4s, 8s, capped at 30s
+    return Math.min(1000 * Math.pow(2, attempt), 30_000);
+  }
+
+  /** Format an error with provider context for user-facing display. */
+  private formatError(e: unknown): string {
+    const raw = e instanceof Error ? e.message : String(e);
+    const status = (e as any).status;
+    const model = this.activeModel.id;
+    const baseURL = (this.llmClient as any).config?.baseURL;
+    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") ||
+        raw.includes("socket hang up")) {
+      const target = baseURL ?? provider ?? "provider";
+      return `Could not connect to ${target} (${raw}). Check that the API endpoint is reachable.`;
+    }
+
+    // Explicit signals only — bare "auth" hit "author" in echoed API params.
+    if (status === 401 || status === 403 ||
+        /\b(unauthorized|authentication|api[-_ ]?key|invalid[-_ ]?token)\b/i.test(raw)) {
+      return `Authentication failed for ${provider ?? "provider"} (model: ${model}). Check your API key.`;
+    }
+
+    // Model not found
+    if (status === 404) {
+      return `Model "${model}" not found at ${provider ?? baseURL ?? "provider"}. Check the model name.`;
+    }
+
+    // Rate limit (after retries exhausted)
+    if (status === 429) {
+      return `Rate limited by ${provider ?? "provider"} (model: ${model}). Try again in a moment.`;
+    }
+
+    // Generic with context
+    const context = provider ? ` (${provider}, model: ${model})` : ` (model: ${model})`;
+    return `${raw}${context}`;
+  }
+
+  /**
+   * Register named handlers that extensions can advise.
+   * Only high-power use cases where multiple extensions compose.
+   */
+  private registerHandlers(): void {
+    const h = this.handlers;
+
+    // Advisable so extensions can inject fallback parsers without
+    // subclassing the protocol.
+    h.define("tool-protocol:extract-calls", (args: {
+      text: string;
+      streamedCalls: ProtocolPendingToolCall[];
+    }) => this.toolProtocol.extractToolCalls(args.text, args.streamedCalls));
+
+    // System prompt: static identity + behavioral instructions. Extensions can
+    // use registerInstruction() for a managed section, advise system-prompt:identity
+    // to replace the kernel identity, advise system-prompt:frontend to describe their
+    // surface high in the prompt, or advise system-prompt:build directly for full control.
+    h.define("system-prompt:identity", () => STATIC_IDENTITY);
+    h.define("system-prompt:build", () => {
+      // The active frontend's surface goes right after the identity; omitted if none.
+      const frontend = ((this.handlers.call("system-prompt:frontend") as string) ?? "").trim();
+      const parts: string[] = [this.handlers.call("system-prompt:identity") as string];
+      if (frontend) parts.push(frontend);
+      parts.push(STATIC_GUIDE);
+
+      // Global behavioral rules (~/.agent-sh/AGENTS.md) — persistent agent memory
+      const agentsMd = loadGlobalAgentsMd();
+      if (agentsMd) parts.push(agentsMd);
+
+      // Global skills — stable across cwd changes, cacheable with the system prompt
+      const globalSkills = discoverGlobalSkills();
+      const skillsBlock = formatSkillsBlock(globalSkills);
+      if (skillsBlock) parts.push(skillsBlock);
+
+      // Project conventions + project skills — stable within a cwd.
+      // Placed here so they enter the provider's prompt cache with the
+      // system prompt, and only re-materialize when cwd changes invalidate
+      // cachedSystemPrompt in executeLoop.
+      const projectStatic = buildStaticByCwd(this.handlers.call("cwd") as string);
+      if (projectStatic) parts.push(projectStatic);
+
+      const extensionSections = this.buildExtensionSections();
+      if (extensionSections.length > 0) {
+        parts.push("# Extension Instructions\n\n" + extensionSections.join("\n\n"));
+      }
+
+      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 — "
+          + "they will be shown to you directly. Use this to inspect screenshots, "
+          + "diagrams, UI mockups, charts, or any visual content relevant to the task.",
+        );
+      }
+
+      return parts.join("\n\n");
+    });
+
+    // ── Orthogonal core-state accessors ──────────────────────────
+    // Each handler exposes one cohesive piece of core-owned runtime
+    // state. Extensions compose whichever they need — core doesn't
+    // 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-model", () => ({
+      model: this.activeModel.id,
+      provider: this.activeModel.provider,
+      thinkingLevel: this.thinkingLevel,
+      contextWindow: this.activeModel.contextWindow ?? DEFAULT_CONTEXT_WINDOW,
+    }));
+
+    h.define("agent:get-tokens", () => {
+      const contextWindow = this.activeModel.contextWindow ?? DEFAULT_CONTEXT_WINDOW;
+      const promptTokens = this.conversation.estimatePromptTokens();
+      return {
+        active: this.conversation.estimateTokens(),
+        peak: this.peakConversationTokens,
+        cumulativeCompacted: this.cumulativeCompactedTokens,
+        promptTokens,
+        contextPercent: Math.round((promptTokens / contextWindow) * 100),
+      };
+    });
+
+    h.define("agent:get-counters", () => ({
+      queryCount: this.queryCount,
+      totalToolCalls: this.totalToolCalls,
+      totalToolErrors: this.totalToolErrors,
+      totalResolutions: this.totalResolutions,
+      totalLoopIterations: this.totalLoopIterations,
+      errorRate: this.totalToolCalls > 0
+        ? Math.round((this.totalToolErrors / this.totalToolCalls) * 100)
+        : 0,
+    }));
+
+    h.define("agent:get-timing", () => ({
+      startedAt: this.sessionStartTime,
+      elapsedSeconds: Math.round((Date.now() - this.sessionStartTime) / 1000),
+    }));
+
+    h.define("agent:get-tool-stats", () =>
+      [...this.toolCallCounts.entries()]
+        .map(([name, counts]) => ({
+          name,
+          total: counts.success + counts.error,
+          success: counts.success,
+          error: counts.error,
+        }))
+        .sort((a, b) => b.total - a.total));
+
+    h.define("agent:get-file-read-cache", () =>
+      [...this.fileReadCache.entries()].map(([p, s]) => ({
+        path: p,
+        offset: s.offset,
+        limit: s.limit ?? null,
+        mtimeMs: s.mtimeMs,
+      })));
+
+    h.define("agent:get-recent-errors", () => ({
+      byTool: [...this.lastErrorByTool.entries()].map(([tool, error]) => ({ tool, error })),
+      byFile: [...this.lastErrorByFile.entries()].map(([file, error]) => ({ file, error })),
+    }));
+
+    h.define("agent:get-compaction-state", () => {
+      const contextWindow = this.activeModel.contextWindow ?? DEFAULT_CONTEXT_WINDOW;
+      const ratio = getSettings().autoCompactThreshold ?? 0.5;
+      return {
+        count: this.compactionCount,
+        autoCompactThreshold: ratio,
+        autoCompactThresholdTokens: Math.floor((contextWindow - RESPONSE_RESERVE) * ratio),
+      };
+    });
+
+    h.define("agent:get-self", () => this);
+
+    // 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: unknown[]) => messages);
+
+    // ── Conversation primitives for compaction strategies ─────────
+    // Canonical array (link/replace index space), not forLLM().
+    h.define("conversation:get-messages", () => this.conversation.get());
+    h.define("conversation:replace-messages", (msgs: unknown[]) => {
+      this.conversation.replace(msgs as ReturnType<typeof this.conversation.get>);
+    });
+    h.define("conversation:estimate-tokens", () => this.conversation.estimateTokens());
+    h.define("conversation:estimate-prompt-tokens", () => this.conversation.estimatePromptTokens());
+    h.define("conversation:link", (index: number, entryId: string) => this.conversation.link(index, entryId));
+
+    h.define("conversation:compact", (opts: {
+      target?: number;
+      keepRecent?: number;
+      force?: boolean;
+      strategy?:
+        | { kind: "two-tier-pin"; target: number; keepRecent?: number; force?: boolean }
+        | { kind: "rewind"; toIndex: number }
+        | { kind: "replace"; messages: unknown[] };
+    }) => {
+      const strategy = opts.strategy;
+      if (strategy?.kind === "rewind" || strategy?.kind === "replace") {
+        const before = this.conversation.estimatePromptTokens();
+        const beforeLen = this.conversation.get().length;
+        const next = strategy.kind === "rewind"
+          ? this.conversation.get().slice(0, strategy.toIndex)
+          : (strategy.messages as ReturnType<LiveView["get"]>);
+        this.conversation.replace(next);
+        const after = this.conversation.estimatePromptTokens();
+        const afterLen = this.conversation.get().length;
+        return { before, after, evictedCount: Math.max(0, beforeLen - afterLen) } as CompactResult;
+      }
+      return null;
+    });
+
+    // Inject a system note mid-loop — used by extensions (subagents,
+    // peer messages) to deliver async results into the next iteration.
+    h.define("conversation:inject-note", (text: string) => {
+      this.conversation.addSystemNote(text);
+      this.bus.emit("conversation:message-appended", { role: "system", content: text });
+    });
+
+    // Fires on user-abort; extensions advise per tool name for cleanup.
+    h.define("tool:cancel", (_ctx: {
+      name: string;
+      args: Record<string, unknown>;
+      reason: "user-aborted";
+    }) => {});
+
+    // Wraps each tool call: permission → execute → emit events.
+    h.define("tool:execute", async (ctx: {
+      name: string; id: string;
+      args: Record<string, unknown>;
+      tool: ToolDefinition;
+      onChunk?: (chunk: string) => void;
+      batchIndex?: number;
+      batchTotal?: number;
+      signal: AbortSignal;
+    }) => {
+      const { name, id, args, tool, signal } = ctx;
+
+      // Validate required input fields before display/permission/execute.
+      // Some models emit wrong arg names (e.g. `file_path` instead of `path`),
+      // and downstream helpers assume required strings are present.
+      const schema = tool.input_schema as { required?: unknown; properties?: Record<string, { type?: string }> } | undefined;
+      const required = Array.isArray(schema?.required) ? schema!.required as string[] : [];
+      const missing = required.filter((k) => args[k] === undefined || args[k] === null);
+      if (missing.length > 0) {
+        const msg = `Missing required argument(s): ${missing.join(", ")}. Expected: ${required.join(", ")}. Received: ${Object.keys(args).join(", ") || "(none)"}`;
+        this.bus.emit("agent:tool-call", { tool: name, args });
+        return { content: msg, exitCode: 1, isError: true };
+      }
+
+      const display = tool.getDisplayInfo?.(args) ?? { kind: "execute" as const };
+
+      const label = tool.displayName ?? name;
+      this.bus.emit("agent:tool-started", {
+        title: typeof args.description === "string" ? `${label}: ${args.description}` : label,
+        name,
+        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.
+      const onChunk = tool.showOutput !== false ? ctx.onChunk : undefined;
+      const toolCtx: ToolExecutionContext = { signal };
+      if (this.compositor) {
+        toolCtx.ui = createToolUI(this.bus, this.compositor.surface("agent"));
+      }
+      let result: Awaited<ReturnType<typeof tool.execute>>;
+      try {
+        result = await raceAbort(this.toolRegistry.call(name, args, onChunk, toolCtx), signal);
+      } catch (err) {
+        if (signal.aborted) {
+          try { this.handlers.call("tool:cancel", { name, args, reason: "user-aborted" }); } catch {}
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        result = { content: message, exitCode: 1, isError: true };
+      }
+
+      if (tool.modifiesFiles && typeof args.path === "string" && !result.isError) {
+        const absPath = path.resolve(process.cwd(), args.path);
+        this.fileReadCache.delete(absPath);
+      }
+
+      const resultDisplay = result.display ?? tool.formatResult?.(args, result);
+
+      // Emit completion events (via transform pipe so extensions can override)
+      this.bus.emitTransform("agent:tool-completed", {
+        toolCallId: id, exitCode: result.exitCode,
+        rawOutput: result.content, kind: display.kind,
+        resultDisplay,
+      });
+      this.bus.emit("agent:tool-output", {
+        tool: name, output: contentText(result.content), exitCode: result.exitCode,
+      });
+
+      return result;
+    });
+  }
+
+  private async handleQuery(query: string, images?: ImageContent[]): Promise<void> {
+    if (this.abortController) {
+      this.abortController.abort();
+    }
+    this.abortController = new AbortController();
+    const signal = this.abortController.signal;
+    // Each loop iteration adds an abort listener (via OpenAI SDK stream);
+    // disable the limit — long-running tool loops can easily exceed any cap.
+    setMaxListeners(0, signal);
+
+    this.queryCount++;
+    this.bus.emit("agent:query", { query });
+    this.bus.emit("agent:processing-start", {});
+    let responseText = "";
+
+    try {
+      // Per-query producers (shell events + any extension-registered
+      // per-query signals) produce content that gets frozen into this
+      // user message inside <query_context>, distinguishing it from the
+      // per-request <dynamic_context> wrapped on the trailing message.
+      const queryContext = ((this.handlers.call("query-context:build") as string) ?? "").trim();
+      const userContent = queryContext
+        ? `<query_context>\n${queryContext}\n</query_context>\n\n${query}`
+        : query;
+
+      // 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);
+    } catch (e) {
+      if (!signal.aborted) {
+        if (e instanceof Error) console.error("[agent-sh] query failed:\n" + e.stack);
+        const msg = this.formatError(e);
+        this.bus.emit("agent:error", { message: msg });
+      }
+    } finally {
+      if (signal.aborted && signal.reason !== "silent") {
+        this.bus.emit("agent:cancelled", {});
+      }
+      // Ensure any buffered text in the stream transform pipeline gets
+      // flushed as a complete line before response-done closes the box.
+      if (responseText && !responseText.endsWith("\n")) {
+        this.bus.emitTransform("agent:response-chunk", {
+          blocks: [{ type: "text", text: "\n" }],
+        });
+      }
+      this.bus.emitTransform("agent:response-done", {
+        response: responseText,
+      });
+      this.bus.emit("agent:processing-done", {});
+      this.abortController = null;
+
+    }
+  }
+
+  /**
+   * Core agent loop: stream LLM response → execute tools → repeat.
+   * Returns the final accumulated response text.
+   */
+  private async executeLoop(signal: AbortSignal): Promise<string> {
+    let fullResponseText = "";
+
+    // System prompt carries things stable within a turn: static identity,
+    // global agent rules, project conventions, project skills. Invalidated
+    // only by compaction (context shape changed) or cwd change (project
+    // conventions/skills changed). Dynamic context rebuilds every iteration
+    // so live signals (budget, in-flight subagents, metacognitive warnings)
+    // are fresh.
+    let cachedSystemPrompt: string | undefined;
+    let lastCwd = this.handlers.call("cwd") as string;
+
+    while (!signal.aborted) {
+      // Auto-compact when total context approaches the window limit.
+      const totalEstimate = this.conversation.estimatePromptTokens();
+      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) {
+        // Compact deeply — shallow targets buy only 1–2 turns of runway on
+        // tool-heavy workloads.
+        const target = Math.floor(threshold * 0.25);
+        const result = await this.compactWithHooks(target, 1);
+        if (!result) {
+          // Auto-compact fired but nothing was evictable. This can happen
+          // in short conversations with heavy tool output where the pin
+          // fraction consumes all turns. Log it so it's not silent.
+          this.bus.emit("ui:info", {
+            message: `[auto-compact] above threshold (${totalEstimate.toLocaleString()} > ${threshold.toLocaleString()}) but nothing to evict — conversation may be too short`,
+          });
+        }
+        cachedSystemPrompt = undefined;
+      }
+
+      const currentCwd = this.handlers.call("cwd") as string;
+      if (currentCwd !== lastCwd) {
+        cachedSystemPrompt = undefined;
+        lastCwd = currentCwd;
+      }
+
+      const systemPrompt = cachedSystemPrompt ?? (cachedSystemPrompt = this.handlers.call("system-prompt:build") as string);
+      const dynamicContext = this.handlers.call("dynamic-context:build") as string;
+
+      // 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.
+      const result = await this.streamWithRetry(systemPrompt, dynamicContext, signal);
+
+      const { text, toolCalls: streamedToolCalls, extras } = result;
+
+      const toolCalls = this.handlers.call("tool-protocol:extract-calls", {
+        text,
+        streamedCalls: streamedToolCalls,
+      }) as ProtocolPendingToolCall[];
+
+      fullResponseText += text;
+
+      if (text || toolCalls.length > 0) {
+        this.toolProtocol.recordAssistant(this.conversation, text, toolCalls, extras);
+        this.bus.emit("conversation:message-appended", {
+          role: "assistant",
+          content: text,
+        });
+      }
+
+      if (signal.aborted) break;
+
+      if (toolCalls.length === 0) {
+        break;
+      }
+
+      // Emit batch info so the TUI can render group headers upfront
+      {
+        const groupMap = new Map<string, Array<{ name: string; displayDetail?: string }>>();
+        for (const tc of toolCalls) {
+          const tool = this.findTool(tc.name);
+          const kind = tool?.getDisplayInfo?.((() => { try { return JSON.parse(tc.argumentsJson); } catch { return {}; } })())?.kind ?? "execute";
+          let args: Record<string, unknown> = {};
+          try { args = JSON.parse(tc.argumentsJson); } catch {}
+          const detail = tool?.formatCall?.(args);
+          if (!groupMap.has(kind)) groupMap.set(kind, []);
+          groupMap.get(kind)!.push({ name: tc.name, displayDetail: detail });
+        }
+        const groups = Array.from(groupMap.entries()).map(([kind, tools]) => ({ kind, tools }));
+        this.bus.emit("agent:tool-batch", { groups });
+      }
+
+      // Execute tool calls — run read-only tools in parallel, permission-
+      // requiring tools sequentially (to avoid overlapping permission prompts).
+      const batchTotal = toolCalls.length;
+      const collectedResults: ProtocolToolResult[] = [];
+
+      // Round-scoped cache for pure, read-only tool calls
+      const roundCache = new Map<string, ProtocolToolResult>();
+
+      const executeSingle = async (tc: PendingToolCall, batchIndex?: number) => {
+        // Rewrite meta-tool calls (e.g., use_extension → actual tool)
+        tc = this.toolProtocol.rewriteToolCall(tc);
+
+        // Check for validation errors from rewrite (e.g., wrong extension params)
+        try {
+          const maybeError = JSON.parse(tc.argumentsJson);
+          if (maybeError._error) {
+            collectedResults.push({
+              callId: tc.id, toolName: tc.name,
+              content: maybeError._error, isError: true,
+            });
+            return;
+          }
+        } catch { /* not an error payload, continue */ }
+
+        const tool = this.findTool(tc.name);
+        if (!tool) {
+          const available = this.getTools().map((t) => t.name).join(", ");
+          collectedResults.push({
+            callId: tc.id, toolName: tc.name,
+            content: `Unknown tool "${tc.name}". Available tools: ${available}`,
+            isError: true,
+          });
+          return;
+        }
+
+        let args: Record<string, unknown>;
+        try {
+          args = JSON.parse(tc.argumentsJson);
+        } catch {
+          collectedResults.push({
+            callId: tc.id, toolName: tc.name,
+            content: `Invalid JSON arguments for ${tc.name}`, isError: true,
+          });
+          return;
+        }
+        // Normalize against the tool's input_schema: some LLMs stringify
+        // nested object/array args despite the schema. See
+        // 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.showOutput !== true;
+        const cacheKey = cacheable ? `${tc.name}:${JSON.stringify(args)}` : null;
+        if (cacheKey) {
+          const cached = roundCache.get(cacheKey);
+          if (cached) {
+            const display = tool.getDisplayInfo?.(args) ?? { kind: "execute" as const };
+            this.bus.emit("agent:tool-started", {
+              title: tool.displayName ?? tc.name,
+              name: tc.name,
+              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 });
+            // Reconstruct a ToolResult for formatResult; ProtocolToolResult has no exitCode
+            const cachedToolResult = { content: cached.content, exitCode: 0, isError: cached.isError };
+            const resultDisplay = tool.formatResult?.(args, cachedToolResult);
+            this.bus.emitTransform("agent:tool-completed", {
+              toolCallId: tc.id, exitCode: 0,
+              rawOutput: cached.content, kind: display.kind,
+              resultDisplay,
+            });
+            this.bus.emit("agent:tool-output", {
+              tool: tc.name, output: contentText(cached.content), exitCode: 0,
+            });
+            collectedResults.push({
+              callId: tc.id, toolName: tc.name,
+              content: cached.content, isError: cached.isError,
+            });
+            return;
+          }
+        }
+
+        // Execute via handler — extensions can advise to add safe-mode,
+        // logging, metrics, custom permission policies, etc.
+        const defaultOnChunk = (chunk: string) => {
+          this.bus.emit("agent:tool-output-chunk", { chunk });
+        };
+        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 },
+        );
+
+        let content = result.content;
+        if (typeof content === "string") {
+          const maxBytes = tool.maxResultBytes ?? 100_000; // ~25k tokens
+          if (content.length > maxBytes) {
+            const headBytes = Math.floor(maxBytes * 0.6);
+            const tailBytes = maxBytes - headBytes;
+            const lines = content.split("\n");
+            let headEnd = 0, headLen = 0;
+            for (let i = 0; i < lines.length && headLen + lines[i].length + 1 <= headBytes; i++) {
+              headLen += lines[i].length + 1;
+              headEnd = i + 1;
+            }
+            let tailStart = lines.length, tailLen = 0;
+            for (let i = lines.length - 1; i >= headEnd && tailLen + lines[i].length + 1 <= tailBytes; i--) {
+              tailLen += lines[i].length + 1;
+              tailStart = i;
+            }
+            const omitted = tailStart - headEnd;
+            content = [
+              ...lines.slice(0, headEnd),
+              `\n[… ${omitted} lines omitted (output truncated to ${Math.round(maxBytes / 1024)}KB) …]\n`,
+              ...lines.slice(tailStart),
+            ].join("\n");
+          }
+        }
+
+        const finalResult: ProtocolToolResult = {
+          callId: tc.id, toolName: tc.name,
+          content, isError: result.isError,
+        };
+        if (cacheKey) {
+          roundCache.set(cacheKey, finalResult);
+        }
+        collectedResults.push(finalResult);
+      };
+
+      const parallel: PendingToolCall[] = [];
+      const sequential: PendingToolCall[] = [];
+      for (const tc of toolCalls) {
+        const tool = this.findTool(tc.name);
+        if (tool && !tool.modifiesFiles) {
+          parallel.push(tc);
+        } else {
+          sequential.push(tc);
+        }
+      }
+
+      // Run read-only tools in parallel
+      let batchIdx = 0;
+      if (parallel.length > 0 && !signal.aborted) {
+        await Promise.all(parallel.map(tc => {
+          const idx = ++batchIdx;
+          return signal.aborted ? Promise.resolve() : executeSingle(tc, idx);
+        }));
+      }
+
+      // Run permission-requiring tools sequentially
+      for (const tc of sequential) {
+        if (signal.aborted) break;
+        await executeSingle(tc, ++batchIdx);
+      }
+
+      // Categorize this round's results; the summaries feed
+      // agent:tool-batch-complete below, where extensions decide on nudges.
+      const errorTools = new Set<string>();
+      const successTools = new Set<string>();
+      const errorSummaries = new Map<string, string>(); // tool → brief error description
+      const successSummaries = new Map<string, string>(); // tool → brief success description
+
+      for (const r of collectedResults) {
+        const content = typeof r.content === "string" ? r.content : String(r.content);
+        const brief = content.slice(0, 80).replace(/\n/g, " ").trim();
+        if (r.isError) {
+          errorTools.add(r.toolName);
+          errorSummaries.set(r.toolName, brief);
+        } else {
+          successTools.add(r.toolName);
+          successSummaries.set(r.toolName, brief);
+        }
+      }
+
+      const hadAnyError = errorTools.size > 0;
+      const hadAnySuccess = successTools.size > 0;
+
+      // ── Session telemetry accumulation ──
+      for (const r of collectedResults) {
+        const counts = this.toolCallCounts.get(r.toolName) ?? { success: 0, error: 0 };
+        if (r.isError) {
+          counts.error++;
+          this.totalToolErrors++;
+        } else {
+          counts.success++;
+        }
+        this.toolCallCounts.set(r.toolName, counts);
+        this.totalToolCalls++;
+      }
+      this.totalLoopIterations++;
+
+      // ── Resolution pattern tracking ──
+      // When a tool errors, record the error context. When the same tool
+      // (or a write tool touching the same file) succeeds afterward,
+      // increment totalResolutions — the positive feedback signal exposed
+      // to extensions via agent:get-counters.
+      if (hadAnyError) {
+        for (const [tool, summary] of errorSummaries) {
+          this.lastErrorByTool.set(tool, summary);
+        }
+        for (const r of collectedResults) {
+          if (!r.isError) continue;
+          const tc = toolCalls.find(t => t.id === r.callId || t.name === r.toolName);
+          if (!tc) continue;
+          try {
+            const args = JSON.parse(tc.argumentsJson);
+            const fp = this.filePathFromArgs(r.toolName, args);
+            if (fp) this.lastErrorByFile.set(fp, errorSummaries.get(r.toolName) ?? "");
+          } catch {}
+        }
+      }
+
+      if (hadAnySuccess) {
+        let resolved = false;
+        for (const [tool] of successSummaries) {
+          if (this.lastErrorByTool.get(tool)) {
+            this.lastErrorByTool.delete(tool);
+            this.totalResolutions++;
+            resolved = true;
+            break;
+          }
+        }
+        if (!resolved) {
+          for (const r of collectedResults) {
+            if (r.isError) continue;
+            const tc = toolCalls.find(t => t.id === r.callId || t.name === r.toolName);
+            if (!tc) continue;
+            try {
+              const args = JSON.parse(tc.argumentsJson);
+              const fp = this.filePathFromArgs(r.toolName, args);
+              if (fp && this.lastErrorByFile.get(fp)) {
+                this.lastErrorByFile.delete(fp);
+                this.totalResolutions++;
+                break;
+              }
+            } catch {}
+          }
+        }
+        for (const tool of successTools) {
+          this.lastErrorByTool.delete(tool);
+        }
+      }
+
+      // Announce the batch — extensions that care about batch-level
+      // outcomes (consecutive-error tracking, resolution pattern logging,
+      // metacognitive nudges) listen here.
+      this.bus.emit("agent:tool-batch-complete", {
+        results: collectedResults.map((r) => ({
+          name: r.toolName,
+          isError: !!r.isError,
+          errorSummary: r.isError ? errorSummaries.get(r.toolName) : undefined,
+        })),
+      });
+
+      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
+      // structure.
+      for (const r of collectedResults) {
+        const content = typeof r.content === "string" ? r.content : String(r.content);
+        const tc = toolCalls.find(t => t.id === r.callId || t.name === r.toolName);
+        let args: Record<string, unknown> = {};
+        try { args = tc ? JSON.parse(tc.argumentsJson) : {}; } catch {}
+        this.bus.emit("conversation:message-appended", {
+          role: "tool",
+          content,
+          toolName: r.toolName,
+          toolArgs: args,
+          isError: !!r.isError,
+        });
+      }
+    }
+
+    return fullResponseText;
+  }
+
+  private readonly maxRetries = 3;
+
+  // ── Resolution pattern helpers ──
+  // Extract a file path from a tool call's arguments. Used to correlate
+  // errors with subsequent successful writes on the same file.
+  private filePathFromArgs(toolName: string, args: Record<string, unknown>): string | undefined {
+    if (toolName === "edit_file" || toolName === "write_file" || toolName === "read_file") {
+      return (args.path ?? args.file_path) as string | undefined;
+    }
+    return undefined;
+  }
+
+  /**
+   * Stream with retry logic. Handles:
+   *   - Context overflow → compact and retry
+   *   - Rate limits (429) → backoff with Retry-After
+   *   - Transient errors (500/502/503, network) → exponential backoff
+   */
+  private async streamWithRetry(
+    systemPrompt: string,
+    dynamicContext: string,
+    signal: AbortSignal,
+  ): ReturnType<typeof this.streamResponse> {
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      try {
+        return await this.streamResponse(systemPrompt, dynamicContext, signal);
+      } catch (e) {
+        if (signal.aborted) throw e;
+
+        // Context overflow — aggressively compact and retry
+        if (this.isContextOverflow(e)) {
+          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.
+          // Surface the real failure instead of looping until exhaustion.
+          if (!stats || stats.after >= stats.before) {
+            this.bus.emit("ui:info", {
+              message: "(context overflow — nothing to compact; aborting retries)",
+            });
+            throw e;
+          }
+          this.bus.emit("ui:info", {
+            message: `(context overflow — compacted ~${stats.before.toLocaleString()} → ~${stats.after.toLocaleString()} tokens, retrying)`,
+          });
+          continue;
+        }
+
+        // Retryable transient error — backoff
+        if (this.isRetryable(e) && attempt < this.maxRetries) {
+          const delay = this.getRetryDelay(e, attempt);
+          const status = (e as any).status;
+          const reason = status === 429 ? "rate limited" : `error ${status ?? "network"}`;
+          this.bus.emit("ui:info", {
+            message: `(${reason}, retrying in ${Math.ceil(delay / 1000)}s — attempt ${attempt + 2}/${this.maxRetries + 1})`,
+          });
+          await new Promise<void>((resolve, reject) => {
+            const timer = setTimeout(resolve, delay);
+            signal.addEventListener("abort", () => { clearTimeout(timer); reject(new Error("aborted")); }, { once: true });
+          });
+          continue;
+        }
+
+        // Non-retryable or exhausted retries
+        throw e;
+      }
+    }
+    // Should not reach here, but TypeScript needs it
+    throw new Error("Retry loop exhausted");
+  }
+
+  /**
+   * Stream a single LLM response. Returns accumulated text, parsed tool calls,
+   * and the raw assistant message data for conversation recording.
+   */
+  private async streamResponse(
+    systemPrompt: string,
+    dynamicContext: string,
+    signal: AbortSignal,
+  ): Promise<{
+    text: string;
+    toolCalls: PendingToolCall[];
+    /** Provider-specific fields (reasoning, reasoning_details, …) to
+     *  echo back verbatim on the next turn. */
+    extras?: Record<string, unknown>;
+  }> {
+    let text = "";
+    // reasoning_details streams as per-chunk fragments keyed by index;
+    // merge .text per index or the provider rejects the fragmented shape.
+    let reasoningField: string | null = null;
+    let reasoning = "";
+    const reasoningDetailsByIndex = new Map<number, Record<string, unknown>>();
+    const pendingToolCalls: PendingToolCall[] = [];
+
+    // Tool protocol controls what goes in the API tools param vs dynamic context.
+    // agent:tools:visible is a filter point on the assembled list — distinct from
+    // getTools(), which other code (e.g. tool bridges) needs unfiltered.
+    const toolView = this.bus.emitPipe("agent:tools:visible", { tools: this.getTools() }).tools;
+    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 = [
+      { role: "system" as const, content: systemPrompt },
+      ...wrapTrailingWithDynamicContext(this.conversation.forLLM(), dynamicContext, toolPrompt),
+    ];
+
+    // Let extensions transform the message array (compact, summarize, filter, etc.)
+    const messages = this.handlers.call("conversation:prepare", rawMessages);
+
+    // Stream filter strips tool tags from display (inline mode only)
+    const streamFilter = this.toolProtocol.createStreamFilter(
+      toolView.map((t) => t.name),
+    );
+
+    const requestParams = {
+      messages,
+      tools: apiTools,
+      model: this.activeModel.id,
+      max_tokens: this.activeModel.maxTokens ?? 65536,
+      ...this.reasoningParams(),
+    };
+    this.bus.emit("llm:request", requestParams);
+
+    const stream = await this.llmClient.stream({ ...requestParams, signal });
+
+    try {
+    for await (const chunk of stream) {
+      if (signal.aborted) break;
+      this.bus.emit("llm:chunk", { chunk });
+
+      // Token usage (may arrive in a chunk with empty choices)
+      if ((chunk as any).usage) {
+        const u = (chunk as any).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 } : {}),
+        });
+        if (promptTokens > 0) {
+          this.conversation.updateApiTokenCount(promptTokens);
+        }
+      }
+
+      const choice = chunk.choices[0];
+      if (!choice) continue;
+
+      const delta = choice.delta;
+
+      if (delta?.content) {
+        text += delta.content;
+        const displayText = streamFilter
+          ? streamFilter.feed(delta.content)
+          : delta.content;
+        if (displayText) {
+          this.bus.emitTransform("agent:response-chunk", {
+            blocks: [{ type: "text", text: displayText }],
+          });
+        }
+      }
+
+      const d = delta as any;
+      for (const name of ["reasoning", "reasoning_content"] as const) {
+        if (typeof d?.[name] === "string" && d[name].length > 0) {
+          reasoning += d[name];
+          reasoningField ??= name;
+          this.bus.emit("agent:thinking-chunk", { text: d[name] });
+        }
+      }
+      if (Array.isArray(d?.reasoning_details)) {
+        for (const x of d.reasoning_details) {
+          const idx = typeof x?.index === "number" ? x.index : reasoningDetailsByIndex.size;
+          const prev = reasoningDetailsByIndex.get(idx);
+          if (!prev) {
+            reasoningDetailsByIndex.set(idx, { ...x });
+          } else {
+            if (typeof x.text === "string") prev.text = (prev.text ?? "") + x.text;
+            for (const [k, v] of Object.entries(x)) if (k !== "text" && prev[k] === undefined) prev[k] = v;
+          }
+        }
+      }
+
+      // Tool calls (streamed incrementally)
+      if (delta?.tool_calls) {
+        for (const tc of delta.tool_calls) {
+          const idx = tc.index;
+
+          if (!pendingToolCalls[idx]) {
+            pendingToolCalls[idx] = {
+              id: tc.id!,
+              name: tc.function!.name!,
+              argumentsJson: "",
+            };
+          }
+
+          if (tc.function?.arguments) {
+            pendingToolCalls[idx].argumentsJson +=
+              tc.function.arguments;
+          }
+        }
+      }
+    }
+    } catch (e) {
+      // On abort, fall through with whatever was accumulated so far.
+      if (!signal.aborted) throw e;
+    }
+
+    if (streamFilter) {
+      const remaining = streamFilter.flush();
+      if (remaining) {
+        this.bus.emitTransform("agent:response-chunk", {
+          blocks: [{ type: "text", text: remaining }],
+        });
+      }
+    }
+
+    // Normalize arguments JSON — some providers (Alibaba/qwen) strictly
+    // validate `function.arguments` as parseable JSON on the NEXT turn,
+    // and reject empty strings or partial chunks. OpenAI itself is lenient,
+    // so empty "" slips through locally but the replay breaks upstream.
+    for (const tc of pendingToolCalls) {
+      if (!tc) continue;
+      const s = tc.argumentsJson.trim();
+      if (s === "") { tc.argumentsJson = "{}"; continue; }
+      try { JSON.parse(s); } catch { tc.argumentsJson = "{}"; }
+    }
+
+    // Echo reasoning only for modes that opt in (e.g. DeepSeek-R1).
+    const extras: Record<string, unknown> = {};
+    if (this.activeModel.echoReasoning) {
+      if (reasoning && reasoningField) extras[reasoningField] = reasoning;
+      if (reasoningDetailsByIndex.size > 0) {
+        extras.reasoning_details = [...reasoningDetailsByIndex.entries()]
+          .sort((a, b) => a[0] - b[0]).map(([, v]) => v);
+      }
+    }
+    return {
+      text,
+      toolCalls: pendingToolCalls,
+      extras: Object.keys(extras).length > 0 ? extras : undefined,
+    };
+  }
+}