agent-sh 0.8.0 → 0.10.0

package/examples/extensions/web-access.ts

@@ -0,0 +1,335 @@
+/**
+ * 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;
+
+  // ── 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({
+    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.8.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"
@@ -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"
@@ -33,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": [
@@ -70,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/overlay-agent.d.ts

@@ -1,14 +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.
- *
- * Rendering reuses the shared tui:render-* handlers so that extensions
- * advising those handlers affect both the main TUI and the overlay.
- *
- * 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;