agent-sh 0.7.0 → 0.9.0

package/dist/agent/nuclear-form.js

@@ -0,0 +1,176 @@
+// ── Tool classification ───────────────────────────────────────────
+/** Read-only tools whose results are dropped at Tier 1→2 (agent can re-read). */
+export const READ_ONLY_TOOLS = new Set([
+    "read_file", "grep", "glob", "ls", "search",
+]);
+/** State-changing tools whose summaries are kept in nuclear memory. */
+export const WRITE_TOOLS = new Set([
+    "write_file", "edit_file", "write", "edit", "patch",
+]);
+// ── Nuclear entry generation ──────────────────────────────────────
+/**
+ * Generate nuclear entries from a logical turn (a sequence of messages
+ * starting with a user message, followed by assistant + tool messages).
+ */
+export function toNuclearEntries(messages, startSeq, instanceId) {
+    const entries = [];
+    let seq = startSeq;
+    const ts = Date.now();
+    for (const msg of messages) {
+        if (msg.role === "user") {
+            const text = typeof msg.content === "string" ? msg.content : "";
+            // Skip compaction markers
+            if (text.startsWith("["))
+                continue;
+            entries.push({
+                seq: seq++, ts, iid: instanceId,
+                kind: "user",
+                sum: `user: "${truncate(text, 80)}"`,
+            });
+        }
+        else if (msg.role === "assistant") {
+            // Process tool calls
+            if ("tool_calls" in msg && msg.tool_calls) {
+                for (const tc of msg.tool_calls) {
+                    if (!("function" in tc))
+                        continue;
+                    const name = tc.function.name;
+                    let args = {};
+                    try {
+                        args = JSON.parse(tc.function.arguments);
+                    }
+                    catch { }
+                    // Store the tool call — we'll enrich it when we see the result
+                    entries.push({
+                        seq: seq++, ts, iid: instanceId,
+                        kind: "tool",
+                        tool: name,
+                        sum: summarizeToolCall(name, args),
+                    });
+                }
+            }
+            else if (typeof msg.content === "string" && msg.content) {
+                entries.push({
+                    seq: seq++, ts, iid: instanceId,
+                    kind: "agent",
+                    sum: `agent: "${truncate(msg.content, 60)}"`,
+                });
+            }
+        }
+        else if (msg.role === "tool") {
+            // Enrich the most recent tool entry with result info
+            const content = typeof msg.content === "string" ? msg.content : "";
+            const lastTool = findLastTool(entries);
+            if (lastTool) {
+                const isError = content.startsWith("Error:");
+                if (isError) {
+                    lastTool.kind = "error";
+                    lastTool.sum = `error: ${lastTool.tool} ${truncate(content.slice(7).trim(), 80)}`;
+                }
+                else {
+                    lastTool.sum = enrichWithResult(lastTool.tool ?? "", lastTool.sum, content);
+                }
+            }
+        }
+    }
+    return entries;
+}
+// ── Formatting ────────────────────────────────────────────────────
+/** Format a nuclear entry as a display line (for in-context injection). */
+export function formatNuclearLine(entry) {
+    const d = new Date(entry.ts);
+    const pad = (n) => String(n).padStart(2, "0");
+    // ISO-ish compact: 2026-04-13 14:05
+    const stamp = `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
+    return `#${entry.seq} [${stamp}] ${entry.sum}`;
+}
+// ── Serialization (JSONL for history file) ────────────────────────
+/** Serialize a nuclear entry to a JSONL line. */
+export function serializeEntry(entry) {
+    return JSON.stringify(entry);
+}
+/** Deserialize a JSONL line to a nuclear entry. Returns null on parse failure. */
+export function deserializeEntry(line) {
+    try {
+        const obj = JSON.parse(line);
+        if (typeof obj.seq === "number" && typeof obj.sum === "string") {
+            return obj;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+// ── 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);
+}
+// ── Internal helpers ──────────────────────────────────────────────
+function truncate(text, maxLen) {
+    const oneLine = text.replace(/\n/g, " ").trim();
+    return oneLine.length > maxLen ? oneLine.slice(0, maxLen) + "..." : oneLine;
+}
+function findLastTool(entries) {
+    for (let i = entries.length - 1; i >= 0; i--) {
+        if (entries[i].kind === "tool")
+            return entries[i];
+    }
+    return undefined;
+}
+function summarizeToolCall(name, args) {
+    switch (name) {
+        case "bash":
+            return `bash: ${truncate(String(args.command ?? ""), 60)}`;
+        case "user_shell":
+            return `user_shell: ${truncate(String(args.command ?? ""), 60)}`;
+        case "edit_file":
+            return `edit_file ${args.path ?? ""}`;
+        case "write_file":
+        case "write":
+            return `write_file ${args.path ?? args.file_path ?? ""}`;
+        case "read_file":
+            return `read_file ${args.path ?? args.file_path ?? ""}`;
+        case "grep":
+            return `grep "${truncate(String(args.pattern ?? ""), 30)}"`;
+        case "glob":
+            return `glob ${args.pattern ?? ""}`;
+        case "ls":
+            return `ls ${args.path ?? "."}`;
+        case "display":
+            return `display: ${truncate(String(args.command ?? ""), 60)}`;
+        default:
+            return `${name}`;
+    }
+}
+function enrichWithResult(toolName, summary, result) {
+    const lines = result.split("\n");
+    const lineCount = lines.length;
+    switch (toolName) {
+        case "bash":
+        case "user_shell": {
+            // Extract exit code from result if present
+            const exitMatch = result.match(/exit code[:\s]*(\d+)/i) ?? result.match(/exit\s+(\d+)/);
+            const exitCode = exitMatch ? exitMatch[1] : "0";
+            return `${summary} (exit ${exitCode}, ${lineCount} lines)`;
+        }
+        case "edit_file":
+        case "edit": {
+            // Try to extract +/- counts from result
+            const addMatch = result.match(/\+(\d+)/);
+            const delMatch = result.match(/-(\d+)/);
+            if (addMatch || delMatch) {
+                return `${summary} (+${addMatch?.[1] ?? 0}/-${delMatch?.[1] ?? 0})`;
+            }
+            return `${summary} (edited)`;
+        }
+        case "write_file":
+        case "write": {
+            const created = result.toLowerCase().includes("created") ? "created" : "written";
+            return `${summary} (${created}, ${lineCount} lines)`;
+        }
+        default:
+            return `${summary} (${lineCount} lines)`;
+    }
+}

package/dist/agent/system-prompt.d.ts

@@ -1,14 +1,13 @@
-import type { ToolDefinition } from "./types.js";
 import type { ContextManager } from "../context-manager.js";
 /**
  * Static system prompt — identical across all queries, cacheable.
  * Contains only identity and behavioral instructions.
  */
-export declare const STATIC_SYSTEM_PROMPT = "You are an AI coding assistant embedded in agent-sh, a terminal shell.\nYou have access to the user's shell environment and can read, write, and execute code.\nYou share the user's working directory, environment variables, and shell history.\n\n# Tool Decision Guide\n\nYou have three categories of tools \u2014 choose based on who needs the output and\nwhether the command has lasting effects:\n\n**Scratchpad tools** (bash, read_file, grep, glob, ls, edit_file, write_file):\nUse these to investigate, search, read, and modify files. Output is returned\nto you for reasoning \u2014 the user doesn't see it directly.\n\n**Display** (display):\nUse this to show output to the user in their terminal. The user sees the\noutput directly, but it is NOT returned to you. Use when:\n- The user asks to see something (cat a file, git log, git diff, man page)\n- The output is for the user to read, not for you to process\n\n**Live shell** (user_shell):\nUse this to run commands with lasting effects in the user's real shell. Use for:\n- Commands that affect shell state (cd, export, source)\n- Installing packages, starting servers, running builds\n- Any command where the user wants real side effects\n- Set return_output=true only if you need to inspect the result\n\nDefault to scratchpad tools for your own investigation. Use display when the\nuser is the intended audience. Use user_shell when the command has real effects.\n\n# Tool Usage Guidelines\n- Use read_file before editing a file you haven't seen\n- Prefer edit_file over write_file for modifying existing files\n- Use grep/glob to find files before reading them\n- Keep bash commands focused; avoid long-running blocking commands\n- Always check command exit codes for errors";
+export declare const STATIC_SYSTEM_PROMPT: string;
 /**
  * Build the dynamic context — injected as a user message before each query.
- * Contains everything that changes: tools, shell context, conventions, cwd.
+ * Contains everything that changes: shell context, conventions, cwd.
  *
- * Runs through the "agent:dynamic-context" pipe so extensions can append.
+ * Runs through the "dynamic-context:build" handler so extensions can advise.
  */
-export declare function buildDynamicContext(tools: ToolDefinition[], contextManager: ContextManager): string;
+export declare function buildDynamicContext(contextManager: ContextManager, shellBudgetTokens?: number): string;

package/dist/agent/system-prompt.js

@@ -1,6 +1,9 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { fileURLToPath } from "node:url";
 import { discoverSkills } from "./skills.js";
+/** Resolve the absolute path to agent-sh's own docs directory. */
+const DOCS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../docs");
 /** File names to scan for project conventions (checked in order). */
 const CONVENTION_FILES = ["CLAUDE.md", "AGENT.md"];
 /**
@@ -36,7 +39,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 embedded in agent-sh, a terminal shell.
+export const STATIC_SYSTEM_PROMPT = `You are ash, an AI coding assistant embedded in 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.
 
@@ -56,7 +59,7 @@ output directly, but it is NOT returned to you. Use when:
 - The output is for the user to read, not for you to process
 
 **Live shell** (user_shell):
-Use this to run commands with lasting effects in the user's real shell. Use for:
+Use this to run complete, non-interactive commands in the user's real shell. Use for:
 - Commands that affect shell state (cd, export, source)
 - Installing packages, starting servers, running builds
 - Any command where the user wants real side effects
@@ -70,18 +73,19 @@ user is the intended audience. Use user_shell when the command has real effects.
 - Prefer edit_file over write_file for modifying existing files
 - Use grep/glob to find files before reading them
 - Keep bash commands focused; avoid long-running blocking commands
-- Always check command exit codes for errors`;
+- Always check command exit codes for errors
+
+# Documentation
+agent-sh documentation is available in: ${DOCS_DIR}
+Use read_file on ${DOCS_DIR}/README.md for an index of all docs.`;
 /**
  * Build the dynamic context — injected as a user message before each query.
- * Contains everything that changes: tools, shell context, conventions, cwd.
+ * Contains everything that changes: shell context, conventions, cwd.
  *
- * Runs through the "agent:dynamic-context" pipe so extensions can append.
+ * Runs through the "dynamic-context:build" handler so extensions can advise.
  */
-export function buildDynamicContext(tools, contextManager) {
+export function buildDynamicContext(contextManager, shellBudgetTokens) {
     const sections = [];
-    // Tools
-    sections.push("# Available Tools\n" +
-        tools.map((t) => `- ${t.name}: ${t.description}`).join("\n"));
     // Project conventions (CLAUDE.md / AGENT.md)
     const conventions = loadConventionFiles(contextManager.getCwd());
     if (conventions.length > 0) {
@@ -92,8 +96,9 @@ export function buildDynamicContext(tools, contextManager) {
     if (skills.length > 0) {
         sections.push(`You have access to ${skills.length} skill(s). Use the list_skills tool to see them, then read_file to load one.`);
     }
-    // Shell context
-    const shellContext = contextManager.getContext();
+    // Shell context — pass token budget converted to bytes (~4 chars/token)
+    const shellBudgetBytes = shellBudgetTokens != null ? shellBudgetTokens * 4 : undefined;
+    const shellContext = contextManager.getContext(shellBudgetBytes);
     if (shellContext) {
         sections.push(shellContext);
     }

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

@@ -0,0 +1,13 @@
+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;
+    /** Total tokens available for shell context + conversation content. */
+    get contentBudget(): number;
+    /** Token budget for the shell context stream. */
+    get shellBudgetTokens(): number;
+    /** Token budget for the conversation messages stream. */
+    get conversationBudgetTokens(): number;
+}

package/dist/agent/token-budget.js

@@ -0,0 +1,50 @@
+/**
+ * Unified token budget manager.
+ *
+ * Splits a model's context window between two streams:
+ *   - Shell context (user shell commands and outputs — situational awareness)
+ *   - Conversation (agent messages and tool results — task continuity)
+ *
+ * The budget accounts for fixed overhead (system prompt, tool definitions,
+ * response reserve) and divides the remaining space by a configurable ratio.
+ */
+import { getSettings } from "../settings.js";
+/** Overhead estimates (tokens). */
+const SYSTEM_PROMPT_OVERHEAD = 800;
+const DYNAMIC_CONTEXT_OVERHEAD = 500; // conventions, metadata, skills list
+const TOKENS_PER_TOOL_DEFINITION = 50;
+const RESPONSE_RESERVE = 8192; // matches llm-client.ts default max_tokens
+/** Fallback when contextWindow is unknown. */
+const DEFAULT_CONTEXT_WINDOW = 60_000;
+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;
+    }
+    /** Total tokens available for shell context + conversation content. */
+    get contentBudget() {
+        const overhead = SYSTEM_PROMPT_OVERHEAD +
+            DYNAMIC_CONTEXT_OVERHEAD +
+            this.toolCount * TOKENS_PER_TOOL_DEFINITION +
+            RESPONSE_RESERVE;
+        return Math.max(0, this.contextWindow - overhead);
+    }
+    /** Token budget for the shell context stream. */
+    get shellBudgetTokens() {
+        const ratio = getSettings().shellContextRatio;
+        return Math.floor(this.contentBudget * ratio);
+    }
+    /** Token budget for the conversation messages stream. */
+    get conversationBudgetTokens() {
+        return this.contentBudget - this.shellBudgetTokens;
+    }
+}

package/dist/agent/tool-protocol.d.ts

@@ -0,0 +1,83 @@
+/**
+ * ToolProtocol — abstracts how tools are presented to the LLM and how
+ * tool calls are parsed from responses.
+ *
+ * Two modes:
+ *   "api"    — tools sent via OpenAI tools param, parsed from delta.tool_calls
+ *   "inline" — tools described as text, tool calls are JSON code blocks
+ *
+ * The agent loop uses this interface uniformly so the rest of the code
+ * doesn't need to know which mode is active.
+ */
+import type { ChatCompletionTool } from "../utils/llm-client.js";
+import type { ToolDefinition } from "./types.js";
+import type { ConversationState } from "./conversation-state.js";
+export interface PendingToolCall {
+    id: string;
+    name: string;
+    argumentsJson: string;
+}
+export interface ToolResult {
+    callId: string;
+    toolName: string;
+    content: string;
+    isError: boolean;
+}
+/** Streaming filter — strips tool calls from display output. */
+export interface StreamFilter {
+    feed(chunk: string): string;
+    flush(): string;
+}
+export interface ToolProtocol {
+    readonly mode: string;
+    /** Tools to pass in the API request's `tools` parameter. undefined = omit. */
+    getApiTools(tools: ToolDefinition[]): ChatCompletionTool[] | undefined;
+    /** Extra text for dynamic context (tool catalog for inline mode). */
+    getToolPrompt(tools: ToolDefinition[]): string;
+    /** Extract tool calls from a completed response. */
+    extractToolCalls(responseText: string, streamedCalls: PendingToolCall[]): PendingToolCall[];
+    /** Rewrite a tool call before execution (e.g., unwrap meta-tool). */
+    rewriteToolCall(tc: PendingToolCall): PendingToolCall;
+    /** Record the assistant turn in conversation state. */
+    recordAssistant(conv: ConversationState, text: string, toolCalls: PendingToolCall[]): void;
+    /** Record all tool results for a batch as conversation messages. */
+    recordResults(conv: ConversationState, results: ToolResult[]): void;
+    /** Create a stream filter for stripping tool calls from display. null = pass-through. */
+    createStreamFilter(toolNames: string[]): StreamFilter | null;
+}
+export declare class ApiToolProtocol implements ToolProtocol {
+    readonly mode: "api";
+    getApiTools(tools: ToolDefinition[]): ChatCompletionTool[] | undefined;
+    getToolPrompt(): string;
+    extractToolCalls(_text: string, streamedCalls: PendingToolCall[]): PendingToolCall[];
+    rewriteToolCall(tc: PendingToolCall): PendingToolCall;
+    recordAssistant(conv: ConversationState, text: string, toolCalls: PendingToolCall[]): void;
+    recordResults(conv: ConversationState, results: ToolResult[]): void;
+    createStreamFilter(): null;
+}
+export declare class InlineToolProtocol implements ToolProtocol {
+    readonly mode: "inline";
+    private callCounter;
+    getApiTools(): undefined;
+    getToolPrompt(tools: ToolDefinition[]): string;
+    rewriteToolCall(tc: PendingToolCall): PendingToolCall;
+    extractToolCalls(text: string, _streamedCalls: PendingToolCall[]): PendingToolCall[];
+    recordAssistant(conv: ConversationState, text: string, _toolCalls: PendingToolCall[]): void;
+    recordResults(conv: ConversationState, results: ToolResult[]): void;
+    createStreamFilter(_toolNames: string[]): StreamFilter;
+}
+export declare class DeferredToolProtocol implements ToolProtocol {
+    readonly mode: "deferred";
+    private coreNames;
+    /** Cached extension tool schemas for arg validation. */
+    private extSchemas;
+    constructor(coreNames: string[]);
+    getApiTools(tools: ToolDefinition[]): ChatCompletionTool[] | undefined;
+    getToolPrompt(): string;
+    extractToolCalls(_text: string, streamedCalls: PendingToolCall[]): PendingToolCall[];
+    rewriteToolCall(tc: PendingToolCall): PendingToolCall;
+    recordAssistant(conv: ConversationState, text: string, toolCalls: PendingToolCall[]): void;
+    recordResults(conv: ConversationState, results: ToolResult[]): void;
+    createStreamFilter(): null;
+}
+export declare function createToolProtocol(mode: "api" | "inline" | "deferred"): ToolProtocol;