wizards 0.1.9

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

@@ -0,0 +1,42 @@
+import { writeStoreFile } from "../store/index.js";
+export const TEXT_LIMIT = 8000;
+export function clip(s, limit = TEXT_LIMIT) {
+    return s.length > limit ? `${s.slice(0, limit)}\n…[truncated ${s.length - limit} chars]` : s;
+}
+/** A tool failure is something the model reads and reacts to, never a crashed step. */
+export async function attempt(run) {
+    try {
+        return await run();
+    }
+    catch (err) {
+        return { error: String(err?.message ?? err).slice(0, 400) };
+    }
+}
+/**
+ * Files a step collects go two places: the wizard's store (kept for next time) and the step's
+ * result (this run's download). One keeper per step, so a file saved twice is one result.
+ */
+export class FileKeeper {
+    ctx;
+    assets;
+    kept = new Map();
+    constructor(ctx, assets) {
+        this.ctx = ctx;
+        this.assets = assets;
+    }
+    async keep(rawPath, data, meta) {
+        const scope = this.ctx.store;
+        const file = await writeStoreFile(scope, rawPath, data, meta);
+        if (!this.kept.has(file.path)) {
+            const ref = await this.ctx.saveAsset({
+                kind: "file",
+                mime: file.mime,
+                name: file.path.split("/").pop() ?? "file",
+                data,
+            });
+            this.kept.set(file.path, ref);
+            this.assets.push(ref);
+        }
+        return { path: file.path, mime: file.mime, size: file.size };
+    }
+}

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

@@ -0,0 +1,238 @@
+import { allFields } from "@engenty-wizards/shared/definition";
+import { TableColumnValueError } from "@engenty-wizards/shared/engenty/data-tables";
+import { createTool } from "@mastra/core/tools";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+import { db, schema } from "../db/client.js";
+import { parseDocument, scanDocument } from "../documents/parse.js";
+import { loadAsset } from "../files/storage.js";
+import { deleteRows, listRows, readStoreFile, saveRows, storeFiles } from "../store/index.js";
+import { attempt, clip } from "./shared.js";
+/** Files the person gave on earlier pages: `upload:<id>` is how tools address them. */
+export async function personUploads(ctx) {
+    const out = [];
+    for (const field of allFields(ctx.def)) {
+        if (field.kind !== "image" && field.kind !== "file") {
+            continue;
+        }
+        const value = ctx.state.values[field.id];
+        const ids = (Array.isArray(value) ? value : [value]).filter((v) => typeof v === "string" && v.length > 0);
+        for (const id of ids) {
+            const row = await db.query.asset.findFirst({ where: eq(schema.asset.id, id) });
+            if (row?.runId === ctx.runId) {
+                out.push({ ref: `upload:${id}`, name: row.name, mime: row.mime, field: field.label });
+            }
+        }
+    }
+    return out;
+}
+/** A file by the name agents use: `upload:<id>` (given by the person) or a path in the store. */
+export async function resolveFile(ctx, file) {
+    if (file.startsWith("upload:")) {
+        const found = await loadAsset(file.slice("upload:".length));
+        if (!found || found.row.runId !== ctx.runId) {
+            throw new Error(`No upload ${file}.`);
+        }
+        return { data: new Uint8Array(found.data), name: found.row.name, mime: found.row.mime };
+    }
+    const stored = await readStoreFile(ctx.store, file);
+    if (!stored) {
+        throw new Error(`No file "${file}". Use files_list to see what is kept.`);
+    }
+    return {
+        data: new Uint8Array(stored.data),
+        name: stored.file.path.split("/").pop() ?? stored.file.path,
+        mime: stored.file.mime,
+    };
+}
+function describeColumns(def) {
+    return def.columns
+        .map((c) => {
+        const rule = c.type === "date"
+            ? c.format.kind === "date"
+                ? "YYYY-MM-DD"
+                : c.format.kind
+            : c.type === "number"
+                ? c.format.style === "currency"
+                    ? `number, ${c.format.currency}`
+                    : "number"
+                : c.type === "select"
+                    ? `one of: ${c.format.options.map((o) => o.id).join(", ")}${c.format.allowCustom ? " (or your own)" : ""}`
+                    : c.type;
+        return `${c.id} (${rule}${c.required ? ", required" : ""})`;
+    })
+        .join("; ");
+}
+/**
+ * What every agent step can do with the wizard's store and the person's files: read and write
+ * the lists, read documents (PDF, scans, photos, Word, Excel, CSV, saved mails).
+ */
+export function storeTools(ctx, uploads, keeper) {
+    const tools = {};
+    const lists = ctx.def.lists ?? [];
+    const charge = (usd) => ctx.chargeUsd(usd);
+    if (lists.length) {
+        const listId = z.enum(lists.map((l) => l.id));
+        const defOf = (id) => lists.find((l) => l.id === id);
+        const catalog = lists
+            .map((l) => `- ${l.id} — ${l.title}${l.key ? ` (rows are matched on "${l.key}")` : ""}: ${describeColumns(l)}`)
+            .join("\n");
+        tools.list_read = createTool({
+            id: "list_read",
+            description: `Read one of the lists this wizard keeps for the person between runs.\n${catalog}`,
+            inputSchema: z.object({ list: listId }),
+            execute: ({ list }) => attempt(async () => {
+                const rows = await listRows(ctx.store, list);
+                return {
+                    list,
+                    total: rows.length,
+                    rows: rows.slice(0, 300).map((r) => ({ id: r.id, ...r.cells })),
+                };
+            }),
+        });
+        tools.list_write = createTool({
+            id: "list_write",
+            description: `Save rows into one of the wizard's lists, so the next run knows them. A row whose key column matches an existing row updates that row (only the columns you give change); otherwise it is added. Values must fit the column: dates as YYYY-MM-DD, numbers as numbers.\n${catalog}`,
+            inputSchema: z.object({
+                list: listId,
+                rows: z
+                    .array(z.record(z.string(), z.unknown()))
+                    .max(200)
+                    .optional()
+                    .describe("Rows as { columnId: value }."),
+                delete: z
+                    .array(z.string())
+                    .max(200)
+                    .optional()
+                    .describe("Rows to remove: their key column's value, or their id."),
+            }),
+            execute: ({ list, rows, delete: remove }) => attempt(async () => {
+                const def = defOf(list);
+                try {
+                    const saved = rows?.length
+                        ? await saveRows(ctx.store, def, rows)
+                        : { added: 0, updated: 0 };
+                    const deleted = remove?.length ? await deleteRows(ctx.store, def, remove) : 0;
+                    await ctx.emit("tool", `Merkt sich ${def.title}`);
+                    return { ...saved, deleted };
+                }
+                catch (err) {
+                    if (err instanceof TableColumnValueError) {
+                        return {
+                            error: `Column "${err.columnId}": ${err.message}. Nothing after that row was saved.`,
+                        };
+                    }
+                    throw err;
+                }
+            }),
+        });
+    }
+    tools.files_list = createTool({
+        id: "files_list",
+        description: "List the files this wizard keeps for the person (invoices collected on earlier runs, scans …), optionally only one folder.",
+        inputSchema: z.object({ folder: z.string().optional() }),
+        execute: ({ folder }) => attempt(async () => {
+            const files = await storeFiles(ctx.store, folder);
+            return {
+                total: files.length,
+                files: files.slice(0, 300).map((f) => ({
+                    path: f.path,
+                    mime: f.mime,
+                    size: f.size,
+                    source: f.source,
+                    date: f.updatedAt.slice(0, 10),
+                })),
+            };
+        }),
+    });
+    if (uploads.length) {
+        tools.files_keep = createTool({
+            id: "files_keep",
+            description: "Keep files the person gave in the wizard's files, several at once: each is stored under `path`, is there on the next run and belongs to this step's result. Returns the path each file now has.",
+            inputSchema: z.object({
+                items: z
+                    .array(z.object({
+                    file: z.string().describe("An upload reference, upload:<id>."),
+                    path: z.string().describe("e.g. belege/2026-09/2026-09-03_Notion_INV-123.pdf"),
+                }))
+                    .min(1)
+                    .max(40),
+            }),
+            execute: ({ items }) => attempt(async () => {
+                await ctx.emit("tool", `Legt ${items.length} Dateien ab`);
+                const kept = [];
+                for (const item of items) {
+                    try {
+                        const source = await resolveFile(ctx, item.file);
+                        const file = await keeper.keep(item.path, source.data, {
+                            mime: source.mime,
+                            source: `Von der Person: ${source.name}`,
+                        });
+                        kept.push({ file: item.file, path: file.path });
+                    }
+                    catch (err) {
+                        kept.push({ file: item.file, error: String(err.message).slice(0, 200) });
+                    }
+                }
+                return { kept };
+            }),
+        });
+    }
+    const fileHint = uploads.length
+        ? ` The person gave: ${uploads.map((u) => `${u.ref} (${u.name})`).join(", ")}.`
+        : "";
+    tools.read_document = createTool({
+        id: "read_document",
+        description: `Read a document as text: PDF, scan or photo (read by a vision model), Word, Excel, CSV, a saved mail. \`file\` is an upload reference or a path in the wizard's files.${fileHint}`,
+        inputSchema: z.object({
+            file: z.string(),
+            offset: z.number().int().min(0).optional().describe("Start at this character, to read on."),
+        }),
+        execute: ({ file, offset }) => attempt(async () => {
+            const source = await resolveFile(ctx, file);
+            await ctx.emit("tool", `Liest ${source.name}`, file.startsWith("upload:") && source.mime.startsWith("image/")
+                ? file.slice("upload:".length)
+                : undefined);
+            const doc = await parseDocument(source, { charge, signal: ctx.signal, call: ctx.call });
+            const start = offset ?? 0;
+            return {
+                file,
+                pages: doc.pages,
+                readBy: doc.via,
+                length: doc.markdown.length,
+                text: clip(doc.markdown.slice(start), 12_000),
+            };
+        }),
+    });
+    tools.scan_documents = createTool({
+        id: "scan_documents",
+        description: `Pull the key fields out of invoices or receipts, several at once: vendor, number, dates, net/tax/total, currency, VAT id. Cheaper and more exact than reading each document yourself. Amounts come back exactly as printed.${fileHint}`,
+        inputSchema: z.object({
+            files: z.array(z.string()).min(1).max(30),
+            kind: z.enum(["invoice", "receipt"]),
+        }),
+        execute: ({ files, kind }) => attempt(async () => {
+            await ctx.emit("tool", `Liest ${files.length} ${kind === "invoice" ? "Rechnungen" : "Belege"}`);
+            const results = [];
+            for (let i = 0; i < files.length; i += 4) {
+                const batch = await Promise.all(files.slice(i, i + 4).map(async (file) => {
+                    try {
+                        const source = await resolveFile(ctx, file);
+                        const scan = await scanDocument(source, kind, {
+                            charge,
+                            signal: ctx.signal,
+                        });
+                        const { line_items: _items, ...fields } = scan;
+                        return { file, ...fields };
+                    }
+                    catch (err) {
+                        return { file, error: String(err.message).slice(0, 200) };
+                    }
+                }));
+                results.push(...batch);
+            }
+            return { documents: results };
+        }),
+    });
+    return tools;
+}

package/apps/runtime/dist/update.js

@@ -0,0 +1,118 @@
+import { spawn } from "node:child_process";
+import { mkdirSync, openSync } from "node:fs";
+import { join } from "node:path";
+import { installedByScript, isCheckout, layout, packageRoot, packageVersion } from "./cli/home.js";
+const RELEASES_URL = process.env.ENGENTY_WIZARDS_RELEASES_URL?.trim() ||
+    "https://api.github.com/repos/engenty/engenty-wizards/releases/latest";
+const FOUND_FOR_MS = 6 * 60 * 60_000;
+const MISSED_FOR_MS = 60 * 60_000;
+/**
+ * The exit code with which the runtime asks the command that started it for a restart: after an
+ * update, that command starts the new version (cli/start.ts).
+ */
+export const RESTART_EXIT = 75;
+/** Set by the command that starts the runtime when it starts it again on RESTART_EXIT. */
+const RESTARTS = "ENGENTY_WIZARDS_RESTARTS";
+let cached = null;
+let applying = "idle";
+let restart = null;
+/** How the runtime stops cleanly; the update calls it with RESTART_EXIT once it is installed. */
+export function onRestart(shutdown) {
+    restart = shutdown;
+}
+function restarts() {
+    return process.env[RESTARTS] === "1" && restart !== null;
+}
+/** `0.2.0` or `v0.2.0` as numbers; anything after a `-` (a pre-release) is ignored. */
+function numbers(version) {
+    return version
+        .replace(/^v/, "")
+        .split("-")[0]
+        .split(".")
+        .map((part) => Number.parseInt(part, 10) || 0);
+}
+export function isNewer(latest, current) {
+    const a = numbers(latest);
+    const b = numbers(current);
+    for (let i = 0; i < Math.max(a.length, b.length); i++) {
+        const diff = (a[i] ?? 0) - (b[i] ?? 0);
+        if (diff !== 0) {
+            return diff > 0;
+        }
+    }
+    return false;
+}
+async function newestRelease() {
+    if (process.env.ENGENTY_WIZARDS_NO_UPDATE_CHECK) {
+        return { latest: null, url: null };
+    }
+    const age = cached ? Date.now() - cached.at : Number.POSITIVE_INFINITY;
+    if (cached && age < (cached.latest ? FOUND_FOR_MS : MISSED_FOR_MS)) {
+        return cached;
+    }
+    let found = { latest: null, url: null };
+    try {
+        const response = await fetch(RELEASES_URL, {
+            headers: { accept: "application/vnd.github+json", "user-agent": "engenty-wizards" },
+            signal: AbortSignal.timeout(5000),
+        });
+        if (response.ok) {
+            const release = (await response.json());
+            if (typeof release.tag_name === "string" && /^v?\d+\.\d+/.test(release.tag_name)) {
+                found = { latest: release.tag_name.replace(/^v/, ""), url: release.html_url ?? null };
+            }
+        }
+    }
+    catch {
+        // offline: the studio says nothing
+    }
+    cached = { at: Date.now(), ...found };
+    return found;
+}
+function installKind() {
+    return installedByScript() ? "script" : isCheckout() ? "checkout" : "npm";
+}
+export async function updateStatus() {
+    const current = packageVersion();
+    const { latest, url } = await newestRelease();
+    const kind = installKind();
+    return {
+        current,
+        latest,
+        newer: latest !== null && isNewer(latest, current),
+        kind,
+        url,
+        canApply: kind === "script",
+        restarts: restarts(),
+        applying,
+    };
+}
+/**
+ * Runs `wizards update` in the background, the same steps as in a terminal. Afterwards a
+ * runtime started by the command restarts into the new version; any other keeps running the old
+ * one until somebody restarts it. The output goes to logs/update.log.
+ */
+export function applyUpdate() {
+    if (applying === "running" || installKind() !== "script") {
+        return applying;
+    }
+    const paths = layout();
+    mkdirSync(paths.logs, { recursive: true });
+    const log = openSync(join(paths.logs, "update.log"), "a");
+    applying = "running";
+    const child = spawn(process.execPath, [join(packageRoot, "bin/wizards.mjs"), "update"], {
+        cwd: paths.home,
+        stdio: ["ignore", log, log],
+    });
+    child.on("error", () => {
+        applying = "failed";
+    });
+    child.on("exit", (code) => {
+        applying = code === 0 ? "done" : "failed";
+        if (applying === "done" && restarts()) {
+            // A moment for the page to hear that it is done.
+            setTimeout(() => restart?.(RESTART_EXIT), 1500);
+        }
+    });
+    return applying;
+}

package/apps/runtime/dist/widgets/bundle.js

@@ -0,0 +1,99 @@
+import { posix } from "node:path";
+import { isTextMime } from "@engenty-wizards/shared/workspace";
+import { getBlob } from "../files/blobs.js";
+import { guardHtml } from "../render/guard.js";
+import { WIDGET_RUNTIME } from "./runtime.js";
+const MAX_BUNDLE_BYTES = 30_000_000;
+function isExternal(ref) {
+    return /^(?:[a-z][a-z0-9+.-]*:|\/\/|#)/i.test(ref);
+}
+/** A reference in a file at `fromDir`, as a workspace path. */
+function resolvePath(ref, fromDir) {
+    const clean = ref.split(/[?#]/)[0];
+    return clean.startsWith("/")
+        ? posix.normalize(clean.slice(1))
+        : posix.normalize(posix.join(fromDir, clean));
+}
+function dataUri(l) {
+    return `data:${l.file.mime};base64,${l.data.toString("base64")}`;
+}
+/**
+ * The widget as ONE self-contained HTML file: its scripts, styles and images inlined, every other
+ * workspace file in the payload `wizard.file()` reads, and the run's data. This file is the result:
+ * it is what the preview shows, what is shared, downloaded, and rendered to PNG/PDF/MP4.
+ */
+export async function bundleWidget(input) {
+    const loaded = new Map();
+    for (const file of input.files) {
+        loaded.set(file.path, { file, data: await getBlob(file.hash) });
+    }
+    const entry = loaded.get(input.entry);
+    if (!entry) {
+        throw new Error(`The widget file ${input.entry} is missing from the workspace.`);
+    }
+    const inlined = new Set([input.entry]);
+    const lookup = (ref, fromDir) => {
+        if (isExternal(ref)) {
+            return null;
+        }
+        return loaded.get(resolvePath(ref, fromDir)) ?? loaded.get(resolvePath(ref, "")) ?? null;
+    };
+    const inlineCssUrls = (css, fromDir) => css.replace(/url\(\s*(['"]?)([^'")]+)\1\s*\)/g, (m, _q, ref) => {
+        const l = lookup(ref, fromDir);
+        return l ? `url("${dataUri(l)}")` : m;
+    });
+    const entryDir = posix.dirname(input.entry) === "." ? "" : posix.dirname(input.entry);
+    let html = entry.data.toString("utf8");
+    html = html.replace(/<script\b([^>]*?)\bsrc\s*=\s*(['"])([^'"]+)\2([^>]*)>\s*<\/script>/gi, (m, before, _q, ref, after) => {
+        const l = lookup(ref, entryDir);
+        if (!l) {
+            return m;
+        }
+        inlined.add(l.file.path);
+        const code = l.data.toString("utf8").replace(/<\/script/gi, "<\\/script");
+        return `<script${before}${after}>${code}</script>`;
+    });
+    html = html.replace(/<link\b[^>]*>/gi, (tag) => {
+        if (!/\brel\s*=\s*(['"]?)stylesheet\1/i.test(tag)) {
+            return tag;
+        }
+        const ref = tag.match(/\bhref\s*=\s*(['"])([^'"]+)\1/i)?.[2];
+        const l = ref ? lookup(ref, entryDir) : null;
+        if (!l) {
+            return tag;
+        }
+        inlined.add(l.file.path);
+        const dir = posix.dirname(l.file.path) === "." ? "" : posix.dirname(l.file.path);
+        return `<style>${inlineCssUrls(l.data.toString("utf8"), dir)}</style>`;
+    });
+    html = html.replace(/(<style\b[^>]*>)([\s\S]*?)(<\/style>)/gi, (_m, open, css, close) => `${open}${inlineCssUrls(css, entryDir)}${close}`);
+    html = html.replace(/(<(?:img|source|video|audio|image|use)\b[^>]*?\b(?:src|href|poster|xlink:href)\s*=\s*)(['"])([^'"]+)\2/gi, (m, head, q, ref) => {
+        const l = lookup(ref, entryDir);
+        return l ? `${head}${q}${dataUri(l)}${q}` : m;
+    });
+    const payloadFiles = {};
+    for (const [path, l] of loaded) {
+        if (inlined.has(path)) {
+            continue;
+        }
+        payloadFiles[path] = isTextMime(l.file.mime)
+            ? { mime: l.file.mime, text: l.data.toString("utf8") }
+            : { mime: l.file.mime, b64: l.data.toString("base64") };
+    }
+    const payload = JSON.stringify({
+        data: input.data ?? {},
+        brand: input.brand,
+        ai: input.ai ?? null,
+        files: payloadFiles,
+        base: entryDir ? `${entryDir}/` : "",
+    }).replace(/</g, "\\u003c");
+    const boot = `<script type="application/json" id="wizard-payload">${payload}</script><script>${WIDGET_RUNTIME}</script>`;
+    html = /<head[^>]*>/i.test(html)
+        ? html.replace(/<head[^>]*>/i, (m) => `${m}${boot}`)
+        : `<!doctype html><html><head>${boot}</head><body>${html}</body></html>`;
+    const out = guardHtml(html, input.media);
+    if (Buffer.byteLength(out) > MAX_BUNDLE_BYTES) {
+        throw new Error("The widget with its files is larger than 30 MB.");
+    }
+    return out;
+}