@engenty/wizards-runtime 0.0.0-stage → 0.7.5

package/apps/runtime/dist/browser/fast/run.js

@@ -0,0 +1,249 @@
+// The loop: observe → decide → (text) → act → observe, until DONE, BLOCKED,
+// the step budget, an ambiguous step (the planner LLM takes over), or
+// the seat is gone. Ported from engenty-pro, which took it from jev-ultrafast
+// `agent.py` `Agent.command`.
+import { buildActionSpace } from "./action-space.js";
+import { decide, tiebreak } from "./decide.js";
+import { FastLoopDriver, StalePageError } from "./driver.js";
+import { buildFieldContext } from "./text-helper.js";
+/** How much page text the planner gets back. */
+const RESULT_TEXT_CHARS = 1500;
+/** Three consecutive non-wait steps that changed nothing = stuck. */
+const STUCK_WINDOW = 3;
+/**
+ * A stale or covered target is re-observed after the page settles; each
+ * retry re-asks the classifier on the fresh observation.
+ */
+const STALE_RETRIES_PER_STEP = 3;
+/** Every note that stops short of DONE ends with the way back. */
+const RESUME = "Do that one step with the browser_* tools, then call browser_run_fast again with the same goal.";
+function describe(step) {
+    return step.target === null
+        ? step.operation
+        : `${step.operation} → [${step.target}] ${step.label}`;
+}
+/** What the acted-on element shows after the step, for the history. */
+function valueAfter(page, action) {
+    if (action.node === undefined) {
+        return null;
+    }
+    const now = page.actions.find((a) => a.node === action.node && a.kind === action.kind);
+    if (!now) {
+        return null;
+    }
+    if (action.kind === "fill") {
+        return now.value ?? null;
+    }
+    if (action.kind === "select") {
+        return now.current_value ?? null;
+    }
+    return now.checked ?? null;
+}
+export async function runFastLoop(input) {
+    const driver = new FastLoopDriver(input.page);
+    const history = [];
+    const startedAt = performance.now();
+    const totals = { input_tokens: 0, jev_latency_ms: 0, text_latency_ms: 0 };
+    let page = await driver.observe();
+    // The helper runs alongside the classifier: as soon as a page with a
+    // typeable field is observed, its values are asked for, so a TYPE_TEXT
+    // decision finds them ready (one call per page, cached per field).
+    const prefetch = { current: null };
+    const prefetchText = (snapshot) => {
+        if (prefetch.current?.fingerprint === snapshot.fingerprint) {
+            return;
+        }
+        const field = snapshot.actions.find((a) => a.kind === "fill");
+        if (!field) {
+            prefetch.current = null;
+            return;
+        }
+        const context = buildFieldContext(input.goal, field, snapshot, history);
+        prefetch.current = {
+            fingerprint: snapshot.fingerprint,
+            promise: Promise.resolve()
+                .then(() => input.fieldText(context))
+                .then((result) => {
+                totals.text_latency_ms += result?.latency_ms ?? 0;
+            }, () => {
+                // The per-field read below reports the failure if the step needs it.
+            }),
+        };
+    };
+    prefetchText(page);
+    const finish = (status, note, withElements) => ({
+        elapsed_ms: Math.round(performance.now() - startedAt),
+        elements: withElements ? buildActionSpace(page.actions).elements : null,
+        history,
+        note,
+        page: {
+            text: page.text.slice(0, RESULT_TEXT_CHARS),
+            title: page.title,
+            url: page.url,
+        },
+        status,
+        steps: history.length,
+        totals,
+    });
+    let staleRetries = 0;
+    while (history.length < input.maxSteps) {
+        if (input.shouldStop?.()) {
+            return finish("interrupted", "The seat was taken or the run stopped; no further step ran.", false);
+        }
+        if (!(await driver.fresh(page))) {
+            page = await driver.observe();
+            prefetchText(page);
+        }
+        const decideInput = {
+            client: input.client,
+            goal: input.goal,
+            history,
+            ...(input.model ? { model: input.model } : {}),
+            page,
+        };
+        let decision;
+        try {
+            decision = await decide(decideInput);
+        }
+        catch (error) {
+            return finish("error", `The classifier gave no usable decision: ${error instanceof Error ? error.message : String(error)}. ${RESUME}`, true);
+        }
+        totals.jev_latency_ms += decision.latency_ms;
+        totals.input_tokens += decision.usage?.input_tokens ?? 0;
+        let tiebreakProbability = null;
+        if (decision.margin < input.minMargin) {
+            const best = {
+                label: decision.target
+                    ? (page.actions.find((a) => a.id === decision.choice)?.label ?? decision.choice)
+                    : decision.operation,
+                operation: decision.operation,
+                target: decision.target,
+            };
+            const contest = decision.runnerUp
+                ? `${describe(best)} (${(decision.runnerUp.joint + decision.margin).toFixed(2)}) and ${describe(decision.runnerUp)} (${decision.runnerUp.joint.toFixed(2)})`
+                : describe(best);
+            let verdict;
+            try {
+                verdict = await tiebreak({ ...decideInput, decision });
+            }
+            catch (error) {
+                return finish("error", `The tiebreak gave no usable answer: ${error instanceof Error ? error.message : String(error)}. ${RESUME}`, true);
+            }
+            totals.jev_latency_ms += verdict.latency_ms;
+            totals.input_tokens += verdict.usage?.input_tokens ?? 0;
+            if (verdict.winner === null) {
+                return finish("uncertain", `The classifier could not choose between ${contest}; a tiebreak did not settle it either (${verdict.probability.toFixed(2)}). ${RESUME}`, true);
+            }
+            tiebreakProbability = verdict.probability;
+            if (verdict.winner === "runner_up" && decision.runnerUp) {
+                const chosen = decision.runnerUp;
+                decision = {
+                    ...decision,
+                    choice: chosen.choice,
+                    operation: chosen.operation,
+                    probability: chosen.probability,
+                    target: chosen.target,
+                };
+            }
+        }
+        if (decision.choice === "DONE" || decision.choice === "BLOCKED") {
+            if (!(await driver.fresh(page))) {
+                page = await driver.observe();
+                prefetchText(page);
+                continue;
+            }
+            const done = decision.choice === "DONE";
+            return finish(done ? "done" : "blocked", done
+                ? "The classifier saw every requirement of the goal visibly satisfied."
+                : `The classifier found no supported operation that makes progress. ${RESUME} If the page itself is the obstacle, ask the person.`, !done);
+        }
+        const action = page.actions.find((a) => a.id === decision.choice);
+        if (!action) {
+            return finish("error", `Decision named an action the page did not offer. ${RESUME}`, true);
+        }
+        let text = null;
+        let textWait = 0;
+        let textSource = null;
+        try {
+            if (action.kind === "fill") {
+                if (!(await driver.fresh(page))) {
+                    throw new StalePageError("Page changed before text generation.");
+                }
+                const waitStarted = performance.now();
+                if (prefetch.current?.fingerprint === page.fingerprint) {
+                    await prefetch.current.promise;
+                }
+                const context = buildFieldContext(input.goal, action, page, history);
+                const result = await input.fieldText(context);
+                textWait = Math.round(performance.now() - waitStarted);
+                // A hit on the prefetched page reports 0; a value the prefetch did
+                // not cover (another source, a changed page) reports its own call.
+                totals.text_latency_ms += result.latency_ms;
+                text = result.text;
+                textSource = result.source;
+                if (text === null) {
+                    return finish("uncertain", `The field "${action.label}" needs a value the goal does not contain. Supply it in the goal and call browser_run_fast again, or ask the person.`, true);
+                }
+            }
+            await driver.act(action, page, text);
+            staleRetries = 0;
+        }
+        catch (error) {
+            if (error instanceof StalePageError && staleRetries < STALE_RETRIES_PER_STEP) {
+                staleRetries += 1;
+                // The target moved or is covered because the page is still changing
+                // (a calendar re-rendering, a dialog sliding in). Let it come to rest
+                // before observing again, or the retry sees the same frame.
+                await driver.settle();
+                page = await driver.observe();
+                prefetchText(page);
+                continue;
+            }
+            return finish("error", `Step failed: ${error instanceof Error ? error.message : String(error)}. ${RESUME}`, true);
+        }
+        const entry = {
+            action: action.label,
+            confidence: decision.confidence,
+            kind: action.kind,
+            latency_ms: decision.latency_ms,
+            operation: decision.operation,
+            page_changed: null,
+            probability: decision.probability,
+            step: history.length + 1,
+            target: decision.target,
+            text,
+            text_latency_ms: textWait,
+            url: page.url,
+            usage: decision.usage,
+            value_after: null,
+        };
+        history.push(entry);
+        const before = page.fingerprint;
+        page = await driver.observe();
+        entry.page_changed = page.fingerprint !== before;
+        entry.url = page.url;
+        entry.value_after = valueAfter(page, action);
+        prefetchText(page);
+        input.onStep?.({
+            confidence: decision.confidence,
+            latency_ms: decision.latency_ms,
+            margin: decision.margin,
+            operation: decision.operation,
+            page_changed: entry.page_changed,
+            probability: decision.probability,
+            step: entry.step,
+            target_confidence: decision.targetConfidence,
+            target_label: decision.target ? action.label : null,
+            text_latency_ms: textWait,
+            text_source: textSource,
+            tiebreak: tiebreakProbability,
+            usage: decision.usage,
+        });
+        const recent = history.slice(-STUCK_WINDOW);
+        if (recent.length === STUCK_WINDOW &&
+            recent.every((h) => h.page_changed === false && h.kind !== "wait")) {
+            return finish("blocked", `The last ${STUCK_WINDOW} steps changed nothing on the page. ${RESUME}`, true);
+        }
+    }
+    return finish("budget", `Stopped at the ${input.maxSteps}-step budget for one call. Check the page, then call browser_run_fast again with the remaining goal.`, true);
+}

package/apps/runtime/dist/browser/fast/span-picker.js

@@ -0,0 +1,153 @@
+// Field values without generation: the goal is cut into candidate spans
+// (dates, names, numbers, quoted strings) and the classifier picks, per
+// typeable field, which span is that field's value — or NONE. A span picker
+// cannot invent a value, which is the contract the text helper promises
+// ("it never invents data"); what it cannot do is rewrite one, so NONE and a
+// close call fall through to the LLM helper. Ported from engenty-pro's fast loop.
+import { validateChoiceAnswer } from "./classifier.js";
+import { SPAN_VALUE } from "./instructions.js";
+/** At most this many spans are offered; beyond that the goal is prose, not values. */
+export const MAX_SPANS = 20;
+/** A span must lead the runner-up by this much of the head's mass. */
+export const SPAN_MIN_MARGIN = 0.2;
+export const NONE = "NONE";
+const MONTH = "(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Sept|Oct|Nov|Dec|Jän|Mär|Mai|Okt|Dez)[a-zäö]*\\.?";
+const SPAN_PATTERNS = [
+    // "12 Oct 2026", "12. Oktober 2026", "Oct 12, 2026", "October 12"
+    new RegExp(`\\b\\d{1,2}\\.?\\s?${MONTH}(?:,?\\s\\d{4})?\\b|\\b${MONTH}\\s\\d{1,2}(?:,?\\s\\d{4})?\\b`, "gi"),
+    // 2026-10-12, 12.10.2026, 10/12/2026, 12.10.
+    /\b\d{4}-\d{2}-\d{2}\b|\b\d{1,2}[./]\d{1,2}(?:[./]\d{2,4})?\b/g,
+    // "quoted" or 'quoted' or „quoted“
+    /["“„']([^"“”„']{1,80})["”“']/g,
+    // e-mail
+    /\b[\w.+-]+@[\w-]+\.[\w.-]+\b/g,
+    // number with a unit or currency: 1 126 €, €1,126, 2 adults, 3 nights
+    /(?:[€$£]\s?\d[\d.,\s]*\d|\b\d[\d.,]*\s?(?:€|EUR|USD|\$|£|%|kg|km|adults?|nights?|persons?|people|passengers?|rooms?|days?|hours?|h))\b/gi,
+    // runs of capitalised words, incl. "Seoul, South Korea", "New York"
+    /\b(?:\p{Lu}[\p{L}\p{M}'’-]+)(?:(?:,\s|\s)(?:\p{Lu}[\p{L}\p{M}'’-]+))*\b/gu,
+    // bare integers
+    /\b\d{1,9}\b/g,
+];
+const SENTENCE_STARTERS = new Set([
+    "a",
+    "an",
+    "and",
+    "book",
+    "click",
+    "enter",
+    "fill",
+    "find",
+    "for",
+    "from",
+    "go",
+    "in",
+    "on",
+    "open",
+    "pick",
+    "search",
+    "select",
+    "set",
+    "the",
+    "then",
+    "to",
+    "type",
+    "use",
+    "with",
+]);
+/**
+ * Candidate values in the goal, in order of appearance, deduplicated. A
+ * quoted span is offered without its quotes. A lone capitalised word that is
+ * only a sentence start ("Search flights…") is not a value.
+ */
+export function extractSpans(goal) {
+    const found = [];
+    for (const pattern of SPAN_PATTERNS) {
+        pattern.lastIndex = 0;
+        for (const match of goal.matchAll(pattern)) {
+            const text = (match[1] ?? match[0]).trim();
+            if (!text) {
+                continue;
+            }
+            found.push({ index: match.index ?? 0, text });
+        }
+    }
+    found.sort((a, b) => a.index - b.index);
+    const spans = [];
+    const seen = new Set();
+    for (const { index, text } of found) {
+        if (seen.has(text)) {
+            continue;
+        }
+        if (/^\p{Lu}[\p{L}]*$/u.test(text) &&
+            SENTENCE_STARTERS.has(text.toLowerCase()) &&
+            (index === 0 || /[.!?;:]\s*$/.test(goal.slice(0, index)))) {
+            continue;
+        }
+        seen.add(text);
+        spans.push(text);
+        if (spans.length >= MAX_SPANS) {
+            break;
+        }
+    }
+    return spans;
+}
+/** Head key per field: `field_1`, `field_2`, … in the fields' order. */
+function headKey(position) {
+    return `field_${position + 1}`;
+}
+/**
+ * One classifier call for every typeable field on the page: which span, if
+ * any, is that field's value. Returns null when the goal offers no spans.
+ */
+export async function pickSpans(input) {
+    const spans = extractSpans(input.context.goal);
+    if (spans.length === 0) {
+        return null;
+    }
+    const ids = spans.map((_, i) => `s${i + 1}`);
+    const criteria = {
+        [NONE]: "No offered piece is this field's value.",
+    };
+    ids.forEach((id, i) => {
+        criteria[id] = spans[i];
+    });
+    const fields = input.context.fields;
+    const questions = {};
+    fields.forEach((field, i) => {
+        questions[headKey(i)] = {
+            criteria,
+            instructions: {
+                field: { label: field.label, role: field.role, value: field.value },
+                goal: input.context.goal,
+                rules: SPAN_VALUE,
+            },
+            type: "choice",
+        };
+    });
+    const startedAt = performance.now();
+    const result = await input.client.systemOne({
+        ...(input.model ? { model: input.model } : {}),
+        questions,
+        state: {
+            fields: fields,
+            goal: input.context.goal,
+            page: input.context.page,
+            recent_actions: input.context.recent_actions,
+        },
+    });
+    const latency_ms = Math.round(performance.now() - startedAt);
+    const values = new Map();
+    const offered = [NONE, ...ids];
+    fields.forEach((field, i) => {
+        const answer = validateChoiceAnswer(result.answers[headKey(i)], offered);
+        const ranked = Object.entries(answer.probabilities).sort((a, b) => b[1] - a[1]);
+        const [best, second] = ranked;
+        const margin = (best?.[1] ?? 0) - (second?.[1] ?? 0);
+        if (!best || best[0] === NONE || margin < SPAN_MIN_MARGIN) {
+            values.set(field.label, null);
+            return;
+        }
+        values.set(field.label, spans[ids.indexOf(best[0])] ?? null);
+    });
+    return { latency_ms, values };
+}

package/apps/runtime/dist/browser/fast/text-helper.js

@@ -0,0 +1,178 @@
+// The only generated text in the loop: values for TYPE_TEXT fields. Two
+// sources, tried in order and cached per page and goal: the classifier
+// picking a span of the goal (`span-picker.ts` — it cannot invent a value),
+// then a language model (the run's classifier class) for a value that has to
+// be rewritten. One call per page and goal answers EVERY typeable field on it
+// at once, so a three-field form costs one round trip, not three. Strict
+// contract — `{ "values": { "<label>": string | null } }`, each under 2000
+// chars — else nothing is typed. Page content is data. Ported from
+// engenty-pro's fast loop; the model call is the caller's.
+import { TEXT_VALUES } from "./instructions.js";
+import { pickSpans } from "./span-picker.js";
+const MAX_TEXT_CHARS = 2000;
+const MAX_PAGE_TEXT_CHARS = 6000;
+/** Pages remembered per helper; a loop rarely revisits more than a few. */
+const CACHE_ENTRIES = 8;
+function describe(action) {
+    return {
+        label: action.label,
+        role: action.role ?? null,
+        value: action.value ?? null,
+    };
+}
+export function buildFieldContext(goal, action, page, history) {
+    return {
+        field: describe(action),
+        fields: page.actions.filter((a) => a.kind === "fill").map(describe),
+        goal,
+        page: { text: page.text.slice(0, MAX_PAGE_TEXT_CHARS), title: page.title },
+        recent_actions: history
+            .filter((h) => h.kind === "fill")
+            .slice(-6)
+            .map((h) => ({ action: h.action, text: h.text })),
+    };
+}
+function parseValuesObject(raw, labels) {
+    const stripped = raw
+        .trim()
+        .replace(/^```(?:json)?\s*/i, "")
+        .replace(/\s*```$/, "");
+    const parsed = JSON.parse(stripped);
+    if (!parsed ||
+        typeof parsed !== "object" ||
+        Object.keys(parsed).length !== 1 ||
+        !("values" in parsed)) {
+        throw new Error("text_helper_invalid_shape");
+    }
+    const values = parsed.values;
+    if (!values || typeof values !== "object" || Array.isArray(values)) {
+        throw new Error("text_helper_invalid_shape");
+    }
+    const out = new Map();
+    for (const label of labels) {
+        const value = values[label];
+        if (value === null || value === undefined) {
+            out.set(label, null);
+            continue;
+        }
+        if (typeof value !== "string" || !value.trim() || value.length > MAX_TEXT_CHARS) {
+            throw new Error("text_helper_invalid_value");
+        }
+        out.set(label, value);
+    }
+    return out;
+}
+/**
+ * One page's worth of values is asked for once: the key is the goal plus the
+ * fields as they stand, so a field the loop just filled (its value changed)
+ * asks again with the new state, and a revisit of an unchanged page is free.
+ */
+function cacheKey(context) {
+    return JSON.stringify([context.goal, context.page.title, context.fields]);
+}
+export function createFieldText(options) {
+    const spans = options.spans ?? null;
+    const cache = new Map();
+    /** Keys whose span pick already ran (with or without a value). */
+    const spansAsked = new Set();
+    const inflight = new Map();
+    const remember = (key) => {
+        let entry = cache.get(key);
+        if (!entry) {
+            entry = new Map();
+            cache.set(key, entry);
+            if (cache.size > CACHE_ENTRIES) {
+                const oldest = cache.keys().next().value;
+                if (oldest !== undefined) {
+                    cache.delete(oldest);
+                    spansAsked.delete(oldest);
+                }
+            }
+        }
+        return entry;
+    };
+    const askSpans = async (key, context) => {
+        if (!spans || spansAsked.has(key)) {
+            return;
+        }
+        spansAsked.add(key);
+        try {
+            const pick = await pickSpans({
+                client: spans.client,
+                context,
+                ...(spans.model ? { model: spans.model } : {}),
+            });
+            if (!pick) {
+                return;
+            }
+            const known = remember(key);
+            for (const [label, text] of pick.values) {
+                if (text !== null) {
+                    known.set(label, { latency_ms: pick.latency_ms, source: "span", text });
+                }
+            }
+        }
+        catch (error) {
+            console.warn("[browser] the span picker failed; asking the language model:", error instanceof Error ? error.message : String(error));
+        }
+    };
+    const askModel = async (key, context) => {
+        const labels = context.fields.map((f) => f.label);
+        if (!labels.includes(context.field.label)) {
+            labels.push(context.field.label);
+        }
+        const startedAt = performance.now();
+        const text = await options.ask(TEXT_VALUES, JSON.stringify({
+            fields: context.fields,
+            goal: context.goal,
+            page: context.page,
+            recent_actions: context.recent_actions,
+        }));
+        const latency_ms = Math.round(performance.now() - startedAt);
+        let values;
+        try {
+            values = parseValuesObject(text, labels);
+        }
+        catch {
+            throw new Error("text_helper_invalid: no valid field value; nothing typed");
+        }
+        const known = remember(key);
+        for (const [label, value] of values) {
+            if (!known.has(label)) {
+                known.set(label, { latency_ms, source: "llm", text: value });
+            }
+        }
+    };
+    const resolve = async (key, context) => {
+        await askSpans(key, context);
+        if (cache.get(key)?.has(context.field.label)) {
+            return;
+        }
+        await askModel(key, context);
+    };
+    return async (context) => {
+        const key = cacheKey(context);
+        const label = context.field.label;
+        const hit = cache.get(key)?.get(label);
+        if (hit) {
+            return { latency_ms: 0, source: hit.source, text: hit.text };
+        }
+        let pending = inflight.get(key);
+        if (!pending) {
+            pending = resolve(key, context).finally(() => inflight.delete(key));
+            inflight.set(key, pending);
+        }
+        await pending;
+        if (!cache.get(key)?.get(label)) {
+            // Another field's in-flight call did not cover this label (the page
+            // changed between them); ask once more for this page as it stands.
+            await resolve(key, context);
+        }
+        const found = cache.get(key)?.get(label);
+        return {
+            latency_ms: found?.latency_ms ?? 0,
+            source: found?.source ?? "llm",
+            text: found?.text ?? null,
+        };
+    };
+}