@engenty/wizards-runtime 0.0.0-stage → 0.7.5

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

@@ -0,0 +1,91 @@
+import { assembleSurface, dataRef, listRef, } from "@engenty-wizards/shared/definition";
+import { note } from "@engenty-wizards/shared/run";
+import { validateSurface } from "@engenty-wizards/shared/surface";
+import { decide } from "./decide.js";
+import { answersAsText, resolveRef } from "./template.js";
+import { StepError } from "./types.js";
+/**
+ * A surface step: its data read from the run (answers, outputs, stored lists; the pictures a
+ * step made as asset ids), its components written once — or, for a decided surface, the pieces
+ * one decision keeps. Checked against the catalog before it is shown.
+ */
+export async function runSurfaceStep(step, ctx) {
+    const data = surfaceData(step.data, ctx);
+    const components = step.components ?? (await decidedComponents(step, ctx));
+    const issues = validateSurface(components, Object.keys(data));
+    if (issues.length) {
+        throw new StepError(note("viewErrors", { detail: issues.map((i) => i.message).join(" ") }));
+    }
+    return { surface: { components, data }, at: new Date().toISOString() };
+}
+/** What a surface reads: key → a field, a step's output or one of its fields, a stored list. */
+export function surfaceData(refs, ctx) {
+    const out = {};
+    for (const [key, raw] of Object.entries(refs)) {
+        const ref = dataRef(raw);
+        const list = listRef(ref);
+        if (list) {
+            out[key] = (ctx.scope.lists?.[list]?.rows ?? []).map((r) => r.cells);
+            continue;
+        }
+        const source = ctx.def.steps.find((s) => `steps.${s.id}` === ref);
+        if (source && (source.type === "generate" || source.type === "widget")) {
+            // Pictures and clips by asset id: the runner shows them from the run's files.
+            const ids = (ctx.state.outputs[source.id]?.assets ?? []).map((a) => a.id);
+            out[key] = source.type === "generate" && source.each ? ids : (ids[0] ?? null);
+            continue;
+        }
+        const output = source ? ctx.state.outputs[source.id] : undefined;
+        out[key] = output ? (output.json ?? output.text ?? null) : (resolveRef(ref, ctx.scope) ?? null);
+    }
+    return out;
+}
+/** The pieces of a decided surface one decision keeps: required ones always. */
+async function decidedComponents(step, ctx) {
+    const candidates = step.candidates ?? [];
+    const questions = {};
+    for (const c of candidates) {
+        if (!c.required && !c.group) {
+            questions[`p_${c.id}`] = {
+                type: "noul",
+                instructions: `Should the view show this: ${c.description}`,
+            };
+        }
+    }
+    for (const g of step.groups ?? []) {
+        const members = candidates.filter((c) => c.group === g.id && !c.required);
+        if (members.length) {
+            questions[`g_${g.id}`] = {
+                type: "choice",
+                instructions: g.instructions,
+                criteria: {
+                    ...Object.fromEntries(members.map((c) => [c.id, c.description])),
+                    ...(g.optional ? { none: "None of these." } : {}),
+                },
+            };
+        }
+    }
+    const kept = new Set(candidates.filter((c) => c.required).map((c) => c.id));
+    if (Object.keys(questions).length) {
+        const results = Object.fromEntries(ctx.def.steps
+            .map((s) => [s.title, ctx.state.outputs[s.id]?.text ?? ""])
+            .filter(([, text]) => text)
+            .map(([title, text]) => [title, text.slice(0, 6000)]));
+        const decision = await decide({
+            state: { answers: answersAsText(ctx.scope), results },
+            questions,
+            call: ctx.call,
+            signal: ctx.signal,
+            charge: ctx.chargeUsd,
+        });
+        for (const [name, answer] of Object.entries(decision.answers)) {
+            if (answer.type === "noul" && answer.noul >= 0.5) {
+                kept.add(name.slice(2));
+            }
+            else if (answer.type === "choice" && answer.choice !== "none") {
+                kept.add(answer.choice);
+            }
+        }
+    }
+    return assembleSurface(candidates, kept);
+}

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

@@ -0,0 +1,240 @@
+import { allFields, isAudioValue, isLocationValue, itemsTotals, localeOf, locationText, wizardLang, } from "@engenty-wizards/shared/definition";
+import { formatMoney } from "@engenty-wizards/shared/numbers";
+import { fontLicenseWords, gradientCss, textStyleLine, } from "@engenty-wizards/shared/projects";
+import { listAsMarkdown } from "@engenty-wizards/shared/store";
+const TEMPLATE_RE = /\{\{\s*([^}]+?)\s*\}\}/g;
+/** Line items as a Markdown table with their totals — what a model needs to write a document. */
+export function itemsAsMarkdown(field, value, values, lang = "en") {
+    const locale = localeOf(lang);
+    const totals = itemsTotals(field, value, values);
+    const cols = field.columns ?? [];
+    if (!totals.rows.length) {
+        return "(no line items)";
+    }
+    const head = `| ${cols.map((c) => c.label).join(" | ")} | Amount |\n|${cols.map(() => " --- ").join("|")}| ---: |`;
+    const body = totals.rows.map((r) => `| ${cols
+        .map((c) => c.kind === "money"
+        ? formatMoney(Number(r[c.id]) || 0, totals.currency, locale)
+        : String(r[c.id] ?? ""))
+        .join(" | ")} | ${formatMoney(r.amount, totals.currency, locale)} |`);
+    const sums = [
+        `Net: ${formatMoney(totals.net, totals.currency, locale)}`,
+        totals.vatRate
+            ? `VAT ${totals.vatRate}%: ${formatMoney(totals.vat, totals.currency, locale)}`
+            : null,
+        `Total: ${formatMoney(totals.gross, totals.currency, locale)}`,
+    ].filter(Boolean);
+    return [head, ...body, "", ...sums].join("\n");
+}
+/** Facts as lines a model reads: "Label: value". */
+export function factLines(facts) {
+    return facts.map((f) => `${f.label}: ${f.value}`).join("\n");
+}
+/**
+ * The colours as a model reads them; a section's after the standard ones. A gradients section
+ * names its gradients as CSS, each with what it is for.
+ */
+export function colorLine(colors, sections = [], gradients = []) {
+    const line = (list) => list.map((c) => (c.name ? `${c.name} ${c.value}` : c.value)).join(", ");
+    const known = (c) => sections.some((s) => s.id === c.section);
+    return [
+        line(colors.filter((c) => !known(c))),
+        ...sections.map((s) => {
+            if (s.kind === "gradients") {
+                const own = gradients.filter((g) => g.section === s.id);
+                const one = (g) => `${g.name || "gradient"}${g.description ? ` (${g.description})` : ""} ${gradientCss(g)}`;
+                return own.length ? `${s.title}: ${own.map(one).join("; ")}` : "";
+            }
+            const own = colors.filter((c) => c.section === s.id);
+            return own.length ? `${s.title}: ${line(own)}` : "";
+        }),
+    ]
+        .filter(Boolean)
+        .join(" · ");
+}
+/**
+ * The brand's type as a model reads it: its fonts with their licences, then its text styles. A
+ * licence that names its uses is binding.
+ */
+export function typeLines(fonts = [], styles = []) {
+    const families = fonts.map((f) => {
+        const weights = f.weights.length ? `, weights ${f.weights.join("/")}` : "";
+        return `- ${f.family}${f.role ? ` (${f.role})` : ""}${weights}${fontLicenseWords(f)}`;
+    });
+    const scale = styles.map((s) => `- ${s.name}: ${textStyleLine(s, fonts)}`);
+    return [
+        families.length ? `Fonts:\n${families.join("\n")}` : "",
+        fonts.some((f) => f.uses?.length)
+            ? "A font's licence is binding: use a font only for what it may be used for, and set anything else in a system font."
+            : "",
+        scale.length ? `Text styles:\n${scale.join("\n")}` : "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
+const sectionWords = (s) => !s ? "" : s.description ? `${s.title} (${s.description})` : s.title;
+/** The logo's section in words — "Logomark (small spaces, app icons)" — or "" where it has none. */
+export function logoSectionLine(sections, fileId) {
+    return sectionWords(sections?.find((x) => x.logos.includes(fileId)));
+}
+/** The title of the asset's section — "Icons" — or "" where it has none. */
+export function assetSectionLine(sections, fileId) {
+    return sections?.find((x) => x.assets.includes(fileId))?.title ?? "";
+}
+function brandRef(brand, key) {
+    switch (key) {
+        case "name":
+            return brand.name ?? "";
+        case "about":
+            return brand.about ?? "";
+        // What the free "details" text once held is now the description and the facts.
+        case "details":
+            return [brand.about, factLines(brand.facts ?? [])].filter(Boolean).join("\n");
+        case "accent":
+            return brand.colors?.[0]?.value ?? "";
+        case "colors":
+            return colorLine(brand.colors ?? [], brand.colorSections, brand.gradients);
+        case "fonts":
+            return typeLines(brand.fonts, brand.textStyles);
+        default:
+            return "";
+    }
+}
+function stringify(v) {
+    if (v === undefined || v === null) {
+        return "";
+    }
+    if (typeof v === "string") {
+        return v;
+    }
+    if (typeof v === "number" || typeof v === "boolean") {
+        return String(v);
+    }
+    if (Array.isArray(v) && v.every((x) => typeof x !== "object")) {
+        return v.join(", ");
+    }
+    return JSON.stringify(v, null, 2);
+}
+export function resolveRef(ref, scope) {
+    const { def, state, brand } = scope;
+    const [head, ...rest] = ref.split(".");
+    if (head === "lists") {
+        const list = scope.lists?.[rest[0] ?? ""];
+        return list ? listAsMarkdown(list.def, list.rows) : "";
+    }
+    if (head === "today") {
+        return new Date().toISOString().slice(0, 10);
+    }
+    if (head === "item" || head === "index" || head === "count") {
+        const entry = scope.entry;
+        if (!entry) {
+            return "";
+        }
+        if (head === "index") {
+            return entry.index + 1;
+        }
+        if (head === "count") {
+            return entry.count;
+        }
+        let cur = entry.item;
+        for (const key of rest) {
+            cur = cur && typeof cur === "object" ? cur[key] : undefined;
+        }
+        return cur;
+    }
+    if (head === "brand") {
+        return brandRef(brand, rest[0] ?? "name");
+    }
+    if (head === "facts") {
+        const facts = brand.facts ?? [];
+        return rest[0] ? (facts.find((f) => f.key === rest[0])?.value ?? "") : factLines(facts);
+    }
+    if (head === "steps") {
+        const out = state.outputs[rest[0] ?? ""];
+        if (!out) {
+            return "";
+        }
+        if (rest.length === 1) {
+            return out.json !== undefined ? out.json : (out.text ?? "");
+        }
+        let cur = out.json;
+        for (const key of rest.slice(1)) {
+            cur = cur && typeof cur === "object" ? cur[key] : undefined;
+        }
+        return cur;
+    }
+    const field = allFields(def).find((f) => f.id === head);
+    const value = state.values[head];
+    if (field?.kind === "items") {
+        if (!rest.length) {
+            return itemsAsMarkdown(field, value, state.values, wizardLang(def));
+        }
+        const totals = itemsTotals(field, value, state.values);
+        return totals[rest[0]];
+    }
+    if (field?.kind === "file" && rest[0] === "speech") {
+        const pieces = state.heard?.[head];
+        // The lines an agent reads and cuts by: "[12.40–15.10] what is said".
+        return pieces
+            ? pieces.map((p) => `[${p.start.toFixed(2)}–${p.end.toFixed(2)}] ${p.text}`).join("\n") ||
+                "(no intelligible speech)"
+            : "";
+    }
+    if (field?.kind === "image" || field?.kind === "file") {
+        // The files themselves are read with read_document / scan_documents by these names.
+        const ids = (Array.isArray(value) ? value : [value]).filter((v) => typeof v === "string" && v.length > 0);
+        return ids.map((id) => `upload:${id}`).join(", ");
+    }
+    if (field?.kind === "location") {
+        if (!isLocationValue(value)) {
+            return "";
+        }
+        switch (rest[0]) {
+            case undefined:
+                return locationText(value);
+            case "map":
+                return value.lat === undefined
+                    ? ""
+                    : `https://www.openstreetmap.org/?mlat=${value.lat}&mlon=${value.lng}#map=17/${value.lat}/${value.lng}`;
+            default:
+                return value[rest[0]];
+        }
+    }
+    if (field?.kind === "audio") {
+        if (!isAudioValue(value)) {
+            return "";
+        }
+        if (rest[0] === "seconds") {
+            return value.seconds;
+        }
+        // A recording reads as what is said in it.
+        return value.transcript?.trim() || "(voice note without intelligible speech)";
+    }
+    if (field?.kind === "signature") {
+        // Documents place it as an image: <img src="asset://ID">.
+        return typeof value === "string" && value ? `asset://${value}` : "";
+    }
+    if (field?.kind === "list") {
+        const list = scope.lists?.[field.list ?? ""];
+        return list ? listAsMarkdown(list.def, list.rows) : "";
+    }
+    if (field?.kind === "toggle") {
+        return value ? "yes" : "no";
+    }
+    return value;
+}
+export function renderTemplate(template, scope) {
+    return template.replace(TEMPLATE_RE, (_m, ref) => stringify(resolveRef(ref.trim(), scope)));
+}
+/** Everything the person entered so far, readable — handed to agents as data. */
+export function answersAsText(scope) {
+    const lines = [];
+    for (const field of allFields(scope.def)) {
+        const value = scope.state.values[field.id];
+        if (value === undefined || value === "" || (Array.isArray(value) && !value.length)) {
+            continue;
+        }
+        lines.push(`### ${field.label}\n${stringify(resolveRef(field.id, scope))}`);
+    }
+    return lines.join("\n\n");
+}

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

@@ -0,0 +1,4 @@
+import { NotedError } from "../model-errors.js";
+/** A step failure the person can read. */
+export class StepError extends NotedError {
+}

package/apps/runtime/dist/env.js

@@ -0,0 +1,295 @@
+import { execFileSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { join, resolve } from "node:path";
+import { findChrome } from "./render/browser-path.js";
+/** Load `.env.local` then `.env` without overriding the real environment. */
+function loadEnvFiles() {
+    for (const name of [".env.local", ".env"]) {
+        const path = resolve(process.cwd(), name);
+        if (!existsSync(path)) {
+            continue;
+        }
+        for (const line of readFileSync(path, "utf8").split("\n")) {
+            const match = line.match(/^\s*([A-Z0-9_]+)\s*=\s*(.*)\s*$/);
+            if (!match || process.env[match[1]] !== undefined) {
+                continue;
+            }
+            process.env[match[1]] = match[2].replace(/^(['"])(.*)\1$/, "$2");
+        }
+    }
+}
+loadEnvFiles();
+const str = (key, fallback = "") => process.env[key]?.trim() || fallback;
+/**
+ * Without `SANDBOX`: Docker when the sandbox image is on this machine, else none.
+ * The image is not published, so a fresh install would otherwise offer a tool that cannot start.
+ */
+function sandboxEngine(image) {
+    const engine = str("SANDBOX");
+    if (str("SANDBOX_ENABLED", "1") !== "1" || engine === "off") {
+        return "off";
+    }
+    if (engine) {
+        return "docker";
+    }
+    return dockerHasImage(image) ? "docker" : "off";
+}
+function dockerHasImage(image) {
+    try {
+        execFileSync("docker", ["image", "inspect", image], { stdio: "ignore", timeout: 5000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** A comma-separated list. */
+const list = (key) => str(key)
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+const num = (key, fallback) => {
+    const v = Number(process.env[key]);
+    return Number.isFinite(v) && v > 0 ? v : fallback;
+};
+const dataDir = resolve(str("DATA_DIR", "data"));
+/**
+ * Signs cookies and links and derives the store's encryption key. A runtime that runs alone
+ * makes its own once and keeps it in the data folder.
+ */
+function appSecret() {
+    const given = str("APP_SECRET");
+    if (given) {
+        return given;
+    }
+    mkdirSync(dataDir, { recursive: true });
+    const file = join(dataDir, "secret");
+    if (!existsSync(file)) {
+        writeFileSync(file, randomBytes(32).toString("hex"), { mode: 0o600 });
+    }
+    return readFileSync(file, "utf8").trim();
+}
+const manageUrl = str("MANAGE_URL").replace(/\/$/, "");
+const port = num("API_PORT", 24368);
+/** From source the Vite dev server on :5181 serves the pages; built, this server does. */
+const fromSource = import.meta.url.endsWith(".ts");
+const sandboxImage = str("SANDBOX_IMAGE", "engenty-sandbox:latest");
+const ROLES = ["studio", "doors", "web", "runner", "all"];
+function role() {
+    const given = str("RUNTIME_ROLE", "all");
+    if (!ROLES.includes(given)) {
+        throw new Error(`RUNTIME_ROLE must be one of ${ROLES.join(", ")}, not "${given}"`);
+    }
+    return given;
+}
+/** The origin people open, e.g. https://wizards.localhost — auth callbacks and links use it. */
+const appUrl = str("APP_URL", fromSource ? "http://localhost:5181" : `http://localhost:${port}`).replace(/\/$/, "");
+export const env = {
+    production: process.env.NODE_ENV === "production",
+    /** Running from source: Vite serves the pages, this server only `/api`. */
+    fromSource,
+    port,
+    /** Listen address; a runtime that runs alone stays on the loopback interface. */
+    host: str("API_HOST", manageUrl ? "0.0.0.0" : "127.0.0.1"),
+    /**
+     * What this process does. `studio`: the makers' half (authoring, publishing, sign-in, MCP, the
+     * studio's pages). `doors`: the customers' half (wizard pages, their API, shared results, the
+     * plugins' public routes). `web`: both halves. `runner`: takes the runs that wait and drives
+     * them (it serves the routes too, for what the web hands it). `all`: everything in one process
+     * (a runtime that runs alone). docs/plans/runner-process.md.
+     */
+    role: role(),
+    /** Which parts this process serves, from its role. */
+    serves: {
+        studio: ["studio", "web", "runner", "all"].includes(role()),
+        doors: ["doors", "web", "runner", "all"].includes(role()),
+        runner: ["runner", "all"].includes(role()),
+    },
+    runner: {
+        /** This runner's name in the control database; a new one each start. */
+        id: `${hostname()}-${randomBytes(3).toString("hex")}`,
+        /** Where the web reaches this runner (the browser's screen of a run it holds). */
+        url: str("RUNNER_URL").replace(/\/$/, ""),
+    },
+    appUrl,
+    /**
+     * Where the wizards' pages live (`/w/<token>`, `/s/<token>`, the embed script): the doors'
+     * origin, when they are served apart from the studio. Links to a wizard, a result or a public
+     * file carry it. Default: APP_URL, the same origin.
+     */
+    publicUrl: str("PUBLIC_URL", appUrl).replace(/\/$/, ""),
+    /** More host names this server answers under, besides APP_URL's and the loopback names. */
+    allowedHosts: list("ALLOWED_HOSTS"),
+    dataDir,
+    /** The control database; empty = a libSQL file in the data folder. */
+    databaseUrl: str("DATABASE_URL", ""),
+    databaseAuthToken: str("DATABASE_AUTH_TOKEN"),
+    /** Tenant databases on a libSQL server: `{tenant}` is replaced by the tenant id. Empty = files. */
+    tenantDbUrlTemplate: str("TENANT_DB_URL_TEMPLATE"),
+    tenantDbAuthToken: str("TENANT_DB_AUTH_TOKEN", str("DATABASE_AUTH_TOKEN")),
+    authSecret: appSecret(),
+    /** Where OAuth providers send people back after connecting an account; default <APP_URL>/api/connect/callback. */
+    connectRedirectUrl: str("CONNECT_REDIRECT_URL"),
+    /** Encrypts connected accounts and kept browser sessions; falls back to the app secret. */
+    storeKey: str("STORE_ENC_KEY"),
+    devLogin: process.env.NODE_ENV !== "production" && str("DEV_LOGIN") === "1",
+    /**
+     * `1`: the studio assistant's developer mode may be switched on here (steps, tools, prompt,
+     * the turns' events). A managed runtime offers it to the platform's admins instead.
+     */
+    assistantDev: str("ASSISTANT_DEV") === "1",
+    /**
+     * The Manage-App this runtime belongs to. Set = people sign in there, tenants come from its
+     * tokens and model calls go through its gateway. Empty = the runtime runs alone with one tenant.
+     */
+    manage: {
+        url: manageUrl,
+        gatewayUrl: str("GATEWAY_URL").replace(/\/$/, ""),
+        clientId: str("MANAGE_CLIENT_ID"),
+        clientSecret: str("MANAGE_CLIENT_SECRET"),
+        /** Authenticates this runtime at the Manage-App and the gateway, and the Manage-App here. */
+        serviceKey: str("MANAGE_SERVICE_KEY"),
+    },
+    /**
+     * A runtime that runs alone answers the studio only with a cookie, set by opening
+     * `/api/local/enter?k=<key>` once. The desktop app passes the key; else one is printed at start.
+     */
+    local: {
+        accessKey: str("LOCAL_ACCESS_KEY"),
+        /** The Manage-App a local runtime links an account to (credits, publishing). */
+        accountUrl: str("ACCOUNT_URL", "https://account.engenty.ai").replace(/\/$/, ""),
+        gatewayUrl: str("ACCOUNT_GATEWAY_URL", "https://gateway.engenty.ai").replace(/\/$/, ""),
+        /** The cloud runtime "publish to the cloud" sends wizards to. */
+        cloudUrl: str("CLOUD_URL", "https://engenty.ai").replace(/\/$/, ""),
+    },
+    /**
+     * The marketplace (docs/marketplace-contract.md): searched live, its starters and what people
+     * starred kept for offline use. `off` = none.
+     */
+    marketplace: {
+        url: str("MARKETPLACE_URL", "https://engenty.ai/wizards")
+            .replace(/^off$/, "")
+            .replace(/\/+$/, ""),
+    },
+    aiGatewayKey: str("AI_GATEWAY_API_KEY"),
+    openaiKey: str("OPENAI_API_KEY"),
+    /** The realtime speech model of live conversations; empty: the runtime's default. */
+    conversationModel: str("CONVERSATION_MODEL"),
+    anthropicKey: str("ANTHROPIC_API_KEY"),
+    googleKey: str("GOOGLE_GENERATIVE_AI_API_KEY"),
+    falKey: str("FAL_KEY"),
+    elevenlabsKey: str("ELEVENLABS_API_KEY"),
+    replicateKey: str("REPLICATE_API_TOKEN"),
+    /** TypeSafe's own API, for the classifier that checks what a search found (Jev). */
+    typesafeKey: str("TYPESAFE_API_KEY"),
+    /**
+     * `off`: agent steps get no `browser_run_fast`, where a decision model would pick each click
+     * on a page. Otherwise they get it wherever a decision model can be reached.
+     */
+    browserFastLoop: str("BROWSER_FAST_LOOP") !== "off",
+    ollamaUrl: str("OLLAMA_URL", "http://127.0.0.1:11434/v1"),
+    /** What each model class runs on when this runtime resolves classes itself (own keys, Ollama). */
+    models: {
+        classifier: str("MODEL_CLASSIFIER", "anthropic/claude-haiku-4.5"),
+        standard: str("MODEL_STANDARD", "anthropic/claude-haiku-4.5"),
+        high: str("MODEL_HIGH", "anthropic/claude-sonnet-5.5"),
+        highest: str("MODEL_HIGHEST", "anthropic/claude-sonnet-5.5"),
+        image: str("MODEL_IMAGE", "google/gemini-3.1-flash-image"),
+        video: str("MODEL_VIDEO", "google/veo-3.1-fast-generate-001"),
+        audio: str("MODEL_AUDIO", "google/gemini-3.5-flash-lite"),
+        speech: str("MODEL_SPEECH", "google/gemini-3.8-flash-tts"),
+        /** Vectors for a project's document index; not a class a step names. */
+        embedding: str("MODEL_EMBEDDING", "openai/text-embedding-3-small"),
+    },
+    /**
+     * Reverse geocoder for location fields (Nominatim's `/reverse`); unset = coordinates only,
+     * nothing about where a person stands leaves this server.
+     */
+    geocoderUrl: str("GEOCODER_URL"),
+    /** CDP endpoint of a Chromium (the engenty-browser image); else a local Chrome is launched. */
+    browserCdpUrl: str("BROWSER_CDP_URL"),
+    /** The browser the setup and `wizards doctor` found (render/browser-path.ts). */
+    chromePath: str("CHROME_PATH", findChrome({ PATH: process.env.PATH }) ??
+        (process.platform === "darwin"
+            ? "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+            : "/usr/bin/chromium")),
+    /** Encodes widget animations to MP4; without it widgets offer no video. */
+    ffmpegPath: str("FFMPEG_PATH", "ffmpeg"),
+    /** What runs an agent's shell and code: a Docker container or nothing. */
+    sandbox: sandboxEngine(sandboxImage),
+    sandboxImage,
+    /** Assets and workspace files in an S3-compatible bucket (R2); empty = the data folder. */
+    s3: {
+        endpoint: str("S3_ENDPOINT").replace(/\/$/, ""),
+        bucket: str("S3_BUCKET"),
+        region: str("S3_REGION", "auto"),
+        accessKeyId: str("S3_ACCESS_KEY_ID"),
+        secretAccessKey: str("S3_SECRET_ACCESS_KEY"),
+    },
+    turnstile: { siteKey: str("TURNSTILE_SITE_KEY"), secret: str("TURNSTILE_SECRET_KEY") },
+    /**
+     * The mobile app (the apps repo engenty-wizards-apps, mobile/): a phone opens this runtime's `/w/` and `/s/` links in it.
+     * Served as /.well-known/apple-app-site-association and /.well-known/assetlinks.json.
+     */
+    mobile: {
+        /** `<team id>.<bundle id>` of the iOS apps; empty = no file. */
+        iosAppIds: list("MOBILE_IOS_APP_IDS"),
+        androidPackage: str("MOBILE_ANDROID_PACKAGE", "ai.engenty.wizards"),
+        /** SHA-256 fingerprints of the Android app's signing certificates; empty = no file. */
+        androidCertSha256: list("MOBILE_ANDROID_CERT_SHA256"),
+    },
+    /** Plugins (docs/content/dev/plugins). Code in these folders runs with the runtime's own rights. */
+    plugins: {
+        /** Folders to look in, besides the `modules/` this runtime ships with. */
+        dirs: list("PLUGINS_DIR").map((dir) => resolve(dir)),
+        /** Managed: plugins every tenant has. The Manage-App switches further ones on per tenant. */
+        defaults: list("PLUGINS_DEFAULT"),
+        /**
+         * A plugin loads again when one of its files changes. Default: on where the runtime runs
+         * alone. A runtime of a Manage-App never reloads: it would hit every tenant.
+         */
+        watch: !manageUrl && str("PLUGINS_WATCH", "1") === "1",
+        /** Plugins' jobs (`server.every`) run. Off (`PLUGIN_JOBS=0`) where another process runs them. */
+        jobs: str("PLUGIN_JOBS", "1") === "1",
+        /**
+         * Public keys (Ed25519, SPKI DER in base64) whose signature a Pro module may carry, besides
+         * the one this runtime ships with (plugins/pro-keys.ts). For testing packages signed elsewhere.
+         */
+        proKeys: list("PRO_MODULES_KEYS"),
+    },
+    limits: {
+        visitorRunsPerHour: num("LIMIT_VISITOR_RUNS_PER_HOUR", 6),
+        defaultDailyRuns: num("LIMIT_DEFAULT_DAILY_RUNS", 50),
+        /** Runs of one tenant that work at the same time; the Manage-App can set another number per tenant. */
+        concurrentRuns: num("LIMIT_CONCURRENT_RUNS", 4),
+        /**
+         * Projects a tenant works with. One: the studio shows no project switcher. The Manage-App
+         * can set another number per tenant; the database holds any number either way.
+         */
+        projects: num("LIMIT_PROJECTS", 1),
+        /** Wizards a local install may keep on this runtime in its synced project. */
+        syncedWizards: num("LIMIT_SYNCED_WIZARDS", 50),
+        /** End-user runs (no account) and their shared links are deleted after this many days. */
+        resultTtlDays: num("RESULT_TTL_DAYS", 7),
+        /** What a wizard keeps for a person (lists, files, accounts) goes when unused this long. */
+        storeTtlDays: num("STORE_TTL_DAYS", 400),
+    },
+};
+/**
+ * The path APP_URL ends in: `/wizards` for https://example.com/wizards, empty for an origin alone. The proxy
+ * may strip it or not, so the server takes both; what it writes into a cookie or a redirect
+ * carries it.
+ */
+export const basePath = new URL(env.appUrl).pathname.replace(/\/+$/, "");
+if (env.production) {
+    const required = [
+        "APP_URL",
+        ...(manageUrl ? ["APP_SECRET", "MANAGE_SERVICE_KEY", "MANAGE_CLIENT_ID"] : []),
+    ];
+    const missing = required.filter((k) => !process.env[k]?.trim());
+    if (missing.length) {
+        throw new Error(`Missing required environment in production: ${missing.join(", ")}`);
+    }
+}