agent-sh 0.10.0 → 0.10.2

package/README.md

@@ -4,6 +4,7 @@ An agent that lives in a shell — not a shell that lives in an agent.
 
 [![npm version](https://img.shields.io/npm/v/agent-sh.svg)](https://www.npmjs.com/package/agent-sh)
 [![license](https://img.shields.io/npm/l/agent-sh.svg)](https://github.com/guanyilun/agent-sh/blob/main/LICENSE)
+[![website](https://img.shields.io/badge/website-agent--sh.dev-blue)](https://agent-sh.dev)
 
 ![demo](assets/demo.gif)
 
@@ -44,7 +45,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 +53,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
@@ -287,6 +280,9 @@ export class AgentLoop {
             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);
@@ -428,30 +424,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 +1038,18 @@ 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);
+                // Compact deeply — shallow targets buy only 1–2 turns of runway on
+                // tool-heavy workloads.
+                const target = Math.floor(threshold * 0.25);
+                const result = this.compactWithHooks(target, 6);
+                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/nuclear-form.d.ts

@@ -43,6 +43,8 @@ export declare function createSessionMarker(iid: string, seq?: number): NuclearE
 export declare function isSessionMarker(entry: NuclearEntry): boolean;
 /** Read-only tools whose results are dropped at Tier 1→2 (agent can re-read). */
 export declare const READ_ONLY_TOOLS: Set<string>;
+export declare function registerReadOnlyTool(name: string): void;
+export declare function unregisterReadOnlyTool(name: string): void;
 /** State-changing tools whose summaries are kept in nuclear memory. */
 export declare const WRITE_TOOLS: Set<string>;
 /**

package/dist/agent/nuclear-form.js

@@ -15,6 +15,14 @@ export function isSessionMarker(entry) {
 export const READ_ONLY_TOOLS = new Set([
     "read_file", "grep", "glob", "ls", "search",
 ]);
+/** Extensions opt their tools in via ToolRegistry.register when readOnly is set. */
+const extraReadOnlyTools = new Set();
+export function registerReadOnlyTool(name) {
+    extraReadOnlyTools.add(name);
+}
+export function unregisterReadOnlyTool(name) {
+    extraReadOnlyTools.delete(name);
+}
 /** State-changing tools whose summaries are kept in nuclear memory. */
 export const WRITE_TOOLS = new Set([
     "write_file", "edit_file", "write", "edit", "patch",
@@ -188,7 +196,9 @@ export function deserializeEntry(line) {
 // ── Classification helpers ────────────────────────────────────────
 /** Check if a nuclear entry represents a read-only action (should be dropped). */
 export function isReadOnly(entry) {
-    return entry.kind === "tool" && entry.tool != null && READ_ONLY_TOOLS.has(entry.tool);
+    if (entry.kind !== "tool" || entry.tool == null)
+        return false;
+    return READ_ONLY_TOOLS.has(entry.tool) || extraReadOnlyTools.has(entry.tool);
 }
 // ── Internal helpers ──────────────────────────────────────────────
 function truncate(text, maxLen) {

package/dist/agent/system-prompt.js

@@ -89,7 +89,7 @@ function loadConventionFiles(dir) {
  * Static system prompt — identical across all queries, cacheable.
  * Contains only identity and behavioral instructions.
  */
-export const STATIC_SYSTEM_PROMPT = `You are an AI coding assistant running inside agent-sh, a terminal shell.
+export const STATIC_SYSTEM_PROMPT = `You are ash, an AI coding assistant running inside agent-sh, a terminal shell.
 You have access to the user's shell environment and can read, write, and execute code.
 You share the user's working directory, environment variables, and shell history.
 agent-sh documentation is at ${path.join(CODE_DIR, "docs")} — start with README.md for an index. Read the docs when you need to understand how the runtime works.

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/tool-registry.js

@@ -1,3 +1,4 @@
+import { registerReadOnlyTool, unregisterReadOnlyTool } from "./nuclear-form.js";
 /**
  * Registry for agent tools. Holds tool definitions and converts them
  * to OpenAI-compatible function schemas for API calls.
@@ -6,9 +7,14 @@ export class ToolRegistry {
     tools = new Map();
     register(tool) {
         this.tools.set(tool.name, tool);
+        if (tool.readOnly)
+            registerReadOnlyTool(tool.name);
+        else
+            unregisterReadOnlyTool(tool.name);
     }
     unregister(name) {
         this.tools.delete(name);
+        unregisterReadOnlyTool(name);
     }
     get(name) {
         return this.tools.get(name);

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.
@@ -78,6 +77,9 @@ export interface ToolDefinition {
     showOutput?: boolean;
     /** Whether this tool may modify files — triggers file watcher (default: false). */
     modifiesFiles?: boolean;
+    /** Results are re-fetchable; nuclear compaction drops the tool_result
+     *  body on eviction (like the builtin read_file/grep/ls). Default: false. */
+    readOnly?: boolean;
     /** Whether to gate execution via permission:request (default: false). */
     requiresPermission?: boolean;
     /** Derive display metadata (icon kind, file paths) for the TUI. */

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;