demobite 1.13.1 → 1.14.1

package/launcher/index.mjs

@@ -116,8 +116,7 @@ const chromePaths = [
 const haveChrome = chromePaths.some((p) => fs.existsSync(p)) || hasBin("google-chrome") || hasBin("google-chrome-stable");
 if (haveChrome) ok("Google Chrome (films with the real browser)");
 else console.log("  · Google Chrome not found — installing Playwright's Chromium for the recorder");
-if (hasBin("claude")) ok("Claude Code (drives the recorder; MCP registers automatically)");
-else warn("Claude Code not found — using Cursor or Codex? They drive the recorder too; MCP setup prints below");
+if (hasBin("claude")) ok("Claude Code found (optional: `--engine=claude` plans demos with it, on your own plan)");
 
 // ── 2. Install / update the skill ──────────────────────────────────────────
 fs.mkdirSync(dest, { recursive: true });
@@ -215,13 +214,24 @@ if (arg === "listen") {
   // speak to it. The model that FILMS is ours (JOB_MODEL), passed per job: the
   // output quality is DemoBites' to defend, never a hidden knob on the machine.
   const JOB_MODEL = process.env.DEMOBITES_JOB_MODEL || "sonnet";
+  // THE BUILT-IN AGENT (1.14.0, founder 2026-10-15): demos are planned by DemoBites' own planner
+  // (scripts/plan.mjs ↔ PUT /api/recorder/agent) and filmed by the camera scripts; no coding agent
+  // needed on the machine. Claude Code stays an option: `--engine=claude` (or DEMOBITES_ENGINE=claude)
+  // plans with it instead, on the person's own plan, and their code never passes through DemoBites.
+  const engine = (argvRest.find((a) => a.startsWith("--engine=")) || "").slice(9) || process.env.DEMOBITES_ENGINE || "builtin";
+  const claudeVersion = (() => {
+    if (!agentBin) return null;
+    const v = spawnSync(agentBin, ["--version"], { encoding: "utf8", timeout: 8000 });
+    return v.status === 0 ? (v.stdout.trim().match(/\d+\.\d+(?:\.\d+)?/) || [null])[0] : null;
+  })();
   const agentInfo = (() => {
-    if (!agentBin) return { agent: null, agent_version: null, model: null, effort: null, job_model: null };
+    if (engine !== "claude") return { agent: "DemoBites agent", agent_version: pkg.version, engine: "builtin", claude_version: claudeVersion, code_sharing: !process.env.DEMOBITES_NO_CODE, model: null, effort: null, job_model: JOB_MODEL };
+    if (!agentBin) return { agent: null, agent_version: null, engine: "claude", model: null, effort: null, job_model: null };
     const v = spawnSync(agentBin, ["--version"], { encoding: "utf8", timeout: 8000 });
     const version = v.status === 0 ? (v.stdout.trim().match(/\d+\.\d+(?:\.\d+)?/) || [null])[0] : null;
     let settings = {};
     try { settings = JSON.parse(fs.readFileSync(path.join(os.homedir(), ".claude", "settings.json"), "utf8")); } catch { /* defaults */ }
-    return { agent: "Claude Code", agent_version: version, model: typeof settings.model === "string" ? settings.model : null, effort: typeof settings.effortLevel === "string" ? settings.effortLevel : (typeof settings.effort === "string" ? settings.effort : null), job_model: JOB_MODEL };
+    return { agent: "Claude Code", agent_version: version, engine: "claude", model: typeof settings.model === "string" ? settings.model : null, effort: typeof settings.effortLevel === "string" ? settings.effortLevel : (typeof settings.effort === "string" ? settings.effort : null), job_model: JOB_MODEL };
   })();
   // The repo this listener was started in (the Code signal on the rail): the
   // git remote's owner/name, or null when the folder is not a repo.
@@ -247,7 +257,7 @@ if (arg === "listen") {
   const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
   console.log(`\n  Listening as "${name}" for ${cfg.workspace?.name ?? "your workspace"} on ${base.replace(/^https?:\/\//, "")}.`);
-  console.log(`  Ask for a demo in the app (Create → Agentic Capture). ${agentBin ? `Claude Code${agentInfo.agent_version ? " " + agentInfo.agent_version : ""} found; demos film on ${JOB_MODEL} unless you pick another model in the app.` : "! Claude Code was not found on this machine — install it and sign in, it does the thinking."}`);
+  console.log(`  Ask for a demo in the app (Create → Agentic Capture). ${engine === "claude" ? (agentBin ? `Claude Code${agentInfo.agent_version ? " " + agentInfo.agent_version : ""} plans the demos, on your own plan; they film on ${JOB_MODEL} unless you pick another model in the app.` : "! --engine=claude, but Claude Code was not found on this machine.") : `Demos are planned by the DemoBites agent on ${JOB_MODEL} (pick another model in the app)${process.env.DEMOBITES_NO_CODE ? "; code sharing is off" : repo ? "; the files it reads from this project are logged in each take" : ""}.`}`);
   // The one thing the person must know, boxed (founder 2026-10-15): this
   // window is the machine's side of every recording.
   console.log(`
@@ -256,7 +266,7 @@ if (arg === "listen") {
   │   LEAVE THIS WINDOW OPEN                                 │
   │                                                          │
   │   It is your machine's side of every recording:          │
-  │   the camera, the sign-ins, the coding agent run here.   │
+  │   the camera, the sign-ins and the planning run here.    │
   │   Closing it, or Ctrl-C, stops the listening.            │
   │                                                          │
   └──────────────────────────────────────────────────────────┘
@@ -316,8 +326,25 @@ if (arg === "listen") {
     // Alive while filming (1.13.1): a heartbeat every 5 s so the rail never shows this machine
     // offline mid-take (the gap after the last step used to do exactly that).
     const heartbeat = setInterval(() => { void api({ action: "checkin", machine_id: listen.machine_id, name, readiness: readiness(), busy: true }); }, 5000);
-    console.log(`\n  ▶ Job ${job.id}: ${job.brief.slice(0, 100)}${job.brief.length > 100 ? "…" : ""}  (filming on ${model})`);
-    if (!agentBin) { await event(job.id, "failed", { message: "Claude Code is not installed on this machine" }); return; }
+    console.log(`\n  ▶ Job ${job.id}: ${job.brief.slice(0, 100)}${job.brief.length > 100 ? "…" : ""}  (${engine === "claude" ? "Claude Code" : "DemoBites agent"} on ${model})`);
+    if (engine !== "claude") {
+      // The built-in agent: plan.mjs plans with the server's planner, films with the camera scripts.
+      await event(job.id, "started", { machine: name });
+      const takeDir = path.join(process.cwd(), ".recorder", "takes", job.id);
+      fs.mkdirSync(takeDir, { recursive: true });
+      fs.writeFileSync(path.join(takeDir, "job.json"), JSON.stringify({ id: job.id, brief: job.brief, url: job.url ?? null, model, review_storyboard: job.review_storyboard !== false }, null, 2) + "\n");
+      // Spawned async (1.14.1): a spawnSync here blocked the event loop, so the 5 s heartbeat never fired
+      // during a take and the rail called the machine offline mid-recording (founder 2026-10-15 17:39).
+      const child = (await import("node:child_process")).spawn("node", [path.join(dest, "scripts", "plan.mjs"), takeDir], { cwd: process.cwd(), stdio: "inherit", env: { ...process.env, RECORDER_JOB: job.id, RECORDER_BASE: base, RECORDER_LISTEN: "1" } });
+      const code = await new Promise((resolve) => child.on("close", resolve));
+      const st = await api({ action: "poll", job_id: job.id });
+      if (st && !["ready", "failed", "cancelled"].includes(st.status)) await event(job.id, "failed", { message: code === 0 ? "The demo did not come through — try again" : `The take stopped (exit ${code})` });
+      clearInterval(heartbeat);
+      console.log(`  ■ Job ${job.id} ${st?.status ?? "ended"}.\n`);
+      waitOn();
+      return;
+    }
+    if (!agentBin) { await event(job.id, "failed", { message: "Claude Code is not installed on this machine" }); clearInterval(heartbeat); waitOn(); return; }
     await event(job.id, "started", { machine: name });
     const prompt = [
       "Film a demo with the agentic-recorder skill. Read ~/.claude/skills/agentic-recorder/SKILL.md first and follow it exactly, in LISTENING MODE (its section \"Listening mode\"): the person is watching in the DemoBites app, not here — never ask anything in this conversation; the scripts carry every question to the app and bring the answer back.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "demobite",
-  "version": "1.13.1",
+  "version": "1.14.1",
   "description": "The DemoBites agentic recorder — you prompt, it films a real browser, and DemoBites turns the take into an editable demo bite.",
   "bin": {
     "demobite": "launcher/index.mjs"

package/skill/scripts/peek.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+// PEEK (the built-in agent, 2026-10-15): one screenshot of an address in the
+// camera's own browser (the recorder profile, so a saved sign-in counts), no
+// video, no window. The planner looks at it when words alone are not enough.
+//
+//   node scripts/peek.mjs <url> <out.jpg>
+//   RESULT { title, url }
+import path from "node:path";
+
+const [url, out] = process.argv.slice(2);
+if (!url || !out) { console.error("Usage: node scripts/peek.mjs <url> <out.jpg>"); process.exit(2); }
+const { chromium } = await import("playwright");
+const profileDir = process.env.RECORDER_PROFILE || path.resolve(process.cwd(), ".recorder", "profile");
+const launchOpts = {
+  headless: true,
+  viewport: { width: 1280, height: 800 },
+  args: ["--force-color-profile=srgb", "--disable-blink-features=AutomationControlled"],
+  ignoreDefaultArgs: ["--enable-automation"],
+};
+let ctx;
+try { ctx = await chromium.launchPersistentContext(profileDir, { ...launchOpts, channel: "chrome" }); }
+catch { ctx = await chromium.launchPersistentContext(profileDir, launchOpts); }
+const page = ctx.pages()[0] ?? (await ctx.newPage());
+try {
+  await page.goto(url, { waitUntil: "networkidle", timeout: 45000 }).catch(() => page.goto(url, { waitUntil: "load", timeout: 45000 }));
+  await page.waitForTimeout(2500);
+  await page.screenshot({ path: out, type: "jpeg", quality: 55 });
+  console.log("RESULT " + JSON.stringify({ title: (await page.title().catch(() => "")).slice(0, 120), url: page.url() }));
+} catch (e) {
+  console.error(String(e.message).split("\n")[0].slice(0, 160));
+  process.exitCode = 1;
+}
+await ctx.close();

package/skill/scripts/plan.mjs

@@ -0,0 +1,270 @@
+#!/usr/bin/env node
+// THE BUILT-IN AGENT (founder 2026-10-15: "I don't want to say to the customer,
+// you need to have Claude Code on your machine"). A demo asked for in the app
+// is planned by DemoBites' own planner (PUT <base>/api/recorder/agent, on
+// DemoBites' bill) and filmed by the camera scripts beside this file. No
+// coding agent on the machine. This script is the loop between the two:
+//
+//   node scripts/plan.mjs <takeDir>            (RECORDER_JOB, RECORDER_BASE set by `npx demobite listen`;
+//                                               <takeDir>/job.json = { id, brief, url, model, review_storyboard })
+//
+// What runs here, on the machine: the sign-in window (signin.mjs), the words
+// of each screen (vocab.mjs), screenshots and the dry run (peek.mjs,
+// probe.mjs), reading the project's files when this folder is the app's
+// repository and sharing is on (DEMOBITES_NO_CODE=1 turns it off), the
+// storyboard box (storyboard.mjs await), and the whole filming pipeline
+// (cleanup --prep, record, cleanup, trim, calibrate, manifest, upload). What
+// runs on the server: the model, and nothing else. Every file the planner
+// reads is logged on the take (<takeDir>/code-shared.log) so the person can
+// see exactly what left the machine.
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { listening, postEvent } from "./listen-event.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const dir = process.argv[2];
+if (!dir) { console.error("Usage: node scripts/plan.mjs <takeDir>"); process.exit(2); }
+if (!listening) { console.error("plan.mjs runs under `npx demobite listen` (RECORDER_JOB and RECORDER_BASE)."); process.exit(2); }
+fs.mkdirSync(dir, { recursive: true });
+const job = JSON.parse(fs.readFileSync(path.join(dir, "job.json"), "utf8"));
+const base = process.env.RECORDER_BASE.replace(/\/+$/, "");
+const cfg = (() => { try { return JSON.parse(fs.readFileSync(path.resolve(".recorder", "config.json"), "utf8")); } catch { return {}; } })();
+if (!cfg.api_key) { console.error("Not connected: .recorder/config.json has no key."); process.exit(1); }
+const say = (t) => { console.log(`· ${t}`); void postEvent("agent", { text: t }); };
+const script = (name) => path.join(here, name);
+const run = (name, args, opts = {}) => spawnSync("node", [script(name), ...args], { cwd: process.cwd(), encoding: "utf8", env: process.env, maxBuffer: 64 * 1024 * 1024, ...opts });
+
+// ── The address and the sign-in ──────────────────────────────────────────
+const ensureSignin = async (url) => {
+  if (!url) return;
+  const check = run("signin.mjs", ["--check", url]);
+  if (check.status === 0) return;
+  // Not in the ledger yet: look first, headless. An open page, or one the profile is already signed
+  // into, needs no window (the window is for a wall, and only for a wall).
+  const look = run("look.mjs", [url]);
+  const last = (look.stdout || "").trim().split("\n").filter((l) => l.startsWith("RESULT ")).pop();
+  let verdict = null; try { verdict = JSON.parse(last.slice(7)); } catch { /* none */ }
+  if (verdict && (verdict.access === "open" || verdict.access === "signed")) return;
+  console.log(`  Sign-in needed at ${new URL(url).origin}; opening the Chrome window.`);
+  const r = spawnSync("node", [script("signin.mjs"), url], { cwd: process.cwd(), stdio: "inherit", env: process.env });
+  if (r.status !== 0) { await postEvent("failed", { message: "Nobody signed in, so the demo did not start" }); process.exit(1); }
+};
+const startUrl = job.url || cfg.url || null;
+if (startUrl) await ensureSignin(startUrl);
+
+// ── What the planner works from ──────────────────────────────────────────
+say("Reading the workspace rules…");
+run("rules.mjs", [dir]);
+const rules = (() => { try { return JSON.parse(fs.readFileSync(path.resolve(".recorder", "rules.json"), "utf8")); } catch { return { version: 0, lines: [] }; } })();
+
+const codeOn = !process.env.DEMOBITES_NO_CODE && spawnSync("git", ["rev-parse", "--is-inside-work-tree"], { encoding: "utf8" }).status === 0;
+const SECRET_RE = /(^|\/)(\.env(\..*)?|.*\.(pem|key|p12|pfx|crt)|.*secret.*|.*credential.*|\.recorder\/.*|node_modules\/.*|\.git\/.*|.*\.lock|package-lock\.json|yarn\.lock|pnpm-lock\.yaml)$/i;
+const UI_RE = /(^|\/)(app|pages|routes|src|components|views|screens|navigation|nav|layouts?|lib\/(nav|routes|menu))(\/|$)|(^|\/)(route|router|routes|nav|navigation|sidebar|menu|layout|page)\.[jt]sx?$|\/page\.[jt]sx?$|\/layout\.[jt]sx?$|\/route\.[jt]s$/i;
+const listFiles = () => {
+  if (!codeOn) return "(no repository here, or code sharing is off)";
+  const r = spawnSync("git", ["ls-files"], { encoding: "utf8", maxBuffer: 32 * 1024 * 1024 });
+  if (r.status !== 0) return "(no repository here)";
+  const all = r.stdout.split("\n").filter(Boolean).filter((f) => !SECRET_RE.test(f) && /\.(tsx?|jsx?|vue|svelte|html|mdx?)$/i.test(f));
+  const ui = all.filter((f) => UI_RE.test(f));
+  const picked = (ui.length ? ui : all).slice(0, 400);
+  return `${picked.join("\n")}${all.length > picked.length ? `\n… ${all.length - picked.length} more files not listed` : ""}`;
+};
+let reads = 0;
+const shared = [];
+const readFile = (rel) => {
+  if (!codeOn) return "Code sharing is off on this machine.";
+  if (typeof rel !== "string" || !rel.trim()) return "path required";
+  const abs = path.resolve(process.cwd(), rel);
+  if (!abs.startsWith(process.cwd() + path.sep)) return "Outside the project.";
+  const r = path.relative(process.cwd(), abs);
+  if (SECRET_RE.test(r)) return "Not that file.";
+  if (reads >= 10) return "No more reads for this storyboard.";
+  let text;
+  try { text = fs.readFileSync(abs, "utf8"); } catch { return "No such file."; }
+  reads++;
+  shared.push(r);
+  fs.appendFileSync(path.join(dir, "code-shared.log"), `${new Date().toISOString()} ${r} (${Math.min(text.length, 12000)} chars)\n`);
+  return text.length > 12000 ? text.slice(0, 12000) + "\n… (cut at 12 KB)" : text;
+};
+const harvest = (urls) => {
+  const ok = (Array.isArray(urls) ? urls : []).filter((u) => /^https?:\/\//.test(String(u))).slice(0, 4);
+  if (!ok.length) return "urls required";
+  const r = run("vocab.mjs", [dir, ...ok]);
+  const out = `${r.stdout || ""}${r.stderr ? `\n${r.stderr}` : ""}`.trim();
+  return out.length > 12000 ? out.slice(0, 12000) + "\n… (cut)" : out || "(nothing harvested)";
+};
+let peeks = 0;
+const screenshot = (url) => {
+  if (!/^https?:\/\//.test(String(url))) return [{ type: "text", text: "url required" }];
+  const file = path.join(dir, `peek-${++peeks}.jpg`);
+  const r = run("peek.mjs", [url, file]);
+  const last = (r.stdout || "").trim().split("\n").filter((l) => l.startsWith("RESULT ")).pop();
+  let meta = null; try { meta = JSON.parse(last.slice(7)); } catch { /* none */ }
+  if (!meta || !fs.existsSync(file)) return [{ type: "text", text: `Could not open ${url}: ${(r.stderr || r.stdout || "").trim().split("\n").pop() || "no answer"}` }];
+  return [
+    { type: "text", text: `${meta.url} — "${meta.title}"` },
+    { type: "image", source: { type: "base64", media_type: "image/jpeg", data: fs.readFileSync(file).toString("base64") } },
+  ];
+};
+const probe = (sb) => {
+  if (!sb || !Array.isArray(sb.steps)) return "storyboard with steps[] required";
+  const file = path.join(dir, "probe.json");
+  fs.writeFileSync(file, JSON.stringify(sb, null, 2) + "\n");
+  const r = run("probe.mjs", [file]);
+  const out = `${r.stdout || ""}${r.stderr ? `\n${r.stderr}` : ""}`.trim();
+  return out.length > 12000 ? out.slice(0, 12000) + "\n… (cut)" : out || "(no report)";
+};
+const ACTIONS = new Set(["goto", "settle", "scroll", "click", "hover", "type", "expect"]);
+const validate = (sb) => {
+  if (!sb || typeof sb !== "object") return "storyboard required";
+  if (!Array.isArray(sb.steps) || !sb.steps.length) return "steps[] is empty";
+  if (sb.steps[0].action !== "goto" || !sb.steps[0].url) return "the first step must be a goto with a url";
+  for (const [i, s] of sb.steps.entries()) {
+    const at = `step ${i + 1}`;
+    if (!ACTIONS.has(s.action)) return `${at}: unknown action ${JSON.stringify(s.action)}`;
+    if ((s.action === "click" || s.action === "hover" || s.action === "expect") && !s.selector) return `${at}: ${s.action} needs selector`;
+    if (s.action === "type" && (!s.selector || typeof s.text !== "string")) return `${at}: type needs selector and text`;
+    if (s.action === "scroll" && typeof s.dy !== "number") return `${at}: scroll needs numeric dy`;
+    if (s.frame !== undefined && s.frame !== "close" && s.frame !== "wide") return `${at}: frame must be close or wide`;
+  }
+  if (sb.steps.length > 14) return "more than 14 steps; 6 to 10 is the law";
+  return null;
+};
+
+// ── The loop with the planner ────────────────────────────────────────────
+const relay = async (messages) => {
+  for (let attempt = 0; attempt < 3; attempt++) {
+    let res;
+    try {
+      res = await fetch(`${base}/api/recorder/agent`, { method: "PUT", headers: { "Content-Type": "application/json", Authorization: `Bearer ${cfg.api_key}` }, body: JSON.stringify({ job_id: job.id, messages }) });
+    } catch (e) { if (attempt === 2) throw e; await new Promise((r) => setTimeout(r, 3000)); continue; }
+    if (res.ok) return res.json();
+    const body = await res.json().catch(() => ({}));
+    if (res.status === 429 || res.status === 409 || res.status === 404 || res.status === 401) throw new Error(body.error || `planner ${res.status}`);
+    if (attempt === 2) throw new Error(body.error || `planner ${res.status}`);
+    await new Promise((r) => setTimeout(r, 3000));
+  }
+  throw new Error("planner unreachable");
+};
+// Only the newest screenshots stay in the conversation; older ones become a note (the request body has a ceiling).
+const prune = (messages) => {
+  let seen = 0;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const c = messages[i].content;
+    if (!Array.isArray(c)) continue;
+    for (const b of c) {
+      if (b.type !== "tool_result" || !Array.isArray(b.content)) continue;
+      for (let k = 0; k < b.content.length; k++) {
+        if (b.content[k].type !== "image") continue;
+        if (++seen > 2) b.content[k] = { type: "text", text: "(a screenshot shown earlier)" };
+      }
+    }
+  }
+};
+
+const firstMessage = () => {
+  const vocab = startUrl ? harvest([startUrl]) : "(no starting address was given: find it from the brief, the code or by looking)";
+  const parts = [
+    `## The brief\n${job.brief}`,
+    `## Starting address\n${startUrl || "(none given)"}`,
+    `## The app's words on the starting screen\n${vocab}`,
+    `## Workspace rules (version ${rules.version || 0})\n${rules.lines?.length ? rules.lines.map((l, i) => `${i + 1}. ${l}`).join("\n") : "(none)"}`,
+    `## The project's files${codeOn ? " (this machine sits in the app's repository; read_file is on)" : " (no code here)"}\n${listFiles()}`,
+    `Write the storyboard, probe it, fix it, probe again, then submit_storyboard.`,
+  ];
+  return parts.join("\n\n");
+};
+
+let storyboard = null;
+let creates = "";
+const messages = [{ role: "user", content: [{ type: "text", text: firstMessage() }] }];
+const plan = async () => {
+  say("Writing the storyboard…");
+  storyboard = null;
+  let nudged = false;
+  for (let turn = 0; turn < 40; turn++) {
+    prune(messages);
+    const res = await relay(messages);
+    const content = Array.isArray(res.content) ? res.content : [];
+    messages.push({ role: "assistant", content });
+    for (const b of content) if (b.type === "text" && b.text?.trim()) console.log(`  ${b.text.trim().split("\n")[0].slice(0, 140)}`);
+    const uses = content.filter((b) => b.type === "tool_use");
+    if (!uses.length) {
+      if (storyboard) return;
+      if (nudged) throw new Error("The planner stopped without a storyboard");
+      nudged = true;
+      messages.push({ role: "user", content: [{ type: "text", text: "Hand in the storyboard with submit_storyboard (after a probe that passed)." }] });
+      continue;
+    }
+    const results = [];
+    for (const u of uses) {
+      const input = u.input || {};
+      let out;
+      try {
+        if (u.name === "list_files") out = listFiles();
+        else if (u.name === "read_file") out = readFile(input.path);
+        else if (u.name === "harvest_words") { console.log(`  harvesting ${(input.urls || []).join(", ")}`); out = harvest(input.urls); }
+        else if (u.name === "screenshot") { console.log(`  looking at ${input.url}`); out = screenshot(input.url); }
+        else if (u.name === "probe") { console.log("  dry run…"); out = probe(input.storyboard); }
+        else if (u.name === "submit_storyboard") {
+          const bad = validate(input.storyboard);
+          if (bad) out = `Not accepted: ${bad}`;
+          else { storyboard = input.storyboard; creates = typeof input.creates === "string" ? input.creates : ""; out = "Accepted."; }
+        } else out = `Unknown tool ${u.name}`;
+      } catch (e) { out = `Tool failed: ${e.message}`; }
+      results.push({ type: "tool_result", tool_use_id: u.id, content: typeof out === "string" ? [{ type: "text", text: out }] : out });
+    }
+    messages.push({ role: "user", content: results });
+    if (storyboard) return;
+  }
+  throw new Error("The planner ran out of turns");
+};
+
+try {
+  for (let revision = 0; revision < 4; revision++) {
+    await plan();
+    if (!storyboard.title) storyboard.title = job.brief.slice(0, 60);
+    if (!storyboard.app) storyboard.app = cfg.app || (startUrl ? new URL(startUrl).hostname : "Demo");
+    if (rules.version) storyboard.rulesVersion = rules.version;
+    const sbFile = path.join(dir, "storyboard.json");
+    fs.writeFileSync(sbFile, JSON.stringify(storyboard, null, 2) + "\n");
+    if (shared.length) console.log(`  Files the planner read: ${shared.join(", ")}`);
+    // The sign-in for the storyboard's own address, when it differs from the start.
+    const sbUrl = storyboard.steps?.[0]?.url || storyboard.url;
+    if (sbUrl && (!startUrl || new URL(sbUrl).origin !== new URL(startUrl).origin)) await ensureSignin(sbUrl);
+    // The box goes to the app; the person's word comes back.
+    const w = run("storyboard.mjs", ["await", sbFile]);
+    const answer = (w.stdout || "").trim().split("\n").pop() || "";
+    if (answer === "cancelled" || w.status === 2) { console.log("  The person cancelled."); process.exit(0); }
+    if (answer.startsWith("change:")) {
+      const note = answer.slice(7).trim();
+      say("Changing the storyboard…");
+      messages.push({ role: "user", content: [{ type: "text", text: `The person asked for a change: "${note}". Revise the storyboard, probe it, and submit_storyboard again.` }] });
+      continue;
+    }
+    break;
+  }
+} catch (e) {
+  console.error(`  ! ${e.message}`);
+  await postEvent("failed", { message: `The storyboard could not be written: ${String(e.message).slice(0, 160)}` });
+  process.exit(1);
+}
+
+// ── The take ─────────────────────────────────────────────────────────────
+const sbFile = path.join(dir, "storyboard.json");
+const step = async (name, args, what) => {
+  const r = spawnSync("node", [script(name), ...args], { cwd: process.cwd(), stdio: "inherit", env: process.env });
+  if (r.status !== 0) { console.error(`  ! ${name} failed (exit ${r.status})`); await postEvent("failed", { message: `${what} did not finish` }); process.exit(1); }
+};
+const sb = JSON.parse(fs.readFileSync(sbFile, "utf8"));
+if (Array.isArray(sb.prep) && sb.prep.length) await step("cleanup.mjs", [dir, "--prep"], "Preparing the data");
+await step("record.mjs", [dir, sbFile], "Filming");
+if (Array.isArray(sb.cleanup) && sb.cleanup.length) await step("cleanup.mjs", [dir], "Putting the data back");
+await step("trim.mjs", [dir], "Trimming the take");
+await step("calibrate.mjs", [dir], "Measuring the take");
+await step("manifest.mjs", [dir], "Packing the take");
+await step("upload.mjs", [dir, "--no-open"], "Delivering the take");
+if (creates) console.log(`  ${creates}`);
+process.exit(0);

package/skill/scripts/probe.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+// PROBE (the built-in agent, 2026-10-15): the headless dry run of a
+// storyboard, the way the skill's Phase 4 asks for it. Every camera step is
+// performed in order on the recorder profile without video; a step marked
+// pointed is only hovered (an irreversible action is never pressed). Each
+// selector is reported resolved or not, by the visible-instance rule of
+// record.mjs (first visible match whose top clears minY). When one fails, the
+// report lists the visible controls on that page so the planner can pick the
+// real one, and the run stops there.
+//
+//   node scripts/probe.mjs <storyboard.json>
+import fs from "node:fs";
+import path from "node:path";
+
+const file = process.argv[2];
+if (!file) { console.error("Usage: node scripts/probe.mjs <storyboard.json>"); process.exit(2); }
+const sb = JSON.parse(fs.readFileSync(file, "utf8"));
+const steps = Array.isArray(sb.steps) ? sb.steps : [];
+const { chromium } = await import("playwright");
+const profileDir = process.env.RECORDER_PROFILE || path.resolve(process.cwd(), ".recorder", "profile");
+const launchOpts = {
+  headless: true,
+  viewport: { width: 1920, height: 1080 },
+  args: ["--force-color-profile=srgb", "--disable-blink-features=AutomationControlled"],
+  ignoreDefaultArgs: ["--enable-automation"],
+};
+let ctx;
+try { ctx = await chromium.launchPersistentContext(profileDir, { ...launchOpts, channel: "chrome" }); }
+catch { ctx = await chromium.launchPersistentContext(profileDir, launchOpts); }
+const page = ctx.pages()[0] ?? (await ctx.newPage());
+if (sb.hideCss) await page.addInitScript((css) => { document.addEventListener("DOMContentLoaded", () => { const s = document.createElement("style"); s.textContent = css; document.head.appendChild(s); }); }, sb.hideCss);
+const ms = (v, d) => (typeof v !== "number" ? d : v < 60 ? v * 1000 : v);
+const lines = [];
+const out = (t) => { lines.push(t); console.log(t); };
+let failed = false;
+
+const visible = async (selector, minY) => {
+  const loc = page.locator(selector);
+  const deadline = Date.now() + 8000;
+  while (Date.now() < deadline) {
+    const n = await loc.count().catch(() => 0);
+    for (let i = 0; i < Math.min(n, 12); i++) {
+      const el = loc.nth(i);
+      const box = await el.boundingBox().catch(() => null);
+      if (box && box.width > 0 && box.height > 0 && box.y >= (minY || 0)) return el;
+    }
+    await page.waitForTimeout(250);
+  }
+  return null;
+};
+const controls = async () => page.evaluate(() => {
+  const vis = (el) => { const r = el.getBoundingClientRect(); const cs = getComputedStyle(el); return r.width > 0 && r.height > 0 && cs.visibility !== "hidden" && cs.display !== "none"; };
+  const clean = (t) => (t || "").replace(/\s+/g, " ").trim();
+  const label = (el) => clean(el.innerText || el.getAttribute("aria-label") || el.getAttribute("title") || el.getAttribute("placeholder") || "");
+  const seen = new Set();
+  const items = [];
+  for (const el of document.querySelectorAll("a[href], button, [role='button'], [role='tab'], [role='menuitem'], input, textarea, select, [role='link']")) {
+    if (!vis(el)) continue;
+    const l = label(el);
+    if (!l || l.length > 60) continue;
+    const tag = el.tagName.toLowerCase();
+    const key = `${tag}:${l}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const extra = el.getAttribute("data-test") || el.getAttribute("data-testid") || el.getAttribute("aria-label") || "";
+    items.push(`${tag}${el.getAttribute("role") ? `[role=${el.getAttribute("role")}]` : ""} "${l}"${extra && extra !== l ? ` (${extra})` : ""}${tag === "a" ? ` → ${el.getAttribute("href")}` : ""}`);
+    if (items.length >= 60) break;
+  }
+  return items;
+});
+
+const started = Date.now();
+for (const [i, s] of steps.entries()) {
+  if (Date.now() - started > 150000) { out(`step ${i + 1}: not reached (the probe ran out of time)`); failed = true; break; }
+  const n = i + 1;
+  try {
+    if (s.action === "goto") {
+      await page.goto(s.url, { waitUntil: "networkidle", timeout: 45000 }).catch(() => page.goto(s.url, { waitUntil: "load", timeout: 45000 }));
+      await page.waitForTimeout(1500);
+      out(`step ${n} goto ${s.url}: ok — "${(await page.title().catch(() => "")).slice(0, 80)}" at ${page.url()}`);
+    } else if (s.action === "settle") {
+      await page.waitForTimeout(Math.min(ms(s.ms, 1200), 4000));
+      out(`step ${n} settle: ok`);
+    } else if (s.action === "scroll") {
+      await page.mouse.wheel(0, s.dy || 0);
+      await page.waitForTimeout(600);
+      out(`step ${n} scroll ${s.dy}: ok`);
+    } else if (s.action === "click" || s.action === "hover" || s.action === "expect" || s.action === "type") {
+      const el = await visible(s.selector, s.minY);
+      if (!el) {
+        out(`step ${n} ${s.action} ${JSON.stringify(s.selector)}: NOT FOUND on ${page.url()}`);
+        out(`  visible controls here:\n    ${(await controls()).join("\n    ")}`);
+        failed = true;
+        if (s.required === false) continue;
+        break;
+      }
+      if (s.action === "click" && s.pointed !== true) {
+        await el.hover().catch(() => {});
+        await el.click({ timeout: 8000 });
+        await page.waitForTimeout(Math.min(ms(s.after, 1500), 4000));
+        if (s.waitLoad) await page.waitForLoadState("load").catch(() => {});
+        let revealed = "";
+        if (typeof s.reveals === "string" && s.reveals) revealed = (await visible(s.reveals, 0)) ? `, reveals ${JSON.stringify(s.reveals)} seen` : `, reveals ${JSON.stringify(s.reveals)} NOT SEEN`;
+        out(`step ${n} click ${JSON.stringify(s.selector)}: ok${revealed} — now at ${page.url()}`);
+      } else if (s.action === "type") {
+        if (s.clear) await el.fill("");
+        await el.click({ timeout: 8000 }).catch(() => {});
+        await el.type(String(s.text), { delay: 10 });
+        if (s.enter) { await page.keyboard.press("Enter"); await page.waitForTimeout(Math.min(ms(s.after, 1500), 4000)); }
+        out(`step ${n} type into ${JSON.stringify(s.selector)}: ok — now at ${page.url()}`);
+      } else {
+        await el.hover().catch(() => {});
+        await page.waitForTimeout(400);
+        out(`step ${n} ${s.action === "click" ? "pointed at" : s.action} ${JSON.stringify(s.selector)}: ok`);
+      }
+    } else {
+      out(`step ${n}: unknown action ${JSON.stringify(s.action)}`);
+      failed = true;
+      break;
+    }
+  } catch (e) {
+    out(`step ${n} ${s.action} ${JSON.stringify(s.selector ?? s.url ?? "")}: FAILED — ${String(e.message).split("\n")[0].slice(0, 160)}`);
+    try { out(`  visible controls here:\n    ${(await controls()).join("\n    ")}`); } catch { /* page gone */ }
+    failed = true;
+    break;
+  }
+}
+out(failed ? "PROBE FAILED: fix the steps above and probe again." : `PROBE PASSED: ${steps.length} steps resolved.`);
+await ctx.close();
+process.exit(failed ? 1 : 0);