agent-sh 0.7.0 → 0.9.0

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/tools/user-shell.js

@@ -8,7 +8,10 @@
 export function createUserShellTool(opts) {
     return {
         name: "user_shell",
-        description: "Run a command with lasting effects in the user's live shell (cd, export, install packages, start servers, apply changes). Output is shown directly to the user but NOT returned to you by default — set return_output=true if you need to inspect the result.",
+        description: "Run a complete, non-interactive command in the user's live shell (cd, export, install packages, start servers, git commands). " +
+            "Use this for commands that have side effects or that the user wants to see. Output is shown directly to the user but NOT returned " +
+            "to you by default — set return_output=true if you need to inspect the result. " +
+            "Do NOT use this to interact with programs that are already running in the terminal — use terminal_keys/terminal_read instead.",
         input_schema: {
             type: "object",
             properties: {

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/context-manager.d.ts

@@ -5,7 +5,6 @@ export declare class ContextManager {
     private nextId;
     private currentCwd;
     private sessionStart;
-    private pendingToolCalls;
     private firstPrompt;
     private agentShellActive;
     private handlers;

package/dist/context-manager.js

@@ -1,16 +1,9 @@
 import { getSettings } from "./settings.js";
-// Non-configurable thresholds (agent response and tool output follow shell settings)
-const AGENT_RESPONSE_TRUNCATE_THRESHOLD = 20;
-const AGENT_RESPONSE_HEAD_LINES = 15;
-const TOOL_TRUNCATE_THRESHOLD = 20;
-const TOOL_HEAD_LINES = 5;
-const TOOL_TAIL_LINES = 5;
 export class ContextManager {
     exchanges = [];
     nextId = 1;
     currentCwd;
     sessionStart;
-    pendingToolCalls = [];
     firstPrompt = true;
     agentShellActive = false; // true while user_shell command is executing
     handlers = null;
@@ -43,46 +36,11 @@ export class ContextManager {
         bus.on("shell:agent-exec-start", () => { this.agentShellActive = true; });
         bus.on("shell:agent-exec-done", () => { this.agentShellActive = false; });
         // ── Subscribe to agent events ──
+        // Only track queries (as markers). Agent responses and tool outputs
+        // live exclusively in ConversationState to avoid duplication.
         bus.on("agent:query", (e) => {
-            this.pendingToolCalls = [];
             this.addExchange({ type: "agent_query", query: e.query });
         });
-        bus.on("agent:response-done", (e) => {
-            this.addExchange({
-                type: "agent_response",
-                response: e.response,
-                toolCalls: this.pendingToolCalls,
-            });
-            this.pendingToolCalls = [];
-        });
-        bus.on("agent:tool-call", (e) => {
-            // Accumulate tool calls for the agent_response summary
-            this.pendingToolCalls.push({
-                tool: e.tool,
-                args: e.args,
-                output: "",
-                exitCode: null,
-            });
-        });
-        bus.on("agent:tool-output", (e) => {
-            // Update the last pending tool call with output
-            const last = this.pendingToolCalls[this.pendingToolCalls.length - 1];
-            if (last) {
-                last.output = e.output;
-                last.exitCode = e.exitCode;
-            }
-            // Also store as a separate exchange for chronological log
-            const lines = e.output.split("\n");
-            this.addExchange({
-                type: "tool_execution",
-                tool: e.tool,
-                args: {},
-                output: e.output,
-                exitCode: e.exitCode,
-                outputLines: lines.length,
-                outputBytes: e.output.length,
-            });
-        });
     }
     // ── Public query API ──────────────────────────────────────────
     getCwd() {
@@ -231,7 +189,6 @@ export class ContextManager {
      */
     clear() {
         this.exchanges = [];
-        this.pendingToolCalls = [];
         this.firstPrompt = true;
         // Don't reset nextId — IDs should be globally unique within a session
     }
@@ -249,12 +206,7 @@ export class ContextManager {
                 const s = getSettings();
                 ex.output = truncateOutput(ex.output, s.shellTruncateThreshold, s.shellHeadLines, s.shellTailLines, ex.id);
             }
-            else if (ex.type === "agent_response") {
-                ex.response = truncateHead(ex.response, AGENT_RESPONSE_TRUNCATE_THRESHOLD, AGENT_RESPONSE_HEAD_LINES, ex.id);
-            }
-            else if (ex.type === "tool_execution") {
-                ex.output = truncateOutput(ex.output, TOOL_TRUNCATE_THRESHOLD, TOOL_HEAD_LINES, TOOL_TAIL_LINES, ex.id);
-            }
+            // agent_query has no output to truncate
         }
         // Pass 2: budget enforcement — strip output from oldest if over budget
         let totalSize = result.reduce((sum, ex) => sum + this.exchangeSize(ex), 0);
@@ -264,12 +216,6 @@ export class ContextManager {
             if (ex.type === "shell_command") {
                 ex.output = `[output omitted, use shell_recall tool to expand id ${ex.id}]`;
             }
-            else if (ex.type === "tool_execution") {
-                ex.output = `[output omitted, use shell_recall tool to expand id ${ex.id}]`;
-            }
-            else if (ex.type === "agent_response") {
-                ex.response = `[response omitted, use shell_recall tool to expand id ${ex.id}]`;
-            }
             totalSize -= before - this.exchangeSize(ex);
         }
         return result;
@@ -288,7 +234,8 @@ export class ContextManager {
             out += `- When the user asks to see, list, view, or display anything, ALWAYS use user_shell. NEVER use internal tools like ls/read/bash for display — the user won't see it.\n`;
             out += `- Only use internal tools when YOU need to reason about content silently (e.g. reading a file to answer a question about it).\n`;
             out += `- After a user_shell command, the user already saw the output. Do NOT repeat or summarize it.\n`;
-            out += `- You can browse or search session history with shell_recall.\n`;
+            out += `- You can browse or search shell history with shell_recall.\n`;
+            out += `- You can browse or search evicted conversation turns with conversation_recall.\n`;
             out += `\n`;
             this.firstPrompt = false;
         }
@@ -326,25 +273,6 @@ export class ContextManager {
             }
             case "agent_query":
                 return `#${ex.id} [you] > ${ex.query}\n`;
-            case "agent_response": {
-                let s = `#${ex.id} [agent] `;
-                if (ex.response)
-                    s += ex.response.split("\n")[0] + "\n";
-                if (ex.response.includes("\n")) {
-                    const rest = ex.response.slice(ex.response.indexOf("\n") + 1);
-                    if (rest.trim())
-                        s += indent(rest, "  ") + "\n";
-                }
-                return s;
-            }
-            case "tool_execution": {
-                let s = `#${ex.id} [tool] ${ex.tool}\n`;
-                if (ex.output)
-                    s += indent(ex.output, "  ") + "\n";
-                if (ex.exitCode !== null)
-                    s += `  exit ${ex.exitCode}\n`;
-                return s;
-            }
         }
     }
     formatExchangeFull(ex) {
@@ -361,16 +289,6 @@ export class ContextManager {
             }
             case "agent_query":
                 return `#${ex.id} [you] > ${ex.query}`;
-            case "agent_response":
-                return `#${ex.id} [agent]\n${ex.response}`;
-            case "tool_execution": {
-                let s = `#${ex.id} [tool] ${ex.tool} (${ex.outputLines} lines, ${ex.outputBytes} bytes)\n`;
-                if (ex.output)
-                    s += ex.output + "\n";
-                if (ex.exitCode !== null)
-                    s += `exit ${ex.exitCode}\n`;
-                return s;
-            }
         }
     }
     exchangeOneLiner(ex) {
@@ -381,12 +299,6 @@ export class ContextManager {
             }
             case "agent_query":
                 return `#${ex.id} query: ${ex.query}`;
-            case "agent_response": {
-                const preview = ex.response.split("\n")[0]?.slice(0, 80) ?? "";
-                return `#${ex.id} agent: ${preview}${ex.response.length > 80 ? "..." : ""}`;
-            }
-            case "tool_execution":
-                return `#${ex.id} tool: ${ex.tool} (${ex.outputLines} lines, exit ${ex.exitCode ?? "?"})`;
         }
     }
     exchangeSearchText(ex) {
@@ -395,10 +307,6 @@ export class ContextManager {
                 return `${ex.command}\n${ex.output}`;
             case "agent_query":
                 return ex.query;
-            case "agent_response":
-                return ex.response;
-            case "tool_execution":
-                return `${ex.tool}\n${ex.output}`;
         }
     }
     exchangeSize(ex) {
@@ -407,10 +315,6 @@ export class ContextManager {
                 return ex.command.length + ex.output.length;
             case "agent_query":
                 return ex.query.length;
-            case "agent_response":
-                return ex.response.length;
-            case "tool_execution":
-                return ex.tool.length + ex.output.length;
         }
     }
 }
@@ -426,15 +330,6 @@ function truncateOutput(text, threshold, headLines, tailLines, id) {
         ...lines.slice(-tailLines),
     ].join("\n");
 }
-function truncateHead(text, threshold, headLines, id) {
-    const lines = text.split("\n");
-    if (lines.length <= threshold)
-        return text;
-    return [
-        ...lines.slice(0, headLines),
-        `[... truncated, use shell_recall tool with expand and id ${id} for full response ...]`,
-    ].join("\n");
-}
 function indent(text, prefix) {
     return text
         .split("\n")

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. */