agent-sh 0.9.0 → 0.10.0

package/examples/extensions/subagents.ts

@@ -8,8 +8,8 @@
  * Usage:
  *   agent-sh -e ./examples/extensions/subagents.ts
  */
-import type { ExtensionContext } from "../../src/types.js";
-import { runSubagent } from "../../src/agent/subagent.js";
+import type { ExtensionContext } from "agent-sh/types";
+import { runSubagent } from "agent-sh/agent/subagent";
 
 export default function activate(ctx: ExtensionContext): void {
   const { bus, llmClient, contextManager } = ctx;
@@ -17,6 +17,12 @@ export default function activate(ctx: ExtensionContext): void {
 
   const allToolNames = () => ctx.getTools().map(t => t.name);
 
+  ctx.registerInstruction("subagent-guide", [
+    "You have a spawn_agent tool for delegating work to a subagent with its own context.",
+    "The subagent inherits your session history, so write a short directive (what to do), not a briefing (what happened).",
+    "Use it for tasks that need multiple tool calls you don't need to see — research, exploration, independent implementation.",
+  ].join("\n"));
+
   ctx.registerTool({
     name: "spawn_agent",
     description:
@@ -44,8 +50,15 @@ export default function activate(ctx: ExtensionContext): void {
 
     getDisplayInfo: () => ({
       kind: "execute",
+      icon: "⤵",
     }),
 
+    formatCall: (args) => {
+      const task = String(args.task ?? "");
+      const max = 80;
+      return task.length > max ? task.slice(0, max - 1) + "…" : task;
+    },
+
     async execute(args) {
       const task = args.task as string;
       const toolNames = args.tools as string[] | undefined;
@@ -56,9 +69,12 @@ export default function activate(ctx: ExtensionContext): void {
         ? allTools.filter(t => toolNames.includes(t.name))
         : allTools.filter(t => t.name !== "spawn_agent");
 
+      const nuclearSummary = bus.emitPipe("agent:get-nuclear-summary", { summary: null }).summary;
+
       const systemPrompt =
         `You are a focused subagent. Complete the task and return a clear, concise result.\n` +
-        `Working directory: ${contextManager.getCwd()}`;
+        `Working directory: ${contextManager.getCwd()}` +
+        (nuclearSummary ? `\n\n[Parent session history]\n${nuclearSummary}` : "");
 
       try {
         const result = await runSubagent({
@@ -66,7 +82,6 @@ export default function activate(ctx: ExtensionContext): void {
           tools,
           systemPrompt,
           task,
-          bus,
           maxIterations: 25,
         });
 

package/examples/extensions/terminal-buffer.ts

@@ -0,0 +1,163 @@
+/**
+ * Terminal buffer extension.
+ *
+ * Registers two agent tools:
+ *   - terminal_read: get the current screen contents + cursor position
+ *   - terminal_keys: send raw keystrokes into the user's live PTY
+ *
+ * Together these let the agent operate inside interactive programs
+ * (vim, htop, less, etc.) by reading the screen and typing keys.
+ *
+ * Requires xterm in the extension directory:
+ *   npm install @xterm/headless@5.5.0 @xterm/addon-serialize@0.13.0
+ *
+ * Core already loads xterm lazily (for floating-panel compositing), so
+ * installing these deps anywhere on the NODE_PATH is enough.
+ */
+import type { ExtensionContext } from "agent-sh/types";
+
+/** Interpret C-style escape sequences (e.g. \r → CR, \x1b → ESC). */
+function interpretEscapes(str: string): string {
+  return str.replace(/\\(x[0-9a-fA-F]{2}|r|n|t|\\|0)/g, (_, seq: string) => {
+    if (seq === "r") return "\r";
+    if (seq === "n") return "\n";
+    if (seq === "t") return "\t";
+    if (seq === "\\") return "\\";
+    if (seq === "0") return "\0";
+    if (seq.startsWith("x")) return String.fromCharCode(parseInt(seq.slice(1), 16));
+    return seq;
+  });
+}
+
+function settle(ms = 100): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export default function activate(ctx: ExtensionContext): void {
+  const { bus, terminalBuffer: tb, registerTool, registerInstruction } = ctx;
+  if (!tb) return; // @xterm/headless not installed
+
+  registerTool({
+    name: "terminal_read",
+    description:
+      "Read what is currently visible on the user's terminal screen. Returns clean text (ANSI stripped) " +
+      "with cursor position and whether an alternate-screen program (vim, htop, less) is active. " +
+      "Use this to observe what the user sees — helpful for answering questions about terminal output, " +
+      "diagnosing errors on screen, or checking state before/after sending keystrokes with terminal_keys.",
+    input_schema: {
+      type: "object",
+      properties: {
+        include_scrollback: {
+          type: "boolean",
+          description:
+            "If true, include scrollback buffer (content that scrolled off screen) " +
+            "in addition to the visible viewport. Useful for capturing output from " +
+            "long-running or streaming commands. Default: false.",
+        },
+      },
+    },
+    showOutput: true,
+
+    getDisplayInfo: () => ({
+      kind: "read" as const,
+      icon: "⊞",
+      locations: [],
+    }),
+
+    async execute(args) {
+      const includeScrollback = (args.include_scrollback as boolean) ?? false;
+      const { text, altScreen, cursorX, cursorY } = tb.readScreen({ includeScrollback });
+      const info = [
+        altScreen ? "mode: alternate screen" : "mode: normal",
+        `cursor: row=${cursorY} col=${cursorX}`,
+      ].join(", ");
+
+      return {
+        content: `[${info}]\n\n${text}`,
+        exitCode: 0,
+        isError: false,
+      };
+    },
+  });
+
+  registerTool({
+    name: "terminal_keys",
+    description:
+      "Send keystrokes directly into the user's live terminal PTY, as if the user typed them. " +
+      "Use this to interact with programs already running in the terminal (vim, htop, less, ssh, REPLs, etc.) " +
+      "or to type commands at the shell prompt. This types directly into whatever is currently on screen.\n\n" +
+      "Escape sequences for special keys:\n" +
+      "  - Escape: \\x1b\n" +
+      "  - Enter/Return: \\r\n" +
+      "  - Tab: \\t\n" +
+      "  - Ctrl+C: \\x03\n" +
+      "  - Ctrl+D: \\x04\n" +
+      "  - Ctrl+Z: \\x1a\n" +
+      "  - Arrow keys: \\x1b[A (up), \\x1b[B (down), \\x1b[C (right), \\x1b[D (left)\n" +
+      "  - Backspace: \\x7f\n\n" +
+      "Example: to quit vim without saving, send keys=\"\\x1b:q!\\r\" (Escape, :q!, Enter).\n" +
+      "Always call terminal_read after sending keys to verify the result.",
+    input_schema: {
+      type: "object",
+      properties: {
+        keys: {
+          type: "string",
+          description:
+            "The keystrokes to send. Use \\x1b for Escape, \\r for Enter, \\t for Tab, " +
+            "\\x03 for Ctrl+C, etc. Regular characters are sent as-is.",
+        },
+        settle_ms: {
+          type: "number",
+          description:
+            "Milliseconds to wait after sending keys for the terminal to settle before " +
+            "returning (default: 150). Increase for slow programs.",
+        },
+      },
+      required: ["keys"],
+    },
+    showOutput: false,
+
+    getDisplayInfo: () => ({
+      kind: "execute" as const,
+      icon: "⌨",
+      locations: [],
+    }),
+
+    formatCall: (args) => {
+      const keys = args.keys as string;
+      return keys
+        .replace(/\\x1b|\x1b/g, "ESC")
+        .replace(/\\r|\r/g, "⏎")
+        .replace(/\\n|\n/g, "↵")
+        .replace(/\\t|\t/g, "TAB")
+        .replace(/\\x03|\x03/g, "^C")
+        .replace(/\\x04|\x04/g, "^D")
+        .replace(/\\x7f|\x7f/g, "BS");
+    },
+
+    async execute(args) {
+      const raw = args.keys as string;
+      const keys = interpretEscapes(raw);
+      const settleMs = (args.settle_ms as number) ?? 150;
+
+      bus.emit("shell:stdout-show", {});
+      process.stdout.write("\n");
+      bus.emit("shell:pty-write", { data: keys });
+
+      await settle(settleMs);
+      bus.emit("shell:stdout-hide", {});
+
+      const { text, altScreen, cursorX, cursorY } = tb.readScreen();
+      const info = [
+        altScreen ? "mode: alternate screen" : "mode: normal",
+        `cursor: row=${cursorY} col=${cursorX}`,
+      ].join(", ");
+
+      return {
+        content: `Keys sent. Screen after:\n[${info}]\n\n${text}`,
+        exitCode: 0,
+        isError: false,
+      };
+    },
+  });
+}

package/examples/extensions/user-shell.ts

@@ -0,0 +1,136 @@
+/**
+ * User shell extension.
+ *
+ * Registers the user_shell tool, which runs commands in the user's live PTY
+ * shell — affecting real shell state (cd, export, source). Also registers
+ * system prompt guidance so the agent knows when to use it.
+ *
+ * Without this extension, the agent only has the isolated bash tool.
+ *
+ * Usage:
+ *   agent-sh -e ./examples/extensions/user-shell.ts
+ *
+ *   # Or copy to ~/.agent-sh/extensions/ for permanent use:
+ *   cp examples/extensions/user-shell.ts ~/.agent-sh/extensions/
+ */
+import type { ExtensionContext } from "agent-sh/types";
+import type { ToolDefinition } from "agent-sh/agent/types";
+
+export default function activate(ctx: ExtensionContext): void {
+  const { bus, registerTool, registerInstruction } = ctx;
+  const getCwd = () => ctx.contextManager.getCwd();
+
+  // ── Tool ───────────────────────────────────────────────────────
+
+  registerTool(createUserShellTool({ getCwd, bus }));
+
+  // ── System prompt guidance ─────────────────────────────────────
+
+  registerInstruction("user-shell-guide", `# user_shell Tool Guide
+
+You have access to user_shell, which runs commands in the user's live shell (PTY).
+- user_shell affects real shell state (cd, export, source).
+- The user sees output directly — do not repeat or summarize it.
+- Use it for: cd, export, source, installing packages, starting servers, git commands.
+- Set return_output=true only if you need to inspect the result.
+- When the user asks to see, list, view, or display anything, use user_shell.
+  Internal tools (bash, read, ls, etc.) run in an isolated subprocess — the user cannot see their output.
+- Only use internal tools when you need to reason about content silently.`);
+}
+
+function createUserShellTool(opts: {
+  getCwd: () => string;
+  bus: ExtensionContext["bus"];
+}): ToolDefinition {
+  return {
+    name: "user_shell",
+    description:
+      "Run a complete, non-interactive command in the user's live shell (cd, export, install packages, start servers, git commands). " +
+      "Use this for commands that have side effects or that the user wants to see. Output is shown directly to the user but NOT returned " +
+      "to you by default — set return_output=true if you need to inspect the result. " +
+      "Do NOT use this to interact with programs that are already running in the terminal — use terminal_keys/terminal_read instead.",
+    input_schema: {
+      type: "object",
+      properties: {
+        command: {
+          type: "string",
+          description: "Command to execute in user's shell",
+        },
+        timeout: {
+          type: "number",
+          description: "Timeout in seconds (default: 30)",
+        },
+        return_output: {
+          type: "boolean",
+          default: false,
+          description:
+            "Whether to return the command output to you. Default false — output is shown directly to the user. Set true only if you need to inspect the result to answer a question.",
+        },
+      },
+      required: ["command"],
+    },
+
+    showOutput: false,
+    modifiesFiles: true,
+
+    getDisplayInfo: () => ({
+      kind: "execute",
+      icon: "▷",
+      locations: [],
+    }),
+
+    async execute(args) {
+      const command = args.command as string;
+      const timeoutSec = (args.timeout as number) ?? 30;
+      const returnOutput = (args.return_output as boolean) ?? false;
+
+      // Execute via the shell-exec extension's async pipe with timeout
+      let result: { output: string; exitCode: number | null; [k: string]: unknown };
+      try {
+        const execPromise = opts.bus.emitPipeAsync(
+          "shell:exec-request",
+          {
+            command,
+            output: "",
+            cwd: opts.getCwd(),
+            exitCode: null as number | null,
+            done: false,
+          },
+        );
+        const timeoutPromise = new Promise<never>((_, reject) =>
+          setTimeout(() => reject(new Error("timeout")), timeoutSec * 1000),
+        );
+        result = await Promise.race([execPromise, timeoutPromise]);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg === "timeout") {
+          return {
+            content: `Command timed out after ${timeoutSec}s.`,
+            exitCode: -1,
+            isError: true,
+          };
+        }
+        return { content: `Error: ${msg}`, exitCode: -1, isError: true };
+      }
+
+      const exitCode = result.exitCode ?? 0;
+      const isError = exitCode !== 0 && exitCode !== null;
+
+      if (returnOutput) {
+        return {
+          content: result.output || "(no output)",
+          exitCode,
+          isError,
+        };
+      }
+
+      return {
+        content: isError
+          ? `Command failed with exit code ${exitCode}.`
+          : "Command executed.",
+        exitCode,
+        isError,
+      };
+    },
+  };
+}

package/examples/extensions/web-access.ts

@@ -230,6 +230,14 @@ export default function activate(ctx: ExtensionContext) {
   const timeout = config.timeout ?? 30000;
   const numResults = config.searchNumResults ?? 5;
 
+  // ── System instruction ────────────────────────────────────────────
+
+  ctx.registerInstruction(
+    "You have access to web search and fetching tools. " +
+    "Use `web_search` to find information on the web, then `web_fetch` to read specific pages. " +
+    "Use `web_fetch` with `raw: true` for JSON APIs or plain text files.",
+  );
+
   // ── Tool: web_search (Exa MCP, free) ────────────────────────────
 
   ctx.registerTool({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sh",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "A shell-first terminal where AI is one keystroke away",
   "type": "module",
   "main": "dist/core.js",
@@ -17,7 +17,7 @@
       "types": "./dist/core.d.ts",
       "default": "./dist/core.js"
     },
-    "./utils/*": "./dist/utils/*.js",
+    "./utils/*": "./dist/utils/*",
     "./types": {
       "types": "./dist/types.d.ts",
       "default": "./dist/types.js"
@@ -41,6 +41,38 @@
     "./utils/terminal-buffer": {
       "types": "./dist/utils/terminal-buffer.d.ts",
       "default": "./dist/utils/terminal-buffer.js"
+    },
+    "./agent/types": {
+      "types": "./dist/agent/types.d.ts",
+      "default": "./dist/agent/types.js"
+    },
+    "./agent/subagent": {
+      "types": "./dist/agent/subagent.d.ts",
+      "default": "./dist/agent/subagent.js"
+    },
+    "./agent/agent-loop": {
+      "types": "./dist/agent/agent-loop.d.ts",
+      "default": "./dist/agent/agent-loop.js"
+    },
+    "./event-bus": {
+      "types": "./dist/event-bus.d.ts",
+      "default": "./dist/event-bus.js"
+    },
+    "./utils/compositor": {
+      "types": "./dist/utils/compositor.d.ts",
+      "default": "./dist/utils/compositor.js"
+    },
+    "./utils/floating-panel": {
+      "types": "./dist/utils/floating-panel.d.ts",
+      "default": "./dist/utils/floating-panel.js"
+    },
+    "./agent/token-budget": {
+      "types": "./dist/agent/token-budget.d.ts",
+      "default": "./dist/agent/token-budget.js"
+    },
+    "./executor": {
+      "types": "./dist/executor.d.ts",
+      "default": "./dist/executor.js"
     }
   },
   "files": [
@@ -78,12 +110,14 @@
   },
   "dependencies": {
     "cli-highlight": "^2.1.11",
+    "diff": "^9.0.0",
     "marked": "^17.0.6",
     "node-pty": "^1.2.0-beta.12",
     "openai": "^6.34.0",
     "tsx": "^4.19.0"
   },
   "devDependencies": {
+    "@types/diff": "^8.0.0",
     "@types/node": "^22.0.0",
     "typescript": "^5.7.0"
   }

package/dist/agent/tools/display.d.ts

@@ -1,13 +0,0 @@
-import type { EventBus } from "../../event-bus.js";
-import type { ToolDefinition } from "../types.js";
-/**
- * display — shows command output to the user in their live terminal.
- *
- * Unlike bash (scratchpad), the user sees the output directly in their shell.
- * Unlike user_shell, this is for read-only display — no lasting side effects.
- * The agent does NOT receive the output back.
- */
-export declare function createDisplayTool(opts: {
-    getCwd: () => string;
-    bus: EventBus;
-}): ToolDefinition;

package/dist/agent/tools/display.js

@@ -1,70 +0,0 @@
-/**
- * display — shows command output to the user in their live terminal.
- *
- * Unlike bash (scratchpad), the user sees the output directly in their shell.
- * Unlike user_shell, this is for read-only display — no lasting side effects.
- * The agent does NOT receive the output back.
- */
-export function createDisplayTool(opts) {
-    return {
-        name: "display",
-        description: "Show command output to the user in their terminal. Use when the user asks to see something (cat, git log, diff, man, etc.) and you don't need to process the output yourself. Output is NOT returned to you.",
-        input_schema: {
-            type: "object",
-            properties: {
-                command: {
-                    type: "string",
-                    description: "Command to run and display output to the user",
-                },
-                timeout: {
-                    type: "number",
-                    description: "Timeout in seconds (default: 30)",
-                },
-            },
-            required: ["command"],
-        },
-        showOutput: false,
-        modifiesFiles: false,
-        getDisplayInfo: () => ({
-            kind: "display",
-            icon: "◇",
-            locations: [],
-        }),
-        async execute(args) {
-            const command = args.command;
-            const timeoutSec = args.timeout ?? 30;
-            let result;
-            try {
-                const execPromise = opts.bus.emitPipeAsync("shell:exec-request", {
-                    command,
-                    output: "",
-                    cwd: opts.getCwd(),
-                    exitCode: null,
-                    done: false,
-                });
-                const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error("timeout")), timeoutSec * 1000));
-                result = await Promise.race([execPromise, timeoutPromise]);
-            }
-            catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
-                if (msg === "timeout") {
-                    return {
-                        content: `Command timed out after ${timeoutSec}s.`,
-                        exitCode: -1,
-                        isError: true,
-                    };
-                }
-                return { content: `Error: ${msg}`, exitCode: -1, isError: true };
-            }
-            const exitCode = result.exitCode ?? 0;
-            const isError = exitCode !== 0 && exitCode !== null;
-            return {
-                content: isError
-                    ? `Command failed with exit code ${exitCode}.`
-                    : "Output displayed to user.",
-                exitCode,
-                isError,
-            };
-        },
-    };
-}

package/dist/agent/tools/user-shell.d.ts

@@ -1,13 +0,0 @@
-import type { EventBus } from "../../event-bus.js";
-import type { ToolDefinition } from "../types.js";
-/**
- * user_shell — runs commands in the user's live PTY shell.
- *
- * Unlike bash, this affects the user's shell state (cd, export, source).
- * Output is shown directly in the terminal. By default, the agent doesn't
- * see the output (return_output=false) to save tokens.
- */
-export declare function createUserShellTool(opts: {
-    getCwd: () => string;
-    bus: EventBus;
-}): ToolDefinition;

package/dist/agent/tools/user-shell.js

@@ -1,87 +0,0 @@
-/**
- * user_shell — runs commands in the user's live PTY shell.
- *
- * Unlike bash, this affects the user's shell state (cd, export, source).
- * Output is shown directly in the terminal. By default, the agent doesn't
- * see the output (return_output=false) to save tokens.
- */
-export function createUserShellTool(opts) {
-    return {
-        name: "user_shell",
-        description: "Run a complete, non-interactive command in the user's live shell (cd, export, install packages, start servers, git commands). " +
-            "Use this for commands that have side effects or that the user wants to see. Output is shown directly to the user but NOT returned " +
-            "to you by default — set return_output=true if you need to inspect the result. " +
-            "Do NOT use this to interact with programs that are already running in the terminal — use terminal_keys/terminal_read instead.",
-        input_schema: {
-            type: "object",
-            properties: {
-                command: {
-                    type: "string",
-                    description: "Command to execute in user's shell",
-                },
-                timeout: {
-                    type: "number",
-                    description: "Timeout in seconds (default: 30)",
-                },
-                return_output: {
-                    type: "boolean",
-                    default: false,
-                    description: "Whether to return the command output to you. Default false — output is shown directly to the user. Set true only if you need to inspect the result to answer a question.",
-                },
-            },
-            required: ["command"],
-        },
-        showOutput: false,
-        modifiesFiles: true,
-        getDisplayInfo: () => ({
-            kind: "execute",
-            icon: "▷",
-            locations: [],
-        }),
-        async execute(args) {
-            const command = args.command;
-            const timeoutSec = args.timeout ?? 30;
-            const returnOutput = args.return_output ?? false;
-            // Execute via the shell-exec extension's async pipe with timeout
-            let result;
-            try {
-                const execPromise = opts.bus.emitPipeAsync("shell:exec-request", {
-                    command,
-                    output: "",
-                    cwd: opts.getCwd(),
-                    exitCode: null,
-                    done: false,
-                });
-                const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error("timeout")), timeoutSec * 1000));
-                result = await Promise.race([execPromise, timeoutPromise]);
-            }
-            catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
-                if (msg === "timeout") {
-                    return {
-                        content: `Command timed out after ${timeoutSec}s.`,
-                        exitCode: -1,
-                        isError: true,
-                    };
-                }
-                return { content: `Error: ${msg}`, exitCode: -1, isError: true };
-            }
-            const exitCode = result.exitCode ?? 0;
-            const isError = exitCode !== 0 && exitCode !== null;
-            if (returnOutput) {
-                return {
-                    content: result.output || "(no output)",
-                    exitCode,
-                    isError,
-                };
-            }
-            return {
-                content: isError
-                    ? `Command failed with exit code ${exitCode}.`
-                    : "Command executed.",
-                exitCode,
-                isError,
-            };
-        },
-    };
-}

package/dist/extensions/terminal-buffer.d.ts

@@ -1,14 +0,0 @@
-/**
- * Built-in terminal buffer extension.
- *
- * Registers two agent tools:
- *   - terminal_read: get the current screen contents + cursor position
- *   - terminal_keys: send raw keystrokes into the user's live PTY
- *
- * Together these let the agent operate inside interactive programs
- * (vim, htop, less, etc.) by reading the screen and typing keys.
- *
- * Requires: npm install @xterm/headless@5.5.0 @xterm/addon-serialize@0.13.0
- */
-import type { ExtensionContext } from "../types.js";
-export default function activate(ctx: ExtensionContext): void;