agent-sh 0.4.0 → 0.6.0

package/dist/core.js

@@ -1,86 +1,306 @@
 /**
  * Core kernel — the minimum viable agent-sh.
  *
- * Wires up EventBus + ContextManager + AcpClient without any frontend.
+ * Wires up EventBus + ContextManager + AgentBackend without any frontend.
  * Consumers attach their own I/O (Shell, WebSocket, REST, tests) by
- * subscribing to bus events and calling client methods.
+ * subscribing to bus events.
  *
- * The core listens for `agent:submit` and `agent:cancel-request` events
- * from any frontend, routing them to the AcpClient. This means frontends
- * never need a direct reference to AcpClient — they just emit events.
+ * The default backend (AgentLoop) is created eagerly but wired lazily —
+ * extensions can register alternative backends via agent:register-backend
+ * before activateBackend() is called.
  *
  * Usage:
  *   import { createCore } from "agent-sh";
- *   const core = createCore({ agentCommand: "pi-acp" });
- *   core.bus.on("agent:response-chunk", ({ text }) => ws.send(text));
- *   await core.start();
- *   core.bus.emit("agent:submit", { query: "hello" });
+ *   const core = createCore({ apiKey: "...", model: "gpt-4o" });
+ *   core.bus.on("agent:response-chunk", ({ blocks }) => { ... });
+ *   core.activateBackend();
+ *   const response = await core.query("hello");
  */
 import { EventBus } from "./event-bus.js";
 import { ContextManager } from "./context-manager.js";
-import { AcpClient } from "./acp-client.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";
 // Re-export types that library consumers need
 export { EventBus } from "./event-bus.js";
 export { palette, setPalette, resetPalette } from "./utils/palette.js";
+export { runSubagent } from "./agent/subagent.js";
+export { LlmClient } from "./utils/llm-client.js";
 export function createCore(config) {
     const bus = new EventBus();
     const handlers = new HandlerRegistry();
     const contextManager = new ContextManager(bus);
-    const client = new AcpClient({ bus, contextManager, config });
-    let connected = false;
-    // Route frontend events to the agent — any frontend (Shell, WebSocket,
-    // REST handler, test harness) can emit these without knowing about AcpClient.
-    bus.on("agent:submit", ({ query, modeInstruction, modeLabel }) => {
-        (async () => {
-            // Wait briefly for agent connection if start() is still in progress
-            if (!connected) {
-                for (let i = 0; i < 30 && !connected; i++) {
-                    await new Promise((r) => setTimeout(r, 100));
-                }
+    // ── Resolve provider ─────────────────────────────────────────
+    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,
+                });
             }
-            if (!connected) {
-                bus.emit("ui:error", { message: "Agent not connected. Please wait a moment and try again." });
+        }
+        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;
+    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) {
+            bus.emit("ui:error", { message: `Unknown backend: ${name}` });
+            return;
+        }
+        // Deactivate current backend
+        if (activeBackendName === "agent-sh") {
+            agentLoop?.unwire();
+        }
+        else 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;
             }
-            await client.sendPrompt(query, { modeInstruction, modeLabel });
-        })().catch((err) => {
-            bus.emit("agent:error", {
-                message: err instanceof Error ? err.message : String(err),
-            });
+            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;
+        }
+        if (!silent) {
+            bus.emit("ui:info", { message: `Backend: ${name}` });
+        }
+        bus.emit("config:changed", {});
+    };
+    bus.on("agent:register-backend", (backend) => {
+        backends.set(backend.name, backend);
+    });
+    bus.on("config:switch-backend", ({ name }) => {
+        activateByName(name);
+    });
+    bus.on("config:list-backends", () => {
+        const names = [];
+        if (agentLoop)
+            names.push("agent-sh");
+        for (const name of backends.keys())
+            names.push(name);
+        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);
+        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,
         });
     });
-    bus.on("agent:cancel-request", () => {
-        client.cancel().catch(() => { });
+    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", {});
     });
     return {
         bus,
         contextManager,
-        client,
-        async start() {
-            await client.start();
-            connected = true;
+        llmClient,
+        activateBackend() {
+            // Silent — backend info is shown in the startup banner.
+            // Runtime switches (config:switch-backend) still emit ui:info.
+            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) {
+                activateByName(backends.keys().next().value, true);
+            }
+        },
+        async query(text) {
+            return new Promise((resolve, reject) => {
+                let response = "";
+                let settled = false;
+                const onChunk = (e) => {
+                    for (const b of e.blocks)
+                        if (b.type === "text")
+                            response += b.text;
+                };
+                const onDone = () => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    cleanup();
+                    resolve(response);
+                };
+                const onError = (e) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    cleanup();
+                    reject(new Error(e.message));
+                };
+                const cleanup = () => {
+                    bus.off("agent:response-chunk", onChunk);
+                    bus.off("agent:processing-done", onDone);
+                    bus.off("agent:error", onError);
+                };
+                bus.on("agent:response-chunk", onChunk);
+                bus.on("agent:processing-done", onDone);
+                bus.on("agent:error", onError);
+                bus.emit("agent:submit", { query: text });
+            });
+        },
+        cancel() {
+            bus.emit("agent:cancel-request", {});
         },
         extensionContext(opts) {
             return {
                 bus,
                 contextManager,
-                getAcpClient: () => client,
+                llmClient,
                 quit: opts.quit,
                 setPalette,
                 createBlockTransform: (o) => streamTransform.createBlockTransform(bus, o),
                 createFencedBlockTransform: (o) => streamTransform.createFencedBlockTransform(bus, o),
                 getExtensionSettings: settingsMod.getExtensionSettings,
+                registerCommand: (name, description, handler) => bus.emit("command:register", { name, description, handler }),
+                registerTool: (tool) => agentLoop?.registerTool(tool),
+                getTools: () => agentLoop?.getTools() ?? [],
                 define: (name, fn) => handlers.define(name, fn),
                 advise: (name, wrapper) => handlers.advise(name, wrapper),
                 call: (name, ...args) => handlers.call(name, ...args),
             };
         },
         kill() {
-            client.kill();
+            if (activeBackendName === "agent-sh") {
+                agentLoop?.kill();
+            }
+            else if (activeBackendName) {
+                backends.get(activeBackendName)?.kill();
+            }
         },
     };
 }

package/dist/event-bus.d.ts

@@ -1,3 +1,5 @@
+import type { AgentMode } from "./types.js";
+import type { ToolResultDisplay } from "./agent/types.js";
 /**
  * Typed event map — every event has a known payload shape.
  */
@@ -22,25 +24,28 @@ export interface ShellEvents {
     "shell:agent-exec-done": Record<string, never>;
     "agent:submit": {
         query: string;
-        modeInstruction?: string;
-        modeLabel?: string;
     };
-    "agent:cancel-request": Record<string, never>;
+    "agent:cancel-request": {
+        silent?: boolean;
+    };
     "input-mode:register": import("./types.js").InputModeConfig;
     "agent:query": {
         query: string;
-        modeLabel?: string;
     };
     "agent:thinking-chunk": {
         text: string;
     };
     "agent:response-chunk": {
-        text: string;
-        blocks?: ContentBlock[];
+        blocks: ContentBlock[];
     };
     "agent:response-done": {
         response: string;
     };
+    "agent:usage": {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
     "agent:processing-start": Record<string, never>;
     "agent:processing-done": Record<string, never>;
     "agent:cancelled": Record<string, never>;
@@ -56,20 +61,37 @@ export interface ShellEvents {
         output: string;
         exitCode: number | null;
     };
+    "agent:tool-batch": {
+        groups: Array<{
+            kind: string;
+            tools: Array<{
+                name: string;
+                displayDetail?: string;
+            }>;
+        }>;
+    };
     "agent:tool-started": {
         title: string;
         toolCallId?: string;
         kind?: string;
+        icon?: string;
         locations?: {
             path: string;
             line?: number | null;
         }[];
         rawInput?: unknown;
+        /** Pre-formatted display detail from tool's formatCall(). */
+        displayDetail?: string;
+        batchIndex?: number;
+        batchTotal?: number;
     };
     "agent:tool-completed": {
         toolCallId?: string;
         exitCode: number | null;
         rawOutput?: unknown;
+        kind?: string;
+        /** Structured result display — set by formatResult or defaults, overridable via onPipe. */
+        resultDisplay?: ToolResultDisplay;
     };
     "agent:tool-output-chunk": {
         chunk: string;
@@ -80,6 +102,11 @@ export interface ShellEvents {
         metadata: Record<string, unknown>;
         decision: Record<string, unknown>;
     };
+    "command:register": {
+        name: string;
+        description: string;
+        handler: (args: string) => Promise<void> | void;
+    };
     "command:execute": {
         name: string;
         args: string;
@@ -90,6 +117,9 @@ export interface ShellEvents {
     "ui:error": {
         message: string;
     };
+    "ui:suggestion": {
+        text: string;
+    };
     "input:keypress": {
         key: string;
     };
@@ -107,24 +137,75 @@ export interface ShellEvents {
         command: string;
         output: string;
         cwd: string;
+        exitCode: number | null;
         done: boolean;
     };
-    "session:configure": {
-        cwd: string;
-        mcpServers: {
-            name: string;
-            command: string;
-            args: string[];
-            env: {
-                name: string;
-                value: string;
-            }[];
-        }[];
+    "agent:info": {
+        name: string;
+        version: string;
+        model?: string;
+        provider?: string;
+        contextWindow?: number;
+    };
+    "agent:reset-session": Record<string, never>;
+    "agent:register-backend": {
+        name: string;
+        kill: () => void;
+        start?: () => Promise<void>;
+    };
+    "config:switch-backend": {
+        name: string;
+    };
+    "config:list-backends": Record<string, never>;
+    "config:get-backends": {
+        names: string[];
+        active: string | null;
     };
     "config:changed": Record<string, never>;
     "config:cycle": Record<string, never>;
+    "config:switch-model": {
+        model: string;
+    };
+    "config:get-models": {
+        models: {
+            model: string;
+            provider: string;
+        }[];
+        active: string | null;
+    };
+    "config:set-thinking": {
+        level: string;
+    };
+    "config:get-thinking": {
+        level: string;
+        levels: string[];
+        supported: boolean;
+    };
+    "config:switch-provider": {
+        provider: string;
+    };
+    "config:set-modes": {
+        modes: AgentMode[];
+    };
+    "provider:register": {
+        id: string;
+        apiKey?: string;
+        baseURL?: string;
+        defaultModel: string;
+        models?: (string | {
+            id: string;
+            reasoning?: boolean;
+            contextWindow?: number;
+        })[];
+        /** Provider supports the reasoning_effort parameter. Default: true. */
+        supportsReasoningEffort?: boolean;
+    };
     "autocomplete:request": {
         buffer: string;
+        /** Parsed slash command name (e.g. "/backend"), or null if not a command. */
+        command: string | null;
+        /** Text after the command name (e.g. "clau" for "/backend clau"), or null. */
+        commandArgs: string | null;
         items: {
             name: string;
             description: string;

package/dist/event-bus.js

@@ -28,7 +28,16 @@ export class EventBus {
      * modify data (e.g. render LaTeX → terminal image) before renderers see it.
      */
     emitTransform(event, payload) {
-        const transformed = this.emitPipe(event, payload);
+        let transformed;
+        try {
+            transformed = this.emitPipe(event, payload);
+        }
+        catch (err) {
+            if (process.env.DEBUG) {
+                process.stderr.write(`[event-bus] pipe error on ${String(event)}: ${err}\n`);
+            }
+            transformed = payload; // fall back to untransformed
+        }
         this.emitter.emit(event, transformed);
     }
     /** Register a transform listener for a pipeline event. */

package/dist/extension-loader.d.ts

@@ -13,4 +13,4 @@ import type { ExtensionContext } from "./types.js";
  * Each module should export a default or named `activate(ctx)` function.
  * Errors are non-fatal — logged via ui:error and skipped.
  */
-export declare function loadExtensions(ctx: ExtensionContext, cliExtensions?: string[]): Promise<void>;
+export declare function loadExtensions(ctx: ExtensionContext, cliExtensions?: string[]): Promise<string[]>;

package/dist/extension-loader.js

@@ -47,7 +47,10 @@ export async function loadExtensions(ctx, cliExtensions) {
         const entries = await fs.readdir(EXT_DIR, { withFileTypes: true });
         for (const entry of entries) {
             const fullPath = path.join(EXT_DIR, entry.name);
-            if (entry.isDirectory()) {
+            // Resolve symlinks to check if they point to directories
+            const isDir = entry.isDirectory() ||
+                (entry.isSymbolicLink() && (await fs.stat(fullPath)).isDirectory());
+            if (isDir) {
                 // Directory extension: look for index.{ts,js,mjs,...}
                 const indexFile = await findIndex(fullPath);
                 if (indexFile) {
@@ -71,6 +74,7 @@ export async function loadExtensions(ctx, cliExtensions) {
         return true;
     });
     // Load each extension
+    const loaded = [];
     for (const specifier of unique) {
         try {
             const importPath = await resolveSpecifier(specifier);
@@ -86,6 +90,10 @@ export async function loadExtensions(ctx, cliExtensions) {
                     : mod.activate;
             if (typeof activate === "function") {
                 activate(ctx);
+                // Extract a short name from the specifier
+                const base = path.basename(specifier).replace(/\.(ts|js|mjs|mts|tsx)$/, "");
+                const name = base === "index" ? path.basename(path.dirname(specifier)) : base;
+                loaded.push(name);
             }
         }
         catch (err) {
@@ -94,6 +102,7 @@ export async function loadExtensions(ctx, cliExtensions) {
             });
         }
     }
+    return loaded;
 }
 /**
  * Find an index file in a directory extension.

package/dist/extensions/command-suggest.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Command suggestion extension (fast-path LLM feature).
+ *
+ * After a shell command fails (non-zero exit), uses llmClient.complete()
+ * to suggest a fix. Shows the suggestion below the prompt.
+ *
+ * Only active when llmClient is available (internal agent mode).
+ */
+import type { ExtensionContext } from "../types.js";
+export default function activate({ bus, llmClient }: ExtensionContext): void;

package/dist/extensions/command-suggest.js

@@ -0,0 +1,41 @@
+export default function activate({ bus, llmClient }) {
+    if (!llmClient)
+        return;
+    let suggesting = false;
+    bus.on("shell:command-done", ({ command, output, exitCode, cwd }) => {
+        if (exitCode === null || exitCode === 0)
+            return;
+        if (!command.trim())
+            return;
+        if (suggesting)
+            return; // don't stack suggestions
+        suggesting = true;
+        // Truncate output to avoid blowing up the prompt
+        const truncated = output.length > 1000
+            ? output.slice(-1000)
+            : output;
+        llmClient.complete({
+            messages: [
+                {
+                    role: "system",
+                    content: "You are a shell assistant. The user's command failed. " +
+                        "Suggest a fix as a single command. Just the command, no explanation, no backticks, no prefix. " +
+                        "If you can't suggest anything useful, reply with an empty string.",
+                },
+                {
+                    role: "user",
+                    content: `cwd: ${cwd}\n$ ${command}\n${truncated}\nexit code: ${exitCode}`,
+                },
+            ],
+            max_tokens: 150,
+        }).then((suggestion) => {
+            suggesting = false;
+            const trimmed = suggestion.trim().replace(/^`+|`+$/g, ""); // strip backticks
+            if (trimmed && trimmed.length < 500) {
+                bus.emit("ui:suggestion", { text: trimmed });
+            }
+        }).catch(() => {
+            suggesting = false;
+        });
+    });
+}

package/dist/extensions/slash-commands.d.ts

@@ -1,2 +1,2 @@
 import type { ExtensionContext } from "../types.js";
-export default function activate({ bus, getAcpClient, quit }: ExtensionContext): void;
+export default function activate({ bus, contextManager }: ExtensionContext): void;