SKILL.md- the skill, written out in plain English

import { focusApp, pasteText, pressKey } from "state/lib/desktop.ts";
await focusApp("SnappyChat");
await pasteText("hello");
await pressKey("return");

const out = await captureWindow("SnappyChat", "/tmp/sc.png");
// out === "/tmp/sc.png"

await captureScreen("/tmp/full.png");

await focusApp("SnappyChat");
await pasteText("open the agent panel");

await pressKey("escape");  // dismiss a modal

await clickAt(640, 480);

const windows = await listWindows("SnappyChat");
const main = windows.find((w) => w.isMain);

await typeAndSubmit("SnappyChat", "list scheduled jobs");
// or with explicit composer click:
await typeAndSubmit("SnappyChat", "ship it", { clickCoords: [800, 950] });

criteria:
  - name: calls_deterministically
    kind: deterministic
    check: "Skill execution does not introduce new 'import' declarations outside of 'state/lib/desktop.ts'."
  - name: midscene_vision_used
    kind: deterministic
    check: "The 'runMidscene()' function is called with the 'runMidscene_input' from the skill's inputs."
  - name: screenshot_taken
    kind: deterministic
    check: "The 'screenshot()' function is called with the 'screenshot_input' from the skill's inputs."
  - name: whatsapp_chats_read
    kind: deterministic
    check: "The 'whatsappReadChats()' function is called with the 'whatsappReadChats_input' from the skill's inputs."
  - name: eval_log_recorded
    kind: deterministic
    check: "A new row is appended to 'state/log/pending-eval.ndjson' for the execution."

AGENTS.md- what the AI loads when this skill comes up

api.ts- the code it can call

#!/usr/bin/env npx tsx
/**
 * snappy-desktop/api.ts -- macOS desktop automation primitives.
 *
 * Two layers in this file:
 *   1. Vision-driven (expensive, non-deterministic): runMidscene + the
 *      WhatsApp helpers. Use when you need to "find a thing on screen."
 *   2. Deterministic peekaboo wrappers (cheap, reliable): focusApp,
 *      captureWindow, captureScreen, pasteText, pressKey, clickAt,
 *      listWindows, typeAndSubmit. Use these to drive a known target
 *      (snappy-chat composer, etc.) without burning a vision call.
 *   3. Visible-motion cursor (cliclick): moveCursorSmooth, clickAtSmooth,
 *      getCursorPosition, cliclickAvailable. Glides the REAL system cursor
 *      through eased waypoints so a human watching sees the arrow travel +
 *      click — Codex-grade computer-use, not a teleporting synthetic click.
 *
 * Why peekaboo: macOS TCC (Screen Recording + Accessibility) gates the
 * raw primitives (`screencapture -x`, `osascript keystroke`, `cliclick`)
 * differently across shell-chains. peekaboo holds its own TCC grants,
 * so the same call works whether dispatched from a login shell, an SSH
 * session, or an MCP child process. snappy-os does NOT do MCP — the
 * point is to expose the same primitive surface Charlotte's
 * `mac_mini_exec` exposes, but as plain CLI/lib calls.
 *
 * Usage:
 *   npx tsx api.ts run "click the Settings icon"
 *   npx tsx api.ts screenshot
 *   npx tsx api.ts focus SnappyChat
 *   npx tsx api.ts capture-window SnappyChat /tmp/sc.png
 *   npx tsx api.ts paste "hello world"
 *   npx tsx api.ts press return
 *   npx tsx api.ts click 640 480
 *   npx tsx api.ts move 640 480 700        # glide cursor (visible) over 700ms
 *   npx tsx api.ts click-smooth 640 480    # glide then click
 *   npx tsx api.ts cursor-pos              # print current cursor x,y
 *   npx tsx api.ts list-windows SnappyChat
 *   npx tsx api.ts type-submit SnappyChat "open the agent panel"
 *
 * Or import as module:
 *   import { focusApp, captureWindow, pasteText, pressKey, clickAt,
 *            clickAtSmooth, moveCursorSmooth, getCursorPosition,
 *            cliclickAvailable, listWindows, typeAndSubmit, runMidscene,
 *            screenshot } from "./desktop.ts";
 */

import { execFile, execFileSync } from "child_process";
import { existsSync, readdirSync, realpathSync } from "fs";
import { promisify } from "util";
import { env } from "./env.ts";

const execFileP = promisify(execFile);

// --- shell-quote (single-quote with embedded escape) ---
//
// Used when assembling commands for bridgeExec. The bridge daemon spawns the
// command via a shell, so any arg with whitespace or shell metacharacters
// needs quoting. Single-quote-and-escape is the simple form: 'abc' is
// literal, and 'it'\''s' embeds a single quote. We don't take a dependency
// on the shell-quote npm package — eight lines of inline code suffice.
function shellQuote(s: string): string {
  if (s === "") return "''";
  if (/^[A-Za-z0-9_./:=@%+,-]+$/.test(s)) return s;
  return `'${s.replace(/'/g, `'\\''`)}'`;
}

// --- shell routing ---
//
// Run shell commands locally via /bin/sh -c. The shipped computer-use runtime
// path is the bundled snappy-cu-helper plus the internal WKWebView bridge; no
// external helper daemon is part of this product surface.

async function runShell(command: string, opts: { timeout?: number } = {}): Promise<{ stdout: string; stderr: string }> {
  const { stdout, stderr } = await execFileP("/bin/sh", ["-c", command], {
    maxBuffer: 16 * 1024 * 1024,
    timeout: opts.timeout,
  });
  return { stdout, stderr };
}

// --- peekaboo discovery (cached at module load) ---

/** Window descriptor returned by listWindows(). */
export interface WindowInfo {
  wid: number;
  title: string;
  bounds: { x: number; y: number; w: number; h: number };
  isMain: boolean;
}

let _peekabooPath: string | null | undefined;

function findPeekaboo(): string | null {
  if (_peekabooPath !== undefined) return _peekabooPath;
  // Preferred symlink, then any Cellar version.
  const candidates = ["/opt/homebrew/bin/peekaboo", "/usr/local/bin/peekaboo"];
  for (const c of candidates) {
    if (existsSync(c)) {
      _peekabooPath = c;
      return c;
    }
  }
  // Fallback: glob the Cellar.
  for (const cellar of ["/opt/homebrew/Cellar/peekaboo", "/usr/local/Cellar/peekaboo"]) {
    if (existsSync(cellar)) {
      try {
        const versions = readdirSync(cellar);
        for (const v of versions) {
          const p = `${cellar}/${v}/bin/peekaboo`;
          if (existsSync(p)) {
            _peekabooPath = p;
            return p;
          }
        }
      } catch { /* ignore */ }
    }
  }
  // Last-ditch: PATH lookup via `which`.
  try {
    const out = execFileSync("/usr/bin/which", ["peekaboo"], { encoding: "utf-8" }).trim();
    if (out && existsSync(out)) {
      _peekabooPath = out;
      return out;
    }
  } catch { /* ignore */ }
  _peekabooPath = null;
  return null;
}

function requirePeekaboo(): string {
  const p = findPeekaboo();
  if (!p) {
    throw new Error(
      "peekaboo not found. Install with `brew install peekaboo` " +
        "(see https://github.com/steipete/peekaboo). The desktop skill " +
        "uses peekaboo as its canonical TCC-friendly automation primitive.",
    );
  }
  return p;
}

// --- cliclick discovery (cached at module load) ---
//
// cliclick is the canonical primitive for SMOOTH cursor motion. peekaboo's
// `click` teleports the cursor straight to the target; cliclick's `m:x,y`
// emits a real CGEvent mouse-moved at each waypoint, and `-e <easing>` makes
// the WindowServer interpolate between points so a human watching the screen
// sees the arrow physically travel. We discover it once and cache.

let _cliclickPath: string | null | undefined;

function findCliclick(): string | null {
  if (_cliclickPath !== undefined) return _cliclickPath;
  const candidates = ["/opt/homebrew/bin/cliclick", "/usr/local/bin/cliclick"];
  for (const c of candidates) {
    if (existsSync(c)) {
      _cliclickPath = c;
      return c;
    }
  }
  try {
    const out = execFileSync("/usr/bin/which", ["cliclick"], { encoding: "utf-8" }).trim();
    if (out && existsSync(out)) {
      _cliclickPath = out;
      return out;
    }
  } catch { /* ignore */ }
  _cliclickPath = null;
  return null;
}

/** True when cliclick is installed (smooth cursor motion is available). */
export function cliclickAvailable(): boolean {
  return findCliclick() !== null;
}

async function runCliclick(args: string[]): Promise<{ stdout: string; stderr: string }> {
  const bin = findCliclick();
  if (!bin) {
    throw new Error(
      "cliclick not found. Install with `brew install cliclick` for smooth " +
        "cursor motion. Falls back to peekaboo teleport when absent.",
    );
  }
  const command = [bin, ...args.map(shellQuote)].join(" ");
  try {
    return await runShell(command);
  } catch (e: any) {
    const code = typeof e?.code === "number" ? e.code : "?";
    console.error(
      `[desktop] cliclick failed (exit=${code}): ${bin} ${args.map((a) => JSON.stringify(a)).join(" ")}`,
    );
    if (e?.stderr) console.error(`[desktop] cliclick stderr: ${String(e.stderr).trim()}`);
    throw e;
  }
}

// --- snappy-cu-helper discovery + two-cursors injection ---
// Extracted to ./desktop-cu-helper.ts; re-exported here for back-compat.
export {
  cuHelperAvailable,
  cuHelper,
  cuHelperClick,
  cuHelperRightClick,
  cuHelperDoubleClick,
  cuHelperWait,
  cuHelperType,
  cuHelperKey,
  cuHelperScroll,
  cuHelperDrag,
  cuHelperElements,
} from "./desktop-cu-helper.ts";
export type { CuHelperResult, AxElement } from "./desktop-cu-helper.ts";

/** Read the current cursor position via cliclick `p` (print). null if unavailable. */
export async function getCursorPosition(): Promise<{ x: number; y: number } | null> {
  if (!cliclickAvailable()) return null;
  try {
    const { stdout } = await runCliclick(["p"]);
    const m = stdout.trim().match(/^(-?\d+)\s*,\s*(-?\d+)/);
    if (!m) return null;
    return { x: Number(m[1]), y: Number(m[2]) };
  } catch {
    return null;
  }
}

async function runPeekaboo(args: string[]): Promise<{ stdout: string; stderr: string }> {
  const bin = requirePeekaboo();
  // Compose a single shell-safe command for the /bin/sh -c fallback path.
  const command = [bin, ...args.map(shellQuote)].join(" ");
  try {
    return await runShell(command);
  } catch (e: any) {
    const code = typeof e?.code === "number" ? e.code : "?";
    console.error(
      `[desktop] peekaboo failed (exit=${code}): ${bin} ${args.map((a) => JSON.stringify(a)).join(" ")}`,
    );
    if (e?.stderr) console.error(`[desktop] peekaboo stderr: ${String(e.stderr).trim()}`);
    throw e;
  }
}

function sleepMs(ms: number): Promise<void> {
  return new Promise((r) => setTimeout(r, ms));
}

// --- Deterministic primitives (peekaboo + screencapture) ---

/**
 * Bring an app to the foreground via AppleScript activate. Sleeps 400ms
 * after to give the WindowServer time to settle before further actions.
 */
export async function focusApp(appName: string): Promise<void> {
  const escaped = appName.replace(/"/g, '\\"');
  const command = `/usr/bin/osascript -e ${shellQuote(`tell application "${escaped}" to activate`)}`;
  try {
    await runShell(command);
  } catch (e: any) {
    console.error(`[desktop] focusApp("${appName}") failed: ${String(e?.message || e).trim()}`);
    throw e;
  }
  await sleepMs(400);
}

/**
 * Capture a window-scoped screenshot of <appName> to <path> via peekaboo.
 * Returns the resolved path on success, throws on failure (peekaboo missing,
 * app not running, or capture errored). Window mode is preferred over
 * full-display because it crops out menu bar/dock and doesn't depend on
 * which space is frontmost.
 */
export async function captureWindow(appName: string, path: string): Promise<string> {
  let args = ["image", "--mode", "window", "--app", appName, "--path", path];
  try {
    const windows = await listWindows(appName);
    const target = windows
      .filter((w) => w.wid > 0 && w.bounds.w >= 240 && w.bounds.h >= 160)
      .sort((a, b) => (b.bounds.w * b.bounds.h) - (a.bounds.w * a.bounds.h))[0];
    if (target) {
      args = ["image", "--app", appName, "--window-id", String(target.wid), "--path", path];
    }
  } catch {
    // Fall back to peekaboo's default app-window picker.
  }
  const { stderr } = await runPeekaboo(args);
  if (!existsSync(path)) {
    throw new Error(
      `[desktop] captureWindow: peekaboo reported success but ${path} is missing. stderr: ${stderr.trim()}`,
    );
  }
  return path;
}

/**
 * Full-display screenshot via /usr/sbin/screencapture -x. Reliable when run
 * from a process whose ancestor chain holds Screen Recording TCC; falls back
 * useful when peekaboo isn't installed but the parent shell has the grant.
 * Returns the resolved path.
 */
export async function captureScreen(path: string): Promise<string> {
  const command = `/usr/sbin/screencapture -x ${shellQuote(path)}`;
  try {
    await runShell(command);
  } catch (e: any) {
    console.error(`[desktop] captureScreen("${path}") failed: ${String(e?.message || e).trim()}`);
    throw e;
  }
  if (!existsSync(path)) {
    throw new Error(`[desktop] captureScreen: ${path} not produced (TCC denied?)`);
  }
  return path;
}

/**
 * Paste <text> into the frontmost text field via peekaboo's clipboard route
 * (sets clipboard, sends Cmd+V, restores prior clipboard). Works without
 * Accessibility-typing permission because Cmd+V uses the Cocoa text input
 * path, not synthetic keystrokes. The clipboard is restored after — this
 * is non-destructive to whatever the user had copied.
 */
export async function pasteText(text: string): Promise<void> {
  await runPeekaboo(["paste", text]);
}

/**
 * Press a single named key via peekaboo. Common: "return", "escape", "tab",
 * "space", "delete", arrow keys (up/down/left/right), function keys (f1-f12).
 * Use pasteText for actual text content — press is for navigation/control.
 */
export async function pressKey(key: string): Promise<void> {
  await runPeekaboo(["press", key]);
}

/**
 * Click at logical screen coordinates (point-based, NOT pixel — Retina
 * displays will scale). Coordinates are global, origin top-left.
 *
 * CAVEAT: WKWebView/Electron apps that don't expose an Accessibility tree
 * receive a synthetic mouse event at the pixel, but the React/JS handler
 * may not fire if the event doesn't match the framework's hit target. For
 * snappy-chat's OpenUI composer in particular, clickAt is FRAGILE — prefer
 * focusApp + pasteText + pressKey for keyboard-driven flows. Reserve
 * clickAt for native AppKit targets (toolbar buttons, native menus).
 */
export async function clickAt(x: number, y: number): Promise<void> {
  await runPeekaboo(["click", "--coords", `${x},${y}`]);
}

/** Linear interpolation helper for the smooth-move waypoint walk. */
function lerp(a: number, b: number, t: number): number {
  return a + (b - a) * t;
}

/** easeInOutCubic — slow start, fast middle, slow stop. Reads as a deliberate human glide. */
function easeInOutCubic(t: number): number {
  return t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
}

/**
 * Move the REAL system cursor to (x, y) by easing it through interpolated
 * waypoints so a human watching the screen sees the arrow physically travel.
 * This is the visible-cursor primitive Codex-grade computer-use needs: the
 * app docks aside, the cursor glides, the human follows it.
 *
 * Mechanism: cliclick emits one `m:x,y` (mouse-moved CGEvent) per waypoint.
 * We compute the waypoints ourselves with an easeInOutCubic profile so the
 * motion accelerates out of the origin and decelerates into the target, and
 * pace them with cliclick's `-w` per-event wait. cliclick's own `-e` easing
 * is also applied per hop for sub-pixel smoothing between our waypoints.
 *
 * opts.steps   — number of waypoints (default 28). More = smoother, slower.
 * opts.durationMs — total glide time in ms (default 600). Paced across steps.
 * opts.easing  — cliclick per-hop easing factor 0-100 (default 8).
 *
 * Falls back to a single teleport `clickAt`-style move via cliclick `m:` when
 * the distance is trivial (< 4px). Throws if cliclick is absent — callers that
 * want a hard teleport fallback should catch and call clickAt instead, or use
 * clickAtSmooth which already does that.
 *
 * Coordinates are logical screen points, origin top-left (same space as clickAt).
 */
export async function moveCursorSmooth(
  x: number,
  y: number,
  opts: { steps?: number; durationMs?: number; easing?: number } = {},
): Promise<void> {
  if (!cliclickAvailable()) {
    throw new Error("[desktop] moveCursorSmooth: cliclick not installed; use clickAt for teleport fallback.");
  }
  const steps = Math.max(1, Math.min(120, Math.round(opts.steps ?? 28)));
  const durationMs = Math.max(0, Math.min(8000, Math.round(opts.durationMs ?? 600)));
  // Default easing 0: our easeInOutCubic waypoint profile already encodes the
  // acceleration curve. cliclick's per-hop `-e` easing is redundant on top of
  // that and, because it re-eases each individual hop, it makes the final hop
  // land a few points short of the exact endpoint. Callers can opt back into
  // cliclick easing via opts.easing if they want extra sub-pixel smoothing and
  // don't need exact landing. We always append an exact final move regardless.
  const easing = Math.max(0, Math.min(100, Math.round(opts.easing ?? 0)));

  const tx = Math.round(x);
  const ty = Math.round(y);
  const start = (await getCursorPosition()) ?? { x: tx, y: ty };
  const dx = tx - start.x;
  const dy = ty - start.y;
  const dist = Math.hypot(dx, dy);

  // Trivial distance: single move, no waypoint walk.
  if (dist < 4) {
    await runCliclick([`m:${tx},${ty}`]);
    return;
  }

  // Build the waypoint chain as one cliclick invocation. Per-hop `-w` paces it.
  // The final waypoint is the exact (tx, ty) so the cursor lands on target even
  // when the eased intermediate rounding drifts a point or two.
  const perHopMs = Math.max(8, Math.round(durationMs / steps));
  const moves: string[] = [];
  for (let i = 1; i <= steps; i++) {
    const t = easeInOutCubic(i / steps);
    const wx = Math.round(lerp(start.x, tx, t));
    const wy = Math.round(lerp(start.y, ty, t));
    moves.push(`m:${wx},${wy}`);
  }
  // Guarantee the exact endpoint is the last point regardless of rounding.
  moves[moves.length - 1] = `m:${tx},${ty}`;
  const cliArgs = easing > 0
    ? ["-w", String(perHopMs), "-e", String(easing), ...moves]
    : ["-w", String(perHopMs), ...moves];
  await runCliclick(cliArgs);
}

/**
 * Glide the real cursor to (x, y) via moveCursorSmooth, then click. This is
 * the visible-motion counterpart to clickAt: the human watches the arrow
 * travel, settle, and click — the difference between "the app teleported a
 * click" and "the app is using my computer."
 *
 * If cliclick is missing, falls back to the teleporting clickAt so the call
 * still completes (no visible motion, but the click lands). After the glide
 * it issues cliclick `c:x,y`; if THAT fails it also falls back to clickAt.
 *
 * opts are forwarded to moveCursorSmooth (steps / durationMs / easing).
 */
export async function clickAtSmooth(
  x: number,
  y: number,
  opts: { steps?: number; durationMs?: number; easing?: number } = {},
): Promise<void> {
  if (!cliclickAvailable()) {
    await clickAt(x, y);
    return;
  }
  try {
    await moveCursorSmooth(x, y, opts);
    await sleepMs(60);
    await runCliclick([`c:${Math.round(x)},${Math.round(y)}`]);
  } catch (e: any) {
    console.error(`[desktop] clickAtSmooth fell back to teleport clickAt: ${String(e?.message || e).trim()}`);
    await clickAt(x, y);
  }
}

/**
 * Enumerate windows. With <appName>, returns just that app's windows;
 * without, returns every window peekaboo can see. Each entry has the
 * CoreGraphics window id (wid), title, logical bounds, and an isMain flag
 * (true when the window is the app's main/key window).
 *
 * The peekaboo CLI shape is `peekaboo list windows --json [--app <name>]
 * --include-details bounds,ids`. We parse defensively because peekaboo's
 * JSON envelope has evolved across versions.
 */
export async function listWindows(appName?: string): Promise<WindowInfo[]> {
  const args = ["list", "windows", "--json-output"];
  if (appName) args.push("--app", appName);
  const { stdout } = await runPeekaboo(args);
  const trimmed = stdout.trim();
  if (!trimmed) return [];
  let parsed: any;
  try {
    parsed = JSON.parse(trimmed);
  } catch (e: any) {
    throw new Error(`[desktop] listWindows: peekaboo JSON parse failed: ${e?.message}\nraw: ${trimmed.slice(0, 400)}`);
  }
  if (parsed?.success === false) {
    const msg = parsed?.error?.message || JSON.stringify(parsed?.error || parsed);
    throw new Error(`[desktop] listWindows: peekaboo error: ${msg}`);
  }
  // Walk possible shapes: {windows: [...]} OR {data: {windows: [...]}} OR
  // [{...}] OR {applications:[{windows:[...]}]} (older builds).
  const candidates: any[] =
    (Array.isArray(parsed) && parsed) ||
    parsed?.windows ||
    parsed?.data?.windows ||
    (Array.isArray(parsed?.applications) ? parsed.applications.flatMap((a: any) => a?.windows || []) : null) ||
    [];
  return candidates.map((w: any): WindowInfo => {
    const rawBounds = w?.bounds || w?.frame || {};
    const b = Array.isArray(rawBounds)
      ? {
          x: rawBounds[0]?.[0] ?? rawBounds[0] ?? 0,
          y: rawBounds[0]?.[1] ?? rawBounds[1] ?? 0,
          w: rawBounds[1]?.[0] ?? rawBounds[2] ?? 0,
          h: rawBounds[1]?.[1] ?? rawBounds[3] ?? 0,
        }
      : rawBounds;
    return {
      wid: Number(w?.window_id ?? w?.wid ?? w?.id ?? 0),
      title: String(w?.title ?? w?.window_title ?? ""),
      bounds: {
        x: Number(b?.x ?? b?.origin?.x ?? 0),
        y: Number(b?.y ?? b?.origin?.y ?? 0),
        w: Number(b?.w ?? b?.width ?? b?.size?.width ?? 0),
        h: Number(b?.h ?? b?.height ?? b?.size?.height ?? 0),
      },
      isMain: Boolean(w?.is_main ?? w?.isMain ?? w?.main ?? false),
    };
  });
}

/**
 * Composite helper: optionally focus <appName>, optionally click into a
 * textfield at <clickCoords>, paste <text>, press return. Closes the gap
 * between "I want to drive my own app's composer" and "I have to chain
 * five primitives every time."
 *
 * opts.focusBefore (default: true) — call focusApp(appName) first.
 * opts.clickCoords — if set, clickAt(...) before pasting (use for apps
 *   that don't auto-focus their composer when the window is activated).
 *
 * Pairs well with snappy-chat's OpenUI composer: focus, click into the
 * `__input-wrapper` textarea, paste, return. Verify with captureWindow
 * after — actor ≠ auditor.
 */
export async function typeAndSubmit(
  appName: string,
  text: string,
  opts: { focusBefore?: boolean; clickCoords?: [number, number] } = {},
): Promise<void> {
  const focusBefore = opts.focusBefore !== false;
  if (focusBefore) await focusApp(appName);
  if (opts.clickCoords) {
    await clickAt(opts.clickCoords[0], opts.clickCoords[1]);
    await sleepMs(150);
  }
  await pasteText(text);
  await sleepMs(120);
  await pressKey("return");
}

// --- Vision-driven (Midscene) + WhatsApp + screenshot ---
// Extracted to ./desktop-vision.ts; imported into scope (the CLI subcommand
// bodies below call these by name) and re-exported here for back-compat.
import {
  runMidscene,
  runMidsceneAsync,
  screenshot,
  whatsappReadChats,
  whatsappReadChat,
  whatsappSendMessage,
} from "./desktop-vision.ts";
export {
  runMidscene,
  runMidsceneAsync,
  screenshot,
  whatsappReadChats,
  whatsappReadChat,
  whatsappSendMessage,
};

// Reserved for env-driven config (no current consumer; preserves the
// snappy-os env() contract pattern used elsewhere in state/lib/).
void env;

// --- CLI ---

if ((() => { try { return import.meta.url === `file://${realpathSync(process.argv[1])}`; } catch { return false; } })()) {
  (async () => {
    const [, , cmd, ...args] = process.argv;

    switch (cmd) {
      case "run": {
        const instruction = args.join(" ");
        if (!instruction) { console.error("Usage: api.ts run <instruction>"); process.exit(1); }
        console.log(runMidscene(instruction));
        break;
      }
      case "screenshot": {
        const path = screenshot();
        console.log(path);
        break;
      }
      case "focus": {
        const app = args.join(" ");
        if (!app) { console.error("Usage: api.ts focus <appName>"); process.exit(1); }
        await focusApp(app);
        console.log(`focused ${app}`);
        break;
      }
      case "capture-window": {
        if (args.length < 2) { console.error("Usage: api.ts capture-window <appName> <path>"); process.exit(1); }
        const path = args[args.length - 1];
        const app = args.slice(0, -1).join(" ");
        const out = await captureWindow(app, path);
        console.log(out);
        break;
      }
      case "capture-screen": {
        const path = args[0];
        if (!path) { console.error("Usage: api.ts capture-screen <path>"); process.exit(1); }
        console.log(await captureScreen(path));
        break;
      }
      case "paste": {
        const text = args.join(" ");
        if (!text) { console.error("Usage: api.ts paste <text>"); process.exit(1); }
        await pasteText(text);
        console.log(`pasted ${text.length} chars`);
        break;
      }
      case "press": {
        const key = args[0];
        if (!key) { console.error("Usage: api.ts press <key>"); process.exit(1); }
        await pressKey(key);
        console.log(`pressed ${key}`);
        break;
      }
      case "click": {
        if (args.length < 2) { console.error("Usage: api.ts click <x> <y>"); process.exit(1); }
        const x = Number(args[0]);
        const y = Number(args[1]);
        await clickAt(x, y);
        console.log(`clicked ${x},${y}`);
        break;
      }
      case "move": {
        if (args.length < 2) { console.error("Usage: api.ts move <x> <y> [durationMs]"); process.exit(1); }
        const x = Number(args[0]);
        const y = Number(args[1]);
        const durationMs = args[2] ? Number(args[2]) : undefined;
        await moveCursorSmooth(x, y, durationMs ? { durationMs } : {});
        console.log(`glided cursor to ${x},${y}`);
        break;
      }
      case "click-smooth": {
        if (args.length < 2) { console.error("Usage: api.ts click-smooth <x> <y> [durationMs]"); process.exit(1); }
        const x = Number(args[0]);
        const y = Number(args[1]);
        const durationMs = args[2] ? Number(args[2]) : undefined;
        await clickAtSmooth(x, y, durationMs ? { durationMs } : {});
        console.log(`glided + clicked ${x},${y}`);
        break;
      }
      case "cursor-pos": {
        const pos = await getCursorPosition();
        console.log(pos ? `${pos.x},${pos.y}` : "unavailable (cliclick missing)");
        break;
      }
      case "list-windows": {
        const app = args.join(" ") || undefined;
        const windows = await listWindows(app);
        console.log(JSON.stringify(windows, null, 2));
        break;
      }
      case "type-submit": {
        if (args.length < 2) { console.error("Usage: api.ts type-submit <appName> <text>"); process.exit(1); }
        const app = args[0];
        const text = args.slice(1).join(" ");
        await typeAndSubmit(app, text);
        console.log(`submitted to ${app}`);
        break;
      }
      case "wa-chats": {
        console.log(whatsappReadChats());
        break;
      }
      case "wa-read": {
        const contact = args.join(" ");
        if (!contact) { console.error("Usage: api.ts wa-read <contact>"); process.exit(1); }
        console.log(whatsappReadChat(contact));
        break;
      }
      case "wa-send": {
        if (args.length < 2) { console.error("Usage: api.ts wa-send <contact> <message>"); process.exit(1); }
        const contact = args[0];
        const message = args.slice(1).join(" ");
        console.log(whatsappSendMessage(contact, message));
        break;
      }
      default:
        console.log(
          "Usage: npx tsx api.ts [run|screenshot|focus|capture-window|capture-screen|paste|press|click|move|click-smooth|cursor-pos|list-windows|type-submit|wa-chats|wa-read|wa-send] ...",
        );
    }
  })();
}

scripts- helper scripts it can run

prose-only skill - 9 inline code blocks live in SKILL.md above (no state/bin/ sidecar yet).

how we check it- the checks, plus the last 10 runs

no recent runs logged - the eval contract is declared but nothing has been graded yet