@agent-native/core 0.214.0 → 0.216.0

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, whenConsentAllows } from "./consent.js";
 import { clientFailureContext } from "./failure-report.js";
 import { replayEndpointFromAnalyticsEndpoint } from "./session-replay-endpoint.js";
 import { scheduleAfterPaint } from "./use-after-paint.js";
@@ -174,6 +178,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 +199,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 +553,7 @@ function writeAttributionCookie(value, spec) {
     const encodedValue = fitAttributionCookieValue(value, spec);
     try {
         document.cookie = attributionCookieAssignment(spec.name, encodedValue);
+        _attributionCookieWritten = true;
     }
     catch {
         // best-effort
@@ -564,16 +582,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;
+}
 /**
- * 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 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;
+}
+/**
+ * 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 +716,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 +754,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 +850,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);

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}`);

package/dist/client/chat/agentkit-protocol.js

@@ -81,53 +81,56 @@ function runtimeAttachmentFromFilePart(part) {
 function runtimeRequestAttachments(args) {
     const attachments = args.message?.parts.flatMap((part) => part.type === "file" ? [runtimeAttachmentFromFilePart(part)] : []) ?? [];
     for (const requestAttachment of args.requestAttachments ?? []) {
-        const originalUrl = requestAttachment.referenceUrl;
-        const originalIndex = originalUrl
-            ? attachments.findIndex((attachment) => attachment.url === originalUrl)
+        const referenceUrl = requestAttachment.referenceUrl;
+        const originalUrl = referenceUrl;
+        const originalLookupUrl = originalUrl ?? requestAttachment.url;
+        const originalIndex = originalLookupUrl
+            ? attachments.findIndex((attachment) => attachment.url === originalLookupUrl)
             : -1;
+        const addReferenceOnly = (replaceOriginal) => {
+            const original = originalIndex >= 0 ? attachments[originalIndex] : null;
+            const reference = {
+                type: "file",
+                name: original?.name || requestAttachment.name,
+                contentType: original?.contentType || requestAttachment.contentType,
+                ...(original?.id ? { id: original.id } : {}),
+                ...(original?.mediaType ? { mediaType: original.mediaType } : {}),
+                url: originalLookupUrl,
+                referenceOnly: true,
+            };
+            if (replaceOriginal && originalIndex >= 0) {
+                attachments.splice(originalIndex, 1, reference);
+            }
+            else {
+                attachments.push(reference);
+            }
+        };
         if (typeof requestAttachment.data === "string") {
-            const imageUrl = requestAttachment.url ?? originalUrl;
-            const keepsOriginalReference = originalUrl !== undefined &&
-                imageUrl !== undefined &&
-                originalUrl !== imageUrl;
+            // The image's identity is exactly what the client fingerprinted: its own
+            // url, never one derived from referenceUrl. An original file part is kept
+            // as a reference (even when the image shares its url), so the submitted
+            // file fingerprint still matches the mapped attachments.
+            const imageUrl = requestAttachment.url;
+            const keepsOriginalReference = originalIndex >= 0 ||
+                (originalUrl !== undefined &&
+                    imageUrl !== undefined &&
+                    originalUrl !== imageUrl);
             if (keepsOriginalReference) {
-                const original = originalIndex >= 0 ? attachments[originalIndex] : null;
-                const reference = {
-                    type: "file",
-                    name: original?.name || requestAttachment.name,
-                    contentType: original?.contentType || requestAttachment.contentType,
-                    url: originalUrl,
-                    referenceOnly: true,
-                };
-                if (originalIndex >= 0)
-                    attachments.splice(originalIndex, 1, reference);
-                else
-                    attachments.push(reference);
+                addReferenceOnly(originalIndex >= 0);
             }
-            const image = {
+            attachments.push({
                 type: "image",
                 name: requestAttachment.name,
                 contentType: requestAttachment.contentType,
                 data: requestAttachment.data,
                 ...(imageUrl ? { url: imageUrl } : {}),
-            };
-            if (originalIndex >= 0 && !keepsOriginalReference) {
-                attachments.splice(originalIndex, 1, image);
-            }
-            else {
-                attachments.push(image);
-            }
+                ...(referenceUrl ? { referenceUrl } : {}),
+            });
             continue;
         }
-        if (originalIndex >= 0 && originalUrl) {
-            const original = attachments[originalIndex];
-            attachments.splice(originalIndex, 1, {
-                type: "file",
-                name: original.name || requestAttachment.name,
-                contentType: original.contentType,
-                url: originalUrl,
-                referenceOnly: true,
-            });
+        if (originalUrl &&
+            (originalIndex < 0 || requestAttachment.url !== originalUrl)) {
+            addReferenceOnly(originalIndex >= 0);
         }
         if (typeof requestAttachment.url === "string") {
             attachments.push({
@@ -135,6 +138,7 @@ function runtimeRequestAttachments(args) {
                 name: requestAttachment.name,
                 contentType: requestAttachment.contentType,
                 url: requestAttachment.url,
+                ...(referenceUrl ? { referenceUrl } : {}),
             });
         }
     }
@@ -189,6 +193,17 @@ function mergeProtocolMetadata(...sources) {
     }
     return merged;
 }
+function withQueuedMessageIdMetadata(metadata, messageId) {
+    if (messageId === undefined)
+        return metadata;
+    return {
+        ...metadata,
+        custom: {
+            ...asRecord(metadata?.custom),
+            agentNativeQueuedMessageId: messageId,
+        },
+    };
+}
 const PROTECTED_PROTOCOL_METADATA_KEYS = [
     "actor",
     "workspace",
@@ -1504,7 +1519,7 @@ export function createAgentKitProtocolAdapter(runtime, options = {}) {
      */
     async function openStartedRun(threadId, session, turn, turnMetadata, observability, start = {}) {
         const runId = turn.runId ?? turn.id ?? createId("run");
-        const runMetadata = mergeTrustedProtocolMetadata(options.metadata, turnMetadata, turn.metadata, {
+        const runMetadata = withQueuedMessageIdMetadata(mergeTrustedProtocolMetadata(options.metadata, turnMetadata, turn.metadata, {
             [AGENT_NATIVE_PROTOCOL_METADATA_KEY]: {
                 observability: {
                     protocolRunId: runId,
@@ -1516,7 +1531,7 @@ export function createAgentKitProtocolAdapter(runtime, options = {}) {
                     ...observability,
                 },
             },
-        });
+        }), start.queuedMessageId);
         setRuntimeRunIdMetadata(runMetadata, turn.runId);
         setRuntimeTurnIdMetadata(runMetadata, turn.id);
         const run = {
@@ -3127,7 +3142,11 @@ export function createAgentKitProtocolAdapter(runtime, options = {}) {
             const latestUserMetadata = asRecord(latestUserMessage?.metadata);
             const recoveryMetadata = asRecord(latestUserMetadata?.custom);
             const isRecoveryRetry = recoveryMetadata?.agentNativeRecoveryAction === "retry";
-            const turnMetadata = mergeTrustedProtocolMetadata(options.metadata, input.metadata, input.options?.metadata, input.options?.agentId ? { agentId: input.options.agentId } : undefined, input.options?.locale ? { locale: input.options.locale } : undefined, input.options?.mode ? { mode: input.options.mode } : undefined, isRecoveryRetry ? { agentNativeInternalContinuation: true } : undefined);
+            const turnMetadata = withQueuedMessageIdMetadata(mergeTrustedProtocolMetadata(options.metadata, input.metadata, input.options?.metadata, input.options?.agentId
+                ? { agentId: input.options.agentId }
+                : undefined, input.options?.locale ? { locale: input.options.locale } : undefined, input.options?.mode ? { mode: input.options.mode } : undefined, isRecoveryRetry
+                ? { agentNativeInternalContinuation: true }
+                : undefined), input.queuePromotion?.messageId);
             const queuePromotionKey = input.queuePromotion
                 ? JSON.stringify([input.threadId, input.queuePromotion.turnId])
                 : undefined;
@@ -3153,9 +3172,11 @@ export function createAgentKitProtocolAdapter(runtime, options = {}) {
                 const turn = await session.startTurn({
                     prompt: latestUserPrompt(input.messages),
                     messages,
+                    ...(input.options ? { options: input.options } : {}),
                     ...(input.submissionPayload
                         ? { submissionPayload: input.submissionPayload }
                         : {}),
+                    ...(input.references?.length ? { references: input.references } : {}),
                     ...(input.queuePromotion
                         ? { queuePromotion: input.queuePromotion }
                         : {}),
@@ -3174,15 +3195,29 @@ export function createAgentKitProtocolAdapter(runtime, options = {}) {
                     metadata: turnMetadata,
                     abortSignal: readers.signal,
                 });
+                if (turn.queuedSubmission)
+                    return turn.queuedSubmission;
                 return openStartedRun(input.threadId, session, turn, turnMetadata, undefined, {
                     attachReplayedRun: true,
                     messageId: latestUserMessage?.id,
+                    ...(input.queuePromotion
+                        ? { queuedMessageId: input.queuePromotion.messageId }
+                        : {}),
                 });
             };
             if (!queuePromotionKey) {
-                return { runId: await createRun(), capabilities };
-            }
-            const pendingRun = Promise.resolve().then(createRun);
+                const started = await createRun();
+                return typeof started === "string"
+                    ? { runId: started, capabilities }
+                    : { queuedSubmission: started, capabilities };
+            }
+            const pendingRun = Promise.resolve().then(async () => {
+                const started = await createRun();
+                if (typeof started !== "string") {
+                    throw new TypeError("A queue promotion cannot be acknowledged as a new queued submission.");
+                }
+                return started;
+            });
             pendingQueuePromotionRuns.set(queuePromotionKey, pendingRun);
             try {
                 return { runId: await pendingRun, capabilities };
@@ -3806,6 +3841,9 @@ export function createAgentKitProtocolAdapter(runtime, options = {}) {
         transport.cancelUpload = hostOperations.cancelUpload;
     if (hostOperations?.listQueuedMessages)
         transport.listQueuedMessages = hostOperations.listQueuedMessages;
+    if (hostOperations?.getQueuedSubmissionStatus)
+        transport.getQueuedSubmissionStatus =
+            hostOperations.getQueuedSubmissionStatus;
     if (hostOperations?.queueMessage) {
         transport.queueMessage = (input, context) => {
             const metadata = mergeTrustedProtocolMetadata(options.metadata, input.metadata);

package/dist/client/chat/runtime.d.ts

@@ -1,4 +1,4 @@
-import type { AgentSuggestion } from "@agent-native/agentkit/protocol";
+import { type AgentRunOptions, type AgentSubmissionReference, type AgentQueuedSubmissionReceipt, type AgentSuggestion } from "@agent-native/agentkit/protocol";
 import type { ActionChatUIConfig } from "../../action-ui.js";
 import type { AgentMcpAppPayload } from "../../mcp-client/app-result.js";
 import type { ReasoningEffort } from "../../shared/reasoning-effort.js";
@@ -89,6 +89,7 @@ export interface AgentChatRuntimeAttachment {
     readonly contentType?: string;
     readonly data?: string;
     readonly url?: string;
+    readonly referenceUrl?: string;
     readonly text?: string;
     readonly metadata?: AgentChatRuntimeMetadata;
 }
@@ -218,6 +219,8 @@ export interface AgentChatRuntimeTurnInput {
     readonly prompt?: string;
     readonly messages?: readonly AgentChatRuntimeMessage[];
     readonly submissionPayload?: unknown;
+    readonly options?: AgentRunOptions;
+    readonly references?: readonly AgentSubmissionReference[];
     readonly queuePromotion?: {
         readonly messageId: string;
         readonly claimId: string;
@@ -549,6 +552,7 @@ export interface AgentChatRuntimeTurn<TEvent extends AgentChatRuntimeEventBase =
     readonly sessionId: AgentChatRuntimeSessionId;
     readonly runId?: string;
     readonly metadata?: AgentChatRuntimeMetadata;
+    readonly queuedSubmission?: AgentQueuedSubmissionReceipt;
     readonly events: AsyncIterable<TEvent>;
     /** Close the local event stream without cancelling the underlying run. */
     closeEvents?(): Promise<void> | void;