@opengeni/react 0.46.1 → 0.52.1

package/src/hooks/use-composer.ts

@@ -1,6 +1,7 @@
 import {
   DEFAULT_FILE_RESOURCE_MOUNT_ROOT,
   type ComposerDraft,
+  type DraftTimelineAnnotation,
   type EffectiveControlResumeOption,
   type EffectiveSessionControl,
   type OpenGeniApiError,
@@ -13,10 +14,12 @@ import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react
 import { useEmbeddedSession, type EmbeddedSessionClientOverride } from "../session-context";
 import { useSessionEventTrigger, type SessionEventFeedOptions } from "./internal";
 
-export type ComposerSendExtras = Omit<SendMessageInput, "text" | "clientEventId">;
+export type ComposerSendExtras = Omit<SendMessageInput, "text" | "clientEventId" | "annotations">;
 
 export type UseComposerOptions = EmbeddedSessionClientOverride &
   SessionEventFeedOptions & {
+    /** Called synchronously after an ordinary Send is accepted by the local UI. */
+    onSubmitted?: ((text: string, input: SendMessageInput) => void) | undefined;
     /** Called with the exact accepted wire input after a successful send. */
     onSent?: ((text: string, input: SendMessageInput) => void) | undefined;
     /**
@@ -42,6 +45,7 @@ export type UseComposerOptions = EmbeddedSessionClientOverride &
 type ComposerDraftShadow = {
   text: string;
   resources: ResourceRef[];
+  annotations: DraftTimelineAnnotation[];
 };
 
 type PendingComposerOperation = {
@@ -49,6 +53,7 @@ type PendingComposerOperation = {
   input: SendMessageInput;
   draftAtSend: string;
   resourcesAtSend: ResourceRef[];
+  annotationsAtSend: DraftTimelineAnnotation[];
   /** Latest local text/resources that must survive an uncertain delivery. */
   newerShadow: ComposerDraftShadow;
   clearDraftOnAccept: boolean;
@@ -61,13 +66,39 @@ type StoredPendingComposerOperation = Omit<PendingComposerOperation, "input" | "
   hasMcpCredentialUpdates: boolean;
 };
 
+export type ComposerOptimisticMessage = {
+  clientEventId: string;
+  text: string;
+  annotations: DraftTimelineAnnotation[];
+  resources: ResourceRef[];
+  occurredAt: string;
+  state: "sending" | "queued" | "failed";
+  error?: string | undefined;
+  outcomeUnknown?: boolean | undefined;
+};
+
+type OptimisticSendOperation = ComposerOptimisticMessage & {
+  input: SendMessageInput;
+  draftPayload: SaveComposerDraftRequest | null;
+  /** Latest unsent local draft that must survive this operation and remounts. */
+  newerShadow: ComposerDraftShadow;
+  canRetry: boolean;
+};
+
+type StoredOptimisticSendOperation = Omit<OptimisticSendOperation, "input" | "canRetry"> & {
+  input: Omit<SendMessageInput, "mcpCredentialUpdates">;
+  hasMcpCredentialUpdates: boolean;
+};
+
 const PENDING_COMPOSER_STORAGE_PREFIX = "opengeni.pending-composer.v1:";
+const OPTIMISTIC_SEND_STORAGE_PREFIX = "opengeni.optimistic-sends.v1:";
 
 // A remount must not manufacture a new operation while the previous mutation
 // is still outcome-unknown. Keep only non-credential request fields here; the
 // mounted hook retains the exact input, including any credential updates. The
 // safe shadow is also session-scoped so a refresh cannot lose newer edits.
 const pendingComposerOperations = new Map<string, StoredPendingComposerOperation>();
+const optimisticSendOperations = new Map<string, StoredOptimisticSendOperation[]>();
 
 function pendingComposerOperationKey(
   workspaceId: string,
@@ -88,6 +119,78 @@ function pendingComposerStorageKey(key: string): string {
   return `${PENDING_COMPOSER_STORAGE_PREFIX}${encodeURIComponent(key)}`;
 }
 
+function optimisticSendStorageKey(key: string): string {
+  return `${OPTIMISTIC_SEND_STORAGE_PREFIX}${encodeURIComponent(key)}`;
+}
+
+function restoreOptimisticSendOperations(key: string | null): OptimisticSendOperation[] {
+  if (!key) return [];
+  let stored = optimisticSendOperations.get(key);
+  if (!stored) {
+    const storage = pendingComposerStorage();
+    try {
+      const parsed: unknown = JSON.parse(storage?.getItem(optimisticSendStorageKey(key)) ?? "[]");
+      stored = Array.isArray(parsed)
+        ? (parsed.filter(
+            (candidate): candidate is StoredOptimisticSendOperation =>
+              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",
+          ) as StoredOptimisticSendOperation[])
+        : [];
+    } 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: string | null,
+  operations: OptimisticSendOperation[],
+): void {
+  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 !== undefined,
+      } satisfies StoredOptimisticSendOperation;
+    });
+  optimisticSendOperations.set(key, stored);
+  try {
+    pendingComposerStorage()?.setItem(optimisticSendStorageKey(key), JSON.stringify(stored));
+  } catch {
+    // Best effort; the in-memory queue still owns this mount.
+  }
+}
+
 function resourceList(value: unknown): value is ResourceRef[] {
   return (
     Array.isArray(value) &&
@@ -103,6 +206,41 @@ function resourceList(value: unknown): value is ResourceRef[] {
   );
 }
 
+function timelineAnnotationList(value: unknown): value is DraftTimelineAnnotation[] {
+  return (
+    Array.isArray(value) &&
+    value.every((candidate) => {
+      if (typeof candidate !== "object" || candidate === null) return false;
+      const annotation = candidate as Record<string, unknown>;
+      const source = annotation.source;
+      if (typeof source !== "object" || source === null) return false;
+      const sourceRecord = source as Record<string, unknown>;
+      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: readonly DraftTimelineAnnotation[],
+): DraftTimelineAnnotation[] {
+  return annotations.map((annotation) => ({
+    ...annotation,
+    source: { ...annotation.source },
+  }));
+}
+
 function readStoredPendingComposerOperation(
   key: string | null,
 ): StoredPendingComposerOperation | null {
@@ -128,18 +266,34 @@ function readStoredPendingComposerOperation(
       (record.delivery !== "send" && record.delivery !== "steer") ||
       typeof record.draftAtSend !== "string" ||
       !resourceList(record.resourcesAtSend) ||
+      (record.annotationsAtSend !== undefined &&
+        !timelineAnnotationList(record.annotationsAtSend)) ||
       typeof shadowRecord.text !== "string" ||
       !resourceList(shadowRecord.resources) ||
+      (shadowRecord.annotations !== undefined &&
+        !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))
+      ("resources" in inputRecord && !resourceList(inputRecord.resources)) ||
+      ("annotations" in inputRecord && !timelineAnnotationList(inputRecord.annotations))
     ) {
       return null;
     }
-    return record as StoredPendingComposerOperation;
+    return {
+      ...(record as StoredPendingComposerOperation),
+      annotationsAtSend: timelineAnnotationList(record.annotationsAtSend)
+        ? record.annotationsAtSend
+        : [],
+      newerShadow: {
+        ...(shadow as ComposerDraftShadow),
+        annotations: timelineAnnotationList(shadowRecord.annotations)
+          ? shadowRecord.annotations
+          : [],
+      },
+    };
   } catch {
     return null;
   }
@@ -168,6 +322,7 @@ function restorePendingComposerOperation(key: string | null): PendingComposerOpe
     newerShadow: stored.newerShadow ?? {
       text: stored.draftAtSend,
       resources: stored.resourcesAtSend,
+      annotations: stored.annotationsAtSend,
     },
     canRetry: !stored.hasMcpCredentialUpdates,
   };
@@ -188,6 +343,7 @@ function rememberPendingComposerOperation(
     newerShadow: {
       text: operation.newerShadow.text,
       resources: [...operation.newerShadow.resources],
+      annotations: cloneAnnotations(operation.newerShadow.annotations),
     },
   } satisfies StoredPendingComposerOperation;
   pendingComposerOperations.set(key, stored);
@@ -212,7 +368,14 @@ function updatePendingComposerShadow(
   shadow: ComposerDraftShadow,
 ): PendingComposerOperation | null {
   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;
 }
@@ -220,14 +383,27 @@ function updatePendingComposerShadow(
 export type ComposerState = {
   value: string;
   setValue: (value: string) => void;
+  annotations?: DraftTimelineAnnotation[] | undefined;
+  addAnnotation?: ((annotation: DraftTimelineAnnotation) => void) | undefined;
+  updateAnnotation?: ((id: string, note: string) => void) | undefined;
+  removeAnnotation?: ((id: string) => void) | undefined;
+  /** Newly captured annotation the review surface should focus. */
+  annotationReviewTargetId?: string | null | undefined;
+  clearAnnotationReviewTarget?: (() => void) | undefined;
   /** Read the current draft synchronously before a destructive replacement. */
   hasDraftContent: () => boolean;
   /** Append the draft behind prompts already visible in the queue. */
   send: (text?: string) => Promise<boolean>;
+  /** Locally acknowledged ordinary sends awaiting durable timeline reconciliation. */
+  optimisticMessages?: ComposerOptimisticMessage[] | undefined;
+  retryOptimisticMessage?: ((clientEventId: string) => void) | undefined;
+  removeOptimisticMessage?: ((clientEventId: string) => void) | undefined;
   /** Supersede current direction with the draft. */
   steer: (text?: string) => Promise<boolean>;
   /** Optimistic-to-durable projection for a Steer that has not started yet. */
   steering?: ComposerSteeringState | null | undefined;
+  /** Immediate mutation-receipt projection while physical cancellation settles. */
+  stoppingAttempt?: "current" | "previous" | null | undefined;
   sending: boolean;
   canSend: boolean;
   /** Pause the session without deleting its prompt queue. */
@@ -259,6 +435,13 @@ export type ComposerSteeringState = {
   clientEventId: string | null;
   triggerEventId: string | null;
   turnId: string | null;
+  /** True only when the accepted Steer durably interrupted a live attempt. */
+  stoppingPreviousAttempt?: boolean | undefined;
+};
+
+type ComposerControlStoppingState = {
+  controlVersion: number;
+  controlEtag: string;
 };
 
 const STEERING_SETTLEMENT_EVENT_TYPES = new Set([
@@ -321,12 +504,20 @@ export function useComposer(
   const targetKey = `${workspaceId}\u0000${sessionId ?? ""}\u0000${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<DraftTimelineAnnotation[]>(
+    () => initialShadow?.annotations ?? [],
+  );
+  const [annotationReviewTargetId, setAnnotationReviewTargetId] = useState<string | null>(null);
   // Keep rendered state behind the committed target identity for one frame:
   // a parent may switch sessionId without remounting this public hook.
   const [stateTargetKey, setStateTargetKey] = useState(targetKey);
   const [sending, setSending] = useState(false);
+  const [optimisticSends, setOptimisticSends] =
+    useState<OptimisticSendOperation[]>(initialOptimisticSends);
   const [steering, setSteering] = useState<ComposerSteeringState | null>(() =>
     initialPendingOperation?.delivery === "steer"
       ? {
@@ -339,6 +530,7 @@ export function useComposer(
       : null,
   );
   const [pausing, setPausing] = useState(false);
+  const [controlStopping, setControlStopping] = useState<ComposerControlStoppingState | null>(null);
   const [resuming, setResuming] = useState(false);
   const [error, setError] = useState<Error | null>(null);
   const [draft, setDraft] = useState<ComposerDraft | null>(null);
@@ -349,12 +541,16 @@ export function useComposer(
     () => initialShadow?.resources ?? [],
   );
   const pendingOperationRef = useRef<PendingComposerOperation | null>(initialPendingOperation);
+  const optimisticSendsRef = useRef<OptimisticSendOperation[]>(initialOptimisticSends);
+  const optimisticProcessorBusyRef = useRef(false);
+  const optimisticCallbackIdsRef = useRef(new Set<string>());
   const steeringSettlementEventsRef = useRef<SessionEvent[]>([]);
   const steeringRef = useRef(steering);
   const pendingClientEventId = useRef<string | null>(
     initialPendingOperation?.input.clientEventId ?? null,
   );
   const valueRef = useRef(initialShadow?.text ?? "");
+  const annotationsRef = useRef<DraftTimelineAnnotation[]>(initialShadow?.annotations ?? []);
   const draftRef = useRef<ComposerDraft | null>(null);
   const restoredResourcesRef = useRef<ResourceRef[]>(initialShadow?.resources ?? []);
   const localEditRevision = useRef(initialShadow ? 1 : 0);
@@ -363,6 +559,7 @@ export function useComposer(
   const lastSavedSignature = useRef<string | null>(null);
   const saveChain = useRef<Promise<void>>(Promise.resolve());
   const onSent = options.onSent;
+  const onSubmitted = options.onSubmitted;
   const onDraftApplied = options.onDraftApplied;
   // Read through a ref so live session/policy projections can replace their
   // apply callback without invalidating the draft loader and re-running its
@@ -392,11 +589,17 @@ export function useComposer(
     targetGeneration.current += 1;
     draftReadGeneration.current += 1;
     pendingOperationRef.current = restorePendingComposerOperation(pendingOperationKey);
+    const restoredOptimisticSends = restoreOptimisticSendOperations(pendingOperationKey);
+    optimisticSendsRef.current = restoredOptimisticSends;
+    optimisticProcessorBusyRef.current = false;
+    optimisticCallbackIdsRef.current = 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;
@@ -405,7 +608,10 @@ export function useComposer(
     saveChain.current = Promise.resolve();
     setStateTargetKey(targetKey);
     setValue(shadow?.text ?? "");
+    setAnnotations(shadow?.annotations ?? []);
+    setAnnotationReviewTargetId(null);
     setSending(false);
+    setOptimisticSends(restoredOptimisticSends);
     setSteering(
       pendingOperationRef.current?.delivery === "steer"
         ? {
@@ -418,6 +624,7 @@ export function useComposer(
         : null,
     );
     setPausing(false);
+    setControlStopping(null);
     setResuming(false);
     setError(null);
     setDraft(null);
@@ -427,17 +634,37 @@ export function useComposer(
     setRestoredResources(shadow?.resources ?? []);
   }, [durableDrafts, pendingOperationKey, sessionId, targetKey]);
 
+  const setOptimisticDraftShadow = useCallback(
+    (shadow: ComposerDraftShadow): void => {
+      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: ComposerDraft): void => {
       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,
@@ -448,18 +675,29 @@ export function useComposer(
               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,
@@ -470,12 +708,21 @@ export function useComposer(
             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(
@@ -496,6 +743,7 @@ export function useComposer(
               baseAtStart,
               valueRef.current,
               restoredResourcesRef.current,
+              annotationsRef.current,
               extrasAtStart,
             ),
           )
@@ -525,15 +773,19 @@ export function useComposer(
           draftRef.current = fetched;
           setDraft(fetched);
           setDraftConflict(null);
-          const shadow = pendingOperationRef.current?.newerShadow;
+          const shadow =
+            pendingOperationRef.current?.newerShadow ??
+            optimisticSendsRef.current.at(-1)?.newerShadow;
           if (shadow) {
             // The server can only know the original operation. Never replace
             // newer local edits while that operation is still uncertain.
             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)
@@ -549,9 +801,11 @@ export function useComposer(
               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);
             }
@@ -675,13 +929,32 @@ export function useComposer(
     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;
+    }
+    // A newer control revision, an impossible same-version/different-etag
+    // projection, or quiescence at this exact revision supersedes the local
+    // mutation receipt. SessionChrome then falls back to durable queue truth.
+    setControlStopping((current) => (current === controlStopping ? null : current));
+  }, [controlStopping, options.effectiveControl]);
+
   const currentDraftPayload = useCallback((): SaveComposerDraftRequest | null => {
     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: SaveComposerDraftRequest): Promise<boolean> => {
@@ -758,6 +1031,177 @@ export function useComposer(
     [client, durableDrafts, sessionId, targetKey, workspaceId],
   );
 
+  const replaceOptimisticSends = useCallback(
+    (
+      update: (current: OptimisticSendOperation[]) => OptimisticSendOperation[],
+    ): OptimisticSendOperation[] => {
+      const next = update(optimisticSendsRef.current);
+      optimisticSendsRef.current = next;
+      rememberOptimisticSendOperations(pendingOperationKey, next);
+      setOptimisticSends(next);
+      return next;
+    },
+    [pendingOperationKey],
+  );
+
+  const markOptimisticAccepted = useCallback(
+    (operation: OptimisticSendOperation): void => {
+      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 as string),
+    );
+    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((): void => {
+    if (!sessionId || optimisticProcessorBusyRef.current) return;
+    const currentOperations = optimisticSendsRef.current;
+    const operationIndex = currentOperations.findIndex(
+      (candidate) => candidate.state === "sending",
+    );
+    const operation = operationIndex < 0 ? undefined : 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: number | undefined;
+        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 !== undefined ? { expectedDraftRevision } : {}),
+        };
+        await client.sendMessage(workspaceId, sessionId, wireInput);
+        if (
+          targetKeyRef.current !== ownedTargetKey ||
+          targetGeneration.current !== ownedGeneration
+        ) {
+          return;
+        }
+        if (options.events === undefined) {
+          markOptimisticAccepted({ ...operation, input: wireInput });
+        } else {
+          replaceOptimisticSends((current) =>
+            current.map((candidate) =>
+              candidate.clientEventId === operation.clientEventId
+                ? { ...candidate, input: wireInput, state: "queued", error: undefined }
+                : 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]);
+
   // Private durable autosave. A newer local edit is never replaced by an older
   // response; saves serialize and each reads the latest acknowledged revision.
   useEffect(() => {
@@ -769,10 +1213,12 @@ export function useComposer(
           restoredResourcesRef.current,
           resolveSendExtras(sendExtrasRef.current).resources ?? [],
         ),
+        annotations: annotationsRef.current,
       };
       if (
         pending.newerShadow.text !== shadow.text ||
-        JSON.stringify(pending.newerShadow.resources) !== JSON.stringify(shadow.resources)
+        JSON.stringify(pending.newerShadow.resources) !== JSON.stringify(shadow.resources) ||
+        JSON.stringify(pending.newerShadow.annotations) !== JSON.stringify(shadow.annotations)
       ) {
         pendingOperationRef.current = updatePendingComposerShadow(
           pendingOperationKey,
@@ -782,6 +1228,27 @@ export function useComposer(
       }
       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 ||
@@ -803,6 +1270,7 @@ export function useComposer(
     liveExtrasVersion,
     pendingOperationKey,
     persistPayload,
+    setOptimisticDraftShadow,
     sending,
     sessionId,
   ]);
@@ -818,14 +1286,19 @@ export function useComposer(
         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 annotationsComplete = annotationsAtSend.every(
+        (annotation) => annotation.note.trim().length > 0,
+      );
       // Resolve the extras once: a file-only message (empty text + ≥1 ready
       // resource) is legitimate, so we must not bail on empty text alone.
       const extras = pending ? {} : resolveSendExtras(sendExtrasRef.current);
       const hasResources = restoredResources.length > 0 || (extras.resources?.length ?? 0) > 0;
       if (
-        (!pending && !hasText && !hasResources) ||
+        (!pending && (!annotationsComplete || (!hasText && !hasResources && !hasAnnotations))) ||
         !sessionId ||
         sending ||
         sendBlockedRef.current?.() === true ||
@@ -848,6 +1321,8 @@ export function useComposer(
         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 = {
@@ -855,6 +1330,7 @@ export function useComposer(
             revision: 0,
             text: "",
             resources: [],
+            annotations: [],
             sourceTurnId: null,
             sourceTurnVersion: null,
             updatedAt: null,
@@ -867,6 +1343,11 @@ export function useComposer(
           restoredResourcesRef.current = [];
           setRestoredResources([]);
         }
+        if (annotationsWereUnchanged) {
+          annotationsRef.current = [];
+          setAnnotations([]);
+          setAnnotationReviewTargetId(null);
+        }
         if (operation.clearDraftOnAccept && draftWasUnchanged) {
           valueRef.current = "";
           setValue("");
@@ -955,6 +1436,8 @@ export function useComposer(
                 clientEventId: pending.input.clientEventId ?? null,
                 triggerEventId: result.accepted.id,
                 turnId: result.turn.id,
+                stoppingPreviousAttempt:
+                  result.replay !== true && (result.interruptionCount ?? 0) > 0,
               });
             }
           } catch (cause) {
@@ -981,7 +1464,7 @@ export function useComposer(
         // and submitted byte-for-byte, while file-only sends use the same
         // placeholder for both operations so the server content fence cannot
         // reject its own client.
-        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;
@@ -1003,15 +1486,18 @@ export function useComposer(
             ? { expectedDraftRevision: draftRef.current.revision }
             : {}),
           resources: mergeResources(restoredResources, extras.resources ?? []),
+          annotations: cloneAnnotations(annotationsAtSend),
         });
         const operation: PendingComposerOperation = {
           delivery,
           input,
           draftAtSend,
           resourcesAtSend: [...restoredResources],
+          annotationsAtSend: cloneAnnotations(annotationsAtSend),
           newerShadow: {
             text: draftAtSend,
             resources: mergeResources(restoredResources, extras.resources ?? []),
+            annotations: cloneAnnotations(annotationsAtSend),
           },
           clearDraftOnAccept: explicit === undefined,
           canRetry: true,
@@ -1037,6 +1523,8 @@ export function useComposer(
               clientEventId: input.clientEventId ?? null,
               triggerEventId: result.accepted.id,
               turnId: result.turn.id,
+              stoppingPreviousAttempt:
+                result.replay !== true && (result.interruptionCount ?? 0) > 0,
             });
           }
         } catch (cause) {
@@ -1079,6 +1567,7 @@ export function useComposer(
       options.effectiveControl?.controlEtag,
       persistPayload,
       restoredResources,
+      annotations,
       sending,
       sessionId,
       targetKey,
@@ -1087,9 +1576,140 @@ export function useComposer(
     ],
   );
 
-  const send = useCallback(async (text?: string) => await dispatch("send", text), [dispatch]);
+  const send = useCallback(
+    async (explicit?: string): Promise<boolean> => {
+      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 annotationsComplete = annotationsAtSend.every(
+        (annotation) => annotation.note.trim().length > 0,
+      );
+      const extras = resolveSendExtras(sendExtrasRef.current);
+      const resources = mergeResources(restoredResourcesRef.current, extras.resources ?? []);
+      if (
+        !sessionId ||
+        sending ||
+        !annotationsComplete ||
+        (!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: OptimisticSendOperation = {
+        clientEventId,
+        text: sendText,
+        annotations: annotationsAtSend,
+        resources,
+        occurredAt: new Date().toISOString(),
+        state: "sending",
+        input,
+        draftPayload: currentPayload ? { ...currentPayload, text: sendText } : null,
+        newerShadow: {
+          text: explicit === undefined ? "" : valueRef.current,
+          resources: explicit === undefined ? [] : [...restoredResourcesRef.current],
+          annotations: explicit === undefined ? [] : cloneAnnotations(annotationsRef.current),
+        },
+        canRetry: true,
+      };
+      replaceOptimisticSends((current) => [...current, operation]);
+      queueMicrotask(processOptimisticSends);
+      setError(null);
+      onSubmitted?.(sendText, input);
+      if (explicit === undefined) {
+        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?: string) => await dispatch("steer", text), [dispatch]);
 
+  const retryOptimisticMessage = useCallback(
+    (clientEventId: string): void => {
+      replaceOptimisticSends((current) =>
+        current.map((operation) => {
+          if (operation.clientEventId !== clientEventId || operation.state !== "failed") {
+            return operation;
+          }
+          if (operation.outcomeUnknown) {
+            return { ...operation, state: "sending", error: undefined };
+          }
+          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: new Date().toISOString(),
+            state: "sending",
+            error: undefined,
+            outcomeUnknown: false,
+            canRetry: true,
+          };
+        }),
+      );
+      queueMicrotask(processOptimisticSends);
+    },
+    [options.effectiveControl?.controlEtag, processOptimisticSends, replaceOptimisticSends],
+  );
+
+  const removeOptimisticMessage = useCallback(
+    (clientEventId: string): void => {
+      replaceOptimisticSends((current) =>
+        current.filter((operation) => operation.clientEventId !== clientEventId),
+      );
+    },
+    [replaceOptimisticSends],
+  );
+
   // A send is possible with non-empty text OR with ≥1 attached resource (a
   // file-only message). Resources ride in `sendExtras`, so we resolve them here
   // — keeping useComposer attachment-agnostic while still lighting up the send
@@ -1099,6 +1719,7 @@ export function useComposer(
     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?: string): Promise<void> => {
@@ -1110,12 +1731,27 @@ export function useComposer(
       setPausing(true);
       setError(null);
       try {
-        await client.pauseSession(workspaceId, sessionId, {
+        const result = await client.pauseSession(workspaceId, sessionId, {
           ...(reason !== undefined ? { 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 &&
@@ -1241,13 +1877,87 @@ export function useComposer(
             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: DraftTimelineAnnotation[], reviewTargetId: string | null = 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: DraftTimelineAnnotation) => {
+      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: string, note: string) => {
+      updateAnnotations(
+        annotationsRef.current.map((annotation) =>
+          annotation.id === id ? { ...annotation, note } : annotation,
+        ),
+      );
+    },
+    [updateAnnotations],
+  );
+
+  const removeAnnotation = useCallback(
+    (id: string) => {
+      updateAnnotations(annotationsRef.current.filter((annotation) => annotation.id !== id));
+    },
+    [updateAnnotations],
+  );
+
+  const clearAnnotationReviewTarget = useCallback(() => {
+    setAnnotationReviewTargetId(null);
+  }, []);
+
   const removeRestoredResource = useCallback(
     (index: number) => {
       if (targetKeyRef.current !== targetKey) return;
@@ -1260,11 +1970,17 @@ export function useComposer(
         {
           text: valueRef.current,
           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((): boolean => {
@@ -1272,6 +1988,7 @@ export function useComposer(
     const extras = resolveSendExtras(sendExtrasRef.current);
     return (
       valueRef.current.length > 0 ||
+      annotationsRef.current.length > 0 ||
       restoredResourcesRef.current.length > 0 ||
       (extras.resources?.length ?? 0) > 0 ||
       (current?.sourceTurnId !== null && current?.sourceTurnId !== undefined)
@@ -1312,6 +2029,7 @@ export function useComposer(
   );
 
   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;
@@ -1322,17 +2040,41 @@ export function useComposer(
   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),
+      annotationsComplete &&
+      (hasPendingOperation ||
+        value.trim().length > 0 ||
+        hasReadyResources ||
+        annotations.length > 0),
     pause,
     pausing: identityMatches ? pausing : false,
     resume,
@@ -1360,12 +2102,12 @@ export function isComposerDraftEvent(event: Pick<SessionEvent, "type">): boolean
 }
 
 /**
- * Default text for a file-only message (attachment(s) present, no typed draft).
- * Kept non-empty so the wire contract (`text: z.string().min(1)`) and the
- * worker's non-whitespace guard accept it; the attached files still ride in
- * `resources`. Exported for tests.
+ * Default text for a resource-only message (attachments present, no typed
+ * draft). Kept non-empty so the wire contract (`text: z.string().min(1)`) and
+ * the worker's non-whitespace guard accept it. The export name is retained for
+ * compatibility now that repositories can ride beside files in `resources`.
  */
-export const FILE_ONLY_MESSAGE_TEXT = "(see attached files)";
+export const FILE_ONLY_MESSAGE_TEXT = "(see attached context)";
 
 /** Resolve possibly-deferred extras to a concrete bag (function evaluated now). */
 export function resolveSendExtras(
@@ -1477,6 +2219,7 @@ function draftPayload(draft: ComposerDraft): SaveComposerDraftRequest {
     expectedRevision: draft.revision,
     text: draft.text,
     resources: draft.resources,
+    annotations: draft.annotations ?? [],
     model: draft.model,
     reasoningEffort: draft.reasoningEffort,
     latencyMode: draft.latencyMode ?? "standard",
@@ -1487,12 +2230,14 @@ function composerDraftPayload(
   base: ComposerDraft,
   text: string,
   restoredResources: ResourceRef[],
+  annotations: DraftTimelineAnnotation[],
   extras: ComposerSendExtras,
 ): SaveComposerDraftRequest {
   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",