@e2e-dev/decision 0.1.0

package/dist/elements.js

@@ -0,0 +1,223 @@
+/** TypeSafe's per-question choice limit; the AI SDK itself has none. */
+const MAX_CHOICES = 255;
+const tappable = new Set([
+    'button',
+    'link',
+    'menuitem',
+    'menuitemcheckbox',
+    'menuitemradio',
+    'tab',
+    'option',
+    'treeitem',
+]);
+const typable = new Set(['textbox', 'searchbox', 'spinbutton', 'combobox']);
+const secretTypable = new Set(['textbox', 'searchbox', 'combobox']);
+const checkable = new Set(['checkbox', 'radio', 'switch']);
+/** Builds the element table and bound targets from the newest observation. */
+export function actionSpace(ctx, observation, canType) {
+    const verbs = ctx.target.verbs;
+    const rows = [];
+    const pageText = [];
+    /** Walks the tree, collecting interactive rows and page text. */
+    const visit = (node, underNativeSelect) => {
+        if (node.states?.disabled !== true && node.states?.hidden !== true) {
+            const operations = [];
+            const role = node.role ?? '';
+            const password = node.inputPurpose === 'password' || node.states?.secure === true;
+            const nativeSelect = role === 'combobox' && (node.children ?? []).some((child) => child.role === 'option');
+            const childSelect = underNativeSelect || nativeSelect;
+            const checkedRadio = role === 'radio' && node.states?.checked === true;
+            if (verbs.has('tap') && tappable.has(role) && !checkable.has(role) && !(role === 'option' && childSelect)) {
+                operations.push('tap');
+            }
+            if (typable.has(role) && !nativeSelect) {
+                if (!password && verbs.has('type') && canType)
+                    operations.push('type');
+                if (verbs.has('typeSecret') && secretTypable.has(role) && ctx.step.secrets.length > 0) {
+                    operations.push('typeSecret');
+                }
+                if (!password && verbs.has('press'))
+                    operations.push('submit');
+            }
+            if (verbs.has('select') && nativeSelect)
+                operations.push('select');
+            // `check` toggles, so a checked radio would be unchecked: offer radios only when unchecked.
+            if (verbs.has('check') && checkable.has(role) && !checkedRadio)
+                operations.push('check');
+            if (operations.length > 0) {
+                rows.push({ node, operations, inViewport: intersects(node, observation.viewport) });
+            }
+            else {
+                const line = pageLine(node);
+                // A checked radio leaves the table, so its state rides on the page text.
+                if (line !== '')
+                    pageText.push(checkedRadio ? `${line} (checked)` : line);
+            }
+        }
+        for (const child of node.children ?? [])
+            visit(child, underNativeSelect || node.role === 'combobox');
+    };
+    visit(observation.tree, false);
+    // Viewport nodes first, then tree order; drop the rest past the cap so
+    // the model can scroll to them, and never block on a large screen.
+    const ordered = [...rows]
+        .map((row, order) => ({ row, order }))
+        .toSorted((a, b) => Number(b.row.inViewport) - Number(a.row.inViewport) || a.order - b.order)
+        .map(({ row }) => row);
+    const omitted = Math.max(0, ordered.length - MAX_CHOICES);
+    const kept = ordered.slice(0, MAX_CHOICES);
+    const targets = new Map();
+    let selectCount = 0;
+    const elements = kept.map((row, position) => {
+        const index = String(position + 1);
+        const label = clip(nodeLabel(row.node), 120);
+        for (const operation of row.operations) {
+            if (operation === 'select') {
+                const options = new Map();
+                for (const [optionIndex, child] of (row.node.children ?? []).entries()) {
+                    if (child.role !== 'option')
+                        continue;
+                    // An option the page hides or disables is no choice: the native
+                    // select cannot perform it, so the model must never see it.
+                    if (child.states?.hidden === true || child.states?.disabled === true)
+                        continue;
+                    // Every select shares one target group and one question, so options
+                    // stop at the per-question cap. They stay out of `omitted`: scrolling
+                    // never reveals an option the cap dropped.
+                    if (selectCount >= MAX_CHOICES)
+                        continue;
+                    const key = `${index}:${optionIndex}`;
+                    const optionLabel = child.name ?? child.text ?? '';
+                    options.set(key, {
+                        description: `select option ${JSON.stringify(optionLabel)} in ${label} [${row.node.id}]`,
+                        optionLabel,
+                        run: () => ctx.actions.select({ id: row.node.id }, optionLabel),
+                    });
+                    selectCount += 1;
+                }
+                if (options.size > 0) {
+                    const group = targets.get('select') ?? new Map();
+                    for (const [key, target] of options)
+                        group.set(key, target);
+                    targets.set('select', group);
+                }
+            }
+            else {
+                const key = index;
+                const target = bind(row.node, operation, label, ctx);
+                const group = targets.get(operation) ?? new Map();
+                group.set(key, target);
+                targets.set(operation, group);
+            }
+        }
+        return {
+            index,
+            role: row.node.role ?? '',
+            label,
+            ...(row.node.value === undefined ? {} : { value: row.node.value }),
+            ...(row.node.states?.checked === undefined ? {} : { checked: row.node.states.checked }),
+            ...(row.node.states?.expanded === undefined ? {} : { expanded: row.node.states.expanded }),
+            operations: row.operations,
+        };
+    });
+    const controls = new Map();
+    if (verbs.has('scroll')) {
+        controls.set('scroll_up', { description: 'scroll viewport up', run: () => ctx.actions.scroll('up') });
+        controls.set('scroll_down', { description: 'scroll viewport down', run: () => ctx.actions.scroll('down') });
+    }
+    if (verbs.has('back')) {
+        controls.set('back', { description: 'back one step in history', run: () => ctx.actions.back() });
+    }
+    return {
+        elements,
+        targets,
+        controls,
+        omitted,
+        pageText: clip(pageText.join('\n'), 6000),
+        fingerprint: fingerprint(observation.path ?? '', observation.tree, observation.viewport),
+    };
+}
+/** Binds one element operation to the runner's actions. */
+function bind(node, operation, label, ctx) {
+    const target = { id: node.id };
+    const where = `${label} [${node.id}]`;
+    switch (operation) {
+        case 'tap':
+            return { description: `tap ${where}`, run: () => ctx.actions.tap(target) };
+        case 'type':
+            return { description: `type into ${where}`, run: (argument = '') => ctx.actions.type(target, argument) };
+        case 'typeSecret':
+            return { description: `typeSecret into ${where}`, run: (argument = '') => ctx.actions.typeSecret(target, argument) };
+        case 'submit':
+            return { description: `submit ${where}`, run: () => ctx.actions.press(target, 'Enter') };
+        case 'check':
+            return { description: `check ${where}`, run: () => ctx.actions.check(target, !(node.states?.checked ?? false)) };
+        case 'select': throw new Error('select binds per option, not per element');
+    }
+}
+/** Label the model reads: name, placeholder, or text. */
+function nodeLabel(node) {
+    return node.name ?? node.attributes?.['placeholder'] ?? node.text ?? '';
+}
+/**
+ * One page-text line for a non-interactive node. A named node keeps its text
+ * when the two differ, as the runner's `formatNode` does: a status named
+ * "Greeting" whose text says "Welcome back, admin!" is the evidence a
+ * completion check needs, and the name alone hides it.
+ */
+function pageLine(node) {
+    const name = (node.name ?? '').trim();
+    const text = (node.text ?? '').replace(/\s+/g, ' ').trim();
+    if (name === '')
+        return text === '' ? (node.attributes?.['placeholder'] ?? '').trim() : text;
+    return text === '' || text === name ? name : `${name} text=${JSON.stringify(text)}`;
+}
+/** Whether the node's box meets the viewport. Nodes without a box stay in tree order. */
+function intersects(node, viewport) {
+    const rect = node.rect;
+    if (rect === undefined)
+        return false;
+    return rect.x < viewport.width && rect.y < viewport.height && rect.x + rect.width > 0 && rect.y + rect.height > 0;
+}
+function clip(text, limit) {
+    return text.length > limit ? text.slice(0, limit) : text;
+}
+/**
+ * Stable hash of the path, the tree content with node ids removed, and
+ * whether each node meets the viewport. Ids change on every capture, so they
+ * stay out. In-view membership lets a scroll that brings other nodes into
+ * view count as progress, while one that moves nothing (the page bottom)
+ * still reads as unchanged; raw coordinates stay out so small layout shifts
+ * do not count.
+ */
+function fingerprint(path, tree, viewport) {
+    let hash = 2166136261;
+    const feed = (text) => {
+        for (let index = 0; index < text.length; index += 1) {
+            hash ^= text.charCodeAt(index);
+            hash = Math.imul(hash, 16777619);
+        }
+    };
+    feed(path);
+    feed('\0');
+    const visit = (node) => {
+        feed(node.role ?? '');
+        feed('\0');
+        feed(node.name ?? '');
+        feed('\0');
+        feed(node.text ?? '');
+        feed('\0');
+        feed(node.value ?? '');
+        feed('\0');
+        feed(JSON.stringify(node.states ?? null));
+        feed('\0');
+        feed(JSON.stringify(node.attributes ?? null));
+        feed('\0');
+        feed(intersects(node, viewport) ? 'v' : '-');
+        feed('\0');
+        for (const child of node.children ?? [])
+            visit(child);
+    };
+    visit(tree);
+    return (hash >>> 0).toString(36);
+}

package/dist/executor.d.ts

@@ -0,0 +1,4 @@
+import type { StepExecutor } from 'e2e';
+import type { DecisionExecutorOptions } from './types.ts';
+/** Builds a step executor that acts through a decision model and an optional text model. */
+export declare function decisionExecutor(options: DecisionExecutorOptions): StepExecutor;

package/dist/executor.js

@@ -0,0 +1,366 @@
+import { AgentError, isAgentError } from 'e2e/agent';
+import { ConfigurationError } from 'e2e/engine';
+import { decide, requireDecide } from './decide.js';
+import { actionSpace } from './elements.js';
+import { assertionRequest, completionRequest, decisionRequest, elementRecords, nonSecretParams, targetKeyIndex, } from './questions.js';
+import { fieldText } from './text.js';
+/** Error codes the runtime owns: rethrown untouched, never absorbed as history. */
+const RUNTIME_CODES = new Set(['STEP_BUDGET_EXHAUSTED', 'STEP_TIMEOUT', 'CANCELLED']);
+/** The handle in the runner's secret-fill summary: `fill secret "<json string>"` at the start. */
+const SECRET_FILL = /^fill secret "(?:[^"\\]|\\.)*"/;
+/** Builds a step executor that acts through a decision model and an optional text model. */
+export function decisionExecutor(options) {
+    if (typeof options !== 'object' || options === null) {
+        throw new ConfigurationError('INVALID_CONFIG', `decisionExecutor() takes an options object; ${EXAMPLE}`);
+    }
+    requireDecide();
+    checkModel(options.model);
+    const minProbability = options.minProbability ?? 0;
+    const minConfidence = options.minConfidence ?? 0;
+    if (!inUnit(minProbability) || !inUnit(minConfidence)) {
+        throw new ConfigurationError('INVALID_CONFIG', 'decisionExecutor({ minProbability, minConfidence }) must be between 0 and 1');
+    }
+    const textModel = options.textModel;
+    return {
+        name: 'decision',
+        version: '1',
+        cache: 'inherit',
+        ...(textModel === undefined ? {} : { model: textModel }),
+        async runStep(ctx) {
+            return run(ctx, options, minProbability, minConfidence);
+        },
+    };
+}
+/** How a valid model reads, for every model error. */
+const EXAMPLE = "pass an AI SDK decision model, e.g. decisionExecutor({ model: typeSafeAi.decisionModel('jev-latest') })";
+/**
+ * Rejects anything the AI SDK cannot decide with, at config load: a model id
+ * string, a language model, or a decision model that cannot answer `choice`.
+ */
+function checkModel(model) {
+    if (typeof model === 'function') {
+        throw new ConfigurationError('INVALID_CONFIG', `decisionExecutor({ model }) got a function, not a model; call it with a model id, ${EXAMPLE}`);
+    }
+    if (typeof model !== 'object' || model === null) {
+        const got = typeof model === 'string' ? `the string ${JSON.stringify(model)}` : String(model);
+        throw new ConfigurationError('INVALID_CONFIG', `decisionExecutor({ model }) got ${got}; ${EXAMPLE}`);
+    }
+    const fields = model;
+    const name = `${String(fields['provider'])}/${String(fields['modelId'])}`;
+    if (typeof fields['doDecide'] !== 'function' && typeof fields['doEvaluate'] !== 'function') {
+        const kind = typeof fields['doGenerate'] === 'function' ? `the language model ${name}` : 'an object that is not a decision model';
+        throw new ConfigurationError('INVALID_CONFIG', `decisionExecutor({ model }) got ${kind}; ${EXAMPLE}`);
+    }
+    if (fields['specificationVersion'] !== 'v4') {
+        throw new ConfigurationError('INVALID_CONFIG', `decisionExecutor({ model }) got ${name}, a ${String(fields['specificationVersion'])} model; the AI SDK decides with v4 decision models`);
+    }
+    const supported = fields['supportedQuestionTypes'];
+    if (!Array.isArray(supported) || !supported.includes('choice')) {
+        throw new ConfigurationError('INVALID_CONFIG', `decisionExecutor({ model }) got ${name}, which does not answer choice questions`);
+    }
+}
+function inUnit(value) {
+    return Number.isFinite(value) && value >= 0 && value <= 1;
+}
+async function run(ctx, options, minProbability, minConfidence) {
+    const model = options.model;
+    let calls = 0;
+    const turns = [];
+    const transcript = [];
+    const history = seedHistory(ctx);
+    const language = ctx.model;
+    const canType = language !== undefined && ctx.target.verbs.has('type');
+    let previousFingerprint;
+    let lastTurn;
+    let rejectedTerminals = 0;
+    const finish = (verdict) => {
+        ctx.attachTurns(turns);
+        ctx.attachTranscript(transcript.join('\n'));
+        return verdict;
+    };
+    const gated = (decision) => decision.probability >= minProbability && decision.confidence >= minConfidence;
+    const describe = (decision) => `p=${decision.probability.toFixed(3)}, confidence ${decision.confidence.toFixed(3)}`;
+    const budgetMessage = () => `The step did not conclude within its ${ctx.budgets.maxModelCalls} decision calls.`;
+    /**
+     * The action space of a complete observation; undefined when the tree is
+     * missing or empty. Verdict views pass `typing: true` so a field the step
+     * filled keeps its row and value even when the step itself cannot type.
+     */
+    const spaceOf = (observation, typing) => {
+        const tree = observation.tree;
+        if (observation.treeUnavailable || tree === undefined || emptyTree(observation))
+            return undefined;
+        return actionSpace(ctx, { path: observation.path ?? '', viewport: observation.viewport, tree }, typing);
+    };
+    const ask = async (request) => {
+        if (calls >= ctx.budgets.maxModelCalls)
+            return undefined;
+        transcript.push(JSON.stringify({ state: request.state, questions: request.questions }));
+        calls += 1;
+        const answers = await decide(ctx, model, request);
+        transcript.push(JSON.stringify(answers));
+        return answers;
+    };
+    const askText = async (field, page) => {
+        if (calls >= ctx.budgets.maxModelCalls)
+            return undefined;
+        if (language === undefined)
+            throw invalid('The decision model chose type with no text model configured.');
+        calls += 1;
+        return fieldText(ctx, language, {
+            goal: ctx.step.instruction,
+            context: ctx.agentContext ?? null,
+            params: nonSecretParams(ctx.step.params),
+            field,
+            page,
+            recentActions: history.slice(-6),
+        });
+    };
+    if (ctx.step.kind === 'assert') {
+        const observation = await ctx.observe({ tree: true });
+        const space = spaceOf(observation, true);
+        if (space === undefined)
+            return finish(inconclusive('A complete semantic observation is required.'));
+        const request = assertionRequest(ctx.step.instruction, observation.path ?? '', space.pageText, elementRecords(space));
+        const answers = await ask(request);
+        if (answers === undefined)
+            return finish(blocked(budgetMessage()));
+        const verdict = need(answers.verdict, 'verdict');
+        const evidence = describe(verdict);
+        if (gated(verdict) && verdict.choice === 'holds') {
+            return finish({ status: 'passed', summary: `The screen shows the assertion holds (${evidence}).` });
+        }
+        if (gated(verdict) && verdict.choice === 'fails') {
+            const summary = `The screen contradicts the assertion (${evidence}).`;
+            return finish({ status: 'failed', errorCode: 'ASSERTION_FAILED', summary });
+        }
+        return finish(inconclusive(`The screen does not settle the assertion (${evidence}).`));
+    }
+    for (;;) {
+        const observation = await ctx.observe({ tree: true });
+        const space = spaceOf(observation, canType);
+        if (space === undefined)
+            return finish(blocked('A complete semantic observation is required.'));
+        const changed = space.fingerprint !== previousFingerprint;
+        if (lastTurn !== undefined) {
+            lastTurn.outcome += changed ? ', page changed' : ', page unchanged';
+            lastTurn = undefined;
+        }
+        const previous = history.at(-1);
+        if (previous !== undefined)
+            history[history.length - 1] = { ...previous, pageChanged: changed };
+        previousFingerprint = space.fingerprint;
+        if (stalled(history))
+            return finish(blocked('Three actions in a row changed nothing on screen.'));
+        const answers = await ask(decisionRequest(ctx, space, history, observation.path ?? ''));
+        if (answers === undefined)
+            return finish(blocked(budgetMessage()));
+        const op = need(answers.operation, 'operation');
+        if (!gated(op))
+            return finish(blocked(`The next operation is uncertain (${describe(op)}).`));
+        if (op.choice === 'blocked')
+            return finish(blocked('The decision model cannot make progress.'));
+        if (op.choice === 'done' || op.choice === 'failed') {
+            const terminal = await terminalCheck(op.choice);
+            if (terminal !== undefined)
+                return finish(terminal);
+            continue;
+        }
+        const { taken, targetAnswer } = resolveTarget(op.choice, answers, space);
+        if (targetAnswer !== undefined && !gated(targetAnswer)) {
+            return finish(blocked(`The next target is uncertain (${describe(targetAnswer)}).`));
+        }
+        if (op.choice === 'type') {
+            const text = await askText(elementField(space, taken.elementKey), space.pageText);
+            if (text === undefined)
+                return finish(blocked(budgetMessage()));
+            if (text === null || text === '') {
+                history.push({ action: taken.target.description, error: 'no value for this field' });
+                continue;
+            }
+            await runTarget(taken, op, targetAnswer, space, text, text);
+            continue;
+        }
+        let secret;
+        if (op.choice === 'typeSecret') {
+            const resolved = resolveSecret(answers.secret);
+            if (resolved.answer !== undefined && !gated(resolved.answer)) {
+                return finish(blocked(`The next secret is uncertain (${describe(resolved.answer)}).`));
+            }
+            secret = resolved.name;
+        }
+        await runTarget(taken, op, targetAnswer, space, secret);
+    }
+    /** Resolves the chosen operation to a bound target. Throws MODEL_OUTPUT_INVALID for anything not offered. */
+    function resolveTarget(choice, answers, space) {
+        const control = space.controls.get(choice);
+        if (control !== undefined)
+            return { taken: { target: control, operation: choice, elementKey: '' } };
+        const group = space.targets.get(choice);
+        if (group === undefined)
+            throw invalid('The decision model chose an unavailable operation.');
+        if (group.size === 1) {
+            const only = group.entries().next();
+            if (only.done === true)
+                throw invalid('The decision model chose an unavailable target.');
+            return { taken: { target: only.value[1], operation: choice, elementKey: only.value[0] } };
+        }
+        const answer = answers[`${choice}_target`];
+        if (answer === undefined)
+            throw invalid('The decision model returned no target answer.');
+        const target = group.get(answer.choice);
+        if (target === undefined)
+            throw invalid('The decision model chose an unavailable target.');
+        return { taken: { target, operation: choice, elementKey: answer.choice }, targetAnswer: answer };
+    }
+    /** Resolves the secret fill: the declared secret, or the gated secret answer with 2+ secrets. */
+    function resolveSecret(answer) {
+        const secrets = ctx.step.secrets;
+        if (secrets.length === 1 && secrets[0] !== undefined)
+            return { name: secrets[0].name };
+        if (answer === undefined)
+            throw invalid('The decision model returned no secret answer.');
+        const found = secrets.find((secret) => secret.name === answer.choice);
+        if (found === undefined)
+            throw invalid('The decision model chose an undeclared secret.');
+        return { name: found.name, answer };
+    }
+    /**
+     * Dispatches a bound target and records the turn and the history entry.
+     * Action failures go back to the model as history; only the runtime's own
+     * stop codes propagate.
+     */
+    async function runTarget(taken, op, targetAnswer, space, argument, typedText) {
+        const targetPart = targetAnswer === undefined ? '' : `, target p=${targetAnswer.probability.toFixed(3)}`;
+        const turn = {
+            index: turns.length + 1,
+            calls: [callLabel(space, taken, op.choice, argument)],
+            outcome: `op p=${op.probability.toFixed(3)}${targetPart}`,
+        };
+        turns.push(turn);
+        lastTurn = turn;
+        const typed = typedText === undefined ? {} : { text: typedText };
+        try {
+            await taken.target.run(argument);
+        }
+        catch (error) {
+            if (isAgentError(error) && RUNTIME_CODES.has(error.code))
+                throw error;
+            const code = isAgentError(error) ? error.code : error instanceof Error ? error.name : 'unknown';
+            history.push({ action: taken.target.description, ...typed, error: code });
+            return;
+        }
+        history.push({ action: taken.target.description, ...typed });
+    }
+    /** One turn call label, e.g. type [3] textbox "New todo" = "Buy milk". */
+    function callLabel(space, taken, operation, text) {
+        if (taken.elementKey === '')
+            return taken.target.description;
+        const element = space.elements.find((item) => item.index === targetKeyIndex(taken.elementKey));
+        if (element === undefined)
+            return taken.target.description;
+        const value = text === undefined ? '' : ` = ${JSON.stringify(text)}`;
+        return `${operation} [${element.index}] ${element.role} ${JSON.stringify(element.label)}${value}`;
+    }
+    /** Field the text helper writes, falling back to the key when the element is gone. */
+    function elementField(space, key) {
+        const element = space.elements.find((item) => item.index === targetKeyIndex(key));
+        if (element === undefined)
+            return { label: key, role: 'textbox' };
+        return { label: element.label, role: element.role, ...(element.value === undefined ? {} : { value: element.value }) };
+    }
+    /**
+     * Verifies a done/failed claim on a fresh screen with the actions taken so
+     * far, but no model reasoning. Returns a verdict, or undefined to continue
+     * the loop. A verdict under the gates confirms nothing.
+     */
+    async function terminalCheck(claim) {
+        const observation = await ctx.observe({ tree: true });
+        const space = spaceOf(observation, true);
+        if (space === undefined)
+            return rejectClaim(claim, 'incomplete observation');
+        const request = completionRequest({
+            goal: ctx.step.instruction,
+            params: nonSecretParams(ctx.step.params),
+            path: observation.path ?? '',
+            pageText: space.pageText,
+            elements: elementRecords(space),
+            history,
+        });
+        const answers = await ask(request);
+        if (answers === undefined)
+            return blocked(budgetMessage());
+        const verdict = need(answers.verdict, 'verdict');
+        const settled = gated(verdict) ? verdict.choice : 'below gate';
+        if (claim === 'done' && settled === 'holds') {
+            return { status: 'passed', summary: `The screen shows the step is done (${describe(verdict)}).` };
+        }
+        if (claim === 'failed' && settled === 'fails') {
+            const summary = `The screen shows the step failed (${describe(verdict)}).`;
+            return { status: 'failed', errorCode: 'ACTION_FAILED', summary };
+        }
+        return rejectClaim(claim, settled);
+    }
+    /**
+     * Records a rejected terminal claim and continues the loop. The second
+     * rejected claim in a step ends it, decided by the check: visible
+     * counter-evidence is a product failure, anything else an automation limit.
+     */
+    function rejectClaim(claim, check) {
+        rejectedTerminals += 1;
+        history.push({ action: claim, error: `check: ${check}` });
+        if (rejectedTerminals < 2)
+            return undefined;
+        if (check === 'fails') {
+            return { status: 'failed', errorCode: 'ACTION_FAILED', summary: `The screen contradicts the ${claim} claim.` };
+        }
+        return blocked(`The screen does not confirm the ${claim} claim (check: ${check}).`);
+    }
+}
+/** A model answer the request never offered: our validation, never the provider's text. */
+function invalid(message) {
+    return new AgentError('MODEL_OUTPUT_INVALID', message);
+}
+/** Requires an answer the model returned; its absence is our bug or a broken transport. */
+function need(answer, what) {
+    if (answer === undefined)
+        throw invalid(`The decision model returned no ${what} answer.`);
+    return answer;
+}
+/**
+ * Seeds history from a replayed prefix, flagging the uncertain action. The
+ * runner's summaries name a filled secret's handle (`fill secret "admin.password"
+ * into ...`, cut at 40 characters); secret names reach the model only as
+ * `secret` question criteria, so that handle becomes `<secret>`. Labels and
+ * values elsewhere in a summary stay as they are, even when they match a name.
+ */
+function seedHistory(ctx) {
+    const prefix = ctx.replayedPrefix;
+    if (prefix === undefined)
+        return [];
+    const redact = (summary) => summary.replace(SECRET_FILL, 'fill secret <secret>');
+    const seeded = prefix.replayedActions.map((action) => ({ action: redact(action), replayed: true }));
+    if (prefix.uncertainAction !== undefined) {
+        seeded.push({ action: redact(prefix.uncertainAction), replayed: true, uncertain: true });
+    }
+    return seeded;
+}
+/** Three recorded actions in a row with no page change. */
+function stalled(history) {
+    if (history.length < 3)
+        return false;
+    return history.slice(-3).every((entry) => entry.pageChanged === false);
+}
+/** No nodes to build an action space from. A truncated observation still acts on what is there. */
+function emptyTree(observation) {
+    const tree = observation.tree;
+    return tree === undefined || ((tree.children ?? []).length === 0 && observation.text.trim() === '');
+}
+/** An automation limitation says nothing about the application correctness. */
+function blocked(summary) {
+    return { status: 'blocked', errorCode: 'AUTOMATION_UNSUPPORTED', summary };
+}
+/** Insufficient evidence must never become an assertion pass. */
+function inconclusive(summary) {
+    return { status: 'failed', errorCode: 'ASSERTION_INCONCLUSIVE', summary };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { decisionExecutor } from './executor.ts';
+export type { DecisionExecutorOptions } from './types.ts';

package/dist/index.js

@@ -0,0 +1 @@
+export { decisionExecutor } from './executor.js';

package/dist/questions.d.ts

@@ -0,0 +1,56 @@
+import type { JsonValue, StepExecutorContext } from 'e2e';
+import type { ActionSpace } from './elements.ts';
+/** One step of history the decision model reads. */
+export interface HistoryEntry {
+    readonly action: string;
+    readonly text?: string;
+    readonly pageChanged?: boolean;
+    readonly error?: string;
+    readonly replayed?: true;
+    readonly uncertain?: true;
+}
+/** One choice question as the request sends it. */
+interface ChoiceQuestion {
+    readonly type: 'choice';
+    readonly instructions: Record<string, JsonValue>;
+    readonly criteria: Record<string, JsonValue | null>;
+}
+export interface DecisionRequest {
+    readonly state: Record<string, JsonValue>;
+    readonly questions: Record<string, ChoiceQuestion>;
+}
+/**
+ * Builds one decide request: the operation question plus one target
+ * question per operation with two or more targets, and a secret question
+ * when two or more secrets are declared. Operations with no targets are
+ * left out; a lone target dispatches with no question.
+ */
+export declare function decisionRequest(ctx: StepExecutorContext, space: ActionSpace, history: readonly HistoryEntry[], path: string): DecisionRequest;
+/** The step params minus secret projections, which travel only as handles. */
+export declare function nonSecretParams(params: Readonly<Record<string, JsonValue>> | undefined): Record<string, JsonValue>;
+/** Element index behind a target key (`7` for both `7` and `7:2`). */
+export declare function targetKeyIndex(key: string): string;
+/** Element table rows as plain records, shared by decision and verdict states. */
+export declare function elementRecords(space: ActionSpace): Record<string, JsonValue>[];
+/**
+ * Builds an assertion verdict request: the goal, the page, and the element
+ * table. No history: an assertion judges the screen alone.
+ */
+export declare function assertionRequest(goal: string, path: string, pageText: string, elements: readonly Record<string, JsonValue>[]): DecisionRequest;
+/** What a completion check reads: the task, its inputs, the screen, and what the step did. */
+export interface CompletionInput {
+    readonly goal: string;
+    readonly params: Record<string, JsonValue>;
+    readonly path: string;
+    readonly pageText: string;
+    readonly elements: readonly Record<string, JsonValue>[];
+    readonly history: readonly HistoryEntry[];
+}
+/**
+ * Builds a completion-check request: the goal with its non-secret params, the
+ * page, the element table, and the actions the step took with the values it
+ * typed. Rejected done/failed claims are left out (they are not actions), and
+ * so is any model reasoning.
+ */
+export declare function completionRequest(input: CompletionInput): DecisionRequest;
+export {};