@agents24/react 0.2.23 → 0.2.25

package/dist/index.js

@@ -571,11 +571,12 @@ function Agents24Provider({
   createAbortController,
   createId = createPortableId,
   storage,
-  visibility
+  visibility,
+  onHitlTiming
 }) {
   const value = React2.useMemo(
-    () => ({ client, createAbortController, createId, storage, visibility: visibility ?? client.visibility }),
-    [client, createAbortController, createId, storage, visibility]
+    () => ({ client, createAbortController, createId, storage, visibility: visibility ?? client.visibility, onHitlTiming }),
+    [client, createAbortController, createId, storage, visibility, onHitlTiming]
   );
   return /* @__PURE__ */ jsx(Agents24Context.Provider, { value, children });
 }
@@ -636,6 +637,41 @@ function createRuntimeEventFrameBuffer(apply, scheduleFrame) {
   };
 }
 
+// src/hitl-resolution.ts
+function applyHitlResolution(messages, receipt) {
+  return messages.map((message) => message.runId !== receipt.run_id ? message : {
+    ...message,
+    parts: message.parts.map((part) => part.kind !== "hitl" || part.interruptId !== receipt.interrupt_id ? part : {
+      ...part,
+      status: receipt.resolution.status,
+      resolution: {
+        ...receipt.resolution,
+        answers: receipt.resolution.answers?.map((answer) => ({
+          questionId: answer.question_id,
+          selectedOptionIds: [...answer.selected_option_ids],
+          ...answer.custom_text ? { customText: answer.custom_text } : {}
+        }))
+      }
+    })
+  });
+}
+function findHitlResolution(messages, runId, interruptId) {
+  return messages.filter((message) => message.runId === runId).flatMap((message) => message.parts).find((part) => part.kind === "hitl" && part.interruptId === interruptId && part.status !== "pending");
+}
+function preserveResolvedHitlParts(current, incoming) {
+  const resolved = current.filter((part) => part.kind === "hitl" && part.status !== "pending");
+  if (!resolved.length) return incoming;
+  const next = incoming.map((part) => {
+    if (part.kind !== "hitl" || part.status !== "pending") return part;
+    const known = resolved.find((item) => item.interruptId === part.interruptId);
+    return known ? { ...part, status: known.status, resolution: known.resolution } : part;
+  });
+  for (const part of resolved) if (!next.some((item) => item.kind === "hitl" && item.interruptId === part.interruptId)) {
+    next.splice(Math.min(current.indexOf(part), next.length), 0, part);
+  }
+  return next;
+}
+
 // src/state.ts
 import {
   compressionFromContextWindow as compressionFromContextWindow2,
@@ -751,6 +787,7 @@ 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);
+    if (live && live.runId === message.runId) message = { ...message, parts: preserveResolvedHitlParts(live.parts, message.parts) };
     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, feedback: message.feedback, durableId: message.durableId || live.durableId } : message;
   });
   const retainedIds = new Set(retained.map((message) => message.id));
@@ -894,7 +931,7 @@ function applyRuntimeEvent(state, event) {
     delta,
     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 lifecycleParts = reconcileModelTurnParts(preserveResolvedHitlParts(existing?.parts || [], projectedParts), event);
   const compressionPart = contextApplies && explicitCompression?.active ? contextCompressionPartFromEvent(event, lifecycleParts) : null;
   const parts = compressionPart ? upsertResponseBlockParts(lifecycleParts, [compressionPart]) : lifecycleParts;
   const activeThreadId = eventThreadId || state.activeThreadId;
@@ -1033,7 +1070,7 @@ function captureChatOperation(read, options = {}) {
   const owner = read();
   return () => {
     const current = read();
-    return current.generation === owner.generation && (options.adoptThread || current.threadId === owner.threadId) && (!options.run || current.runId === owner.runId) && (!options.stream || current.stream === owner.stream);
+    return current.client === owner.client && current.generation === owner.generation && (options.adoptThread || current.threadId === owner.threadId) && (!options.run || current.runId === owner.runId) && (!options.stream || current.stream === owner.stream);
   };
 }
 
@@ -1382,8 +1419,202 @@ function discardOptimisticSubmission(state, message) {
   };
 }
 
+// src/use-agent-chat-hitl-submissions.ts
+import * as React4 from "react";
+
+// src/hitl-submission.ts
+var timers = globalThis;
+async function withHitlDeadline(factory, work, ms = 15e3) {
+  const abort = factory();
+  let timer;
+  try {
+    return await Promise.race([work(abort.signal), new Promise((_, reject) => {
+      timer = timers.setTimeout(() => {
+        abort.abort();
+        reject(new Error("Submission acknowledgement timed out."));
+      }, ms);
+    })]);
+  } finally {
+    timers.clearTimeout(timer);
+  }
+}
+function isDefinitiveHitlRejection(error) {
+  const status = error?.status ?? error?.statusCode;
+  return typeof status === "number" && status >= 400 && status < 500 && ![408, 409, 425, 429].includes(status);
+}
+function createHitlSubmission(options) {
+  const response = { ...options.response, answers: options.response.answers?.map((answer) => ({
+    ...answer,
+    selected_option_ids: [...answer.selected_option_ids]
+  })) };
+  let pending;
+  let accepted = false;
+  let failed = false;
+  let uncertain = false;
+  const now = options.now ?? Date.now;
+  const publish = (state) => {
+    if (options.isCurrent()) options.changed(state);
+  };
+  const accept = (receipt) => {
+    if (!options.isCurrent() || accepted) return;
+    accepted = true;
+    uncertain = false;
+    options.accept(receipt);
+    publish({ action: receipt.resolution.action || response.action, status: "accepted" });
+  };
+  const retry = () => {
+    if (pending) return pending;
+    if (accepted || !options.isCurrent()) return Promise.resolve();
+    failed = false;
+    uncertain = false;
+    publish({ action: response.action, status: "submitting" });
+    pending = Promise.resolve().then(async () => {
+      try {
+        await withHitlDeadline(options.createAbortController, async (signal) => {
+          const started = now();
+          await options.prepare?.({ signal });
+          options.timing?.("preparation", now() - started);
+          if (!options.isCurrent() || signal.aborted) return;
+          const submitted = now();
+          const receipt = await options.send(response, options.idempotencyKey, signal);
+          options.timing?.("acknowledgement", now() - submitted);
+          accept(receipt);
+        });
+      } catch (error) {
+        if (!options.isCurrent() || accepted) return;
+        if (isDefinitiveHitlRejection(error)) {
+          failed = true;
+          publish({ action: response.action, status: "error", error: error instanceof Error ? error.message : "Submission was rejected." });
+          throw error;
+        }
+        publish({ action: response.action, status: "checking" });
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+          try {
+            const resolved = await withHitlDeadline(options.createAbortController, options.reconcile, 3e3);
+            if (resolved) accept(resolved);
+          } catch {
+          }
+          if (accepted || !options.isCurrent()) return;
+        }
+        uncertain = true;
+        publish({ action: response.action, status: "uncertain", retry });
+      }
+    }).finally(() => {
+      pending = void 0;
+    });
+    return pending;
+  };
+  return { retry, get failed() {
+    return failed;
+  }, get uncertain() {
+    return uncertain;
+  } };
+}
+
+// src/use-agent-chat-hitl-submissions.ts
+function hitlSubmissionKey(threadId, runId, interruptId, generation) {
+  return `${generation}:${threadId}:${runId}:${interruptId}`;
+}
+function useAgentChatHitlSubmissions(options) {
+  const latest = React4.useRef(options);
+  latest.current = options;
+  const mounted = React4.useRef(true);
+  const operations = React4.useRef(/* @__PURE__ */ new Map());
+  const [states, setStates] = React4.useState({});
+  const clientRef = React4.useRef(options.client);
+  if (clientRef.current !== options.client) {
+    clientRef.current = options.client;
+    operations.current.clear();
+  }
+  React4.useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+      operations.current.clear();
+    };
+  }, []);
+  const resumeHitl = React4.useCallback((part, response, submission) => {
+    const captured = latest.current;
+    const { client, runtime, stateRef, ownOperation, pageSize } = captured;
+    const threadId = stateRef.current.activeThreadId;
+    const runId = part.runId || stateRef.current.messages.find((message) => message.parts.some((candidate) => candidate.id === part.id))?.runId || stateRef.current.activeRunId;
+    if (!threadId || !runId) return Promise.reject(new Error("No paused run is available to resume."));
+    const isOwned = ownOperation();
+    const isCurrent = () => mounted.current && latest.current.client === client && isOwned() && (!stateRef.current.activeRunId || stateRef.current.activeRunId === runId);
+    const key = hitlSubmissionKey(threadId, runId, part.interruptId, captured.selectionGeneration.current);
+    const live = stateRef.current.messages.filter((message) => message.runId === runId).flatMap((message) => message.parts).find((candidate) => candidate.kind === "hitl" && candidate.interruptId === part.interruptId);
+    if (part.status !== "pending" || live && live.status !== "pending") return Promise.resolve();
+    const previous = operations.current.get(key);
+    if (previous && !previous.failed) return previous.retry();
+    if (["cancelling", "cancelled", "failed", "completed"].includes(stateRef.current.runState)) return Promise.resolve();
+    const operation = createHitlSubmission({
+      response,
+      idempotencyKey: runtime.createId(),
+      prepare: submission?.prepare,
+      createAbortController: runtime.createAbortController,
+      isCurrent,
+      send: (decision, idempotencyKey, signal) => client.hitl.resume({ runId, interruptId: part.interruptId, ...decision, idempotencyKey, signal }),
+      accept: (receipt) => {
+        captured.accept(receipt);
+        if (!["completed", "failed", "cancelled"].includes(receipt.run_status || "")) captured.attach(receipt.run_id);
+      },
+      reconcile: async (signal) => {
+        const [page, detail] = await Promise.all([
+          client.threads.messages.list({ threadId, limit: pageSize, signal }),
+          client.threads.get({ threadId, limit: pageSize, signal })
+        ]);
+        if (!isCurrent()) return null;
+        const part2 = findHitlResolution(threadTimelineToMessages(page.items), runId, capturedPart.interruptId);
+        if (!part2?.resolution) return null;
+        return {
+          run_id: runId,
+          thread_id: threadId,
+          interrupt_id: part2.interruptId,
+          run_status: detail.active_run?.run_id === runId ? detail.active_run.status : detail.last_run_id === runId ? detail.last_run_status || void 0 : void 0,
+          resolution: {
+            ...part2.resolution,
+            status: part2.status,
+            action: part2.resolution.action || null,
+            outcome: part2.resolution.outcome || part2.status,
+            resolved_at: part2.resolution.resolved_at,
+            answers: part2.resolution.answers?.map((answer) => ({
+              question_id: answer.questionId,
+              selected_option_ids: answer.selectedOptionIds,
+              custom_text: answer.customText
+            }))
+          }
+        };
+      },
+      changed: (state) => {
+        if (isCurrent()) setStates((current) => ({ ...current, [key]: state }));
+      },
+      timing: (stage, durationMs) => runtime.onHitlTiming?.({ stage, durationMs })
+    });
+    const capturedPart = part;
+    operations.current.set(key, operation);
+    return operation.retry();
+  }, []);
+  const selection = options.stateRef.current.activeThreadId;
+  const generation = options.selectionGeneration.current;
+  React4.useEffect(() => {
+    const prefix = `${generation}:${selection}:`;
+    for (const key of operations.current.keys()) if (!key.startsWith(prefix)) operations.current.delete(key);
+    setStates((current) => Object.fromEntries(Object.entries(current).filter(([key]) => key.startsWith(prefix))));
+  }, [options.client, selection, generation]);
+  return { resumeHitl, getHitlSubmissionState: (part) => {
+    const runId = part.runId || options.stateRef.current.messages.find((message) => message.parts.some((candidate) => candidate.id === part.id))?.runId || options.stateRef.current.activeRunId;
+    const key = runId ? hitlSubmissionKey(selection, runId, part.interruptId, generation) : null;
+    const state = key && operations.current.has(key) ? states[key] : void 0;
+    if (!state) return void 0;
+    if (part.status !== "pending") {
+      return !options.stateRef.current.activeRunId || ["completed", "failed", "cancelled"].includes(options.stateRef.current.runState) ? void 0 : { action: String(part.resolution?.action || state.action), status: "accepted" };
+    }
+    return state;
+  } };
+}
+
 // src/use-agent-chat.ts
-import * as React7 from "react";
+import * as React8 from "react";
 
 // src/refresh-chat-summaries.ts
 async function refreshChatSummaries(input) {
@@ -1433,17 +1664,17 @@ async function refreshChatSummaries(input) {
 }
 
 // src/use-agent-chat-thread-list.ts
-import * as React4 from "react";
+import * as React5 from "react";
 function summaryToStored(thread) {
   return { ...thread, id: String(thread.id), messages: [], isHydrated: false };
 }
 function useAgentChatThreadList({ client, threadPageSize, stateRef, update, clearOperationError, failOperation }) {
-  const [isLoadingThreads, setIsLoadingThreads] = React4.useState(false);
-  const [isLoadingMoreThreads, setIsLoadingMoreThreads] = React4.useState(false);
-  const [threadTotal, setThreadTotal] = React4.useState();
-  const refreshPromiseRef = React4.useRef(null);
-  const eventsDuringRefreshRef = React4.useRef(null);
-  const refreshThreads = React4.useCallback(() => {
+  const [isLoadingThreads, setIsLoadingThreads] = React5.useState(false);
+  const [isLoadingMoreThreads, setIsLoadingMoreThreads] = React5.useState(false);
+  const [threadTotal, setThreadTotal] = React5.useState();
+  const refreshPromiseRef = React5.useRef(null);
+  const eventsDuringRefreshRef = React5.useRef(null);
+  const refreshThreads = React5.useCallback(() => {
     if (refreshPromiseRef.current) return refreshPromiseRef.current;
     clearOperationError();
     setIsLoadingThreads(true);
@@ -1478,7 +1709,7 @@ function useAgentChatThreadList({ client, threadPageSize, stateRef, update, clea
     }).catch(() => void 0);
     return request;
   }, [clearOperationError, client, failOperation, threadPageSize, update]);
-  const loadMoreThreads = React4.useCallback(async () => {
+  const loadMoreThreads = React5.useCallback(async () => {
     if (isLoadingMoreThreads) return;
     const skip = stateRef.current.threads.length;
     if (threadTotal !== void 0 && skip >= threadTotal) return;
@@ -1513,10 +1744,10 @@ function useAgentChatThreadList({ client, threadPageSize, stateRef, update, clea
 }
 
 // src/use-agent-chat-feedback.ts
-import * as React5 from "react";
+import * as React6 from "react";
 function useAgentChatFeedback({ client, update, clearOperationError, failOperation, ownOperation, refreshMessages }) {
-  const mutations = React5.useRef(/* @__PURE__ */ new Map());
-  const captureRead = React5.useCallback(() => {
+  const mutations = React6.useRef(/* @__PURE__ */ new Map());
+  const captureRead = React6.useCallback(() => {
     const revisions = new Map([...mutations.current].map(([run, mutation]) => [run, mutation.readRevision]));
     return (incoming, current) => incoming.map((message) => {
       const mutation = message.runId ? mutations.current.get(message.runId) : void 0;
@@ -1525,7 +1756,7 @@ function useAgentChatFeedback({ client, update, clearOperationError, failOperati
       return live ? { ...message, feedback: live.feedback } : message;
     });
   }, []);
-  const setFeedback = React5.useCallback(async (message, input) => {
+  const setFeedback = React6.useCallback(async (message, input) => {
     const runId = message.runId;
     if (!runId || message.role !== "assistant" || message.isFinal === false) {
       const error = new Error("Only persisted final responses can receive feedback.");
@@ -1575,7 +1806,7 @@ function useAgentChatFeedback({ client, update, clearOperationError, failOperati
 }
 
 // src/use-agent-chat-queue-actions.ts
-import * as React6 from "react";
+import * as React7 from "react";
 function useAgentChatQueueActions({
   queue,
   stateRef,
@@ -1586,7 +1817,7 @@ function useAgentChatQueueActions({
   attachRun,
   ownOperation
 }) {
-  const steer = React6.useCallback(async (text2) => {
+  const steer = React7.useCallback(async (text2) => {
     const threadId = stateRef.current.activeThreadId;
     if (!threadId || !text2.trim()) throw new Error("An active thread and text are required to steer.");
     const isCurrent = ownOperation();
@@ -1599,7 +1830,7 @@ function useAgentChatQueueActions({
       throw error;
     }
   }, [clearOperationError, createId, failOperation, queue.submit, refreshMessages, stateRef, ownOperation]);
-  const editPendingMessage = React6.useCallback(async (message, input) => {
+  const editPendingMessage = React7.useCallback(async (message, input) => {
     await queue.edit(message, {
       text: input.text,
       attachmentIds: input.attachmentIds ?? message.attachment_ids,
@@ -1607,10 +1838,10 @@ function useAgentChatQueueActions({
       requestedModelId: input.requestedModelId
     });
   }, [queue.edit]);
-  const steerPendingMessage = React6.useCallback(async (message) => {
+  const steerPendingMessage = React7.useCallback(async (message) => {
     await queue.edit(message, { text: message.text, attachmentIds: message.attachment_ids, mode: "steer" });
   }, [queue.edit]);
-  const resumeQueue = React6.useCallback(async () => {
+  const resumeQueue = React7.useCallback(async () => {
     if (!stateRef.current.activeThreadId) return;
     const isCurrent = ownOperation();
     const result = await queue.resume();
@@ -1638,7 +1869,7 @@ function useAgentChat(options = {}) {
   const client = options.client || runtime.client;
   const pageSize = options.pageSize ?? 30;
   const threadPageSize = options.threadPageSize ?? 50;
-  const [state, setState] = React7.useState(() => ({
+  const [state, setState] = React8.useState(() => ({
     ...initialAgentChatState,
     activeThreadId: resolveInitialActiveThreadId(
       options,
@@ -1646,37 +1877,51 @@ function useAgentChat(options = {}) {
     ),
     threads: runtime.storage?.loadThreads() ?? []
   }));
-  const [isLoadingHistory, setIsLoadingHistory] = React7.useState(false);
-  const [isLoadingOlder, setIsLoadingOlder] = React7.useState(false);
-  const [isSubmitting, setIsSubmitting] = React7.useState(false);
-  const streamControllerRef = React7.useRef(null);
-  const threadOpenControllerRef = React7.useRef(null);
-  const threadOpenGenerationRef = React7.useRef(0);
-  const attachRunRef = React7.useRef(async () => void 0);
-  const messageRefreshVersionRef = React7.useRef(0);
-  const promotedRunHintRef = React7.useRef(null);
-  const promotedAttachRef = React7.useRef(null);
-  const olderRequestRef = React7.useRef(null);
-  const submissionGenerationRef = React7.useRef(0);
-  const stateRef = React7.useRef(state);
+  const [isLoadingHistory, setIsLoadingHistory] = React8.useState(false);
+  const [isLoadingOlder, setIsLoadingOlder] = React8.useState(false);
+  const [isSubmitting, setIsSubmitting] = React8.useState(false);
+  const streamControllerRef = React8.useRef(null);
+  const threadOpenControllerRef = React8.useRef(null);
+  const threadOpenGenerationRef = React8.useRef(0);
+  const attachRunRef = React8.useRef(async () => void 0);
+  const messageRefreshVersionRef = React8.useRef(0);
+  const promotedRunHintRef = React8.useRef(null);
+  const promotedAttachRef = React8.useRef(null);
+  const olderRequestRef = React8.useRef(null);
+  const submissionGenerationRef = React8.useRef(0);
+  const continuationTiming = React8.useRef(/* @__PURE__ */ new Map());
+  const resolutionFences = React8.useRef(/* @__PURE__ */ new Map());
+  const clientIdentityRef = React8.useRef(client);
+  if (clientIdentityRef.current !== client) {
+    resolutionFences.current.clear();
+    continuationTiming.current.clear();
+    clientIdentityRef.current = client;
+  }
+  const stateRef = React8.useRef(state);
   stateRef.current = state;
-  const ownOperation = React7.useCallback((options2) => captureChatOperation(() => ({
+  const ownOperation = React8.useCallback((options2) => captureChatOperation(() => ({
+    client: clientIdentityRef.current,
     generation: threadOpenGenerationRef.current,
     threadId: stateRef.current.activeThreadId,
     runId: stateRef.current.activeRunId,
     stream: streamControllerRef.current
   }), options2), []);
-  const persist = React7.useCallback((next) => {
+  const persist = React8.useCallback((next) => {
     runtime.storage?.saveThreads(next.threads);
     runtime.storage?.saveActiveThreadId?.(next.activeThreadId);
   }, [runtime.storage]);
-  const update = React7.useCallback((updater) => {
-    const next = updater(stateRef.current);
+  const update = React8.useCallback((updater) => {
+    let next = updater(stateRef.current);
+    for (const receipt of resolutionFences.current.values()) next = {
+      ...next,
+      messages: applyHitlResolution(next.messages, receipt),
+      threads: next.threads.map((thread) => thread.id !== receipt.thread_id ? thread : { ...thread, messages: applyHitlResolution(thread.messages, receipt) })
+    };
     stateRef.current = next;
     persist(next);
     setState(next);
   }, [persist]);
-  const queueTransport = React7.useMemo(() => ({
+  const queueTransport = React8.useMemo(() => ({
     list: (threadId, signal) => client.threads.messages.list({ threadId, limit: pageSize, signal }),
     submit: (input) => client.threads.messages.submit(input),
     edit: (message, input) => client.threads.messages.edit({
@@ -1694,7 +1939,7 @@ function useAgentChat(options = {}) {
     },
     resume: (threadId) => client.threads.resumeQueue({ threadId })
   }), [client, pageSize]);
-  const attachPromotion = React7.useCallback((runId, threadId) => {
+  const attachPromotion = React8.useCallback((runId, threadId) => {
     if (stateRef.current.activeThreadId !== threadId) return;
     promotedRunHintRef.current = runId;
     if (stateRef.current.activeRunId === runId || promotedAttachRef.current === runId) return;
@@ -1704,7 +1949,7 @@ function useAgentChat(options = {}) {
       if (isCurrent() && promotedAttachRef.current === runId) promotedAttachRef.current = null;
     });
   }, [ownOperation]);
-  const onQueuePromotion = React7.useCallback((message, runId) => {
+  const onQueuePromotion = React8.useCallback((message, runId) => {
     if (stateRef.current.activeThreadId !== message.thread_id) return;
     const userMessage = threadTimelineToMessages([{ ...message, run_id: runId, status: "delivered" }])[0];
     update((current) => current.activeThreadId === message.thread_id ? {
@@ -1729,20 +1974,20 @@ function useAgentChat(options = {}) {
     onDiscard: (message) => update((current) => discardOptimisticSubmission(current, message))
   });
   const { pendingMessages, messageQueue } = queue;
-  const eventBuffer = React7.useMemo(
+  const eventBuffer = React8.useMemo(
     () => createRuntimeEventFrameBuffer(
       (events) => update((current) => applyRuntimeEvents(current, events)),
       runtimeEventFrameScheduler()
     ),
     [update]
   );
-  const clearOperationError = React7.useCallback((operation) => {
+  const clearOperationError = React8.useCallback((operation) => {
     update((current) => clearAgentChatOperationError(current, operation));
   }, [update]);
-  const clearBackgroundError = React7.useCallback(() => {
+  const clearBackgroundError = React8.useCallback(() => {
     update(clearAgentChatBackgroundError);
   }, [update]);
-  const failOperation = React7.useCallback((operation, cause) => {
+  const failOperation = React8.useCallback((operation, cause) => {
     update((current) => withAgentChatOperationError(current, operation, cause));
   }, [update]);
   const {
@@ -1753,7 +1998,7 @@ function useAgentChat(options = {}) {
     refreshThreads,
     loadMoreThreads
   } = useAgentChatThreadList({ client, threadPageSize, stateRef, update, clearOperationError, failOperation });
-  const invalidateThreadOpen = React7.useCallback(() => {
+  const invalidateThreadOpen = React8.useCallback(() => {
     threadOpenGenerationRef.current += 1;
     threadOpenControllerRef.current?.abort("Thread selection changed.");
     threadOpenControllerRef.current = null;
@@ -1762,26 +2007,28 @@ function useAgentChat(options = {}) {
     promotedRunHintRef.current = null;
     olderRequestRef.current = null;
     queue.reset();
+    resolutionFences.current.clear();
+    continuationTiming.current.clear();
     setIsSubmitting(false);
     setIsLoadingOlder(false);
     setIsLoadingHistory(false);
   }, [queue.reset]);
-  const detach = React7.useCallback(() => {
+  const detach = React8.useCallback(() => {
     eventBuffer.flush();
     streamControllerRef.current?.abort();
     streamControllerRef.current = null;
     update((current) => ({ ...current, streamingMessageId: null, runState: current.activeRunId ? "reconnecting" : "idle" }));
   }, [eventBuffer, update]);
-  const refreshMessagesRef = React7.useRef(async () => void 0);
+  const refreshMessagesRef = React8.useRef(async () => void 0);
   const { setFeedback, captureRead: captureFeedbackRead } = useAgentChatFeedback({
     client,
     update,
     clearOperationError,
     failOperation,
     ownOperation,
-    refreshMessages: React7.useCallback(() => refreshMessagesRef.current(), [])
+    refreshMessages: React8.useCallback(() => refreshMessagesRef.current(), [])
   });
-  const refreshMessages = React7.useCallback(async (threadId, promotedRunId, signal) => {
+  const refreshMessages = React8.useCallback(async (threadId, promotedRunId, signal) => {
     const target = threadId || stateRef.current.activeThreadId;
     if (!target) return;
     const isCurrent = ownOperation();
@@ -1804,13 +2051,13 @@ function useAgentChat(options = {}) {
     });
   }, [client, ownOperation, pageSize, queue.hydrate, update, captureFeedbackRead]);
   refreshMessagesRef.current = refreshMessages;
-  React7.useEffect(() => () => {
+  React8.useEffect(() => () => {
     threadOpenGenerationRef.current += 1;
     eventBuffer.dispose();
     streamControllerRef.current?.abort();
     threadOpenControllerRef.current?.abort();
   }, [eventBuffer]);
-  const openThread = React7.useCallback(async (threadId) => {
+  const openThread = React8.useCallback(async (threadId) => {
     const previousSelection = captureAgentChatThreadSelection(stateRef.current);
     invalidateThreadOpen();
     const requestController = runtime.createAbortController();
@@ -1883,7 +2130,17 @@ function useAgentChat(options = {}) {
       }
     }
   }, [clearOperationError, client, detach, failOperation, pageSize, queue.hydrate, runtime, update, invalidateThreadOpen, ownOperation, captureFeedbackRead]);
-  const consumeEvent = React7.useCallback((event) => {
+  const consumeEvent = React8.useCallback((event) => {
+    const timing = continuationTiming.current.get(event.run_id);
+    if (timing && !timing.attached) {
+      timing.attached = true;
+      runtime.onHitlTiming?.({ stage: "attachment", durationMs: Date.now() - timing.acknowledgedAt });
+    }
+    if (timing && !timing.active && ["assistant.delta", "model.turn.started", "tool.started"].includes(event.event)) {
+      timing.active = true;
+      runtime.onHitlTiming?.({ stage: "first_activity", durationMs: Date.now() - timing.acknowledgedAt });
+    }
+    if (["run.completed", "run.cancelled", "run.failed"].includes(event.event)) continuationTiming.current.delete(event.run_id);
     const eventThreadId = typeof event.payload?.thread_id === "string" ? event.payload.thread_id.trim() : "";
     if (eventThreadId && !stateRef.current.activeThreadId) {
       queue.confirmThreadAdmission(eventThreadId);
@@ -1891,8 +2148,8 @@ function useAgentChat(options = {}) {
       setIsSubmitting(false);
     }
     eventBuffer.push(event);
-  }, [eventBuffer, update, queue.confirmThreadAdmission]);
-  const attachRun = React7.useCallback(async (runId, cursor) => {
+  }, [eventBuffer, update, queue.confirmThreadAdmission, runtime.onHitlTiming]);
+  const attachRun = React8.useCallback(async (runId, cursor) => {
     eventBuffer.flush();
     streamControllerRef.current?.abort();
     const controller = runtime.createAbortController();
@@ -1910,7 +2167,7 @@ function useAgentChat(options = {}) {
       if (!result.detached && result.threadId) await refreshMessages(result.threadId);
     } catch (error) {
       if (isCurrent() && !isAbortLike(error)) {
-        update((current) => ({ ...current, runState: "failed", streamingMessageId: null }));
+        update((current) => ({ ...current, runState: "reconnecting", streamingMessageId: null }));
         failOperation("attach_run", error);
         throw error;
       }
@@ -1919,7 +2176,7 @@ function useAgentChat(options = {}) {
     }
   }, [clearOperationError, client, consumeEvent, eventBuffer, failOperation, refreshMessages, runtime, update, ownOperation]);
   attachRunRef.current = attachRun;
-  const submit = React7.useCallback(async (input) => {
+  const submit = React8.useCallback(async (input) => {
     if (!input.text.trim() && !input.attachmentIds?.length && !input.uploads?.length) return;
     const existingThreadId = stateRef.current.activeThreadId;
     if (existingThreadId || queue.hasPendingAdmission()) {
@@ -2090,12 +2347,12 @@ function useAgentChat(options = {}) {
     attachRun,
     ownOperation
   });
-  const startNewThread = React7.useCallback(() => {
+  const startNewThread = React8.useCallback(() => {
     invalidateThreadOpen();
     detach();
     update((current) => ({ ...initialAgentChatState, threads: current.threads }));
   }, [detach, invalidateThreadOpen, update]);
-  const deleteThread = React7.useCallback(async (threadId) => {
+  const deleteThread = React8.useCallback(async (threadId) => {
     const isCurrent = ownOperation();
     clearOperationError();
     try {
@@ -2109,7 +2366,7 @@ function useAgentChat(options = {}) {
       }
     }
   }, [clearOperationError, client, failOperation, ownOperation, runtime, startNewThread, update]);
-  const cancelRun = React7.useCallback(async () => {
+  const cancelRun = React8.useCallback(async () => {
     const runId = stateRef.current.activeRunId;
     if (!runId || stateRef.current.runState === "cancelling") return;
     const isCurrent = ownOperation({ run: true, stream: true });
@@ -2150,29 +2407,27 @@ function useAgentChat(options = {}) {
       }
     }
   }, [clearOperationError, client, detach, failOperation, runtime, update, ownOperation]);
-  const resumeHitl = React7.useCallback(async (part, response) => {
-    const isCurrent = ownOperation({ run: true, stream: true });
-    const runId = stateRef.current.activeRunId || stateRef.current.messages.find((message) => message.parts.includes(part))?.runId;
-    clearOperationError();
-    if (!runId) {
-      const error = new Error("No paused run is available to resume.");
-      failOperation("resume_hitl", error);
-      throw error;
-    }
-    try {
-      const result = await client.hitl.resume({
-        runId,
-        interruptId: part.interruptId,
-        ...response,
-        idempotencyKey: runtime.createId()
+  const { resumeHitl, getHitlSubmissionState } = useAgentChatHitlSubmissions({
+    client,
+    runtime,
+    pageSize,
+    stateRef,
+    ownOperation,
+    selectionGeneration: threadOpenGenerationRef,
+    accept: (receipt) => {
+      resolutionFences.current.set(`${receipt.run_id}:${receipt.interrupt_id}`, receipt);
+      continuationTiming.current.set(receipt.run_id, { acknowledgedAt: Date.now(), attached: false, active: false });
+      update((current) => {
+        const status = receipt.run_status;
+        return current.activeRunId === receipt.run_id && (status === "completed" || status === "failed" || status === "cancelled") ? { ...current, activeRunId: null, runState: status, streamingMessageId: null } : current;
       });
-      if (isCurrent()) await attachRun(result.run_id || runId);
-    } catch (error) {
-      if (isCurrent() && !isAbortLike(error)) failOperation("resume_hitl", error);
-      throw error;
+    },
+    attach: (runId) => {
+      if (["completed", "failed", "cancelled", "cancelling"].includes(stateRef.current.runState)) return;
+      void attachRunRef.current(runId, stateRef.current.cursor ?? void 0).catch(() => void 0);
     }
-  }, [attachRun, clearOperationError, client, failOperation, runtime, ownOperation]);
-  const loadOlder = React7.useCallback(() => {
+  });
+  const loadOlder = React8.useCallback(() => {
     const thread = stateRef.current.threads.find((item) => item.id === stateRef.current.activeThreadId);
     if (thread?.nextBeforeTurnIndex == null) return Promise.resolve();
     const cursor = thread.nextBeforeTurnIndex;
@@ -2211,7 +2466,7 @@ function useAgentChat(options = {}) {
     olderRequestRef.current = { key, promise };
     return promise;
   }, [clearOperationError, client, failOperation, ownOperation, pageSize, update, captureFeedbackRead]);
-  const regenerate = React7.useCallback(async (message) => {
+  const regenerate = React8.useCallback(async (message) => {
     const index = stateRef.current.messages.findIndex((item) => item.id === message.id);
     const user = stateRef.current.messages.slice(0, index).reverse().find((item) => item.role === "user");
     if (user) await submit({
@@ -2297,7 +2552,7 @@ function useAgentChat(options = {}) {
       }
     }
   });
-  React7.useEffect(() => {
+  React8.useEffect(() => {
     const threadId = options.activeThreadId;
     const activeThread2 = stateRef.current.threads.find((thread) => thread.id === stateRef.current.activeThreadId);
     if (shouldHydrateSelectedThread(threadId, stateRef.current.activeThreadId, Boolean(activeThread2?.isHydrated))) {
@@ -2337,6 +2592,7 @@ function useAgentChat(options = {}) {
     resumeQueue,
     steer,
     resumeHitl,
+    getHitlSubmissionState,
     setFeedback,
     startNewThread,
     submit
@@ -2344,15 +2600,15 @@ function useAgentChat(options = {}) {
 }
 
 // src/use-agent-resources.ts
-import * as React8 from "react";
+import * as React9 from "react";
 function useAgentThreads(options = {}) {
   const { client, createAbortController } = useAgents24Runtime();
-  const [threads, setThreads] = React8.useState([]);
-  const [total, setTotal] = React8.useState();
-  const [isLoading, setIsLoading] = React8.useState(true);
-  const [error, setError] = React8.useState(null);
-  const controllerRef = React8.useRef(null);
-  const load = React8.useCallback(async () => {
+  const [threads, setThreads] = React9.useState([]);
+  const [total, setTotal] = React9.useState();
+  const [isLoading, setIsLoading] = React9.useState(true);
+  const [error, setError] = React9.useState(null);
+  const controllerRef = React9.useRef(null);
+  const load = React9.useCallback(async () => {
     controllerRef.current?.abort();
     const controller = createAbortController();
     controllerRef.current = controller;
@@ -2371,7 +2627,7 @@ function useAgentThreads(options = {}) {
       }
     }
   }, [client, createAbortController, options.limit, options.skip]);
-  React8.useEffect(() => {
+  React9.useEffect(() => {
     void load();
     return () => controllerRef.current?.abort();
   }, [load]);
@@ -2379,11 +2635,11 @@ function useAgentThreads(options = {}) {
 }
 function useAgentThread(threadId, options = {}) {
   const { client, createAbortController } = useAgents24Runtime();
-  const [thread, setThread] = React8.useState(null);
-  const [isLoading, setIsLoading] = React8.useState(Boolean(threadId));
-  const [error, setError] = React8.useState(null);
-  const controllerRef = React8.useRef(null);
-  const load = React8.useCallback(async () => {
+  const [thread, setThread] = React9.useState(null);
+  const [isLoading, setIsLoading] = React9.useState(Boolean(threadId));
+  const [error, setError] = React9.useState(null);
+  const controllerRef = React9.useRef(null);
+  const load = React9.useCallback(async () => {
     if (!threadId) {
       controllerRef.current?.abort();
       controllerRef.current = null;
@@ -2410,7 +2666,7 @@ function useAgentThread(threadId, options = {}) {
       }
     }
   }, [client, createAbortController, options.beforeTurnIndex, options.limit, threadId]);
-  React8.useEffect(() => {
+  React9.useEffect(() => {
     void load();
     return () => controllerRef.current?.abort();
   }, [load]);
@@ -2418,11 +2674,11 @@ function useAgentThread(threadId, options = {}) {
 }
 function useThreadComputer(threadId) {
   const { client, createAbortController } = useAgents24Runtime();
-  const [computer, setComputer] = React8.useState(null);
-  const [isLoading, setIsLoading] = React8.useState(Boolean(threadId));
-  const [error, setError] = React8.useState(null);
-  const controllerRef = React8.useRef(null);
-  const refresh = React8.useCallback(async () => {
+  const [computer, setComputer] = React9.useState(null);
+  const [isLoading, setIsLoading] = React9.useState(Boolean(threadId));
+  const [error, setError] = React9.useState(null);
+  const controllerRef = React9.useRef(null);
+  const refresh = React9.useCallback(async () => {
     controllerRef.current?.abort();
     if (!threadId) {
       setComputer(null);
@@ -2447,19 +2703,19 @@ function useThreadComputer(threadId) {
       }
     }
   }, [client, createAbortController, threadId]);
-  React8.useEffect(() => {
+  React9.useEffect(() => {
     void refresh();
     return () => controllerRef.current?.abort();
   }, [refresh]);
-  const list = React8.useCallback((input) => {
+  const list = React9.useCallback((input) => {
     if (!threadId) throw new Error("A thread is required to list computer files");
     return client.threads.computer.list({ threadId, ...input });
   }, [client, threadId]);
-  const read = React8.useCallback((path) => {
+  const read = React9.useCallback((path) => {
     if (!threadId) throw new Error("A thread is required to read a computer file");
     return client.threads.computer.read({ threadId, path });
   }, [client, threadId]);
-  const createContentAccess = React8.useCallback((path, download = false) => {
+  const createContentAccess = React9.useCallback((path, download = false) => {
     if (!threadId) throw new Error("A thread is required to access a computer file");
     return client.threads.computer.createContentAccess({ threadId, path, download });
   }, [client, threadId]);
@@ -2467,16 +2723,16 @@ function useThreadComputer(threadId) {
 }
 function useAgentRun() {
   const { client, createAbortController, createId } = useAgents24Runtime();
-  const controllerRef = React8.useRef(null);
-  const [isAttached, setIsAttached] = React8.useState(false);
-  const [error, setError] = React8.useState(null);
-  React8.useEffect(() => () => controllerRef.current?.abort(), []);
-  const detach = React8.useCallback(() => {
+  const controllerRef = React9.useRef(null);
+  const [isAttached, setIsAttached] = React9.useState(false);
+  const [error, setError] = React9.useState(null);
+  React9.useEffect(() => () => controllerRef.current?.abort(), []);
+  const detach = React9.useCallback(() => {
     controllerRef.current?.abort();
     controllerRef.current = null;
     setIsAttached(false);
   }, []);
-  const attach = React8.useCallback(async (runId, onEvent, cursor) => {
+  const attach = React9.useCallback(async (runId, onEvent, cursor) => {
     detach();
     const controller = createAbortController();
     controllerRef.current = controller;
@@ -2492,7 +2748,7 @@ function useAgentRun() {
       setIsAttached(false);
     }
   }, [client, createAbortController, detach]);
-  const cancel = React8.useCallback(async (runId) => {
+  const cancel = React9.useCallback(async (runId) => {
     const result = await client.runs.cancel({ runId, idempotencyKey: createId() });
     detach();
     return result;
@@ -2501,9 +2757,9 @@ function useAgentRun() {
 }
 function useAgentAttachments() {
   const { client, createId } = useAgents24Runtime();
-  const [uploads, setUploads] = React8.useState({});
-  const [isUploading, setIsUploading] = React8.useState(false);
-  const uploadBatch = React8.useCallback(async (input) => {
+  const [uploads, setUploads] = React9.useState({});
+  const [isUploading, setIsUploading] = React9.useState(false);
+  const uploadBatch = React9.useCallback(async (input) => {
     setIsUploading(true);
     try {
       const results = await client.attachments.uploadBatch({ uploads: input.uploads, threadId: input.threadId, requestedAgentId: input.requestedAgentId, idempotencyKey: createId(), signal: input.signal });
@@ -2516,7 +2772,7 @@ function useAgentAttachments() {
       setIsUploading(false);
     }
   }, [client, createId]);
-  const createContentAccess = React8.useCallback(
+  const createContentAccess = React9.useCallback(
     (input) => client.attachments.createContentAccess(input),
     [client]
   );
@@ -2524,9 +2780,9 @@ function useAgentAttachments() {
 }
 function useAgentHitl() {
   const { client, createId } = useAgents24Runtime();
-  const [isResolving, setIsResolving] = React8.useState(false);
-  const [lastResult, setLastResult] = React8.useState(null);
-  const resume = React8.useCallback(async (input) => {
+  const [isResolving, setIsResolving] = React9.useState(false);
+  const [lastResult, setLastResult] = React9.useState(null);
+  const resume = React9.useCallback(async (input) => {
     setIsResolving(true);
     try {
       const result = await client.hitl.resume({ ...input, idempotencyKey: createId() });
@@ -2540,8 +2796,8 @@ function useAgentHitl() {
 }
 function useAgentMcp() {
   const { client, createId } = useAgents24Runtime();
-  const [isAuthorizing, setIsAuthorizing] = React8.useState(false);
-  const startAuthorization = React8.useCallback(async (input) => {
+  const [isAuthorizing, setIsAuthorizing] = React9.useState(false);
+  const startAuthorization = React9.useCallback(async (input) => {
     setIsAuthorizing(true);
     try {
       return await client.mcp.startAuthorization({ ...input, idempotencyKey: createId() });
@@ -2549,13 +2805,14 @@ function useAgentMcp() {
       setIsAuthorizing(false);
     }
   }, [client, createId]);
-  const redeemCallback = React8.useCallback(async (input) => client.mcp.redeemCallback({ ...input, idempotencyKey: createId() }), [client, createId]);
+  const redeemCallback = React9.useCallback(async (input) => client.mcp.redeemCallback({ ...input, idempotencyKey: createId() }), [client, createId]);
   return { isAuthorizing, redeemCallback, startAuthorization };
 }
 export {
   Agents24Provider,
   adoptStreamingThread,
   appendStableStreamingTurn,
+  applyHitlResolution,
   applyRuntimeEvent,
   applyRuntimeEvents,
   applyThreadSummaryEvent,
@@ -2569,12 +2826,15 @@ export {
   computerResourceTargets,
   contextCompressionPartFromEvent,
   createChatObservation,
+  createHitlSubmission,
   createPortableId,
   createRuntimeEventFrameBuffer,
   discardOptimisticSubmission,
+  findHitlResolution,
   getThreadActivity,
   initialAgentChatState,
   isAbortLike,
+  isDefinitiveHitlRejection,
   latestThreadContext,
   modelTurnPartFromEvent,
   optimisticSubmissionState,
@@ -2583,6 +2843,7 @@ export {
   preferNewestThreadSummary,
   prependThreadTimeline,
   preserveMountedMessageIds,
+  preserveResolvedHitlParts,
   promoteThreadMessage,
   reconcileRefreshedThreads,
   reconcileThreadTimeline,
@@ -2606,6 +2867,7 @@ export {
   useThreadComputer,
   useThreadMessageQueue,
   withAgentChatBackgroundError,
-  withAgentChatOperationError
+  withAgentChatOperationError,
+  withHitlDeadline
 };
 //# sourceMappingURL=index.js.map