@moxxy/plugin-computer-control 0.26.0

package/src/tools/applescript.ts

@@ -0,0 +1,41 @@
+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' },
+  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

@@ -0,0 +1,52 @@
+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' },
+  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

@@ -0,0 +1,63 @@
+import { defineTool, MoxxyError, z } from '@moxxy/sdk';
+import { ensureDarwin, procFailureCause, runProcess } from '../shell.js';
+
+export const clipboardTool = defineTool({
+  name: 'computer_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' },
+  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

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

package/src/tools/open.ts

@@ -0,0 +1,81 @@
+import { defineTool, MoxxyError, z } from '@moxxy/sdk';
+import { ensureDarwin, procFailureCause, runProcess } from '../shell.js';
+
+export const openTool = defineTool({
+  name: 'computer_open',
+  description:
+    'Open a URL, file path, or .app bundle via macOS `open`. Use this to ' +
+    'launch / activate a specific app or jump to a web page. The model should ' +
+    'prefer this over typing into Spotlight when the target is known.',
+  inputSchema: z.object({
+    target: z
+      .string()
+      .min(1)
+      .describe(
+        'URL (https://...), file path (/Users/...), or app name (Safari). ' +
+          'For app names, prefer the `app` field — `target` is treated as a path.',
+      )
+      .optional(),
+    app: z
+      .string()
+      .min(1)
+      .max(120)
+      .describe(
+        'Application name to activate (e.g. "Safari", "Visual Studio Code"). ' +
+          'When `target` is also set, the app opens `target` (e.g. open a file in VS Code).',
+      )
+      .optional(),
+  }),
+  permission: { action: 'prompt' },
+  async handler({ target, app }, ctx) {
+    ensureDarwin('computer_open');
+    if (!target && !app) {
+      throw new MoxxyError({
+        code: 'TOOL_ERROR',
+        message: 'computer_open: at least one of `target` or `app` is required',
+        context: { tool: 'computer_open' },
+      });
+    }
+    // A target/app beginning with '-' (e.g. '-g', '-n', '-W') is parsed by
+    // /usr/bin/open as an OPTION FLAG, not a path/URL/app — silently changing
+    // behavior (open in background, new instance) the user did not approve.
+    // Reject it: no legitimate path/URL/app name starts with a dash, and
+    // spawn is array-form so this is the only argument-injection vector.
+    for (const [field, value] of [
+      ['target', target],
+      ['app', app],
+    ] as const) {
+      if (value !== undefined && value.startsWith('-')) {
+        throw new MoxxyError({
+          code: 'TOOL_ERROR',
+          message: `computer_open: \`${field}\` must not begin with '-' (would be parsed as an option flag)`,
+          context: { tool: 'computer_open', field },
+        });
+      }
+    }
+    const args: string[] = [];
+    if (app) {
+      args.push('-a', app);
+    }
+    // `--` ends option parsing so the positional target is treated strictly
+    // as a path/URL operand even if a future change relaxes the guard above.
+    if (target) {
+      args.push('--', target);
+    }
+    const proc = await runProcess('open', args, {
+      ...(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
+          ? `open ${cause}`
+          : `open failed (exit ${proc.exitCode}): ${proc.stderr.trim() || '(no error message)'}`,
+        context: { tool: 'computer_open', exitCode: proc.exitCode, timedOut: proc.timedOut ? 1 : 0 },
+      });
+    }
+    return { ok: true, app, target };
+  },
+});

package/src/tools/screenshot.ts

@@ -0,0 +1,181 @@
+import { randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { defineTool, MoxxyError, z } from '@moxxy/sdk';
+import { ensureDarwin, procFailureCause, runProcess } from '../shell.js';
+
+const regionSchema = z.object({
+  x: z.number().int().min(0),
+  y: z.number().int().min(0),
+  width: z.number().int().positive(),
+  height: z.number().int().positive(),
+});
+
+/**
+ * Defaults aggressive on size — a Retina full-screen PNG can pass
+ * 5 MB base64-encoded and instantly blow the model's context window.
+ * 1280px JPEG @ q72 is ~150 KB for a typical desktop and still
+ * legible enough for the model to identify UI elements.
+ */
+const DEFAULT_MAX_DIM = 1280;
+const DEFAULT_FORMAT = 'jpeg' as const;
+const DEFAULT_JPEG_QUALITY = 72;
+/** Soft cap on the encoded image size in bytes. We refuse to return
+ *  anything bigger than this even after the model asks for high-res —
+ *  better to fail loudly than silently nuke the context. */
+const MAX_BYTES = 1_500_000;
+
+export const screenshotTool = defineTool({
+  name: 'computer_screenshot',
+  description:
+    'Take a screenshot of the macOS desktop. Returns base64-encoded image bytes ' +
+    'the model can see directly. By default the image is downscaled to 1280px ' +
+    'and JPEG-compressed so a single screenshot stays well under context — ' +
+    'override `maxDim` / `format` / `quality` only when you genuinely need full ' +
+    'resolution. macOS will prompt for Screen Recording permission on first use.',
+  inputSchema: z.object({
+    region: regionSchema
+      .optional()
+      .describe(
+        'Crop to a rectangle in screen-pixel coordinates (top-left origin). Omit for full screen.',
+      ),
+    maxDim: z
+      .number()
+      .int()
+      .min(256)
+      .max(3840)
+      .optional()
+      .describe(
+        `Resize so the longest edge is <= this many pixels. Default ${DEFAULT_MAX_DIM}. ` +
+          'Lower = smaller payload + less context cost; raise only when you need pixel detail.',
+      ),
+    format: z
+      .enum(['jpeg', 'png'])
+      .optional()
+      .describe(
+        `Output format. Default "${DEFAULT_FORMAT}" (much smaller). Pick "png" only when ` +
+          'you need lossless (rare — JPEG is fine for UI screenshots).',
+      ),
+    quality: z
+      .number()
+      .int()
+      .min(40)
+      .max(100)
+      .optional()
+      .describe(
+        `JPEG quality (1-100). Default ${DEFAULT_JPEG_QUALITY}. Ignored for PNG output.`,
+      ),
+  }),
+  permission: { action: 'prompt' },
+  async handler({ region, maxDim, format, quality }, ctx) {
+    ensureDarwin('computer_screenshot');
+    const fmt = format ?? DEFAULT_FORMAT;
+    const dim = maxDim ?? DEFAULT_MAX_DIM;
+    const q = quality ?? DEFAULT_JPEG_QUALITY;
+
+    // Always capture as PNG first (preserves color depth + no double
+    // compression), then let `sips` resize and convert in one pass.
+    // `-x` silences the camera-shutter sound.
+    // A random suffix guarantees uniqueness even for two captures in the
+    // same process within the same millisecond (pid+Date.now() alone can
+    // collide and cross-corrupt the temp files).
+    const uniq = randomUUID();
+    const captureTmp = path.join(
+      os.tmpdir(),
+      `moxxy-screencap-${process.pid}-${Date.now()}-${uniq}.png`,
+    );
+    const captureArgs = ['-x', '-t', 'png'];
+    if (region) {
+      captureArgs.push('-R', `${region.x},${region.y},${region.width},${region.height}`);
+    }
+    captureArgs.push(captureTmp);
+    // Guarantee the original PNG (potentially several MB for a Retina full
+    // screen) is removed on EVERY exit path — success, throw, or a spawn
+    // reject (e.g. `sips` not on PATH) / mid-capture timeout that may have
+    // left a partial file. Without this, those failure paths leak the temp
+    // file in os.tmpdir() permanently and accumulate over repeated failures.
+    try {
+      const cap = await runProcess('screencapture', captureArgs, {
+        ...(ctx.signal ? { signal: ctx.signal } : {}),
+        timeoutMs: 15_000,
+      });
+      if (cap.exitCode !== 0) {
+        const cause = procFailureCause(cap, 15_000);
+        throw new MoxxyError({
+          code: 'TOOL_ERROR',
+          message: cause
+            ? `screencapture ${cause}`
+            : `screencapture failed (exit ${cap.exitCode}): ${cap.stderr.trim() || '(no stderr — likely Screen Recording permission missing — grant in System Settings → Privacy & Security)'}`,
+          context: { tool: 'computer_screenshot', exitCode: cap.exitCode, timedOut: cap.timedOut ? 1 : 0 },
+        });
+      }
+
+      // Resize + format-convert in one sips call. `-Z N` fits within N
+      // on the longest edge while preserving aspect ratio. Output ext
+      // picks the format; format options apply when JPEG.
+      const outExt = fmt === 'jpeg' ? 'jpg' : 'png';
+      const outTmp = path.join(
+        os.tmpdir(),
+        `moxxy-screencap-${process.pid}-${Date.now()}-${uniq}-out.${outExt}`,
+      );
+      const sipsArgs = [
+        '-Z',
+        String(dim),
+        '--setProperty',
+        'format',
+        fmt,
+      ];
+      if (fmt === 'jpeg') {
+        sipsArgs.push('--setProperty', 'formatOptions', String(q));
+      }
+      sipsArgs.push(captureTmp, '--out', outTmp);
+      const sip = await runProcess('sips', sipsArgs, {
+        ...(ctx.signal ? { signal: ctx.signal } : {}),
+        timeoutMs: 15_000,
+      });
+      if (sip.exitCode !== 0) {
+        await fs.rm(outTmp, { force: true });
+        const cause = procFailureCause(sip, 15_000);
+        throw new MoxxyError({
+          code: 'TOOL_ERROR',
+          message: cause
+            ? `sips resize/convert ${cause}`
+            : `sips resize/convert failed (exit ${sip.exitCode}): ${sip.stderr.trim() || '(no error message)'}`,
+          context: { tool: 'computer_screenshot', exitCode: sip.exitCode, timedOut: sip.timedOut ? 1 : 0 },
+        });
+      }
+
+      try {
+        const bytes = await fs.readFile(outTmp);
+        if (bytes.length > MAX_BYTES) {
+          throw new MoxxyError({
+            code: 'TOOL_ERROR',
+            message:
+              `screenshot exceeded ${MAX_BYTES} bytes after compression (got ${bytes.length}). ` +
+              `Lower maxDim (currently ${dim}) or quality (currently ${q}), or pass a smaller region.`,
+            context: { tool: 'computer_screenshot', byteLength: bytes.length },
+          });
+        }
+        // The `{ mediaType, base64 }` pair is load-bearing, not decorative: the
+        // SDK's tool_result projection keys off exactly this shape to emit a
+        // provider `image` ContentBlock so the model SEES the pixels. Returning
+        // the bytes inside a stringified blob (the JSON.stringify fallback path)
+        // would reach the model as base64 TEXT it cannot decode. Extra fields
+        // are diagnostic only and ignored by the image projection.
+        return {
+          mediaType: fmt === 'jpeg' ? ('image/jpeg' as const) : ('image/png' as const),
+          base64: bytes.toString('base64'),
+          byteLength: bytes.length,
+          maxDim: dim,
+          format: fmt,
+          ...(fmt === 'jpeg' ? { quality: q } : {}),
+        };
+      } finally {
+        await fs.rm(outTmp, { force: true });
+      }
+    } finally {
+      await fs.rm(captureTmp, { force: true });
+    }
+  },
+});

package/src/tools/type.ts

@@ -0,0 +1,60 @@
+import { defineTool, MoxxyError, z } from '@moxxy/sdk';
+import { ensureDarwin, procFailureCause, runProcess } from '../shell.js';
+
+export const typeTool = defineTool({
+  name: 'computer_type',
+  description:
+    'Type a string into whatever has keyboard focus. Use AFTER clicking the ' +
+    'target field. Macros (cmd+C, etc.) belong in computer_key, not here — this ' +
+    'tool sends each character literally. Requires Accessibility permission.',
+  inputSchema: z.object({
+    text: z
+      .string()
+      .max(4000)
+      .describe(
+        'The literal text to type. Newlines and tabs are typed as-is. ' +
+          'Pre-existing focus is the target — click first if needed.',
+      ),
+  }),
+  permission: { action: 'prompt' },
+  async handler({ text }, ctx) {
+    ensureDarwin('computer_type');
+    if (text.length === 0) return { ok: true, length: 0 };
+    // Serialize the text to an AppleScript string literal ourselves and
+    // pass it inline via `osascript -e`, so we never have to escape
+    // AppleScript quote rules at the shell layer.
+    const literal = toAppleScriptString(text);
+    const directScript = `tell application "System Events" to keystroke ${literal}`;
+    const proc = await runProcess('osascript', ['-e', directScript], {
+      ...(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
+          ? `type ${cause}`
+          : `type failed (exit ${proc.exitCode}): ${proc.stderr.trim() || '(check Accessibility permission)'}`,
+        context: { tool: 'computer_type', exitCode: proc.exitCode, timedOut: proc.timedOut ? 1 : 0 },
+      });
+    }
+    return { ok: true, length: text.length };
+  },
+});
+
+/**
+ * Serialize an arbitrary JS string into a valid AppleScript string
+ * literal. AppleScript string syntax: `"..."` with `\"` and `\\` as
+ * the only escapes; newlines are written as `" & return & "`.
+ */
+export function toAppleScriptString(s: string): string {
+  // Split on newlines to use `return` (AppleScript's CR constant) so
+  // a multi-line type call sends actual Enter keystrokes rather than a
+  // literal `\n` in one keystroke (which keystroke would refuse).
+  const parts = s.split('\n').map((line) => {
+    const escaped = line.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    return `"${escaped}"`;
+  });
+  return parts.join(' & return & ');
+}