agent-sh 0.3.1 → 0.5.0

package/dist/extensions/shell-exec.js

@@ -1,188 +0,0 @@
-/**
- * Shell exec extension.
- *
- * Runs a Unix domain socket server speaking JSON-RPC 2.0 that external
- * tools (MCP server, pi extensions, etc.) connect to for interacting
- * with the user's live PTY shell.
- *
- * Also registers the MCP server via the `session:configure` pipe so
- * ACP agents discover the `user_shell` tool automatically.
- *
- * This extension has no direct PTY or Shell knowledge — it communicates
- * exclusively through the bus, following the headless-core philosophy.
- *
- * ## Socket protocol (JSON-RPC 2.0, newline-delimited)
- *
- *   shell/exec    { command: string }  → { output, cwd }
- *   shell/cwd     {}                   → { cwd }
- *   shell/info    {}                   → { busy, shell }
- *   shell/recall  { operation, ... }   → { result }
- */
-import * as net from "node:net";
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { fileURLToPath } from "node:url";
-import { getSettings } from "../settings.js";
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-export default function activate({ bus, contextManager }, opts) {
-    const { socketPath } = opts;
-    // Register MCP server so ACP agents discover the bridge tools.
-    // Agents that don't support MCP (e.g. pi-acp) simply ignore it.
-    // Can be disabled via settings.json if not needed.
-    if (getSettings().enableMcp) {
-        bus.onPipe("session:configure", (payload) => {
-            return {
-                ...payload,
-                mcpServers: [
-                    ...payload.mcpServers,
-                    {
-                        name: "agent-sh",
-                        command: process.execPath,
-                        args: [path.join(__dirname, "..", "mcp-server.js")],
-                        env: [{ name: "AGENT_SH_SOCKET", value: socketPath }],
-                    },
-                ],
-            };
-        });
-    }
-    // Set AGENT_SH_SOCKET for agent extensions that connect directly
-    process.env.AGENT_SH_SOCKET = socketPath;
-    // Serialize shell/exec requests — only one PTY command at a time
-    let execPending = Promise.resolve();
-    // ── JSON-RPC handler ────────────────────────────────────────────
-    async function handleRequest(method, params) {
-        switch (method) {
-            case "shell/exec": {
-                const command = params?.command;
-                if (typeof command !== "string" || !command) {
-                    throw rpcError(-32602, "Missing required parameter: command");
-                }
-                // Serialize — one PTY command at a time
-                return new Promise((resolve, reject) => {
-                    execPending = execPending.then(async () => {
-                        try {
-                            bus.emit("shell:agent-exec-start", {});
-                            const result = await bus.emitPipeAsync("shell:exec-request", {
-                                command,
-                                output: "",
-                                cwd: "",
-                                done: false,
-                            });
-                            bus.emit("shell:agent-exec-done", {});
-                            resolve({ output: result.output, cwd: result.cwd });
-                        }
-                        catch (err) {
-                            bus.emit("shell:agent-exec-done", {});
-                            const message = err instanceof Error ? err.message : String(err);
-                            reject(rpcError(-32000, message));
-                        }
-                    });
-                });
-            }
-            case "shell/cwd":
-                return { cwd: contextManager.getCwd() };
-            case "shell/info":
-                return {
-                    shell: process.env.SHELL || "unknown",
-                    agentSh: true,
-                };
-            case "shell/recall": {
-                const operation = params?.operation || "browse";
-                switch (operation) {
-                    case "search": {
-                        const query = params?.query;
-                        if (typeof query !== "string" || !query) {
-                            throw rpcError(-32602, "Missing required parameter: query");
-                        }
-                        return { result: contextManager.search(query) };
-                    }
-                    case "expand": {
-                        const ids = params?.ids;
-                        if (!Array.isArray(ids) || ids.length === 0) {
-                            throw rpcError(-32602, "Missing required parameter: ids (array of numbers)");
-                        }
-                        const start = typeof params?.start === "number" ? params.start : undefined;
-                        const end = typeof params?.end === "number" ? params.end : undefined;
-                        return { result: contextManager.expand(ids.map(Number), start, end) };
-                    }
-                    case "browse":
-                        return { result: contextManager.getRecentSummary() };
-                    default:
-                        throw rpcError(-32602, `Unknown recall operation: ${operation}`);
-                }
-            }
-            default:
-                throw rpcError(-32601, `Method not found: ${method}`);
-        }
-    }
-    // ── Socket server ───────────────────────────────────────────────
-    const server = net.createServer((conn) => {
-        let buffer = "";
-        conn.on("data", (chunk) => {
-            buffer += chunk.toString();
-            // Process complete lines (newline-delimited JSON-RPC)
-            let newlineIdx;
-            while ((newlineIdx = buffer.indexOf("\n")) !== -1) {
-                const line = buffer.slice(0, newlineIdx).trim();
-                buffer = buffer.slice(newlineIdx + 1);
-                if (!line)
-                    continue;
-                processMessage(conn, line);
-            }
-        });
-    });
-    function processMessage(conn, line) {
-        let id = null;
-        try {
-            const msg = JSON.parse(line);
-            id = msg.id ?? null;
-            const method = msg.method;
-            if (!method) {
-                sendError(conn, id, -32600, "Invalid request: missing method");
-                return;
-            }
-            handleRequest(method, msg.params)
-                .then((result) => sendResult(conn, id, result))
-                .catch((err) => {
-                if (err && typeof err === "object" && "rpcCode" in err) {
-                    sendError(conn, id, err.rpcCode, err.message);
-                }
-                else {
-                    sendError(conn, id, -32603, String(err));
-                }
-            });
-        }
-        catch {
-            sendError(conn, id, -32700, "Parse error");
-        }
-    }
-    // Clean up stale socket file
-    try {
-        fs.unlinkSync(socketPath);
-    }
-    catch {
-        // Doesn't exist — fine
-    }
-    server.listen(socketPath);
-    // Cleanup on exit
-    const cleanup = () => {
-        server.close();
-        try {
-            fs.unlinkSync(socketPath);
-        }
-        catch { }
-    };
-    process.on("exit", cleanup);
-}
-// ── JSON-RPC helpers ──────────────────────────────────────────────
-function sendResult(conn, id, result) {
-    conn.write(JSON.stringify({ jsonrpc: "2.0", id, result }) + "\n");
-}
-function sendError(conn, id, code, message) {
-    conn.write(JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } }) + "\n");
-}
-function rpcError(code, message) {
-    const err = new Error(message);
-    err.rpcCode = code;
-    return err;
-}

package/dist/mcp-server.d.ts

@@ -1,13 +0,0 @@
-#!/usr/bin/env node
-/**
- * Minimal MCP server exposing a `user_shell` tool.
- *
- * Spawned by the ACP agent (pi-acp, claude-agent-acp, etc.) as an MCP
- * stdio server. When the LLM calls `user_shell`, this process connects
- * to agent-sh's Unix socket to execute the command in the user's live
- * PTY shell.
- *
- * Protocol: MCP over stdio (newline-delimited JSON-RPC 2.0).
- * No SDK dependency — the protocol surface is tiny.
- */
-export {};

package/dist/mcp-server.js

@@ -1,234 +0,0 @@
-#!/usr/bin/env node
-/**
- * Minimal MCP server exposing a `user_shell` tool.
- *
- * Spawned by the ACP agent (pi-acp, claude-agent-acp, etc.) as an MCP
- * stdio server. When the LLM calls `user_shell`, this process connects
- * to agent-sh's Unix socket to execute the command in the user's live
- * PTY shell.
- *
- * Protocol: MCP over stdio (newline-delimited JSON-RPC 2.0).
- * No SDK dependency — the protocol surface is tiny.
- */
-import { createConnection } from "node:net";
-import { createInterface } from "node:readline";
-const SOCKET_PATH = process.env.AGENT_SH_SOCKET;
-// ── MCP protocol helpers ────────────────────────────────────────
-function send(msg) {
-    process.stdout.write(JSON.stringify({ jsonrpc: "2.0", ...msg }) + "\n");
-}
-function sendResult(id, result) {
-    send({ id, result });
-}
-function sendError(id, code, message) {
-    send({ id, error: { code, message } });
-}
-// ── Tool definition ─────────────────────────────────────────────
-const SHELL_CWD_TOOL = {
-    name: "shell_cwd",
-    description: "Get the user's current working directory in their live shell. " +
-        "IMPORTANT: Your internal working directory may differ from the user's actual shell cwd — " +
-        "the user may have cd'd after your session started. Call this tool to get the real cwd " +
-        "before file operations if you're unsure.",
-    inputSchema: {
-        type: "object",
-        properties: {},
-    },
-};
-const USER_SHELL_TOOL = {
-    name: "user_shell",
-    description: "Execute a command in the user's live terminal session. " +
-        "Use this for commands that should affect the user's shell state: " +
-        "cd, export, source, pushd/popd, alias, etc. " +
-        "The command runs in the user's actual shell with their full environment " +
-        "(aliases, functions, PATH), not an isolated subprocess. " +
-        "NOTE: Your internal cwd may be stale — the user may have cd'd. " +
-        "Check the shell context for [shell cwd:...] labels or call shell_cwd " +
-        "to determine the real working directory. Use absolute paths when possible.",
-    inputSchema: {
-        type: "object",
-        properties: {
-            command: {
-                type: "string",
-                description: "Shell command to execute in the user's live terminal",
-            },
-        },
-        required: ["command"],
-    },
-};
-const SHELL_RECALL_TOOL = {
-    name: "shell_recall",
-    description: "Retrieve past shell commands, agent responses, and tool executions from the session history. " +
-        "Use this to look up truncated output, search for previous commands or errors, " +
-        "or browse recent exchanges. Each entry shows [shell cwd:...] so you can see " +
-        "which directory commands were run in. Operations: " +
-        '"browse" lists recent exchange summaries with line counts, ' +
-        '"search" finds exchanges matching a regex query, ' +
-        '"expand" retrieves content by exchange ID (use start/end for specific line ranges).',
-    inputSchema: {
-        type: "object",
-        properties: {
-            operation: {
-                type: "string",
-                enum: ["search", "expand", "browse"],
-                description: 'Operation to perform (default: "browse")',
-            },
-            query: {
-                type: "string",
-                description: 'Search query — supports regex (required for "search" operation)',
-            },
-            ids: {
-                type: "array",
-                items: { type: "number" },
-                description: 'Exchange IDs to expand (required for "expand" operation)',
-            },
-            start: {
-                type: "number",
-                description: "Start line number, 1-indexed (optional, for expand)",
-            },
-            end: {
-                type: "number",
-                description: "End line number, inclusive (optional, for expand)",
-            },
-        },
-    },
-};
-// ── agent-sh socket client (JSON-RPC 2.0) ──────────────────────
-let rpcId = 0;
-function callSocket(method, params) {
-    return new Promise((resolve, reject) => {
-        if (!SOCKET_PATH) {
-            reject(new Error("AGENT_SH_SOCKET not set — not running inside agent-sh"));
-            return;
-        }
-        const conn = createConnection(SOCKET_PATH);
-        let buffer = "";
-        conn.on("connect", () => {
-            const msg = { jsonrpc: "2.0", id: ++rpcId, method, params: params ?? {} };
-            conn.write(JSON.stringify(msg) + "\n");
-        });
-        conn.on("data", (chunk) => {
-            buffer += chunk.toString();
-            const newlineIdx = buffer.indexOf("\n");
-            if (newlineIdx === -1)
-                return;
-            const line = buffer.slice(0, newlineIdx).trim();
-            conn.destroy();
-            try {
-                const response = JSON.parse(line);
-                if (response.error) {
-                    reject(new Error(response.error.message || "RPC error"));
-                }
-                else {
-                    resolve(response.result);
-                }
-            }
-            catch {
-                reject(new Error(`Invalid response from agent-sh: ${line}`));
-            }
-        });
-        conn.on("error", (err) => {
-            reject(new Error(`Failed to connect to agent-sh: ${err.message}`));
-        });
-        conn.setTimeout(35_000, () => {
-            conn.destroy();
-            reject(new Error("Connection to agent-sh timed out"));
-        });
-    });
-}
-// ── Request handler ─────────────────────────────────────────────
-async function handleRequest(id, method, params) {
-    switch (method) {
-        case "initialize":
-            sendResult(id, {
-                protocolVersion: params?.protocolVersion ?? "2024-11-05",
-                capabilities: { tools: {} },
-                serverInfo: { name: "agent-sh-shell", version: "0.1.0" },
-            });
-            break;
-        case "notifications/initialized":
-            // Client acknowledgement — nothing to do
-            break;
-        case "tools/list":
-            sendResult(id, { tools: [SHELL_CWD_TOOL, USER_SHELL_TOOL, SHELL_RECALL_TOOL] });
-            break;
-        case "tools/call": {
-            const toolName = params?.name;
-            const args = params?.arguments ?? {};
-            try {
-                let text;
-                if (toolName === "shell_cwd") {
-                    const result = await callSocket("shell/cwd", {});
-                    text = `User's current working directory: ${result.cwd}`;
-                }
-                else if (toolName === "user_shell") {
-                    const command = args.command;
-                    if (!command || typeof command !== "string") {
-                        sendError(id, -32602, "Missing required parameter: command");
-                        return;
-                    }
-                    const result = await callSocket("shell/exec", { command });
-                    text = result.output || "(no output)";
-                }
-                else if (toolName === "shell_recall") {
-                    const result = await callSocket("shell/recall", {
-                        operation: args.operation || "browse",
-                        query: args.query,
-                        ids: args.ids,
-                        start: args.start,
-                        end: args.end,
-                    });
-                    text = result.result || "(no results)";
-                }
-                else {
-                    sendError(id, -32602, `Unknown tool: ${toolName}`);
-                    return;
-                }
-                sendResult(id, {
-                    content: [{ type: "text", text }],
-                });
-            }
-            catch (err) {
-                sendResult(id, {
-                    content: [
-                        {
-                            type: "text",
-                            text: `Error: ${err instanceof Error ? err.message : String(err)}`,
-                        },
-                    ],
-                    isError: true,
-                });
-            }
-            break;
-        }
-        default:
-            // Unknown methods: return method-not-found for requests (those with id)
-            if (id !== undefined && id !== null) {
-                sendError(id, -32601, `Method not found: ${method}`);
-            }
-            break;
-    }
-}
-// ── Main loop ───────────────────────────────────────────────────
-const rl = createInterface({ input: process.stdin });
-rl.on("line", (line) => {
-    if (!line.trim())
-        return;
-    try {
-        const msg = JSON.parse(line);
-        const { id, method, params } = msg;
-        if (method) {
-            handleRequest(id, method, params).catch((err) => {
-                if (id !== undefined && id !== null) {
-                    sendError(id, -32603, String(err));
-                }
-            });
-        }
-    }
-    catch {
-        // Malformed JSON — ignore
-    }
-});
-rl.on("close", () => {
-    process.exit(0);
-});

package/examples/pi-agent-sh.ts

@@ -1,166 +0,0 @@
-/**
- * Pi extension: agent-sh tools (user_shell + shell_recall).
- *
- * When running inside agent-sh, registers tools that communicate with
- * the user's live terminal via a Unix domain socket (JSON-RPC 2.0).
- *
- * - user_shell:   execute commands in the user's live PTY
- * - shell_recall:  search/expand/browse session exchange history
- *
- * Socket path comes from the AGENT_SH_SOCKET env var.
- * When not running inside agent-sh, the extension silently does nothing.
- */
-
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { Type } from "@sinclair/typebox";
-import { createConnection } from "node:net";
-
-const SOCKET_PATH = process.env.AGENT_SH_SOCKET;
-
-export default function (pi: ExtensionAPI): void {
-  if (!SOCKET_PATH) return; // Not running inside agent-sh
-
-  pi.registerTool({
-    name: "shell_cwd",
-    label: "Shell CWD",
-    description:
-      "Get the user's current working directory in their live shell. " +
-      "IMPORTANT: Your internal working directory may differ from the user's actual shell cwd — " +
-      "the user may have cd'd after your session started. Call this tool to get the real cwd " +
-      "before file operations if you're unsure.",
-    promptSnippet:
-      "Get the user's real shell cwd (may differ from your internal cwd).",
-    parameters: Type.Object({}),
-
-    async execute() {
-      const result = (await callSocket("shell/cwd", {})) as { cwd: string };
-      return {
-        content: [{ type: "text", text: `User's current working directory: ${result.cwd}` }],
-      };
-    },
-  });
-
-  pi.registerTool({
-    name: "user_shell",
-    label: "User Shell",
-    description:
-      "Execute a command in the user's live terminal session. " +
-      "Use this for commands that should affect the user's shell state: " +
-      "cd, export, source, pushd/popd, alias, etc. " +
-      "The command runs in the user's actual shell with their full environment " +
-      "(aliases, functions, PATH), not an isolated subprocess. " +
-      "NOTE: Your internal cwd may be stale — the user may have cd'd. " +
-      "Check the shell context for [shell cwd:...] labels or call shell_cwd " +
-      "to determine the real working directory. Use absolute paths when possible.",
-    promptSnippet:
-      "Run commands in the user's live shell (cd, export, source — affects their session). " +
-      "Your internal cwd may be stale — check shell context or use shell_cwd for the real cwd.",
-    parameters: Type.Object({
-      command: Type.String({ description: "Shell command to execute in the user's live terminal" }),
-    }),
-
-    async execute(_toolCallId, params) {
-      const result = (await callSocket("shell/exec", { command: params.command })) as {
-        output: string;
-        cwd: string;
-      };
-      return {
-        content: [{ type: "text", text: result.output || "(no output)" }],
-      };
-    },
-  });
-
-  pi.registerTool({
-    name: "shell_recall",
-    label: "Shell Recall",
-    description:
-      "Retrieve past shell commands, agent responses, and tool executions from the session history. " +
-      "Use this to look up truncated output, search for previous commands or errors, " +
-      "or browse recent exchanges. Each entry shows [shell cwd:...] so you can see " +
-      "which directory commands were run in. Operations: " +
-      '"browse" lists recent exchange summaries with line counts, ' +
-      '"search" finds exchanges matching a regex query, ' +
-      '"expand" retrieves content by exchange ID (use start/end for specific line ranges).',
-    promptSnippet:
-      "Look up session history — search past commands/output, expand truncated exchanges, or browse recent activity.",
-    parameters: Type.Object({
-      operation: Type.Optional(
-        Type.Union([Type.Literal("search"), Type.Literal("expand"), Type.Literal("browse")], {
-          description: 'Operation to perform (default: "browse")',
-        }),
-      ),
-      query: Type.Optional(
-        Type.String({ description: 'Search query — supports regex (required for "search")' }),
-      ),
-      ids: Type.Optional(
-        Type.Array(Type.Number(), {
-          description: 'Exchange IDs to expand (required for "expand")',
-        }),
-      ),
-      start: Type.Optional(
-        Type.Number({ description: "Start line number, 1-indexed (optional, for expand)" }),
-      ),
-      end: Type.Optional(
-        Type.Number({ description: "End line number, inclusive (optional, for expand)" }),
-      ),
-    }),
-
-    async execute(_toolCallId, params) {
-      const result = (await callSocket("shell/recall", {
-        operation: params.operation || "browse",
-        query: params.query,
-        ids: params.ids,
-        start: params.start,
-        end: params.end,
-      })) as { result: string };
-      return {
-        content: [{ type: "text", text: result.result || "(no results)" }],
-      };
-    },
-  });
-}
-
-// -- agent-sh socket client (JSON-RPC 2.0) --
-
-let rpcId = 0;
-
-function callSocket(method: string, params?: Record<string, unknown>): Promise<unknown> {
-  return new Promise((resolve, reject) => {
-    const conn = createConnection(SOCKET_PATH!);
-    let buffer = "";
-
-    conn.on("connect", () => {
-      const msg = { jsonrpc: "2.0", id: ++rpcId, method, params: params ?? {} };
-      conn.write(JSON.stringify(msg) + "\n");
-    });
-
-    conn.on("data", (chunk) => {
-      buffer += chunk.toString();
-      const newlineIdx = buffer.indexOf("\n");
-      if (newlineIdx === -1) return;
-
-      const line = buffer.slice(0, newlineIdx).trim();
-      conn.destroy();
-
-      try {
-        const response = JSON.parse(line);
-        if (response.error) {
-          reject(new Error(response.error.message || "RPC error"));
-        } else {
-          resolve(response.result);
-        }
-      } catch {
-        reject(new Error(`Invalid response from agent-sh: ${line}`));
-      }
-    });
-
-    conn.on("error", (err) => {
-      reject(new Error(`Failed to connect to agent-sh: ${err.message}`));
-    });
-
-    conn.setTimeout(35_000, () => {
-      conn.destroy();
-      reject(new Error("Connection to agent-sh timed out"));
-    });
-  });
-}