@ai-devkit/agent-manager 0.37.0 → 0.39.0

package/src/terminal/TtyWriter.ts

@@ -1,346 +1,26 @@
-import { execFile } from "child_process";
-import { promisify } from "util";
-import type { TerminalLocation } from "./TerminalFocusManager.js";
-import { TerminalType } from "./TerminalFocusManager.js";
-import { escapeAppleScript } from "../utils/applescript.js";
+import { TERMINAL_BACKENDS, terminalBackendFor } from "./backends/index.js";
+import type { TerminalLocation } from "./types.js";
 
-const execFileAsync = promisify(execFile);
-
-/**
- * Carriage return byte (0x0d). Sent as a fixed discrete argv element with
- * `--no-paste` to deliver Enter literally (shell equivalent: $'\x0d').
- */
-const CARRIAGE_RETURN = "\x0d";
-
-/**
- * Escape byte (0x1b). Recognized by `sendKey` and translated to the
- * backend-native representation (`Escape` for tmux, `key code 53` for
- * AppleScript, the literal byte for WezTerm).
- */
-const ESCAPE_BYTE = "\x1b";
+const SUPPORTED = `Supported: ${TERMINAL_BACKENDS.map((backend) => backend.label).join(", ")}.`;
 
 export class TtyWriter {
-  /**
-   * Send a message as keyboard input to a terminal session.
-   *
-   * Dispatches to the correct mechanism based on terminal type:
-   * - tmux: `tmux send-keys`
-   * - iTerm2: Two separate AppleScript `write text` calls (text then newline)
-   * - Terminal.app: Two separate AppleScript `do script` calls (text then newline)
-   *
-   * All AppleScript is executed via `execFile('osascript', ['-e', script])`
-   * to avoid shell interpolation and command injection.
-   *
-   * @param location Terminal location from TerminalFocusManager.findTerminal()
-   * @param message Text to send
-   * @throws Error if terminal type is unsupported or send fails
-   */
   static async send(location: TerminalLocation, message: string): Promise<void> {
-    switch (location.type) {
-      case TerminalType.TMUX:
-        return TtyWriter.sendViaTmux(location.identifier, message);
-      case TerminalType.WEZTERM:
-        return TtyWriter.sendViaWezterm(location.identifier, message);
-      case TerminalType.ITERM2:
-        return TtyWriter.sendViaITerm2(location.tty, message);
-      case TerminalType.TERMINAL_APP:
-        return TtyWriter.sendViaTerminalApp(location.tty, message);
-      default:
-        throw new Error(
-          `Cannot send input: unsupported terminal type "${location.type}". ` +
-            "Supported: tmux, WezTerm, iTerm2, Terminal.app.",
-        );
+    const backend = terminalBackendFor(location.type);
+    if (!backend) {
+      throw new Error(
+        `Cannot send input: unsupported terminal type "${location.type}". ${SUPPORTED}`,
+      );
     }
+    await backend.send(location, message);
   }
 
-  /**
-   * Send a single raw key (e.g. "1", "Enter", "Up") to the terminal as a
-   * keystroke — bypassing bracketed paste and without auto-appending Enter.
-   *
-   * Use this when the target TUI distinguishes between typed text and raw
-   * keypresses (e.g. an `AskUserQuestion` picker that selects on digit-key
-   * press, not on a pasted digit followed by Enter).
-   *
-   * - tmux: `tmux send-keys -t <id> <key>` — direct keystroke, no paste buffer.
-   * - WezTerm: `wezterm cli send-text --pane-id <id> --no-paste <key>`.
-   * - iTerm2 / Terminal.app: AppleScript via System Events. Requires
-   *   Accessibility permissions.
-   */
   static async sendKey(location: TerminalLocation, key: string): Promise<void> {
-    switch (location.type) {
-      case TerminalType.TMUX:
-        return TtyWriter.sendKeyViaTmux(location.identifier, key);
-      case TerminalType.WEZTERM:
-        return TtyWriter.sendKeyViaWezterm(location.identifier, key);
-      case TerminalType.ITERM2:
-        return TtyWriter.sendKeyViaITerm2(location.tty, key);
-      case TerminalType.TERMINAL_APP:
-        return TtyWriter.sendKeyViaTerminalApp(location.tty, key);
-      default:
-        throw new Error(
-          `Cannot send key: unsupported terminal type "${location.type}". ` +
-            "Supported: tmux, WezTerm, iTerm2, Terminal.app.",
-        );
-    }
-  }
-
-  private static async sendKeyViaTmux(identifier: string, key: string): Promise<void> {
-    // tmux send-keys interprets named keys (Enter, Up, Escape, ...) and
-    // passes literals through. No bracketed paste, no auto-Enter.
-    const arg = key === ESCAPE_BYTE ? "Escape" : key;
-    await execFileAsync("tmux", ["send-keys", "-t", identifier, arg]);
-  }
-
-  private static async sendKeyViaWezterm(paneId: string, key: string): Promise<void> {
-    // --no-paste delivers the key bytes literally outside bracketed-paste
-    // markers; the TUI sees a raw keystroke. For Esc (`\x1b`), wezterm
-    // accepts the byte directly.
-    await execFileAsync("wezterm", ["cli", "send-text", "--pane-id", paneId, "--no-paste", key]);
-  }
-
-  private static async sendKeyViaITerm2(tty: string, key: string): Promise<void> {
-    // Focus the target session, then press the key via System Events so the
-    // inner TUI sees a raw keystroke (not a bracketed-paste text run).
-    const action = appleScriptKeyAction(key);
-    const script = `
-tell application "iTerm"
-  set targetSession to missing value
-  repeat with w in windows
-    repeat with t in tabs of w
-      repeat with s in sessions of t
-        if tty of s is "${tty}" then
-          set targetSession to s
-          set frontmost of w to true
-          tell t to select
-          tell s to select
-          exit repeat
-        end if
-      end repeat
-      if targetSession is not missing value then exit repeat
-    end repeat
-    if targetSession is not missing value then exit repeat
-  end repeat
-  if targetSession is missing value then return "not_found"
-  activate
-end tell
-tell application "System Events" to ${action}
-return "ok"`;
-
-    const { stdout } = await execFileAsync("osascript", ["-e", script]);
-    if (stdout.trim() !== "ok") {
-      throw new Error(`iTerm2 session not found for TTY ${tty}`);
+    const backend = terminalBackendFor(location.type);
+    if (!backend) {
+      throw new Error(
+        `Cannot send key: unsupported terminal type "${location.type}". ${SUPPORTED}`,
+      );
     }
+    await backend.sendKey(location, key);
   }
-
-  private static async sendKeyViaTerminalApp(tty: string, key: string): Promise<void> {
-    const action = appleScriptKeyAction(key);
-    const script = `
-tell application "Terminal"
-  set targetTab to missing value
-  set targetWindow to missing value
-  repeat with w in windows
-    repeat with i from 1 to count of tabs of w
-      set t to tab i of w
-      if tty of t is "${tty}" then
-        set targetTab to t
-        set targetWindow to w
-        exit repeat
-      end if
-    end repeat
-    if targetTab is not missing value then exit repeat
-  end repeat
-  if targetTab is missing value then return "not_found"
-  set selected of targetTab to true
-  set frontmost of targetWindow to true
-  activate
-end tell
-tell application "System Events" to ${action}
-return "ok"`;
-
-    const { stdout } = await execFileAsync("osascript", ["-e", script]);
-    if (stdout.trim() !== "ok") {
-      throw new Error(`Terminal.app tab not found for TTY ${tty}`);
-    }
-  }
-
-  private static async sendViaWezterm(paneId: string, message: string): Promise<void> {
-    // Two explicit CLI calls, mirroring the text-then-Enter convention used
-    // by tmux / iTerm2 / Terminal.app so a bracketed-paste-aware TUI still
-    // sees Enter as a submit.
-    //
-    // Step 1 (text): write the message to stdin so prompt contents are not
-    // exposed through process arguments. execFile still spawns wezterm
-    // directly (no shell), so shell metacharacters remain inert.
-    // Step 2 (Enter): pass a fixed carriage return (0x0d) as a discrete
-    // argv element (the JS char '\x0d') with --no-paste, so the CR is
-    // delivered literally rather than wrapped in paste brackets. The
-    // equivalent shell command is:
-    //   wezterm cli send-text --pane-id <id> --no-paste $'\x0d'
-    // (ANSI-C quoting, note the leading $).
-    await TtyWriter.execFileWithInput(
-      "wezterm",
-      ["cli", "send-text", "--pane-id", paneId],
-      message,
-    );
-    await new Promise((resolve) => setTimeout(resolve, 150));
-    await execFileAsync("wezterm", [
-      "cli",
-      "send-text",
-      "--pane-id",
-      paneId,
-      "--no-paste",
-      CARRIAGE_RETURN,
-    ]);
-  }
-
-  private static async sendViaTmux(identifier: string, message: string): Promise<void> {
-    // Paste the message body using tmux bracketed paste, then send Enter as
-    // a separate key so the inner TUI treats it as submission rather than
-    // pasted content.
-    const bufferName = `ai-devkit-send-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
-    await TtyWriter.execFileWithInput("tmux", ["load-buffer", "-b", bufferName, "-"], message);
-    await execFileAsync("tmux", ["paste-buffer", "-t", identifier, "-b", bufferName, "-p", "-d"]);
-    await new Promise((resolve) => setTimeout(resolve, 150));
-    await execFileAsync("tmux", ["send-keys", "-t", identifier, "Enter"]);
-  }
-
-  private static async execFileWithInput(
-    command: string,
-    args: string[],
-    input: string,
-  ): Promise<void> {
-    await new Promise<void>((resolve, reject) => {
-      const child = execFile(command, args, (error) => {
-        if (error) {
-          reject(error);
-          return;
-        }
-        resolve();
-      });
-      if (!child.stdin) {
-        reject(new Error(`Cannot write stdin to ${command}`));
-        return;
-      }
-      child.stdin.end(input);
-    });
-  }
-
-  /**
-   * Build an AppleScript that finds an iTerm2 session by TTY and runs a
-   * command against it. The `sessionCommand` is inserted inside a
-   * `tell targetSession` block.
-   */
-  private static iterm2SessionScript(tty: string, sessionCommand: string): string {
-    return `
-tell application "iTerm"
-  set targetSession to missing value
-  repeat with w in windows
-    repeat with t in tabs of w
-      repeat with s in sessions of t
-        if tty of s is "${tty}" then
-          set targetSession to s
-          exit repeat
-        end if
-      end repeat
-      if targetSession is not missing value then exit repeat
-    end repeat
-    if targetSession is not missing value then exit repeat
-  end repeat
-  if targetSession is missing value then return "not_found"
-  tell targetSession to ${sessionCommand}
-end tell
-return "ok"`;
-  }
-
-  private static async sendViaITerm2(tty: string, message: string): Promise<void> {
-    const escaped = escapeAppleScript(message);
-    // Send text and Enter as two separate write text calls so the newline
-    // is delivered outside the bracketed paste sequence of the message body.
-    // iTerm2 appends the newline after the paste-end marker (\e[201~), so
-    // the inner TUI (Claude Code, Codex) sees it as a real submit action.
-    const textScript = TtyWriter.iterm2SessionScript(tty, `write text "${escaped}" newline no`);
-
-    const { stdout: textResult } = await execFileAsync("osascript", ["-e", textScript]);
-    if (textResult.trim() !== "ok") {
-      throw new Error(`iTerm2 session not found for TTY ${tty}`);
-    }
-
-    // Wait for the paste to complete before sending Enter separately
-    await new Promise((resolve) => setTimeout(resolve, 150));
-
-    const enterScript = TtyWriter.iterm2SessionScript(tty, 'write text "" newline yes');
-    const { stdout: enterResult } = await execFileAsync("osascript", ["-e", enterScript]);
-    if (enterResult.trim() !== "ok") {
-      throw new Error(`iTerm2 session disappeared before Enter could be sent for TTY ${tty}`);
-    }
-  }
-
-  private static async sendViaTerminalApp(tty: string, message: string): Promise<void> {
-    const escaped = escapeAppleScript(message);
-    // Use Terminal.app's `do script` to send text to the correct tab by TTY.
-    // We avoid System Events `keystroke` + `key code 36` because it requires
-    // accessibility permissions and unreliably delivers the Return key.
-    //
-    // `do script` with `in` targets a specific tab without opening a new one.
-    // We send text and Enter as two separate calls so the newline arrives
-    // outside of bracketed paste mode — same pattern as iTerm2 and tmux.
-    const textScript = `
-tell application "Terminal"
-  set targetTab to missing value
-  repeat with w in windows
-    repeat with i from 1 to count of tabs of w
-      set t to tab i of w
-      if tty of t is "${tty}" then
-        set targetTab to t
-        exit repeat
-      end if
-    end repeat
-    if targetTab is not missing value then exit repeat
-  end repeat
-  if targetTab is missing value then return "not_found"
-  do script "${escaped}" in targetTab
-end tell
-return "ok"`;
-
-    const { stdout: textResult } = await execFileAsync("osascript", ["-e", textScript]);
-    if (textResult.trim() !== "ok") {
-      throw new Error(`Terminal.app tab not found for TTY ${tty}`);
-    }
-
-    // Wait for the text to be delivered before sending Enter
-    await new Promise((resolve) => setTimeout(resolve, 150));
-
-    const enterScript = `
-tell application "Terminal"
-  set targetTab to missing value
-  repeat with w in windows
-    repeat with i from 1 to count of tabs of w
-      set t to tab i of w
-      if tty of t is "${tty}" then
-        set targetTab to t
-        exit repeat
-      end if
-    end repeat
-    if targetTab is not missing value then exit repeat
-  end repeat
-  if targetTab is missing value then return "not_found"
-  do script "" in targetTab
-end tell
-return "ok"`;
-
-    const { stdout: enterResult } = await execFileAsync("osascript", ["-e", enterScript]);
-    if (enterResult.trim() !== "ok") {
-      throw new Error(`Terminal.app tab disappeared before Enter could be sent for TTY ${tty}`);
-    }
-  }
-}
-
-/**
- * AppleScript `keystroke` only delivers typeable characters; non-typeable
- * keys (Esc, arrows, F-keys, …) must be sent via `key code <N>`. Add more
- * mappings here as new special keys are needed.
- */
-function appleScriptKeyAction(key: string): string {
-  if (key === ESCAPE_BYTE) return "key code 53";
-  return `keystroke "${escapeAppleScript(key)}"`;
 }

package/src/terminal/backends/ghostty.ts

@@ -0,0 +1,180 @@
+import { execFile } from "child_process";
+import { writeFile } from "fs/promises";
+import { promisify } from "util";
+import { escapeAppleScript } from "../../utils/applescript.js";
+import { getProcessCwdsAsync } from "../../utils/process.js";
+import { TerminalType, type TerminalBackend, type TerminalLocation } from "../types.js";
+import { CARRIAGE_RETURN, isProcessName, sleep } from "./shared.js";
+
+const execFileAsync = promisify(execFile);
+
+/** Separates fields in AppleScript output; never part of an id, title or path. */
+const FIELD_SEPARATOR = "\x1f";
+const MARKER_POLL_ATTEMPTS = 10;
+const MARKER_POLL_INTERVAL_MS = 50;
+
+interface GhosttyTerminal {
+  id: string;
+  name: string;
+  workingDirectory: string;
+}
+
+interface ProcessRow {
+  pid: number;
+  ppid: number;
+  tty: string;
+  comm: string;
+}
+
+async function listProcesses(): Promise<ProcessRow[]> {
+  const { stdout } = await execFileAsync("ps", ["-Axo", "pid=,ppid=,tty=,comm="]);
+  const rows: ProcessRow[] = [];
+  for (const line of stdout.split("\n")) {
+    const match = line.trim().match(/^(\d+)\s+(\d+)\s+(\S+)\s+(.+)$/);
+    if (match) {
+      rows.push({ pid: Number(match[1]), ppid: Number(match[2]), tty: match[3], comm: match[4] });
+    }
+  }
+  return rows;
+}
+
+async function listTerminals(): Promise<GhosttyTerminal[]> {
+  const script = `
+tell application "Ghostty"
+  set out to ""
+  repeat with t in terminals
+    set out to out & (id of t) & (character id 31) & (name of t) & (character id 31) & (working directory of t) & linefeed
+  end repeat
+  return out
+end tell`;
+  const { stdout } = await execFileAsync("osascript", ["-e", script]);
+  return stdout
+    .split("\n")
+    .map((line) => line.split(FIELD_SEPARATOR))
+    .filter((fields) => fields.length === 3 && fields[0])
+    .map(([id, name, workingDirectory]) => ({ id, name, workingDirectory }));
+}
+
+/** Run an AppleScript `command` with `t` bound to the located terminal; false if it is gone. */
+async function onTerminal(location: TerminalLocation, command: string): Promise<boolean> {
+  const script = `
+tell application "Ghostty"
+  set matches to (every terminal whose id is "${escapeAppleScript(location.identifier)}")
+  if (count of matches) is 0 then return "not_found"
+  set t to item 1 of matches
+  ${command}
+end tell
+return "ok"`;
+  const { stdout } = await execFileAsync("osascript", ["-e", script]);
+  return stdout.trim() === "ok";
+}
+
+/** Set the window title of whatever terminal owns `tty` (OSC 2). */
+async function writeTitle(tty: string, title: string): Promise<void> {
+  // eslint-disable-next-line no-control-regex
+  const safe = title.replace(/[\x00-\x1f\x7f]/g, "");
+  await writeFile(tty, `\x1b]2;${safe}\x07`, { flag: "a" });
+}
+
+/**
+ * Ghostty's AppleScript terminals expose an id, title and working directory,
+ * but not their TTY. Find the one owning `tty` without guessing:
+ * 1. only TTYs whose session was started by a ghostty process qualify;
+ * 2. if exactly one terminal's working directory matches a process on this
+ *    TTY, and no other Ghostty TTY has a process there, that is it;
+ * 3. otherwise briefly set a unique title on the TTY, find the terminal now
+ *    showing it, and restore its previous title.
+ */
+async function findTerminalId(tty: string): Promise<string | null> {
+  const processes = await listProcesses();
+  const ghosttyPids = new Set(
+    processes.filter((p) => isProcessName(p.comm, "ghostty")).map((p) => p.pid),
+  );
+  if (ghosttyPids.size === 0) return null;
+
+  const ttyName = tty.replace(/^\/dev\//, "");
+  const ghosttyTtys = new Set(
+    processes.filter((p) => ghosttyPids.has(p.ppid) && p.tty !== "??").map((p) => p.tty),
+  );
+  if (!ghosttyTtys.has(ttyName)) return null;
+
+  const terminals = await listTerminals();
+  const sessionProcesses = processes.filter((p) => ghosttyTtys.has(p.tty));
+  const cwdByPid = await getProcessCwdsAsync(sessionProcesses.map((p) => p.pid));
+  const ownDirs = new Set<string>();
+  const otherDirs = new Set<string>();
+  for (const p of sessionProcesses) {
+    const cwd = cwdByPid.get(p.pid);
+    if (cwd) (p.tty === ttyName ? ownDirs : otherDirs).add(cwd);
+  }
+
+  // Trust the directory only when exactly one terminal is in a folder no other Ghostty TTY uses.
+  const byDirectory = terminals.filter((t) => ownDirs.has(t.workingDirectory));
+  if (byDirectory.length === 1 && !otherDirs.has(byDirectory[0].workingDirectory)) {
+    return byDirectory[0].id;
+  }
+
+  const marker = `ai-devkit-${process.pid}-${Date.now()}`;
+  await writeTitle(tty, marker);
+  for (let attempt = 0; attempt < MARKER_POLL_ATTEMPTS; attempt++) {
+    const marked = (await listTerminals()).find((t) => t.name === marker);
+    if (marked) {
+      const previous = terminals.find((t) => t.id === marked.id)?.name ?? "";
+      await writeTitle(tty, previous);
+      return marked.id;
+    }
+    await sleep(MARKER_POLL_INTERVAL_MS);
+  }
+  return null;
+}
+
+/**
+ * A Ghostty `text:` action that writes `bytes` to the terminal as typed.
+ * Unlike `send key`, it does not go through the keyboard layout or input
+ * method, which can turn a digit key into another character.
+ */
+function textAction(bytes: string): string {
+  const escaped = Array.from(bytes, (char) => {
+    if (char === "\\") return "\\\\";
+    const code = char.charCodeAt(0);
+    return code >= 0x20 && code < 0x7f ? char : `\\x${code.toString(16).padStart(2, "0")}`;
+  }).join("");
+  return `perform action "${escapeAppleScript(`text:${escaped}`)}" on t`;
+}
+
+export const ghosttyBackend: TerminalBackend = {
+  type: TerminalType.GHOSTTY,
+  label: "Ghostty",
+
+  async find(tty) {
+    try {
+      const id = await findTerminalId(tty);
+      return id ? { type: TerminalType.GHOSTTY, identifier: id, tty } : null;
+    } catch {
+      // Ghostty not installed, not scriptable, or the TTY is not writable
+      return null;
+    }
+  },
+
+  async focus(location) {
+    return onTerminal(location, "focus t\n  activate");
+  },
+
+  async send(location, message) {
+    if (!(await onTerminal(location, `input text "${escapeAppleScript(message)}" to t`))) {
+      throw new Error(`Ghostty terminal not found for TTY ${location.tty}`);
+    }
+    await sleep(150);
+    if (!(await onTerminal(location, textAction(CARRIAGE_RETURN)))) {
+      throw new Error(
+        `Ghostty terminal disappeared before Enter could be sent for TTY ${location.tty}`,
+      );
+    }
+  },
+
+  async sendKey(location, key) {
+    if (!(await onTerminal(location, textAction(key)))) {
+      throw new Error(`Ghostty terminal not found for TTY ${location.tty}`);
+    }
+  },
+};

package/src/terminal/backends/index.ts

@@ -0,0 +1,23 @@
+import type { TerminalBackend } from "../types.js";
+import { TerminalType } from "../types.js";
+import { ghosttyBackend } from "./ghostty.js";
+import { iterm2Backend } from "./iterm2.js";
+import { terminalAppBackend } from "./terminal-app.js";
+import { tmuxBackend } from "./tmux.js";
+import { weztermBackend } from "./wezterm.js";
+
+export const TERMINAL_BACKENDS: readonly TerminalBackend[] = [
+  tmuxBackend,
+  weztermBackend,
+  ghosttyBackend,
+  iterm2Backend,
+  terminalAppBackend,
+];
+
+const BACKENDS_BY_TYPE = new Map<TerminalType, TerminalBackend>(
+  TERMINAL_BACKENDS.map((backend) => [backend.type, backend]),
+);
+
+export function terminalBackendFor(type: TerminalType): TerminalBackend | undefined {
+  return BACKENDS_BY_TYPE.get(type);
+}

package/src/terminal/backends/iterm2.ts

@@ -0,0 +1,126 @@
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { escapeAppleScript } from "../../utils/applescript.js";
+import { TerminalType, type TerminalBackend } from "../types.js";
+import { appleScriptKeyAction, isProcessRunning, sleep } from "./shared.js";
+
+const execFileAsync = promisify(execFile);
+
+function sessionScript(tty: string, sessionCommand: string): string {
+  return `
+tell application "iTerm"
+  set targetSession to missing value
+  repeat with w in windows
+    repeat with t in tabs of w
+      repeat with s in sessions of t
+        if tty of s is "${escapeAppleScript(tty)}" then
+          set targetSession to s
+          exit repeat
+        end if
+      end repeat
+      if targetSession is not missing value then exit repeat
+    end repeat
+    if targetSession is not missing value then exit repeat
+  end repeat
+  if targetSession is missing value then return "not_found"
+  tell targetSession to ${sessionCommand}
+end tell
+return "ok"`;
+}
+
+export const iterm2Backend: TerminalBackend = {
+  type: TerminalType.ITERM2,
+  label: "iTerm2",
+
+  async find(tty) {
+    try {
+      if (!(await isProcessRunning("iTerm2"))) return null;
+      const script = `
+        tell application "iTerm"
+          repeat with w in windows
+            repeat with t in tabs of w
+              repeat with s in sessions of t
+                if tty of s is "${escapeAppleScript(tty)}" then
+                  return "found"
+                end if
+              end repeat
+            end repeat
+          end repeat
+        end tell
+      `;
+      const { stdout } = await execFileAsync("osascript", ["-e", script]);
+      return stdout.trim() === "found" ? { type: TerminalType.ITERM2, identifier: tty, tty } : null;
+    } catch {
+      return null;
+    }
+  },
+
+  async focus(location) {
+    const script = `
+       tell application "iTerm"
+         activate
+         repeat with w in windows
+           repeat with t in tabs of w
+             repeat with s in sessions of t
+               if tty of s is "${escapeAppleScript(location.tty)}" then
+                 select s
+                 return "true"
+               end if
+             end repeat
+           end repeat
+         end repeat
+       end tell
+     `;
+    const { stdout } = await execFileAsync("osascript", ["-e", script]);
+    return stdout.trim() === "true";
+  },
+
+  async send(location, message) {
+    const textScript = sessionScript(
+      location.tty,
+      `write text "${escapeAppleScript(message)}" newline no`,
+    );
+    const { stdout: textResult } = await execFileAsync("osascript", ["-e", textScript]);
+    if (textResult.trim() !== "ok") {
+      throw new Error(`iTerm2 session not found for TTY ${location.tty}`);
+    }
+    await sleep(150);
+    const enterScript = sessionScript(location.tty, 'write text "" newline yes');
+    const { stdout: enterResult } = await execFileAsync("osascript", ["-e", enterScript]);
+    if (enterResult.trim() !== "ok") {
+      throw new Error(
+        `iTerm2 session disappeared before Enter could be sent for TTY ${location.tty}`,
+      );
+    }
+  },
+
+  async sendKey(location, key) {
+    const script = `
+tell application "iTerm"
+  set targetSession to missing value
+  repeat with w in windows
+    repeat with t in tabs of w
+      repeat with s in sessions of t
+        if tty of s is "${escapeAppleScript(location.tty)}" then
+          set targetSession to s
+          set frontmost of w to true
+          tell t to select
+          tell s to select
+          exit repeat
+        end if
+      end repeat
+      if targetSession is not missing value then exit repeat
+    end repeat
+    if targetSession is not missing value then exit repeat
+  end repeat
+  if targetSession is missing value then return "not_found"
+  activate
+end tell
+tell application "System Events" to ${appleScriptKeyAction(key)}
+return "ok"`;
+    const { stdout } = await execFileAsync("osascript", ["-e", script]);
+    if (stdout.trim() !== "ok") {
+      throw new Error(`iTerm2 session not found for TTY ${location.tty}`);
+    }
+  },
+};