agent-sh 0.8.0 → 0.10.0

package/dist/event-bus.d.ts

@@ -89,6 +89,28 @@ export interface ShellEvents {
             }>;
         }>;
     };
+    "agent:tool-batch-complete": {
+        results: Array<{
+            name: string;
+            isError: boolean;
+            errorSummary?: string;
+        }>;
+    };
+    "conversation:message-appended": {
+        role: "user" | "assistant" | "tool" | "system";
+        content: string;
+        /** For role="tool": name of the tool whose result this is. */
+        toolName?: string;
+        /** For role="tool": parsed arguments passed to the tool. */
+        toolArgs?: Record<string, unknown>;
+        /** For role="tool": whether the tool errored. */
+        isError?: boolean;
+    };
+    "conversation:after-compact": {
+        beforeTokens: number;
+        afterTokens: number;
+        evictedCount: number;
+    };
     "agent:tool-started": {
         title: string;
         toolCallId?: string;
@@ -115,10 +137,24 @@ export interface ShellEvents {
     "agent:tool-output-chunk": {
         chunk: string;
     };
+    "agent:subagent-started": {
+        taskId: string;
+        task: string;
+    };
+    "agent:subagent-completed": {
+        taskId: string;
+        task: string;
+        result: string;
+        isError: boolean;
+    };
+    "tool:interactive-start": Record<string, never>;
+    "tool:interactive-end": Record<string, never>;
     "permission:request": {
         kind: string;
         title: string;
         metadata: Record<string, unknown>;
+        /** Interactive UI capability — available when the built-in agent is active. */
+        ui?: unknown;
         decision: Record<string, unknown>;
     };
     "command:register": {
@@ -126,6 +162,9 @@ export interface ShellEvents {
         description: string;
         handler: (args: string) => Promise<void> | void;
     };
+    "command:unregister": {
+        name: string;
+    };
     "command:execute": {
         name: string;
         args: string;
@@ -139,6 +178,10 @@ export interface ShellEvents {
     "ui:suggestion": {
         text: string;
     };
+    "compositor:write": {
+        stream: string;
+        text: string;
+    };
     "input:keypress": {
         key: string;
     };
@@ -178,8 +221,7 @@ export interface ShellEvents {
     "agent:compact-request": Record<string, never>;
     "context:get-stats": {
         activeTokens: number;
-        nuclearEntries: number;
-        recallArchiveSize: number;
+        totalTokens: number;
         budgetTokens: number;
     };
     "agent:register-backend": {
@@ -218,12 +260,18 @@ export interface ShellEvents {
     "config:switch-provider": {
         provider: string;
     };
+    "config:get-initial-modes": {
+        modes: AgentMode[];
+        initialModeIndex: number;
+    };
     "config:set-modes": {
         modes: AgentMode[];
+        activeIndex?: number;
     };
     "config:add-modes": {
         modes: AgentMode[];
     };
+    "core:extensions-loaded": Record<string, never>;
     "provider:register": {
         id: string;
         apiKey?: string;
@@ -237,6 +285,39 @@ export interface ShellEvents {
         /** Provider supports the reasoning_effort parameter. Default: true. */
         supportsReasoningEffort?: boolean;
     };
+    "agent:register-tool": {
+        tool: import("./agent/types.js").ToolDefinition;
+        extensionName?: string;
+    };
+    "agent:unregister-tool": {
+        name: string;
+    };
+    "agent:get-tools": {
+        tools: import("./agent/types.js").ToolDefinition[];
+    };
+    "agent:register-instruction": {
+        name: string;
+        text: string;
+        extensionName: string;
+    };
+    "agent:remove-instruction": {
+        name: string;
+    };
+    "agent:register-skill": {
+        name: string;
+        description: string;
+        filePath: string;
+        extensionName: string;
+    };
+    "agent:remove-skill": {
+        name: string;
+    };
+    "banner:collect": {
+        sections: Array<{
+            label: string;
+            items: string[];
+        }>;
+    };
     "autocomplete:request": {
         buffer: string;
         /** Parsed slash command name (e.g. "/backend"), or null if not a command. */
@@ -291,6 +372,8 @@ export declare class EventBus {
     emitTransform<K extends keyof ShellEvents>(event: K, payload: ShellEvents[K]): void;
     /** Register a transform listener for a pipeline event. */
     onPipe<K extends keyof ShellEvents>(event: K, fn: PipeListener<ShellEvents[K]>): void;
+    /** Remove a transform listener from a pipeline event. */
+    offPipe<K extends keyof ShellEvents>(event: K, fn: PipeListener<ShellEvents[K]>): void;
     /**
      * Emit a pipeline event — each registered pipe listener receives the
      * output of the previous one. Returns the final transformed payload.

package/dist/event-bus.js

@@ -49,6 +49,15 @@ export class EventBus {
         }
         listeners.push(fn);
     }
+    /** Remove a transform listener from a pipeline event. */
+    offPipe(event, fn) {
+        const listeners = this.pipeListeners.get(event);
+        if (!listeners)
+            return;
+        const idx = listeners.indexOf(fn);
+        if (idx !== -1)
+            listeners.splice(idx, 1);
+    }
     /**
      * Emit a pipeline event — each registered pipe listener receives the
      * output of the previous one. Returns the final transformed payload.
@@ -60,7 +69,17 @@ export class EventBus {
             return payload;
         let result = payload;
         for (const fn of listeners) {
-            result = fn(result);
+            try {
+                const out = fn(result);
+                if (out && typeof out.then === "function") {
+                    console.error(`[event-bus] Warning: async handler in sync pipe "${String(event)}" — use onPipeAsync instead`);
+                    continue;
+                }
+                result = out;
+            }
+            catch (err) {
+                console.error(`[event-bus] Pipe handler error in "${String(event)}":`, err instanceof Error ? err.message : err);
+            }
         }
         return result;
     }

package/dist/executor.d.ts

@@ -25,7 +25,8 @@ export declare function executeCommand(opts: {
     done: Promise<void>;
 };
 /**
- * Kill a running session's process group.
- * Sends SIGTERM first, then SIGKILL after 5 seconds.
+ * Kill a running session's process group: SIGTERM, then SIGKILL after 5s.
+ * Returns a cleanup that cancels the pending SIGKILL — callers should invoke
+ * it once the process has exited.
  */
-export declare function killSession(session: ExecutorSession): void;
+export declare function killSession(session: ExecutorSession): () => void;

package/dist/executor.js

@@ -60,14 +60,15 @@ export function executeCommand(opts) {
     };
     child.stdout?.on("data", handleData);
     child.stderr?.on("data", handleData);
-    // Timeout handler
+    let cancelKill;
     const timer = setTimeout(() => {
         if (!session.done) {
-            killSession(session);
+            cancelKill = killSession(session);
         }
     }, timeout);
     child.on("exit", (code, signal) => {
         clearTimeout(timer);
+        cancelKill?.();
         session.exitCode = code ?? (signal ? -1 : null);
         session.done = true;
         session.process = null;
@@ -75,6 +76,7 @@ export function executeCommand(opts) {
     });
     child.on("error", (err) => {
         clearTimeout(timer);
+        cancelKill?.();
         if (!session.done) {
             session.exitCode = -1;
             session.output += `\nProcess error: ${err.message}`;
@@ -86,31 +88,32 @@ export function executeCommand(opts) {
     return { session, done };
 }
 /**
- * Kill a running session's process group.
- * Sends SIGTERM first, then SIGKILL after 5 seconds.
+ * Kill a running session's process group: SIGTERM, then SIGKILL after 5s.
+ * Returns a cleanup that cancels the pending SIGKILL — callers should invoke
+ * it once the process has exited.
  */
 export function killSession(session) {
     const proc = session.process;
     if (!proc || !proc.pid)
-        return;
+        return () => { };
     try {
-        // Kill the entire process group
         process.kill(-proc.pid, "SIGTERM");
     }
-    catch {
-        // Process may already be dead
-    }
-    // Fallback: SIGKILL after 5 seconds
+    catch { }
+    let settled = false;
     const fallback = setTimeout(() => {
-        if (!session.done && proc.pid) {
+        if (!settled && !session.done && proc.pid) {
             try {
                 process.kill(-proc.pid, "SIGKILL");
             }
-            catch {
-                // Ignore
-            }
+            catch { }
         }
     }, 5000);
-    // Don't let the timer keep the process alive
     fallback.unref();
+    return () => {
+        if (!settled) {
+            settled = true;
+            clearTimeout(fallback);
+        }
+    };
 }

package/dist/extension-loader.d.ts

@@ -14,3 +14,8 @@ import type { ExtensionContext } from "./types.js";
  * Errors are non-fatal — logged via ui:error and skipped.
  */
 export declare function loadExtensions(ctx: ExtensionContext, cliExtensions?: string[]): Promise<string[]>;
+/**
+ * Reload user extensions (from ~/.agent-sh/extensions/).
+ * Tears down old registrations, busts the module cache, and re-activates.
+ */
+export declare function reloadExtensions(ctx: ExtensionContext): Promise<string[]>;

package/dist/extension-loader.js

@@ -17,6 +17,78 @@ async function ensureTsSupport() {
         // tsx not available — TS extensions will fail with a clear error
     }
 }
+/**
+ * Wrap an ExtensionContext to track all registrations (bus.on, bus.onPipe,
+ * advise, command:register). Returns the wrapped context and a dispose()
+ * function that tears down everything registered through it.
+ */
+function createScopedContext(ctx, extensionName) {
+    const cleanups = [];
+    const bus = ctx.bus;
+    const scopedBus = Object.create(bus);
+    // Track bus.on registrations
+    scopedBus.on = ((event, fn) => {
+        bus.on(event, fn);
+        cleanups.push(() => bus.off(event, fn));
+    });
+    // Track bus.onPipe registrations
+    scopedBus.onPipe = ((event, fn) => {
+        bus.onPipe(event, fn);
+        cleanups.push(() => bus.offPipe(event, fn));
+    });
+    // Track advise registrations
+    const scopedAdvise = (name, wrapper) => {
+        const unadvise = ctx.advise(name, wrapper);
+        cleanups.push(unadvise);
+        return unadvise;
+    };
+    // Track instruction registrations — extension name captured in scope
+    const scopedRegisterInstruction = (name, text) => {
+        bus.emit("agent:register-instruction", { name, text, extensionName });
+        cleanups.push(() => bus.emit("agent:remove-instruction", { name }));
+    };
+    // Track skill registrations — extension name captured in scope
+    const scopedRegisterSkill = (name, description, filePath) => {
+        bus.emit("agent:register-skill", { name, description, filePath, extensionName });
+        cleanups.push(() => bus.emit("agent:remove-skill", { name }));
+    };
+    // Track tool registrations — extension name captured in scope
+    const scopedRegisterTool = (tool) => {
+        bus.emit("agent:register-tool", { tool, extensionName });
+        cleanups.push(() => bus.emit("agent:unregister-tool", { name: tool.name }));
+    };
+    // Track slash command registrations — without this, reloading an
+    // extension stacks its commands (old `/status` + new `/status`) in
+    // the slash-commands registry.
+    const scopedRegisterCommand = (name, description, handler) => {
+        ctx.registerCommand(name, description, handler);
+        cleanups.push(() => bus.emit("command:unregister", { name }));
+    };
+    const scoped = {
+        ...ctx,
+        bus: scopedBus,
+        advise: scopedAdvise,
+        registerInstruction: scopedRegisterInstruction,
+        removeInstruction: ctx.removeInstruction,
+        registerSkill: scopedRegisterSkill,
+        removeSkill: ctx.removeSkill,
+        registerTool: scopedRegisterTool,
+        unregisterTool: ctx.unregisterTool,
+        registerCommand: scopedRegisterCommand,
+    };
+    const dispose = () => {
+        for (const fn of cleanups) {
+            try {
+                fn();
+            }
+            catch { /* ignore */ }
+        }
+        cleanups.length = 0;
+    };
+    return { scoped, dispose };
+}
+// Track disposers for user extensions so reload can tear them down
+const extensionDisposers = new Map();
 /**
  * Load extensions from three sources (merged, deduplicated):
  *
@@ -43,19 +115,39 @@ export async function loadExtensions(ctx, cliExtensions) {
         specifiers.push(...settings.extensions);
     }
     // 3. ~/.agent-sh/extensions/ directory
+    const userSpecifiers = await discoverUserExtensions();
+    specifiers.push(...userSpecifiers);
+    // Deduplicate
+    const seen = new Set();
+    const unique = specifiers.filter((s) => {
+        if (seen.has(s))
+            return false;
+        seen.add(s);
+        return true;
+    });
+    // Load each extension (user extensions get scoped contexts for reloadability)
+    const loaded = await loadSpecifiers(unique, ctx, false, userSpecifiers);
+    return loaded;
+}
+async function discoverUserExtensions() {
+    const specifiers = [];
+    const disabled = new Set(getSettings().disabledExtensions ?? []);
     try {
         const entries = await fs.readdir(EXT_DIR, { withFileTypes: true });
         for (const entry of entries) {
+            // Disable check: directory name for dir-extensions, or basename sans
+            // extension for file-extensions. Lets settings.json turn one off
+            // without renaming it.
+            const nameForDisable = entry.name.replace(/\.[^.]+$/, "");
+            if (disabled.has(nameForDisable))
+                continue;
             const fullPath = path.join(EXT_DIR, entry.name);
-            // 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) {
+                if (indexFile)
                     specifiers.push(indexFile);
-                }
             }
             else if (SCRIPT_EXTS.some((ext) => entry.name.endsWith(ext))) {
                 specifiers.push(fullPath);
@@ -65,22 +157,22 @@ export async function loadExtensions(ctx, cliExtensions) {
     catch {
         // Directory doesn't exist — no user extensions
     }
-    // Deduplicate
-    const seen = new Set();
-    const unique = specifiers.filter((s) => {
-        if (seen.has(s))
-            return false;
-        seen.add(s);
-        return true;
-    });
-    // Load each extension
+    return specifiers;
+}
+async function loadSpecifiers(specifiers, ctx, bustCache, userSpecifiers) {
+    const userSet = new Set(userSpecifiers ?? []);
     const loaded = [];
-    for (const specifier of unique) {
+    for (const specifier of specifiers) {
         try {
-            const importPath = await resolveSpecifier(specifier);
+            let importPath = await resolveSpecifier(specifier);
             if (TS_EXTS.some((ext) => importPath.endsWith(ext))) {
                 await ensureTsSupport();
             }
+            // Append timestamp query to bust Node's module cache on reload
+            if (bustCache) {
+                const sep = importPath.includes("?") ? "&" : "?";
+                importPath += `${sep}t=${Date.now()}`;
+            }
             const mod = await import(importPath);
             // tsx may double-wrap default exports: mod.default.default
             const activate = typeof mod.default === "function"
@@ -89,10 +181,25 @@ export async function loadExtensions(ctx, cliExtensions) {
                     ? mod.default.default
                     : 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;
+                // Scoped context so /reload can tear user extensions down.
+                // Awaiting activate() lets extensions with async setup (e.g.
+                // openrouter fetching its model catalog) finish before we move
+                // on; a 10s outer timeout in index.ts guards against hangs.
+                if (userSet.has(specifier)) {
+                    // Dispose previous load if reloading
+                    extensionDisposers.get(name)?.();
+                    const { scoped, dispose } = createScopedContext(ctx, name);
+                    await activate(scoped);
+                    extensionDisposers.set(name, dispose);
+                }
+                else {
+                    const { scoped, dispose } = createScopedContext(ctx, name);
+                    await activate(scoped);
+                    // Non-user extensions aren't reloadable, but track for cleanup on shutdown
+                    extensionDisposers.set(name, dispose);
+                }
                 loaded.push(name);
             }
         }
@@ -104,6 +211,14 @@ export async function loadExtensions(ctx, cliExtensions) {
     }
     return loaded;
 }
+/**
+ * Reload user extensions (from ~/.agent-sh/extensions/).
+ * Tears down old registrations, busts the module cache, and re-activates.
+ */
+export async function reloadExtensions(ctx) {
+    const specifiers = await discoverUserExtensions();
+    return loadSpecifiers(specifiers, ctx, true, specifiers);
+}
 /**
  * Find an index file in a directory extension.
  */
@@ -136,8 +251,17 @@ async function resolveSpecifier(specifier) {
         resolved = specifier;
     }
     else {
-        // Bare specifier — npm package
-        return specifier;
+        // Distinguish bare npm specifier from a relative path lacking "./".
+        // Scoped packages ("@scope/pkg") contain "/" but are npm specifiers,
+        // so the "@" prefix takes precedence over the "/" heuristic.
+        if (specifier.includes("/") && !specifier.startsWith("@")) {
+            // Treat as relative path from cwd
+            resolved = path.resolve(process.cwd(), specifier);
+        }
+        else {
+            // Bare specifier — npm package (including @scope/pkg)
+            return specifier;
+        }
     }
     // If it's a directory, find the index file
     try {

package/dist/extensions/agent-backend.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Built-in agent backend extension.
+ *
+ * Constructs the AgentLoop synchronously with a placeholder LlmClient,
+ * so core handlers (history:append, system-prompt:build, conversation:*)
+ * are defined before user extensions activate. Mode resolution is
+ * deferred to `core:extensions-loaded`, giving runtime-registered
+ * providers (e.g. openrouter) a chance to register before we look up
+ * settings.defaultProvider. Without this deferral, a persisted
+ * `defaultProvider: "openrouter"` loses to a cold-start race and the
+ * backend bails silently.
+ */
+import type { ExtensionContext } from "../types.js";
+export default function agentBackend(ctx: ExtensionContext): void;