wizards 0.2.25 → 0.2.27

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

@@ -1,4 +1,5 @@
-import { branchValues, dataRef, formatsFor, LIST_FORMATS, listRef, nextStepId, } from "@engenty-wizards/shared/definition";
+import { marginOf, } from "@engenty-wizards/shared/decision";
+import { branchValues, conditionsOf, dataRef, followRules, formatsFor, isDecidedField, LIST_FORMATS, listRef, loopKey, MAX_SHOWN_FIELDS, optionsFromData, otherwiseOf, pageNeeds, whenHolds, } from "@engenty-wizards/shared/definition";
 import { eq } from "drizzle-orm";
 import { nanoid } from "nanoid";
 import { connectionViews } from "../connectors/index.js";
@@ -17,13 +18,14 @@ import { listRows, scopeOf } from "../store/index.js";
 import { activeRuns, indexRun, markRunActive } from "../tenants/control.js";
 import { currentTenant } from "../tenants/tenant.js";
 import { askPerson, clearStaleAsk, unattended } from "./asks.js";
+import { decide } from "./decide.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 { releaseResources, resourcesFor } from "./resources.js";
 import { runAutomaticStep } from "./steps.js";
-import { resolveRef } from "./template.js";
+import { answersAsText, resolveRef } from "./template.js";
 import { StepError } from "./types.js";
 /** A command the run cannot take in its current state. */
 export class RunConflict extends Error {
@@ -226,6 +228,45 @@ export function kick(runId) {
         signalChanged(runId);
     });
 }
+/** What conditions read in this run: answers, outputs, and how many rows each stored list has. */
+async function flowValues(run, state) {
+    const counts = {};
+    if (run.definition.lists?.length) {
+        for (const [id, list] of Object.entries(await storedLists(run))) {
+            counts[id] = list.rows.length;
+        }
+    }
+    return branchValues(state.values, state.outputs, counts);
+}
+/**
+ * What a page knows besides the person's input: what its fields' `when` read from before the
+ * page (its own earlier answers left out, so a revisit decides on what is typed now) and the
+ * choices its `optionsFrom` fields find in the run.
+ */
+async function pageContext(run, step) {
+    const needs = pageNeeds(step.fields);
+    const sourced = step.fields.filter((f) => f.optionsFrom);
+    const decided = step.fields.some(isDecidedField) ? (run.state.pages?.[step.id]?.shown ?? []) : [];
+    if (!needs.length && !sourced.length) {
+        return { known: {}, options: {}, decided };
+    }
+    const all = await flowValues(run, run.state);
+    const known = Object.fromEntries(needs.map((ref) => [ref, all[ref]]));
+    const lists = sourced.some((f) => f.optionsFrom?.startsWith("lists."))
+        ? await storedLists(run)
+        : {};
+    const options = {};
+    for (const field of sourced) {
+        const found = optionsFromData(field.optionsFrom ?? "", run.state.outputs, lists);
+        if (found.length) {
+            options[field.id] = found;
+        }
+    }
+    return { known, options, decided };
+}
+function viewContext(ctx) {
+    return { known: ctx.known, options: ctx.options, decidedFields: ctx.decided };
+}
 /** The wizard's lists with the person's rows, by list id. */
 async function storedLists(run) {
     const scope = scopeOf(run);
@@ -243,6 +284,7 @@ async function makeContext(run, project, state, signal) {
     return {
         runId: run.id,
         tenantId: run.tenantId,
+        test: run.mode === "test",
         stepId,
         store,
         def: run.definition,
@@ -271,6 +313,146 @@ async function makeContext(run, project, state, signal) {
         }),
     };
 }
+/** A decided branch is taken only when its pick leads the runner-up by this much. */
+const BRANCH_MARGIN = 0.1;
+/**
+ * Where the run goes after `stepId`: a `when` rule or the next step at once — counted, so a loop
+ * stops at its rule's max — or, for `ask` rules, a decision the drive loop makes (`deciding`).
+ */
+async function advance(run, stepId, state) {
+    const outcome = followRules(run.definition, stepId, await flowValues(run, state), state.loops);
+    if (outcome.kind === "decide") {
+        state.deciding = stepId;
+        return stepId;
+    }
+    return taken(run.definition, stepId, outcome.rule, outcome.cursor, state);
+}
+function taken(def, stepId, rule, cursor, state) {
+    const goto = rule === null ? null : stepOf(def, stepId)?.next?.[rule]?.goto;
+    if (goto) {
+        const key = loopKey(stepId, goto);
+        state.loops = { ...state.loops, [key]: (state.loops?.[key] ?? 0) + 1 };
+    }
+    return cursor;
+}
+/** What a decision about the run reads: the person's answers and what the steps made so far. */
+function runSummary(run, state) {
+    const results = {};
+    for (const step of run.definition.steps) {
+        const out = state.outputs[step.id];
+        const text = out?.text ?? (out?.json === undefined ? "" : JSON.stringify(out.json));
+        if (text) {
+            results[step.title] = text.slice(0, 6000);
+        }
+    }
+    return {
+        answers: answersAsText({ def: run.definition, state, brand: {} }),
+        results,
+    };
+}
+/**
+ * The decision over a step's open `ask` rules: one choice among their statements and "none".
+ * Kept in the run; a pick that does not lead clearly (where there are probabilities) is none.
+ */
+async function decideBranch(run, step, state, signal) {
+    const outcome = followRules(run.definition, step.id, {}, state.loops);
+    const rules = outcome.kind === "decide" ? outcome.rules : [];
+    const criteria = {};
+    for (const i of rules) {
+        criteria[`r${i}`] = step.next?.[i]?.ask ?? "";
+    }
+    criteria.none = "None of these clearly holds: go on with the next step.";
+    await emitEvent(run.id, step.id, "info", { code: "deciding" });
+    const decision = await decide({
+        state: runSummary(run, state),
+        questions: {
+            next: {
+                type: "choice",
+                instructions: "Which statement is true of this run? Answer none unless one clearly holds.",
+                criteria,
+            },
+        },
+        call: { runId: run.id, stepId: step.id },
+        signal,
+        charge: (usd) => addLocalCost(run.id, step.id, usd),
+    });
+    const answer = decision.answers.next;
+    const margin = marginOf(answer);
+    const pick = margin !== null && margin < BRANCH_MARGIN ? "none" : answer.choice;
+    const rule = pick === "none" ? null : Number(pick.slice(1));
+    state.decisions = {
+        ...state.decisions,
+        [step.id]: {
+            rule,
+            source: decision.source,
+            ...(answer.probabilities ? { probabilities: answer.probabilities } : {}),
+            at: new Date().toISOString(),
+        },
+    };
+    delete state.deciding;
+    if (rule === null) {
+        const otherwise = otherwiseOf(run.definition, step.id, state.loops);
+        return taken(run.definition, step.id, otherwise.rule, otherwise.cursor, state);
+    }
+    const goto = step.next?.[rule]?.goto ?? "end";
+    return taken(run.definition, step.id, rule, goto === "end" ? null : goto, state);
+}
+/**
+ * The decided fields (`ask`, `group`) of a page a decision keeps, in one call as the run reaches
+ * the page. A field whose condition on earlier data already fails is not asked about. With the
+ * fields always shown, at most MAX_SHOWN_FIELDS appear.
+ */
+async function decidePageFields(run, page, state, signal) {
+    const values = await flowValues(run, state);
+    const own = new Set(page.fields.map((f) => f.id));
+    const possible = page.fields.filter((f) => isDecidedField(f) &&
+        whenHolds(conditionsOf(f.when).filter((c) => !own.has(c.field)), values));
+    const questions = {};
+    for (const f of possible.filter((f) => f.ask)) {
+        questions[`f_${f.id}`] = {
+            type: "noul",
+            instructions: `Should the page ask "${f.label}"? It is asked when this holds: ${f.ask}`,
+        };
+    }
+    for (const g of page.groups ?? []) {
+        const members = possible.filter((f) => f.group === g.id);
+        if (members.length) {
+            questions[`g_${g.id}`] = {
+                type: "choice",
+                instructions: g.instructions,
+                criteria: {
+                    ...Object.fromEntries(members.map((f) => [f.id, f.help ? `${f.label} — ${f.help}` : f.label])),
+                    ...(g.optional ? { none: "None of these." } : {}),
+                },
+            };
+        }
+    }
+    if (!Object.keys(questions).length) {
+        return [];
+    }
+    await emitEvent(run.id, page.id, "info", { code: "choosingFields" });
+    const decision = await decide({
+        state: runSummary(run, state),
+        questions,
+        call: { runId: run.id, stepId: page.id },
+        signal,
+        charge: (usd) => addLocalCost(run.id, page.id, usd),
+    });
+    const kept = new Set();
+    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);
+        }
+    }
+    const room = MAX_SHOWN_FIELDS - page.fields.filter((f) => !isDecidedField(f)).length;
+    return page.fields
+        .filter((f) => isDecidedField(f) && kept.has(f.id))
+        .slice(0, Math.max(0, room))
+        .map((f) => f.id);
+}
 async function drive(runId, signal) {
     await clearStaleAsk(runId);
     while (!signal.aborted) {
@@ -279,11 +461,59 @@ async function drive(runId, signal) {
             return;
         }
         const def = run.definition;
+        // A step's `ask` branches wait on a decision before the run goes on.
+        const deciding = run.state.deciding ? stepOf(def, run.state.deciding) : undefined;
+        if (deciding) {
+            const state = structuredClone(run.state);
+            try {
+                const cursor = await decideBranch(run, deciding, state, signal);
+                if (signal.aborted) {
+                    return;
+                }
+                await syncRunCost(runId);
+                await updateRun(runId, { state, cursor, status: cursor ? "running" : "done", error: null });
+            }
+            catch (err) {
+                if (signal.aborted) {
+                    return;
+                }
+                console.error(`[run ${runId} deciding ${deciding.id}]`, err);
+                const message = friendly(err);
+                await emitEvent(runId, deciding.id, "error", message);
+                await updateRun(runId, { status: "failed", error: message });
+                return;
+            }
+            continue;
+        }
         const step = stepOf(def, run.cursor);
         if (!step) {
             await updateRun(runId, { status: "done" });
             return;
         }
+        // A page whose fields a decision picks: picked once, as the run reaches it.
+        if (step.type === "page" && step.fields.some(isDecidedField) && !run.state.pages?.[step.id]) {
+            const state = structuredClone(run.state);
+            try {
+                const shown = await decidePageFields(run, step, state, signal);
+                if (signal.aborted) {
+                    return;
+                }
+                state.pages = { ...state.pages, [step.id]: { shown } };
+                await syncRunCost(runId);
+                await updateRun(runId, { state, error: null });
+            }
+            catch (err) {
+                if (signal.aborted) {
+                    return;
+                }
+                console.error(`[run ${runId} fields of ${step.id}]`, err);
+                const message = friendly(err);
+                await emitEvent(runId, step.id, "error", message);
+                await updateRun(runId, { status: "failed", error: message });
+                return;
+            }
+            continue;
+        }
         if (step.type === "result") {
             await updateRun(runId, { status: "done" });
             return;
@@ -312,7 +542,7 @@ async function drive(runId, signal) {
             state.outputs[step.id] = output;
             delete state.notes[step.id];
             delete state.redo?.[step.id];
-            const cursor = nextStepId(def, step.id, branchValues(state.values, state.outputs));
+            const cursor = await advance(run, step.id, state);
             await updateRun(runId, { state, cursor, status: cursor ? "running" : "done", error: null });
             await emitEvent(runId, step.id, "step_done", step.title);
         }
@@ -363,7 +593,7 @@ export async function submitPage(runId, stepId, input) {
     if (step?.type !== "page") {
         throw new RunConflict("Not a page");
     }
-    const { values, errors } = readPageInput(step, input);
+    const { values, errors } = readPageInput(step, input, await pageContext(run, step));
     // An answer that leads to a step without a model here would stop the run there, later.
     const closed = await closedChoices(run.definition, step, run.state.values);
     for (const [id, choice] of Object.entries(closed)) {
@@ -408,8 +638,13 @@ export async function submitPage(runId, stepId, input) {
             delete state.values[field.id];
         }
     }
+    // Later pages decide their fields again on what is answered now.
+    const at = run.definition.steps.indexOf(step);
+    for (const later of run.definition.steps.slice(at + 1)) {
+        delete state.pages?.[later.id];
+    }
     state.history.push(stepId);
-    const cursor = nextStepId(run.definition, stepId, branchValues(state.values, state.outputs));
+    const cursor = await advance(run, stepId, state);
     await updateRun(runId, { state, cursor, status: "running", error: null });
     kick(runId);
 }
@@ -427,7 +662,7 @@ export async function reviewStep(runId, stepId, action) {
             }
         }
         state.history.push(stepId);
-        const cursor = nextStepId(run.definition, stepId, branchValues(state.values, state.outputs));
+        const cursor = await advance(run, stepId, state);
         await updateRun(runId, { state, cursor, status: "running", error: null });
         kick(runId);
         return;
@@ -458,6 +693,8 @@ export async function goBack(runId) {
     if (!previous) {
         throw new RunConflict("Kein vorheriger Schritt.");
     }
+    // A decision that failed belongs to the step left behind.
+    delete state.deciding;
     await updateRun(runId, { state, cursor: previous, status: "waiting_input", error: null });
 }
 export async function retry(runId) {
@@ -578,6 +815,15 @@ export async function runView(run, brand) {
         step,
         values: run.state.values,
         prefill: step?.type === "page" ? prefillOf(step, run, closed) : {},
+        ...(step?.type === "page" ? viewContext(await pageContext(run, step)) : {}),
+        ...(run.mode === "test" && run.state.decisions
+            ? {
+                decisions: Object.fromEntries(Object.entries(run.state.decisions).map(([id, d]) => [
+                    id,
+                    { ...d, over: def.steps.find((s) => s.id === id)?.next ?? [] },
+                ])),
+            }
+            : {}),
         closed,
         outputs: Object.fromEntries(shownIds.map((id) => [id, run.state.outputs[id]]).filter(([, o]) => o)),
         shown,

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

@@ -1,4 +1,6 @@
+import { pOf } from "@engenty-wizards/shared/decision";
 import { allFields, dataRef, isDecisionStep, LOCALES, templateRefs, wizardLang, } from "@engenty-wizards/shared/definition";
+import { SURFACE_GUIDE, validateSurface, } from "@engenty-wizards/shared/surface";
 import { Agent } from "@mastra/core/agent";
 import { generateText, Output } from "ai";
 import { z } from "zod";
@@ -12,7 +14,9 @@ import { buildStepTools } from "../tools/index.js";
 import { spaceContextOf } from "../tools/plugin.js";
 import { personUploads } from "../tools/store.js";
 import { runWidgetStep } from "../widgets/step.js";
+import { decide } from "./decide.js";
 import { prepareInputs } from "./prepare.js";
+import { runSurfaceStep } from "./surface.js";
 import { answersAsText, colorLine, factLines, renderTemplate, resolveRef, } from "./template.js";
 import { StepError } from "./types.js";
 /** Today's date as the wizard's people write it. */
@@ -51,7 +55,12 @@ async function previousResult(ctx, stepId) {
 async function revisionBlock(ctx, stepId) {
     const note = ctx.state.notes[stepId];
     if (!note) {
-        return "";
+        // A branch back to this step (a loop) runs it again: it builds on what it made last time.
+        const looped = Object.entries(ctx.state.loops ?? {}).some(([key, n]) => n > 0 && key.endsWith(`→${stepId}`));
+        const prev = looped ? await previousResult(ctx, stepId) : "";
+        return prev
+            ? `# EARLIER ATTEMPT\nA later step sent the run back to this step. What it made last time — improve on it with what is known now:\n"""\n${prev}\n"""`
+            : "";
     }
     const prev = await previousResult(ctx, stepId);
     return `# REVISION REQUEST\nThe person reviewed the previous result and asked for this change:\n"""${note}"""\n\n${prev ? `Previous result:\n"""\n${prev}\n"""` : ""}`;
@@ -88,6 +97,11 @@ function outputSchema(step) {
             case "choice":
                 shape[f.id] = z.enum(f.options).describe(d);
                 break;
+            case "score":
+                shape[f.id] = z
+                    .enum(f.options)
+                    .describe(`${d} (lowest to highest)`);
+                break;
             case "table":
                 shape[f.id] = f.columns?.length
                     ? z
@@ -148,7 +162,186 @@ async function seenPhotos(step, ctx, resolved, uploads) {
     }
     return out;
 }
+/**
+ * A decision step: its yes/no, choice and score fields are the questions, its prompt the state,
+ * answered in one call through decide() — with probabilities where a decision model answers.
+ */
+async function decideStep(step, prompt, ctx) {
+    const fields = step.output.fields ?? [];
+    const questions = {};
+    for (const f of fields) {
+        const instructions = f.description ?? f.id;
+        if (f.kind === "yesno") {
+            questions[f.id] = { type: "noul", instructions };
+        }
+        else if (f.kind === "choice") {
+            questions[f.id] = {
+                type: "choice",
+                instructions,
+                criteria: Object.fromEntries((f.options ?? []).map((o) => [o, null])),
+            };
+        }
+        else if (f.kind === "score") {
+            questions[f.id] = { type: "score", instructions, criteria: f.options ?? [] };
+        }
+    }
+    const decision = await decide({
+        state: prompt,
+        questions,
+        call: ctx.call,
+        signal: ctx.signal,
+        charge: ctx.chargeUsd,
+    });
+    const json = {};
+    const decided = {};
+    for (const [id, answer] of Object.entries(decision.answers)) {
+        json[id] =
+            answer.type === "noul"
+                ? answer.noul >= 0.5
+                : answer.type === "choice"
+                    ? answer.choice
+                    : answer.label;
+        decided[id] = Math.round(pOf(answer) * 1000) / 1000;
+    }
+    const text = fields
+        .map((f) => {
+        const value = json[f.id];
+        return `${f.description ?? f.id}: ${value === true ? "ja" : value === false ? "nein" : String(value)}`;
+    })
+        .join("\n");
+    return { text, json, decided, at: new Date().toISOString() };
+}
+/** The JSON array in a model's answer, fenced or not. */
+function jsonArrayIn(text) {
+    const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/)?.[1] ?? text;
+    const start = fenced.indexOf("[");
+    const end = fenced.lastIndexOf("]");
+    if (start < 0 || end <= start) {
+        return null;
+    }
+    try {
+        return JSON.parse(fenced.slice(start, end + 1));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The view an agent step composes of its result: the standard class writes components from the
+ * surface catalog bound to the step's fields, the catalog's validator checks them, and one try
+ * with the issues follows. Without a valid view the plain result shows: the step never fails
+ * for its view.
+ */
+async function composeSurface(step, json, ctx) {
+    const keys = Object.keys(json);
+    const fields = (step.output.fields ?? [])
+        .map((f) => `- /${f.id} (${f.kind}${f.columns ? `: ${f.columns.join(", ")}` : ""}): ${f.description ?? ""}`)
+        .join("\n");
+    const sample = JSON.stringify(json).slice(0, 4000);
+    try {
+        const writer = await textModel("standard", ctx.call);
+        let issues = [];
+        for (let attempt = 0; attempt < 2; attempt++) {
+            const result = await generateText({
+                model: writer.model,
+                abortSignal: ctx.signal,
+                prompt: [
+                    `Compose a view of this result for the person who ran "${ctx.def.title}". Answer with the JSON array of components only.`,
+                    SURFACE_GUIDE,
+                    `# THE DATA (bind by path, never copy values)\n${fields}\n\nSample: ${sample}`,
+                    issues.length
+                        ? `# YOUR LAST ANSWER HAD THESE PROBLEMS — fix them\n${issues.join("\n")}`
+                        : "",
+                ]
+                    .filter(Boolean)
+                    .join("\n\n"),
+            });
+            await ctx.chargeUsd(costOf(writer, result.usage));
+            const components = jsonArrayIn(result.text);
+            issues = validateSurface(components, keys).map((i) => i.message);
+            if (!issues.length) {
+                return { components: components, data: json };
+            }
+        }
+        console.warn(`[step ${step.id}] no valid view:`, issues.join("; "));
+    }
+    catch (err) {
+        if (ctx.signal.aborted) {
+            throw err;
+        }
+        console.warn(`[step ${step.id}] view not composed:`, err.message);
+    }
+    return undefined;
+}
+/** An agent step runs this many times at most with `each`; more entries are left out. */
+const MAX_AGENT_ENTRIES = 20;
+/** The entries an agent step with `each` runs for: rows of a table, entries of a list, list rows. */
+function agentEntries(step, ctx) {
+    const ref = dataRef(step.each ?? "");
+    const list = ref.match(/^lists\.([a-zA-Z][a-zA-Z0-9_]*)$/)?.[1];
+    const value = list
+        ? (ctx.scope.lists?.[list]?.rows ?? []).map((r) => r.cells)
+        : resolveRef(ref, ctx.scope);
+    return (Array.isArray(value) ? value : []).slice(0, MAX_AGENT_ENTRIES);
+}
+/**
+ * An agent step with `each`: the step once per entry, one after the other, each reading its
+ * entry as {{item}}. The results become one table — the entry's columns and the step's output
+ * fields — and one text with a heading per entry.
+ */
+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.");
+    }
+    // The view, if any, is composed once over the table of all entries.
+    const single = {
+        ...step,
+        each: undefined,
+        output: { ...step.output, surface: false },
+    };
+    const rows = [];
+    const texts = [];
+    const assets = [];
+    for (const [index, item] of entries.entries()) {
+        await ctx.emit("info", { code: "entry", params: { n: index + 1, total: entries.length } });
+        const scope = { ...ctx.scope, entry: { item, index, count: entries.length } };
+        const out = await runAgentStep(single, { ...ctx, scope });
+        const own = item && typeof item === "object" ? item : { item };
+        const json = out.json && typeof out.json === "object" ? out.json : {};
+        rows.push({ ...own, ...json });
+        const title = Object.values(own).find((v) => typeof v === "string") ?? `${index + 1}`;
+        texts.push(`## ${String(title)}\n\n${out.text ?? ""}`.trim());
+        assets.push(...(out.assets ?? []));
+    }
+    const json = { rows };
+    const surface = step.output.surface
+        ? await composeSurface({
+            ...step,
+            output: {
+                ...step.output,
+                fields: [
+                    {
+                        id: "rows",
+                        kind: "table",
+                        description: "One row per entry: its columns and the step's fields",
+                    },
+                ],
+            },
+        }, json, ctx)
+        : undefined;
+    return {
+        text: texts.join("\n\n"),
+        json,
+        ...(surface ? { surface } : {}),
+        assets: assets.length ? assets : undefined,
+        at: new Date().toISOString(),
+    };
+}
 export async function runAgentStep(step, ctx) {
+    if (step.each) {
+        return runAgentEach(step, ctx);
+    }
     const resolved = await textModel(step.model ?? "high", { ...ctx.call, effort: step.effort });
     const uploads = await personUploads(ctx);
     const { tools, assets, close } = await buildStepTools(step, ctx, resolved, uploads);
@@ -192,22 +385,7 @@ export async function runAgentStep(step, ctx) {
             .join("\n\n");
         // A decision needs no agent: its questions go to the classifier class in one call.
         if (isDecisionStep(step) && uploads.length === 0) {
-            const { schema, fields } = outputSchema(step);
-            const decision = await generateText({
-                model: resolved.model,
-                abortSignal: ctx.signal,
-                output: Output.object({ schema }),
-                prompt,
-            });
-            await ctx.chargeUsd(costOf(resolved, decision.usage));
-            const json = decision.output;
-            const text = fields
-                .map((f) => {
-                const value = json[f.id];
-                return `${f.description ?? f.id}: ${value === true ? "ja" : value === false ? "nein" : String(value)}`;
-            })
-                .join("\n");
-            return { text, json, at: new Date().toISOString() };
+            return decideStep(step, prompt, ctx);
         }
         const agent = new Agent({
             id: `step-${step.id}`,
@@ -260,7 +438,14 @@ export async function runAgentStep(step, ctx) {
         });
         await ctx.chargeUsd(costOf(structurer, structured.usage));
         const json = tablesToRecords(structured.output, fields);
-        return { text, json, assets: assets.length ? assets : undefined, at: new Date().toISOString() };
+        const surface = step.output.surface ? await composeSurface(step, json, ctx) : undefined;
+        return {
+            text,
+            json,
+            ...(surface ? { surface } : {}),
+            assets: assets.length ? assets : undefined,
+            at: new Date().toISOString(),
+        };
     }
     finally {
         await close();
@@ -604,5 +789,8 @@ export async function runAutomaticStep(step, ctx) {
     if (step.type === "film") {
         return runFilmStep(step, ctx);
     }
+    if (step.type === "surface") {
+        return runSurfaceStep(step, ctx);
+    }
     throw new StepError(`Step ${step.id} is not automatic.`);
 }