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

echo "[$(date -u +%FT%TZ)] desktop: <what was missing>" >> state/log/loader-feedback.log

echo "[$(date -u +%FT%TZ)] desktop: <what was missing or fixed> [FIXED|LOGGED] action_kind=<kind>" >> state/log/loader-feedback.log

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.
 *
 * 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 list-windows SnappyChat
 *   npx tsx api.ts type-submit SnappyChat "open the agent panel"
 *
 * Or import as module:
 *   import { focusApp, captureWindow, pasteText, pressKey, clickAt,
 *            listWindows, typeAndSubmit, runMidscene, screenshot } from "./desktop.ts";
 */

import { execFile, execFileSync, execSync } from "child_process";
import { existsSync, readFileSync, readdirSync, realpathSync, unlinkSync } from "fs";
import { promisify } from "util";
import { env } from "./env.ts";
import { bridgeAvailable, bridgeExec } from "./bridge.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, `'\\''`)}'`;
}

// --- bridge routing ---
//
// When the openclaw helper daemon is available, route shell commands through
// it so they inherit its TCC grants (Screen Recording, Accessibility). When
// it is NOT available, fall back to direct execFile so the skill remains
// usable on machines without the bridge -- the local call may still succeed
// if the agent's own process tree happens to hold the relevant grants.
//
// The probe is cached inside bridge.ts (60s TTL), so this is one round-trip
// per minute, not per call.
async function runShell(command: string, opts: { timeout?: number } = {}): Promise<{ stdout: string; stderr: string }> {
  if (await bridgeAvailable()) {
    const r = await bridgeExec(command, opts);
    if (!r.ok) {
      throw new Error(`[desktop] bridge exec failed: ${r.error ?? "unknown"}${r.stderr ? ` -- ${r.stderr}` : ""}`);
    }
    return { stdout: r.output ?? "", stderr: "" };
  }
  // Local fallback: spawn /bin/sh -c <command>. Same shape as the bridge,
  // different process tree. Will fail with TCC errors when those bite.
  const { stdout, stderr } = await execFileP("/bin/sh", ["-c", command], { maxBuffer: 16 * 1024 * 1024 });
  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;
}

async function runPeekaboo(args: string[]): Promise<{ stdout: string; stderr: string }> {
  const bin = requirePeekaboo();
  // Compose a single shell-safe command so the bridge can run it through its
  // shell (the daemon's /exec endpoint takes one string, not an argv array).
  // Local fallback path also goes through /bin/sh -c via runShell.
  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> {
  const args = ["image", "--mode", "window", "--app", appName, "--path", path];
  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}`]);
}

/**
 * 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", "--include-details", "bounds,ids"];
  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 b = w?.bounds || w?.frame || {};
    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) ---

/** Run a Midscene vision instruction via Terminal routing (required for Screen Recording). */
export function runMidscene(instruction: string): string {
  const runId = Date.now().toString();
  const scriptPath = `/tmp/midscene-cmd-${runId}.sh`;
  const outPath = `/tmp/midscene-out-${runId}.txt`;
  const donePath = `/tmp/midscene-done-${runId}`;

  const escaped = instruction.replace(/"/g, '\\"');
  const script = `#!/bin/bash
source ~/.midscene-env
npx -y @midscene/computer@1 act --prompt "${escaped}" > ${outPath} 2>&1
echo "EXIT_CODE=$?" >> ${outPath}
touch ${donePath}
`;

  execSync(`cat > ${scriptPath} << 'SCRIPT_EOF'\n${script}SCRIPT_EOF`, { encoding: "utf-8" });
  execSync(`chmod +x ${scriptPath}`);
  execSync(`osascript -e 'tell application "Terminal" to do script "${scriptPath}"'`);

  // Poll for completion
  const maxWait = 60_000;
  const start = Date.now();
  while (!existsSync(donePath) && Date.now() - start < maxWait) {
    execSync("sleep 2");
  }

  let output = "";
  if (existsSync(outPath)) {
    output = readFileSync(outPath, "utf-8");
  } else {
    output = "ERROR: Midscene timed out after 60s";
  }

  // Cleanup
  for (const f of [scriptPath, outPath, donePath]) {
    if (existsSync(f)) unlinkSync(f);
  }

  return output.trim();
}

/**
 * Take a full-display screenshot and return the file path.
 *
 * Delegates to captureScreen() so callers don't have two parallel APIs.
 * Kept synchronous-return-shaped for back-compat with existing consumers
 * (whatsappReadChats / whatsappReadChat) by blocking on the async call
 * via execSync glue. New code should call captureScreen() directly.
 */
export function screenshot(): string {
  const runId = Date.now().toString();
  const path = `/tmp/screenshot-${runId}.png`;
  // Inline the screencapture invocation here (sync) so this function stays
  // string-returning. The async captureScreen() is the canonical API; this
  // is the back-compat shim.
  try {
    execFileSync("/usr/sbin/screencapture", ["-x", path]);
  } catch (e: any) {
    console.error(`[desktop] screenshot failed: ${String(e?.message || e).trim()}`);
    throw e;
  }
  if (!existsSync(path)) {
    throw new Error("[desktop] screenshot: screencapture produced no file (TCC denied?)");
  }
  return path;
}

/** Helper: activate WhatsApp.app and wait for it to be frontmost. */
function activateWhatsApp(): void {
  execSync(`osascript -e 'tell application "WhatsApp" to activate'`);
  execSync("sleep 2");
}

/** Helper: run a Midscene query (read-only vision extraction, no clicks). */
function queryMidscene(question: string): string {
  const runId = Date.now().toString();
  const scriptPath = `/tmp/midscene-cmd-${runId}.sh`;
  const outPath = `/tmp/midscene-out-${runId}.txt`;
  const donePath = `/tmp/midscene-done-${runId}`;

  const escaped = question.replace(/"/g, '\\"');
  const script = `#!/bin/bash
source ~/.midscene-env
osascript -e 'tell application "WhatsApp" to activate'
sleep 1
npx -y @midscene/computer@1 query --prompt "${escaped}" > ${outPath} 2>&1
echo "EXIT_CODE=$?" >> ${outPath}
touch ${donePath}
`;

  execSync(`cat > ${scriptPath} << 'SCRIPT_EOF'\n${script}SCRIPT_EOF`, { encoding: "utf-8" });
  execSync(`chmod +x ${scriptPath}`);
  execSync(`osascript -e 'tell application "Terminal" to do script "${scriptPath}"'`);

  const maxWait = 60_000;
  const start = Date.now();
  while (!existsSync(donePath) && Date.now() - start < maxWait) {
    execSync("sleep 2");
  }

  let output = "";
  if (existsSync(outPath)) {
    output = readFileSync(outPath, "utf-8");
  } else {
    output = "ERROR: Midscene query timed out after 60s";
  }

  for (const f of [scriptPath, outPath, donePath]) {
    if (existsSync(f)) unlinkSync(f);
  }

  return output.trim();
}

/**
 * Open WhatsApp.app, screenshot the chat list, extract chat names + unread badges via Midscene.
 * Returns the raw Midscene vision output describing visible chats.
 */
export function whatsappReadChats(): string {
  activateWhatsApp();
  const screenshotPath = screenshot();
  const result = queryMidscene(
    "List every chat visible in the WhatsApp sidebar. For each chat return: contact name, last message preview, timestamp, and whether it has an unread badge (and the count if visible). Return as a structured list."
  );
  return `screenshot: ${screenshotPath}\n\n${result}`;
}

/**
 * Click into a specific WhatsApp chat and extract recent messages.
 * @param contactName - The name of the contact or group to open.
 */
export function whatsappReadChat(contactName: string): string {
  activateWhatsApp();
  // Use Cmd+F to search for the contact, more reliable than vision-clicking the sidebar
  const escaped = contactName.replace(/"/g, '\\"');
  runMidscene(`Click on the search field at the top of WhatsApp, type "${escaped}", then click on the first matching chat result`);
  execSync("sleep 2");
  // Re-activate WhatsApp after Terminal steals focus from runMidscene
  activateWhatsApp();
  const screenshotPath = screenshot();
  const result = queryMidscene(
    `Read the currently open WhatsApp chat. Extract the most recent messages visible on screen. For each message return: sender name, message text, and timestamp. Return as a structured list, most recent last.`
  );
  return `screenshot: ${screenshotPath}\n\n${result}`;
}

/**
 * Open a WhatsApp chat and send a message.
 * @param contactName - The name of the contact or group.
 * @param text - The message text to send.
 */
export function whatsappSendMessage(contactName: string, text: string): string {
  activateWhatsApp();
  // Search and open the chat
  const escapedName = contactName.replace(/"/g, '\\"');
  runMidscene(`Click on the search field at the top of WhatsApp, type "${escapedName}", then click on the first matching chat result`);
  execSync("sleep 2");
  // Re-activate WhatsApp and type the message via AppleScript (more reliable than Midscene typing)
  activateWhatsApp();
  // Click the message input field via Midscene
  runMidscene("Click on the message input field at the bottom of the chat");
  execSync("sleep 1");
  // Re-activate and type via AppleScript keystroke
  execSync(`osascript -e 'tell application "WhatsApp" to activate'`);
  execSync("sleep 0.5");
  // Use clipboard to handle special characters reliably
  const escapedText = text.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
  execSync(`osascript -e 'set the clipboard to "${escapedText}"' -e 'tell application "System Events" to keystroke "v" using command down'`);
  execSync("sleep 0.5");
  // Press Enter to send
  execSync(`osascript -e 'tell application "System Events" to key code 36'`);
  execSync("sleep 1");
  activateWhatsApp();
  const screenshotPath = screenshot();
  return `sent to ${contactName}: "${text}"\nscreenshot: ${screenshotPath}`;
}

// 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 "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|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