@agent-native/core 0.214.0 → 0.217.0

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;

package/dist/client/chat/runtime.js

@@ -1,4 +1,5 @@
 import { AgentKitRunSlotBusyError } from "@agent-native/agentkit/client";
+import { parseAgentQueuedSubmissionReceipt, } from "@agent-native/agentkit/protocol";
 import { AUTO_CONTINUE_OF_RUN_METADATA_KEY, CONTINUE_OF_RUN_METADATA_KEY, } from "../../agent/auto-continue.js";
 import { RUN_NOT_STARTED_METADATA_KEY } from "../../shared/agent-chat-run-not-started.js";
 import { agentEngineStatusUrlForChatApi, requireAgentEngineConfiguredForDispatch, } from "../agent-engine-readiness.js";
@@ -261,6 +262,8 @@ function defaultHttpRuntimeRequest(input) {
         messages: input.turn.messages,
         attachments: input.turn.attachments,
         submissionPayload: input.turn.submissionPayload,
+        options: input.turn.options,
+        references: input.turn.references,
         tools: input.turn.tools,
         model: input.turn.model,
         reasoningEffort: input.turn.reasoningEffort,
@@ -476,6 +479,43 @@ export function createHttpAgentChatRuntime(options) {
                 }
                 throw withTurnId(error, turnId);
             }
+            if (response.status === 202) {
+                let queuedSubmission;
+                try {
+                    if (!response.headers
+                        .get("Content-Type")
+                        ?.toLowerCase()
+                        .includes("application/json")) {
+                        throw new TypeError("Expected a JSON queued submission receipt.");
+                    }
+                    queuedSubmission = parseAgentQueuedSubmissionReceipt(await response.json());
+                    const submission = asRecord(turn.submissionPayload);
+                    const expectedThreadId = summary.threadId ?? sessionId;
+                    if (queuedSubmission.message.threadId !== expectedThreadId ||
+                        (typeof submission?.id === "string" &&
+                            queuedSubmission.message.id !== submission.id)) {
+                        throw new TypeError("The queued submission receipt does not match this session turn.");
+                    }
+                }
+                catch (cause) {
+                    cleanup();
+                    throw withTurnId(Object.assign(new Error(cause instanceof Error
+                        ? `Invalid queued submission response: ${cause.message}`
+                        : "Invalid queued submission response.", { cause }), {
+                        code: "invalid_queued_submission_response",
+                        status: response.status,
+                        retryable: true,
+                    }), turnId);
+                }
+                cleanup();
+                forgetTurnContext(turnId, turn);
+                return {
+                    id: turnId,
+                    sessionId,
+                    queuedSubmission,
+                    events: (async function* () { })(),
+                };
+            }
             const runId = response.headers.get("X-Run-Id") ?? undefined;
             const events = (async function* () {
                 let retryableFailure = false;
@@ -3230,6 +3270,8 @@ export function createAgentNativeChatRuntime(options = {}) {
                 ...(turn.submissionPayload !== undefined
                     ? { submissionPayload: turn.submissionPayload }
                     : {}),
+                ...(turn.references?.length ? { references: turn.references } : {}),
+                ...(turn.options ? { options: turn.options } : {}),
                 ...(turn.queuePromotion
                     ? {
                         queuedMessageId: turn.queuePromotion.messageId,
@@ -3298,6 +3340,7 @@ export function createAgentNativeChatRuntime(options = {}) {
             const turnToContinue = continuation.attachments?.length
                 ? { ...previousTurn, attachments: continuation.attachments }
                 : previousTurn;
+            const { submissionPayload: _submissionPayload, ...continuationTurn } = turnToContinue ?? {};
             const approval = continuation.approval;
             const connection = continuation.connection;
             const messageStateKey = continuation.turnId ?? session.id;
@@ -3314,7 +3357,7 @@ export function createAgentNativeChatRuntime(options = {}) {
                 if (messageState)
                     messageState.message.connectionPending = false;
                 return startTurn({
-                    ...turnToContinue,
+                    ...continuationTurn,
                     prompt: continuation.prompt ??
                         `The ${connection.id} connection is now available. Continue the requested work.`,
                     metadata: {
@@ -3334,7 +3377,7 @@ export function createAgentNativeChatRuntime(options = {}) {
                 if (messageState)
                     messageState.message.approvalPending = false;
                 return startTurn({
-                    ...turnToContinue,
+                    ...continuationTurn,
                     prompt: continuation.prompt,
                     metadata: {
                         ...previousMetadata,
@@ -3376,7 +3419,7 @@ export function createAgentNativeChatRuntime(options = {}) {
             if (messageState)
                 messageState.message.approvalPending = false;
             return startTurn({
-                ...turnToContinue,
+                ...continuationTurn,
                 prompt: continuation.prompt ??
                     "Approved. Go ahead and run the requested action.",
                 metadata: {

package/dist/client/consent.d.ts

@@ -0,0 +1,48 @@
+import { type ConsentCategory, type ConsentChoice, type ConsentRegion } from "../shared/consent.js";
+export type { ConsentCategory, ConsentChoice, ConsentRegion };
+/** The visitor's stored choice, or `null` before they've made one. */
+export declare function getConsentChoice(): ConsentChoice | null;
+/**
+ * Whether this visitor gets the banner: the server's answer from the
+ * request's country, else the browser's time zone. Asked once a session.
+ */
+export declare function resolveConsentRegion(): Promise<ConsentRegion>;
+/**
+ * Whether `category` is allowed right now, on the time zone's guess until the
+ * server answers. Pair it with `whenConsentAllows` and a `revoke` that undoes
+ * whatever this let through.
+ */
+export declare function consentAllowsNow(category: ConsentCategory): boolean;
+/**
+ * Whether `category` is allowed, from the visitor's choice or the server's
+ * region; `null` until one of them is known, where `consentAllowsNow` would
+ * guess from the time zone. For what `revoke` can't undo once it's sent.
+ */
+export declare function consentDecision(category: ConsentCategory): boolean | null;
+export interface WhenConsentAllowsOptions {
+    /**
+     * Run now on the time zone's guess instead of waiting for the server, and
+     * call `revoke` if the server or the visitor then says no. Only for storage
+     * `revoke` can fully undo; a third-party script can't be unloaded.
+     */
+    optimistic?: boolean;
+    revoke?: () => void;
+}
+/**
+ * Run `run` once `category` is allowed: at once outside the consent region,
+ * and inside it when the visitor accepts. A later "reject" calls `revoke`.
+ */
+export declare function whenConsentAllows(category: ConsentCategory, run: () => void, options?: WhenConsentAllowsOptions): void;
+/**
+ * Run `send` once the visitor's choice or the server's region is known, so
+ * the time zone's guess never sends what consent covers. `decided` is false
+ * when the page closes first; send then without what consent covers.
+ */
+export declare function whenConsentDecided(send: (decided: boolean) => void): void;
+/** Store the visitor's choice for every app on this site, and apply it. */
+export declare function setConsentChoice(choice: ConsentChoice): void;
+/** Reopen the banner so the visitor can change their choice. */
+export declare function openConsentSettings(): void;
+/** Whether the banner should show now, for the banner component. */
+export declare function shouldShowConsentBanner(): boolean;
+export declare function subscribeConsent(listener: () => void): () => void;