@engenty/wizards-runtime 0.7.7 → 0.7.9

package/apps/runtime/dist/authoring/guide.js

@@ -159,7 +159,7 @@ type AgentStep = {
 // "code" brings: execute_typescript — the model writes one program that calls the step's other tools (not the browser) as
 //   functions: loops, Promise.all, filtering, sums; only its answer reaches the model. For many calls of one kind (fetch 30
 //   pages, read every row of a list, search a mailbox month by month). It needs other tools to call; a change the person
-//   must allow first is never made from a program.
+//   must allow first, generate_image and scan_documents are never called from a program.
 // "browser" brings: browser_open/read/click/type/select/scroll/press/back/wait, browser_screenshot (the model looks at the page),
 //   browser_run_fast (a decision model clicks through a page's mechanical part, where one is reached),
 //   browser_request_credentials (the PERSON types a login into the page — the model never sees it; sign-ins can be remembered),
@@ -259,10 +259,14 @@ type FilmStep = {
   brief: string                 // a template: what the film is — story, look, length, what to use. The kit carries the craft.
   skills?: string[]             // skill packages the client reads; default ["hyperframes"]. A workspace package: "skills/<name>" (has SKILL.md)
   kit?: string                  // workspace path of a STYLE KIT (.zip): a showreel made once with its rules (frame.md),
-                                //   techniques (SHOWCASE.md), helpers and stills — the bar every film of this wizard reaches
+                                //   techniques (SHOWCASE.md), helpers and stills — the bar every film of this wizard reaches.
+                                //   A kit with base/ (index.9x16.html, index.16x9.html, index.1x1.html, PARTS.md, BRAND.md,
+                                //   scene templates) is the project a film starts from: the client composes instead of building
   inputs?: { [name]: string }   // name (lowercase, -) → fieldId | steps.stepId: voice lines, pictures, uploads become files in
                                 //   input/<name>/, text in input/<name>.md, json in input/<name>.json
   format?: "16:9" | "9:16" | "1:1"
+  from?: string                 // "steps.<filmStepId>": start from that earlier film's code and lay it out for this format —
+                                //   the second format of a film in minutes; made from scratch when that step did not run
   seconds?: number              // about how long
   model?: "standard" | "high"   // default standard
   effort?: Effort
@@ -271,7 +275,8 @@ type FilmStep = {
 // the AI client installed on the person's computer (Claude Code) writes the film as code in a folder of its own, with the
 // skills, the kit, the space's brand (colours, logo, facts) and the inputs; it looks at its frames and fixes them; the
 // runtime renders the MP4. It runs only where Claude Code is set up as the AI subscription — never on credits or in the
-// cloud — and takes 10–40 minutes. Sounds come from a fixed catalog (CC0); voice comes from a generate voice step before it.
+// cloud — and takes 5–40 minutes (less with a base kit; what a base film makes from the space's brand is kept for the
+// next films there). Sounds come from a fixed catalog (CC0); voice comes from a generate voice step before it.
 
 type ReviewStep = { type: "review", show: (stepId | "lists.<listId>")[], edit?: boolean, regenerate?: boolean }
 // shows earlier outputs; the person accepts, edits text outputs (edit), or asks for a new version with a note (regenerate)

package/apps/runtime/dist/browser/fast/classifier.js

@@ -56,12 +56,16 @@ export function validateChoiceAnswer(answer, ids) {
 }
 const RETRYABLE = new Set([429, 503, 529]);
 /**
- * The run's way to a decision model (credits, an AI Gateway key or a TypeSafe key), or null
- * when there is none — then the fast loop is not offered.
+ * The run's way to a hosted decision model (credits, an AI Gateway key or a TypeSafe key), or
+ * null when there is none — then the fast loop is not offered. Clef in the local Ollama is not
+ * taken: a page's elements are more than its 26 options, and on a laptop one step took over a
+ * minute (base M4, Ollama 0.35 and 0.40, 20 to 160 s a call, also with the elements asked in
+ * groups of 26) and stopped at a search box Jev fills, where the agent's own browser tools take
+ * seconds.
  */
 export async function classifierClient(signal) {
     const access = await systemOneAccess().catch(() => null);
-    if (!access) {
+    if (!access || access.local) {
         return null;
     }
     return {
@@ -83,7 +87,8 @@ export async function classifierClient(signal) {
                     return (await res.json());
                 }
                 if (!(RETRYABLE.has(res.status) && attempt < 2)) {
-                    throw new Error(`The decision model answered ${res.status}.`);
+                    const why = (await res.text().catch(() => "")).trim().slice(0, 300);
+                    throw new Error(`The decision model answered ${res.status}${why ? `: ${why}` : ""}`);
                 }
             }
         },

package/apps/runtime/dist/cli/main.js

@@ -29,7 +29,7 @@ ${line(command(), "show the status and a menu (start, stop, update…); runs the
 ${more("(needs a terminal)")}
 ${line(`${command()} start`, "start it in this terminal and open the studio (Ctrl-C stops it)")}
 ${line(`${command()} studio`, "open the studio, starting it in the background if needed")}
-${line(`${command()} setup`, "set up your engenty account, an AI client, ffmpeg and start at login")}
+${line(`${command()} setup`, "set up your engenty account, an AI client, ffmpeg, a decision model and start at login")}
 ${line(`${command()} account`, "show your engenty account; add sign-in or sign-out to change it")}
 ${line(`${command()} open`, "sign this browser in to the running studio (--print: only print the link)")}
 ${line(`${command()} status`, "show what’s installed and running")}

package/apps/runtime/dist/cli/menu.js

@@ -71,7 +71,11 @@ function choices({ running, atLogin, release, account }) {
         hint: account.kind === "linked"
             ? `signed in as ${describeAccount(account)}`
             : describeAccount(account),
-    }, { value: "status", label: "Status", hint: "what’s installed, and any problems" }, { value: "setup", label: "Setup", hint: "account, AI client, ffmpeg, start at login" }, {
+    }, { value: "status", label: "Status", hint: "what’s installed, and any problems" }, {
+        value: "setup",
+        label: "Setup",
+        hint: "account, AI client, ffmpeg, decision model, start at login",
+    }, {
         value: "uninstall",
         label: "Uninstall",
         hint: "remove it from this computer; asks about your data first",

package/apps/runtime/dist/cli/ollama.js

@@ -0,0 +1,302 @@
+import { spawn } from "node:child_process";
+import { accessSync, constants, existsSync, mkdirSync, mkdtempSync, openSync, realpathSync, rmSync, } from "node:fs";
+import { statfs } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { decisionModelIn, ollamaRoot } from "../decision-model.js";
+import { runLogged } from "./exec.js";
+import { findOnPath } from "./machine.js";
+/** The first Ollama that answers decision questions at /v1/systemone. */
+const DECISIONS_SINCE = [0, 35, 0];
+/** What Clef-flash takes on disk, and about as much memory while it answers, in GB. */
+export const DECISION_MODEL_GB = 11;
+/** The Ollama app on a Mac: its server and its command are inside it. */
+const MAC_APPS = ["/Applications/Ollama.app", join(homedir(), "Applications", "Ollama.app")];
+const MAC_DOWNLOAD = "https://ollama.com/download/Ollama-darwin.zip";
+/** Ollama's own installer on Linux: it puts the server in a systemd service, with sudo. */
+const LINUX_SCRIPT = "https://ollama.com/install.sh";
+/**
+ * What that installer needs and a fresh Debian lacks: zstd, to unpack Ollama. Installed first
+ * with the system's package manager, under the same password.
+ */
+const LINUX_ZSTD = [
+    "if ! command -v zstd >/dev/null 2>&1; then",
+    "  if command -v apt-get >/dev/null 2>&1; then sudo apt-get update -qq && sudo apt-get install -y -qq zstd",
+    "  elif command -v dnf >/dev/null 2>&1; then sudo dnf install -y -q zstd",
+    "  elif command -v pacman >/dev/null 2>&1; then sudo pacman -S --noconfirm --needed zstd",
+    "  elif command -v zypper >/dev/null 2>&1; then sudo zypper --non-interactive install zstd",
+    "  fi",
+    "fi",
+].join("\n");
+/** Where Ollama answers: OLLAMA_URL as the runtime takes it (…/v1), without the /v1. */
+export function ollamaAddress(env = process.env) {
+    return ollamaRoot(env.OLLAMA_URL || "http://127.0.0.1:11434/v1");
+}
+function executable(file) {
+    try {
+        accessSync(file, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The `ollama` command: on the PATH, or inside the app on a Mac that never linked it. */
+export function findOllama(env = process.env) {
+    const onPath = findOnPath("ollama", env.PATH ?? "");
+    if (onPath || process.platform !== "darwin") {
+        return onPath;
+    }
+    return (MAC_APPS.map((app) => join(app, "Contents", "Resources", "ollama")).find(executable) ?? null);
+}
+async function getJson(url) {
+    try {
+        const res = await fetch(url, { signal: AbortSignal.timeout(2000) });
+        return res.ok ? (await res.json()) : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function ollamaState(env = process.env) {
+    const root = ollamaAddress(env);
+    const version = (await getJson(`${root}/api/version`))?.version ?? null;
+    const tags = version ? await getJson(`${root}/api/tags`) : null;
+    return {
+        path: findOllama(env),
+        version,
+        model: decisionModelIn((tags?.models ?? []).map((m) => m.name)),
+    };
+}
+/** Whether this Ollama is new enough to answer decision questions. */
+export function servesDecisions(version) {
+    const parts = version.split(/[.-]/).map((n) => Number.parseInt(n, 10) || 0);
+    for (const [i, wanted] of DECISIONS_SINCE.entries()) {
+        const have = parts[i] ?? 0;
+        if (have !== wanted) {
+            return have > wanted;
+        }
+    }
+    return true;
+}
+/** Free space where Ollama keeps its models (the home folder), in GB. */
+export async function freeGb(dir = homedir()) {
+    try {
+        const stats = await statfs(dir);
+        return Math.floor((stats.bavail * stats.bsize) / 2 ** 30);
+    }
+    catch {
+        return null;
+    }
+}
+/** The app an `ollama` command belongs to on a Mac; null for one from Homebrew or elsewhere. */
+function macApp(path) {
+    if (process.platform !== "darwin") {
+        return null;
+    }
+    if (!path) {
+        return MAC_APPS.find((app) => existsSync(app)) ?? null;
+    }
+    try {
+        const real = realpathSync(path);
+        const at = real.indexOf(".app/");
+        return at > 0 ? real.slice(0, at + 4) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Installs Ollama. On a Mac its app goes into Applications (~/Applications where that is not
+ * writable) and asks for no password; on Linux Ollama's own script runs in this terminal and
+ * asks for one, as it installs a system service.
+ */
+export async function installOllama(paths, onLine) {
+    const logFile = join(paths.logs, "install.log");
+    if (process.platform === "darwin") {
+        let target = "/Applications";
+        try {
+            accessSync(target, constants.W_OK);
+        }
+        catch {
+            target = join(homedir(), "Applications");
+            mkdirSync(target, { recursive: true });
+        }
+        const tmp = mkdtempSync(join(tmpdir(), "ollama-"));
+        try {
+            const zip = join(tmp, "Ollama.zip");
+            const download = await runLogged("curl", ["-fsSL", MAC_DOWNLOAD, "-o", zip], {
+                logFile,
+                onLine,
+            });
+            if (download.code !== 0) {
+                return { ok: false, message: `The download failed. ${lastLine(download.tail)}` };
+            }
+            const unpack = await runLogged("ditto", ["-x", "-k", zip, target], { logFile, onLine });
+            if (unpack.code !== 0) {
+                return { ok: false, message: `It could not be unpacked. ${lastLine(unpack.tail)}` };
+            }
+            return { ok: true, message: join(target, "Ollama.app") };
+        }
+        finally {
+            rmSync(tmp, { recursive: true, force: true });
+        }
+    }
+    if (process.platform === "linux") {
+        const code = await new Promise((resolve) => {
+            const child = spawn("sh", ["-c", `${LINUX_ZSTD}\ncurl -fsSL ${LINUX_SCRIPT} | sh`], {
+                stdio: "inherit",
+            });
+            child.on("error", () => resolve(127));
+            child.on("close", (status) => resolve(status ?? 1));
+        });
+        return code === 0
+            ? { ok: true, message: findOllama() ?? "ollama" }
+            : { ok: false, message: `Ollama’s installer stopped (exit ${code}).` };
+    }
+    return { ok: false, message: "Ollama is installed by this setup on macOS and Linux only." };
+}
+const lastLine = (text) => text.split("\n").pop() ?? "";
+/**
+ * Whether the Ollama app asks for the Mac's password when it starts: the first time, it wants to
+ * link its `ollama` command into /usr/local/bin, and its server waits for the answer (cancel
+ * works too). Not once that link points into the app.
+ */
+export function appAsksForPassword(path) {
+    const app = macApp(path);
+    if (!app) {
+        return false;
+    }
+    try {
+        return realpathSync("/usr/local/bin/ollama") !== join(app, "Contents", "Resources", "ollama");
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * Starts Ollama's server where it does not run: the app on a Mac (it then starts at login by
+ * itself), Homebrew's service, else `ollama serve` in the background. Its version once it
+ * answers; null where it does not in time — three minutes for the app, which may wait for a
+ * password, half a minute otherwise.
+ */
+export async function startOllama(path, paths) {
+    const logFile = join(paths.logs, "install.log");
+    const app = macApp(path);
+    const brew = findOnPath("brew", process.env.PATH ?? "");
+    let real = path ?? "";
+    try {
+        real = path ? realpathSync(path) : "";
+    }
+    catch {
+        // a dangling link: started as it is
+    }
+    if (app) {
+        await runLogged("open", ["-g", app], { logFile });
+    }
+    else if (brew && real.includes("/Cellar/ollama/")) {
+        await runLogged(brew, ["services", "start", "ollama"], { logFile });
+    }
+    else if (path) {
+        mkdirSync(paths.logs, { recursive: true });
+        const out = openSync(join(paths.logs, "ollama.log"), "a");
+        spawn(path, ["serve"], { detached: true, stdio: ["ignore", out, out] }).unref();
+    }
+    else {
+        return null;
+    }
+    const deadline = Date.now() + (app ? 180_000 : 30_000);
+    while (Date.now() < deadline) {
+        const { version } = await ollamaState();
+        if (version) {
+            return version;
+        }
+        await sleep(500);
+    }
+    return null;
+}
+/**
+ * Whether Ollama runs the model: one question it has to answer. Null when it does; otherwise
+ * Ollama's reason, such as a newer Ollama that no longer runs a model in the format it was pulled
+ * in. The model is loaded for it, which takes some seconds the first time.
+ */
+export async function decisionModelProblem(model, env = process.env) {
+    try {
+        const res = await fetch(`${ollamaAddress(env)}/v1/systemone`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                model,
+                state: "The setup checks the decision model.",
+                questions: { check: { type: "noul", instructions: "Is this a check?" } },
+            }),
+            signal: AbortSignal.timeout(180_000),
+        });
+        if (res.ok) {
+            return null;
+        }
+        const text = (await res.text()).trim();
+        try {
+            return JSON.parse(text).error ?? text;
+        }
+        catch {
+            return text || `Ollama answered ${res.status}.`;
+        }
+    }
+    catch (error) {
+        return error.message;
+    }
+}
+/**
+ * Pulls a model into the running Ollama; `onProgress` hears the bytes so far and in all as they
+ * come. Rejects with Ollama's own reason.
+ */
+export async function pullModel(model, onProgress, env = process.env) {
+    const res = await fetch(`${ollamaAddress(env)}/api/pull`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ model, stream: true }),
+    });
+    if (!(res.ok && res.body)) {
+        throw new Error(`Ollama answered ${res.status}. ${await res.text().catch(() => "")}`.trim());
+    }
+    // Each part of the model reports on its own; the sum is the download.
+    const parts = new Map();
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let pending = "";
+    let finished = false;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done) {
+            break;
+        }
+        pending += decoder.decode(value, { stream: true });
+        const lines = pending.split("\n");
+        pending = lines.pop() ?? "";
+        for (const line of lines) {
+            if (!line.trim()) {
+                continue;
+            }
+            const event = JSON.parse(line);
+            if (event.error) {
+                throw new Error(event.error);
+            }
+            if (event.digest && event.total) {
+                parts.set(event.digest, { total: event.total, completed: event.completed ?? 0 });
+                let sum = 0;
+                let all = 0;
+                for (const part of parts.values()) {
+                    sum += part.completed;
+                    all += part.total;
+                }
+                onProgress(sum, all);
+            }
+            finished ||= event.status === "success";
+        }
+    }
+    if (!finished) {
+        throw new Error("The download broke off.");
+    }
+}

package/apps/runtime/dist/cli/setup.js

@@ -1,7 +1,8 @@
 import { appendFileSync, existsSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
+import { homedir, totalmem } from "node:os";
 import { delimiter, join } from "node:path";
 import * as p from "@clack/prompts";
+import { LOCAL_DECISION_MODEL } from "../decision-model.js";
 import { accountStep } from "./account.js";
 import { autostartForStatus, setAutostart } from "./autostart.js";
 import { installClient, installCommand } from "./clients.js";
@@ -9,6 +10,7 @@ import { appStates, connectApps } from "./connect.js";
 import { runLogged } from "./exec.js";
 import { command, installedByScript, isCheckout, packageVersion, readInstallNote, writeInstallNote, } from "./home.js";
 import { CLIENTS, detectClients, findChrome, findFfmpeg, findOnPath, suggestedClient, vendorApp, } from "./machine.js";
+import { appAsksForPassword, DECISION_MODEL_GB, decisionModelProblem, freeGb, installOllama, ollamaState, pullModel, servesDecisions, startOllama, } from "./ollama.js";
 import { runningRuntime, settings } from "./start.js";
 import { badge, busy, cmd, cyan, dim, tilde } from "./ui.js";
 /** The studio as an app of its own: Chrome (or Edge) installs it from the page. */
@@ -123,6 +125,101 @@ async function toolsStep(interactive) {
         }
     }
 }
+const gb = (bytes) => (bytes / 2 ** 30).toFixed(1);
+/**
+ * A decision model on this computer: Ollama with Cloudflare's Clef-flash. It answers a wizard's
+ * decisions (which branch, which option) without a key or credits. Asked, never assumed: it is a
+ * download of about 11 GB.
+ */
+async function decisionModelStep(paths, interactive) {
+    const state = await ollamaState();
+    if (state.version && !servesDecisions(state.version)) {
+        p.log.warn(`Ollama ${state.version} is too old for a decision model (it needs 0.35 or newer).\n${dim(`Update Ollama, then run ${cmd("setup")} again.`)}`);
+        return;
+    }
+    // Pulled is not enough: a newer Ollama may no longer run a model pulled in an older format.
+    let broken = null;
+    if (state.model) {
+        const check = busy(`Checking ${state.model}…`);
+        broken = await decisionModelProblem(state.model);
+        if (!broken) {
+            check.stop(`Decision model: ${state.model} ${dim(`in Ollama ${state.version}`)}`);
+            return;
+        }
+        check.fail(`${state.model} doesn’t run in Ollama ${state.version}: ${broken}`);
+    }
+    const model = state.model ?? LOCAL_DECISION_MODEL;
+    const what = state.path ? `Clef-flash into Ollama` : "Ollama with Clef-flash";
+    if (!interactive) {
+        p.log.info(dim(broken
+            ? `To download it again: ${cyan(`ollama pull ${model}`)}`
+            : `Optional: a decision model on this computer (${what}, about ${DECISION_MODEL_GB} GB). To add it: ${cmd("setup")}`));
+        return;
+    }
+    const free = await freeGb();
+    if (free !== null && free < DECISION_MODEL_GB + 2) {
+        p.log.warn(`There isn’t room for a decision model: it needs about ${DECISION_MODEL_GB + 2} GB and ${free} GB are free.`);
+        return;
+    }
+    const memory = Math.round(totalmem() / 2 ** 30);
+    const answer = await p.confirm({
+        message: broken
+            ? `Download ${model} again, in the format this Ollama runs? About ${DECISION_MODEL_GB} GB.`
+            : `Install a decision model on this computer? ${what} makes the wizards’ decisions (which branch, which option) here, without a key or credits. About ${DECISION_MODEL_GB} GB${memory < 16 ? `; it needs 16 GB of memory and this computer has ${memory}` : ""}.`,
+        initialValue: Boolean(broken),
+    });
+    if (cancelled(answer)) {
+        return "cancelled";
+    }
+    if (!answer) {
+        p.log.info(dim(`To add it later: ${cmd("setup")}`));
+        return;
+    }
+    let { path: ollama, version } = state;
+    if (!ollama) {
+        // On Linux Ollama's installer writes to this terminal itself, and may ask for a password.
+        const task = process.platform === "linux" ? null : p.taskLog({ title: "Installing Ollama", limit: 6 });
+        if (!task) {
+            p.log.info("Ollama’s own installer runs now and asks for your password.");
+        }
+        const outcome = await installOllama(paths, (line) => task?.message(line));
+        if (!outcome.ok) {
+            const text = `Ollama didn’t install. ${outcome.message}`;
+            task ? task.error(text) : p.log.error(text);
+            return;
+        }
+        const installed = `Ollama installed ${dim(tilde(outcome.message))}`;
+        task ? task.success(installed) : p.log.success(installed);
+        // Linux's installer starts it as a service already.
+        ({ path: ollama, version } = await ollamaState());
+    }
+    if (!version) {
+        if (appAsksForPassword(ollama)) {
+            p.log.info("Ollama starts now and asks once for your Mac’s password, to put its `ollama` command in /usr/local/bin. Enter it, or cancel: Ollama runs either way.");
+        }
+        const spinner = p.spinner();
+        spinner.start("Waiting for Ollama");
+        version = await startOllama(ollama, paths);
+        if (!version) {
+            spinner.error(`Ollama isn’t answering. Start it, then run ${cmd("setup")} again.`);
+            return;
+        }
+        if (!servesDecisions(version)) {
+            spinner.error(`Ollama ${version} is too old for a decision model (it needs 0.35 or newer).`);
+            return;
+        }
+        spinner.stop(`Ollama ${version} is running`);
+    }
+    const spinner = p.spinner();
+    spinner.start(`Downloading ${model}`);
+    try {
+        await pullModel(model, (done, total) => spinner.message(`Downloading ${model}  ${gb(done)} of ${gb(total)} GB`));
+        spinner.stop(`Decision model: ${model} ${dim(`in Ollama ${version}`)}`);
+    }
+    catch (error) {
+        spinner.error(`${model} didn’t download. ${error.message}\n${dim(`To try again: ${cyan(`ollama pull ${model}`)}`)}`);
+    }
+}
 /**
  * Starting at login: on a Mac a LaunchAgent starts the runtime, on Linux a systemd user
  * service does. Asked, never assumed; `autostart off` undoes it.
@@ -287,7 +384,7 @@ async function howToUse(paths) {
 }
 /**
  * The guided setup: the account this computer joins, then what this machine has, what is
- * missing, and what to install — an AI client to think with, ffmpeg, starting at login. It
+ * missing, and what to install — an AI client to think with, ffmpeg, a decision model, starting at login. It
  * starts nothing; it ends with what runs and how to start, stop and check it. Returns false
  * when it was stopped.
  */
@@ -308,6 +405,9 @@ export async function setup(paths, options) {
     if ((await toolsStep(interactive)) === "cancelled") {
         return false;
     }
+    if ((await decisionModelStep(paths, interactive)) === "cancelled") {
+        return false;
+    }
     if ((await autostartStep(paths, interactive)) === "cancelled") {
         return false;
     }

package/apps/runtime/dist/clients.js

@@ -0,0 +1,118 @@
+import { env } from "./env.js";
+import { allowed } from "./limits.js";
+import { managed } from "./manage.js";
+/**
+ * The clients of the public run API: who starts runs here (docs/content/dev/api.md,
+ * docs/plans/api-clients.md). A client names itself in the `x-wizards-client` header: `web` (the
+ * runner in a browser), `app` (the mobile app), `cli`, or the id of a client registered at the
+ * Manage-App. The id is no secret: it carries the terms, the limits and the revocation of a
+ * client, not its proof. The run keeps it.
+ *
+ * A managed runtime fetches the list of clients from its Manage-App at the start and once an
+ * hour, and keeps the last list when a fetch fails. Without a list every client may start runs:
+ * the Manage-App being down must not close the wizards. A runtime that runs alone fetches
+ * nothing and refuses nothing — its API is the person's own.
+ */
+export const CLIENT_HEADER = "x-wizards-client";
+/** The clients this repository ships: the runner, the mobile app, the command line. */
+export const OWN_CLIENTS = ["web", "app", "cli"];
+const ID = /^[a-z0-9][a-z0-9-]{0,63}$/;
+/** The client a request names, or null when it names none or a malformed one. */
+export function clientOf(c) {
+    const id = c.req.header(CLIENT_HEADER)?.trim().toLowerCase() ?? "";
+    return ID.test(id) ? id : null;
+}
+let list = null;
+/** The list in force; tests set it, a managed runtime fetches it. */
+export function setClientList(next) {
+    list = next;
+}
+const HOUR = 3600_000;
+/**
+ * Why `client` may not start a run now, or null when it may. Counts the try against the
+ * client's hourly cap, so call it once per start.
+ */
+export function clientRefused(client) {
+    if (!list) {
+        return null;
+    }
+    const known = list.clients.find((c) => c.id === client);
+    const cap = known ? known.runsPerHour : list.unknown.runsPerHour;
+    if (known ? known.revoked : !list.unknown.allow) {
+        return {
+            status: 403,
+            code: "client_refused",
+            note: "clientRefused",
+        };
+    }
+    if (cap !== null && !allowed(`client:${client ?? "unknown"}`, cap, HOUR)) {
+        return {
+            status: 429,
+            code: "client_limit",
+            note: "clientLimit",
+        };
+    }
+    return null;
+}
+/** The list as the Manage-App sends it, checked; throws on a shape this runtime does not know. */
+export function parseClientList(body) {
+    const raw = body;
+    if (!Array.isArray(raw?.clients)) {
+        throw new Error("no clients");
+    }
+    const clients = raw.clients.map((c) => {
+        if (typeof c?.id !== "string" || !ID.test(c.id)) {
+            throw new Error("bad client id");
+        }
+        return {
+            id: c.id,
+            name: typeof c.name === "string" ? c.name : c.id,
+            runsPerHour: typeof c.runsPerHour === "number" && c.runsPerHour >= 0 ? c.runsPerHour : null,
+            revoked: c.revoked === true,
+        };
+    });
+    const unknown = (raw.unknown ?? {});
+    return {
+        clients,
+        unknown: {
+            allow: unknown.allow !== false,
+            runsPerHour: typeof unknown.runsPerHour === "number" && unknown.runsPerHour >= 0
+                ? unknown.runsPerHour
+                : null,
+        },
+    };
+}
+/**
+ * Fetches the Manage-App's list. A Manage-App without the call (404) means no list: everything
+ * may start runs. Any other failure keeps the list from before.
+ */
+export async function loadClientList() {
+    if (!managed) {
+        return;
+    }
+    try {
+        const res = await fetch(`${env.manage.url}/v1/clients`, {
+            headers: { authorization: `Bearer ${env.manage.serviceKey}` },
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (res.status === 404) {
+            list = null;
+            return;
+        }
+        if (!res.ok) {
+            throw new Error(`HTTP ${res.status}`);
+        }
+        list = parseClientList(await res.json());
+    }
+    catch (err) {
+        console.warn(`[clients] the Manage-App's client list was not read: ${err.message}`);
+    }
+}
+/** A managed runtime: the list now, and again every hour. */
+export function startClientChecks() {
+    if (!managed) {
+        return;
+    }
+    void loadClientList();
+    setInterval(() => void loadClientList(), HOUR).unref();
+}