agent-sh 0.9.0 → 0.10.1

package/examples/extensions/ash-mcp-bridge/index.ts

@@ -65,6 +65,17 @@ export default async function activate(ctx: any): Promise<void> {
     }
   }
 
+  // Contribute connected servers to the startup banner
+  bus.onPipe("banner:collect", (e) => {
+    if (connected.length > 0) {
+      e.sections.push({
+        label: "MCP Servers",
+        items: connected.map((s) => s.name),
+      });
+    }
+    return e;
+  });
+
   // Clean up on exit
   bus.on("app:quit", () => {
     for (const server of connected) {
@@ -84,6 +95,7 @@ async function connectServer(
     command: config.command,
     args: config.args,
     env: { ...process.env, ...config.env } as Record<string, string>,
+    stderr: "pipe",
   });
 
   const client = new Client({ name: `ash-${name}`, version: "0.1.0" });
@@ -146,9 +158,7 @@ async function connectServer(
     });
   }
 
-  ctx.bus.emit("ui:info", {
-    message: `mcp-bridge: "${name}" connected (${tools.length} tools)`,
-  });
+  // ui:info suppressed — connection is silent by default
 
   return { name, client, transport };
 }

package/examples/extensions/claude-code-bridge/README.md

@@ -33,3 +33,17 @@ Or switch at runtime:
 
 - `ANTHROPIC_API_KEY` must be set in your environment
 - Claude Code manages its own model selection — no model configuration needed in agent-sh
+
+## What this bridge is
+
+A pure protocol translator between the Claude Agent SDK's event stream and agent-sh's bus events. Claude Code uses its own built-in tools exactly as the SDK ships them (`Read`, `Edit`, `Write`, `Bash`, `Glob`, `Grep`). The bridge adds no tools of its own.
+
+## What this bridge intentionally does NOT bundle
+
+Three PTY-access tools are left out on purpose:
+
+- `terminal_read` — observe the user's live terminal screen
+- `terminal_keys` — send keystrokes to the user's PTY
+- `user_shell` — run commands in the user's live shell with lasting `cd`/`export`/`source` effects
+
+These are opt-in capabilities that belong in their own extensions. If you want any of them with Claude Code, write a companion extension that uses the SDK's `tool()` + `createSdkMcpServer()` to expose them as MCP tools, and extend the bridge (or fork it) to attach that MCP server to the SDK's `query()` options.

package/examples/extensions/claude-code-bridge/index.ts

@@ -2,148 +2,76 @@
  * Claude Code bridge — runs Claude Code Agent SDK in-process as agent-sh's backend.
  *
  * Uses the official @anthropic-ai/claude-agent-sdk to spawn a Claude Code
- * session with a custom user_shell MCP tool for PTY access. Claude Code
- * handles its own model selection, tool execution, and permissions.
+ * session. Claude Code handles its own model selection, tool execution, and
+ * permissions — the bridge is a pure protocol translator between the SDK's
+ * event stream and agent-sh's bus events.
  *
- * Setup:
- *   npm install @anthropic-ai/claude-agent-sdk
+ * PTY-access tools (`terminal_read`, `terminal_keys`, `user_shell`) are
+ * intentionally NOT bundled here. If you want Claude Code to observe or
+ * drive the user's live terminal, load a companion extension that
+ * registers those tools as MCP tools the SDK can consume.
+ *
+ * Setup (from repo root):
+ *   npm run build && npm link                    # register local agent-sh globally
+ *   cd examples/extensions/claude-code-bridge
+ *   npm install && npm link agent-sh             # link local dev copy
  *
  * Usage:
  *   agent-sh -e examples/extensions/claude-code-bridge
  *
  * Requires: Claude Code CLI installed and authenticated (claude login).
  */
-import {
-  query,
-  tool,
-  createSdkMcpServer,
-  type Query,
-} from "@anthropic-ai/claude-agent-sdk";
-import { z } from "zod";
-import type { ExtensionContext } from "../../src/types.js";
-import type { EventBus } from "../../src/event-bus.js";
-
-// ── Helpers ──────────────────────────────────────────────────────
-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));
-}
-
-// ── user_shell MCP tool ───────────────────────────────────────────
-function createUserShellTool(bus: EventBus) {
-  let liveCwd = process.cwd();
-  bus.on("shell:cwd-change", ({ cwd }) => { liveCwd = cwd; });
-
-  return tool(
-    "user_shell",
-    "Run a command with lasting effects in the user's live shell (cd, export, " +
-    "install packages, start servers) or show output the user wants to see. " +
-    "Set return_output=true only if you need to inspect the result.",
-    {
-      command: z.string().describe("Command to execute in user's shell"),
-      return_output: z.boolean().optional().describe(
-        "Whether to return the command output. Default false.",
-      ),
-    },
-    async (args) => {
-      const result = await bus.emitPipeAsync("shell:exec-request", {
-        command: args.command,
-        output: "",
-        cwd: liveCwd,
-        done: false,
-      });
-
-      const text = args.return_output
-        ? result.output || "(no output)"
-        : "Command executed.";
-
-      return { content: [{ type: "text" as const, text }] };
-    },
-  );
-}
-
-// ── terminal_read MCP tool ────────────────────────────────────────
-function createTerminalReadTool(ctx: ExtensionContext) {
-  return tool(
-    "terminal_read",
-    "Read the current terminal screen contents. Returns clean text (ANSI stripped) " +
-    "with cursor position and whether an alternate-screen program (vim, htop, less) is active. " +
-    "Use this to see what the user sees before sending keystrokes with terminal_keys.",
-    {},
-    async () => {
-      const tb = ctx.terminalBuffer;
-      if (!tb) return { content: [{ type: "text" as const, text: "terminal buffer not available" }] };
-      const { text, altScreen, cursorX, cursorY } = tb.readScreen();
-      const info = [
-        altScreen ? "mode: alternate screen" : "mode: normal",
-        `cursor: row=${cursorY} col=${cursorX}`,
-      ].join(", ");
-      return { content: [{ type: "text" as const, text: `[${info}]\n\n${text}` }] };
-    },
-  );
-}
-
-// ── terminal_keys MCP tool ───────────────────────────────────────
-function createTerminalKeysTool(bus: EventBus, ctx: ExtensionContext) {
-  return tool(
-    "terminal_keys",
-    "Send keystrokes to the user's live terminal. The keys are written directly to the PTY " +
-    "as if the user typed them. Use escape sequences for special keys:\n" +
-    "  - Escape: \\x1b  - Enter: \\r  - Tab: \\t\n" +
-    "  - Ctrl+C: \\x03  - Arrow keys: \\x1b[A/B/C/D  - Backspace: \\x7f\n" +
-    "Example: to quit vim without saving, send keys=\"\\x1b:q!\\r\".\n" +
-    "Always call terminal_read after sending keys to verify the result.",
-    {
-      keys: z.string().describe("Keystrokes to send (use \\x1b for Escape, \\r for Enter, etc.)"),
-      settle_ms: z.number().optional().describe("Wait time in ms after sending keys (default: 150)"),
-    },
-    async (args) => {
-      const keys = interpretEscapes(args.keys);
-      const settleMs = args.settle_ms ?? 150;
-      bus.emit("shell:stdout-show", {});
-      process.stdout.write("\n");
-      bus.emit("shell:pty-write", { data: keys });
-      await settle(settleMs);
-
-      const tb = ctx.terminalBuffer;
-      if (!tb) return { content: [{ type: "text" as const, text: "Keys sent." }] };
-      const { text, altScreen, cursorX, cursorY } = tb.readScreen();
-      const info = [
-        altScreen ? "mode: alternate screen" : "mode: normal",
-        `cursor: row=${cursorY} col=${cursorX}`,
-      ].join(", ");
-      return { content: [{ type: "text" as const, text: `Keys sent. Screen after:\n[${info}]\n\n${text}` }] };
-    },
-  );
-}
+import { query, type Query } from "@anthropic-ai/claude-agent-sdk";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import type { ExtensionContext } from "agent-sh/types";
+import { computeDiff, type DiffResult } from "agent-sh/utils/diff";
 
 // ── Extension entry point ─────────────────────────────────────────
 export default function activate(ctx: ExtensionContext): void {
   const { bus } = ctx;
 
-  const shellTool = createUserShellTool(bus);
-  const termReadTool = createTerminalReadTool(ctx);
-  const termKeysTool = createTerminalKeysTool(bus, ctx);
-  const shellServer = createSdkMcpServer({
-    name: "agent-sh",
-    version: "1.0.0",
-    tools: [shellTool, termReadTool, termKeysTool],
-  });
-
   let activeQuery: Query | null = null;
   const listeners: Array<{ event: string; fn: Function }> = [];
 
+  // ── Tool display helpers ────────────────────────────────────────
+
+  /** Map Claude Code tool names to agent-sh display kinds. */
+  function toolKind(name: string): string {
+    if (name === "Read") return "read";
+    if (name === "Edit") return "edit";
+    if (name === "Write") return "write";
+    if (name === "Glob" || name === "Grep") return "search";
+    if (name === "Bash") return "execute";
+    return "execute";
+  }
+
+  /** Map Claude Code tool names to agent-sh display icons. */
+  function toolIcon(name: string): string | undefined {
+    if (name === "Read") return "◆";
+    if (name === "Edit") return "✎";
+    if (name === "Write") return "✎";
+    if (name === "Glob" || name === "Grep") return "⌕";
+    return undefined;
+  }
+
+  /** Extract file locations from tool input args. */
+  function toolLocations(input: Record<string, unknown>): { path: string; line?: number | null }[] | undefined {
+    const raw = input.file_path ?? input.path;
+    if (typeof raw !== "string") return undefined;
+    const line = (input.line_number ?? input.line ?? input.offset) as number | undefined;
+    return [{ path: raw, line: line ?? null }];
+  }
+
+  /** Format a compact display string for a tool call. */
+  function formatToolCall(name: string, input: Record<string, unknown>): string {
+    const str = (v: unknown) => typeof v === "string" ? v : "";
+    if (name === "Bash") return `$ ${str(input.command)}`;
+    if (name === "Read" || name === "Edit" || name === "Write") return str(input.file_path ?? input.path);
+    if (name === "Grep" || name === "Glob") return `${str(input.pattern)} ${str(input.path)}`.trim();
+    return name;
+  }
+
   const wireListeners = () => {
     const onSubmit = async ({ query: userQuery }: any) => {
       bus.emit("agent:query", { query: userQuery });
@@ -151,6 +79,14 @@ export default function activate(ctx: ExtensionContext): void {
 
       let fullResponseText = "";
       let streamed = false;
+      /** Track in-flight tool calls so we can emit tool-completed when results arrive. */
+      const pendingTools = new Map<string, { name: string; kind: string; input?: Record<string, unknown> }>();
+      /** Tool input JSON being streamed via input_json_delta events. */
+      const inputBuffers = new Map<number, string>();
+      /** Tool metadata per content block index (for correlating deltas). */
+      const blockMeta = new Map<number, { name: string; id: string }>();
+      /** Pre-edit file snapshots for diff display (Edit/Write tools). */
+      const fileSnapshots = new Map<string, string | null>();
 
       try {
         activeQuery = query({
@@ -162,17 +98,9 @@ export default function activate(ctx: ExtensionContext): void {
               preset: "claude_code",
               append:
                 "You are running inside agent-sh, a terminal wrapper.\n" +
-                "Use your standard tools (Read, Edit, Write, Bash, Glob, Grep) for investigation.\n" +
-                "Use mcp__agent-sh__user_shell to run commands in the user's live shell when they ask to see output or need lasting effects (cd, install, start servers).\n" +
-                "Default to standard tools. Use user_shell when the user is the intended audience for the output or the command has real effects.",
+                "Use your standard tools (Read, Edit, Write, Bash, Glob, Grep) for investigation.",
             },
-            mcpServers: { "agent-sh": shellServer },
-            allowedTools: [
-              "mcp__agent-sh__user_shell",
-              "mcp__agent-sh__terminal_read",
-              "mcp__agent-sh__terminal_keys",
-              "Read", "Edit", "Write", "Bash", "Glob", "Grep",
-            ],
+            allowedTools: ["Read", "Edit", "Write", "Bash", "Glob", "Grep"],
             permissionMode: "acceptEdits",
             includePartialMessages: true,
           },
@@ -183,16 +111,56 @@ export default function activate(ctx: ExtensionContext): void {
             case "stream_event": {
               streamed = true;
               const event = message.event;
-              if (event.type === "content_block_delta") {
-                const delta = event.delta as any;
-                if (delta.type === "text_delta" && delta.text) {
+              if (event.type === "content_block_start") {
+                const cb = (event as any).content_block;
+                if (cb?.type === "tool_use") {
+                  blockMeta.set(event.index, { name: cb.name, id: cb.id });
+                  inputBuffers.set(event.index, "");
+                }
+              } else if (event.type === "content_block_delta") {
+                const delta = (event as any).delta;
+                if (delta?.type === "text_delta" && delta.text) {
                   bus.emitTransform("agent:response-chunk", {
                     blocks: [{ type: "text" as const, text: delta.text }],
                   });
                   fullResponseText += delta.text;
-                } else if (delta.type === "thinking_delta" && delta.thinking) {
+                } else if (delta?.type === "thinking_delta" && delta.thinking) {
                   bus.emit("agent:thinking-chunk", { text: delta.thinking });
+                } else if (delta?.type === "input_json_delta" && delta.partial_json != null) {
+                  // Accumulate tool input JSON as it streams in
+                  const buf = inputBuffers.get(event.index) ?? "";
+                  inputBuffers.set(event.index, buf + delta.partial_json);
                 }
+              } else if (event.type === "content_block_stop") {
+                const meta = blockMeta.get(event.index);
+                const inputJson = inputBuffers.get(event.index);
+                if (meta && inputJson != null) {
+                  blockMeta.delete(event.index);
+                  inputBuffers.delete(event.index);
+
+                  let input: Record<string, unknown> = {};
+                  try { input = JSON.parse(inputJson || "{}"); } catch {}
+
+                  const kind = toolKind(meta.name);
+                  bus.emit("agent:tool-started", {
+                    title: meta.name,
+                    toolCallId: meta.id,
+                    kind,
+                    icon: toolIcon(meta.name),
+                    locations: toolLocations(input),
+                    rawInput: input,
+                    displayDetail: formatToolCall(meta.name, input),
+                  });
+                  pendingTools.set(meta.id, { name: meta.name, kind, input });
+
+                  // Snapshot file content before Edit/Write modifies it
+                  if ((meta.name === "Edit" || meta.name === "Write") && typeof (input as any).file_path === "string") {
+                    const absPath = resolve(process.cwd(), (input as any).file_path);
+                    readFile(absPath, "utf-8")
+                      .then(content => fileSnapshots.set(meta.id, content))
+                      .catch(() => fileSnapshots.set(meta.id, null)); // file doesn't exist yet
+                  }
+              }
               }
               break;
             }
@@ -206,24 +174,115 @@ export default function activate(ctx: ExtensionContext): void {
                     blocks: [{ type: "text" as const, text: b.text }],
                   });
                   fullResponseText += b.text;
-                } else if (b.type === "tool_use") {
+                } else if (b.type === "tool_use" && !streamed) {
+                  // Non-streamed fallback: emit tool-started from full message
+                  const input = (b.input ?? {}) as Record<string, unknown>;
+                  const kind = toolKind(b.name);
                   bus.emit("agent:tool-started", {
                     title: b.name,
                     toolCallId: b.id,
-                    kind: b.name.includes("shell") || b.name === "Bash"
-                      ? "execute"
-                      : "read",
+                    kind,
+                    icon: toolIcon(b.name),
+                    locations: toolLocations(input),
+                    rawInput: input,
+                    displayDetail: formatToolCall(b.name, input),
                   });
+                  pendingTools.set(b.id, { name: b.name, kind, input });
+
+                  // Snapshot file content before Edit/Write modifies it
+                  if ((b.name === "Edit" || b.name === "Write") && typeof (input as any).file_path === "string") {
+                    const absPath = resolve(process.cwd(), (input as any).file_path);
+                    readFile(absPath, "utf-8")
+                      .then(content => fileSnapshots.set(b.id, content))
+                      .catch(() => fileSnapshots.set(b.id, null));
+                  }
                 }
               }
               break;
             }
 
+            case "user": {
+              // Tool results come back as user messages with tool_result content blocks
+              const msg = message.message as any;
+              if (msg?.content && Array.isArray(msg.content)) {
+                for (const block of msg.content) {
+                  if (block.type === "tool_result") {
+                    const toolUseId = block.tool_use_id as string;
+                    const pending = pendingTools.get(toolUseId);
+                    if (!pending) continue;
+                    pendingTools.delete(toolUseId);
+
+                    const isError = !!block.is_error;
+                    const content = typeof block.content === "string"
+                      ? block.content
+                      : Array.isArray(block.content)
+                        ? block.content.map((c: any) => c.text ?? JSON.stringify(c)).join("\n")
+                        : "";
+
+                    // Compute diff for Edit/Write tools
+                    let resultDisplay: { summary?: string; body?: { kind: "diff"; diff: DiffResult; filePath: string } } | undefined;
+                    if (!isError && (pending.name === "Edit" || pending.name === "Write")) {
+                      const oldContent = fileSnapshots.get(toolUseId);
+                      fileSnapshots.delete(toolUseId);
+                      const filePath = (pending.input as any)?.file_path as string | undefined;
+                      if (filePath) {
+                        const absPath = resolve(process.cwd(), filePath);
+                        try {
+                          const newContent = await readFile(absPath, "utf-8");
+                          const diff = computeDiff(oldContent, newContent);
+                          if (!diff.isIdentical) {
+                            const summary = diff.isNewFile
+                              ? `+${diff.added}`
+                              : `+${diff.added} -${diff.removed}`;
+                            resultDisplay = {
+                              summary,
+                              body: { kind: "diff", diff, filePath: absPath },
+                            };
+                          }
+                        } catch { /* file may not exist after failed edit */ }
+                      }
+                    } else {
+                      fileSnapshots.delete(toolUseId);
+                    }
+
+                    const exitCode = isError ? 1 : 0;
+                    bus.emitTransform("agent:tool-completed", {
+                      toolCallId: toolUseId,
+                      exitCode,
+                      rawOutput: content,
+                      kind: pending.kind,
+                      resultDisplay,
+                    });
+                    bus.emit("agent:tool-output", {
+                      tool: pending.name,
+                      output: content,
+                      exitCode,
+                    });
+                  }
+                }
+              }
+              break;
+            }
+
+            case "tool_progress":
+              // Tool still running — nothing to do, TUI spinner already active
+              break;
+
             case "result":
               break;
           }
         }
 
+        // Emit completion for any tools still pending (edge case: interrupted query)
+        for (const [id, pending] of pendingTools) {
+          bus.emitTransform("agent:tool-completed", {
+            toolCallId: id,
+            exitCode: 0,
+            rawOutput: "",
+            kind: pending.kind,
+          });
+        }
+
         bus.emitTransform("agent:response-done", {
           response: fullResponseText,
         });

package/examples/extensions/claude-code-bridge/package.json

@@ -6,6 +6,7 @@
   "main": "index.ts",
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.0",
+    "agent-sh": "^0.9.0",
     "zod": "^4.0.0"
   }
 }

package/examples/extensions/interactive-prompts.ts

@@ -18,9 +18,44 @@ import { palette as p } from "agent-sh/utils/palette.js";
 import type { ExtensionContext } from "agent-sh/types";
 import type { ToolUI } from "agent-sh/agent/types.js";
 
-export default function activate({ bus }: ExtensionContext) {
+export default function activate(ctx: ExtensionContext) {
   let autoApproveWrites = false;
 
+  // Advise the TUI diff renderer to add permission prompt framing.
+  // This replaces the default plain diff box with one that has a warning
+  // border and key hints, so only one diff box is shown (not two).
+  ctx.advise("tui:render-diff", (next, filePath: string, diff: any, width: number) => {
+    const boxW = Math.min(84, width);
+    const contentW = boxW - 4;
+    const MAX_DISPLAY = 25;
+
+    const stats = diff.isNewFile
+      ? `(+${diff.added} lines)`
+      : `(+${diff.added} / -${diff.removed})`;
+    const title = diff.isNewFile
+      ? `new: ${filePath}  ${stats}`
+      : `${filePath}  ${stats}`;
+
+    const diffLines = renderDiff(diff, {
+      width: contentW,
+      filePath,
+      maxLines: MAX_DISPLAY,
+      trueColor: true,
+      mode: "unified",
+    });
+    const content = ["", ...diffLines.slice(1), ""];
+
+    return renderBoxFrame(content, {
+      width: boxW,
+      style: "rounded",
+      borderColor: p.warning,
+      title,
+      footer: [`  ${p.bold}[y] Apply  [n] Skip  [a] Don't ask again${p.reset}`],
+    });
+  });
+
+  const { bus } = ctx;
+
   bus.onPipeAsync("permission:request", async (payload) => {
     const ui = payload.ui as ToolUI | undefined;
     if (!ui) return payload;
@@ -82,36 +117,15 @@ async function handleToolCall(payload: any, ui: ToolUI) {
 }
 
 async function handleFileWrite(payload: any, ui: ToolUI) {
-  const diff = payload.metadata.diff;
-  const filePath = payload.metadata.path ?? payload.title;
-
   const answer = await ui.custom<"approve" | "approve_all" | "reject">({
     render(width) {
       const boxW = Math.min(84, width);
-      const contentW = boxW - 4;
-      const MAX_DISPLAY = 25;
-
-      const stats = diff.isNewFile
-        ? `(+${diff.added} lines)`
-        : `(+${diff.added} / -${diff.removed})`;
-      const title = diff.isNewFile
-        ? `new: ${filePath}  ${stats}`
-        : `${filePath}  ${stats}`;
-
-      const diffLines = renderDiff(diff, {
-        width: contentW,
-        filePath,
-        maxLines: MAX_DISPLAY,
-        trueColor: true,
-        mode: "unified",
-      });
-      const content = ["", ...diffLines.slice(1), ""];
-
-      return renderBoxFrame(content, {
+      // Just show the prompt actions — the diff itself was already rendered
+      // by our advise on "tui:render-diff".
+      return renderBoxFrame([], {
         width: boxW,
         style: "rounded",
         borderColor: p.warning,
-        title,
         footer: [`  ${p.bold}[y] Apply  [n] Skip  [a] Don't ask again${p.reset}`],
       });
     },

package/examples/extensions/overlay-agent.ts

@@ -16,9 +16,9 @@
  *
  * Requires: npm install @xterm/headless@5.5.0 @xterm/addon-serialize@0.13.0
  */
-import type { ExtensionContext, RemoteSession } from "../../src/types.js";
-import type { RenderSurface } from "../../src/utils/compositor.js";
-import { FloatingPanel } from "../../src/utils/floating-panel.js";
+import type { ExtensionContext, RemoteSession } from "agent-sh/types";
+import type { RenderSurface } from "agent-sh/utils/compositor";
+import { FloatingPanel } from "agent-sh/utils/floating-panel";
 
 /** Adapt a FloatingPanel to the RenderSurface interface. */
 function createPanelSurface(panel: FloatingPanel): RenderSurface {