agent-sh 0.13.6 → 0.14.0

package/dist/core/index.js

@@ -1,23 +1,14 @@
 /**
- * Core kernel — the minimum viable agent-sh.
- *
- * Wires up EventBus + HandlerRegistry without any frontend or agent backend.
- * Consumers attach their own I/O (Shell, WebSocket, REST, tests) by
- * subscribing to bus events. Shell-specific tracking lives in the
- * shell-context built-in extension.
- *
- * Agent backends register themselves via the agent:register-backend bus
- * event. The built-in "ash" backend lives in src/agent/ and is activated
- * by hosts via activateAgent().
- *
- * Usage:
- *   import { createCore } from "agent-sh";
- *   const core = createCore({ apiKey: "...", model: "gpt-4o" });
- *   core.bus.on("agent:response-chunk", ({ blocks }) => { ... });
- *   core.activateBackend();
- *   const response = await core.query("hello");
+ * Core kernel — EventBus + HandlerRegistry + backend registry. Knows
+ * nothing about LLMs, tools, or specific backends; backends (ash,
+ * claude-code-bridge, ...) register through `agent:register-backend`
+ * and core dispatches to whichever is configured as default.
  */
 import { EventBus } from "./event-bus.js";
+// Side-effect imports so downstream tsc sees module-augmented BusEvents.
+import "../shell/events.js";
+import "../agent/events.js";
+import "../extensions/slash-commands/events.js";
 import * as settingsMod from "./settings.js";
 import { HandlerRegistry } from "../utils/handler-registry.js";
 import crypto from "node:crypto";
@@ -27,117 +18,74 @@ import { CONFIG_DIR } from "./settings.js";
 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 { LlmClient } from "../agent/llm-client.js";
 export { HistoryFile, InMemoryHistory, NoopHistory } from "../agent/history-file.js";
 export { compileSearchRegex, matchEntry, formatNuclearLine } from "../agent/nuclear-form.js";
 export function createCore(config) {
     const bus = new EventBus();
     const handlers = new HandlerRegistry();
-    // 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.
+    // 3 bytes = 6 hex chars; legacy content may have 16-char iids so parsers
+    // should accept ≥6 hex chars.
     const instanceId = crypto.randomBytes(3).toString("hex");
     bus.setSource(instanceId);
-    const settings = settingsMod.getSettings();
     handlers.define("config:get-app-config", () => config);
-    // Default; shell-context advises with the PTY-tracked cwd when loaded.
     handlers.define("cwd", () => process.cwd());
     // Empty defaults so registerContextProducer can advise regardless of
-    // backend. Each backend chooses whether to consume the strings — ash
-    // wraps them in <dynamic_context>/<query_context>; bridges may pull
-    // query-context:build and splice into the target SDK however they like.
+    // backend. Each backend chooses how to consume the strings.
     handlers.define("dynamic-context:build", () => "");
     handlers.define("query-context:build", () => "");
     const backends = new Map();
     let activeBackendName = null;
+    bus.on("agent:register-backend", (backend) => {
+        backends.set(backend.name, backend);
+    });
+    bus.onPipe("config:get-backends", () => ({
+        names: [...backends.keys()],
+        active: activeBackendName,
+    }));
     const activateByName = async (name) => {
         const backend = backends.get(name);
         if (!backend) {
             bus.emit("ui:error", { message: `Unknown backend: ${name}` });
             return false;
         }
-        if (activeBackendName) {
+        if (activeBackendName && activeBackendName !== name) {
             backends.get(activeBackendName)?.kill();
         }
-        await backend.start?.();
         activeBackendName = name;
+        await backend.start?.();
         return true;
     };
-    bus.on("agent:register-backend", (backend) => {
-        backends.set(backend.name, backend);
-    });
     bus.on("config:switch-backend", ({ name }) => {
         activateByName(name).then((ok) => {
             if (!ok)
                 return;
             settingsMod.updateSettings({ defaultBackend: name });
-            // Single ui:info; config:changed (which triggers prompt redraw) follows it.
             bus.emit("ui:info", { message: `Backend: ${name} (saved as default)` });
             bus.emit("config:changed", {});
         });
     });
     bus.on("config:list-backends", () => {
-        const names = [...backends.keys()];
-        const list = names
+        const list = [...backends.keys()]
             .map((n) => n === activeBackendName ? `${n} (active)` : n)
             .join(", ");
-        bus.emit("ui:info", { message: `Backends: ${list}` });
-    });
-    bus.onPipe("config:get-backends", () => {
-        const names = [...backends.keys()];
-        return { names, active: activeBackendName };
+        bus.emit("ui:info", { message: `Backends: ${list || "(none registered)"}` });
     });
     return {
         bus,
         handlers,
         instanceId,
         async activateBackend(override) {
-            if (backends.size === 0)
+            if (backends.size === 0) {
+                bus.emit("ui:info", { message: "No agent backend registered." });
                 return;
-            const preferred = override ?? settings.defaultBackend;
-            const name = preferred && backends.has(preferred) ? preferred : backends.keys().next().value;
+            }
+            const preferred = override ?? settingsMod.getSettings().defaultBackend;
+            const name = preferred && backends.has(preferred)
+                ? preferred
+                : backends.keys().next().value;
             await activateByName(name);
         },
-        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", {});
-        },
-        appendUserMessage(text) {
-            bus.emit("agent:append-user-message", { text });
-        },
         extensionContext(opts) {
             const ctx = {
                 bus,
@@ -165,6 +113,7 @@ export function createCore(config) {
         kill() {
             if (activeBackendName) {
                 backends.get(activeBackendName)?.kill();
+                activeBackendName = null;
             }
         },
     };

package/dist/extensions/index.d.ts

@@ -2,7 +2,8 @@
  * Cross-cutting built-ins, toggleable via `disabledBuiltins`.
  * Module-owned built-ins activate inline:
  *   shell-context, tui-renderer → registerShellHandlers (src/shell/)
- *   agent-backend, providers    → activateAgent         (src/agent/)
+ *   ash (a specific backend)    → activateAgent         (src/agent/)
+ *   backend registry             → createCore           (src/core/)
  */
 import type { ExtensionContext } from "../shell/host-types.js";
 type ActivateFn = (ctx: ExtensionContext) => void;

package/dist/extensions/index.js

@@ -1,5 +1,5 @@
 export const BUILTIN_EXTENSIONS = [
-    { name: "slash-commands", load: () => import("./slash-commands.js").then(m => m.default) },
+    { name: "slash-commands", load: () => import("./slash-commands/index.js").then(m => m.default) },
     { name: "file-autocomplete", load: () => import("./file-autocomplete.js").then(m => m.default) },
 ];
 /**

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

@@ -0,0 +1,18 @@
+/** Events slash-commands owns. */
+declare module "../../core/event-bus.js" {
+    interface BusEvents {
+        "command:register": {
+            name: string;
+            description: string;
+            handler: (args: string) => Promise<void> | void;
+        };
+        "command:unregister": {
+            name: string;
+        };
+        "command:execute": {
+            name: string;
+            args: string;
+        };
+    }
+}
+export {};

package/dist/extensions/slash-commands/events.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,15 @@
+/**
+ * Slash commands extension.
+ *
+ * Registers built-in slash commands on the event bus:
+ * - Listens for "command:register" to accept commands from extensions
+ * - Responds to "autocomplete:request" pipe for /-prefixed completions
+ * - Handles "command:execute" events and dispatches to matching handler
+ * - Uses "ui:info"/"ui:error" for user feedback (no direct TUI dependency)
+ *
+ * Argument completion is composable: any extension can onPipe("autocomplete:request")
+ * and check payload.command / payload.commandArgs to add completions for any command.
+ */
+import "./events.js";
+import type { ExtensionContext } from "../../shell/host-types.js";
+export default function activate(ctx: ExtensionContext): void;

package/dist/extensions/{slash-commands.js → slash-commands/index.js}

@@ -10,9 +10,10 @@
  * Argument completion is composable: any extension can onPipe("autocomplete:request")
  * and check payload.command / payload.commandArgs to add completions for any command.
  */
-import { palette as p } from "../utils/palette.js";
-import { discoverSkills, loadSkillContent } from "../agent/skills.js";
-import { reloadExtensions } from "../core/extension-loader.js";
+import "./events.js";
+import { palette as p } from "../../utils/palette.js";
+import { discoverSkills, loadSkillContent } from "../../agent/skills.js";
+import { reloadExtensions } from "../../core/extension-loader.js";
 export default function activate(ctx) {
     const { bus } = ctx;
     const commands = new Map();

package/dist/shell/events.d.ts

@@ -0,0 +1,85 @@
+/** Events owned by the shell subsystem. */
+declare module "../core/event-bus.js" {
+    interface BusEvents {
+        "shell:command-start": {
+            command: string;
+            cwd: string;
+        };
+        "shell:command-done": {
+            command: string;
+            output: string;
+            cwd: string;
+            exitCode: number | null;
+        };
+        "shell:cwd-change": {
+            cwd: string;
+        };
+        "shell:foreground-busy": {
+            busy: boolean;
+        };
+        "shell:agent-exec-start": Record<string, never>;
+        "shell:agent-exec-done": Record<string, never>;
+        "shell:pty-data": {
+            raw: string;
+        };
+        "shell:pty-write": {
+            data: string;
+        };
+        "shell:pty-resize": {
+            cols: number;
+            rows: number;
+        };
+        "shell:buffer-request": Record<string, never>;
+        "shell:buffer-snapshot": {
+            text: string;
+            altScreen: boolean;
+            cursor: {
+                x: number;
+                y: number;
+            };
+        };
+        "shell:stdout-hold": Record<string, never>;
+        "shell:stdout-release": Record<string, never>;
+        "shell:stdout-show": Record<string, never>;
+        "shell:stdout-hide": Record<string, never>;
+        /** Sync pipe: handled=true suppresses default redraw. */
+        "shell:redraw-prompt": {
+            cwd: string;
+            kind: "fresh" | "redraw";
+            handled: boolean;
+        };
+        /** Async pipe: extension → user's PTY. */
+        "shell:exec-request": {
+            command: string;
+            output: string;
+            cwd: string;
+            exitCode: number | null;
+            done: boolean;
+        };
+        "input-mode:register": import("./host-types.js").InputModeConfig;
+        "input:keypress": {
+            key: string;
+        };
+        "input:intercept": {
+            data: string;
+            consumed: boolean;
+        };
+        "compositor:write": {
+            stream: string;
+            text: string;
+        };
+        /** Sync pipe: extensions append items. */
+        "autocomplete:request": {
+            buffer: string;
+            /** "/backend" or null if not a command. */
+            command: string | null;
+            /** Text after the command name, or null. */
+            commandArgs: string | null;
+            items: {
+                name: string;
+                description: string;
+            }[];
+        };
+    }
+}
+export {};

package/dist/shell/events.js

@@ -0,0 +1 @@
+export {};

package/dist/shell/index.d.ts

@@ -3,6 +3,7 @@
  * built-in extensions manifest) because PTY + stdin raw mode ownership is
  * order-critical.
  */
+import "./events.js";
 import type { ExtensionContext } from "./host-types.js";
 export interface ShellActivateOptions {
     cols: number;

package/dist/shell/index.js

@@ -1,3 +1,9 @@
+/**
+ * Frontend bootstrap. Loaded directly from src/cli/index.ts (not the
+ * built-in extensions manifest) because PTY + stdin raw mode ownership is
+ * order-critical.
+ */
+import "./events.js"; // augments BusEvents with shell-owned events
 import { Shell } from "./shell.js";
 import { DefaultCompositor, StdoutSurface } from "../utils/compositor.js";
 import { TerminalBuffer } from "../utils/terminal-buffer.js";

package/dist/shell/tui-renderer.js

@@ -149,7 +149,6 @@ export default function activate(ctx) {
             titleRight: modelLabel,
         });
     });
-    // Track backend/model info for display on response border
     let backendInfo = null;
     bus.on("agent:info", (info) => { backendInfo = info; });
     // ── Register fenced block transform (code blocks → ContentBlock) ──

package/examples/extensions/ash-acp-bridge/src/index.ts

@@ -434,10 +434,10 @@ function waitForModelsToSettle(
       timer = setTimeout(done, Math.max(0, Math.min(quietMs, remaining)));
     };
     const done = () => {
-      core.bus.off("config:add-modes", arm);
+      core.bus.off("agent:modes-changed", arm);
       resolve();
     };
-    core.bus.on("config:add-modes", arm);
+    core.bus.on("agent:modes-changed", arm);
     arm();
   });
 }

package/examples/extensions/ashi/package.json

@@ -48,7 +48,7 @@
   },
   "dependencies": {
     "@earendil-works/pi-tui": "^0.74.0",
-    "agent-sh": "^0.13.3",
+    "agent-sh": "^0.14.0",
     "chalk": "^5.5.0",
     "cli-highlight": "^2.1.11"
   },

package/examples/extensions/ollama.ts

@@ -1,60 +1,65 @@
 /**
- * Ollama provider extension — local daemon or Ollama Cloud.
- *
- * Cloud auth (any of):
- *   agent-sh auth login ollama-cloud   # preferred
- *   OLLAMA_API_KEY=...                 # env fallback
- *
- * Local host:
- *   OLLAMA_HOST (default http://localhost:11434)
- *
- * Catalog comes from /api/tags; per-model context length is fetched
- * from /api/show (model_info["${arch}.context_length"]). Chat goes
- * through the OpenAI-compatible /v1/chat/completions shim.
- *
- * Usage:
- *   agent-sh -e ./examples/extensions/ollama.ts
- *
- *   # Or add to settings.json:
- *   { "extensions": ["./examples/extensions/ollama.ts"] }
+ * Registers `ollama` (local, no auth) and `ollama-cloud` (login via
+ * `agent-sh auth login ollama-cloud` or OLLAMA_API_KEY). Local host
+ * overridable via OLLAMA_HOST.
  */
 import { resolveApiKey } from "agent-sh/auth";
 import type { AgentContext } from "agent-sh/types";
 
 const ECHO_REASONING_PATTERNS: RegExp[] = [/deepseek/i];
 
+function reasoningParams(level: string): Record<string, unknown> {
+  if (level === "off") return { reasoning_effort: "none" };
+  return { reasoning_effort: level === "xhigh" ? "high" : level };
+}
+
 export default function activate(ctx: AgentContext): void {
   const cloudKey = resolveApiKey("ollama-cloud").key ?? process.env.OLLAMA_API_KEY;
-  const host = cloudKey
-    ? "https://ollama.com"
-    : (process.env.OLLAMA_HOST ?? "http://localhost:11434").replace(/\/$/, "");
-  const id = cloudKey ? "ollama-cloud" : "ollama";
-
-  // OpenAI SDK rejects an empty apiKey; the local daemon ignores the value.
-  const sdkKey = cloudKey || "no-key";
-  const baseURL = `${host}/v1`;
-  const headers: Record<string, string> = {};
-  if (cloudKey) headers.Authorization = `Bearer ${cloudKey}`;
-
-  ctx.agent.providers.configure(id, {
-    reasoningParams: (level) => {
-      if (level === "off") return { reasoning_effort: "none" };
-      return { reasoning_effort: level === "xhigh" ? "high" : level };
-    },
+  const cloudHost = "https://ollama.com";
+  const cloudBaseURL = `${cloudHost}/v1`;
+  ctx.agent.providers.configure("ollama-cloud", { reasoningParams });
+  ctx.agent.providers.register({
+    id: "ollama-cloud",
+    apiKey: cloudKey ?? undefined,
+    baseURL: cloudBaseURL,
+    models: [],
   });
+  if (cloudKey) {
+    const headers = { Authorization: `Bearer ${cloudKey}` };
+    fetchCatalog(cloudHost, headers).then((models) => {
+      if (models.length === 0) return;
+      ctx.agent.providers.register({
+        id: "ollama-cloud",
+        apiKey: cloudKey,
+        baseURL: cloudBaseURL,
+        defaultModel: models[0]!.id,
+        models,
+      });
+    }).catch(() => {});
+  }
 
-  ctx.bus.emit("provider:register", { id, apiKey: sdkKey, baseURL, models: [] });
-
-  fetchCatalog(host, headers).then((models) => {
+  const localHost = (process.env.OLLAMA_HOST ?? "http://localhost:11434").replace(/\/$/, "");
+  const localBaseURL = `${localHost}/v1`;
+  ctx.agent.providers.configure("ollama", { reasoningParams });
+  // OpenAI SDK rejects an empty apiKey; the local daemon ignores it.
+  ctx.agent.providers.register({
+    id: "ollama",
+    apiKey: "no-key",
+    baseURL: localBaseURL,
+    models: [],
+    noAuth: true,
+  });
+  fetchCatalog(localHost, {}).then((models) => {
     if (models.length === 0) return;
-    ctx.bus.emit("provider:register", {
-      id,
-      apiKey: sdkKey,
-      baseURL,
+    ctx.agent.providers.register({
+      id: "ollama",
+      apiKey: "no-key",
+      baseURL: localBaseURL,
       defaultModel: models[0]!.id,
       models,
+      noAuth: true,
     });
-  }).catch(() => { /* leave empty — user supplies via --model */ });
+  }).catch(() => {});
 }
 
 async function fetchCatalog(

package/examples/extensions/opencode-bridge/README.md

@@ -40,6 +40,10 @@ opencode reads its own config from `~/.local/share/opencode/` (auth credentials)
 - opencode authenticated locally — run `opencode auth login` once before using this bridge.
 - Provider env vars (e.g. `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`) as required by opencode for the model you've selected.
 
+## Environment
+
+- `OPENCODE_SDK_PORT` — port for the in-process opencode HTTP server. Defaults to `0` (OS-assigned free port) so a stale standalone opencode on the SDK's default port 4096 can't collide with the bridge. Set explicitly only if you need a deterministic port.
+
 ## What works under opencode
 
 agent-sh's per-query context producers (e.g. `<shell_events>` from `shell-context`) are inlined into opencode's prompt before each query, so opencode sees the user's recent shell activity even though the SDK doesn't subscribe to agent-sh's shell bus directly. The current cwd is part of that context, so opencode knows where the user is even when its tools are anchored elsewhere.

package/examples/extensions/opencode-bridge/index.ts

@@ -429,7 +429,9 @@ export default function activate(ctx: ExtensionContext): void {
     start: async () => {
       try {
         serverAbort = new AbortController();
-        runtime = await createOpencode({ signal: serverAbort.signal });
+        // port: 0 dodges collision with SDK default 4096 (override via OPENCODE_SDK_PORT).
+        const port = process.env.OPENCODE_SDK_PORT ? Number(process.env.OPENCODE_SDK_PORT) : 0;
+        runtime = await createOpencode({ signal: serverAbort.signal, port });
 
         streamAbort = new AbortController();
         // Subscribe before creating the session so we don't miss early events.

package/examples/extensions/pi-bridge/index.ts

@@ -272,14 +272,13 @@ export default function activate(ctx: ExtensionContext): void {
         }
       });
 
-      const model = session.model;
+      booting = false;
+      const m = session.model;
       bus.emit("agent:info", {
         name: "pi",
         version: "0.66",
-        model: model ? `${model.provider}/${model.id}` : undefined,
+        model: m ? `${m.provider}/${m.id}` : undefined,
       });
-
-      booting = false;
     } catch (err) {
       booting = false;
       bus.emit("ui:error", {

package/examples/extensions/zai-coding-plan.ts

@@ -25,14 +25,10 @@ function buildReasoningParams(level: string, _model?: string): Record<string, un
 
 export default function activate(ctx: AgentContext): void {
   const { key } = resolveApiKey(ID);
-  const apiKey = key ?? process.env.ZAI_API_KEY ?? process.env.ZHIPU_API_KEY;
-  if (!apiKey) return;
-
   ctx.agent.providers.configure(ID, { reasoningParams: buildReasoningParams });
-
-  ctx.bus.emit("provider:register", {
+  ctx.agent.providers.register({
     id: ID,
-    apiKey: apiKey,
+    apiKey: key ?? process.env.ZAI_API_KEY ?? process.env.ZHIPU_API_KEY,
     baseURL: BASE_URL,
     defaultModel: DEFAULT_MODELS[0].id,
     models: DEFAULT_MODELS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sh",
-  "version": "0.13.6",
+  "version": "0.14.0",
   "description": "A shell-first terminal where AI is one keystroke away",
   "type": "module",
   "main": "dist/core/index.js",
@@ -121,6 +121,7 @@
     "dev": "tsx src/cli/index.ts",
     "build": "tsc",
     "start": "node dist/cli/index.js",
+    "test": "npm run build && node --import tsx --test $(find tests -name '*.test.ts' -type f)",
     "prepare": "test -d dist || npm run build"
   },
   "keywords": [

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

@@ -1,2 +0,0 @@
-import type { ExtensionContext } from "../shell/host-types.js";
-export default function activate(ctx: ExtensionContext): void;

package/dist/utils/llm-facade.d.ts

@@ -1,11 +0,0 @@
-/**
- * ctx.llm facade — delegates to an `llm:invoke` handler registered by the
- * active backend. No handler → `available` is false and calls reject.
- */
-import type { LlmInterface } from "../agent/host-types.js";
-interface HandlerGate {
-    list: () => string[];
-    call: (name: string, ...args: unknown[]) => unknown;
-}
-export declare function createLlmFacade(handlers: HandlerGate): LlmInterface;
-export {};