agent-sh 0.7.0 → 0.9.0

package/examples/extensions/web-access.ts

@@ -0,0 +1,327 @@
+/**
+ * Web Access extension — web search & content extraction for agent-sh.
+ *
+ * Provides two tools:
+ *   - web_search:  Search the web via Exa MCP (free, no API key)
+ *   - web_fetch:   Extract page content as clean markdown
+ *                   Fallback chain: Z.AI reader → Jina Reader → direct fetch
+ *
+ * Optional: ZAI_API_KEY environment variable (for Z.AI reader, best quality)
+ *
+ * Optional configuration (~/.agent-sh/settings.json):
+ *   {
+ *     "web-access": {
+ *       "timeout": 30000,
+ *       "searchNumResults": 5
+ *     }
+ *   }
+ *
+ * Inspired by: https://github.com/nicobailon/pi-web-access
+ */
+import type { ExtensionContext } from "agent-sh/types";
+
+// ── Constants ────────────────────────────────────────────────────────
+
+const EXA_MCP_URL = "https://mcp.exa.ai/mcp";
+
+const ZAI_BASE = "https://api.z.ai";
+const ZAI_READER_PATH = "/api/mcp/web_reader/mcp";
+
+const JINA_READER_URL = "https://r.jina.ai";
+
+// ── Exa MCP search (free, no key, no session) ───────────────────────
+
+async function exaSearch(
+  query: string,
+  numResults: number,
+  timeout: number,
+): Promise<string> {
+  const res = await fetch(EXA_MCP_URL, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Accept: "application/json, text/event-stream",
+    },
+    body: JSON.stringify({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "tools/call",
+      params: {
+        name: "web_search_exa",
+        arguments: {
+          query,
+          numResults,
+          type: "auto",
+          livecrawl: "fallback",
+          contextMaxCharacters: 3000,
+        },
+      },
+    }),
+    signal: AbortSignal.timeout(timeout),
+  });
+
+  if (!res.ok) {
+    throw new Error(`Exa MCP ${res.status}: ${(await res.text()).slice(0, 200)}`);
+  }
+
+  const body = await res.text();
+
+  // Parse SSE or JSON response
+  let parsed: any = null;
+  for (const line of body.split("\n")) {
+    if (!line.startsWith("data:")) continue;
+    const payload = line.slice(line.charAt(5) === " " ? 6 : 5).trim();
+    if (!payload) continue;
+    try {
+      const candidate = JSON.parse(payload);
+      if (candidate?.result || candidate?.error) { parsed = candidate; break; }
+    } catch { /* skip */ }
+  }
+
+  if (!parsed) {
+    try { parsed = JSON.parse(body); } catch { /* skip */ }
+  }
+
+  if (!parsed) throw new Error("Exa MCP returned empty response");
+  if (parsed.error) throw new Error(parsed.error.message ?? JSON.stringify(parsed.error));
+  if (parsed.result?.isError) {
+    const msg = parsed.result.content?.find((c: any) => c.type === "text")?.text;
+    throw new Error(msg ?? "Exa MCP returned an error");
+  }
+
+  const text = parsed.result?.content?.find(
+    (c: any) => c.type === "text" && c.text?.trim(),
+  )?.text;
+
+  if (!text) throw new Error("Exa MCP returned empty content");
+  return text;
+}
+
+// ── Z.AI MCP reader (requires API key + session) ────────────────────
+
+let zaiRpcId = 0;
+const zaiSessionId = { current: "" };
+
+async function zaiMcpPost(
+  apiKey: string,
+  body: Record<string, unknown>,
+  timeout: number,
+): Promise<any> {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    Accept: "application/json, text/event-stream",
+    Authorization: `Bearer ${apiKey}`,
+  };
+  if (zaiSessionId.current) headers["mcp-session-id"] = zaiSessionId.current;
+
+  const res = await fetch(`${ZAI_BASE}${ZAI_READER_PATH}`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(timeout),
+  });
+
+  if (!res.ok) throw new Error(`Z.AI MCP ${res.status}`);
+
+  const sid = res.headers.get("mcp-session-id");
+  if (sid) zaiSessionId.current = sid;
+
+  const ct = res.headers.get("content-type") ?? "";
+  if (ct.includes("text/event-stream")) {
+    const text = await res.text();
+    for (const line of text.split("\n")) {
+      if (!line.startsWith("data:")) continue;
+      const payload = line.slice(line.charAt(5) === " " ? 6 : 5);
+      if (!payload) continue;
+      const parsed = JSON.parse(payload);
+      if (parsed.error) throw new Error(parsed.error.message);
+      return parsed.result;
+    }
+    throw new Error("No data in Z.AI SSE response");
+  }
+
+  const json = await res.json();
+  const response = Array.isArray(json) ? json[0] : json;
+  if (response?.error) throw new Error(response.error.message);
+  return response?.result;
+}
+
+async function zaiRead(apiKey: string, url: string, timeout: number): Promise<string> {
+  // Initialize session if needed
+  if (!zaiSessionId.current) {
+    await zaiMcpPost(apiKey, {
+      jsonrpc: "2.0", id: ++zaiRpcId, method: "initialize",
+      params: {
+        protocolVersion: "2024-11-05", capabilities: {},
+        clientInfo: { name: "ash-web-access", version: "1.0.0" },
+      },
+    }, timeout);
+    await zaiMcpPost(apiKey, {
+      jsonrpc: "2.0", method: "notifications/initialized",
+    }, timeout);
+  }
+
+  const result = await zaiMcpPost(apiKey, {
+    jsonrpc: "2.0", id: ++zaiRpcId, method: "tools/call",
+    params: { name: "webReader", arguments: { url } },
+  }, timeout);
+
+  // Unwrap double-encoded JSON response
+  const textBlock = result?.content?.find((c: any) => c.type === "text" && c.text);
+  if (!textBlock) return JSON.stringify(result, null, 2);
+
+  let data: any;
+  try {
+    data = JSON.parse(textBlock.text);
+    if (typeof data === "string") data = JSON.parse(data);
+  } catch {
+    return textBlock.text;
+  }
+
+  if (data && typeof data === "object" && !Array.isArray(data)) {
+    const title = data.title ? `# ${data.title}\n\n` : "";
+    const source = data.url ? `**Source:** ${data.url}\n\n` : "";
+    const body = data.content ?? data.markdown ?? data.text ?? JSON.stringify(data, null, 2);
+    return `${title}${source}${body}`;
+  }
+
+  return typeof data === "string" ? data : JSON.stringify(data, null, 2);
+}
+
+// ── Jina Reader (free, no key) ───────────────────────────────────────
+
+async function jinaRead(url: string, timeout: number): Promise<string> {
+  const res = await fetch(`${JINA_READER_URL}/${url}`, {
+    headers: { Accept: "text/markdown", "X-Return-Format": "markdown" },
+    signal: AbortSignal.timeout(timeout),
+  });
+  if (!res.ok) throw new Error(`Jina Reader ${res.status}`);
+  return res.text();
+}
+
+// ── Direct fetch (last resort) ───────────────────────────────────────
+
+async function directFetch(url: string, timeout: number): Promise<string> {
+  const res = await fetch(url, {
+    headers: {
+      "User-Agent":
+        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 " +
+        "(KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
+    },
+    signal: AbortSignal.timeout(timeout),
+    redirect: "follow",
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status}: ${res.statusText}`);
+  const ct = res.headers.get("content-type") ?? "";
+  if (ct.includes("application/json")) return JSON.stringify(await res.json(), null, 2);
+  return res.text();
+}
+
+// ── Extension entry point ────────────────────────────────────────────
+
+export default function activate(ctx: ExtensionContext) {
+  const apiKey = process.env.ZAI_API_KEY ?? "";
+
+  const config = ctx.getExtensionSettings("web-access", {
+    timeout: 30000,
+    searchNumResults: 5,
+  });
+
+  const timeout = config.timeout ?? 30000;
+  const numResults = config.searchNumResults ?? 5;
+
+  // ── Tool: web_search (Exa MCP, free) ────────────────────────────
+
+  ctx.registerTool({
+    name: "web_search",
+    displayName: "Web Search",
+    description:
+      "Search the web and return results with titles, URLs, and content snippets. " +
+      "Free, no API key required. Powered by Exa.",
+    input_schema: {
+      type: "object" as const,
+      properties: {
+        query: {
+          type: "string",
+          description: "The search query",
+        },
+        numResults: {
+          type: "number",
+          description: `Number of results (default: ${numResults}, max: 10)`,
+        },
+      },
+      required: ["query"],
+    },
+    async execute(args: { query: string; numResults?: number }) {
+      const n = Math.min(args.numResults ?? numResults, 10);
+      try {
+        const results = await exaSearch(args.query, n, timeout);
+        return { content: results, exitCode: 0, isError: false };
+      } catch (err: any) {
+        return { content: `Search failed: ${err.message}`, exitCode: 1, isError: true };
+      }
+    },
+    formatCall(args: { query: string }) {
+      return `Searching: "${args.query}"`;
+    },
+  });
+
+  // ── Tool: web_fetch ─────────────────────────────────────────────
+
+  ctx.registerTool({
+    name: "web_fetch",
+    displayName: "Web Fetch",
+    description:
+      "Fetch a URL and extract its content as clean markdown. " +
+      "Handles web pages, articles, and documentation. " +
+      "Uses Z.AI reader (best quality), Jina Reader, or direct fetch as fallback.",
+    input_schema: {
+      type: "object" as const,
+      properties: {
+        url: {
+          type: "string",
+          description: "The URL to fetch",
+        },
+        raw: {
+          type: "boolean",
+          description:
+            "If true, fetch raw content directly (useful for JSON APIs, raw text files)",
+        },
+      },
+      required: ["url"],
+    },
+    async execute(args: { url: string; raw?: boolean }) {
+      if (args.raw) {
+        try {
+          const content = await directFetch(args.url, timeout);
+          return { content, exitCode: 0, isError: false };
+        } catch (err: any) {
+          return { content: `Fetch failed: ${err.message}`, exitCode: 1, isError: true };
+        }
+      }
+
+      // Fallback chain: Z.AI reader → Jina Reader → direct fetch
+      if (apiKey) {
+        try {
+          const content = await zaiRead(apiKey, args.url, timeout);
+          return { content, exitCode: 0, isError: false };
+        } catch { /* fall through */ }
+      }
+
+      try {
+        const content = await jinaRead(args.url, timeout);
+        return { content, exitCode: 0, isError: false };
+      } catch { /* fall through */ }
+
+      try {
+        const content = await directFetch(args.url, timeout);
+        return { content, exitCode: 0, isError: false };
+      } catch (err: any) {
+        return { content: `All fetch methods failed: ${err.message}`, exitCode: 1, isError: true };
+      }
+    },
+    formatCall(args: { url: string }) {
+      return `Fetching: ${args.url}`;
+    },
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sh",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "A shell-first terminal where AI is one keystroke away",
   "type": "module",
   "main": "dist/core.js",
@@ -26,6 +26,14 @@
       "types": "./dist/settings.d.ts",
       "default": "./dist/settings.js"
     },
+    "./extension-loader": {
+      "types": "./dist/extension-loader.d.ts",
+      "default": "./dist/extension-loader.js"
+    },
+    "./extensions": {
+      "types": "./dist/extensions/index.d.ts",
+      "default": "./dist/extensions/index.js"
+    },
     "./utils/stream-transform": {
       "types": "./dist/utils/stream-transform.d.ts",
       "default": "./dist/utils/stream-transform.js"

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

@@ -1,11 +0,0 @@
-/**
- * Built-in overlay agent.
- *
- * Provides a hotkey (Ctrl+\) to summon the agent from anywhere — even
- * 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
- */
-import type { ExtensionContext } from "../types.js";
-export default function activate({ bus, createFloatingPanel }: ExtensionContext): void;

package/dist/extensions/overlay-agent.js

@@ -1,43 +0,0 @@
-const BOLD = "\x1b[1m";
-const CYAN = "\x1b[36m";
-const RESET = "\x1b[0m";
-export default function activate({ bus, createFloatingPanel }) {
-    const panel = createFloatingPanel({
-        trigger: "\x1c", // Ctrl+\
-        dimBackground: true,
-        autoDismissMs: 2000,
-    });
-    // ── Panel lifecycle ────────────────────────────────────────
-    panel.handlers.advise("panel:submit", (_next, query) => {
-        panel.setActive();
-        panel.appendLine(`${CYAN}${BOLD}❯${RESET} ${query}`);
-        panel.appendLine("");
-        bus.emit("agent: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);
-            }
-        }
-    });
-    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);
-    });
-    bus.on("agent:processing-done", () => {
-        if (!panel.active)
-            return;
-        panel.setDone();
-    });
-}

package/examples/extensions/terminal-buffer.ts

@@ -1,184 +0,0 @@
-/**
- * Terminal buffer extension.
- *
- * Maintains a headless xterm.js terminal fed from raw PTY data.
- * Provides an accurate, clean-text snapshot of the terminal screen
- * that the agent can use for context — handling ANSI codes, cursor
- * movement, alternate screen (vim/htop), and line wrapping correctly.
- *
- * 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
- *
- * Usage:
- *   agent-sh -e ./examples/extensions/terminal-buffer.ts
- *
- *   # Or copy to ~/.agent-sh/extensions/ for permanent use:
- *   cp examples/extensions/terminal-buffer.ts ~/.agent-sh/extensions/
- */
-import type { ExtensionContext } from "agent-sh/types";
-
-/** Wait for PTY output to settle after sending keystrokes. */
-function settle(ms = 100): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-/** Interpret C-style escape sequences in a string (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;
-  });
-}
-
-export default function activate({ bus, terminalBuffer: tb, registerTool }: ExtensionContext): void {
-  if (!tb) {
-    console.warn("terminal-buffer: @xterm/headless not installed — extension disabled");
-    return;
-  }
-
-  // ── Agent tools ─────────────────────────────────────────────
-  // Context injection is intentionally NOT done here — the terminal
-  // buffer content would bloat every agent message.  The agent can
-  // call terminal_read on demand, and the overlay extension injects
-  // context only when the overlay is active.
-
-  registerTool({
-    name: "terminal_read",
-    description:
-      "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.",
-    input_schema: {
-      type: "object",
-      properties: {},
-    },
-    showOutput: true,
-
-    getDisplayInfo: () => ({
-      kind: "read" as const,
-      icon: "⊞",
-      locations: [],
-    }),
-
-    async execute() {
-      const { text, altScreen, cursorX, cursorY } = tb.readScreen();
-      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 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\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: (args) => ({
-      kind: "execute" as const,
-      icon: "⌨",
-      locations: [],
-    }),
-
-    formatCall: (args) => {
-      const keys = args.keys as string;
-      // Show a readable version of the keys — handle both literal
-      // escape strings (\\x1b) and actual bytes (\x1b)
-      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;
-
-      // Force PTY output visible so the user sees the program's response.
-      // Stays visible for the rest of agent processing — Shell resets
-      // paused=false on processing-done anyway.
-      bus.emit("shell:stdout-show", {});
-      process.stdout.write("\n");
-      bus.emit("shell:pty-write", { data: keys });
-
-      // Wait for the terminal to process the keystrokes and render
-      await settle(settleMs);
-
-      // Return the screen state after the keystrokes
-      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,
-      };
-    },
-  });
-
-  // ── Bus snapshot for other extensions ───────────────────────
-
-  bus.on("shell:buffer-request", () => {
-    const { text, altScreen, cursorX, cursorY } = tb.readScreen();
-    bus.emit("shell:buffer-snapshot", {
-      text,
-      altScreen,
-      cursor: { x: cursorX, y: cursorY },
-    });
-  });
-}