@trusty-squire/mcp 1.1.13-rc.8 → 1.1.13

package/dist/bot/compact-observation-v2.js

@@ -0,0 +1,1038 @@
+import { Buffer } from "node:buffer";
+export const OBSERVE_V2_MAX_WIRE_BYTES = 4_096;
+export const OBSERVE_V2_MAX_TOKENS = 1_024;
+const FIRST_PAGE_ROW_LIMIT = 4;
+export function compactV2PayloadWithinBudget(payload) {
+    const bytes = Buffer.byteLength(JSON.stringify(payload), "utf8");
+    return bytes <= OBSERVE_V2_MAX_WIRE_BYTES && bytes <= OBSERVE_V2_MAX_TOKENS;
+}
+/**
+ * Semantic essentials are sticky across V2 deltas. A repeat observation only
+ * needs to carry them when their already-sealed representation changed; the
+ * consumer retains the prior title/heading just like it retains safe_table.
+ */
+export function equalSafePageSemanticsV2(left, right) {
+    return left.title === right.title && (left.headings?.[0] ?? "") === (right.headings?.[0] ?? "");
+}
+/** `@e:` + a truncated session-secret HMAC of (document epoch, fingerprint). */
+export const COMPACT_V2_HANDLE_LENGTH = 10;
+const COMPACT_V2_HANDLE_RE = new RegExp(`^@e:[A-Za-z0-9_-]{${COMPACT_V2_HANDLE_LENGTH}}$`);
+const COMPACT_V2_LABEL_RE = /^@[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export function isCompactV2Handle(target) {
+    return COMPACT_V2_HANDLE_RE.test(target);
+}
+/** The `@label` alias form, distinguishable from a handle by its `@e:` prefix. */
+export function isCompactV2Label(target) {
+    return COMPACT_V2_LABEL_RE.test(target);
+}
+/**
+ * Resolve a handle only when it is well-formed AND a member of the current
+ * snapshot's sealed map. Callers must never turn an unknown @e: value into a
+ * label or legacy-ref lookup. The handle is document-scoped by construction
+ * (the epoch is hashed into it), so a ref from a replaced document finds no
+ * live match rather than resolving onto whatever now occupies its position.
+ */
+export function compactV2LegacyRefForHandle(handles, target) {
+    if (!isCompactV2Handle(target))
+        return null;
+    return handles.get(target) ?? null;
+}
+const LABEL_MAX_CHARS = 32;
+/**
+ * The addressable alias for a screened control description. Slugified so the
+ * agent can type it back verbatim; `undefined` when the description screened
+ * out or carries no alphanumeric content.
+ */
+export function controlLabelV2(description) {
+    if (description === undefined)
+        return undefined;
+    const slug = description
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, LABEL_MAX_CHARS)
+        .replace(/-+$/g, "");
+    return slug.length === 0 ? undefined : `@${slug}`;
+}
+// The protocol is intentionally positional to keep repeated observes small.
+// Tuple schema: [ref, role(b/l/t/s/c/r/tb/m/f), optional compact description].
+// The description starts with the `@label` alias (itself a valid act target)
+// and appends only present code-owned facts (`s=`, `a=`, `f=`, `q=`, `x=`). It
+// is deliberately one sparse string rather than nullable columns:
+// checked/unchecked, disabled, action, field, card choice, and frame context
+// remain distinguishable without paying for empty slots on every row. The
+// label's slug charset excludes `|` and `=`, so no escaping is needed.
+function wireControl(row) {
+    const role = {
+        button: "b",
+        link: "l",
+        textbox: "t",
+        select: "s",
+        checkbox: "c",
+        radio: "r",
+        tab: "tb",
+        menuitem: "m",
+        file: "f",
+    };
+    const facts = [
+        row.label,
+        ...(row.state === undefined ? [] : [`s=${row.state}`]),
+        ...(row.action === undefined ? [] : [`a=${row.action}`]),
+        ...(row.field === undefined ? [] : [`f=${row.field}`]),
+        ...(row.choice === undefined ? [] : [`q=${row.choice}`]),
+        ...(row.frame === "main" ? [] : [`x=${row.frame === "same_origin" ? "s" : "x"}`]),
+    ].filter((value) => value !== undefined);
+    return facts.length === 0
+        ? [row.ref, role[row.role]]
+        : [row.ref, role[row.role], facts.join("|")];
+}
+const SAFE_DESCRIPTION_MAX_CHARS = 40;
+// There is NO description screening on the observation path. Every string a
+// page renders — OAuth button copy, an email address, a Gmail subject line, a
+// street address, a rendered API key, a card number — is content the driving
+// agent needs to read. The only transform left is truncation, which is the
+// compactness budget, not masking.
+const CARD_SECURITY_VALUE_RE = /\b(?:cvv|cvc|security\s*code)\s*[:#-]?\s*\d{3,4}\b/i;
+const PAN_MAX_SPAN_CHARS = 96;
+function luhnValid(digits) {
+    let sum = 0;
+    let double = false;
+    for (let index = digits.length - 1; index >= 0; index -= 1) {
+        let digit = Number(digits[index]);
+        if (double) {
+            digit *= 2;
+            if (digit > 9)
+                digit -= 9;
+        }
+        sum += digit;
+        double = !double;
+    }
+    return sum % 10 === 0;
+}
+/** A rendered card number: 13-19 digits in one span that passes Luhn. */
+function containsLuhnPan(value) {
+    const positions = Array.from(value.matchAll(/\d/g), (match) => match.index);
+    for (let start = 0; start + 13 <= positions.length; start += 1) {
+        const maxLength = Math.min(19, positions.length - start);
+        for (let length = 13; length <= maxLength; length += 1) {
+            const span = positions.slice(start, start + length);
+            if (span[span.length - 1] - span[0] + 1 > PAN_MAX_SPAN_CHARS)
+                break;
+            if (luhnValid(span.map((position) => value[position]).join("")))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Card material, used ONLY by the recordable-token screen below (the operator's
+ * stderr audit trail and the action trace a capture publishes to the SHARED
+ * skill registry). It is never applied to what the agent is shown.
+ */
+function carriesPaymentMaterial(value) {
+    return containsLuhnPan(value) || CARD_SECURITY_VALUE_RE.test(value);
+}
+// ---- Recordable-token screen (NOT observation redaction) -------------------
+// Two surfaces are not the agent's view of the page and keep their original
+// closed-vocabulary screen: the operator's structured stderr audit trail, and
+// the recorded action trace that a captured run publishes to the SHARED skill
+// registry. Both cross a boundary the payment-only observation policy says
+// nothing about — one is a log, the other is cross-user institutional memory —
+// so a page-derived string still has to be recognizable code-owned vocabulary
+// before it lands there. Never use this to screen what `operate_observe`,
+// `operate_observe_query`, or `operate_screenshot` shows the driving agent.
+const RECORDABLE_TOKEN_MAX_CHARS = 40;
+const RECORDABLE_EMAIL_RE = /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/i;
+const RECORDABLE_SECRET_ASSIGNMENT_RE = /\b(?:password|passcode|token|api[_ -]?key|secret)\b\s*[:=]\s*\S{4,}/i;
+const RECORDABLE_HIGH_ENTROPY_RE = /\b[A-Za-z0-9_-]{24,}\b/;
+const RECORDABLE_GRAMMAR_RE = /^[\p{L}\p{N}][\p{L}\p{N}\s&'’+,.!?():=/@_$|-]*$/u;
+const RECORDABLE_WORDS = new Set([
+    "a",
+    "access",
+    "account",
+    "add",
+    "address",
+    "an",
+    "and",
+    "api",
+    "back",
+    "bag",
+    "basket",
+    "billing",
+    "button",
+    "cancel",
+    "card",
+    "cart",
+    "choose",
+    "checkout",
+    "city",
+    "close",
+    "code",
+    "confirm",
+    "contact",
+    "continue",
+    "control",
+    "controls",
+    "copy",
+    "country",
+    "create",
+    "customer",
+    "date",
+    "dense",
+    "delivery",
+    "details",
+    "different",
+    "discount",
+    "dismiss",
+    "done",
+    "economy",
+    "email",
+    "example",
+    "express",
+    "external",
+    "first",
+    "finish",
+    "form",
+    "free",
+    "gift",
+    "google",
+    "ground",
+    "in",
+    "item",
+    "key",
+    "large",
+    "log",
+    "login",
+    "merchant",
+    "method",
+    "name",
+    "native",
+    "next",
+    "no",
+    "now",
+    "option",
+    "order",
+    "overnight",
+    "page",
+    "password",
+    "pay",
+    "payment",
+    "phone",
+    "pickup",
+    "postal",
+    "previous",
+    "priority",
+    "private",
+    "proceed",
+    "product",
+    "promo",
+    "quantity",
+    "rate",
+    "region",
+    "register",
+    "registration",
+    "review",
+    "save",
+    "sample",
+    "search",
+    "secure",
+    "select",
+    "serialized",
+    "shipping",
+    "sign",
+    "signup",
+    "size",
+    "standard",
+    "storefront",
+    "style",
+    "submit",
+    "terms",
+    "thanks",
+    "to",
+    "token",
+    "united",
+    "username",
+    "variant",
+    "verification",
+    "view",
+    "with",
+    "workspace",
+    "your",
+]);
+function hasRecordableGrammar(value) {
+    if (!RECORDABLE_GRAMMAR_RE.test(value))
+        return false;
+    const words = value.match(/[\p{L}\p{N}]+/gu) ?? [];
+    return (words.length > 0 &&
+        words.every((word) => RECORDABLE_WORDS.has(word.toLowerCase()) || /^\d{1,6}$/.test(word)));
+}
+/**
+ * The screen for the audit trail and the registry-bound action trace. Returns
+ * `undefined` for anything outside the code-owned vocabulary; callers turn that
+ * into `<sealed>` or refuse to record the action.
+ */
+export function recordableTokenV2(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const normalized = value.replace(/\s+/g, " ").trim();
+    if (normalized.length === 0 ||
+        !hasRecordableGrammar(normalized) ||
+        carriesPaymentMaterial(normalized) ||
+        normalized.replace(/\D/g, "").length >= 13 ||
+        RECORDABLE_EMAIL_RE.test(normalized) ||
+        RECORDABLE_SECRET_ASSIGNMENT_RE.test(normalized) ||
+        RECORDABLE_HIGH_ENTROPY_RE.test(normalized)) {
+        return undefined;
+    }
+    return normalized.length <= RECORDABLE_TOKEN_MAX_CHARS
+        ? normalized
+        : `${normalized.slice(0, RECORDABLE_TOKEN_MAX_CHARS - 1)}…`;
+}
+/**
+ * Normalize and length-budget a page-derived description for the wire row. It
+ * rejects nothing: the truncation is the compactness budget, not redaction.
+ */
+export function safeDescriptionV2(value) {
+    if (typeof value !== "string")
+        return undefined;
+    // Control characters would break the positional wire encoding; they are not
+    // page copy, so dropping them is formatting rather than masking.
+    const normalized = value
+        .replace(/[\p{Cc}\p{Cf}]/gu, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    if (normalized.length === 0)
+        return undefined;
+    return normalized.length <= SAFE_DESCRIPTION_MAX_CHARS
+        ? normalized
+        : `${normalized.slice(0, SAFE_DESCRIPTION_MAX_CHARS - 1)}…`;
+}
+const SAFE_AUTOCOMPLETE_TOKENS = new Set([
+    "address-level1",
+    "address-level2",
+    "address-line1",
+    "address-line2",
+    "address-line3",
+    "bday",
+    "bday-day",
+    "bday-month",
+    "bday-year",
+    "cc-csc",
+    "cc-exp",
+    "cc-exp-month",
+    "cc-exp-year",
+    "cc-name",
+    "cc-number",
+    "country",
+    "country-name",
+    "current-password",
+    "email",
+    "family-name",
+    "given-name",
+    "honorific-prefix",
+    "honorific-suffix",
+    "name",
+    "new-password",
+    "nickname",
+    "one-time-code",
+    "organization",
+    "organization-title",
+    "postal-code",
+    "shipping",
+    "street-address",
+    "tel",
+    "tel-area-code",
+    "tel-country-code",
+    "tel-extension",
+    "tel-local",
+    "tel-local-prefix",
+    "tel-local-suffix",
+    "tel-national",
+    "transaction-amount",
+    "transaction-currency",
+    "username",
+]);
+function safeAutocompleteV2(value) {
+    if (typeof value !== "string")
+        return null;
+    const tokens = value.toLowerCase().trim().split(/\s+/).filter(Boolean);
+    return tokens.length > 0 && tokens.every((token) => SAFE_AUTOCOMPLETE_TOKENS.has(token))
+        ? tokens.join(" ")
+        : null;
+}
+// Structural hostname validity only — no content screen. A host that fails this
+// is malformed, not sensitive.
+function safeHostnameV2(value) {
+    const hostname = value.toLowerCase();
+    if (hostname.length === 0 || hostname.length > 253)
+        return false;
+    return hostname.split(".").every((label) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label));
+}
+export function safeOriginV2(value) {
+    if (typeof value !== "string")
+        return null;
+    try {
+        const parsed = new URL(value);
+        if ((parsed.protocol !== "https:" && parsed.protocol !== "http:") ||
+            parsed.username.length > 0 ||
+            parsed.password.length > 0 ||
+            !safeHostnameV2(parsed.hostname)) {
+            return null;
+        }
+        return parsed.origin;
+    }
+    catch {
+        return null;
+    }
+}
+// Audit-trail sealing: the operator's structured stderr trail must never carry
+// a raw URL or host while compact-v2 is sealing an observation. These two are
+// the audit-side counterpart of safeOriginV2, and live here with it so both the
+// lifecycle transaction and the observe/act surface can reach them.
+export function compactV2AuditUrl(rawUrl) {
+    return safeOriginV2(rawUrl) ?? "<sealed-origin>";
+}
+export function compactV2AuditHost(rawHost) {
+    const origin = safeOriginV2(rawHost.includes("://") ? rawHost : `https://${rawHost}`);
+    if (origin === null)
+        return "<sealed-host>";
+    return new URL(origin).host;
+}
+export function compactV2AuditValue(key, value) {
+    if ((key === "url" || key === "service_url") && typeof value === "string") {
+        return compactV2AuditUrl(value);
+    }
+    if ((key === "host" || key === "url_host" || key === "frame_origin" || key === "recipe_domain") &&
+        typeof value === "string") {
+        return compactV2AuditHost(value);
+    }
+    if (key === "allowed_hosts" && Array.isArray(value)) {
+        return value.map((host) => typeof host === "string" ? compactV2AuditHost(host) : "<sealed-host>");
+    }
+    if (typeof value === "string")
+        return recordableTokenV2(value) ?? "<sealed>";
+    if (Array.isArray(value))
+        return value.map((item) => compactV2AuditValue("", item));
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([nestedKey, nestedValue]) => [
+            nestedKey,
+            compactV2AuditValue(nestedKey, nestedValue),
+        ]));
+    }
+    return value;
+}
+export function sealRetainedInteractiveElementsV2(elements, selectorFor = () => "") {
+    // The retained inventory is what the recorded action trace reads its
+    // dom_hint / accessible_name from, so it is screened for RECORDABILITY, not
+    // by the payment-only observation policy. What the agent SEES is built from
+    // freshly extracted elements through safeDescriptionV2.
+    const description = (value) => recordableTokenV2(value) ?? null;
+    const finiteToken = (value, allowed) => {
+        const normalized = value?.toLowerCase();
+        return normalized !== undefined && allowed.has(normalized) ? normalized : null;
+    };
+    const tags = new Set([
+        "a",
+        "button",
+        "details",
+        "input",
+        "label",
+        "option",
+        "select",
+        "summary",
+        "textarea",
+    ]);
+    const types = new Set([
+        "button",
+        "checkbox",
+        "date",
+        "email",
+        "file",
+        "hidden",
+        "image",
+        "month",
+        "number",
+        "password",
+        "radio",
+        "reset",
+        "search",
+        "submit",
+        "tel",
+        "text",
+        "time",
+        "url",
+        "week",
+    ]);
+    const roles = new Set([
+        "button",
+        "checkbox",
+        "combobox",
+        "link",
+        "listbox",
+        "menuitem",
+        "option",
+        "radio",
+        "searchbox",
+        "switch",
+        "tab",
+        "textbox",
+    ]);
+    return elements.map((element) => ({
+        index: element.index,
+        tag: finiteToken(element.tag, tags) ?? "unknown",
+        type: finiteToken(element.type, types),
+        id: description(element.id),
+        name: description(element.name),
+        placeholder: description(element.placeholder),
+        ariaLabel: description(element.ariaLabel),
+        role: finiteToken(element.role, roles),
+        labelText: description(element.labelText),
+        visibleText: description(element.visibleText),
+        selector: selectorFor(element),
+        visible: element.visible === true,
+        inViewport: element.inViewport === true,
+        inConsentWidget: element.inConsentWidget === true,
+        href: null,
+        iconLabel: description(element.iconLabel),
+        title: description(element.title),
+        testId: description(element.testId),
+        autocomplete: safeAutocompleteV2(element.autocomplete),
+        dataRole: null,
+        landmark: typeof element.landmark === "string" &&
+            /^(?:header|main|footer|nav|aside|article|section)$/.test(element.landmark)
+            ? element.landmark
+            : null,
+        value: null,
+        checked: element.checked ?? null,
+        disabled: element.disabled ?? null,
+        required: element.required ?? null,
+        selectOptions: null,
+        selectedOptionText: null,
+        interactedThisRun: element.interactedThisRun === true,
+        screenPath: null,
+        container: null,
+        containerId: typeof element.containerId === "number" &&
+            Number.isSafeInteger(element.containerId) &&
+            element.containerId > 0
+            ? element.containerId
+            : null,
+        formId: typeof element.formId === "number" &&
+            Number.isSafeInteger(element.formId) &&
+            element.formId > 0
+            ? element.formId
+            : null,
+        topmost: element.topmost ?? null,
+        occludedBy: null,
+        cardRadioGroup: element.cardRadioGroup !== null &&
+            element.cardRadioGroup !== undefined &&
+            Number.isSafeInteger(element.cardRadioGroup.id) &&
+            Number.isSafeInteger(element.cardRadioGroup.position) &&
+            Number.isSafeInteger(element.cardRadioGroup.total)
+            ? {
+                id: element.cardRadioGroup.id,
+                position: element.cardRadioGroup.position,
+                total: element.cardRadioGroup.total,
+            }
+            : null,
+        frameOrigin: safeOriginV2(element.frameOrigin),
+        frameUrl: null,
+        framePath: typeof element.framePath === "string" && /^\d+(?:\/\d+)*$/.test(element.framePath)
+            ? element.framePath
+            : null,
+        frameOpaque: element.frameOpaque === true,
+    }));
+}
+export function safePageSemanticsV2(source) {
+    const title = safeDescriptionV2(source.title);
+    const headings = source.headings
+        .map((heading) => safeDescriptionV2(heading))
+        .filter((value) => value !== undefined)
+        .filter((value, index, all) => all.indexOf(value) === index)
+        .slice(0, 1);
+    return {
+        ...(title === undefined ? {} : { title }),
+        ...(headings.length === 0 ? {} : { headings }),
+    };
+}
+/**
+ * Diff only the sealed representation.  In particular, raw changes to a
+ * field value, card number, live region, or merchant copy cannot cause either
+ * the raw data or a page-derived derivative to cross into the delta.
+ */
+export function diffSafeControlsV2(previous, stage, rows) {
+    const current = new Map(rows.map((row) => [row.ref, row]));
+    const added = [];
+    const changed = [];
+    for (const row of rows) {
+        const before = previous.byRef.get(row.ref);
+        if (before === undefined)
+            added.push(row);
+        else if (JSON.stringify(wireControl(before)) !== JSON.stringify(wireControl(row)))
+            changed.push(row);
+    }
+    const removed = [...previous.byRef.keys()].filter((ref) => !current.has(ref));
+    return { added, changed, removed, stageChanged: previous.stage !== stage };
+}
+/**
+ * Encodes a structural V2 delta. `null` deliberately asks the caller to send
+ * a paged full resync instead: a delta must never exceed the hard wire budget.
+ */
+export function encodeV2Delta(args) {
+    const payload = {
+        format: "compact-v2",
+        url: args.pageUrl ?? "",
+        text: "",
+        session_id: args.sessionId,
+        delta: true,
+        ...(args.semantics === undefined ? {} : { semantic: args.semantics }),
+        ...(args.delta.stageChanged ? { stage: args.stage } : {}),
+        // `safe_table` follows the established TS delta protocol: rows are
+        // upserts, irrespective of whether their ref is new or changed. This keeps
+        // existing delta consumers compatible while the @e: map itself stays V2.
+        ...(args.delta.added.length + args.delta.changed.length > 0
+            ? { safe_table: [...args.delta.added, ...args.delta.changed].map(wireControl) }
+            : {}),
+        ...(args.delta.removed.length > 0 ? { removed: args.delta.removed } : {}),
+    };
+    return compactV2PayloadWithinBudget(payload) ? payload : null;
+}
+const INTENTS = [
+    ["add_to_cart", /add\s+(?:to\s+)?(?:cart|bag|basket)/i],
+    ["view_cart", /view\s+(?:cart|bag|basket)/i],
+    ["destructive", /\b(?:delete|remove|erase|destroy)\b/i],
+    ["checkout", /^(?:(?:go|proceed|continue)(?:\s+to)?\s+)?(?:secure\s+)?checkout(?:\s+now)?$/i],
+    ["payment", /\b(?:pay(?:ment)?|card)\b/i],
+    ["signup", /sign\s*up|create\s+(?:account|workspace)|register/i],
+    ["login", /log\s*in|sign\s*in|continue\s+with/i],
+    ["search", /search|find/i],
+    ["close", /close|dismiss|cancel|no\s+thanks/i],
+    ["next", /next/i],
+    ["previous", /previous|back/i],
+    ["submit", /submit|save|create|send/i],
+    ["continue", /continue|proceed|start|accept|allow|keep|retain/i],
+];
+const BUTTON_INPUT_TYPES = new Set(["button", "submit", "reset", "image"]);
+function isButtonInput(el) {
+    return el.tag === "input" && BUTTON_INPUT_TYPES.has((el.type ?? "").toLowerCase());
+}
+function controlNamingTexts(el) {
+    return [
+        el.visibleText,
+        el.labelText,
+        el.ariaLabel,
+        el.iconLabel,
+        el.title,
+        el.placeholder,
+        isButtonInput(el) ? el.value : undefined,
+    ];
+}
+function candidateTexts(el) {
+    return [
+        el.visibleText,
+        el.labelText,
+        el.ariaLabel,
+        el.iconLabel,
+        el.title,
+        el.placeholder,
+        el.name,
+        el.id,
+        ...(isButtonInput(el) ? [el.value] : []),
+    ]
+        .filter((part) => typeof part === "string")
+        .map((part) => part.replace(/[-_]+/g, " ").replace(/\s+/g, " ").trim())
+        .filter(Boolean);
+}
+function candidateText(el) {
+    return candidateTexts(el).join(" ");
+}
+function controlDescription(el) {
+    // Labels are chosen from visible/accessibility naming sources only. Native
+    // button values are names; field values, `name`, and `id` stay excluded.
+    return controlNamingTexts(el)
+        .map((candidate) => safeDescriptionV2(candidate))
+        .find((candidate) => candidate !== undefined);
+}
+function privateQueryTokenV2(value) {
+    const normalized = value.normalize("NFKC").trim().toLowerCase();
+    if (normalized.length < 1 ||
+        normalized.length > 48 ||
+        !/^[\p{L}\p{M}\p{N}]{1,48}$/u.test(normalized) ||
+        (/^\p{N}+$/u.test(normalized) && normalized.length > 4)) {
+        return null;
+    }
+    return normalized;
+}
+function privateQueryTermsV2(value) {
+    const normalized = value.normalize("NFKC").trim().toLowerCase();
+    if (normalized.length < 1 || normalized.length > 96)
+        return null;
+    const rawTerms = normalized.match(/[\p{L}\p{M}\p{N}]{1,48}/gu);
+    if (rawTerms === null || rawTerms.length === 0 || rawTerms.length > 6)
+        return null;
+    const separators = normalized.replace(/[\p{L}\p{M}\p{N}]{1,48}/gu, "");
+    if (!/^[\s&'’+,.!?():/_|-]*$/u.test(separators))
+        return null;
+    const terms = rawTerms.map(privateQueryTokenV2);
+    return terms.every((term) => term !== null) ? [...new Set(terms)] : null;
+}
+export function controlMatchesPrivateQueryV2(el, query) {
+    const needles = privateQueryTermsV2(query);
+    if (needles === null)
+        return false;
+    // The private match also consults the element's name/id slugs so
+    // choice-group members without their own copy — Shopify shipping-rate
+    // radios (name "checkout[shipping_rate][id]", id "checkout_shipping_rate_…")
+    // — stay queryable. These are DOM identifiers, never field values, and each
+    // candidate still passes the full secret-shape gate below before any token
+    // comparison.
+    return [...controlNamingTexts(el), el.name, el.id].some((candidate) => {
+        if (typeof candidate !== "string")
+            return false;
+        const tokens = candidate.normalize("NFKC").match(/[\p{L}\p{M}\p{N}]{1,48}/gu);
+        if (tokens === null)
+            return false;
+        const safeTokens = new Set(tokens.map(privateQueryTokenV2).filter((token) => token !== null));
+        return needles.every((needle) => safeTokens.has(needle));
+    });
+}
+function roleOf(el) {
+    const role = (el.role ?? "").toLowerCase();
+    const type = (el.type ?? "").toLowerCase();
+    if (type === "file")
+        return "file";
+    if (isButtonInput(el))
+        return "button";
+    if (type === "checkbox" || role === "checkbox")
+        return "checkbox";
+    if (type === "radio" || role === "radio")
+        return "radio";
+    if (el.tag === "select" || role === "combobox" || role === "listbox")
+        return "select";
+    if (el.tag === "input" || el.tag === "textarea" || role === "textbox")
+        return "textbox";
+    if (el.tag === "a" || role === "link")
+        return "link";
+    if (role === "tab")
+        return "tab";
+    if (role === "menuitem" || role === "option")
+        return "menuitem";
+    if (el.tag === "button" ||
+        role === "button" ||
+        (el.topmost !== null && el.topmost !== undefined)) {
+        return "button";
+    }
+    return null;
+}
+function stateOf(el) {
+    // A compact code-owned bitset: c=checked, u=unchecked, d=disabled,
+    // r=required.  It is deliberately not a page-provided string.
+    let state = "";
+    if (el.checked === true)
+        state += "c";
+    else if (el.checked === false)
+        state += "u";
+    if (el.disabled === true)
+        state += "d";
+    if (el.required === true)
+        state += "r";
+    return state || undefined;
+}
+function intentOf(el) {
+    const texts = candidateTexts(el);
+    return INTENTS.find(([, expression]) => texts.some((text) => expression.test(text)))?.[0];
+}
+function hasExplicitPaymentFieldSignal(el) {
+    const autocomplete = (el.autocomplete ?? "").toLowerCase();
+    const text = candidateText(el).toLowerCase();
+    return (autocomplete
+        .trim()
+        .split(/\s+/)
+        .some((token) => token.startsWith("cc-")) ||
+        /\b(?:cvc|cvv|csc|card verification(?: (?:value|number))?|card security code)\b/.test(text) ||
+        /\b(?:card number|payment card|credit card|debit card)\b/.test(text));
+}
+function fieldOf(el, paymentContext = false) {
+    const autocomplete = (el.autocomplete ?? "").toLowerCase();
+    const autocompleteTokens = new Set(autocomplete.trim().split(/\s+/).filter(Boolean));
+    const hasAutocomplete = (...tokens) => tokens.some((token) => autocompleteTokens.has(token));
+    const type = (el.type ?? "").toLowerCase();
+    const text = candidateText(el).toLowerCase();
+    if (hasExplicitPaymentFieldSignal(el) ||
+        (paymentContext && /\b(?:security code|cvn|cid)\b/.test(text))) {
+        return "payment";
+    }
+    if (type === "password" || hasAutocomplete("current-password", "new-password")) {
+        return "password";
+    }
+    if (type === "email" || hasAutocomplete("email") || /\be-?mail\b/.test(text))
+        return "email";
+    if (type === "tel" ||
+        [...autocompleteTokens].some((token) => token === "tel" || token.startsWith("tel-")) ||
+        /\b(phone|mobile|telephone)\b/.test(text))
+        return "phone";
+    if (type === "search" || /\bsearch\b/.test(text))
+        return "search";
+    if (hasAutocomplete("username") || /\b(user ?name|handle)\b/.test(text))
+        return "username";
+    if (/\b(card|payment|cc-)/.test(`${autocomplete} ${text}`))
+        return "payment";
+    if (hasAutocomplete("address-level2") || /\b(city|town)\b/.test(text))
+        return "city";
+    if (hasAutocomplete("address-level1") || /\b(state|province|region)\b/.test(text))
+        return "region";
+    if (hasAutocomplete("postal-code") || /\b(zip|postal)\b/.test(text))
+        return "postal";
+    if (hasAutocomplete("country", "country-name") || /\bcountry\b/.test(text))
+        return "country";
+    // `address-line2` is the optional apartment/suite field in the HTML
+    // autocomplete vocabulary. Shopify renders it directly below a required
+    // Places-backed `address-line1` combobox. Treating both as `address` makes
+    // the compact action map advertise two interchangeable street fields, and a
+    // caller can put the delivery address in the apartment field instead. Keep
+    // `address` reserved for the required street-address / line-1 control; the
+    // optional secondary line is intentionally not a checkout fill target.
+    if (hasAutocomplete("address-line2", "address-line3") ||
+        /\b(?:apartment|apt\.?|suite|unit|floor|building)\b/.test(text) ||
+        /\boptional\b/.test(text))
+        return undefined;
+    if (hasAutocomplete("street-address", "address-line1") || /\b(address|street)\b/.test(text))
+        return "address";
+    if (type === "date" ||
+        [...autocompleteTokens].some((token) => token.startsWith("bday")) ||
+        /\bdate\b/.test(text))
+        return "date";
+    if (/\b(quantity|qty)\b/.test(text))
+        return "quantity";
+    if (/\b(promo|coupon|discount)\b/.test(text))
+        return "promo";
+    if ([...autocompleteTokens].some((token) => token === "name" || token.endsWith("-name")) ||
+        /\b(full )?name\b/.test(text))
+        return "name";
+    return undefined;
+}
+/** A code-owned page-stage enum; it never forwards the URL or page copy. */
+export function safeStageV2(url, elements) {
+    let pathname = "";
+    try {
+        pathname = decodeURIComponent(new URL(url).pathname).toLowerCase();
+    }
+    catch { }
+    if (/(?:^|\/)(?:success|complete|thank-you|thank_you|finished|done)(?:\.(?:php|html?))?(?:\/|$)/.test(pathname)) {
+        return "complete";
+    }
+    const actionableElements = elements.filter((element) => element.visible === true && element.topmost !== false);
+    const routeStage = checkoutStageFromUrlV2(url);
+    const paymentContext = routeStage !== null ||
+        actionableElements.some((element) => hasExplicitPaymentFieldSignal(element));
+    const checkoutFields = new Set([
+        "address",
+        "city",
+        "region",
+        "postal",
+        "country",
+        "payment",
+    ]);
+    const hasCheckoutField = actionableElements.some((el) => {
+        const role = roleOf(el);
+        const field = fieldOf(el, paymentContext);
+        return ((role === "textbox" || role === "select") && field !== undefined && checkoutFields.has(field));
+    });
+    const authFields = actionableElements.filter((el) => {
+        const role = roleOf(el);
+        if (role !== "textbox" && role !== "select")
+            return false;
+        const field = fieldOf(el, paymentContext);
+        return field === "email" || field === "username" || field === "password";
+    });
+    const hasPasswordField = authFields.some((el) => fieldOf(el, paymentContext) === "password");
+    const hasScopedAuthForm = actionableElements.some((el) => {
+        if (roleOf(el) !== "button" || (intentOf(el) !== "login" && intentOf(el) !== "signup")) {
+            return false;
+        }
+        const ownerId = el.formId ?? el.containerId;
+        const framePath = el.framePath ?? null;
+        return (ownerId !== undefined &&
+            ownerId !== null &&
+            authFields.some((field) => (field.formId ?? field.containerId) === ownerId &&
+                (field.framePath ?? null) === framePath));
+    });
+    if (hasPasswordField || hasScopedAuthForm)
+        return "auth";
+    if (routeStage !== null)
+        return routeStage;
+    const hasPaymentField = actionableElements.some((el) => {
+        const role = roleOf(el);
+        return (role === "textbox" || role === "select") && fieldOf(el, paymentContext) === "payment";
+    });
+    const hasCheckoutAction = actionableElements.some((el) => roleOf(el) === "button" && intentOf(el) === "checkout");
+    if (hasPaymentField || (hasCheckoutAction && hasCheckoutField))
+        return "checkout";
+    if (actionableElements.some((el) => intentOf(el) === "add_to_cart"))
+        return "browse";
+    if (actionableElements.some((el) => roleOf(el) === "textbox" || roleOf(el) === "select"))
+        return "form";
+    return "browse";
+}
+export function checkoutStageFromUrlV2(url) {
+    let pathname = "";
+    try {
+        pathname = decodeURIComponent(new URL(url).pathname).toLowerCase();
+    }
+    catch {
+        return null;
+    }
+    if (/(?:^|\/)(?:checkout|secure[-_]?checkout|payment|order[-_]?review|order\/review)(?:\.(?:php|html?))?(?:\/|$)/i.test(pathname)) {
+        return "checkout";
+    }
+    if (/(?:^|\/)(?:cart|shopping[-_]?cart|view[-_]?cart|basket|bag)(?:\.(?:php|html?))?(?:\/|$)/i.test(pathname)) {
+        return "cart";
+    }
+    return null;
+}
+function frameOf(el, pageOrigin) {
+    if (el.frameOrigin === null || el.frameOrigin === undefined)
+        return "main";
+    return el.frameOrigin === pageOrigin ? "same_origin" : "cross_origin";
+}
+export function buildSafeControlsV2(args) {
+    const rows = [];
+    const paymentContext = checkoutStageFromUrlV2(args.pageUrl ?? "") !== null ||
+        args.elements.some((element) => hasExplicitPaymentFieldSignal(element));
+    for (const el of args.elements) {
+        if (el.visible !== true || el.topmost === false)
+            continue;
+        const role = roleOf(el);
+        const legacy = args.legacyRefs.get(el);
+        const ref = args.handles.get(el);
+        if (role === null || legacy === undefined || ref === undefined)
+            continue;
+        const state = stateOf(el);
+        const action = intentOf(el);
+        const field = fieldOf(el, paymentContext);
+        const cardChoice = el.cardRadioGroup;
+        // Native TypeScript port of browse-use's compact DOM formatting: the
+        // already CDP-derived interactive inventory supplies each visible control's
+        // descendant/accessibility name. This pass binds that name to its own live
+        // element, so no cross-serializer tag/role fallback can swap labels.
+        const label = controlLabelV2(controlDescription(el));
+        const row = {
+            role,
+            visibility: el.inViewport ? "viewport" : "near",
+            frame: frameOf(el, args.pageOrigin),
+            ...(state === undefined ? {} : { state }),
+            ...(action === undefined ? {} : { action }),
+            ...(field === undefined ? {} : { field }),
+            ...(label === undefined ? {} : { label }),
+            ...(cardChoice === null || cardChoice === undefined
+                ? {}
+                : { choice: `${cardChoice.position}/${cardChoice.total}` }),
+        };
+        // A signup/login action is the useful first move on a landing page. Put it
+        // ahead of unlabeled navigation chrome while preserving the existing
+        // viewport and role ordering within each group.
+        const actionPriority = action === "signup" ? -20 : action === "login" ? -10 : 0;
+        rows.push({
+            ref,
+            legacy,
+            row,
+            priority: actionPriority + (el.inViewport ? 0 : 10) + (role === "button" ? 0 : 1),
+        });
+    }
+    rows.sort((a, b) => a.priority - b.priority || a.legacy.localeCompare(b.legacy));
+    const byRef = new Map();
+    const safeRows = rows.map(({ ref, legacy, row }) => {
+        byRef.set(ref, legacy);
+        return { ref, ...row };
+    });
+    return { rows: safeRows, byRef };
+}
+export function encodeV2Page(args) {
+    const offset = args.offset ?? 0;
+    if (args.unchanged === true && offset === 0) {
+        const payload = {
+            format: "compact-v2",
+            url: args.pageUrl ?? "",
+            text: "",
+            session_id: args.sessionId,
+            stage: args.stage,
+            ...(args.startMetadata?.hint === undefined ? {} : { hint: args.startMetadata.hint }),
+            ...(args.startMetadata?.userEmail === undefined
+                ? {}
+                : { user_email: args.startMetadata.userEmail }),
+            ...(args.startMetadata?.hintOverflow === undefined
+                ? {}
+                : { hint_overflow: args.startMetadata.hintOverflow }),
+            ...(args.semantics === undefined || Object.keys(args.semantics).length === 0
+                ? {}
+                : { semantic: args.semantics }),
+            delta: true,
+        };
+        if (!compactV2PayloadWithinBudget(payload)) {
+            throw new Error("compact-v2 budget metadata exceeded");
+        }
+        return {
+            payload,
+            nextOffset: 0,
+        };
+    }
+    const visible = [];
+    // Initial observations stay decisively small. Overflow is retrieved through
+    // the in-MCP query cursor, never a shell-readable snapshot file.
+    const pageEnd = offset === 0 ? Math.min(args.rows.length, FIRST_PAGE_ROW_LIMIT) : args.rows.length;
+    for (let index = offset; index < pageEnd; index += 1) {
+        const candidate = args.rows[index];
+        const remainder = args.rows.length - (index + 1);
+        const payload = {
+            format: "compact-v2",
+            url: args.pageUrl ?? "",
+            text: "",
+            session_id: args.sessionId,
+            stage: args.stage,
+            ...(args.startMetadata?.hint === undefined ? {} : { hint: args.startMetadata.hint }),
+            ...(args.startMetadata?.userEmail === undefined
+                ? {}
+                : { user_email: args.startMetadata.userEmail }),
+            ...(args.startMetadata?.hintOverflow === undefined
+                ? {}
+                : { hint_overflow: args.startMetadata.hintOverflow }),
+            ...(args.semantics === undefined || Object.keys(args.semantics).length === 0
+                ? {}
+                : { semantic: args.semantics }),
+            safe_table: [...visible, wireControl(candidate)],
+            ...(remainder > 0
+                ? { overflow: { remaining: remainder, next_cursor: args.cursorFor(index + 1) } }
+                : {}),
+        };
+        if (!compactV2PayloadWithinBudget(payload))
+            break;
+        visible.push(wireControl(candidate));
+    }
+    const nextOffset = offset + visible.length;
+    const remaining = args.rows.length - nextOffset;
+    const payload = {
+        format: "compact-v2",
+        url: args.pageUrl ?? "",
+        text: "",
+        session_id: args.sessionId,
+        stage: args.stage,
+        ...(args.startMetadata?.hint === undefined ? {} : { hint: args.startMetadata.hint }),
+        ...(args.startMetadata?.userEmail === undefined
+            ? {}
+            : { user_email: args.startMetadata.userEmail }),
+        ...(args.startMetadata?.hintOverflow === undefined
+            ? {}
+            : { hint_overflow: args.startMetadata.hintOverflow }),
+        ...(args.semantics === undefined || Object.keys(args.semantics).length === 0
+            ? {}
+            : { semantic: args.semantics }),
+        safe_table: visible,
+        ...(remaining > 0 ? { overflow: { remaining, next_cursor: args.cursorFor(nextOffset) } } : {}),
+    };
+    // The fixed fields are deliberately tiny, so failure means a hostilely long
+    // session id/cursor. Fail closed rather than exceeding the wire contract.
+    if (!compactV2PayloadWithinBudget(payload)) {
+        throw new Error("compact-v2 budget metadata exceeded");
+    }
+    return { payload, nextOffset };
+}
+//# sourceMappingURL=compact-observation-v2.js.map