@engenty/wizards-runtime 0.0.0-stage → 0.7.5

package/apps/runtime/dist/routes/wizard-stream.js

@@ -0,0 +1,30 @@
+import { Hono } from "hono";
+import { streamSSE } from "hono/streaming";
+import { subscribeDraft } from "../services/draft-events.js";
+import { ownedWizard } from "../services/wizards.js";
+/**
+ * Live changes to a wizard the editor has open — from an MCP client, the architect or another
+ * tab. The editor refetches on `change`; `hello` carries the revision to catch up after a gap.
+ */
+export const wizardStream = new Hono().get("/:id/stream", async (c) => {
+    const w = await ownedWizard(c.get("user").id, c.req.param("id"));
+    return streamSSE(c, async (stream) => {
+        let closed = false;
+        const unsubscribe = subscribeDraft(w.id, (change) => {
+            if (!closed) {
+                void stream.writeSSE({ event: "change", data: JSON.stringify(change) });
+            }
+        });
+        stream.onAbort(() => {
+            closed = true;
+            unsubscribe();
+        });
+        await stream.writeSSE({ event: "hello", data: JSON.stringify({ revision: w.revision }) });
+        while (!closed) {
+            await stream.sleep(20_000);
+            if (!closed) {
+                await stream.writeSSE({ event: "ping", data: "" });
+            }
+        }
+    });
+});

package/apps/runtime/dist/running.js

@@ -0,0 +1,39 @@
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+const FILE = "running.json";
+export function writeRunning(dataDir, running) {
+    mkdirSync(dataDir, { recursive: true });
+    writeFileSync(join(dataDir, FILE), `${JSON.stringify(running, null, 2)}\n`, { mode: 0o600 });
+}
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM: the process exists and belongs to somebody else.
+        return error.code === "EPERM";
+    }
+}
+/** The runtime that holds this data folder, if its process still exists. */
+export function readRunning(dataDir) {
+    try {
+        const running = JSON.parse(readFileSync(join(dataDir, FILE), "utf8"));
+        return Number.isInteger(running.pid) && alive(running.pid) ? running : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Takes the note away, unless another runtime wrote it meanwhile. */
+export function clearRunning(dataDir, pid = process.pid) {
+    try {
+        const running = JSON.parse(readFileSync(join(dataDir, FILE), "utf8"));
+        if (running.pid === pid) {
+            rmSync(join(dataDir, FILE), { force: true });
+        }
+    }
+    catch {
+        // nothing there
+    }
+}

package/apps/runtime/dist/sandbox/docker.js

@@ -0,0 +1,75 @@
+import { DockerSandbox } from "@mastra/docker";
+/** The image's own working directory, the one its unprivileged user may write to. */
+const WORKDIR = "/sandbox";
+/** Bytes per append when a file is written through the shell; stays far below ARG_MAX. */
+const WRITE_CHUNK = 48 * 1024;
+/** What the engenty-sandbox image carries. The container sits on Docker's default bridge. */
+export const DOCKER_CAPABILITIES = {
+    commands: ["bash", "python3", "pip", "uv", "node", "npm", "bun", "jq", "curl", "git", "unzip"],
+    network: "open internet",
+    uses: "calculations, charts or file conversion",
+    workdir: WORKDIR,
+};
+const quote = (value) => `'${value.replaceAll("'", `'\\''`)}'`;
+/** One container per run through the host's Docker. */
+export class DockerRunSandbox {
+    runId;
+    image;
+    capabilities = DOCKER_CAPABILITIES;
+    container = null;
+    constructor(runId, image) {
+        this.runId = runId;
+        this.image = image;
+    }
+    start() {
+        this.container ??= (async () => {
+            const sandbox = new DockerSandbox({
+                id: `wizards-${this.runId.toLowerCase()}`,
+                image: this.image,
+                memory: 1024 * 1024 * 1024,
+                pidsLimit: 256,
+                capDrop: ["ALL"],
+                securityOpt: ["no-new-privileges"],
+                workingDir: WORKDIR,
+                labels: { "engenty-wizards.run": this.runId },
+            });
+            await sandbox.start();
+            return sandbox;
+        })();
+        return this.container;
+    }
+    async exec(command, options = {}) {
+        const sandbox = await this.start();
+        const result = await sandbox.executeCommand(command, [], {
+            timeout: options.timeoutMs,
+            cwd: options.cwd,
+            env: options.env,
+        });
+        return { exitCode: result.exitCode, stdout: result.stdout, stderr: result.stderr };
+    }
+    async writeFile(path, data) {
+        const target = quote(path);
+        const bytes = typeof data === "string" ? Buffer.from(data, "utf8") : Buffer.from(data);
+        await this.must(`mkdir -p "$(dirname ${target})" && : > ${target}`);
+        for (let at = 0; at < bytes.length; at += WRITE_CHUNK) {
+            const chunk = bytes.subarray(at, at + WRITE_CHUNK).toString("base64");
+            await this.must(`printf %s ${chunk} | base64 -d >> ${target}`);
+        }
+    }
+    async readFile(path) {
+        const result = await this.must(`base64 -w0 ${quote(path)}`);
+        return Buffer.from(result.stdout.trim(), "base64");
+    }
+    async must(command) {
+        const result = await this.exec(command);
+        if (result.exitCode !== 0) {
+            throw new Error(result.stderr.trim() || `exit code ${result.exitCode}`);
+        }
+        return result;
+    }
+    async destroy() {
+        const container = this.container;
+        this.container = null;
+        await (await container?.catch(() => null))?.destroy();
+    }
+}

package/apps/runtime/dist/sandbox/index.js

@@ -0,0 +1,23 @@
+import { env } from "../env.js";
+import { DOCKER_CAPABILITIES, DockerRunSandbox } from "./docker.js";
+/** What this server's sandbox runs, or null when it is switched off. */
+export function sandboxCapabilities() {
+    if (env.sandbox === "off") {
+        return null;
+    }
+    return DOCKER_CAPABILITIES;
+}
+export function createSandbox(runId) {
+    if (env.sandbox === "off") {
+        throw new Error("The sandbox is switched off on this server.");
+    }
+    return new DockerRunSandbox(runId, env.sandboxImage);
+}
+export function shellToolDescription(caps) {
+    return `Run a shell command in a private Linux sandbox (${caps.commands.join(", ")}). Working directory ${caps.workdir}. Network: ${caps.network}.`;
+}
+/** The authoring guide's line about the sandbox tool. */
+export function sandboxGuideLine() {
+    const uses = (sandboxCapabilities() ?? DOCKER_CAPABILITIES).uses;
+    return `- The sandbox runs code (python/node) for ${uses}; export_file hands files to the person.`;
+}

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

@@ -0,0 +1 @@
+export {};

package/apps/runtime/dist/secrets/crypto.js

@@ -0,0 +1,28 @@
+import { createCipheriv, createDecipheriv, hkdfSync, randomBytes } from "node:crypto";
+import { env } from "../env.js";
+/** AES-256-GCM for what the store keeps secret (account tokens, passwords, browser sessions). */
+const key = Buffer.from(hkdfSync("sha256", env.storeKey || env.authSecret, "engenty-wizards", "store-secrets", 32));
+export function seal(value) {
+    const iv = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", key, iv);
+    const body = Buffer.concat([cipher.update(JSON.stringify(value), "utf8"), cipher.final()]);
+    return `v1.${iv.toString("base64url")}.${cipher.getAuthTag().toString("base64url")}.${body.toString("base64url")}`;
+}
+export function unseal(sealed) {
+    const [version, iv, tag, body] = sealed.split(".");
+    if (version !== "v1" || !iv || !tag || !body) {
+        return null;
+    }
+    try {
+        const decipher = createDecipheriv("aes-256-gcm", key, Buffer.from(iv, "base64url"));
+        decipher.setAuthTag(Buffer.from(tag, "base64url"));
+        const plain = Buffer.concat([
+            decipher.update(Buffer.from(body, "base64url")),
+            decipher.final(),
+        ]);
+        return JSON.parse(plain.toString("utf8"));
+    }
+    catch {
+        return null;
+    }
+}

package/apps/runtime/dist/secrets/signing.js

@@ -0,0 +1,52 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { env } from "../env.js";
+/** The query the signature covers: everything but exp/sig, sorted, so parameter order never matters. */
+function payload(url, exp) {
+    const params = [...url.searchParams.entries()]
+        .filter(([k]) => k !== "exp" && k !== "sig")
+        .sort(([a], [b]) => a.localeCompare(b));
+    return `${url.pathname}?${new URLSearchParams(params)}|${exp}`;
+}
+function sign(data) {
+    return createHmac("sha256", env.authSecret).update(data).digest("base64url");
+}
+/**
+ * A link that opens one GET path without a session — for clients that have no studio cookie,
+ * such as an MCP client handing a download to the admin.
+ */
+export function signedUrl(path, ttlSeconds = 3600) {
+    const url = new URL(path, env.appUrl);
+    const exp = String(Math.floor(Date.now() / 1000) + ttlSeconds);
+    url.searchParams.set("exp", exp);
+    url.searchParams.set("sig", sign(payload(url, exp)));
+    return url.toString();
+}
+function sameSignature(data, sig) {
+    const expected = Buffer.from(sign(data));
+    const given = Buffer.from(sig);
+    return expected.length === given.length && timingSafeEqual(expected, given);
+}
+export function verifySignedUrl(href) {
+    const url = new URL(href, env.appUrl);
+    const exp = url.searchParams.get("exp");
+    const sig = url.searchParams.get("sig");
+    if (!exp || !sig || Number(exp) * 1000 < Date.now()) {
+        return false;
+    }
+    return sameSignature(payload(url, exp), sig);
+}
+/**
+ * A ticket to one run's routes without a session: the widget an AI app shows runs on the host's
+ * origin and reaches the run with it. Sent as `?rt=`, since an EventSource sends no headers.
+ */
+export function runTicket(runId, ttlSeconds = 12 * 3600) {
+    const exp = String(Math.floor(Date.now() / 1000) + ttlSeconds);
+    return `${exp}.${sign(`run:${runId}|${exp}`)}`;
+}
+export function runTicketValid(runId, ticket) {
+    const [exp, sig] = (ticket ?? "").split(".");
+    if (!exp || !sig || Number(exp) * 1000 < Date.now()) {
+        return false;
+    }
+    return sameSignature(`run:${runId}|${exp}`, sig);
+}

package/apps/runtime/dist/secrets/vault.js

@@ -0,0 +1,59 @@
+import { execFile } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { env } from "../env.js";
+import { seal, unseal } from "./crypto.js";
+const run = promisify(execFile);
+/**
+ * Secrets of a runtime that runs alone: the keys the person entered and the linked account's
+ * refresh token. In the desktop app (`SECRETS=keychain`) they live in the macOS Keychain, never
+ * in the database; elsewhere in an encrypted file in the data folder.
+ */
+const SERVICE = "engenty-wizards";
+const keychain = process.env.SECRETS === "keychain" && process.platform === "darwin";
+const file = join(env.dataDir, "vault");
+function readFileVault() {
+    if (!existsSync(file)) {
+        return {};
+    }
+    return unseal(readFileSync(file, "utf8").trim()) ?? {};
+}
+function writeFileVault(all) {
+    writeFileSync(file, seal(all), { mode: 0o600 });
+}
+export async function vaultGet(name) {
+    if (!keychain) {
+        return readFileVault()[name] ?? null;
+    }
+    try {
+        const { stdout } = await run("security", [
+            "find-generic-password",
+            "-s",
+            SERVICE,
+            "-a",
+            name,
+            "-w",
+        ]);
+        return stdout.replace(/\n$/, "") || null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function vaultSet(name, value) {
+    if (!keychain) {
+        writeFileVault({ ...readFileVault(), [name]: value });
+        return;
+    }
+    await run("security", ["add-generic-password", "-U", "-s", SERVICE, "-a", name, "-w", value]);
+}
+export async function vaultDelete(name) {
+    if (!keychain) {
+        const all = readFileVault();
+        delete all[name];
+        writeFileVault(all);
+        return;
+    }
+    await run("security", ["delete-generic-password", "-s", SERVICE, "-a", name]).catch(() => undefined);
+}

package/apps/runtime/dist/services/access.js

@@ -0,0 +1,88 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { note } from "@engenty-wizards/shared/run";
+import { and, eq } from "drizzle-orm";
+import { db, schema } from "../db/client.js";
+import { managed, tenantInfo } from "../manage.js";
+import { currentTenant } from "../tenants/tenant.js";
+import { ServiceError } from "./errors.js";
+/**
+ * Who may change what on this runtime. A project a local install synced (`origin: "local"`) is
+ * changed only by that install's next sync: here it is shown and run. And a tenant the
+ * Manage-App gives no building (`limits.build: false`) makes and changes nothing on this
+ * runtime. Every write of a project or a wizard asks here, whichever way it came in: studio,
+ * MCP client or API.
+ */
+const sync = new AsyncLocalStorage();
+/** Runs the writes of a sync: they are the one way a synced project changes. */
+export function asSync(fn) {
+    return sync.run(true, fn);
+}
+const syncing = () => sync.getStore() === true;
+// --- roles -----------------------------------------------------------------------------
+// In a team, an owner or admin makes and deletes (wizards, spaces, connectors); a member edits
+// the wizards there are. A runtime that runs alone has one person, who does everything.
+const actor = new AsyncLocalStorage();
+/** Runs a request as the person's role in the tenant; set once per entry, like the tenant. */
+export function asRole(role, fn) {
+    return actor.run(role, fn);
+}
+/** The role of who acts now. A context without one (a job, a sync) acts as the owner. */
+export function currentRole() {
+    return actor.getStore() ?? "owner";
+}
+export const isAdminRole = (role) => role === "owner" || role === "admin";
+export const MEMBERS_EDIT_ONLY = note("onlyTeamAdmins");
+/** Refuses a member: making and deleting is for the owner and the admins of the team. */
+export async function requireAdmin() {
+    if (syncing() || !managed || isAdminRole(currentRole())) {
+        return;
+    }
+    throw new ServiceError("forbidden", MEMBERS_EDIT_ONLY);
+}
+/** Whether the person makes and deletes here: builds at all, and is no mere member. */
+export async function mayCreate() {
+    return (await mayBuild()) && (!managed || isAdminRole(currentRole()));
+}
+/** Whether the tenant builds wizards on this runtime. A runtime that runs alone always does. */
+export async function mayBuild() {
+    if (!managed) {
+        return true;
+    }
+    const info = await tenantInfo(currentTenant()).catch(() => null);
+    // An older Manage-App does not say: then it builds. One that cannot be reached: nothing changes.
+    return info ? info.limits.build !== false : false;
+}
+export const READ_ONLY_PROJECT = note("spaceEditedLocally");
+export const READ_ONLY_TENANT = note("wizardsRunOncePublished");
+/** Refuses when the tenant builds nothing here. */
+export async function requireBuild() {
+    if (syncing() || (await mayBuild())) {
+        return;
+    }
+    throw new ServiceError("read_only", READ_ONLY_TENANT);
+}
+/** Refuses a change of a synced project, and any change by a tenant that builds nothing here. */
+export async function requireWritable(project) {
+    if (syncing()) {
+        return;
+    }
+    if (project.origin === "local") {
+        throw new ServiceError("read_only", READ_ONLY_PROJECT);
+    }
+    await requireBuild();
+}
+export async function requireWritableProject(projectId) {
+    if (syncing()) {
+        return;
+    }
+    const project = await db.query.project.findFirst({
+        where: and(eq(schema.project.id, projectId), eq(schema.project.tenantId, currentTenant())),
+        columns: { origin: true },
+    });
+    // A project that is not there is the caller's "not found", not ours.
+    await requireWritable(project ?? { origin: null });
+}
+/** Whether the person may change this project's wizards and settings here. */
+export async function projectWritable(project) {
+    return project.origin !== "local" && (await mayBuild());
+}

package/apps/runtime/dist/services/api.js

@@ -0,0 +1,248 @@
+import { textLang, wizardLang, } from "@engenty-wizards/shared/definition";
+import { standaloneEntry } from "@engenty-wizards/shared/fit";
+import { pluginsOf } from "@engenty-wizards/shared/marketplace";
+import { noteText } from "@engenty-wizards/shared/run";
+import { and, count, desc, eq, gte, inArray, isNotNull, or, sql } from "drizzle-orm";
+import { MICROS_PER_CREDIT } from "../credits/credits.js";
+import { db, schema } from "../db/client.js";
+import { env } from "../env.js";
+import { wizardUnavailable } from "../limits.js";
+import { codeOf } from "../tenants/control.js";
+import { currentTenant } from "../tenants/tenant.js";
+import { serverText } from "../texts.js";
+import { mayBuild, projectWritable, READ_ONLY_TENANT } from "./access.js";
+import { mainLogoId } from "./brand.js";
+import { notFound, ServiceError } from "./errors.js";
+import { knowledgeCounts } from "./knowledge.js";
+import { listProjects, ownedProject } from "./projects.js";
+import { runReport } from "./runs.js";
+import { shareUrlFor } from "./shares.js";
+import { shareUrl, studioUrl } from "./wizards.js";
+/** The spaces the caller works with, as the studio lists them, and whether each may change here. */
+export async function apiSpaces(userId) {
+    const projects = await listProjects(userId);
+    return Promise.all(projects.map(async (p) => ({
+        id: p.id,
+        name: p.name,
+        title: p.brand.name ?? "",
+        wizards: p.wizardCount,
+        writable: await projectWritable(p),
+    })));
+}
+/** The space a call names, or the one a caller means when it names none: the first one listed. */
+export async function apiSpace(userId, spaceId) {
+    if (spaceId) {
+        return ownedProject(userId, spaceId);
+    }
+    const [first] = await listProjects(userId);
+    if (!first) {
+        // A plan that builds nothing here has a space only once its local install synced one.
+        if (!(await mayBuild())) {
+            throw new ServiceError("read_only", READ_ONLY_TENANT);
+        }
+        throw notFound();
+    }
+    return first;
+}
+/** The space's own details: what it says about itself, and what its wizards look things up in. */
+export async function apiSpaceDetails(userId, spaceId) {
+    const p = await apiSpace(userId, spaceId);
+    const logo = await mainLogoId(p.id);
+    return {
+        id: p.id,
+        name: p.name,
+        title: p.brand.name ?? "",
+        about: p.brand.about ?? "",
+        colors: p.brand.colors ?? [],
+        facts: p.facts.map(({ label, value }) => ({ label, value })),
+        logoUrl: logo ? `${env.publicUrl}/api/public/logos/${logo}` : null,
+        knowledge: await knowledgeCounts(p.id),
+        writable: await projectWritable(p),
+        studioUrl: `${env.appUrl}/studio/space`,
+    };
+}
+/**
+ * The wizards of the caller's spaces, newest change first. A published one carries what a website
+ * embeds it with: its link's token and the ID the mobile app takes.
+ */
+export async function apiWizards(userId, spaceId) {
+    const spaces = (await listProjects(userId)).filter((p) => !spaceId || p.id === spaceId);
+    if (!spaces.length) {
+        return [];
+    }
+    const rows = await db.query.wizard.findMany({
+        where: and(eq(schema.wizard.tenantId, currentTenant()), inArray(schema.wizard.projectId, spaces.map((p) => p.id))),
+        orderBy: [desc(schema.wizard.updatedAt)],
+    });
+    const published = rows.filter((w) => w.publishedVersion !== null);
+    const versions = published.length
+        ? await db.query.wizardVersion.findMany({
+            where: or(...published.map((w) => and(eq(schema.wizardVersion.wizardId, w.id), eq(schema.wizardVersion.version, w.publishedVersion)))),
+            columns: { wizardId: true, definition: true },
+        })
+        : [];
+    return Promise.all(rows.map(async (w) => {
+        const live = versions.find((v) => v.wizardId === w.id)?.definition;
+        const def = live ?? w.draft;
+        const reason = live ? await wizardUnavailable(w) : null;
+        return {
+            id: w.id,
+            spaceId: w.projectId,
+            title: def.title,
+            description: def.description ?? "",
+            avatar: def.avatar ?? null,
+            published: Boolean(live),
+            publishedVersion: w.publishedVersion,
+            token: live ? w.shareToken : null,
+            code: live ? await codeOf(w.shareToken) : null,
+            shareUrl: live ? shareUrl(w.shareToken) : null,
+            shareEnabled: w.shareEnabled,
+            iconUrl: live
+                ? `${env.publicUrl}/api/public/wizards/${w.shareToken}/icons/icon-192.png`
+                : null,
+            available: Boolean(live) && !reason,
+            unavailableReason: reason && noteText(reason, wizardLang(def)),
+            dailyRunLimit: w.dailyRunLimit,
+            /** The plugins its steps call: a wizard that books needs `appointments`. */
+            plugins: pluginsOf(def),
+            /** Whether it runs on a website by itself, in the gallery's words (packages/shared/src/fit.ts). */
+            standalone: standaloneEntry(def),
+            studioUrl: studioUrl(w.id),
+            updatedAt: w.updatedAt.toISOString(),
+        };
+    }));
+}
+/** A value as one line of text, in the wizard's language: what the person typed or picked. */
+function answerText(field, value, lang) {
+    if (value === undefined || value === null || value === "") {
+        return "";
+    }
+    if (typeof value === "boolean") {
+        return serverText(lang, value ? "yes" : "no");
+    }
+    if (typeof value === "string" || typeof value === "number") {
+        return String(value);
+    }
+    if (Array.isArray(value)) {
+        if (["file", "image", "audio", "signature"].includes(field.kind)) {
+            return serverText(lang, "fileCount", { count: value.length });
+        }
+        return value
+            .map((v) => (typeof v === "object" && v ? Object.values(v).join(" ") : String(v)))
+            .join(", ");
+    }
+    if (typeof value === "object") {
+        const v = value;
+        const said = v.label ?? v.address ?? v.text ?? v.name ?? v.start;
+        return typeof said === "string" ? said : JSON.stringify(value).slice(0, 200);
+    }
+    return "";
+}
+/** What the person answered on the run's pages, by the fields' labels, in the order asked. */
+function answersOf(run) {
+    const answers = [];
+    const lang = textLang(wizardLang(run.definition));
+    for (const step of run.definition.steps) {
+        if (step.type !== "page") {
+            continue;
+        }
+        for (const field of step.fields) {
+            const value = answerText(field, run.state.values[field.id], lang);
+            if (value) {
+                answers.push({ field: field.id, label: field.label, kind: field.kind, value });
+            }
+        }
+    }
+    return answers;
+}
+/** The person's address where a page asked for one: the first e-mail field answered. */
+function emailOf(answers) {
+    return (answers.find((a) => a.kind === "email")?.value ??
+        answers.find((a) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(a.value))?.value ??
+        null);
+}
+const PAGE = 50;
+/** The live runs of the caller's wizards, newest first, by pages of 50: what visitors left. */
+export async function apiRuns(userId, filter = {}) {
+    const wizards = await apiWizards(userId, filter.spaceId);
+    const ids = wizards.map((w) => w.id).filter((id) => !filter.wizardId || id === filter.wizardId);
+    const page = Math.max(1, filter.page ?? 1);
+    if (!ids.length) {
+        return { runs: [], page, pages: 0, total: 0 };
+    }
+    const q = filter.q?.trim().toLowerCase();
+    const like = q ? `%${q.replace(/[\\%_]/g, (c) => `\\${c}`)}%` : null;
+    const status = filter.status ?? "done";
+    const where = and(inArray(schema.run.wizardId, ids), eq(schema.run.mode, "live"), status === "done"
+        ? eq(schema.run.status, "done")
+        : status === "open"
+            ? inArray(schema.run.status, ["waiting_input", "running"])
+            : undefined, filter.days
+        ? gte(schema.run.createdAt, new Date(Date.now() - filter.days * 86_400_000))
+        : undefined, like
+        ? or(sql `lower(${schema.run.state}) like ${like} escape '\\'`, sql `lower(coalesce(${schema.run.origin}, '')) like ${like} escape '\\'`)
+        : undefined);
+    const [{ total }] = await db.select({ total: count() }).from(schema.run).where(where);
+    const rows = await db.query.run.findMany({
+        where,
+        orderBy: [desc(schema.run.createdAt)],
+        limit: PAGE,
+        offset: (page - 1) * PAGE,
+    });
+    const assets = rows.length
+        ? await db
+            .select({ runId: schema.asset.runId, n: count() })
+            .from(schema.asset)
+            .where(and(isNotNull(schema.asset.runId), inArray(schema.asset.runId, rows.map((r) => r.id))))
+            .groupBy(schema.asset.runId)
+        : [];
+    return {
+        runs: rows.map((r) => {
+            const answers = answersOf(r);
+            return {
+                id: r.id,
+                wizardId: r.wizardId,
+                wizard: wizards.find((w) => w.id === r.wizardId)?.title ?? r.definition.title,
+                status: r.status,
+                step: r.definition.steps.find((s) => s.id === r.cursor)?.title ?? null,
+                createdAt: r.createdAt.toISOString(),
+                updatedAt: r.updatedAt.toISOString(),
+                origin: r.origin,
+                email: emailOf(answers),
+                /** The first answers, for a line in a list. */
+                summary: answers
+                    .slice(0, 3)
+                    .map((a) => a.value)
+                    .join(" · ")
+                    .slice(0, 200),
+                credits: Math.ceil(r.costMicros / MICROS_PER_CREDIT),
+                files: assets.find((a) => a.runId === r.id)?.n ?? 0,
+            };
+        }),
+        page,
+        pages: Math.ceil(total / PAGE),
+        total,
+    };
+}
+/** One run with everything a reader of the result needs: the answers, the outputs, the downloads. */
+export async function apiRun(userId, runId) {
+    // Refuses what is no live run of the tenant.
+    const report = await runReport(userId, runId, 0, "live");
+    const run = await db.query.run.findFirst({
+        where: and(eq(schema.run.id, runId), eq(schema.run.tenantId, currentTenant())),
+    });
+    if (!run) {
+        throw notFound();
+    }
+    const answers = answersOf(run);
+    return {
+        ...report,
+        wizard: run.definition.title,
+        createdAt: run.createdAt.toISOString(),
+        updatedAt: run.updatedAt.toISOString(),
+        origin: run.origin,
+        email: emailOf(answers),
+        answers: answers.map(({ label, kind, value }) => ({ label, kind, value })),
+        shareUrl: run.shareToken ? shareUrlFor(run.shareToken) : null,
+    };
+}