@agent-native/core 0.214.0 → 0.217.0

package/dist/agent/production-agent.js

@@ -1,5 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
-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 { isDeepStrictEqual } from "node:util";
+import { AGENT_NATIVE_SUBMISSION_EXPIRES_AT_METADATA_KEY, AGENT_NATIVE_SUBMISSION_TTL_MS_METADATA_KEY, MAX_AGENT_REQUEST_ATTACHMENT_DATA_CHARS, parseQueueMessageInput, persistableFilePart, fingerprintAgentSubmissionAttachment, submissionAttachmentsMatch, } from "@agent-native/agentkit/protocol";
 import Ajv from "ajv";
 import Ajv2020 from "ajv/dist/2020.js";
 import { defineEventHandler, getHeader, setResponseHeader, setResponseStatus, getMethod, } from "h3";
@@ -22,6 +23,7 @@ import { describeAttachmentBytesVerdict, normalizeImageMediaType, reconcileImage
 import { formatBase64CharBudget, MAX_INLINE_FILE_BASE64_CHARS, MAX_INLINE_IMAGE_BASE64_CHARS, } from "../file-upload/inline-attachment-limits.js";
 import { claimOwnedAttachmentHydrationCandidate, createOwnedAttachmentHydrationBudget, describeOwnedImageReadFailure, hydrateOwnedImageUrl, } from "../file-upload/owned-attachment.js";
 import { preUploadAttachments } from "../file-upload/pre-upload-attachments.js";
+import { uploadFile } from "../file-upload/registry.js";
 import { canonicalImageReferenceUrl } from "../file-upload/thread-image-history.js";
 import { derivedTool, plainJsonSnapshot, UninterpretedSchema, UnusableSchemaError, usableInputSchema, } from "../json-schema/unusable-schema.js";
 import { assertUsableSchema } from "../json-schema/usable-schema.js";
@@ -87,7 +89,7 @@ import { maybeCompactThread, buildObservationalContext, hasObservationalMemory,
 import { ProcessorChain, TripWire, toolCallsFromContent, } from "./processors.js";
 import { applyUncheckedDefaultModelReplacement } from "./provider-model-selection.js";
 import { startRun, subscribeToRun, replayCompletedTurn, getActiveRunForThread, getActiveRunForThreadAsync, getRun, abortRun, abortRunDurably, abortRunAndTurnDurably, abortRunAtSafeBoundaryDurably, abortTurnByRefDurably, abortTurnDurably, getSlotHoldingRunId, tryClaimRunSlot, isHostedRuntime, resolveRunSoftTimeoutMs, resolveRunToolTimeoutCeilingMs, endsAfterToolResultWithoutAssistantFinal, endsDuringActionPreparation, } from "./run-manager.js";
-import { writeLedgerEntry, readLedgerEntry, beginAgentExecutionStep, completeAgentExecutionStep, markAgentExecutionStepDispatched, markAgentExecutionStepUnknown, recordLateAgentExecutionStepOutcome, clearLedgerForThread, AgentTurnInitiatorMismatchError, AgentTurnInitiatorUnavailableError, insertRun, insertRunEvent, isTurnAborted, markRunAborted, updateRunHeartbeat, updateRunStatusIfRunning, updateRunTerminalStateIfRunning, setRunError, setRunTerminalReason, claimBackgroundRun, readBackgroundRunClaim, recordRunDiagnostic, countRunsForTurn, RUN_DIAG_STAGE, UNCLAIMED_BACKGROUND_RUN_GRACE_MS, turnRunLedgerExhausted, } from "./run-store.js";
+import { writeLedgerEntry, readLedgerEntry, beginAgentExecutionStep, completeAgentExecutionStep, markAgentExecutionStepDispatched, markAgentExecutionStepUnknown, recordLateAgentExecutionStepOutcome, clearLedgerForThread, AgentTurnInitiatorMismatchError, AgentTurnInitiatorUnavailableError, insertRun, insertRunEvent, isRunAborted, isTurnAborted, markRunAborted, updateRunHeartbeat, updateRunStatusIfRunning, updateRunTerminalStateIfRunning, setRunError, setRunTerminalReason, claimBackgroundRun, readBackgroundRunClaim, recordRunDiagnostic, countRunsForTurn, RUN_DIAG_STAGE, UNCLAIMED_BACKGROUND_RUN_GRACE_MS, turnRunLedgerExhausted, } from "./run-store.js";
 import { buildCurrentTimeUserContext } from "./runtime-context.js";
 import { claimSetupResume, setupResumeRefusedRunId, } from "./setup-resume-claim.js";
 import { getStrictToolInputValidator } from "./strict-tool-input.js";
@@ -619,6 +621,34 @@ function runSlotBusy(event, activeRunId) {
         activeRunId,
     };
 }
+function queuedSubmissionResponse(event, message, activeRunId) {
+    setResponseStatus(event, 202);
+    setResponseHeader(event, "Content-Type", "application/json");
+    return {
+        state: "queued",
+        message,
+        ...(activeRunId ? { activeRunId } : {}),
+    };
+}
+const QUEUED_REASONING_EFFORTS = new Set(["none", "minimal", "low", "medium", "high", "xhigh"]);
+function effectiveQueuedRunOptions(options, model, effort, mode) {
+    const effective = options ? { ...options } : undefined;
+    let result = effective;
+    if (typeof model === "string" && model.trim()) {
+        result ??= {};
+        result.model = model;
+    }
+    if (typeof effort === "string" &&
+        QUEUED_REASONING_EFFORTS.has(effort)) {
+        result ??= {};
+        result.reasoningEffort = effort;
+    }
+    if (mode !== undefined) {
+        result ??= {};
+        result.mode = mode;
+    }
+    return result;
+}
 /**
  * The error a chat turn answers with when no model credential is usable. A
  * member whose org restricts personal API keys can't fix that by adding a key,
@@ -4606,6 +4636,31 @@ function notifyModelInputObserver(observer, messages) {
         // coercion-ok: observer failures cannot change agent execution.
     }
 }
+export function createRunSafeBoundaryGuards(input) {
+    return {
+        beforeModelDispatch: async (dispatch) => {
+            await input.flushEvents();
+            const interruptResult = await input.interruptRequestedAtBoundary();
+            if (input.signal.aborted || interruptResult !== "none") {
+                return { started: false };
+            }
+            return { started: true, value: dispatch() };
+        },
+        beforeWrite: async () => {
+            await input.flushEvents();
+            const interruptResult = await input.interruptRequestedAtBoundary();
+            if (input.signal.aborted || interruptResult !== "none") {
+                throw new Error("Run aborted at a safe boundary");
+            }
+        },
+    };
+}
+export async function confirmQueuedRunInterrupt(input) {
+    if (await input.abort())
+        return "aborted";
+    await input.defer();
+    return "pending";
+}
 export async function runAgentLoop(opts) {
     const { engine, systemPrompt: providedSystemPrompt, tools: providedTools, availableTools: providedAvailableTools, messages, actions, send, signal, } = opts;
     // Every audit row this loop writes reads from this: each action's own, and
@@ -8084,15 +8139,118 @@ async function readTurnStartedAt(threadId, turnId) {
     const startedAt = Number(raw);
     return Number.isFinite(startedAt) && startedAt > 0 ? startedAt : null;
 }
+function requestAttachmentIndexes(submission, attachments) {
+    const unmatched = new Set(attachments.map((_, index) => index));
+    for (const identity of submission.attachments ?? []) {
+        const match = [...unmatched].find((index) => fingerprintAgentSubmissionAttachment(attachments[index], "file") ===
+            identity.fingerprint);
+        if (match === undefined)
+            return null;
+        unmatched.delete(match);
+    }
+    const requestIndexes = new Set();
+    for (const identity of submission.requestAttachments ?? []) {
+        const match = [...unmatched].find((index) => attachments[index]?.type === "image" &&
+            fingerprintAgentSubmissionAttachment(attachments[index], "image") ===
+                identity.fingerprint);
+        if (match === undefined)
+            return null;
+        unmatched.delete(match);
+        requestIndexes.add(match);
+    }
+    return requestIndexes;
+}
+async function queueableAttachments(attachments, ownerEmail, requestAttachmentIndexes) {
+    const files = [];
+    const requestFiles = [];
+    for (const [index, attachment] of attachments.entries()) {
+        if (attachment.displayOnly === true)
+            continue;
+        if (attachment.type !== "image" &&
+            attachment.type !== "file" &&
+            attachment.type !== "document") {
+            return null;
+        }
+        if (typeof attachment.name !== "string") {
+            return null;
+        }
+        const record = attachment;
+        const mediaType = typeof attachment.contentType === "string" && attachment.contentType
+            ? attachment.contentType
+            : typeof attachment.mediaType === "string"
+                ? attachment.mediaType
+                : undefined;
+        const inlineData = typeof attachment.data === "string"
+            ? attachment.data
+            : typeof attachment.text === "string"
+                ? `data:${mediaType ?? "text/plain"};base64,${Buffer.from(attachment.text, "utf8").toString("base64")}`
+                : typeof attachment.url === "string" &&
+                    attachment.url.startsWith("data:")
+                    ? attachment.url
+                    : undefined;
+        let part = persistableFilePart({
+            type: "file",
+            name: attachment.name,
+            ...(mediaType ? { mediaType } : {}),
+            ...(typeof attachment.url === "string" ? { url: attachment.url } : {}),
+            ...(typeof record.fileId === "string"
+                ? { fileId: record.fileId }
+                : typeof record.id === "string"
+                    ? { fileId: record.id }
+                    : {}),
+        });
+        if (!part.fileId &&
+            inlineData &&
+            (!part.url || !record.uploadProvider || record.storageUploadFailed)) {
+            const parsedData = parseBase64DataUrl(inlineData);
+            if (parsedData) {
+                const uploaded = await uploadFile({
+                    data: new Uint8Array(Buffer.from(parsedData.data, "base64")),
+                    filename: attachment.name,
+                    mimeType: mediaType ?? parsedData.mediaType,
+                    ownerEmail: ownerEmail ?? undefined,
+                });
+                if (uploaded) {
+                    attachment.url = uploaded.url;
+                    attachment.uploadProvider = uploaded.provider;
+                    part = persistableFilePart({
+                        type: "file",
+                        name: attachment.name,
+                        ...(mediaType ? { mediaType } : {}),
+                        url: uploaded.url,
+                    });
+                }
+            }
+        }
+        if (requestAttachmentIndexes.has(index)) {
+            if (!part.url || !hasDurableAttachmentUrl(part.url))
+                return null;
+            const referenceUrl = attachment.referenceUrl;
+            if (referenceUrl && !hasDurableAttachmentUrl(referenceUrl))
+                return null;
+            requestFiles.push({
+                type: "image",
+                name: attachment.name,
+                ...(mediaType ? { contentType: mediaType } : {}),
+                url: part.url,
+                ...(referenceUrl ? { referenceUrl } : {}),
+            });
+            continue;
+        }
+        if (!part.url && !part.fileId)
+            return null;
+        files.push(part);
+    }
+    return { attachments: files, requestAttachments: requestFiles };
+}
 function queuedPromotionRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
         ? value
         : null;
 }
 function validateQueuedPromotionRequestAttachments(value) {
-    if (!Array.isArray(value) || value.length > MAX_AGENT_REQUEST_ATTACHMENTS) {
+    if (!Array.isArray(value))
         return null;
-    }
     let totalDataChars = 0;
     const attachments = [];
     for (const entry of value) {
@@ -8141,7 +8299,8 @@ function validateQueuedPromotionRequestAttachments(value) {
     }
     return attachments;
 }
-async function readAdmittedQueuedMessagePromotion(opts) {
+/** @internal exported for unit tests only */
+export async function readAdmittedQueuedMessagePromotion(opts) {
     const messageId = typeof opts.messageId === "string" ? opts.messageId.trim() : "";
     const claimId = typeof opts.claimId === "string" ? opts.claimId.trim() : "";
     if (!opts.ownerEmail ||
@@ -8197,6 +8356,9 @@ async function readAdmittedQueuedMessagePromotion(opts) {
     const options = hasOwn(queuedMessage, "options")
         ? queuedMessage.options
         : undefined;
+    const references = hasOwn(queuedMessage, "references")
+        ? queuedMessage.references
+        : undefined;
     if ((attachments !== undefined && !Array.isArray(attachments)) ||
         (Array.isArray(attachments) &&
             attachments.some((attachment) => {
@@ -8208,14 +8370,19 @@ async function readAdmittedQueuedMessagePromotion(opts) {
         (metadata !== undefined &&
             (!metadata || typeof metadata !== "object" || Array.isArray(metadata))) ||
         (options !== undefined &&
-            (!options || typeof options !== "object" || Array.isArray(options)))) {
+            (!options || typeof options !== "object" || Array.isArray(options))) ||
+        (references !== undefined && !Array.isArray(references))) {
         return null;
     }
+    parseQueueMessageInput({ ...queuedMessage, threadId: opts.threadId }, "queuedMessagePromotion", { allowLegacyQueueCount: true });
     return {
         id: messageId,
         text: queuedMessage.text,
         ...(Array.isArray(attachments) ? { attachments } : {}),
         ...(requestAttachments ? { requestAttachments } : {}),
+        ...(Array.isArray(references)
+            ? { references: references }
+            : {}),
         ...(metadata ? { metadata: metadata } : {}),
         ...(options ? { options: options } : {}),
     };
@@ -8302,6 +8469,7 @@ export function queuedPromotionAttachments(attachments, requestAttachments = [])
                 : {}),
             ...(data ? { data } : {}),
             ...(imageUrl ? { url: imageUrl } : {}),
+            ...(referenceUrl ? { referenceUrl } : {}),
             ...(fileId ? { id: fileId } : {}),
         };
         const replacementIndex = matchingIndex >= 0 && matchingIndex !== referenceIndex
@@ -8414,6 +8582,7 @@ export async function chainServerDrivenContinuation(opts) {
         recordRunDiagnostic: opts.deps?.recordRunDiagnostic ?? recordRunDiagnostic,
         markBackgroundContinuationChunkTerminal: opts.deps?.markBackgroundContinuationChunkTerminal ??
             markBackgroundContinuationChunkTerminal,
+        isRunAborted: opts.deps?.isRunAborted ?? isRunAborted,
         generateRunId: opts.deps?.generateRunId ?? generateRunId,
         sleep: opts.deps?.sleep ??
             ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
@@ -8497,9 +8666,20 @@ export async function chainServerDrivenContinuation(opts) {
     delete continuationBody.approvedToolCalls;
     delete continuationBody.approvedToolCallAskIds;
     delete continuationBody[AGENT_CHAT_BACKGROUND_RUN_FIELD];
+    const markRunsAbortedOrThrow = async (...runIds) => {
+        const results = await Promise.allSettled(runIds.map(async (targetRunId) => {
+            if (await d.markRunAborted(targetRunId, "user"))
+                return true;
+            return await d.isRunAborted(targetRunId);
+        }));
+        const failedRunIds = results.flatMap((result, index) => result.status === "fulfilled" && result.value ? [] : [runIds[index]]);
+        if (failedRunIds.length > 0) {
+            throw new Error(`Could not confirm durable abort for continuation run(s): ${failedRunIds.join(", ")}`);
+        }
+    };
     try {
         if (await d.isTurnAborted(effectiveThreadId, effectiveTurnId)) {
-            await d.markRunAborted(runId, "user").catch(() => { });
+            await markRunsAbortedOrThrow(runId);
             return;
         }
         await d
@@ -8527,9 +8707,7 @@ export async function chainServerDrivenContinuation(opts) {
             console.error("[agent-chat] continuation insertRun failed; dispatching with inline body:", insertErr instanceof Error ? insertErr.message : insertErr);
         }
         if (await d.isTurnAborted(effectiveThreadId, effectiveTurnId)) {
-            if (nextRowInserted)
-                await d.markRunAborted(nextRunId, "user").catch(() => { });
-            await d.markRunAborted(runId, "user").catch(() => { });
+            await markRunsAbortedOrThrow(...(nextRowInserted ? [nextRunId] : []), runId);
             return;
         }
         const continuationTerminalEvent = {
@@ -8544,6 +8722,11 @@ export async function chainServerDrivenContinuation(opts) {
         if (!terminalMarked) {
             throw new Error(`Could not release run ${runId} for continuation ${nextRunId}`);
         }
+        if (await d.isTurnAborted(effectiveThreadId, effectiveTurnId)) {
+            if (nextRowInserted)
+                await markRunsAbortedOrThrow(nextRunId);
+            return;
+        }
         run.continuationTerminalEvent = continuationTerminalEvent;
         const dispatchBody = nextRowInserted
             ? {
@@ -8775,7 +8958,7 @@ export function createProductionAgentHandler(options) {
                 return { error: "Invalid request body" };
             }
         }
-        const { message, history: submittedHistory = [], structuredHistory: submittedStructuredHistory, loadedSkillSlugs: requestedLoadedSkillSlugs, references: submittedReferences = [], threadId, attachments, displayMessage, parentId, queuedMessageId, queuedMessageClaimId, agentKitMessageId: requestedAgentKitMessageId, submissionPayload: requestedSubmissionPayload, internalContinuation: submittedInternalContinuation, autoContinueOfRunId: requestedAutoContinueOfRunId, continueOfRunId: requestedContinueOfRunId, turnId: requestTurnId, model: submittedModel, engine: submittedEngine, effort: submittedEffort, browserTabId, scope, harness: submittedHarness, trackInRunsTray, skipPendingSelectionContext, } = body;
+        const { message, history: submittedHistory = [], structuredHistory: submittedStructuredHistory, loadedSkillSlugs: requestedLoadedSkillSlugs, references: submittedReferences = [], threadId, attachments, displayMessage, parentId, queuedMessageId, queuedMessageClaimId, agentKitMessageId: requestedAgentKitMessageId, submissionPayload: requestedSubmissionPayload, internalContinuation: submittedInternalContinuation, autoContinueOfRunId: requestedAutoContinueOfRunId, continueOfRunId: requestedContinueOfRunId, turnId: requestTurnId, model: submittedModel, engine: submittedEngine, effort: submittedEffort, options: submittedRunOptions, browserTabId, scope, harness: submittedHarness, trackInRunsTray, skipPendingSelectionContext, } = body;
         let requestHistory = submittedHistory;
         let requestStructuredHistory = submittedStructuredHistory;
         let requestReferences = submittedReferences;
@@ -8784,6 +8967,11 @@ export function createProductionAgentHandler(options) {
         let requestModel = submittedModel;
         let requestEngine = submittedEngine;
         let requestEffort = submittedEffort;
+        let requestOptions = submittedRunOptions &&
+            typeof submittedRunOptions === "object" &&
+            !Array.isArray(submittedRunOptions)
+            ? submittedRunOptions
+            : undefined;
         let internalContinuation = submittedInternalContinuation;
         let requestHarness = submittedHarness;
         let requestSkipPendingSelectionContext = skipPendingSelectionContext;
@@ -8838,7 +9026,49 @@ export function createProductionAgentHandler(options) {
                 setResponseStatus(event, 400);
                 return { error: "submissionPayload does not match this message" };
             }
-            submissionPayload = candidate;
+            let validatedSubmissionPayload;
+            try {
+                validatedSubmissionPayload = parseQueueMessageInput({
+                    threadId: candidate.threadId,
+                    id: candidate.id,
+                    text: candidate.text,
+                    submissionPayload: candidate,
+                }, "submissionPayload").submissionPayload;
+            }
+            catch {
+                setResponseStatus(event, 400);
+                return { error: "Invalid submissionPayload" };
+            }
+            if (!validatedSubmissionPayload) {
+                setResponseStatus(event, 400);
+                return { error: "Invalid submissionPayload" };
+            }
+            submissionPayload = validatedSubmissionPayload;
+            if (validatedSubmissionPayload.text !==
+                (typeof message === "string" ? message : "") ||
+                !isDeepStrictEqual(validatedSubmissionPayload.references ?? [], submittedReferences) ||
+                !isDeepStrictEqual(validatedSubmissionPayload.options ?? {}, requestOptions ?? {})) {
+                setResponseStatus(event, 400);
+                return { error: "submissionPayload does not match this message" };
+            }
+        }
+        let requestMode = body.mode === "plan" || requestOptions?.mode === "plan" ? "plan" : "act";
+        requestOptions = effectiveQueuedRunOptions(requestOptions, requestModel, requestEffort, body.mode !== undefined || requestOptions?.mode !== undefined
+            ? requestMode
+            : undefined);
+        if (submissionPayload) {
+            const metadata = submissionPayload.metadata === undefined && requestEngine === undefined
+                ? undefined
+                : {
+                    ...submissionPayload.metadata,
+                    ...(requestEngine === undefined ? {} : { engine: requestEngine }),
+                };
+            submissionPayload = {
+                ...submissionPayload,
+                ...(requestOptions === undefined ? {} : { options: requestOptions }),
+                ...(metadata === undefined ? {} : { metadata }),
+            };
+            requestMetadata = normalizeSubmissionDeadlineMetadata(submissionPayload.metadata);
         }
         const backgroundRunMarker = preInjectedBody &&
             body[AGENT_CHAT_BACKGROUND_RUN_FIELD] &&
@@ -8942,7 +9172,6 @@ export function createProductionAgentHandler(options) {
             requestRunCtx.chatScope = requestChatScope;
             requestRunCtx.isBackgroundWorker = isBackgroundWorker;
         }
-        let requestMode = body.mode === "plan" ? "plan" : "act";
         const hasMessageText = typeof message === "string" && message.trim().length > 0;
         let hasAttachments = Array.isArray(attachments) && attachments.length > 0;
         if (!hasMessageText && !hasAttachments) {
@@ -8951,6 +9180,19 @@ export function createProductionAgentHandler(options) {
         }
         let requestMessage = hasMessageText ? message : "Use the attached context.";
         let requestAttachments = Array.isArray(attachments) ? attachments : [];
+        const submissionAttachmentsAreConsistent = submissionPayload !== undefined &&
+            submissionAttachmentsMatch(submissionPayload, requestAttachments);
+        if (submissionPayload && !submissionAttachmentsAreConsistent) {
+            setResponseStatus(event, 400);
+            return { error: "submissionPayload does not match this message" };
+        }
+        const submissionRequestAttachmentIndexes = submissionPayload
+            ? requestAttachmentIndexes(submissionPayload, requestAttachments)
+            : new Set();
+        if (!submissionRequestAttachmentIndexes) {
+            setResponseStatus(event, 400);
+            return { error: "submissionPayload does not match this message" };
+        }
         let attachmentHydrationBudget;
         let requestDisplayMessage = displayMessage;
         let requestContext = buildRecentUserRequestContext({
@@ -8969,6 +9211,211 @@ export function createProductionAgentHandler(options) {
                 anonymous: runRequestContext?.agentRunAnonymous === true,
             }
             : undefined;
+        const busySubmissionQueueEligible = Boolean(submissionPayload &&
+            agentKitMessageId &&
+            threadId &&
+            ownerEmail &&
+            !internalContinuation &&
+            !continueOf &&
+            !queuedMessageId &&
+            !queuedMessageClaimId &&
+            !isBackgroundWorker &&
+            submittedInternalContinuation !== true &&
+            typeof requestedAutoContinueOfRunId !== "string" &&
+            typeof requestedContinueOfRunId !== "string" &&
+            !hasOwn(body, "approvedToolCalls") &&
+            !hasOwn(body, "approvedToolCallAskIds") &&
+            !hasOwn(body, "resume"));
+        const busySubmissionAttachmentsAreQueueable = requestAttachments.every((attachment) => attachment.displayOnly === true ||
+            ((attachment.type === "image" ||
+                attachment.type === "file" ||
+                attachment.type === "document") &&
+                typeof attachment.name === "string"));
+        const tryAdmitBusySubmission = async () => {
+            if (!submissionPayload ||
+                !agentKitMessageId ||
+                !threadId ||
+                !ownerEmail ||
+                internalContinuation ||
+                continueOf ||
+                queuedMessageId ||
+                queuedMessageClaimId ||
+                isBackgroundWorker ||
+                submittedInternalContinuation === true ||
+                typeof requestedAutoContinueOfRunId === "string" ||
+                typeof requestedContinueOfRunId === "string" ||
+                hasOwn(body, "approvedToolCalls") ||
+                hasOwn(body, "approvedToolCallAskIds") ||
+                hasOwn(body, "resume")) {
+                return null;
+            }
+            const { resolveThreadAccess } = await import("../chat-threads/store.js");
+            const accessibleThread = await resolveThreadAccess(ownerEmail, threadId, "editor", { orgId: getRequestOrgId() ?? undefined });
+            if (!accessibleThread) {
+                setResponseStatus(event, 404);
+                return { error: "Thread not found" };
+            }
+            const attachmentsForQueue = await queueableAttachments(requestAttachments, ownerEmail, submissionRequestAttachmentIndexes);
+            if (!attachmentsForQueue) {
+                if (requestAttachments.some((attachment) => attachment.displayOnly !== true &&
+                    (attachment.type === "image" ||
+                        attachment.type === "file" ||
+                        attachment.type === "document"))) {
+                    setResponseStatus(event, 503);
+                    return {
+                        error: "The attachment could not be saved for later delivery",
+                        code: "queued_attachment_reference_unavailable",
+                        retryable: true,
+                    };
+                }
+                return null;
+            }
+            const queueText = typeof message === "string" && message.trim()
+                ? message
+                : "Use the attached context.";
+            let parsedMessage;
+            try {
+                parsedMessage = parseQueueMessageInput({
+                    threadId,
+                    id: agentKitMessageId,
+                    text: queueText,
+                    ...(attachmentsForQueue.attachments.length
+                        ? { attachments: attachmentsForQueue.attachments }
+                        : {}),
+                    ...(attachmentsForQueue.requestAttachments.length
+                        ? { requestAttachments: attachmentsForQueue.requestAttachments }
+                        : {}),
+                    ...(submittedReferences.length
+                        ? { references: submittedReferences }
+                        : {}),
+                    ...(requestMetadata ? { metadata: requestMetadata } : {}),
+                    ...(requestOptions ? { options: requestOptions } : {}),
+                    ...(submissionPayload.interruptActiveRun === true
+                        ? { interruptActiveRun: true }
+                        : {}),
+                }, "agentChatSubmission");
+            }
+            catch {
+                setResponseStatus(event, 400);
+                return {
+                    error: "This submission cannot be saved for later delivery",
+                    code: "queued_submission_invalid",
+                    retryable: false,
+                };
+            }
+            if (!parsedMessage.text.trim()) {
+                setResponseStatus(event, 400);
+                return {
+                    error: "This submission cannot be saved for later delivery",
+                    code: "queued_submission_invalid",
+                    retryable: false,
+                };
+            }
+            const { mutateThreadQueuedMessages, QueuedSubmissionAdmissionError } = await import("../chat-threads/store.js");
+            const requestContext = getRequestContext();
+            const actor = {
+                email: requestContext?.userEmail ?? ownerEmail,
+                ...(requestContext?.authUserId
+                    ? { authUserId: requestContext.authUserId }
+                    : {}),
+                ...(requestContext?.identityAuthenticatedAtMs !== undefined
+                    ? {
+                        identityAuthenticatedAtMs: requestContext.identityAuthenticatedAtMs,
+                    }
+                    : {}),
+                ...(requestContext?.userName ? { name: requestContext.userName } : {}),
+                orgId: requestContext?.orgId ?? null,
+                orgScope: requestContext?.orgScope ?? null,
+                anonymous: requestContext?.agentRunAnonymous === true,
+            };
+            const queuedMessage = {
+                ...parsedMessage,
+                id: agentKitMessageId,
+                threadId,
+                createdAt: new Date().toISOString(),
+                ...(attachmentsForQueue.attachments.length
+                    ? { attachments: attachmentsForQueue.attachments }
+                    : {}),
+                ...(attachmentsForQueue.requestAttachments.length
+                    ? { requestAttachments: attachmentsForQueue.requestAttachments }
+                    : {}),
+            };
+            let result;
+            try {
+                result = await mutateThreadQueuedMessages(threadId, {
+                    type: "append",
+                    message: queuedMessage,
+                    hashInput: submissionPayload,
+                }, { actor });
+            }
+            catch (error) {
+                if (!(error instanceof QueuedSubmissionAdmissionError))
+                    throw error;
+                setResponseStatus(event, 409);
+                return {
+                    error: "This message ID is no longer available for submission",
+                    code: error.code,
+                    retryable: false,
+                };
+            }
+            if (!result)
+                return null;
+            if (result.receiptUnavailable) {
+                setResponseStatus(event, 503);
+                return {
+                    error: "The queued submission receipt could not be saved",
+                    code: "queued_submission_receipt_unavailable",
+                    retryable: true,
+                };
+            }
+            if (result.receiptConflict) {
+                setResponseStatus(event, 409);
+                return {
+                    error: "This message ID was already used for a different submission",
+                    code: "queued_message_id_conflict",
+                    retryable: false,
+                };
+            }
+            if (result.submissionExpired) {
+                setResponseStatus(event, 409);
+                return {
+                    error: "This submission expired before it could be queued",
+                    code: "submission_expired",
+                    retryable: false,
+                };
+            }
+            if (result.alreadySubmitted && result.submittedRunId) {
+                const stream = subscribeToRun(result.submittedRunId, 0);
+                if (!stream) {
+                    setResponseStatus(event, 503);
+                    return {
+                        error: "The accepted submission run is no longer replayable",
+                        code: "queued_message_run_unavailable",
+                        retryable: true,
+                    };
+                }
+                setResponseHeader(event, "Content-Type", "text/event-stream");
+                setResponseHeader(event, "Cache-Control", "no-cache");
+                setResponseHeader(event, "Connection", "keep-alive");
+                setResponseHeader(event, "X-Run-Id", result.submittedRunId);
+                setResponseHeader(event, "X-Dispatch-Mode", "replay");
+                return stream;
+            }
+            if (!result.message) {
+                setResponseStatus(event, 503);
+                return {
+                    error: "The queued submission receipt could not be read",
+                    code: "queued_submission_receipt_unavailable",
+                    retryable: true,
+                };
+            }
+            return queuedSubmissionResponse(event, {
+                ...result.message,
+                id: agentKitMessageId,
+                threadId,
+                createdAt: result.message.createdAt ?? queuedMessage.createdAt,
+            }, await getSlotHoldingRunId(threadId));
+        };
         if (submissionPayload &&
             ownerEmail &&
             threadId &&
@@ -8976,7 +9423,7 @@ export function createProductionAgentHandler(options) {
             !queuedMessageId &&
             !queuedMessageClaimId &&
             !isBackgroundWorker) {
-            const { getQueuedSubmissionReceipt, hashQueuedSubmissionPayload, resolveThreadAccess, } = await import("../chat-threads/store.js");
+            const { getQueuedSubmissionReceipt, getQueuedSubmissionReceiptStatus, hashQueuedSubmissionPayload, resolveThreadAccess, } = await import("../chat-threads/store.js");
             const receipt = await getQueuedSubmissionReceipt(threadId, String(submissionPayload.id));
             if (receipt) {
                 const accessibleThread = await resolveThreadAccess(ownerEmail, threadId, "editor", { orgId: getRequestOrgId() ?? undefined });
@@ -9002,8 +9449,23 @@ export function createProductionAgentHandler(options) {
                         retryable: false,
                     };
                 }
-                if (receipt.state === "submitted") {
-                    if (!receipt.submittedRunId) {
+                let receiptState = receipt.state;
+                let submittedRunId = receipt.submittedRunId;
+                if (receipt.state === "queued") {
+                    const status = await getQueuedSubmissionReceiptStatus(threadId, receipt.messageId);
+                    if (!status) {
+                        setResponseStatus(event, 503);
+                        return {
+                            error: "The queued submission receipt could not be read",
+                            code: "queued_submission_receipt_unavailable",
+                            retryable: true,
+                        };
+                    }
+                    receiptState = status.state;
+                    submittedRunId = status.submittedRunId;
+                }
+                if (receiptState === "submitted") {
+                    if (!submittedRunId) {
                         setResponseStatus(event, 503);
                         return {
                             error: "The accepted submission has no replayable run",
@@ -9011,7 +9473,7 @@ export function createProductionAgentHandler(options) {
                             retryable: true,
                         };
                     }
-                    const stream = subscribeToRun(receipt.submittedRunId, 0);
+                    const stream = subscribeToRun(submittedRunId, 0);
                     if (!stream) {
                         setResponseStatus(event, 503);
                         return {
@@ -9023,12 +9485,26 @@ export function createProductionAgentHandler(options) {
                     setResponseHeader(event, "Content-Type", "text/event-stream");
                     setResponseHeader(event, "Cache-Control", "no-cache");
                     setResponseHeader(event, "Connection", "keep-alive");
-                    setResponseHeader(event, "X-Run-Id", receipt.submittedRunId);
+                    setResponseHeader(event, "X-Run-Id", submittedRunId);
                     setResponseHeader(event, "X-Dispatch-Mode", "replay");
                     return stream;
                 }
-                if (receipt.state === "queued") {
-                    return runSlotBusy(event, null);
+                if (receiptState === "queued") {
+                    if (!receipt.message) {
+                        setResponseStatus(event, 503);
+                        return {
+                            error: "The queued submission receipt has no replayable message",
+                            code: "queued_submission_receipt_unavailable",
+                            retryable: true,
+                        };
+                    }
+                    return queuedSubmissionResponse(event, {
+                        ...receipt.message,
+                        id: receipt.messageId,
+                        threadId,
+                        createdAt: receipt.message.createdAt ??
+                            new Date(receipt.createdAt).toISOString(),
+                    }, await getSlotHoldingRunId(threadId));
                 }
                 setResponseStatus(event, 409);
                 return {
@@ -9153,6 +9629,9 @@ export function createProductionAgentHandler(options) {
                 retryable: false,
             };
         }
+        const isAuthorizedApprovalContinuation = Boolean(submittedInternalContinuation === true &&
+            requestedApprovedToolCallAskIds?.length &&
+            resolvedApprovalTurnId);
         // The continuation marker is client-controlled. Defer setup admission only
         // for automatic successors when the named stop and turn can be checked
         // under the run-slot lock. A user's manual Continue starts new work and
@@ -9184,7 +9663,8 @@ export function createProductionAgentHandler(options) {
             requestDisplayMessage = admittedQueuedMessage.text;
             requestAttachments = queuedPromotionAttachments(admittedQueuedMessage.attachments ?? [], admittedQueuedMessage.requestAttachments);
             hasAttachments = requestAttachments.length > 0;
-            requestReferences = [];
+            requestReferences = admittedQueuedMessage.references ?? [];
+            requestOptions = promotionOptions;
             requestHistory = [];
             requestStructuredHistory = undefined;
             internalContinuation = false;
@@ -9217,6 +9697,7 @@ export function createProductionAgentHandler(options) {
             mutableBody.history = requestHistory;
             delete mutableBody.structuredHistory;
             mutableBody.metadata = requestMetadata;
+            mutableBody.options = requestOptions;
             mutableBody.model = requestModel;
             if (requestEngine === undefined) {
                 delete mutableBody.engine;
@@ -9231,7 +9712,6 @@ export function createProductionAgentHandler(options) {
             delete mutableBody.continueOfRunId;
             delete mutableBody.harness;
             delete mutableBody.parentId;
-            delete mutableBody.options;
             delete mutableBody.skipPendingSelectionContext;
         }
         const recordUnstartedTurn = async (failure) => {
@@ -9301,6 +9781,14 @@ export function createProductionAgentHandler(options) {
             }
         }
         setupMark("aiGate");
+        if (hasOwn(body, "queuedMessageClaimId") && !admittedQueuedMessage) {
+            setResponseStatus(event, 409);
+            return {
+                error: "This queued message can no longer be promoted",
+                code: "queued_message_claim_invalid",
+                retryable: false,
+            };
+        }
         const contextPrefetchDeadlineAt = Date.now() + 1_300;
         const preparedRequest = await options.prepareRequest?.({
             event,
@@ -9489,18 +9977,23 @@ export function createProductionAgentHandler(options) {
             }
         }
         workerStep("db_request_ctx");
+        if (hasAttachments &&
+            threadId &&
+            !isBackgroundWorker &&
+            requestAttachments.some((attachment) => attachment.displayOnly !== true &&
+                (attachment.type === "image" ||
+                    attachment.type === "file" ||
+                    attachment.type === "document"))) {
+            const activeRunId = await getSlotHoldingRunId(threadId);
+            if (activeRunId &&
+                (!busySubmissionQueueEligible || !busySubmissionAttachmentsAreQueueable)) {
+                return runSlotBusy(event, activeRunId);
+            }
+        }
         workerStep("attach_start");
         if (hasAttachments &&
             requestAttachments.some((a) => a.displayOnly !== true &&
                 (a.type === "image" || a.type === "file" || a.type === "document"))) {
-            // A busy thread refuses this message (409) and the client sends it again
-            // once the thread frees up; uploading first would store every
-            // attachment again on each refusal.
-            if (threadId && !isBackgroundWorker) {
-                const activeRunId = await getSlotHoldingRunId(threadId);
-                if (activeRunId)
-                    return runSlotBusy(event, activeRunId);
-            }
             try {
                 attachmentHydrationBudget ??= createOwnedAttachmentHydrationBudget();
                 const preUpload = await preUploadAttachments({
@@ -9521,6 +10014,15 @@ export function createProductionAgentHandler(options) {
                     ? `${requestMessage}\n\n${describeAttachmentPreUploadWarning()}`
                     : describeAttachmentPreUploadWarning();
             }
+            if (threadId && !isBackgroundWorker) {
+                const activeRunId = await getSlotHoldingRunId(threadId);
+                if (activeRunId) {
+                    const queued = await tryAdmitBusySubmission();
+                    if (queued !== null)
+                        return queued;
+                    return runSlotBusy(event, activeRunId);
+                }
+            }
         }
         const textAttachmentResourceMap = new Map();
         if (hasAttachments && threadId) {
@@ -10273,6 +10775,11 @@ export function createProductionAgentHandler(options) {
             }
             let slot;
             try {
+                const runThreadId = threadId;
+                const shouldPreserveQueuedOrder = Boolean(!isAuthorizedApprovalContinuation &&
+                    !queuedMessageId &&
+                    !queuedMessageClaimId &&
+                    !isBackgroundWorker);
                 slot = await tryClaimRunSlot(threadId, runId, undefined, {
                     turnId: effectiveTurnId,
                     ...(turnInitiator ? { turnInitiator } : {}),
@@ -10288,6 +10795,14 @@ export function createProductionAgentHandler(options) {
                         ? { dispatchPayload: durableDispatchPayload }
                         : {}),
                     ...(continueOf ? { continueOf } : {}),
+                    ...(shouldPreserveQueuedOrder
+                        ? {
+                            hasPendingQueuedSubmission: async (tx) => {
+                                const { hasPendingQueuedSubmissionReceipt } = await import("../chat-threads/store.js");
+                                return hasPendingQueuedSubmissionReceipt(tx, runThreadId);
+                            },
+                        }
+                        : {}),
                 });
             }
             catch (error) {
@@ -10323,6 +10838,15 @@ export function createProductionAgentHandler(options) {
             }
             if (!slot.claimed) {
                 await setupResumeClaim?.release();
+                if (slot.queuedSubmissionPending) {
+                    const queued = await tryAdmitBusySubmission();
+                    if (queued !== null)
+                        return queued;
+                    return runSlotBusy(event, null);
+                }
+                const queued = await tryAdmitBusySubmission();
+                if (queued !== null)
+                    return queued;
                 return runSlotBusy(event, slot.activeRunId);
             }
             foregroundRunRowInserted = true;
@@ -10891,6 +11415,77 @@ export function createProductionAgentHandler(options) {
                 rawSend(event);
                 updateTrackedProgressFromEvent(event);
             };
+            const interruptQueuedRunAtBoundary = async () => {
+                if (!threadId)
+                    return "none";
+                const { clearQueuedSubmissionInterruptRun, listQueuedSubmissionReceipts, mutateThreadQueuedMessages, recordQueuedSubmissionInterruptRun, retryQueuedSubmissionReceipt, } = await import("../chat-threads/store.js");
+                const pending = await listQueuedSubmissionReceipts({
+                    limit: 25,
+                    threadId,
+                    interruptActiveRun: true,
+                });
+                for (const receipt of pending) {
+                    if (receipt.message?.interruptActiveRun !== true)
+                        continue;
+                    const claimId = randomUUID();
+                    let claimed = false;
+                    try {
+                        const claim = await mutateThreadQueuedMessages(threadId, {
+                            type: "claimFromInbox",
+                            receipt,
+                            claimId,
+                        });
+                        if (!claim?.claimedMessage)
+                            continue;
+                        claimed = true;
+                        if (receipt.interruptRunId &&
+                            receipt.interruptRunId !== runId) {
+                            const { getRunById } = await import("./run-store.js");
+                            const interruptedRun = await getRunById(receipt.interruptRunId);
+                            if (interruptedRun?.status === "running")
+                                continue;
+                            const cleared = await clearQueuedSubmissionInterruptRun({
+                                threadId,
+                                messageId: receipt.messageId,
+                                runId: receipt.interruptRunId,
+                                claimId,
+                            });
+                            if (!cleared)
+                                continue;
+                        }
+                        if (!(await recordQueuedSubmissionInterruptRun({
+                            threadId,
+                            messageId: receipt.messageId,
+                            runId,
+                            claimId,
+                        }))) {
+                            continue;
+                        }
+                        const aborted = await confirmQueuedRunInterrupt({
+                            abort: () => abortRunAtSafeBoundaryDurably(runId, "user"),
+                            defer: () => retryQueuedSubmissionReceipt(threadId, receipt.messageId, Date.now() + 10_000, { claimId }),
+                        });
+                        if (aborted === "pending")
+                            return "pending";
+                    }
+                    finally {
+                        if (claimed) {
+                            await mutateThreadQueuedMessages(threadId, {
+                                type: "release",
+                                messageId: receipt.messageId,
+                                claimId,
+                            });
+                        }
+                    }
+                    return "aborted";
+                }
+                return "none";
+            };
+            const { beforeModelDispatch, beforeWrite } = createRunSafeBoundaryGuards({
+                signal,
+                flushEvents: control.flushEvents,
+                interruptRequestedAtBoundary: interruptQueuedRunAtBoundary,
+            });
             if (selfChainBudget?.skipToBoundary) {
                 await recordRunDiagnostic(runId, RUN_DIAG_STAGE.workerSetupStep, `self_chain_budget_exhausted elapsed=${Date.now() - setupT0}ms`).catch(() => { });
                 send({ type: "auto_continue", reason: "run_timeout" });
@@ -10988,7 +11583,8 @@ export function createProductionAgentHandler(options) {
                             threadId: effectiveThreadId,
                             turnId: effectiveTurnId,
                             durableStepIdForToolCall: namespacedDurableStepId,
-                            beforeWrite: control.flushEvents,
+                            beforeModelDispatch,
+                            beforeWrite,
                             unknownOutcomes,
                             internalContinuation,
                             ...(shouldRecoverCompletedExecutionSteps
@@ -11161,7 +11757,8 @@ export function createProductionAgentHandler(options) {
                     : {}),
                 systemSections: contextXraySystemSections,
                 actions: requestActions,
-                beforeWrite: control.flushEvents,
+                beforeModelDispatch,
+                beforeWrite,
                 unknownOutcomes,
                 internalContinuation,
                 send,