agent-sh 0.9.0 → 0.10.0

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;

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.js

@@ -24,7 +24,11 @@ import * as settingsMod from "./settings.js";
 import { HandlerRegistry } from "./utils/handler-registry.js";
 import { TerminalBuffer } from "./utils/terminal-buffer.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";
@@ -34,7 +38,10 @@ export function createCore(config) {
     const bus = new EventBus();
     const handlers = new HandlerRegistry();
     const contextManager = new ContextManager(bus, handlers);
-    const instanceId = crypto.randomBytes(2).toString("hex");
+    // 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();
     // Expose raw CLI config so the agent backend extension can resolve
     // providers and create the LLM client.
@@ -63,7 +70,12 @@ 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 = [...backends.keys()];
@@ -77,7 +89,7 @@ export function createCore(config) {
         return { names, active: activeBackendName };
     });
     // ── Compositor ──────────────────────────────────────────────
-    const compositor = new DefaultCompositor();
+    const compositor = new DefaultCompositor(bus);
     const stdoutSurface = new StdoutSurface();
     compositor.setDefault("agent", stdoutSurface);
     compositor.setDefault("query", stdoutSurface);
@@ -145,7 +157,7 @@ export function createCore(config) {
             bus.emit("agent:cancel-request", {});
         },
         extensionContext(opts) {
-            return {
+            const ctx = {
                 bus,
                 contextManager,
                 instanceId,
@@ -154,15 +166,23 @@ export function createCore(config) {
                 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) => bus.emit("agent:register-tool", { tool }),
+                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 }),
+                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(); },
                 compositor,
                 createRemoteSession: (opts) => {
@@ -207,6 +227,7 @@ export function createCore(config) {
                     };
                 },
             };
+            return ctx;
         },
         kill() {
             if (activeBackendName) {

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,6 +137,16 @@ 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": {
@@ -130,6 +162,9 @@ export interface ShellEvents {
         description: string;
         handler: (args: string) => Promise<void> | void;
     };
+    "command:unregister": {
+        name: string;
+    };
     "command:execute": {
         name: string;
         args: string;
@@ -143,6 +178,10 @@ export interface ShellEvents {
     "ui:suggestion": {
         text: string;
     };
+    "compositor:write": {
+        stream: string;
+        text: string;
+    };
     "input:keypress": {
         key: string;
     };
@@ -182,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": {
@@ -228,10 +266,12 @@ export interface ShellEvents {
     };
     "config:set-modes": {
         modes: AgentMode[];
+        activeIndex?: number;
     };
     "config:add-modes": {
         modes: AgentMode[];
     };
+    "core:extensions-loaded": Record<string, never>;
     "provider:register": {
         id: string;
         apiKey?: string;
@@ -247,6 +287,7 @@ export interface ShellEvents {
     };
     "agent:register-tool": {
         tool: import("./agent/types.js").ToolDefinition;
+        extensionName?: string;
     };
     "agent:unregister-tool": {
         name: string;
@@ -257,10 +298,26 @@ export interface ShellEvents {
     "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. */

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.js

@@ -22,7 +22,7 @@ async function ensureTsSupport() {
  * advise, command:register). Returns the wrapped context and a dispose()
  * function that tears down everything registered through it.
  */
-function createScopedContext(ctx) {
+function createScopedContext(ctx, extensionName) {
     const cleanups = [];
     const bus = ctx.bus;
     const scopedBus = Object.create(bus);
@@ -42,15 +42,27 @@ function createScopedContext(ctx) {
         cleanups.push(unadvise);
         return unadvise;
     };
-    // Track instruction registrations
+    // Track instruction registrations — extension name captured in scope
     const scopedRegisterInstruction = (name, text) => {
-        ctx.registerInstruction(name, text);
-        cleanups.push(() => ctx.removeInstruction(name));
+        bus.emit("agent:register-instruction", { name, text, extensionName });
+        cleanups.push(() => bus.emit("agent:remove-instruction", { name }));
     };
-    // Track tool registrations
+    // 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) => {
-        ctx.registerTool(tool);
-        cleanups.push(() => ctx.unregisterTool(tool.name));
+        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,
@@ -58,8 +70,11 @@ function createScopedContext(ctx) {
         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) {
@@ -116,9 +131,16 @@ export async function loadExtensions(ctx, cliExtensions) {
 }
 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);
             const isDir = entry.isDirectory() ||
                 (entry.isSymbolicLink() && (await fs.stat(fullPath)).isDirectory());
@@ -161,16 +183,22 @@ async function loadSpecifiers(specifiers, ctx, bustCache, userSpecifiers) {
             if (typeof activate === "function") {
                 const base = path.basename(specifier).replace(/\.(ts|js|mjs|mts|tsx)$/, "");
                 const name = base === "index" ? path.basename(path.dirname(specifier)) : base;
-                // User extensions get a scoped context so /reload can tear them down
+                // 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);
-                    activate(scoped);
+                    const { scoped, dispose } = createScopedContext(ctx, name);
+                    await activate(scoped);
                     extensionDisposers.set(name, dispose);
                 }
                 else {
-                    activate(ctx);
+                    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);
             }
@@ -223,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

@@ -1,13 +1,14 @@
 /**
  * Built-in agent backend extension.
  *
- * Owns the full LLM lifecycle:
- *   1. Resolves providers from settings + CLI config
- *   2. Creates and manages the LlmClient
- *   3. Builds mode list for model cycling
- *   4. Creates AgentLoop and registers it as the "ash" backend
- *   5. Handles runtime provider switching and provider registration
- *   6. Exposes llm:get-client handler for other extensions (e.g. command-suggest)
+ * 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;