@opengeni/react 0.13.0 → 0.15.0

package/src/hooks/use-composer.ts

@@ -1,38 +1,60 @@
-import type { SendMessageInput } from "@opengeni/sdk";
+import type {
+  ComposerDraft,
+  EffectiveControlResumeOption,
+  EffectiveSessionControl,
+  ResourceRef,
+  SaveComposerDraftRequest,
+  SendMessageInput,
+  SessionEvent,
+} from "@opengeni/sdk";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { useOpenGeni, type ClientOverride } from "../provider";
+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 = ClientOverride &
+  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;
+  };
 
 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;
+  /** 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,18 +69,30 @@ export function useComposer(
   sessionId: string | null | undefined,
   options: UseComposerOptions = {},
 ): ComposerState {
-  const { client, workspaceId } = useOpenGeni(options);
+  const { client, workspaceId, registerSessionReconciler } = useOpenGeni(options);
   const [value, setValue] = useState("");
   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));
+  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 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;
+  const liveExtrasVersion = JSON.stringify(resolveSendExtras(options.sendExtras));
 
   // A composer is bound to one session: switching targets must not leak the
   // previous session's draft, error, or retry idempotency key.
@@ -67,20 +101,160 @@ export function useComposer(
   useEffect(() => {
     if (targetKeyRef.current !== targetKey) {
       targetKeyRef.current = targetKey;
+      targetGeneration.current += 1;
       pendingClientEventId.current = null;
+      localEditRevision.current = 0;
+      draftRef.current = null;
+      lastSavedSignature.current = null;
       setValue("");
       setError(null);
+      setDraft(null);
+      setDraftConflict(null);
+      setRestoredResources([]);
     }
   }, [targetKey]);
 
-  const send = useCallback(
-    async (explicit?: string, delivery: ComposerMode = "queue"): Promise<boolean> => {
+  const applyDraft = useCallback(
+    (next: ComposerDraft): void => {
+      draftRef.current = next;
+      lastSavedSignature.current = draftSignature(draftPayload(next));
+      localEditRevision.current += 1;
+      pendingClientEventId.current = null;
+      setDraft(next);
+      setValue(next.text);
+      setRestoredResources(next.resources);
+      setDraftConflict(null);
+      onDraftApplied?.(next);
+    },
+    [onDraftApplied],
+  );
+
+  const loadDraft = useCallback(
+    async (replaceLocal: boolean): Promise<void> => {
+      if (!sessionId) return;
+      const generation = targetGeneration.current;
+      const localAtStart = localEditRevision.current;
+      setDraftLoading(true);
+      try {
+        const fetched = await client.getComposerDraft(workspaceId, sessionId);
+        if (generation !== targetGeneration.current) return;
+        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);
+        }
+      } catch (cause) {
+        if (generation === targetGeneration.current) setError(asError(cause));
+      } finally {
+        if (generation === targetGeneration.current) setDraftLoading(false);
+      }
+    },
+    [client, onDraftApplied, sessionId, workspaceId],
+  );
+
+  useEffect(() => {
+    if (!sessionId) {
+      setDraftLoading(false);
+      return;
+    }
+    void loadDraft(false);
+  }, [loadDraft, sessionId]);
+  useEffect(() => {
+    if (!sessionId) return;
+    return registerSessionReconciler(sessionId, "composer", async () => await loadDraft(false));
+  }, [loadDraft, registerSessionReconciler, sessionId]);
+  useSessionEventTrigger(
+    client,
+    workspaceId,
+    sessionId,
+    isComposerDraftEvent,
+    () => void loadDraft(false),
+    {
+      enabled: Boolean(sessionId),
+      ...(options.events !== undefined ? { events: options.events } : {}),
+    },
+  );
+
+  const currentDraftPayload = useCallback((): SaveComposerDraftRequest | 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, value]);
+
+  const persistPayload = useCallback(
+    async (payload: SaveComposerDraftRequest): Promise<boolean> => {
+      if (!sessionId) return false;
+      let success = false;
+      const run = async () => {
+        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);
+          draftRef.current = saved;
+          setDraft(saved);
+          lastSavedSignature.current = signature;
+          setDraftConflict(null);
+          success = true;
+        } catch (cause) {
+          const problem = asError(cause);
+          setDraftConflict(problem);
+          setError(problem);
+        } finally {
+          setDraftSaving(false);
+        }
+      };
+      saveChain.current = saveChain.current.then(run, run);
+      await saveChain.current;
+      return success;
+    },
+    [client, sessionId, 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 (!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,
+    draftConflict,
+    draftLoading,
+    liveExtrasVersion,
+    persistPayload,
+    sending,
+    sessionId,
+  ]);
+
+  const dispatch = useCallback(
+    async (delivery: "send" | "steer", explicit?: string): Promise<boolean> => {
       const draftAtSend = value;
       const text = (explicit ?? draftAtSend).trim();
       // 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;
+      const hasResources = restoredResources.length > 0 || (extras.resources?.length ?? 0) > 0;
       if ((!text && !hasResources) || !sessionId || sending) {
         return false;
       }
@@ -90,17 +264,41 @@ export function useComposer(
       setSending(true);
       setError(null);
       try {
+        const payload = currentDraftPayload();
+        if (payload && !(await persistPayload(payload))) return false;
         // 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);
+        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);
         }
         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.
@@ -115,15 +313,31 @@ export function useComposer(
         setSending(false);
       }
     },
-    [client, workspaceId, sessionId, value, sending, onSent],
+    [
+      client,
+      currentDraftPayload,
+      onSent,
+      options.effectiveControl?.controlEtag,
+      persistPayload,
+      restoredResources,
+      sending,
+      sessionId,
+      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 ||
+    (resolveSendExtras(sendExtrasRef.current).resources?.length ?? 0) > 0;
 
   const pause = useCallback(
     async (reason?: string): Promise<void> => {
@@ -133,14 +347,19 @@ export function useComposer(
       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)));
       } finally {
         setPausing(false);
       }
     },
-    [client, workspaceId, sessionId, pausing],
+    [client, workspaceId, sessionId, pausing, options.effectiveControl?.controlEtag],
   );
 
   const resume = useCallback(
@@ -149,36 +368,120 @@ export function useComposer(
       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)));
       } finally {
         setResuming(false);
       }
     },
-    [client, workspaceId, sessionId, resuming],
+    [client, workspaceId, sessionId, resuming, options.effectiveControl?.controlEtag],
+  );
+
+  const resumeScope = useCallback(
+    async (option: EffectiveControlResumeOption): Promise<void> => {
+      if (!sessionId || resuming) return;
+      setResuming(true);
+      setError(null);
+      try {
+        if (option.scope === "workspace") {
+          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);
+          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) {
+        setError(asError(cause));
+      } finally {
+        setResuming(false);
+      }
+    },
+    [client, options.effectiveControl, resuming, sessionId, workspaceId],
   );
 
   const updateValue = useCallback((next: string) => {
     pendingClientEventId.current = null;
+    localEditRevision.current += 1;
     setValue(next);
   }, []);
 
+  const removeRestoredResource = useCallback((index: number) => {
+    localEditRevision.current += 1;
+    setRestoredResources((current) => current.filter((_, candidate) => candidate !== index));
+  }, []);
+
+  const resolveDraftConflict = useCallback(
+    async (choice: "keep_mine" | "use_remote"): Promise<void> => {
+      if (!sessionId) return;
+      const remote = await client.getComposerDraft(workspaceId, sessionId);
+      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, persistPayload, sessionId, workspaceId],
+  );
+
   return {
     value,
     setValue: updateValue,
     send,
+    steer,
     sending,
     canSend: Boolean(sessionId) && !sending && (value.trim().length > 0 || hasReadyResources),
     pause,
     pausing,
     resume,
+    resumeScope,
     resuming,
+    draft,
+    draftRevision: draft?.revision ?? 0,
+    draftLoading,
+    draftSaving,
+    draftConflict,
+    applyDraft,
+    reloadDraft: useCallback(async () => await loadDraft(true), [loadDraft]),
+    resolveDraftConflict,
+    restoredResources,
+    removeRestoredResource,
     error,
-    clearError: useCallback(() => setError(null), []),
+    clearError: useCallback(() => {
+      setError(null);
+      setDraftConflict(null);
+    }, []),
   };
 }
 
+/** 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 +505,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 +525,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;
+  });
 }

package/src/hooks/use-session-control.ts

@@ -1,4 +1,4 @@
-import type { SessionEvent } from "@opengeni/sdk";
+import type { SessionControlResponse, SessionEvent } from "@opengeni/sdk";
 import { useCallback } from "react";
 import { useOpenGeni, type ClientOverride } from "../provider";
 import { useMutationRunner } from "./internal";
@@ -6,8 +6,8 @@ import { useMutationRunner } from "./internal";
 export type UseSessionControlOptions = ClientOverride;
 
 export type UseSessionControlResult = {
-  pause: (reason?: string) => Promise<SessionEvent | null>;
-  resume: (reason?: string) => Promise<SessionEvent | null>;
+  pause: (reason?: string) => Promise<SessionControlResponse | null>;
+  resume: (reason?: string) => Promise<SessionControlResponse | null>;
   controlling: boolean;
   /** Approve a pending `requires_action` approval. */
   approve: (approvalId: string, message?: string) => Promise<SessionEvent | null>;
@@ -43,7 +43,7 @@ export function useSessionControl(
   } = useMutationRunner();
 
   const pause = useCallback(
-    async (reason?: string): Promise<SessionEvent | null> => {
+    async (reason?: string): Promise<SessionControlResponse | null> => {
       if (!sessionId) {
         return null;
       }
@@ -55,12 +55,11 @@ export function useSessionControl(
   );
 
   const resume = useCallback(
-    async (reason?: string): Promise<SessionEvent | null> => {
+    async (reason?: string): Promise<SessionControlResponse | null> => {
       if (!sessionId) return null;
-      const result = await runControl(() =>
+      return await runControl(() =>
         client.resumeSession(workspaceId, sessionId, reason !== undefined ? { reason } : {}),
       );
-      return result?.event ?? null;
     },
     [client, workspaceId, sessionId, runControl],
   );

package/src/hooks/use-session-events.ts

@@ -58,7 +58,7 @@ export function useSessionEvents(
   sessionId: string | null | undefined,
   options: UseSessionEventsOptions = {},
 ): UseSessionEventsResult {
-  const { client, workspaceId } = useOpenGeni(options);
+  const { client, workspaceId, reconcileSession } = useOpenGeni(options);
   const enabled = options.enabled ?? true;
   const after = options.after ?? 0;
   const replay = options.replay ?? "windowed";
@@ -160,6 +160,7 @@ export function useSessionEvents(
         const stream = client.streamEvents(workspaceId, sessionId, {
           after: lastSequenceRef.current,
           signal: controller.signal,
+          beforeLive: async () => await reconcileSession(sessionId),
           onStateChange: (state) => {
             if (!controller.signal.aborted) {
               setConnectionState(state);
@@ -189,7 +190,7 @@ export function useSessionEvents(
         clearTimeout(flushTimer);
       }
     };
-  }, [client, workspaceId, sessionId, after, enabled, fullReplay, streamKey]);
+  }, [client, workspaceId, sessionId, after, enabled, fullReplay, streamKey, reconcileSession]);
 
   const loadOlder = useCallback(async (): Promise<boolean> => {
     if (!sessionId || fullReplay || loadingOlderRef.current || !hasOlderRef.current) {

package/src/hooks/use-session-lineage.ts

@@ -57,7 +57,8 @@ export function useSessionLineage(
   sessionId: string | null | undefined,
   options: UseSessionLineageOptions = {},
 ): UseSessionLineageResult {
-  const { client, workspaceId } = useOpenGeni(options);
+  const { client, workspaceId, workspaceControlEvent, registerSessionReconciler } =
+    useOpenGeni(options);
   const enabled = (options.enabled ?? true) && Boolean(sessionId);
   const load = useCallback(
     async () =>
@@ -67,7 +68,15 @@ export function useSessionLineage(
     [client, workspaceId, sessionId],
   );
   const state = usePolledValue(load, { pollIntervalMs: options.pollIntervalMs, enabled });
-  const refreshSoon = useDebouncedCallback(() => void state.refresh(), 150);
+  const refresh = state.refresh;
+  useEffect(() => {
+    if (enabled && workspaceControlEvent) void refresh();
+  }, [enabled, refresh, workspaceControlEvent]);
+  useEffect(() => {
+    if (!sessionId || !enabled) return;
+    return registerSessionReconciler(sessionId, "lineage", refresh);
+  }, [enabled, refresh, registerSessionReconciler, sessionId]);
+  const refreshSoon = useDebouncedCallback(() => void refresh(), 150);
   const delayedChildRefreshRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   // Clear a pending delayed refresh on session/workspace SWITCH (not just
   // unmount): otherwise a timer scheduled for the previous session can fire
@@ -81,15 +90,15 @@ export function useSessionLineage(
     };
   }, [sessionId, workspaceId]);
   const refreshAfterChildCreate = useCallback(() => {
-    void state.refresh();
+    void refresh();
     if (delayedChildRefreshRef.current !== null) {
       clearTimeout(delayedChildRefreshRef.current);
     }
     delayedChildRefreshRef.current = setTimeout(() => {
       delayedChildRefreshRef.current = null;
-      void state.refresh();
+      void refresh();
     }, 2500);
-  }, [state]);
+  }, [refresh]);
   useSessionEventTrigger(
     client,
     workspaceId,
@@ -114,6 +123,6 @@ export function useSessionLineage(
     lineage: state.data,
     loading: state.loading,
     error: state.error,
-    refresh: state.refresh,
+    refresh,
   };
 }