@dudousxd/nestjs-agent-react 0.26.0 → 0.27.0

package/dist/index.cjs

@@ -214,12 +214,48 @@ var AgentClient = class {
         signal: request.signal
       } : {}
     });
+    if (response.status === 202) {
+      return {
+        body: emptyStream(),
+        queued: await response.json()
+      };
+    }
     if (!response.ok || !response.body) {
       throw await this.failure(response, "POST", `${this.agentPath()}/chat`);
     }
     return streamResponse(response);
   }
   /**
+  * `POST <path>/chat` for a message that should wait in the thread's queue — the body carries
+  * `mode: 'queue'` (or `'interrupt'`), which the server always answers with `202` JSON.
+  */
+  enqueueMessage(request) {
+    return this.request("POST", "/chat", {
+      mode: "queue",
+      ...request.body
+    });
+  }
+  /** `GET <path>/threads/:id/queue` — the thread's waiting messages, and whether it drains. */
+  getQueue(threadId) {
+    return this.request("GET", `/threads/${encodeURIComponent(threadId)}/queue`);
+  }
+  /** `PATCH <path>/queue/:messageId` — change a waiting message's text/attachments, or move it. */
+  updateQueuedMessage(messageId, update) {
+    return this.request("PATCH", `/queue/${encodeURIComponent(messageId)}`, update);
+  }
+  /** `DELETE <path>/queue/:messageId`. */
+  removeQueuedMessage(messageId) {
+    return this.request("DELETE", `/queue/${encodeURIComponent(messageId)}`);
+  }
+  /** `DELETE <path>/threads/:id/queue` — drop every waiting message. */
+  clearQueue(threadId) {
+    return this.request("DELETE", `/threads/${encodeURIComponent(threadId)}/queue`);
+  }
+  /** `POST <path>/threads/:id/queue/resume` — lift a pause; `runId` when the head started. */
+  resumeQueue(threadId) {
+    return this.request("POST", `/threads/${encodeURIComponent(threadId)}/queue/resume`);
+  }
+  /**
   * `GET <path>/chat/:runId/stream[?after=<seq>]` → the run's SSE stream, or `null` when nothing is
   * streaming under that id (404).
   */
@@ -485,6 +521,14 @@ var AgentClient = class {
     return JSON.parse(text);
   }
 };
+function emptyStream() {
+  return new ReadableStream({
+    start(controller) {
+      controller.close();
+    }
+  });
+}
+__name(emptyStream, "emptyStream");
 function streamResponse(response) {
   const body = response.body;
   const runId = response.headers?.get(HEADER_RUN_ID) ?? void 0;
@@ -647,6 +691,10 @@ var AgentChatTransport = class {
           signal: options.abortSignal
         } : {}
       });
+      if (response.queued !== void 0) {
+        this.attemptLive = false;
+        return queuedChunkStream(response.queued);
+      }
       this.captureHeaderMeta(response);
       return this.toChunkStream(response, {
         ...headers !== void 0 ? {
@@ -677,6 +725,7 @@ var AgentChatTransport = class {
       });
       if (response === null) {
         this.attemptLive = false;
+        this.options.onResumeGone?.(runId);
         return null;
       }
       this.captureHeaderMeta(response);
@@ -1054,6 +1103,9 @@ var AgentChatTransport = class {
               break;
             case "title":
             case "cancelled":
+            // The thread's queue changed, or this run handed the thread to the next queued message
+            // (`started`). Thread-level, like the title.
+            case "queue":
               forwardAsData(event, true);
               break;
             default:
@@ -1156,6 +1208,22 @@ var AgentChatTransport = class {
     });
   }
 };
+function queuedChunkStream(queued) {
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue({
+        type: "data-queue",
+        data: {
+          queue: queued.queue,
+          queuedSend: queued
+        },
+        transient: true
+      });
+      controller.close();
+    }
+  });
+}
+__name(queuedChunkStream, "queuedChunkStream");
 function parseSseFrame(raw) {
   let event;
   let id;
@@ -3870,6 +3938,7 @@ function useChatTranscript(options) {
     } : {}
   });
   const showTypingIndicator = isBusy && lastMessage?.role !== "assistant";
+  const queued = useQueuedItems(options.queue ?? null, options.readOnly === true);
   return {
     items,
     status,
@@ -3892,10 +3961,53 @@ function useChatTranscript(options) {
       available: isBusy && options.readOnly !== true && options.onStop !== void 0,
       isStopping: stopRequested,
       stop
-    }
+    },
+    queued,
+    queuePaused: options.queue?.paused ?? null
   };
 }
 __name(useChatTranscript, "useChatTranscript");
+function useQueuedItems(queue, readOnly) {
+  const latestQueue = (0, import_react17.useRef)(queue);
+  latestQueue.current = queue;
+  const removers = (0, import_react17.useRef)(/* @__PURE__ */ new Map());
+  const removerFor = (0, import_react17.useCallback)((id) => {
+    let remover = removers.current.get(id);
+    if (remover === void 0) {
+      remover = /* @__PURE__ */ __name(() => {
+        void latestQueue.current?.remove?.(id);
+      }, "remover");
+      removers.current.set(id, remover);
+    }
+    return remover;
+  }, []);
+  if (queue === null || queue === void 0) {
+    return [];
+  }
+  return queue.items.map((message, position) => {
+    const state = message.state === "sending" ? "sending" : queue.paused !== null ? "paused" : "queued";
+    return {
+      id: message.id,
+      role: "user",
+      text: message.text,
+      files: message.attachments.map((attachment) => ({
+        url: attachment.url,
+        mediaType: attachment.contentType,
+        filename: attachment.name,
+        isImage: attachment.contentType.startsWith("image/")
+      })),
+      state,
+      position,
+      isNext: position === 0,
+      interrupt: message.interrupt,
+      remove: {
+        available: !readOnly && state !== "sending" && queue.remove !== void 0,
+        run: removerFor(message.id)
+      }
+    };
+  });
+}
+__name(useQueuedItems, "useQueuedItems");
 function useTranscriptItem(options) {
   const { message, isStreaming = false } = options;
   const messagesRef = (0, import_react17.useRef)([
@@ -4514,7 +4626,7 @@ function joinClasses(...entries) {
 __name(joinClasses, "joinClasses");
 
 // src/components/message-list.tsx
-function MessageList({ messages, status, renderToolPart, renderToolGroup, renderText, renderReasoning, renderFiles, renderUi, reasoningLabel, getMeta, readOnly, onFork, editable, onEditSubmit, regeneratable, onRegenerate, getUsage, getCreatedAt, emptyState, typingIndicator, followUps, onFollowUpClick, error, onRetry, classNames }) {
+function MessageList({ messages, status, renderToolPart, renderToolGroup, renderText, renderReasoning, renderFiles, renderUi, reasoningLabel, getMeta, readOnly, onFork, editable, onEditSubmit, regeneratable, onRegenerate, getUsage, getCreatedAt, emptyState, typingIndicator, followUps, onFollowUpClick, error, onRetry, queue, classNames }) {
   const transcript = useChatTranscript({
     messages,
     status,
@@ -4544,9 +4656,16 @@ function MessageList({ messages, status, renderToolPart, renderToolGroup, render
     } : {},
     ...followUps !== void 0 ? {
       followUps
+    } : {},
+    ...queue !== void 0 ? {
+      queue: {
+        items: queue.items,
+        paused: queue.paused,
+        remove: queue.remove
+      }
     } : {}
   });
-  if (transcript.showEmptyState) {
+  if (transcript.showEmptyState && transcript.queued.length === 0) {
     return /* @__PURE__ */ React.createElement("div", {
       className: classNames?.empty
     }, emptyState);
@@ -4590,7 +4709,23 @@ function MessageList({ messages, status, renderToolPart, renderToolGroup, render
     ...getMeta ? {
       meta: getMeta(item.message)
     } : {}
-  })), transcript.showTypingIndicator ? /* @__PURE__ */ React.createElement("div", {
+  })), transcript.queued.length > 0 ? /* @__PURE__ */ React.createElement("div", {
+    className: classNames?.queue
+  }, transcript.queued.map((item) => /* @__PURE__ */ React.createElement("div", {
+    key: item.id,
+    className: classNames?.queuedItem,
+    "data-state": item.state
+  }, /* @__PURE__ */ React.createElement("span", null, item.text), item.remove.available ? /* @__PURE__ */ React.createElement("button", {
+    type: "button",
+    className: classNames?.queuedRemove,
+    onClick: item.remove.run
+  }, "Remove") : null)), transcript.queuePaused !== null && queue !== void 0 ? /* @__PURE__ */ React.createElement("div", {
+    className: classNames?.queuePaused
+  }, /* @__PURE__ */ React.createElement("span", null, "Queue paused"), /* @__PURE__ */ React.createElement("button", {
+    type: "button",
+    className: classNames?.queueResume,
+    onClick: /* @__PURE__ */ __name(() => void queue.resume(), "onClick")
+  }, "Resume")) : null) : null, transcript.showTypingIndicator ? /* @__PURE__ */ React.createElement("div", {
     className: classNames?.typing
   }, typingIndicator ?? "Thinking\u2026") : null, error && onRetry ? /* @__PURE__ */ React.createElement("div", {
     className: classNames?.error
@@ -5359,6 +5494,77 @@ __name(sumUsage, "sumUsage");
 // src/use-agent-chat.ts
 var import_react22 = require("@ai-sdk/react");
 var import_react23 = require("react");
+var EMPTY_QUEUE = {
+  items: [],
+  paused: null
+};
+var localQueueSequence = 0;
+function queuedUserMessage(turn) {
+  return {
+    id: turn.messageId,
+    role: "user",
+    metadata: {
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    },
+    parts: [
+      ...turn.attachments.map((attachment) => ({
+        type: "file",
+        mediaType: attachment.contentType,
+        filename: attachment.name,
+        url: attachment.url,
+        providerMetadata: {
+          agent: {
+            mediaId: attachment.mediaId
+          }
+        }
+      })),
+      ...turn.text.length > 0 ? [
+        {
+          type: "text",
+          text: turn.text
+        }
+      ] : []
+    ]
+  };
+}
+__name(queuedUserMessage, "queuedUserMessage");
+function draftOf(message) {
+  if (typeof message !== "object" || message === null) {
+    return {
+      text: "",
+      attachments: []
+    };
+  }
+  const draft = message;
+  let text = typeof draft.text === "string" ? draft.text : "";
+  if (text === "" && Array.isArray(draft.parts)) {
+    text = draft.parts.filter((part) => part.type === "text" && typeof part.text === "string").map((part) => part.text).join("");
+  }
+  const files = Array.isArray(draft.files) ? draft.files : Array.isArray(draft.parts) ? draft.parts.filter((part) => part.type === "file") : [];
+  const attachments = files.flatMap((file) => {
+    const mediaId = file.providerMetadata?.agent?.mediaId;
+    return typeof mediaId === "string" ? [
+      {
+        mediaId,
+        url: String(file.url ?? ""),
+        contentType: String(file.mediaType ?? "application/octet-stream"),
+        name: String(file.filename ?? mediaId)
+      }
+    ] : [];
+  });
+  return {
+    text,
+    attachments
+  };
+}
+__name(draftOf, "draftOf");
+function lastUserIndex(messages) {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    if (messages[index]?.role === "user") return index;
+  }
+  return -1;
+}
+__name(lastUserIndex, "lastUserIndex");
 var localChatSequence = 0;
 function localChatId() {
   localChatSequence += 1;
@@ -5398,6 +5604,41 @@ function useAgentChat(options = {}) {
   const pendingPin = (0, import_react23.useRef)(void 0);
   const regenerateNext = (0, import_react23.useRef)(false);
   const currentThreadId = (0, import_react23.useCallback)(() => latest.current.threadId ?? createdThreadId.current, []);
+  const [queueState, setQueueState] = (0, import_react23.useState)(EMPTY_QUEUE);
+  const queueStateRef = (0, import_react23.useRef)(queueState);
+  const applyQueue = (0, import_react23.useCallback)((next) => {
+    queueStateRef.current = next;
+    setQueueState(next);
+  }, []);
+  const [pendingSends, setPendingSends] = (0, import_react23.useState)([]);
+  const [queueError, setQueueError] = (0, import_react23.useState)(null);
+  const handoff = (0, import_react23.useRef)(void 0);
+  const queuedSend = (0, import_react23.useRef)(void 0);
+  const threadWaiters = (0, import_react23.useRef)([]);
+  const turnBody = (0, import_react23.useCallback)(() => {
+    const current = latest.current;
+    const pageContext = current.getPageContext?.() ?? null;
+    const threadId = currentThreadId();
+    const model = current.model ?? (lockedRef.current ? void 0 : pickedModelRef.current);
+    return {
+      // Read per send: a host that switches agents before the first message (a picker on a new
+      // chat) sends the one picked now, not the one this chat mounted with.
+      ...current.agent !== void 0 ? {
+        agent: current.agent
+      } : {},
+      ...threadId !== void 0 ? {
+        threadId
+      } : {},
+      ...model !== void 0 ? {
+        model
+      } : {},
+      ...pageContext ? {
+        pageContext
+      } : {}
+    };
+  }, [
+    currentThreadId
+  ]);
   const [connection, setConnection] = (0, import_react23.useState)({
     status: "live"
   });
@@ -5406,6 +5647,11 @@ function useAgentChat(options = {}) {
     function onMeta(meta) {
       settlingRunIdRef.current = meta.runId;
       setRunId(meta.runId);
+      if (meta.threadId) {
+        const waiting = threadWaiters.current;
+        threadWaiters.current = [];
+        for (const resolve of waiting) resolve(meta.threadId);
+      }
       if (latest.current.threadId === void 0 && meta.threadId && createdThreadId.current !== meta.threadId) {
         createdThreadId.current = meta.threadId;
         const pin = pendingPin.current;
@@ -5437,27 +5683,10 @@ function useAgentChat(options = {}) {
         agent: options.agent
       } : {},
       getBody: /* @__PURE__ */ __name(() => {
-        const current = latest.current;
-        const pageContext = current.getPageContext?.() ?? null;
         const regenerate2 = regenerateNext.current;
         regenerateNext.current = false;
-        const threadId = currentThreadId();
-        const model = current.model ?? (lockedRef.current ? void 0 : pickedModelRef.current);
         return {
-          // Read per send: a host that switches agents before the first message (a picker on a
-          // new chat) sends the one picked now, not the one this chat mounted with.
-          ...current.agent !== void 0 ? {
-            agent: current.agent
-          } : {},
-          ...threadId !== void 0 ? {
-            threadId
-          } : {},
-          ...model !== void 0 ? {
-            model
-          } : {},
-          ...pageContext ? {
-            pageContext
-          } : {},
+          ...turnBody(),
           ...regenerate2 ? {
             regenerate: true
           } : {}
@@ -5467,7 +5696,11 @@ function useAgentChat(options = {}) {
       onMeta,
       onAttemptStart: /* @__PURE__ */ __name(() => {
         settlingRunIdRef.current = void 0;
-      }, "onAttemptStart")
+      }, "onAttemptStart"),
+      // A queued turn this chat went to attach to had already finished: read what it wrote.
+      onResumeGone: /* @__PURE__ */ __name(() => {
+        void resyncFromThread();
+      }, "onResumeGone")
     });
   }, []);
   const backgroundRef = (0, import_react23.useRef)(() => Promise.resolve());
@@ -5480,6 +5713,9 @@ function useAgentChat(options = {}) {
     } : {},
     onData: /* @__PURE__ */ __name((part) => {
       latest.current.onData?.(part);
+      if (part.type === "data-queue") {
+        onQueueData(part.data);
+      }
       if (part.type === "data-title") {
         const title = part.data?.title;
         if (typeof title === "string") {
@@ -5511,6 +5747,20 @@ function useAgentChat(options = {}) {
       setConnection({
         status: "live"
       });
+      const queuedInstead = queuedSend.current;
+      if (queuedInstead !== void 0) {
+        queuedSend.current = void 0;
+        chatRef.current.setMessages((current) => {
+          const last = lastUserIndex(current);
+          return last === -1 ? current : current.slice(0, last);
+        });
+      }
+      const next = handoff.current;
+      handoff.current = void 0;
+      if (next !== void 0) {
+        attachTo(next);
+        return;
+      }
       if (resyncAfterSettle.current) {
         resyncAfterSettle.current = false;
         void resyncFromThread();
@@ -5519,6 +5769,46 @@ function useAgentChat(options = {}) {
   });
   const chatRef = (0, import_react23.useRef)(chat);
   chatRef.current = chat;
+  function onQueueData(data) {
+    const frame = data ?? {};
+    const before = queueStateRef.current;
+    if (frame.queue !== void 0) applyQueue(frame.queue);
+    const started = frame.started;
+    if (started !== void 0 && started.runId !== settlingRunIdRef.current) {
+      const waiting = before.items.find((item) => item.id === started.messageId);
+      handoff.current = {
+        ...started,
+        text: waiting?.content ?? "",
+        attachments: waiting?.attachments ?? []
+      };
+    }
+    if (frame.queuedSend !== void 0) {
+      queuedSend.current = frame.queuedSend;
+      if (frame.queuedSend.runId !== void 0) {
+        handoff.current = {
+          messageId: frame.queuedSend.messageId,
+          runId: frame.queuedSend.runId,
+          ...draftOf(chatRef.current.messages[lastUserIndex(chatRef.current.messages)])
+        };
+      }
+    }
+  }
+  __name(onQueueData, "onQueueData");
+  function attachTo(turn) {
+    setTimeout(() => {
+      if (turn.text.length > 0 || turn.attachments.length > 0) {
+        chatRef.current.setMessages((current) => current.some((message) => message.id === turn.messageId) ? current : [
+          ...current,
+          queuedUserMessage(turn)
+        ]);
+      } else {
+        resyncAfterSettle.current = true;
+      }
+      autoResumeRunIdRef.current = turn.runId;
+      void chatRef.current.resumeStream();
+    }, 0);
+  }
+  __name(attachTo, "attachTo");
   async function resyncFromThread() {
     const threadId = currentThreadId();
     if (threadId === void 0) return;
@@ -5541,6 +5831,11 @@ function useAgentChat(options = {}) {
     setHistoryError(null);
     autoResumeRunIdRef.current = void 0;
     pendingPin.current = void 0;
+    applyQueue(EMPTY_QUEUE);
+    setPendingSends([]);
+    setQueueError(null);
+    handoff.current = void 0;
+    queuedSend.current = void 0;
   }, [
     chatId
   ]);
@@ -5560,6 +5855,11 @@ function useAgentChat(options = {}) {
       setActiveRunId(active);
       setThreadModel(thread.model ?? null);
       setHistoryError(null);
+      const queue2 = thread.queue ?? EMPTY_QUEUE;
+      applyQueue(queue2);
+      if (queue2.items.length > 0 && queue2.paused === null && active === null && typeof client.resumeQueue === "function") {
+        void resumeQueueRef.current().catch(() => void 0);
+      }
       const resuming = wantResume && active !== null;
       if (wantHistory && chatRef.current.messages.length === 0) {
         const rows = resuming ? stored.filter((message) => !(message.role === "assistant" && message.runId === active)) : stored;
@@ -5595,10 +5895,98 @@ function useAgentChat(options = {}) {
   const blocked = options.blocked !== void 0 ? options.blocked : quota.blocked;
   const blockedRef = (0, import_react23.useRef)(blocked);
   blockedRef.current = blocked;
+  const whileRunning = typeof client.enqueueMessage === "function" ? options.whileRunning ?? "queue" : "block";
+  const whileRunningRef = (0, import_react23.useRef)(whileRunning);
+  whileRunningRef.current = whileRunning;
+  const threadForQueue = (0, import_react23.useCallback)(async () => {
+    const known = currentThreadId();
+    if (known !== void 0) return known;
+    if (!isTurnInFlight()) throw new Error("queue: this chat has no thread yet");
+    return new Promise((resolve) => threadWaiters.current.push(resolve));
+  }, [
+    currentThreadId,
+    isTurnInFlight
+  ]);
+  const queueCall = (0, import_react23.useCallback)(async (run) => {
+    try {
+      const result = await run();
+      setQueueError(null);
+      return result;
+    } catch (error) {
+      setQueueError(error instanceof Error ? error : new Error(String(error)));
+      throw error;
+    }
+  }, []);
+  const enqueue = (0, import_react23.useCallback)(async (text2, { attachments = [], mode = "queue" } = {}) => {
+    const block = blockedRef.current;
+    if (block != null) throw new QuotaBlockedError(block);
+    const send = client.enqueueMessage;
+    if (typeof send !== "function") throw new AgentBackendUnsupportedError("enqueueMessage");
+    localQueueSequence += 1;
+    const localId = `local-queued-${localQueueSequence}`;
+    setPendingSends((current) => [
+      ...current,
+      {
+        id: localId,
+        text: text2,
+        attachments,
+        state: "sending",
+        interrupt: mode === "interrupt",
+        createdAt: (/* @__PURE__ */ new Date()).toISOString()
+      }
+    ]);
+    try {
+      await queueCall(async () => {
+        const threadId = await threadForQueue();
+        const result = await send.call(client, {
+          body: {
+            ...turnBody(),
+            threadId,
+            message: text2,
+            mode,
+            ...attachments.length > 0 ? {
+              attachments: attachments.map(({ mediaId }) => ({
+                mediaId
+              }))
+            } : {}
+          }
+        });
+        applyQueue(result.queue);
+        if (result.runId !== void 0) {
+          const turn = {
+            messageId: result.messageId,
+            runId: result.runId,
+            text: text2,
+            attachments
+          };
+          if (isTurnInFlight()) handoff.current = turn;
+          else attachTo(turn);
+        }
+      });
+    } finally {
+      setPendingSends((current) => current.filter((item) => item.id !== localId));
+    }
+  }, [
+    client,
+    queueCall,
+    threadForQueue,
+    turnBody,
+    applyQueue,
+    isTurnInFlight
+  ]);
   const sendMessage = (0, import_react23.useCallback)(async (...args) => {
     const block = blockedRef.current;
     if (block != null) throw new QuotaBlockedError(block);
-    if (isTurnInFlight()) return;
+    if (isTurnInFlight()) {
+      const mode = whileRunningRef.current;
+      if (mode === "block") return;
+      const draft = draftOf(args[0]);
+      await enqueue(draft.text, {
+        attachments: draft.attachments,
+        mode
+      });
+      return;
+    }
     turnInFlight.current = true;
     try {
       await chatRef.current.sendMessage(...args);
@@ -5606,8 +5994,122 @@ function useAgentChat(options = {}) {
       turnInFlight.current = false;
     }
   }, [
+    isTurnInFlight,
+    enqueue
+  ]);
+  const removeQueued = (0, import_react23.useCallback)(async (id) => {
+    const previous = queueStateRef.current;
+    applyQueue({
+      ...previous,
+      items: previous.items.filter((item) => item.id !== id)
+    });
+    try {
+      applyQueue(await queueCall(() => requireBackendMethod(client, "removeQueuedMessage")(id)));
+    } catch (error) {
+      applyQueue(previous);
+      throw error;
+    }
+  }, [
+    client,
+    queueCall,
+    applyQueue
+  ]);
+  const editQueued = (0, import_react23.useCallback)(async (id, text2) => {
+    applyQueue(await queueCall(() => requireBackendMethod(client, "updateQueuedMessage")(id, {
+      message: text2
+    })));
+  }, [
+    client,
+    queueCall,
+    applyQueue
+  ]);
+  const moveQueued = (0, import_react23.useCallback)(async (id, index) => {
+    const previous = queueStateRef.current;
+    const moving = previous.items.find((item) => item.id === id);
+    if (moving !== void 0) {
+      const rest = previous.items.filter((item) => item.id !== id);
+      rest.splice(Math.max(0, Math.min(rest.length, index)), 0, moving);
+      applyQueue({
+        ...previous,
+        items: rest
+      });
+    }
+    try {
+      applyQueue(await queueCall(() => requireBackendMethod(client, "updateQueuedMessage")(id, {
+        position: index
+      })));
+    } catch (error) {
+      applyQueue(previous);
+      throw error;
+    }
+  }, [
+    client,
+    queueCall,
+    applyQueue
+  ]);
+  const clearQueue = (0, import_react23.useCallback)(async () => {
+    const threadId = currentThreadId();
+    if (threadId === void 0) return;
+    applyQueue(await queueCall(() => requireBackendMethod(client, "clearQueue")(threadId)));
+  }, [
+    client,
+    queueCall,
+    currentThreadId,
+    applyQueue
+  ]);
+  const resumeQueue = (0, import_react23.useCallback)(async () => {
+    const threadId = currentThreadId();
+    if (threadId === void 0) return;
+    const before = queueStateRef.current;
+    const result = await queueCall(() => requireBackendMethod(client, "resumeQueue")(threadId));
+    applyQueue({
+      items: result.items,
+      paused: result.paused
+    });
+    if (result.runId !== void 0) {
+      const head = before.items.find((item) => item.id === result.runId) ?? before.items[0];
+      const turn = {
+        messageId: result.runId,
+        runId: result.runId,
+        text: head?.content ?? "",
+        attachments: head?.attachments ?? []
+      };
+      if (isTurnInFlight()) handoff.current = turn;
+      else attachTo(turn);
+    }
+  }, [
+    client,
+    queueCall,
+    currentThreadId,
+    applyQueue,
     isTurnInFlight
   ]);
+  const resumeQueueRef = (0, import_react23.useRef)(resumeQueue);
+  resumeQueueRef.current = resumeQueue;
+  const queuedItems = [
+    ...pendingSends.filter((item) => item.interrupt),
+    ...queueState.items.map((item) => ({
+      id: item.id,
+      text: item.content,
+      attachments: item.attachments ?? [],
+      state: "queued",
+      interrupt: item.interrupt === true,
+      createdAt: item.createdAt
+    })),
+    ...pendingSends.filter((item) => !item.interrupt)
+  ];
+  const queue = {
+    items: queuedItems,
+    paused: queueState.paused,
+    isSupported: typeof client.enqueueMessage === "function",
+    add: enqueue,
+    remove: removeQueued,
+    edit: editQueued,
+    move: moveQueued,
+    clear: clearQueue,
+    resume: resumeQueue,
+    error: queueError
+  };
   const addToolResult = (0, import_react23.useCallback)(({ tool, toolCallId, output }) => chatRef.current.addToolResult({
     tool,
     toolCallId,
@@ -5848,12 +6350,14 @@ function useAgentChat(options = {}) {
   };
   const status = connection.status === "reconnecting" ? "reconnecting" : chat.status;
   const isBusy = status === "submitted" || status === "streaming" || status === "reconnecting";
+  const isBusyRef = (0, import_react23.useRef)(isBusy);
+  isBusyRef.current = isBusy;
   const files = useAttachments({
     ...options.composer,
     backend: client
   });
   const [text, setText] = (0, import_react23.useState)("");
-  const blockedBy = blocked != null ? "quota" : files.isUploading ? "uploading" : isBusy ? "busy" : text.trim().length === 0 && files.refs.length === 0 ? "empty" : null;
+  const blockedBy = blocked != null ? "quota" : files.isUploading ? "uploading" : isBusy && whileRunning === "block" ? "busy" : text.trim().length === 0 && files.refs.length === 0 ? "empty" : null;
   const composerRef = (0, import_react23.useRef)({
     text,
     files,
@@ -5884,6 +6388,17 @@ function useAgentChat(options = {}) {
     const draft = current.text.trim();
     setText("");
     current.files.clear();
+    const mode = whileRunningRef.current;
+    if (mode !== "block" && (isTurnInFlight() || isBusyRef.current)) {
+      const attachments = current.files.items.flatMap((item) => item.status === "ready" && item.attachment !== void 0 ? [
+        item.attachment
+      ] : []);
+      await enqueue(draft, {
+        attachments,
+        mode
+      });
+      return;
+    }
     await sendMessage(files2.length > 0 ? {
       text: draft,
       files: files2
@@ -5895,7 +6410,9 @@ function useAgentChat(options = {}) {
       }
     } : void 0);
   }, [
-    sendMessage
+    sendMessage,
+    enqueue,
+    isTurnInFlight
   ]);
   const composer = {
     text,
@@ -5930,6 +6447,11 @@ function useAgentChat(options = {}) {
     ...ownCatalog === void 0 ? {
       toolCatalog: tools.catalog
     } : {},
+    queue: {
+      items: queue.items,
+      paused: queue.paused,
+      remove: removeQueued
+    },
     ...options.transcript
   });
   const background = {
@@ -5964,6 +6486,11 @@ function useAgentChat(options = {}) {
     transcript,
     /** A headless composer: draft, files, send gate, `submit()`. */
     composer,
+    /**
+    * Messages sent while a turn was running, waiting their turn (server-side): list, edit, move,
+    * remove, clear, and resume a paused queue.
+    */
+    queue,
     /** The model picker: `list`, `selected`, `select(id)`, `pinToThread(id)`. */
     models,
     /** The caller's budget (`GET <base>/quota`); `quota.blocked` gates sends. */