browxai 0.7.0

package/dist/util/failure.js

@@ -0,0 +1,50 @@
+// Classify a failure as app-origin vs browxai-origin.
+//
+// A browxai-side context teardown/detach (another agent closed the session,
+// an incognito context was discarded, an anti-wedge deadline fired) surfaces
+// as a Playwright/CDP error that *looks* identical to an application
+// navigation or renderer crash. Agents then file expensive false "CRITICAL:
+// page crashed" defects against the app. This labels the failure so the agent
+// can tell "the app broke" from "the tool tore the context down".
+const BROWXAI_PATTERNS = /(target (page|context|browser).*(closed|crashed)|context (was|has been) (closed|destroyed)|execution context was destroyed|browser has been closed|session closed|page has been closed|protocol error.*(target closed|session closed)|anti-wedge|deadline exceeded|deadlineerror|invariant violated|invarianterror)/i;
+const APP_PATTERNS = /(page crashed|renderer (crash|process gone)|net::err_|err_(connection|name_not_resolved|aborted|timed_out)|navigation (failed|to .* was interrupted)|frame was detached due to navigation)/i;
+/** Pure; exported for unit tests. */
+export function classifyFailure(message) {
+    const m = message || "";
+    // browxai teardown is checked first: "target closed" mid-navigation is far
+    // more often a session reap than a genuine app crash, and a false
+    // app-crash defect is the expensive mistake we're preventing.
+    if (BROWXAI_PATTERNS.test(m)) {
+        // Three browxai-origin shapes match here, each with a different recovery: a
+        // context teardown is fixed by reopening; an anti-wedge deadline must NOT be
+        // blindly retried (that is the wedged-session loop); an invariant violation
+        // (L8) is a browxai-internal contract failure — a defect to report, not a
+        // usage error, and the session itself is usually unaffected.
+        const isDeadline = /anti-wedge|deadline exceeded|deadlineerror/i.test(m);
+        const isInvariant = /invariant violated|invarianterror/i.test(m);
+        let hint;
+        if (isInvariant) {
+            hint =
+                "browxai-internal invariant violated (L8) — browxai reached a state one of its own modules guarantees cannot happen and refused with a structured error instead of returning a wrong answer. NOT an application crash and NOT a usage error: this indicates a bug in browxai. The session is usually unaffected — retry once; if it recurs, capture the message and file it as a browxai defect.";
+        }
+        else if (isDeadline) {
+            hint =
+                "anti-wedge deadline fired — browxai returned instead of stalling on a wedged page op. NOT an application crash; do not file an app-crash defect. Retry the call ONCE; if timeouts keep recurring on this session it is wedged — discard it (`close_session`) and `open_session` a fresh one. A bigger `timeoutMs` will not recover a wedged session.";
+        }
+        else {
+            hint =
+                "browxai-side context teardown/detach (session closed by another agent, or an incognito context discarded) — NOT an application crash. Re-open the session and retry; do not file an app-crash defect.";
+        }
+        return { source: "browxai", hint };
+    }
+    if (APP_PATTERNS.test(m)) {
+        return {
+            source: "app",
+            hint: "application-origin failure (navigation/renderer). This one is a real app signal — safe to investigate as a defect.",
+        };
+    }
+    return {
+        source: "unknown",
+        hint: "origin indeterminate — confirm the session is still open (list_sessions) before treating this as an app defect.",
+    };
+}

package/dist/util/flake-check.d.ts

@@ -0,0 +1,109 @@
+import { type BatchCall, type BatchOptions, type BatchReport, type BatchEntry } from "./batch.js";
+import type { ActionDescriptor, PlanEvidence } from "../page/plan.js";
+export interface FlakeCheckOptions extends BatchOptions {
+    /** How many times to run the same call sequence. Bounded by the caller
+     *  schema (3..20) — the impl tolerates anything ≥1 so unit tests stay
+     *  lightweight, but the MCP surface enforces the documented range. */
+    n: number;
+    /** Short-circuit when `stopOnAllGreen` consecutive runs all-pass. Off by
+     *  default — set to a number to opt in. */
+    stopOnAllGreen?: number;
+}
+/** Per-step roll-up across all completed runs. */
+export interface StepStats {
+    /** Step index (0-based; matches the `calls[]` argument order). */
+    step: number;
+    /** Tool name (echoed for cross-reference; same as `calls[step].tool`). */
+    tool: string;
+    /** Echo of the call's label when supplied. */
+    label?: string;
+    /** Number of runs that reached this step. (When `runBatch` halts early on
+     *  a failure earlier in the sequence, later steps never run — their `runs`
+     *  count drops below `n`.) */
+    runs: number;
+    /** Number of those reaching-this-step runs where the step succeeded. */
+    ok: number;
+    /** `ok / runs` — null when the step was never reached. */
+    successRate: number | null;
+    /** Distinct error messages observed (deduped, capped at 8 entries for
+     *  result-size sanity — anything noisier is itself the finding). */
+    errors: string[];
+    /** Distinct resolution signatures observed (`<ref>::<selectorHint>` for
+     *  plan/find, or `target:<ref|selector|named>` for bound calls). One entry
+     *  means the step landed identically across every run that reached it. */
+    signatures: string[];
+}
+/** A `{step → cached resolver}` entry — the self-heal artifact. Shape mirrors
+ *  the `ActionDescriptor` returned by `plan()` so a downstream caller can hand
+ *  it to `execute()` directly (after re-snapshotting to refresh the ref). */
+export interface CachedResolver {
+    step: number;
+    tool: string;
+    label?: string;
+    /** The resolved ref the step landed on (from plan/find result). */
+    ref?: string;
+    /** The `selectorHint` captured at plan/find time — what a downstream
+     *  Playwright export would write. */
+    selectorHint?: string;
+    /** Carried only when the source step was a `plan` call — re-usable by a
+     *  follow-up `execute` against a fresh snapshot. Note: `expiresAt` is
+     *  echoed from the source run; the consumer is expected to re-plan if it's
+     *  in the past. */
+    descriptor?: Pick<ActionDescriptor, "ref" | "verb" | "args"> & {
+        /** Carried for evidence-trail purposes only — caller should not trust
+         *  the `score` / `actionable` fields if it intends to re-execute later. */
+        evidence?: Pick<PlanEvidence, "selectorHint" | "selectorTier" | "stability" | "role" | "name" | "testId">;
+    };
+    /** How many of the reaching-this-step runs agreed on this resolver. The
+     *  caller's read of `runs == n` + `agreedRuns == runs` is the "100% green"
+     *  case where this cache is safe to replay. */
+    agreedRuns: number;
+}
+export interface FlakeCheckReport {
+    /** Number of inner-batch runs actually performed (may be < n when
+     *  `stopOnAllGreen` short-circuited). */
+    runsCompleted: number;
+    /** True when every completed run passed every step. */
+    allGreen: boolean;
+    /** When `stopOnAllGreen` short-circuited, the count of consecutive all-green
+     *  runs that triggered the break. Absent otherwise. */
+    shortCircuitedAfter?: number;
+    /** Per-step roll-up. Indexed by call-array position. */
+    steps: StepStats[];
+    /** Earliest step (0-based) where `ok` differed across the completed runs,
+     *  or null when every run agreed on every step's pass/fail (whether that
+     *  was all-green or all-red — agreement IS the finding). */
+    firstDivergence: {
+        step: number;
+        tool: string;
+        label?: string;
+    } | null;
+    /** Cached resolvers for steps where every reaching-this-step run agreed on
+     *  the resolution signature AND succeeded. Replay-safe in that strict
+     *  sense — not a free pass past a `descriptor expired`. */
+    cachedResolvers: CachedResolver[];
+    /** Echo of the per-run BatchReports so the caller can drill in. Order is
+     *  chronological. */
+    runs: BatchReport[];
+}
+/**
+ * Run `calls` repeatedly through `runBatch` and roll up variance + cached
+ * resolvers. Always runs the inner batch with `stopOnError:false` so the
+ * variance picture survives a mid-sequence failure (the whole point — knowing
+ * step 4 sometimes fails AND that step 5 then also fails differently).
+ */
+export declare function runFlakeCheck(calls: BatchCall[], opts: FlakeCheckOptions): Promise<FlakeCheckReport>;
+/** Pure; exported for unit tests. Walks every run's results and produces a
+ *  per-step StepStats record. */
+export declare function rollUpSteps(calls: BatchCall[], runs: BatchReport[]): StepStats[];
+/** Pure; exported for tests. Smallest step index where `ok` differed across
+ *  the runs that reached that step. */
+export declare function findFirstDivergence(calls: BatchCall[], runs: BatchReport[]): FlakeCheckReport["firstDivergence"];
+/** Pure; exported for tests. Builds the self-heal cache for steps where every
+ *  reaching-this-step run agreed on the resolution signature AND succeeded.
+ *  Steps with no extractable resolver (no ref/selectorHint payload + no bound
+ *  target) yield no entry. */
+export declare function extractCachedResolvers(calls: BatchCall[], runs: BatchReport[], steps: StepStats[]): CachedResolver[];
+/** Pure; exported for tests. Computes a per-step resolution signature from
+ *  the inner call + its result entry. */
+export declare function signatureFor(call: BatchCall, entry: BatchEntry): string;

package/dist/util/flake-check.js

@@ -0,0 +1,342 @@
+// Flake-check — run the same `batch` payload N times and report what shifted
+// between runs. Composes existing primitives (no parallel dispatcher, no
+// parallel action surface): `runBatch` is the inner runner; the cached-selector
+// artifact uses the `ActionDescriptor` shape already shipped with `plan`/
+// `execute`. Diagnoses AND fixes — green runs produce a `{step → resolved
+// ref/selectorHint}` map a follow-up run can replay against (the Stagehand
+// self-heal trick).
+//
+// Determining "the step landed identically" — judgment captured here so the
+// next reader doesn't have to reconstruct it:
+//
+//   1. Strict resolution-signature match. Where the inner tool's result carries
+//      a resolution payload — `plan` returns a descriptor with `ref` +
+//      `evidence.selectorHint`; `find` returns a candidate list with `ref` +
+//      `selectorHint` — we use `<ref>::<selectorHint>` as the signature.
+//      Identical only when every green run produced the same pair.
+//
+//   2. Bound-target steps (click/fill/etc. called with a fixed `ref`/`selector`/
+//      `named`) have no candidate ranker to disagree about — their signature
+//      is just the supplied target string. They contribute a cached entry
+//      iff every green run reported ok=true. (The artifact is the same input
+//      the original call used — the value is the per-step pass/fail summary,
+//      not a new resolver.)
+//
+//   3. Steps where the runs produced different signatures get NO cached entry.
+//      `variance.signatures[step]` lists what was seen so the agent can decide.
+//
+// This module is intentionally dep-free below `runBatch` — unit tests can
+// exercise the variance / cache logic without standing up the MCP server.
+import { runBatch, } from "./batch.js";
+const MAX_DISTINCT_ERRORS_PER_STEP = 8;
+const MAX_DISTINCT_SIGNATURES_PER_STEP = 8;
+/**
+ * Run `calls` repeatedly through `runBatch` and roll up variance + cached
+ * resolvers. Always runs the inner batch with `stopOnError:false` so the
+ * variance picture survives a mid-sequence failure (the whole point — knowing
+ * step 4 sometimes fails AND that step 5 then also fails differently).
+ */
+export async function runFlakeCheck(calls, opts) {
+    const n = Math.max(1, opts.n | 0);
+    const runs = [];
+    let consecutiveGreen = 0;
+    let shortCircuitedAfter;
+    for (let runIdx = 0; runIdx < n; runIdx++) {
+        const report = await runBatch(calls, {
+            allowed: opts.allowed,
+            handlers: opts.handlers,
+            // Variance-on-the-tail is the entire point — don't let a stopOnError
+            // setting from the caller hide the variance picture.
+            stopOnError: false,
+        });
+        runs.push(report);
+        const green = report.failedAt === null && report.results.every((r) => r.ok);
+        consecutiveGreen = green ? consecutiveGreen + 1 : 0;
+        if (opts.stopOnAllGreen !== undefined &&
+            opts.stopOnAllGreen > 0 &&
+            consecutiveGreen >= opts.stopOnAllGreen) {
+            shortCircuitedAfter = consecutiveGreen;
+            break;
+        }
+    }
+    const steps = rollUpSteps(calls, runs);
+    const firstDivergence = findFirstDivergence(calls, runs);
+    const cachedResolvers = extractCachedResolvers(calls, runs, steps);
+    const allGreen = runs.every((r) => r.failedAt === null && r.results.every((e) => e.ok));
+    const out = {
+        runsCompleted: runs.length,
+        allGreen,
+        steps,
+        firstDivergence,
+        cachedResolvers,
+        runs,
+    };
+    if (shortCircuitedAfter !== undefined)
+        out.shortCircuitedAfter = shortCircuitedAfter;
+    return out;
+}
+/** Pure; exported for unit tests. Walks every run's results and produces a
+ *  per-step StepStats record. */
+export function rollUpSteps(calls, runs) {
+    return calls.map((call, step) => {
+        const entries = [];
+        for (const r of runs) {
+            const e = r.results[step];
+            if (e)
+                entries.push(e);
+        }
+        const ok = entries.filter((e) => e.ok).length;
+        const runsAt = entries.length;
+        const errorSet = new Set();
+        for (const e of entries) {
+            if (e.ok)
+                continue;
+            // `runBatch` only sets `entry.error` on its own failure surfaces (expect
+            // mismatch / thrown handler / unknown tool). When the inner call returns
+            // `{ok:false, error:"…"}`, the message lives on `entry.result.error` —
+            // surface that too so the variance roll-up isn't blank when the inner
+            // tool failed cleanly.
+            const fromEntry = typeof e.error === "string" ? e.error : null;
+            const fromResult = e.result &&
+                typeof e.result === "object" &&
+                typeof e.result.error === "string"
+                ? e.result.error
+                : null;
+            const msg = fromEntry ?? fromResult;
+            if (msg) {
+                errorSet.add(msg);
+                if (errorSet.size >= MAX_DISTINCT_ERRORS_PER_STEP)
+                    break;
+            }
+        }
+        const sigSet = new Set();
+        for (const e of entries) {
+            const s = signatureFor(call, e);
+            sigSet.add(s);
+            if (sigSet.size >= MAX_DISTINCT_SIGNATURES_PER_STEP)
+                break;
+        }
+        const stats = {
+            step,
+            tool: call.tool,
+            runs: runsAt,
+            ok,
+            successRate: runsAt === 0 ? null : ok / runsAt,
+            errors: [...errorSet],
+            signatures: [...sigSet],
+        };
+        if (call.label !== undefined)
+            stats.label = call.label;
+        return stats;
+    });
+}
+/** Pure; exported for tests. Smallest step index where `ok` differed across
+ *  the runs that reached that step. */
+export function findFirstDivergence(calls, runs) {
+    for (let step = 0; step < calls.length; step++) {
+        let seenOk = false;
+        let seenFail = false;
+        for (const r of runs) {
+            const e = r.results[step];
+            if (!e)
+                continue;
+            if (e.ok)
+                seenOk = true;
+            else
+                seenFail = true;
+            if (seenOk && seenFail) {
+                const out = {
+                    step,
+                    tool: calls[step].tool,
+                };
+                if (calls[step].label !== undefined)
+                    out.label = calls[step].label;
+                return out;
+            }
+        }
+    }
+    return null;
+}
+/** Pure; exported for tests. Builds the self-heal cache for steps where every
+ *  reaching-this-step run agreed on the resolution signature AND succeeded.
+ *  Steps with no extractable resolver (no ref/selectorHint payload + no bound
+ *  target) yield no entry. */
+export function extractCachedResolvers(calls, runs, steps) {
+    const out = [];
+    for (let step = 0; step < calls.length; step++) {
+        const call = calls[step];
+        const stat = steps[step];
+        // Only cache when every reaching-this-step run agreed and all succeeded.
+        if (stat.runs === 0)
+            continue;
+        if (stat.ok !== stat.runs)
+            continue;
+        if (stat.signatures.length !== 1)
+            continue;
+        // Take the first reaching-this-step entry as the source (all agreed,
+        // so any one is canonical).
+        let source;
+        for (const r of runs) {
+            const e = r.results[step];
+            if (e) {
+                source = e;
+                break;
+            }
+        }
+        if (!source)
+            continue;
+        const resolver = buildResolver(step, call, source);
+        if (resolver) {
+            resolver.agreedRuns = stat.runs;
+            out.push(resolver);
+        }
+    }
+    return out;
+}
+/** Pure; exported for tests. Computes a per-step resolution signature from
+ *  the inner call + its result entry. */
+export function signatureFor(call, entry) {
+    // Plan: descriptor.ref + evidence.selectorHint.
+    const planSig = planSignature(entry.result);
+    if (planSig)
+        return `plan:${planSig}`;
+    // Find: top candidate ref + selectorHint.
+    const findSig = findSignature(entry.result);
+    if (findSig)
+        return `find:${findSig}`;
+    // Bound target: just the supplied target string (ref / selector / named).
+    // Coords intentionally not cached — by construction non-replayable across
+    // a re-render (see plan.ts's policy note).
+    const args = call.args ?? {};
+    if (typeof args.ref === "string")
+        return `ref:${args.ref}`;
+    if (typeof args.selector === "string")
+        return `selector:${args.selector}`;
+    if (typeof args.named === "string")
+        return `named:${args.named}`;
+    // No structured target — signature is the ok-ness plus a tool tag so
+    // step success-rate still rolls up cleanly.
+    return `${call.tool}:${entry.ok ? "ok" : "fail"}`;
+}
+function planSignature(result) {
+    if (!result || typeof result !== "object")
+        return null;
+    const r = result;
+    const d = r.descriptor;
+    if (!d || typeof d !== "object")
+        return null;
+    const ref = typeof d.ref === "string" ? d.ref : null;
+    if (!ref)
+        return null;
+    const ev = d.evidence;
+    const hint = ev &&
+        typeof ev === "object" &&
+        typeof ev.selectorHint === "string"
+        ? ev.selectorHint
+        : "";
+    return `${ref}::${hint}`;
+}
+function findSignature(result) {
+    if (!result || typeof result !== "object")
+        return null;
+    const r = result;
+    if (!Array.isArray(r.candidates) || r.candidates.length === 0)
+        return null;
+    const top = r.candidates[0];
+    const ref = typeof top.ref === "string" ? top.ref : null;
+    if (!ref)
+        return null;
+    const hint = typeof top.selectorHint === "string" ? top.selectorHint : "";
+    return `${ref}::${hint}`;
+}
+function buildResolver(step, call, source) {
+    const base = { step, tool: call.tool, agreedRuns: 0 };
+    if (call.label !== undefined)
+        base.label = call.label;
+    // plan() — richest cache (full descriptor projection).
+    const planDescriptor = extractPlanDescriptor(source.result);
+    if (planDescriptor) {
+        base.ref = planDescriptor.ref;
+        base.selectorHint = planDescriptor.evidence?.selectorHint;
+        base.descriptor = planDescriptor;
+        return base;
+    }
+    // find() — top candidate's ref + selectorHint.
+    const findTop = extractFindTop(source.result);
+    if (findTop) {
+        base.ref = findTop.ref;
+        base.selectorHint = findTop.selectorHint;
+        return base;
+    }
+    // Bound target — at minimum record what the caller used. Useful because
+    // the per-step success rate is the load-bearing finding here, not a new
+    // resolver.
+    const args = call.args ?? {};
+    if (typeof args.ref === "string") {
+        base.ref = args.ref;
+        return base;
+    }
+    if (typeof args.selector === "string") {
+        base.selectorHint = args.selector;
+        return base;
+    }
+    if (typeof args.named === "string") {
+        base.selectorHint = `named:${args.named}`;
+        return base;
+    }
+    // No target info to cache — skip the step entirely so the artifact stays
+    // signal-dense.
+    return null;
+}
+function extractPlanDescriptor(result) {
+    if (!result || typeof result !== "object")
+        return null;
+    const r = result;
+    const d = r.descriptor;
+    if (!d || typeof d !== "object")
+        return null;
+    const ref = d.ref;
+    const verb = d.verb;
+    const args = d.args;
+    if (typeof ref !== "string" || typeof verb !== "string")
+        return null;
+    const out = {
+        ref,
+        verb: verb,
+        args: args && typeof args === "object" ? args : {},
+    };
+    const ev = d.evidence;
+    if (ev && typeof ev === "object") {
+        const e = ev;
+        const projected = {
+            selectorHint: typeof e.selectorHint === "string" ? e.selectorHint : "",
+            selectorTier: (typeof e.selectorTier === "number"
+                ? e.selectorTier
+                : 5),
+            stability: (typeof e.stability === "string"
+                ? e.stability
+                : "low"),
+            role: typeof e.role === "string" ? e.role : "",
+        };
+        if (typeof e.name === "string")
+            projected.name = e.name;
+        if (typeof e.testId === "string")
+            projected.testId = e.testId;
+        out.evidence = projected;
+    }
+    return out;
+}
+function extractFindTop(result) {
+    if (!result || typeof result !== "object")
+        return null;
+    const r = result;
+    if (!Array.isArray(r.candidates) || r.candidates.length === 0)
+        return null;
+    const top = r.candidates[0];
+    if (typeof top.ref !== "string")
+        return null;
+    return {
+        ref: top.ref,
+        selectorHint: typeof top.selectorHint === "string" ? top.selectorHint : "",
+    };
+}

package/dist/util/invariant.d.ts

@@ -0,0 +1,25 @@
+/** A contained, structured invariant violation — the L8 analogue of
+ *  `DeadlineError`. Carries the violated-contract message verbatim; the
+ *  dispatcher renders it as a structured refusal (`ToolResponse{ok:false}`),
+ *  never a raw throw past the dispatch boundary. `name` is `"InvariantError"` so
+ *  the failure classifier and any catch-site can recognise a browxai-origin
+ *  internal fault (vs an application/page error). */
+export declare class InvariantError extends Error {
+    constructor(message: string);
+}
+/**
+ * Assert an internal invariant. On a falsy `cond`, throws `InvariantError` (a
+ * contained, structured refusal — never a bare `assert`/crash). The TypeScript
+ * `asserts cond` signature narrows the type after the call, so a passing
+ * invariant also tells the compiler the condition holds (the L6 boundary
+ * discipline, applied internally) — e.g. `invariant(x !== undefined, …)` lets
+ * the code below treat `x` as defined.
+ *
+ * Use ONLY for contracts the surrounding code already depends on, so the call is
+ * a no-op on every valid input. Never validate user/wire data here (that is the
+ * boundary's job, L6); never assert an optional or best-effort condition.
+ *
+ *   invariant(REGISTRY.size > 0, "engine registry is empty at dispatch");
+ *   invariant(cap > 0, `ring cap must be positive, got ${cap}`);
+ */
+export declare function invariant(cond: unknown, msg: string): asserts cond;

package/dist/util/invariant.js

@@ -0,0 +1,66 @@
+// invariant() — assert an internal contract (RFC 0004 L8).
+//
+// browxai already contains faults at three boundaries as STRUCTURED, recoverable
+// refusals rather than crashes: the anti-wedge deadline (`DeadlineError`,
+// deadline.ts:13-32), the secrets scope check (`materialize` returns
+// `{ok:false, error}`, secrets.ts), and the capability gate (a denied tool
+// returns a refusal). L8 generalizes that single proven pattern: every internal
+// invariant that, if violated, means browxai itself is in a corrupt state — a
+// registry with two entries for one key, a ring whose cap went non-positive, a
+// precedence chain that lost a layer — surfaces through the SAME structured-
+// refusal envelope, contained at the dispatch boundary, never propagated as an
+// uncontained throw that wedges the dispatch loop.
+//
+// `invariant(cond, msg)` is the fault-containment generalization: it throws an
+// `InvariantError` (a tagged, contained error, NOT a bare `assert`) whose message
+// is an explicit agent-facing playbook — same posture as `DeadlineError`. The
+// dispatcher maps `InvariantError` to a `ToolResponse{ok:false}` the agent can
+// act on, exactly as it maps `DeadlineError`. The `classifyFailure` patterns
+// (failure.ts) already route a browxai-origin fault to the right recovery, and
+// `invariant violated` joins that family.
+//
+// CRITICAL: an invariant asserts only what the surrounding code ALREADY
+// guarantees on valid inputs, so it is a NO-OP in production and on every test —
+// the assertion-density fitness function and the full unit + keystone suites run
+// with NO invariant firing. An invariant that fires on a legitimate edge case is
+// a bug in the invariant, not a feature; assert contracts the code depends on,
+// never user-supplied data (that is the boundary's job — L6, validate at the
+// edge), and never an optional/best-effort condition.
+/** A contained, structured invariant violation — the L8 analogue of
+ *  `DeadlineError`. Carries the violated-contract message verbatim; the
+ *  dispatcher renders it as a structured refusal (`ToolResponse{ok:false}`),
+ *  never a raw throw past the dispatch boundary. `name` is `"InvariantError"` so
+ *  the failure classifier and any catch-site can recognise a browxai-origin
+ *  internal fault (vs an application/page error). */
+export class InvariantError extends Error {
+    constructor(message) {
+        super(`invariant violated: ${message}. This is a browxai-internal contract failure ` +
+            `(NOT an application or page error) — browxai reached a state one of its own ` +
+            `modules guarantees cannot happen, so it refused instead of returning a wrong ` +
+            `answer or crashing the dispatch loop. This is a RECOVERABLE signal: the tool ` +
+            `returned a structured refusal. Treat it as a defect to report (it indicates a ` +
+            `bug in browxai, not in your usage); the session itself is usually unaffected ` +
+            `— retry the call, and if it recurs, capture the message and file it.`);
+        this.name = "InvariantError";
+    }
+}
+/**
+ * Assert an internal invariant. On a falsy `cond`, throws `InvariantError` (a
+ * contained, structured refusal — never a bare `assert`/crash). The TypeScript
+ * `asserts cond` signature narrows the type after the call, so a passing
+ * invariant also tells the compiler the condition holds (the L6 boundary
+ * discipline, applied internally) — e.g. `invariant(x !== undefined, …)` lets
+ * the code below treat `x` as defined.
+ *
+ * Use ONLY for contracts the surrounding code already depends on, so the call is
+ * a no-op on every valid input. Never validate user/wire data here (that is the
+ * boundary's job, L6); never assert an optional or best-effort condition.
+ *
+ *   invariant(REGISTRY.size > 0, "engine registry is empty at dispatch");
+ *   invariant(cap > 0, `ring cap must be positive, got ${cap}`);
+ */
+export function invariant(cond, msg) {
+    if (!cond) {
+        throw new InvariantError(msg);
+    }
+}

package/dist/util/logging.d.ts

@@ -0,0 +1,6 @@
+export type LogLevel = "info" | "warn" | "error";
+export declare const log: {
+    info: (msg: string, fields?: Record<string, unknown>) => void;
+    warn: (msg: string, fields?: Record<string, unknown>) => void;
+    error: (msg: string, fields?: Record<string, unknown>) => void;
+};

package/dist/util/logging.js

@@ -0,0 +1,12 @@
+// stderr-only structured logger. stdout is the MCP wire — anything we write there
+// corrupts the protocol. Importing `console.log` in src/ is a bug.
+function emit(level, msg, fields) {
+    const ts = new Date().toISOString();
+    const tail = fields && Object.keys(fields).length ? " " + JSON.stringify(fields) : "";
+    process.stderr.write(`[${ts}] ${level} browxai: ${msg}${tail}\n`);
+}
+export const log = {
+    info: (msg, fields) => emit("info", msg, fields),
+    warn: (msg, fields) => emit("warn", msg, fields),
+    error: (msg, fields) => emit("error", msg, fields),
+};