agent-sh 0.8.0 → 0.9.0

package/examples/extensions/tmux-pane.ts

@@ -0,0 +1,307 @@
+/**
+ * Tmux side-pane extension.
+ *
+ * Two modes:
+ *   /split  — agent output renders in the side pane, queries typed
+ *             in the main shell (> prompt).
+ *   /rsplit — reverse split: the side pane has its own input prompt,
+ *             the agent can see and control the main pane via
+ *             terminal_read / terminal_keys.
+ *
+ * Both modes use createRemoteSession() which handles compositor
+ * routing, shell lifecycle, and chrome suppression automatically.
+ *
+ * Usage:
+ *   ash -e ./examples/extensions/tmux-pane.ts
+ *
+ *   # Or install permanently
+ *   cp examples/extensions/tmux-pane.ts ~/.agent-sh/extensions/
+ */
+import * as fs from "node:fs";
+import * as net from "node:net";
+import * as os from "node:os";
+import * as path from "node:path";
+import { execSync, spawn } from "node:child_process";
+import type { ExtensionContext, RenderSurface, RemoteSession } from "agent-sh/types";
+
+// ── Helpers ─────────────────────────────────────────────────────
+
+function inTmux(): boolean {
+  return !!process.env.TMUX;
+}
+
+function tmux(...args: string[]): string {
+  return execSync(
+    "tmux " + args.map(a => `'${a.replace(/'/g, "'\\''")}'`).join(" "),
+    { encoding: "utf-8" },
+  ).trim();
+}
+
+function getPaneWidth(paneId: string): number {
+  try {
+    return parseInt(tmux("display-message", "-p", "-t", paneId, "#{pane_width}"), 10) || 80;
+  } catch {
+    return 80;
+  }
+}
+
+function paneExists(paneId: string): boolean {
+  try {
+    tmux("display-message", "-p", "-t", paneId, "#{pane_id}");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ── Chat client script (runs in rsplit pane) ────────────────────
+
+const CHAT_CLIENT_SCRIPT = `
+const net = require("net");
+const readline = require("readline");
+
+const sockPath = process.argv[2];
+if (!sockPath) { console.error("No socket path"); process.exit(1); }
+
+const sock = net.createConnection(sockPath);
+const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+sock.on("data", (data) => {
+  readline.clearLine(process.stdout, 0);
+  readline.cursorTo(process.stdout, 0);
+  process.stdout.write(data.toString());
+  rl.prompt(true);
+});
+
+sock.on("end", () => process.exit(0));
+sock.on("error", () => process.exit(1));
+
+rl.setPrompt("\\x1b[36m❯\\x1b[0m ");
+rl.prompt();
+
+rl.on("line", (line) => {
+  const trimmed = line.trim();
+  if (!trimmed) { rl.prompt(); return; }
+  sock.write(trimmed + "\\n");
+});
+
+rl.on("close", () => { sock.end(); process.exit(0); });
+`;
+
+// ── Surface factory ─────────────────────────────────────────────
+
+function createSurface(
+  paneId: string,
+  ttyFd: fs.WriteStream,
+  socketClient: () => net.Socket | undefined,
+): RenderSurface {
+  let cachedWidth = getPaneWidth(paneId);
+  let lastWidthCheck = Date.now();
+
+  return {
+    write(text: string): void {
+      // In rsplit mode, route through socket so client can manage prompt
+      const c = socketClient();
+      if (c && !c.destroyed) {
+        try { c.write(text); } catch {}
+        return;
+      }
+      // In split mode (or fallback), write directly to tty
+      if (ttyFd.destroyed) return;
+      try { ttyFd.write(text); } catch {}
+    },
+    writeLine(line: string): void {
+      this.write(line + "\n");
+    },
+    get columns(): number {
+      const now = Date.now();
+      if (now - lastWidthCheck > 2000) {
+        cachedWidth = getPaneWidth(paneId);
+        lastWidthCheck = now;
+      }
+      return cachedWidth;
+    },
+  };
+}
+
+// ── Pane state ──────────────────────────────────────────────────
+
+type PaneMode = "split" | "rsplit";
+
+interface PaneState {
+  mode: PaneMode;
+  paneId: string;
+  ttyFd: fs.WriteStream;
+  session: RemoteSession;
+  // rsplit-mode only
+  server?: net.Server;
+  client?: net.Socket;
+  sockPath?: string;
+  scriptPath?: string;
+}
+
+// ── Extension ───────────────────────────────────────────────────
+
+export default function activate(ctx: ExtensionContext): void {
+  const { bus, registerCommand, registerInstruction, createRemoteSession } = ctx;
+
+  if (!inTmux()) return;
+
+  let state: PaneState | null = null;
+
+  registerInstruction("Tmux Interactive Session", [
+    "When the dynamic context includes `interactive-session: true`, the user is chatting",
+    "with you in a side pane next to their terminal. They may have a program running in",
+    "the other pane (vim, htop, a REPL, etc.). In this mode:",
+    "- Use terminal_read to see what's on their screen.",
+    "- Use terminal_keys to interact with their running program.",
+    "- Use user_shell only for standalone commands, not for interacting with what's on screen.",
+    "- Keep responses concise.",
+  ].join("\n"));
+
+  // ── Open / close ──────────────────────────────────────────────
+
+  function openSplit(): void {
+    if (state) close();
+
+    try {
+      const paneId = tmux(
+        "split-window", "-h", "-l", "45%",
+        "-P", "-F", "#{pane_id}", "cat",
+      ).trim();
+      execSync("sleep 0.1");
+
+      const tty = tmux("display-message", "-p", "-t", paneId, "#{pane_tty}");
+      const ttyFd = fs.createWriteStream(tty, { flags: "w" });
+      ttyFd.on("error", () => destroyStale());
+
+      const surface = createSurface(paneId, ttyFd, () => undefined);
+      const session = createRemoteSession({ surface });
+
+      state = { mode: "split", paneId, ttyFd, session };
+      surface.writeLine("\x1b[2m── agent output ──\x1b[0m\n");
+      bus.emit("ui:info", { message: "Split pane opened (/split to close, /rsplit for interactive)." });
+    } catch (e) {
+      bus.emit("ui:error", {
+        message: `Failed to open split: ${e instanceof Error ? e.message : String(e)}`,
+      });
+    }
+  }
+
+  function openRsplit(): void {
+    if (state) close();
+
+    try {
+      const sockPath = path.join(os.tmpdir(), `agent-sh-chat-${process.pid}.sock`);
+      try { fs.unlinkSync(sockPath); } catch {}
+
+      let client: net.Socket | undefined;
+
+      const server = net.createServer((conn) => {
+        client = conn;
+        if (state) state.client = conn;
+        conn.on("data", (data) => {
+          for (const line of data.toString().split("\n")) {
+            const trimmed = line.trim();
+            if (trimmed) session.submit(trimmed);
+          }
+        });
+        conn.on("end", () => { client = undefined; if (state) state.client = undefined; });
+        conn.on("error", () => { client = undefined; if (state) state.client = undefined; });
+      });
+      server.listen(sockPath);
+
+      const scriptPath = path.join(os.tmpdir(), `agent-sh-chat-${process.pid}.js`);
+      fs.writeFileSync(scriptPath, CHAT_CLIENT_SCRIPT);
+
+      const paneId = tmux(
+        "split-window", "-h", "-l", "45%",
+        "-P", "-F", "#{pane_id}",
+        "node", scriptPath, sockPath,
+      ).trim();
+      execSync("sleep 0.2");
+
+      const tty = tmux("display-message", "-p", "-t", paneId, "#{pane_tty}");
+      const ttyFd = fs.createWriteStream(tty, { flags: "w" });
+      ttyFd.on("error", () => destroyStale());
+
+      const surface = createSurface(paneId, ttyFd, () => client);
+      const session = createRemoteSession({
+        surface,
+        suppressQueryBox: true,
+        interactive: true,
+      });
+
+      state = { mode: "rsplit", paneId, ttyFd, session, server, client, sockPath, scriptPath };
+      bus.emit("ui:info", { message: "Reverse split opened (/rsplit to close, /split for output-only)." });
+    } catch (e) {
+      bus.emit("ui:error", {
+        message: `Failed to open rsplit: ${e instanceof Error ? e.message : String(e)}`,
+      });
+      if (state) close();
+    }
+  }
+
+  function close(): void {
+    if (!state) return;
+    const s = state;
+    state = null;
+
+    s.session.close();
+    if (s.client) { try { s.client.end(); } catch {} }
+    if (s.server) { try { s.server.close(); } catch {} }
+    try { s.ttyFd.end(); } catch {}
+    try { tmux("kill-pane", "-t", s.paneId); } catch {}
+    if (s.sockPath) { try { fs.unlinkSync(s.sockPath); } catch {} }
+    if (s.scriptPath) { try { fs.unlinkSync(s.scriptPath); } catch {} }
+  }
+
+  function destroyStale(): void {
+    if (!state) return;
+    const s = state;
+    state = null;
+
+    s.session.close();
+    if (s.client) { try { s.client.end(); } catch {} }
+    if (s.server) { try { s.server.close(); } catch {} }
+    try { s.ttyFd.end(); } catch {}
+    if (s.sockPath) { try { fs.unlinkSync(s.sockPath); } catch {} }
+    if (s.scriptPath) { try { fs.unlinkSync(s.scriptPath); } catch {} }
+  }
+
+  // ── Commands ──────────────────────────────────────────────────
+
+  registerCommand("split", "Toggle tmux side pane for agent output", (args) => {
+    const cmd = args.trim().toLowerCase();
+    if (cmd === "close") return close();
+    if (cmd === "open") return openSplit();
+    if (state?.mode === "split") close(); else openSplit();
+  });
+
+  registerCommand("rsplit", "Toggle interactive tmux side pane (reverse split)", (args) => {
+    const cmd = args.trim().toLowerCase();
+    if (cmd === "close") return close();
+    if (cmd === "open") return openRsplit();
+    if (state?.mode === "rsplit") close(); else openRsplit();
+  });
+
+  // ── Lifecycle events ──────────────────────────────────────────
+
+  // In split mode, redraw prompt immediately after query submit.
+  bus.on("agent:query", () => {
+    if (state?.mode !== "split") return;
+    setImmediate(() => bus.emit("shell:pty-write", { data: "\n" }));
+  });
+
+  // In rsplit mode, re-prompt the client after agent finishes.
+  bus.on("agent:processing-done", () => {
+    if (!state) return;
+    if (!paneExists(state.paneId)) { destroyStale(); return; }
+    if (state.mode === "rsplit" && state.client && !state.client.destroyed) {
+      state.client.write("\n");
+    }
+    state.session.surface.writeLine("");
+  });
+
+  process.on("exit", () => { if (state) close(); });
+}

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.8.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,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;