wizards 0.4.3 → 0.4.5

package/apps/runtime/dist/docs/dev/plugins/routes.md

@@ -1,7 +1,7 @@
 ---
 title: Routes
 description: HTTP routes below the plugin's own address — signed in, inside the person's tenant.
-version: 0.3.2
+version: 0.4.3
 ---
 
 A plugin's routes live below `/api/studio/plugins/<id>`, and for programs with a key below
@@ -130,6 +130,40 @@ const address = await server.publicUrl(`/signal/${source.token}`);
 - A body is taken up to 4 MB. Answers and errors work as for the plugin's other routes.
 - A tenant without the plugin, or a suspended one, answers `404`.
 
+## Shared routes
+
+Some services post to one webhook for everyone: one account of the runtime's, one app. A shared
+route has one address for all tenants, and the call itself says which tenant it is for, with
+the ref the plugin handed the service before:
+
+```ts
+// Handed to the service with the call it is about to make: names the tenant.
+const ref = await server.publicRef();
+
+server.registerSharedRoute({
+  method: "POST",
+  path: "/incoming",
+  handler: async ({ request, inTenant }) => {
+    const raw = await request.text();
+    if (!signedByTheService(raw, request.headers)) {
+      throw Object.assign(new Error("Bad signature."), { status: 401, code: "bad_signature" });
+    }
+    const event = JSON.parse(raw);
+    return inTenant(event.ref, () => pickUp(event));
+  },
+});
+
+// The address to enter at the service, once: the same for every tenant.
+server.sharedUrl("/incoming");
+// https://…/api/public/plugins/<id>/shared/incoming
+```
+
+- The handler runs outside any tenant: check the service's signature, then `inTenant`.
+- `inTenant(ref, work)` runs `work` inside the tenant of that ref, as a public route of the
+  tenant would run. A ref no tenant has, a suspended tenant and one without the plugin throw
+  `404` / `not_found`.
+- `publicRef()` is the part of `publicUrl` that names the tenant; it is the same every time.
+
 ## From the studio half
 
 `studio.api` calls the plugin's own routes and gives the parsed JSON:

package/apps/runtime/dist/docs/dev/plugins/server.md

@@ -1,7 +1,7 @@
 ---
 title: The server half
 description: The function a plugin exports, what it is handed, and the rules it runs under.
-version: 0.3.7
+version: 0.4.3
 ---
 
 The server half is a file whose default export is a function. The runtime calls it once when the
@@ -43,6 +43,8 @@ export default definePlugin((wizards) => {
 | `index.put(entry)`, `index.remove(space, key?)` | Texts in the space's search index | [The space](./space.md#the-search-index) |
 | `registerHttpRoute(route)` | A route below `/api/studio/plugins/<id>` | [Routes](./routes.md) |
 | `registerPublicRoute(route)`, `publicUrl(path)` | A route anyone may call, and its address | [Routes](./routes.md#public-routes) |
+| `registerSharedRoute(route)`, `sharedUrl(path)`, `publicRef()` | One route for every tenant, and the ref that names one | [Routes](./routes.md#shared-routes) |
+| `channels.get()`, `request`, `withdraw`, `book` | The numbers the Manage-App gives the tenant | below |
 | `registerRunner(runner)` | A door a wizard runs through, beside the page and the chat | [Runners](./runners.md) |
 | `runs.start(…)`, `report`, `answerPage`, … | Drives runs from the plugin's own door | [Runners](./runners.md#drive-a-run) |
 | `speech.conversation()` | The tenant's realtime speech model, for a call | [Runners](./runners.md#a-call) |
@@ -85,6 +87,30 @@ Either way a plugin never names a tenant:
 - State kept in a variable of the module is shared by all tenants. Keep per-tenant state in a
   table.
 
+## Numbers of the Manage-App
+
+On engenty.ai a team gets its number for texts and calls from engenty: it asks for one, an
+admin assigns it. `server.channels` reads it for the current tenant and books what it carries;
+the prices are the Manage-App's ([manage contract](https://github.com/engenty/wizards/blob/main/docs/manage-contract.md#numbers-of-a-tenant)).
+
+```ts
+const channels = await server.channels.get();
+// { number: { number: "+43…", country: "AT", kinds: ["sms", "call"], providerRef: "PN…" } | null,
+//   request: { id, country, wish, createdAt } | null,
+//   shared: [{ number, country, kinds }] }
+
+await server.channels.request({ userId: request.user.id, country: "AT", lang: "de" });
+await server.channels.book({ kind: "sms", quantity: segments, key: messageSid, runId });
+```
+
+- `get` is kept for a minute; `request` and `withdraw` forget it.
+- `request` throws `403` / `plan` on a plan without a number and `409` / `has_number` when
+  the team has one. Asking again answers the open request.
+- `book`: `sms` by segment, sent or received, `call` by started minute. The same `key` books
+  once.
+- A runtime without a Manage-App has no numbers: `get` gives `null`, `request` and `withdraw`
+  throw `404` / `not_managed`, `book` books nothing.
+
 ## Asking a model
 
 `server.generate` asks one of the tenant's models, the same ones its wizards run on, and is paid

package/apps/runtime/dist/docs/dev/plugins/starters.md

@@ -27,7 +27,7 @@ server.registerStarter({
 | `id` | Lower case, digits and `-`, starting with a letter, at most 40 characters. Unique in the plugin |
 | `title` | What the list of templates calls it |
 | `description` | What it makes, in one or two sentences. Shown under the title |
-| `language` | `"de"` or `"en"`, the language its texts are in. Default: `"de"` |
+| `language` | `"de"` or `"en"`, the language its texts are in. Default: `"en"` |
 | `definition` | A complete wizard definition: the JSON the studio keeps and `get_authoring_guide` describes |
 | `files` | Files of the wizard's workspace by path: widgets, sample data. A string is written as UTF-8, a `Uint8Array` as it is |
 

package/apps/runtime/dist/documents/parse.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { existsSync, mkdirSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { bilingual } from "@engenty-wizards/shared/run";
 import { generateText, Output } from "ai";
 import PostalMime from "postal-mime";
 import { z } from "zod";
@@ -11,9 +12,10 @@ import { splitMarkdownByPageBreaks } from "../engenty/doc-converter/page-break.j
 import { LocalProvider } from "../engenty/doc-converter/providers/local/index.js";
 import { invoiceSchema, receiptSchema } from "../engenty/document-scanner/schemas/index.js";
 import { env } from "../env.js";
+import { NotedError } from "../model-errors.js";
 import { costOf, textModel } from "../models.js";
 import { htmlToMarkdown } from "../render/convert.js";
-export class UnreadableDocument extends Error {
+export class UnreadableDocument extends NotedError {
 }
 const DOCX = "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
 const XLSX = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
@@ -168,7 +170,7 @@ async function read(input, opts) {
     const vision = new VisionProvider(opts.charge, opts.signal, opts.call);
     if (mime.startsWith("image/")) {
         if (!vision.canConvert(mime)) {
-            throw new UnreadableDocument(`Bilder vom Typ ${mime} kann ich nicht lesen (PNG, JPEG, WebP gehen).`);
+            throw new UnreadableDocument(bilingual(`Bilder vom Typ ${mime} kann ich nicht lesen (PNG, JPEG, WebP gehen).`, `I cannot read images of type ${mime} (PNG, JPEG and WebP work).`));
         }
         const result = await vision.convert(data, name, mime);
         return { markdown: result.markdown, pages: 1, via: "vision" };
@@ -212,7 +214,7 @@ async function read(input, opts) {
     if (mime === "application/json" || mime.startsWith("text/")) {
         return { markdown: text(), pages: null, via: "text" };
     }
-    throw new UnreadableDocument(`„${name}“ (${mime}) kann ich nicht lesen.`);
+    throw new UnreadableDocument(bilingual(`„${name}“ (${mime}) kann ich nicht lesen.`, `I cannot read “${name}” (${mime}).`));
 }
 // --- structured extraction -----------------------------------------------------
 /** The scanner's schemas say nothing about the currency; SaaS invoices come in several. */

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

@@ -7,7 +7,7 @@ const bus = new EventEmitter();
 bus.setMaxListeners(0);
 export async function emitEvent(runId, stepId, type, said, asset) {
     const note = typeof said === "string" ? null : said;
-    const message = note ? noteText(note, "de") : said;
+    const message = note ? noteText(note, "en") : said;
     const [row] = await db
         .insert(schema.runEvent)
         .values({

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

@@ -1,4 +1,9 @@
 import { isDecidedField, isLocationValue, MAX_FILES, offeredSlot, shownFields, } from "@engenty-wizards/shared/definition";
+import { bilingual, saidText } from "@engenty-wizards/shared/run";
+/** The field errors in a language, for whoever reads them. */
+export function fieldErrorsIn(errors, lang) {
+    return errors.map((e) => ({ field: e.field, message: saidText(e.message, lang) }));
+}
 function empty(v) {
     return v === undefined || v === null || v === "" || (Array.isArray(v) && v.length === 0);
 }
@@ -137,36 +142,48 @@ export function readPageInput(step, input, context = {}) {
             continue;
         }
         if (field.required && empty(v) && field.kind !== "toggle") {
-            errors.push({ field: field.id, message: "Pflichtfeld" });
+            errors.push({ field: field.id, message: bilingual("Pflichtfeld", "Required") });
             continue;
         }
         if (Array.isArray(v) && (field.kind === "image" || field.kind === "file")) {
             if (field.min && v.length < field.min) {
-                errors.push({ field: field.id, message: `Bitte mindestens ${field.min} auswählen` });
+                errors.push({
+                    field: field.id,
+                    message: bilingual(`Bitte mindestens ${field.min} auswählen`, `Please choose at least ${field.min}`),
+                });
                 continue;
             }
             if (field.max && v.length > field.max) {
                 errors.push({
                     field: field.id,
-                    message: `Höchstens ${field.max} – bitte einige entfernen`,
+                    message: bilingual(`Höchstens ${field.max} – bitte einige entfernen`, `At most ${field.max} – please remove some`),
                 });
                 continue;
             }
         }
         if (field.kind === "number" && Number.isNaN(v)) {
-            errors.push({ field: field.id, message: "Bitte eine Zahl eingeben" });
+            errors.push({
+                field: field.id,
+                message: bilingual("Bitte eine Zahl eingeben", "Please enter a number"),
+            });
             continue;
         }
         if (field.kind === "select" && !empty(v) && !field.options?.includes(String(v))) {
-            errors.push({ field: field.id, message: "Ungültige Auswahl" });
+            errors.push({ field: field.id, message: bilingual("Ungültige Auswahl", "Invalid choice") });
             continue;
         }
         if (field.kind === "slot" && !empty(v) && !field.options?.includes(String(v))) {
-            errors.push({ field: field.id, message: "Dieser Termin wird nicht angeboten" });
+            errors.push({
+                field: field.id,
+                message: bilingual("Dieser Termin wird nicht angeboten", "This time is not offered"),
+            });
             continue;
         }
         if (field.kind === "email" && !empty(v) && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(String(v))) {
-            errors.push({ field: field.id, message: "Keine gültige E-Mail-Adresse" });
+            errors.push({
+                field: field.id,
+                message: bilingual("Keine gültige E-Mail-Adresse", "Not a valid email address"),
+            });
             continue;
         }
         if (field.kind === "url" && !empty(v)) {
@@ -174,7 +191,10 @@ export function readPageInput(step, input, context = {}) {
                 new URL(String(v));
             }
             catch {
-                errors.push({ field: field.id, message: "Keine gültige URL" });
+                errors.push({
+                    field: field.id,
+                    message: bilingual("Keine gültige URL", "Not a valid URL"),
+                });
                 continue;
             }
         }

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

@@ -68,7 +68,7 @@ async function listenTo(ctx, id, label, value) {
     if (!found || found.row.runId !== ctx.runId || !/^(audio|video)\//.test(found.row.mime)) {
         return;
     }
-    await ctx.emit("info", `Hört „${label}“ an …`);
+    await ctx.emit("info", { code: "listen", params: { label } });
     try {
         const { pieces, costUsd } = await listenPieces({
             bytes: new Uint8Array(found.data),
@@ -85,6 +85,6 @@ async function listenTo(ctx, id, label, value) {
         }
         // The step goes on without the words; the next one tries again.
         console.error(`[run ${ctx.runId}] listen ${id}`, err);
-        await ctx.emit("info", `„${label}“ konnte nicht verschriftlicht werden.`);
+        await ctx.emit("info", { code: "listenFailed", params: { label } });
     }
 }

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

@@ -1,5 +1,6 @@
 import { conditionMatches, conditionsOf, isDecidedField, isDecisionStep, isOtherwise, MODEL_CLASSES, } from "@engenty-wizards/shared/definition";
 import { closedChoicesFor, openValue, otherwiseIndex, unavoidableFrom, unavoidableSteps, } from "@engenty-wizards/shared/fit";
+import { bilingual, saidText } from "@engenty-wizards/shared/run";
 import { classProblem, filmClient } from "../models.js";
 // The steps every run passes through, and the choices that lead around a missing model, are
 // pure and shared (packages/shared/src/fit.ts): the standalone check uses the same.
@@ -220,8 +221,12 @@ export async function stepsWithoutModel(def) {
     const missing = await missingClasses();
     return new Set(def.steps.filter((s) => stepClasses(s).some((cls) => missing.has(cls))).map((s) => s.id));
 }
+/** The classes this wizard needs that this runtime cannot serve, in a language; empty = every step can run. */
+export async function missingModels(def, lang = "en") {
+    return (await missingModelsSaid(def)).map((m) => ({ ...m, problem: saidText(m.problem, lang) }));
+}
 /** The classes this wizard needs that this runtime cannot serve; empty = every step can run. */
-export async function missingModels(def) {
+export async function missingModelsSaid(def) {
     const unavoidable = unavoidableSteps(def);
     const needs = new Map();
     for (const step of def.steps) {
@@ -268,9 +273,13 @@ export function blockingMessage(missing) {
     if (!blocking.length) {
         return null;
     }
-    return blocking
-        .map((m) => `${m.steps.map((s) => `„${s.title}“`).join(", ")}: ${m.problem}`)
+    const line = (lang) => blocking
+        .map((m) => {
+        const steps = m.steps.map((s) => (lang === "de" ? `„${s.title}“` : `“${s.title}”`));
+        return `${steps.join(", ")}: ${saidText(m.problem, lang)}`;
+    })
         .join(" ");
+    return bilingual(line("de"), line("en"));
 }
 /** The class a marketplace capability stands for; the rest need no model of their own. */
 const CAPABILITY_CLASS = {

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

@@ -1,6 +1,6 @@
 import { marginOf, } from "@engenty-wizards/shared/decision";
 import { branchValues, cardsFromData, conditionsOf, dataRef, followRules, formatsFor, isDecidedField, LIST_FORMATS, listRef, loopKey, MAX_SHOWN_FIELDS, optionsFromData, otherwiseOf, pageNeeds, whenHolds, wizardLang, } from "@engenty-wizards/shared/definition";
-import { noteText, } from "@engenty-wizards/shared/run";
+import { bilingual, saidText, } from "@engenty-wizards/shared/run";
 import { CONVERSATION_RUNNERS, DEFAULT_RUNNER_SETTINGS } from "@engenty-wizards/shared/runners";
 import { eq } from "drizzle-orm";
 import { nanoid } from "nanoid";
@@ -12,7 +12,7 @@ import { env } from "../env.js";
 import { saveAsset } from "../files/storage.js";
 import { managed, tenantInfo } from "../manage.js";
 import { hasFfmpeg } from "../media/ffmpeg.js";
-import { NotedError, noteOf } from "../model-errors.js";
+import { NotedError, noteOf, saidOf } from "../model-errors.js";
 import { conversationAvailable, freeTierRefusal, freeTierText, ModelUnavailableError, noteFreeTierRefusal, } from "../models.js";
 import { runEnded } from "../plugins/events.js";
 import { projectFiles } from "../services/project-files.js";
@@ -26,7 +26,7 @@ import { clearDeviceCalls } from "./device.js";
 import { emitEvent, recentEvents, signalChanged } from "./events.js";
 import { readPageInput } from "./input.js";
 import { pushRun } from "./push.js";
-import { blockingMessage, closedChoices, missingModels, openValue, stepsWithoutModel, } from "./requirements.js";
+import { blockingMessage, closedChoices, missingModelsSaid, openValue, stepsWithoutModel, } from "./requirements.js";
 import { releaseResources, resourcesFor } from "./resources.js";
 import { runAutomaticStep } from "./steps.js";
 import { answersAsText, resolveRef } from "./template.js";
@@ -41,9 +41,9 @@ export class RunInputError extends NotedError {
         this.errors = errors;
     }
 }
-export class NoCreditsError extends Error {
+export class NoCreditsError extends NotedError {
     constructor() {
-        super("Dieser Wizard hat gerade kein Guthaben mehr. Bitte später erneut versuchen.");
+        super(bilingual("Dieser Wizard hat gerade kein Guthaben mehr. Bitte später erneut versuchen.", "This wizard has no credits left right now. Please try again later."));
     }
 }
 /** The runs this process drives right now, with the handle that stops each. */
@@ -99,7 +99,7 @@ function stepOf(def, id) {
 }
 function friendly(err) {
     if (err instanceof StepError || err instanceof ModelUnavailableError) {
-        return err.message;
+        return saidOf(err);
     }
     // An own AI Gateway key on Vercel's free tier: the person can top it up or pick another way.
     const refused = freeTierRefusal(err);
@@ -109,32 +109,32 @@ function friendly(err) {
     const msg = err?.message ?? String(err);
     // The model-gateway answers 402 once the tenant's credits are used up.
     if (/insufficient_credits|\b402\b/i.test(msg)) {
-        return new NoCreditsError().message;
+        return saidOf(new NoCreditsError());
     }
     // A runtime that runs alone pays its provider itself: its admin can top the account up.
     if (!managed && /minimum balance|insufficient_funds|top up your credits/i.test(msg)) {
-        return "Das Guthaben beim Modell-Anbieter reicht dafür nicht aus (Videos brauchen dort ein Mindestguthaben). Bitte dort aufladen und noch einmal versuchen.";
+        return bilingual("Das Guthaben beim Modell-Anbieter reicht dafür nicht aus (Videos brauchen dort ein Mindestguthaben). Bitte dort aufladen und noch einmal versuchen.", "The credit with the model provider is not enough for this (videos need a minimum balance there). Please top up there and try again.");
     }
     if (/rate.?limit|429/i.test(msg)) {
-        return "Der KI-Dienst ist gerade ausgelastet. Bitte gleich noch einmal versuchen.";
+        return bilingual("Der KI-Dienst ist gerade ausgelastet. Bitte gleich noch einmal versuchen.", "The AI service is busy right now. Please try again in a moment.");
     }
     if (/timeout|timed out/i.test(msg)) {
-        return "Der Schritt hat zu lange gedauert. Bitte noch einmal versuchen.";
+        return bilingual("Der Schritt hat zu lange gedauert. Bitte noch einmal versuchen.", "The step took too long. Please try again.");
     }
     // The platform's own provider account (budget, quota, key): nothing the person can fix.
     if (/budget|quota|insufficient|billing|credit balance|api key|unauthori[sz]ed|401|403/i.test(msg)) {
-        return "Der KI-Dienst ist gerade nicht erreichbar. Bitte später noch einmal versuchen.";
+        return bilingual("Der KI-Dienst ist gerade nicht erreichbar. Bitte später noch einmal versuchen.", "The AI service cannot be reached right now. Please try again later.");
     }
-    return `Dieser Schritt ist fehlgeschlagen: ${msg.slice(0, 300)}`;
+    return bilingual(`Dieser Schritt ist fehlgeschlagen: ${msg.slice(0, 300)}`, `This step failed: ${msg.slice(0, 300)}`);
 }
 /**
  * A step that failed ends the run. A failure with a note (Apple Intelligence's) goes into the log
  * as that note, so a runner shows it in its language; the run's error is in the wizard's.
  */
 async function failRun(run, stepId, err) {
-    const note = noteOf(err);
-    const message = note ? noteText(note, wizardLang(run.definition)) : friendly(err);
-    await emitEvent(run.id, stepId, "error", note ?? message);
+    const said = noteOf(err) ?? friendly(err);
+    const message = saidText(said, wizardLang(run.definition));
+    await emitEvent(run.id, stepId, "error", said);
     await updateRun(run.id, { status: "failed", error: message });
 }
 // --- creating & driving ------------------------------------------------------
@@ -143,7 +143,7 @@ export async function createRun(input) {
     const first = input.definition.steps[0];
     const state = { values: {}, outputs: {}, history: [], notes: {} };
     // A step every run passes through needs a model this runtime cannot serve: refuse before anything is held.
-    const blocked = blockingMessage(await missingModels(input.definition));
+    const blocked = blockingMessage(await missingModelsSaid(input.definition));
     if (blocked) {
         throw new ModelUnavailableError(blocked);
     }
@@ -219,7 +219,11 @@ async function take(runId, tenant) {
     await withTenant(tenant, () => drive(runId, abort.signal))
         .catch(async (err) => {
         console.error(`[run ${runId}]`, err);
-        await withTenant(tenant, () => updateRun(runId, { status: "failed", error: friendly(err) })).catch(() => undefined);
+        await withTenant(tenant, async () => {
+            const run = await loadRun(runId);
+            const lang = run ? wizardLang(run.definition) : "en";
+            await updateRun(runId, { status: "failed", error: saidText(friendly(err), lang) });
+        }).catch(() => undefined);
     })
         .finally(async () => {
         clearInterval(beat);
@@ -631,14 +635,17 @@ export async function submitPage(runId, stepId, input) {
         const answer = values[id];
         if (answer !== undefined &&
             (choice.values.length === 0 || choice.values.some((v) => String(v) === String(answer)))) {
-            errors.push({ field: id, message: "Das ist hier gerade nicht verfügbar." });
+            errors.push({
+                field: id,
+                message: bilingual("Das ist hier gerade nicht verfügbar.", "That is not available here right now."),
+            });
         }
     }
     if (errors.length) {
         throw new RunInputError(errors);
     }
     const connections = step.fields.some((f) => f.kind === "connection")
-        ? await connectionViews(run.definition.connections ?? [], scopeOf(run), await projectIdOf(run))
+        ? await connectionViews(run.definition.connections ?? [], scopeOf(run), await projectIdOf(run), wizardLang(run.definition))
         : [];
     for (const field of step.fields) {
         if (field.kind === "image" || field.kind === "file") {
@@ -646,7 +653,9 @@ export async function submitPage(runId, stepId, input) {
             for (const id of Array.isArray(value) ? value : value ? [value] : []) {
                 const asset = await db.query.asset.findFirst({ where: eq(schema.asset.id, String(id)) });
                 if (asset?.runId !== runId) {
-                    throw new RunInputError([{ field: field.id, message: "Datei nicht gefunden" }]);
+                    throw new RunInputError([
+                        { field: field.id, message: bilingual("Datei nicht gefunden", "File not found") },
+                    ]);
                 }
             }
         }
@@ -657,7 +666,9 @@ export async function submitPage(runId, stepId, input) {
                 values[field.id] = account.label;
             }
             else if (field.required) {
-                throw new RunInputError([{ field: field.id, message: "Bitte zuerst verbinden" }]);
+                throw new RunInputError([
+                    { field: field.id, message: bilingual("Bitte zuerst verbinden", "Please connect first") },
+                ]);
             }
         }
     }
@@ -701,7 +712,7 @@ export async function reviewStep(runId, stepId, action) {
     if (!step.show.includes(action.target)) {
         throw new RunConflict("Unknown target");
     }
-    state.notes[action.target] = action.note.slice(0, 2000) || "Bitte eine neue Variante.";
+    state.notes[action.target] = action.note.slice(0, 2000) || "Please make a new variant.";
     // A step with several results makes only the named ones again.
     if (action.items?.length) {
         state.redo = { ...state.redo, [action.target]: action.items };
@@ -884,7 +895,7 @@ export async function runView(run, brand) {
         ask: run.status === "running" ? run.ask : null,
         lists,
         connections: step?.type === "page" && step.fields.some((f) => f.kind === "connection")
-            ? await connectionViews(def.connections ?? [], scopeOf(run), await projectIdOf(run))
+            ? await connectionViews(def.connections ?? [], scopeOf(run), await projectIdOf(run), wizardLang(def))
             : [],
         keeps: Boolean(def.lists?.length || def.connections?.length),
         shareUrl: run.shareToken ? `${env.publicUrl}/s/${run.shareToken}` : null,

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

@@ -1,6 +1,7 @@
 import { pOf } from "@engenty-wizards/shared/decision";
 import { allFields, dataRef, isDecisionStep, LOCALES, templateRefs, wizardLang, } from "@engenty-wizards/shared/definition";
 import { mainLogo, ruleLines } from "@engenty-wizards/shared/projects";
+import { bilingual } from "@engenty-wizards/shared/run";
 import { SURFACE_GUIDE, validateSurface, } from "@engenty-wizards/shared/surface";
 import { Agent } from "@mastra/core/agent";
 import { generateText, Output } from "ai";
@@ -378,7 +379,7 @@ function agentEntries(step, ctx) {
 async function runAgentEach(step, ctx) {
     const entries = agentEntries(step, ctx);
     if (!entries.length) {
-        throw new StepError("Es gibt keine Einträge, für die dieser Schritt arbeiten könnte.");
+        throw new StepError(bilingual("Es gibt keine Einträge, für die dieser Schritt arbeiten könnte.", "There are no entries for this step to work on."));
     }
     // The view, if any, is composed once over the table of all entries.
     const single = {
@@ -553,7 +554,7 @@ export async function runAgentStep(step, ctx) {
         const text = step.output.format === "json" ? everything : closing || everything;
         if (step.output.format !== "json") {
             if (!text && !assets.length) {
-                throw new StepError("Der Schritt hat kein Ergebnis geliefert.");
+                throw new StepError(bilingual("Der Schritt hat kein Ergebnis geliefert.", "The step did not deliver a result."));
             }
             return { text, assets: assets.length ? assets : undefined, at: new Date().toISOString() };
         }
@@ -754,7 +755,7 @@ async function writeHtml(step, ctx, kind) {
         .replace(/```\s*$/, "")
         .trim();
     if (!/<html|<!doctype/i.test(html)) {
-        throw new StepError("Das Dokument konnte nicht erstellt werden.");
+        throw new StepError(bilingual("Das Dokument konnte nicht erstellt werden.", "The document could not be made."));
     }
     // On screen (preview, PNG) a print document needs the margin its @page rule gives it on paper.
     return kind === "document"
@@ -805,7 +806,7 @@ async function inParallel(items, limit, work) {
 async function runMediaStep(step, ctx, asset) {
     const entries = entriesOf(step, ctx);
     if (!entries.length) {
-        throw new StepError("Für diesen Schritt fehlen die Vorlagen (Bilder oder Szenen).");
+        throw new StepError(bilingual("Für diesen Schritt fehlen die Vorlagen (Bilder oder Szenen).", "This step is missing its sources (images or scenes)."));
     }
     const previous = ctx.state.outputs[step.id];
     const before = previous?.assets?.filter((a) => a.kind === asset) ?? [];
@@ -897,7 +898,7 @@ export async function runGenerateStep(step, ctx) {
         case "voice": {
             const text = renderTemplate(step.prompt, ctx.scope).trim().slice(0, 4000);
             if (!text) {
-                throw new StepError("Es gibt keinen Text zum Vorlesen.");
+                throw new StepError(bilingual("Es gibt keinen Text zum Vorlesen.", "There is no text to read aloud."));
             }
             const note = ctx.state.notes[step.id];
             const media = await generateSpeechMedia({

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

@@ -1,4 +1,5 @@
 import { assembleSurface, dataRef, listRef, } from "@engenty-wizards/shared/definition";
+import { bilingual } from "@engenty-wizards/shared/run";
 import { validateSurface } from "@engenty-wizards/shared/surface";
 import { decide } from "./decide.js";
 import { answersAsText, resolveRef } from "./template.js";
@@ -13,7 +14,7 @@ export async function runSurfaceStep(step, ctx) {
     const components = step.components ?? (await decidedComponents(step, ctx));
     const issues = validateSurface(components, Object.keys(data));
     if (issues.length) {
-        throw new StepError(`Die Ansicht ist fehlerhaft: ${issues.map((i) => i.message).join(" ")}`);
+        throw new StepError(bilingual(`Die Ansicht ist fehlerhaft: ${issues.map((i) => i.message).join(" ")}`, `The view is faulty: ${issues.map((i) => i.message).join(" ")}`));
     }
     return { surface: { components, data }, at: new Date().toISOString() };
 }

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

@@ -11,7 +11,7 @@ function money(n, currency, locale) {
     }
 }
 /** Line items as a Markdown table with their totals — what a model needs to write a document. */
-export function itemsAsMarkdown(field, value, values, lang = "de") {
+export function itemsAsMarkdown(field, value, values, lang = "en") {
     const locale = LOCALES[lang];
     const totals = itemsTotals(field, value, values);
     const cols = field.columns ?? [];

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

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

package/apps/runtime/dist/film/project.js

@@ -250,7 +250,7 @@ export async function prepareFilmFolder(step, ctx) {
     const preset = { "16:9": "landscape", "9:16": "portrait", "1:1": "square" }[step.format];
     const init = await runHyperframes(["init", "film", "--non-interactive", "--skip-transcribe", `--resolution=${preset}`], { cwd: root, signal: ctx.signal, timeoutMs: 5 * 60_000 });
     if (init.code !== 0 || !existsSync(join(root, "film"))) {
-        throw new Error(`Das Filmprojekt konnte nicht angelegt werden: ${init.out.slice(-300)}`);
+        throw new Error(`The film project could not be set up: ${init.out.slice(-300)}`);
     }
     await put(root, ".engenty/inputs", stamp);
     return { root, brief };

package/apps/runtime/dist/film/skills.js

@@ -21,7 +21,7 @@ const fetching = new Map();
 export function platformSkills(name) {
     const pkg = PLATFORM_SKILLS[name];
     if (!pkg) {
-        return Promise.reject(new Error(`Das Skill-Paket „${name}“ gibt es nicht.`));
+        return Promise.reject(new Error(`There is no skill package “${name}”.`));
     }
     const dir = join(env.dataDir, "skills", `${pkg.name}@${pkg.version.slice(0, 12)}`);
     if (existsSync(join(dir, ".complete"))) {
@@ -37,7 +37,7 @@ export function platformSkills(name) {
 async function fetchPackage(pkg, dir) {
     const res = await fetch(pkg.tarball);
     if (!res.ok) {
-        throw new Error(`Das Skill-Paket „${pkg.name}“ konnte nicht geladen werden (${res.status}).`);
+        throw new Error(`The skill package “${pkg.name}” could not be loaded (${res.status}).`);
     }
     const tmp = `${dir}.part`;
     await rm(tmp, { recursive: true, force: true });

package/apps/runtime/dist/film/sounds.js

@@ -108,7 +108,7 @@ async function build() {
         }
     }
     if (!sounds.length) {
-        throw new Error("Die Geräusche für Filme konnten nicht geladen werden.");
+        throw new Error("The sounds for films could not be loaded.");
     }
     sounds.sort((a, b) => a.file.localeCompare(b.file));
     await writeFile(join(tmp, "catalog.json"), JSON.stringify({

package/apps/runtime/dist/film/step.js

@@ -2,10 +2,12 @@ import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { readFile, rm, stat } from "node:fs/promises";
 import { isAbsolute, join, normalize } from "node:path";
+import { bilingual } from "@engenty-wizards/shared/run";
 import { StepError } from "../engine/types.js";
 import { CLAUDE_BIN, claudeEnv } from "../harness/claude.js";
 import { failureOf } from "../harness/model.js";
 import { openBridge } from "../mcp/bridge.js";
+import { errorText } from "../model-errors.js";
 import { filmClient } from "../models.js";
 import { prepareFilmFolder, savedSession, saveSession } from "./project.js";
 import { runHyperframes } from "./tools.js";
@@ -227,12 +229,13 @@ export async function runFilmStep(step, ctx) {
             if (ctx.signal.aborted) {
                 throw err;
             }
-            throw new StepError(`${client.name} hat beim Film aufgehört: ${err.message}. Die Arbeit ist gespeichert; ein neuer Versuch macht dort weiter.`);
+            throw new StepError(bilingual(`${client.name} hat beim Film aufgehört: ${err.message}. Die Arbeit ist gespeichert; ein neuer Versuch macht dort weiter.`, `${client.name} stopped working on the film: ${err.message}. The work is saved; a new attempt carries on from there.`));
         });
         const result = last;
         if (!result || result.is_error) {
-            const detail = String(result?.result ?? (stderr.trim() || "kein Ergebnis")).slice(0, 400);
-            throw new StepError(`${failureOf(client, detail).message} Die Arbeit ist gespeichert; ein neuer Versuch macht dort weiter.`);
+            const detail = String(result?.result ?? (stderr.trim() || "no result")).slice(0, 400);
+            const failure = failureOf(client, detail);
+            throw new StepError(bilingual(`${errorText(failure, "de")} Die Arbeit ist gespeichert; ein neuer Versuch macht dort weiter.`, `${errorText(failure, "en")} The work is saved; a new attempt carries on from there.`));
         }
         return result;
     };
@@ -262,7 +265,7 @@ export async function runFilmStep(step, ctx) {
             }
             const problem = renderProblem(render.out);
             if (attempt >= RENDER_FIXES) {
-                throw new StepError(`Der Film ließ sich nicht rendern: ${problem.slice(0, 400)}`);
+                throw new StepError(bilingual(`Der Film ließ sich nicht rendern: ${problem.slice(0, 400)}`, `The film could not be rendered: ${problem.slice(0, 400)}`));
             }
             await ctx.emit("tool", { code: "filmFix" });
             const fixed = await turn(`The final render of film/ failed:\n\n${problem}\n\nFind the cause in the composition's code, fix it, run \`check\` and a draft render through the hyperframes tool until both pass, and end with one line on what you fixed.`, await savedSession(root));

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

@@ -40,7 +40,7 @@ async function install() {
         `hyperframes@${HYPERFRAMES_VERSION}`,
     ], { cwd: home, timeoutMs: 10 * 60_000 });
     if (code !== 0 || !existsSync(entry)) {
-        throw new Error(`HyperFrames konnte nicht installiert werden: ${out.slice(-400)}`);
+        throw new Error(`HyperFrames could not be installed: ${out.slice(-400)}`);
     }
     return entry;
 }