@opengeni/react 0.48.0 → 0.57.0

package/dist/{chunk-FWXGSNXT.js → chunk-IGC6A2ZI.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-KZ73RL76.js";
 import {
   useEmbeddedSession
-} from "./chunk-EKZH6IDG.js";
+} from "./chunk-C5ZPSSS5.js";
 
 // src/hooks/use-composer.ts
 import {
@@ -11,7 +11,9 @@ import {
 } from "@opengeni/sdk";
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
 var PENDING_COMPOSER_STORAGE_PREFIX = "opengeni.pending-composer.v1:";
+var OPTIMISTIC_SEND_STORAGE_PREFIX = "opengeni.optimistic-sends.v1:";
 var pendingComposerOperations = /* @__PURE__ */ new Map();
+var optimisticSendOperations = /* @__PURE__ */ new Map();
 function pendingComposerOperationKey(workspaceId, sessionId) {
   return sessionId ? `${workspaceId}\0${sessionId}` : null;
 }
@@ -25,6 +27,50 @@ function pendingComposerStorage() {
 function pendingComposerStorageKey(key) {
   return `${PENDING_COMPOSER_STORAGE_PREFIX}${encodeURIComponent(key)}`;
 }
+function optimisticSendStorageKey(key) {
+  return `${OPTIMISTIC_SEND_STORAGE_PREFIX}${encodeURIComponent(key)}`;
+}
+function restoreOptimisticSendOperations(key) {
+  if (!key) return [];
+  let stored = optimisticSendOperations.get(key);
+  if (!stored) {
+    const storage = pendingComposerStorage();
+    try {
+      const parsed = JSON.parse(storage?.getItem(optimisticSendStorageKey(key)) ?? "[]");
+      stored = Array.isArray(parsed) ? parsed.filter(
+        (candidate) => typeof candidate === "object" && candidate !== null && typeof candidate.clientEventId === "string" && typeof candidate.text === "string" && typeof candidate.occurredAt === "string" && (candidate.state === "sending" || candidate.state === "failed") && typeof candidate.input === "object" && candidate.input !== null && typeof candidate.input.text === "string" && typeof candidate.hasMcpCredentialUpdates === "boolean"
+      ) : [];
+    } catch {
+      stored = [];
+    }
+  }
+  return stored.map(({ hasMcpCredentialUpdates, ...operation }) => ({
+    ...operation,
+    newerShadow: operation.newerShadow ?? { text: "", resources: [], annotations: [] },
+    state: operation.state === "sending" || operation.state === "queued" ? "sending" : operation.state,
+    outcomeUnknown: operation.state === "sending" || operation.state === "queued" ? true : operation.outcomeUnknown,
+    error: operation.state === "sending" ? "Delivery was interrupted; retry to reconcile this message." : operation.error,
+    input: operation.input,
+    canRetry: !hasMcpCredentialUpdates
+  }));
+}
+function rememberOptimisticSendOperations(key, operations) {
+  if (!key) return;
+  const stored = operations.filter((operation) => operation.state !== "queued").map((operation) => {
+    const { canRetry: _canRetry, input, ...rest } = operation;
+    const { mcpCredentialUpdates: _credentials, ...safeInput } = input;
+    return {
+      ...rest,
+      input: safeInput,
+      hasMcpCredentialUpdates: input.mcpCredentialUpdates !== void 0
+    };
+  });
+  optimisticSendOperations.set(key, stored);
+  try {
+    pendingComposerStorage()?.setItem(optimisticSendStorageKey(key), JSON.stringify(stored));
+  } catch {
+  }
+}
 function resourceList(value) {
   return Array.isArray(value) && value.every((candidate) => {
     if (typeof candidate !== "object" || candidate === null) return false;
@@ -32,6 +78,22 @@ function resourceList(value) {
     return resource.kind === "file" ? typeof resource.fileId === "string" : resource.kind === "repository" && typeof resource.uri === "string" && typeof resource.ref === "string";
   });
 }
+function timelineAnnotationList(value) {
+  return Array.isArray(value) && value.every((candidate) => {
+    if (typeof candidate !== "object" || candidate === null) return false;
+    const annotation = candidate;
+    const source = annotation.source;
+    if (typeof source !== "object" || source === null) return false;
+    const sourceRecord = source;
+    return typeof annotation.id === "string" && typeof annotation.quote === "string" && typeof annotation.note === "string" && typeof sourceRecord.eventId === "string" && typeof sourceRecord.eventType === "string" && typeof sourceRecord.sequence === "number" && (typeof sourceRecord.turnId === "string" || sourceRecord.turnId === null) && typeof sourceRecord.startOffset === "number" && typeof sourceRecord.endOffset === "number" && typeof sourceRecord.contextBefore === "string" && typeof sourceRecord.contextAfter === "string";
+  });
+}
+function cloneAnnotations(annotations) {
+  return annotations.map((annotation) => ({
+    ...annotation,
+    source: { ...annotation.source }
+  }));
+}
 function readStoredPendingComposerOperation(key) {
   const storage = key ? pendingComposerStorage() : null;
   if (!storage || !key) return null;
@@ -46,10 +108,17 @@ function readStoredPendingComposerOperation(key) {
     }
     const inputRecord = input;
     const shadowRecord = shadow;
-    if (record.delivery !== "send" && record.delivery !== "steer" || typeof record.draftAtSend !== "string" || !resourceList(record.resourcesAtSend) || typeof shadowRecord.text !== "string" || !resourceList(shadowRecord.resources) || typeof record.clearDraftOnAccept !== "boolean" || typeof record.hasMcpCredentialUpdates !== "boolean" || typeof inputRecord.text !== "string" || typeof inputRecord.clientEventId !== "string" || "mcpCredentialUpdates" in inputRecord || "resources" in inputRecord && !resourceList(inputRecord.resources)) {
+    if (record.delivery !== "send" && record.delivery !== "steer" || typeof record.draftAtSend !== "string" || !resourceList(record.resourcesAtSend) || record.annotationsAtSend !== void 0 && !timelineAnnotationList(record.annotationsAtSend) || typeof shadowRecord.text !== "string" || !resourceList(shadowRecord.resources) || shadowRecord.annotations !== void 0 && !timelineAnnotationList(shadowRecord.annotations) || typeof record.clearDraftOnAccept !== "boolean" || typeof record.hasMcpCredentialUpdates !== "boolean" || typeof inputRecord.text !== "string" || typeof inputRecord.clientEventId !== "string" || "mcpCredentialUpdates" in inputRecord || "resources" in inputRecord && !resourceList(inputRecord.resources) || "annotations" in inputRecord && !timelineAnnotationList(inputRecord.annotations)) {
       return null;
     }
-    return record;
+    return {
+      ...record,
+      annotationsAtSend: timelineAnnotationList(record.annotationsAtSend) ? record.annotationsAtSend : [],
+      newerShadow: {
+        ...shadow,
+        annotations: timelineAnnotationList(shadowRecord.annotations) ? shadowRecord.annotations : []
+      }
+    };
   } catch {
     return null;
   }
@@ -70,7 +139,8 @@ function restorePendingComposerOperation(key) {
     input: stored.input,
     newerShadow: stored.newerShadow ?? {
       text: stored.draftAtSend,
-      resources: stored.resourcesAtSend
+      resources: stored.resourcesAtSend,
+      annotations: stored.annotationsAtSend
     },
     canRetry: !stored.hasMcpCredentialUpdates
   };
@@ -86,7 +156,8 @@ function rememberPendingComposerOperation(key, operation) {
     hasMcpCredentialUpdates: operation.input.mcpCredentialUpdates !== void 0,
     newerShadow: {
       text: operation.newerShadow.text,
-      resources: [...operation.newerShadow.resources]
+      resources: [...operation.newerShadow.resources],
+      annotations: cloneAnnotations(operation.newerShadow.annotations)
     }
   };
   pendingComposerOperations.set(key, stored);
@@ -104,7 +175,14 @@ function forgetPendingComposerOperation(key) {
 }
 function updatePendingComposerShadow(key, operation, shadow) {
   if (!key || !operation) return operation;
-  const next = { ...operation, newerShadow: { ...shadow, resources: [...shadow.resources] } };
+  const next = {
+    ...operation,
+    newerShadow: {
+      ...shadow,
+      resources: [...shadow.resources],
+      annotations: cloneAnnotations(shadow.annotations)
+    }
+  };
   rememberPendingComposerOperation(key, next);
   return next;
 }
@@ -140,10 +218,16 @@ function useComposer(sessionId, options = {}) {
   const targetKey = `${workspaceId}\0${sessionId ?? ""}\0${durableDrafts ? "durable" : "disabled"}`;
   const pendingOperationKey = pendingComposerOperationKey(workspaceId, sessionId);
   const initialPendingOperation = restorePendingComposerOperation(pendingOperationKey);
-  const initialShadow = initialPendingOperation?.newerShadow;
+  const initialOptimisticSends = restoreOptimisticSendOperations(pendingOperationKey);
+  const initialShadow = initialPendingOperation?.newerShadow ?? initialOptimisticSends.at(-1)?.newerShadow;
   const [value, setValue] = useState(() => initialShadow?.text ?? "");
+  const [annotations, setAnnotations] = useState(
+    () => initialShadow?.annotations ?? []
+  );
+  const [annotationReviewTargetId, setAnnotationReviewTargetId] = useState(null);
   const [stateTargetKey, setStateTargetKey] = useState(targetKey);
   const [sending, setSending] = useState(false);
+  const [optimisticSends, setOptimisticSends] = useState(initialOptimisticSends);
   const [steering, setSteering] = useState(
     () => initialPendingOperation?.delivery === "steer" ? {
       phase: "submitting",
@@ -154,6 +238,7 @@ function useComposer(sessionId, options = {}) {
     } : null
   );
   const [pausing, setPausing] = useState(false);
+  const [controlStopping, setControlStopping] = useState(null);
   const [resuming, setResuming] = useState(false);
   const [error, setError] = useState(null);
   const [draft, setDraft] = useState(null);
@@ -164,12 +249,16 @@ function useComposer(sessionId, options = {}) {
     () => initialShadow?.resources ?? []
   );
   const pendingOperationRef = useRef(initialPendingOperation);
+  const optimisticSendsRef = useRef(initialOptimisticSends);
+  const optimisticProcessorBusyRef = useRef(false);
+  const optimisticCallbackIdsRef = useRef(/* @__PURE__ */ new Set());
   const steeringSettlementEventsRef = useRef([]);
   const steeringRef = useRef(steering);
   const pendingClientEventId = useRef(
     initialPendingOperation?.input.clientEventId ?? null
   );
   const valueRef = useRef(initialShadow?.text ?? "");
+  const annotationsRef = useRef(initialShadow?.annotations ?? []);
   const draftRef = useRef(null);
   const restoredResourcesRef = useRef(initialShadow?.resources ?? []);
   const localEditRevision = useRef(initialShadow ? 1 : 0);
@@ -178,6 +267,7 @@ function useComposer(sessionId, options = {}) {
   const lastSavedSignature = useRef(null);
   const saveChain = useRef(Promise.resolve());
   const onSent = options.onSent;
+  const onSubmitted = options.onSubmitted;
   const onDraftApplied = options.onDraftApplied;
   const onDraftAppliedRef = useRef(onDraftApplied);
   useLayoutEffect(() => {
@@ -198,18 +288,26 @@ function useComposer(sessionId, options = {}) {
     targetGeneration.current += 1;
     draftReadGeneration.current += 1;
     pendingOperationRef.current = restorePendingComposerOperation(pendingOperationKey);
+    const restoredOptimisticSends = restoreOptimisticSendOperations(pendingOperationKey);
+    optimisticSendsRef.current = restoredOptimisticSends;
+    optimisticProcessorBusyRef.current = false;
+    optimisticCallbackIdsRef.current = /* @__PURE__ */ new Set();
     steeringSettlementEventsRef.current = [];
     pendingClientEventId.current = pendingOperationRef.current?.input.clientEventId ?? null;
-    const shadow = pendingOperationRef.current?.newerShadow;
+    const shadow = pendingOperationRef.current?.newerShadow ?? restoredOptimisticSends.at(-1)?.newerShadow;
     localEditRevision.current = shadow ? 1 : 0;
     valueRef.current = shadow?.text ?? "";
+    annotationsRef.current = shadow?.annotations ?? [];
     draftRef.current = null;
     restoredResourcesRef.current = shadow?.resources ?? [];
     lastSavedSignature.current = null;
     saveChain.current = Promise.resolve();
     setStateTargetKey(targetKey);
     setValue(shadow?.text ?? "");
+    setAnnotations(shadow?.annotations ?? []);
+    setAnnotationReviewTargetId(null);
     setSending(false);
+    setOptimisticSends(restoredOptimisticSends);
     setSteering(
       pendingOperationRef.current?.delivery === "steer" ? {
         phase: "submitting",
@@ -220,6 +318,7 @@ function useComposer(sessionId, options = {}) {
       } : null
     );
     setPausing(false);
+    setControlStopping(null);
     setResuming(false);
     setError(null);
     setDraft(null);
@@ -228,17 +327,36 @@ function useComposer(sessionId, options = {}) {
     setDraftConflict(null);
     setRestoredResources(shadow?.resources ?? []);
   }, [durableDrafts, pendingOperationKey, sessionId, targetKey]);
+  const setOptimisticDraftShadow = useCallback(
+    (shadow) => {
+      if (optimisticSendsRef.current.length === 0) return;
+      const next = optimisticSendsRef.current.map((operation) => ({
+        ...operation,
+        newerShadow: {
+          text: shadow.text,
+          resources: [...shadow.resources],
+          annotations: cloneAnnotations(shadow.annotations)
+        }
+      }));
+      optimisticSendsRef.current = next;
+      rememberOptimisticSendOperations(pendingOperationKey, next);
+      setOptimisticSends(next);
+    },
+    [pendingOperationKey]
+  );
   const applyDraft = useCallback(
     (next) => {
       if (targetKeyRef.current !== targetKey) return;
       if (!durableDrafts) {
         localEditRevision.current += 1;
         valueRef.current = next.text;
+        annotationsRef.current = next.annotations ?? [];
         restoredResourcesRef.current = next.resources;
         draftRef.current = null;
         lastSavedSignature.current = null;
         setDraft(null);
         setValue(next.text);
+        setAnnotations(next.annotations ?? []);
         setRestoredResources(next.resources);
         pendingOperationRef.current = updatePendingComposerShadow(
           pendingOperationKey,
@@ -248,19 +366,30 @@ function useComposer(sessionId, options = {}) {
             resources: mergeResources(
               next.resources,
               resolveSendExtras(sendExtrasRef.current).resources ?? []
-            )
+            ),
+            annotations: next.annotations ?? []
           }
         );
+        setOptimisticDraftShadow({
+          text: next.text,
+          resources: mergeResources(
+            next.resources,
+            resolveSendExtras(sendExtrasRef.current).resources ?? []
+          ),
+          annotations: next.annotations ?? []
+        });
         setDraftConflict(null);
         return;
       }
       valueRef.current = next.text;
+      annotationsRef.current = next.annotations ?? [];
       draftRef.current = next;
       restoredResourcesRef.current = next.resources;
       lastSavedSignature.current = draftSignature(draftPayload(next));
       localEditRevision.current += 1;
       setDraft(next);
       setValue(next.text);
+      setAnnotations(next.annotations ?? []);
       setRestoredResources(next.resources);
       pendingOperationRef.current = updatePendingComposerShadow(
         pendingOperationKey,
@@ -270,13 +399,22 @@ function useComposer(sessionId, options = {}) {
           resources: mergeResources(
             next.resources,
             resolveSendExtras(sendExtrasRef.current).resources ?? []
-          )
+          ),
+          annotations: next.annotations ?? []
         }
       );
+      setOptimisticDraftShadow({
+        text: next.text,
+        resources: mergeResources(
+          next.resources,
+          resolveSendExtras(sendExtrasRef.current).resources ?? []
+        ),
+        annotations: next.annotations ?? []
+      });
       setDraftConflict(null);
       onDraftAppliedRef.current?.(next);
     },
-    [durableDrafts, pendingOperationKey, targetKey]
+    [durableDrafts, pendingOperationKey, setOptimisticDraftShadow, targetKey]
   );
   const loadDraft = useCallback(
     async (replaceLocal) => {
@@ -295,6 +433,7 @@ function useComposer(sessionId, options = {}) {
           baseAtStart,
           valueRef.current,
           restoredResourcesRef.current,
+          annotationsRef.current,
           extrasAtStart
         )
       ) : null;
@@ -313,21 +452,25 @@ function useComposer(sessionId, options = {}) {
           draftRef.current = fetched;
           setDraft(fetched);
           setDraftConflict(null);
-          const shadow = pendingOperationRef.current?.newerShadow;
+          const shadow = pendingOperationRef.current?.newerShadow ?? optimisticSendsRef.current.at(-1)?.newerShadow;
           if (shadow) {
             valueRef.current = shadow.text;
             restoredResourcesRef.current = shadow.resources;
+            annotationsRef.current = shadow.annotations;
             localEditRevision.current ||= 1;
             setValue(shadow.text);
             setRestoredResources(shadow.resources);
+            setAnnotations(shadow.annotations);
           } else if (replaceLocal || !localWasDirtyAtStart && localAtStart === localEditRevision.current) {
             const extrasNow = resolveSendExtras(sendExtrasRef.current);
             const pickerChangedDuringFetch = extrasNow.model !== extrasAtStart.model || extrasNow.reasoningEffort !== extrasAtStart.reasoningEffort || extrasNow.latencyMode !== extrasAtStart.latencyMode;
             valueRef.current = fetched.text;
             restoredResourcesRef.current = fetched.resources;
+            annotationsRef.current = fetched.annotations ?? [];
             lastSavedSignature.current = draftSignature(draftPayload(fetched));
             setValue(fetched.text);
             setRestoredResources(fetched.resources);
+            setAnnotations(fetched.annotations ?? []);
             if (replaceLocal || !pickerChangedDuringFetch) {
               onDraftAppliedRef.current?.(fetched);
             }
@@ -436,13 +579,24 @@ function useComposer(sessionId, options = {}) {
     steeringSettlementEventsRef.current = [];
     setSteering(null);
   }, [options.events, steering]);
+  useEffect(() => {
+    if (!controlStopping) return;
+    const effectiveControl = options.effectiveControl;
+    if (!effectiveControl || effectiveControl.controlVersion < controlStopping.controlVersion) {
+      return;
+    }
+    if (effectiveControl.controlVersion === controlStopping.controlVersion && effectiveControl.controlEtag === controlStopping.controlEtag && effectiveControl.settlement !== null) {
+      return;
+    }
+    setControlStopping((current) => current === controlStopping ? null : current);
+  }, [controlStopping, options.effectiveControl]);
   const currentDraftPayload = useCallback(() => {
     if (!durableDrafts || targetKeyRef.current !== targetKey) return null;
     const base = draftRef.current;
     if (!base) return null;
     const extras = resolveSendExtras(sendExtrasRef.current);
-    return composerDraftPayload(base, value, restoredResources, extras);
-  }, [durableDrafts, restoredResources, targetKey, value]);
+    return composerDraftPayload(base, value, restoredResources, annotations, extras);
+  }, [annotations, durableDrafts, restoredResources, targetKey, value]);
   const persistPayload = useCallback(
     async (payload) => {
       const ownedTargetKey = targetKey;
@@ -505,6 +659,152 @@ function useComposer(sessionId, options = {}) {
     },
     [client, durableDrafts, sessionId, targetKey, workspaceId]
   );
+  const replaceOptimisticSends = useCallback(
+    (update) => {
+      const next = update(optimisticSendsRef.current);
+      optimisticSendsRef.current = next;
+      rememberOptimisticSendOperations(pendingOperationKey, next);
+      setOptimisticSends(next);
+      return next;
+    },
+    [pendingOperationKey]
+  );
+  const markOptimisticAccepted = useCallback(
+    (operation) => {
+      if (!optimisticCallbackIdsRef.current.has(operation.clientEventId)) {
+        optimisticCallbackIdsRef.current.add(operation.clientEventId);
+        onSent?.(operation.input.text, operation.input);
+      }
+      replaceOptimisticSends(
+        (current) => current.filter((candidate) => candidate.clientEventId !== operation.clientEventId)
+      );
+    },
+    [onSent, replaceOptimisticSends]
+  );
+  useEffect(() => {
+    const acceptedIds = new Set(
+      (options.events ?? []).filter((event) => event.type === "user.message" && event.clientEventId).map((event) => event.clientEventId)
+    );
+    if (acceptedIds.size === 0) return;
+    const accepted = optimisticSendsRef.current.filter(
+      (operation) => acceptedIds.has(operation.clientEventId)
+    );
+    for (const operation of accepted) markOptimisticAccepted(operation);
+  }, [markOptimisticAccepted, options.events]);
+  const processOptimisticSends = useCallback(() => {
+    if (!sessionId || optimisticProcessorBusyRef.current) return;
+    const currentOperations = optimisticSendsRef.current;
+    const operationIndex = currentOperations.findIndex(
+      (candidate) => candidate.state === "sending"
+    );
+    const operation = operationIndex < 0 ? void 0 : currentOperations[operationIndex];
+    if (!operation) return;
+    const ownedTargetKey = targetKey;
+    const ownedGeneration = targetGeneration.current;
+    optimisticProcessorBusyRef.current = true;
+    void (async () => {
+      try {
+        if (operation.outcomeUnknown) {
+          const events = await client.listEvents(workspaceId, sessionId, {
+            includeTypes: ["user.message"],
+            limit: 100,
+            payloadMode: "none"
+          });
+          if (events.some(
+            (event) => event.type === "user.message" && event.clientEventId === operation.clientEventId
+          )) {
+            markOptimisticAccepted(operation);
+            return;
+          }
+          if (!operation.canRetry) {
+            throw new Error(
+              "OpenGeni cannot safely retry this uncertain request after remount; reconcile the session before sending again."
+            );
+          }
+        }
+        let expectedDraftRevision;
+        if (durableDrafts && operation.draftPayload) {
+          if (!await persistPayload(operation.draftPayload)) {
+            throw new Error("The message draft could not be saved before delivery.");
+          }
+          expectedDraftRevision = draftRef.current?.revision;
+        }
+        if (targetKeyRef.current !== ownedTargetKey || targetGeneration.current !== ownedGeneration) {
+          return;
+        }
+        const wireInput = {
+          ...operation.input,
+          ...expectedDraftRevision !== void 0 ? { expectedDraftRevision } : {}
+        };
+        await client.sendMessage(workspaceId, sessionId, wireInput);
+        if (targetKeyRef.current !== ownedTargetKey || targetGeneration.current !== ownedGeneration) {
+          return;
+        }
+        if (options.events === void 0) {
+          markOptimisticAccepted({ ...operation, input: wireInput });
+        } else {
+          replaceOptimisticSends(
+            (current) => current.map(
+              (candidate) => candidate.clientEventId === operation.clientEventId ? { ...candidate, input: wireInput, state: "queued", error: void 0 } : candidate
+            )
+          );
+        }
+        if (!optimisticCallbackIdsRef.current.has(operation.clientEventId)) {
+          optimisticCallbackIdsRef.current.add(operation.clientEventId);
+          onSent?.(wireInput.text, wireInput);
+        }
+        if (durableDrafts && draftRef.current) {
+          const cleared = {
+            ...draftRef.current,
+            revision: 0,
+            text: "",
+            resources: [],
+            annotations: [],
+            sourceTurnId: null,
+            sourceTurnVersion: null,
+            updatedAt: null
+          };
+          draftRef.current = cleared;
+          setDraft(cleared);
+          lastSavedSignature.current = draftSignature(draftPayload(cleared));
+        }
+      } catch (cause) {
+        const problem = asError(cause);
+        const outcomeUnknown = isOutcomeUnknownError(cause) || operation.outcomeUnknown === true;
+        if (targetKeyRef.current === ownedTargetKey && targetGeneration.current === ownedGeneration) {
+          replaceOptimisticSends(
+            (current) => current.map(
+              (candidate) => candidate.clientEventId === operation.clientEventId ? {
+                ...candidate,
+                state: "failed",
+                error: problem.message,
+                outcomeUnknown
+              } : candidate
+            )
+          );
+        }
+      } finally {
+        optimisticProcessorBusyRef.current = false;
+        if (targetKeyRef.current === ownedTargetKey) {
+          setOptimisticSends([...optimisticSendsRef.current]);
+        }
+      }
+    })();
+  }, [
+    client,
+    durableDrafts,
+    markOptimisticAccepted,
+    onSent,
+    options.events,
+    persistPayload,
+    replaceOptimisticSends,
+    sessionId,
+    targetKey,
+    workspaceId
+  ]);
+  useEffect(() => {
+    processOptimisticSends();
+  }, [optimisticSends, processOptimisticSends]);
   useEffect(() => {
     const pending = pendingOperationRef.current;
     if (pending) {
@@ -513,9 +813,10 @@ function useComposer(sessionId, options = {}) {
         resources: mergeResources(
           restoredResourcesRef.current,
           resolveSendExtras(sendExtrasRef.current).resources ?? []
-        )
+        ),
+        annotations: annotationsRef.current
       };
-      if (pending.newerShadow.text !== shadow.text || JSON.stringify(pending.newerShadow.resources) !== JSON.stringify(shadow.resources)) {
+      if (pending.newerShadow.text !== shadow.text || JSON.stringify(pending.newerShadow.resources) !== JSON.stringify(shadow.resources) || JSON.stringify(pending.newerShadow.annotations) !== JSON.stringify(shadow.annotations)) {
         pendingOperationRef.current = updatePendingComposerShadow(
           pendingOperationKey,
           pending,
@@ -524,6 +825,23 @@ function useComposer(sessionId, options = {}) {
       }
       return;
     }
+    const optimistic = optimisticSendsRef.current.at(-1);
+    if (optimistic) {
+      const shadow = {
+        text: valueRef.current,
+        resources: mergeResources(
+          restoredResourcesRef.current,
+          resolveSendExtras(sendExtrasRef.current).resources ?? []
+        ),
+        annotations: annotationsRef.current
+      };
+      if (optimistic.newerShadow.text !== shadow.text || JSON.stringify(optimistic.newerShadow.resources) !== JSON.stringify(shadow.resources) || JSON.stringify(optimistic.newerShadow.annotations) !== JSON.stringify(shadow.annotations)) {
+        setOptimisticDraftShadow(shadow);
+      }
+    }
+    if (optimisticSendsRef.current.some((operation) => operation.state === "sending")) {
+      return;
+    }
     if (!durableDrafts || !sessionId || draftLoading || sending || !draftRef.current || draftConflict)
       return;
     const payload = currentDraftPayload();
@@ -538,6 +856,7 @@ function useComposer(sessionId, options = {}) {
     liveExtrasVersion,
     pendingOperationKey,
     persistPayload,
+    setOptimisticDraftShadow,
     sending,
     sessionId
   ]);
@@ -552,11 +871,16 @@ function useComposer(sessionId, options = {}) {
         pendingClientEventId.current = pending.input.clientEventId ?? null;
       }
       const draftAtSend = value;
+      const annotationsAtSend = annotations;
       const rawText = explicit ?? draftAtSend;
       const hasText = rawText.trim().length > 0;
+      const hasAnnotations = annotationsAtSend.length > 0;
+      const annotationsComplete2 = annotationsAtSend.every(
+        (annotation) => annotation.note.trim().length > 0
+      );
       const extras = pending ? {} : resolveSendExtras(sendExtrasRef.current);
       const hasResources = restoredResources.length > 0 || (extras.resources?.length ?? 0) > 0;
-      if (!pending && !hasText && !hasResources || !sessionId || sending || sendBlockedRef.current?.() === true || targetKeyRef.current !== ownedTargetKey) {
+      if (!pending && (!annotationsComplete2 || !hasText && !hasResources && !hasAnnotations) || !sessionId || sending || sendBlockedRef.current?.() === true || targetKeyRef.current !== ownedTargetKey) {
         return false;
       }
       const clearPending = () => {
@@ -569,6 +893,7 @@ function useComposer(sessionId, options = {}) {
         clearPending();
         const draftWasUnchanged = valueRef.current === operation.draftAtSend;
         const resourcesWereUnchanged = JSON.stringify(restoredResourcesRef.current) === JSON.stringify(operation.resourcesAtSend);
+        const annotationsWereUnchanged = JSON.stringify(annotationsRef.current) === JSON.stringify(operation.annotationsAtSend);
         const previousDraft = draftRef.current;
         if (previousDraft) {
           const cleared = {
@@ -576,6 +901,7 @@ function useComposer(sessionId, options = {}) {
             revision: 0,
             text: "",
             resources: [],
+            annotations: [],
             sourceTurnId: null,
             sourceTurnVersion: null,
             updatedAt: null
@@ -588,6 +914,11 @@ function useComposer(sessionId, options = {}) {
           restoredResourcesRef.current = [];
           setRestoredResources([]);
         }
+        if (annotationsWereUnchanged) {
+          annotationsRef.current = [];
+          setAnnotations([]);
+          setAnnotationReviewTargetId(null);
+        }
         if (operation.clearDraftOnAccept && draftWasUnchanged) {
           valueRef.current = "";
           setValue("");
@@ -664,7 +995,8 @@ function useComposer(sessionId, options = {}) {
                 text: pending.input.text,
                 clientEventId: pending.input.clientEventId ?? null,
                 triggerEventId: result.accepted.id,
-                turnId: result.turn.id
+                turnId: result.turn.id,
+                stoppingPreviousAttempt: result.replay !== true && (result.interruptionCount ?? 0) > 0
               });
             }
           } catch (cause) {
@@ -680,7 +1012,7 @@ function useComposer(sessionId, options = {}) {
           settleAccepted(pending);
           return true;
         }
-        const sendText = hasText ? rawText : FILE_ONLY_MESSAGE_TEXT;
+        const sendText = hasText ? rawText : hasAnnotations ? "" : FILE_ONLY_MESSAGE_TEXT;
         const currentPayload = currentDraftPayload();
         const payload = currentPayload ? { ...currentPayload, text: sendText } : null;
         if (payload && !await persistPayload(payload)) return false;
@@ -691,16 +1023,19 @@ function useComposer(sessionId, options = {}) {
         const input = composeSendInput(sendText, pendingClientEventId.current, extras, {
           ...options.effectiveControl?.controlEtag ? { controlEtag: options.effectiveControl.controlEtag } : {},
           ...durableDrafts && draftRef.current ? { expectedDraftRevision: draftRef.current.revision } : {},
-          resources: mergeResources(restoredResources, extras.resources ?? [])
+          resources: mergeResources(restoredResources, extras.resources ?? []),
+          annotations: cloneAnnotations(annotationsAtSend)
         });
         const operation = {
           delivery,
           input,
           draftAtSend,
           resourcesAtSend: [...restoredResources],
+          annotationsAtSend: cloneAnnotations(annotationsAtSend),
           newerShadow: {
             text: draftAtSend,
-            resources: mergeResources(restoredResources, extras.resources ?? [])
+            resources: mergeResources(restoredResources, extras.resources ?? []),
+            annotations: cloneAnnotations(annotationsAtSend)
           },
           clearDraftOnAccept: explicit === void 0,
           canRetry: true
@@ -725,7 +1060,8 @@ function useComposer(sessionId, options = {}) {
               text: sendText,
               clientEventId: input.clientEventId ?? null,
               triggerEventId: result.accepted.id,
-              turnId: result.turn.id
+              turnId: result.turn.id,
+              stoppingPreviousAttempt: result.replay !== true && (result.interruptionCount ?? 0) > 0
             });
           }
         } catch (cause) {
@@ -759,6 +1095,7 @@ function useComposer(sessionId, options = {}) {
       options.effectiveControl?.controlEtag,
       persistPayload,
       restoredResources,
+      annotations,
       sending,
       sessionId,
       targetKey,
@@ -766,10 +1103,126 @@ function useComposer(sessionId, options = {}) {
       workspaceId
     ]
   );
-  const send = useCallback(async (text) => await dispatch("send", text), [dispatch]);
+  const send = useCallback(
+    async (explicit) => {
+      if (pendingOperationRef.current?.delivery === "send") {
+        return await dispatch("send", explicit);
+      }
+      const rawText = explicit ?? valueRef.current;
+      const annotationsAtSend = cloneAnnotations(annotationsRef.current);
+      const hasText = rawText.trim().length > 0;
+      const hasAnnotations = annotationsAtSend.length > 0;
+      const annotationsComplete2 = annotationsAtSend.every(
+        (annotation) => annotation.note.trim().length > 0
+      );
+      const extras = resolveSendExtras(sendExtrasRef.current);
+      const resources = mergeResources(restoredResourcesRef.current, extras.resources ?? []);
+      if (!sessionId || sending || !annotationsComplete2 || !hasText && !hasAnnotations && resources.length === 0 || sendBlockedRef.current?.() === true || targetKeyRef.current !== targetKey) {
+        return false;
+      }
+      const sendText = hasText ? rawText : hasAnnotations ? "" : FILE_ONLY_MESSAGE_TEXT;
+      const clientEventId = generateClientEventId();
+      const input = composeSendInput(sendText, clientEventId, extras, {
+        ...options.effectiveControl?.controlEtag ? { controlEtag: options.effectiveControl.controlEtag } : {},
+        resources,
+        annotations: annotationsAtSend
+      });
+      const currentPayload = currentDraftPayload();
+      const operation = {
+        clientEventId,
+        text: sendText,
+        annotations: annotationsAtSend,
+        resources,
+        occurredAt: (/* @__PURE__ */ new Date()).toISOString(),
+        state: "sending",
+        input,
+        draftPayload: currentPayload ? { ...currentPayload, text: sendText } : null,
+        newerShadow: {
+          text: explicit === void 0 ? "" : valueRef.current,
+          resources: explicit === void 0 ? [] : [...restoredResourcesRef.current],
+          annotations: explicit === void 0 ? [] : cloneAnnotations(annotationsRef.current)
+        },
+        canRetry: true
+      };
+      replaceOptimisticSends((current) => [...current, operation]);
+      queueMicrotask(processOptimisticSends);
+      setError(null);
+      onSubmitted?.(sendText, input);
+      if (explicit === void 0) {
+        valueRef.current = "";
+        annotationsRef.current = [];
+        restoredResourcesRef.current = [];
+        localEditRevision.current += 1;
+        setValue("");
+        setAnnotations([]);
+        setAnnotationReviewTargetId(null);
+        setRestoredResources([]);
+      }
+      return true;
+    },
+    [
+      currentDraftPayload,
+      dispatch,
+      onSubmitted,
+      options.effectiveControl?.controlEtag,
+      processOptimisticSends,
+      replaceOptimisticSends,
+      sending,
+      sessionId,
+      targetKey
+    ]
+  );
   const steer = useCallback(async (text) => await dispatch("steer", text), [dispatch]);
+  const retryOptimisticMessage = useCallback(
+    (clientEventId) => {
+      replaceOptimisticSends(
+        (current) => current.map((operation) => {
+          if (operation.clientEventId !== clientEventId || operation.state !== "failed") {
+            return operation;
+          }
+          if (operation.outcomeUnknown) {
+            return { ...operation, state: "sending", error: void 0 };
+          }
+          const nextClientEventId = generateClientEventId();
+          const retryExtras = resolveSendExtras(sendExtrasRef.current);
+          const retryInput = composeSendInput(operation.text, nextClientEventId, retryExtras, {
+            ...options.effectiveControl?.controlEtag ? { controlEtag: options.effectiveControl.controlEtag } : {},
+            resources: operation.resources,
+            annotations: operation.annotations
+          });
+          return {
+            ...operation,
+            clientEventId: nextClientEventId,
+            input: retryInput,
+            draftPayload: operation.draftPayload ? {
+              ...operation.draftPayload,
+              model: retryExtras.model ?? operation.draftPayload.model,
+              reasoningEffort: retryExtras.reasoningEffort ?? operation.draftPayload.reasoningEffort,
+              latencyMode: retryExtras.latencyMode ?? operation.draftPayload.latencyMode
+            } : null,
+            occurredAt: (/* @__PURE__ */ new Date()).toISOString(),
+            state: "sending",
+            error: void 0,
+            outcomeUnknown: false,
+            canRetry: true
+          };
+        })
+      );
+      queueMicrotask(processOptimisticSends);
+    },
+    [options.effectiveControl?.controlEtag, processOptimisticSends, replaceOptimisticSends]
+  );
+  const removeOptimisticMessage = useCallback(
+    (clientEventId) => {
+      replaceOptimisticSends(
+        (current) => current.filter((operation) => operation.clientEventId !== clientEventId)
+      );
+    },
+    [replaceOptimisticSends]
+  );
   const hasReadyResources = restoredResources.length > 0 || (resolveSendExtras(sendExtrasRef.current).resources?.length ?? 0) > 0;
   const hasPendingOperation = pendingOperationRef.current !== null;
+  const annotationsComplete = annotations.every((annotation) => annotation.note.trim().length > 0);
   const pause = useCallback(
     async (reason) => {
       const ownedTargetKey = targetKey;
@@ -780,10 +1233,18 @@ function useComposer(sessionId, options = {}) {
       setPausing(true);
       setError(null);
       try {
-        await client.pauseSession(workspaceId, sessionId, {
+        const result = await client.pauseSession(workspaceId, sessionId, {
           ...reason !== void 0 ? { reason } : {},
           ...options.effectiveControl?.controlEtag ? { expectedControlEtag: options.effectiveControl.controlEtag } : {}
         });
+        if (targetKeyRef.current === ownedTargetKey && targetGeneration.current === ownedGeneration) {
+          setControlStopping(
+            result.interruptionCount > 0 && result.effectiveControl.state === "paused" && result.effectiveControl.settlement !== null ? {
+              controlVersion: result.effectiveControl.controlVersion,
+              controlEtag: result.effectiveControl.controlEtag
+            } : null
+          );
+        }
       } catch (cause) {
         if (targetKeyRef.current === ownedTargetKey && targetGeneration.current === ownedGeneration) {
           setError(cause instanceof Error ? cause : new Error(String(cause)));
@@ -880,13 +1341,82 @@ function useComposer(sessionId, options = {}) {
           resources: mergeResources(
             restoredResourcesRef.current,
             resolveSendExtras(sendExtrasRef.current).resources ?? []
-          )
+          ),
+          annotations: annotationsRef.current
         }
       );
+      setOptimisticDraftShadow({
+        text: next,
+        resources: mergeResources(
+          restoredResourcesRef.current,
+          resolveSendExtras(sendExtrasRef.current).resources ?? []
+        ),
+        annotations: annotationsRef.current
+      });
       setValue(next);
     },
-    [pendingOperationKey, targetKey]
+    [pendingOperationKey, setOptimisticDraftShadow, targetKey]
   );
+  const updateAnnotations = useCallback(
+    (next, reviewTargetId = null) => {
+      if (targetKeyRef.current !== targetKey) return;
+      localEditRevision.current += 1;
+      annotationsRef.current = next;
+      pendingOperationRef.current = updatePendingComposerShadow(
+        pendingOperationKey,
+        pendingOperationRef.current,
+        {
+          text: valueRef.current,
+          resources: mergeResources(
+            restoredResourcesRef.current,
+            resolveSendExtras(sendExtrasRef.current).resources ?? []
+          ),
+          annotations: next
+        }
+      );
+      setOptimisticDraftShadow({
+        text: valueRef.current,
+        resources: mergeResources(
+          restoredResourcesRef.current,
+          resolveSendExtras(sendExtrasRef.current).resources ?? []
+        ),
+        annotations: next
+      });
+      setAnnotations(next);
+      setAnnotationReviewTargetId(reviewTargetId);
+    },
+    [pendingOperationKey, setOptimisticDraftShadow, targetKey]
+  );
+  const addAnnotation = useCallback(
+    (annotation) => {
+      if (annotationsRef.current.length >= 12) {
+        setError(new Error("A message can include at most 12 timeline annotations."));
+        return;
+      }
+      const next = [...annotationsRef.current, annotation];
+      updateAnnotations(next, annotation.id);
+    },
+    [updateAnnotations]
+  );
+  const updateAnnotation = useCallback(
+    (id, note) => {
+      updateAnnotations(
+        annotationsRef.current.map(
+          (annotation) => annotation.id === id ? { ...annotation, note } : annotation
+        )
+      );
+    },
+    [updateAnnotations]
+  );
+  const removeAnnotation = useCallback(
+    (id) => {
+      updateAnnotations(annotationsRef.current.filter((annotation) => annotation.id !== id));
+    },
+    [updateAnnotations]
+  );
+  const clearAnnotationReviewTarget = useCallback(() => {
+    setAnnotationReviewTargetId(null);
+  }, []);
   const removeRestoredResource = useCallback(
     (index) => {
       if (targetKeyRef.current !== targetKey) return;
@@ -898,17 +1428,23 @@ function useComposer(sessionId, options = {}) {
         pendingOperationRef.current,
         {
           text: valueRef.current,
-          resources: mergeResources(next, resolveSendExtras(sendExtrasRef.current).resources ?? [])
+          resources: mergeResources(next, resolveSendExtras(sendExtrasRef.current).resources ?? []),
+          annotations: annotationsRef.current
         }
       );
+      setOptimisticDraftShadow({
+        text: valueRef.current,
+        resources: mergeResources(next, resolveSendExtras(sendExtrasRef.current).resources ?? []),
+        annotations: annotationsRef.current
+      });
       setRestoredResources(next);
     },
-    [pendingOperationKey, targetKey]
+    [pendingOperationKey, setOptimisticDraftShadow, targetKey]
   );
   const hasDraftContent = useCallback(() => {
     const current = draftRef.current;
     const extras = resolveSendExtras(sendExtrasRef.current);
-    return valueRef.current.length > 0 || restoredResourcesRef.current.length > 0 || (extras.resources?.length ?? 0) > 0 || current?.sourceTurnId !== null && current?.sourceTurnId !== void 0;
+    return valueRef.current.length > 0 || annotationsRef.current.length > 0 || restoredResourcesRef.current.length > 0 || (extras.resources?.length ?? 0) > 0 || current?.sourceTurnId !== null && current?.sourceTurnId !== void 0;
   }, []);
   const resolveDraftConflict = useCallback(
     async (choice) => {
@@ -943,6 +1479,7 @@ function useComposer(sessionId, options = {}) {
     ]
   );
   const identityMatches = stateTargetKey === targetKey;
+  const visibleSteering = identityMatches ? steering : null;
   const reloadDraft = useCallback(async () => await loadDraft(true), [loadDraft]);
   const clearError = useCallback(() => {
     if (targetKeyRef.current !== targetKey) return;
@@ -952,12 +1489,24 @@ function useComposer(sessionId, options = {}) {
   return {
     value: identityMatches ? value : "",
     setValue: updateValue,
+    annotations: identityMatches ? annotations : [],
+    addAnnotation,
+    updateAnnotation,
+    removeAnnotation,
+    annotationReviewTargetId: identityMatches ? annotationReviewTargetId : null,
+    clearAnnotationReviewTarget,
     hasDraftContent,
     send,
+    optimisticMessages: identityMatches ? optimisticSends.map(
+      ({ input: _input, draftPayload: _payload, canRetry: _retry, ...item }) => item
+    ) : [],
+    retryOptimisticMessage,
+    removeOptimisticMessage,
     steer,
-    steering: identityMatches ? steering : null,
+    steering: visibleSteering,
+    stoppingAttempt: identityMatches ? controlStopping ? "current" : visibleSteering?.phase === "accepted" && visibleSteering.stoppingPreviousAttempt === true ? "previous" : null : null,
     sending: identityMatches ? sending : false,
-    canSend: identityMatches && Boolean(sessionId) && !sending && sendBlockedRef.current?.() !== true && (hasPendingOperation || value.trim().length > 0 || hasReadyResources),
+    canSend: identityMatches && Boolean(sessionId) && !sending && sendBlockedRef.current?.() !== true && annotationsComplete && (hasPendingOperation || value.trim().length > 0 || hasReadyResources || annotations.length > 0),
     pause,
     pausing: identityMatches ? pausing : false,
     resume,
@@ -981,7 +1530,7 @@ function useComposer(sessionId, options = {}) {
 function isComposerDraftEvent(event) {
   return event.type === "user.message" || event.type === "session.queue.changed";
 }
-var FILE_ONLY_MESSAGE_TEXT = "(see attached files)";
+var FILE_ONLY_MESSAGE_TEXT = "(see attached context)";
 function resolveSendExtras(extras) {
   return (typeof extras === "function" ? extras() : extras) ?? {};
 }
@@ -1034,16 +1583,18 @@ function draftPayload(draft) {
     expectedRevision: draft.revision,
     text: draft.text,
     resources: draft.resources,
+    annotations: draft.annotations ?? [],
     model: draft.model,
     reasoningEffort: draft.reasoningEffort,
     latencyMode: draft.latencyMode ?? "standard"
   };
 }
-function composerDraftPayload(base, text, restoredResources, extras) {
+function composerDraftPayload(base, text, restoredResources, annotations, extras) {
   return {
     expectedRevision: base.revision,
     text,
     resources: mergeResources(restoredResources, extras.resources ?? []),
+    annotations,
     model: extras.model ?? base.model,
     reasoningEffort: extras.reasoningEffort ?? base.reasoningEffort,
     latencyMode: extras.latencyMode ?? base.latencyMode ?? "standard"
@@ -1070,4 +1621,4 @@ export {
   shouldSubmitOnKey,
   shouldSteerOnKey
 };
-//# sourceMappingURL=chunk-FWXGSNXT.js.map
+//# sourceMappingURL=chunk-IGC6A2ZI.js.map