agent-sh 0.8.0 → 0.10.0

package/dist/agent/tools/ls.js

@@ -44,21 +44,20 @@ export function createLsTool(getCwd) {
                 const entries = await fs.readdir(absPath, {
                     withFileTypes: true,
                 });
-                const lines = [];
-                for (const e of entries) {
+                const items = await Promise.all(entries.map(async (e) => {
                     const fullPath = path.join(absPath, e.name);
                     try {
                         const stat = await fs.stat(fullPath);
                         const size = e.isDirectory() ? "-" : formatSize(stat.size);
                         const mtime = stat.mtime.toISOString().slice(0, 16).replace("T", " ");
-                        lines.push(`${mtime}  ${size.padStart(8)}  ${e.isDirectory() ? e.name + "/" : e.name}`);
+                        return `${mtime}  ${size.padStart(8)}  ${e.isDirectory() ? e.name + "/" : e.name}`;
                     }
                     catch {
-                        lines.push(`${"?".padStart(16)}  ${"?".padStart(8)}  ${e.isDirectory() ? e.name + "/" : e.name}`);
+                        return `${"?".padStart(16)}  ${"?".padStart(8)}  ${e.isDirectory() ? e.name + "/" : e.name}`;
                     }
-                }
+                }));
                 return {
-                    content: lines.join("\n") || "(empty directory)",
+                    content: items.join("\n") || "(empty directory)",
                     exitCode: 0,
                     isError: false,
                 };

package/dist/agent/types.d.ts

@@ -38,7 +38,7 @@ export type ToolResultBody = {
     maxLines?: number;
 };
 export interface ToolDisplayInfo {
-    kind: "read" | "write" | "execute" | "search" | "display";
+    kind: "read" | "write" | "execute" | "search";
     locations?: {
         path: string;
         line?: number | null;
@@ -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

@@ -24,6 +24,23 @@ export declare class ContextManager {
      * Optional start/end restrict to a line range (1-indexed).
      */
     expand(ids: number[], start?: number, end?: number): string;
+    /**
+     * Return shell events with id > afterId, formatted as an incremental
+     * delta suitable for injection into conversation history. Skips
+     * agent-source commands (already visible in tool results). Returns
+     * null when nothing new exists.
+     *
+     * The motivation: resending the full <shell_context> every turn wastes
+     * tokens — N turns × full history = O(N²) cost for O(N) information.
+     * Instead we inject only new events as regular conversation messages,
+     * so the provider's prefix cache amortizes them to O(N).
+     */
+    getEventsSince(afterId: number): {
+        text: string;
+        lastSeq: number;
+    } | null;
+    /** Highest exchange id seen so far (0 if none). */
+    lastSeq(): number;
     /**
      * One-line summaries of last N exchanges.
      */

package/dist/context-manager.js

@@ -140,6 +140,43 @@ export class ContextManager {
         }
         return results.join("\n\n");
     }
+    /**
+     * Return shell events with id > afterId, formatted as an incremental
+     * delta suitable for injection into conversation history. Skips
+     * agent-source commands (already visible in tool results). Returns
+     * null when nothing new exists.
+     *
+     * The motivation: resending the full <shell_context> every turn wastes
+     * tokens — N turns × full history = O(N²) cost for O(N) information.
+     * Instead we inject only new events as regular conversation messages,
+     * so the provider's prefix cache amortizes them to O(N).
+     */
+    getEventsSince(afterId) {
+        const fresh = this.exchanges.filter((e) => e.id > afterId && !(e.type === "shell_command" && e.source === "agent"));
+        if (fresh.length === 0)
+            return null;
+        const lastSeq = this.exchanges[this.exchanges.length - 1].id;
+        // Apply per-type truncation so giant outputs don't blow up the turn.
+        const truncated = fresh.map((ex) => {
+            if (ex.type === "shell_command") {
+                const s = getSettings();
+                return {
+                    ...ex,
+                    output: truncateOutput(ex.output, s.shellTruncateThreshold, s.shellHeadLines, s.shellTailLines, ex.id),
+                };
+            }
+            return { ...ex };
+        });
+        const body = truncated.map((ex) => this.formatExchangeTruncated(ex)).join("\n");
+        return {
+            text: `<shell-events>\n${body}</shell-events>`,
+            lastSeq,
+        };
+    }
+    /** Highest exchange id seen so far (0 if none). */
+    lastSeq() {
+        return this.exchanges.length === 0 ? 0 : this.exchanges[this.exchanges.length - 1].id;
+    }
     /**
      * One-line summaries of last N exchanges.
      */
@@ -229,13 +266,9 @@ export class ContextManager {
             out += `The user interacts with a real shell (PTY) and sends you queries inline. You are there to help them with their tasks.\n`;
             out += `\n`;
             out += `IMPORTANT tool usage rules:\n`;
-            out += `- user_shell runs commands in the user's live shell (PTY). The user sees output directly — no summary needed.\n`;
             out += `- Your internal tools (bash, read, write, ls, etc.) run in an isolated subprocess. The user CANNOT see their output.\n`;
-            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 shell history with shell_recall.\n`;
-            out += `- You can browse or search evicted conversation turns with conversation_recall.\n`;
             out += `\n`;
             this.firstPrompt = 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. */

package/dist/core.js

@@ -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,15 +18,17 @@
  */
 import { EventBus } from "./event-bus.js";
 import { ContextManager } from "./context-manager.js";
-import { AgentLoop } from "./agent/agent-loop.js";
-import { LlmClient } from "./utils/llm-client.js";
 import { setPalette } from "./utils/palette.js";
 import * as streamTransform from "./utils/stream-transform.js";
 import * as settingsMod from "./settings.js";
-import { resolveProvider, getProviderNames } from "./settings.js";
 import { HandlerRegistry } from "./utils/handler-registry.js";
 import { TerminalBuffer } from "./utils/terminal-buffer.js";
-import { FloatingPanel } from "./utils/floating-panel.js";
+import crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { DefaultCompositor, StdoutSurface } from "./utils/compositor.js";
+const STORAGE_ROOT = path.join(os.homedir(), ".agent-sh");
 // Re-export types that library consumers need
 export { EventBus } from "./event-bus.js";
 export { palette, setPalette, resetPalette } from "./utils/palette.js";
@@ -36,92 +38,29 @@ export function createCore(config) {
     const bus = new EventBus();
     const handlers = new HandlerRegistry();
     const contextManager = new ContextManager(bus, handlers);
-    // ── Resolve provider ─────────────────────────────────────────
+    // 3 bytes = 6 hex chars, ~16M values — ample for per-lineage uniqueness and
+    // short enough to read/remember. Legacy content may have 16-char iids; any
+    // parsers should accept ≥6 hex chars.
+    const instanceId = crypto.randomBytes(3).toString("hex");
     const settings = settingsMod.getSettings();
-    let activeProvider = null;
-    const providerRegistry = new Map();
-    for (const name of getProviderNames()) {
-        const p = resolveProvider(name);
-        if (p)
-            providerRegistry.set(name, p);
-    }
-    const providerName = config.provider ?? settings.defaultProvider;
-    if (providerName) {
-        activeProvider = providerRegistry.get(providerName) ?? null;
-    }
-    // Build flat modes list across all providers
-    const buildModes = () => {
-        const allModes = [];
-        for (const [id, p] of providerRegistry) {
-            if (!p.apiKey)
-                continue;
-            for (const model of p.models) {
-                const mc = p.modelCapabilities?.get(model);
-                allModes.push({
-                    model,
-                    provider: id,
-                    providerConfig: { apiKey: p.apiKey, baseURL: p.baseURL },
-                    contextWindow: mc?.contextWindow ?? p.contextWindow,
-                    reasoning: mc?.reasoning,
-                    supportsReasoningEffort: p.supportsReasoningEffort,
-                });
-            }
-        }
-        return allModes;
-    };
-    const effectiveApiKey = config.apiKey ?? activeProvider?.apiKey;
-    const effectiveBaseURL = config.baseURL ?? activeProvider?.baseURL;
-    const effectiveModel = config.model ?? activeProvider?.defaultModel;
-    let modes = buildModes();
-    if (modes.length === 0 && effectiveApiKey && effectiveModel) {
-        modes = [{ model: effectiveModel }];
-    }
-    const initialModeIndex = Math.max(0, modes.findIndex((m) => m.model === effectiveModel && (!activeProvider || m.provider === activeProvider.id)));
-    // Shared LLM client — used by agent loop AND fast-path features
-    let llmClient = null;
-    if (effectiveApiKey) {
-        if (!effectiveModel) {
-            throw new Error("No model specified. Use --model or configure a provider with defaultModel in ~/.agent-sh/settings.json");
-        }
-        llmClient = new LlmClient({
-            apiKey: effectiveApiKey,
-            baseURL: effectiveBaseURL,
-            model: effectiveModel,
-        });
-    }
-    // Create AgentLoop (unwired — tools only, no bus subscriptions yet)
-    const agentLoop = llmClient
-        ? new AgentLoop(bus, contextManager, llmClient, handlers, modes, initialModeIndex)
-        : null;
+    // Expose raw CLI config so the agent backend extension can resolve
+    // providers and create the LLM client.
+    handlers.define("config:get-shell-config", () => config);
     const backends = new Map();
     let activeBackendName = null;
     const activateByName = async (name, silent = false) => {
-        const backend = name === "agent-sh" ? null : backends.get(name);
-        if (name !== "agent-sh" && !backend) {
+        const backend = backends.get(name);
+        if (!backend) {
             bus.emit("ui:error", { message: `Unknown backend: ${name}` });
             return;
         }
         // Deactivate current backend
-        if (activeBackendName === "agent-sh") {
-            agentLoop?.unwire();
-        }
-        else if (activeBackendName) {
+        if (activeBackendName) {
             backends.get(activeBackendName)?.kill();
         }
         // Activate new backend
-        if (name === "agent-sh") {
-            if (!agentLoop) {
-                bus.emit("ui:error", { message: "No LLM provider configured for built-in backend" });
-                return;
-            }
-            agentLoop.wire();
-            activeBackendName = "agent-sh";
-            bus.emit("agent:info", { name: "agent-sh", version: "0.4", model: llmClient?.model, provider: activeProvider?.id, contextWindow: activeProvider?.contextWindow });
-        }
-        else {
-            await backend.start?.();
-            activeBackendName = name;
-        }
+        await backend.start?.();
+        activeBackendName = name;
         if (!silent) {
             bus.emit("ui:info", { message: `Backend: ${name}` });
         }
@@ -131,107 +70,30 @@ export function createCore(config) {
         backends.set(backend.name, backend);
     });
     bus.on("config:switch-backend", ({ name }) => {
-        activateByName(name);
+        activateByName(name).then(() => {
+            if (activeBackendName === name) {
+                settingsMod.updateSettings({ defaultBackend: name });
+                bus.emit("ui:info", { message: `Saved '${name}' as default backend.` });
+            }
+        });
     });
     bus.on("config:list-backends", () => {
-        const names = [];
-        if (agentLoop)
-            names.push("agent-sh");
-        for (const name of backends.keys())
-            names.push(name);
+        const names = [...backends.keys()];
         const list = names
             .map((n) => n === activeBackendName ? `${n} (active)` : n)
             .join(", ");
         bus.emit("ui:info", { message: `Backends: ${list}` });
     });
-    bus.onPipe("config:get-backends", (payload) => {
-        const names = [];
-        if (agentLoop)
-            names.push("agent-sh");
-        for (const name of backends.keys())
-            names.push(name);
+    bus.onPipe("config:get-backends", () => {
+        const names = [...backends.keys()];
         return { names, active: activeBackendName };
     });
-    // ── Runtime provider management ──────────────────────────────
-    bus.on("provider:register", (p) => {
-        const rawModels = p.models ?? (p.defaultModel ? [p.defaultModel] : []);
-        const modelIds = [];
-        const caps = new Map();
-        for (const m of rawModels) {
-            if (typeof m === "string") {
-                modelIds.push(m);
-            }
-            else {
-                modelIds.push(m.id);
-                caps.set(m.id, { reasoning: m.reasoning, contextWindow: m.contextWindow });
-            }
-        }
-        providerRegistry.set(p.id, {
-            id: p.id,
-            apiKey: p.apiKey,
-            baseURL: p.baseURL,
-            defaultModel: p.defaultModel,
-            models: modelIds,
-            supportsReasoningEffort: p.supportsReasoningEffort,
-            modelCapabilities: caps.size > 0 ? caps : undefined,
-        });
-        // Push registered models into the agent loop so they appear in
-        // autocomplete and are selectable via /model.
-        const addModes = modelIds.map((m) => {
-            const mc = caps.get(m);
-            return {
-                model: m,
-                provider: p.id,
-                providerConfig: { apiKey: p.apiKey ?? "", baseURL: p.baseURL },
-                contextWindow: mc?.contextWindow,
-                reasoning: mc?.reasoning,
-                supportsReasoningEffort: p.supportsReasoningEffort,
-            };
-        });
-        bus.emit("config:add-modes", { modes: addModes });
-    });
-    bus.on("config:switch-provider", ({ provider: name }) => {
-        const p = providerRegistry.get(name);
-        if (!p) {
-            bus.emit("ui:error", { message: `Unknown provider: ${name}` });
-            return;
-        }
-        if (!llmClient) {
-            bus.emit("ui:error", { message: `Provider switching requires internal agent mode` });
-            return;
-        }
-        const newApiKey = p.apiKey;
-        if (!newApiKey) {
-            bus.emit("ui:error", { message: `Provider "${name}" has no API key configured` });
-            return;
-        }
-        const switchModel = p.defaultModel ?? p.models[0];
-        if (!switchModel) {
-            bus.emit("ui:error", { message: `Provider "${name}" has no models configured` });
-            return;
-        }
-        llmClient.reconfigure({
-            apiKey: newApiKey,
-            baseURL: p.baseURL,
-            model: switchModel,
-        });
-        const newModes = p.models.map((m) => {
-            const mc = p.modelCapabilities?.get(m);
-            return {
-                model: m,
-                provider: name,
-                providerConfig: { apiKey: newApiKey, baseURL: p.baseURL },
-                contextWindow: mc?.contextWindow ?? p.contextWindow,
-                reasoning: mc?.reasoning,
-                supportsReasoningEffort: p.supportsReasoningEffort,
-            };
-        });
-        bus.emit("config:set-modes", { modes: newModes });
-        activeProvider = p;
-        bus.emit("agent:info", { name: "agent-sh", version: "0.4", model: switchModel, provider: name, contextWindow: p.contextWindow });
-        bus.emit("ui:info", { message: `Switched to ${name} (${switchModel})` });
-        bus.emit("config:changed", {});
-    });
+    // ── Compositor ──────────────────────────────────────────────
+    const compositor = new DefaultCompositor(bus);
+    const stdoutSurface = new StdoutSurface();
+    compositor.setDefault("agent", stdoutSurface);
+    compositor.setDefault("query", stdoutSurface);
+    compositor.setDefault("status", stdoutSurface);
     // ── Lazy singleton terminal buffer ──────────────────────────
     let terminalBufferSingleton; // undefined = not yet created
     const getTerminalBuffer = () => {
@@ -243,23 +105,17 @@ export function createCore(config) {
     return {
         bus,
         contextManager,
-        llmClient,
+        handlers,
         activateBackend() {
             // Silent — backend info is shown in the startup banner.
             // Runtime switches (config:switch-backend) still emit ui:info.
+            if (backends.size === 0)
+                return;
             const preferred = settings.defaultBackend;
             if (preferred && backends.has(preferred)) {
                 activateByName(preferred, true);
             }
-            else if (backends.size > 0 && !agentLoop) {
-                activateByName(backends.keys().next().value, true);
-            }
-            else if (agentLoop) {
-                agentLoop.wire();
-                activeBackendName = "agent-sh";
-                bus.emit("agent:info", { name: "agent-sh", version: "0.4", model: llmClient?.model, provider: activeProvider?.id, contextWindow: activeProvider?.contextWindow });
-            }
-            else if (backends.size > 0) {
+            else {
                 activateByName(backends.keys().next().value, true);
             }
         },
@@ -301,33 +157,80 @@ export function createCore(config) {
             bus.emit("agent:cancel-request", {});
         },
         extensionContext(opts) {
-            return {
+            const ctx = {
                 bus,
                 contextManager,
-                llmClient,
+                instanceId,
                 quit: opts.quit,
                 setPalette,
                 createBlockTransform: (o) => streamTransform.createBlockTransform(bus, o),
                 createFencedBlockTransform: (o) => streamTransform.createFencedBlockTransform(bus, o),
                 getExtensionSettings: settingsMod.getExtensionSettings,
+                getStoragePath: (namespace) => {
+                    const dir = path.join(STORAGE_ROOT, namespace);
+                    fs.mkdirSync(dir, { recursive: true });
+                    return dir;
+                },
                 registerCommand: (name, description, handler) => bus.emit("command:register", { name, description, handler }),
-                registerTool: (tool) => agentLoop?.registerTool(tool),
-                getTools: () => agentLoop?.getTools() ?? [],
+                registerTool: (tool) => bus.emit("agent:register-tool", { tool, extensionName: "" }),
+                unregisterTool: (name) => bus.emit("agent:unregister-tool", { name }),
+                getTools: () => bus.emitPipe("agent:get-tools", { tools: [] }).tools,
+                registerInstruction: (name, text) => bus.emit("agent:register-instruction", { name, text, extensionName: "" }),
+                removeInstruction: (name) => bus.emit("agent:remove-instruction", { name }),
+                registerSkill: (name, description, filePath) => bus.emit("agent:register-skill", { name, description, filePath, extensionName: "" }),
+                removeSkill: (name) => bus.emit("agent:remove-skill", { name }),
                 define: (name, fn) => handlers.define(name, fn),
                 advise: (name, wrapper) => handlers.advise(name, wrapper),
                 call: (name, ...args) => handlers.call(name, ...args),
+                list: () => handlers.list(),
                 get terminalBuffer() { return getTerminalBuffer(); },
-                createFloatingPanel: (config) => {
-                    const tb = config.dimBackground !== false ? getTerminalBuffer() : null;
-                    return new FloatingPanel(bus, { ...config, terminalBuffer: tb ?? undefined });
+                compositor,
+                createRemoteSession: (opts) => {
+                    const { surface } = opts;
+                    const cleanups = [];
+                    let active = true;
+                    // Redirect all render streams
+                    cleanups.push(compositor.redirect("agent", surface));
+                    cleanups.push(compositor.redirect("query", surface));
+                    cleanups.push(compositor.redirect("status", surface));
+                    // Keep shell interactive
+                    cleanups.push(handlers.advise("shell:on-processing-start", (next) => active ? undefined : next()));
+                    cleanups.push(handlers.advise("shell:on-processing-done", (next) => active ? undefined : next()));
+                    // Suppress chrome
+                    if (opts.suppressBorders !== false) {
+                        cleanups.push(handlers.advise("tui:response-border", (next, ...a) => active ? null : next(...a)));
+                    }
+                    if (opts.suppressQueryBox) {
+                        cleanups.push(handlers.advise("tui:render-user-query", (next, ...a) => active ? [] : next(...a)));
+                    }
+                    if (opts.suppressUsage !== false) {
+                        cleanups.push(handlers.advise("tui:render-usage", (next, ...a) => active ? "" : next(...a)));
+                    }
+                    if (opts.interactive) {
+                        cleanups.push(handlers.advise("dynamic-context:build", (next) => {
+                            const base = next();
+                            return active ? base + "\ninteractive-session: true\n" : base;
+                        }));
+                    }
+                    return {
+                        submit(query) { bus.emit("agent:submit", { query }); },
+                        get surface() { return surface; },
+                        get active() { return active; },
+                        close() {
+                            if (!active)
+                                return;
+                            active = false;
+                            for (const fn of cleanups.reverse())
+                                fn();
+                            cleanups.length = 0;
+                        },
+                    };
                 },
             };
+            return ctx;
         },
         kill() {
-            if (activeBackendName === "agent-sh") {
-                agentLoop?.kill();
-            }
-            else if (activeBackendName) {
+            if (activeBackendName) {
                 backends.get(activeBackendName)?.kill();
             }
         },