agent-sh 0.8.0 → 0.9.0

package/dist/agent/nuclear-form.js

@@ -78,10 +78,11 @@ export function toNuclearEntries(messages, startSeq, instanceId) {
 // ── Formatting ────────────────────────────────────────────────────
 /** Format a nuclear entry as a display line (for in-context injection). */
 export function formatNuclearLine(entry) {
-    const time = new Date(entry.ts).toLocaleTimeString("en-US", {
-        hour: "2-digit", minute: "2-digit", hour12: false,
-    });
-    return `#${entry.seq} ${time} ${entry.sum}`;
+    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. */

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 complete, non-interactive commands 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\n**Terminal interaction** (terminal_read, terminal_keys):\nUse these to observe and interact with what is currently on the user's terminal screen.\n- terminal_read: see what the user sees (current screen contents, cursor position)\n- terminal_keys: send keystrokes as if the user typed them\nUse for: driving interactive programs (vim, htop, less, ssh, REPLs), answering questions\nabout what's on screen, or typing at the shell prompt when a program is already running.\nDo NOT use user_shell to interact with an already-running program \u2014 use these instead.\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.\nUse terminal_read/terminal_keys when interacting with what's already on screen.\n\n# Interactive Overlay Sessions\n\nWhen the dynamic context includes `interactive-session: true`, the user has summoned you\nvia a hotkey overlay from inside their live terminal. They may be in the middle of using\na program (vim, ssh, a REPL, etc.) or at a shell prompt. In this mode:\n- Start with terminal_read if you need to understand what's on screen.\n- Prefer terminal_keys to interact with whatever is currently running.\n- Use user_shell only for running new, standalone commands \u2014 not for interacting with\n  what's already on screen.\n- Keep responses concise \u2014 the user is in the middle of a workflow.\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, shellBudgetTokens?: number): 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.
 
@@ -62,46 +65,27 @@ Use this to run complete, non-interactive commands in the user's real shell. Use
 - 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.
 
 # 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
+
+# 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, shellBudgetTokens) {
+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) {

package/dist/{token-budget.js → agent/token-budget.js}

@@ -8,7 +8,7 @@
  * 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";
+import { getSettings } from "../settings.js";
 /** Overhead estimates (tokens). */
 const SYSTEM_PROMPT_OVERHEAD = 800;
 const DYNAMIC_CONTEXT_OVERHEAD = 500; // conventions, metadata, skills list

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;

package/dist/agent/tool-protocol.js

@@ -0,0 +1,386 @@
+// ── API mode (current behavior) ──────────────────────────────────
+export class ApiToolProtocol {
+    mode = "api";
+    getApiTools(tools) {
+        if (tools.length === 0)
+            return undefined;
+        return tools.map((t) => ({
+            type: "function",
+            function: {
+                name: t.name,
+                description: t.description,
+                parameters: t.input_schema,
+            },
+        }));
+    }
+    getToolPrompt() {
+        return "";
+    }
+    extractToolCalls(_text, streamedCalls) {
+        return streamedCalls;
+    }
+    rewriteToolCall(tc) {
+        return tc;
+    }
+    recordAssistant(conv, text, toolCalls) {
+        const calls = toolCalls.length
+            ? toolCalls.map((tc) => ({
+                id: tc.id,
+                function: { name: tc.name, arguments: tc.argumentsJson },
+            }))
+            : undefined;
+        conv.addAssistantMessage(text || null, calls);
+    }
+    recordResults(conv, results) {
+        for (const r of results) {
+            const content = r.isError ? `Error: ${r.content}` : r.content;
+            conv.addToolResult(r.callId, content);
+        }
+    }
+    createStreamFilter() {
+        return null;
+    }
+}
+// ── Inline mode (JSON code block tool calls) ─────────────────────
+export class InlineToolProtocol {
+    mode = "inline";
+    callCounter = 0;
+    getApiTools() {
+        return undefined;
+    }
+    getToolPrompt(tools) {
+        if (tools.length === 0)
+            return "";
+        const lines = [
+            "",
+            "# Tools",
+            "",
+            "To call a tool, write a ```tool fenced block with JSON:",
+            "",
+            "```tool",
+            '{"tool": "grep", "pattern": "TODO", "path": "src/"}',
+            "```",
+            "",
+            "The `tool` field selects which tool. All other fields are arguments.",
+            "Multiple tool blocks allowed per response.",
+            "",
+            "Available: " + tools.map((t) => `${t.name}${formatParams(t.input_schema)}`).join(", "),
+        ];
+        return lines.join("\n");
+    }
+    rewriteToolCall(tc) {
+        return tc;
+    }
+    extractToolCalls(text, _streamedCalls) {
+        const calls = [];
+        // Match ```tool ... ``` blocks
+        const regex = /```tool\s*\n([\s\S]*?)```/g;
+        let match;
+        while ((match = regex.exec(text)) !== null) {
+            const body = match[1].trim();
+            try {
+                const obj = JSON.parse(body);
+                const name = obj.tool;
+                if (typeof name !== "string")
+                    continue;
+                // Separate tool name from args
+                const { tool: _, ...args } = obj;
+                calls.push({
+                    id: `inline_${++this.callCounter}`,
+                    name,
+                    argumentsJson: JSON.stringify(args),
+                });
+            }
+            catch {
+                // Not valid JSON — skip
+            }
+        }
+        return calls;
+    }
+    recordAssistant(conv, text, _toolCalls) {
+        conv.addAssistantMessage(text || null);
+    }
+    recordResults(conv, results) {
+        if (results.length === 0)
+            return;
+        const parts = results.map((r) => {
+            const status = r.isError ? "error" : "ok";
+            return `[${r.toolName} ${r.callId} ${status}]\n${r.content}`;
+        });
+        conv.addToolResultInline(parts.join("\n\n"));
+    }
+    createStreamFilter(_toolNames) {
+        return new CodeBlockFilter();
+    }
+}
+// ── Code block stream filter ────────────────────────────────────
+/**
+ * Strips ```tool ... ``` blocks from streamed text.
+ * Simple state machine: normal → in_fence → normal.
+ */
+class CodeBlockFilter {
+    buf = "";
+    inFence = false;
+    lastEmittedNewlines = 0; // track trailing newlines to collapse blanks
+    feed(chunk) {
+        this.buf += chunk;
+        let raw = "";
+        while (this.buf.length > 0) {
+            if (this.inFence) {
+                // Look for closing ```
+                const closeIdx = this.buf.indexOf("```");
+                if (closeIdx !== -1) {
+                    // Skip past closing ``` and any trailing whitespace on that line
+                    let end = closeIdx + 3;
+                    while (end < this.buf.length && this.buf[end] === "\n")
+                        end++;
+                    this.buf = this.buf.slice(end);
+                    this.inFence = false;
+                    continue;
+                }
+                // No closing yet — keep buffering
+                break;
+            }
+            // Look for opening ```tool
+            const openIdx = this.buf.indexOf("```tool");
+            if (openIdx !== -1) {
+                // Emit everything before the fence, trimming trailing newline
+                let before = this.buf.slice(0, openIdx);
+                if (before.endsWith("\n"))
+                    before = before.slice(0, -1);
+                raw += before;
+                this.buf = this.buf.slice(openIdx + 7); // skip ```tool
+                this.inFence = true;
+                continue;
+            }
+            // Stray ``` on its own line (residual closing fence)
+            const strayIdx = this.buf.indexOf("```");
+            if (strayIdx !== -1) {
+                // Check if it's just backticks on a line (possibly with whitespace)
+                const lineStart = this.buf.lastIndexOf("\n", strayIdx - 1) + 1;
+                const lineEnd = this.buf.indexOf("\n", strayIdx);
+                const line = this.buf.slice(lineStart, lineEnd === -1 ? undefined : lineEnd).trim();
+                if (line === "```") {
+                    raw += this.buf.slice(0, lineStart);
+                    this.buf = this.buf.slice(lineEnd === -1 ? this.buf.length : lineEnd + 1);
+                    continue;
+                }
+            }
+            // Could be a partial match at the end
+            const marker = "```tool";
+            let partial = false;
+            for (let i = Math.min(marker.length - 1, this.buf.length); i >= 1; i--) {
+                if (this.buf.endsWith(marker.slice(0, i))) {
+                    raw += this.buf.slice(0, this.buf.length - i);
+                    this.buf = this.buf.slice(this.buf.length - i);
+                    partial = true;
+                    break;
+                }
+            }
+            if (partial)
+                break;
+            // No fence anywhere — emit all
+            raw += this.buf;
+            this.buf = "";
+        }
+        // Collapse runs of 3+ newlines into 2 (one blank line max)
+        return this.collapseNewlines(raw);
+    }
+    flush() {
+        const out = this.collapseNewlines(this.buf);
+        this.buf = "";
+        this.inFence = false;
+        return out;
+    }
+    collapseNewlines(text) {
+        if (!text)
+            return text;
+        // Count leading newlines and merge with trailing from last emit
+        let i = 0;
+        while (i < text.length && text[i] === "\n")
+            i++;
+        const leading = i;
+        const totalNewlines = this.lastEmittedNewlines + leading;
+        // Allow at most 2 consecutive newlines
+        let prefix = "";
+        if (leading > 0) {
+            const allowed = Math.max(0, 2 - this.lastEmittedNewlines);
+            prefix = "\n".repeat(Math.min(leading, allowed));
+            text = text.slice(leading);
+        }
+        // Collapse internal runs
+        text = text.replace(/\n{3,}/g, "\n\n");
+        // Track trailing newlines for next call
+        let trailing = 0;
+        let j = text.length;
+        while (j > 0 && text[j - 1] === "\n") {
+            j--;
+            trailing++;
+        }
+        this.lastEmittedNewlines = trailing > 0 ? trailing : (prefix ? totalNewlines - leading + prefix.length : 0);
+        return prefix + text;
+    }
+}
+// ── Helpers ──────────────────────────────────────────────────────
+function formatParams(schema) {
+    const props = schema.properties;
+    if (!props || Object.keys(props).length === 0)
+        return "()";
+    const required = new Set(schema.required ?? []);
+    const params = Object.entries(props).map(([name, prop]) => {
+        const opt = required.has(name) ? "" : "?";
+        const enumVals = prop.enum;
+        if (enumVals)
+            return `${name}${opt}: ${enumVals.join("|")}`;
+        return `${name}${opt}`;
+    });
+    return `(${params.join(", ")})`;
+}
+// ── Deferred mode (core tools full schema, extensions via meta-tool) ──
+const META_TOOL_NAME = "use_extension";
+export class DeferredToolProtocol {
+    mode = "deferred";
+    coreNames;
+    /** Cached extension tool schemas for arg validation. */
+    extSchemas = new Map();
+    constructor(coreNames) {
+        this.coreNames = new Set(coreNames);
+    }
+    getApiTools(tools) {
+        const core = tools.filter((t) => this.coreNames.has(t.name));
+        const ext = tools.filter((t) => !this.coreNames.has(t.name));
+        // Cache extension schemas for validation in rewriteToolCall
+        this.extSchemas.clear();
+        for (const t of ext) {
+            this.extSchemas.set(t.name, t.input_schema);
+        }
+        const apiTools = core.map((t) => ({
+            type: "function",
+            function: {
+                name: t.name,
+                description: t.description,
+                parameters: t.input_schema,
+            },
+        }));
+        if (ext.length > 0) {
+            const catalog = ext
+                .map((t) => `${t.name}${formatParams(t.input_schema)}`)
+                .join(", ");
+            apiTools.push({
+                type: "function",
+                function: {
+                    name: META_TOOL_NAME,
+                    description: `Call an extension tool. Available: ${catalog}`,
+                    parameters: {
+                        type: "object",
+                        properties: {
+                            name: { type: "string", description: "Tool name to call" },
+                            args: {
+                                type: "object",
+                                description: "Tool arguments",
+                                properties: {},
+                                additionalProperties: true,
+                            },
+                        },
+                        required: ["name"],
+                    },
+                },
+            });
+        }
+        return apiTools.length > 0 ? apiTools : undefined;
+    }
+    getToolPrompt() {
+        return "";
+    }
+    extractToolCalls(_text, streamedCalls) {
+        return streamedCalls;
+    }
+    rewriteToolCall(tc) {
+        if (tc.name !== META_TOOL_NAME)
+            return tc;
+        // Unwrap: use_extension(name="foo", args={...}) → foo({...})
+        try {
+            const parsed = JSON.parse(tc.argumentsJson);
+            const targetName = parsed.name;
+            const targetArgs = (parsed.args ?? {});
+            // Validate: does the extension exist?
+            const schema = this.extSchemas.get(targetName);
+            if (!schema) {
+                const available = [...this.extSchemas.keys()].join(", ");
+                return {
+                    id: tc.id,
+                    name: META_TOOL_NAME,
+                    argumentsJson: JSON.stringify({
+                        _error: `Unknown extension "${targetName}". Available: ${available}`,
+                    }),
+                };
+            }
+            // Validate: check for unknown/missing params against schema
+            const schemaProps = schema.properties;
+            const requiredParams = new Set(schema.required ?? []);
+            if (schemaProps) {
+                const validParams = new Set(Object.keys(schemaProps));
+                const providedParams = Object.keys(targetArgs);
+                // Check for unknown params (likely wrong names)
+                const unknown = providedParams.filter((p) => !validParams.has(p));
+                // Check for missing required params
+                const missing = [...requiredParams].filter((p) => !targetArgs[p]);
+                if (unknown.length > 0 || missing.length > 0) {
+                    const expected = [...validParams]
+                        .map((p) => `${p}${requiredParams.has(p) ? " (required)" : ""}`)
+                        .join(", ");
+                    let hint = `Wrong arguments for "${targetName}". Expected params: ${expected}.`;
+                    if (unknown.length > 0)
+                        hint += ` Unknown: ${unknown.join(", ")}.`;
+                    if (missing.length > 0)
+                        hint += ` Missing: ${missing.join(", ")}.`;
+                    return {
+                        id: tc.id,
+                        name: META_TOOL_NAME,
+                        argumentsJson: JSON.stringify({ _error: hint }),
+                    };
+                }
+            }
+            return {
+                id: tc.id,
+                name: targetName,
+                argumentsJson: JSON.stringify(targetArgs),
+            };
+        }
+        catch {
+            return tc; // Let it fail naturally downstream
+        }
+    }
+    recordAssistant(conv, text, toolCalls) {
+        const calls = toolCalls.length
+            ? toolCalls.map((tc) => ({
+                id: tc.id,
+                function: { name: tc.name, arguments: tc.argumentsJson },
+            }))
+            : undefined;
+        conv.addAssistantMessage(text || null, calls);
+    }
+    recordResults(conv, results) {
+        for (const r of results) {
+            const content = r.isError ? `Error: ${r.content}` : r.content;
+            conv.addToolResult(r.callId, content);
+        }
+    }
+    createStreamFilter() {
+        return null;
+    }
+}
+// ── Factory ─────────────────────────────────────────────────────
+/** Core tool names — always sent with full schema. */
+const CORE_TOOLS = [
+    "bash", "read_file", "write_file", "edit_file",
+    "grep", "glob", "ls", "user_shell", "display",
+    "list_skills", "conversation_recall",
+];
+export function createToolProtocol(mode) {
+    if (mode === "inline")
+        return new InlineToolProtocol();
+    if (mode === "deferred")
+        return new DeferredToolProtocol(CORE_TOOLS);
+    return new ApiToolProtocol();
+}

package/dist/agent/types.d.ts

@@ -47,13 +47,33 @@ export interface ToolDisplayInfo {
      *  icon + detail only. When absent, the tool name is shown alongside the detail. */
     icon?: string;
 }
+/** Interactive UI session — imperative control over rendering + input. */
+export interface InteractiveSession<T> {
+    /** Return lines to render. Called on mount and after each input. */
+    render(width: number): string[];
+    /** Handle raw input. Call done(result) to finish the session. */
+    handleInput(data: string, done: (result: T) => void): void;
+    /** Called when session starts. Receives invalidate() for async re-renders. */
+    onMount?(invalidate: () => void): void;
+    /** Called when session ends (cleanup). */
+    onUnmount?(): void;
+}
+/** Interactive UI capability passed to tools during execution. */
+export interface ToolUI {
+    /** Present a custom interactive UI and wait for the user's response. */
+    custom<T>(session: InteractiveSession<T>): Promise<T>;
+}
+/** Context passed to tool execute() as optional third parameter. */
+export interface ToolExecutionContext {
+    ui: ToolUI;
+}
 export interface ToolDefinition {
     name: string;
     /** Short label for TUI display (e.g. "search" instead of "ads_search"). Defaults to name. */
     displayName?: string;
     description: string;
     input_schema: Record<string, unknown>;
-    execute(args: Record<string, unknown>, onChunk?: (chunk: string) => void): Promise<ToolResult>;
+    execute(args: Record<string, unknown>, onChunk?: (chunk: string) => void, ctx?: ToolExecutionContext): Promise<ToolResult>;
     /** Whether to stream tool output to the TUI (default: true). */
     showOutput?: boolean;
     /** Whether this tool may modify files — triggers file watcher (default: false). */

package/dist/core.d.ts

@@ -1,13 +1,13 @@
 /**
  * Core kernel — the minimum viable agent-sh.
  *
- * Wires up EventBus + ContextManager + AgentBackend without any frontend.
+ * Wires up EventBus + ContextManager without any frontend or agent backend.
  * Consumers attach their own I/O (Shell, WebSocket, REST, tests) by
  * subscribing to bus events.
  *
- * The default backend (AgentLoop) is created eagerly but wired lazily —
- * extensions can register alternative backends via agent:register-backend
- * before activateBackend() is called.
+ * Agent backends are loaded as extensions and register themselves via
+ * the agent:register-backend bus event. The built-in "ash" backend is
+ * loaded from src/extensions/agent-backend.ts.
  *
  * Usage:
  *   import { createCore } from "agent-sh";
@@ -18,8 +18,8 @@
  */
 import { EventBus } from "./event-bus.js";
 import { ContextManager } from "./context-manager.js";
-import { LlmClient } from "./utils/llm-client.js";
 import type { AgentShellConfig, ExtensionContext } from "./types.js";
+import { HandlerRegistry } from "./utils/handler-registry.js";
 export { EventBus } from "./event-bus.js";
 export type { ShellEvents } from "./event-bus.js";
 export type { AgentShellConfig, ExtensionContext } from "./types.js";
@@ -31,8 +31,8 @@ export { LlmClient } from "./utils/llm-client.js";
 export interface AgentShellCore {
     bus: EventBus;
     contextManager: ContextManager;
-    /** LLM client for fast-path features (null when no provider configured). */
-    llmClient: LlmClient | null;
+    /** Handler registry for define/advise/call. */
+    handlers: HandlerRegistry;
     /** Activate the agent backend (call after extensions load). */
     activateBackend(): void;
     /** Convenience: emit agent:submit and await the response. */