@tea-agent/loop-agent 0.33.7-beta.0 → 0.34.1

package/dist/worker/console/static-src/operator-chat/useChatStream.js

@@ -1,56 +1,175 @@
 import { useCallback, useEffect } from "react";
 import { formatOperatorUserError } from "../../operator-user-error.js";
 import { confirmationToken, requestId, sleep } from "./format.js";
-/** Inline prompt SSE + background reconnect GET /events stream (M1-T04/T05). */
+function sseEventName(block) {
+    return (block
+        .split("\n")
+        .find((line) => line.startsWith("event: "))
+        ?.slice(7)
+        .trim() ?? "message");
+}
+function sleepBriefly() {
+    return new Promise((resolve) => window.setTimeout(resolve, 25));
+}
+/** One GET /events stream owns all Chat events. Sending a prompt creates a
+ * detached Turn resource only; it never opens a second inline SSE consumer. */
 export function useChatStream(params) {
-    const { origin, refs, session, thread, composer, setError, setAutoScroll } = params;
+    const { origin, refs, session, thread, composer, setError, setAutoScroll, recoveryVersion = 0, watchSessionTitle, } = params;
     const { applySseBlock, setMessages, setStreaming, setStreamingAssistantId, streaming, } = thread;
     const { setInput, setPendingImages } = composer;
+    /** Follow one session's event stream until it is explicitly aborted. The
+     * server's `stream_ready` marker separates replay from live events; this
+     * means replay cannot render duplicate messages while live text remains
+     * smooth (M4.1/M4.3). */
+    const openEventsStream = useCallback(async (sessionId, generation, signal) => {
+        while (!signal.aborted) {
+            const state = refs.eventsStreamStateRef.current;
+            if (!state ||
+                state.sessionId !== sessionId ||
+                state.generation !== generation)
+                return;
+            state.ready = false;
+            try {
+                const headers = {
+                    Accept: "text/event-stream",
+                };
+                const last = refs.lastEventIdRef.current;
+                if (last)
+                    headers["Last-Event-ID"] = last;
+                const res = await fetch(`${origin}/api/operator/v1/chat/sessions/${encodeURIComponent(sessionId)}/events`, { headers, credentials: "include", signal });
+                if (!res.ok || !res.body) {
+                    if (res.status === 404)
+                        return;
+                    await sleep(2_000, signal);
+                    continue;
+                }
+                const reader = res.body.getReader();
+                const decoder = new TextDecoder();
+                let buffer = "";
+                let replay = true;
+                const fallbackAssistantId = requestId("a");
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    buffer += decoder.decode(value, { stream: true });
+                    const blocks = buffer.split("\n\n");
+                    buffer = blocks.pop() ?? "";
+                    for (const block of blocks) {
+                        if (sseEventName(block) === "stream_ready") {
+                            const current = refs.eventsStreamStateRef.current;
+                            if (current?.sessionId === sessionId &&
+                                current.generation === generation)
+                                current.ready = true;
+                            replay = false;
+                            continue;
+                        }
+                        const assistantId = refs.assistantIdRef.current ?? fallbackAssistantId;
+                        const eventId = applySseBlock(block, assistantId, {
+                            replay,
+                            targetSessionId: sessionId,
+                            generation,
+                        });
+                        if (eventId)
+                            refs.lastEventIdRef.current = eventId;
+                    }
+                }
+                const current = refs.eventsStreamStateRef.current;
+                if (current?.sessionId === sessionId &&
+                    current.generation === generation)
+                    current.ready = false;
+                await sleep(1_000, signal);
+            }
+            catch {
+                if (signal.aborted)
+                    return;
+                await sleep(2_000, signal);
+            }
+        }
+    }, [origin, refs, applySseBlock]);
+    const startEventsStream = useCallback((sessionId, generation) => {
+        const existing = refs.eventsStreamStateRef.current;
+        if (existing?.sessionId === sessionId &&
+            existing.generation === generation &&
+            refs.reconnectAbortRef.current)
+            return;
+        refs.reconnectAbortRef.current?.abort();
+        const controller = new AbortController();
+        refs.reconnectAbortRef.current = controller;
+        refs.eventsStreamStateRef.current = {
+            sessionId,
+            generation,
+            ready: false,
+        };
+        void openEventsStream(sessionId, generation, controller.signal);
+    }, [refs, openEventsStream]);
+    /** Wait until the GET stream completed its retained replay and entered follow
+     * mode. The bounded wait gives an actionable error rather than accidentally
+     * falling back to a second POST-SSE owner (M4.1). */
+    const ensureEventsConnected = useCallback(async (sessionId, generation) => {
+        startEventsStream(sessionId, generation);
+        const deadline = Date.now() + 5_000;
+        while (Date.now() < deadline) {
+            const state = refs.eventsStreamStateRef.current;
+            if (state?.sessionId === sessionId &&
+                state.generation === generation &&
+                state.ready)
+                return;
+            if (refs.sessionRef.current?.sessionId !== sessionId ||
+                refs.sessionGenerationRef.current !== generation)
+                throw new Error("会话已切换");
+            await sleepBriefly();
+        }
+        throw new Error("事件连接未就绪，请检查 Console 连接后重试");
+    }, [refs, startEventsStream]);
     const sendPrompt = useCallback(async (text, images) => {
-        // Read from refs (the source of truth) so callers that captured a
-        // stale closure — notably suggestion chips chaining
-        // createSession().then(sendPrompt) — still see the freshly created
-        // session rather than the null from an earlier render.
-        const session = refs.sessionRef.current;
-        if (!session ||
+        const activeSession = refs.sessionRef.current;
+        const generation = refs.sessionGenerationRef.current;
+        if (!activeSession ||
             (!text.trim() && images.length === 0) ||
             refs.streamingRef.current)
             return;
+        try {
+            await ensureEventsConnected(activeSession.sessionId, generation);
+        }
+        catch (error) {
+            if (refs.sessionRef.current?.sessionId === activeSession.sessionId &&
+                refs.sessionGenerationRef.current === generation) {
+                setError(formatOperatorUserError(error instanceof Error ? error.message : String(error)));
+            }
+            return;
+        }
+        if (refs.sessionRef.current?.sessionId !== activeSession.sessionId ||
+            refs.sessionGenerationRef.current !== generation)
+            return;
         const userMsg = {
             id: requestId("u"),
             role: "user",
             text: text.trim(),
             createdAt: Date.now(),
         };
-        setMessages((m) => [...m, userMsg]);
+        const assistantId = requestId("a");
+        setMessages((messages) => [
+            ...messages,
+            userMsg,
+            { id: assistantId, role: "assistant", text: "", createdAt: Date.now() },
+        ]);
         setInput("");
-        // Stop the background replay stream before opening the inline SSE
-        // stream. Otherwise both connections can consume the same persisted
-        // event under different assistant ids and render duplicate bubbles.
-        refs.reconnectAbortRef.current?.abort();
-        refs.reconnectAbortRef.current = null;
-        refs.streamingRef.current = true;
-        setStreaming(true);
         setAutoScroll(true);
         setError(null);
-        const assistantId = requestId("a");
+        refs.streamingRef.current = true;
         refs.assistantIdRef.current = assistantId;
+        setStreaming(true);
         setStreamingAssistantId(assistantId);
-        setMessages((m) => [
-            ...m,
-            { id: assistantId, role: "assistant", text: "", createdAt: Date.now() },
-        ]);
-        const ac = new AbortController();
-        refs.abortRef.current = ac;
-        refs.sessionAbortControllersRef.current.set(session.sessionId, ac);
-        refs.inlineStreamSessionIdsRef.current.add(session.sessionId);
+        const controller = new AbortController();
+        refs.abortRef.current = controller;
+        refs.sessionAbortControllersRef.current.set(activeSession.sessionId, controller);
         try {
-            const res = await fetch(`${origin}/api/operator/v1/chat/sessions/${session.sessionId}/prompt`, {
+            const res = await fetch(`${origin}/api/operator/v1/chat/sessions/${encodeURIComponent(activeSession.sessionId)}/turns`, {
                 method: "POST",
                 headers: {
                     "Content-Type": "application/json",
                     "x-loop-console-confirmation": confirmationToken(),
-                    Accept: "text/event-stream",
                 },
                 credentials: "include",
                 body: JSON.stringify({
@@ -61,134 +180,111 @@ export function useChatStream(params) {
                         data,
                     })),
                 }),
-                signal: ac.signal,
+                signal: controller.signal,
             });
-            if (!res.ok || !res.body) {
-                const body = (await res.json().catch(() => ({})));
+            const body = (await res.json().catch(() => ({})));
+            if (!res.ok || !body.turnId)
                 throw new Error(body.error?.message ?? `HTTP ${res.status}`);
-            }
-            const reader = res.body.getReader();
-            const decoder = new TextDecoder();
-            let buffer = "";
-            for (;;) {
-                const { done, value } = await reader.read();
-                if (done)
-                    break;
-                buffer += decoder.decode(value, { stream: true });
-                const events = buffer.split("\n\n");
-                buffer = events.pop() ?? "";
-                for (const block of events) {
-                    const eid = applySseBlock(block, assistantId, {
-                        targetSessionId: session.sessionId,
-                    });
-                    if (eid)
-                        refs.lastEventIdRef.current = eid;
-                }
-            }
-        }
-        catch (e) {
-            if (e?.name === "AbortError") {
-                // user stopped; keep partial assistant text
-            }
-            else if (refs.sessionRef.current?.sessionId === session.sessionId) {
-                setError(formatOperatorUserError(e instanceof Error ? e.message : String(e)));
-            }
+            // A successful accepted turn is the browser-side authorization to
+            // watch this session's late automatic title. The watcher is independent
+            // of the active-session generation, so switching away does not lose it.
+            watchSessionTitle(activeSession.sessionId);
+            // Slow POST returns cannot alter a later selection/turn (M5.2).
+            if (refs.sessionRef.current?.sessionId !== activeSession.sessionId ||
+                refs.sessionGenerationRef.current !== generation)
+                return;
+            refs.activeTurnIdRef.current = body.turnId;
+            refs.turnAssistantIdsRef.current.set(body.turnId, assistantId);
+            setPendingImages([]);
         }
-        finally {
-            if (refs.sessionRef.current?.sessionId === session.sessionId) {
+        catch (error) {
+            if (error?.name !== "AbortError" &&
+                refs.sessionRef.current?.sessionId === activeSession.sessionId &&
+                refs.sessionGenerationRef.current === generation) {
+                setError(formatOperatorUserError(error instanceof Error ? error.message : String(error)));
                 refs.streamingRef.current = false;
+                refs.assistantIdRef.current = null;
                 setStreaming(false);
                 setStreamingAssistantId(null);
-                refs.abortRef.current = null;
-                refs.assistantIdRef.current = null;
-                setPendingImages([]);
+                setMessages((messages) => messages.filter((message) => message.id !== assistantId || message.text.trim()));
             }
-            refs.inlineStreamSessionIdsRef.current.delete(session.sessionId);
-            refs.sessionAbortControllersRef.current.delete(session.sessionId);
+        }
+        finally {
+            refs.sessionAbortControllersRef.current.delete(activeSession.sessionId);
+            if (refs.abortRef.current === controller)
+                refs.abortRef.current = null;
         }
     }, [
         origin,
         refs,
-        applySseBlock,
+        ensureEventsConnected,
         setMessages,
-        setStreaming,
-        setStreamingAssistantId,
         setInput,
-        setPendingImages,
         setAutoScroll,
         setError,
+        setStreaming,
+        setStreamingAssistantId,
+        setPendingImages,
+        watchSessionTitle,
     ]);
     const handleStop = useCallback(() => {
         refs.abortRef.current?.abort();
+        if (refs.activeTurnIdRef.current)
+            refs.settledTurnIdsRef.current.add(refs.activeTurnIdRef.current);
         refs.streamingRef.current = false;
+        refs.activeTurnIdRef.current = null;
         setStreaming(false);
         setStreamingAssistantId(null);
-        // User-initiated stop: immediately drop the still-empty placeholder
-        // bubble (no text yet) instead of leaving a forever "…" row (pi-web
-        // hides empty assistant rows on abort).
-        setMessages((m) => m.filter((msg) => !(msg.id === refs.assistantIdRef.current &&
-            msg.role === "assistant" &&
-            !msg.text.trim())));
+        setMessages((messages) => messages.filter((message) => !(message.id === refs.assistantIdRef.current &&
+            message.role === "assistant" &&
+            !message.text.trim())));
+        refs.assistantIdRef.current = null;
     }, [refs, setStreaming, setStreamingAssistantId, setMessages]);
-    // Reconcile client streaming state with the server (pi-web get_state loop).
-    // When SSE events are missed (network drop, backgrounded tab, half-open
-    // connection) agent_end/agent_settled never arrive and the UI stays
-    // streaming forever. If the server reports no active turn while we still
-    // think a turn is streaming, force the same finish a terminal event would
-    // have produced. Also refreshes activeTurnIdRef so replayed agent_start
-    // frames are judged against current server truth.
+    // State reconciliation is only a status fence: it never consumes/creates
+    // message events, and a generation check discards late responses (M5.3).
     useEffect(() => {
         if (!session || !streaming)
             return;
-        const sid = session.sessionId;
+        const sessionId = session.sessionId;
+        const generation = refs.sessionGenerationRef.current;
         let cancelled = false;
         const sync = async () => {
-            if (cancelled)
-                return;
             try {
-                const res = await fetch(`${origin}/api/operator/v1/chat/sessions/${encodeURIComponent(sid)}/state`, { credentials: "include" });
-                if (!res.ok)
+                const res = await fetch(`${origin}/api/operator/v1/chat/sessions/${encodeURIComponent(sessionId)}/state`, { credentials: "include" });
+                const body = (await res.json().catch(() => ({})));
+                if (cancelled ||
+                    !res.ok ||
+                    refs.sessionRef.current?.sessionId !== sessionId ||
+                    refs.sessionGenerationRef.current !== generation)
                     return;
-                const body = (await res.json());
                 const activeTurnId = body.state?.activeTurnId ?? null;
                 refs.activeTurnIdRef.current = activeTurnId;
                 if (activeTurnId !== null || !refs.streamingRef.current)
                     return;
-                // Server idle while the client still thinks a turn is streaming.
-                // Skip when an inline prompt request is still in flight — the
-                // server may not have created its turn lease yet (POST prompt
-                // creates the turn server-side after the request lands), and
-                // force-finishing then would kill a just-sent prompt.
-                if (refs.inlineStreamSessionIdsRef.current.has(sid))
-                    return;
-                const pendingAssistantId = refs.assistantIdRef.current;
+                const assistantId = refs.assistantIdRef.current;
                 refs.streamingRef.current = false;
+                refs.assistantIdRef.current = null;
                 setStreaming(false);
                 setStreamingAssistantId(null);
-                refs.abortRef.current?.abort();
-                refs.abortRef.current = null;
-                refs.assistantIdRef.current = null;
-                setMessages((m) => m.filter((msg) => !(msg.id === pendingAssistantId &&
-                    msg.role === "assistant" &&
-                    !msg.text.trim())));
+                setMessages((messages) => messages.filter((message) => !(message.id === assistantId &&
+                    message.role === "assistant" &&
+                    !message.text.trim())));
             }
             catch {
-                // Network still down — the next poll / visibility / online tick retries.
+                // offline/background case: interval, visibility and online retry.
             }
         };
         const onVisible = () => {
             if (document.visibilityState === "visible")
                 void sync();
         };
-        const onOnline = () => {
-            void sync();
-        };
-        const interval = setInterval(() => void sync(), 15_000);
+        const onOnline = () => void sync();
+        const interval = window.setInterval(() => void sync(), 15_000);
         document.addEventListener("visibilitychange", onVisible);
         window.addEventListener("online", onOnline);
         return () => {
             cancelled = true;
-            clearInterval(interval);
+            window.clearInterval(interval);
             document.removeEventListener("visibilitychange", onVisible);
             window.removeEventListener("online", onOnline);
         };
@@ -201,87 +297,22 @@ export function useChatStream(params) {
         setStreamingAssistantId,
         setMessages,
     ]);
-    /** Open the reconnectable GET /events stream for a session and apply events
-     *  until it closes, then reopen with the latest Last-Event-ID (M1-T04/T05).
-     *
-     *  The stream is strictly a recovery path: it is stopped before an inline
-     *  prompt SSE starts, then reopened after that prompt settles. This preserves
-     *  one owner for an in-flight assistant bubble while still replaying the
-     *  durable tail after refreshes and network blips. */
-    const openEventsStream = useCallback(async (sessionId, signal) => {
-        while (!signal.aborted) {
-            try {
-                const headers = {
-                    Accept: "text/event-stream",
-                };
-                const last = refs.lastEventIdRef.current;
-                if (last)
-                    headers["Last-Event-ID"] = last;
-                const res = await fetch(`${origin}/api/operator/v1/chat/sessions/${sessionId}/events`, { headers, credentials: "include", signal });
-                if (!res.ok || !res.body) {
-                    // 404 = session gone; stop the loop quietly.
-                    if (res.status === 404)
-                        return;
-                    // transient error: back off before retrying.
-                    await sleep(2000, signal);
-                    continue;
-                }
-                const reader = res.body.getReader();
-                const decoder = new TextDecoder();
-                let buffer = "";
-                // Reconnect assistant id: events arriving here belong to whichever
-                // turn is/was active; reuse the in-flight one or allocate a stable
-                // placeholder so streaming text patches a single bubble.
-                let rcAssistantId = refs.assistantIdRef.current;
-                if (!rcAssistantId) {
-                    rcAssistantId = requestId("a");
-                    refs.assistantIdRef.current = rcAssistantId;
-                }
-                for (;;) {
-                    const { done, value } = await reader.read();
-                    if (done)
-                        break;
-                    buffer += decoder.decode(value, { stream: true });
-                    const blocks = buffer.split("\n\n");
-                    buffer = blocks.pop() ?? "";
-                    for (const block of blocks) {
-                        const eid = applySseBlock(block, rcAssistantId, {
-                            replay: true,
-                            targetSessionId: sessionId,
-                        });
-                        if (eid)
-                            refs.lastEventIdRef.current = eid;
-                    }
-                }
-                // Server closed the follow window (idle). Reopen from the last id
-                // after a short pause unless we were aborted.
-                await sleep(1000, signal);
-            }
-            catch (e) {
-                if (signal.aborted)
-                    return;
-                // Network blip: back off and retry (keeps reconnect resilient).
-                await sleep(2000, signal);
-            }
-        }
-    }, [origin, refs, applySseBlock]);
-    // Reconnect effect: open/refresh the events stream whenever the active
-    // session or streaming state changes. Aborts the previous stream on cleanup
-    // so switching sessions, starting an inline prompt, or unmounting does not
-    // leak a dangling connection. It resumes after settle/stop to catch the tail.
+    // Exactly one owner starts/aborts GET /events. Switching sessions or
+    // recovering a cursor aborts the prior stream before the next one is made.
     useEffect(() => {
-        if (!session ||
-            (streaming &&
-                refs.inlineStreamSessionIdsRef.current.has(session.sessionId)))
+        if (!session)
             return;
-        const ac = new AbortController();
-        refs.reconnectAbortRef.current = ac;
-        void openEventsStream(session.sessionId, ac.signal);
+        const generation = refs.sessionGenerationRef.current;
+        startEventsStream(session.sessionId, generation);
         return () => {
-            ac.abort();
-            if (refs.reconnectAbortRef.current === ac)
+            const state = refs.eventsStreamStateRef.current;
+            if (state?.sessionId === session.sessionId &&
+                state.generation === generation) {
+                refs.reconnectAbortRef.current?.abort();
                 refs.reconnectAbortRef.current = null;
+                refs.eventsStreamStateRef.current = null;
+            }
         };
-    }, [session, streaming, openEventsStream, refs]);
+    }, [session, recoveryVersion, refs, startEventsStream]);
     return { sendPrompt, handleStop, openEventsStream };
 }

package/dist/worker/console/static-src/operator-chat/useChatThread.js

@@ -1,6 +1,6 @@
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { buildTurnProcessGroups } from "../../chat/turn-process.js";
-import { createChatSseEventApplier } from "./chat-sse-events.js";
+import { createChatSseEventApplier, } from "./chat-sse-events.js";
 import { taskContextUnchanged } from "./format.js";
 const EMPTY_USAGE = {
     inputTokens: 0,
@@ -15,7 +15,7 @@ const EMPTY_USAGE = {
  * slices it patches and the derived timeline projections.
  */
 export function useChatThread(params) {
-    const { origin, refs, sessionId, setError, setProcessOpen } = params;
+    const { origin, refs, sessionId, setError, setProcessOpen, onReconcile } = params;
     const [messages, setMessages] = useState([]);
     const [toolCalls, setToolCalls] = useState([]);
     const [operationCards, setOperationCards] = useState([]);
@@ -35,6 +35,7 @@ export function useChatThread(params) {
     // applier identity is stable across renders.
     const applyChatSseEvent = useMemo(() => createChatSseEventApplier({
         refs,
+        onReconcile,
         setError,
         setProcessOpen,
         setInterview,
@@ -47,12 +48,14 @@ export function useChatThread(params) {
         setUsage,
         setMessages,
         setToolCalls,
-    }), [refs, setError, setProcessOpen]);
+    }), [refs, onReconcile, setError, setProcessOpen]);
     /** Parse + apply one raw SSE block (frames separated by \n\n). Returns the
      *  eventId if the block carried an `id:` line (for Last-Event-ID tracking). */
     const applySseBlock = useCallback((block, assistantId, options) => {
-        if (options?.targetSessionId &&
-            refs.sessionRef.current?.sessionId !== options.targetSessionId)
+        if ((options?.targetSessionId &&
+            refs.sessionRef.current?.sessionId !== options.targetSessionId) ||
+            (options?.generation !== undefined &&
+                refs.sessionGenerationRef.current !== options.generation))
             return null;
         const lines = block.split("\n");
         let eventName = "message";
@@ -186,6 +189,46 @@ export function useChatThread(params) {
         setUnread(0);
         setHistoryLimit(50);
     }, [refs]);
+    /** Reconcile recovery (AC-001/AC-002/AC-003): reload the canonical session
+     *  facts (session-store messages + event-ring tail cursor) and REPLACE the
+     *  thread projection. Never calls applyActivatedSession: that would clear the
+     *  operation/human-gate/artifact/interview cards, which the reconnected tail
+     *  stream will not replay (they live in the ring, already consumed). */
+    const recoverSession = useCallback(async (targetSessionId) => {
+        try {
+            const res = await fetch(`${origin}/api/operator/v1/chat/sessions/${encodeURIComponent(targetSessionId)}`, { credentials: "include" });
+            if (!res.ok)
+                return false;
+            const body = (await res.json());
+            if (!body.session ||
+                refs.sessionRef.current?.sessionId !== targetSessionId)
+                return false;
+            const activeTurnId = body.session.activeTurnId ?? null;
+            refs.activeTurnIdRef.current = activeTurnId;
+            refs.streamingRef.current = Boolean(activeTurnId);
+            // Resume the events stream from the snapshot tail so the next
+            // reconnect never immediately re-expires (AC-003). The refs below
+            // are reset so any follow-up tail replay re-applies cleanly.
+            refs.lastEventIdRef.current = body.lastEventId ?? null;
+            refs.seenEventIdsRef.current = new Set();
+            refs.turnAssistantIdsRef.current = new Map();
+            setMessages((body.session.messages ?? [])
+                .filter((message) => message.role === "user" || message.role === "assistant")
+                .map((message) => ({
+                id: message.id,
+                role: message.role,
+                text: message.text,
+                createdAt: Date.parse(message.at) || Date.now(),
+            })));
+            setStreamingAssistantId(null);
+            return true;
+        }
+        catch {
+            // Reload failed: keep the old cursor; the next stream reopen will
+            // trigger another reconcile and retry (best-effort recovery).
+            return false;
+        }
+    }, [origin, refs, setMessages, setStreamingAssistantId]);
     return {
         messages,
         setMessages,
@@ -214,5 +257,6 @@ export function useChatThread(params) {
         loadTaskContext,
         resetForNewSession,
         applyActivatedSession,
+        recoverSession,
     };
 }

package/dist/worker/console/static-src/operator-chat/useComposer.js

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, } from "react";
 import { SHORTCUTS } from "../../chat/shortcuts.js";
 import { confirmationToken } from "./format.js";
+import { attachRuntimeSnapshotController } from "./useRuntimeSnapshot.js";
 /** Composer state: input text, @file palette, image attachments, /shortcuts,
  *  IME composition guards, auto-grow and server-side draft sync. */
 export function useComposer(params) {
@@ -103,6 +104,20 @@ export function useComposer(params) {
         refs.isComposingRef.current = false;
         refs.compositionEndedAtRef.current = Date.now();
     }, [refs]);
+    /** IME guard used by the ChatComposer keyboard wrapper (mirrors OperatorChat). */
+    const isComposingNow = useCallback(() => {
+        return refs.isComposingRef.current;
+    }, [refs]);
+    /** 100ms post-composition window (mirrors OperatorChat). */
+    const recentlyComposedNow = useCallback(() => {
+        return Date.now() - refs.compositionEndedAtRef.current < 100;
+    }, [refs]);
+    // Bind the shared runtime snapshot to the active session (the composer owns
+    // origin + sessionId + refs in a writable file; the snapshot store is
+    // consumed by ChatComposer / panels / runtime-context popover).
+    useEffect(() => {
+        attachRuntimeSnapshotController({ origin, sessionId, refs });
+    }, [origin, sessionId, refs]);
     return {
         input,
         setInput,
@@ -121,5 +136,7 @@ export function useComposer(params) {
         textareaRef,
         onCompositionStart,
         onCompositionEnd,
+        isComposingNow,
+        recentlyComposedNow,
     };
 }