@ai-devkit/agent-manager 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export { AgentStatus } from './adapters/AgentAdapter';
 export type { AgentAdapter, AgentType, AgentInfo, ProcessInfo } from './adapters/AgentAdapter';
 export { TerminalFocusManager, TerminalType } from './terminal/TerminalFocusManager';
 export type { TerminalLocation } from './terminal/TerminalFocusManager';
+export { TtyWriter } from './terminal/TtyWriter';
 export { listProcesses, getProcessCwd, getProcessTty, isProcessRunning, getProcessInfo } from './utils/process';
 export type { ListProcessesOptions } from './utils/process';
 export { readLastLines, readJsonLines, fileExists, readJson } from './utils/file';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE/F,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AACrF,YAAY,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAExE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,aAAa,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAChH,YAAY,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE/F,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AACrF,YAAY,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEjD,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,aAAa,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAChH,YAAY,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.readJson = exports.fileExists = exports.readJsonLines = exports.readLastLines = exports.getProcessInfo = exports.isProcessRunning = exports.getProcessTty = exports.getProcessCwd = exports.listProcesses = exports.TerminalType = exports.TerminalFocusManager = exports.AgentStatus = exports.CodexAdapter = exports.ClaudeCodeAdapter = exports.AgentManager = void 0;
+exports.readJson = exports.fileExists = exports.readJsonLines = exports.readLastLines = exports.getProcessInfo = exports.isProcessRunning = exports.getProcessTty = exports.getProcessCwd = exports.listProcesses = exports.TtyWriter = exports.TerminalType = exports.TerminalFocusManager = exports.AgentStatus = exports.CodexAdapter = exports.ClaudeCodeAdapter = exports.AgentManager = void 0;
 var AgentManager_1 = require("./AgentManager");
 Object.defineProperty(exports, "AgentManager", { enumerable: true, get: function () { return AgentManager_1.AgentManager; } });
 var ClaudeCodeAdapter_1 = require("./adapters/ClaudeCodeAdapter");
@@ -12,6 +12,8 @@ Object.defineProperty(exports, "AgentStatus", { enumerable: true, get: function
 var TerminalFocusManager_1 = require("./terminal/TerminalFocusManager");
 Object.defineProperty(exports, "TerminalFocusManager", { enumerable: true, get: function () { return TerminalFocusManager_1.TerminalFocusManager; } });
 Object.defineProperty(exports, "TerminalType", { enumerable: true, get: function () { return TerminalFocusManager_1.TerminalType; } });
+var TtyWriter_1 = require("./terminal/TtyWriter");
+Object.defineProperty(exports, "TtyWriter", { enumerable: true, get: function () { return TtyWriter_1.TtyWriter; } });
 var process_1 = require("./utils/process");
 Object.defineProperty(exports, "listProcesses", { enumerable: true, get: function () { return process_1.listProcesses; } });
 Object.defineProperty(exports, "getProcessCwd", { enumerable: true, get: function () { return process_1.getProcessCwd; } });

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,+CAA8C;AAArC,4GAAA,YAAY,OAAA;AAErB,kEAAiE;AAAxD,sHAAA,iBAAiB,OAAA;AAC1B,wDAAuD;AAA9C,4GAAA,YAAY,OAAA;AACrB,wDAAsD;AAA7C,2GAAA,WAAW,OAAA;AAGpB,wEAAqF;AAA5E,4HAAA,oBAAoB,OAAA;AAAE,oHAAA,YAAY,OAAA;AAG3C,2CAAgH;AAAvG,wGAAA,aAAa,OAAA;AAAE,wGAAA,aAAa,OAAA;AAAE,wGAAA,aAAa,OAAA;AAAE,2GAAA,gBAAgB,OAAA;AAAE,yGAAA,cAAc,OAAA;AAEtF,qCAAkF;AAAzE,qGAAA,aAAa,OAAA;AAAE,qGAAA,aAAa,OAAA;AAAE,kGAAA,UAAU,OAAA;AAAE,gGAAA,QAAQ,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,+CAA8C;AAArC,4GAAA,YAAY,OAAA;AAErB,kEAAiE;AAAxD,sHAAA,iBAAiB,OAAA;AAC1B,wDAAuD;AAA9C,4GAAA,YAAY,OAAA;AACrB,wDAAsD;AAA7C,2GAAA,WAAW,OAAA;AAGpB,wEAAqF;AAA5E,4HAAA,oBAAoB,OAAA;AAAE,oHAAA,YAAY,OAAA;AAE3C,kDAAiD;AAAxC,sGAAA,SAAS,OAAA;AAElB,2CAAgH;AAAvG,wGAAA,aAAa,OAAA;AAAE,wGAAA,aAAa,OAAA;AAAE,wGAAA,aAAa,OAAA;AAAE,2GAAA,gBAAgB,OAAA;AAAE,yGAAA,cAAc,OAAA;AAEtF,qCAAkF;AAAzE,qGAAA,aAAa,OAAA;AAAE,qGAAA,aAAa,OAAA;AAAE,kGAAA,UAAU,OAAA;AAAE,gGAAA,QAAQ,OAAA"}

package/dist/terminal/TtyWriter.d.ts

@@ -0,0 +1,23 @@
+import type { TerminalLocation } from './TerminalFocusManager';
+export declare 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: AppleScript `write text`
+     * - Terminal.app: System Events `keystroke` + `key code 36` (Return)
+     *
+     * 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 send(location: TerminalLocation, message: string): Promise<void>;
+    private static sendViaTmux;
+    private static sendViaITerm2;
+    private static sendViaTerminalApp;
+}
+//# sourceMappingURL=TtyWriter.d.ts.map

package/dist/terminal/TtyWriter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TtyWriter.d.ts","sourceRoot":"","sources":["../../src/terminal/TtyWriter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAa/D,qBAAa,SAAS;IAClB;;;;;;;;;;;;;;OAcG;WACU,IAAI,CAAC,QAAQ,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;mBAgBxD,WAAW;mBAIX,aAAa;mBAuBb,kBAAkB;CAqC1C"}

package/dist/terminal/TtyWriter.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TtyWriter = void 0;
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const TerminalFocusManager_1 = require("./TerminalFocusManager");
+const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
+/**
+ * Escape a string for safe use inside an AppleScript double-quoted string.
+ * Backslashes and double quotes must be escaped.
+ */
+function escapeAppleScript(text) {
+    return text.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+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: AppleScript `write text`
+     * - Terminal.app: System Events `keystroke` + `key code 36` (Return)
+     *
+     * 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, message) {
+        switch (location.type) {
+            case TerminalFocusManager_1.TerminalType.TMUX:
+                return TtyWriter.sendViaTmux(location.identifier, message);
+            case TerminalFocusManager_1.TerminalType.ITERM2:
+                return TtyWriter.sendViaITerm2(location.tty, message);
+            case TerminalFocusManager_1.TerminalType.TERMINAL_APP:
+                return TtyWriter.sendViaTerminalApp(location.tty, message);
+            default:
+                throw new Error(`Cannot send input: unsupported terminal type "${location.type}". ` +
+                    'Supported: tmux, iTerm2, Terminal.app.');
+        }
+    }
+    static async sendViaTmux(identifier, message) {
+        await execFileAsync('tmux', ['send-keys', '-t', identifier, message, 'Enter']);
+    }
+    static async sendViaITerm2(tty, message) {
+        const escaped = escapeAppleScript(message);
+        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 "${tty}" then
+          tell s to write text "${escaped}"
+          return "ok"
+        end if
+      end repeat
+    end repeat
+  end repeat
+end tell
+return "not_found"`;
+        const { stdout } = await execFileAsync('osascript', ['-e', script]);
+        if (stdout.trim() !== 'ok') {
+            throw new Error(`iTerm2 session not found for TTY ${tty}`);
+        }
+    }
+    static async sendViaTerminalApp(tty, message) {
+        const escaped = escapeAppleScript(message);
+        // Use System Events keystroke to type into the foreground process,
+        // NOT Terminal.app's "do script" which runs a new shell command.
+        // First activate Terminal and select the correct tab, then type via System Events.
+        const script = `
+tell application "Terminal"
+  set targetFound to false
+  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 selected tab of w to t
+        set index of w to 1
+        activate
+        set targetFound to true
+        exit repeat
+      end if
+    end repeat
+    if targetFound then exit repeat
+  end repeat
+  if not targetFound then return "not_found"
+end tell
+delay 0.1
+tell application "System Events"
+  tell process "Terminal"
+    keystroke "${escaped}"
+    key code 36
+  end tell
+end tell
+return "ok"`;
+        const { stdout } = await execFileAsync('osascript', ['-e', script]);
+        if (stdout.trim() !== 'ok') {
+            throw new Error(`Terminal.app tab not found for TTY ${tty}`);
+        }
+    }
+}
+exports.TtyWriter = TtyWriter;
+//# sourceMappingURL=TtyWriter.js.map

package/dist/terminal/TtyWriter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TtyWriter.js","sourceRoot":"","sources":["../../src/terminal/TtyWriter.ts"],"names":[],"mappings":";;;AAAA,iDAAyC;AACzC,+BAAiC;AAEjC,iEAAsD;AAEtD,MAAM,aAAa,GAAG,IAAA,gBAAS,EAAC,wBAAQ,CAAC,CAAC;AAE1C;;;GAGG;AACH,SAAS,iBAAiB,CAAC,IAAY;IACnC,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AAC5D,CAAC;AAED,MAAa,SAAS;IAClB;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,QAA0B,EAAE,OAAe;QACzD,QAAQ,QAAQ,CAAC,IAAI,EAAE,CAAC;YACpB,KAAK,mCAAY,CAAC,IAAI;gBAClB,OAAO,SAAS,CAAC,WAAW,CAAC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;YAC/D,KAAK,mCAAY,CAAC,MAAM;gBACpB,OAAO,SAAS,CAAC,aAAa,CAAC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;YAC1D,KAAK,mCAAY,CAAC,YAAY;gBAC1B,OAAO,SAAS,CAAC,kBAAkB,CAAC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;YAC/D;gBACI,MAAM,IAAI,KAAK,CACX,iDAAiD,QAAQ,CAAC,IAAI,KAAK;oBACnE,wCAAwC,CAC3C,CAAC;QACV,CAAC;IACL,CAAC;IAEO,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,UAAkB,EAAE,OAAe;QAChE,MAAM,aAAa,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;IACnF,CAAC;IAEO,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,GAAW,EAAE,OAAe;QAC3D,MAAM,OAAO,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC;QAC3C,MAAM,MAAM,GAAG;;;;;0BAKG,GAAG;kCACK,OAAO;;;;;;;mBAOtB,CAAC;QAEZ,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;QACpE,IAAI,MAAM,CAAC,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,oCAAoC,GAAG,EAAE,CAAC,CAAC;QAC/D,CAAC;IACL,CAAC;IAEO,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAAC,GAAW,EAAE,OAAe;QAChE,MAAM,OAAO,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC;QAC3C,mEAAmE;QACnE,iEAAiE;QACjE,mFAAmF;QACnF,MAAM,MAAM,GAAG;;;;;;wBAMC,GAAG;;;;;;;;;;;;;;;iBAeV,OAAO;;;;YAIZ,CAAC;QAEL,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;QACpE,IAAI,MAAM,CAAC,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,sCAAsC,GAAG,EAAE,CAAC,CAAC;QACjE,CAAC;IACL,CAAC;CACJ;AAhGD,8BAgGC"}

package/dist/terminal/index.d.ts

@@ -1,4 +1,5 @@
 export { TerminalFocusManager } from './TerminalFocusManager';
 export { TerminalType } from './TerminalFocusManager';
 export type { TerminalLocation } from './TerminalFocusManager';
+export { TtyWriter } from './TtyWriter';
 //# sourceMappingURL=index.d.ts.map

package/dist/terminal/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/terminal/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/terminal/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/dist/terminal/index.js

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TerminalType = exports.TerminalFocusManager = void 0;
+exports.TtyWriter = exports.TerminalType = exports.TerminalFocusManager = void 0;
 var TerminalFocusManager_1 = require("./TerminalFocusManager");
 Object.defineProperty(exports, "TerminalFocusManager", { enumerable: true, get: function () { return TerminalFocusManager_1.TerminalFocusManager; } });
 var TerminalFocusManager_2 = require("./TerminalFocusManager");
 Object.defineProperty(exports, "TerminalType", { enumerable: true, get: function () { return TerminalFocusManager_2.TerminalType; } });
+var TtyWriter_1 = require("./TtyWriter");
+Object.defineProperty(exports, "TtyWriter", { enumerable: true, get: function () { return TtyWriter_1.TtyWriter; } });
 //# sourceMappingURL=index.js.map

package/dist/terminal/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/terminal/index.ts"],"names":[],"mappings":";;;AAAA,+DAA8D;AAArD,4HAAA,oBAAoB,OAAA;AAC7B,+DAAsD;AAA7C,oHAAA,YAAY,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/terminal/index.ts"],"names":[],"mappings":";;;AAAA,+DAA8D;AAArD,4HAAA,oBAAoB,OAAA;AAC7B,+DAAsD;AAA7C,oHAAA,YAAY,OAAA;AAErB,yCAAwC;AAA/B,sGAAA,SAAS,OAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-devkit/agent-manager",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Standalone agent detection and management utilities for AI DevKit",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/__tests__/terminal/TtyWriter.test.ts

@@ -0,0 +1,154 @@
+import { describe, it, expect, jest, beforeEach } from '@jest/globals';
+import { TtyWriter } from '../../terminal/TtyWriter';
+import { TerminalType } from '../../terminal/TerminalFocusManager';
+import type { TerminalLocation } from '../../terminal/TerminalFocusManager';
+import { execFile } from 'child_process';
+
+jest.mock('child_process', () => {
+    const actual = jest.requireActual<typeof import('child_process')>('child_process');
+    return {
+        ...actual,
+        execFile: jest.fn(),
+    };
+});
+
+const mockedExecFile = execFile as unknown as jest.Mock;
+
+function mockExecFileSuccess(stdout = '') {
+    mockedExecFile.mockImplementation((...args: unknown[]) => {
+        const cb = args[args.length - 1] as (err: Error | null, result: { stdout: string }, stderr: string) => void;
+        cb(null, { stdout }, '');
+    });
+}
+
+function mockExecFileError(message: string) {
+    mockedExecFile.mockImplementation((...args: unknown[]) => {
+        const cb = args[args.length - 1] as (err: Error | null, result: null, stderr: string) => void;
+        cb(new Error(message), null, '');
+    });
+}
+
+describe('TtyWriter', () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+
+    describe('tmux', () => {
+        const location: TerminalLocation = {
+            type: TerminalType.TMUX,
+            identifier: 'main:0.1',
+            tty: '/dev/ttys030',
+        };
+
+        it('sends message via tmux send-keys', async () => {
+            mockExecFileSuccess();
+
+            await TtyWriter.send(location, 'continue');
+
+            expect(mockedExecFile).toHaveBeenCalledWith(
+                'tmux',
+                ['send-keys', '-t', 'main:0.1', 'continue', 'Enter'],
+                expect.any(Function),
+            );
+        });
+
+        it('throws on tmux failure', async () => {
+            mockExecFileError('tmux not running');
+
+            await expect(TtyWriter.send(location, 'hello'))
+                .rejects.toThrow('tmux not running');
+        });
+    });
+
+    describe('iTerm2', () => {
+        const location: TerminalLocation = {
+            type: TerminalType.ITERM2,
+            identifier: '/dev/ttys030',
+            tty: '/dev/ttys030',
+        };
+
+        it('sends message via osascript with execFile (no shell)', async () => {
+            mockExecFileSuccess('ok');
+
+            await TtyWriter.send(location, 'hello');
+
+            expect(mockedExecFile).toHaveBeenCalledWith(
+                'osascript',
+                ['-e', expect.stringContaining('write text "hello"')],
+                expect.any(Function),
+            );
+        });
+
+        it('escapes special characters in message', async () => {
+            mockExecFileSuccess('ok');
+
+            await TtyWriter.send(location, 'say "hi" \\ there');
+
+            expect(mockedExecFile).toHaveBeenCalledWith(
+                'osascript',
+                ['-e', expect.stringContaining('write text "say \\"hi\\" \\\\ there"')],
+                expect.any(Function),
+            );
+        });
+
+        it('throws when session not found', async () => {
+            mockExecFileSuccess('not_found');
+
+            await expect(TtyWriter.send(location, 'test'))
+                .rejects.toThrow('iTerm2 session not found');
+        });
+    });
+
+    describe('Terminal.app', () => {
+        const location: TerminalLocation = {
+            type: TerminalType.TERMINAL_APP,
+            identifier: '/dev/ttys030',
+            tty: '/dev/ttys030',
+        };
+
+        it('sends message via System Events keystroke (not do script)', async () => {
+            mockExecFileSuccess('ok');
+
+            await TtyWriter.send(location, 'hello');
+
+            const scriptArg = (mockedExecFile.mock.calls[0] as unknown[])[1] as string[];
+            const script = scriptArg[1];
+            // Must use keystroke, NOT do script
+            expect(script).toContain('keystroke "hello"');
+            expect(script).toContain('key code 36');
+            expect(script).not.toContain('do script');
+        });
+
+        it('uses execFile to avoid shell injection', async () => {
+            mockExecFileSuccess('ok');
+
+            await TtyWriter.send(location, "don't stop");
+
+            expect(mockedExecFile).toHaveBeenCalledWith(
+                'osascript',
+                ['-e', expect.any(String)],
+                expect.any(Function),
+            );
+        });
+
+        it('throws when tab not found', async () => {
+            mockExecFileSuccess('not_found');
+
+            await expect(TtyWriter.send(location, 'test'))
+                .rejects.toThrow('Terminal.app tab not found');
+        });
+    });
+
+    describe('unsupported terminal', () => {
+        it('throws for unknown terminal type', async () => {
+            const location: TerminalLocation = {
+                type: TerminalType.UNKNOWN,
+                identifier: '',
+                tty: '/dev/ttys030',
+            };
+
+            await expect(TtyWriter.send(location, 'test'))
+                .rejects.toThrow('Cannot send input: unsupported terminal type');
+        });
+    });
+});

package/src/index.ts

@@ -7,6 +7,7 @@ export type { AgentAdapter, AgentType, AgentInfo, ProcessInfo } from './adapters
 
 export { TerminalFocusManager, TerminalType } from './terminal/TerminalFocusManager';
 export type { TerminalLocation } from './terminal/TerminalFocusManager';
+export { TtyWriter } from './terminal/TtyWriter';
 
 export { listProcesses, getProcessCwd, getProcessTty, isProcessRunning, getProcessInfo } from './utils/process';
 export type { ListProcessesOptions } from './utils/process';

package/src/terminal/TtyWriter.ts

@@ -0,0 +1,112 @@
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import type { TerminalLocation } from './TerminalFocusManager';
+import { TerminalType } from './TerminalFocusManager';
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Escape a string for safe use inside an AppleScript double-quoted string.
+ * Backslashes and double quotes must be escaped.
+ */
+function escapeAppleScript(text: string): string {
+    return text.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+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: AppleScript `write text`
+     * - Terminal.app: System Events `keystroke` + `key code 36` (Return)
+     *
+     * 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.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, iTerm2, Terminal.app.'
+                );
+        }
+    }
+
+    private static async sendViaTmux(identifier: string, message: string): Promise<void> {
+        await execFileAsync('tmux', ['send-keys', '-t', identifier, message, 'Enter']);
+    }
+
+    private static async sendViaITerm2(tty: string, message: string): Promise<void> {
+        const escaped = escapeAppleScript(message);
+        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 "${tty}" then
+          tell s to write text "${escaped}"
+          return "ok"
+        end if
+      end repeat
+    end repeat
+  end repeat
+end tell
+return "not_found"`;
+
+        const { stdout } = await execFileAsync('osascript', ['-e', script]);
+        if (stdout.trim() !== 'ok') {
+            throw new Error(`iTerm2 session not found for TTY ${tty}`);
+        }
+    }
+
+    private static async sendViaTerminalApp(tty: string, message: string): Promise<void> {
+        const escaped = escapeAppleScript(message);
+        // Use System Events keystroke to type into the foreground process,
+        // NOT Terminal.app's "do script" which runs a new shell command.
+        // First activate Terminal and select the correct tab, then type via System Events.
+        const script = `
+tell application "Terminal"
+  set targetFound to false
+  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 selected tab of w to t
+        set index of w to 1
+        activate
+        set targetFound to true
+        exit repeat
+      end if
+    end repeat
+    if targetFound then exit repeat
+  end repeat
+  if not targetFound then return "not_found"
+end tell
+delay 0.1
+tell application "System Events"
+  tell process "Terminal"
+    keystroke "${escaped}"
+    key code 36
+  end tell
+end tell
+return "ok"`;
+
+        const { stdout } = await execFileAsync('osascript', ['-e', script]);
+        if (stdout.trim() !== 'ok') {
+            throw new Error(`Terminal.app tab not found for TTY ${tty}`);
+        }
+    }
+}

package/src/terminal/index.ts

@@ -1,3 +1,4 @@
 export { TerminalFocusManager } from './TerminalFocusManager';
 export { TerminalType } from './TerminalFocusManager';
 export type { TerminalLocation } from './TerminalFocusManager';
+export { TtyWriter } from './TtyWriter';