@opengeni/react 0.13.0 → 0.20.0

package/src/hooks/use-composer.ts

@@ -1,38 +1,79 @@
-import type { SendMessageInput } from "@opengeni/sdk";
-import { useCallback, useEffect, useRef, useState } from "react";
-import { useOpenGeni, type ClientOverride } from "../provider";
+import type {
+  ComposerDraft,
+  EffectiveControlResumeOption,
+  EffectiveSessionControl,
+  ResourceRef,
+  SaveComposerDraftRequest,
+  SendMessageInput,
+  SessionEvent,
+} from "@opengeni/sdk";
+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">;
 
-/**
- * Enter appends a prompt; Cmd/Ctrl+Enter steers it to the head and supersedes
- * the current inference.
- */
-export type ComposerMode = "queue" | "steer";
-
-export type UseComposerOptions = ClientOverride & {
-  /** Called with the accepted text after a successful send. */
-  onSent?: ((text: string) => void) | undefined;
-  /**
-   * Extra message fields (resources, tools, model, reasoningEffort) merged
-   * into every send. A function is evaluated at send time so it can read the
-   * surrounding UI state (attachment pickers, model selectors, ...).
-   */
-  sendExtras?: ComposerSendExtras | (() => ComposerSendExtras) | undefined;
-};
+export type UseComposerOptions = EmbeddedSessionClientOverride &
+  SessionEventFeedOptions & {
+    /** Called with the accepted text after a successful send. */
+    onSent?: ((text: string) => void) | undefined;
+    /**
+     * Extra message fields (resources, tools, model, reasoningEffort) merged
+     * into every send. A function is evaluated at send time so it can read the
+     * surrounding UI state (attachment pickers, model selectors, ...).
+     */
+    sendExtras?: ComposerSendExtras | (() => ComposerSendExtras) | undefined;
+    /** Latest server-derived workstream control; bound into Send/Steer OCC. */
+    effectiveControl?: EffectiveSessionControl | null | undefined;
+    /** Apply durable model/tool/reasoning settings in the host's controlled UI. */
+    onDraftApplied?: ((draft: ComposerDraft) => void) | undefined;
+    /**
+     * Opt out of OpenGeni's remote composer-draft reads and writes. Embedded
+     * hosts can use this when their human lane permits messages and controls but
+     * deliberately withholds draft mutation because model/tool policy is
+     * server-owned. The unsent value remains local React state and send/steer
+     * continue to work without a draft revision fence. Queue checkout is hidden
+     * because the current queue-edit contract necessarily creates a durable
+     * composer draft.
+     *
+     * @default "durable"
+     */
+    draftPersistence?: "durable" | "disabled" | undefined;
+  };
 
 export type ComposerState = {
   value: string;
   setValue: (value: string) => void;
-  /** Send the draft (or explicit text). Queue is the default; steer is explicit. */
-  send: (text?: string, mode?: ComposerMode) => Promise<boolean>;
+  /** Append the draft behind prompts already visible in the queue. */
+  send: (text?: string) => Promise<boolean>;
+  /** Supersede current direction with the draft. */
+  steer: (text?: string) => Promise<boolean>;
   sending: boolean;
   canSend: boolean;
   /** Pause the session without deleting its prompt queue. */
   pause: (reason?: string) => Promise<void>;
   pausing: boolean;
   resume: (reason?: string) => Promise<void>;
+  resumeScope: (option: EffectiveControlResumeOption) => Promise<void>;
   resuming: boolean;
+  draft: ComposerDraft | null;
+  draftRevision: number;
+  draftLoading: boolean;
+  draftSaving: boolean;
+  draftConflict: Error | null;
+  /**
+   * Whether this controller owns a durable server-side draft. Custom
+   * controllers that omit the field retain the historical durable behavior.
+   * Queue checkout is unavailable when persistence is disabled because the
+   * current queue-edit contract atomically moves the turn into that draft.
+   */
+  draftPersistence?: "durable" | "disabled" | undefined;
+  /** Apply an atomic queue Edit checkout without a second read. */
+  applyDraft: (draft: ComposerDraft) => void;
+  reloadDraft: () => Promise<void>;
+  resolveDraftConflict: (choice: "keep_mine" | "use_remote") => Promise<void>;
+  restoredResources: ResourceRef[];
+  removeRestoredResource: (index: number) => void;
   error: Error | null;
   clearError: () => void;
 };
@@ -47,41 +88,304 @@ export function useComposer(
   sessionId: string | null | undefined,
   options: UseComposerOptions = {},
 ): ComposerState {
-  const { client, workspaceId } = useOpenGeni(options);
+  const { client, workspaceId, registerSessionReconciler } = useEmbeddedSession(options);
+  const durableDrafts = options.draftPersistence !== "disabled";
+  const targetKey = `${workspaceId}\u0000${sessionId ?? ""}\u0000${durableDrafts ? "durable" : "disabled"}`;
   const [value, setValue] = useState("");
+  const [stateTargetKey, setStateTargetKey] = useState(targetKey);
   const [sending, setSending] = useState(false);
   const [pausing, setPausing] = useState(false);
   const [resuming, setResuming] = useState(false);
   const [error, setError] = useState<Error | null>(null);
+  const [draft, setDraft] = useState<ComposerDraft | null>(null);
+  const [draftLoading, setDraftLoading] = useState(Boolean(sessionId) && durableDrafts);
+  const [draftSaving, setDraftSaving] = useState(false);
+  const [draftConflict, setDraftConflict] = useState<Error | null>(null);
+  const [restoredResources, setRestoredResources] = useState<ResourceRef[]>([]);
   const pendingClientEventId = useRef<string | null>(null);
+  const draftRef = useRef<ComposerDraft | null>(null);
+  const draftLoadErrorRef = useRef<Error | null>(null);
+  const draftReadGeneration = useRef(0);
+  const localEditRevision = useRef(0);
+  const targetGeneration = useRef(0);
+  const lastSavedSignature = useRef<string | null>(null);
+  const saveChain = useRef<Promise<void>>(Promise.resolve());
   const onSent = options.onSent;
+  const onDraftApplied = options.onDraftApplied;
   // Read through a ref so a new extras closure (created every render by
   // callers passing inline functions) does not invalidate `send`.
   const sendExtrasRef = useRef(options.sendExtras);
-  sendExtrasRef.current = options.sendExtras;
+  useLayoutEffect(() => {
+    sendExtrasRef.current = options.sendExtras;
+  }, [options.sendExtras]);
+  const liveExtras = resolveSendExtras(options.sendExtras);
+  const liveExtrasVersion = JSON.stringify(liveExtras);
 
   // A composer is bound to one session: switching targets must not leak the
-  // previous session's draft, error, or retry idempotency key.
-  const targetKey = `${workspaceId}\u0000${sessionId ?? ""}`;
+  // previous session's draft, error, or retry idempotency key. Revoke the old
+  // target only when the new render commits: a suspended transition must leave
+  // the still-visible composer fully interactive.
   const targetKeyRef = useRef(targetKey);
-  useEffect(() => {
-    if (targetKeyRef.current !== targetKey) {
-      targetKeyRef.current = targetKey;
+  useLayoutEffect(() => {
+    if (targetKeyRef.current === targetKey) return;
+    targetKeyRef.current = targetKey;
+    targetGeneration.current += 1;
+    pendingClientEventId.current = null;
+    localEditRevision.current = 0;
+    draftReadGeneration.current += 1;
+    draftRef.current = null;
+    draftLoadErrorRef.current = null;
+    lastSavedSignature.current = null;
+    // An unresolved save for the old target must neither block nor join the
+    // new target's autosave chain. Its own generation fence drops settlement.
+    saveChain.current = Promise.resolve();
+    setStateTargetKey(targetKey);
+    setValue("");
+    setSending(false);
+    setPausing(false);
+    setResuming(false);
+    setError(null);
+    setDraft(null);
+    setDraftLoading(Boolean(sessionId) && durableDrafts);
+    setDraftSaving(false);
+    setDraftConflict(null);
+    setRestoredResources([]);
+  }, [durableDrafts, sessionId, targetKey]);
+
+  const applyDraft = useCallback(
+    (next: ComposerDraft): void => {
+      if (targetKeyRef.current !== targetKey) return;
+      if (!durableDrafts) {
+        pendingClientEventId.current = null;
+        localEditRevision.current += 1;
+        draftRef.current = null;
+        lastSavedSignature.current = null;
+        setDraft(null);
+        setValue(next.text);
+        setRestoredResources(next.resources);
+        setDraftConflict(null);
+        return;
+      }
+      draftRef.current = next;
+      lastSavedSignature.current = draftSignature(draftPayload(next));
+      localEditRevision.current += 1;
       pendingClientEventId.current = null;
-      setValue("");
-      setError(null);
+      setDraft(next);
+      setValue(next.text);
+      setRestoredResources(next.resources);
+      setDraftConflict(null);
+      onDraftApplied?.(next);
+    },
+    [durableDrafts, onDraftApplied, targetKey],
+  );
+
+  const loadDraft = useCallback(
+    async (replaceLocal: boolean, rejectOnFailure = false): Promise<void> => {
+      if (targetKeyRef.current !== targetKey) return;
+      if (!sessionId || !durableDrafts) {
+        setDraftLoading(false);
+        return;
+      }
+      const generation = targetGeneration.current;
+      const readTicket = ++draftReadGeneration.current;
+      const localAtStart = localEditRevision.current;
+      setDraftLoading(true);
+      try {
+        const fetched = await client.getComposerDraft(workspaceId, sessionId);
+        if (generation !== targetGeneration.current || targetKeyRef.current !== targetKey) {
+          return;
+        }
+        const ownsLatestRead = readTicket === draftReadGeneration.current;
+        const currentRevision = draftRef.current?.revision ?? -1;
+        if ((ownsLatestRead || rejectOnFailure) && fetched.revision >= currentRevision) {
+          draftRef.current = fetched;
+          setDraft(fetched);
+          setDraftConflict(null);
+          if (replaceLocal || localAtStart === localEditRevision.current) {
+            lastSavedSignature.current = draftSignature(draftPayload(fetched));
+            setValue(fetched.text);
+            setRestoredResources(fetched.resources);
+            onDraftApplied?.(fetched);
+          }
+        }
+        const authoritativeRevision = draftRef.current?.revision ?? -1;
+        if (rejectOnFailure && authoritativeRevision < fetched.revision) {
+          throw new TypeError("Composer draft reconciliation did not commit authoritative state");
+        }
+        if (ownsLatestRead || rejectOnFailure) {
+          const recoveredError = draftLoadErrorRef.current;
+          draftLoadErrorRef.current = null;
+          if (recoveredError) {
+            setError((current) => (current === recoveredError ? null : current));
+          }
+        }
+      } catch (cause) {
+        if (
+          generation === targetGeneration.current &&
+          targetKeyRef.current === targetKey &&
+          (readTicket === draftReadGeneration.current || rejectOnFailure)
+        ) {
+          const failure = asError(cause);
+          draftLoadErrorRef.current = failure;
+          setError(failure);
+        }
+        if (rejectOnFailure) throw cause;
+      } finally {
+        if (
+          generation === targetGeneration.current &&
+          targetKeyRef.current === targetKey &&
+          readTicket === draftReadGeneration.current
+        ) {
+          setDraftLoading(false);
+        }
+      }
+    },
+    [client, durableDrafts, onDraftApplied, sessionId, targetKey, workspaceId],
+  );
+
+  useEffect(() => {
+    if (!sessionId || !durableDrafts) {
+      setDraftLoading(false);
+      return;
     }
-  }, [targetKey]);
+    void loadDraft(false);
+  }, [durableDrafts, loadDraft, sessionId]);
+  useEffect(() => {
+    if (!sessionId || !durableDrafts) return;
+    return registerSessionReconciler(sessionId, "composer", async () => await loadDraft(false));
+  }, [durableDrafts, loadDraft, registerSessionReconciler, sessionId]);
+  useSessionEventTrigger(
+    client,
+    workspaceId,
+    sessionId,
+    isComposerDraftEvent,
+    () => void loadDraft(false),
+    {
+      enabled: Boolean(sessionId) && durableDrafts,
+      ...(options.events !== undefined ? { events: options.events } : {}),
+    },
+    async () => await loadDraft(false, true),
+  );
 
-  const send = useCallback(
-    async (explicit?: string, delivery: ComposerMode = "queue"): Promise<boolean> => {
+  const currentDraftPayload = useCallback((): SaveComposerDraftRequest | null => {
+    if (targetKeyRef.current !== targetKey) return null;
+    const base = draftRef.current;
+    if (!base) return null;
+    const extras = resolveSendExtras(sendExtrasRef.current);
+    return {
+      expectedRevision: base.revision,
+      text: value,
+      resources: mergeResources(restoredResources, extras.resources ?? []),
+      tools: extras.tools ?? base.tools,
+      model: extras.model ?? base.model,
+      reasoningEffort: extras.reasoningEffort ?? base.reasoningEffort,
+    };
+  }, [restoredResources, targetKey, value]);
+
+  const persistPayload = useCallback(
+    async (payload: SaveComposerDraftRequest): Promise<boolean> => {
+      const ownedTargetKey = targetKey;
+      const ownedGeneration = targetGeneration.current;
+      if (!sessionId || targetKeyRef.current !== ownedTargetKey) return false;
+      let success = false;
+      const run = async () => {
+        if (
+          targetKeyRef.current !== ownedTargetKey ||
+          targetGeneration.current !== ownedGeneration
+        ) {
+          return;
+        }
+        const current = draftRef.current;
+        if (!current) return;
+        const request = { ...payload, expectedRevision: current.revision };
+        const signature = draftSignature(request);
+        if (signature === lastSavedSignature.current) {
+          success = true;
+          return;
+        }
+        setDraftSaving(true);
+        try {
+          const saved = await client.saveComposerDraft(workspaceId, sessionId, request);
+          if (
+            targetKeyRef.current !== ownedTargetKey ||
+            targetGeneration.current !== ownedGeneration
+          ) {
+            return;
+          }
+          draftRef.current = saved;
+          setDraft(saved);
+          lastSavedSignature.current = signature;
+          setDraftConflict(null);
+          success = true;
+        } catch (cause) {
+          if (
+            targetKeyRef.current === ownedTargetKey &&
+            targetGeneration.current === ownedGeneration
+          ) {
+            const problem = asError(cause);
+            setDraftConflict(problem);
+            setError(problem);
+          }
+        } finally {
+          if (
+            targetKeyRef.current === ownedTargetKey &&
+            targetGeneration.current === ownedGeneration
+          ) {
+            setDraftSaving(false);
+          }
+        }
+      };
+      saveChain.current = saveChain.current.then(run, run);
+      await saveChain.current;
+      return success;
+    },
+    [client, sessionId, targetKey, workspaceId],
+  );
+
+  // Private durable autosave. A newer local edit is never replaced by an older
+  // response; saves serialize and each reads the latest acknowledged revision.
+  useEffect(() => {
+    if (
+      !durableDrafts ||
+      !sessionId ||
+      draftLoading ||
+      sending ||
+      !draftRef.current ||
+      draftConflict
+    )
+      return;
+    const payload = currentDraftPayload();
+    if (!payload || draftSignature(payload) === lastSavedSignature.current) return;
+    const timer = window.setTimeout(() => void persistPayload(payload), 500);
+    return () => window.clearTimeout(timer);
+  }, [
+    currentDraftPayload,
+    durableDrafts,
+    draftConflict,
+    draftLoading,
+    liveExtrasVersion,
+    persistPayload,
+    sending,
+    sessionId,
+  ]);
+
+  const dispatch = useCallback(
+    async (delivery: "send" | "steer", explicit?: string): Promise<boolean> => {
+      const ownedTargetKey = targetKey;
+      const ownedGeneration = targetGeneration.current;
       const draftAtSend = value;
-      const text = (explicit ?? draftAtSend).trim();
+      const rawText = explicit ?? draftAtSend;
+      const hasText = rawText.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 = resolveSendExtras(sendExtrasRef.current);
-      const hasResources = (extras.resources?.length ?? 0) > 0;
-      if ((!text && !hasResources) || !sessionId || sending) {
+      const hasResources = restoredResources.length > 0 || (extras.resources?.length ?? 0) > 0;
+      if (
+        (!hasText && !hasResources) ||
+        !sessionId ||
+        sending ||
+        targetKeyRef.current !== ownedTargetKey
+      ) {
         return false;
       }
       // Reuse the clientEventId across retries of the same draft so a
@@ -90,17 +394,56 @@ export function useComposer(
       setSending(true);
       setError(null);
       try {
-        // The wire contract requires non-empty text (z.string().min(1)) and the
-        // worker rejects whitespace-only text; a file-only message therefore
-        // carries a minimal default so the attachments still get delivered.
-        const sendText = text || FILE_ONLY_MESSAGE_TEXT;
-        const input = composeSendInput(sendText, pendingClientEventId.current, extras);
+        // Trimming is only an emptiness check. A non-blank prompt must be sent
+        // byte-for-byte as the user wrote it, because expectedDraftRevision
+        // binds the submission to that exact durable draft. File-only messages
+        // use the same non-blank placeholder in both the saved draft and the
+        // submitted prompt so the content fence cannot reject its own client.
+        const sendText = hasText ? rawText : FILE_ONLY_MESSAGE_TEXT;
+        const currentPayload = currentDraftPayload();
+        const payload = currentPayload ? { ...currentPayload, text: sendText } : null;
+        if (payload && !(await persistPayload(payload))) return false;
+        if (
+          targetKeyRef.current !== ownedTargetKey ||
+          targetGeneration.current !== ownedGeneration
+        ) {
+          return false;
+        }
+        const input = composeSendInput(sendText, pendingClientEventId.current, extras, {
+          ...(options.effectiveControl?.controlEtag
+            ? { controlEtag: options.effectiveControl.controlEtag }
+            : {}),
+          ...(draftRef.current ? { expectedDraftRevision: draftRef.current.revision } : {}),
+          resources: mergeResources(restoredResources, extras.resources ?? []),
+        });
         if (delivery === "steer") {
           await client.steerMessage(workspaceId, sessionId, input);
         } else {
           await client.sendMessage(workspaceId, sessionId, input);
         }
+        if (
+          targetKeyRef.current !== ownedTargetKey ||
+          targetGeneration.current !== ownedGeneration
+        ) {
+          return false;
+        }
         pendingClientEventId.current = null;
+        const previousDraft = draftRef.current;
+        if (previousDraft) {
+          const cleared = {
+            ...previousDraft,
+            revision: 0,
+            text: "",
+            resources: [],
+            sourceTurnId: null,
+            sourceTurnVersion: null,
+            updatedAt: null,
+          };
+          draftRef.current = cleared;
+          setDraft(cleared);
+          setRestoredResources([]);
+          lastSavedSignature.current = draftSignature(draftPayload(cleared));
+        }
         if (explicit === undefined) {
           // Clear only the draft that was sent: edits made while the request
           // was in flight were never delivered and must survive.
@@ -109,76 +452,267 @@ export function useComposer(
         onSent?.(sendText);
         return true;
       } catch (cause) {
-        setError(cause instanceof Error ? cause : new Error(String(cause)));
+        if (
+          targetKeyRef.current === ownedTargetKey &&
+          targetGeneration.current === ownedGeneration
+        ) {
+          setError(cause instanceof Error ? cause : new Error(String(cause)));
+        }
         return false;
       } finally {
-        setSending(false);
+        if (
+          targetKeyRef.current === ownedTargetKey &&
+          targetGeneration.current === ownedGeneration
+        ) {
+          setSending(false);
+        }
       }
     },
-    [client, workspaceId, sessionId, value, sending, onSent],
+    [
+      client,
+      currentDraftPayload,
+      onSent,
+      options.effectiveControl?.controlEtag,
+      persistPayload,
+      restoredResources,
+      sending,
+      sessionId,
+      targetKey,
+      value,
+      workspaceId,
+    ],
   );
 
+  const send = useCallback(async (text?: string) => await dispatch("send", text), [dispatch]);
+  const steer = useCallback(async (text?: string) => await dispatch("steer", text), [dispatch]);
+
   // 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
   // affordance the moment a file is ready. ChatComposer additionally gates this
   // on its `attachments.uploading` flag so a message never departs mid-upload.
-  const hasReadyResources = (resolveSendExtras(sendExtrasRef.current).resources?.length ?? 0) > 0;
+  const hasReadyResources = restoredResources.length > 0 || (liveExtras.resources?.length ?? 0) > 0;
 
   const pause = useCallback(
     async (reason?: string): Promise<void> => {
-      if (!sessionId || pausing) {
+      const ownedTargetKey = targetKey;
+      const ownedGeneration = targetGeneration.current;
+      if (!sessionId || pausing || targetKeyRef.current !== ownedTargetKey) {
         return;
       }
       setPausing(true);
       setError(null);
       try {
-        await client.pauseSession(workspaceId, sessionId, reason !== undefined ? { reason } : {});
+        await client.pauseSession(workspaceId, sessionId, {
+          ...(reason !== undefined ? { reason } : {}),
+          ...(options.effectiveControl?.controlEtag
+            ? { expectedControlEtag: options.effectiveControl.controlEtag }
+            : {}),
+        });
       } catch (cause) {
-        setError(cause instanceof Error ? cause : new Error(String(cause)));
+        if (
+          targetKeyRef.current === ownedTargetKey &&
+          targetGeneration.current === ownedGeneration
+        ) {
+          setError(cause instanceof Error ? cause : new Error(String(cause)));
+        }
       } finally {
-        setPausing(false);
+        if (
+          targetKeyRef.current === ownedTargetKey &&
+          targetGeneration.current === ownedGeneration
+        ) {
+          setPausing(false);
+        }
       }
     },
-    [client, workspaceId, sessionId, pausing],
+    [client, workspaceId, sessionId, pausing, options.effectiveControl?.controlEtag, targetKey],
   );
 
   const resume = useCallback(
     async (reason?: string): Promise<void> => {
-      if (!sessionId || resuming) return;
+      const ownedTargetKey = targetKey;
+      const ownedGeneration = targetGeneration.current;
+      if (!sessionId || resuming || targetKeyRef.current !== ownedTargetKey) return;
       setResuming(true);
       setError(null);
       try {
-        await client.resumeSession(workspaceId, sessionId, reason !== undefined ? { reason } : {});
+        await client.resumeSession(workspaceId, sessionId, {
+          ...(reason !== undefined ? { reason } : {}),
+          ...(options.effectiveControl?.controlEtag
+            ? { expectedControlEtag: options.effectiveControl.controlEtag }
+            : {}),
+        });
       } catch (cause) {
-        setError(cause instanceof Error ? cause : new Error(String(cause)));
+        if (
+          targetKeyRef.current === ownedTargetKey &&
+          targetGeneration.current === ownedGeneration
+        ) {
+          setError(cause instanceof Error ? cause : new Error(String(cause)));
+        }
       } finally {
-        setResuming(false);
+        if (
+          targetKeyRef.current === ownedTargetKey &&
+          targetGeneration.current === ownedGeneration
+        ) {
+          setResuming(false);
+        }
       }
     },
-    [client, workspaceId, sessionId, resuming],
+    [client, workspaceId, sessionId, resuming, options.effectiveControl?.controlEtag, targetKey],
   );
 
-  const updateValue = useCallback((next: string) => {
-    pendingClientEventId.current = null;
-    setValue(next);
-  }, []);
+  const resumeScope = useCallback(
+    async (option: EffectiveControlResumeOption): Promise<void> => {
+      const ownedTargetKey = targetKey;
+      const ownedGeneration = targetGeneration.current;
+      if (!sessionId || resuming || targetKeyRef.current !== ownedTargetKey) return;
+      setResuming(true);
+      setError(null);
+      try {
+        if (option.scope === "workspace") {
+          if (!client.setWorkspaceInferenceState) {
+            throw new Error("Workspace-level resume is not available through this client");
+          }
+          const workspaceBlocker = options.effectiveControl?.blockers.find(
+            (blocker) => blocker.kind === "workspace",
+          );
+          await client.setWorkspaceInferenceState(workspaceId, {
+            action: "resume",
+            clientEventId: generateClientEventId(),
+            ...(workspaceBlocker ? { expectedRevision: workspaceBlocker.revision } : {}),
+          });
+        } else if (option.scope === "session" && option.targetId) {
+          const target = await client.getQueue(workspaceId, option.targetId);
+          if (
+            targetKeyRef.current !== ownedTargetKey ||
+            targetGeneration.current !== ownedGeneration
+          ) {
+            return;
+          }
+          await client.resumeSession(workspaceId, option.targetId, {
+            expectedControlEtag: target.effectiveControl.controlEtag,
+          });
+        } else {
+          await client.resumeSession(workspaceId, sessionId, {
+            ...(options.effectiveControl?.controlEtag
+              ? { expectedControlEtag: options.effectiveControl.controlEtag }
+              : {}),
+          });
+        }
+      } catch (cause) {
+        if (
+          targetKeyRef.current === ownedTargetKey &&
+          targetGeneration.current === ownedGeneration
+        ) {
+          setError(asError(cause));
+        }
+      } finally {
+        if (
+          targetKeyRef.current === ownedTargetKey &&
+          targetGeneration.current === ownedGeneration
+        ) {
+          setResuming(false);
+        }
+      }
+    },
+    [client, options.effectiveControl, resuming, sessionId, targetKey, workspaceId],
+  );
+
+  const updateValue = useCallback(
+    (next: string) => {
+      if (targetKeyRef.current !== targetKey) return;
+      pendingClientEventId.current = null;
+      localEditRevision.current += 1;
+      setValue(next);
+    },
+    [targetKey],
+  );
+
+  const removeRestoredResource = useCallback(
+    (index: number) => {
+      if (targetKeyRef.current !== targetKey) return;
+      localEditRevision.current += 1;
+      setRestoredResources((current) => current.filter((_, candidate) => candidate !== index));
+    },
+    [targetKey],
+  );
+
+  const resolveDraftConflict = useCallback(
+    async (choice: "keep_mine" | "use_remote"): Promise<void> => {
+      const ownedTargetKey = targetKey;
+      const ownedGeneration = targetGeneration.current;
+      if (!sessionId || !durableDrafts || targetKeyRef.current !== ownedTargetKey) return;
+      const remote = await client.getComposerDraft(workspaceId, sessionId);
+      if (targetKeyRef.current !== ownedTargetKey || targetGeneration.current !== ownedGeneration) {
+        return;
+      }
+      if (choice === "use_remote") {
+        applyDraft(remote);
+        return;
+      }
+      draftRef.current = remote;
+      setDraft(remote);
+      setDraftConflict(null);
+      const payload = currentDraftPayload();
+      if (payload) await persistPayload({ ...payload, expectedRevision: remote.revision });
+    },
+    [
+      applyDraft,
+      client,
+      currentDraftPayload,
+      durableDrafts,
+      persistPayload,
+      sessionId,
+      targetKey,
+      workspaceId,
+    ],
+  );
+
+  const identityMatches = stateTargetKey === targetKey;
+  const reloadDraft = useCallback(async () => await loadDraft(true), [loadDraft]);
+  const clearError = useCallback(() => {
+    if (targetKeyRef.current !== targetKey) return;
+    setError(null);
+    setDraftConflict(null);
+  }, [targetKey]);
 
   return {
-    value,
+    value: identityMatches ? value : "",
     setValue: updateValue,
     send,
-    sending,
-    canSend: Boolean(sessionId) && !sending && (value.trim().length > 0 || hasReadyResources),
+    steer,
+    sending: identityMatches ? sending : false,
+    canSend:
+      identityMatches &&
+      Boolean(sessionId) &&
+      !sending &&
+      (value.trim().length > 0 || hasReadyResources),
     pause,
-    pausing,
+    pausing: identityMatches ? pausing : false,
     resume,
-    resuming,
-    error,
-    clearError: useCallback(() => setError(null), []),
+    resumeScope,
+    resuming: identityMatches ? resuming : false,
+    draft: identityMatches ? draft : null,
+    draftRevision: identityMatches ? (draft?.revision ?? 0) : 0,
+    draftLoading: identityMatches ? draftLoading : Boolean(sessionId) && durableDrafts,
+    draftSaving: identityMatches ? draftSaving : false,
+    draftConflict: identityMatches ? draftConflict : null,
+    draftPersistence: durableDrafts ? "durable" : "disabled",
+    applyDraft,
+    reloadDraft,
+    resolveDraftConflict,
+    restoredResources: identityMatches ? restoredResources : [],
+    removeRestoredResource,
+    error: identityMatches ? error : null,
+    clearError,
   };
 }
 
+/** Events that can atomically replace or clear this subject's durable draft. */
+export function isComposerDraftEvent(event: Pick<SessionEvent, "type">): boolean {
+  return event.type === "user.message" || event.type === "session.queue.changed";
+}
+
 /**
  * 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
@@ -202,8 +736,9 @@ export function composeSendInput(
   text: string,
   clientEventId: string,
   extras: ComposerSendExtras | (() => ComposerSendExtras) | undefined,
+  bound: Partial<SendMessageInput> = {},
 ): SendMessageInput {
-  return { ...resolveSendExtras(extras), text, clientEventId };
+  return { ...resolveSendExtras(extras), ...bound, text, clientEventId };
 }
 
 /** Submit on plain Enter; Shift+Enter inserts a newline. Exported for tests. */
@@ -221,14 +756,40 @@ export function shouldSubmitOnKey(event: {
 }
 
 /** Cmd/Ctrl+Enter steers; ordinary Enter appends to the queue. */
-export function composerModeForKey(event: { metaKey?: boolean; ctrlKey?: boolean }): ComposerMode {
-  return event.metaKey || event.ctrlKey ? "steer" : "queue";
+export function shouldSteerOnKey(event: { metaKey?: boolean; ctrlKey?: boolean }): boolean {
+  return event.metaKey === true || event.ctrlKey === true;
 }
 
 function generateClientEventId(): string {
-  const cryptoApi = globalThis.crypto;
-  if (cryptoApi && "randomUUID" in cryptoApi) {
-    return cryptoApi.randomUUID();
-  }
-  return `ce-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+  return globalThis.crypto.randomUUID();
+}
+
+function asError(cause: unknown): Error {
+  return cause instanceof Error ? cause : new Error(String(cause));
+}
+
+function draftPayload(draft: ComposerDraft): SaveComposerDraftRequest {
+  return {
+    expectedRevision: draft.revision,
+    text: draft.text,
+    resources: draft.resources,
+    tools: draft.tools,
+    model: draft.model,
+    reasoningEffort: draft.reasoningEffort,
+  };
+}
+
+function draftSignature(payload: SaveComposerDraftRequest): string {
+  const { expectedRevision: _revision, ...content } = payload;
+  return JSON.stringify(content);
+}
+
+function mergeResources(base: ResourceRef[], additions: ResourceRef[]): ResourceRef[] {
+  const seen = new Set<string>();
+  return [...base, ...additions].filter((resource) => {
+    const key = JSON.stringify(resource);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
 }