@mlola/browser-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MLola
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,10 @@
+# @mlola/browser-core
+
+The orchestration engine of the [MLola Browser Runtime](https://mlola.com/browser-runtime):
+task loop, dynamic action space, safe executor, verification and recovery.
+
+```ts
+import { TaskOrchestrator, buildActionSpace, verifyStep } from "@mlola/browser-core";
+```
+
+Most users want the SDK instead: [`@mlola/browser-runtime`](https://www.npmjs.com/package/@mlola/browser-runtime).

package/dist/action-space.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Candidate builder: observation → dynamic typed action space (PRD §14).
+ *
+ * Only compatible targets are exposed per operation, so the decision model
+ * picks from small, correct sets instead of a combinatorial action list.
+ * Blocking UI gets priority (PRD §37).
+ */
+import type { ActionSpace, BrowserSnapshot } from "@mlola/browser-protocol";
+export interface ActionSpaceLimits {
+    click: number;
+    type: number;
+    select: number;
+    option: number;
+    openTab: number;
+    download: number;
+    upload: number;
+    tab: number;
+}
+export declare const DEFAULT_SPACE_LIMITS: ActionSpaceLimits;
+export interface ActionSpaceInput {
+    snapshot: BrowserSnapshot;
+    /** Uploads denied by policy means the head is not offered at all. */
+    uploadAllowed: boolean;
+    /** Goal text, used only to rank candidates on large pages (deterministic). */
+    goal?: string;
+    limits?: Partial<ActionSpaceLimits>;
+}
+export declare const buildActionSpace: (input: ActionSpaceInput) => ActionSpace;
+/** Deterministic count summary for traces. */
+export declare const spaceSummary: (space: ActionSpace) => {
+    operations: string[];
+    headSizes: Record<string, number>;
+    quarantined: number;
+};
+export declare const isBlockedSet: (space: ActionSpace) => boolean;
+//# sourceMappingURL=action-space.d.ts.map

package/dist/action-space.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-space.d.ts","sourceRoot":"","sources":["../src/action-space.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,eAAe,EAKhB,MAAM,yBAAyB,CAAC;AAGjC,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;CACb;AAED,eAAO,MAAM,oBAAoB,EAAE,iBASlC,CAAC;AAEF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,eAAe,CAAC;IAC1B,qEAAqE;IACrE,aAAa,EAAE,OAAO,CAAC;IACvB,8EAA8E;IAC9E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACrC;AA4DD,eAAO,MAAM,gBAAgB,GAAI,OAAO,gBAAgB,KAAG,WAsK1D,CAAC;AAwCF,8CAA8C;AAC9C,eAAO,MAAM,YAAY,GAAI,OAAO,WAAW,KAAG;IAAE,UAAU,EAAE,MAAM,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAM/H,CAAC;AAEF,eAAO,MAAM,YAAY,GAAI,OAAO,WAAW,KAAG,OAAsD,CAAC"}

package/dist/action-space.js

@@ -0,0 +1,264 @@
+/**
+ * Candidate builder: observation → dynamic typed action space (PRD §14).
+ *
+ * Only compatible targets are exposed per operation, so the decision model
+ * picks from small, correct sets instead of a combinatorial action list.
+ * Blocking UI gets priority (PRD §37).
+ */
+import { headForOperation } from "@mlola/browser-protocol";
+export const DEFAULT_SPACE_LIMITS = {
+    click: 80,
+    type: 30,
+    select: 12,
+    option: 40,
+    openTab: 20,
+    download: 60,
+    upload: 10,
+    tab: 15,
+};
+const shortLabel = (node) => {
+    const label = node.label.replace(/\s+/g, " ").trim();
+    const base = label.length > 90 ? `${label.slice(0, 89)}…` : label;
+    return base.length > 0 ? base : `(${node.role} without label)`;
+};
+const describeCandidate = (node, extra) => {
+    const parts = [`${node.role}`, JSON.stringify(shortLabel(node))];
+    if (node.value && node.value.length > 0 && node.role !== "textbox" && node.role !== "searchbox") {
+        parts.push(`value=${JSON.stringify(node.value.slice(0, 40))}`);
+    }
+    if (node.placeholder)
+        parts.push(`placeholder=${JSON.stringify(node.placeholder.slice(0, 40))}`);
+    if (node.flags.offscreen)
+        parts.push("(offscreen)");
+    if (extra)
+        parts.push(extra);
+    return parts.join(" ");
+};
+/** Candidate ordering: visible first, then goal relevance, then document order. */
+const orderNodes = (nodes, keywords = []) => [...nodes].sort((a, b) => {
+    if (a.flags.visible !== b.flags.visible)
+        return a.flags.visible ? -1 : 1;
+    const ra = relevance(a.label, keywords);
+    const rb = relevance(b.label, keywords);
+    if (ra !== rb)
+        return rb - ra;
+    return a.index - b.index;
+});
+const STOPWORDS = new Set([
+    "the", "and", "for", "with", "that", "this", "from", "into", "your", "you", "a", "an", "to", "of", "in", "on",
+    "my", "me", "it", "is", "are", "be", "then", "after", "before", "please", "can", "could", "would", "should",
+    "get", "go", "do", "make", "sure", "them", "its", "our", "their",
+]);
+const goalKeywords = (goal) => {
+    if (!goal)
+        return [];
+    return [
+        ...new Set(goal
+            .toLowerCase()
+            .replace(/[^\p{L}\p{N}\s-]/gu, " ")
+            .split(/\s+/)
+            .filter((word) => word.length >= 4 && !STOPWORDS.has(word))),
+    ];
+};
+const relevance = (label, keywords) => {
+    if (keywords.length === 0)
+        return 0;
+    const lower = label.toLowerCase();
+    let score = 0;
+    for (const keyword of keywords) {
+        if (lower.includes(keyword))
+            score += 1;
+    }
+    return score;
+};
+const hasOp = (node, op) => node.operations.includes(op);
+export const buildActionSpace = (input) => {
+    const { snapshot } = input;
+    const limits = { ...DEFAULT_SPACE_LIMITS, ...(input.limits ?? {}) };
+    const nodes = snapshot.nodes;
+    const keywords = goalKeywords(input.goal);
+    const heads = {};
+    const quarantined = [];
+    const operations = [];
+    const clickNodes = orderNodes(nodes.filter((n) => hasOp(n, "CLICK") && !n.flags.disabled && !n.flags.inert), keywords);
+    const typeNodes = orderNodes(nodes.filter((n) => hasOp(n, "TYPE_TEXT") && !n.flags.disabled && !n.flags.readonly), keywords);
+    const selectNodes = orderNodes(nodes.filter((n) => hasOp(n, "SELECT") && !n.flags.disabled), keywords);
+    const downloadNodes = orderNodes(nodes.filter((n) => hasOp(n, "DOWNLOAD") && !n.flags.disabled), keywords);
+    const uploadNodes = orderNodes(nodes.filter((n) => hasOp(n, "UPLOAD") && !n.flags.disabled), keywords);
+    const openTabNodes = orderNodes(nodes.filter((n) => n.role === "link" && n.href !== undefined && (n.kind === "_blank" || n.kind === "new-tab")), keywords);
+    const blocking = snapshot.blockingUi;
+    const isNativeDialog = blocking !== undefined &&
+        blocking.nodeIndexes.length === 0 &&
+        ["alert", "confirm", "prompt", "beforeunload", "unknown"].includes(blocking.kind);
+    const blockingNodeOrder = blocking?.nodeIndexes ?? [];
+    const blockedSet = new Set(blockingNodeOrder);
+    // ── Blocking UI priority (PRD §37): while a modal or dialog is open, the
+    // action space is restricted to resolving it.
+    if (blocking && blockingNodeOrder.length > 0) {
+        const modalNodes = blockingNodeOrder
+            .map((i) => nodes.find((n) => n.index === i))
+            .filter((n) => n !== undefined);
+        heads.click_target = modalNodes.map((n) => candidateForNode(n));
+        if (heads.click_target.length > 0)
+            operations.push("CLICK");
+        operations.push("WAIT", "BLOCKED", "ASK_USER");
+        return { operations, heads, headForOperation: buildHeadMap(operations), quarantined };
+    }
+    if (isNativeDialog) {
+        operations.push("DISMISS_DIALOG");
+        if (blocking.kind !== "prompt")
+            operations.push("ACCEPT_DIALOG");
+        operations.push("WAIT", "BLOCKED", "ASK_USER");
+        return { operations, heads, headForOperation: buildHeadMap(operations), quarantined };
+    }
+    // ── Control-level quarantine (PRD §22.4): a control sitting next to
+    // agent-directed instruction text is not offered at all.
+    const quarantinedNodes = new Set();
+    const quarantineNode = (node, reason) => {
+        if (quarantinedNodes.has(node.nodeId))
+            return;
+        quarantinedNodes.add(node.nodeId);
+        quarantined.push({
+            key: String(node.index),
+            label: node.label,
+            nodeIndex: node.index,
+            nodeId: node.nodeId,
+            provenance: "untrusted_page_content",
+            quarantined: true,
+            quarantineReason: reason,
+        });
+    };
+    for (const node of nodes) {
+        if (node.flags.suspicious) {
+            quarantineNode(node, "control is adjacent to agent-directed instruction text");
+        }
+    }
+    const usable = (node) => !quarantinedNodes.has(node.nodeId);
+    // ── Normal space ──────────────────────────────────────────────────────────
+    const clicks = dedupe(clickNodes.filter(usable)).slice(0, limits.click);
+    if (clicks.length > 0) {
+        heads.click_target = clicks.map((n) => candidateForNode(n));
+        operations.push("CLICK");
+    }
+    const types = dedupe(typeNodes.filter(usable)).slice(0, limits.type);
+    if (types.length > 0) {
+        heads.type_text_target = types.map((n) => candidateForNode(n));
+        operations.push("TYPE_TEXT");
+    }
+    const selects = dedupe(selectNodes.filter(usable)).slice(0, limits.select);
+    const selectCandidates = [];
+    for (const node of selects) {
+        const options = (node.options ?? []).filter((o) => !o.disabled).slice(0, limits.option);
+        const selected = node.options?.find((o) => o.selected);
+        for (const option of options) {
+            selectCandidates.push({
+                key: `${node.index}:${option.index}`,
+                label: `${describeCandidate(node)} → option ${JSON.stringify(option.label)}${option.selected ? " (currently selected)" : ""}`,
+                nodeIndex: node.index,
+                nodeId: node.nodeId,
+                optionIndex: option.index,
+                optionValue: option.value,
+                provenance: node.provenance,
+            });
+        }
+    }
+    if (selectCandidates.length > 0) {
+        heads.select_target = selectCandidates;
+        operations.push("SELECT");
+    }
+    const downloads = dedupe(downloadNodes.filter(usable)).slice(0, limits.download);
+    if (downloads.length > 0) {
+        heads.download_target = downloads.map((n) => candidateForNode(n));
+        operations.push("DOWNLOAD");
+    }
+    const uploads = input.uploadAllowed ? dedupe(uploadNodes.filter(usable)).slice(0, limits.upload) : [];
+    if (uploads.length > 0) {
+        heads.upload_target = uploads.map((n) => {
+            const accept = n.accept ? ` accept=${n.accept}` : "";
+            return candidateForNode(n, `${accept} (upload artifact)`);
+        });
+        operations.push("UPLOAD");
+    }
+    const openTabs = dedupe(openTabNodes.filter(usable)).slice(0, limits.openTab);
+    if (openTabs.length > 0) {
+        heads.open_tab_target = openTabs.map((n, i) => ({
+            key: `L${i + 1}`,
+            label: `${describeCandidate(n)} → ${truncateUrl(n.href ?? "")}`,
+            nodeIndex: n.index,
+            nodeId: n.nodeId,
+            url: n.href,
+            provenance: n.provenance,
+        }));
+        operations.push("OPEN_TAB");
+    }
+    const otherTabs = snapshot.tabs.filter((t) => !t.active).slice(0, limits.tab);
+    if (otherTabs.length > 0) {
+        heads.switch_tab_target = otherTabs.map((t) => ({
+            key: t.id,
+            label: `tab ${t.id} ${JSON.stringify(t.title || t.url)} (${t.ownership})${t.url ? ` url=${truncateUrl(t.url)}` : ""}`,
+            tabId: t.id,
+            provenance: "browser_runtime",
+        }));
+        operations.push("SWITCH_TAB");
+    }
+    const viewport = snapshot.viewport;
+    const canScrollDown = viewport.scrollY + viewport.height < viewport.documentHeight - 8;
+    const canScrollUp = viewport.scrollY > 8;
+    if (canScrollDown)
+        operations.push("SCROLL_DOWN");
+    if (canScrollUp)
+        operations.push("SCROLL_UP");
+    if (snapshot.history?.canGoBack)
+        operations.push("BACK");
+    if (snapshot.history?.canGoForward)
+        operations.push("FORWARD");
+    operations.push("WAIT", "DONE", "BLOCKED", "ASK_USER");
+    return { operations, heads, headForOperation: buildHeadMap(operations), quarantined };
+};
+const candidateForNode = (node, extra) => ({
+    key: String(node.index),
+    label: `${node.index}: ${describeCandidate(node, extra)}`,
+    nodeIndex: node.index,
+    nodeId: node.nodeId,
+    provenance: node.provenance,
+});
+const dedupe = (nodes) => {
+    const seen = new Set();
+    const out = [];
+    for (const n of nodes) {
+        if (seen.has(n.nodeId))
+            continue;
+        seen.add(n.nodeId);
+        out.push(n);
+    }
+    return out;
+};
+const truncateUrl = (url) => {
+    try {
+        const parsed = new URL(url);
+        const path = `${parsed.pathname}${parsed.search}`;
+        return `${parsed.host}${path.length > 60 ? `${path.slice(0, 59)}…` : path}`;
+    }
+    catch {
+        return url.slice(0, 80);
+    }
+};
+const buildHeadMap = (operations) => {
+    const map = {};
+    for (const op of operations) {
+        const head = headForOperation(op);
+        if (head)
+            map[op] = head;
+    }
+    return map;
+};
+/** Deterministic count summary for traces. */
+export const spaceSummary = (space) => {
+    const headSizes = {};
+    for (const [head, candidates] of Object.entries(space.heads)) {
+        headSizes[head] = candidates?.length ?? 0;
+    }
+    return { operations: [...space.operations], headSizes, quarantined: space.quarantined.length };
+};
+export const isBlockedSet = (space) => space.operations.includes("DONE") === false;
+//# sourceMappingURL=action-space.js.map

package/dist/action-space.js.map

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

package/dist/budget.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Budget manager (PRD §45).
+ *
+ * Every task has explicit budgets. The manager can continue, degrade, ask the
+ * user, or fail cleanly — and never silently overruns.
+ */
+import type { BudgetSnapshot, BudgetVerdict, Budgets, CostRates, ProviderRole, Usage } from "@mlola/browser-protocol";
+export interface BudgetManagerOptions {
+    budgets?: Partial<Budgets>;
+    costRates?: Partial<Record<ProviderRole, CostRates>>;
+    now?: () => number;
+}
+export declare class BudgetManager {
+    #private;
+    readonly budgets: Budgets;
+    constructor(opts?: BudgetManagerOptions);
+    get snapshot(): BudgetSnapshot;
+    stepCompleted(): void;
+    charge(role: ProviderRole, usage?: Usage): number;
+    recoveryAttempt(): void;
+    humanHelp(): void;
+    /** Warnings at 80% of a budget; used for BUDGET_WARNING events. */
+    warnings(): {
+        reason: string;
+        level: "warn" | "critical";
+    }[];
+    /** The pre-step gate. */
+    check(): BudgetVerdict;
+    /** Whether fallback providers may still be used (degrade tier). */
+    fallbackAllowed(): boolean;
+}
+//# sourceMappingURL=budget.d.ts.map

package/dist/budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../src/budget.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAEtH,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3B,SAAS,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC,CAAC;IACrD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,qBAAa,aAAa;;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;gBAWd,IAAI,GAAE,oBAAyB;IAO3C,IAAI,QAAQ,IAAI,cAAc,CAS7B;IAED,aAAa,IAAI,IAAI;IAIrB,MAAM,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM;IAOjD,eAAe,IAAI,IAAI;IAIvB,SAAS,IAAI,IAAI;IAIjB,mEAAmE;IACnE,QAAQ,IAAI;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAAA;KAAE,EAAE;IA0B5D,yBAAyB;IACzB,KAAK,IAAI,aAAa;IAsCtB,mEAAmE;IACnE,eAAe,IAAI,OAAO;CAO3B"}

package/dist/budget.js

@@ -0,0 +1,127 @@
+/**
+ * Budget manager (PRD §45).
+ *
+ * Every task has explicit budgets. The manager can continue, degrade, ask the
+ * user, or fail cleanly — and never silently overruns.
+ */
+import { DEFAULT_BUDGETS, estimateCost } from "@mlola/browser-protocol";
+export class BudgetManager {
+    budgets;
+    #steps = 0;
+    #calls = { decision: 0, planner: 0, text: 0, vision: 0 };
+    #costUsd = 0;
+    #recoveryAttempts = 0;
+    #humanHelpRequests = 0;
+    #startedAt;
+    #now;
+    #costRates;
+    #warned = new Set();
+    constructor(opts = {}) {
+        this.budgets = { ...DEFAULT_BUDGETS, ...(opts.budgets ?? {}) };
+        this.#now = opts.now ?? (() => Date.now());
+        this.#startedAt = this.#now();
+        this.#costRates = opts.costRates ?? {};
+    }
+    get snapshot() {
+        return {
+            steps: this.#steps,
+            calls: { ...this.#calls },
+            costUsd: this.#costUsd,
+            durationMs: this.#now() - this.#startedAt,
+            recoveryAttempts: this.#recoveryAttempts,
+            humanHelpRequests: this.#humanHelpRequests,
+        };
+    }
+    stepCompleted() {
+        this.#steps += 1;
+    }
+    charge(role, usage) {
+        this.#calls[role] += usage?.calls ?? 1;
+        const cost = estimateCost(usage ?? { provider: role }, this.#costRates[role]);
+        this.#costUsd += cost;
+        return cost;
+    }
+    recoveryAttempt() {
+        this.#recoveryAttempts += 1;
+    }
+    humanHelp() {
+        this.#humanHelpRequests += 1;
+    }
+    /** Warnings at 80% of a budget; used for BUDGET_WARNING events. */
+    warnings() {
+        const out = [];
+        const s = this.snapshot;
+        const check = (name, used, max) => {
+            if (max <= 0)
+                return;
+            const ratio = used / max;
+            const key = `${name}:${ratio >= 1 ? "critical" : ratio >= 0.8 ? "warn" : ""}`;
+            if (ratio >= 0.8 && !this.#warned.has(key)) {
+                this.#warned.add(key);
+                out.push({
+                    reason: `${name} at ${used}/${max}`,
+                    level: ratio >= 1 ? "critical" : "warn",
+                });
+            }
+        };
+        check("steps", s.steps, this.budgets.maxSteps);
+        check("decision calls", s.calls.decision, this.budgets.maxDecisionCalls);
+        check("planner calls", s.calls.planner, this.budgets.maxPlannerCalls);
+        check("text calls", s.calls.text, this.budgets.maxTextCalls);
+        check("vision calls", s.calls.vision, this.budgets.maxVisionCalls);
+        check("duration ms", s.durationMs, this.budgets.maxDurationMs);
+        check("recovery attempts", s.recoveryAttempts, this.budgets.maxRecoveryAttemptsTotal);
+        check("human helps", s.humanHelpRequests, this.budgets.maxHumanHelpRequests);
+        return out;
+    }
+    /** The pre-step gate. */
+    check() {
+        const s = this.snapshot;
+        if (s.steps >= this.budgets.maxSteps) {
+            return { kind: "fail", reason: `step budget exhausted (${this.budgets.maxSteps})`, code: "BUDGET_EXHAUSTED" };
+        }
+        if (s.durationMs >= this.budgets.maxDurationMs) {
+            return {
+                kind: "fail",
+                reason: `duration budget exhausted (${Math.round(this.budgets.maxDurationMs / 1000)}s)`,
+                code: "BUDGET_EXHAUSTED",
+            };
+        }
+        if (s.calls.decision >= this.budgets.maxDecisionCalls) {
+            return {
+                kind: "fail",
+                reason: `decision budget exhausted (${this.budgets.maxDecisionCalls})`,
+                code: "BUDGET_EXHAUSTED",
+            };
+        }
+        if (s.calls.planner >= this.budgets.maxPlannerCalls && s.calls.planner > 0) {
+            // Degrade: continue on the fast path, no more planning.
+            return { kind: "degrade", reason: `planner budget exhausted (${this.budgets.maxPlannerCalls})` };
+        }
+        if (s.humanHelpRequests >= this.budgets.maxHumanHelpRequests) {
+            return {
+                kind: "fail",
+                reason: `human help budget exhausted (${this.budgets.maxHumanHelpRequests})`,
+                code: "BUDGET_EXHAUSTED",
+            };
+        }
+        if (this.#costUsd >= this.budgets.maxCostUsd) {
+            return s.calls.planner > 0
+                ? { kind: "degrade", reason: `cost budget reached ($${this.#costUsd.toFixed(4)})` }
+                : { kind: "ask_user", reason: `cost budget reached ($${this.#costUsd.toFixed(4)})` };
+        }
+        return { kind: "continue" };
+    }
+    /** Whether fallback providers may still be used (degrade tier). */
+    fallbackAllowed() {
+        const s = this.snapshot;
+        if (s.calls.planner >= this.budgets.maxPlannerCalls)
+            return false;
+        if (this.#costUsd >= this.budgets.maxCostUsd)
+            return false;
+        if (s.durationMs >= this.budgets.maxDurationMs * 0.95)
+            return false;
+        return true;
+    }
+}
+//# sourceMappingURL=budget.js.map

package/dist/budget.js.map

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

package/dist/decision-validation.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Decision response validation (PRD §16).
+ *
+ * Provider output is never trusted blindly: the selected choice must exist and
+ * be top-ranked, probabilities must be well-formed, and the target must belong
+ * to the selected operation's head. An invalid response is discarded and turns
+ * into a provider error for the recovery ladder.
+ */
+import type { ActionSpace, DecisionOutput, OperationId, TargetHeadId } from "@mlola/browser-protocol";
+export interface ValidationIssue {
+    code: string;
+    detail: string;
+}
+export interface ValidationResult {
+    ok: boolean;
+    issues: ValidationIssue[];
+    /** Warnings do not invalidate a decision; they are recorded in the trace. */
+    warnings: ValidationIssue[];
+    targetHead?: TargetHeadId;
+    targetKey?: string;
+}
+export interface ValidationOptions {
+    /** Minimum operation confidence; 0 disables the check. */
+    minOperationConfidence?: number;
+    minTargetConfidence?: number;
+    /** Require the selected choice to be the argmax of its probabilities. */
+    requireTopChoice?: boolean;
+}
+export declare const validateDecision: (decision: DecisionOutput, space: ActionSpace, opts?: ValidationOptions) => ValidationResult;
+export declare const terminalOperation: (op: OperationId) => boolean;
+//# sourceMappingURL=decision-validation.d.ts.map

package/dist/decision-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-validation.d.ts","sourceRoot":"","sources":["../src/decision-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAGtG,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,6EAA6E;IAC7E,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,UAAU,CAAC,EAAE,YAAY,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,0DAA0D;IAC1D,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAID,eAAO,MAAM,gBAAgB,GAC3B,UAAU,cAAc,EACxB,OAAO,WAAW,EAClB,OAAM,iBAAsB,KAC3B,gBAsEF,CAAC;AAiEF,eAAO,MAAM,iBAAiB,GAAI,IAAI,WAAW,KAAG,OACI,CAAC"}