agent-sh 0.7.0 → 0.8.0

package/dist/utils/terminal-buffer.d.ts

@@ -28,6 +28,8 @@ export declare function formatScreenContext(screen: ScreenSnapshot, maxLines?: n
 export declare class TerminalBuffer {
     private readonly term;
     private readonly serializeAddon;
+    /** Flush pending drip-feed data (set by createWired). */
+    _flushPending: (() => void) | null;
     private constructor();
     /**
      * Create a new TerminalBuffer. Returns null if xterm is not installed.
@@ -38,6 +40,8 @@ export declare class TerminalBuffer {
      * Returns null if xterm is not installed.
      */
     static createWired(bus: EventBus, config?: TerminalBufferConfig): TerminalBuffer | null;
+    /** Flush any pending drip-feed data into the virtual terminal. */
+    flush(): void;
     /** Write raw data into the virtual terminal. */
     write(data: string): void;
     /** Get the raw serialized terminal output (includes ANSI sequences). */

package/dist/utils/terminal-buffer.js

@@ -65,6 +65,8 @@ export function formatScreenContext(screen, maxLines = 80, baseContext) {
 export class TerminalBuffer {
     term;
     serializeAddon;
+    /** Flush pending drip-feed data (set by createWired). */
+    _flushPending = null;
     constructor(term, serialize) {
         this.term = term;
         this.serializeAddon = serialize;
@@ -103,11 +105,22 @@ export class TerminalBuffer {
                 tb.write(d);
             }
         }, 50);
+        tb._flushPending = () => {
+            if (pending) {
+                const d = pending;
+                pending = "";
+                tb.write(d);
+            }
+        };
         process.stdout.on("resize", () => {
             tb.resize(process.stdout.columns || 80, process.stdout.rows || 24);
         });
         return tb;
     }
+    /** Flush any pending drip-feed data into the virtual terminal. */
+    flush() {
+        this._flushPending?.();
+    }
     /** Write raw data into the virtual terminal. */
     write(data) {
         this.term.write(data);

package/dist/utils/tool-display.d.ts

@@ -30,6 +30,7 @@ export declare function selectToolDisplayMode(width: number): ToolDisplayMode;
 export declare function renderToolCall(tool: ToolCallRender, width: number): string[];
 export declare function renderToolResult(result: ToolResultRender, width: number): string[];
 export declare function formatElapsed(ms: number): string;
+export declare const SPINNER_FRAMES: string[];
 export interface SpinnerState {
     frame: number;
     startTime: number;

package/dist/utils/tool-display.js

@@ -205,7 +205,7 @@ export function formatElapsed(ms) {
     return rm > 0 ? `${h}h ${rm}m` : `${h}h`;
 }
 // ── Spinner with elapsed timer ───────────────────────────────────
-const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+export const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 export function createSpinner(opts) {
     return { frame: 0, startTime: opts?.startTime || Date.now() };
 }

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

@@ -23,6 +23,23 @@ import { z } from "zod";
 import type { ExtensionContext } from "../../src/types.js";
 import type { EventBus } from "../../src/event-bus.js";
 
+// ── 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 MCP tool ───────────────────────────────────────────
 function createUserShellTool(bus: EventBus) {
   let liveCwd = process.cwd();
@@ -56,15 +73,72 @@ function createUserShellTool(bus: EventBus) {
   );
 }
 
+// ── 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 shellTool = createUserShellTool(bus);
+  const termReadTool = createTerminalReadTool(ctx);
+  const termKeysTool = createTerminalKeysTool(bus, ctx);
   const shellServer = createSdkMcpServer({
     name: "agent-sh",
     version: "1.0.0",
-    tools: [shellTool],
+    tools: [shellTool, termReadTool, termKeysTool],
   });
 
   let activeQuery: Query | null = null;
@@ -95,6 +169,8 @@ export default function activate(ctx: ExtensionContext): void {
             mcpServers: { "agent-sh": shellServer },
             allowedTools: [
               "mcp__agent-sh__user_shell",
+              "mcp__agent-sh__terminal_read",
+              "mcp__agent-sh__terminal_keys",
               "Read", "Edit", "Write", "Bash", "Glob", "Grep",
             ],
             permissionMode: "acceptEdits",

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

@@ -26,7 +26,22 @@ import { Type } from "@sinclair/typebox";
 import type { ExtensionContext } from "../../src/types.js";
 import type { EventBus } from "../../src/event-bus.js";
 
-// ── agent-sh context injected via tool promptGuidelines + promptSnippet ──
+// ── 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) {
@@ -81,12 +96,82 @@ function createUserShellToolDef(bus: EventBus) {
   };
 }
 
+// ── 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;
@@ -105,7 +190,7 @@ export default function activate(ctx: ExtensionContext): void {
         const result = await createAgentSessionFromServices({
           services,
           sessionManager: opts.sessionManager ?? sessionManager,
-          customTools: [userShellTool],
+          customTools: [userShellTool, termReadTool, termKeysTool],
         });
         return { ...result, services };
       };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sh",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "A shell-first terminal where AI is one keystroke away",
   "type": "module",
   "main": "dist/core.js",