agent-sh 0.10.0 → 0.10.1

package/README.md

@@ -44,7 +44,7 @@ Requires Node.js 18+.
 
 **Context that just works.** Every query includes your cwd, recent commands, and their output. Run a failing test, type `> fix this`, and agent-sh knows exactly what happened. Context management works like shell history — continuous, persistent across restarts, no sessions to manage. See [Context Management](docs/context-management.md).
 
-**Any LLM, any backend.** agent-sh works with any OpenAI-compatible API out of the box. Define multiple providers in settings and cycle between models at runtime with Shift+Tab. Or swap in a completely different agent — [Claude Code](examples/extensions/claude-code-bridge/) and [pi](examples/extensions/pi-bridge/) run as drop-in backend extensions.
+**Any LLM, any backend.** agent-sh works with any OpenAI-compatible API out of the box. Define multiple providers in settings and switch models at runtime with `/model <name>`. Or swap in a completely different agent — [Claude Code](examples/extensions/claude-code-bridge/) and [pi](examples/extensions/pi-bridge/) run as drop-in backend extensions.
 
 **Extensible by design.** The entire system is built on a typed event bus. Extensions can add custom input modes, content transforms (render LaTeX as images, Mermaid as diagrams), themes, slash commands, or replace the agent backend entirely. The built-in TUI renderer is itself just an extension.
 
@@ -52,14 +52,16 @@ Requires Node.js 18+.
 
 ## Documentation
 
-- [Usage Guide](docs/usage.md) — providers, models, configuration
-- [Internal Agent](docs/agent.md) — tools, context, streaming
-- [Context Management](docs/context-management.md) — three-tier history, token budget
-- [Architecture](docs/architecture.md) — design philosophy, component overview
-- [Extensions](docs/extensions.md) — event bus, content transforms, custom backends, theming
-- [TUI Composition](docs/tui-composition.md) — compositor, render surfaces, stream routing
-- [Library Usage](docs/library.md) — embedding agent-sh in your own apps
-- [Troubleshooting](docs/troubleshooting.md) — common errors and debug mode
+Start with **Usage** to get running, then **Architecture** for the mental model.
+
+1. [Usage Guide](docs/usage.md) — install, run, configure providers and models
+2. [Architecture](docs/architecture.md) — pure kernel + extensions, the shell ↔ agent boundary
+3. [The Built-in Agent: ash](docs/agent.md) — query flow, tools, system prompt, model switching
+4. [Context Management](docs/context-management.md) — shell-output spill, three-tier conversation compaction, recall APIs
+5. [Extensions](docs/extensions.md) — event bus, content transforms, custom agent backends, theming
+6. [TUI Composition](docs/tui-composition.md) — compositor, render surfaces, stream routing
+7. [Library Usage](docs/library.md) — embedding agent-sh in your own apps
+8. [Troubleshooting](docs/troubleshooting.md) — common errors and debug mode
 
 ## Development
 

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

@@ -4,7 +4,6 @@
  * Subscribes to bus events in constructor:
  *   - agent:submit → run query through LLM tool loop
  *   - agent:cancel-request → abort current loop
- *   - config:cycle → cycle through modes
  *
  * Emits bus events during execution:
  *   - agent:query, agent:processing-start/done, agent:response-chunk/done
@@ -36,7 +35,6 @@ export declare class AgentLoop implements AgentBackend {
     private historyFile;
     private conversation;
     private fileReadCache;
-    private tokenBudget;
     private modes;
     private currentModeIndex;
     private boundListeners;
@@ -104,7 +102,6 @@ export declare class AgentLoop implements AgentBackend {
     private cancel;
     /** Check if reasoning_effort should be sent for the current model/provider. */
     private shouldSendReasoningEffort;
-    private cycleMode;
     private get currentMode();
     private get currentModel();
     /**

package/dist/agent/agent-loop.js

@@ -8,7 +8,8 @@ import { HistoryFile } from "./history-file.js";
 import { nucleate, formatNuclearLine, isReadOnly } from "./nuclear-form.js";
 import { STATIC_SYSTEM_PROMPT, buildDynamicContext, buildStaticByCwd, formatSkillsBlock, loadGlobalAgentsMd } from "./system-prompt.js";
 import { createToolUI } from "../utils/tool-interactive.js";
-import { TokenBudget, RESPONSE_RESERVE, DEFAULT_CONTEXT_WINDOW } from "./token-budget.js";
+import { RESPONSE_RESERVE, DEFAULT_CONTEXT_WINDOW } from "./token-budget.js";
+import { PACKAGE_VERSION } from "../utils/package-version.js";
 import { getSettings, updateSettings } from "../settings.js";
 import { createToolProtocol } from "./tool-protocol.js";
 // Core tool factories
@@ -40,7 +41,6 @@ export class AgentLoop {
     historyFile;
     conversation;
     fileReadCache = new Map();
-    tokenBudget;
     modes;
     currentModeIndex = 0;
     boundListeners = [];
@@ -105,8 +105,6 @@ export class AgentLoop {
             ? config.modes
             : [{ model: config.llmClient.model }];
         this.currentModeIndex = config.initialModeIndex ?? 0;
-        // Unified token budget — adapts to current model's context window
-        this.tokenBudget = new TokenBudget(this.currentMode.contextWindow);
         // Tool protocol — controls how tools are presented to the LLM
         this.toolProtocol = createToolProtocol(getSettings().toolMode ?? "api");
         // Register core tools
@@ -115,8 +113,6 @@ export class AgentLoop {
         const protocolTools = this.toolProtocol.getProtocolTools?.() ?? [];
         for (const t of protocolTools)
             this.registerTool(t);
-        // Update token budget with tool count
-        this.tokenBudget.update(undefined, this.toolRegistry.all().length);
         // Register handlers — extensions can advise these
         this.registerHandlers();
         // Subscribe to bus-based tool/instruction registration from extensions.
@@ -165,7 +161,6 @@ export class AgentLoop {
             else {
                 this.llmClient.model = m.model;
             }
-            this.tokenBudget.update(m.contextWindow, this.toolRegistry.all().length);
             this.bus.emit("config:changed", {});
         });
         const getToolsPipe = () => ({ tools: this.getTools() });
@@ -184,7 +179,6 @@ export class AgentLoop {
         on("agent:cancel-request", (e) => {
             this.abortController?.abort(e.silent ? "silent" : undefined);
         });
-        on("config:cycle", () => this.cycleMode());
         on("config:switch-model", ({ model: target }) => {
             const idx = this.modes.findIndex((m) => m.model === target);
             if (idx === -1) {
@@ -199,9 +193,8 @@ export class AgentLoop {
             else {
                 this.llmClient.model = m.model;
             }
-            this.tokenBudget.update(m.contextWindow, this.toolRegistry.all().length);
             const label = m.provider ? `${m.provider}: ${m.model}` : m.model;
-            this.bus.emit("agent:info", { name: "ash", version: "0.4", model: m.model, provider: m.provider, contextWindow: m.contextWindow });
+            this.bus.emit("agent:info", { name: "ash", version: PACKAGE_VERSION, model: m.model, provider: m.provider, contextWindow: m.contextWindow });
             // 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
@@ -428,30 +421,6 @@ export class AgentLoop {
             return false;
         return true;
     }
-    cycleMode() {
-        const prevMode = this.modes[this.currentModeIndex];
-        this.currentModeIndex =
-            (this.currentModeIndex + 1) % this.modes.length;
-        const newMode = this.modes[this.currentModeIndex];
-        // Reconfigure LlmClient if provider changed
-        if (newMode.provider !== prevMode.provider && newMode.providerConfig) {
-            this.llmClient.reconfigure({
-                apiKey: newMode.providerConfig.apiKey,
-                baseURL: newMode.providerConfig.baseURL,
-                model: newMode.model,
-            });
-        }
-        else {
-            this.llmClient.model = newMode.model;
-        }
-        this.tokenBudget.update(newMode.contextWindow, this.toolRegistry.all().length);
-        const label = newMode.provider
-            ? `${newMode.provider}: ${newMode.model}`
-            : newMode.model;
-        this.bus.emit("agent:info", { name: "ash", version: "0.4", model: newMode.model, provider: newMode.provider, contextWindow: newMode.contextWindow });
-        this.bus.emit("ui:info", { message: `Model: ${label}` });
-        this.bus.emit("config:changed", {});
-    }
     get currentMode() {
         return this.modes[this.currentModeIndex];
     }
@@ -1066,7 +1035,15 @@ export class AgentLoop {
             const contextWindow = this.currentMode.contextWindow ?? DEFAULT_CONTEXT_WINDOW;
             const threshold = Math.floor((contextWindow - RESPONSE_RESERVE) * getSettings().autoCompactThreshold);
             if (totalEstimate > threshold) {
-                this.compactWithHooks(threshold);
+                const result = this.compactWithHooks(threshold);
+                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.contextManager.getCwd();

package/dist/agent/conversation-state.js

@@ -217,12 +217,18 @@ export class ConversationState {
         if (!force && convEstimate <= convTarget)
             return null;
         const turns = this.parseTurns();
-        if (turns.length <= 2)
+        // With force, allow compacting down to 1 turn (the current response).
+        // Without force, keep at least 2 turns (user + agent) to avoid
+        // annihilating a young conversation.
+        if (turns.length <= (force ? 1 : 2))
             return null;
         // Cap the pinned window so enough turns remain evictable.
         const maxPinnedFraction = force ? 0.4 : 0.6;
         const maxPinned = Math.max(2, Math.floor(turns.length * maxPinnedFraction));
-        const pinnedCount = Math.min(recentTurnsToKeep, turns.length - 1, maxPinned);
+        // Ensure at least 1 turn is evictable when force is true, even in
+        // very short conversations (e.g. 3 turns with heavy tool output).
+        const maxPinnedForced = force ? Math.min(maxPinned, turns.length - 2) : maxPinned;
+        const pinnedCount = Math.min(recentTurnsToKeep, turns.length - 1, Math.max(1, maxPinnedForced));
         for (let i = 0; i < turns.length; i++) {
             turns[i].priority = this.inferPriority(turns[i].messages);
         }

package/dist/agent/token-budget.d.ts

@@ -1,14 +1,10 @@
+/**
+ * Shared token-budget constants used by auto-compaction.
+ *
+ * RESPONSE_RESERVE: tokens reserved for the model's output.
+ * DEFAULT_CONTEXT_WINDOW: fallback when the active mode doesn't declare one.
+ */
 /** Response reserve — tokens reserved for the model's output. */
-declare const RESPONSE_RESERVE = 8192;
+export declare const RESPONSE_RESERVE = 8192;
 /** Fallback when contextWindow is unknown. */
-declare const DEFAULT_CONTEXT_WINDOW = 60000;
-export { RESPONSE_RESERVE, DEFAULT_CONTEXT_WINDOW };
-export declare class TokenBudget {
-    private contextWindow;
-    private toolCount;
-    constructor(contextWindow?: number, toolCount?: number);
-    /** Update when model or tool set changes. */
-    update(contextWindow?: number, toolCount?: number): void;
-    /** Token budget for the shell context stream. */
-    get shellBudgetTokens(): number;
-}
+export declare const DEFAULT_CONTEXT_WINDOW = 60000;

package/dist/agent/token-budget.js

@@ -1,45 +1,10 @@
 /**
- * Token budget for shell context sizing.
+ * Shared token-budget constants used by auto-compaction.
  *
- * Computes how much of the context window to allocate to shell history
- * (user commands and outputs — situational awareness). The remaining
- * space is for the conversation, system prompt, tools, and response.
- *
- * Shell context is sized loosely — chars/4 accuracy is fine for this.
- * Conversation and compaction decisions use API-grounded token counts
- * (see ConversationState.estimatePromptTokens).
+ * RESPONSE_RESERVE: tokens reserved for the model's output.
+ * DEFAULT_CONTEXT_WINDOW: fallback when the active mode doesn't declare one.
  */
-import { getSettings } from "../settings.js";
-const SYSTEM_PROMPT_OVERHEAD = 800;
-const DYNAMIC_CONTEXT_OVERHEAD = 500; // conventions, metadata, skills list
-const TOKENS_PER_TOOL_DEFINITION = 50;
 /** Response reserve — tokens reserved for the model's output. */
-const RESPONSE_RESERVE = 8192;
+export const RESPONSE_RESERVE = 8192;
 /** Fallback when contextWindow is unknown. */
-const DEFAULT_CONTEXT_WINDOW = 60_000;
-export { RESPONSE_RESERVE, DEFAULT_CONTEXT_WINDOW };
-export class TokenBudget {
-    contextWindow;
-    toolCount;
-    constructor(contextWindow, toolCount = 0) {
-        this.contextWindow = contextWindow ?? DEFAULT_CONTEXT_WINDOW;
-        this.toolCount = toolCount;
-    }
-    /** Update when model or tool set changes. */
-    update(contextWindow, toolCount) {
-        if (contextWindow != null)
-            this.contextWindow = contextWindow;
-        if (toolCount != null)
-            this.toolCount = toolCount;
-    }
-    /** Token budget for the shell context stream. */
-    get shellBudgetTokens() {
-        const overhead = SYSTEM_PROMPT_OVERHEAD +
-            DYNAMIC_CONTEXT_OVERHEAD +
-            this.toolCount * TOKENS_PER_TOOL_DEFINITION +
-            RESPONSE_RESERVE;
-        const contentBudget = Math.max(0, this.contextWindow - overhead);
-        const ratio = getSettings().shellContextRatio;
-        return Math.floor(contentBudget * ratio);
-    }
-}
+export const DEFAULT_CONTEXT_WINDOW = 60_000;

package/dist/agent/types.d.ts

@@ -4,7 +4,6 @@
  * Backends self-wire to bus events in their constructor:
  *   - agent:submit → handle queries
  *   - agent:cancel-request → handle cancellation
- *   - config:cycle → handle mode switching
  *
  * They emit bus events for results:
  *   - agent:response-chunk, agent:tool-started, agent:tool-completed, etc.

package/dist/context-manager.d.ts

@@ -4,26 +4,13 @@ export declare class ContextManager {
     private exchanges;
     private nextId;
     private currentCwd;
-    private sessionStart;
-    private firstPrompt;
     private agentShellActive;
-    private handlers;
-    constructor(bus: EventBus, handlers?: HandlerRegistry);
+    constructor(bus: EventBus, _handlers?: HandlerRegistry);
     getCwd(): string;
-    /**
-     * Build the <shell_context> block for the agent prompt.
-     * Pipeline: window → truncate → format
-     */
-    getContext(budget?: number): string;
     /**
      * Regex/keyword search across all exchanges. Returns formatted results.
      */
     search(query: string): string;
-    /**
-     * Return content for specific exchange IDs.
-     * Optional start/end restrict to a line range (1-indexed).
-     */
-    expand(ids: number[], start?: number, end?: number): string;
     /**
      * Return shell events with id > afterId, formatted as an incremental
      * delta suitable for injection into conversation history. Skips
@@ -45,17 +32,10 @@ export declare class ContextManager {
      * One-line summaries of last N exchanges.
      */
     getRecentSummary(n?: number): string;
-    /**
-     * Parse and handle shell_recall commands.
-     */
-    handleRecallCommand(command: string): string;
     /**
      * Clear exchange history (used by /clear command).
      */
     clear(): void;
-    private applyWindow;
-    private applyTruncation;
-    private formatContext;
     private addExchange;
     private formatExchangeTruncated;
     private formatExchangeFull;

package/dist/context-manager.js

@@ -1,32 +1,43 @@
 import { getSettings } from "./settings.js";
+import { spillOutput } from "./utils/shell-output-spill.js";
 export class ContextManager {
     exchanges = [];
     nextId = 1;
     currentCwd;
-    sessionStart;
-    firstPrompt = true;
     agentShellActive = false; // true while user_shell command is executing
-    handlers = null;
-    constructor(bus, handlers) {
-        if (handlers) {
-            this.handlers = handlers;
-            // Extensions can advise this to inject extra context (e.g. terminal buffer)
-            handlers.define("context:build-extra", () => "");
-        }
+    constructor(bus, _handlers) {
         this.currentCwd = process.cwd();
-        this.sessionStart = Date.now();
         // ── Subscribe to shell events ──
         bus.on("shell:command-done", (e) => {
             const lines = e.output.split("\n");
+            const s = getSettings();
+            // Spill long outputs to a tempfile so the agent can `read_file` them
+            // on demand instead of carrying the full text in LLM context.
+            let output = e.output;
+            let spillPath;
+            if (lines.length > s.shellTruncateThreshold) {
+                // Reserve the id we're about to assign so the tempfile name matches.
+                const id = this.nextId;
+                try {
+                    spillPath = spillOutput(id, e.output);
+                    output = buildSpillStub(lines, s.shellHeadLines, s.shellTailLines, spillPath);
+                }
+                catch {
+                    // If spill fails (e.g. disk full), fall back to keeping output in memory.
+                    output = e.output;
+                    spillPath = undefined;
+                }
+            }
             this.addExchange({
                 type: "shell_command",
                 command: e.command,
-                output: e.output,
+                output,
                 cwd: e.cwd,
                 exitCode: e.exitCode,
                 outputLines: lines.length,
                 outputBytes: e.output.length,
                 source: this.agentShellActive ? "agent" : "user",
+                spillPath,
             });
         });
         bus.on("shell:cwd-change", (e) => {
@@ -46,16 +57,6 @@ export class ContextManager {
     getCwd() {
         return this.currentCwd;
     }
-    /**
-     * Build the <shell_context> block for the agent prompt.
-     * Pipeline: window → truncate → format
-     */
-    getContext(budget) {
-        budget ??= getSettings().contextBudget;
-        let exchanges = this.applyWindow(this.exchanges);
-        exchanges = this.applyTruncation(exchanges, budget);
-        return this.formatContext(exchanges);
-    }
     /**
      * Regex/keyword search across all exchanges. Returns formatted results.
      */
@@ -106,40 +107,6 @@ export class ContextManager {
         }
         return parts.join("\n");
     }
-    /**
-     * Return content for specific exchange IDs.
-     * Optional start/end restrict to a line range (1-indexed).
-     */
-    expand(ids, start, end) {
-        const results = [];
-        for (const id of ids) {
-            const ex = this.exchanges.find((e) => e.id === id);
-            if (!ex) {
-                results.push(`#${id}: not found`);
-                continue;
-            }
-            const text = this.formatExchangeFull(ex);
-            const lines = text.split("\n");
-            const total = lines.length;
-            if (start != null || end != null) {
-                // Line range requested
-                const s = Math.max(0, (start ?? 1) - 1);
-                const e = end ?? total;
-                results.push(lines.slice(s, e).join("\n") +
-                    `\n[showing lines ${s + 1}-${Math.min(e, total)} of ${total}]`);
-            }
-            else if (total > getSettings().recallExpandMaxLines) {
-                // Too large — tell the agent to narrow down
-                results.push(`#${ex.id}: output is ${total} lines, too large to expand fully. ` +
-                    `Use start/end params to select a line range (e.g. start=1, end=50), ` +
-                    `or use search with a regex to find specific content.`);
-            }
-            else {
-                results.push(text);
-            }
-        }
-        return results.join("\n\n");
-    }
     /**
      * Return shell events with id > afterId, formatted as an incremental
      * delta suitable for injection into conversation history. Skips
@@ -156,18 +123,8 @@ export class ContextManager {
         if (fresh.length === 0)
             return null;
         const lastSeq = this.exchanges[this.exchanges.length - 1].id;
-        // Apply per-type truncation so giant outputs don't blow up the turn.
-        const truncated = fresh.map((ex) => {
-            if (ex.type === "shell_command") {
-                const s = getSettings();
-                return {
-                    ...ex,
-                    output: truncateOutput(ex.output, s.shellTruncateThreshold, s.shellHeadLines, s.shellTailLines, ex.id),
-                };
-            }
-            return { ...ex };
-        });
-        const body = truncated.map((ex) => this.formatExchangeTruncated(ex)).join("\n");
+        // Outputs already carry head+tail+spillPath stubs from capture time.
+        const body = fresh.map((ex) => this.formatExchangeTruncated(ex)).join("\n");
         return {
             text: `<shell-events>\n${body}</shell-events>`,
             lastSeq,
@@ -186,104 +143,13 @@ export class ContextManager {
             return "No exchanges yet.";
         return recent.map((ex) => this.exchangeOneLiner(ex)).join("\n");
     }
-    /**
-     * Parse and handle shell_recall commands.
-     */
-    handleRecallCommand(command) {
-        const args = command.replace(/^_*shell_recall\s*/, "").trim();
-        if (!args || args === "--help") {
-            return [
-                "Usage:",
-                "  shell_recall                    Browse recent exchanges",
-                "  shell_recall --search <query>   Search all exchanges",
-                "  shell_recall --expand <id,...>   Show full content of exchanges",
-                "",
-                "Examples:",
-                '  shell_recall --search "test fail"',
-                "  shell_recall --expand 41",
-                "  shell_recall --expand 41,42,43",
-            ].join("\n");
-        }
-        const searchMatch = args.match(/^--search\s+(?:"([^"]+)"|(\S+))/);
-        if (searchMatch) {
-            return this.search(searchMatch[1] ?? searchMatch[2] ?? "");
-        }
-        const expandMatch = args.match(/^--expand\s+([\d,\s]+)/);
-        if (expandMatch) {
-            const ids = expandMatch[1]
-                .split(/[,\s]+/)
-                .map(Number)
-                .filter((n) => !isNaN(n));
-            if (ids.length === 0)
-                return "No valid IDs provided.";
-            return this.expand(ids);
-        }
-        // Default: browse
-        return this.getRecentSummary();
-    }
     /**
      * Clear exchange history (used by /clear command).
      */
     clear() {
         this.exchanges = [];
-        this.firstPrompt = true;
         // Don't reset nextId — IDs should be globally unique within a session
     }
-    // ── Pipeline stages ───────────────────────────────────────────
-    applyWindow(exchanges, windowSize) {
-        windowSize ??= getSettings().contextWindowSize;
-        return exchanges.slice(-windowSize);
-    }
-    applyTruncation(exchanges, budget) {
-        // Deep clone so we don't mutate the source
-        const result = exchanges.map((e) => ({ ...e }));
-        // Pass 1: per-type truncation
-        for (const ex of result) {
-            if (ex.type === "shell_command") {
-                const s = getSettings();
-                ex.output = truncateOutput(ex.output, s.shellTruncateThreshold, s.shellHeadLines, s.shellTailLines, ex.id);
-            }
-            // agent_query has no output to truncate
-        }
-        // Pass 2: budget enforcement — strip output from oldest if over budget
-        let totalSize = result.reduce((sum, ex) => sum + this.exchangeSize(ex), 0);
-        for (let i = 0; i < result.length - 1 && totalSize > budget; i++) {
-            const ex = result[i];
-            const before = this.exchangeSize(ex);
-            if (ex.type === "shell_command") {
-                ex.output = `[output omitted, use shell_recall tool to expand id ${ex.id}]`;
-            }
-            totalSize -= before - this.exchangeSize(ex);
-        }
-        return result;
-    }
-    formatContext(exchanges) {
-        const elapsed = Math.round((Date.now() - this.sessionStart) / 60000);
-        const totalCount = this.exchanges.length;
-        let out = "<shell_context>\n";
-        if (this.firstPrompt) {
-            out += `You are an AI assistant living inside agent-sh, a shell-first terminal.\n`;
-            out += `The user interacts with a real shell (PTY) and sends you queries inline. You are there to help them with their tasks.\n`;
-            out += `\n`;
-            out += `IMPORTANT tool usage rules:\n`;
-            out += `- Your internal tools (bash, read, write, ls, etc.) run in an isolated subprocess. The user CANNOT see their output.\n`;
-            out += `- Only use internal tools when YOU need to reason about content silently (e.g. reading a file to answer a question about it).\n`;
-            out += `- You can browse or search shell history with shell_recall.\n`;
-            out += `\n`;
-            this.firstPrompt = false;
-        }
-        out += `cwd: ${this.currentCwd}\n`;
-        out += `session: ${totalCount} exchanges, ${elapsed}m elapsed\n`;
-        for (const ex of exchanges) {
-            out += "\n" + this.formatExchangeTruncated(ex);
-        }
-        // Allow extensions to inject extra context (e.g. terminal buffer snapshot)
-        const extra = this.handlers?.call("context:build-extra");
-        if (extra)
-            out += "\n" + extra + "\n";
-        out += "\n</shell_context>\n";
-        return out;
-    }
     // ── Internal helpers ──────────────────────────────────────────
     addExchange(partial) {
         const exchange = {
@@ -352,14 +218,11 @@ export class ContextManager {
     }
 }
 // ── Utility functions ─────────────────────────────────────────
-function truncateOutput(text, threshold, headLines, tailLines, id) {
-    const lines = text.split("\n");
-    if (lines.length <= threshold)
-        return text;
+function buildSpillStub(lines, headLines, tailLines, spillPath) {
     const omitted = lines.length - headLines - tailLines;
     return [
         ...lines.slice(0, headLines),
-        `[... ${omitted} lines truncated, use shell_recall tool with expand and id ${id} to see full output ...]`,
+        `[... ${omitted} lines truncated — full output at ${spillPath}; use read_file to expand ...]`,
         ...lines.slice(-tailLines),
     ].join("\n");
 }

package/dist/event-bus.d.ts

@@ -238,7 +238,6 @@ export interface ShellEvents {
         active: string | null;
     };
     "config:changed": Record<string, never>;
-    "config:cycle": Record<string, never>;
     "config:switch-model": {
         model: string;
     };

package/dist/extension-loader.js

@@ -5,12 +5,33 @@ const EXT_DIR = path.join(CONFIG_DIR, "extensions");
 const TS_EXTS = [".ts", ".tsx", ".mts"];
 const SCRIPT_EXTS = [".js", ".mjs", ".ts", ".tsx", ".mts"];
 let tsRegistered = false;
-async function ensureTsSupport() {
-    if (tsRegistered)
+let tsxUnregister = null;
+/**
+ * Register tsx's ESM loader for .ts file support.
+ *
+ * Called before importing .ts extensions. The tsx loader uses Node's
+ * module.register() which creates a background thread with a MessageChannel.
+ * On reload, the old loader may become stale (the MessageChannel port can be
+ * GC'd or the loader thread can stop responding), so we unregister the old
+ * handle and re-register on each reload.
+ *
+ * Initial load: registers fresh.
+ * Reload: unregisters old handle, registers new one.
+ * Non-reload calls within the same load: no-op (tsRegistered guard).
+ */
+async function ensureTsSupport(force = false) {
+    if (tsRegistered && !force)
         return;
     try {
+        // Unregister previous loader if reloading
+        if (tsxUnregister) {
+            try {
+                await tsxUnregister();
+            }
+            catch { /* ignore stale handle */ }
+        }
         const { register } = await import("tsx/esm/api");
-        register();
+        tsxUnregister = register();
         tsRegistered = true;
     }
     catch {
@@ -166,7 +187,7 @@ async function loadSpecifiers(specifiers, ctx, bustCache, userSpecifiers) {
         try {
             let importPath = await resolveSpecifier(specifier);
             if (TS_EXTS.some((ext) => importPath.endsWith(ext))) {
-                await ensureTsSupport();
+                await ensureTsSupport(bustCache);
             }
             // Append timestamp query to bust Node's module cache on reload
             if (bustCache) {

package/dist/extensions/agent-backend.js

@@ -1,6 +1,7 @@
 import { AgentLoop } from "../agent/agent-loop.js";
 import { LlmClient } from "../utils/llm-client.js";
 import { resolveProvider, getProviderNames, getSettings } from "../settings.js";
+import { PACKAGE_VERSION } from "../utils/package-version.js";
 /** Read the user's persisted defaultModel for a provider, if any. */
 function persistedModelFor(providerName) {
     if (!providerName)
@@ -71,7 +72,7 @@ export default function agentBackend(ctx) {
             agentLoop.wire();
             bus.emit("agent:info", {
                 name: "ash",
-                version: "0.4",
+                version: PACKAGE_VERSION,
                 model: llmClient.model,
                 provider: modes[initialModeIndex]?.provider,
                 contextWindow: modes[initialModeIndex]?.contextWindow,
@@ -181,7 +182,7 @@ export default function agentBackend(ctx) {
             };
         });
         bus.emit("config:set-modes", { modes: newModes });
-        bus.emit("agent:info", { name: "ash", version: "0.4", model: switchModel, provider: name, contextWindow: p.contextWindow });
+        bus.emit("agent:info", { name: "ash", version: PACKAGE_VERSION, model: switchModel, provider: name, contextWindow: p.contextWindow });
         bus.emit("ui:info", { message: `Switched to ${name} (${switchModel})` });
         bus.emit("config:changed", {});
     });