agent-sh 0.6.0 → 0.8.0

package/README.md

@@ -21,7 +21,7 @@ agent-sh flips this. It's your shell first — full PTY, your rc config, your al
 
 **Real terminal, zero compromise.** Full PTY with your shell config, aliases, and environment. Shell starts instantly — the agent connects asynchronously in the background.
 
-**Context-aware agent.** Every query includes your cwd, recent commands, and their output. Run a failing test, type `> fix this`, and the agent knows exactly what happened. It has built-in tools for file read/write/edit, bash, grep, glob — no external setup needed.
+**Context-aware agent.** Every query includes your cwd, recent commands, and their output. Run a failing test, type `> fix this`, and the agent knows exactly what happened. It has built-in tools for file read/write/edit, bash, grep, glob — no external setup needed. Context management works like shell history — continuous, persistent across restarts, no sessions to manage. See [Context Management](docs/context-management.md).
 
 **Agent decides how to help.** One entry point (`>`), three tool categories. The agent uses scratchpad tools to investigate, `display` to show you output, and `user_shell` for commands with lasting effects. No need to pick a mode — the agent reasons about which tools to use based on your intent.
 
@@ -59,6 +59,9 @@ Everything else works as a normal shell — commands go straight to the PTY. Inp
 | `/help` | Show available commands |
 | `/model [name]` | Cycle to the next model, or switch to a specific one |
 | `/backend [name]` | List backends, or switch to a named backend |
+| `/compact` | Compact conversation (free up context space) |
+| `/context` | Show context budget usage |
+| `/thinking [level]` | Set reasoning effort (off, low, medium, high) |
 
 ## Configuration
 
@@ -68,6 +71,7 @@ Configure via `~/.agent-sh/settings.json`. See the [Usage Guide](docs/usage.md#c
 
 - [Usage Guide](docs/usage.md) — providers, models, configuration, provider profiles
 - [Internal Agent](docs/agent.md) — how the agent loop works: tools, context, streaming
+- [Context Management](docs/context-management.md) — three-tier history, token budget, design philosophy
 - [Architecture](docs/architecture.md) — design philosophy, component overview, project structure
 - [Extensions](docs/extensions.md) — event bus, content transforms, custom backends, theming
 - [Library Usage](docs/library.md) — embedding agent-sh in your own apps

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

@@ -25,8 +25,10 @@ export declare class AgentLoop implements AgentBackend {
     private handlers;
     private abortController;
     private toolRegistry;
+    private historyFile;
     private conversation;
     private fileReadCache;
+    private tokenBudget;
     private modes;
     private currentModeIndex;
     private boundListeners;
@@ -63,8 +65,6 @@ export declare class AgentLoop implements AgentBackend {
      */
     private registerHandlers;
     private handleQuery;
-    /** Max tokens before auto-compaction (conservative default). */
-    private maxContextTokens;
     /**
      * Core agent loop: stream LLM response → execute tools → repeat.
      * Returns the final accumulated response text.

package/dist/agent/agent-loop.js

@@ -4,7 +4,9 @@ import * as path from "node:path";
 import { computeDiff } from "../utils/diff.js";
 import { ToolRegistry } from "./tool-registry.js";
 import { ConversationState } from "./conversation-state.js";
+import { HistoryFile } from "./history-file.js";
 import { STATIC_SYSTEM_PROMPT, buildDynamicContext } from "./system-prompt.js";
+import { TokenBudget } from "../token-budget.js";
 // Core tool factories
 import { createBashTool } from "./tools/bash.js";
 import { createReadFileTool } from "./tools/read-file.js";
@@ -24,8 +26,10 @@ export class AgentLoop {
     handlers;
     abortController = null;
     toolRegistry = new ToolRegistry();
-    conversation = new ConversationState();
+    historyFile = new HistoryFile();
+    conversation = new ConversationState(this.historyFile);
     fileReadCache = new Map();
+    tokenBudget;
     modes;
     currentModeIndex = 0;
     boundListeners = [];
@@ -42,8 +46,12 @@ export class AgentLoop {
             { model: llmClient.model },
         ];
         this.currentModeIndex = initialModeIndex ?? 0;
+        // Unified token budget — adapts to current model's context window
+        this.tokenBudget = new TokenBudget(this.currentMode.contextWindow);
         // Register core tools
         this.registerCoreTools();
+        // Update token budget with tool count
+        this.tokenBudget.update(undefined, this.toolRegistry.all().length);
         // Register handlers — extensions can advise these
         this.registerHandlers();
     }
@@ -74,6 +82,7 @@ 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: "agent-sh", version: "0.4", model: m.model, provider: m.provider, contextWindow: m.contextWindow });
             this.bus.emit("ui:info", { message: `Model: ${label}` });
@@ -117,13 +126,50 @@ export class AgentLoop {
             else {
                 this.llmClient.model = m.model;
             }
+            this.tokenBudget.update(m.contextWindow, this.toolRegistry.all().length);
+            this.bus.emit("config:changed", {});
+        });
+        on("config:add-modes", ({ modes: extra }) => {
+            // Remove any existing modes for the same provider, then append
+            const providers = new Set(extra.map((m) => m.provider).filter(Boolean));
+            this.modes = [
+                ...this.modes.filter((m) => !m.provider || !providers.has(m.provider)),
+                ...extra,
+            ];
             this.bus.emit("config:changed", {});
         });
         on("agent:reset-session", () => {
             this.cancel();
-            this.conversation = new ConversationState();
+            this.conversation = new ConversationState(this.historyFile);
             this.lastProjectSkillNames.clear();
         });
+        on("agent:compact-request", () => {
+            const budgetTokens = this.tokenBudget.conversationBudgetTokens;
+            const stats = this.conversation.compact(budgetTokens);
+            this.conversation.flush().catch(() => { });
+            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)" });
+            }
+        });
+        this.bus.onPipe("context:get-stats", () => {
+            return {
+                activeTokens: this.conversation.estimateTokens(),
+                nuclearEntries: this.conversation.getNuclearEntryCount(),
+                recallArchiveSize: this.conversation.getRecallArchiveSize(),
+                budgetTokens: this.tokenBudget.conversationBudgetTokens,
+            };
+        });
+        // Load prior history from disk (non-blocking)
+        this.historyFile.readRecent().then((entries) => {
+            if (entries.length > 0) {
+                this.conversation.loadPriorHistory(entries);
+            }
+        }).catch(() => { });
         on("shell:cwd-change", ({ cwd }) => {
             const projectSkills = discoverProjectSkills(cwd);
             const newNames = new Set(projectSkills.map(s => s.name));
@@ -187,6 +233,7 @@ export class AgentLoop {
         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;
@@ -289,6 +336,45 @@ export class AgentLoop {
         this.toolRegistry.register(createUserShellTool({ getCwd, bus: this.bus }));
         this.toolRegistry.register(createDisplayTool({ getCwd, bus: this.bus }));
         this.toolRegistry.register(createListSkillsTool(getCwd));
+        // conversation_recall — search/expand evicted conversation turns
+        this.toolRegistry.register({
+            name: "conversation_recall",
+            description: "Browse, search, or expand evicted conversation turns. " +
+                "Use when you need context from earlier in the conversation that was compacted away.",
+            input_schema: {
+                type: "object",
+                properties: {
+                    action: {
+                        type: "string",
+                        enum: ["browse", "search", "expand"],
+                        description: "browse: list evicted turns, search: regex search, expand: show full turn",
+                    },
+                    query: {
+                        type: "string",
+                        description: "Search query (for action=search)",
+                    },
+                    turn_id: {
+                        type: "number",
+                        description: "Turn ID to expand (for action=expand)",
+                    },
+                },
+                required: ["action"],
+            },
+            execute: async (args) => {
+                const action = args.action;
+                let content;
+                if (action === "search") {
+                    content = await this.conversation.search(args.query ?? "");
+                }
+                else if (action === "expand") {
+                    content = await this.conversation.expand(args.turn_id);
+                }
+                else {
+                    content = await this.conversation.browse();
+                }
+                return { content, exitCode: 0, isError: false };
+            },
+        });
     }
     /**
      * Register named handlers that extensions can advise.
@@ -297,7 +383,7 @@ export class AgentLoop {
     registerHandlers() {
         const h = this.handlers;
         // Extensions compose additional context (git info, project rules, etc.)
-        h.define("dynamic-context:build", () => buildDynamicContext(this.toolRegistry.all(), this.contextManager));
+        h.define("dynamic-context:build", () => buildDynamicContext(this.toolRegistry.all(), this.contextManager, this.tokenBudget.shellBudgetTokens));
         // 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.
@@ -441,8 +527,6 @@ export class AgentLoop {
             this.abortController = null;
         }
     }
-    /** Max tokens before auto-compaction (conservative default). */
-    maxContextTokens = 60_000;
     /**
      * Core agent loop: stream LLM response → execute tools → repeat.
      * Returns the final accumulated response text.
@@ -450,11 +534,16 @@ export class AgentLoop {
     async executeLoop(signal) {
         let fullResponseText = "";
         while (!signal.aborted) {
-            // Auto-compact if conversation is getting large
-            const estimatedTokens = Math.ceil(JSON.stringify(this.conversation.getMessages()).length / 4);
-            if (estimatedTokens > this.maxContextTokens) {
-                this.conversation.compact(10);
-                this.bus.emit("ui:info", { message: "(conversation compacted)" });
+            // Auto-compact if conversation exceeds the model-aware budget
+            const budgetTokens = this.tokenBudget.conversationBudgetTokens;
+            if (this.conversation.estimateTokens() > budgetTokens) {
+                const stats = this.conversation.compact(budgetTokens);
+                await this.conversation.flush();
+                if (stats) {
+                    this.bus.emit("ui:info", {
+                        message: `(compacted: ~${stats.before.toLocaleString()} → ~${stats.after.toLocaleString()} tokens)`,
+                    });
+                }
             }
             // System prompt is static (cacheable); dynamic context uses handler
             // so extensions can compose additional context via advise()
@@ -591,10 +680,14 @@ export class AgentLoop {
             catch (e) {
                 if (signal.aborted)
                     throw e;
-                // Context overflow — compact and retry (no backoff needed)
+                // Context overflow — aggressively compact and retry
                 if (this.isContextOverflow(e)) {
-                    this.conversation.compact(6);
-                    this.bus.emit("ui:info", { message: "(context overflow — compacted, retrying)" });
+                    // Use 60% of the budget to leave headroom
+                    const aggressiveBudget = Math.floor(this.tokenBudget.conversationBudgetTokens * 0.6);
+                    const stats = this.conversation.compact(aggressiveBudget, 6);
+                    await this.conversation.flush();
+                    const detail = stats ? ` ~${stats.before.toLocaleString()} → ~${stats.after.toLocaleString()} tokens` : "";
+                    this.bus.emit("ui:info", { message: `(context overflow — compacted${detail}, retrying)` });
                     continue;
                 }
                 // Retryable transient error — backoff

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

@@ -1,11 +1,14 @@
 import type { ChatCompletionMessageParam } from "../utils/llm-client.js";
-/**
- * Manages the OpenAI chat messages array for the agent loop.
- * Separate from ContextManager — this is the LLM conversation,
- * not the shell history.
- */
+import { type NuclearEntry } from "./nuclear-form.js";
+import type { HistoryFile } from "./history-file.js";
 export declare class ConversationState {
     private messages;
+    private nuclearEntries;
+    private recallArchive;
+    private historyFile;
+    private nextSeq;
+    constructor(historyFile?: HistoryFile);
+    get instanceId(): string;
     addUserMessage(text: string): void;
     addAssistantMessage(content: string | null, toolCalls?: {
         id: string;
@@ -15,13 +18,40 @@ export declare class ConversationState {
         };
     }[]): void;
     addToolResult(toolCallId: string, content: string): void;
-    /** Inject a system-level note into the conversation (e.g. context change). */
     addSystemNote(text: string): void;
     getMessages(): ChatCompletionMessageParam[];
+    estimateTokens(): number;
     /**
-     * Simple compaction — drop oldest turns, keeping the first user message
-     * (original task context) and the most recent turns.
+     * Priority-based compaction. Evicts lowest-priority turns, replacing
+     * them with nuclear one-liner summaries that stay in the conversation.
+     * Read-only tool results are dropped entirely.
      */
-    compact(maxTurns: number): void;
+    compact(targetTokens: number, recentTurnsToKeep?: number): {
+        before: number;
+        after: number;
+    } | null;
+    /**
+     * Flush oldest nuclear entries to the history file when the
+     * in-context nuclear block grows too large.
+     */
+    flush(): Promise<void>;
+    /**
+     * Inject prior session history from the history file as a context note.
+     */
+    loadPriorHistory(entries: NuclearEntry[]): void;
+    /** Search Tier 2 archive + Tier 3 history file. */
+    search(query: string): Promise<string>;
+    /** Expand full content of a nuclear entry by seq number. */
+    expand(seq: number): Promise<string>;
+    /** Browse nuclear entries (Tier 2) + recent history (Tier 3). */
+    browse(): Promise<string>;
+    getNuclearEntryCount(): number;
+    getRecallArchiveSize(): number;
     clear(): void;
+    private buildNuclearBlock;
+    private updateNuclearBlockInMessages;
+    private parseTurns;
+    private inferPriority;
+    private searchArchive;
+    private turnToText;
 }