@agent-native/core 0.214.0 → 0.217.0

package/dist/client/analytics-session.d.ts

@@ -1,5 +1,12 @@
 /** One id for this page load, shared by every pageview until it reloads. */
 export declare function getAnalyticsPageLoadId(): string;
+/**
+ * The visitor id, `an_aid`, waits for analytics consent where the banner
+ * applies, and for the server's region rather than the time zone's guess,
+ * since a sent id can't be recalled. Until then this returns `undefined` and
+ * stores nothing, so events still count but can't be tied to one visitor
+ * across pages.
+ */
 export declare function getOrCreateAnalyticsAnonymousId(): string | undefined;
 export declare function setAnalyticsSessionId(sessionId: string): string | undefined;
 export declare function clearAnalyticsSessionId(): void;

package/dist/client/analytics-session.js

@@ -1,5 +1,6 @@
-import { serializeAnalyticsAnonymousIdCookie } from "../shared/analytics-anonymous-id.js";
+import { ANALYTICS_ANONYMOUS_ID_COOKIE_NAME, serializeAnalyticsAnonymousIdCookie, } from "../shared/analytics-anonymous-id.js";
 import { ANALYTICS_SESSION_ID_COOKIE_NAME, ANALYTICS_SESSION_ID_MAX_LENGTH, normalizeAnalyticsSessionId, serializeAnalyticsSessionIdCookie, } from "../shared/analytics-session-id.js";
+import { consentDecision, whenConsentAllows } from "./consent.js";
 const ANONYMOUS_ID_STORAGE_KEY = "agent-native.anonymous_id";
 const SESSION_ID_STORAGE_KEY = "agent-native.session_id";
 const SESSION_ID_PIN_STORAGE_KEY = "agent-native.session_id_pin";
@@ -72,9 +73,34 @@ export function getAnalyticsPageLoadId() {
     pageLoadId ??= generateVisitorId();
     return pageLoadId;
 }
+let anonymousIdConsentWatched = false;
+function clearAnalyticsAnonymousId() {
+    safeStorageRemove(ANONYMOUS_ID_STORAGE_KEY);
+    try {
+        document.cookie = `${ANALYTICS_ANONYMOUS_ID_COOKIE_NAME}=; path=/; max-age=0; SameSite=Lax`;
+    }
+    catch {
+        // coercion-ok: a frame that can't read cookies never stored one.
+    }
+}
+/**
+ * The visitor id, `an_aid`, waits for analytics consent where the banner
+ * applies, and for the server's region rather than the time zone's guess,
+ * since a sent id can't be recalled. Until then this returns `undefined` and
+ * stores nothing, so events still count but can't be tied to one visitor
+ * across pages.
+ */
 export function getOrCreateAnalyticsAnonymousId() {
     if (typeof window === "undefined")
         return undefined;
+    if (!anonymousIdConsentWatched) {
+        anonymousIdConsentWatched = true;
+        whenConsentAllows("performance", () => { }, {
+            revoke: clearAnalyticsAnonymousId,
+        });
+    }
+    if (consentDecision("performance") !== true)
+        return undefined;
     let id = safeStorageGet(ANONYMOUS_ID_STORAGE_KEY);
     if (!id) {
         id = generateVisitorId();

package/dist/client/analytics.js

@@ -4,6 +4,7 @@ import { ANALYTICS_CLIENT_PLATFORM_PROPERTY, } from "../shared/analytics-platfor
 import { hasAttributionSource, } from "../shared/attribution-source.js";
 import { resolveLaneEndpoint } from "../shared/environment-lanes.js";
 import { classifyErrorNoise, } from "../shared/error-noise.js";
+import { FIRST_TOUCH_SERVER_COOKIE_NAME, FIRST_TOUCH_SERVER_COOKIE_VERSION, FIRST_TOUCH_SERVER_PATH, firstTouchServerExpiry, isSameFirstTouch, preferFirstTouch, } from "../shared/first-touch-persistence.js";
 import { llmConnectionTrackingProperties, } from "../shared/llm-connection.js";
 import { loadOptionalPeer } from "../shared/optional-peer.js";
 import { isTestIdentityEmail } from "../shared/qa-test-email.js";
@@ -11,8 +12,11 @@ import { isSyntheticTrafficValue } from "../shared/test-traffic.js";
 import { toPostHogExceptionProperties } from "../tracking/posthog-exception.js";
 import { getAnalyticsClientPlatform } from "./analytics-platform.js";
 import { getAnalyticsPageLoadId, getOrCreateAnalyticsAnonymousId, getOrCreateAnalyticsSessionId, } from "./analytics-session.js";
+import { agentNativePath } from "./api-path.js";
+import { agentNativeApiDisabledReason } from "./api-surface.js";
 import { injectedAgentNativeConfig } from "./app-config.js";
 import { clientBuildId } from "./build-compatibility.js";
+import { consentAllowsNow, consentDecision, getConsentChoice, whenConsentAllows, whenConsentDecided, } from "./consent.js";
 import { clientFailureContext } from "./failure-report.js";
 import { replayEndpointFromAnalyticsEndpoint } from "./session-replay-endpoint.js";
 import { scheduleAfterPaint } from "./use-after-paint.js";
@@ -35,6 +39,7 @@ let _amplitudeModule = null;
 let _amplitudeLoadPromise = null;
 let _amplitudeApiKey = null;
 let _pendingAmplitudeEvents = [];
+let _amplitudeConsent = "unasked";
 let _sentryInitialized = false;
 let _sentryModule = null;
 let _sentryLoadPromise = null;
@@ -174,6 +179,11 @@ const LAST_TOUCH_COOKIE = {
     priority: LAST_TOUCH_COOKIE_FIELD_PRIORITY,
 };
 let _firstTouchCaptured = false;
+// Bounds the resend after a response race; see `syncFirstTouchToServer`.
+let _firstTouchSyncsLeft = 2;
+// Set when this page wrote `an_ft` or `an_lt`, which the server then writes
+// again: Safari keeps a cookie page JavaScript wrote for seven days at most.
+let _attributionCookieWritten = false;
 function safeStorageGet(key) {
     try {
         return window.localStorage.getItem(key);
@@ -190,6 +200,14 @@ function safeStorageSet(key, value) {
         // private browsing / storage disabled — best-effort
     }
 }
+function safeStorageRemove(key) {
+    try {
+        window.localStorage.removeItem(key);
+    }
+    catch {
+        // coercion-ok: storage that can't be read holds nothing to remove.
+    }
+}
 function readCachedLlmConnectionStatus() {
     if (typeof window === "undefined")
         return null;
@@ -536,6 +554,7 @@ function writeAttributionCookie(value, spec) {
     const encodedValue = fitAttributionCookieValue(value, spec);
     try {
         document.cookie = attributionCookieAssignment(spec.name, encodedValue);
+        _attributionCookieWritten = true;
     }
     catch {
         // best-effort
@@ -564,16 +583,132 @@ function backfillAttributionCookie(storageKey, spec) {
         // signup handoff goes without it.
     }
 }
+/** Remove every stored touch, in storage and cookies. */
+function clearStoredAttribution() {
+    safeStorageRemove(FIRST_TOUCH_STORAGE_KEY);
+    safeStorageRemove(LAST_TOUCH_STORAGE_KEY);
+    if (typeof document === "undefined")
+        return;
+    for (const name of [
+        FIRST_TOUCH_COOKIE_NAME,
+        LAST_TOUCH_COOKIE_NAME,
+        FIRST_TOUCH_SERVER_COOKIE_NAME,
+    ]) {
+        try {
+            document.cookie = `${name}=; path=/; max-age=0; SameSite=Lax`;
+        }
+        catch {
+            // coercion-ok: a sandboxed iframe can't read or write cookies, so
+            // there is none here to clear.
+        }
+    }
+}
+/** The year-long copy our server keeps in `an_fts`. */
+function readServerFirstTouch() {
+    const touch = readAttributionCookieValue(FIRST_TOUCH_SERVER_COOKIE_NAME);
+    if (!touch || touch.v !== FIRST_TOUCH_SERVER_COOKIE_VERSION)
+        return null;
+    const { v: _version, ...firstTouch } = touch;
+    return firstTouch;
+}
+/**
+ * The browser's own copies: localStorage, then the 30-day `an_ft` cookie. A
+ * visit more than a year old no longer counts, or the cookie it's copied back
+ * into would keep it going.
+ */
+function readLocalFirstTouch() {
+    const touch = readStoredAttribution(FIRST_TOUCH_STORAGE_KEY, FIRST_TOUCH_COOKIE_NAME);
+    return touch && firstTouchServerExpiry(touch) ? touch : null;
+}
 /**
- * Capture the visitor's referral attribution once per page load, into both
- * `localStorage` and a first-party cookie the signup boundary reads. Fully
- * defensive and SSR-safe — any failure is swallowed so it can never break app
- * boot.
+ * The server writes `an_lt` again from each request's cookies, so a slow
+ * response from an older page can put back an older last touch. The newest
+ * one is in localStorage. Returns whether it had to write it back.
+ */
+function restoreNewestLastTouchCookie() {
+    const stored = safeStorageGet(LAST_TOUCH_STORAGE_KEY);
+    const newest = parseAttribution(stored);
+    if (!stored || !newest)
+        return false;
+    const cookie = readAttributionCookieValue(LAST_TOUCH_COOKIE_NAME);
+    if (Date.parse(cookie?.touched_at ?? "") >= Date.parse(newest.touched_at ?? "")) {
+        return false;
+    }
+    writeAttributionCookie(stored, LAST_TOUCH_COOKIE);
+    return true;
+}
+/**
+ * Ask our server to keep `firstTouch` in its year-long cookie, unless it
+ * already holds that visit and this page wrote no attribution cookie; the
+ * same request has the server write `an_ft` and `an_lt` again. Two tabs can each send a touch before either
+ * response lands, and the later response wins the cookie, so when ours
+ * leaves a worse touch there than this browser holds, send the better one
+ * again. Until the server holds it, signup still reads `an_ft`.
+ */
+function syncFirstTouchToServer(firstTouch) {
+    if (!_attributionCookieWritten &&
+        isSameFirstTouch(readServerFirstTouch(), firstTouch)) {
+        return;
+    }
+    // An embed that must not call our API (the Builder shell canvas) keeps only
+    // the browser's copies.
+    if (agentNativeApiDisabledReason())
+        return;
+    if (_firstTouchSyncsLeft <= 0 || typeof fetch !== "function")
+        return;
+    _firstTouchSyncsLeft -= 1;
+    _attributionCookieWritten = false;
+    void fetch(agentNativePath(FIRST_TOUCH_SERVER_PATH), {
+        method: "POST",
+        credentials: "same-origin",
+        keepalive: true,
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ firstTouch }),
+    })
+        .then(async (response) => {
+        if (!response.ok)
+            return;
+        const result = (await response.json());
+        // The visitor may have rejected while this request was out.
+        if (result.reason === "consent_required" ||
+            !consentAllowsNow("targeting")) {
+            clearStoredAttribution();
+            return;
+        }
+        // Written back by page JavaScript, Safari would keep it a week.
+        const repaired = restoreNewestLastTouchCookie();
+        const server = readServerFirstTouch();
+        const local = readLocalFirstTouch();
+        if (!server)
+            return;
+        if (isSameFirstTouch(server, local)) {
+            if (repaired && local)
+                syncFirstTouchToServer(local);
+            return;
+        }
+        if (preferFirstTouch(server, local) === server) {
+            storeAttribution(FIRST_TOUCH_STORAGE_KEY, FIRST_TOUCH_COOKIE, server);
+        }
+        else if (local) {
+            syncFirstTouchToServer(local);
+        }
+    })
+        .catch(() => {
+        // coercion-ok: the 30-day `an_ft` cookie still carries first touch to
+        // signup; the next page load tries again.
+    });
+}
+/**
+ * Capture the visitor's referral attribution once per page load, into
+ * `localStorage`, a first-party cookie the signup boundary reads, and the
+ * server's year-long copy. Fully defensive and SSR-safe — any failure is
+ * swallowed so it can never break app boot.
  *
- * First touch (`an_attribution` / `an_ft`) is first-write-wins, except over a
- * visit that had no source: the first visit that says where this person came
- * from replaces it. Without that, an untagged first visit would hide every
- * tagged visit after it.
+ * First touch (`an_attribution` / `an_ft` / `an_fts`) is the first visit that
+ * said where this person came from, else the first visit; see
+ * `preferFirstTouch`. Without that, an untagged first visit would hide every
+ * tagged visit after it. When the browser's copies are gone, as Safari clears
+ * them, the server's copy restores them.
  */
 function captureFirstTouchAttribution(options = {}) {
     if (_firstTouchCaptured)
@@ -582,16 +717,32 @@ function captureFirstTouchAttribution(options = {}) {
     if (typeof window === "undefined")
         return;
     try {
+        // Read the visit now: the URL can change before the visitor consents.
         const current = buildFirstTouchAttribution(options.landingPath ?? window.location.pathname);
-        const existing = getFirstTouchAttribution();
-        if (existing &&
-            (hasAttributionSource(existing) || !hasAttributionSource(current))) {
+        const forwarded = readForwardedLastTouch();
+        const forwardedAt = readForwardedLastTouchAt();
+        // Where the banner applies, nothing is stored until the visitor accepts
+        // targeting cookies, and a later "reject" clears it again.
+        whenConsentAllows("targeting", () => storeTouches(current, forwarded, forwardedAt), { optimistic: true, revoke: clearStoredAttribution });
+    }
+    catch {
+        // coercion-ok: attribution is best-effort telemetry; never let it break
+        // boot.
+    }
+}
+function storeTouches(current, forwarded, forwardedAt) {
+    try {
+        const local = readLocalFirstTouch();
+        // The same visit in both keeps the local copy, which was never trimmed.
+        const firstTouch = preferFirstTouch(preferFirstTouch(local, readServerFirstTouch()), current);
+        if (firstTouch === local) {
             backfillAttributionCookie(FIRST_TOUCH_STORAGE_KEY, FIRST_TOUCH_COOKIE);
         }
         else {
-            storeAttribution(FIRST_TOUCH_STORAGE_KEY, FIRST_TOUCH_COOKIE, current);
+            storeAttribution(FIRST_TOUCH_STORAGE_KEY, FIRST_TOUCH_COOKIE, firstTouch);
         }
-        captureLastTouchAttribution(current);
+        captureLastTouchAttribution(current, forwarded, forwardedAt);
+        syncFirstTouchToServer(firstTouch);
     }
     catch {
         // Attribution is best-effort telemetry; never let it break boot.
@@ -604,10 +755,8 @@ function captureFirstTouchAttribution(options = {}) {
  * visit keeps the time it happened, and loses to a newer visit the app has
  * already recorded.
  */
-function captureLastTouchAttribution(current) {
-    const forwarded = readForwardedLastTouch();
+function captureLastTouchAttribution(current, forwarded, forwardedAt) {
     const source = forwarded ?? (hasAttributionSource(current) ? current : null);
-    const forwardedAt = readForwardedLastTouchAt();
     const existing = getLastTouchAttribution();
     const existingAt = Date.parse(existing?.touched_at ?? "");
     if (!source ||
@@ -702,7 +851,9 @@ function readStoredAttribution(storageKey, cookieName) {
     return hasAttributionSource(cookie) ? cookie : (stored ?? cookie);
 }
 export function getFirstTouchAttribution() {
-    return readStoredAttribution(FIRST_TOUCH_STORAGE_KEY, FIRST_TOUCH_COOKIE_NAME);
+    if (typeof window === "undefined")
+        return null;
+    return preferFirstTouch(readLocalFirstTouch(), readServerFirstTouch());
 }
 export function getLastTouchAttribution() {
     return readStoredAttribution(LAST_TOUCH_STORAGE_KEY, LAST_TOUCH_COOKIE_NAME);
@@ -731,20 +882,82 @@ function isSyntheticBrowserTraffic() {
     return (typeof window !== "undefined" &&
         isSyntheticTrafficValue(window.__AGENT_NATIVE_SYNTHETIC_TRAFFIC__));
 }
+/**
+ * Amplitude keeps its device id in a cookie on the widest domain it can set,
+ * and its marketing touch and unsent events beside it, all named from the
+ * API key. A reject clears them at every level of this host.
+ */
+function clearAmplitudeStorage(apiKey) {
+    const key = apiKey.slice(0, 10);
+    const names = [
+        `AMP_${key}`,
+        `AMP_MKTG_${key}`,
+        `AMP_MKTG_ORIGINAL_${key}`,
+        `AMP_unsent_${key}`,
+        `amp_${apiKey.slice(0, 6)}`,
+    ];
+    try {
+        const labels = window.location.hostname.split(".");
+        const domains = [""];
+        for (let i = 0; i < labels.length - 1; i += 1) {
+            domains.push(`; domain=.${labels.slice(i).join(".")}`);
+        }
+        for (const name of names) {
+            for (const domain of domains) {
+                document.cookie = `${name}=; path=/; max-age=0${domain}`;
+            }
+        }
+    }
+    catch {
+        // coercion-ok: a sandboxed iframe can't read or write cookies, so
+        // Amplitude stored none here.
+    }
+    for (const name of names)
+        safeStorageRemove(name);
+}
 function ensureAmplitude() {
     if (isSyntheticBrowserTraffic())
         return false;
-    if (_amplitudeInitialized)
-        return true;
     const key = import.meta.env
         ?.VITE_AMPLITUDE_API_KEY;
     if (!key)
         return false;
     _amplitudeApiKey = key;
+    if (_amplitudeConsent !== "granted") {
+        if (_amplitudeConsent === "unasked") {
+            _amplitudeConsent = "waiting";
+            // Amplitude keeps a device id in the browser, so where the banner
+            // applies it waits for performance cookies.
+            whenConsentAllows("performance", () => {
+                _amplitudeConsent = "granted";
+                // Held before the region answered: with a choice on record, the
+                // visitor had to choose, so what came before it never goes out.
+                if (getConsentChoice())
+                    _pendingAmplitudeEvents = [];
+                _amplitudeModule?.setOptOut(false);
+                ensureAmplitude();
+            }, {
+                revoke: () => {
+                    _amplitudeConsent = "revoked";
+                    _pendingAmplitudeEvents = [];
+                    _amplitudeModule?.setOptOut(true);
+                    // A later accept starts a new device id, not the one in memory.
+                    _amplitudeModule?.reset();
+                    clearAmplitudeStorage(key);
+                },
+            });
+        }
+        return false;
+    }
+    if (_amplitudeInitialized)
+        return true;
     if (_amplitudeLoadPromise)
         return false;
     _amplitudeLoadPromise = loadOptionalPeer("@amplitude/analytics-browser", () => import("@amplitude/analytics-browser"))
         .then((module) => {
+        // A reject while the SDK loaded: the next accept initializes it.
+        if (_amplitudeConsent !== "granted")
+            return null;
         module.init(key, { autocapture: false });
         _amplitudeModule = module;
         _amplitudeInitialized = true;
@@ -2005,15 +2218,30 @@ function sendAgentNativeAnalytics(name, properties) {
             ?.VITE_AGENT_NATIVE_ANALYTICS_ENDPOINT ||
         AGENT_NATIVE_ANALYTICS_DEFAULT_ENDPOINT, window.location.hostname);
     const userId = typeof properties.userId === "string" ? properties.userId : undefined;
-    const body = JSON.stringify({
-        publicKey,
-        event: name,
-        properties,
-        userId,
-        anonymousId: getOrCreateAnonymousId(),
-        sessionId: getOrCreateSessionId(),
-        timestamp: new Date().toISOString(),
+    const sessionId = getOrCreateSessionId();
+    const timestamp = new Date().toISOString();
+    whenConsentDecided((decided) => {
+        const anonymousId = decided ? getOrCreateAnonymousId() : undefined;
+        postAgentNativeAnalytics(endpoint, JSON.stringify({
+            publicKey,
+            event: name,
+            // The visitor id waits for analytics consent; mark the event so
+            // reports can tell it from one that lost its id some other way, and
+            // a refusal from a page that closed before the region was known.
+            properties: anonymousId
+                ? properties
+                : {
+                    ...properties,
+                    analytics_consent: decided ? "withheld" : "unknown",
+                },
+            userId,
+            anonymousId,
+            sessionId,
+            timestamp,
+        }));
     });
+}
+function postAgentNativeAnalytics(endpoint, body) {
     try {
         if (navigator.sendBeacon) {
             const sent = navigator.sendBeacon(endpoint, body);
@@ -2037,17 +2265,34 @@ function createTrackingAliasId() {
         ? crypto.randomUUID()
         : undefined;
 }
+function pageHasGoogleTags() {
+    const holder = window;
+    return Boolean(holder.__AN_CONSENT_LAYERS__ ||
+        window.__AGENT_NATIVE_GA_GTAG__ ||
+        window.gtag);
+}
 function emitBrowserTrackingEvent(name, props, options = {}) {
     const { agentNativeProperties = props, gtagProperties = props, sendGtag = true, } = options;
     const amplitudeProps = amplitudeEventProperties(name, props);
-    if (sendGtag) {
-        const gtag = window.__AGENT_NATIVE_GA_GTAG__ ?? window.gtag;
-        gtag?.("event", name.replace(/\s+/g, "_"), gtagProperties);
+    // Without Google tags there is nothing to hold, and asking for the region
+    // would be a request a scoped embed (an MCP App widget) may not make.
+    if (sendGtag && pageHasGoogleTags()) {
+        whenConsentDecided(() => {
+            if (consentDecision("performance") !== true)
+                return;
+            const gtag = window.__AGENT_NATIVE_GA_GTAG__ ?? window.gtag;
+            gtag?.("event", name.replace(/\s+/g, "_"), gtagProperties);
+        });
     }
     if (ensureAmplitude()) {
         _amplitudeModule?.track(name, amplitudeProps);
     }
-    else if (_amplitudeApiKey) {
+    else if (_amplitudeApiKey &&
+        // Only while it loads after an accept, or before the region is known;
+        // the region's answer clears what's held if the visitor must choose.
+        (_amplitudeConsent === "granted" ||
+            (_amplitudeConsent !== "revoked" &&
+                consentDecision("performance") === null))) {
         if (_pendingAmplitudeEvents.length < 100) {
             _pendingAmplitudeEvents.push([name, amplitudeProps]);
         }

package/dist/client/chat/agentkit-agent-native.js

@@ -1,5 +1,5 @@
 import { AgentKitRunSlotBusyError } from "@agent-native/agentkit/client";
-import { AGENT_NATIVE_SUBMISSION_DEADLINES_CAPABILITY_ID, createCapabilityUnavailableError, createCapabilityUnsupportedError, agentEventSequenceEnd, isAgentKitProtocolVersion, negotiateAgentKitProtocolVersion, parseAgentQueuedMessage, parseAgentRunOptions, parseAgentThreadSnapshot, persistableFilePart, } from "@agent-native/agentkit/protocol";
+import { AGENT_NATIVE_SUBMISSION_DEADLINES_CAPABILITY_ID, createCapabilityUnavailableError, createCapabilityUnsupportedError, agentEventSequenceEnd, isAgentKitProtocolVersion, negotiateAgentKitProtocolVersion, parseAgentQueuedMessage, parseNullableAgentQueuedSubmissionStatus, parseAgentRunOptions, parseAgentThreadSnapshot, persistableFilePart, } from "@agent-native/agentkit/protocol";
 import { failedRunIdsWithError, isRenderedRunNotStartedNotice, projectRootAssistantMessages, } from "../../agent/thread-message-projection.js";
 import { RUN_NOT_STARTED_METADATA_KEY, retryContextFromRequest, } from "../../shared/agent-chat-run-not-started.js";
 import { AGENT_CHAT_THREAD_ABSENCE_HEADER } from "../../shared/agent-chat.js";
@@ -1258,6 +1258,15 @@ function storedQueue(value, threadId, fallbackCreatedAt) {
                 createdAt: timestamp(queued.createdAt, fallbackCreatedAt),
                 requestAttachments: queued.requestAttachments,
             }).requestAttachments;
+        const references = queued.references === undefined
+            ? undefined
+            : parseAgentQueuedMessage({
+                id: queued.id,
+                threadId,
+                text: queued.text,
+                createdAt: timestamp(queued.createdAt, fallbackCreatedAt),
+                references: queued.references,
+            }).references;
         return {
             id: queued.id,
             threadId,
@@ -1265,6 +1274,7 @@ function storedQueue(value, threadId, fallbackCreatedAt) {
             createdAt: timestamp(queued.createdAt, fallbackCreatedAt),
             ...(attachments?.length ? { attachments } : {}),
             ...(requestAttachments?.length ? { requestAttachments } : {}),
+            ...(references?.length ? { references } : {}),
             ...(asRecord(queued.metadata)
                 ? { metadata: asRecord(queued.metadata) }
                 : {}),
@@ -3233,6 +3243,7 @@ export function createAgentNativeAgentKitTransport(options = {}) {
                 ? { alreadySubmitted: true, submittedRunId }
                 : {}),
             ...(value.submissionExpired === true ? { submissionExpired: true } : {}),
+            ...(value.receiptManaged === true ? { receiptManaged: true } : {}),
         };
     }
     // A server that predates `active` meaning "in flight" reports a run inside
@@ -3292,6 +3303,16 @@ export function createAgentNativeAgentKitTransport(options = {}) {
         });
         try {
             const run = await startRun(input, context);
+            if (!run.runId) {
+                dispatchAgentChatRunning({
+                    isRunning: false,
+                    phase: "idle",
+                    threadId: input.threadId,
+                    tabId: input.threadId,
+                    reason: "submission_queued",
+                });
+                return run;
+            }
             dispatchAgentChatRunning({
                 isRunning: true,
                 phase: "working",
@@ -3329,6 +3350,42 @@ export function createAgentNativeAgentKitTransport(options = {}) {
                 ? messageEvent.message
                 : undefined));
     }
+    async function readQueuedSubmissionStatus(threadId, messageId) {
+        const requestHeaders = await headers({ sessionId: threadId });
+        requestHeaders.set(AGENT_CHAT_THREAD_ABSENCE_HEADER, "typed");
+        const response = await fetcher(scopedThreadEndpoint(`${apiUrl}/threads/${encodeURIComponent(threadId)}/queue/${encodeURIComponent(messageId)}/receipt`, options), { headers: requestHeaders });
+        if (response.status === 404)
+            return null;
+        if (!response.ok)
+            throw await responseError(response);
+        return parseNullableAgentQueuedSubmissionStatus(await response.json());
+    }
+    async function reconcileQueuedSubmission(threadId, messageId) {
+        const status = await readQueuedSubmissionStatus(threadId, messageId);
+        if (!status) {
+            throw new TypeError(`Receipt-managed queue message ${messageId} has no submission receipt.`);
+        }
+        if (status.state === "submitted") {
+            if (!status.submittedRunId) {
+                throw new TypeError(`Submitted queue message ${messageId} has no run ID.`);
+            }
+            return {
+                runId: status.submittedRunId,
+                alreadySubmitted: true,
+            };
+        }
+        if (status.state === "removed" || status.state === "expired") {
+            return { alreadyRemoved: true };
+        }
+        if (status.state === "blocked") {
+            const error = new Error(`Queued submission ${messageId} is blocked in the server inbox.`);
+            Object.assign(error, { code: "queue_item_blocked", retryable: false });
+            throw error;
+        }
+        const error = new Error(`Queued submission ${messageId} is still waiting in the server inbox.`);
+        Object.assign(error, { code: "queue_item_busy", retryable: true });
+        throw error;
+    }
     const runtime = options.runtime ?? createAgentNativeChatRuntime(options);
     const feedbackUrl = options.feedbackUrl ??
         agentNativePath("/_agent-native/observability/feedback");
@@ -3360,7 +3417,10 @@ export function createAgentNativeAgentKitTransport(options = {}) {
             },
             getThreadSnapshot: ({ threadId }) => threadSnapshotWithActiveRun(threadId),
             listQueuedMessages: async ({ threadId }) => readQueue(threadId),
-            queueMessage: async ({ threadId, id, text, attachments, requestAttachments, metadata, options: runOptions, interruptActiveRun, submissionPayload, }) => {
+            getQueuedSubmissionStatus: async ({ threadId, messageId }) => {
+                return readQueuedSubmissionStatus(threadId, messageId);
+            },
+            queueMessage: async ({ threadId, id, text, attachments, requestAttachments, references, metadata, options: runOptions, interruptActiveRun, submissionPayload, }) => {
                 const queueSubmissionPayload = submissionPayload
                     ? { ...submissionPayload, metadata }
                     : undefined;
@@ -3375,6 +3435,7 @@ export function createAgentNativeAgentKitTransport(options = {}) {
                     createdAt: now(),
                     attachments,
                     requestAttachments,
+                    references,
                     metadata,
                     options: runOptions,
                     ...(interruptActiveRun ? { interruptActiveRun: true } : {}),
@@ -3405,7 +3466,8 @@ export function createAgentNativeAgentKitTransport(options = {}) {
                 return { message: result.message };
             },
             removeQueuedMessage: async ({ threadId, messageId }) => {
-                await persistQueueMutation(threadId, { type: "remove", messageId });
+                await persistQueueMutation(threadId, { type: "cancel", messageId });
+                clearPromotionClaimId(threadId, messageId);
             },
             moveQueuedMessageToTop: async ({ threadId, messageId }) => {
                 await persistQueueMutation(threadId, { type: "moveToTop", messageId });
@@ -3457,6 +3519,11 @@ export function createAgentNativeAgentKitTransport(options = {}) {
                         clearPromotionClaimId(threadId, messageId);
                         return { alreadyRemoved: true };
                     }
+                    if (claim.receiptManaged) {
+                        clearPromotionClaimId(threadId, messageId);
+                        claimHeld = false;
+                        return await reconcileQueuedSubmission(threadId, messageId);
+                    }
                     if (!claim.claimedMessage) {
                         throw new TypeError("Agent chat queue claim response is invalid.");
                     }
@@ -3524,6 +3591,11 @@ export function createAgentNativeAgentKitTransport(options = {}) {
                                 clearPromotionClaimId(threadId, messageId);
                                 return { alreadyRemoved: true };
                             }
+                            if (claim.receiptManaged) {
+                                clearPromotionClaimId(threadId, messageId);
+                                claimHeld = false;
+                                return await reconcileQueuedSubmission(threadId, messageId);
+                            }
                             if (claim.alreadySubmitted && claim.submittedRunId) {
                                 clearPromotionClaimId(threadId, messageId);
                                 return {
@@ -3557,6 +3629,7 @@ export function createAgentNativeAgentKitTransport(options = {}) {
                             },
                         ],
                         requestAttachments: claimedMessage.requestAttachments,
+                        references: claimedMessage.references,
                         options: claimedMessage.options,
                         metadata: claimedMessage.metadata,
                         queuePromotion: {
@@ -3565,6 +3638,9 @@ export function createAgentNativeAgentKitTransport(options = {}) {
                             turnId: `queue-${messageId}`,
                         },
                     }, undefined);
+                    if (!run.runId) {
+                        throw new TypeError("A queue promotion cannot be acknowledged as a new queued submission.");
+                    }
                     const latestThread = await snapshot(threadId);
                     if (!latestThread) {
                         throw new Error(`Unknown agent chat thread: ${threadId}`);