@ai-devkit/agent-manager 0.22.1 → 0.24.0

package/src/terminal/TerminalFocusManager.ts

@@ -7,6 +7,7 @@ const execFileAsync = promisify(execFile);
 
 export enum TerminalType {
     TMUX = 'tmux',
+    WEZTERM = 'wezterm',
     ITERM2 = 'iterm2',
     TERMINAL_APP = 'terminal-app',
     UNKNOWN = 'unknown',
@@ -14,11 +15,31 @@ export enum TerminalType {
 
 export interface TerminalLocation {
     type: TerminalType;
-    identifier: string; // e.g., "session:window.pane" for tmux, or TTY for others
+    identifier: string; // e.g., "session:window.pane" for tmux, WezTerm pane id, or TTY for others
     tty: string;        // e.g., "/dev/ttys030"
 }
 
+/**
+ * Subset of a `wezterm cli list --format json` entry. Only `pane_id` and
+ * `tty_name` are read; extra fields are ignored so schema additions across
+ * WezTerm versions don't break parsing. (The TTY is exposed as `tty_name` in
+ * the JSON, not `tty`.)
+ */
+interface WeztermPaneEntry {
+    pane_id?: number;
+    tty_name?: string | null;
+}
+
+/**
+ * Optional trace sink. When provided to {@link TerminalFocusManager}, each
+ * discovery/focus step reports a human-readable line so callers (e.g. the
+ * `agent open --debug` command) can inspect the matching/focus decision path.
+ */
+export type TerminalDebugLogger = (message: string) => void;
+
 export class TerminalFocusManager {
+    constructor(private readonly debug?: TerminalDebugLogger) {}
+
     /**
      * Find the terminal location (emulator info) for a given process ID
      */
@@ -27,24 +48,47 @@ export class TerminalFocusManager {
 
         // If no TTY or invalid, we can't find the terminal
         if (!ttyShort || ttyShort === '?') {
+            this.debug?.(`findTerminal(pid=${pid}): no usable TTY, cannot resolve terminal`);
             return null;
         }
 
         const fullTty = `/dev/${ttyShort}`;
+        this.debug?.(`findTerminal(pid=${pid}): resolving terminal for ${fullTty}`);
 
         // 1. Check tmux (most specific if running inside it)
         const tmuxLocation = await this.findTmuxPane(fullTty);
-        if (tmuxLocation) return tmuxLocation;
+        if (tmuxLocation) {
+            this.debug?.(`findTerminal: matched tmux (identifier=${tmuxLocation.identifier})`);
+            return tmuxLocation;
+        }
+        this.debug?.('findTerminal: tmux no match');
+
+        // 2. Check WezTerm (cross-platform, via its CLI — no AppleScript)
+        const weztermLocation = await this.findWeztermPane(fullTty);
+        if (weztermLocation) {
+            this.debug?.(`findTerminal: matched wezterm (pane_id=${weztermLocation.identifier})`);
+            return weztermLocation;
+        }
+        this.debug?.('findTerminal: wezterm no match');
 
-        // 2. Check iTerm2
+        // 3. Check iTerm2
         const itermLocation = await this.findITerm2Session(fullTty);
-        if (itermLocation) return itermLocation;
+        if (itermLocation) {
+            this.debug?.(`findTerminal: matched iTerm2 (tty=${itermLocation.tty})`);
+            return itermLocation;
+        }
+        this.debug?.('findTerminal: iTerm2 no match');
 
-        // 3. Check Terminal.app
+        // 4. Check Terminal.app
         const terminalAppLocation = await this.findTerminalAppWindow(fullTty);
-        if (terminalAppLocation) return terminalAppLocation;
+        if (terminalAppLocation) {
+            this.debug?.(`findTerminal: matched Terminal.app (tty=${terminalAppLocation.tty})`);
+            return terminalAppLocation;
+        }
+        this.debug?.('findTerminal: Terminal.app no match');
 
-        // 4. Fallback: we know the TTY but not the emulator wrapper
+        // 5. Fallback: we know the TTY but not the emulator wrapper
+        this.debug?.('findTerminal: no emulator matched; returning UNKNOWN');
         return {
             type: TerminalType.UNKNOWN,
             identifier: '',
@@ -56,17 +100,65 @@ export class TerminalFocusManager {
      * Focus the terminal identified by the location
      */
     async focusTerminal(location: TerminalLocation): Promise<boolean> {
+        this.debug?.(`focusTerminal: focusing ${location.type} (identifier=${location.identifier}, tty=${location.tty})`);
+        let success = false;
         try {
             switch (location.type) {
                 case TerminalType.TMUX:
-                    return await this.focusTmuxPane(location.identifier);
+                    success = await this.focusTmuxPane(location.identifier);
+                    break;
+                case TerminalType.WEZTERM:
+                    success = await this.focusWeztermPane(location.identifier);
+                    break;
                 case TerminalType.ITERM2:
-                    return await this.focusITerm2Session(location.tty);
+                    success = await this.focusITerm2Session(location.tty);
+                    break;
                 case TerminalType.TERMINAL_APP:
-                    return await this.focusTerminalAppWindow(location.tty);
+                    success = await this.focusTerminalAppWindow(location.tty);
+                    break;
                 default:
-                    return false;
+                    success = false;
+            }
+        } catch {
+            success = false;
+        }
+        this.debug?.(`focusTerminal: ${success ? 'succeeded' : 'failed'} for ${location.type}`);
+        return success;
+    }
+
+    private async findWeztermPane(tty: string): Promise<TerminalLocation | null> {
+        try {
+            const { stdout } = await execFileAsync('wezterm', [
+                'cli', 'list', '--format', 'json',
+            ]);
+
+            const panes = JSON.parse(stdout) as WeztermPaneEntry[];
+            if (!Array.isArray(panes)) return null;
+
+            for (const pane of panes) {
+                if (
+                    pane &&
+                    typeof pane.tty_name === 'string' &&
+                    pane.tty_name === tty &&
+                    pane.pane_id != null
+                ) {
+                    return {
+                        type: TerminalType.WEZTERM,
+                        identifier: String(pane.pane_id),
+                        tty,
+                    };
+                }
             }
+        } catch {
+            // wezterm not installed, not running, or returned invalid JSON
+        }
+        return null;
+    }
+
+    private async focusWeztermPane(paneId: string): Promise<boolean> {
+        try {
+            await execFileAsync('wezterm', ['cli', 'activate-pane', '--pane-id', paneId]);
+            return true;
         } catch {
             return false;
         }

package/src/terminal/TtyWriter.ts

@@ -6,6 +6,19 @@ import { escapeAppleScript } from '../utils/applescript.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';
+
 export class TtyWriter {
     /**
      * Send a message as keyboard input to a terminal session.
@@ -26,6 +39,8 @@ export class TtyWriter {
         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:
@@ -33,11 +48,146 @@ export class TtyWriter {
             default:
                 throw new Error(
                     `Cannot send input: unsupported terminal type "${location.type}". ` +
-                    'Supported: tmux, iTerm2, Terminal.app.'
+                    'Supported: tmux, WezTerm, iTerm2, Terminal.app.'
                 );
         }
     }
 
+    /**
+     * 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}`);
+        }
+    }
+
+    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
@@ -175,3 +325,13 @@ return "ok"`;
         }
     }
 }
+
+/**
+ * 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/utils/agent-requests.ts

@@ -0,0 +1,28 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface AgentRequest {
+    sessionId: string;
+    toolName: string;
+    toolInput: Record<string, unknown>;
+    timestamp: string;
+}
+
+export function getAgentRequestPath(homeDir: string, sessionId: string): string {
+    return path.join(homeDir, '.ai-devkit', 'agent-requests', `${sessionId}.json`);
+}
+
+export function readLatestAgentRequest(homeDir: string, sessionId: string): AgentRequest | null {
+    try {
+        const raw = fs.readFileSync(getAgentRequestPath(homeDir, sessionId), 'utf-8');
+        return JSON.parse(raw) as AgentRequest;
+    } catch {
+        return null;
+    }
+}
+
+export function writeAgentRequest(homeDir: string, entry: AgentRequest): void {
+    const filePath = getAgentRequestPath(homeDir, entry.sessionId);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(entry, null, 2), 'utf-8');
+}