castle-web-cli 0.4.78 → 0.4.80

package/dist/native/playtest.js

@@ -0,0 +1,314 @@
+// The `playtest` tool: schema, arg validation/expansion, capture-health
+// diagnostics, and result digest -- everything that can be exercised without
+// a real browser. Deliberately holds NO Playwright import (not even a type
+// import) so this module (and everything that imports it -- tools.ts,
+// loop.ts) stays safe to load in a serve that never calls playtest, with
+// zero cost and zero risk of a missing-dependency crash. The Playwright-
+// specific pieces (browser lifecycle, the actual page automation) live in
+// native/playtest-browser.ts and native/playtest-executor.ts, reached only
+// through the PlaytestExecutor interface below -- see the QA battery
+// (scripts/tests/agent-qa/native/run-native.mjs), which fakes that interface
+// entirely and never touches Playwright.
+//
+// diagnoseCapture / countDistinctFrames / captureReport are ported near-
+// verbatim from castle-djinn's src/lib/playtest.ts (the iframe-postMessage
+// playtest harness) -- same ~60fps-tick heuristic, same "a starved capture is
+// NOT a broken game" warning language, adapted from a diagnostics object an
+// iframe posts back to one a Playwright page reports directly.
+import * as fs from "fs";
+import * as path from "path";
+// -- caps + fixed geometry ------------------------------------------------------
+// Ratified constants. The viewport is FIXED (not per-deck): every digest and
+// the schema description both state it, so the model never has to guess
+// what coordinate space `x`/`y` live in.
+export const PLAYTEST_MAX_DURATION_MS = 15_000;
+export const PLAYTEST_MAX_ACTIONS = 20;
+export const PLAYTEST_MAX_SHOTS = 6;
+export const PLAYTEST_MAX_CALLS_PER_RUN = 4;
+export const PLAYTEST_VIEWPORT = { width: 500, height: 700 };
+// Fixed settle before the session clock starts -- lets the page's own load
+// work (bundler eval, first paint, any async init) finish before t=0, so
+// screenshots at t=0 show a settled frame instead of a half-loaded one.
+export const PLAYTEST_SETTLE_MS = 1_500;
+// A `key` action without an explicit durationMs gets this hold length.
+const PLAYTEST_DEFAULT_KEY_DURATION_MS = 100;
+function isFiniteNumber(v) {
+    return typeof v === "number" && Number.isFinite(v);
+}
+function validateAction(raw, index) {
+    if (!raw || typeof raw !== "object")
+        return { error: `actions[${index}] must be an object` };
+    const a = raw;
+    if (!isFiniteNumber(a.t) || a.t < 0)
+        return { error: `actions[${index}].t must be a non-negative number` };
+    if (a.type !== "down" && a.type !== "move" && a.type !== "up" && a.type !== "tap" && a.type !== "key") {
+        return { error: `actions[${index}].type must be one of down/move/up/tap/key, got ${JSON.stringify(a.type)}` };
+    }
+    if (a.type === "key") {
+        if (typeof a.key !== "string" || a.key.trim() === "") {
+            return { error: `actions[${index}] (type "key") requires a non-empty \`key\` string` };
+        }
+        if (a.durationMs !== undefined && (!isFiniteNumber(a.durationMs) || a.durationMs <= 0)) {
+            return { error: `actions[${index}].durationMs must be a positive number when given` };
+        }
+        return { action: { t: a.t, type: "key", key: a.key, durationMs: a.durationMs } };
+    }
+    if (!isFiniteNumber(a.x) || !isFiniteNumber(a.y)) {
+        return { error: `actions[${index}] (type "${a.type}") requires numeric \`x\`/\`y\`` };
+    }
+    if (a.x < 0 || a.x > PLAYTEST_VIEWPORT.width || a.y < 0 || a.y > PLAYTEST_VIEWPORT.height) {
+        return {
+            error: `actions[${index}]'s coordinates (${a.x}, ${a.y}) fall outside the fixed ${PLAYTEST_VIEWPORT.width}x${PLAYTEST_VIEWPORT.height} viewport`,
+        };
+    }
+    return { action: { t: a.t, type: a.type, x: a.x, y: a.y } };
+}
+export function validatePlaytestArgs(args) {
+    if (!isFiniteNumber(args.durationMs) || args.durationMs < 0) {
+        return { ok: false, error: "durationMs is required and must be a non-negative number" };
+    }
+    if (args.durationMs > PLAYTEST_MAX_DURATION_MS) {
+        return { ok: false, error: `durationMs (${args.durationMs}) exceeds the ${PLAYTEST_MAX_DURATION_MS}ms cap` };
+    }
+    const durationMs = args.durationMs;
+    const rawActions = args.actions;
+    const actions = [];
+    if (rawActions !== undefined) {
+        if (!Array.isArray(rawActions))
+            return { ok: false, error: "actions must be an array" };
+        if (rawActions.length > PLAYTEST_MAX_ACTIONS) {
+            return { ok: false, error: `actions has ${rawActions.length} entries, exceeding the cap of ${PLAYTEST_MAX_ACTIONS}` };
+        }
+        for (let i = 0; i < rawActions.length; i++) {
+            const result = validateAction(rawActions[i], i);
+            if ("error" in result)
+                return { ok: false, error: result.error };
+            if (result.action.t > durationMs) {
+                return { ok: false, error: `actions[${i}].t (${result.action.t}) is after durationMs (${durationMs})` };
+            }
+            actions.push(result.action);
+        }
+    }
+    const rawShots = args.screenshots;
+    let screenshots;
+    if (rawShots === undefined) {
+        screenshots = [0, durationMs];
+    }
+    else {
+        if (!Array.isArray(rawShots))
+            return { ok: false, error: "screenshots must be an array of timestamps (ms)" };
+        if (rawShots.length > PLAYTEST_MAX_SHOTS) {
+            return { ok: false, error: `screenshots has ${rawShots.length} entries, exceeding the cap of ${PLAYTEST_MAX_SHOTS}` };
+        }
+        screenshots = [];
+        for (let i = 0; i < rawShots.length; i++) {
+            const v = rawShots[i];
+            if (!isFiniteNumber(v) || v < 0)
+                return { ok: false, error: `screenshots[${i}] must be a non-negative number` };
+            if (v > durationMs)
+                return { ok: false, error: `screenshots[${i}] (${v}) is after durationMs (${durationMs})` };
+            screenshots.push(v);
+        }
+    }
+    return { ok: true, value: { durationMs, actions, screenshots } };
+}
+// Expands tap/key sugar into raw primitives and merges in screenshot
+// requests, stable-sorted by t (ties: actions before screenshots, so a shot
+// requested at the same timestamp as an action captures its effect).
+export function buildTimeline(args) {
+    const events = [];
+    for (const a of args.actions) {
+        if (a.type === "tap") {
+            events.push({ t: a.t, kind: "mousedown", x: a.x, y: a.y });
+            events.push({ t: a.t, kind: "mouseup", x: a.x, y: a.y });
+        }
+        else if (a.type === "key") {
+            const holdMs = a.durationMs ?? PLAYTEST_DEFAULT_KEY_DURATION_MS;
+            events.push({ t: a.t, kind: "keydown", key: a.key });
+            events.push({ t: a.t + holdMs, kind: "keyup", key: a.key });
+        }
+        else {
+            const kind = a.type === "down" ? "mousedown" : a.type === "up" ? "mouseup" : "mousemove";
+            events.push({ t: a.t, kind, x: a.x, y: a.y });
+        }
+    }
+    for (const t of args.screenshots)
+        events.push({ t, kind: "screenshot" });
+    return events
+        .map((e, i) => ({ e, i }))
+        .sort((a, b) => (a.e.t - b.e.t) || (a.i - b.i))
+        .map(({ e }) => e);
+}
+export function diagnoseCapture(d) {
+    const expectedTicks = Math.max(1, Math.round((d.wallMs || 0) / 16));
+    const starved = d.rafTicks <= 1 || d.rafTicks < expectedTicks * 0.2;
+    return { expectedTicks, starved };
+}
+export function countDistinctFrames(frames) {
+    const seen = new Set();
+    for (const f of frames)
+        if (f.png.length > 0)
+            seen.add(f.png.toString("base64"));
+    return seen.size;
+}
+export function captureReport(frames, d) {
+    const distinct = countDistinctFrames(frames);
+    const { expectedTicks, starved } = diagnoseCapture(d);
+    const lines = [
+        `Capture health: ${d.rafTicks} animation frame(s) over ${d.wallMs}ms (a live ~60fps session is ~${expectedTicks}); ${d.framesCaptured}/${d.framesRequested} screenshot(s) captured${d.hidden ? "; document reported HIDDEN" : ""}.`,
+    ];
+    if (starved) {
+        lines.push("WARNING: the capture environment was barely rendering (animation frames near zero). That points to a throttled/dead CAPTURE (e.g. the browser or its Chromium process), not a frozen game -- the screenshots can look stuck even though the game runs fine. Treat this as a capture failure: do NOT conclude the game is broken from it. Retry the playtest once before drawing any conclusion.");
+    }
+    if (frames.length > 1 && distinct <= 1 && !starved) {
+        lines.push(`All ${frames.length} captured frames are pixel-identical -- if something should have moved or responded, check the input mapping or game loop; if nothing should have changed yet, this is expected.`);
+    }
+    return { distinct, starved, expectedTicks, lines };
+}
+// -- deck URL ---------------------------------------------------------------------
+// The serve's ROOT (`/`) is the editor shell UI (ide.ts serves the built
+// cli/dist/shell bundle there); the deck itself is `/index.html`, served by
+// Vite, which the shell's own play panel iframes as `/index.html?edit=0`
+// (see PlaytestPanel in shell/main.tsx). Playtest must load the DECK page,
+// not the shell -- v1 navigated to the origin and screenshotted the agent
+// chat UI instead of the game. `edit=0` mirrors the play iframe: the serve
+// injects `CastleEmbed={edit:true}` into every deck page, and `edit=0` is
+// the URL override that flips it to play mode (kits route to their play-only
+// view; the SDK applies its play-card layout). The play iframe's other param
+// (`logs=1`, the postMessage console forwarder for the shell's logs drawer)
+// is deliberately NOT mirrored: its inject bails on a top-level page, and
+// Playwright captures console output natively.
+export function playtestDeckUrl(serveOrigin) {
+    return `${serveOrigin.replace(/\/+$/, "")}/index.html?edit=0`;
+}
+const CONSOLE_LOG_CAP = 20;
+function fmtConsolePhase(entry) {
+    return `[${entry.phase} +${entry.t}ms] ${entry.level}: ${entry.text}`;
+}
+function buildDigest(opts) {
+    const { callIndex, args, session, report, persisted } = opts;
+    const lines = [
+        `Playtest call ${callIndex}/${PLAYTEST_MAX_CALLS_PER_RUN} -- ${session.viewport.width}x${session.viewport.height} fixed viewport, ${args.durationMs}ms session (${args.actions.length} action(s), ${args.screenshots.length} screenshot(s) requested).`,
+    ];
+    lines.push("Frames:");
+    for (const p of persisted)
+        lines.push(`  t=${p.t}ms -> ${p.relPath}`);
+    lines.push(...report.lines);
+    if (session.browserInstallMs && session.browserInstallMs > 0) {
+        lines.push(`Note: a first-run browser download added ~${Math.max(1, Math.round(session.browserInstallMs / 1000))}s to this call -- that was one-time setup, not the game loading slowly; later playtests skip it.`);
+    }
+    const consoleEntries = session.console;
+    const errorCount = consoleEntries.filter((c) => c.level === "error" || c.level === "pageerror").length;
+    if (consoleEntries.length === 0) {
+        lines.push("Console: (nothing logged across load + settle + session)");
+    }
+    else {
+        const shown = consoleEntries.slice(-CONSOLE_LOG_CAP);
+        const omitted = consoleEntries.length - shown.length;
+        lines.push(`Console (${consoleEntries.length} total, ${errorCount} error(s)${omitted > 0 ? `, showing last ${shown.length}` : ""}):`);
+        for (const entry of shown)
+            lines.push(`  ${fmtConsolePhase(entry)}`);
+    }
+    const distinctNote = persisted.length > 1 ? `${report.distinct} distinct` : `${report.distinct}`;
+    const activitySummary = `Playtested ${args.durationMs}ms: ${persisted.length} frame(s), ${distinctNote}` +
+        (errorCount > 0 ? `, ${errorCount} console error(s)` : "") +
+        (report.starved ? " [CAPTURE STARVED -- retry]" : "");
+    return { text: lines.join("\n"), activitySummary };
+}
+export async function runPlaytest(args, deckDir, ctx, signal) {
+    if (!ctx) {
+        return {
+            ok: false,
+            output: "Error: playtest has no browser/serve wired up in this context (this deck isn't being run through a serve that supports it).",
+        };
+    }
+    const parsed = validatePlaytestArgs(args);
+    if (!parsed.ok)
+        return { ok: false, output: `Error: ${parsed.error}` };
+    if (ctx.callCount.value >= PLAYTEST_MAX_CALLS_PER_RUN) {
+        return {
+            ok: false,
+            output: `Error: playtest budget exhausted -- this run has already called playtest ${PLAYTEST_MAX_CALLS_PER_RUN} time(s), the max per run. Rely on your own read of the code (or report what you've already observed) instead of playtesting again.`,
+        };
+    }
+    ctx.callCount.value += 1;
+    const callIndex = ctx.callCount.value;
+    const timeline = buildTimeline(parsed.value);
+    const session = await ctx.executor.runSession({
+        url: playtestDeckUrl(ctx.serveUrl),
+        durationMs: parsed.value.durationMs,
+        timeline,
+        signal,
+        onProgress: ctx.onProgress,
+        onInstallEvent: ctx.onInstallEvent,
+    });
+    if (!session.ok) {
+        return {
+            ok: false,
+            output: `Error: playtest capture failed: ${session.error ?? "unknown error"}. This is very likely a CAPTURE problem (the browser died or failed to load the page), not evidence the game itself is broken -- retry once before concluding anything about the game.`,
+        };
+    }
+    fs.mkdirSync(ctx.framesDir, { recursive: true });
+    const persisted = [];
+    for (const frame of session.frames) {
+        const filename = `${callIndex}-${frame.t}.png`;
+        const absPath = path.join(ctx.framesDir, filename);
+        fs.writeFileSync(absPath, frame.png);
+        persisted.push({ t: frame.t, relPath: path.relative(deckDir, absPath).split(path.sep).join("/") });
+    }
+    const report = captureReport(session.frames, session.diagnostics);
+    const digest = buildDigest({ callIndex, args: parsed.value, session, report, persisted });
+    return {
+        ok: true,
+        output: digest.text,
+        images: session.frames.map((f) => ({
+            label: `playtest call ${callIndex} frame t=${f.t}ms`,
+            dataUrl: `data:image/png;base64,${f.png.toString("base64")}`,
+        })),
+        playtestFrames: persisted.map((p) => p.relPath),
+        activitySummary: digest.activitySummary,
+    };
+}
+// -- tool schema (model-facing) ------------------------------------------------
+export const PLAYTEST_TOOL_DESCRIPTION = [
+    `Load the served deck in a real headless browser, optionally drive timed mouse/keyboard input, and capture screenshots + console/error output. Use this after changing behavior or visuals to actually SEE what you built, not just read the code back.`,
+    `Coordinates (x/y) are CSS pixels in a FIXED ${PLAYTEST_VIEWPORT.width}x${PLAYTEST_VIEWPORT.height} viewport, regardless of the deck's own canvas size.`,
+    `durationMs is the session length (ms, up to ${PLAYTEST_MAX_DURATION_MS}). actions (up to ${PLAYTEST_MAX_ACTIONS}) are timed inputs: {t,type:"down"|"move"|"up",x,y} raw mouse primitives, {t,type:"tap",x,y} (down+up sugar), or {t,type:"key",key,durationMs?} (keydown at t, keyup at t+durationMs, default ${PLAYTEST_DEFAULT_KEY_DURATION_MS}ms -- overlapping holds are fine). screenshots (up to ${PLAYTEST_MAX_SHOTS} timestamps in ms) default to [0, durationMs].`,
+    `The result is a text digest (frame list, console/error log, capture-health) plus the actual frame images delivered right after. A "capture starved" warning means the CAPTURE wasn't rendering (throttled/dead browser) -- that is not proof the game is broken; retry before concluding anything. This tool is capped at ${PLAYTEST_MAX_CALLS_PER_RUN} calls per run.`,
+].join(" ");
+export const PLAYTEST_TOOL_PARAMETERS = {
+    type: "object",
+    properties: {
+        durationMs: {
+            type: "integer",
+            description: `Session length in ms, 0-${PLAYTEST_MAX_DURATION_MS}.`,
+        },
+        actions: {
+            type: "array",
+            maxItems: PLAYTEST_MAX_ACTIONS,
+            description: `Up to ${PLAYTEST_MAX_ACTIONS} timed input actions, in a fixed ${PLAYTEST_VIEWPORT.width}x${PLAYTEST_VIEWPORT.height} CSS-pixel viewport.`,
+            items: {
+                type: "object",
+                properties: {
+                    t: { type: "integer", description: "Milliseconds from session start." },
+                    type: { type: "string", enum: ["down", "move", "up", "tap", "key"] },
+                    x: { type: "number", description: `CSS pixels, 0-${PLAYTEST_VIEWPORT.width}. Required for down/move/up/tap.` },
+                    y: { type: "number", description: `CSS pixels, 0-${PLAYTEST_VIEWPORT.height}. Required for down/move/up/tap.` },
+                    key: { type: "string", description: 'Key name (e.g. "ArrowLeft", "a", " "). Required for type "key".' },
+                    durationMs: {
+                        type: "integer",
+                        description: `Hold length for a "key" action -- keyup fires at t+durationMs. Defaults to ${PLAYTEST_DEFAULT_KEY_DURATION_MS}ms.`,
+                    },
+                },
+                required: ["t", "type"],
+            },
+        },
+        screenshots: {
+            type: "array",
+            maxItems: PLAYTEST_MAX_SHOTS,
+            items: { type: "integer" },
+            description: `Up to ${PLAYTEST_MAX_SHOTS} timestamps (ms) to screenshot at. Defaults to [0, durationMs].`,
+        },
+    },
+    required: ["durationMs"],
+};

package/dist/native/tools.d.ts

@@ -0,0 +1,38 @@
+import type { NativeRole } from "./types.js";
+import { type PlaytestToolContext } from "./playtest.js";
+export interface PolicyDecision {
+    allow: boolean;
+    reason?: string;
+}
+export type PolicyCheck = (call: {
+    tool: string;
+    args: Record<string, unknown>;
+}) => PolicyDecision;
+export interface ToolExecContext {
+    deckDir: string;
+    signal?: AbortSignal;
+    checkPolicy?: PolicyCheck;
+    playtest?: PlaytestToolContext;
+    restart?: () => void;
+}
+export interface ToolCallResult {
+    ok: boolean;
+    output: string;
+    filesTouched?: string[];
+    images?: Array<{
+        label: string;
+        dataUrl: string;
+    }>;
+    playtestFrames?: string[];
+    activitySummary?: string;
+}
+export declare function toolSchemasForRole(role: NativeRole): Array<{
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}>;
+export declare function executeTool(name: string, args: Record<string, unknown>, role: NativeRole, ctx: ToolExecContext): Promise<ToolCallResult>;
+export declare function activityLabelForCall(name: string, args: Record<string, unknown>): string;