agent-sh 0.8.0 → 0.9.0

package/examples/extensions/ash-mcp-bridge/README.md

@@ -0,0 +1,72 @@
+# ash-mcp-bridge
+
+Connects any MCP (Model Context Protocol) server to ash. Spawns servers as child processes over stdio, discovers their tools, and registers each as a native ash tool.
+
+## Setup
+
+```bash
+cp -r examples/extensions/ash-mcp-bridge ~/.agent-sh/extensions/
+cd ~/.agent-sh/extensions/ash-mcp-bridge && npm install
+```
+
+## Configuration
+
+Add server definitions to `~/.agent-sh/settings.json`:
+
+```json
+{
+  "mcp-bridge": {
+    "servers": {
+      "vision": {
+        "command": "npx",
+        "args": ["-y", "@z_ai/mcp-server"],
+        "env": {
+          "Z_AI_API_KEY": "your-key",
+          "Z_AI_MODE": "ZAI"
+        }
+      }
+    }
+  }
+}
+```
+
+Each server entry:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `command` | `string` | Executable to spawn (e.g. `npx`, `node`) |
+| `args` | `string[]` | Command arguments |
+| `env` | `Record<string, string>` | Extra environment variables (merged with `process.env`) |
+
+## How it works
+
+On activation, the extension:
+
+1. Reads `mcp-bridge.servers` from settings
+2. Spawns each server as a child process with stdio transport
+3. Connects via the MCP SDK client
+4. Calls `listTools()` to discover available tools
+5. Registers each tool as `mcp_{server}_{tool}` (e.g. `mcp_vision_image_analysis`)
+
+Tools are then available to the agent like any built-in tool.
+
+## Example: Z.AI Vision
+
+```json
+{
+  "mcp-bridge": {
+    "servers": {
+      "vision": {
+        "command": "npx",
+        "args": ["-y", "@z_ai/mcp-server"],
+        "env": {
+          "Z_AI_API_KEY": "your-key",
+          "Z_AI_MODE": "ZAI"
+        }
+      }
+    }
+  }
+}
+```
+
+This gives the agent access to tools like `mcp_vision_image_analysis`, `mcp_vision_ui_to_artifact`, `mcp_vision_extract_text_from_screenshot`, etc.

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

@@ -0,0 +1,154 @@
+/**
+ * MCP Bridge — connects external MCP servers to agent-sh.
+ *
+ * Spawns MCP servers as child processes, discovers their tools,
+ * and registers each tool as an agent-sh ToolDefinition.
+ *
+ * Configure in ~/.agent-sh/settings.json:
+ *
+ *   {
+ *     "extensions": ["./path/to/mcp-bridge"],
+ *     "mcp-bridge": {
+ *       "servers": {
+ *         "vision": {
+ *           "command": "npx",
+ *           "args": ["-y", "@z_ai/mcp-server"],
+ *           "env": {
+ *             "Z_AI_API_KEY": "your-key",
+ *             "Z_AI_MODE": "ZAI"
+ *           }
+ *         }
+ *       }
+ *     }
+ *   }
+ */
+
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+interface McpServerConfig {
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+}
+
+interface McpBridgeSettings {
+  servers: Record<string, McpServerConfig>;
+}
+
+interface ConnectedServer {
+  name: string;
+  client: Client;
+  transport: StdioClientTransport;
+}
+
+export default async function activate(ctx: any): Promise<void> {
+  const { bus } = ctx;
+
+  const settings = ctx.getExtensionSettings("mcp-bridge", {
+    servers: {},
+  }) as McpBridgeSettings;
+
+  const serverEntries = Object.entries(settings.servers);
+  if (serverEntries.length === 0) return;
+
+  const connected: ConnectedServer[] = [];
+
+  for (const [name, config] of serverEntries) {
+    try {
+      const server = await connectServer(name, config, ctx);
+      connected.push(server);
+    } catch (err: any) {
+      bus.emit("ui:info", {
+        message: `mcp-bridge: failed to connect "${name}": ${err.message}`,
+      });
+    }
+  }
+
+  // Clean up on exit
+  bus.on("app:quit", () => {
+    for (const server of connected) {
+      try {
+        server.transport.close();
+      } catch {}
+    }
+  });
+}
+
+async function connectServer(
+  name: string,
+  config: McpServerConfig,
+  ctx: any,
+): Promise<ConnectedServer> {
+  const transport = new StdioClientTransport({
+    command: config.command,
+    args: config.args,
+    env: { ...process.env, ...config.env } as Record<string, string>,
+  });
+
+  const client = new Client({ name: `ash-${name}`, version: "0.1.0" });
+  await client.connect(transport);
+
+  // Discover and register tools
+  const { tools } = await client.listTools();
+  for (const tool of tools) {
+    const toolName = `mcp_${name}_${tool.name}`;
+    ctx.registerTool({
+      name: toolName,
+      displayName: tool.name,
+      description: `[${name}] ${tool.description ?? ""}`,
+      input_schema: tool.inputSchema as Record<string, unknown>,
+
+      async execute(args: Record<string, unknown>) {
+        try {
+          const result = await client.callTool({
+            name: tool.name,
+            arguments: args,
+          });
+
+          const text = (result.content as any[])
+            .map((c: any) => {
+              if (c.type === "text") return c.text;
+              if (c.type === "image") return `[image: ${c.mimeType}]`;
+              return JSON.stringify(c);
+            })
+            .join("\n");
+
+          return {
+            content: text,
+            exitCode: result.isError ? 1 : 0,
+            isError: !!result.isError,
+          };
+        } catch (err: any) {
+          return {
+            content: `MCP error: ${err.message}`,
+            exitCode: 1,
+            isError: true,
+          };
+        }
+      },
+
+      getDisplayInfo() {
+        return { kind: "execute" as const };
+      },
+
+      formatCall(args: Record<string, unknown>) {
+        // Show a compact summary of the args
+        const keys = Object.keys(args);
+        if (keys.length === 0) return tool.name;
+        const first = args[keys[0]];
+        const preview =
+          typeof first === "string"
+            ? first.slice(0, 60) + (first.length > 60 ? "…" : "")
+            : JSON.stringify(first).slice(0, 60);
+        return `${tool.name}: ${preview}`;
+      },
+    });
+  }
+
+  ctx.bus.emit("ui:info", {
+    message: `mcp-bridge: "${name}" connected (${tools.length} tools)`,
+  });
+
+  return { name, client, transport };
+}

package/examples/extensions/ash-mcp-bridge/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "ash-mcp-bridge",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  }
+}

package/examples/extensions/interactive-prompts.ts

@@ -4,34 +4,36 @@
  * Adds permission gates for tool calls and file writes.
  * Without this extension, agent-sh runs in yolo mode (auto-approve).
  *
+ * Uses the interactive UI primitive for compositor-aware, themed rendering.
+ *
  * Usage:
- *   # Load by short name (built-in):
- *   agent-sh --extensions interactive-prompts
+ *   agent-sh -e ./examples/extensions/interactive-prompts.ts
  *
  *   # Or copy to ~/.agent-sh/extensions/ for permanent use:
  *   cp examples/extensions/interactive-prompts.ts ~/.agent-sh/extensions/
- *
- *   # Or install as an npm package and load by name:
- *   agent-sh --extensions my-prompts-package
  */
 import { renderDiff } from "agent-sh/utils/diff-renderer.js";
 import { renderBoxFrame } from "agent-sh/utils/box-frame.js";
 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) {
   let autoApproveWrites = false;
 
   bus.onPipeAsync("permission:request", async (payload) => {
+    const ui = payload.ui as ToolUI | undefined;
+    if (!ui) return payload;
+
     switch (payload.kind) {
       case "tool-call":
-        return handleToolCallPermission(payload);
+        return handleToolCall(payload, ui);
       case "file-write": {
         if (autoApproveWrites) {
-          return { ...payload, decision: { approved: true } };
+          return { ...payload, decision: { outcome: "approved" } };
         }
-        const result = await handleFileWritePermission(payload);
-        if (result.decision.autoApprove) {
+        const result = await handleFileWrite(payload, ui);
+        if ((result.decision as any).autoApprove) {
           autoApproveWrites = true;
         }
         return result;
@@ -42,120 +44,90 @@ export default function activate({ bus }: ExtensionContext) {
   });
 }
 
-async function handleToolCallPermission(payload) {
+async function handleToolCall(payload: any, ui: ToolUI) {
   const options = payload.metadata.options;
-  const answer = await promptPermission(payload.title);
+
+  const answer = await ui.custom<"approve" | "approve_all" | "deny">({
+    render(width) {
+      const boxW = Math.min(84, width);
+      return renderBoxFrame(
+        [`${p.bold}⚠ ${payload.title}${p.reset}`],
+        {
+          width: boxW,
+          style: "rounded",
+          borderColor: p.warning,
+          title: "Permission required",
+          footer: [`  ${p.dim}[y]es / [n]o / [a]llow all${p.reset}`],
+        },
+      );
+    },
+    handleInput(data, done) {
+      const ch = data.toLowerCase();
+      if (ch === "y") done("approve");
+      else if (ch === "a") done("approve_all");
+      else if (ch === "n" || ch === "\x1b") done("deny");
+    },
+  });
 
   if (answer === "approve" || answer === "approve_all") {
-    const option = answer === "approve_all"
-      ? options.find((o) => o.kind === "allow_always") ?? options.find((o) => o.kind === "allow_once")
-      : options.find((o) => o.kind === "allow_once" || o.kind === "allow_always");
+    const kind = answer === "approve_all" ? "allow_always" : "allow_once";
+    const option = options?.find((o: any) => o.kind === kind)
+      ?? options?.find((o: any) => o.kind === "allow_once" || o.kind === "allow_always");
     if (option) {
       return { ...payload, decision: { outcome: "selected", optionId: option.optionId } };
     }
+    return { ...payload, decision: { outcome: "approved" } };
   }
   return { ...payload, decision: { outcome: "cancelled" } };
 }
 
-async function handleFileWritePermission(payload) {
+async function handleFileWrite(payload: any, ui: ToolUI) {
   const diff = payload.metadata.diff;
-  const filePath = payload.metadata.path;
-  const answer = await previewDiff({ path: filePath, diff });
-  if (answer === "approve") {
-    return { ...payload, decision: { approved: true } };
-  }
-  if (answer === "approve_all") {
-    return { ...payload, decision: { approved: true, autoApprove: true } };
-  }
-  return { ...payload, decision: { approved: false } };
-}
-
-async function promptPermission(title) {
-  const termW = process.stdout.columns || 80;
-  const boxW = Math.min(84, termW);
-
-  const framed = renderBoxFrame(
-    [`${p.bold}⚠ ${title}${p.reset}`],
-    {
-      width: boxW,
-      style: "rounded",
-      borderColor: p.warning,
-      title: "Permission required",
-      footer: [`  ${p.dim}[y]es / [n]o / [a]llow all${p.reset}`],
+  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, {
+        width: boxW,
+        style: "rounded",
+        borderColor: p.warning,
+        title,
+        footer: [`  ${p.bold}[y] Apply  [n] Skip  [a] Don't ask again${p.reset}`],
+      });
+    },
+    handleInput(data, done) {
+      const ch = data.toLowerCase();
+      if (ch === "y") done("approve");
+      else if (ch === "a") done("approve_all");
+      else if (ch === "n" || ch === "\x1b") done("reject");
     },
-  );
-
-  process.stdout.write("\n");
-  for (const line of framed) {
-    process.stdout.write(line + "\n");
-  }
-  process.stdout.write("  ");
-
-  return new Promise((resolve) => {
-    const handler = (data) => {
-      const ch = data.toString("utf-8").toLowerCase();
-      process.stdin.removeListener("data", handler);
-      process.stdout.write("\n");
-
-      if (ch === "y") resolve("approve");
-      else if (ch === "a") resolve("approve_all");
-      else resolve(null);
-    };
-    process.stdin.on("data", handler);
-  });
-}
-
-async function previewDiff(opts) {
-  const termW = process.stdout.columns || 80;
-  const boxW = Math.min(84, termW);
-  const contentW = boxW - 4;
-  const MAX_DISPLAY = 25;
-
-  const stats = opts.diff.isNewFile
-    ? `(+${opts.diff.added} lines)`
-    : `(+${opts.diff.added} / -${opts.diff.removed})`;
-  const title = opts.diff.isNewFile
-    ? `new: ${opts.path}  ${stats}`
-    : `${opts.path}  ${stats}`;
-
-  const diffLines = renderDiff(opts.diff, {
-    width: contentW,
-    filePath: opts.path,
-    maxLines: MAX_DISPLAY,
-    trueColor: true,
-    mode: "unified",
-  });
-  const content = ["", ...diffLines.slice(1), ""];
-
-  const framed = renderBoxFrame(content, {
-    width: boxW,
-    style: "rounded",
-    borderColor: p.warning,
-    title,
-    footer: [`  ${p.bold}[y] Apply  [n] Skip  [a] Don't ask again${p.reset}`],
   });
 
-  process.stdout.write("\n");
-  for (const line of framed) {
-    process.stdout.write(line + "\n");
+  if (answer === "approve") {
+    return { ...payload, decision: { outcome: "approved" } };
   }
-
-  return new Promise((resolve) => {
-    const handler = (data) => {
-      const ch = data.toString("utf-8").toLowerCase();
-      process.stdin.removeListener("data", handler);
-
-      if (ch === "y") {
-        process.stdout.write(`  ${p.success}✓ Applied${p.reset}\n`);
-        resolve("approve");
-      } else if (ch === "a") {
-        process.stdout.write(`  ${p.success}✓ Applied (auto-approve on)${p.reset}\n`);
-        resolve("approve_all");
-      } else {
-        process.stdout.write(`  ${p.error}✗ Skipped${p.reset}\n`);
-        resolve("reject");
-      }
-    };
-    process.stdin.on("data", handler);
-  });
+  if (answer === "approve_all") {
+    return { ...payload, decision: { outcome: "approved", autoApprove: true } };
+  }
+  return { ...payload, decision: { outcome: "cancelled" } };
 }

package/examples/extensions/overlay-agent.ts

@@ -5,66 +5,112 @@
  * inside vim, htop, or ssh. Composites a floating response box on top
  * of the current terminal content.
  *
- * Requires: npm install @xterm/headless@5.5.0 @xterm/addon-serialize@0.13.0
+ * Uses createRemoteSession() to route the full tui-renderer pipeline
+ * (markdown, tool grouping, spinner, diffs) into the floating panel.
+ *
+ * Install:
+ *   cp examples/extensions/overlay-agent.ts ~/.agent-sh/extensions/
  *
- * Usage:
+ * Or load directly:
  *   agent-sh -e ./examples/extensions/overlay-agent.ts
  *
- *   # Or copy to ~/.agent-sh/extensions/ for permanent use:
- *   cp examples/extensions/overlay-agent.ts ~/.agent-sh/extensions/
+ * Requires: npm install @xterm/headless@5.5.0 @xterm/addon-serialize@0.13.0
  */
-import type { ExtensionContext } from "agent-sh/types";
-import { formatScreenContext } from "agent-sh/utils/terminal-buffer.js";
+import type { ExtensionContext, RemoteSession } from "../../src/types.js";
+import type { RenderSurface } from "../../src/utils/compositor.js";
+import { FloatingPanel } from "../../src/utils/floating-panel.js";
 
-const BOLD = "\x1b[1m";
-const CYAN = "\x1b[36m";
-const RESET = "\x1b[0m";
+/** Adapt a FloatingPanel to the RenderSurface interface. */
+function createPanelSurface(panel: FloatingPanel): RenderSurface {
+  return {
+    write(text: string): void {
+      // Handle \r (carriage return) — overwrite the current line.
+      // The spinner uses "\r  <content>\x1b[K" to update in-place.
+      if (text.startsWith("\r")) {
+        // Strip \r and any erase-line sequences
+        const cleaned = text.replace(/^\r/, "").replace(/\x1b\[\d*K/g, "");
+        if (cleaned.trim()) {
+          panel.updateLastLine(() => cleaned);
+        }
+        return;
+      }
+
+      // Regular text — may contain newlines
+      panel.appendText(text);
+    },
+    writeLine(line: string): void {
+      panel.appendLine(line);
+    },
+    get columns(): number {
+      return panel.computeGeometry().contentW;
+    },
+  };
+}
 
-export default function activate({ bus, advise, createFloatingPanel, terminalBuffer }: ExtensionContext): void {
-  const panel = createFloatingPanel({
+export default function activate(ctx: ExtensionContext): void {
+  const { bus, registerInstruction, createRemoteSession, terminalBuffer } = ctx;
+
+  const panel = new FloatingPanel(bus, {
     trigger: "\x1c", // Ctrl+\
     dimBackground: true,
-    autoDismissMs: 2000,
+    terminalBuffer: terminalBuffer ?? undefined,
   });
 
-  // ── Inject terminal buffer into agent context ──────────────
-  if (terminalBuffer) {
-    advise("context:build-extra", (next: () => string) =>
-      formatScreenContext(terminalBuffer.readScreen(), 80, next()),
-    );
-  }
+  const panelSurface = createPanelSurface(panel);
+  let session: RemoteSession | null = null;
+
+  registerInstruction("Interactive Overlay Sessions", [
+    "When the dynamic context includes `interactive-session: true`, the user has summoned you",
+    "via a hotkey overlay from inside their live terminal. They may be in the middle of using",
+    "a program (vim, ssh, a REPL, etc.) or at a shell prompt. In this mode:",
+    "- Start with terminal_read if you need to understand what's on screen.",
+    "- Prefer terminal_keys to interact with whatever is currently running.",
+    "- Use user_shell only for running new, standalone commands — not for interacting with",
+    "  what's already on screen.",
+    "- Keep responses concise — the user is in the middle of a workflow.",
+  ].join("\n"));
+
+  // ── Panel lifecycle ────────────────────────────────────────────
 
-  // ── Panel lifecycle ────────────────────────────────────────
   panel.handlers.advise("panel:submit", (_next, query: string) => {
+    if (!session) {
+      session = createRemoteSession({
+        surface: panelSurface,
+        suppressQueryBox: true,
+        interactive: true,
+      });
+    }
     panel.setActive();
-    panel.appendLine(`${CYAN}${BOLD}❯${RESET} ${query}`);
-    panel.appendLine("");
-    bus.emit("agent:submit", { query });
+    session.submit(query);
   });
 
-  // ── Stream agent response into panel ───────────────────────
-  bus.on("agent:response-chunk", (e) => {
-    if (!panel.active) return;
-    for (const block of e.blocks) {
-      if (block.type === "text" && block.text) {
-        panel.appendText(block.text);
-      }
+  panel.handlers.advise("panel:show", (_next) => {
+    // Re-establish session if panel is shown while agent is still working
+    if (panel.active && !session) {
+      session = createRemoteSession({
+        surface: panelSurface,
+        suppressQueryBox: true,
+        interactive: true,
+      });
     }
   });
 
-  bus.on("agent:tool-started", (e) => {
-    if (!panel.active) return;
-    panel.appendLine(`▶ ${e.title}${e.displayDetail ? " " + e.displayDetail : ""}`);
-  });
-
-  bus.on("agent:tool-completed", (e) => {
-    if (!panel.active) return;
-    const mark = e.exitCode === 0 ? " ✓" : ` ✗ exit ${e.exitCode}`;
-    panel.updateLastLine((line) => line + mark);
+  // On dismiss: close session only if agent is not actively processing.
+  // If agent is still working (phase="active"), keep session alive so
+  // output buffers in the panel and agent can keep executing tools.
+  panel.handlers.advise("panel:dismiss", (next) => {
+    next();
+    if (session && !panel.processing) {
+      session.close();
+      session = null;
+    }
   });
 
   bus.on("agent:processing-done", () => {
     if (!panel.active) return;
     panel.setDone();
+    // If panel was hidden while processing (passthrough), setDone()
+    // triggers dismiss() which closes the session above.
+    // If panel is still visible, session stays for the follow-up prompt.
   });
 }