@engenty/wizards-runtime 0.7.7 → 0.7.8

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/decision-model.js

@@ -0,0 +1,33 @@
+/**
+ * A decision model on the person's own machine: Cloudflare's Clef-flash (open weights, Apache
+ * 2.0), which Ollama 0.35 and newer serves at /v1/systemone with the same questions and answers
+ * as TypeSafe's Jev. The setup offers to pull it; the runtime asks it where no hosted decision
+ * model is set up.
+ */
+/** The model the setup pulls. Clef, its larger sibling, is taken as well where it is there. */
+export const LOCAL_DECISION_MODEL = "clef-flash";
+/** Ollama's own address from the one the runtime uses for its OpenAI-style API (…/v1). */
+export function ollamaRoot(url) {
+    return url.trim().replace(/\/+$/, "").replace(/\/v1$/, "");
+}
+/** The decision model among the models Ollama lists: Clef-flash, else Clef. */
+export function decisionModelIn(names) {
+    const named = (base) => names.find((n) => n === base || n.startsWith(`${base}:`));
+    return named(LOCAL_DECISION_MODEL) ?? named("clef") ?? null;
+}
+/** The decision model the Ollama at `url` holds; null where it does not run or has none. */
+export async function ollamaDecisionModel(url, timeoutMs = 1500) {
+    try {
+        const res = await fetch(`${ollamaRoot(url)}/api/tags`, {
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok) {
+            return null;
+        }
+        const { models } = (await res.json());
+        return decisionModelIn((models ?? []).map((m) => m.name));
+    }
+    catch {
+        return null;
+    }
+}

package/apps/runtime/dist/docs/user/command-line.md

@@ -11,7 +11,7 @@ version: 0.5.0
 | `wizards` | Shows what is running, and a menu. While it runs, you can open the studio, restart or stop it; while it doesn’t, “Start in the background” or “Start in this terminal”. Then “Update”, which restarts it into the new version, “Start at login”, “Connect AI apps”, “Account”, “Status”, “Setup”, “Uninstall” and “Help”. The first time, the setup runs first. It needs a terminal |
 | `wizards start` | Starts it and opens the studio. It runs in that terminal, and Ctrl-C stops it. The first time, the setup runs first |
 | `wizards studio` | Opens the studio in your browser. If it isn’t running, it starts in the background first |
-| `wizards setup` | Runs the guided setup again: your account, an AI client, the browser and ffmpeg, start at login, your AI apps. `--local` leaves the account out ([Local only](./local-only.md)) |
+| `wizards setup` | Runs the guided setup again: your account, an AI client, the browser and ffmpeg, a decision model, start at login, your AI apps. `--local` leaves the account out ([Local only](./local-only.md)) |
 | `wizards account` | Shows the account this computer is signed in to: who, which team, the credits. `sign-in` shows a link and a code and opens your browser; `sign-out` disconnects this computer |
 | `wizards open` | Signs this browser in to the running studio. `--print` only prints the link; it works once, within a minute |
 | `wizards status` | Shows what is installed and running, with the browser it uses for PDF, PNG and websites |

package/apps/runtime/dist/docs/user/install.md

@@ -32,6 +32,7 @@ have is left alone), installs engenty wizards into `~/.engenty/wizards` (about 6
 | Your engenty account | Asks “Sign in or create your account now?”. If you say yes, it shows a link and a code and opens your browser for the sign-in at account.engenty.ai; check that the page shows the same code (if you have no account yet, the page creates one with your invitation code, or puts you on the waitlist). While it waits, Enter opens the page again and Esc goes on without an account. Once you are signed in, what you publish on this computer runs in the cloud too. If you say no, `wizards account sign-in` does it any time. Setting it up again with `--local` signs an account out. `--local` leaves the account out altogether: see [Local only](./local-only.md) |
 | An AI client | Looks for Codex, Claude Code, Antigravity and Cursor Agent and offers to install the ones that are missing. It puts first the one whose app (ChatGPT, Claude, Antigravity, Cursor) is on your Mac, as you most likely have that subscription already. You can also use your account’s credits, an API key, [Ollama](https://ollama.com) or, on a Mac with Apple silicon and macOS 26, Apple Intelligence: the studio’s [first page](./first-start.md) offers them |
 | A browser and ffmpeg | Names the browser for PDF and PNG exports and steps on websites: the first of Chrome, Edge and Chromium it finds (on a Mac also Brave). engenty wizards uses that one; [`CHROME_PATH`](./command-line.md#settings) picks another. It also says whether ffmpeg is there for MP4 videos of animated widgets, and with Homebrew it offers to install it |
+| A decision model (optional) | Offers to install [Ollama](https://ollama.com) if it isn’t there and to download Cloudflare’s Clef-flash into it (about 11 GB). The wizards then make their decisions, such as which branch to take, on your computer, without a key or credits. On a Mac the Ollama app goes into Applications and, when it first starts, asks once for your Mac’s password to set up its `ollama` command (cancel works too); on Linux Ollama’s own installer runs, installs `zstd` if it is missing, and asks for your password |
 | Start at login (optional) | engenty wizards starts in the background when you log in, so links and AI apps can always reach it. It is a LaunchAgent on a Mac and a systemd user service on Linux |
 | Your AI apps (optional) | Offers to add your wizards to the [AI apps](./ai-apps.md) it finds, such as Claude Desktop, Cursor or Codex |
 | The command | If `~/.local/bin` is not on your PATH, it offers to add it in your shell’s settings file |

package/apps/runtime/dist/engine/decide.js

@@ -32,7 +32,9 @@ async function askSystemOne(input, signal) {
                 return readSystemOne(input.questions, await res.json());
             }
             if (!(RETRYABLE.has(res.status) && attempt < 2)) {
-                console.warn(`[decide] the decision model answered ${res.status}`);
+                const why = (await res.text().catch(() => "")).trim().slice(0, 300);
+                access.refused?.(res.status, why);
+                console.warn(`[decide] the decision model answered ${res.status}${why ? `: ${why}` : ""}`);
                 return {};
             }
         }