agent-sh 0.9.0 → 0.10.1

package/examples/extensions/peer-mesh.ts

@@ -268,6 +268,54 @@ export default function activate(ctx: ExtensionContext): void {
   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());
@@ -412,6 +460,71 @@ export default function activate(ctx: ExtensionContext): void {
     }),
   });
 
+  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", () => {
@@ -435,6 +548,8 @@ export default function activate(ctx: ExtensionContext): void {
     "- `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"));
 

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 "../../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 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 };
-    },
-  };
-}
+import type { ExtensionContext } from "agent-sh/types";
 
 // ── 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/examples/extensions/questionnaire.ts

@@ -55,15 +55,26 @@ interface QuestionnaireResult {
 
 // ── Extension ────────────────────────────────────────────────────
 
-export default function activate({ registerTool }: ExtensionContext) {
+export default function activate({ registerTool, registerInstruction }: ExtensionContext) {
+  registerInstruction("questionnaire", [
+    "# When to use the questionnaire tool",
+    "ALWAYS use the `questionnaire` tool instead of asking the user a question in plain text when:",
+    "- You need the user to choose from specific options (e.g. frameworks, approaches, yes/no decisions)",
+    "- You are unsure about a preference and can enumerate reasonable choices",
+    "- The user's answer determines a significant branch in your behavior",
+    "",
+    "Do NOT just list options in your reply prose — call the questionnaire tool so the user can select interactively.",
+    "This applies to single questions too (yes/no, pick-one).",
+  ].join("\n"));
+
   registerTool({
     name: "questionnaire",
     displayName: "questionnaire",
     description:
-      "Ask the user one or more questions with selectable options. " +
-      "Use for clarifying requirements, getting preferences, or confirming decisions. " +
-      "For single questions, shows a simple option list. " +
-      "For multiple questions, shows a tab-based interface.",
+      "Present the user with one or more questions with selectable options and wait for their interactive response. " +
+      "PREFER THIS over asking questions in plain text — it gives the user an interactive picker (arrow keys + enter). " +
+      "Use for: clarifying requirements, getting preferences, confirming decisions, choosing between options. " +
+      "Single question → simple option list. Multiple questions → tab-based multi-page interface.",
     input_schema: {
       type: "object",
       properties: {

package/examples/extensions/subagents.ts

@@ -8,8 +8,8 @@
  * Usage:
  *   agent-sh -e ./examples/extensions/subagents.ts
  */
-import type { ExtensionContext } from "../../src/types.js";
-import { runSubagent } from "../../src/agent/subagent.js";
+import type { ExtensionContext } from "agent-sh/types";
+import { runSubagent } from "agent-sh/agent/subagent";
 
 export default function activate(ctx: ExtensionContext): void {
   const { bus, llmClient, contextManager } = ctx;
@@ -17,6 +17,12 @@ export default function activate(ctx: ExtensionContext): void {
 
   const allToolNames = () => ctx.getTools().map(t => t.name);
 
+  ctx.registerInstruction("subagent-guide", [
+    "You have a spawn_agent tool for delegating work to a subagent with its own context.",
+    "The subagent inherits your session history, so write a short directive (what to do), not a briefing (what happened).",
+    "Use it for tasks that need multiple tool calls you don't need to see — research, exploration, independent implementation.",
+  ].join("\n"));
+
   ctx.registerTool({
     name: "spawn_agent",
     description:
@@ -44,8 +50,15 @@ export default function activate(ctx: ExtensionContext): void {
 
     getDisplayInfo: () => ({
       kind: "execute",
+      icon: "⤵",
     }),
 
+    formatCall: (args) => {
+      const task = String(args.task ?? "");
+      const max = 80;
+      return task.length > max ? task.slice(0, max - 1) + "…" : task;
+    },
+
     async execute(args) {
       const task = args.task as string;
       const toolNames = args.tools as string[] | undefined;
@@ -56,9 +69,12 @@ export default function activate(ctx: ExtensionContext): void {
         ? allTools.filter(t => toolNames.includes(t.name))
         : allTools.filter(t => t.name !== "spawn_agent");
 
+      const nuclearSummary = bus.emitPipe("agent:get-nuclear-summary", { summary: null }).summary;
+
       const systemPrompt =
         `You are a focused subagent. Complete the task and return a clear, concise result.\n` +
-        `Working directory: ${contextManager.getCwd()}`;
+        `Working directory: ${contextManager.getCwd()}` +
+        (nuclearSummary ? `\n\n[Parent session history]\n${nuclearSummary}` : "");
 
       try {
         const result = await runSubagent({
@@ -66,7 +82,6 @@ export default function activate(ctx: ExtensionContext): void {
           tools,
           systemPrompt,
           task,
-          bus,
           maxIterations: 25,
         });
 

package/examples/extensions/terminal-buffer.ts

@@ -0,0 +1,163 @@
+/**
+ * Terminal buffer extension.
+ *
+ * Registers two agent tools:
+ *   - terminal_read: get the current screen contents + cursor position
+ *   - terminal_keys: send raw keystrokes into the user's live PTY
+ *
+ * Together these let the agent operate inside interactive programs
+ * (vim, htop, less, etc.) by reading the screen and typing keys.
+ *
+ * Requires xterm in the extension directory:
+ *   npm install @xterm/headless@5.5.0 @xterm/addon-serialize@0.13.0
+ *
+ * Core already loads xterm lazily (for floating-panel compositing), so
+ * installing these deps anywhere on the NODE_PATH is enough.
+ */
+import type { ExtensionContext } from "agent-sh/types";
+
+/** Interpret C-style escape sequences (e.g. \r → CR, \x1b → ESC). */
+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));
+}
+
+export default function activate(ctx: ExtensionContext): void {
+  const { bus, terminalBuffer: tb, registerTool, registerInstruction } = ctx;
+  if (!tb) return; // @xterm/headless not installed
+
+  registerTool({
+    name: "terminal_read",
+    description:
+      "Read what is currently visible on the user's terminal screen. Returns clean text (ANSI stripped) " +
+      "with cursor position and whether an alternate-screen program (vim, htop, less) is active. " +
+      "Use this to observe what the user sees — helpful for answering questions about terminal output, " +
+      "diagnosing errors on screen, or checking state before/after sending keystrokes with terminal_keys.",
+    input_schema: {
+      type: "object",
+      properties: {
+        include_scrollback: {
+          type: "boolean",
+          description:
+            "If true, include scrollback buffer (content that scrolled off screen) " +
+            "in addition to the visible viewport. Useful for capturing output from " +
+            "long-running or streaming commands. Default: false.",
+        },
+      },
+    },
+    showOutput: true,
+
+    getDisplayInfo: () => ({
+      kind: "read" as const,
+      icon: "⊞",
+      locations: [],
+    }),
+
+    async execute(args) {
+      const includeScrollback = (args.include_scrollback as boolean) ?? false;
+      const { text, altScreen, cursorX, cursorY } = tb.readScreen({ includeScrollback });
+      const info = [
+        altScreen ? "mode: alternate screen" : "mode: normal",
+        `cursor: row=${cursorY} col=${cursorX}`,
+      ].join(", ");
+
+      return {
+        content: `[${info}]\n\n${text}`,
+        exitCode: 0,
+        isError: false,
+      };
+    },
+  });
+
+  registerTool({
+    name: "terminal_keys",
+    description:
+      "Send keystrokes directly into the user's live terminal PTY, as if the user typed them. " +
+      "Use this to interact with programs already running in the terminal (vim, htop, less, ssh, REPLs, etc.) " +
+      "or to type commands at the shell prompt. This types directly into whatever is currently on screen.\n\n" +
+      "Escape sequences for special keys:\n" +
+      "  - Escape: \\x1b\n" +
+      "  - Enter/Return: \\r\n" +
+      "  - Tab: \\t\n" +
+      "  - Ctrl+C: \\x03\n" +
+      "  - Ctrl+D: \\x04\n" +
+      "  - Ctrl+Z: \\x1a\n" +
+      "  - Arrow keys: \\x1b[A (up), \\x1b[B (down), \\x1b[C (right), \\x1b[D (left)\n" +
+      "  - Backspace: \\x7f\n\n" +
+      "Example: to quit vim without saving, send keys=\"\\x1b:q!\\r\" (Escape, :q!, Enter).\n" +
+      "Always call terminal_read after sending keys to verify the result.",
+    input_schema: {
+      type: "object",
+      properties: {
+        keys: {
+          type: "string",
+          description:
+            "The keystrokes to send. Use \\x1b for Escape, \\r for Enter, \\t for Tab, " +
+            "\\x03 for Ctrl+C, etc. Regular characters are sent as-is.",
+        },
+        settle_ms: {
+          type: "number",
+          description:
+            "Milliseconds to wait after sending keys for the terminal to settle before " +
+            "returning (default: 150). Increase for slow programs.",
+        },
+      },
+      required: ["keys"],
+    },
+    showOutput: false,
+
+    getDisplayInfo: () => ({
+      kind: "execute" as const,
+      icon: "⌨",
+      locations: [],
+    }),
+
+    formatCall: (args) => {
+      const keys = args.keys as string;
+      return keys
+        .replace(/\\x1b|\x1b/g, "ESC")
+        .replace(/\\r|\r/g, "⏎")
+        .replace(/\\n|\n/g, "↵")
+        .replace(/\\t|\t/g, "TAB")
+        .replace(/\\x03|\x03/g, "^C")
+        .replace(/\\x04|\x04/g, "^D")
+        .replace(/\\x7f|\x7f/g, "BS");
+    },
+
+    async execute(args) {
+      const raw = args.keys as string;
+      const keys = interpretEscapes(raw);
+      const settleMs = (args.settle_ms as number) ?? 150;
+
+      bus.emit("shell:stdout-show", {});
+      process.stdout.write("\n");
+      bus.emit("shell:pty-write", { data: keys });
+
+      await settle(settleMs);
+      bus.emit("shell:stdout-hide", {});
+
+      const { text, altScreen, cursorX, cursorY } = tb.readScreen();
+      const info = [
+        altScreen ? "mode: alternate screen" : "mode: normal",
+        `cursor: row=${cursorY} col=${cursorX}`,
+      ].join(", ");
+
+      return {
+        content: `Keys sent. Screen after:\n[${info}]\n\n${text}`,
+        exitCode: 0,
+        isError: false,
+      };
+    },
+  });
+}