@oxvo/ai-live-assist 7.3.4 → 7.4.23

package/lib/client.d.ts

@@ -1,4 +1,4 @@
-import type { AssistMode, BootstrapConfig, ConsentScope, LaunchResult, ExperienceMode } from './types.js';
+import type { AssistMode, AiGuideCompanionState, BootstrapConfig, ConsentScope, HandoffRecoveryResult, LaunchResult, ExperienceMode, MessengerConversationState } from "./types.js";
 export declare class RuntimeClientError extends Error {
     readonly code: string;
     readonly retryable: boolean;
@@ -6,17 +6,22 @@ export declare class RuntimeClientError extends Error {
     readonly status: number;
     constructor(code: string, message: string, retryable: boolean, retryAfterMs: number | null, status: number);
 }
-type LaunchInput = {
+export declare const MAX_ASSIST_SESSION_GRANT_LENGTH = 4096;
+export declare const isValidReplaySessionId: (value: unknown) => value is string;
+export declare const isValidAssistSessionGrant: (value: unknown) => value is string;
+export type ReplayLaunchContext = {
+    sessionId: string;
+    tabId: string;
+    grant: string;
+};
+export type LaunchInput = {
     siteKey: string;
     configRevision: number;
     path: string;
     tabId: string;
     mode: AssistMode;
     anonymousId: string;
-    replay?: {
-        sessionId: string;
-        tabId: string;
-    };
+    replay: ReplayLaunchContext;
     disclosureChecksum: string;
     scopes: ConsentScope[];
     locale: string;
@@ -26,6 +31,55 @@ type LaunchInput = {
     experienceMode: ExperienceMode;
     fallbackIntent?: "standard_assist" | "human_handoff";
     lowPower: boolean;
+    idempotencyKey: string;
+};
+export type ModeUpgradeResumeInput = {
+    sessionId: string;
+    resumeCredential: string;
+    path: string;
+    protocolVersion: 1 | 2;
+    requestId: string;
+    idempotencyKey: string;
+};
+export type ModeUpgradeRecoveryResult = {
+    schemaVersion: 1;
+    status: "voice_committed";
+    resume: LaunchResult;
+} | {
+    schemaVersion: 1;
+    status: "terminalized";
+    sessionId: string;
+    state: "ended" | "failed" | "revoked";
+};
+export type RuntimeSessionState = "created" | "authorizing" | "connecting" | "active_text" | "active_voice" | "paused" | "reconnecting" | "handoff_pending" | "human_controlled" | "ending" | "ended" | "failed" | "revoked";
+export type PauseCommandIdentity = {
+    operationId: string;
+    clientSequence: number;
+};
+export type PauseCommandResult = {
+    schemaVersion: 1;
+    operationId: string;
+    clientSequence: number;
+    fencingToken: number;
+    action: "pause" | "resume";
+    status: "applied" | "replayed" | "superseded";
+    state: RuntimeSessionState;
+};
+export type CompanionSurfaceSwitchInput = {
+    linkId: string;
+    switchGrant: string;
+    visitorId: string;
+    expectedOwnerEpoch: number;
+    targetSurface: "ai" | "messenger";
+    lastAiMode: AssistMode;
+    currentAiSessionId?: string;
+    idempotencyKey: string;
+};
+export type CompanionSurfaceSwitchResult = {
+    schemaVersion: 1;
+    status: "switched" | "replayed" | "stale";
+    companion: AiGuideCompanionState;
+    messengerConversation: MessengerConversationState;
 };
 export declare const idempotencyKey: (prefix: string) => string;
 export declare class RuntimeClient {
@@ -35,19 +89,26 @@ export declare class RuntimeClient {
     bootstrap(siteKey: string, path: string, anonymousId: string, signal: AbortSignal): Promise<BootstrapConfig>;
     launch(input: LaunchInput, signal: AbortSignal): Promise<LaunchResult>;
     resume(sessionId: string, credential: string, path: string, protocolVersion: 1 | 2, signal: AbortSignal): Promise<LaunchResult>;
-    offer(result: LaunchResult, offerSdp: string, signal: AbortSignal): Promise<{
+    resumePendingHandoff(sessionId: string, credential: string, path: string, protocolVersion: 1 | 2, messengerBindingChallengeId: string, signal: AbortSignal): Promise<HandoffRecoveryResult>;
+    resumeModeUpgrade(input: ModeUpgradeResumeInput, signal: AbortSignal): Promise<LaunchResult>;
+    reconcileModeUpgrade(input: ModeUpgradeResumeInput, signal?: AbortSignal, keepalive?: boolean): Promise<ModeUpgradeRecoveryResult>;
+    offer(result: LaunchResult, offerSdp: string, signal: AbortSignal, offerIdempotencyKey?: string): Promise<{
         answerSdp: string;
         fencingToken: number;
+        sessionState: "active_text" | "active_voice" | null;
     }>;
     end(result: LaunchResult, fencingToken: number, signal?: AbortSignal): Promise<void>;
-    pauseOrResume(result: LaunchResult, fencingToken: number, operation: 'pause' | 'resume', signal?: AbortSignal): Promise<void>;
+    recoverAndEnd(sessionId: string, resumeCredential: string, protocolVersion: 1 | 2, signal?: AbortSignal): Promise<void>;
+    pauseOrResume(result: LaunchResult, fencingToken: number, operation: "pause" | "resume", identity: PauseCommandIdentity, signal?: AbortSignal): Promise<PauseCommandResult>;
+    switchCompanionSurface(input: CompanionSurfaceSwitchInput, signal?: AbortSignal): Promise<CompanionSurfaceSwitchResult>;
     feedback(result: LaunchResult, payload: {
         rating: number | null;
-        outcome: 'resolved' | 'partially_resolved' | 'not_resolved' | 'handoff';
+        outcome: "resolved" | "partially_resolved" | "not_resolved" | "handoff";
     }, signal?: AbortSignal): Promise<void>;
     private postEmpty;
+    private parseCompanionState;
+    private parseMessengerConversation;
     private postJson;
     private parseJson;
     private throwResponse;
 }
-export {};

package/lib/client.js

@@ -5,40 +5,90 @@ export class RuntimeClientError extends Error {
         this.retryable = retryable;
         this.retryAfterMs = retryAfterMs;
         this.status = status;
-        this.name = 'RuntimeClientError';
+        this.name = "RuntimeClientError";
     }
 }
+const MAX_SIGNED_INT64 = "9223372036854775807";
+const CONTROL_OPERATION_ID_PATTERN = /^[A-Za-z0-9_.:-]{8,128}$/;
+export const MAX_ASSIST_SESSION_GRANT_LENGTH = 4096;
+export const isValidReplaySessionId = (value) => {
+    if (typeof value !== "string" || !/^[1-9]\d{0,18}$/.test(value)) {
+        return false;
+    }
+    return value.length < MAX_SIGNED_INT64.length || value <= MAX_SIGNED_INT64;
+};
+export const isValidAssistSessionGrant = (value) => typeof value === "string" &&
+    value.length > 0 &&
+    value.length <= MAX_ASSIST_SESSION_GRANT_LENGTH &&
+    value.trim() === value;
+const RUNTIME_SESSION_STATES = new Set([
+    "created",
+    "authorizing",
+    "connecting",
+    "active_text",
+    "active_voice",
+    "paused",
+    "reconnecting",
+    "handoff_pending",
+    "human_controlled",
+    "ending",
+    "ended",
+    "failed",
+    "revoked",
+]);
 const requestId = () => `req_${crypto.randomUUID()}`;
 export const idempotencyKey = (prefix) => `${prefix}_${crypto.randomUUID()}`;
 export class RuntimeClient {
     constructor(runtimeUrl, clientVersion) {
         this.clientVersion = clientVersion;
         const url = new URL(runtimeUrl, window.location.href);
-        if (!['http:', 'https:'].includes(url.protocol)) {
-            throw new Error('AI Guide runtime URL must use HTTP or HTTPS.');
+        if (!["http:", "https:"].includes(url.protocol)) {
+            throw new Error("AI Guide runtime URL must use HTTP or HTTPS.");
         }
-        this.baseUrl = url.origin + url.pathname.replace(/\/$/, '');
+        this.baseUrl = url.origin + url.pathname.replace(/\/$/, "");
     }
     async bootstrap(siteKey, path, anonymousId, signal) {
         const url = new URL(`${this.baseUrl}/ai-live-assist/v1/public/bootstrap`);
-        url.searchParams.set('siteKey', siteKey);
-        url.searchParams.set('path', path);
+        url.searchParams.set("siteKey", siteKey);
+        url.searchParams.set("path", path);
         const response = await fetch(url, {
-            method: 'GET',
-            mode: 'cors',
-            credentials: 'omit',
-            cache: 'no-store',
+            method: "GET",
+            mode: "cors",
+            credentials: "omit",
+            cache: "no-store",
             headers: {
-                Accept: 'application/json',
-                'X-Oxvo-Ai-Client-Version': this.clientVersion,
-                'X-Oxvo-Ai-Visitor-Id': anonymousId,
-                'X-Request-Id': requestId(),
+                Accept: "application/json",
+                "X-Oxvo-Ai-Client-Version": this.clientVersion,
+                "X-Oxvo-Ai-Visitor-Id": anonymousId,
+                "X-Request-Id": requestId(),
             },
             signal,
         });
         return this.parseJson(response);
     }
     async launch(input, signal) {
+        if (!/^[A-Za-z0-9_.:-]{8,128}$/.test(input.idempotencyKey)) {
+            throw new Error("Invalid AI Guide launch idempotency key.");
+        }
+        const replaySessionId = input.replay?.sessionId;
+        const replayTabId = input.replay?.tabId;
+        const replayGrant = input.replay?.grant;
+        if (!isValidReplaySessionId(replaySessionId)) {
+            throw new Error("Invalid AI Guide replay session ID.");
+        }
+        if (typeof replayTabId !== "string" ||
+            replayTabId !== input.tabId ||
+            !/^[A-Za-z0-9_.:-]{1,128}$/.test(replayTabId)) {
+            throw new Error("Invalid AI Guide replay tab ID.");
+        }
+        if (!isValidAssistSessionGrant(replayGrant)) {
+            throw new Error("Invalid AI Guide replay grant.");
+        }
+        const replay = {
+            sessionId: replaySessionId,
+            tabId: replayTabId,
+            grant: replayGrant,
+        };
         const shared = {
             clientVersion: this.clientVersion,
             siteKey: input.siteKey,
@@ -47,7 +97,7 @@ export class RuntimeClient {
             tabId: input.tabId,
             mode: input.mode,
             visitor: { anonymousId: input.anonymousId },
-            ...(input.replay ? { replay: input.replay } : {}),
+            replay,
             consent: {
                 disclosureChecksum: input.disclosureChecksum,
                 scopes: input.scopes,
@@ -65,13 +115,12 @@ export class RuntimeClient {
                 ...shared,
                 capabilitySummary: {
                     microphone: input.microphone,
-                    webrtc: typeof RTCPeerConnection !== 'undefined',
-                    audioPlayback: typeof HTMLAudioElement !== 'undefined',
-                    webAudio: typeof AudioContext !== 'undefined' ||
-                        typeof window
-                            .webkitAudioContext !== 'undefined',
-                    svgOverlay: typeof SVGElement !== 'undefined',
-                    visualViewport: typeof window.visualViewport !== 'undefined',
+                    webrtc: typeof RTCPeerConnection !== "undefined",
+                    audioPlayback: typeof HTMLAudioElement !== "undefined",
+                    webAudio: typeof AudioContext !== "undefined" ||
+                        typeof window.webkitAudioContext !== "undefined",
+                    svgOverlay: typeof SVGElement !== "undefined",
+                    visualViewport: typeof window.visualViewport !== "undefined",
                     reducedMotion: input.reducedMotion,
                     lowPower: input.lowPower,
                 },
@@ -82,83 +131,290 @@ export class RuntimeClient {
                 ...shared,
                 capabilitySummary: {
                     microphone: input.microphone,
-                    webrtc: typeof RTCPeerConnection !== 'undefined',
+                    webrtc: typeof RTCPeerConnection !== "undefined",
                     reducedMotion: input.reducedMotion,
                 },
             };
-        return this.postJson('/ai-live-assist/v1/public/launch', body, {
-            'Idempotency-Key': idempotencyKey('launch'),
+        return this.postJson("/ai-live-assist/v1/public/launch", body, {
+            "Idempotency-Key": input.idempotencyKey,
         }, signal);
     }
     async resume(sessionId, credential, path, protocolVersion, signal) {
-        return this.postJson(`/ai-live-assist/v1/public/sessions/${encodeURIComponent(sessionId)}/resume`, {
+        const request = this.postJson(`/ai-live-assist/v1/public/sessions/${encodeURIComponent(sessionId)}/resume`, {
             schemaVersion: protocolVersion,
             protocolVersion,
             path,
-            reason: 'navigation',
+            reason: "navigation",
         }, { Authorization: `Bearer ${credential}` }, signal);
+        try {
+            return await request;
+        }
+        catch (error) {
+            if (error instanceof TypeError) {
+                throw new RuntimeClientError("RUNTIME_UNAVAILABLE", "AI Guide is temporarily unavailable.", true, null, 0);
+            }
+            throw error;
+        }
+    }
+    async resumePendingHandoff(sessionId, credential, path, protocolVersion, messengerBindingChallengeId, signal) {
+        if (!/^[A-Za-z0-9_.:-]{8,128}$/.test(messengerBindingChallengeId)) {
+            throw new Error("Invalid Messenger handoff recovery identity.");
+        }
+        try {
+            return await this.postJson(`/ai-live-assist/v1/public/sessions/${encodeURIComponent(sessionId)}/resume`, {
+                schemaVersion: protocolVersion,
+                protocolVersion,
+                path,
+                reason: "handoff_recovery",
+                messengerBindingChallengeId,
+            }, { Authorization: `Bearer ${credential}` }, signal);
+        }
+        catch (error) {
+            if (error instanceof TypeError) {
+                throw new RuntimeClientError("RUNTIME_UNAVAILABLE", "AI Guide is temporarily unavailable.", true, null, 0);
+            }
+            throw error;
+        }
+    }
+    async resumeModeUpgrade(input, signal) {
+        if (!/^[A-Za-z0-9_.:-]{8,128}$/.test(input.requestId) ||
+            !/^[A-Za-z0-9_.:-]{8,128}$/.test(input.idempotencyKey)) {
+            throw new Error("Invalid AI Guide mode-upgrade identity.");
+        }
+        return this.postJson(`/ai-live-assist/v1/public/sessions/${encodeURIComponent(input.sessionId)}/resume`, {
+            schemaVersion: input.protocolVersion,
+            protocolVersion: input.protocolVersion,
+            path: input.path,
+            reason: "mode_upgrade",
+            modeUpgradeRequestId: input.requestId,
+        }, {
+            Authorization: `Bearer ${input.resumeCredential}`,
+            "Idempotency-Key": input.idempotencyKey,
+        }, signal);
+    }
+    async reconcileModeUpgrade(input, signal, keepalive = false) {
+        if (!/^[A-Za-z0-9_.:-]{8,128}$/.test(input.requestId) ||
+            !/^[A-Za-z0-9_.:-]{8,128}$/.test(input.idempotencyKey)) {
+            throw new Error("Invalid AI Guide mode-upgrade recovery identity.");
+        }
+        return this.postJson(`/ai-live-assist/v1/public/sessions/${encodeURIComponent(input.sessionId)}/mode-upgrade/reconcile`, {
+            schemaVersion: input.protocolVersion,
+            protocolVersion: input.protocolVersion,
+            path: input.path,
+            modeUpgradeRequestId: input.requestId,
+        }, {
+            Authorization: `Bearer ${input.resumeCredential}`,
+            "Idempotency-Key": input.idempotencyKey,
+        }, signal, keepalive);
     }
-    async offer(result, offerSdp, signal) {
+    async offer(result, offerSdp, signal, offerIdempotencyKey = idempotencyKey("offer")) {
+        if (!/^[A-Za-z0-9_.:-]{8,128}$/.test(offerIdempotencyKey)) {
+            throw new Error("Invalid AI Guide realtime-offer idempotency key.");
+        }
         const response = await fetch(result.realtimeOfferUrl, {
-            method: 'POST',
-            mode: 'cors',
-            credentials: 'omit',
-            cache: 'no-store',
+            method: "POST",
+            mode: "cors",
+            credentials: "omit",
+            cache: "no-store",
             headers: {
-                Accept: 'application/sdp',
+                Accept: "application/sdp",
                 Authorization: `Bearer ${result.launchCredential}`,
-                'Content-Type': 'application/sdp',
-                'Idempotency-Key': idempotencyKey('offer'),
-                'X-Oxvo-Ai-Client-Version': this.clientVersion,
-                'X-Request-Id': requestId(),
+                "Content-Type": "application/sdp",
+                "Idempotency-Key": offerIdempotencyKey,
+                "X-Oxvo-Ai-Client-Version": this.clientVersion,
+                "X-Request-Id": requestId(),
             },
             body: offerSdp,
             signal,
         });
         if (!response.ok)
             await this.throwResponse(response);
-        const fencingToken = Number(response.headers.get('X-Oxvo-Fencing-Token'));
+        const fencingToken = Number(response.headers.get("X-Oxvo-Fencing-Token"));
         if (!Number.isSafeInteger(fencingToken) || fencingToken < 1) {
-            throw new RuntimeClientError('PROTOCOL_INVALID', 'The runtime returned an invalid control lease.', false, null, 502);
+            throw new RuntimeClientError("PROTOCOL_INVALID", "The runtime returned an invalid control lease.", false, null, 502);
         }
-        return { answerSdp: await response.text(), fencingToken };
+        const sessionStateHeader = response.headers.get("X-Oxvo-Session-State");
+        const sessionState = sessionStateHeader === "active_text" ||
+            sessionStateHeader === "active_voice"
+            ? sessionStateHeader
+            : null;
+        return {
+            answerSdp: await response.text(),
+            fencingToken,
+            sessionState,
+        };
     }
     async end(result, fencingToken, signal) {
-        await this.postEmpty(`/ai-live-assist/v1/public/sessions/${encodeURIComponent(result.sessionId)}/end`, result.controlCredential, fencingToken, result.protocolVersion, signal);
+        await this.postEmpty(`/ai-live-assist/v1/public/sessions/${encodeURIComponent(result.sessionId)}/end`, result.controlCredential, fencingToken, result.protocolVersion, signal, true);
+    }
+    async recoverAndEnd(sessionId, resumeCredential, protocolVersion, signal) {
+        await this.postJson(`/ai-live-assist/v1/public/sessions/${encodeURIComponent(sessionId)}/end`, {
+            schemaVersion: protocolVersion,
+            protocolVersion,
+            fencingToken: 0,
+            terminalRecovery: true,
+        }, { Authorization: `Bearer ${resumeCredential}` }, signal, true, true);
     }
-    async pauseOrResume(result, fencingToken, operation, signal) {
-        await this.postEmpty(`/ai-live-assist/v1/public/sessions/${encodeURIComponent(result.sessionId)}/${operation}`, result.controlCredential, fencingToken, result.protocolVersion, signal);
+    async pauseOrResume(result, fencingToken, operation, identity, signal) {
+        if (!CONTROL_OPERATION_ID_PATTERN.test(identity.operationId) ||
+            !Number.isSafeInteger(identity.clientSequence) ||
+            identity.clientSequence < 1) {
+            throw new Error("Invalid AI Guide pause command identity.");
+        }
+        const response = await this.postJson(`/ai-live-assist/v1/public/sessions/${encodeURIComponent(result.sessionId)}/actions/${operation}`, {
+            schemaVersion: result.protocolVersion,
+            protocolVersion: result.protocolVersion,
+            fencingToken,
+            operationId: identity.operationId,
+            clientSequence: identity.clientSequence,
+        }, { Authorization: `Bearer ${result.controlCredential}` }, signal);
+        if (!response ||
+            typeof response !== "object" ||
+            response.schemaVersion !== 1 ||
+            response.operationId !== identity.operationId ||
+            response.clientSequence !== identity.clientSequence ||
+            response.fencingToken !== fencingToken ||
+            response.action !== operation ||
+            !["applied", "replayed", "superseded"].includes(response.status) ||
+            !RUNTIME_SESSION_STATES.has(response.state)) {
+            throw new RuntimeClientError("PROTOCOL_INVALID", "The runtime returned an invalid pause command result.", false, null, 502);
+        }
+        return response;
+    }
+    async switchCompanionSurface(input, signal) {
+        if (!CONTROL_OPERATION_ID_PATTERN.test(input.linkId) ||
+            !isValidAssistSessionGrant(input.switchGrant) ||
+            !CONTROL_OPERATION_ID_PATTERN.test(input.visitorId) ||
+            !Number.isSafeInteger(input.expectedOwnerEpoch) ||
+            input.expectedOwnerEpoch < 0 ||
+            !["ai", "messenger"].includes(input.targetSurface) ||
+            !["text", "voice"].includes(input.lastAiMode) ||
+            !CONTROL_OPERATION_ID_PATTERN.test(input.idempotencyKey) ||
+            (input.currentAiSessionId !== undefined &&
+                !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(input.currentAiSessionId))) {
+            throw new Error("Invalid AI Guide companion switch request.");
+        }
+        const response = await this.postJson(`/ai-live-assist/v1/public/companion-links/${encodeURIComponent(input.linkId)}/surface`, {
+            schemaVersion: 1,
+            expectedOwnerEpoch: input.expectedOwnerEpoch,
+            targetSurface: input.targetSurface,
+            lastAiMode: input.lastAiMode,
+            ...(input.currentAiSessionId
+                ? { currentAiSessionId: input.currentAiSessionId }
+                : {}),
+            idempotencyKey: input.idempotencyKey,
+        }, {
+            Authorization: `Bearer ${input.switchGrant}`,
+            "X-Oxvo-Ai-Visitor-Id": input.visitorId,
+        }, signal);
+        const companion = this.parseCompanionState(response.companion, response.switchGrant);
+        const messengerConversation = this.parseMessengerConversation(response.messengerConversation);
+        if (response.schemaVersion !== 1 ||
+            (response.status !== "switched" &&
+                response.status !== "replayed" &&
+                response.status !== "stale") ||
+            !companion ||
+            !messengerConversation ||
+            companion.linkId !== input.linkId) {
+            throw new RuntimeClientError("PROTOCOL_INVALID", "The runtime returned an invalid companion switch result.", false, null, 502);
+        }
+        return {
+            schemaVersion: 1,
+            status: response.status,
+            companion,
+            messengerConversation,
+        };
     }
     async feedback(result, payload, signal) {
         await this.postJson(`/ai-live-assist/v1/public/sessions/${encodeURIComponent(result.sessionId)}/feedback`, payload, {
             Authorization: `Bearer ${result.feedbackCredential}`,
         }, signal);
     }
-    async postEmpty(path, credential, fencingToken, protocolVersion, signal) {
+    async postEmpty(path, credential, fencingToken, protocolVersion, signal, keepalive = false) {
         await this.postJson(path, {
             schemaVersion: protocolVersion,
             protocolVersion,
             fencingToken,
-        }, { Authorization: `Bearer ${credential}` }, signal);
+        }, { Authorization: `Bearer ${credential}` }, signal, keepalive);
+    }
+    parseCompanionState(value, switchGrant) {
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+            return null;
+        }
+        const candidate = value;
+        const currentAiSessionId = candidate.currentAiSessionId;
+        const expiresAt = typeof candidate.expiresAt === "string"
+            ? Date.parse(candidate.expiresAt)
+            : Number.NaN;
+        if (candidate.schemaVersion !== 1 ||
+            typeof candidate.linkId !== "string" ||
+            !CONTROL_OPERATION_ID_PATTERN.test(candidate.linkId) ||
+            (candidate.activeSurface !== "ai" &&
+                candidate.activeSurface !== "messenger") ||
+            (candidate.lastAiMode !== "text" && candidate.lastAiMode !== "voice") ||
+            !Number.isSafeInteger(candidate.ownerEpoch) ||
+            candidate.ownerEpoch < 0 ||
+            (currentAiSessionId !== null &&
+                (typeof currentAiSessionId !== "string" ||
+                    !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(currentAiSessionId))) ||
+            !Number.isFinite(expiresAt) ||
+            expiresAt <= Date.now() ||
+            !isValidAssistSessionGrant(switchGrant)) {
+            return null;
+        }
+        return {
+            schemaVersion: 1,
+            linkId: candidate.linkId,
+            activeSurface: candidate.activeSurface,
+            lastAiMode: candidate.lastAiMode,
+            ownerEpoch: candidate.ownerEpoch,
+            currentAiSessionId: currentAiSessionId,
+            expiresAt: candidate.expiresAt,
+            switchGrant,
+        };
     }
-    async postJson(path, body, extraHeaders, signal) {
+    parseMessengerConversation(value) {
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+            return null;
+        }
+        const candidate = value;
+        if (candidate.state !== "connected" ||
+            typeof candidate.conversationDisplayId !== "string" ||
+            !/^[1-9]\d{0,18}$/.test(candidate.conversationDisplayId) ||
+            typeof candidate.inboxId !== "string" ||
+            !/^[1-9]\d{0,18}$/.test(candidate.inboxId)) {
+            return null;
+        }
+        return {
+            state: "connected",
+            conversationDisplayId: candidate.conversationDisplayId,
+            inboxId: candidate.inboxId,
+        };
+    }
+    async postJson(path, body, extraHeaders, signal, keepalive = false, requireNoContent = false) {
         const response = await fetch(`${this.baseUrl}${path}`, {
-            method: 'POST',
-            mode: 'cors',
-            credentials: 'omit',
-            cache: 'no-store',
+            method: "POST",
+            mode: "cors",
+            credentials: "omit",
+            cache: "no-store",
             headers: {
-                Accept: 'application/json',
-                'Content-Type': 'application/json',
-                'X-Oxvo-Ai-Client-Version': this.clientVersion,
-                'X-Request-Id': requestId(),
+                Accept: "application/json",
+                "Content-Type": "application/json",
+                "X-Oxvo-Ai-Client-Version": this.clientVersion,
+                "X-Request-Id": requestId(),
                 ...extraHeaders,
             },
             body: JSON.stringify(body),
+            ...(keepalive ? { keepalive: true } : {}),
             ...(signal ? { signal } : {}),
         });
         if (response.status === 204)
             return undefined;
+        if (requireNoContent) {
+            if (!response.ok)
+                await this.throwResponse(response);
+            throw new RuntimeClientError("PROTOCOL_INVALID", "The runtime returned an invalid terminal response.", false, null, 502);
+        }
         return this.parseJson(response);
     }
     async parseJson(response) {
@@ -168,7 +424,7 @@ export class RuntimeClient {
             return (await response.json());
         }
         catch {
-            throw new RuntimeClientError('PROTOCOL_INVALID', 'The runtime returned an invalid response.', false, null, response.status);
+            throw new RuntimeClientError("PROTOCOL_INVALID", "The runtime returned an invalid response.", false, null, response.status);
         }
     }
     async throwResponse(response) {
@@ -180,8 +436,8 @@ export class RuntimeClient {
         catch {
             // Keep the public fallback generic; response bodies may come from a proxy.
         }
-        throw new RuntimeClientError(typeof error.code === 'string' ? error.code : 'RUNTIME_UNAVAILABLE', typeof error.message === 'string'
+        throw new RuntimeClientError(typeof error.code === "string" ? error.code : "RUNTIME_UNAVAILABLE", typeof error.message === "string"
             ? error.message
-            : 'AI Guide is temporarily unavailable.', error.retryable === true, typeof error.retryAfterMs === 'number' ? error.retryAfterMs : null, response.status);
+            : "AI Guide is temporarily unavailable.", error.retryable === true, typeof error.retryAfterMs === "number" ? error.retryAfterMs : null, response.status);
     }
 }

package/lib/context.d.ts

@@ -1,17 +1,22 @@
-import type { ActionExecutionResult, ActionGrant, PageContextSnapshot, PresentationTarget, VisualContextCapture } from './types.js';
+import type { ActionExecutionResult, ActionGrant, PageContextSnapshot, SanitizedTarget, PresentationTarget, VisualContextCapture } from './types.js';
+export declare const actionTargetFingerprint: (target: SanitizedTarget, subtle?: Pick<SubtleCrypto, "digest"> | undefined) => Promise<string | null>;
 type SelectorRegionRule = {
     digest: string;
     selector: string;
 };
 type ContextCallbacks = {
     onSnapshot: (snapshot: PageContextSnapshot) => void | Promise<void>;
-    onNavigation: (pageId: string, revision: number, url: string) => void | Promise<void>;
+    onActionMutationApplied?: (actionId: string, revision: number, url: string) => void;
+    onCausalNavigationObserved?: (pageId: string, revision: number, url: string, causalActionId: string) => void;
+    onNavigation: (pageId: string, revision: number, url: string, causalActionId?: string) => boolean | void | Promise<boolean | void>;
     onHighlight: (element: Element | null, status: 'focus' | 'success' | 'failure') => void;
 };
 export declare class PageContextCollector {
     private readonly callbacks;
     private readonly selectorRegionRules;
     private readonly policyVersion;
+    private readonly trustedGuideRoot;
+    private readonly statefulButtonActionProof;
     private pageId;
     private revision;
     private running;
@@ -28,19 +33,21 @@ export declare class PageContextCollector {
     private pendingNavigation;
     private pendingCapture;
     private deferredNavigation;
+    private navigationSettlementGeneration;
+    private navigationSettlement;
     private recentSelection;
     private latestSemanticSignature;
-    constructor(callbacks: ContextCallbacks, selectorRegionRules?: SelectorRegionRule[], policyVersion?: number);
+    constructor(callbacks: ContextCallbacks, selectorRegionRules?: SelectorRegionRule[], policyVersion?: number, trustedGuideRoot?: Element | null, statefulButtonActionProof?: boolean);
     get currentRevision(): number;
     get currentPageId(): string;
     presentationTarget(targetId: string, revision: number): PresentationTarget | null;
     start(): void;
     stop(): void;
-    captureAndPublish(): Promise<PageContextSnapshot>;
+    captureAndPublish(): Promise<PageContextSnapshot | null>;
     capture(): PageContextSnapshot;
     private captureSnapshot;
     captureVisualContext(): VisualContextCapture | null;
-    execute(grant: ActionGrant): Promise<ActionExecutionResult>;
+    execute(grant: ActionGrant, authorityIsCurrent?: () => boolean): Promise<ActionExecutionResult>;
     completeActionExecution(actionId: string): Promise<string | null>;
     private click;
     private type;
@@ -59,6 +66,9 @@ export declare class PageContextCollector {
     private handleControlStateChange;
     private readSafeSelection;
     private handleNavigation;
+    private beginNavigationSettlement;
+    private observeCausalNavigationAfterMutation;
+    private reportCausalNavigationObservation;
     private installNavigationHooks;
     private restoreNavigationHooks;
     private reducedMotion;