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

package/dist/bot/compact-observation-v2.d.ts

@@ -0,0 +1,167 @@
+import type { InteractiveElement } from "./browser.js";
+export declare const OBSERVE_V2_MAX_WIRE_BYTES = 4096;
+export declare const OBSERVE_V2_MAX_TOKENS = 1024;
+export declare function compactV2PayloadWithinBudget(payload: unknown): boolean;
+export type SafeRoleV2 = "button" | "link" | "textbox" | "select" | "checkbox" | "radio" | "tab" | "menuitem" | "file";
+export type SafeIntentV2 = "search" | "close" | "next" | "previous" | "submit" | "continue" | "login" | "signup" | "add_to_cart" | "view_cart" | "checkout" | "payment" | "destructive";
+export type SafeFieldV2 = "email" | "password" | "username" | "name" | "phone" | "search" | "address" | "city" | "region" | "postal" | "country" | "date" | "quantity" | "promo" | "payment";
+export type SafeStageV2 = "browse" | "auth" | "form" | "cart" | "checkout" | "complete";
+export interface SafeControlV2 {
+    ref: string;
+    role: SafeRoleV2;
+    state?: string;
+    visibility: "viewport" | "near";
+    action?: SafeIntentV2;
+    field?: SafeFieldV2;
+    /**
+     * The legible alias the agent may target instead of `ref` (`@email-address`).
+     * Screened and slugified from the control's accessible name; never a value.
+     */
+    label?: string;
+    choice?: string;
+    frame: "main" | "same_origin" | "cross_origin";
+}
+/** Raw DOM input is accepted only from title and visible heading elements. */
+export interface ObservationSemanticSourceV2 {
+    title: string;
+    headings: readonly string[];
+}
+export interface SafePageSemanticsV2 {
+    title?: string;
+    headings?: string[];
+}
+/**
+ * The observed document version an act is authorized against
+ * (docs/observation-model.md §4.1). `doc` is an internal HMAC of the browser's
+ * stable main-document identity; `rev` is a monotonic counter that advances
+ * whenever the skeleton is re-serialized after a DOM mutation. A `doc` change
+ * (a real navigation) invalidates every ref minted under it; a `rev` change is
+ * benign and only re-binds paging cursors.
+ */
+export interface ObservationEpochV2 {
+    doc: string;
+    rev: number;
+}
+export interface SafeObservationIndexV2 {
+    epoch: ObservationEpochV2;
+    stage: SafeStageV2;
+    semantics: SafePageSemanticsV2;
+    rows: SafeControlV2[];
+    byRef: Map<string, string>;
+    expiresAt: number;
+}
+/**
+ * The only V2 state retained between observations.  These rows have already
+ * crossed the allowlist seal: they contain generation-bound index refs and
+ * code-owned enums, never DOM values or arbitrary page copy.
+ */
+export interface SafeObservationBaselineV2 {
+    epoch: ObservationEpochV2;
+    stage: SafeStageV2;
+    semantics: SafePageSemanticsV2;
+    byRef: Map<string, SafeControlV2>;
+}
+/**
+ * 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 declare function equalSafePageSemanticsV2(left: SafePageSemanticsV2, right: SafePageSemanticsV2): boolean;
+/** `@e:` + a truncated session-secret HMAC of (document epoch, fingerprint). */
+export declare const COMPACT_V2_HANDLE_LENGTH = 10;
+export declare function isCompactV2Handle(target: string): boolean;
+/** The `@label` alias form, distinguishable from a handle by its `@e:` prefix. */
+export declare function isCompactV2Label(target: string): boolean;
+/**
+ * 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 declare function compactV2LegacyRefForHandle(handles: ReadonlyMap<string, string>, target: string): string | null;
+/**
+ * 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 declare function controlLabelV2(description: string | undefined): string | undefined;
+/**
+ * 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 declare function recordableTokenV2(value: string | null | undefined): string | undefined;
+/**
+ * Normalize and length-budget a page-derived description for the wire row. It
+ * rejects nothing: the truncation is the compactness budget, not redaction.
+ */
+export declare function safeDescriptionV2(value: string | null | undefined): string | undefined;
+export declare function safeOriginV2(value: string | null | undefined): string | null;
+export declare function compactV2AuditUrl(rawUrl: string): string;
+export declare function compactV2AuditHost(rawHost: string): string;
+export declare function compactV2AuditValue(key: string, value: unknown): unknown;
+export declare function sealRetainedInteractiveElementsV2(elements: readonly InteractiveElement[], selectorFor?: (element: InteractiveElement) => string): InteractiveElement[];
+export declare function safePageSemanticsV2(source: ObservationSemanticSourceV2): SafePageSemanticsV2;
+export interface SafeObservationDeltaV2 {
+    added: SafeControlV2[];
+    changed: SafeControlV2[];
+    removed: string[];
+    stageChanged: boolean;
+}
+/**
+ * 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 declare function diffSafeControlsV2(previous: SafeObservationBaselineV2, stage: SafeStageV2, rows: readonly SafeControlV2[]): SafeObservationDeltaV2;
+/**
+ * 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 declare function encodeV2Delta(args: {
+    sessionId: string;
+    stage: SafeStageV2;
+    /** Only the screened origin reaches the wire; paths and query strings stay private. */
+    pageUrl?: string;
+    semantics?: SafePageSemanticsV2 | undefined;
+    delta: SafeObservationDeltaV2;
+}): Record<string, unknown> | null;
+export declare function controlMatchesPrivateQueryV2(el: InteractiveElement, query: string): boolean;
+/** A code-owned page-stage enum; it never forwards the URL or page copy. */
+export declare function safeStageV2(url: string, elements: readonly InteractiveElement[]): SafeStageV2;
+export declare function checkoutStageFromUrlV2(url: string): "cart" | "checkout" | null;
+export declare function buildSafeControlsV2(args: {
+    elements: readonly InteractiveElement[];
+    legacyRefs: ReadonlyMap<InteractiveElement, string>;
+    /** Durable per-element handles, minted by the session (document-scoped). */
+    handles: ReadonlyMap<InteractiveElement, string>;
+    pageOrigin: string;
+    pageUrl?: string;
+}): {
+    rows: SafeControlV2[];
+    byRef: Map<string, string>;
+};
+export declare function encodeV2Page(args: {
+    sessionId: string;
+    stage: SafeStageV2;
+    /** The live page URL, path and query included — the agent needs to know where it is. */
+    pageUrl?: string;
+    semantics?: SafePageSemanticsV2;
+    rows: readonly SafeControlV2[];
+    cursorFor: (offset: number) => string;
+    offset?: number;
+    unchanged?: boolean;
+    startMetadata?: {
+        hint?: string;
+        userEmail?: string;
+        hintOverflow?: {
+            remaining: number;
+            next_cursor: string;
+        };
+    };
+}): {
+    payload: Record<string, unknown>;
+    nextOffset: number;
+};
+//# sourceMappingURL=compact-observation-v2.d.ts.map

package/dist/bot/compact-observation-v2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compact-observation-v2.d.ts","sourceRoot":"","sources":["../../src/bot/compact-observation-v2.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,eAAO,MAAM,yBAAyB,OAAQ,CAAC;AAC/C,eAAO,MAAM,qBAAqB,OAAQ,CAAC;AAG3C,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAGtE;AAED,MAAM,MAAM,UAAU,GAClB,QAAQ,GACR,MAAM,GACN,SAAS,GACT,QAAQ,GACR,UAAU,GACV,OAAO,GACP,KAAK,GACL,UAAU,GACV,MAAM,CAAC;AACX,MAAM,MAAM,YAAY,GACpB,QAAQ,GACR,OAAO,GACP,MAAM,GACN,UAAU,GACV,QAAQ,GACR,UAAU,GACV,OAAO,GACP,QAAQ,GACR,aAAa,GACb,WAAW,GACX,UAAU,GACV,SAAS,GACT,aAAa,CAAC;AAIlB,MAAM,MAAM,WAAW,GACnB,OAAO,GACP,UAAU,GACV,UAAU,GACV,MAAM,GACN,OAAO,GACP,QAAQ,GACR,SAAS,GACT,MAAM,GACN,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,MAAM,GACN,UAAU,GACV,OAAO,GACP,SAAS,CAAC;AACd,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,CAAC;AAExF,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,UAAU,GAAG,MAAM,CAAC;IAChC,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,GAAG,aAAa,GAAG,cAAc,CAAC;CAChD;AAED,8EAA8E;AAC9E,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,kBAAkB,CAAC;IAC1B,KAAK,EAAE,WAAW,CAAC;IACnB,SAAS,EAAE,mBAAmB,CAAC;IAC/B,IAAI,EAAE,aAAa,EAAE,CAAC;IACtB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,kBAAkB,CAAC;IAC1B,KAAK,EAAE,WAAW,CAAC;IACnB,SAAS,EAAE,mBAAmB,CAAC;IAC/B,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CACnC;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,mBAAmB,EACzB,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAET;AAED,gFAAgF;AAChF,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAI3C,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED,kFAAkF;AAClF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,MAAM,EAAE,MAAM,GACb,MAAM,GAAG,IAAI,CAGf;AAID;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CASlF;AA8ND;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAiBtF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAYtF;AAgED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAgB5E;AAMD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAI1D;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CA0BxE;AAED,wBAAgB,iCAAiC,CAC/C,QAAQ,EAAE,SAAS,kBAAkB,EAAE,EACvC,WAAW,GAAE,CAAC,OAAO,EAAE,kBAAkB,KAAK,MAAiB,GAC9D,kBAAkB,EAAE,CAiItB;AAED,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,2BAA2B,GAClC,mBAAmB,CAWrB;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,yBAAyB,EACnC,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,SAAS,aAAa,EAAE,GAC7B,sBAAsB,CAYxB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,WAAW,CAAC;IACnB,uFAAuF;IACvF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;IAC5C,KAAK,EAAE,sBAAsB,CAAC;CAC/B,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAkBjC;AAyFD,wBAAgB,4BAA4B,CAAC,EAAE,EAAE,kBAAkB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAkB3F;AAmHD,4EAA4E;AAC5E,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,kBAAkB,EAAE,GAAG,WAAW,CAuE7F;AAED,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,IAAI,CAsB9E;AAOD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACxC,UAAU,EAAE,WAAW,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC;IACpD,4EAA4E;IAC5E,OAAO,EAAE,WAAW,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG;IAAE,IAAI,EAAE,aAAa,EAAE,CAAC;IAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAuDxD;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,WAAW,CAAC;IACnB,wFAAwF;IACxF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAChC,IAAI,EAAE,SAAS,aAAa,EAAE,CAAC;IAC/B,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,aAAa,CAAC,EAAE;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,YAAY,CAAC,EAAE;YAAE,SAAS,EAAE,MAAM,CAAC;YAAC,WAAW,EAAE,MAAM,CAAA;SAAE,CAAC;KAC3D,CAAC;CACH,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAwF3D"}