agent-sh 0.10.0 → 0.10.2

package/examples/extensions/claude-code-bridge/index.ts

@@ -2,8 +2,14 @@
  * Claude Code bridge — runs Claude Code Agent SDK in-process as agent-sh's backend.
  *
  * Uses the official @anthropic-ai/claude-agent-sdk to spawn a Claude Code
- * session with custom MCP tools for PTY access. Claude Code
- * handles its own model selection, tool execution, and permissions.
+ * session. Claude Code handles its own model selection, tool execution, and
+ * permissions — the bridge is a pure protocol translator between the SDK's
+ * event stream and agent-sh's bus events.
+ *
+ * PTY-access tools (`terminal_read`, `terminal_keys`, `user_shell`) are
+ * intentionally NOT bundled here. If you want Claude Code to observe or
+ * drive the user's live terminal, load a companion extension that
+ * registers those tools as MCP tools the SDK can consume.
  *
  * Setup (from repo root):
  *   npm run build && npm link                    # register local agent-sh globally
@@ -15,103 +21,16 @@
  *
  * Requires: Claude Code CLI installed and authenticated (claude login).
  */
-import {
-  query,
-  tool,
-  createSdkMcpServer,
-  type Query,
-} from "@anthropic-ai/claude-agent-sdk";
-import { z } from "zod";
+import { query, type Query } from "@anthropic-ai/claude-agent-sdk";
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import type { ExtensionContext } from "agent-sh/types";
-import type { EventBus } from "agent-sh/event-bus";
 import { computeDiff, type DiffResult } from "agent-sh/utils/diff";
 
-// ── Helpers ──────────────────────────────────────────────────────
-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;
-  });
-}
-
-function settle(ms = 100): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-// ── terminal_read MCP tool ────────────────────────────────────────
-function createTerminalReadTool(ctx: ExtensionContext) {
-  return tool(
-    "terminal_read",
-    "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.",
-    {},
-    async () => {
-      const tb = ctx.terminalBuffer;
-      if (!tb) return { content: [{ type: "text" as const, text: "terminal buffer not available" }] };
-      const { text, altScreen, cursorX, cursorY } = tb.readScreen();
-      const info = [
-        altScreen ? "mode: alternate screen" : "mode: normal",
-        `cursor: row=${cursorY} col=${cursorX}`,
-      ].join(", ");
-      return { content: [{ type: "text" as const, text: `[${info}]\n\n${text}` }] };
-    },
-  );
-}
-
-// ── terminal_keys MCP tool ───────────────────────────────────────
-function createTerminalKeysTool(bus: EventBus, ctx: ExtensionContext) {
-  return tool(
-    "terminal_keys",
-    "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  - Enter: \\r  - Tab: \\t\n" +
-    "  - Ctrl+C: \\x03  - Arrow keys: \\x1b[A/B/C/D  - Backspace: \\x7f\n" +
-    "Example: to quit vim without saving, send keys=\"\\x1b:q!\\r\".\n" +
-    "Always call terminal_read after sending keys to verify the result.",
-    {
-      keys: z.string().describe("Keystrokes to send (use \\x1b for Escape, \\r for Enter, etc.)"),
-      settle_ms: z.number().optional().describe("Wait time in ms after sending keys (default: 150)"),
-    },
-    async (args) => {
-      const keys = interpretEscapes(args.keys);
-      const settleMs = args.settle_ms ?? 150;
-      bus.emit("shell:stdout-show", {});
-      process.stdout.write("\n");
-      bus.emit("shell:pty-write", { data: keys });
-      await settle(settleMs);
-
-      const tb = ctx.terminalBuffer;
-      if (!tb) return { content: [{ type: "text" as const, text: "Keys sent." }] };
-      const { text, altScreen, cursorX, cursorY } = tb.readScreen();
-      const info = [
-        altScreen ? "mode: alternate screen" : "mode: normal",
-        `cursor: row=${cursorY} col=${cursorX}`,
-      ].join(", ");
-      return { content: [{ type: "text" as const, text: `Keys sent. Screen after:\n[${info}]\n\n${text}` }] };
-    },
-  );
-}
-
 // ── Extension entry point ─────────────────────────────────────────
 export default function activate(ctx: ExtensionContext): void {
   const { bus } = ctx;
 
-  const termReadTool = createTerminalReadTool(ctx);
-  const termKeysTool = createTerminalKeysTool(bus, ctx);
-  const shellServer = createSdkMcpServer({
-    name: "agent-sh",
-    version: "1.0.0",
-    tools: [termReadTool, termKeysTool],
-  });
-
   let activeQuery: Query | null = null;
   const listeners: Array<{ event: string; fn: Function }> = [];
 
@@ -119,11 +38,11 @@ export default function activate(ctx: ExtensionContext): void {
 
   /** Map Claude Code tool names to agent-sh display kinds. */
   function toolKind(name: string): string {
-    if (name === "Read" || name.includes("terminal_read")) return "read";
+    if (name === "Read") return "read";
     if (name === "Edit") return "edit";
     if (name === "Write") return "write";
     if (name === "Glob" || name === "Grep") return "search";
-    if (name === "Bash" || name.includes("terminal_keys")) return "execute";
+    if (name === "Bash") return "execute";
     return "execute";
   }
 
@@ -150,7 +69,6 @@ export default function activate(ctx: ExtensionContext): void {
     if (name === "Bash") return `$ ${str(input.command)}`;
     if (name === "Read" || name === "Edit" || name === "Write") return str(input.file_path ?? input.path);
     if (name === "Grep" || name === "Glob") return `${str(input.pattern)} ${str(input.path)}`.trim();
-    if (name.includes("terminal_keys")) return str(input.keys);
     return name;
   }
 
@@ -180,15 +98,9 @@ export default function activate(ctx: ExtensionContext): void {
               preset: "claude_code",
               append:
                 "You are running inside agent-sh, a terminal wrapper.\n" +
-                "Use your standard tools (Read, Edit, Write, Bash, Glob, Grep) for investigation.\n" +
-                "Use mcp__agent-sh__terminal_read and mcp__agent-sh__terminal_keys to observe and interact with the user's live terminal.",
+                "Use your standard tools (Read, Edit, Write, Bash, Glob, Grep) for investigation.",
             },
-            mcpServers: { "agent-sh": shellServer },
-            allowedTools: [
-              "mcp__agent-sh__terminal_read",
-              "mcp__agent-sh__terminal_keys",
-              "Read", "Edit", "Write", "Bash", "Glob", "Grep",
-            ],
+            allowedTools: ["Read", "Edit", "Write", "Bash", "Glob", "Grep"],
             permissionMode: "acceptEdits",
             includePartialMessages: true,
           },

package/examples/extensions/pi-bridge/README.md

@@ -33,3 +33,19 @@ Or switch at runtime:
 
 - pi must be configured separately (`~/.pi/settings.json`) with API keys and model preferences
 - agent-sh does not override pi's configuration — it uses whatever pi is set up with
+
+## What this bridge is
+
+A pure protocol translator between pi's event stream and agent-sh's bus events. Pi's built-in tools (command execution, file ops, etc.) are used exactly as pi ships them. The bridge adds no tools of its own.
+
+## What this bridge intentionally does NOT bundle
+
+Three PTY-access tools are left out on purpose:
+
+- `terminal_read` — observe the user's live terminal screen
+- `terminal_keys` — send keystrokes to the user's PTY
+- `user_shell` — run commands in the user's live shell with lasting `cd`/`export`/`source` effects
+
+These are opt-in capabilities that belong in their own extensions. If you want any of them with pi, write a small companion extension that registers the tool as a pi `ToolDefinition` (TypeBox schema, wired to the relevant bus event: `shell:pty-write`, `shell:exec-request`, or `ctx.terminalBuffer.readScreen()`) and load it alongside pi-bridge.
+
+Keeping this split means the bridge stays narrow — only translating events — and the capability surface is composable per-backend.

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

@@ -5,9 +5,12 @@
  * provider settings, extensions, session management, and tool system.
  * Agent-sh provides the shell frontend and TUI rendering.
  *
- * In addition to pi's built-in tools, this bridge registers `user_shell`
- * so pi can execute commands in agent-sh's live PTY (visible to the user,
- * affects shell state like cd/export/source).
+ * The bridge is a pure protocol translator between pi's event stream and
+ * agent-sh's bus events. Pi brings its own tools for command execution,
+ * file ops, etc. PTY-access tools (`terminal_read`, `terminal_keys`,
+ * `user_shell`) are intentionally NOT bundled here — if you want pi to
+ * observe or mutate the user's live terminal, load a companion extension
+ * that registers those tools in pi's ToolDefinition format.
  *
  * Setup:
  *   npm install @mariozechner/pi-agent-core @mariozechner/pi-ai @mariozechner/pi-coding-agent
@@ -22,157 +25,13 @@ import {
   createAgentSessionRuntime,
   SessionManager,
 } from "@mariozechner/pi-coding-agent";
-import { Type } from "@sinclair/typebox";
 import type { ExtensionContext } from "agent-sh/types";
-import type { EventBus } from "agent-sh/event-bus";
-
-// ── Helpers ──────────────────────────────────────────────────────
-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;
-  });
-}
-
-function settle(ms = 100): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-// ── user_shell as a pi ToolDefinition ─────────────────────────────
-function createUserShellToolDef(bus: EventBus) {
-  // Track agent-sh's live cwd so user_shell always runs in the right place
-  let liveCwd = process.cwd();
-  bus.on("shell:cwd-change", ({ cwd }) => { liveCwd = cwd; });
-
-  const schema = Type.Object({
-    command: Type.String({ description: "Command to execute in user's shell" }),
-    return_output: Type.Optional(
-      Type.Boolean({
-        description:
-          "Whether to return the command output. Default false — output is shown directly to the user.",
-      }),
-    ),
-  });
-
-  return {
-    name: "user_shell",
-    label: "user_shell",
-    description:
-      "Run a command with lasting effects in the user's live shell (cd, export, " +
-      "install packages, start servers) or show output the user wants to see. " +
-      "Output is shown directly to the user. Set return_output=true only " +
-      "if you need to inspect the result.",
-    promptSnippet: "Execute commands in the user's live terminal (PTY).",
-    promptGuidelines: [
-      "You are running inside agent-sh, a terminal wrapper.",
-      "Use your standard tools (bash, file ops) for investigation — output goes to you, not the user.",
-      "Use user_shell to run commands in the user's live shell when they ask to see output or need lasting effects (cd, install, start servers).",
-      "Default to standard tools. Use user_shell when the user is the intended audience for the output or the command has real effects.",
-    ],
-    parameters: schema,
-
-    async execute(_toolCallId, params) {
-      const command = params.command;
-      const returnOutput = params.return_output ?? false;
-
-      const result = await bus.emitPipeAsync("shell:exec-request", {
-        command,
-        output: "",
-        cwd: liveCwd,
-        done: false,
-      });
-
-      const text = returnOutput
-        ? result.output || "(no output)"
-        : "Command executed.";
-
-      return { content: [{ type: "text", text }], details: undefined };
-    },
-  };
-}
-
-// ── terminal_read as a pi ToolDefinition ─────────────────────────
-function createTerminalReadToolDef(ctx: ExtensionContext) {
-  return {
-    name: "terminal_read",
-    label: "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.",
-    promptSnippet: "Read the terminal screen to see what the user sees.",
-    promptGuidelines: [
-      "Use terminal_read to see the current terminal screen before sending keystrokes.",
-      "Check altScreen to know if a full-screen program (vim, htop) is running.",
-    ],
-    parameters: Type.Object({}),
-    async execute() {
-      const tb = ctx.terminalBuffer;
-      if (!tb) return { content: [{ type: "text", text: "terminal buffer not available" }], details: undefined };
-      const { text, altScreen, cursorX, cursorY } = tb.readScreen();
-      const info = [
-        altScreen ? "mode: alternate screen" : "mode: normal",
-        `cursor: row=${cursorY} col=${cursorX}`,
-      ].join(", ");
-      return { content: [{ type: "text", text: `[${info}]\n\n${text}` }], details: undefined };
-    },
-  };
-}
-
-// ── terminal_keys as a pi ToolDefinition ─────────────────────────
-function createTerminalKeysToolDef(bus: EventBus, ctx: ExtensionContext) {
-  return {
-    name: "terminal_keys",
-    label: "terminal_keys",
-    description:
-      "Send keystrokes to the user's live terminal as if the user typed them. " +
-      "Use escape sequences: \\x1b for Escape, \\r for Enter, \\t for Tab, " +
-      "\\x03 for Ctrl+C, \\x1b[A/B/C/D for arrow keys, \\x7f for Backspace. " +
-      "Example: \\x1b:q!\\r to quit vim. Always call terminal_read after.",
-    promptSnippet: "Send keystrokes to interactive programs in the terminal.",
-    promptGuidelines: [
-      "Use terminal_keys to type into interactive programs (vim, htop, less).",
-      "Always call terminal_read after sending keys to verify the result.",
-    ],
-    parameters: Type.Object({
-      keys: Type.String({ description: "Keystrokes to send (use \\x1b for Escape, \\r for Enter, etc.)" }),
-      settle_ms: Type.Optional(
-        Type.Number({ description: "Wait time in ms after sending keys (default: 150)" }),
-      ),
-    }),
-    async execute(_toolCallId: string, params: any) {
-      const keys = interpretEscapes(params.keys);
-      const settleMs = params.settle_ms ?? 150;
-      bus.emit("shell:stdout-show", {});
-      process.stdout.write("\n");
-      bus.emit("shell:pty-write", { data: keys });
-      await settle(settleMs);
-
-      const tb = ctx.terminalBuffer;
-      if (!tb) return { content: [{ type: "text", text: "Keys sent." }], details: undefined };
-      const { text, altScreen, cursorX, cursorY } = tb.readScreen();
-      const info = [
-        altScreen ? "mode: alternate screen" : "mode: normal",
-        `cursor: row=${cursorY} col=${cursorX}`,
-      ].join(", ");
-      return { content: [{ type: "text", text: `Keys sent. Screen after:\n[${info}]\n\n${text}` }], details: undefined };
-    },
-  };
-}
 
 // ── Extension entry point ─────────────────────────────────────────
 export default function activate(ctx: ExtensionContext): void {
   const { bus } = ctx;
   const cwd = process.cwd();
 
-  const userShellTool = createUserShellToolDef(bus);
-  const termReadTool = createTerminalReadToolDef(ctx);
-  const termKeysTool = createTerminalKeysToolDef(bus, ctx);
-
   // ── Boot pi session (async — register backend synchronously first) ──
   let session: any = null;
   let runtime: any = null;
@@ -190,7 +49,6 @@ export default function activate(ctx: ExtensionContext): void {
         const result = await createAgentSessionFromServices({
           services,
           sessionManager: opts.sessionManager ?? sessionManager,
-          customTools: [userShellTool, termReadTool, termKeysTool],
         });
         return { ...result, services };
       };
@@ -227,9 +85,7 @@ export default function activate(ctx: ExtensionContext): void {
             bus.emit("agent:tool-started", {
               title: (event as any).toolName,
               toolCallId: (event as any).toolCallId,
-              kind: (event as any).toolName === "user_shell" || (event as any).toolName === "bash"
-                ? "execute"
-                : "read",
+              kind: (event as any).toolName === "bash" ? "execute" : "read",
             });
             break;
 
@@ -251,9 +107,7 @@ export default function activate(ctx: ExtensionContext): void {
             bus.emit("agent:tool-completed", {
               toolCallId: (event as any).toolCallId,
               exitCode: (event as any).isError ? 1 : 0,
-              kind: (event as any).toolName === "user_shell" || (event as any).toolName === "bash"
-                ? "execute"
-                : "read",
+              kind: (event as any).toolName === "bash" ? "execute" : "read",
             });
             break;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sh",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "description": "A shell-first terminal where AI is one keystroke away",
   "type": "module",
   "main": "dist/core.js",
@@ -70,6 +70,14 @@
       "types": "./dist/agent/token-budget.d.ts",
       "default": "./dist/agent/token-budget.js"
     },
+    "./agent/history-file": {
+      "types": "./dist/agent/history-file.d.ts",
+      "default": "./dist/agent/history-file.js"
+    },
+    "./agent/nuclear-form": {
+      "types": "./dist/agent/nuclear-form.d.ts",
+      "default": "./dist/agent/nuclear-form.js"
+    },
     "./executor": {
       "types": "./dist/executor.d.ts",
       "default": "./dist/executor.js"

package/dist/extensions/shell-recall.d.ts

@@ -1,9 +0,0 @@
-/**
- * Shell recall extension.
- *
- * Intercepts __shell_recall terminal commands via the
- * "agent:terminal-intercept" pipe, returning virtual output from
- * ContextManager's recall API without spawning a subprocess.
- */
-import type { ExtensionContext } from "../types.js";
-export default function activate({ bus, contextManager }: ExtensionContext): void;

package/dist/extensions/shell-recall.js

@@ -1,8 +0,0 @@
-export default function activate({ bus, contextManager }) {
-    bus.onPipe("agent:terminal-intercept", (payload) => {
-        if (!payload.command.trimStart().startsWith("__shell_recall"))
-            return payload;
-        const output = contextManager.handleRecallCommand(payload.command.trim());
-        return { ...payload, intercepted: true, output };
-    });
-}