@opengeni/react 3.1.0 → 3.1.2

package/src/hooks/use-composer.ts

@@ -5,7 +5,7 @@ import {
   type EffectiveControlResumeOption,
   type EffectiveSessionControl,
   type LatencyMode,
-  type OpenGeniApiError,
+  OpenGeniApiError,
   type ReasoningEffort,
   type ResourceRef,
   type SaveComposerDraftRequest,
@@ -15,6 +15,16 @@ import {
 } from "@opengeni/sdk";
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
 import { useEmbeddedSession, type EmbeddedSessionClientOverride } from "../session-context";
+import {
+  COMPOSER_MODEL_UNAVAILABLE_MESSAGE,
+  ComposerReconciliationRequiredError,
+  ComposerStateError,
+  ComposerWorkspaceControlUnavailableError,
+  composerSubmissionCanRetry,
+  composerSubmissionErrorMessage,
+} from "../lib/format";
+import { normalizeError, useErrorMessage } from "../lib/error-message";
+import { notifyObserver as notifyComposerObserver } from "../lib/notify-observer";
 import { useSessionEventTrigger, type SessionEventFeedOptions } from "./internal";
 
 export type ComposerPolicy = {
@@ -28,11 +38,19 @@ export type ComposerSendExtras = Omit<
   "text" | "clientEventId" | "annotations" | "model" | "reasoningEffort" | "latencyMode"
 >;
 
+/** Unsent local content handed off from a new-conversation composer. */
+export type InitialComposerDraft = {
+  text: string;
+  resources?: ResourceRef[] | undefined;
+  annotations?: DraftTimelineAnnotation[] | undefined;
+  policy?: ComposerPolicy | undefined;
+};
+
 export type UseComposerOptions = EmbeddedSessionClientOverride &
   SessionEventFeedOptions & {
-    /** Called synchronously after an ordinary Send is accepted by the local UI. */
+    /** Called synchronously after local submission. Observer errors never change delivery. */
     onSubmitted?: ((text: string, input: SendMessageInput) => void) | undefined;
-    /** Called with the exact accepted wire input after a successful send. */
+    /** Called with the accepted wire input. Observer errors never turn acceptance into failure. */
     onSent?: ((text: string, input: SendMessageInput) => void) | undefined;
     /** Called with the exact wire input after a delivery failure. */
     onDeliveryError?:
@@ -57,6 +75,13 @@ export type UseComposerOptions = EmbeddedSessionClientOverride &
     draftPersistence?: "durable" | "disabled" | undefined;
     /** Required explicit authority when durable draft persistence is disabled. */
     initialPolicy?: ComposerPolicy | undefined;
+    /**
+     * Seed local unsent content once when this session is mounted/selected.
+     * The real server draft still supplies the revision used for persistence.
+     * A retained uncertain submission takes precedence over this handoff.
+     * An empty seed does not erase an existing server draft.
+     */
+    initialDraft?: InitialComposerDraft | undefined;
   };
 
 type ComposerDraftShadow = {
@@ -66,6 +91,19 @@ type ComposerDraftShadow = {
   policy?: ComposerPolicy | undefined;
 };
 
+function initialComposerShadow(
+  seed: InitialComposerDraft | undefined,
+): ComposerDraftShadow | undefined {
+  if (!seed || (!seed.text && !seed.resources?.length && !seed.annotations?.length && !seed.policy))
+    return undefined;
+  return {
+    text: seed.text,
+    resources: [...(seed.resources ?? [])],
+    annotations: cloneAnnotations(seed.annotations ?? []),
+    ...(seed.policy ? { policy: { ...seed.policy } } : {}),
+  };
+}
+
 type PendingComposerOperation = {
   delivery: "send" | "steer";
   input: SendMessageInput;
@@ -97,6 +135,10 @@ export type ComposerOptimisticMessage = {
   triggerEventId?: string | null | undefined;
   appliedQueueVersion?: number | null | undefined;
   error?: string | undefined;
+  /** Bounded support reference retained independently of display copy across remounts. */
+  correlationId?: string | undefined;
+  /** False for a definitive refusal that requires changing payment or allowance settings. */
+  retryable?: boolean | undefined;
   outcomeUnknown?: boolean | undefined;
 };
 
@@ -182,15 +224,43 @@ function restoreOptimisticSendOperations(key: string | null): OptimisticSendOper
       operation.state === "sending" || operation.state === "queued"
         ? true
         : operation.outcomeUnknown,
-    error:
-      operation.state === "sending"
-        ? "Delivery was interrupted; retry to reconcile this message."
-        : operation.error,
+    correlationId: restoredCorrelationId(operation.correlationId),
+    error: restoredErrorReference(
+      operation.correlationId,
+      hasMcpCredentialUpdates && (operation.state === "sending" || operation.outcomeUnknown)
+        ? composerSubmissionErrorMessage(new ComposerReconciliationRequiredError())
+        : operation.state === "sending"
+          ? "Delivery was interrupted; retry to reconcile this message."
+          : operation.outcomeUnknown
+            ? "The request could not be confirmed. Check its status before retrying."
+            : operation.error
+              ? composerSubmissionErrorMessage(new Error(operation.error))
+              : undefined,
+    ),
+    retryable:
+      operation.state === "sending" || operation.outcomeUnknown
+        ? true
+        : (operation.retryable ??
+          (operation.error ? composerSubmissionCanRetry(new Error(operation.error)) : true)),
     input: operation.input,
     canRetry: !hasMcpCredentialUpdates,
   }));
 }
 
+function restoredCorrelationId(value: unknown): string | undefined {
+  return typeof value === "string" && /^[\w.:-]{1,128}$/u.test(value) ? value : undefined;
+}
+
+function restoredErrorReference(
+  reference: unknown,
+  message: string | undefined,
+): string | undefined {
+  const correlationId = restoredCorrelationId(reference);
+  return message && correlationId && message !== COMPOSER_MODEL_UNAVAILABLE_MESSAGE
+    ? `${message} Reference: ${correlationId}.`
+    : message;
+}
+
 function rememberOptimisticSendOperations(
   key: string | null,
   operations: OptimisticSendOperation[],
@@ -424,6 +494,8 @@ export type ComposerState = {
   /** Newly captured annotation the review surface should focus. */
   annotationReviewTargetId?: string | null | undefined;
   clearAnnotationReviewTarget?: (() => void) | undefined;
+  /** Focus an annotation, or the first incomplete note when omitted. */
+  requestAnnotationReview?: ((id?: string) => void) | undefined;
   /** Read the current draft synchronously before a destructive replacement. */
   hasDraftContent: () => boolean;
   /** Append the draft behind prompts already visible in the queue. */
@@ -431,6 +503,8 @@ export type ComposerState = {
   /** Locally acknowledged ordinary sends awaiting durable timeline reconciliation. */
   optimisticMessages?: ComposerOptimisticMessage[] | undefined;
   retryOptimisticMessage?: ((clientEventId: string) => void) | undefined;
+  /** Move a definitively refused message into an empty composer without resending it. */
+  restoreOptimisticMessage?: ((clientEventId: string) => void) | undefined;
   removeOptimisticMessage?: ((clientEventId: string) => void) | undefined;
   /** Supersede current direction with the draft. */
   steer: (text?: string) => Promise<boolean>;
@@ -569,9 +643,17 @@ function reconcileOptimisticSendFromEvents(
   );
   const triggerEventId = operation.triggerEventId ?? accepted?.id ?? null;
   const turnId = operation.turnId ?? promptTurnIdForTrigger(triggerEventId, events);
+  const acceptedRouting = promptRoutingFromAcceptedEvent(accepted ?? null);
+  const destination =
+    acceptedRouting === "queued_for_execution"
+      ? "queue"
+      : acceptedRouting === "accepted_for_execution" || acceptedRouting === "accepted_for_steering"
+        ? "chat"
+        : operation.destination;
   const needsAdmissionUpdate =
     accepted !== undefined &&
     (operation.state !== "queued" ||
+      operation.destination !== destination ||
       operation.triggerEventId !== triggerEventId ||
       operation.turnId !== turnId ||
       operation.error !== undefined ||
@@ -580,6 +662,7 @@ function reconcileOptimisticSendFromEvents(
     ? {
         ...operation,
         state: "queued",
+        destination,
         triggerEventId,
         turnId,
         error: undefined,
@@ -628,6 +711,7 @@ export function useComposer(
   options: UseComposerOptions = {},
 ): ComposerControllerState {
   const { client, workspaceId, registerSessionReconciler } = useEmbeddedSession(options);
+  const formatError = useErrorMessage();
   const durableDrafts = options.draftPersistence !== "disabled";
   if (!durableDrafts && !options.initialPolicy) {
     throw new Error("useComposer requires initialPolicy when draft persistence is disabled");
@@ -637,7 +721,9 @@ export function useComposer(
   const initialPendingOperation = restorePendingComposerOperation(pendingOperationKey);
   const initialOptimisticSends = restoreOptimisticSendOperations(pendingOperationKey);
   const initialShadow =
-    initialPendingOperation?.newerShadow ?? initialOptimisticSends.at(-1)?.newerShadow;
+    initialPendingOperation?.newerShadow ??
+    initialOptimisticSends.at(-1)?.newerShadow ??
+    initialComposerShadow(options.initialDraft);
   const [value, setValue] = useState(() => initialShadow?.text ?? "");
   const [annotations, setAnnotations] = useState<DraftTimelineAnnotation[]>(
     () => initialShadow?.annotations ?? [],
@@ -666,6 +752,8 @@ export function useComposer(
   const [acceptedControl, setAcceptedControl] = useState<EffectiveSessionControl | null>(null);
   const [resuming, setResuming] = useState(false);
   const [error, setError] = useState<Error | null>(null);
+  // Background draft reads recover independently of Send/Steer/control failures.
+  const [draftReadError, setDraftReadError] = useState<Error | null>(null);
   const [draft, setDraft] = useState<ComposerDraft | null>(null);
   const [draftLoading, setDraftLoading] = useState(Boolean(sessionId) && durableDrafts);
   const [draftSaving, setDraftSaving] = useState(false);
@@ -697,6 +785,7 @@ export function useComposer(
   const targetGeneration = useRef(0);
   const draftReadGeneration = useRef(0);
   const draftReadInFlightRef = useRef<string | null>(null);
+  const draftReadAbortRef = useRef<AbortController | null>(null);
   const draftReadRetryRef = useRef<{
     targetKey: string;
     failures: number;
@@ -704,8 +793,18 @@ export function useComposer(
   }>({ targetKey, failures: 0, timer: null });
   const lastSavedSignature = useRef<string | null>(null);
   const saveChain = useRef<Promise<void>>(Promise.resolve());
-  const onSent = options.onSent;
-  const onSubmitted = options.onSubmitted;
+  const onSent = useCallback(
+    (text: string, input: SendMessageInput) => {
+      notifyComposerObserver(options.onSent, text, input);
+    },
+    [options.onSent],
+  );
+  const onSubmitted = useCallback(
+    (text: string, input: SendMessageInput) => {
+      notifyComposerObserver(options.onSubmitted, text, input);
+    },
+    [options.onSubmitted],
+  );
   const onDeliveryErrorRef = useRef(options.onDeliveryError);
   onDeliveryErrorRef.current = options.onDeliveryError;
   useLayoutEffect(() => {
@@ -733,6 +832,8 @@ export function useComposer(
     if (draftReadRetryRef.current.timer !== null) {
       clearTimeout(draftReadRetryRef.current.timer);
     }
+    draftReadAbortRef.current?.abort();
+    draftReadAbortRef.current = null;
     draftReadRetryRef.current = { targetKey, failures: 0, timer: null };
     targetKeyRef.current = targetKey;
     targetGeneration.current += 1;
@@ -745,7 +846,9 @@ export function useComposer(
     steeringSettlementEventsRef.current = [];
     pendingClientEventId.current = pendingOperationRef.current?.input.clientEventId ?? null;
     const shadow =
-      pendingOperationRef.current?.newerShadow ?? restoredOptimisticSends.at(-1)?.newerShadow;
+      pendingOperationRef.current?.newerShadow ??
+      restoredOptimisticSends.at(-1)?.newerShadow ??
+      initialComposerShadow(options.initialDraft);
     localEditRevision.current = shadow ? 1 : 0;
     valueRef.current = shadow?.text ?? "";
     annotationsRef.current = shadow?.annotations ?? [];
@@ -780,17 +883,30 @@ export function useComposer(
     setAcceptedControl(null);
     setResuming(false);
     setError(null);
+    setDraftReadError(null);
     setDraft(null);
     setDraftLoading(Boolean(sessionId) && durableDrafts);
     setDraftSaving(false);
     setDraftConflict(null);
     setRestoredResources(shadow?.resources ?? []);
-  }, [durableDrafts, options.initialPolicy, pendingOperationKey, sessionId, targetKey]);
+  }, [
+    durableDrafts,
+    options.initialPolicy,
+    options.initialDraft,
+    pendingOperationKey,
+    sessionId,
+    targetKey,
+  ]);
   useEffect(
     () => () => {
       if (draftReadRetryRef.current.timer !== null) {
         clearTimeout(draftReadRetryRef.current.timer);
       }
+      targetGeneration.current += 1;
+      draftReadGeneration.current += 1;
+      draftReadInFlightRef.current = null;
+      draftReadAbortRef.current?.abort();
+      draftReadAbortRef.current = null;
     },
     [],
   );
@@ -901,6 +1017,7 @@ export function useComposer(
       if (targetKeyRef.current !== targetKey) return;
       if (!sessionId || !durableDrafts) {
         setDraftLoading(false);
+        setDraftReadError(null);
         return;
       }
       let retry = draftReadRetryRef.current;
@@ -929,6 +1046,9 @@ export function useComposer(
       draftReadInFlightRef.current = targetKey;
       const generation = targetGeneration.current;
       const readTicket = ++draftReadGeneration.current;
+      const requestAbort = new AbortController();
+      draftReadAbortRef.current?.abort();
+      draftReadAbortRef.current = requestAbort;
       const localAtStart = localEditRevision.current;
       const baseAtStart = draftRef.current;
       const policyAtStart = policyRef.current;
@@ -958,7 +1078,9 @@ export function useComposer(
         setDraftLoading(true);
       }
       try {
-        const fetched = await client.getComposerDraft(workspaceId, sessionId);
+        const fetched = await client.getComposerDraft(workspaceId, sessionId, {
+          signal: requestAbort.signal,
+        });
         if (
           generation !== targetGeneration.current ||
           targetKeyRef.current !== targetKey ||
@@ -969,6 +1091,8 @@ export function useComposer(
         if (retry.timer !== null) clearTimeout(retry.timer);
         retry.failures = 0;
         retry.timer = null;
+        // Recovery also counts when the server returns the same draft revision.
+        setDraftReadError(null);
         const currentRevision = draftRef.current?.revision ?? -1;
         // Reconnect and client-generation effects can legitimately ask for the
         // draft again. A same-revision response is not new authority: publishing
@@ -1021,12 +1145,20 @@ export function useComposer(
         }
       } catch (cause) {
         if (
+          !requestAbort.signal.aborted &&
           generation === targetGeneration.current &&
           targetKeyRef.current === targetKey &&
           readTicket === draftReadGeneration.current
         ) {
-          setError(asError(cause));
+          const problem = asError(cause);
+          const timedOut = problem.name === "TimeoutError";
+          setDraftReadError(
+            timedOut
+              ? new ComposerStateError("Draft sync timed out. Retrying…", { cause })
+              : problem,
+          );
           if (
+            timedOut ||
             cause instanceof TypeError ||
             (cause && typeof cause === "object" && "retryable" in cause && cause.retryable === true)
           ) {
@@ -1049,6 +1181,9 @@ export function useComposer(
         if (draftReadInFlightRef.current === targetKey) {
           draftReadInFlightRef.current = null;
         }
+        if (draftReadAbortRef.current === requestAbort) {
+          draftReadAbortRef.current = null;
+        }
       }
     },
     [client, durableDrafts, sessionId, targetKey, workspaceId],
@@ -1327,21 +1462,34 @@ export function useComposer(
     optimisticProcessorBusyRef.current = true;
     void (async () => {
       let mutationFailureObserved = false;
-      const markFailed = (problem: Error, outcomeUnknown: boolean): void => {
+      const markFailed = (cause: unknown, outcomeUnknown: boolean): void => {
         if (
           targetKeyRef.current !== ownedTargetKey ||
           targetGeneration.current !== ownedGeneration
         ) {
           return;
         }
+        const problem = asError(cause);
         replaceOptimisticSends((current) =>
           current.map((candidate) =>
             candidate.clientEventId === operation.clientEventId
               ? {
                   ...candidate,
                   state: "failed",
-                  error: problem.message,
+                  error: formatError(
+                    cause,
+                    outcomeUnknown &&
+                      !isOutcomeUnknownError(problem) &&
+                      !(problem instanceof ComposerReconciliationRequiredError)
+                      ? `The request could not be confirmed. Check its status before retrying.${problem instanceof OpenGeniApiError && problem.correlationId ? ` Reference: ${problem.correlationId}.` : ""}`
+                      : composerSubmissionErrorMessage(problem),
+                  ),
+                  retryable: outcomeUnknown || composerSubmissionCanRetry(problem),
                   outcomeUnknown,
+                  correlationId:
+                    problem instanceof OpenGeniApiError
+                      ? problem.correlationId
+                      : candidate.correlationId,
                 }
               : candidate,
           ),
@@ -1368,7 +1516,7 @@ export function useComposer(
             // This read cannot settle the prior mutation in either direction.
             // Preserve its exact key and uncertain status until reconciliation
             // succeeds or that same mutation is actually replayed.
-            markFailed(asError(cause), true);
+            markFailed(cause, true);
             return;
           }
           const reconciled = reconcileOptimisticSendFromEvents(operation, events);
@@ -1392,15 +1540,13 @@ export function useComposer(
             return;
           }
           if (!operation.canRetry) {
-            throw new Error(
-              "OpenGeni cannot safely retry this uncertain request after remount; reconcile the session before sending again.",
-            );
+            throw new ComposerReconciliationRequiredError();
           }
         }
         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.");
+            throw new ComposerStateError("The message draft could not be saved before delivery.");
           }
           expectedDraftRevision = draftRef.current?.revision;
         }
@@ -1418,7 +1564,7 @@ export function useComposer(
         let acceptedEvent: SessionEvent | null = null;
         if (durableDrafts) {
           if (!operation.draftPayload || expectedDraftRevision === undefined) {
-            throw new Error("The durable composer draft is not ready for delivery.");
+            throw new ComposerStateError("The durable composer draft is not ready for delivery.");
           }
           const result = await client
             .submitComposerDraft(workspaceId, sessionId, {
@@ -1436,9 +1582,10 @@ export function useComposer(
               ...(wireInput.mcpCredentialUpdates
                 ? { mcpCredentialUpdates: wireInput.mcpCredentialUpdates }
                 : {}),
-              ...(wireInput.connectionAuthorities
-                ? { connectionAuthorities: wireInput.connectionAuthorities }
+              ...(wireInput.connectionAccounts
+                ? { connectionAccounts: wireInput.connectionAccounts }
                 : {}),
+
               ...(wireInput.personalResourceAttachment
                 ? { personalResourceAttachment: wireInput.personalResourceAttachment }
                 : {}),
@@ -1463,10 +1610,13 @@ export function useComposer(
         ) {
           return;
         }
+        const acceptedRouting =
+          acceptedResult?.routing ?? promptRoutingFromAcceptedEvent(acceptedEvent);
         const acceptedDestination =
-          acceptedResult?.routing === "queued_for_execution"
+          acceptedRouting === "queued_for_execution"
             ? "queue"
-            : acceptedResult?.routing === "accepted_for_execution"
+            : acceptedRouting === "accepted_for_execution" ||
+                acceptedRouting === "accepted_for_steering"
               ? "chat"
               : operation.destination;
         if (options.events === undefined && acceptedDestination === "chat") {
@@ -1505,14 +1655,14 @@ export function useComposer(
           return;
         }
         const problem = asError(cause);
-        onDeliveryErrorRef.current?.(problem, operation.input, "send");
+        notifyComposerObserver(onDeliveryErrorRef.current, problem, operation.input, "send");
         // Only an actual mutation replay can replace prior uncertainty with a
         // definitive response. Local preparation failures remain retry-only.
         const outcomeUnknown =
           operation.outcomeUnknown && !mutationFailureObserved
             ? true
             : isOutcomeUnknownError(cause);
-        markFailed(problem, outcomeUnknown);
+        markFailed(cause, outcomeUnknown);
       } finally {
         optimisticProcessorBusyRef.current = false;
         if (targetKeyRef.current === ownedTargetKey) {
@@ -1524,6 +1674,7 @@ export function useComposer(
     adoptDraftBase,
     client,
     durableDrafts,
+    formatError,
     markOptimisticAccepted,
     loadDraft,
     onSent,
@@ -1692,7 +1843,7 @@ export function useComposer(
             input.reasoningEffort === undefined ||
             input.latencyMode === undefined
           ) {
-            throw new Error("The durable composer draft is not ready for delivery.");
+            throw new ComposerStateError("The durable composer draft is not ready for delivery.");
           }
           const result = await client.submitComposerDraft(workspaceId, sessionId, {
             text: input.text,
@@ -1709,9 +1860,7 @@ export function useComposer(
             ...(input.mcpCredentialUpdates
               ? { mcpCredentialUpdates: input.mcpCredentialUpdates }
               : {}),
-            ...(input.connectionAuthorities
-              ? { connectionAuthorities: input.connectionAuthorities }
-              : {}),
+            ...(input.connectionAccounts ? { connectionAccounts: input.connectionAccounts } : {}),
             ...(input.personalResourceAttachment
               ? { personalResourceAttachment: input.personalResourceAttachment }
               : {}),
@@ -1799,11 +1948,7 @@ export function useComposer(
             return true;
           }
           if (!pending.canRetry) {
-            setError(
-              new Error(
-                "OpenGeni cannot safely retry this uncertain request after remount; reconcile the session before sending again.",
-              ),
-            );
+            setError(new ComposerReconciliationRequiredError());
             return false;
           }
           try {
@@ -1823,7 +1968,12 @@ export function useComposer(
           } catch (cause) {
             const problem = asError(cause);
             const outcomeUnknown = isOutcomeUnknownError(cause);
-            onDeliveryErrorRef.current?.(problem, pending.input, pending.delivery);
+            notifyComposerObserver(
+              onDeliveryErrorRef.current,
+              problem,
+              pending.input,
+              pending.delivery,
+            );
             if (!outcomeUnknown) {
               clearPending();
               keepSteering = false;
@@ -1926,7 +2076,12 @@ export function useComposer(
             });
           }
         } catch (cause) {
-          onDeliveryErrorRef.current?.(asError(cause), operation.input, operation.delivery);
+          notifyComposerObserver(
+            onDeliveryErrorRef.current,
+            asError(cause),
+            operation.input,
+            operation.delivery,
+          );
           if (!isOutcomeUnknownError(cause)) {
             clearPending();
           } else if (delivery === "steer") {
@@ -2097,6 +2252,7 @@ export function useComposer(
           if (operation.outcomeUnknown) {
             return { ...operation, state: "sending", error: undefined };
           }
+          if (operation.retryable === false) return operation;
           const nextClientEventId = generateClientEventId();
           const currentPersonalResourceAttachment = resolveSendExtras(
             sendExtrasRef.current,
@@ -2126,6 +2282,7 @@ export function useComposer(
             occurredAt: new Date().toISOString(),
             state: "sending",
             error: undefined,
+            retryable: undefined,
             outcomeUnknown: false,
             canRetry: true,
           };
@@ -2196,7 +2353,7 @@ export function useComposer(
           targetKeyRef.current === ownedTargetKey &&
           targetGeneration.current === ownedGeneration
         ) {
-          setError(cause instanceof Error ? cause : new Error(String(cause)));
+          setError(normalizeError(cause));
         }
       } finally {
         if (
@@ -2240,7 +2397,7 @@ export function useComposer(
           targetKeyRef.current === ownedTargetKey &&
           targetGeneration.current === ownedGeneration
         ) {
-          setError(cause instanceof Error ? cause : new Error(String(cause)));
+          setError(normalizeError(cause));
         }
       } finally {
         if (
@@ -2267,9 +2424,7 @@ export function useComposer(
             (blocker) => blocker.kind === "workspace",
           );
           if (!client.setWorkspaceInferenceState) {
-            throw new Error(
-              "@opengeni/react: workspace-scoped resume requires setWorkspaceInferenceState.",
-            );
+            throw new ComposerWorkspaceControlUnavailableError();
           }
           const clientEventId = generateClientEventId();
           await replayOutcomeUnknown(() =>
@@ -2399,7 +2554,7 @@ export function useComposer(
   const addAnnotation = useCallback(
     (annotation: DraftTimelineAnnotation) => {
       if (annotationsRef.current.length >= 12) {
-        setError(new Error("A message can include at most 12 timeline annotations."));
+        setError(new ComposerStateError("A message can include at most 12 timeline annotations."));
         return;
       }
       const next = [...annotationsRef.current, annotation];
@@ -2430,6 +2585,20 @@ export function useComposer(
     setAnnotationReviewTargetId(null);
   }, []);
 
+  const requestAnnotationReview = useCallback((id?: string) => {
+    const current = annotationsRef.current;
+    if (current.length === 0) {
+      setAnnotationReviewTargetId(null);
+      return;
+    }
+    if (id && current.some((annotation) => annotation.id === id)) {
+      setAnnotationReviewTargetId(id);
+      return;
+    }
+    const incomplete = current.find((annotation) => annotation.note.trim().length === 0);
+    setAnnotationReviewTargetId(incomplete?.id ?? current[0]!.id);
+  }, []);
+
   const updatePolicy = useCallback(
     (next: ComposerPolicy): void => {
       if (targetKeyRef.current !== targetKey) return;
@@ -2518,6 +2687,42 @@ export function useComposer(
     );
   }, []);
 
+  const restoreOptimisticMessage = useCallback(
+    (clientEventId: string): void => {
+      if (
+        targetKeyRef.current !== targetKey ||
+        draftLoading ||
+        pendingOperationRef.current ||
+        hasDraftContent()
+      )
+        return;
+      const operation = optimisticSendsRef.current.find(
+        (candidate) => candidate.clientEventId === clientEventId,
+      );
+      if (!operation || operation.state !== "failed" || operation.outcomeUnknown) return;
+      // Restoring is a new draft edit, not a retry. Keep the user's current model
+      // selection and never copy credentials from the old rejected request.
+      localEditRevision.current += 1;
+      valueRef.current = operation.text;
+      restoredResourcesRef.current = [...operation.resources];
+      annotationsRef.current = cloneAnnotations(operation.annotations);
+      setValue(operation.text);
+      setRestoredResources(restoredResourcesRef.current);
+      setAnnotations(annotationsRef.current);
+      setError(null);
+      setOptimisticDraftShadow({
+        text: operation.text,
+        resources: restoredResourcesRef.current,
+        annotations: annotationsRef.current,
+        policy: policyRef.current ?? undefined,
+      });
+      replaceOptimisticSends((current) =>
+        current.filter((candidate) => candidate.clientEventId !== clientEventId),
+      );
+    },
+    [draftLoading, hasDraftContent, replaceOptimisticSends, setOptimisticDraftShadow, targetKey],
+  );
+
   const resolveDraftConflict = useCallback(
     async (choice: "keep_mine" | "use_remote"): Promise<void> => {
       const ownedTargetKey = targetKey;
@@ -2595,6 +2800,7 @@ export function useComposer(
   const clearError = useCallback(() => {
     if (targetKeyRef.current !== targetKey) return;
     setError(null);
+    setDraftReadError(null);
     setDraftConflict(null);
   }, [targetKey]);
   // `valueRef` is the synchronous composer authority. React state exists to
@@ -2615,10 +2821,15 @@ export function useComposer(
     removeAnnotation,
     annotationReviewTargetId: identityMatches ? annotationReviewTargetId : null,
     clearAnnotationReviewTarget,
+    requestAnnotationReview,
     hasDraftContent,
     send,
     optimisticMessages: visibleOptimisticMessages,
     retryOptimisticMessage,
+    restoreOptimisticMessage:
+      !draftLoading && !pendingOperationRef.current && !hasDraftContent()
+        ? restoreOptimisticMessage
+        : undefined,
     removeOptimisticMessage,
     steer,
     steering: visibleSteering,
@@ -2661,7 +2872,7 @@ export function useComposer(
     resolveDraftConflict,
     restoredResources: identityMatches ? restoredResources : [],
     removeRestoredResource,
-    error: identityMatches ? error : null,
+    error: identityMatches ? (error ?? draftReadError) : null,
     clearError,
   };
 }
@@ -2740,7 +2951,25 @@ async function replayOutcomeUnknown<T>(command: () => Promise<T>): Promise<T> {
 }
 
 function asError(cause: unknown): Error {
-  return cause instanceof Error ? cause : new Error(String(cause));
+  return normalizeError(cause);
+}
+
+function promptRoutingFromAcceptedEvent(
+  event: SessionEvent | null,
+): "accepted_for_execution" | "queued_for_execution" | "accepted_for_steering" | null {
+  if (
+    typeof event?.payload !== "object" ||
+    event.payload === null ||
+    Array.isArray(event.payload)
+  ) {
+    return null;
+  }
+  const routing = (event.payload as Record<string, unknown>).routing;
+  return routing === "accepted_for_execution" ||
+    routing === "queued_for_execution" ||
+    routing === "accepted_for_steering"
+    ? routing
+    : null;
 }
 
 function isDraftConflictError(error: Error): boolean {