@agents24/react 0.2.11 → 0.2.13

package/compatibility.json

@@ -1,5 +1,5 @@
 {
-  "contractHash": "37437aff006eec5ea404f4259bf2e8cb0ba442ecc5aa72b4d39964530899d58a",
+  "contractHash": "0394b689ce7604b444b11c8792050fae0c1da4233d6b318d22832c3b89516a4a",
   "contractVersion": "0.3.0",
   "corpus": "conformance/v1/corpus.json",
   "generatedBy": "@agents24/sdk-contract",
@@ -15,11 +15,11 @@
       "reactDom": ">=19 <20"
     },
     "@agents24/client": {
-      "contract": "37437aff006eec5ea404f4259bf2e8cb0ba442ecc5aa72b4d39964530899d58a",
+      "contract": "0394b689ce7604b444b11c8792050fae0c1da4233d6b318d22832c3b89516a4a",
       "runtime": "run-stream.v3"
     },
     "@agents24/node": {
-      "contract": "37437aff006eec5ea404f4259bf2e8cb0ba442ecc5aa72b4d39964530899d58a",
+      "contract": "0394b689ce7604b444b11c8792050fae0c1da4233d6b318d22832c3b89516a4a",
       "node": "^22.0.0 || ^24.0.0"
     },
     "@agents24/react": {
@@ -27,11 +27,11 @@
       "react": ">=19 <20"
     },
     "@talmudpedia/runtime-sdk": {
-      "contract": "37437aff006eec5ea404f4259bf2e8cb0ba442ecc5aa72b4d39964530899d58a",
+      "contract": "0394b689ce7604b444b11c8792050fae0c1da4233d6b318d22832c3b89516a4a",
       "protocolOwner": "@agents24/client"
     },
     "agents24": {
-      "contract": "37437aff006eec5ea404f4259bf2e8cb0ba442ecc5aa72b4d39964530899d58a",
+      "contract": "0394b689ce7604b444b11c8792050fae0c1da4233d6b318d22832c3b89516a4a",
       "python": ">=3.10"
     }
   },

package/dist/index.js

@@ -379,7 +379,8 @@ function threadDetailToMessages(detail) {
         runId,
         content: assistantText,
         createdAt: text(turn.completed_at) || createdAt,
-        isFinal: !["queued", "running", "paused", "cancelling"].includes(String(turn.status || "").toLowerCase()),
+        responseCompletion: item.response_completion,
+        isFinal: Boolean(item.response_completion) || !["queued", "running", "paused", "cancelling"].includes(String(turn.status || "").toLowerCase()),
         feedback,
         parts: assistantParts,
         messageIndex: typeof turn.turn_index === "number" ? turn.turn_index : index
@@ -392,12 +393,14 @@ function threadTimelineToMessages(items, detail) {
   const feedbackByRun = new Map((detail?.turns || []).flatMap((turn) => turn.run_id && turn.feedback ? [[turn.run_id, turn.feedback]] : []));
   return items.map((item) => ({
     id: item.id,
+    clientSubmissionId: item.client_submission_id || void 0,
     role: item.role,
     runId: item.run_id,
     segmentIndex: item.segment_index,
     content: item.text,
     createdAt: item.created_at,
     isFinal: item.status === "completed" || item.status === "delivered",
+    responseCompletion: item.response_completion,
     parts: item.role === "assistant" ? partsFromResponseBlocks(item.response_blocks, item.text, `${item.id}-text`) : item.text ? [{ id: `${item.id}-text`, type: "text", kind: "text", text: item.text }] : [],
     attachments: item.role === "user" ? item.attachment_ids.map((id) => {
       const descriptor = item.attachments?.find((attachment) => attachment.id === id);
@@ -602,7 +605,7 @@ function appendStableStreamingTurn(messages, userMessage, assistantMessage) {
 }
 function preserveMountedMessageIds(canonical, current) {
   return canonical.map((message) => {
-    const mounted = current.find((item) => item.role === message.role && (item.durableId === message.id || item.id === message.id || message.role === "assistant" && message.segmentIndex === 1 && item.runId && item.runId === message.runId && !item.durableId));
+    const mounted = current.find((item) => item.role === message.role && (item.durableId === message.id || item.id === message.id || Boolean(message.clientSubmissionId && item.clientSubmissionId === message.clientSubmissionId) || message.role === "assistant" && message.segmentIndex === 1 && item.runId && item.runId === message.runId && !item.durableId));
     return mounted && mounted.id !== message.id ? { ...message, id: mounted.id, durableId: message.id } : message;
   });
 }
@@ -612,15 +615,15 @@ function reconcileThreadTimeline(current, canonical, activeRunId, streamingMessa
   const retained = current.filter((message) => !canonicalIds.has(message.id) && (message.isFinal || activeRunId && (!message.runId || message.runId === activeRunId)));
   const reconciled = mounted.map((message) => {
     const live = current.find((item) => item.id === message.id);
-    return activeRunId && live?.role === "assistant" && live.runId === activeRunId && (live.id === streamingMessageId || !live.isFinal) ? { ...message, ...live, durableId: message.durableId || live.durableId } : message;
+    return activeRunId && live?.role === "assistant" && live.runId === activeRunId && (live.id === streamingMessageId || !live.isFinal || live.responseCompletion) ? message.responseCompletion && !live.responseCompletion ? { ...message, id: live.id, durableId: message.durableId || live.durableId } : { ...message, ...live, durableId: message.durableId || live.durableId } : message;
   });
   return [...retained, ...reconciled];
 }
 function promoteThreadMessage(current, message, runId) {
   const promoted = { ...message, runId, isFinal: true };
-  const index = current.findIndex((item) => item.id === message.id || item.durableId === message.id);
-  if (index < 0) return [...current, promoted];
-  return current.map((item, itemIndex) => itemIndex === index ? { ...item, ...promoted, id: item.id, durableId: item.id === message.id ? item.durableId : message.id } : item);
+  const index = current.findIndex((item) => item.id === message.id || item.durableId === message.id || Boolean(message.clientSubmissionId && item.clientSubmissionId === message.clientSubmissionId));
+  if (index < 0) return [...current, message.clientSubmissionId ? { ...promoted, id: message.clientSubmissionId, durableId: message.id } : promoted];
+  return current.map((item, itemIndex) => itemIndex === index ? { ...item, ...promoted, id: item.id, durableId: item.id === message.id ? item.durableId : message.id } : message.clientSubmissionId && item.role === "assistant" && item.id === `${current[index].id}:assistant` ? { ...item, runId } : item);
 }
 function upsertStableAssistantMessage(messages, input) {
   const next = [...messages];
@@ -659,7 +662,7 @@ function reconcileModelTurnParts(parts, event) {
   const terminal = eventName === "run.completed" || eventName === "run.failed" || eventName === "run.cancelled";
   const modelTurnId = typeof payload.model_turn_id === "string" ? payload.model_turn_id : null;
   let next = parts;
-  if (eventName === "run.snapshot" || terminal) {
+  if (eventName === "run.snapshot" || eventName === "assistant.completed" || terminal) {
     next = next.filter((part) => part.kind !== "model-turn");
   } else if (eventName === "assistant.delta" && typeof payload.content === "string" && payload.content) {
     next = next.filter((part) => part.kind !== "model-turn" || part.turnKind !== "agent");
@@ -677,17 +680,20 @@ function applyRuntimeEvent(state, event) {
     let optimisticIndex = -1;
     for (let index = state.messages.length - 1; index >= 0; index -= 1) {
       const message = state.messages[index];
-      if (message.role === "user" && !message.runId && !message.durableId) {
+      if (message.role === "user" && (event.payload.client_submission_id ? message.clientSubmissionId === event.payload.client_submission_id : !message.runId && !message.durableId)) {
         optimisticIndex = index;
         break;
       }
     }
     if (optimisticIndex >= 0) {
-      state = { ...state, messages: state.messages.map((message, index) => index === optimisticIndex ? { ...message, durableId: messageId2, runId: event.run_id } : message.role === "assistant" && !message.runId ? { ...message, runId: event.run_id } : message) };
+      const assistantId = event.payload.client_submission_id ? `${state.messages[optimisticIndex].id}:assistant` : state.streamingMessageId;
+      state = { ...state, streamingMessageId: assistantId, messages: state.messages.map((message, index) => index === optimisticIndex ? { ...message, durableId: messageId2, runId: event.run_id } : message.role === "assistant" && message.id === assistantId ? { ...message, runId: event.run_id } : message) };
     }
   }
   const projection = assistantProjectionFromEvent(event);
   const eventName = String(event.event || "");
+  const completion = eventName === "assistant.completed" ? event.payload : event.payload?.response_completion;
+  const responseCompleted = Boolean(completion?.completed_at);
   const runId = state.activeRunId && event.event !== "run.accepted" ? state.activeRunId : event.run_id || state.activeRunId;
   const segmentId = typeof event.payload?.segment_id === "string" ? event.payload.segment_id : null;
   const distinctSegment = Boolean(segmentId && segmentId !== `${runId}:0`);
@@ -697,6 +703,7 @@ function applyRuntimeEvent(state, event) {
   const suspension = eventName === "run.waiting" ? "waiting" : eventName === "run.interrupted" ? "interrupted" : null;
   const cancelling = eventName === "run.cancelling" || String(event.payload?.status || "") === "cancelling";
   const existing = state.messages.find((message) => message.role === "assistant" && message.id === messageId) || (!distinctSegment ? state.messages.find((message) => message.role === "assistant" && Boolean(runId && message.runId === runId)) : void 0);
+  const sealedAfterTerminal = responseCompleted && !state.activeRunId && ["completed", "failed", "cancelled"].includes(state.runState) && existing?.runId === runId;
   const payload = event.payload || {};
   const eventThreadId = typeof payload.thread_id === "string" && payload.thread_id.trim() ? payload.thread_id.trim() : null;
   const contextApplies = (!state.activeThreadId || !eventThreadId || eventThreadId === state.activeThreadId) && (!state.activeRunId || !runId || runId === state.activeRunId);
@@ -715,13 +722,13 @@ function applyRuntimeEvent(state, event) {
   const projectedParts = hasCanonicalResponseBlocks ? projection.parts : delta ? appendAssistantDelta(
     existing?.parts || [],
     delta,
-    `${runId || "run"}-assistant-text-${event.seq}`
+    typeof payload.block_id === "string" ? payload.block_id : `${runId || "run"}-assistant-text-${event.seq}`
   ) : projection.parts.length ? upsertResponseBlockParts(existing?.parts || [], projection.parts) : existing?.parts || [];
   const lifecycleParts = reconcileModelTurnParts(projectedParts, event);
   const compressionPart = contextApplies && explicitCompression?.active ? contextCompressionPartFromEvent(event, lifecycleParts) : null;
   const parts = compressionPart ? upsertResponseBlockParts(lifecycleParts, [compressionPart]) : lifecycleParts;
   const activeThreadId = eventThreadId || state.activeThreadId;
-  const messages = upsertStableAssistantMessage(state.messages, {
+  let messages = upsertStableAssistantMessage(state.messages, {
     messageId,
     runId,
     strictMessageId: distinctSegment,
@@ -731,7 +738,8 @@ function applyRuntimeEvent(state, event) {
       runId,
       content,
       createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-      isFinal: terminal,
+      isFinal: terminal || responseCompleted,
+      responseCompletion: completion,
       parts
     }),
     update: (message) => ({
@@ -739,9 +747,20 @@ function applyRuntimeEvent(state, event) {
       runId: runId ?? message.runId,
       content,
       parts,
-      isFinal: terminal || message.isFinal
+      isFinal: terminal || responseCompleted || message.isFinal,
+      responseCompletion: completion || message.responseCompletion
     })
   });
+  if (responseCompleted) messages = messages.map((message) => {
+    if (message.role !== "assistant" || message.runId !== runId) return message;
+    const segment = completion?.segments.find((item) => item.message_id === message.durableId || item.message_id === message.id || message.id.endsWith(`-assistant-${item.segment_id}`)) || (!message.segmentIndex || message.segmentIndex === 1 ? completion?.segments[0] : void 0);
+    return {
+      ...message,
+      isFinal: true,
+      responseCompletion: completion,
+      ...segment ? { durableId: segment.message_id } : {}
+    };
+  });
   const threads = activeThreadId ? state.threads.some((thread) => thread.id === activeThreadId) ? state.threads.map((thread) => thread.id === activeThreadId ? {
     ...thread,
     messages,
@@ -763,15 +782,15 @@ function applyRuntimeEvent(state, event) {
   return {
     ...state,
     activeThreadId,
-    activeRunId: terminal ? null : runId,
+    activeRunId: terminal || sealedAfterTerminal ? null : runId,
     cursor: typeof event.seq === "number" ? event.seq : state.cursor,
     messages,
     threads,
     contextWindow,
     contextCompression,
     contextCompressionRevision: hasLiveCompressionUpdate ? state.contextCompressionRevision + 1 : state.contextCompressionRevision,
-    runState: suspension || (paused ? "paused" : cancelling ? "cancelling" : terminal ? eventName === "run.completed" ? "completed" : eventName === "run.cancelled" ? "cancelled" : "failed" : "streaming"),
-    streamingMessageId: terminal || paused || suspension ? null : messageId
+    runState: sealedAfterTerminal ? state.runState : suspension || (paused ? "paused" : cancelling ? "cancelling" : terminal ? eventName === "run.completed" ? "completed" : eventName === "run.cancelled" ? "cancelled" : "failed" : "streaming"),
+    streamingMessageId: terminal || paused || suspension || responseCompleted || existing?.responseCompletion ? null : messageId
   };
 }
 function applyRuntimeEvents(state, events) {
@@ -808,7 +827,16 @@ function applyThreadSummaryEvent(threads, event) {
 
 // src/thread-message-queue.ts
 import * as React2 from "react";
-function useThreadMessageQueue({ threadId, transport, onPromoted }) {
+async function retrySubmissionAdmission(admit) {
+  try {
+    return await admit();
+  } catch (error) {
+    const failure = error;
+    if (failure?.kind !== "network" && failure?.name !== "HttpRequestTimeoutError" && !(error instanceof TypeError)) throw error;
+    return admit();
+  }
+}
+function useThreadMessageQueue({ threadId, transport, onPromoted, onOptimistic, onDiscard }) {
   const [pendingMessages, setPendingMessages] = React2.useState([]);
   const [messageQueue, setMessageQueue] = React2.useState(null);
   const pendingRef = React2.useRef(/* @__PURE__ */ new Map());
@@ -821,15 +849,19 @@ function useThreadMessageQueue({ threadId, transport, onPromoted }) {
   threadRef.current = threadId;
   transportRef.current = transport;
   onPromotedRef.current = onPromoted;
+  const callbacksRef = React2.useRef({ onOptimistic, onDiscard });
+  callbacksRef.current = { onOptimistic, onDiscard };
+  const knownMessage = (id, submissionId) => pendingRef.current.get(id) || (submissionId ? [...pendingRef.current.values()].find((item) => item.client_submission_id === submissionId) : void 0);
   const hydrate = React2.useCallback((page, selectedThreadId) => {
     if (threadRef.current !== selectedThreadId) return;
     const pending = page.pending.filter((message) => !promotedRef.current.has(message.id)).map((message) => {
-      const known = pendingRef.current.get(message.id);
+      const known = knownMessage(message.id, message.client_submission_id);
       if (message.attachments?.length || !known?.attachments?.length) return message;
       return { ...message, attachments: known.attachments.filter((attachment) => message.attachment_ids.includes(attachment.id)) };
     });
     for (const message of pending) pendingRef.current.set(message.id, message);
-    setPendingMessages(pending);
+    const optimistic = [...pendingRef.current.values()].filter((message) => message.thread_id === selectedThreadId && message.revision === 0 && message.optimisticQueued && !pending.some((item) => item.client_submission_id === message.client_submission_id));
+    setPendingMessages([...pending, ...optimistic]);
     setMessageQueue(page.queue);
   }, []);
   const refresh = React2.useCallback(async (selectedThreadId = threadRef.current) => {
@@ -839,9 +871,10 @@ function useThreadMessageQueue({ threadId, transport, onPromoted }) {
     if (version !== versionRef.current || threadRef.current !== selectedThreadId) return null;
     for (const item of page.items) {
       if (item.role === "user" && item.status === "delivered" && item.run_id) {
-        const pending = pendingRef.current.get(item.id);
+        const pending = knownMessage(item.id, item.client_submission_id);
         if (pending && !promotedRef.current.has(item.id)) {
           promotedRef.current.add(item.id);
+          pendingRef.current.delete(pending.id);
           pendingRef.current.delete(item.id);
           onPromotedRef.current({
             ...pending,
@@ -857,56 +890,98 @@ function useThreadMessageQueue({ threadId, transport, onPromoted }) {
   const acceptNotice = React2.useCallback((notice) => {
     if (notice.cursor && notice.cursor <= cursorRef.current) return false;
     if (notice.cursor) cursorRef.current = notice.cursor;
-    const pending = pendingRef.current.get(notice.messageId);
-    if (notice.status === "delivered" && notice.runId && pending && !promotedRef.current.has(pending.id)) {
-      promotedRef.current.add(pending.id);
+    const pending = knownMessage(notice.messageId, notice.clientSubmissionId);
+    if (notice.status === "delivered" && notice.runId && pending && !promotedRef.current.has(notice.messageId)) {
+      promotedRef.current.add(notice.messageId);
       pendingRef.current.delete(pending.id);
       versionRef.current += 1;
       setPendingMessages((current) => current.filter((message) => message.id !== pending.id));
-      onPromotedRef.current(pending, notice.runId);
+      onPromotedRef.current({ ...pending, id: notice.messageId, run_id: notice.runId, status: "delivered" }, notice.runId);
     }
     if (notice.status === "removed") pendingRef.current.delete(notice.messageId);
     void refresh().catch(() => void 0);
     return true;
   }, [refresh]);
+  const beginSubmission = React2.useCallback((input, queued = false) => {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const message = {
+      id: input.clientSubmissionId,
+      client_submission_id: input.clientSubmissionId,
+      thread_id: threadRef.current || "",
+      sequence: Number.MAX_SAFE_INTEGER,
+      run_id: null,
+      turn_id: null,
+      segment_index: 0,
+      role: "user",
+      status: "queued",
+      requested_mode: input.mode || "queue",
+      text: input.input,
+      attachment_ids: input.attachmentIds || input.attachments?.map((item) => item.id) || [],
+      attachments: input.attachments,
+      response_blocks: [],
+      revision: 0,
+      created_at: now,
+      updated_at: now
+    };
+    pendingRef.current.set(message.id, { ...message, optimisticQueued: queued });
+    versionRef.current += 1;
+    if (queued) setPendingMessages((current) => [...current, message]);
+    else callbacksRef.current.onOptimistic?.(message, Boolean(input.uploading));
+    return message;
+  }, []);
+  const discardSubmission = React2.useCallback((message) => {
+    if (!pendingRef.current.has(message.id)) return;
+    pendingRef.current.delete(message.id);
+    callbacksRef.current.onDiscard?.(message);
+    versionRef.current += 1;
+    setPendingMessages((current) => current.filter((item) => item.client_submission_id !== message.client_submission_id));
+  }, []);
   const submit = React2.useCallback(async (input) => {
     const selectedThreadId = threadRef.current;
     if (!selectedThreadId) throw new Error("No active Agent thread is available.");
-    const { attachments, ...submission } = input;
-    const result = await transportRef.current.submit({ ...submission, threadId: selectedThreadId });
-    if (threadRef.current !== selectedThreadId) return result;
-    versionRef.current += 1;
-    if (!result.run_id && ["queued", "steer_pending", "blocked"].includes(result.status)) {
-      const now = (/* @__PURE__ */ new Date()).toISOString();
-      const pending = {
+    const { queued, prepare, attachments, uploading, ...submission } = input;
+    const optimistic = beginSubmission({
+      ...submission,
+      attachments,
+      uploading,
+      clientSubmissionId: submission.clientSubmissionId || submission.idempotencyKey
+    }, queued);
+    try {
+      const prepared = prepare ? await prepare() : {};
+      if (threadRef.current === selectedThreadId) pendingRef.current.set(optimistic.id, { ...optimistic, optimisticQueued: queued, attachment_ids: prepared.attachmentIds || optimistic.attachment_ids, attachments: prepared.attachments || attachments });
+      const request = { ...submission, ...prepared, clientSubmissionId: optimistic.client_submission_id, threadId: selectedThreadId };
+      const result = await retrySubmissionAdmission(() => transportRef.current.submit(request));
+      if (threadRef.current !== selectedThreadId) return result;
+      versionRef.current += 1;
+      const bound = {
+        ...optimistic,
         id: result.message_id,
-        thread_id: selectedThreadId,
-        sequence: Number.MAX_SAFE_INTEGER,
-        run_id: null,
-        turn_id: null,
-        segment_index: null,
-        role: "user",
+        client_submission_id: result.client_submission_id || optimistic.client_submission_id,
+        attachment_ids: request.attachmentIds || [],
+        attachments: prepared.attachments || attachments,
+        run_id: result.run_id,
         status: result.status,
-        requested_mode: input.mode,
-        text: input.input,
-        attachment_ids: input.attachmentIds || [],
-        attachments,
-        response_blocks: [],
-        revision: 1,
-        created_at: now,
-        updated_at: now
+        revision: 1
       };
-      pendingRef.current.set(pending.id, pending);
-      setPendingMessages((current) => current.some((message) => message.id === pending.id) ? current : [...current, pending]);
-      setMessageQueue((current) => ({
-        pending_count: Math.max(current?.pending_count || 0, result.queue_position || 1),
-        paused: current?.paused || false,
-        reason: current?.reason || null
-      }));
+      pendingRef.current.delete(optimistic.id);
+      if (result.run_id) {
+        setPendingMessages((current) => current.filter((item) => item.client_submission_id !== bound.client_submission_id));
+        if (!promotedRef.current.has(bound.id)) {
+          promotedRef.current.add(bound.id);
+          onPromotedRef.current(bound, result.run_id);
+        }
+      } else if (!promotedRef.current.has(bound.id)) {
+        if (!queued) callbacksRef.current.onDiscard?.(optimistic);
+        pendingRef.current.set(bound.id, bound);
+        setPendingMessages((current) => [...current.filter((item) => item.client_submission_id !== bound.client_submission_id), bound]);
+      }
+      void refresh().catch(() => void 0);
+      return result;
+    } catch (error) {
+      if (threadRef.current === selectedThreadId) discardSubmission(optimistic);
+      throw error;
     }
-    void refresh().catch(() => void 0);
-    return result;
-  }, [refresh]);
+  }, [beginSubmission, discardSubmission, refresh]);
   const edit = React2.useCallback(async (message, input) => {
     const updated = await transportRef.current.edit(message, input);
     versionRef.current += 1;
@@ -949,7 +1024,51 @@ function useThreadMessageQueue({ threadId, transport, onPromoted }) {
     }, 3e3);
     return () => clock.clearInterval(timer);
   }, [threadId, pendingMessages.length, messageQueue?.paused, refresh]);
-  return { pendingMessages, messageQueue, refresh, hydrate, acceptNotice, submit, edit, remove, retractForEdit, resume };
+  return { pendingMessages, messageQueue, refresh, hydrate, acceptNotice, beginSubmission, discardSubmission, submit, edit, remove, retractForEdit, resume };
+}
+function optimisticSubmissionTurn(message) {
+  const user = {
+    id: message.client_submission_id || message.id,
+    clientSubmissionId: message.client_submission_id || void 0,
+    role: "user",
+    content: message.text,
+    createdAt: message.created_at,
+    isFinal: true,
+    parts: message.text ? [{ id: `${message.id}:text`, type: "text", kind: "text", text: message.text }] : [],
+    attachments: message.attachments?.map((item) => ({
+      id: item.id,
+      filename: item.filename,
+      mediaType: item.mime_type,
+      byteSize: item.byte_size
+    }))
+  };
+  return [user, {
+    id: `${user.id}:assistant`,
+    role: "assistant",
+    content: "",
+    parts: [],
+    createdAt: message.created_at,
+    isFinal: false
+  }];
+}
+function optimisticSubmissionState(state, message, uploading) {
+  const [user, assistant] = optimisticSubmissionTurn(message);
+  return {
+    ...state,
+    messages: appendStableStreamingTurn(state.messages, user, assistant),
+    streamingMessageId: assistant.id,
+    runState: uploading ? "uploading" : "streaming",
+    error: null
+  };
+}
+function discardOptimisticSubmission(state, message) {
+  const activeDraft = state.streamingMessageId === `${message.id}:assistant`;
+  return {
+    ...state,
+    messages: state.messages.filter((item) => item.runId || item.id !== message.id && item.id !== `${message.id}:assistant`),
+    streamingMessageId: activeDraft ? null : state.streamingMessageId,
+    runState: activeDraft && !state.activeRunId ? "idle" : state.runState
+  };
 }
 
 // src/use-agent-chat.ts
@@ -1254,7 +1373,13 @@ function useAgentChat(options = {}) {
       });
     }
   }, [update]);
-  const queue = useThreadMessageQueue({ threadId: state.activeThreadId, transport: queueTransport, onPromoted: onQueuePromotion });
+  const queue = useThreadMessageQueue({
+    threadId: state.activeThreadId,
+    transport: queueTransport,
+    onPromoted: onQueuePromotion,
+    onOptimistic: (message, uploading) => update((current) => optimisticSubmissionState(current, message, uploading)),
+    onDiscard: (message) => update((current) => discardOptimisticSubmission(current, message))
+  });
   const { pendingMessages, messageQueue } = queue;
   const eventBuffer = React6.useMemo(
     () => createRuntimeEventFrameBuffer(
@@ -1465,38 +1590,46 @@ function useAgentChat(options = {}) {
       clearOperationError();
       setIsSubmitting(true);
       try {
-        const uploaded = input.uploads?.length ? await client.attachments.uploadBatch({
-          uploads: input.uploads,
-          threadId: existingThreadId,
-          requestedAgentId: input.requestedAgentId,
-          idempotencyKey: runtime.createId()
-        }) : [];
-        const result = await queue.submit({
+        await queue.submit({
           mode: "queue",
           input: input.text.trim(),
-          attachmentIds: uploaded.length ? uploaded.map((item) => item.id) : input.attachmentIds,
+          attachmentIds: input.attachmentIds,
+          attachments: input.attachments?.map((item, index) => ({
+            id: item.id || `attachment-${index}`,
+            filename: item.filename || "Attachment",
+            mime_type: item.mediaType || "application/octet-stream",
+            byte_size: typeof item.byteSize === "number" ? item.byteSize : 0
+          })) || input.uploads?.map((item, index) => ({
+            id: `upload-${index}`,
+            filename: item.name,
+            mime_type: item.mediaType || "application/octet-stream",
+            byte_size: 0
+          })),
+          queued: Boolean(stateRef.current.activeRunId),
+          uploading: Boolean(input.uploads?.length),
           requestedAgentId: input.requestedAgentId,
           requestedModelId: input.requestedModelId,
-          idempotencyKey: runtime.createId()
+          clientSubmissionId: runtime.createId(),
+          idempotencyKey: runtime.createId(),
+          prepare: async () => {
+            const uploaded = input.uploads?.length ? await client.attachments.uploadBatch({
+              uploads: input.uploads,
+              threadId: existingThreadId,
+              requestedAgentId: input.requestedAgentId,
+              idempotencyKey: runtime.createId()
+            }) : [];
+            if (input.uploads?.length && uploaded.length !== input.uploads.length) throw new Error("Attachment upload returned an incomplete batch");
+            return {
+              attachmentIds: uploaded.length ? uploaded.map((item) => item.id) : input.attachmentIds,
+              attachments: uploaded.length ? uploaded.map((item) => ({
+                id: item.id,
+                filename: item.filename,
+                mime_type: item.mime_type,
+                byte_size: item.byte_size
+              })) : void 0
+            };
+          }
         });
-        if (stateRef.current.activeThreadId !== existingThreadId) return;
-        if (result.run_id) {
-          const userMessage = {
-            id: result.message_id,
-            role: "user",
-            runId: result.run_id,
-            content: input.text.trim(),
-            createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-            isFinal: true,
-            parts: input.text.trim() ? [{ id: `${result.message_id}-text`, type: "text", kind: "text", text: input.text.trim() }] : [],
-            attachments: input.attachments || []
-          };
-          update((current) => current.activeThreadId !== existingThreadId || current.messages.some((message) => message.id === userMessage.id) ? current : { ...current, messages: [...current.messages, userMessage] });
-        }
-        void refreshMessages(existingThreadId).catch(() => void 0);
-        if (result.run_id && promotedAttachRef.current !== result.run_id && stateRef.current.activeRunId !== result.run_id) {
-          void attachRunRef.current(result.run_id).catch(() => void 0);
-        }
       } catch (error) {
         failOperation("submit", error);
         throw error;
@@ -1513,28 +1646,28 @@ function useAgentChat(options = {}) {
       detach();
       const controller = runtime.createAbortController();
       streamControllerRef.current = controller;
-      const userId = runtime.createId();
-      const assistantId = runtime.createId();
+      const ticket = queue.beginSubmission({
+        input: input.text.trim(),
+        clientSubmissionId: runtime.createId(),
+        uploading: Boolean(input.uploads?.length),
+        attachmentIds: input.attachmentIds,
+        attachments: input.attachments?.map((item, index) => ({
+          id: item.id || `attachment-${index}`,
+          filename: item.filename || "Attachment",
+          mime_type: item.mediaType || "application/octet-stream",
+          byte_size: typeof item.byteSize === "number" ? item.byteSize : 0
+        })) || input.uploads?.map((upload, index) => ({
+          id: `upload-${index}`,
+          filename: upload.name,
+          mime_type: upload.mediaType || "application/octet-stream",
+          byte_size: 0
+        }))
+      });
+      const userId = ticket.id;
       const idempotencyKey = runtime.createId();
-      const optimisticAttachments = input.attachments?.length ? input.attachments : input.uploads?.map((upload, index) => ({
-        id: `${userId}-attachment-${index}`,
-        filename: upload.name,
-        mediaType: upload.mediaType,
-        status: "uploading"
-      }));
-      const userMessage = { id: userId, role: "user", content: input.text.trim(), createdAt: (/* @__PURE__ */ new Date()).toISOString(), parts: input.text.trim() ? [{ id: `${userId}-text`, type: "text", kind: "text", text: input.text.trim() }] : [], attachments: optimisticAttachments };
-      const assistantMessage = { id: assistantId, role: "assistant", content: "", createdAt: (/* @__PURE__ */ new Date()).toISOString(), isFinal: false, parts: [] };
       clearOperationError();
       const hasPendingUploads = Boolean(input.uploads?.length);
-      update((current) => ({
-        ...current,
-        messages: appendStableStreamingTurn(current.messages, userMessage, assistantMessage),
-        streamingMessageId: assistantId,
-        runState: hasPendingUploads ? "uploading" : "streaming",
-        error: null
-      }));
       setIsSubmitting(true);
-      let streamStarted = false;
       try {
         const uploaded = hasPendingUploads ? await client.attachments.uploadBatch({
           uploads: input.uploads || [],
@@ -1555,8 +1688,7 @@ function useAgentChat(options = {}) {
             runState: "streaming"
           }));
         }
-        streamStarted = true;
-        const result = await client.chat.stream({ input: input.text.trim(), threadId: stateRef.current.activeThreadId || void 0, attachmentIds, requestedModelId: input.requestedModelId, requestedAgentId: input.requestedAgentId, idempotencyKey, signal: controller.signal }, consumeEvent);
+        const result = await client.chat.stream({ clientSubmissionId: ticket.client_submission_id, input: input.text.trim(), threadId: stateRef.current.activeThreadId || void 0, attachmentIds, requestedModelId: input.requestedModelId, requestedAgentId: input.requestedAgentId, idempotencyKey, signal: controller.signal }, consumeEvent);
         eventBuffer.flush();
         update((current) => {
           const threadId = result.threadId || current.activeThreadId;
@@ -1572,19 +1704,13 @@ function useAgentChat(options = {}) {
         if (result.threadId) await refreshThreads().catch(() => void 0);
         if (result.threadId && !result.detached) await refreshMessages(result.threadId);
       } catch (error) {
-        if (isAbortLike(error) && !streamStarted) {
-          update((current) => current.streamingMessageId === assistantId ? {
-            ...current,
-            messages: current.messages.filter((message) => message.id !== userId && message.id !== assistantId),
-            runState: "idle",
-            streamingMessageId: null
-          } : current);
-        } else if (!isAbortLike(error)) {
+        const admitted = Boolean(stateRef.current.messages.find((message) => message.id === userId)?.runId);
+        if (!admitted) queue.discardSubmission(ticket);
+        if (!isAbortLike(error)) {
           update((current) => ({
             ...current,
-            messages: streamStarted ? current.messages : current.messages.filter((message) => message.id !== userId && message.id !== assistantId),
-            runState: "failed",
-            streamingMessageId: null
+            runState: admitted ? "reconnecting" : "failed",
+            streamingMessageId: admitted ? current.streamingMessageId : null
           }));
           failOperation("submit", error);
           throw error;
@@ -1744,7 +1870,8 @@ function useAgentChat(options = {}) {
             messageId: event.message_id,
             status: event.status,
             runId: event.run_id,
-            cursor: event.cursor
+            cursor: event.cursor,
+            clientSubmissionId: event.client_submission_id
           });
           if (wasQueued) void refreshMessages(event.thread_id, event.run_id || void 0).catch(() => void 0);
         }
@@ -2041,11 +2168,14 @@ export {
   contextCompressionPartFromEvent,
   createPortableId,
   createRuntimeEventFrameBuffer,
+  discardOptimisticSubmission,
   getThreadActivity,
   initialAgentChatState,
   isAbortLike,
   latestThreadContext,
   modelTurnPartFromEvent,
+  optimisticSubmissionState,
+  optimisticSubmissionTurn,
   partsFromResponseBlocks,
   preferNewestThreadSummary,
   preserveMountedMessageIds,
@@ -2053,6 +2183,7 @@ export {
   reconcileRefreshedThreads,
   reconcileThreadTimeline,
   restoreAgentChatThreadSelection,
+  retrySubmissionAdmission,
   runtimeEventFrameScheduler,
   threadDetailToMessages,
   threadTimelineToMessages,