@mlola/decision-jev 0.1.0

package/dist/provider.js

@@ -0,0 +1,79 @@
+/**
+ * Jev fast-path decision provider (PRD §15, §44).
+ *
+ * One request per normal decision cycle: operation head + speculative target
+ * heads built from the runtime's own action space.
+ */
+import { RuntimeError, headForOperation, } from "@mlola/browser-protocol";
+import { JevClient } from "./client.js";
+import { buildQuestions } from "./questions.js";
+import { renderDecisionState } from "./state.js";
+export class JevDecisionProvider {
+    name;
+    client;
+    constructor(options = {}) {
+        this.name = options.name ?? "typesafe";
+        this.client = new JevClient(options);
+    }
+    get model() {
+        return this.client.model;
+    }
+    async warmup() {
+        await this.client.warmup();
+    }
+    async decide(input) {
+        const { text } = renderDecisionState(input);
+        const { questions, headForOperation: heads } = buildQuestions(input.actionSpace);
+        const { response, latencyMs } = await this.client.decide({ state: text, questions });
+        const operationAnswer = response.answers["operation"];
+        if (!operationAnswer) {
+            throw new RuntimeError("PROVIDER_FAILURE", "Jev did not answer the operation question", {
+                evidence: { answered: Object.keys(response.answers) },
+            });
+        }
+        const operation = operationAnswer.choice;
+        const operationProbabilities = operationAnswer.probabilities ?? {};
+        const output = {
+            operation,
+            operationProbabilities,
+            operationConfidence: operationAnswer.confidence ?? 0,
+            latencyMs,
+            provider: this.name,
+            model: response.model ?? this.client.model,
+            raw: response,
+        };
+        const head = heads[operation] ?? headForOperation(operation);
+        if (head !== undefined) {
+            const targetAnswer = response.answers[head];
+            if (targetAnswer) {
+                output.target = targetAnswer.choice;
+                output.targetProbabilities = targetAnswer.probabilities ?? {};
+                output.targetConfidence = targetAnswer.confidence ?? 0;
+            }
+            else {
+                // No compatible targets were offered, or the answer is missing: the
+                // validator turns this into a DECISION_INVALID for the recovery ladder.
+                output.targetProbabilities = {};
+                output.targetConfidence = 0;
+            }
+        }
+        const usage = usageFrom(response);
+        if (usage)
+            output.usage = usage;
+        return output;
+    }
+}
+const usageFrom = (response) => {
+    const usage = response?.usage;
+    if (!usage)
+        return undefined;
+    const inputTokens = usage["input_tokens"] ?? usage["prompt_tokens"] ?? usage["inputTokens"];
+    const outputTokens = usage["output_tokens"] ?? usage["completion_tokens"] ?? usage["outputTokens"];
+    return {
+        provider: "typesafe",
+        calls: 1,
+        ...(inputTokens !== undefined ? { inputTokens } : {}),
+        ...(outputTokens !== undefined ? { outputTokens } : {}),
+    };
+};
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,YAAY,EACZ,gBAAgB,GAMjB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,SAAS,EAAyB,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AASjD,MAAM,OAAO,mBAAmB;IACrB,IAAI,CAAS;IACb,MAAM,CAAY;IAE3B,YAAY,UAAsC,EAAE;QAClD,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,UAAU,CAAC;QACvC,IAAI,CAAC,MAAM,GAAG,IAAI,SAAS,CAAC,OAAO,CAAC,CAAC;IACvC,CAAC;IAED,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;IAC3B,CAAC;IAED,KAAK,CAAC,MAAM;QACV,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,KAAoB;QAC/B,MAAM,EAAE,IAAI,EAAE,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;QAC5C,MAAM,EAAE,SAAS,EAAE,gBAAgB,EAAE,KAAK,EAAE,GAAG,cAAc,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;QAEjF,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;QAErF,MAAM,eAAe,GAAG,QAAQ,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QACtD,IAAI,CAAC,eAAe,EAAE,CAAC;YACrB,MAAM,IAAI,YAAY,CAAC,kBAAkB,EAAE,2CAA2C,EAAE;gBACtF,QAAQ,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE;aACtD,CAAC,CAAC;QACL,CAAC;QAED,MAAM,SAAS,GAAG,eAAe,CAAC,MAAqC,CAAC;QACxE,MAAM,sBAAsB,GAAG,eAAe,CAAC,aAAa,IAAI,EAAE,CAAC;QAEnE,MAAM,MAAM,GAAmB;YAC7B,SAAS;YACT,sBAAsB;YACtB,mBAAmB,EAAE,eAAe,CAAC,UAAU,IAAI,CAAC;YACpD,SAAS;YACT,QAAQ,EAAE,IAAI,CAAC,IAAI;YACnB,KAAK,EAAE,QAAQ,CAAC,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK;YAC1C,GAAG,EAAE,QAAQ;SACd,CAAC;QAEF,MAAM,IAAI,GAA6B,KAAK,CAAC,SAAS,CAAC,IAAI,gBAAgB,CAAC,SAAS,CAAC,CAAC;QACvF,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,MAAM,YAAY,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAC5C,IAAI,YAAY,EAAE,CAAC;gBACjB,MAAM,CAAC,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC;gBACpC,MAAM,CAAC,mBAAmB,GAAG,YAAY,CAAC,aAAa,IAAI,EAAE,CAAC;gBAC9D,MAAM,CAAC,gBAAgB,GAAG,YAAY,CAAC,UAAU,IAAI,CAAC,CAAC;YACzD,CAAC;iBAAM,CAAC;gBACN,oEAAoE;gBACpE,wEAAwE;gBACxE,MAAM,CAAC,mBAAmB,GAAG,EAAE,CAAC;gBAChC,MAAM,CAAC,gBAAgB,GAAG,CAAC,CAAC;YAC9B,CAAC;QACH,CAAC;QAED,MAAM,KAAK,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;QAClC,IAAI,KAAK;YAAE,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC;QAChC,OAAO,MAAM,CAAC;IAChB,CAAC;CACF;AAED,MAAM,SAAS,GAAG,CAAC,QAAwD,EAAqB,EAAE;IAChG,MAAM,KAAK,GAAG,QAAQ,EAAE,KAAK,CAAC;IAC9B,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,MAAM,WAAW,GAAG,KAAK,CAAC,cAAc,CAAC,IAAI,KAAK,CAAC,eAAe,CAAC,IAAI,KAAK,CAAC,aAAa,CAAC,CAAC;IAC5F,MAAM,YAAY,GAAG,KAAK,CAAC,eAAe,CAAC,IAAI,KAAK,CAAC,mBAAmB,CAAC,IAAI,KAAK,CAAC,cAAc,CAAC,CAAC;IACnG,OAAO;QACL,QAAQ,EAAE,UAAU;QACpB,KAAK,EAAE,CAAC;QACR,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrD,GAAG,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxD,CAAC;AACJ,CAAC,CAAC"}

package/dist/questions.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Dynamic question builder (PRD §14).
+ *
+ * One request carries the operation head plus speculative target heads; only
+ * compatible targets are exposed per operation. The runtime uses the head that
+ * matches the selected operation and ignores the rest.
+ */
+import type { ActionSpace, OperationId, TargetHeadId } from "@mlola/browser-protocol";
+import type { JevRequest } from "@mlola/browser-protocol";
+export interface JevQuestion {
+    type: "choice";
+    instructions: string;
+    criteria: Record<string, string>;
+}
+export interface BuildQuestionsResult {
+    questions: Record<string, JevQuestion>;
+    /** Which question carries the target for each offered operation. */
+    headForOperation: Partial<Record<OperationId, TargetHeadId>>;
+}
+export declare const buildQuestions: (space: ActionSpace) => BuildQuestionsResult;
+export declare const buildJevRequest: (input: {
+    model: string;
+    state: string;
+    questions: Record<string, JevQuestion>;
+}) => JevRequest;
+//# sourceMappingURL=questions.d.ts.map

package/dist/questions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"questions.d.ts","sourceRoot":"","sources":["../src/questions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAEtF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAE1D,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAkCD,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACvC,oEAAoE;IACpE,gBAAgB,EAAE,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC,CAAC;CAC9D;AAED,eAAO,MAAM,cAAc,GAAI,OAAO,WAAW,KAAG,oBAmCnD,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,OAAO;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;CACxC,KAAG,UAIF,CAAC"}

package/dist/questions.js

@@ -0,0 +1,79 @@
+/**
+ * Dynamic question builder (PRD §14).
+ *
+ * One request carries the operation head plus speculative target heads; only
+ * compatible targets are exposed per operation. The runtime uses the head that
+ * matches the selected operation and ignores the rest.
+ */
+import { headForOperation } from "@mlola/browser-protocol";
+const OPERATION_DESCRIPTIONS = {
+    CLICK: "Click one element from click_target.",
+    TYPE_TEXT: "Type text into one field from type_text_target. The runtime decides the exact text.",
+    SELECT: "Choose one option from select_target.",
+    SCROLL_UP: "Scroll up to see content above the current viewport.",
+    SCROLL_DOWN: "Scroll down to see more content.",
+    WAIT: "Wait briefly for the page to settle.",
+    BACK: "Go back in browser history.",
+    FORWARD: "Go forward in browser history.",
+    OPEN_TAB: "Open one link from open_tab_target in a new tab.",
+    SWITCH_TAB: "Switch to one tab from switch_tab_target.",
+    CLOSE_TAB: "Close the current tab.",
+    DOWNLOAD: "Download the file offered by one control from download_target.",
+    UPLOAD: "Upload an already-obtained file (chosen by the runtime) using one control from upload_target.",
+    PRESS: "Press a key.",
+    ACCEPT_DIALOG: "Accept the open browser dialog (e.g. leave the page).",
+    DISMISS_DIALOG: "Dismiss the open browser dialog (e.g. stay on the page).",
+    DONE: "The task (or the current subgoal) is complete.",
+    BLOCKED: "You cannot make progress without human help.",
+    ASK_USER: "You need the person to answer something or perform a step.",
+};
+const HEAD_INSTRUCTIONS = {
+    click_target: "Choose the element to click.",
+    type_text_target: "Choose the field to type into.",
+    select_target: "Choose the dropdown option to select.",
+    switch_tab_target: "Choose the tab to switch to.",
+    open_tab_target: "Choose the link to open in a new tab.",
+    download_target: "Choose the control that downloads the requested file.",
+    upload_target: "Choose the control that accepts the file upload.",
+};
+export const buildQuestions = (space) => {
+    const questions = {};
+    const operationCriteria = {};
+    for (const op of space.operations) {
+        operationCriteria[op] = OPERATION_DESCRIPTIONS[op] ?? op;
+    }
+    questions["operation"] = {
+        type: "choice",
+        instructions: "Choose the single best next operation to make progress on the goal. " +
+            "Prefer operations that are directly supported by the offered targets.",
+        criteria: operationCriteria,
+    };
+    const heads = {};
+    for (const op of space.operations) {
+        const head = headForOperation(op);
+        if (!head)
+            continue;
+        heads[op] = head;
+        const candidates = space.heads[head] ?? [];
+        if (candidates.length === 0)
+            continue;
+        if (questions[head])
+            continue;
+        const criteria = {};
+        for (const candidate of candidates) {
+            criteria[candidate.key] = candidate.label;
+        }
+        questions[head] = {
+            type: "choice",
+            instructions: HEAD_INSTRUCTIONS[head],
+            criteria,
+        };
+    }
+    return { questions, headForOperation: heads };
+};
+export const buildJevRequest = (input) => ({
+    model: input.model,
+    state: input.state,
+    questions: input.questions,
+});
+//# sourceMappingURL=questions.js.map

package/dist/questions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"questions.js","sourceRoot":"","sources":["../src/questions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAS3D,MAAM,sBAAsB,GAAgC;IAC1D,KAAK,EAAE,sCAAsC;IAC7C,SAAS,EAAE,qFAAqF;IAChG,MAAM,EAAE,uCAAuC;IAC/C,SAAS,EAAE,sDAAsD;IACjE,WAAW,EAAE,kCAAkC;IAC/C,IAAI,EAAE,sCAAsC;IAC5C,IAAI,EAAE,6BAA6B;IACnC,OAAO,EAAE,gCAAgC;IACzC,QAAQ,EAAE,kDAAkD;IAC5D,UAAU,EAAE,2CAA2C;IACvD,SAAS,EAAE,wBAAwB;IACnC,QAAQ,EAAE,gEAAgE;IAC1E,MAAM,EAAE,+FAA+F;IACvG,KAAK,EAAE,cAAc;IACrB,aAAa,EAAE,uDAAuD;IACtE,cAAc,EAAE,0DAA0D;IAC1E,IAAI,EAAE,gDAAgD;IACtD,OAAO,EAAE,8CAA8C;IACvD,QAAQ,EAAE,4DAA4D;CACvE,CAAC;AAEF,MAAM,iBAAiB,GAAiC;IACtD,YAAY,EAAE,8BAA8B;IAC5C,gBAAgB,EAAE,gCAAgC;IAClD,aAAa,EAAE,uCAAuC;IACtD,iBAAiB,EAAE,8BAA8B;IACjD,eAAe,EAAE,uCAAuC;IACxD,eAAe,EAAE,uDAAuD;IACxE,aAAa,EAAE,kDAAkD;CAClE,CAAC;AAQF,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAkB,EAAwB,EAAE;IACzE,MAAM,SAAS,GAAgC,EAAE,CAAC;IAElD,MAAM,iBAAiB,GAA2B,EAAE,CAAC;IACrD,KAAK,MAAM,EAAE,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;QAClC,iBAAiB,CAAC,EAAE,CAAC,GAAG,sBAAsB,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC;IAC3D,CAAC;IACD,SAAS,CAAC,WAAW,CAAC,GAAG;QACvB,IAAI,EAAE,QAAQ;QACd,YAAY,EACV,sEAAsE;YACtE,uEAAuE;QACzE,QAAQ,EAAE,iBAAiB;KAC5B,CAAC;IAEF,MAAM,KAAK,GAA+C,EAAE,CAAC;IAC7D,KAAK,MAAM,EAAE,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;QAClC,MAAM,IAAI,GAAG,gBAAgB,CAAC,EAAE,CAAC,CAAC;QAClC,IAAI,CAAC,IAAI;YAAE,SAAS;QACpB,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;QACjB,MAAM,UAAU,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QAC3C,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QACtC,IAAI,SAAS,CAAC,IAAI,CAAC;YAAE,SAAS;QAC9B,MAAM,QAAQ,GAA2B,EAAE,CAAC;QAC5C,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACnC,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC;QAC5C,CAAC;QACD,SAAS,CAAC,IAAI,CAAC,GAAG;YAChB,IAAI,EAAE,QAAQ;YACd,YAAY,EAAE,iBAAiB,CAAC,IAAI,CAAC;YACrC,QAAQ;SACT,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,KAAK,EAAE,CAAC;AAChD,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,KAI/B,EAAc,EAAE,CAAC,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC,KAAK;IAClB,KAAK,EAAE,KAAK,CAAC,KAAK;IAClB,SAAS,EAAE,KAAK,CAAC,SAAS;CAC3B,CAAC,CAAC"}

package/dist/state.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Fast-path state rendering.
+ *
+ * This is everything Jev sees about the world for one decision. It is compact,
+ * structured and provenance-clean: no selectors, no coordinates, no secrets, no
+ * security verdicts (those are applied in code, not in the prompt).
+ */
+import type { DecisionInput, ObservedNode } from "@mlola/browser-protocol";
+export declare const renderElement: (node: ObservedNode) => string;
+export interface RenderedState {
+    text: string;
+}
+export declare const renderDecisionState: (input: DecisionInput) => RenderedState;
+//# sourceMappingURL=state.d.ts.map

package/dist/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAM3E,eAAO,MAAM,aAAa,GAAI,MAAM,YAAY,KAAG,MAalD,CAAC;AAEF,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,eAAO,MAAM,mBAAmB,GAAI,OAAO,aAAa,KAAG,aAmF1D,CAAC"}

package/dist/state.js

@@ -0,0 +1,112 @@
+/**
+ * Fast-path state rendering.
+ *
+ * This is everything Jev sees about the world for one decision. It is compact,
+ * structured and provenance-clean: no selectors, no coordinates, no secrets, no
+ * security verdicts (those are applied in code, not in the prompt).
+ */
+const collapse = (s) => s.replace(/\s+/g, " ").trim();
+const truncate = (s, n) => (s.length <= n ? s : `${s.slice(0, n - 1)}…`);
+export const renderElement = (node) => {
+    const parts = [`[${node.index}]`, node.role, JSON.stringify(truncate(collapse(node.label), 70))];
+    if (node.value !== undefined && node.value.length > 0)
+        parts.push(`value=${JSON.stringify(truncate(node.value, 40))}`);
+    if (node.placeholder)
+        parts.push(`placeholder=${JSON.stringify(truncate(node.placeholder, 30))}`);
+    if (node.flags.checked !== undefined)
+        parts.push(node.flags.checked ? "checked" : "unchecked");
+    if (node.flags.selected !== undefined)
+        parts.push(node.flags.selected ? "selected" : "unselected");
+    if (node.flags.expanded !== undefined)
+        parts.push(node.flags.expanded ? "expanded" : "collapsed");
+    if (node.flags.offscreen)
+        parts.push("offscreen");
+    if (!node.flags.enabled || node.flags.disabled)
+        parts.push("disabled");
+    if (node.flags.readonly)
+        parts.push("readonly");
+    if (node.flags.required)
+        parts.push("required");
+    if (node.accept)
+        parts.push(`accept=${node.accept}`);
+    return parts.join(" ");
+};
+export const renderDecisionState = (input) => {
+    const { snapshot, memory, history, artifacts } = input;
+    const lines = [];
+    lines.push("TASK");
+    lines.push(`goal: ${input.goal}`);
+    if (input.subgoal)
+        lines.push(`current_subgoal: ${input.subgoal}`);
+    lines.push(`step: ${input.step}`);
+    lines.push("");
+    lines.push("PAGE");
+    lines.push(`url: ${snapshot.url}`);
+    lines.push(`title: ${truncate(collapse(snapshot.title), 120)}`);
+    lines.push(`viewport: ${snapshot.viewport.width}x${snapshot.viewport.height} scroll_y=${Math.round(snapshot.viewport.scrollY)} document_height=${Math.round(snapshot.viewport.documentHeight)}`);
+    const tabs = snapshot.tabs
+        .map((t) => `${t.id}${t.active ? "*" : ""} ${JSON.stringify(truncate(collapse(t.title || t.url), 60))} (${t.ownership})`)
+        .join(" | ");
+    lines.push(`tabs: ${tabs.length > 0 ? tabs : "(one tab)"}`);
+    if (snapshot.blockingUi) {
+        const ui = snapshot.blockingUi;
+        lines.push(`blocking_ui: ${ui.kind}${ui.text ? ` ${JSON.stringify(truncate(collapse(ui.text), 140))}` : ""}`);
+    }
+    if (snapshot.visualOnly)
+        lines.push("note: the page is a visual surface with no semantic controls");
+    const offered = new Set();
+    for (const list of Object.values(input.actionSpace.heads)) {
+        for (const candidate of list ?? [])
+            if (candidate.nodeIndex !== undefined)
+                offered.add(candidate.nodeIndex);
+    }
+    lines.push("");
+    lines.push("ELEMENTS");
+    const visibleNodes = snapshot.nodes.filter((n) => n.flags.visible);
+    const shown = visibleNodes.length > 0 ? visibleNodes : snapshot.nodes;
+    for (const node of shown.slice(0, 80)) {
+        const mark = offered.has(node.index) ? " " : "~";
+        lines.push(`${mark}${renderElement(node)}`);
+    }
+    if (shown.length > 80)
+        lines.push(`… ${shown.length - 80} more elements`);
+    if (shown.length === 0)
+        lines.push("(no elements were detected)");
+    if (snapshot.textSummary.trim().length > 0) {
+        lines.push("");
+        lines.push("VISIBLE_TEXT");
+        const text = collapse(snapshot.textSummary);
+        lines.push(truncate(text, 1200));
+    }
+    if (artifacts.length > 0) {
+        lines.push("");
+        lines.push("FILES");
+        for (const a of artifacts) {
+            lines.push(`- ${a.id} ${a.name} (${a.documentType ?? a.mimeType}, ${a.verified ? "verified" : "unverified"})`);
+        }
+    }
+    if (history.length > 0) {
+        lines.push("");
+        lines.push("RECENT_STEPS");
+        for (const step of history.slice(-8)) {
+            lines.push(`${step.step}. ${step.action} -> ${step.outcome}${step.detail ? ` (${truncate(step.detail, 90)})` : ""}`);
+        }
+    }
+    const facts = memory.facts.slice(-8);
+    const failures = memory.failedAttempts.slice(-4);
+    if (facts.length > 0 || failures.length > 0) {
+        lines.push("");
+        lines.push("MEMORY");
+        for (const f of facts)
+            lines.push(`- ${truncate(f.text, 120)}`);
+        for (const f of failures)
+            lines.push(`- avoid repeating: ${truncate(f.text, 120)} (step ${f.step})`);
+    }
+    if (input.failure) {
+        lines.push("");
+        lines.push("PREVIOUS_ATTEMPT");
+        lines.push(`failed: ${truncate(input.failure, 200)}`);
+    }
+    return { text: lines.join("\n") };
+};
+//# sourceMappingURL=state.js.map

package/dist/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"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"}

package/dist/testing/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Offline decision providers for tests, evals and demos.
+ *
+ * Neither of these is a decision model. `ScriptedDecisionProvider` replays a
+ * fixed sequence through the full runtime (validation, policy, execution,
+ * verification); `KeywordDecisionProvider` is a deterministic keyword baseline
+ * used for offline demos and as the PRD §56 C baseline. The product fast path
+ * is the Jev provider.
+ */
+import { actionSignature, type DecisionInput, type DecisionOutput, type DecisionProvider, type OperationId } from "@mlola/browser-protocol";
+export interface ScriptStep {
+    operation: OperationId;
+    /** Exact target key inside the operation's head. */
+    target?: string;
+    /**
+     * Resolve the target by matching a candidate label (string substring or
+     * RegExp). Robust against index shifts across re-renders.
+     */
+    targetLabel?: string | RegExp;
+    note?: string;
+}
+export type ScriptEntry = ScriptStep | ((input: DecisionInput) => ScriptStep | Promise<ScriptStep>);
+export declare class ScriptedDecisionProvider implements DecisionProvider {
+    #private;
+    readonly name: string;
+    readonly seen: DecisionInput[];
+    constructor(steps: ScriptEntry[], name?: string);
+    get remaining(): number;
+    decide(input: DecisionInput): Promise<DecisionOutput>;
+}
+export interface KeywordProviderOptions {
+    /** Provider name recorded in traces. */
+    name?: string;
+    /** Minimum score before a click/type target is chosen. */
+    minScore?: number;
+}
+export declare class KeywordDecisionProvider implements DecisionProvider {
+    #private;
+    readonly name: string;
+    constructor(options?: KeywordProviderOptions);
+    decide(input: DecisionInput): Promise<DecisionOutput>;
+}
+/** Signature helper re-exported for tests that assert loop behaviour. */
+export { actionSignature };
+//# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAEL,eAAe,EAGf,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAEjB,MAAM,yBAAyB,CAAC;AAIjC,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,WAAW,CAAC;IACvB,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,CAAC,CAAC,KAAK,EAAE,aAAa,KAAK,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC;AAEpG,qBAAa,wBAAyB,YAAW,gBAAgB;;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,aAAa,EAAE,CAAM;gBAIxB,KAAK,EAAE,WAAW,EAAE,EAAE,IAAI,SAAa;IAKnD,IAAI,SAAS,IAAI,MAAM,CAEtB;IAEK,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC;CAsD5D;AAmBD,MAAM,WAAW,sBAAsB;IACrC,wCAAwC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AASD,qBAAa,uBAAwB,YAAW,gBAAgB;;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAIV,OAAO,GAAE,sBAA2B;IAK1C,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC;CAiK5D;AAID,yEAAyE;AACzE,OAAO,EAAE,eAAe,EAAE,CAAC"}