@moxxy/plugin-computer-control 0.26.0

package/skills/computer-control.md

@@ -0,0 +1,159 @@
+---
+name: computer-control
+description: Drive the user's Mac (mouse, keyboard, screenshot, clipboard, app launch) when the task can't be done with files/web alone.
+triggers:
+  - "click on"
+  - "click the"
+  - "take a screenshot"
+  - "screenshot the"
+  - "screen capture"
+  - "screen shot"
+  - "open the app"
+  - "open app"
+  - "launch app"
+  - "switch to"
+  - "type into"
+  - "type this"
+  - "paste this"
+  - "what's on my screen"
+  - "what is on screen"
+  - "show me the screen"
+  - "control my computer"
+  - "automate"
+  - "for me on the screen"
+  - "use my mac"
+  - "drive the ui"
+allowed-tools:
+  - computer_screenshot
+  - computer_click
+  - computer_type
+  - computer_key
+  - computer_open
+  - computer_clipboard
+  - computer_applescript
+---
+
+# Computer control (macOS)
+
+When the task requires driving the user's actual desktop — clicking a UI
+button, typing into an open app, taking a screenshot, launching software —
+use the `computer_*` tools. Each one prompts for permission **every time**;
+the user explicitly approves each action. There is no "allow always" for
+these by design.
+
+## macOS permission prerequisites
+
+On first use the user will see a system dialog from macOS itself. Tell them
+which one to expect:
+
+- **Screen Recording** — required by `computer_screenshot`. Grant in System
+  Settings → Privacy & Security → Screen Recording.
+- **Accessibility** — required by `computer_click`, `computer_type`,
+  `computer_key`, and most `computer_applescript` snippets that touch UI.
+  Grant in System Settings → Privacy & Security → Accessibility.
+
+If a tool returns "(check Accessibility permission)" or "(check Screen
+Recording permission)" in its error, surface that message verbatim and
+stop — don't loop on the same failing call.
+
+## The standard loop: see → act → verify
+
+Almost every UI automation follows this rhythm. Do it explicitly:
+
+1. **See** — call `computer_screenshot` to capture the current state.
+   Look at the image, identify the target element, note its pixel
+   coordinates from the top-left.
+2. **Act** — `computer_click` / `computer_type` / `computer_key` on the
+   coordinates / focused field.
+3. **Verify** — `computer_screenshot` again, confirm the expected
+   change. If not, diagnose before retrying.
+
+**Do NOT skip the verify.** A 200ms animation, a popup, or a focus shift
+can silently break the next step. The agent that screenshots after every
+action is the agent that doesn't accidentally type a password into the
+wrong field.
+
+## Tool reference (quick)
+
+```
+computer_screenshot({ region?, maxDim?, format?, quality? })
+  → { mediaType, base64, byteLength, maxDim, format }
+  Default: full screen → 1280px JPEG @ q72 (~150 KB).
+  Override `maxDim`/`format`/`quality` only when you need pixel detail —
+  context-cost climbs fast for large/PNG images.
+
+computer_click({ x, y, count? })          # count: 1=single, 2=double, 3=triple
+
+computer_type({ text })                   # types into whatever has focus
+                                          # CLICK FIRST to set focus
+
+computer_key({ key, modifiers? })         # key: "a", "tab", "return", "f5", ...
+                                          # modifiers: ["cmd","shift","option","control"]
+
+computer_open({ target?, app? })          # app: "Safari", target: URL or path
+
+computer_clipboard({ action: "read" })
+computer_clipboard({ action: "write", text })
+
+computer_applescript({ script })          # escape hatch — anything else
+```
+
+## Common patterns
+
+**Take a screenshot and describe it:**
+```
+1. computer_screenshot({})
+2. Look at the image — describe the active app, visible windows, any errors
+```
+
+**Open an app and click a known button:**
+```
+1. computer_open({ app: "Safari" })
+2. (wait a moment for activation)
+3. computer_screenshot({})       # find the button's coordinates
+4. computer_click({ x: ..., y: ... })
+5. computer_screenshot({})       # verify
+```
+
+**Paste text into the focused field:**
+```
+1. computer_clipboard({ action: "write", text: "..." })
+2. computer_key({ key: "v", modifiers: ["cmd"] })
+```
+
+**Get the frontmost app name (via the escape hatch):**
+```
+computer_applescript({
+  script: 'tell application "System Events" to get name of first application process whose frontmost is true'
+})
+```
+
+## Don't
+
+- **Don't click without screenshotting first.** Coordinates change between
+  turns; a button moves when the window resizes. One screenshot per
+  action group is the minimum.
+- **Don't type into "focus" you didn't set.** `computer_type` sends keys
+  to whatever currently has keyboard focus. Click the target field first
+  (or call `computer_key` with cmd+l to focus an address bar, etc.).
+- **Don't loop on a failed click.** If a click "succeeded" (exit 0) but
+  the next screenshot shows nothing changed, the coordinates were wrong.
+  Re-screenshot, re-find the target, try again — but stop after two
+  failed attempts and explain to the user.
+- **Don't use computer_key for typing words.** `computer_key({ key: "h" })`
+  sends one keystroke. Use `computer_type({ text: "hello" })` instead.
+- **Don't paste passwords / API keys via clipboard if the user has a
+  password manager.** Suggest they trigger the manager instead. The
+  clipboard is observable by every app.
+- **Don't run open-ended `computer_applescript` snippets when a
+  dedicated tool fits.** The escape hatch is for the long tail.
+- **Don't take screenshots the user didn't ask for.** Each one captures
+  whatever happens to be on screen — including messages, notifications,
+  unrelated windows. Take one when you need pixels for an action, not
+  out of curiosity.
+
+## Platforms other than macOS
+
+This plugin currently only supports macOS. On Linux/Windows the tools
+register but each handler throws `currently only supports macOS`. Tell
+the user that explicitly instead of looping on failures.

package/src/index.ts

@@ -0,0 +1,55 @@
+import { definePlugin, type Plugin, type ToolDef } from '@moxxy/sdk';
+import { IS_DARWIN } from './shell.js';
+import { applescriptTool } from './tools/applescript.js';
+import { clickTool } from './tools/click.js';
+import { clipboardTool } from './tools/clipboard.js';
+import { keyTool } from './tools/key.js';
+import { openTool } from './tools/open.js';
+import { screenshotTool } from './tools/screenshot.js';
+import { typeTool } from './tools/type.js';
+
+export {
+  applescriptTool,
+  clickTool,
+  clipboardTool,
+  keyTool,
+  openTool,
+  screenshotTool,
+  typeTool,
+};
+
+export const computerControlTools: ReadonlyArray<ToolDef> = [
+  screenshotTool,
+  clickTool,
+  typeTool,
+  keyTool,
+  openTool,
+  clipboardTool,
+  applescriptTool,
+];
+
+/**
+ * `@moxxy/plugin-computer-control` — programmatic control of the host
+ * computer (mouse, keyboard, screenshot, clipboard, app launching,
+ * AppleScript escape hatch).
+ *
+ * Currently macOS-only: every tool shells out to built-in binaries
+ * (`screencapture`, `osascript`, `open`, `pbpaste`, `pbcopy`). On any
+ * other platform the plugin still registers — the tools' handlers
+ * throw a clear "macOS only" error — so the model's tool list stays
+ * stable across hosts (avoids "tool disappeared on Linux" confusion).
+ *
+ * Every tool is `permission: 'prompt'`. There is intentionally no
+ * "allow always" shortcut for these — granting blanket permission to
+ * drive the user's screen + keyboard is exactly the wrong default.
+ */
+export const computerControlPlugin: Plugin = definePlugin({
+  name: '@moxxy/plugin-computer-control',
+  version: '0.0.0',
+  tools: [...computerControlTools],
+});
+
+export default computerControlPlugin;
+
+// Re-export for callers that want a runtime gate.
+export { IS_DARWIN };

package/src/shell.test.ts

@@ -0,0 +1,186 @@
+import { MoxxyError } from '@moxxy/sdk';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { ensureDarwin, MAX_OUTPUT_BYTES, procFailureCause, runProcess } from './shell.js';
+
+describe('runProcess stdout capture (chunked, O(n) concat-at-close)', () => {
+  it('captures the full stdout across many small chunks', async () => {
+    // A child that writes 5000 lines one at a time — exercises the multi-chunk
+    // 'data' path that used to re-copy the whole buffer per event.
+    const script =
+      "for (let i = 0; i < 5000; i++) { process.stdout.write('line ' + i + '\\n'); }";
+    const res = await runProcess(process.execPath, ['-e', script], { timeoutMs: 30_000 });
+
+    expect(res.exitCode).toBe(0);
+    const lines = res.stdout.split('\n');
+    // 5000 lines + a trailing '' from the final newline.
+    expect(lines).toHaveLength(5001);
+    expect(lines[0]).toBe('line 0');
+    expect(lines[4999]).toBe('line 4999');
+    expect(lines[5000]).toBe('');
+  });
+
+  it('captures binary-ish/multibyte stdout without corrupting it', async () => {
+    const script = "process.stdout.write('héllo 🦊 wörld');";
+    const res = await runProcess(process.execPath, ['-e', script], { timeoutMs: 30_000 });
+    expect(res.stdout).toBe('héllo 🦊 wörld');
+  });
+
+  it('writes input to stdin and reads it back', async () => {
+    const script =
+      "let s=''; process.stdin.on('data', d => s += d); process.stdin.on('end', () => process.stdout.write(s.toUpperCase()));";
+    const res = await runProcess(process.execPath, ['-e', script], { input: 'hello' });
+    expect(res.stdout).toBe('HELLO');
+  });
+
+  it('does not crash (EPIPE) when the child exits before stdin is fully written', async () => {
+    // The child exits immediately WITHOUT reading stdin; writing a large
+    // buffer to its closed stdin pipe emits 'error' (EPIPE) on the Writable.
+    // With no 'error' listener that throws as an unhandled rejection that can
+    // take down the parent — the swallow handler must keep us alive.
+    const big = 'x'.repeat(2 * 1024 * 1024);
+    const res = await runProcess(process.execPath, ['-e', 'process.exit(0)'], {
+      input: big,
+      timeoutMs: 30_000,
+    });
+    // We don't assert on stdout here — only that the call settles without an
+    // uncaught EPIPE. The child's own exit code is what matters.
+    expect(res.exitCode).toBe(0);
+  });
+});
+
+describe('runProcess exit/stderr/abort/timeout', () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('captures stderr and maps a non-zero exit code', async () => {
+    const script = "process.stderr.write('boom'); process.exit(3);";
+    const res = await runProcess(process.execPath, ['-e', script], { timeoutMs: 30_000 });
+    expect(res.exitCode).toBe(3);
+    expect(res.stderr).toBe('boom');
+    expect(res.stdout).toBe('');
+    // A genuine non-zero exit is neither a timeout nor an abort.
+    expect(res.timedOut).toBe(false);
+    expect(res.aborted).toBe(false);
+    expect(procFailureCause(res, 30_000)).toBe('');
+  });
+
+  it('captures multibyte stderr without corruption (chunk-boundary safe)', async () => {
+    // A flood of 3-byte glyphs forces the stream to split a UTF-8 sequence
+    // mid-character across 'data' chunk boundaries (the ~8 KB pipe chunk size
+    // is not a multiple of 3, so a boundary lands inside a glyph). Decoding
+    // each chunk in isolation — the pre-fix behavior — emits replacement chars
+    // (U+FFFD); concat-at-close preserves the exact bytes. This matters for
+    // osascript/sips error text with non-ASCII app names.
+    // Exit only AFTER the write fully drains so the pipe isn't truncated by a
+    // premature process.exit (a harness artifact, not the behavior under test).
+    const count = 20000;
+    const script = `process.stderr.write('世'.repeat(${count}), () => process.exit(1));`;
+    const res = await runProcess(process.execPath, ['-e', script], { timeoutMs: 30_000 });
+    expect(res.exitCode).toBe(1);
+    expect(res.stderr).toBe('世'.repeat(count));
+    expect(res.stderr).not.toContain('�');
+  });
+
+  it('does not spawn and resolves as aborted when the signal is ALREADY aborted', async () => {
+    // DOM semantics: addEventListener('abort', ...) on an already-aborted
+    // signal never fires — so without an up-front check a cancelled turn would
+    // still run the child to completion. The child here would write a sentinel
+    // and exit 0 if it ran; we assert it never did.
+    const ctrl = new AbortController();
+    ctrl.abort();
+    const script = "process.stdout.write('SHOULD_NOT_RUN'); process.exit(0);";
+    const res = await runProcess(process.execPath, ['-e', script], {
+      signal: ctrl.signal,
+      timeoutMs: 30_000,
+    });
+    expect(res.aborted).toBe(true);
+    expect(res.stdout).toBe('');
+    expect(res.exitCode).toBe(-1);
+    expect(res.timedOut).toBe(false);
+    expect(res.tooLarge).toBe(false);
+    expect(procFailureCause(res)).toBe('aborted (turn cancelled)');
+  });
+
+  it('rejects when the binary does not exist (spawn error)', async () => {
+    await expect(
+      runProcess('definitely-not-a-real-binary-xyz', [], { timeoutMs: 30_000 }),
+    ).rejects.toThrow();
+  });
+
+  it('kills the child when the AbortSignal fires', async () => {
+    const ctrl = new AbortController();
+    // A child that would otherwise run for a long time.
+    const script = 'setTimeout(() => {}, 60_000);';
+    const promise = runProcess(process.execPath, ['-e', script], { signal: ctrl.signal });
+    // Give the child a tick to spawn, then abort.
+    await new Promise((r) => setTimeout(r, 50));
+    ctrl.abort();
+    const res = await promise;
+    // SIGTERM-killed child resolves via 'close' with a null code -> -1.
+    expect(res.exitCode).toBe(-1);
+    // ...but the `aborted` flag distinguishes it from a genuine -1 exit.
+    expect(res.aborted).toBe(true);
+    expect(res.timedOut).toBe(false);
+    expect(procFailureCause(res)).toBe('aborted (turn cancelled)');
+  });
+
+  it('kills the child when timeoutMs elapses', async () => {
+    const script = 'setTimeout(() => {}, 60_000);';
+    const res = await runProcess(process.execPath, ['-e', script], { timeoutMs: 100 });
+    expect(res.exitCode).toBe(-1);
+    // A timed-out child is flagged so callers can report a precise cause
+    // rather than a confusing bare `exit -1`.
+    expect(res.timedOut).toBe(true);
+    expect(res.aborted).toBe(false);
+    expect(res.tooLarge).toBe(false);
+    expect(procFailureCause(res, 100)).toBe('timed out after 100ms');
+  });
+
+  it('force-kills a child that floods stdout past MAX_OUTPUT_BYTES instead of OOMing', async () => {
+    // A runaway child that writes an unbounded stream. The byte cap must kill
+    // it well before it can accumulate gigabytes in the parent; we cap the
+    // child's own attempt above MAX_OUTPUT_BYTES so the test also terminates
+    // on its own if the cap somehow fails to fire.
+    const target = MAX_OUTPUT_BYTES + 4 * 1024 * 1024;
+    const script = `
+      const chunk = Buffer.alloc(1024 * 1024, 0x61);
+      let sent = 0;
+      const target = ${target};
+      function pump() {
+        while (sent < target) {
+          sent += chunk.length;
+          if (!process.stdout.write(chunk)) { process.stdout.once('drain', pump); return; }
+        }
+      }
+      pump();
+    `;
+    const res = await runProcess(process.execPath, ['-e', script], { timeoutMs: 30_000 });
+    expect(res.tooLarge).toBe(true);
+    // We STOP retaining chunks the instant the cap is tripped, so the captured
+    // output never exceeds the cap plus one already-buffered chunk — it does
+    // NOT keep growing toward `target` while the child is being killed.
+    expect(Buffer.byteLength(res.stdout, 'utf8')).toBeLessThanOrEqual(
+      MAX_OUTPUT_BYTES + 1024 * 1024,
+    );
+    expect(res.timedOut).toBe(false);
+    expect(procFailureCause(res, 30_000)).toContain('output exceeded');
+  });
+});
+
+describe('ensureDarwin', () => {
+  it('matches the current platform contract', () => {
+    if (process.platform === 'darwin') {
+      expect(() => ensureDarwin('screenshot')).not.toThrow();
+    } else {
+      expect(() => ensureDarwin('screenshot')).toThrow(MoxxyError);
+      try {
+        ensureDarwin('screenshot');
+      } catch (err) {
+        expect(err).toBeInstanceOf(MoxxyError);
+        expect((err as MoxxyError).code).toBe('TOOL_ERROR');
+        expect((err as MoxxyError).message).toContain('screenshot');
+      }
+    }
+  });
+});

package/src/shell.ts

@@ -0,0 +1,213 @@
+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/tools/applescript-serialize.test.ts

@@ -0,0 +1,74 @@
+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"');
+    }
+  });
+});