agent-sh 0.12.26 → 0.12.27

package/examples/extensions/emacs-buffer.ts

@@ -0,0 +1,364 @@
+/**
+ * Emacs buffer extension.
+ *
+ * Mirrors the terminal-buffer extension but for a running Emacs server,
+ * trading PTY screen-scraping for structural access via `emacsclient -e`.
+ *
+ * Registers three agent tools (only when `emacsclient` is available and
+ * a server is reachable):
+ *
+ *   - emacs_read  : structured snapshot of the selected window —
+ *                   buffer, file, mode, point, narrowing, modeline,
+ *                   echo area, and the visible region (window-start
+ *                   to window-end). Optional all-windows mode.
+ *
+ *   - emacs_keys  : send a `kbd`-notation key sequence
+ *                   (e.g. "C-x C-s", "SPC f f"). Goes through Emacs's
+ *                   own key parser, so failed chords don't leak as
+ *                   literal text and Doom leaders work without timing
+ *                   tricks.
+ *
+ *   - emacs_eval  : evaluate arbitrary elisp inside the running Emacs.
+ *                   Use for structural operations (buffer edits,
+ *                   window manipulation, calling commands directly).
+ *
+ * All three round-trip results through a temp file as JSON. Requires
+ * Emacs 27+ for `json-serialize`.
+ *
+ * Usage:
+ *   ash -e ./examples/extensions/emacs-buffer.ts
+ *
+ *   # Or install permanently
+ *   cp examples/extensions/emacs-buffer.ts ~/.agent-sh/extensions/
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { spawnSync } from "node:child_process";
+import type { ExtensionContext } from "agent-sh/types";
+
+function emacsclientAvailable(): boolean {
+  // `emacsclient -e t` exits 0 only if a server is actually reachable.
+  const r = spawnSync("emacsclient", ["-e", "t"], { encoding: "utf-8" });
+  return r.status === 0;
+}
+
+function evalToJson<T = unknown>(body: string): T {
+  const out = path.join(
+    os.tmpdir(),
+    `agent-sh-emacs-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.json`,
+  );
+  // Compute the result *before* with-temp-file: inside its body, current-buffer
+  // is the temp buffer, and execute-kbd-macro can shift current-buffer to the
+  // user's live buffer mid-flight, causing (insert ...) to write JSON into it.
+  const wrapped = `(let ((__result (progn ${body}))) (with-temp-file ${JSON.stringify(out)} (insert (json-serialize __result))))`;
+  const r = spawnSync("emacsclient", ["-e", wrapped], { encoding: "utf-8" });
+  if (r.status !== 0) {
+    try { fs.unlinkSync(out); } catch { /* ignore */ }
+    throw new Error(`emacsclient failed: ${(r.stderr || r.stdout || "").trim()}`);
+  }
+  let json: string;
+  try {
+    json = fs.readFileSync(out, "utf-8");
+  } finally {
+    try { fs.unlinkSync(out); } catch { /* ignore */ }
+  }
+  return JSON.parse(json) as T;
+}
+
+// Used by emacs_eval, where the result might not be JSON-serializable.
+function evalPrinted(body: string): string {
+  const r = spawnSync("emacsclient", ["-e", body], { encoding: "utf-8" });
+  if (r.status !== 0) {
+    throw new Error(`emacsclient failed: ${(r.stderr || r.stdout || "").trim()}`);
+  }
+  return r.stdout.replace(/\n$/, "");
+}
+
+interface WindowSnapshot {
+  selected: boolean;
+  buffer: string;
+  file: string | null;
+  mode: string;
+  modified: boolean;
+  narrowed: boolean;
+  point: number;
+  line: number;
+  column: number;
+  window_start: number;
+  window_end: number;
+  visible: string;
+  modeline: string;
+}
+
+interface EmacsSnapshot {
+  windows: WindowSnapshot[];
+  echo_area: string | null;
+  minibuffer_active: boolean;
+  minibuffer_prompt: string | null;
+  minibuffer_contents: string | null;
+}
+
+// Plist for one window. Conventions: t / :false for booleans (json-serialize
+// would otherwise map nil → {}, not null), :null for explicit nulls.
+const WINDOW_PLIST = `
+  (let* ((buf (window-buffer w))
+         (s (window-start w))
+         (e (window-end w t)))
+    (with-current-buffer buf
+      (save-excursion
+        (goto-char (window-point w))
+        (list
+          :selected (if (eq w (selected-window)) t :false)
+          :buffer (buffer-name)
+          :file (or (buffer-file-name) :null)
+          :mode (symbol-name major-mode)
+          :modified (if (buffer-modified-p) t :false)
+          :narrowed (if (or (/= (point-min) 1) (/= (point-max) (1+ (buffer-size)))) t :false)
+          :point (point)
+          :line (line-number-at-pos (point))
+          :column (current-column)
+          :window_start s
+          :window_end e
+          :visible (buffer-substring-no-properties s e)
+          :modeline (substring-no-properties (format-mode-line mode-line-format nil w))))))
+`;
+
+function snapshotElisp(allWindows: boolean): string {
+  const winList = allWindows
+    ? "(window-list)"
+    : "(list (selected-window))";
+  return `
+    (list
+      :windows (vconcat
+        (mapcar (lambda (w) ${WINDOW_PLIST}) ${winList}))
+      :echo_area (or (current-message) :null)
+      :minibuffer_active (if (active-minibuffer-window) t :false)
+      :minibuffer_prompt (or (and (active-minibuffer-window)
+                                  (with-current-buffer (window-buffer (minibuffer-window))
+                                    (or (minibuffer-prompt) "")))
+                             :null)
+      :minibuffer_contents (or (and (active-minibuffer-window)
+                                    (with-current-buffer (window-buffer (minibuffer-window))
+                                      (minibuffer-contents-no-properties)))
+                               :null))
+  `;
+}
+
+function snapshot(allWindows: boolean): EmacsSnapshot {
+  return evalToJson<EmacsSnapshot>(snapshotElisp(allWindows));
+}
+
+function renderWindow(w: WindowSnapshot, idx: number): string {
+  const tag = w.selected ? "selected" : `window ${idx}`;
+  const flags: string[] = [];
+  if (w.modified) flags.push("modified");
+  if (w.narrowed) flags.push("narrowed");
+  const flagsStr = flags.length ? ` [${flags.join(", ")}]` : "";
+  const fileStr = w.file ? ` file=${w.file}` : "";
+  const visible = markCursor(w.visible, w.point - w.window_start);
+
+  return [
+    `── ${tag}${flagsStr} ──`,
+    `buffer=${w.buffer}${fileStr} mode=${w.mode}`,
+    `point=${w.point} line=${w.line} col=${w.column}`,
+    `modeline: ${w.modeline}`,
+    `visible (${w.window_start}..${w.window_end}):`,
+    visible,
+  ].join("\n");
+}
+
+function markCursor(visible: string, offset: number): string {
+  if (offset < 0 || offset > visible.length) return visible;
+  return visible.slice(0, offset) + "▮" + visible.slice(offset);
+}
+
+function renderSnapshot(snap: EmacsSnapshot): string {
+  const parts = snap.windows.map((w, i) => renderWindow(w, i));
+  if (snap.minibuffer_active && snap.minibuffer_prompt !== null) {
+    parts.push(
+      `── minibuffer ──\n${snap.minibuffer_prompt}${snap.minibuffer_contents ?? ""}`,
+    );
+  }
+  if (snap.echo_area) {
+    parts.push(`── echo area ──\n${snap.echo_area}`);
+  }
+  return parts.join("\n\n");
+}
+
+export default function activate(ctx: ExtensionContext): void {
+  const { registerTool } = ctx;
+  if (!emacsclientAvailable()) return;
+
+  registerTool({
+    name: "emacs_read",
+    description:
+      "Read the state of the user's running Emacs: selected window's buffer, " +
+      "file path, major mode, point (line/column), narrowing, modeline, the " +
+      "currently visible region (window-start to window-end) with a ▮ cursor " +
+      "marker, plus the echo area / minibuffer if active. With all_windows=true, " +
+      "returns the same data for every visible window. Use this to ground answers " +
+      "in what the user is actually looking at, not just guessing from filenames. " +
+      "Far more reliable than terminal_read for Emacs — it sees structure, not pixels.",
+    input_schema: {
+      type: "object",
+      properties: {
+        all_windows: {
+          type: "boolean",
+          description:
+            "Include every visible window in the current frame, not just the " +
+            "selected one. Default: false.",
+        },
+      },
+    },
+    showOutput: true,
+    getDisplayInfo: () => ({ kind: "read" as const, icon: "⌬", locations: [] }),
+
+    async execute(args) {
+      const all = (args.all_windows as boolean) ?? false;
+      try {
+        const snap = snapshot(all);
+        return { content: renderSnapshot(snap), exitCode: 0, isError: false };
+      } catch (e) {
+        return {
+          content: `emacs_read failed: ${(e as Error).message}`,
+          exitCode: 1,
+          isError: true,
+        };
+      }
+    },
+  });
+
+  registerTool({
+    name: "emacs_keys",
+    description:
+      "Send a key sequence to the user's running Emacs, parsed by Emacs itself " +
+      "via `kbd`. Use Emacs `kbd` notation:\n" +
+      "  C-x C-s        — Ctrl+x Ctrl+s (save)\n" +
+      "  M-x            — Meta/Alt+x\n" +
+      "  C-M-f          — Ctrl+Meta+f\n" +
+      "  SPC f f        — Doom/Spacemacs leader find-file (no timing tricks needed)\n" +
+      "  RET ESC TAB DEL — named keys\n" +
+      "  <up> <down>    — arrow keys\n\n" +
+      "Why this beats terminal_keys for Emacs: the key parser is authoritative, so " +
+      "C-c works as a prefix without queueing garbage, leader keys resolve without " +
+      "inter-key delays, and failed chords surface as a `kbd` parse error instead of " +
+      "leaking into the buffer as text. Returns a fresh emacs_read snapshot after " +
+      "the keys execute.",
+    input_schema: {
+      type: "object",
+      properties: {
+        keys: {
+          type: "string",
+          description:
+            "A `kbd`-style key sequence, e.g. \"C-x C-s\", \"M-x find-file RET\", \"SPC f f\".",
+        },
+      },
+      required: ["keys"],
+    },
+    showOutput: false,
+    getDisplayInfo: () => ({ kind: "execute" as const, icon: "⌥", locations: [] }),
+    formatCall: (args) => `keys: ${args.keys}`,
+
+    async execute(args) {
+      const keys = args.keys as string;
+      try {
+        // condition-case so kbd parse / runtime errors surface structurally
+        // rather than as a non-zero emacsclient exit.
+        const body = `
+          (condition-case err
+              (progn
+                (execute-kbd-macro (kbd ${JSON.stringify(keys)}))
+                ${snapshotElisp(false).trim()})
+            (error (list :error (error-message-string err))))
+        `;
+        const result = evalToJson<EmacsSnapshot | { error: string }>(body);
+        if ("error" in result) {
+          return {
+            content: `emacs_keys error: ${result.error}`,
+            exitCode: 1,
+            isError: true,
+          };
+        }
+        return {
+          content: `Keys sent.\n\n${renderSnapshot(result)}`,
+          exitCode: 0,
+          isError: false,
+        };
+      } catch (e) {
+        return {
+          content: `emacs_keys failed: ${(e as Error).message}`,
+          exitCode: 1,
+          isError: true,
+        };
+      }
+    },
+  });
+
+  registerTool({
+    name: "emacs_eval",
+    description:
+      "Evaluate elisp inside the user's running Emacs. The high-leverage tool: " +
+      "buffer edits, window manipulation, calling named commands, reading any " +
+      "data structure Emacs knows. Returns the printed value plus a fresh " +
+      "emacs_read snapshot.\n\n" +
+      "Useful idioms:\n" +
+      "  (with-current-buffer \"foo.org\" (buffer-substring-no-properties (point-min) (point-max)))\n" +
+      "  (with-current-buffer (window-buffer (selected-window)) (save-buffer))\n" +
+      "  (call-interactively '+default/find-file)\n" +
+      "  (split-window-right)\n\n" +
+      "Caveat: this mutates the user's live editor. The change is undoable in the " +
+      "buffer (C-/) but not all elisp side effects are reversible — be deliberate.",
+    input_schema: {
+      type: "object",
+      properties: {
+        elisp: {
+          type: "string",
+          description:
+            "Elisp form(s) to evaluate. Multiple forms are allowed; only the last " +
+            "form's value is returned in the printed-value section.",
+        },
+        skip_snapshot: {
+          type: "boolean",
+          description:
+            "If true, don't return a post-eval emacs_read snapshot. Useful for " +
+            "pure read-only evals where the snapshot would be noise. Default: false.",
+        },
+      },
+      required: ["elisp"],
+    },
+    showOutput: false,
+    getDisplayInfo: () => ({ kind: "execute" as const, icon: "λ", locations: [] }),
+    formatCall: (args) => {
+      const elisp = (args.elisp as string).trim().split("\n")[0];
+      return elisp.length > 80 ? elisp.slice(0, 77) + "..." : elisp;
+    },
+
+    async execute(args) {
+      const elisp = args.elisp as string;
+      const skipSnap = (args.skip_snapshot as boolean) ?? false;
+      try {
+        const printed = evalPrinted(elisp);
+        let suffix = "";
+        if (!skipSnap) {
+          try {
+            suffix = "\n\n" + renderSnapshot(snapshot(false));
+          } catch (e) {
+            suffix = `\n\n(snapshot failed: ${(e as Error).message})`;
+          }
+        }
+        return {
+          content: `=> ${printed}${suffix}`,
+          exitCode: 0,
+          isError: false,
+        };
+      } catch (e) {
+        return {
+          content: `emacs_eval failed: ${(e as Error).message}`,
+          exitCode: 1,
+          isError: true,
+        };
+      }
+    },
+  });
+}

package/examples/extensions/overlay-agent.ts

@@ -104,8 +104,18 @@ export default function activate(ctx: ExtensionContext): void {
         surface: panelSurface,
       });
     }
-    panel.setActive();
-    session.submit(query);
+    if (query.startsWith("/")) {
+      // Sync commands (/model, /help) render via ui:info and leave us in
+      // input phase; ones that fan out to agent:submit flip the phase via
+      // the agent:processing-start listener below.
+      const spaceIdx = query.indexOf(" ");
+      const name = spaceIdx === -1 ? query : query.slice(0, spaceIdx);
+      const args = spaceIdx === -1 ? "" : query.slice(spaceIdx + 1).trim();
+      bus.emit("command:execute", { name, args });
+    } else {
+      panel.setActive();
+      session.submit(query);
+    }
   });
 
   panel.handlers.advise("panel:show", (_next) => {
@@ -114,9 +124,9 @@ export default function activate(ctx: ExtensionContext): void {
     }
   });
 
-  // Keep the session alive while the agent is still working, even after
-  // dismiss — so output keeps buffering and tools keep executing.
-  panel.handlers.advise("panel:dismiss", (next) => {
+  // While the agent is still working, keep the session open so output and
+  // tool calls survive a hide. Once it's idle, close to release redirects.
+  panel.handlers.advise("panel:hide", (next) => {
     next();
     if (session && !panel.processing) {
       session.close();
@@ -124,6 +134,19 @@ export default function activate(ctx: ExtensionContext): void {
     }
   });
 
+  panel.handlers.advise("panel:reset", (next) => {
+    next();
+    if (session) {
+      session.close();
+      session = null;
+    }
+  });
+
+  // Picks up turns triggered indirectly (e.g. /skill:foo → agent:submit).
+  bus.on("agent:processing-start", () => {
+    if (panel.active && !panel.processing) panel.setActive();
+  });
+
   bus.on("agent:processing-done", () => {
     if (panel.active) panel.setDone();
   });

package/examples/extensions/terminal-buffer.ts

@@ -16,25 +16,129 @@
  */
 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;
-  });
+const NAMED_KEYS: Record<string, string> = {
+  RET: "\r", ENTER: "\r", CR: "\r",
+  ESC: "\x1b",
+  TAB: "\t",
+  BS: "\x7f", BACKSPACE: "\x7f",
+  DEL: "\x1b[3~", DELETE: "\x1b[3~",
+  SPC: " ", SPACE: " ",
+  UP: "\x1b[A", DOWN: "\x1b[B", RIGHT: "\x1b[C", LEFT: "\x1b[D",
+  HOME: "\x1b[H", END: "\x1b[F",
+  PGUP: "\x1b[5~", PGDN: "\x1b[6~",
+};
+
+function ctrlByte(ch: string): string {
+  if (ch === " ") return "\x00";
+  const code = ch.charCodeAt(0);
+  if (code >= 0x40 && code <= 0x7e) return String.fromCharCode(code & 0x1f);
+  throw new Error(`Cannot apply Ctrl modifier to ${JSON.stringify(ch)}`);
+}
+
+function parseToken(body: string): string {
+  if (!body) throw new Error("Empty key token <>");
+  const upper = body.toUpperCase();
+  if (upper in NAMED_KEYS) return NAMED_KEYS[upper];
+
+  const fn = /^F(\d{1,2})$/i.exec(body);
+  if (fn) {
+    const n = parseInt(fn[1], 10);
+    const map: Record<number, string> = {
+      1: "\x1bOP", 2: "\x1bOQ", 3: "\x1bOR", 4: "\x1bOS",
+      5: "\x1b[15~", 6: "\x1b[17~", 7: "\x1b[18~", 8: "\x1b[19~",
+      9: "\x1b[20~", 10: "\x1b[21~", 11: "\x1b[23~", 12: "\x1b[24~",
+    };
+    if (n in map) return map[n];
+    throw new Error(`Unknown function key <${body}>`);
+  }
+
+  let rest = body;
+  let ctrl = false, meta = false;
+  while (true) {
+    if (/^C-/i.test(rest)) { ctrl = true; rest = rest.slice(2); }
+    else if (/^M-/i.test(rest) || /^A-/i.test(rest)) { meta = true; rest = rest.slice(2); }
+    else break;
+  }
+
+  let core: string;
+  const restUpper = rest.toUpperCase();
+  if (restUpper in NAMED_KEYS) core = NAMED_KEYS[restUpper];
+  else if (rest.length === 1) core = rest;
+  else throw new Error(`Unparseable key token <${body}>`);
+
+  if (ctrl) {
+    if (core.length !== 1) {
+      throw new Error(`Ctrl modifier on multi-byte key <${body}> not supported`);
+    }
+    core = ctrlByte(core);
+  }
+  if (meta) core = "\x1b" + core;
+  return core;
+}
+
+/**
+ * Tokenize a `keys` string into chords — atomic units that get written
+ * separately when inter_key_ms > 0, so multi-key leaders resolve under
+ * the leader timer.
+ */
+export function tokenizeKeys(input: string): string[] {
+  const chords: string[] = [];
+  let i = 0;
+  while (i < input.length) {
+    const ch = input[i];
+    if (ch === "<") {
+      const end = input.indexOf(">", i + 1);
+      if (end === -1) throw new Error(`Unterminated key token starting at index ${i}`);
+      chords.push(parseToken(input.slice(i + 1, end)));
+      i = end + 1;
+      continue;
+    }
+    if (ch === "\\" && i + 1 < input.length) {
+      const next = input[i + 1];
+      if (next === "r") { chords.push("\r"); i += 2; continue; }
+      if (next === "n") { chords.push("\n"); i += 2; continue; }
+      if (next === "t") { chords.push("\t"); i += 2; continue; }
+      if (next === "\\") { chords.push("\\"); i += 2; continue; }
+      if (next === "0") { chords.push("\0"); i += 2; continue; }
+      if (next === "x" && i + 3 < input.length) {
+        const hex = input.slice(i + 2, i + 4);
+        if (/^[0-9a-fA-F]{2}$/.test(hex)) {
+          chords.push(String.fromCharCode(parseInt(hex, 16)));
+          i += 4;
+          continue;
+        }
+      }
+      chords.push(ch);
+      i += 1;
+      continue;
+    }
+    chords.push(ch);
+    i += 1;
+  }
+  return chords;
 }
 
 function settle(ms = 100): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+function diffScreens(before: string, after: string): string {
+  const beforeLines = before.split("\n");
+  const afterLines = after.split("\n");
+  const max = Math.max(beforeLines.length, afterLines.length);
+  const changes: string[] = [];
+  for (let i = 0; i < max; i++) {
+    const a = beforeLines[i] ?? "";
+    const b = afterLines[i] ?? "";
+    if (a !== b) changes.push(`row ${i}: ${JSON.stringify(a)} → ${JSON.stringify(b)}`);
+  }
+  if (changes.length === 0) return "(no visible change)";
+  if (changes.length > 12) return `${changes.length} rows changed (see full screen below)`;
+  return changes.join("\n");
+}
+
 export default function activate(ctx: ExtensionContext): void {
-  const { bus, registerTool, registerInstruction } = ctx;
+  const { bus, registerTool } = ctx;
   const tb = ctx.call("terminal-buffer");
   if (!tb) return; // @xterm/headless not installed, or shell frontend not loaded
 
@@ -86,17 +190,22 @@ export default function activate(ctx: ExtensionContext): void {
     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" +
+      "or to type commands at the shell prompt.\n\n" +
+      "Preferred input: named-key tokens in angle brackets. They are unambiguous and let inter_key_ms " +
+      "delay the right boundaries (one chord per token):\n" +
+      "  <RET> <ESC> <TAB> <BS> <DEL> <SPC>\n" +
+      "  <UP> <DOWN> <LEFT> <RIGHT> <HOME> <END> <PGUP> <PGDN>\n" +
+      "  <F1>..<F12>\n" +
+      "  <C-x> = Ctrl+x, <M-x> = Meta/Alt+x, <C-M-x> = Ctrl+Meta+x\n\n" +
+      "Backslash escapes are also accepted for raw bytes: \\r \\n \\t \\xNN.\n\n" +
+      "Example: quit vim without saving — keys=\"<ESC>:q!<RET>\" (or the older \"\\x1b:q!\\r\").\n\n" +
+      "Emacs pitfalls (read before sending keys to a running Emacs):\n" +
+      "  - Abort is <C-g>, NOT <C-c>. <C-c> is a prefix key in Emacs and will queue garbage.\n" +
+      "  - Failed multi-key chords get inserted into the buffer as literal text. Send small, " +
+      "    well-tested sequences and call terminal_read between them to verify.\n" +
+      "  - Doom/Spacemacs leader sequences (e.g. <SPC> f f) need timing — set inter_key_ms=50 " +
+      "    or higher so the leader timer can resolve each chord.\n" +
+      "  - For complex Emacs operations, prefer `emacsclient -e '(...)'` over typing keys.\n\n" +
       "Always call terminal_read after sending keys to verify the result.",
     input_schema: {
       type: "object",
@@ -104,14 +213,20 @@ export default function activate(ctx: ExtensionContext): void {
         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.",
+            "The keystrokes to send. Prefer named tokens like <C-g>, <RET>, <ESC>, <SPC>. " +
+            "Backslash escapes (\\r, \\t, \\x1b) and raw characters are also accepted.",
         },
         settle_ms: {
           type: "number",
           description:
-            "Milliseconds to wait after sending keys for the terminal to settle before " +
-            "returning (default: 150). Increase for slow programs.",
+            "Milliseconds to wait after the last chord for the terminal to settle before " +
+            "snapshotting the screen (default: 150). Increase for slow programs.",
+        },
+        inter_key_ms: {
+          type: "number",
+          description:
+            "Milliseconds to wait between chords. Default 0 (send all at once). Set ~50 for " +
+            "Doom/Spacemacs leader sequences or any binding that depends on key-chord timeouts.",
         },
       },
       required: ["keys"],
@@ -133,29 +248,55 @@ export default function activate(ctx: ExtensionContext): void {
         .replace(/\\t|\t/g, "TAB")
         .replace(/\\x03|\x03/g, "^C")
         .replace(/\\x04|\x04/g, "^D")
+        .replace(/\\x07|\x07/g, "^G")
         .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;
+      const interKeyMs = (args.inter_key_ms as number) ?? 0;
+
+      let chords: string[];
+      try {
+        chords = tokenizeKeys(raw);
+      } catch (e) {
+        return {
+          content: `Invalid keys argument: ${(e as Error).message}`,
+          exitCode: 1,
+          isError: true,
+        };
+      }
+
+      tb.flush();
+      const before = tb.readScreen();
 
       bus.emit("shell:stdout-show", {});
       process.stdout.write("\n");
-      bus.emit("shell:pty-write", { data: keys });
+
+      for (let i = 0; i < chords.length; i++) {
+        bus.emit("shell:pty-write", { data: chords[i] });
+        if (interKeyMs > 0 && i < chords.length - 1) {
+          await settle(interKeyMs);
+        }
+      }
 
       await settle(settleMs);
       bus.emit("shell:stdout-hide", {});
 
-      const { text, altScreen, cursorX, cursorY } = tb.readScreen();
+      tb.flush();
+      const after = tb.readScreen();
       const info = [
-        altScreen ? "mode: alternate screen" : "mode: normal",
-        `cursor: row=${cursorY} col=${cursorX}`,
+        after.altScreen ? "mode: alternate screen" : "mode: normal",
+        `cursor: row=${after.cursorY} col=${after.cursorX}`,
       ].join(", ");
+      const diff = diffScreens(before.text, after.text);
 
       return {
-        content: `Keys sent. Screen after:\n[${info}]\n\n${text}`,
+        content:
+          `Keys sent (${chords.length} chord${chords.length === 1 ? "" : "s"}).\n` +
+          `Diff:\n${diff}\n\n` +
+          `Screen after:\n[${info}]\n\n${after.text}`,
         exitCode: 0,
         isError: false,
       };