retake-demos 0.2.0

package/dist/manifest.js

@@ -0,0 +1,358 @@
+/**
+ * The demo manifest — the one file a human (or later, an agent) writes.
+ *
+ * It is a superset of a testreel recording definition: the browser/steps
+ * vocabulary is testreel's, plus Retake's own layers on top:
+ *   - `seed`     what state the app should be in before the camera rolls
+ *   - `scene`    step markers that become burned-in captions + the proof log
+ *   - `outputs`  which artifacts to produce and how
+ */
+import fs from "node:fs";
+import path from "node:path";
+import YAML from "yaml";
+import { z } from "zod";
+import { DEFAULT_PRESET, PRESETS } from "./presets.js";
+const Selector = z.string().min(1);
+/** Where a pointer goes: a selector (its centre), a raw viewport point, or a
+    selector plus an offset. Points are resolved by reading the rect in the
+    page rather than through Playwright's locator engine, because canvas
+    editors (Blockly, PixiJS) intercept pointer events and make ordinary
+    locators time out. */
+export const Point = z.union([
+    Selector,
+    z.object({ x: z.number(), y: z.number() }),
+    z.object({ selector: Selector, dx: z.number().default(0), dy: z.number().default(0) }),
+]);
+const Base = z.object({
+    /** ms to rest after the step. */
+    pauseAfter: z.number().nonnegative().optional(),
+    /** Selector to wait for before running the step. */
+    waitFor: Selector.optional(),
+    timeout: z.number().positive().optional(),
+    /** This step handles a secret. Its text is never logged, never written to the
+        proof log, and never echoed to the UI. Put the value in .env and reference
+        it as ${VAR} — do not paste passwords into a manifest. */
+    secret: z.boolean().optional(),
+});
+export const Step = z.discriminatedUnion("action", [
+    Base.extend({ action: z.literal("wait"), ms: z.number().nonnegative().default(1000) }),
+    Base.extend({ action: z.literal("click"), selector: Selector.optional(), at: Point.optional(), zoom: z.number().positive().optional() }),
+    Base.extend({
+        action: z.literal("type"),
+        selector: Selector,
+        text: z.string(),
+        delay: z.number().nonnegative().optional(),
+        clear: z.boolean().optional(),
+    }),
+    Base.extend({ action: z.literal("fill"), selector: Selector, text: z.string() }),
+    Base.extend({ action: z.literal("hover"), selector: Selector.optional(), at: Point.optional() }),
+    /** Scroll by a pixel delta, or `to` a selector — which computes the delta so
+        the element lands where you want it and animates there, so the viewer sees
+        the page move rather than jumping. */
+    /** Press at one point, move, release: the gesture that block editors,
+        canvases and sortable lists are built on. The cursor overlay gets two
+        keyframes (start, end) while the page gets many small moves, so a drag
+        costs the overlay no more than a click does. */
+    Base.extend({
+        action: z.literal("drag"),
+        from: Point,
+        to: Point,
+        /** Intermediate mouse moves. The page needs several to believe a drag. */
+        steps: z.number().int().min(4).max(60).default(16),
+        /** Pause after pressing, before moving. Some editors need it. */
+        holdMs: z.number().int().min(0).max(2000).default(120),
+        /** How long the move takes, ms. */
+        durationMs: z.number().int().min(120).max(6000).default(700),
+    }),
+    Base.extend({
+        action: z.literal("scroll"),
+        x: z.number().optional(),
+        y: z.number().optional(),
+        /** A selector to bring into view, or "top" / "bottom" of the page.
+            (x/y are a relative nudge in pixels — y: 0 moves nothing.) */
+        to: z.union([z.literal("top"), z.literal("bottom"), Selector]).optional(),
+        /** Where the target should end up: top | center (default) | bottom. */
+        align: z.enum(["top", "center", "bottom"]).default("center"),
+        /** How fast to move. 1 is the default 600ms; below 1 is slower, so
+            `speed: 0.4` takes 1.5s. A long scroll at full speed reads as a jump —
+            slow it down and the viewer can follow what went past. */
+        speed: z.number().positive().max(4).optional(),
+    }),
+    Base.extend({
+        action: z.literal("zoom"),
+        selector: Selector.optional(),
+        scale: z.number().positive().default(2),
+        x: z.number().optional(),
+        y: z.number().optional(),
+        duration: z.number().positive().optional(),
+    }),
+    Base.extend({ action: z.literal("keyboard"), key: z.string().min(1) }),
+    Base.extend({ action: z.literal("navigate"), url: z.string().min(1) }),
+    Base.extend({ action: z.literal("screenshot"), name: z.string().optional() }),
+    /** Attach local files to a file input (no OS dialog is involved). */
+    Base.extend({ action: z.literal("upload"), selector: Selector, files: z.union([z.string(), z.array(z.string())]) }),
+    /** Click something that downloads, and catch the file. Saved next to the
+        video as downloads/<name>; `expect` fails the step if the name mismatches. */
+    Base.extend({ action: z.literal("download"), selector: Selector.optional(), saveAs: z.string().optional(), expect: z.string().optional() }),
+    /** Wait for a selector to appear (Retake extra; the thing testreel's JSON lacks
+        for AI-driven apps whose next screen arrives whenever the model answers). */
+    Base.extend({ action: z.literal("waitFor"), selector: Selector }),
+    /** Run JS in the page (Retake extra). Used for seeding, hiding chrome, etc. */
+    Base.extend({ action: z.literal("evaluate"), script: z.string().min(1) }),
+    /** Change what a stubbed endpoint answers, mid-take. This is how a demo shows
+        something *arriving*: the queue is empty, an action happens, the stub is
+        swapped, the next poll shows the new row. */
+    Base.extend({
+        action: z.literal("stub"),
+        url: z.string().min(1),
+        method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]).optional(),
+        status: z.number().int().optional(),
+        json: z.unknown().optional(),
+        from: z.string().optional(),
+    }),
+    /** A named beat. Timestamps go into the proof log; `caption` gets burned into
+        the video from this moment until the next scene (or `holdMs`). */
+    Base.extend({
+        action: z.literal("scene"),
+        label: z.string().min(1),
+        caption: z.string().optional(),
+        holdMs: z.number().positive().optional(),
+        /** Where the camera looks during this scene. Omitted → the manifest's
+            `camera` policy (auto = focus on the last selector used, static = none). */
+        camera: z
+            .union([z.literal("static"), z.literal("auto"), z.object({ focus: Selector.optional(), zoom: z.number().min(1).max(3).optional() })])
+            .optional(),
+    }),
+]).superRefine((st, ctx) => {
+    if ((st.action === "click" || st.action === "hover") && !st.selector && !st.at) {
+        ctx.addIssue({ code: "custom", message: `${st.action} needs either a selector or an \`at\` point` });
+    }
+});
+/** Answer a network call with canned data for the length of a take.
+    Lets a demo show populated screens when the real backend is unavailable,
+    rate-limited, or full of data you must not put on camera. Every stubbed
+    pattern is named in the proof log — a take never hides that it was faked. */
+export const Stub = z.object({
+    /** Glob or regex-ish pattern, Playwright style: "**\/api/requests*". */
+    url: z.string().min(1),
+    /** Only intercept this method; other methods pass through to the app. */
+    method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]).optional(),
+    status: z.number().int().default(200),
+    /** Inline JSON, or a file next to the manifest. One of the two. */
+    json: z.unknown().optional(),
+    from: z.string().optional(),
+    contentType: z.string().default("application/json; charset=utf-8"),
+});
+export const Seed = z.discriminatedUnion("kind", [
+    /** Write a JSON document to a file before the app is touched. Good for apps
+        with a file-backed sync hub (Capture: SYNC_DATA_DIR/sync.json). */
+    z.object({
+        kind: z.literal("file"), path: z.string(), from: z.string(),
+        /** Resolve "-12d", "+6h", "now" strings in the JSON to epoch ms at seed
+            time, so a fixture that says "three days ago" still says it next
+            month. Every app with relative dates in its UI needs this. */
+        relativeDates: z.boolean().default(false),
+    }),
+    /** Run JS in the page before recording starts, then reload. Good for
+        IndexedDB / localStorage-backed apps. `from` is a JSON file exposed as
+        `window.__seed` for the script. */
+    z.object({ kind: z.literal("evaluate"), script: z.string(), from: z.string().optional() }),
+    /** Shell command run before recording (e.g. `curl -X POST …/reset`). */
+    z.object({ kind: z.literal("command"), run: z.string() }),
+]);
+const ManifestShape = z.object({
+    name: z.string().regex(/^[a-z0-9-]+$/, "kebab-case only"),
+    title: z.string().optional(),
+    url: z.string().url(),
+    /** Quality preset — the publishing format. Fields below override it. */
+    preset: z.enum(Object.keys(PRESETS)).default(DEFAULT_PRESET),
+    /** Recording viewport (video pixels). Default = the preset's canvas. Give a
+        narrow app a narrower viewport (e.g. 1240×1080 for a 620px column at 2×)
+        and the card layout centres it in the canvas. */
+    viewport: z.object({ width: z.number().int(), height: z.number().int() }).optional(),
+    /** CSS zoom applied to the page (2 → app sees half the canvas in CSS px, renders crisp). */
+    scale: z.number().min(0.5).max(4).optional(),
+    fps: z.number().int().min(10).max(60).optional(),
+    crf: z.number().int().min(10).max(35).optional(),
+    /** band (default): the site fills the frame, caption strip below · card: the recording framed on a soft canvas · overlay-*: caption over the video · none */
+    layout: z.enum(["band", "card", "overlay-bottom", "overlay-top", "none"]).optional(),
+    /** auto: each scene zooms toward the last element the demo touched · static: no camera moves. */
+    camera: z.union([z.literal("auto"), z.literal("static"), z.object({ zoom: z.number().min(1).max(3) })]).default("auto"),
+    /** Seconds cut from the head/tail of the finished video. Render-only: change
+        it and re-render, no re-recording. */
+    trim: z.object({ head: z.number().nonnegative().default(0), tail: z.number().nonnegative().default(0) }).prefault({}),
+    /** Sign in once, reuse the session. `storageState` is a Playwright state file
+        (cookies + localStorage) written after `setup` and loaded on later runs, so
+        the login only happens when the file is missing or stale. */
+    auth: z
+        .object({
+        storageState: z.string(),
+        maxAgeHours: z.number().positive().default(72),
+        /** The sign-in steps themselves. These are the ONLY steps skipped when a
+            saved session is reused — `setup` always runs, because it usually
+            contains things that have nothing to do with logging in. */
+        setup: z.array(Step).default([]),
+    })
+        .optional(),
+    captions: z.union([z.boolean(), z.object({ fontSize: z.number().int().optional(), color: z.string().optional() })]).default(true),
+    theme: z.object({ background: z.string().optional(), ink: z.string().optional() }).prefault({}),
+    colorScheme: z.enum(["light", "dark"]).default("light"),
+    /** Ask the page for reduced motion. Apps that respect it lose their infinite
+        spinners and entrance animations — steadier frames, smaller files. */
+    reducedMotion: z.boolean().default(false),
+    waitForSelector: Selector.optional(),
+    speed: z.number().positive().default(1),
+    /** Cursor overlay (testreel). false → none; {style: touch} → tap dot. Size is preset-scaled unless set. */
+    /** cursor.idleHide: fade the cursor out when idle (testreel default). Each
+        idle gap adds a nested if() to the ffmpeg alpha expression, and ffmpeg's
+        parser has a depth limit — long demos blow past it. Retake turns it off
+        automatically above 60 steps; set it explicitly either way. */
+    cursor: z.union([z.boolean(), z.object({ style: z.enum(["default", "pointer", "text", "touch"]).optional(), size: z.number().optional(), idleHideMs: z.number().optional(), idleHide: z.boolean().optional() })]).default(true),
+    seed: z.array(Seed).default([]),
+    /** What a failed step does to the take. "stop" (default): the camera stops
+        at the failure, so nobody gets one interaction and ten minutes of
+        nothing. "continue": keep rolling — for demos that tolerate a miss. */
+    /** A demo that opens a second tab loses its subject: Retake records one
+        page. By default new tabs are folded back into this one (window.open and
+        target=_blank navigate in place), so the flow stays on camera. Set false
+        when a demo genuinely needs a separate window. */
+    keepInTab: z.boolean().default(true),
+    /** Demos that share live state (one Capture hub, one test account) must
+        not run at once: the second take's seed wipes the first take's board
+        mid-video. Name the shared thing; takes holding the same name queue. */
+    lock: z.string().regex(/^[a-z0-9-]+$/).optional(),
+    onFail: z.enum(["stop", "continue"]).default("stop"),
+    /** Playback tempo applied at render time: 0.8 slows the whole take for a
+        client who needs it gentler; 1.2 tightens it. Cursor and clicks stay in
+        sync by construction (they are pixels in the recording); captions are
+        retimed to match. Re-render only — never a re-record. */
+    tempo: z.number().min(0.5).max(2).default(1),
+    /** Hard ceiling on a take, seconds. Unset, it scales with the demo
+        (≈10s per step plus the explicit waits, never under 240s): the cap is
+        for a take that is stuck, not one that is long. Set it to override. */
+    maxSeconds: z.number().int().min(10).max(3600).optional(),
+    /** Canned network responses, armed before the first navigation. */
+    stub: z.array(Stub).default([]),
+    /** Steps run before the camera rolls. */
+    setup: z.array(Step).default([]),
+    steps: z.array(Step).min(1),
+    outputs: z
+        .object({
+        mp4: z.boolean().default(true),
+        /** GIF is opt-in (secondary): true → preset's GIF settings (or 720px/15fps), or give width/fps. */
+        gif: z.union([z.boolean(), z.object({ width: z.number().int().optional(), fps: z.number().int().optional() })]).default(false),
+        /** Which scene's frame becomes the thumbnail; default = last scene. */
+        thumbnail: z.union([z.boolean(), z.object({ scene: z.string() })]).default(true),
+        /** One PNG per scene, into outputs/<name>/stills/. */
+        stills: z.boolean().default(true),
+    })
+        .prefault({}),
+});
+export const Manifest = ManifestShape.superRefine((m, ctx) => {
+    [...m.steps, ...m.setup].forEach((st, i) => {
+        if ((st.action === "click" || st.action === "hover") && !st.selector && !st.at) {
+            ctx.addIssue({ code: "custom", path: ["steps", i], message: `${st.action} needs either a selector or an \`at\` point` });
+        }
+    });
+    // Scenes are addressed by label (thumbnail, captions, camera, stills,
+    // until); two with the same label make every one of those ambiguous.
+    const seen = new Map();
+    m.steps.forEach((st, i) => {
+        if (st.action !== "scene")
+            return;
+        if (seen.has(st.label))
+            ctx.addIssue({ code: "custom", path: ["steps", i, "label"], message: `duplicate scene label "${st.label}" (also step ${seen.get(st.label)}) — labels must be unique` });
+        else
+            seen.set(st.label, i);
+    });
+});
+export function loadManifest(file) {
+    const abs = path.resolve(file);
+    const raw = fs.readFileSync(abs, "utf8");
+    let data;
+    try {
+        data = abs.endsWith(".json") ? JSON.parse(raw) : YAML.parse(raw);
+    }
+    catch (e) {
+        // The classic trap: a one-line JS object literal under `script:` is a
+        // YAML mapping, and the parser fails before validation ever runs. Find
+        // the line it choked on; if that line carries a script, say so.
+        const err = e;
+        const line = err.linePos?.[0]?.line;
+        const src = line ? raw.split("\n")[line - 1] ?? "" : "";
+        const hint = /\bscript:/.test(src) || /compact mappings/.test(err.message) ? "\n  hint: a one-line script with braces parses as YAML, not JS — write it as a block:\n    script: |\n      window.scrollTo({ top: 0 })" : "";
+        throw new Error(`Could not parse ${file}: ${err.message.split("\n")[0]}${hint}`);
+    }
+    const parsed = Manifest.safeParse(data);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((i) => {
+            const where = i.path.join(".") || "(root)";
+            // The classic trap: a one-line JS object literal under `script:` parses
+            // as a YAML mapping. Name it, or everyone hits it once.
+            const hint = where.endsWith(".script") && /expected string/i.test(i.message) ? " — a one-line script with braces parses as YAML; write it as a block:  script: |" : "";
+            return `  - ${where}: ${i.message}${hint}`;
+        }).join("\n");
+        throw new Error(`Invalid manifest ${file}:\n${issues}`);
+    }
+    return { manifest: parsed.data, file: abs, dir: path.dirname(abs) };
+}
+/** Things worth saying out loud before a run. Not errors — the run proceeds. */
+export function warnings(m) {
+    const w = [];
+    // Secrets typed during recorded steps end up in the video. In `setup` they do
+    // not: setup runs before the camera and is trimmed off the front.
+    const onCamera = m.steps.filter((s) => s.secret).length;
+    if (onCamera)
+        w.push(`${onCamera} step(s) marked secret are in \`steps\`, not \`setup\` — redaction hides them from the logs, but they will be VISIBLE IN THE VIDEO. Move the sign-in into \`setup\`.`);
+    for (const s of [...m.steps, ...m.setup]) {
+        if ((s.action === "type" || s.action === "fill") && !s.secret && /pass|secret|token|api[-_ ]?key/i.test(s.selector)) {
+            w.push(`step "${s.action} ${s.selector}" looks like a credential field but is not marked \`secret: true\` — its text will be logged.`);
+        }
+    }
+    if (m.auth && !m.auth.setup.length && !m.setup.length)
+        w.push("`auth.storageState` is set but there are no sign-in steps under `auth.setup` — there is nothing to save a session from.");
+    const moves = m.steps.filter((st) => ["click", "type", "fill", "hover", "scroll", "upload"].includes(st.action)).length;
+    if (m.cursor !== false && moves > 45)
+        w.push(`~${moves} cursor moves — the cursor overlay (testreel/ffmpeg) cannot exceed ~45 in one take and will be MISSING from the video. Split the demo into shorter ones, or set \`cursor: false\`.`);
+    m.steps.forEach((st, i) => {
+        if (st.action !== "scene")
+            return;
+        const rest = m.steps.slice(i + 1);
+        const nextScene = rest.findIndex((x) => x.action === "scene");
+        const between = nextScene === -1 ? rest : rest.slice(0, nextScene);
+        // A closing hold on the payoff is normal; only a waits-only scene *followed by another* is empty.
+        if (nextScene !== -1 && between.length && between.every((x) => x.action === "wait"))
+            w.push(`scene "${st.label}" has only waits before the next scene — nothing happens on camera in it.`);
+    });
+    return w;
+}
+/** `${VAR}` substitution against process.env, like testreel. */
+export function expandEnv(s) {
+    return s.replace(/\$\{([A-Z0-9_]+)\}/g, (_, k) => {
+        const v = process.env[k];
+        if (v === undefined)
+            throw new Error(`manifest references \${${k}} but it is not set`);
+        return v;
+    });
+}
+export function resolve(m) {
+    const p = PRESETS[m.preset] ?? PRESETS[DEFAULT_PRESET];
+    const viewport = { width: m.viewport?.width ?? p.width, height: m.viewport?.height ?? p.height };
+    const gifOverride = m.outputs.gif;
+    const gif = gifOverride === false ? false : gifOverride === true ? p.gif : p.gif === false ? { width: gifOverride.width ?? 720, fps: gifOverride.fps ?? 15 } : { width: gifOverride.width ?? p.gif.width, fps: gifOverride.fps ?? p.gif.fps };
+    const cursor = m.cursor === false ? false : { style: (m.cursor === true ? "default" : m.cursor.style ?? "default"), size: m.cursor === true ? p.cursorSize : m.cursor.size ?? p.cursorSize, idleHideMs: m.cursor === true ? 2000 : m.cursor.idleHideMs ?? 2000, idleHide: m.cursor === true ? undefined : m.cursor.idleHide };
+    const captions = m.captions === false ? false : { fontSize: m.captions === true ? p.captionFontSize : m.captions.fontSize ?? p.captionFontSize, color: m.captions === true ? undefined : m.captions.color };
+    return {
+        ...p,
+        viewport,
+        scale: m.scale ?? p.scale,
+        fps: m.fps ?? p.fps,
+        crf: m.crf ?? p.crf,
+        layout: m.layout ?? p.layout,
+        cameraZoom: typeof m.camera === "object" ? m.camera.zoom : p.cameraZoom,
+        gif,
+        cursor,
+        captions,
+        theme: { background: m.theme.background ?? "#e6e9e2", ink: m.theme.ink ?? "#191d19" },
+    };
+}

package/dist/operator/run.js

@@ -0,0 +1,231 @@
+/**
+ * Operator sessions: the signed-in coding agent driving Retake, fenced to
+ * Retake's MCP tools, narrating to the UI, asking only when stuck.
+ *
+ * One session = one "make me a demo" request. The agent's shell is denied;
+ * its only hands are src/operator/tools.ts. Approvals (start the app) and
+ * questions come back here as pending items the UI shows, and the tool call
+ * blocks until the person answers.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync, spawn } from "node:child_process";
+import { entry } from "../paths.js";
+const sessions = new Map();
+export const getSession = (id) => sessions.get(id);
+function push(s, type, data) {
+    // Keep everything a person might want to re-read; the UI decides what to show.
+    if (type === "line")
+        s.lines.push(String(data));
+    else if (type === "tool")
+        s.lines.push(`→ ${String(data)}`);
+    else if (type === "thought")
+        s.lines.push(`  ${String(data)}`);
+    for (const l of s.listeners)
+        l({ type, data });
+}
+/** What the operator is told it is, and how to behave. Short on purpose: the
+    tools carry their own instructions, and rules beat prose. */
+export function brief(input) {
+    return [
+        "You are Retake's operator. A person wants a demo video of their web app. You have Retake's tools and nothing else — no shell.",
+        "",
+        `What they want: ${input.describe}`,
+        input.url ? `Their app is at: ${input.url}` : "They did not give a URL.",
+        input.project ? `Their app's source is in: ${input.project}` : "No source folder was given.",
+        input.name ? `Use the demo name: ${input.name}` : "Pick a short kebab-case demo name from what they asked for.",
+        "",
+        "How to work — the order that wins:",
+        "1. If you have a folder, read_project first. It tells you routes, the start command, sign-in fields, selectors, and what animates forever.",
+        "2. Make sure the app answers: scout the URL. If it refuses, check ports — dev servers often come up one port over. If it is really down and you have the folder and its start command, start_app immediately; a request made inside Retake already authorizes starting that selected project. If you cannot tell which app or port is meant, ask — one question, with what you found.",
+        "3. draft the manifest from the sentence (or write_manifest yourself if you know better). Read the returned YAML. Make sure its recorded steps actually perform every requested interaction — scene and wait steps only narrate/pause and never substitute for clicks, typing, or navigation. Fix it with write_manifest or edit: wait for results not timers, unique selectors, logins under auth.setup with ${ENV} placeholders and secret: true, reducedMotion if things animate forever, scroll to long forms.",
+        "4. dry. Always before run. Fix what it reports and dry again. Do not run a manifest whose dry run fails.",
+        "5. run with preview=true. Read the receipts. If a step failed or the story is wrong, edit and run again. Two or three rounds is normal; more than four means ask the person.",
+        "6. When it is good, run with preview=false once for the real quality, then done with one sentence.",
+        "",
+        "Rules:",
+        "- Never type real passwords into a manifest; use ${ENV_VAR} and secret: true, and tell the person which variable to set.",
+        "- Never invent selectors; use what scout/read_project returned.",
+        "- Never accept a static manifest for an interactive request. It must perform the requested actions after setup, not merely describe them with scenes and waits.",
+        "- Narrate nothing yourself — the tools already tell the person what is happening. Your text is for thinking; keep it short.",
+        "- If the backend is unavailable, prefer a stub: block in the manifest over giving up; say so in done.",
+    ].join("\n");
+}
+export function startOperator(input) {
+    const id = "op" + Date.now().toString(36);
+    const s = { id, proc: null, lines: [], pending: [], done: false, code: null, onDemo: input.onDemo, startedAt: Date.now(), listeners: new Set() };
+    sessions.set(id, s);
+    const tools = entry("operator/tools");
+    const toolEnv = { RETAKE_ROOT: input.root, RETAKE_UI: input.ui, RETAKE_SESSION: id, RETAKE_OUT: process.env.RETAKE_OUT ?? "", RETAKE_PROJECT: input.project ?? "" };
+    const mcpConfig = { mcpServers: { retake: { command: tools.command, args: tools.args, env: toolEnv } } };
+    const cfgPath = path.join(input.root, ".drafts", `mcp-${id}.json`);
+    fs.mkdirSync(path.dirname(cfgPath), { recursive: true });
+    fs.writeFileSync(cfgPath, JSON.stringify(mcpConfig));
+    // A clean env: inside another Claude Code session the inherited vars point
+    // the child at the wrong auth (see describe.ts); HOME + PATH is enough.
+    const env = { HOME: process.env.HOME ?? "", PATH: process.env.PATH ?? "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin" };
+    let catalogPath = null;
+    let proc;
+    if (input.provider === "claude-code") {
+        proc = spawn("claude", [
+            "-p", "--output-format", "stream-json", "--verbose",
+            ...(process.env.RETAKE_CLAUDE_MODEL ? ["--model", process.env.RETAKE_CLAUDE_MODEL] : []),
+            "--mcp-config", cfgPath, "--strict-mcp-config",
+            // The fence: Retake's tools are allowed, the shell and editors are not.
+            "--allowedTools", "mcp__retake__*",
+            "--disallowedTools", "Bash", "Edit", "Write", "NotebookEdit", "WebFetch", "WebSearch", "Agent", "Task",
+            "--max-turns", "60",
+        ], { env, cwd: input.root, stdio: ["pipe", "pipe", "pipe"] });
+    }
+    else {
+        // Codex installations share ~/.codex/models_cache.json, so a newer app or
+        // extension can leave a cache schema an older CLI cannot deserialize. Use
+        // the catalog bundled with the exact binary Retake launches instead. The
+        // official model_catalog_json override keeps this invocation independent
+        // from that mutable shared cache.
+        const codex = execFileSync("which", ["codex"], { encoding: "utf8", env }).trim() || "codex";
+        catalogPath = path.join(input.root, ".drafts", `codex-models-${id}.json`);
+        const catalog = execFileSync(codex, ["debug", "models", "--bundled"], { encoding: "utf8", env, timeout: 15_000, maxBuffer: 4e6 });
+        JSON.parse(catalog); // fail before spawning with a corrupt/partial catalog
+        fs.writeFileSync(catalogPath, catalog);
+        // Codex: MCP servers come from config; pass ours inline via -c and use read-only sandbox (our tools do the writing).
+        proc = spawn(codex, [
+            "-a", "never", "exec", "--skip-git-repo-check", "--ephemeral", "--ignore-user-config", "--ignore-rules", "-s", "read-only", "--color", "never", "--json",
+            "-c", `model_catalog_json=${JSON.stringify(catalogPath)}`,
+            ...(process.env.RETAKE_CODEX_MODEL ? ["-m", process.env.RETAKE_CODEX_MODEL] : []),
+            ...(process.env.RETAKE_CODEX_REASONING ? ["-c", `model_reasoning_effort=${JSON.stringify(process.env.RETAKE_CODEX_REASONING)}`] : []),
+            "-c", `mcp_servers.retake.command=${JSON.stringify(tools.command)}`,
+            "-c", `mcp_servers.retake.args=${JSON.stringify(tools.args)}`,
+            "-c", `mcp_servers.retake.env={${Object.entries(toolEnv).map(([key, value]) => `${key}=${JSON.stringify(value)}`).join(",")}}`,
+            "-c", "mcp_servers.retake.required=true",
+            "-",
+        ], { env, cwd: input.root, stdio: ["pipe", "pipe", "pipe"] });
+    }
+    s.proc = proc;
+    proc.stdin?.write(brief(input));
+    proc.stdin?.end();
+    let buf = "";
+    proc.stdout?.on("data", (chunk) => {
+        buf += chunk.toString();
+        let i;
+        while ((i = buf.indexOf("\n")) >= 0) {
+            const line = buf.slice(0, i).trim();
+            buf = buf.slice(i + 1);
+            if (!line.startsWith("{"))
+                continue;
+            try {
+                handle(s, JSON.parse(line));
+            }
+            catch { /* ignore */ }
+        }
+    });
+    proc.stderr?.on("data", (c) => { const t = c.toString().trim(); if (t && !/SessionEnd hook|hook_/.test(t))
+        push(s, "line", `· ${t.slice(0, 200)}`); });
+    proc.on("close", (code) => {
+        const tail = buf.trim();
+        if (tail.startsWith("{")) {
+            try {
+                handle(s, JSON.parse(tail));
+            }
+            catch { /* ignore */ }
+        }
+        s.done = true;
+        s.code = code;
+        if (!s.demo && s.lastDemo) {
+            s.demo = s.lastDemo;
+            s.onDemo?.(s.demo);
+        }
+        if (!s.summary) {
+            s.summary = s.lastMessage || (code === 0
+                ? "The operator finished without creating a demo. Please try the request again."
+                : "The operator stopped before the demo was ready. The details above show what failed.");
+        }
+        // A task that used Retake but never called `done` is incomplete, even if
+        // the agent process itself happened to exit cleanly.
+        if (s.code === 0 && s.usedTools && !s.demo)
+            s.code = 2;
+        push(s, "done", { code: s.code, summary: s.summary, demo: s.demo, cost: s.cost, turns: s.turns });
+        fs.rmSync(cfgPath, { force: true });
+        if (catalogPath)
+            fs.rmSync(catalogPath, { force: true });
+    });
+    return s;
+}
+/** Turn the CLI's event stream into plain lines for the page. */
+function handle(s, d) {
+    const type = d.type;
+    if (type === "assistant") {
+        const content = (d.message?.content) ?? [];
+        for (const c of content) {
+            if (c.type === "tool_use") {
+                const name = String(c.name ?? "").replace(/^mcp__retake__/, "");
+                const inp = c.input ?? {};
+                const what = name === "dry" || name === "run" || name === "render" || name === "receipts" || name === "read_manifest" ? `${name} ${inp.name ?? ""}${inp.preview === false ? " (final)" : ""}` : name === "scout" ? `scout ${inp.url ?? ""}` : name === "read_project" ? `read ${inp.dir ?? ""}` : name === "edit" ? `edit ${inp.name ?? ""} (${inp.edits?.length ?? 0} change${(inp.edits?.length ?? 0) === 1 ? "" : "s"})` : name;
+                push(s, "tool", what);
+            }
+            else if (c.type === "text" && c.text && c.text.trim()) {
+                push(s, "thought", c.text.trim().slice(0, 300));
+            }
+        }
+    }
+    else if (type === "result") {
+        s.cost = Number(d.total_cost_usd ?? 0) || undefined;
+        s.turns = Number(d.num_turns ?? 0) || undefined;
+        if (d.subtype && d.subtype !== "success")
+            push(s, "line", `✗ operator stopped: ${d.subtype}`);
+    }
+    else if (type === "item" || type === "event" || type === "item.started" || type === "item.completed") {
+        // Current Codex JSONL uses item.started/item.completed. Keep the older
+        // names too so Retake works across CLI upgrades.
+        const it = d.item;
+        if (it?.type === "mcp_tool_call") {
+            s.usedTools = true;
+            const name = String(it.tool ?? "tool").replace(/^mcp__retake__/, "");
+            const inp = it.arguments ?? {};
+            if (type === "item.started" || type === "item") {
+                const what = name === "dry" || name === "run" || name === "render" || name === "receipts" || name === "read_manifest"
+                    ? `${name} ${inp.name ?? ""}${inp.preview === false ? " (final)" : ""}`
+                    : name === "scout" ? `scout ${inp.url ?? ""}`
+                        : name === "read_project" ? `read ${inp.dir ?? ""}`
+                            : name === "edit" ? `edit ${inp.name ?? ""} (${inp.edits?.length ?? 0} change${(inp.edits?.length ?? 0) === 1 ? "" : "s"})`
+                                : name;
+                push(s, "tool", what);
+            }
+            if (type === "item.completed" && it.error?.message)
+                push(s, "line", `✗ ${name}: ${it.error.message}`);
+            if (type === "item.completed" && name === "run" && it.status === "completed" && typeof inp.name === "string")
+                s.lastDemo = inp.name;
+        }
+        else if (type === "item.completed" && it?.type === "agent_message" && it.text?.trim()) {
+            s.lastMessage = it.text.trim();
+            push(s, "thought", s.lastMessage.slice(0, 500));
+        }
+        else if (it?.text) {
+            push(s, "thought", it.text.slice(0, 300));
+        }
+    }
+    else if (type === "turn.failed" || type === "error") {
+        const err = d.error;
+        const message = typeof err === "string" ? err : err?.message;
+        push(s, "line", `✗ ${message || "The operator failed."}`);
+    }
+}
+// --- pending questions / approvals ------------------------------------------
+export function addPending(s, kind, text, detail) {
+    const p = { id: "q" + Date.now().toString(36) + Math.random().toString(36).slice(2, 5), kind, text, detail, answered: false, at: Date.now() };
+    s.pending.push(p);
+    push(s, "pending", p);
+    return p;
+}
+export function answerPending(s, id, answer) {
+    const p = s.pending.find((x) => x.id === id);
+    if (!p)
+        return false;
+    p.answered = true;
+    p.answer = answer;
+    push(s, "answered", { id, answer });
+    return true;
+}
+export function markDone(s, summary, demo) { s.summary = summary; s.demo = demo; if (demo)
+    s.onDemo?.(demo); push(s, "line", `✓ ${summary}`); }
+export function stopSession(s) { s.proc?.kill("SIGTERM"); }