@agent-native/core 0.209.1-nightly-20261015153252 → 0.209.1

package/dist/a2a/index.d.ts

@@ -1,4 +1,4 @@
-export { mountA2A, verifyA2AToken } from "./server.js";
+export { diagnoseA2ATokenFailure, mountA2A, verifyA2AToken, type A2ATokenFailureCause, } from "./server.js";
 export type { A2ATokenPayload } from "./server.js";
 export { generateAgentCard } from "./agent-card.js";
 export { A2A_AGENT_ACTIVITY_KIND, A2A_AGENT_ACTIVITY_VERSION, MAX_A2A_ACTIVITY_REASONING_CHARS, MAX_A2A_ACTIVITY_REASONING_SEGMENTS, MAX_A2A_ACTIVITY_RESPONSE_CHARS, MAX_A2A_ACTIVITY_TOOL_CALLS, MAX_A2A_ACTIVITY_TOTAL_CHARS, MAX_A2A_ACTIVITY_TOOL_ID_CHARS, MAX_A2A_ACTIVITY_TOOL_INPUT_CHARS, MAX_A2A_ACTIVITY_TOOL_NAME_CHARS, MAX_A2A_ACTIVITY_TOOL_PAYLOAD_CHARS, MAX_A2A_ACTIVITY_TOOL_RESULT_CHARS, applyA2AAgentActivityEvent, buildA2AAgentActivityPart, buildA2AAgentActivitySnapshot, createA2AAgentActivityState, parseA2AAgentActivityPart, } from "./activity.js";

package/dist/a2a/index.js

@@ -1,4 +1,4 @@
-export { mountA2A, verifyA2AToken } from "./server.js";
+export { diagnoseA2ATokenFailure, mountA2A, verifyA2AToken, } from "./server.js";
 export { generateAgentCard } from "./agent-card.js";
 export { A2A_AGENT_ACTIVITY_KIND, A2A_AGENT_ACTIVITY_VERSION, MAX_A2A_ACTIVITY_REASONING_CHARS, MAX_A2A_ACTIVITY_REASONING_SEGMENTS, MAX_A2A_ACTIVITY_RESPONSE_CHARS, MAX_A2A_ACTIVITY_TOOL_CALLS, MAX_A2A_ACTIVITY_TOTAL_CHARS, MAX_A2A_ACTIVITY_TOOL_ID_CHARS, MAX_A2A_ACTIVITY_TOOL_INPUT_CHARS, MAX_A2A_ACTIVITY_TOOL_NAME_CHARS, MAX_A2A_ACTIVITY_TOOL_PAYLOAD_CHARS, MAX_A2A_ACTIVITY_TOOL_RESULT_CHARS, applyA2AAgentActivityEvent, buildA2AAgentActivityPart, buildA2AAgentActivitySnapshot, createA2AAgentActivityState, parseA2AAgentActivityPart, } from "./activity.js";
 export { A2AClient, A2AJsonRpcResponseError, A2AMissingJsonRpcResponseError, A2ANoJsonRpcInterfaceError, A2AProtocolError, assertCredentialedA2AUrl, callAction, callAgent, clearA2ACardCache, getGlobalA2ASecret, signA2AOrganizationToken, signA2AToken, } from "./client.js";

package/dist/a2a/server.d.ts

@@ -48,5 +48,15 @@ export declare function verifyA2AToken(token: string, event?: any, audienceOptio
     /** Only use this explicitly configured credential; never fall back. */
     verificationSecret?: string;
 }): Promise<A2ATokenPayload>;
+export type A2ATokenFailureCause = "malformed" | "secret-missing" | "audience-unresolvable" | "audience" | "issuer" | "expired" | "signature" | "invalid-claims" | "mcp-credential" | "missing-subject" | "org-binding" | "org-lookup-failed" | "undetermined";
+/**
+ * Names why a token that `verifyA2AToken` resolved no identity for was
+ * refused. `verifyA2AToken` collapses a wrong audience, a wrong secret and an
+ * unbound organization into one empty identity; this re-checks the same inputs,
+ * against the deploy secret and then the organization's, to tell them apart.
+ * Diagnostic only: it never grants anything, and its answer must not be used as
+ * an authorization result.
+ */
+export declare function diagnoseA2ATokenFailure(token: string, event?: any): Promise<A2ATokenFailureCause>;
 export declare function mountA2A(nitroApp: any, config: A2AConfig, routePrefix?: string): void;
 export declare function filterPublicAgentCardSkills(config: A2AConfig): AgentSkill[];

package/dist/a2a/server.js

@@ -159,6 +159,102 @@ function isDirectReadSkill(skill) {
 export async function verifyA2AToken(token, event, audienceOptions) {
     return (await verifyA2ATokenInternal(token, event, audienceOptions)).payload;
 }
+async function checkAgainstSecret(token, secret, options) {
+    try {
+        const { payload } = await jose.jwtVerify(token, new TextEncoder().encode(secret), options);
+        return { payload };
+    }
+    catch (error) {
+        const { code, claim } = error;
+        if (code === "ERR_JWT_EXPIRED")
+            return { cause: "expired" };
+        if (code === "ERR_JWS_SIGNATURE_VERIFICATION_FAILED") {
+            return { cause: "signature" };
+        }
+        if (code === "ERR_JWT_CLAIM_VALIDATION_FAILED") {
+            if (claim === "aud")
+                return { cause: "audience" };
+            if (claim === "iss")
+                return { cause: "issuer" };
+        }
+        return { cause: "invalid-claims" };
+    }
+}
+async function diagnoseVerifiedPayload(payload) {
+    if (isMcpCredential(payload))
+        return "mcp-credential";
+    if (typeof payload.sub !== "string" || !payload.sub.trim()) {
+        return "missing-subject";
+    }
+    try {
+        const organization = await verifyA2AOrganizationIdentity(payload);
+        return organization === null ? "org-binding" : "undetermined";
+    }
+    catch {
+        // coercion-ok: an unreadable organization registry is the typed "org-lookup-failed" cause.
+        return "org-lookup-failed";
+    }
+}
+/**
+ * Names why a token that `verifyA2AToken` resolved no identity for was
+ * refused. `verifyA2AToken` collapses a wrong audience, a wrong secret and an
+ * unbound organization into one empty identity; this re-checks the same inputs,
+ * against the deploy secret and then the organization's, to tell them apart.
+ * Diagnostic only: it never grants anything, and its answer must not be used as
+ * an authorization result.
+ */
+export async function diagnoseA2ATokenFailure(token, event) {
+    let claims;
+    try {
+        claims = jose.decodeJwt(token);
+    }
+    catch {
+        // coercion-ok: an undecodable token is the typed "malformed" cause.
+        return "malformed";
+    }
+    const secret = readDeployCredentialEnv("A2A_SECRET")?.trim();
+    const options = {};
+    if (typeof claims.aud !== "undefined") {
+        const audience = expectedJwtAudience(event);
+        if (!audience)
+            return "audience-unresolvable";
+        options.audience = audience;
+    }
+    if (typeof claims.iss === "string" && claims.iss.length > 0) {
+        options.issuer = claims.iss;
+    }
+    // The verifier goes on to the organization's own secret when the deploy secret
+    // is unset or does not verify the token, so neither is the final answer yet.
+    let deployCause = "secret-missing";
+    if (secret) {
+        const deploy = await checkAgainstSecret(token, secret, options);
+        if ("payload" in deploy)
+            return diagnoseVerifiedPayload(deploy.payload);
+        deployCause = deploy.cause;
+    }
+    const orgDomain = typeof claims.org_domain === "string" ? claims.org_domain.trim() : "";
+    if ((deployCause !== "signature" && deployCause !== "secret-missing") ||
+        !orgDomain) {
+        return deployCause;
+    }
+    let organization;
+    try {
+        const { resolveA2AOrganizationCredentialsByDomain } = await import("../org/context.js");
+        organization = await resolveA2AOrganizationCredentialsByDomain(orgDomain);
+    }
+    catch {
+        // coercion-ok: an unreadable organization registry is the typed "org-lookup-failed" cause.
+        return "org-lookup-failed";
+    }
+    if (!organization)
+        return deployCause;
+    const orgCheck = await checkAgainstSecret(token, organization.secret, options);
+    if ("cause" in orgCheck)
+        return orgCheck.cause;
+    return organizationPrincipalClaims(orgCheck.payload, organization)
+        ? "undetermined"
+        : "org-binding";
+}
 async function verifyA2ATokenInternal(token, event, audienceOptions) {
     // Step 1: Peek at JWT claims WITHOUT verification to get org_domain.
     // This is safe because we only use org_domain to look up the secret,

package/dist/agent/production-agent.d.ts

@@ -329,6 +329,7 @@ export interface ProductionAgentOptions {
         attachments?: AgentChatAttachment[];
         queuedMessageId?: string;
         queuedMessageClaimId?: string;
+        submissionExpiresAt?: unknown;
     }) => void | Promise<void>;
     /**
      * The turn was refused before a run started (no usable model credential).
@@ -342,6 +343,7 @@ export interface ProductionAgentOptions {
         attachments?: AgentChatAttachment[];
         queuedMessageId?: string;
         agentKitMessageId?: string;
+        submissionExpiresAt?: unknown;
         retryContext: RefusedTurnRetryContext;
         failure: {
             code: string;

package/dist/agent/production-agent.js

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import { MAX_AGENT_REQUEST_ATTACHMENT_DATA_CHARS, MAX_AGENT_REQUEST_ATTACHMENTS, } from "@agent-native/agentkit/protocol";
+import { AGENT_NATIVE_SUBMISSION_EXPIRES_AT_METADATA_KEY, AGENT_NATIVE_SUBMISSION_TTL_MS_METADATA_KEY, MAX_AGENT_REQUEST_ATTACHMENT_DATA_CHARS, MAX_AGENT_REQUEST_ATTACHMENTS, } from "@agent-native/agentkit/protocol";
 import Ajv from "ajv";
 import Ajv2020 from "ajv/dist/2020.js";
 import { defineEventHandler, getHeader, setResponseHeader, setResponseStatus, getMethod, } from "h3";
@@ -83,6 +83,7 @@ import { writeLedgerEntry, readLedgerEntry, clearLedgerForThread, AgentTurnIniti
 import { buildCurrentTimeUserContext } from "./runtime-context.js";
 import { claimSetupResume, setupResumeRefusedRunId, } from "./setup-resume-claim.js";
 import { getStrictToolInputValidator } from "./strict-tool-input.js";
+import { normalizeSubmissionDeadlineMetadata } from "./submission-deadline.js";
 import { consumeAgentToolApproval, createAgentToolApproval, isAgentToolAlwaysAllowed, resolveAgentToolApprovalTurnId, } from "./tool-approval-store.js";
 import { findCompletedJournalEntry, isUnavailableToolCallInput, } from "./tool-call-journal.js";
 import { redactSensitiveFields, sanitizeToolErrorText, sanitizeToolErrorValue, } from "./tool-error-redaction.js";
@@ -1024,6 +1025,42 @@ export function createPlanModeActionRegistry(actions) {
     }
     return filtered;
 }
+function submissionExpiryMetadata(metadata) {
+    if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+        return undefined;
+    }
+    const custom = metadata.custom;
+    if (!custom ||
+        typeof custom !== "object" ||
+        Array.isArray(custom) ||
+        !Object.prototype.hasOwnProperty.call(custom, AGENT_NATIVE_SUBMISSION_EXPIRES_AT_METADATA_KEY)) {
+        return undefined;
+    }
+    return {
+        submissionExpiresAt: custom[AGENT_NATIVE_SUBMISSION_EXPIRES_AT_METADATA_KEY],
+    };
+}
+function mergeQueuedPromotionMetadata(admittedMetadata, optionMetadata) {
+    const admitted = queuedPromotionRecord(admittedMetadata) ?? {};
+    const options = queuedPromotionRecord(optionMetadata) ?? {};
+    const admittedCustom = queuedPromotionRecord(admitted.custom) ?? {};
+    const optionCustom = queuedPromotionRecord(options.custom) ?? {};
+    const custom = { ...admittedCustom, ...optionCustom };
+    delete custom[AGENT_NATIVE_SUBMISSION_TTL_MS_METADATA_KEY];
+    delete custom[AGENT_NATIVE_SUBMISSION_EXPIRES_AT_METADATA_KEY];
+    if (Object.prototype.hasOwnProperty.call(admittedCustom, AGENT_NATIVE_SUBMISSION_EXPIRES_AT_METADATA_KEY)) {
+        custom[AGENT_NATIVE_SUBMISSION_EXPIRES_AT_METADATA_KEY] =
+            admittedCustom[AGENT_NATIVE_SUBMISSION_EXPIRES_AT_METADATA_KEY];
+    }
+    const metadata = { ...admitted, ...options };
+    if (Object.keys(custom).length > 0) {
+        metadata.custom = custom;
+    }
+    else {
+        delete metadata.custom;
+    }
+    return metadata;
+}
 export async function resolveAgentOwnerEmail(options, event) {
     let ownerEmail = null;
     if (options.resolveOwnerEmail) {
@@ -7955,7 +7992,7 @@ export function createProductionAgentHandler(options) {
             : typeof parentId === "string" && parentId.trim()
                 ? parentId.trim()
                 : undefined;
-        let requestMetadata = body.metadata;
+        let requestMetadata = normalizeSubmissionDeadlineMetadata(body.metadata);
         const continuedRunId = (requested) => internalContinuation === true &&
             typeof requested === "string" &&
             requested.trim().length <= 200
@@ -8248,10 +8285,7 @@ export function createProductionAgentHandler(options) {
         if (admittedQueuedMessage) {
             // A claim admits the persisted queue payload, not extra fields in this request.
             const promotionOptions = admittedQueuedMessage.options ?? {};
-            const promotionMetadata = {
-                ...(admittedQueuedMessage.metadata ?? {}),
-                ...(queuedPromotionRecord(promotionOptions.metadata) ?? {}),
-            };
+            const promotionMetadata = mergeQueuedPromotionMetadata(admittedQueuedMessage.metadata, promotionOptions.metadata);
             requestMessage = admittedQueuedMessage.text;
             agentKitMessageId = admittedQueuedMessage.id;
             requestDisplayMessage = admittedQueuedMessage.text;
@@ -8330,6 +8364,7 @@ export function createProductionAgentHandler(options) {
                         ? requestDisplayMessage
                         : requestMessage,
                     attachments: requestAttachments,
+                    ...submissionExpiryMetadata(requestMetadata),
                     ...(typeof queuedMessageId === "string" && queuedMessageId.trim()
                         ? { queuedMessageId: queuedMessageId.trim() }
                         : {}),
@@ -8715,6 +8750,7 @@ export function createProductionAgentHandler(options) {
                         ? requestDisplayMessage
                         : requestMessage,
                     attachments: requestAttachments,
+                    ...submissionExpiryMetadata(requestMetadata),
                     ...(typeof queuedMessageId === "string" && queuedMessageId.trim()
                         ? { queuedMessageId: queuedMessageId.trim() }
                         : {}),
@@ -9549,6 +9585,7 @@ export function createProductionAgentHandler(options) {
                     message: messageToPersist,
                     ...(agentKitMessageId ? { agentKitMessageId } : {}),
                     attachments: requestAttachments,
+                    ...submissionExpiryMetadata(requestMetadata),
                     ...(typeof queuedMessageId === "string" && queuedMessageId.trim()
                         ? { queuedMessageId: queuedMessageId.trim() }
                         : {}),

package/dist/agent/submission-deadline.d.ts

@@ -0,0 +1 @@
+export declare function normalizeSubmissionDeadlineMetadata(metadata: unknown, serverReceivedAt?: number): Record<string, unknown> | undefined;

package/dist/agent/submission-deadline.js

@@ -0,0 +1,27 @@
+import { AGENT_NATIVE_SUBMISSION_EXPIRES_AT_METADATA_KEY, AGENT_NATIVE_SUBMISSION_TTL_MS_METADATA_KEY, } from "@agent-native/agentkit/protocol";
+export function normalizeSubmissionDeadlineMetadata(metadata, serverReceivedAt = Date.now()) {
+    if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+        return undefined;
+    }
+    const record = metadata;
+    const custom = record.custom;
+    if (!custom || typeof custom !== "object" || Array.isArray(custom)) {
+        return record;
+    }
+    const customRecord = custom;
+    if (!Object.prototype.hasOwnProperty.call(customRecord, AGENT_NATIVE_SUBMISSION_TTL_MS_METADATA_KEY)) {
+        return record;
+    }
+    const ttlMs = customRecord[AGENT_NATIVE_SUBMISSION_TTL_MS_METADATA_KEY];
+    const expiresAt = typeof ttlMs === "number" &&
+        Number.isFinite(ttlMs) &&
+        ttlMs >= 0 &&
+        Number.isFinite(serverReceivedAt) &&
+        Number.isFinite(serverReceivedAt + ttlMs)
+        ? serverReceivedAt + ttlMs
+        : Number.NaN;
+    const normalizedCustom = { ...customRecord };
+    delete normalizedCustom[AGENT_NATIVE_SUBMISSION_TTL_MS_METADATA_KEY];
+    normalizedCustom[AGENT_NATIVE_SUBMISSION_EXPIRES_AT_METADATA_KEY] = expiresAt;
+    return { ...record, custom: normalizedCustom };
+}

package/dist/agent/thread-data-builder.d.ts

@@ -128,7 +128,7 @@ export declare function applySubmittedUserMessage(repo: any, userMessage: UserMe
     status: "submitted" | "already_submitted";
     repo: any;
 } | {
-    status: "already_claimed" | "claim_expired";
+    status: "already_claimed" | "claim_expired" | "submission_expired";
 };
 /**
  * Whether a stored user message is the prompt this run answers, rather than
@@ -150,6 +150,7 @@ export declare function buildUserMessage(opts: {
     turnId?: string;
     agentKitMessageId?: string;
     queuedMessageId?: string;
+    submissionExpiresAt?: unknown;
     createdAt?: Date;
     /** The turn was refused before a run started; its retry reads this back. */
     refusedRetry?: RefusedTurnRetryContext;

package/dist/agent/thread-data-builder.js

@@ -1,4 +1,4 @@
-import { parseAgentSuggestion, } from "@agent-native/agentkit/protocol";
+import { AGENT_NATIVE_SUBMISSION_EXPIRES_AT_METADATA_KEY, parseAgentSuggestion, } from "@agent-native/agentkit/protocol";
 import { formatChatErrorText, normalizeChatError, } from "../client/error-format.js";
 import { isCredentialGapCodeAgentEvent, normalizeCodeAgentTranscript, } from "../code-agents/transcript-normalizer.js";
 import { stripAgentChatContextFromMessage } from "../shared/agent-chat-context.js";
@@ -1252,11 +1252,8 @@ export function claimQueuedMessage(repo, messageId) {
     return pruneClaimedQueuedMessages(normalized);
 }
 export function applySubmittedUserMessage(repo, userMessage, queuedMessage) {
-    if (!queuedMessage) {
-        return { status: "submitted", repo: upsertUserMessage(repo, userMessage) };
-    }
     const userCustom = userMessage.metadata.custom;
-    const wasSubmitted = Array.isArray(repo?.messages)
+    const wasSubmitted = queuedMessage && Array.isArray(repo?.messages)
         ? repo.messages.some((entry) => {
             const outer = entry;
             const message = outer?.message ?? outer;
@@ -1274,12 +1271,41 @@ export function applySubmittedUserMessage(repo, userMessage, queuedMessage) {
                     userCustom?.submittedRunId);
         })
         : false;
-    if (wasSubmitted) {
+    if (wasSubmitted && queuedMessage) {
         return {
             status: "already_submitted",
             repo: claimQueuedMessage(repo, queuedMessage.id),
         };
     }
+    const submittedRunId = userCustom?.submittedRunId;
+    const wasDirectlySubmitted = !queuedMessage &&
+        typeof submittedRunId === "string" &&
+        submittedRunId.trim().length > 0 &&
+        Array.isArray(repo?.messages) &&
+        repo.messages.some((entry) => {
+            const message = getStoredMessage(entry);
+            const custom = message?.metadata?.custom;
+            return (message?.role === "user" &&
+                custom &&
+                typeof custom === "object" &&
+                !Array.isArray(custom) &&
+                custom.submittedRunId === submittedRunId);
+        });
+    if (wasDirectlySubmitted) {
+        return { status: "already_submitted", repo };
+    }
+    if (userCustom &&
+        Object.prototype.hasOwnProperty.call(userCustom, AGENT_NATIVE_SUBMISSION_EXPIRES_AT_METADATA_KEY)) {
+        const submissionExpiresAt = userCustom[AGENT_NATIVE_SUBMISSION_EXPIRES_AT_METADATA_KEY];
+        if (typeof submissionExpiresAt !== "number" ||
+            !Number.isFinite(submissionExpiresAt) ||
+            submissionExpiresAt <= Date.now()) {
+            return { status: "submission_expired" };
+        }
+    }
+    if (!queuedMessage) {
+        return { status: "submitted", repo: upsertUserMessage(repo, userMessage) };
+    }
     if (hasClaimedQueuedMessage(repo, queuedMessage.id)) {
         return { status: "already_claimed" };
     }
@@ -3136,6 +3162,11 @@ export function buildUserMessage(opts) {
                 ...(opts.queuedMessageId
                     ? { agentNativeQueuedMessageId: opts.queuedMessageId }
                     : {}),
+                ...(Object.prototype.hasOwnProperty.call(opts, "submissionExpiresAt")
+                    ? {
+                        [AGENT_NATIVE_SUBMISSION_EXPIRES_AT_METADATA_KEY]: opts.submissionExpiresAt,
+                    }
+                    : {}),
                 ...(opts.refusedRetry ? { [RUN_NOT_STARTED_METADATA_KEY]: true } : {}),
             },
         },

package/dist/authorization/check-action.js

@@ -1,6 +1,7 @@
 import { getDbExec } from "../db/client.js";
 import { getAppPermissionOverrides, getRegisteredAppRoles, resolveAppRole, } from "../org/app-roles.js";
-import { isWorkspaceAppAccessAllowed, WORKSPACE_APP_ACCESS_UNAVAILABLE, WORKSPACE_APP_ACCESS_UNAVAILABLE_MESSAGE, } from "../org/workspace-app-access.js";
+import { isWorkspaceAppAccessUnavailable, WORKSPACE_APP_ACCESS_UNAVAILABLE_MESSAGE, } from "../org/workspace-app-access-outcome.js";
+import { checkWorkspaceAppAccess } from "../org/workspace-app-access.js";
 import { resolveWorkspaceAccessAppId } from "../org/workspace-app-identity.js";
 import { ForbiddenError, resolveAccess } from "../sharing/access.js";
 import { ROLE_RANK } from "../sharing/schema.js";
@@ -66,12 +67,12 @@ export async function checkAction(config, args, ctx, target) {
         }
         const workspaceAppId = resolveWorkspaceAccessAppId(appId);
         const appAllowed = workspaceAppId
-            ? await isWorkspaceAppAccessAllowed(workspaceAppId, {
+            ? await checkWorkspaceAppAccess(workspaceAppId, {
                 email: identity.userEmail,
                 orgId: identity.orgId,
             })
             : true;
-        if (appAllowed === WORKSPACE_APP_ACCESS_UNAVAILABLE) {
+        if (isWorkspaceAppAccessUnavailable(appAllowed)) {
             throw Object.assign(new Error(WORKSPACE_APP_ACCESS_UNAVAILABLE_MESSAGE), {
                 statusCode: 503,
             });

package/dist/chat-threads/store.d.ts

@@ -255,6 +255,7 @@ export interface ThreadQueuedMessageMutationResult {
     message?: QueuedMessage;
     claimedMessage?: QueuedMessage;
     claimBusy?: boolean;
+    submissionExpired?: boolean;
     promotionBusy?: boolean;
     released?: boolean;
 }

package/dist/chat-threads/store.js

@@ -1,5 +1,6 @@
 import crypto from "node:crypto";
-import { parseQueueMessageInput, } from "@agent-native/agentkit/protocol";
+import { AGENT_NATIVE_SUBMISSION_EXPIRES_AT_METADATA_KEY, parseQueueMessageInput, } from "@agent-native/agentkit/protocol";
+import { normalizeSubmissionDeadlineMetadata } from "../agent/submission-deadline.js";
 import { extractThreadMeta, mergeThreadDataForClientSave, normalizeThreadRepository, normalizeThreadTitle, } from "../agent/thread-data-builder.js";
 import { failedRunIdsWithError, isRenderedRunNotStartedNotice, projectRootAssistantMessages, threadMessageRecord, } from "../agent/thread-message-projection.js";
 import { getDbExec } from "../db/client.js";
@@ -1259,9 +1260,30 @@ export async function setThreadEngineMeta(threadId, meta) {
     });
 }
 const QUEUED_MESSAGE_CLAIM_TTL_MS = 60_000;
+function queuedSubmissionExpired(message, now) {
+    const custom = message.metadata?.custom;
+    if (!custom ||
+        typeof custom !== "object" ||
+        Array.isArray(custom) ||
+        !Object.prototype.hasOwnProperty.call(custom, AGENT_NATIVE_SUBMISSION_EXPIRES_AT_METADATA_KEY)) {
+        return false;
+    }
+    const expiresAt = custom[AGENT_NATIVE_SUBMISSION_EXPIRES_AT_METADATA_KEY];
+    return (typeof expiresAt !== "number" ||
+        !Number.isFinite(expiresAt) ||
+        expiresAt <= now);
+}
 /** Applies a queue operation to the latest durable thread state on every CAS retry. */
 export async function mutateThreadQueuedMessages(threadId, mutation) {
     if (mutation.type === "append") {
+        const metadata = normalizeSubmissionDeadlineMetadata(mutation.message.metadata, Date.now());
+        mutation = {
+            type: "append",
+            message: {
+                ...mutation.message,
+                ...(metadata ? { metadata } : {}),
+            },
+        };
         try {
             assertNoInlineImageBytes({ type: "file", metadata: mutation.message.metadata }, "queuedMessage.metadata");
         }
@@ -1304,6 +1326,10 @@ export async function mutateThreadQueuedMessages(threadId, mutation) {
                 let response = {};
                 switch (mutation.type) {
                     case "append": {
+                        if (queuedSubmissionExpired(mutation.message, Date.now())) {
+                            response = { submissionExpired: true };
+                            break;
+                        }
                         const existing = current.find((message) => message.id === mutation.message.id);
                         const { promotionClaim: _claim, ...existingMessage } = existing ?? {};
                         if (existing &&
@@ -1320,7 +1346,8 @@ export async function mutateThreadQueuedMessages(threadId, mutation) {
                         const index = current.findIndex((message) => message.id === mutation.messageId);
                         const message = current[index];
                         if (message?.promotionClaim &&
-                            message.promotionClaim.expiresAt > Date.now()) {
+                            message.promotionClaim.expiresAt > Date.now() &&
+                            !queuedSubmissionExpired(message, Date.now())) {
                             response = { promotionBusy: true };
                             break;
                         }
@@ -1351,6 +1378,11 @@ export async function mutateThreadQueuedMessages(threadId, mutation) {
                         }
                         const message = current[index];
                         const now = Date.now();
+                        if (queuedSubmissionExpired(message, now)) {
+                            queuedMessages = current.filter((candidate) => candidate.id !== mutation.messageId);
+                            response = { submissionExpired: true };
+                            break;
+                        }
                         if (message.promotionClaim &&
                             message.promotionClaim.id !== mutation.claimId &&
                             message.promotionClaim.expiresAt > now) {

package/dist/client/agent-chat.d.ts

@@ -42,6 +42,8 @@ export interface AgentChatMessage {
      * {@link AGENT_CHAT_SUBMIT_RESULT_EVENT}. Auto-generated if omitted.
      */
     submitMessageId?: string;
+    /** Drop a queued submit instead of handing it to chat after this time. */
+    submissionExpiresAt?: number;
     usageLabel?: string;
     approvedToolCalls?: string[];
 }
@@ -176,6 +178,7 @@ export interface ParsedSubmitChat {
     attachments?: AgentChatAttachment[];
     requestMode?: AgentChatRequestMode;
     submitMessageId?: string;
+    submissionExpiresAt?: number;
     usageLabel?: string;
     approvedToolCalls?: string[];
 }

package/dist/client/agent-chat.js

@@ -747,11 +747,17 @@ export function parseSubmitChatMessage(event) {
     ].filter((image) => typeof image === "string" && image.trim().length > 0);
     const images = imageSources.length > 0 ? [...new Set(imageSources)] : undefined;
     const hasActionScope = Object.prototype.hasOwnProperty.call(raw, "actionScope");
+    const hasSubmissionExpiresAt = Object.prototype.hasOwnProperty.call(raw, "submissionExpiresAt");
     const actionScope = hasActionScope
         ? tryNormalizeAgentActionScope(raw.actionScope)
         : undefined;
     if (hasActionScope && !actionScope)
         return null;
+    if (hasSubmissionExpiresAt &&
+        (typeof raw.submissionExpiresAt !== "number" ||
+            !Number.isFinite(raw.submissionExpiresAt))) {
+        return null;
+    }
     return {
         message,
         context: typeof raw.context === "string" ? raw.context : undefined,
@@ -771,6 +777,9 @@ export function parseSubmitChatMessage(event) {
         attachments: parseSubmitChatAttachments(raw.attachments),
         requestMode: normalizeAgentChatRequestMode(raw.requestMode ?? raw.mode),
         submitMessageId: typeof raw.submitMessageId === "string" ? raw.submitMessageId : undefined,
+        ...(hasSubmissionExpiresAt
+            ? { submissionExpiresAt: raw.submissionExpiresAt }
+            : {}),
         usageLabel: nonEmptyString(raw.usageLabel),
         approvedToolCalls: parseSubmitChatApprovedToolCalls(raw.approvedToolCalls),
     };