agent-sh 0.8.0 → 0.10.0

package/dist/agent/system-prompt.js

@@ -1,15 +1,66 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { discoverSkills } from "./skills.js";
+import { fileURLToPath } from "node:url";
+import { discoverProjectSkills } from "./skills.js";
+/**
+ * Format skills for inline display in prompt.
+ * Shows name, description, and file path so the model can decide immediately
+ * whether to load a skill — no extra round-trip needed.
+ */
+export function formatSkillsBlock(skills) {
+    if (skills.length === 0)
+        return "";
+    return "# Available Skills\n\n"
+        + "Load a skill's full content with read_file on its file path when needed.\n\n"
+        + skills.map(s => `- **${s.name}**: ${s.description}\n  Path: ${s.filePath}`).join("\n\n");
+}
+// Resolve to the user's home-based config dir — user's standing instructions to the agent
+import * as os from "node:os";
+const GLOBAL_AGENTS_MD = path.join(os.homedir(), ".agent-sh", "AGENTS.md");
+// ── File caches ─────────────────────────────────────────────────────
+// Convention files (CLAUDE.md/AGENT.md) are walked synchronously from
+// CWD to root on every query. In practice they almost never change,
+// so a short TTL cache keyed by CWD avoids redundant filesystem walks.
+// The 5-second TTL is short enough to pick up edits quickly but long
+// enough to eliminate repeated walks within a multi-tool agent loop.
+const CACHE_TTL_MS = 5_000;
+/** TTL cache for convention files, keyed by resolved CWD. */
+let conventionCache = null;
+/** TTL cache for global AGENTS.md — changes extremely rarely. */
+let agentsMdCache = null;
+export function loadGlobalAgentsMd() {
+    const now = Date.now();
+    if (agentsMdCache && now < agentsMdCache.expiry) {
+        return agentsMdCache.result;
+    }
+    try {
+        const content = fs.readFileSync(GLOBAL_AGENTS_MD, "utf-8").trim();
+        const result = content || null;
+        agentsMdCache = { result, expiry: now + CACHE_TTL_MS };
+        return result;
+    }
+    catch {
+        agentsMdCache = { result: null, expiry: now + CACHE_TTL_MS };
+        return null;
+    }
+}
+/** Resolve the absolute path to agent-sh's own docs directory. */
+const CODE_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../");
 /** File names to scan for project conventions (checked in order). */
 const CONVENTION_FILES = ["CLAUDE.md", "AGENT.md"];
 /**
  * Scan from `dir` upward for project convention files.
  * Returns contents ordered root-first (general → specific).
+ * Results are cached for CACHE_TTL_MS, keyed by resolved directory.
  */
 function loadConventionFiles(dir) {
+    const cwd = path.resolve(dir);
+    const now = Date.now();
+    if (conventionCache && conventionCache.cwd === cwd && now < conventionCache.expiry) {
+        return conventionCache.result;
+    }
     const files = [];
-    let current = path.resolve(dir);
+    let current = cwd;
     while (true) {
         for (const name of CONVENTION_FILES) {
             const candidate = path.join(current, name);
@@ -30,95 +81,77 @@ function loadConventionFiles(dir) {
         current = parent;
     }
     files.reverse();
-    return files.map(f => `<!-- ${f.path} -->\n${f.content}`);
+    const result = files.map(f => `<!-- ${f.path} -->\n${f.content}`);
+    conventionCache = { cwd, result, expiry: now + CACHE_TTL_MS };
+    return result;
 }
 /**
  * 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 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.
 
 # Tool Decision Guide
-
-You have three categories of tools — choose based on who needs the output and
-whether the command has lasting effects:
-
-**Scratchpad tools** (bash, read_file, grep, glob, ls, edit_file, write_file):
+bash, read_file, grep, glob, ls, edit_file, write_file::
 Use these to investigate, search, read, and modify files. Output is returned
 to you for reasoning — the user doesn't see it directly.
 
-**Display** (display):
-Use this to show output to the user in their terminal. The user sees the
-output directly, but it is NOT returned to you. Use when:
-- The user asks to see something (cat a file, git log, git diff, man page)
-- The output is for the user to read, not for you to process
-
-**Live shell** (user_shell):
-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
-- Set return_output=true only if you need to inspect the result
-
-**Terminal interaction** (terminal_read, terminal_keys):
-Use these to observe and interact with what is currently on the user's terminal screen.
-- terminal_read: see what the user sees (current screen contents, cursor position)
-- terminal_keys: send keystrokes as if the user typed them
-Use for: driving interactive programs (vim, htop, less, ssh, REPLs), answering questions
-about what's on screen, or typing at the shell prompt when a program is already running.
-Do NOT use user_shell to interact with an already-running program — use these instead.
-
-Default to scratchpad tools for your own investigation. Use display when the
-user is the intended audience. Use user_shell when the command has real effects.
-Use terminal_read/terminal_keys when interacting with what's already on screen.
-
-# Interactive Overlay Sessions
-
-When the dynamic context includes \`interactive-session: true\`, the user has summoned you
-via a hotkey overlay from inside their live terminal. They may be in the middle of using
-a program (vim, ssh, a REPL, etc.) or at a shell prompt. In this mode:
-- Start with terminal_read if you need to understand what's on screen.
-- Prefer terminal_keys to interact with whatever is currently running.
-- Use user_shell only for running new, standalone commands — not for interacting with
-  what's already on screen.
-- Keep responses concise — the user is in the middle of a workflow.
+Extensions may register additional tools — follow their instructions.
 
 # Tool Usage Guidelines
 - Use read_file before editing a file you haven't seen
 - 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
+
+# Preference Learning
+
+Treat the user's past commands as standing preferences. Before acting, check shell history
+and conversation context for recurring patterns — apply them proactively and do not wait to
+be reminded.`;
 /**
- * Build the dynamic context — injected as a user message before each query.
- * Contains everything that changes: tools, shell context, conventions, cwd.
- *
- * Runs through the "agent:dynamic-context" pipe so extensions can append.
+ * CWD-scoped static context: project conventions (CLAUDE.md / AGENT.md)
+ * and discovered skills. Stable for a given cwd — callers should cache
+ * on cwd identity rather than rebuilding per LLM iteration.
  */
-export function buildDynamicContext(tools, contextManager, shellBudgetTokens) {
+export function buildStaticByCwd(cwd) {
     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());
+    const conventions = loadConventionFiles(cwd);
     if (conventions.length > 0) {
         sections.push("# Project Conventions\n\n" + conventions.join("\n\n"));
     }
-    // Skills hint
-    const skills = discoverSkills(contextManager.getCwd());
-    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.`);
+    const projectSkills = discoverProjectSkills(cwd);
+    const skillsBlock = formatSkillsBlock(projectSkills);
+    if (skillsBlock) {
+        sections.push(skillsBlock);
     }
-    // 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);
-    }
-    // Metadata
-    sections.push(`Current date: ${new Date().toISOString().split("T")[0]}\nWorking directory: ${contextManager.getCwd()}`);
     return sections.join("\n\n");
 }
+/**
+ * Per-iteration dynamic context: date, working directory, token usage.
+ * Rebuilt every LLM call. Extension advisors add more sections (budget,
+ * subagents, metacognitive signals, etc.) on top.
+ *
+ * Skills, AGENTS.md, and project conventions live in the system prompt
+ * (see `system-prompt:build` in agent-loop) so they enter the provider's
+ * prefix cache instead of being rebuilt and re-sent every turn.
+ *
+ * Shell context is likewise not injected here — it flows into the
+ * conversation as incremental <shell-events> messages (see
+ * AgentLoop.injectShellDelta) for the same reason.
+ */
+export function buildDynamicContext(contextManager, tokenStatus) {
+    const envLines = [
+        `Current date: ${new Date().toISOString().split("T")[0]}`,
+        `Working directory: ${contextManager.getCwd()}`,
+    ];
+    const usedK = (tokenStatus.promptTokens / 1000).toFixed(1);
+    const maxK = (tokenStatus.contextWindow / 1000).toFixed(0);
+    const pct = Math.min(100, Math.round((tokenStatus.promptTokens / tokenStatus.contextWindow) * 100));
+    envLines.push(`Token usage: ${usedK}k/${maxK}k (${pct}%)`);
+    return `<environment>\n${envLines.join("\n")}\n</environment>`;
+}

package/dist/{token-budget.d.ts → agent/token-budget.d.ts}

@@ -1,13 +1,14 @@
+/** Response reserve — tokens reserved for the model's output. */
+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;
-    /** 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/{token-budget.js → agent/token-budget.js}

@@ -1,21 +1,23 @@
 /**
- * Unified token budget manager.
+ * Token budget for shell context sizing.
  *
- * 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)
+ * 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.
  *
- * The budget accounts for fixed overhead (system prompt, tool definitions,
- * response reserve) and divides the remaining space by a configurable ratio.
+ * Shell context is sized loosely — chars/4 accuracy is fine for this.
+ * Conversation and compaction decisions use API-grounded token counts
+ * (see ConversationState.estimatePromptTokens).
  */
-import { getSettings } from "./settings.js";
-/** Overhead estimates (tokens). */
+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;
-const RESPONSE_RESERVE = 8192; // matches llm-client.ts default max_tokens
+/** Response reserve — tokens reserved for the model's output. */
+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;
@@ -30,21 +32,14 @@ export class TokenBudget {
         if (toolCount != null)
             this.toolCount = toolCount;
     }
-    /** Total tokens available for shell context + conversation content. */
-    get contentBudget() {
+    /** 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;
-        return Math.max(0, this.contextWindow - overhead);
-    }
-    /** Token budget for the shell context stream. */
-    get shellBudgetTokens() {
+        const contentBudget = Math.max(0, this.contextWindow - overhead);
         const ratio = getSettings().shellContextRatio;
-        return Math.floor(this.contentBudget * ratio);
-    }
-    /** Token budget for the conversation messages stream. */
-    get conversationBudgetTokens() {
-        return this.contentBudget - this.shellBudgetTokens;
+        return Math.floor(contentBudget * ratio);
     }
 }

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

@@ -0,0 +1,105 @@
+/**
+ * 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;
+    /**
+     * Extra tool definitions the protocol wants registered in the tool registry.
+     * Used by deferred-lookup mode to register its `load_tool` meta-tool.
+     * Default: none.
+     */
+    getProtocolTools?(): ToolDefinition[];
+}
+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 class DeferredLookupProtocol implements ToolProtocol {
+    readonly mode: "deferred-lookup";
+    private coreNames;
+    private loadedExt;
+    /** Cache of the current tools list so load_tool's execute can find schemas. */
+    private toolsRef;
+    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;
+    getProtocolTools(): ToolDefinition[];
+}
+export declare function createToolProtocol(mode: "api" | "inline" | "deferred" | "deferred-lookup"): ToolProtocol;