@moxxy/plugin-computer-control 0.41.2 → 0.42.0

package/src/shell.ts

@@ -1,213 +0,0 @@
-import { spawn } from 'node:child_process';
-import { MoxxyError } from '@moxxy/sdk';
-
-export const IS_DARWIN = process.platform === 'darwin';
-
-/**
- * Hard ceiling on combined stdout+stderr a child may emit before it is
- * force-killed. The wall-clock timeout caps duration but not throughput —
- * a runaway or hostile child (e.g. `pbpaste` on a gigabyte clipboard, or an
- * `osascript` snippet that streams unbounded output) can accumulate hundreds
- * of MB well inside the timeout and OOM the host. 16 MB is far above any
- * legitimate tool output here (the screenshot path caps its own encoded file
- * separately) while still bounding worst-case memory.
- */
-export const MAX_OUTPUT_BYTES = 16 * 1024 * 1024;
-
-/** Grace period after SIGTERM before escalating to SIGKILL. */
-const SIGKILL_GRACE_MS = 2_500;
-
-export interface ProcResult {
-  readonly exitCode: number;
-  readonly stdout: string;
-  readonly stderr: string;
-  /**
-   * True when the child was force-killed because it exceeded `timeoutMs`.
-   * A timed-out child still resolves (via 'close') with `exitCode: -1`, so
-   * this flag is the only reliable way for callers to distinguish a timeout
-   * from a genuine non-zero exit and surface an actionable message.
-   */
-  readonly timedOut: boolean;
-  /** True when the child was force-killed because `opts.signal` aborted. */
-  readonly aborted: boolean;
-  /**
-   * True when the child was force-killed because its combined stdout+stderr
-   * exceeded `MAX_OUTPUT_BYTES`. The captured output is whatever had been
-   * read up to the cap.
-   */
-  readonly tooLarge: boolean;
-}
-
-/**
- * Build a uniform failure suffix that names a timeout/abort when the process
- * was force-killed, so a stuck `osascript` (etc.) is reported as a clear
- * cause rather than a bare `exit -1`. Returns '' for a normal exit.
- */
-export function procFailureCause(proc: ProcResult, timeoutMs?: number): string {
-  if (proc.tooLarge) return `output exceeded ${MAX_OUTPUT_BYTES} bytes (killed)`;
-  if (proc.timedOut) {
-    return timeoutMs ? `timed out after ${timeoutMs}ms` : 'timed out';
-  }
-  if (proc.aborted) return 'aborted (turn cancelled)';
-  return '';
-}
-
-/**
- * Spawn a process with array-form args (no shell). Returns stdout +
- * stderr + exit code. Optional `input` is written to stdin. Optional
- * `signal` propagates aborts from the tool ctx so a stuck `osascript`
- * dies with the turn instead of hanging the parent.
- *
- * Never use this with string interpolation into a single command —
- * each argument MUST be a separate array entry. The `bash -c` shape
- * would re-introduce the shell-injection risk this helper exists to
- * eliminate.
- */
-export function runProcess(
-  cmd: string,
-  args: ReadonlyArray<string>,
-  opts: {
-    readonly input?: string | Buffer;
-    readonly signal?: AbortSignal;
-    readonly timeoutMs?: number;
-  } = {},
-): Promise<ProcResult> {
-  return new Promise((resolve, reject) => {
-    // An ALREADY-aborted signal never emits 'abort' to a listener added after
-    // the fact (DOM semantics), so without this short-circuit a cancelled turn
-    // would still spawn the child and run it to completion — defeating the
-    // abort contract. Resolve immediately as an aborted no-op without spawning.
-    if (opts.signal?.aborted) {
-      resolve({
-        exitCode: -1,
-        stdout: '',
-        stderr: '',
-        timedOut: false,
-        aborted: true,
-        tooLarge: false,
-      });
-      return;
-    }
-    const child = spawn(cmd, [...args], { stdio: ['pipe', 'pipe', 'pipe'] });
-    // Collect BOTH stdout and stderr as chunks and concat ONCE at close.
-    // Re-concatenating the whole accumulated buffer on every 'data' event is
-    // O(n^2) and churns the GC; decoding each chunk with `.toString('utf8')`
-    // in isolation also corrupts any multibyte sequence (e.g. an osascript
-    // error containing a non-ASCII app name) that straddles a chunk boundary.
-    const stdoutChunks: Buffer[] = [];
-    const stderrChunks: Buffer[] = [];
-    let outputBytes = 0;
-    let settled = false;
-    let timedOut = false;
-    let aborted = false;
-    let tooLarge = false;
-    let killTimer: ReturnType<typeof setTimeout> | null = null;
-
-    // Force the child to die: SIGTERM first, then escalate to SIGKILL after a
-    // grace period for a child that traps/ignores SIGTERM (a wedged GUI helper
-    // or an osascript stuck behind an Accessibility prompt). Without the
-    // escalation the tool's timeout/abort isn't actually enforced — the parent
-    // hangs until the child closes on its own, which may be never.
-    const forceKill = (): void => {
-      try {
-        child.kill('SIGTERM');
-      } catch {
-        /* ignore */
-      }
-      if (killTimer) return;
-      killTimer = setTimeout(() => {
-        if (settled) return;
-        try {
-          child.kill('SIGKILL');
-        } catch {
-          /* ignore */
-        }
-      }, SIGKILL_GRACE_MS);
-      killTimer.unref?.();
-    };
-
-    const onAbort = (): void => {
-      if (settled) return;
-      aborted = true;
-      forceKill();
-    };
-    opts.signal?.addEventListener('abort', onAbort, { once: true });
-
-    const timer = opts.timeoutMs
-      ? setTimeout(() => {
-          if (settled) return;
-          timedOut = true;
-          forceKill();
-        }, opts.timeoutMs)
-      : null;
-
-    child.stdout.on('data', (chunk: Buffer) => {
-      outputBytes += chunk.length;
-      // Once over the cap we stop retaining further chunks (the child is being
-      // killed) so a flood between the cap-trip and SIGTERM landing can't keep
-      // growing memory; we still account the bytes to keep `outputBytes` honest.
-      if (!tooLarge) stdoutChunks.push(chunk);
-      if (!tooLarge && outputBytes > MAX_OUTPUT_BYTES) {
-        tooLarge = true;
-        forceKill();
-      }
-    });
-    child.stderr.on('data', (chunk: Buffer) => {
-      outputBytes += chunk.length;
-      if (!tooLarge) stderrChunks.push(chunk);
-      if (!tooLarge && outputBytes > MAX_OUTPUT_BYTES) {
-        tooLarge = true;
-        forceKill();
-      }
-    });
-    // A child that exits/closes stdin before our write completes makes the
-    // stdin Writable emit 'error' (EPIPE/ECONNRESET). With no listener that
-    // throws and surfaces as an unhandled rejection that can take down the
-    // parent — swallow it; the child 'error'/'close' path reports the real
-    // failure. Same defensiveness on stdout/stderr for symmetry.
-    child.stdin.on('error', () => {});
-    child.stdout.on('error', () => {});
-    child.stderr.on('error', () => {});
-    const cleanup = (): void => {
-      if (timer) clearTimeout(timer);
-      if (killTimer) clearTimeout(killTimer);
-      opts.signal?.removeEventListener('abort', onAbort);
-    };
-    child.once('error', (err) => {
-      if (settled) return;
-      settled = true;
-      cleanup();
-      reject(err);
-    });
-    child.once('close', (code) => {
-      if (settled) return;
-      settled = true;
-      cleanup();
-      resolve({
-        exitCode: code ?? -1,
-        stdout: Buffer.concat(stdoutChunks).toString('utf8'),
-        stderr: Buffer.concat(stderrChunks).toString('utf8'),
-        timedOut,
-        aborted,
-        tooLarge,
-      });
-    });
-
-    if (opts.input !== undefined) {
-      child.stdin.end(opts.input);
-    } else {
-      child.stdin.end();
-    }
-  });
-}
-
-/** Throw a clear error when a tool is invoked on a non-darwin host. */
-export function ensureDarwin(toolName: string): void {
-  if (!IS_DARWIN) {
-    throw new MoxxyError({
-      code: 'TOOL_ERROR',
-      message: `${toolName}: @moxxy/plugin-computer-control currently only supports macOS (process.platform = ${process.platform})`,
-      context: { tool: toolName, platform: process.platform },
-    });
-  }
-}

package/src/temporary-files.test.ts

@@ -1,18 +0,0 @@
-import { mkdtemp, writeFile, access, rm } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { expect, it } from 'vitest';
-import { withTemporaryFiles } from './temporary-files.js';
-
-it('cleans both screenshot files when conversion rejects after creating its output', async () => {
-  const dir = await mkdtemp(join(tmpdir(), 'moxxy-capture-test-'));
-  const files = [join(dir, 'capture.png'), join(dir, 'output.jpg')];
-  try {
-    const failure = new Error('converter aborted');
-    await expect(withTemporaryFiles(files, async () => {
-      for (const file of files) await writeFile(file, 'partial image');
-      throw failure;
-    })).rejects.toBe(failure);
-    for (const file of files) await expect(access(file)).rejects.toThrow();
-  } finally { await rm(dir, { recursive: true, force: true }); }
-});

package/src/temporary-files.ts

@@ -1,9 +0,0 @@
-import { rm } from 'node:fs/promises';
-
-export async function withTemporaryFiles<T>(paths: readonly string[], work: () => Promise<T>): Promise<T> {
-  try {
-    return await work();
-  } finally {
-    await Promise.all(paths.map((path) => rm(path, { force: true })));
-  }
-}

package/src/tools/applescript-serialize.test.ts

@@ -1,74 +0,0 @@
-import { MoxxyError } from '@moxxy/sdk';
-import { describe, expect, it } from 'vitest';
-import { buildKeyScript } from './key.js';
-import { toAppleScriptString } from './type.js';
-
-describe('toAppleScriptString', () => {
-  it('wraps a plain string in quotes', () => {
-    expect(toAppleScriptString('hello')).toBe('"hello"');
-  });
-
-  it('escapes embedded double-quotes and backslashes', () => {
-    // `a"b` -> a\"b ; backslashes are doubled.
-    expect(toAppleScriptString('a"b')).toBe('"a\\"b"');
-    expect(toAppleScriptString('a\\b')).toBe('"a\\\\b"');
-    // A backslash followed by a quote: both escaped, order preserved.
-    expect(toAppleScriptString('\\"')).toBe('"\\\\\\""');
-  });
-
-  it('splits newlines into separate literals joined by AppleScript return', () => {
-    expect(toAppleScriptString('a\nb')).toBe('"a" & return & "b"');
-    expect(toAppleScriptString('one\ntwo\nthree')).toBe(
-      '"one" & return & "two" & return & "three"',
-    );
-  });
-});
-
-describe('buildKeyScript', () => {
-  it('uses key code for named keys with no modifiers', () => {
-    expect(buildKeyScript('return', [])).toBe('tell application "System Events" to key code 36');
-    expect(buildKeyScript('escape', [])).toBe('tell application "System Events" to key code 53');
-  });
-
-  it('is case-insensitive for named keys', () => {
-    expect(buildKeyScript('Return', [])).toBe('tell application "System Events" to key code 36');
-  });
-
-  it('appends a using-clause mapping short modifier names to AppleScript', () => {
-    expect(buildKeyScript('return', ['cmd'])).toBe(
-      'tell application "System Events" to key code 36 using {command down}',
-    );
-    expect(buildKeyScript('c', ['cmd', 'shift'])).toBe(
-      'tell application "System Events" to keystroke "c" using {command down, shift down}',
-    );
-    expect(buildKeyScript('a', ['option', 'control'])).toBe(
-      'tell application "System Events" to keystroke "a" using {option down, control down}',
-    );
-  });
-
-  it('uses keystroke for single characters and escapes them', () => {
-    expect(buildKeyScript('/', [])).toBe('tell application "System Events" to keystroke "/"');
-    expect(buildKeyScript('"', [])).toBe('tell application "System Events" to keystroke "\\""');
-  });
-
-  it('routes a single literal whitespace char to its key code (chord-safe)', () => {
-    // ctrl+space must press the Space key, not type a space char with control
-    // held — so it goes through `key code 49`, not `keystroke " "`.
-    expect(buildKeyScript(' ', ['control'])).toBe(
-      'tell application "System Events" to key code 49 using {control down}',
-    );
-    expect(buildKeyScript('\t', [])).toBe('tell application "System Events" to key code 48');
-    expect(buildKeyScript('\r', [])).toBe('tell application "System Events" to key code 36');
-    expect(buildKeyScript('\n', [])).toBe('tell application "System Events" to key code 36');
-  });
-
-  it('throws a TOOL_ERROR for an unknown multi-char key', () => {
-    expect(() => buildKeyScript('notakey', [])).toThrow(MoxxyError);
-    try {
-      buildKeyScript('notakey', []);
-    } catch (err) {
-      expect((err as MoxxyError).code).toBe('TOOL_ERROR');
-      expect((err as MoxxyError).message).toContain('unknown key "notakey"');
-    }
-  });
-});

package/src/tools/applescript.ts

@@ -1,53 +0,0 @@
-import { defineTool, MoxxyError, z } from '@moxxy/sdk';
-import { ensureDarwin, procFailureCause, runProcess } from '../shell.js';
-
-export const applescriptTool = defineTool({
-  name: 'computer_applescript',
-  description:
-    'Escape hatch: run an arbitrary AppleScript snippet via `osascript`. Use ' +
-    'for anything the dedicated tools can\'t cover (frontmost app name, list ' +
-    'open Safari tabs, drive a specific app via its scripting dictionary, etc.). ' +
-    'Returns the script\'s stdout. The user approves every invocation — keep ' +
-    'scripts focused and reversible.',
-  inputSchema: z.object({
-    script: z
-      .string()
-      .min(1)
-      .max(8000)
-      .describe(
-        'AppleScript source. Multi-line is fine — pass `\\n` between statements. ' +
-          'For JavaScript for Automation, prefix with `#!/usr/bin/osascript -l JavaScript`',
-      ),
-  }),
-  permission: { action: 'prompt' },
-  // Arbitrary AppleScript is an escape hatch on par with a shell: the script
-  // can itself shell out (`do shell script`) and reach the network, so the
-  // honest bounds are subprocess + any net — a confining isolator must not
-  // assume osascript stays offline. Budget = the 30s child timeout + kill grace.
-  isolation: {
-    capabilities: {
-      subprocess: true,
-      commands: ['osascript'],
-      net: { mode: 'any' },
-      timeMs: 40_000,
-    },
-  },
-  async handler({ script }, ctx) {
-    ensureDarwin('computer_applescript');
-    const proc = await runProcess('osascript', ['-e', script], {
-      ...(ctx.signal ? { signal: ctx.signal } : {}),
-      timeoutMs: 30_000,
-    });
-    if (proc.exitCode !== 0) {
-      const cause = procFailureCause(proc, 30_000);
-      throw new MoxxyError({
-        code: 'TOOL_ERROR',
-        message: cause
-          ? `osascript ${cause}`
-          : `osascript failed (exit ${proc.exitCode}): ${proc.stderr.trim() || '(no error message)'}`,
-        context: { tool: 'computer_applescript', exitCode: proc.exitCode, timedOut: proc.timedOut ? 1 : 0 },
-      });
-    }
-    return { ok: true, output: proc.stdout.trim() };
-  },
-});

package/src/tools/click.ts

@@ -1,60 +0,0 @@
-import { defineTool, MoxxyError, z } from '@moxxy/sdk';
-import { ensureDarwin, procFailureCause, runProcess } from '../shell.js';
-
-export const clickTool = defineTool({
-  name: 'computer_click',
-  description:
-    'Click the mouse at screen-pixel coordinates (top-left origin). Uses macOS ' +
-    'System Events; requires Accessibility permission on first use. Pass count=2 ' +
-    'for a double-click. Right/middle buttons are not supported via this tool — ' +
-    'use computer_applescript for those (rare).',
-  inputSchema: z.object({
-    x: z.number().int().min(0).describe('X pixel from the top-left of the display.'),
-    y: z.number().int().min(0).describe('Y pixel from the top-left of the display.'),
-    count: z
-      .number()
-      .int()
-      .min(1)
-      .max(3)
-      .optional()
-      .describe('Number of consecutive clicks. 1 = single, 2 = double, 3 = triple. Default 1.'),
-  }),
-  permission: { action: 'prompt' },
-  isolation: {
-    capabilities: {
-      subprocess: true,
-      commands: ['osascript'],
-      net: { mode: 'none' },
-      timeMs: 15_000,
-    },
-  },
-  async handler({ x, y, count }, ctx) {
-    ensureDarwin('computer_click');
-    const n = count ?? 1;
-    // `click at {x, y}` repeats N times via a repeat block. Use a
-    // bare AppleScript string with numeric interpolation — no
-    // user-supplied text reaches the script, so injection isn't a
-    // risk here.
-    const script =
-      `tell application "System Events"\n` +
-      `  repeat ${n} times\n` +
-      `    click at {${Math.round(x)}, ${Math.round(y)}}\n` +
-      `  end repeat\n` +
-      `end tell`;
-    const proc = await runProcess('osascript', ['-e', script], {
-      ...(ctx.signal ? { signal: ctx.signal } : {}),
-      timeoutMs: 10_000,
-    });
-    if (proc.exitCode !== 0) {
-      const cause = procFailureCause(proc, 10_000);
-      throw new MoxxyError({
-        code: 'TOOL_ERROR',
-        message: cause
-          ? `click ${cause}`
-          : `click failed (exit ${proc.exitCode}): ${proc.stderr.trim() || '(check Accessibility permission in System Settings → Privacy & Security → Accessibility)'}`,
-        context: { tool: 'computer_click', exitCode: proc.exitCode, timedOut: proc.timedOut ? 1 : 0 },
-      });
-    }
-    return { ok: true, x, y, count: n };
-  },
-});

package/src/tools/clipboard.ts

@@ -1,72 +0,0 @@
-import { defineTool, MoxxyError, z } from '@moxxy/sdk';
-import { ensureDarwin, procFailureCause, runProcess } from '../shell.js';
-
-export const clipboardTool = defineTool({
-  name: 'computer_clipboard',
-  icon: 'clipboard',
-  description:
-    'Read from or write to the macOS clipboard. Use `read` to fetch what the ' +
-    'user just copied; use `write` to stage text the user can then paste with ' +
-    '⌘V. Writing the clipboard does NOT trigger a paste — call computer_key ' +
-    'with cmd+v after if you need to paste.',
-  inputSchema: z.object({
-    action: z.enum(['read', 'write']),
-    text: z
-      .string()
-      .max(64_000)
-      .optional()
-      .describe('Text to put on the clipboard. Required when action="write".'),
-  }),
-  permission: { action: 'prompt' },
-  isolation: {
-    capabilities: {
-      subprocess: true,
-      commands: ['pbpaste', 'pbcopy'],
-      net: { mode: 'none' },
-      timeMs: 10_000,
-    },
-  },
-  async handler({ action, text }, ctx) {
-    ensureDarwin('computer_clipboard');
-    if (action === 'read') {
-      const proc = await runProcess('pbpaste', [], {
-        ...(ctx.signal ? { signal: ctx.signal } : {}),
-        timeoutMs: 5_000,
-      });
-      if (proc.exitCode !== 0) {
-        const cause = procFailureCause(proc, 5_000);
-        throw new MoxxyError({
-          code: 'TOOL_ERROR',
-          message: cause
-            ? `pbpaste ${cause}`
-            : `pbpaste failed (exit ${proc.exitCode}): ${proc.stderr.trim()}`,
-          context: { tool: 'computer_clipboard', exitCode: proc.exitCode, timedOut: proc.timedOut ? 1 : 0 },
-        });
-      }
-      return { ok: true, text: proc.stdout };
-    }
-    if (text === undefined) {
-      throw new MoxxyError({
-        code: 'TOOL_ERROR',
-        message: 'computer_clipboard: `text` is required when action="write"',
-        context: { tool: 'computer_clipboard' },
-      });
-    }
-    const proc = await runProcess('pbcopy', [], {
-      ...(ctx.signal ? { signal: ctx.signal } : {}),
-      input: text,
-      timeoutMs: 5_000,
-    });
-    if (proc.exitCode !== 0) {
-      const cause = procFailureCause(proc, 5_000);
-      throw new MoxxyError({
-        code: 'TOOL_ERROR',
-        message: cause
-          ? `pbcopy ${cause}`
-          : `pbcopy failed (exit ${proc.exitCode}): ${proc.stderr.trim()}`,
-        context: { tool: 'computer_clipboard', exitCode: proc.exitCode, timedOut: proc.timedOut ? 1 : 0 },
-      });
-    }
-    return { ok: true, length: text.length };
-  },
-});

package/src/tools/key.ts

@@ -1,155 +0,0 @@
-import { defineTool, MoxxyError, z } from '@moxxy/sdk';
-import { ensureDarwin, procFailureCause, runProcess } from '../shell.js';
-
-const MODIFIER_NAMES = ['cmd', 'shift', 'option', 'control'] as const;
-type Modifier = (typeof MODIFIER_NAMES)[number];
-
-/**
- * Named keys → macOS key codes used by AppleScript's
- * `key code N` command. Subset focused on what an automation agent
- * actually needs (navigation, editing, function keys). Letters and
- * digits go through `keystroke "x" using ...` instead of `key code`.
- */
-const KEY_CODES: Record<string, number> = {
-  return: 36,
-  enter: 36,
-  tab: 48,
-  space: 49,
-  escape: 53,
-  esc: 53,
-  delete: 51,
-  backspace: 51,
-  forward_delete: 117,
-  left: 123,
-  right: 124,
-  down: 125,
-  up: 126,
-  home: 115,
-  end: 119,
-  page_up: 116,
-  page_down: 121,
-  f1: 122,
-  f2: 120,
-  f3: 99,
-  f4: 118,
-  f5: 96,
-  f6: 97,
-  f7: 98,
-  f8: 100,
-  f9: 101,
-  f10: 109,
-  f11: 103,
-  f12: 111,
-};
-
-/**
- * Single literal whitespace chars → their key codes. A bare ' '/'\t'/'\r'/'\n'
- * would otherwise be sent via `keystroke`, which types the character (wrong for
- * modifier chords like ctrl+space). Mirrors the matching KEY_CODES entries.
- */
-const WHITESPACE_KEY_CODES: Record<string, number> = {
-  ' ': 49, // space
-  '\t': 48, // tab
-  '\r': 36, // return
-  '\n': 36, // return
-};
-
-export const keyTool = defineTool({
-  name: 'computer_key',
-  description:
-    'Send a single key chord with optional modifiers. Use this for shortcuts ' +
-    '(cmd+c, cmd+tab, cmd+shift+4) and named keys (return, tab, escape, arrows, ' +
-    'page_up/down, f1–f12). For typing arbitrary text, use computer_type.',
-  inputSchema: z.object({
-    key: z
-      .string()
-      .min(1)
-      .describe(
-        'A single character ("a", "1", "/") OR a named key from the catalog: ' +
-          Object.keys(KEY_CODES).join(', ') +
-          '.',
-      ),
-    modifiers: z
-      .array(z.enum(MODIFIER_NAMES))
-      .optional()
-      .describe(
-        'Held modifiers. Common combos: ["cmd"] for cmd+key, ["cmd","shift"], ["control","option"].',
-      ),
-  }),
-  permission: { action: 'prompt' },
-  isolation: {
-    capabilities: {
-      subprocess: true,
-      commands: ['osascript'],
-      net: { mode: 'none' },
-      timeMs: 15_000,
-    },
-  },
-  async handler({ key, modifiers }, ctx) {
-    ensureDarwin('computer_key');
-    const mods = modifiers ?? [];
-    const script = buildKeyScript(key, mods);
-    const proc = await runProcess('osascript', ['-e', script], {
-      ...(ctx.signal ? { signal: ctx.signal } : {}),
-      timeoutMs: 10_000,
-    });
-    if (proc.exitCode !== 0) {
-      const cause = procFailureCause(proc, 10_000);
-      throw new MoxxyError({
-        code: 'TOOL_ERROR',
-        message: cause
-          ? `key ${cause}`
-          : `key failed (exit ${proc.exitCode}): ${proc.stderr.trim() || '(check Accessibility permission)'}`,
-        context: { tool: 'computer_key', exitCode: proc.exitCode, timedOut: proc.timedOut ? 1 : 0 },
-      });
-    }
-    return { ok: true, key, modifiers: mods };
-  },
-});
-
-/**
- * Build the `osascript -e` body for a single key chord. Named keys go
- * through `key code N`, single characters through `keystroke "x"`, and a
- * multi-char unknown key throws. Pure (no I/O) so it can be unit-tested.
- */
-export function buildKeyScript(key: string, modifiers: ReadonlyArray<Modifier>): string {
-  const usingClause =
-    modifiers.length > 0 ? ` using {${modifiers.map(modifierClause).join(', ')}}` : '';
-  const lower = key.toLowerCase();
-  if (lower in KEY_CODES) {
-    return `tell application "System Events" to key code ${KEY_CODES[lower]}${usingClause}`;
-  }
-  // A single literal whitespace char (' ', '\t', '\r', '\n') keystroked with a
-  // held modifier types the character rather than pressing the key, breaking
-  // chords like ctrl+space. Route it to the corresponding key code instead.
-  if (key.length === 1) {
-    const wsCode = WHITESPACE_KEY_CODES[key];
-    if (wsCode !== undefined) {
-      return `tell application "System Events" to key code ${wsCode}${usingClause}`;
-    }
-  }
-  if (key.length === 1) {
-    const literal = `"${key.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
-    return `tell application "System Events" to keystroke ${literal}${usingClause}`;
-  }
-  throw new MoxxyError({
-    code: 'TOOL_ERROR',
-    message: `unknown key "${key}". Use a single character or one of: ${Object.keys(KEY_CODES).join(', ')}.`,
-    context: { tool: 'computer_key', key },
-  });
-}
-
-function modifierClause(m: Modifier): string {
-  // AppleScript uses "command down", "shift down", "option down",
-  // "control down" — map our short names.
-  switch (m) {
-    case 'cmd':
-      return 'command down';
-    case 'shift':
-      return 'shift down';
-    case 'option':
-      return 'option down';
-    case 'control':
-      return 'control down';
-  }
-}