agent-sh 0.8.0 → 0.10.0

package/examples/extensions/peer-mesh.ts

@@ -0,0 +1,565 @@
+/**
+ * Peer mesh — cross-instance communication for agent-sh.
+ *
+ * Lets all running ash instances discover each other and communicate.
+ * Inspired by Ray's @ray.remote: opt-in exposure of named handlers,
+ * transparent network calls, automatic discovery.
+ *
+ * What this extension provides:
+ *   1. PeerServer — Unix socket server + peer file registry + client
+ *   2. Standard exposed handlers — terminal read, context, search
+ *   3. Agent tools — peers, peer_terminal, peer_history, peer_search
+ *   4. Handler registry API — peer:call, peer:discover, peer:expose
+ *      for other extensions to use
+ *
+ * Usage:
+ *   ash -e ./examples/extensions/peer-mesh.ts
+ *
+ *   # Or install permanently
+ *   cp examples/extensions/peer-mesh.ts ~/.agent-sh/extensions/
+ *
+ * Other extensions can depend on this via the handler registry:
+ *   ctx.define("my:data", () => computeData());
+ *   ctx.call("peer:expose", "my:data");
+ *   const result = await ctx.call("peer:call", peerId, "my:data");
+ */
+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 type { ExtensionContext } from "agent-sh/types";
+
+// ── Types ──────────────────────────────────────────────────────
+
+interface PeerInfo {
+  id: string;
+  pid: number;
+  cwd: string;
+  socketPath: string;
+  startTime: number;
+}
+
+interface RpcRequest {
+  method: string;
+  args: unknown[];
+}
+
+interface RpcResponse {
+  ok: boolean;
+  result?: unknown;
+  error?: string;
+}
+
+// ── Paths ──────────────────────────────────────────────────────
+
+const PEERS_DIR = path.join(os.homedir(), ".agent-sh", "peers");
+
+function peerFilePath(id: string): string {
+  return path.join(PEERS_DIR, `${id}.json`);
+}
+
+function socketPath(pid: number): string {
+  return path.join(os.tmpdir(), `agent-sh-peer-${pid}.sock`);
+}
+
+// ── PeerServer ─────────────────────────────────────────────────
+
+class PeerServer {
+  private server: net.Server | null = null;
+  private exposed = new Set<string>();
+  private readonly info: PeerInfo;
+  private readonly callHandler: (name: string, ...args: unknown[]) => unknown;
+
+  constructor(
+    instanceId: string,
+    cwd: string,
+    callHandler: (name: string, ...args: unknown[]) => unknown,
+  ) {
+    this.callHandler = callHandler;
+    this.info = {
+      id: instanceId,
+      pid: process.pid,
+      cwd,
+      socketPath: socketPath(process.pid),
+      startTime: Date.now(),
+    };
+  }
+
+  // ── Lifecycle ──────────────────────────────────────────────
+
+  start(): void {
+    // Ensure peers directory exists
+    fs.mkdirSync(PEERS_DIR, { recursive: true });
+
+    // Clean up stale socket
+    try { fs.unlinkSync(this.info.socketPath); } catch {}
+
+    // Start Unix socket server
+    this.server = net.createServer((conn) => this.handleConnection(conn));
+    this.server.on("error", () => {}); // swallow server errors
+    this.server.listen(this.info.socketPath);
+
+    // Register peer file
+    fs.writeFileSync(peerFilePath(this.info.id), JSON.stringify(this.info));
+
+    // Cleanup on exit
+    const cleanup = () => this.stop();
+    process.on("exit", cleanup);
+    process.on("SIGTERM", () => { cleanup(); process.exit(0); });
+    process.on("SIGINT", () => { cleanup(); process.exit(0); });
+  }
+
+  stop(): void {
+    if (this.server) {
+      try { this.server.close(); } catch {}
+      this.server = null;
+    }
+    try { fs.unlinkSync(this.info.socketPath); } catch {}
+    try { fs.unlinkSync(peerFilePath(this.info.id)); } catch {}
+  }
+
+  // ── Expose / discover / call ───────────────────────────────
+
+  expose(name: string): void {
+    this.exposed.add(name);
+  }
+
+  discover(): PeerInfo[] {
+    const peers: PeerInfo[] = [];
+    let entries: string[];
+    try { entries = fs.readdirSync(PEERS_DIR); } catch { return []; }
+
+    for (const entry of entries) {
+      if (!entry.endsWith(".json")) continue;
+      try {
+        const raw = fs.readFileSync(path.join(PEERS_DIR, entry), "utf-8");
+        const info: PeerInfo = JSON.parse(raw);
+        // Skip self
+        if (info.id === this.info.id) continue;
+        // Check if process is alive
+        try { process.kill(info.pid, 0); } catch {
+          // Stale — prune
+          try { fs.unlinkSync(path.join(PEERS_DIR, entry)); } catch {}
+          continue;
+        }
+        peers.push(info);
+      } catch {
+        // Malformed file — skip
+      }
+    }
+    return peers;
+  }
+
+  async call(peerId: string, method: string, ...args: unknown[]): Promise<unknown> {
+    // Find peer socket path
+    const peers = this.discover();
+    const peer = peers.find((p) => p.id === peerId);
+    if (!peer) throw new Error(`Peer "${peerId}" not found`);
+
+    return this.callSocket(peer.socketPath, method, args);
+  }
+
+  // ── Private ────────────────────────────────────────────────
+
+  private handleConnection(conn: net.Socket): void {
+    let buffer = "";
+    conn.on("data", (data) => {
+      buffer += data.toString();
+      const newlineIdx = buffer.indexOf("\n");
+      if (newlineIdx === -1) return;
+
+      const line = buffer.slice(0, newlineIdx);
+      buffer = buffer.slice(newlineIdx + 1);
+
+      let response: RpcResponse;
+      try {
+        const req: RpcRequest = JSON.parse(line);
+        if (!this.exposed.has(req.method)) {
+          response = { ok: false, error: `Handler "${req.method}" is not exposed` };
+        } else {
+          const result = this.callHandler(req.method, ...(req.args ?? []));
+          response = { ok: true, result };
+        }
+      } catch (e) {
+        response = { ok: false, error: e instanceof Error ? e.message : String(e) };
+      }
+
+      try {
+        conn.write(JSON.stringify(response) + "\n");
+      } catch {}
+      conn.end();
+    });
+
+    conn.on("error", () => {});
+    // Timeout in case client hangs
+    conn.setTimeout(5000, () => conn.destroy());
+  }
+
+  private callSocket(sockPath: string, method: string, args: unknown[]): Promise<unknown> {
+    return new Promise((resolve, reject) => {
+      const conn = net.createConnection(sockPath);
+      let buffer = "";
+      let settled = false;
+
+      const settle = (fn: () => void) => {
+        if (settled) return;
+        settled = true;
+        fn();
+      };
+
+      conn.on("connect", () => {
+        const req: RpcRequest = { method, args };
+        conn.write(JSON.stringify(req) + "\n");
+      });
+
+      conn.on("data", (data) => {
+        buffer += data.toString();
+        const newlineIdx = buffer.indexOf("\n");
+        if (newlineIdx === -1) return;
+
+        const line = buffer.slice(0, newlineIdx);
+        try {
+          const resp: RpcResponse = JSON.parse(line);
+          settle(() => resp.ok ? resolve(resp.result) : reject(new Error(resp.error)));
+        } catch (e) {
+          settle(() => reject(e));
+        }
+        conn.end();
+      });
+
+      conn.on("error", (e) => settle(() => reject(e)));
+      conn.setTimeout(5000, () => settle(() => {
+        reject(new Error("Peer call timed out"));
+        conn.destroy();
+      }));
+    });
+  }
+}
+
+// ── Extension ──────────────────────────────────────────────────
+
+export default function activate(ctx: ExtensionContext): void {
+  const { bus, contextManager, registerCommand, registerTool, registerInstruction, define } = ctx;
+  const startTime = Date.now();
+
+  const server = new PeerServer(ctx.instanceId, contextManager.getCwd(), (...args) => ctx.call(...args));
+  server.start();
+
+  // ── Standard handlers (define + expose) ────────────────────
+
+  define("peer:info", () => ({
+    id: ctx.instanceId,
+    pid: process.pid,
+    cwd: contextManager.getCwd(),
+    uptime: Math.round((Date.now() - startTime) / 1000),
+  }));
+  server.expose("peer:info");
+
+  define("peer:terminal-read", () => {
+    const tb = ctx.terminalBuffer;
+    if (!tb) return { text: "(terminal buffer not available)", altScreen: false };
+    return tb.readScreen({ includeScrollback: true });
+  });
+  server.expose("peer:terminal-read");
+
+  define("peer:context-recent", (n: number = 15) => contextManager.getRecentSummary(n));
+  server.expose("peer:context-recent");
+
+  define("peer:context-search", (query: string) => contextManager.search(query));
+  server.expose("peer:context-search");
+
+  // ── Inter-peer messaging ───────────────────────────────────
+
+  interface InboxEntry { from: string; text: string; at: number; }
+  const inbox: InboxEntry[] = [];
+  const INBOX_MAX = 100;
+
+  const pending: InboxEntry[] = [];
+
+  define("peer:message", (from: string, text: string) => {
+    if (typeof from !== "string" || typeof text !== "string") {
+      throw new Error("peer:message requires (from: string, text: string)");
+    }
+    const entry: InboxEntry = { from, text, at: Date.now() };
+    inbox.push(entry);
+    if (inbox.length > INBOX_MAX) inbox.splice(0, inbox.length - INBOX_MAX);
+    pending.push(entry);
+    bus.emit("peer:message-received", entry);
+    bus.emit("ui:info", { message: `[peer ${from}] ${text}` });
+    setTimeout(drainPending, 100);
+    return { ok: true };
+  });
+  server.expose("peer:message");
+
+  // Drain pending peer messages by injecting a synthetic user turn.
+  // Only one submission per processing cycle — wait for agent:processing-done
+  // before releasing the next batch.
+  let busy = false;
+
+  function drainPending(): void {
+    if (busy || pending.length === 0) return;
+    const batch = pending.splice(0, pending.length);
+    const lines = batch.map((e) => `[from peer ${e.from}] ${e.text}`);
+    const query = [
+      "You received message(s) from other peer(s) in the mesh:",
+      "",
+      ...lines,
+      "",
+      "Decide whether to reply (via `peer_send`), act on the request, or note and continue.",
+    ].join("\n");
+    busy = true;
+    bus.emit("agent:submit", { query });
+  }
+
+  bus.on("agent:processing-done", () => {
+    busy = false;
+    setTimeout(drainPending, 100);
+  });
+
+  // ── Handler registry API (for other extensions) ────────────
+
+  define("peer:discover", () => server.discover());
+  define("peer:call", (peerId: string, method: string, ...args: unknown[]) =>
+    server.call(peerId, method, ...args));
+  define("peer:expose", (name: string) => server.expose(name));
+
+  // ── Agent tools ────────────────────────────────────────────
+
+  registerTool({
+    name: "peers",
+    description: "List all running agent-sh instances that can be communicated with.",
+    input_schema: { type: "object", properties: {}, required: [] },
+    showOutput: false,
+    getDisplayInfo: () => ({ kind: "search" as const }),
+    formatCall: () => "discovering peers",
+
+    async execute() {
+      const peers = server.discover();
+      if (peers.length === 0) {
+        return { content: "No other agent-sh instances found.", exitCode: 0, isError: false };
+      }
+      const lines = peers.map((p) =>
+        `- id: ${p.id}, pid: ${p.pid}, cwd: ${p.cwd}, uptime: ${Math.round((Date.now() - p.startTime) / 1000)}s`
+      );
+      return {
+        content: `Found ${peers.length} peer(s):\n${lines.join("\n")}`,
+        exitCode: 0,
+        isError: false,
+      };
+    },
+
+    formatResult: (_args, result) => ({
+      summary: result.content.startsWith("No") ? "none found" : result.content.split("\n")[0],
+    }),
+  });
+
+  registerTool({
+    name: "peer_terminal",
+    description: "Read the terminal screen content of another running agent-sh instance. Shows what is currently visible on their terminal.",
+    input_schema: {
+      type: "object",
+      properties: {
+        peer_id: { type: "string", description: "The instance ID of the peer (from the peers tool)." },
+      },
+      required: ["peer_id"],
+    },
+    showOutput: false,
+    getDisplayInfo: () => ({ kind: "read" as const }),
+    formatCall: (args) => `peer ${args.peer_id}`,
+
+    async execute(args) {
+      try {
+        const screen = await server.call(args.peer_id as string, "peer:terminal-read") as any;
+        const text = screen?.text?.trim() || "(empty screen)";
+        const alt = screen?.altScreen ? " [alternate screen active]" : "";
+        return {
+          content: `Terminal content from peer ${args.peer_id}${alt}:\n\n${text}`,
+          exitCode: 0,
+          isError: false,
+        };
+      } catch (e) {
+        return {
+          content: `Failed to read peer terminal: ${e instanceof Error ? e.message : String(e)}`,
+          exitCode: 1,
+          isError: true,
+        };
+      }
+    },
+
+    formatResult: (_args, result) => ({
+      summary: result.isError ? "failed" : `${result.content.split("\n").length - 2} lines`,
+    }),
+  });
+
+  registerTool({
+    name: "peer_history",
+    description: "Get the recent shell command history from another running agent-sh instance.",
+    input_schema: {
+      type: "object",
+      properties: {
+        peer_id: { type: "string", description: "The instance ID of the peer." },
+        count: { type: "number", description: "Number of recent exchanges to return (default: 15)." },
+      },
+      required: ["peer_id"],
+    },
+    showOutput: false,
+    getDisplayInfo: () => ({ kind: "read" as const }),
+    formatCall: (args) => `peer ${args.peer_id}`,
+
+    async execute(args) {
+      try {
+        const n = (args.count as number) || 15;
+        const summary = await server.call(args.peer_id as string, "peer:context-recent", n) as string;
+        return { content: summary || "(no history)", exitCode: 0, isError: false };
+      } catch (e) {
+        return {
+          content: `Failed to read peer history: ${e instanceof Error ? e.message : String(e)}`,
+          exitCode: 1,
+          isError: true,
+        };
+      }
+    },
+
+    formatResult: (_args, result) => ({
+      summary: result.isError ? "failed" : `${result.content.split("\n").length} lines`,
+    }),
+  });
+
+  registerTool({
+    name: "peer_search",
+    description: "Search another agent-sh instance's shell context by keyword or regex.",
+    input_schema: {
+      type: "object",
+      properties: {
+        peer_id: { type: "string", description: "The instance ID of the peer." },
+        query: { type: "string", description: "Search query (keyword or regex)." },
+      },
+      required: ["peer_id", "query"],
+    },
+    showOutput: false,
+    getDisplayInfo: () => ({ kind: "search" as const }),
+    formatCall: (args) => `peer ${args.peer_id}: "${args.query}"`,
+
+    async execute(args) {
+      try {
+        const results = await server.call(
+          args.peer_id as string, "peer:context-search", args.query as string,
+        ) as string;
+        return { content: results || "(no matches)", exitCode: 0, isError: false };
+      } catch (e) {
+        return {
+          content: `Failed to search peer context: ${e instanceof Error ? e.message : String(e)}`,
+          exitCode: 1,
+          isError: true,
+        };
+      }
+    },
+
+    formatResult: (_args, result) => ({
+      summary: result.isError ? "failed" : `${result.content.split("\n").length} lines`,
+    }),
+  });
+
+  registerTool({
+    name: "peer_send",
+    description: "Send a text message to another running agent-sh peer. The peer will see it in their UI and on their next turn.",
+    input_schema: {
+      type: "object",
+      properties: {
+        peer_id: { type: "string", description: "The instance ID of the peer (from the peers tool)." },
+        text: { type: "string", description: "Message body." },
+      },
+      required: ["peer_id", "text"],
+    },
+    showOutput: false,
+    getDisplayInfo: () => ({ kind: "write" as const }),
+    formatCall: (args) => `peer ${args.peer_id}: "${String(args.text).slice(0, 40)}"`,
+
+    async execute(args) {
+      try {
+        await server.call(args.peer_id as string, "peer:message", ctx.instanceId, args.text as string);
+        return { content: `Sent to peer ${args.peer_id}.`, exitCode: 0, isError: false };
+      } catch (e) {
+        return {
+          content: `Failed to send: ${e instanceof Error ? e.message : String(e)}`,
+          exitCode: 1,
+          isError: true,
+        };
+      }
+    },
+
+    formatResult: (_args, result) => ({
+      summary: result.isError ? "failed" : "sent",
+    }),
+  });
+
+  registerTool({
+    name: "peer_inbox",
+    description: "Read recent messages received from other peers via peer_send.",
+    input_schema: {
+      type: "object",
+      properties: {
+        count: { type: "number", description: "Number of recent messages to return (default: 20)." },
+      },
+      required: [],
+    },
+    showOutput: false,
+    getDisplayInfo: () => ({ kind: "read" as const }),
+    formatCall: () => "reading inbox",
+
+    async execute(args) {
+      const n = (args.count as number) || 20;
+      const recent = inbox.slice(-n);
+      if (recent.length === 0) {
+        return { content: "(inbox empty)", exitCode: 0, isError: false };
+      }
+      const lines = recent.map((e) => {
+        const ago = Math.round((Date.now() - e.at) / 1000);
+        return `[${ago}s ago] ${e.from}: ${e.text}`;
+      });
+      return { content: lines.join("\n"), exitCode: 0, isError: false };
+    },
+
+    formatResult: (_args, result) => ({
+      summary: result.content === "(inbox empty)" ? "empty" : `${result.content.split("\n").length} msg`,
+    }),
+  });
+
+  // ── Slash command ──────────────────────────────────────────
+
+  registerCommand("peers", "List running agent-sh peer instances", () => {
+    const peers = server.discover();
+    if (peers.length === 0) {
+      bus.emit("ui:info", { message: "No peers found." });
+      return;
+    }
+    const lines = peers.map((p) => {
+      const uptime = Math.round((Date.now() - p.startTime) / 1000);
+      return `  ${p.id}  pid=${p.pid}  cwd=${p.cwd}  ${uptime}s`;
+    });
+    bus.emit("ui:info", { message: `Peers:\n${lines.join("\n")}` });
+  });
+
+  // ── System prompt instruction ──────────────────────────────
+
+  registerInstruction("Peer Mesh", [
+    "You have access to a peer mesh — other running agent-sh instances on this machine.",
+    "Use the `peers` tool to discover them, then:",
+    "- `peer_terminal` to see what's on another terminal's screen",
+    "- `peer_history` to see what commands they ran recently",
+    "- `peer_search` to search their shell context by keyword",
+    "- `peer_send` to deliver a text message to another peer (appears in their UI)",
+    "- `peer_inbox` to read messages other peers have sent you",
+    "When the user references 'the other terminal' or 'my other shell', use these tools.",
+  ].join("\n"));
+
+  // ── Update CWD in peer file on directory change ────────────
+
+  bus.on("shell:cwd-change", ({ cwd }) => {
+    try {
+      const info: PeerInfo = JSON.parse(fs.readFileSync(peerFilePath(ctx.instanceId), "utf-8"));
+      info.cwd = cwd;
+      fs.writeFileSync(peerFilePath(ctx.instanceId), JSON.stringify(info));
+    } catch {}
+  });
+}

package/examples/extensions/pi-bridge/index.ts

@@ -23,8 +23,8 @@ import {
   SessionManager,
 } from "@mariozechner/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
-import type { ExtensionContext } from "../../src/types.js";
-import type { EventBus } from "../../src/event-bus.js";
+import type { ExtensionContext } from "agent-sh/types";
+import type { EventBus } from "agent-sh/event-bus";
 
 // ── Helpers ──────────────────────────────────────────────────────
 function interpretEscapes(str: string): string {