@engenty/wizards-runtime 0.0.0-stage → 0.7.5

package/apps/runtime/dist/film/step.js

@@ -0,0 +1,289 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { readFile, rm, stat } from "node:fs/promises";
+import { isAbsolute, join, normalize } from "node:path";
+import { note as runNote } from "@engenty-wizards/shared/run";
+import { StepError } from "../engine/types.js";
+import { CLAUDE_BIN, claudeEnv } from "../harness/claude.js";
+import { failureOf } from "../harness/model.js";
+import { openBridge } from "../mcp/bridge.js";
+import { saidOf } from "../model-errors.js";
+import { filmClient } from "../models.js";
+import { prepareFilmFolder, savedSession, saveSession } from "./project.js";
+import { runHyperframes } from "./tools.js";
+/**
+ * A film step: the installed client (Claude Code) works in the film's folder with the skills,
+ * the style kit, the brand and the run's material, and writes the film as code. Its shell runs
+ * in the client's sandbox — writes only inside the folder, no network; HyperFrames (render,
+ * snapshots, checks) runs outside it, through the `hyperframes` tool of this step, limited to
+ * the folder. The final render is the runtime's, not the client's. A run that stops (a limit,
+ * a crash) keeps the folder and the client's session: the next attempt picks up from there.
+ */
+/** What the client may run through the tool; everything that reaches the network stays out. */
+const ALLOWED = new Set([
+    "lint",
+    "check",
+    "validate",
+    "inspect",
+    "snapshot",
+    "render",
+    "compositions",
+    "timeline",
+    "info",
+    "keyframes",
+    "compare",
+    "grade-compare",
+    "beats",
+    "normalize-audio",
+    "media-treatment",
+    "transcribe",
+    "docs",
+]);
+/** The longest a film may take the client before the step gives up. */
+const LIMIT_MS = 3 * 60 * 60_000;
+function hyperframesTool(root, signal) {
+    return {
+        name: "hyperframes",
+        description: "Runs the HyperFrames CLI in the film folder: lint, check, snapshot, render, inspect, timeline, transcribe, keyframes, compare, docs and the like. Paths are relative to the folder. Returns what it printed.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                args: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: 'The arguments, e.g. ["snapshot", "film", "--at", "1,4,8"].',
+                },
+            },
+            required: ["args"],
+        },
+        async execute(input) {
+            const args = (input.args ?? []);
+            if (!args.length || !args.every((a) => typeof a === "string")) {
+                return "args: a list of strings, the subcommand first.";
+            }
+            const [cmd] = args;
+            if (!ALLOWED.has(cmd)) {
+                return `"${cmd}" is not available here. Available: ${[...ALLOWED].join(", ")}.`;
+            }
+            // Every path stays inside the folder.
+            for (const a of args) {
+                const value = a.includes("=") && a.startsWith("-") ? a.slice(a.indexOf("=") + 1) : a;
+                if (isAbsolute(value) || normalize(value).startsWith("..")) {
+                    return `"${a}" leaves the film folder.`;
+                }
+            }
+            const extra = cmd === "transcribe" ? ["--no-runtime-install"] : [];
+            const { code, out } = await runHyperframes([...args, ...extra], {
+                cwd: root,
+                signal,
+                timeoutMs: 20 * 60_000,
+            });
+            return `exit ${code}\n${out.slice(-6000)}`;
+        },
+    };
+}
+/** Lines of a failed render worth reading: what failed and why, not the progress bars. */
+function renderProblem(out) {
+    const lines = out
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => /✗|fail|error|blocked|warning|cannot|undefined/i.test(l) && l.length < 600);
+    return (lines.join("\n") || out.slice(-800)).slice(0, 2500);
+}
+/** How many times a failed final render goes back to the client to be fixed. */
+const RENDER_FIXES = 2;
+export async function runFilmStep(step, ctx) {
+    const found = await filmClient(step.model ?? "standard");
+    if ("problem" in found) {
+        throw new StepError(found.problem);
+    }
+    const { client, alias } = found;
+    await ctx.emit("info", { code: "filmSetup" });
+    const { root, brief } = await prepareFilmFolder(step, ctx);
+    const resume = await savedSession(root);
+    await ctx.emit("info", resume ? { code: "filmResume" } : { code: "filmClient", params: { client: client.name } });
+    const limit = AbortSignal.any([ctx.signal, AbortSignal.timeout(LIMIT_MS)]);
+    const bridge = openBridge([hyperframesTool(root, limit)]);
+    /** One turn of the client in the folder; returns its final event. */
+    const turn = async (prompt, session) => {
+        const args = [
+            "-p",
+            "--output-format",
+            "stream-json",
+            "--verbose",
+            "--model",
+            alias,
+            "--setting-sources",
+            "project",
+            "--strict-mcp-config",
+            "--mcp-config",
+            JSON.stringify({ mcpServers: { film: { type: "http", url: bridge.url } } }),
+            // The shell writes only inside the folder and has no network.
+            "--settings",
+            JSON.stringify({
+                sandbox: { enabled: true, autoAllowBashIfSandboxed: true, allowUnsandboxedCommands: false },
+            }),
+            "--allowedTools",
+            [
+                "Bash",
+                "Read(./**)",
+                "Edit(./**)",
+                "Write(./**)",
+                "Glob",
+                "Grep",
+                "Task",
+                "TodoWrite",
+                "TaskCreate",
+                "TaskUpdate",
+                "TaskList",
+                "TaskGet",
+                "Skill",
+                "mcp__film",
+            ].join(","),
+            "--disallowedTools",
+            "WebFetch,WebSearch",
+        ];
+        if (step.effort) {
+            args.push("--effort", step.effort);
+        }
+        if (session) {
+            args.push("--resume", session);
+        }
+        let last = null;
+        let stderr = "";
+        await new Promise((resolve, reject) => {
+            void (async () => {
+                const child = spawn(CLAUDE_BIN, args, {
+                    cwd: root,
+                    env: await claudeEnv(),
+                    stdio: ["pipe", "pipe", "pipe"],
+                    signal: limit,
+                });
+                let buffer = "";
+                let lastLook = 0;
+                let lastTask = "";
+                const subjects = [];
+                const task = async (now) => {
+                    if (now && now !== lastTask) {
+                        lastTask = now;
+                        await ctx.emit("tool", { code: "filmTask", params: { task: now.slice(0, 90) } });
+                    }
+                };
+                const onEvent = async (event) => {
+                    if (event.session_id && event.type === "system") {
+                        await saveSession(root, event.session_id);
+                    }
+                    if (event.type === "result") {
+                        last = event;
+                    }
+                    for (const part of event.message?.content ?? []) {
+                        if (part.type !== "tool_use") {
+                            continue;
+                        }
+                        const input = part.input ?? {};
+                        // What the client is on, as its own task list says; else a look at its frames.
+                        if (part.name === "TodoWrite") {
+                            const todos = (input.todos ?? []);
+                            await task(todos.find((t) => t.status === "in_progress")?.content);
+                        }
+                        else if (part.name === "TaskCreate") {
+                            subjects.push(String(input.subject ?? ""));
+                        }
+                        else if (part.name === "TaskUpdate" && input.status === "in_progress") {
+                            const id = Number(input.taskId);
+                            await task(typeof input.subject === "string" ? input.subject : subjects[id - 1] || undefined);
+                        }
+                        else if (part.name === "mcp__film__hyperframes" &&
+                            input.args?.[0] === "snapshot" &&
+                            Date.now() - lastLook > 60_000) {
+                            lastLook = Date.now();
+                            await ctx.emit("tool", { code: "filmLooks" });
+                        }
+                    }
+                };
+                child.stdout.on("data", (chunk) => {
+                    buffer += String(chunk);
+                    let nl = buffer.indexOf("\n");
+                    while (nl >= 0) {
+                        const line = buffer.slice(0, nl).trim();
+                        buffer = buffer.slice(nl + 1);
+                        nl = buffer.indexOf("\n");
+                        if (line.startsWith("{")) {
+                            try {
+                                void onEvent(JSON.parse(line)).catch(() => { });
+                            }
+                            catch {
+                                // not a line of the stream
+                            }
+                        }
+                    }
+                });
+                child.stderr.on("data", (chunk) => {
+                    stderr = (stderr + String(chunk)).slice(-4000);
+                });
+                child.on("error", reject);
+                child.on("close", () => resolve());
+                child.stdin.end(prompt);
+            })().catch(reject);
+        }).catch((err) => {
+            if (ctx.signal.aborted) {
+                throw err;
+            }
+            throw new StepError(runNote("filmClientStopped", { name: client.name, detail: err.message }));
+        });
+        const result = last;
+        if (!result || result.is_error) {
+            const detail = String(result?.result ?? (stderr.trim() || "no result")).slice(0, 400);
+            const failure = failureOf(client, detail);
+            throw new StepError(runNote("filmWorkSaved", { problem: saidOf(failure) }));
+        }
+        return result;
+    };
+    const out = join(root, "film", "renders", "film.mp4");
+    let summary = "";
+    try {
+        // A review's note asks for a change: the film's code is there, so it is edited, not redone.
+        const note = ctx.state.notes[step.id]?.trim();
+        const prompt = resume && note
+            ? `The person watched the film and asks for this change:\n\n${note}\n\nChange the film in film/ accordingly — keep what they did not mention — check the frames again, and end with a short summary of what you changed.`
+            : resume
+                ? "Carry on with the film where you stopped. Read PROGRESS.md and the folder to see where that was, then finish it."
+                : `Make the film BRIEF.md asks for, following CLAUDE.md.\n\n${brief}`;
+        const first = await turn(prompt, resume);
+        summary = typeof first.result === "string" ? first.result.trim() : "";
+        // The final render is ours: it does not depend on the client still running. What fails
+        // goes back to the client, which fixes its code.
+        for (let attempt = 0;; attempt++) {
+            if (!existsSync(join(root, "film", "index.html"))) {
+                throw new StepError(`${client.name} hat keinen Film hinterlassen.`);
+            }
+            await ctx.emit("info", { code: "videoRendering" });
+            await rm(out, { force: true });
+            const render = await runHyperframes(["render", "film", "-o", "film/renders/film.mp4", "--crf", "23", "--quiet"], { cwd: root, signal: ctx.signal, timeoutMs: 30 * 60_000 });
+            if (render.code === 0 && existsSync(out) && (await stat(out)).size > 0) {
+                break;
+            }
+            const problem = renderProblem(render.out);
+            if (attempt >= RENDER_FIXES) {
+                throw new StepError(runNote("filmRenderFailed", { detail: problem.slice(0, 400) }));
+            }
+            await ctx.emit("tool", { code: "filmFix" });
+            const fixed = await turn(`The final render of film/ failed:\n\n${problem}\n\nFind the cause in the composition's code, fix it, run \`check\` and a draft render through the hyperframes tool until both pass, and end with one line on what you fixed.`, await savedSession(root));
+            if (typeof fixed.result === "string" && fixed.result.trim()) {
+                summary = `${summary}\n\n${fixed.result.trim()}`.trim();
+            }
+        }
+    }
+    finally {
+        bridge.close();
+    }
+    const ref = await ctx.saveAsset({
+        stepId: step.id,
+        kind: "video",
+        mime: "video/mp4",
+        name: `${step.id}.mp4`,
+        data: new Uint8Array(await readFile(out)),
+        ai: "generated",
+    });
+    return { text: summary.slice(0, 3000), assets: [ref], at: new Date().toISOString() };
+}

package/apps/runtime/dist/film/tools.js

@@ -0,0 +1,99 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { env } from "../env.js";
+/**
+ * The HyperFrames CLI (github.com/heygen-com/hyperframes, Apache 2.0): renders a composition of
+ * HTML, CSS and JS to MP4 frame by frame in headless Chrome. Installed once into the data folder
+ * on the first film, pinned to a version; Chrome comes with it on its first render.
+ */
+export const HYPERFRAMES_VERSION = "0.8.137";
+const home = join(env.dataDir, "tools", `hyperframes-${HYPERFRAMES_VERSION}`);
+const entry = join(home, "node_modules", "hyperframes", "bin", "hyperframes.mjs");
+let installing = null;
+/** Terminal colour codes. */
+const ANSI = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
+/** The CLI's entry script; installs it on first use. */
+export function hyperframesEntry() {
+    if (existsSync(entry)) {
+        return Promise.resolve(entry);
+    }
+    installing ??= install().finally(() => {
+        installing = null;
+    });
+    return installing;
+}
+async function install() {
+    await mkdir(home, { recursive: true });
+    // npm sits next to the node that runs us; else the one on PATH.
+    const local = join(dirname(process.execPath), "npm");
+    const npm = existsSync(local) ? local : "npm";
+    const { code, out } = await spawnText(npm, [
+        "install",
+        "--prefix",
+        home,
+        "--no-audit",
+        "--no-fund",
+        "--loglevel",
+        "error",
+        `hyperframes@${HYPERFRAMES_VERSION}`,
+    ], { cwd: home, timeoutMs: 10 * 60_000 });
+    if (code !== 0 || !existsSync(entry)) {
+        throw new Error(`HyperFrames could not be installed: ${out.slice(-400)}`);
+    }
+    return entry;
+}
+/** What the CLI and the renderer see: no keys of ours, no telemetry. */
+function cliEnv() {
+    const pass = ["PATH", "HOME", "USER", "LOGNAME", "LANG", "TMPDIR", "SHELL"];
+    const out = {};
+    for (const k of pass) {
+        if (process.env[k]) {
+            out[k] = process.env[k];
+        }
+    }
+    // ffmpeg as the runtime finds it, first on the PATH.
+    if (env.ffmpegPath.includes("/")) {
+        out.PATH = `${dirname(env.ffmpegPath)}:${out.PATH ?? ""}`;
+    }
+    out.HYPERFRAMES_NO_TELEMETRY = "1";
+    out.HYPERFRAMES_SKIP_SKILLS = "1";
+    return out;
+}
+/** Runs `hyperframes <args>` in a project folder and returns what it printed (the tail). */
+export async function runHyperframes(args, opts) {
+    const cli = await hyperframesEntry();
+    return spawnText(process.execPath, [cli, ...args], {
+        cwd: opts.cwd,
+        signal: opts.signal,
+        timeoutMs: opts.timeoutMs ?? 20 * 60_000,
+        env: cliEnv(),
+    });
+}
+function spawnText(bin, args, opts) {
+    return new Promise((resolve) => {
+        let out = "";
+        const child = spawn(bin, args, {
+            cwd: opts.cwd,
+            env: opts.env ?? cliEnv(),
+            stdio: ["ignore", "pipe", "pipe"],
+            signal: opts.signal,
+        });
+        const keep = (d) => {
+            out = (out + String(d)).slice(-30_000);
+        };
+        child.stdout.on("data", keep);
+        child.stderr.on("data", keep);
+        const timer = setTimeout(() => child.kill("SIGTERM"), opts.timeoutMs);
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            resolve({ code: 1, out: `${out}\n${err.message}` });
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            // Colours and progress bars mean nothing to a model reading this.
+            resolve({ code: code ?? 1, out: out.replace(ANSI, "") });
+        });
+    });
+}

package/apps/runtime/dist/geocode.js

@@ -0,0 +1,58 @@
+import { env } from "./env.js";
+const cache = new Map();
+let queue = Promise.resolve();
+let lastCall = 0;
+/** "Herrengasse 16, 8010 Graz" from a reverse-geocoding answer; null when it names nothing. */
+export function placeLabel(result) {
+    const a = result.address;
+    if (!a) {
+        return result.display_name?.split(",").slice(0, 3).join(",").trim() || null;
+    }
+    const street = [a.road ?? a.pedestrian ?? a.footway ?? a.path, a.house_number]
+        .filter(Boolean)
+        .join(" ");
+    const town = a.city ?? a.town ?? a.village ?? a.municipality ?? a.hamlet ?? a.county;
+    const place = [a.postcode, town].filter(Boolean).join(" ");
+    return [street, place].filter(Boolean).join(", ") || null;
+}
+/**
+ * The address of a position, when the server has a geocoder (`GEOCODER_URL`). Calls go out one
+ * at a time and at most one a second — what a public Nominatim asks of its users.
+ */
+export function reverseGeocode(lat, lng, language = "en") {
+    if (!env.geocoderUrl) {
+        return Promise.resolve(null);
+    }
+    // ~10 m: the same spot asked twice is one call.
+    const key = `${lat.toFixed(4)},${lng.toFixed(4)},${language}`;
+    if (cache.has(key)) {
+        return Promise.resolve(cache.get(key) ?? null);
+    }
+    const call = queue.then(async () => {
+        await new Promise((r) => setTimeout(r, Math.max(0, lastCall + 1000 - Date.now())));
+        lastCall = Date.now();
+        try {
+            const url = new URL(env.geocoderUrl);
+            url.searchParams.set("format", "jsonv2");
+            url.searchParams.set("lat", String(lat));
+            url.searchParams.set("lon", String(lng));
+            url.searchParams.set("zoom", "18");
+            url.searchParams.set("addressdetails", "1");
+            const res = await fetch(url, {
+                headers: { "accept-language": language, "user-agent": `engenty-wizards (${env.appUrl})` },
+                signal: AbortSignal.timeout(4000),
+            });
+            const label = res.ok ? placeLabel((await res.json())) : null;
+            if (cache.size > 500) {
+                cache.clear();
+            }
+            cache.set(key, label);
+            return label;
+        }
+        catch {
+            return null;
+        }
+    });
+    queue = call;
+    return call;
+}

package/apps/runtime/dist/harness/antigravity.js

@@ -0,0 +1,129 @@
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { resolveEnv, run } from "./env.js";
+import { failureOf, HarnessModel, runClient, } from "./model.js";
+/**
+ * Antigravity CLI: `agy` answers on the Google sign-in it cached — the Google AI subscription,
+ * which Gemini CLI no longer serves. The prompt goes on stdin as one stream-json message, the
+ * instructions in front of it: the client reads no system prompt and no rules of a folder it
+ * does not trust. It searches the web and reads the call's files with its own tools; the step's
+ * tools it cannot take, as it reads MCP servers only from the person's own config. The answer
+ * is checked against the schema by the client itself.
+ */
+export const AGY_BIN = process.env.AGY_BIN?.trim() || "agy";
+/** The models carry their effort in the name: `gemini-3.8-flash-<low|medium|high>`. */
+const CLASSES = {
+    classifier: "gemini-3.8-flash-low",
+    standard: "gemini-3.8-flash-medium",
+    high: "gemini-3.8-flash-high",
+    highest: "gemini-3.8-flash-high",
+};
+/** The model of that name at the effort a step asks for, where the name carries one. */
+export function withEffort(model, effort) {
+    return effort ? model.replace(/-(low|medium|high)$/, `-${effort}`) : model;
+}
+const spec = {
+    id: "antigravity",
+    passThrough: /^(AGY_ADC_AUTH|GOOGLE_APPLICATION_CREDENTIALS|GOOGLE_CLOUD_PROJECT)$/,
+    keyVars: [],
+    // No status command, and a call without a sign-in waits a minute for one in the browser:
+    // listing the models is quick, and refuses at once when nobody is signed in.
+    async auth(env) {
+        try {
+            await run(AGY_BIN, ["models"], { timeout: 20_000, env });
+            return "subscription";
+        }
+        catch {
+            return "none";
+        }
+    },
+};
+/** The client's result among the events it prints; null when it printed none. */
+export function antigravityAnswer(stdout) {
+    for (const line of stdout.trim().split("\n").reverse()) {
+        try {
+            const event = JSON.parse(line);
+            if (event?.event === "result" && event.result) {
+                return event.result;
+            }
+        }
+        catch {
+            // a line it logs
+        }
+    }
+    return null;
+}
+/** The instructions in front of the prompt: the client takes one message and nothing besides. */
+export function antigravityMessage(system, prompt) {
+    const content = system ? `<instructions>\n${system}\n</instructions>\n\n${prompt}` : prompt;
+    return `${JSON.stringify({ event: "user", message: { content } })}\n`;
+}
+class AntigravityModel extends HarnessModel {
+    provider = "antigravity";
+    nativeSchema = true;
+    usesTools = false;
+    async invoke(call) {
+        const { env, auth } = await resolveEnv(spec);
+        if (auth === "none") {
+            throw failureOf(this.harness, "not logged in");
+        }
+        const args = [
+            "--input-format",
+            "stream-json",
+            "--output-format",
+            "stream-json",
+            "--model",
+            withEffort(this.modelId, call.effort),
+            "--disable-slash-commands",
+        ];
+        if (call.schema) {
+            const schemaFile = join(call.dir, "schema.json");
+            writeFileSync(schemaFile, JSON.stringify(call.schema));
+            args.push("--json-schema", schemaFile);
+        }
+        const { stdout, stderr, code } = await runClient(AGY_BIN, args, {
+            cwd: call.dir,
+            env: { ...env, NO_COLOR: "1" },
+            signal: call.signal,
+            stdin: antigravityMessage(call.system, call.prompt),
+        });
+        const result = antigravityAnswer(stdout);
+        if (!result) {
+            throw failureOf(this.harness, stderr.trim() || `exit ${code}`);
+        }
+        if (result.status !== "SUCCESS") {
+            throw failureOf(this.harness, result.error || stderr.trim() || result.status || "error");
+        }
+        const u = result.usage ?? {};
+        return {
+            text: result.structured_output !== undefined
+                ? JSON.stringify(result.structured_output)
+                : (result.response ?? ""),
+            usage: {
+                input: u.input_tokens ?? 0,
+                cacheRead: u.cache_read_tokens ?? 0,
+                output: (u.output_tokens ?? 0) + (u.thinking_tokens ?? 0),
+            },
+            sessionId: result.conversation_id,
+            meta: { turns: result.num_turns ?? 0, seconds: result.duration_seconds ?? 0 },
+        };
+    }
+}
+export const antigravity = {
+    ...spec,
+    name: "Antigravity",
+    bin: AGY_BIN,
+    classes: CLASSES,
+    async version(env) {
+        try {
+            const { stdout } = await run(AGY_BIN, ["--version"], { timeout: 10_000, env });
+            return stdout.trim().split("\n").pop()?.trim() || null;
+        }
+        catch {
+            return null;
+        }
+    },
+    // No login command: the client asks for the Google sign-in when it starts without one.
+    login: { args: [], interactive: true },
+    model: (alias, effort) => new AntigravityModel(antigravity, alias || CLASSES.standard, effort),
+};