@ouispec/agent-react 0.1.0

package/dist/provider/AgentProvider.js

@@ -0,0 +1,800 @@
+import React, { createContext, useContext, useState, useCallback, useEffect, useRef } from 'react';
+import { APPROVAL_DECIDE_EVENT } from '@ouispec/agent-core';
+import { ALL_AGENT_SOCKET_EVENTS, parseSocketEvent } from '@ouispec/agent-core';
+import { createSocketIOSocket } from './socketio.js';
+import { ApprovalDecisionContext, approvalRefusalText } from '../approvals/decision.js';
+import { annotationRegistry } from '../annotations/singleton.js';
+import { storedToAgentMessages } from './stored-messages.js';
+const AgentContext = createContext(null);
+const MAX_DEBUG_LOGS = 500;
+const DEFAULT_ACTIVE_CONVERSATION_KEY = 'agent-sdk.activeConversation';
+const HISTORY_PAGE_SIZE = 20;
+/** How long the card waits for the approval store to answer a click. */
+const APPROVAL_DECIDE_TIMEOUT_MS = 10_000;
+/**
+ * The tab's remembered active conversation, in `sessionStorage` so a reload
+ * returns to it and a new tab starts fresh. Storage can be missing or throw
+ * (private windows, blocked site data): then nothing is remembered.
+ */
+function sessionKeyOf(config) {
+    if (!config.getConversation || config.activeConversationKey === false)
+        return null;
+    return config.activeConversationKey ?? DEFAULT_ACTIVE_CONVERSATION_KEY;
+}
+function readRemembered(key) {
+    if (!key)
+        return null;
+    try {
+        return window.sessionStorage.getItem(key);
+    }
+    catch {
+        return null;
+    }
+}
+function writeRemembered(key, conversationId) {
+    if (!key)
+        return;
+    try {
+        if (conversationId)
+            window.sessionStorage.setItem(key, conversationId);
+        else
+            window.sessionStorage.removeItem(key);
+    }
+    catch {
+        // Nothing is remembered; the conversation still works.
+    }
+}
+/**
+ * Whether a conversation still belongs in a list with this filter after a
+ * change. Only what the SDK can see is checked: a search is the platform's.
+ */
+function passesFilter(summary, filter) {
+    const status = filter.status ?? 'active';
+    if (status === 'active' && summary.archivedAt)
+        return false;
+    if (status === 'archived' && !summary.archivedAt)
+        return false;
+    if (filter.scopeId !== undefined && (summary.scope?.id ?? null) !== filter.scopeId)
+        return false;
+    return true;
+}
+function reasonOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+const ALL_DEBUG_NAMESPACES = ['agent:socket', 'agent:protocol', 'agent:state', 'agent:api'];
+let debugLogCounter = 0;
+function createDebugEntry(level, ns, message, data) {
+    return {
+        id: `dbg_${++debugLogCounter}`,
+        timestamp: Date.now(),
+        level,
+        ns,
+        message,
+        data,
+    };
+}
+/**
+ * AgentProvider — turnkey provider that handles the complete agent lifecycle.
+ *
+ * The platform provides:
+ * - createConversation() / sendMessage() — API callbacks
+ * - realtime: { url, getToken } — where and how to connect
+ *
+ * The SDK owns:
+ * - Socket.IO connection lifecycle (connect, reconnect, auth)
+ * - Room subscription tied to active turns, kept across reconnects
+ * - All event parsing (agent:* protocol)
+ * - Streaming state, message history, keyboard shortcuts
+ *
+ * UI actions are not dispatched here: the client's OUI surface runtime answers
+ * them on the same socket (ADR-0209).
+ */
+export function AgentProvider({ config, children }) {
+    const [isOpen, setIsOpen] = useState(false);
+    const [isStreaming, setIsStreaming] = useState(false);
+    const [currentTurnId, setCurrentTurnId] = useState(null);
+    const [conversationId, setConversationId] = useState(null);
+    // The same id, read by callbacks that must not wait for a re-render (a send
+    // that follows a restore, a switch during a restore).
+    const conversationIdRef = useRef(null);
+    const [isLoadingConversation, setIsLoadingConversation] = useState(false);
+    const pendingLoadRef = useRef(null);
+    const loadSeqRef = useRef(0);
+    const [historyConversations, setHistoryConversations] = useState([]);
+    const [historyTotal, setHistoryTotal] = useState(0);
+    const [historyLoading, setHistoryLoading] = useState(false);
+    const [historyError, setHistoryError] = useState(null);
+    // The listed conversations, read by changes that must not wait for a re-render.
+    const historyConversationsRef = useRef([]);
+    const [historyFilter, setHistoryFilter] = useState({});
+    const historyFilterRef = useRef({});
+    const [historyRevision, setHistoryRevision] = useState(0);
+    const isStreamingRef = useRef(false);
+    const [messages, setMessages] = useState([]);
+    const [connected, setConnected] = useState(false);
+    const [debugEnabled, setDebugEnabled] = useState(false);
+    const [debugLogs, setDebugLogs] = useState([]);
+    const [presentedOptions, setPresentedOptions] = useState(null);
+    // The call a turn stopped at for the user's approval (ADR-0228), until they decide.
+    const [pendingApproval, setPendingApproval] = useState(null);
+    const [approvalDeciding, setApprovalDeciding] = useState(false);
+    const [approvalError, setApprovalError] = useState(null);
+    const socketRef = useRef(null);
+    const unsubscribeRef = useRef(null);
+    // The room of the turn in progress and its token. A reconnect gives the
+    // server a new socket that is in no room, so the join is repeated on every
+    // connect while a turn is active; without it the turn streams to nobody and
+    // the panel waits forever.
+    const activeRoomRef = useRef(null);
+    const streamBufferRef = useRef('');
+    const roundPrefixRef = useRef('');
+    const configRef = useRef(config);
+    const debugEnabledRef = useRef(debugEnabled);
+    configRef.current = config;
+    debugEnabledRef.current = debugEnabled;
+    isStreamingRef.current = isStreaming;
+    const shortcutKey = config.shortcutKey ?? 'k';
+    const setActiveConversation = useCallback((id) => {
+        conversationIdRef.current = id;
+        setConversationId(id);
+        writeRemembered(sessionKeyOf(configRef.current), id);
+    }, []);
+    const addDebugLog = useCallback((level, ns, message, data) => {
+        if (!debugEnabledRef.current)
+            return;
+        const entry = createDebugEntry(level, ns, message, data);
+        setDebugLogs(prev => {
+            const next = [...prev, entry];
+            return next.length > MAX_DEBUG_LOGS ? next.slice(-MAX_DEBUG_LOGS) : next;
+        });
+    }, []);
+    const clearDebugLogs = useCallback(() => setDebugLogs([]), []);
+    // --- Socket connection lifecycle (SDK-owned; the socket is a seam) ---
+    useEffect(() => {
+        const { url, getToken, createSocket = createSocketIOSocket } = config.realtime;
+        if (!url)
+            return;
+        const socket = createSocket({ url, getToken });
+        socket.on('connect', () => {
+            setConnected(true);
+            addDebugLog('info', 'agent:socket', 'Connected', { socketId: socket.id, url });
+            const active = activeRoomRef.current;
+            if (active) {
+                addDebugLog('info', 'agent:socket', `Rejoining turn room after reconnect: ${active.room}`, { room: active.room });
+                joinRoom(socket, active.room, active.token);
+            }
+        });
+        socket.on('disconnect', (reason) => {
+            setConnected(false);
+            addDebugLog('warn', 'agent:socket', `Disconnected: ${reason}`, { reason });
+        });
+        socket.on('connect_error', (err) => {
+            addDebugLog('error', 'agent:socket', `Connection error: ${err.message}`, { error: err.message });
+        });
+        socket.on('reconnect_attempt', (attempt) => {
+            addDebugLog('info', 'agent:socket', `Reconnecting (attempt ${attempt})`, { attempt });
+        });
+        socket.connect();
+        addDebugLog('info', 'agent:socket', 'Connecting...', { url });
+        socketRef.current = socket;
+        return () => {
+            socket.disconnect();
+            socketRef.current = null;
+            setConnected(false);
+        };
+    }, [config.realtime.url]);
+    // Keyboard shortcut
+    useEffect(() => {
+        const handler = (e) => {
+            if ((e.metaKey || e.ctrlKey) && e.key === shortcutKey) {
+                e.preventDefault();
+                setIsOpen(prev => !prev);
+            }
+        };
+        document.addEventListener('keydown', handler);
+        return () => document.removeEventListener('keydown', handler);
+    }, [shortcutKey]);
+    // --- Protocol event handler ---
+    const handleProtocolEvent = useCallback((event) => {
+        addDebugLog('event', 'agent:protocol', `${event.type}`, event);
+        configRef.current.onEvent?.(event);
+        switch (event.type) {
+            case 'token': {
+                if (!event.content)
+                    break;
+                streamBufferRef.current += event.content;
+                // Snapshot the accumulated content BEFORE enqueueing the state update.
+                // React batches updates and runs the setMessages callback later; if the
+                // 'done' event arrives and clears streamBufferRef.current before the
+                // batch flushes, the deferred callback would otherwise read '' and wipe
+                // the message. Capturing into a local makes the update self-contained.
+                const snapshot = streamBufferRef.current;
+                setMessages(prev => {
+                    const msgId = `msg_${event.turnId}`;
+                    const existingIdx = prev.findIndex(m => m.id === msgId);
+                    if (existingIdx !== -1) {
+                        // Update in place — never create a duplicate with the same id.
+                        const updated = [...prev];
+                        updated[existingIdx] = { ...updated[existingIdx], content: snapshot, isStreaming: true };
+                        return updated;
+                    }
+                    // Defensive: drop any stale streaming messages for this turnId before adding a fresh one.
+                    const cleaned = prev.filter(m => m.id !== msgId);
+                    return [...cleaned, {
+                            id: msgId,
+                            role: 'assistant',
+                            content: snapshot,
+                            timestamp: Date.now(),
+                            isStreaming: true,
+                        }];
+                });
+                break;
+            }
+            case 'token_clear':
+                // A tool_use round ended. Preserve text from previous rounds so the
+                // user sees the full multi-round response. Only truly clear if no text
+                // has been accumulated yet (first round).
+                if (streamBufferRef.current) {
+                    // Commit the current buffer as a completed round prefix.
+                    roundPrefixRef.current = streamBufferRef.current;
+                    // Add a separator — the next round's tokens will append after this.
+                    streamBufferRef.current = roundPrefixRef.current + '\n\n';
+                }
+                // Don't update message content — leave the existing text visible.
+                break;
+            case 'intent_call':
+                setMessages(prev => [...prev, {
+                        id: `tool_${event.id}`,
+                        role: 'tool',
+                        content: null,
+                        timestamp: Date.now(),
+                        toolCall: { id: event.id, name: event.intentId, status: 'running' },
+                    }]);
+                break;
+            case 'intent_result':
+                // Detect present_options tool results and surface them as interactive UI state.
+                if (event.result && typeof event.result === 'object' && event.result.__present_options) {
+                    const payload = event.result;
+                    setPresentedOptions({
+                        prompt: payload.prompt ?? '',
+                        options: payload.options ?? [],
+                        style: payload.style ?? undefined,
+                    });
+                }
+                setMessages(prev => prev.map(m => m.toolCall?.id === event.callId
+                    ? { ...m, toolCall: { ...m.toolCall, status: event.success ? 'complete' : 'error', result: event.result } }
+                    : m));
+                break;
+            case 'approval_required': {
+                // The card renders it; only the user's click on it decides.
+                const { type: _type, ...request } = event;
+                setPendingApproval(request);
+                setApprovalError(null);
+                setApprovalDeciding(false);
+                break;
+            }
+            case 'done':
+                // Finalize all streaming messages. Drop any assistant streaming bubble
+                // that ended up truly empty (e.g. token_clear wiped it and no text was
+                // re-emitted). Preserve tool messages (which legitimately have null content).
+                streamBufferRef.current = '';
+                roundPrefixRef.current = '';
+                setMessages(prev => {
+                    const finalized = prev.map(m => m.isStreaming ? { ...m, isStreaming: false } : m);
+                    return finalized.filter(m => {
+                        // Only drop assistant bubbles that are empty (null or empty string).
+                        // Tool messages have null content by design — keep them.
+                        if (m.role === 'assistant' && (m.content === null || m.content === '')) {
+                            return false;
+                        }
+                        return true;
+                    });
+                });
+                setIsStreaming(false);
+                setCurrentTurnId(null);
+                activeRoomRef.current = null;
+                if (unsubscribeRef.current) {
+                    unsubscribeRef.current();
+                    unsubscribeRef.current = null;
+                }
+                break;
+            case 'error':
+                streamBufferRef.current = '';
+                roundPrefixRef.current = '';
+                setMessages(prev => {
+                    const last = prev[prev.length - 1];
+                    if (last?.isStreaming) {
+                        return [...prev.slice(0, -1), { ...last, isStreaming: false, content: last.content || 'An error occurred.' }];
+                    }
+                    return [...prev, {
+                            id: `err_${Date.now()}`,
+                            role: 'assistant',
+                            content: event.message || 'An error occurred.',
+                            timestamp: Date.now(),
+                        }];
+                });
+                setIsStreaming(false);
+                setCurrentTurnId(null);
+                activeRoomRef.current = null;
+                if (unsubscribeRef.current) {
+                    unsubscribeRef.current();
+                    unsubscribeRef.current = null;
+                }
+                break;
+        }
+    }, []);
+    // --- Join a turn room ---
+    // The realtime server requires a signed room token for a turn room and
+    // denies the join without one — the socket stays connected, the
+    // turn completes server-side, and no event ever arrives. Send the
+    // token-bearing form when we have a token, and ACK the result so a denial
+    // is visible instead of looking like the agent simply never replied.
+    const joinRoom = useCallback((socket, room, roomToken) => {
+        if (roomToken) {
+            socket.emit('subscribe', { rooms: [room], tokens: { [room]: roomToken } }, (res) => {
+                if (res && (!res.ok || res.denied?.includes(room))) {
+                    addDebugLog('error', 'agent:socket', `Room subscription DENIED: ${room}`, {
+                        room,
+                        denied: res.denied,
+                        error: res.error,
+                    });
+                }
+                else {
+                    addDebugLog('info', 'agent:socket', `Room joined: ${room}`, { room, joined: res?.joined });
+                }
+            });
+        }
+        else {
+            addDebugLog('warn', 'agent:socket', `Subscribing to ${room} WITHOUT a room token`, {
+                room,
+                hint: 'agent:* rooms require a signed token; the server will deny this join',
+            });
+            socket.emit('subscribe', [room]);
+        }
+    }, [addDebugLog]);
+    // --- Subscribe to a socket room for agent events ---
+    const subscribeToRoom = useCallback((room, turnId, roomToken) => {
+        const socket = socketRef.current;
+        if (!socket) {
+            addDebugLog('error', 'agent:socket', 'Cannot subscribe — no socket (realtime URL not configured)', { room });
+            return () => { };
+        }
+        addDebugLog('info', 'agent:socket', `Subscribing to room: ${room}`, {
+            room,
+            turnId,
+            hasRoomToken: !!roomToken,
+            connected: socket.connected,
+        });
+        // Joined now if connected; otherwise on the next connect, which the
+        // connect handler does for the active room.
+        activeRoomRef.current = { room, token: roomToken };
+        if (socket.connected)
+            joinRoom(socket, room, roomToken);
+        const handlers = new Map();
+        for (const eventName of ALL_AGENT_SOCKET_EVENTS) {
+            const handler = (data) => {
+                addDebugLog('socket', 'agent:socket', `← ${eventName}`, { eventName, data });
+                const parsed = parseSocketEvent(eventName, data, turnId);
+                if (parsed)
+                    handleProtocolEvent(parsed);
+            };
+            handlers.set(eventName, handler);
+            socket.on(eventName, handler);
+        }
+        return () => {
+            for (const [eventName, handler] of handlers) {
+                socket.off(eventName, handler);
+            }
+            socket.emit('unsubscribe', [room]);
+            addDebugLog('info', 'agent:socket', `Unsubscribed from room: ${room}`, { room });
+        };
+    }, [handleProtocolEvent, addDebugLog, joinRoom]);
+    // Collect context from visible annotations and current route
+    const collectContext = useCallback(() => {
+        const annotations = annotationRegistry.getVisibleAnnotations();
+        return {
+            currentPath: typeof window !== 'undefined' ? window.location.pathname : undefined,
+            visibleAnnotations: annotations,
+        };
+    }, []);
+    // --- Start a turn: the user's message, or the continuation after an approval decision ---
+    const startTurn = useCallback(async (content, attachments, approval) => {
+        // A message sent while a conversation loads belongs to that conversation.
+        if (pendingLoadRef.current)
+            await pendingLoadRef.current;
+        let convId = conversationIdRef.current;
+        if (!convId) {
+            addDebugLog('info', 'agent:api', 'Creating conversation...', {});
+            const result = await configRef.current.createConversation();
+            convId = result.conversationId;
+            setActiveConversation(convId);
+            addDebugLog('info', 'agent:api', `Conversation created: ${convId}`, { conversationId: convId });
+        }
+        // A click on the approval card continues the turn, but it is not a message.
+        if (!approval) {
+            const userMsg = {
+                id: `msg_user_${Date.now()}`,
+                role: 'user',
+                content,
+                timestamp: Date.now(),
+            };
+            setMessages(prev => [...prev, userMsg]);
+            // A new message moves on: a card still waiting belongs to the previous turn.
+            setPendingApproval(null);
+        }
+        // Any choice still on screen belongs to the previous turn.
+        setPresentedOptions(null);
+        setIsStreaming(true);
+        streamBufferRef.current = '';
+        try {
+            const context = collectContext();
+            addDebugLog('info', 'agent:api', approval ? 'Continuing after an approval decision...' : 'Sending message...', {
+                conversationId: convId,
+                contentLength: content.length,
+                context,
+                ...(approval ? { approvalId: approval.approvalId, decision: approval.decision } : {}),
+            });
+            const { turnId, socketRoom, roomToken } = await configRef.current.sendMessage({
+                conversationId: convId,
+                content,
+                context,
+                attachments,
+                ...(approval ? { approval } : {}),
+            });
+            addDebugLog('info', 'agent:api', `Turn started: ${turnId}`, {
+                turnId,
+                socketRoom,
+                hasRoomToken: !!roomToken,
+            });
+            addDebugLog('info', 'agent:state', 'Streaming started', { turnId });
+            setCurrentTurnId(turnId);
+            if (unsubscribeRef.current)
+                unsubscribeRef.current();
+            unsubscribeRef.current = subscribeToRoom(socketRoom, turnId, roomToken);
+            return { turnId };
+        }
+        catch (err) {
+            addDebugLog('error', 'agent:api', `Send failed: ${err instanceof Error ? err.message : String(err)}`, { error: err });
+            setIsStreaming(false);
+            setMessages(prev => [...prev, {
+                    id: `err_${Date.now()}`,
+                    role: 'assistant',
+                    content: err instanceof Error ? err.message : 'Failed to send message.',
+                    timestamp: Date.now(),
+                }]);
+            return { turnId: '' };
+        }
+    }, [collectContext, subscribeToRoom, addDebugLog, setActiveConversation]);
+    const sendMessage = useCallback((content, attachments) => startTurn(content, attachments), [startTurn]);
+    // --- The user's decision on an approval card (ADR-0228 §2.2.3) ---
+    // Only the card calls this: it is not on the context `useAgent` returns, so
+    // nothing an app binds for the assistant can reach it.
+    const pendingApprovalRef = useRef(null);
+    pendingApprovalRef.current = pendingApproval;
+    const decideApproval = useCallback(async (decision) => {
+        const request = pendingApprovalRef.current;
+        const socket = socketRef.current;
+        if (!request)
+            return;
+        if (!socket) {
+            setApprovalError('Not connected: try again once the assistant reconnects.');
+            return;
+        }
+        setApprovalDeciding(true);
+        setApprovalError(null);
+        addDebugLog('info', 'agent:api', `Approval ${decision}`, { approvalId: request.approvalId, tool: request.tool });
+        const result = await new Promise(resolve => {
+            const timer = setTimeout(() => resolve({ ok: false, reason: 'invalid', error: 'the server did not answer' }), APPROVAL_DECIDE_TIMEOUT_MS);
+            socket.emit(APPROVAL_DECIDE_EVENT, { approvalId: request.approvalId, decision }, (answer) => {
+                clearTimeout(timer);
+                resolve(answer);
+            });
+        });
+        if (!result.ok) {
+            addDebugLog('warn', 'agent:api', `Approval refused: ${result.reason}`, { approvalId: request.approvalId, reason: result.reason });
+            setApprovalError(approvalRefusalText(result));
+            setApprovalDeciding(false);
+            return;
+        }
+        // The grant goes to this tab's OUI runtime before the turn that dispatches the call starts.
+        if (result.decision === 'approve') {
+            configRef.current.grantApproval?.({ approvalId: result.approvalId, argsHash: result.argsHash, expiresAt: result.expiresAt });
+        }
+        setPendingApproval(null);
+        setApprovalDeciding(false);
+        await startTurn('', undefined, result.decision === 'approve'
+            ? { approvalId: result.approvalId, decision: 'approve', token: result.token }
+            : { approvalId: result.approvalId, decision: 'decline' });
+    }, [startTurn, addDebugLog]);
+    const dismissApproval = useCallback(() => {
+        setPendingApproval(null);
+        setApprovalError(null);
+        setApprovalDeciding(false);
+    }, []);
+    // --- Conversation history ---
+    /** Stop listening to the turn in progress, if any. */
+    const leaveTurn = useCallback(() => {
+        if (unsubscribeRef.current) {
+            unsubscribeRef.current();
+            unsubscribeRef.current = null;
+        }
+        activeRoomRef.current = null;
+        streamBufferRef.current = '';
+        roundPrefixRef.current = '';
+        setCurrentTurnId(null);
+    }, []);
+    /**
+     * Show a stored conversation. The latest request wins: a load that finishes
+     * after another began is discarded. A restore that fails (the conversation
+     * was deleted, or belongs to someone else) forgets it and starts fresh.
+     */
+    const loadConversation = useCallback((id, { restoring }) => {
+        const getConversation = configRef.current.getConversation;
+        if (!getConversation)
+            return Promise.resolve();
+        const seq = ++loadSeqRef.current;
+        setIsLoadingConversation(true);
+        addDebugLog('info', 'agent:api', `${restoring ? 'Restoring' : 'Loading'} conversation ${id}`, { conversationId: id });
+        const load = (async () => {
+            try {
+                const stored = await getConversation(id);
+                if (seq !== loadSeqRef.current)
+                    return;
+                setActiveConversation(stored.conversationId);
+                setMessages(storedToAgentMessages(stored.messages));
+                setPresentedOptions(null);
+                setPendingApproval(null);
+                setHistoryError(null);
+            }
+            catch (err) {
+                if (seq !== loadSeqRef.current)
+                    return;
+                const message = err instanceof Error ? err.message : String(err);
+                addDebugLog('warn', 'agent:api', `Could not load conversation ${id}: ${message}`, { conversationId: id });
+                if (restoring) {
+                    setActiveConversation(null);
+                }
+                else {
+                    setHistoryError('That conversation could not be opened.');
+                }
+            }
+            finally {
+                if (seq === loadSeqRef.current) {
+                    setIsLoadingConversation(false);
+                    pendingLoadRef.current = null;
+                }
+            }
+        })();
+        pendingLoadRef.current = load;
+        return load;
+    }, [addDebugLog, setActiveConversation]);
+    // Return to the tab's conversation after a reload.
+    useEffect(() => {
+        const remembered = readRemembered(sessionKeyOf(configRef.current));
+        if (remembered)
+            void loadConversation(remembered, { restoring: true });
+    }, [loadConversation]);
+    const refreshHistory = useCallback(async (filter) => {
+        const listConversations = configRef.current.listConversations;
+        if (!listConversations)
+            return;
+        if (filter) {
+            historyFilterRef.current = filter;
+            setHistoryFilter(filter);
+        }
+        const asked = historyFilterRef.current;
+        setHistoryLoading(true);
+        try {
+            const page = await listConversations({ limit: HISTORY_PAGE_SIZE, offset: 0, ...asked });
+            // A refresh with another filter started since: its answer wins.
+            if (asked !== historyFilterRef.current)
+                return;
+            historyConversationsRef.current = page.conversations;
+            setHistoryConversations(page.conversations);
+            setHistoryTotal(page.total);
+            setHistoryError(null);
+        }
+        catch (err) {
+            addDebugLog('warn', 'agent:api', `Could not list conversations: ${reasonOf(err)}`);
+            setHistoryError('Your conversations could not be loaded.');
+        }
+        finally {
+            setHistoryLoading(false);
+        }
+    }, [addDebugLog]);
+    const queryConversations = useCallback(async (params) => {
+        const listConversations = configRef.current.listConversations;
+        if (!listConversations)
+            throw new Error('This app cannot list conversations.');
+        return listConversations(params);
+    }, []);
+    /** Replace the listed conversations after a change, and count the change. */
+    const setListed = useCallback((next) => {
+        const dropped = historyConversationsRef.current.length - next.length;
+        historyConversationsRef.current = next;
+        setHistoryConversations(next);
+        if (dropped > 0)
+            setHistoryTotal(total => Math.max(0, total - dropped));
+        setHistoryRevision(r => r + 1);
+    }, []);
+    /** Put changed conversations into the listed ones, dropping those the filter no longer lets in. */
+    const applyToHistory = useCallback((changed) => {
+        const byId = new Map(changed.map(c => [c.conversationId, c]));
+        const filter = historyFilterRef.current;
+        setListed(historyConversationsRef.current.flatMap(c => {
+            const updated = byId.get(c.conversationId);
+            if (!updated)
+                return [c];
+            return passesFilter(updated, filter) ? [updated] : [];
+        }));
+    }, [setListed]);
+    const renameConversation = useCallback(async (id, title) => {
+        const rename = configRef.current.renameConversation;
+        if (!rename)
+            throw new Error('This app cannot rename conversations.');
+        addDebugLog('info', 'agent:api', `Renaming conversation ${id}`, { conversationId: id, automatic: title === null });
+        const updated = await rename(id, title);
+        applyToHistory([updated]);
+        return updated;
+    }, [addDebugLog, applyToHistory]);
+    const updateConversations = useCallback(async (ids, changes) => {
+        const update = configRef.current.updateConversations;
+        if (!update)
+            throw new Error('This app cannot file or archive conversations.');
+        addDebugLog('info', 'agent:api', `Updating ${ids.length} conversation(s)`, { conversationIds: ids, changes });
+        const updated = await update(ids, changes);
+        applyToHistory(updated);
+        return updated;
+    }, [addDebugLog, applyToHistory]);
+    const switchConversation = useCallback(async (id) => {
+        if (isStreaming || id === conversationIdRef.current)
+            return;
+        leaveTurn();
+        await loadConversation(id, { restoring: false });
+    }, [isStreaming, leaveTurn, loadConversation]);
+    /** Leave the open conversation for a new one. Callers check that no turn is answering. */
+    const resetToNewConversation = useCallback(() => {
+        loadSeqRef.current++;
+        pendingLoadRef.current = null;
+        setIsLoadingConversation(false);
+        leaveTurn();
+        setActiveConversation(null);
+        setMessages([]);
+        setPresentedOptions(null);
+        setPendingApproval(null);
+        addDebugLog('info', 'agent:state', 'New conversation');
+    }, [leaveTurn, setActiveConversation, addDebugLog]);
+    const startNewConversation = useCallback(() => {
+        if (isStreaming)
+            return;
+        resetToNewConversation();
+    }, [isStreaming, resetToNewConversation]);
+    const removeConversations = useCallback(async (ids) => {
+        const remove = configRef.current.deleteConversations;
+        if (!remove)
+            throw new Error('This app cannot delete conversations.');
+        const open = conversationIdRef.current;
+        const removingOpen = open !== null && ids.includes(open);
+        if (removingOpen && isStreamingRef.current) {
+            throw new Error('That conversation is answering. Wait for it to finish, then delete it.');
+        }
+        addDebugLog('info', 'agent:api', `Deleting ${ids.length} conversation(s)`, { conversationIds: ids });
+        await remove(ids);
+        const gone = new Set(ids);
+        setListed(historyConversationsRef.current.filter(c => !gone.has(c.conversationId)));
+        if (removingOpen && conversationIdRef.current === open)
+            resetToNewConversation();
+    }, [addDebugLog, resetToNewConversation, setListed]);
+    const exportSession = useCallback(() => {
+        const session = {
+            exportedAt: new Date().toISOString(),
+            sdkVersion: '0.2.14',
+            session: {
+                conversationId,
+                currentTurnId,
+                connected,
+                isStreaming,
+                messageCount: messages.length,
+                messages: messages.map(m => ({
+                    id: m.id,
+                    role: m.role,
+                    content: m.content,
+                    timestamp: new Date(m.timestamp).toISOString(),
+                    isStreaming: m.isStreaming,
+                    toolCall: m.toolCall,
+                })),
+            },
+            debug: {
+                enabled: debugEnabled,
+                logCount: debugLogs.length,
+                logs: debugLogs,
+            },
+            environment: {
+                userAgent: typeof navigator !== 'undefined' ? navigator.userAgent : 'unknown',
+                url: typeof window !== 'undefined' ? window.location.href : 'unknown',
+                realtimeUrl: config.realtime.url,
+            },
+        };
+        const blob = new Blob([JSON.stringify(session, null, 2)], { type: 'application/json' });
+        const url = URL.createObjectURL(blob);
+        const a = document.createElement('a');
+        a.href = url;
+        const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+        a.download = `agent-session-${conversationId ?? 'no-conv'}-${stamp}.json`;
+        document.body.appendChild(a);
+        a.click();
+        document.body.removeChild(a);
+        URL.revokeObjectURL(url);
+    }, [conversationId, currentTurnId, connected, isStreaming, messages, debugEnabled, debugLogs, config.realtime.url]);
+    const debugState = {
+        enabled: debugEnabled,
+        setEnabled: setDebugEnabled,
+        logs: debugLogs,
+        clearLogs: clearDebugLogs,
+        namespaces: ALL_DEBUG_NAMESPACES,
+        exportSession,
+    };
+    const selectOption = useCallback((value) => {
+        setPresentedOptions(null);
+        sendMessage(value);
+    }, [sendMessage]);
+    const dismissOptions = useCallback(() => {
+        setPresentedOptions(null);
+    }, []);
+    const contextValue = {
+        isOpen,
+        toggle: useCallback(() => setIsOpen(p => !p), []),
+        open: useCallback(() => setIsOpen(true), []),
+        close: useCallback(() => setIsOpen(false), []),
+        sendMessage,
+        messages,
+        isStreaming,
+        isProcessing: isStreaming,
+        currentTurnId,
+        conversationId,
+        connected,
+        debug: debugState,
+        presentedOptions,
+        selectOption,
+        dismissOptions,
+        pendingApproval,
+        socket: socketRef.current,
+        history: {
+            available: Boolean(config.listConversations && config.getConversation),
+            manage: {
+                rename: Boolean(config.renameConversation),
+                update: Boolean(config.updateConversations),
+                remove: Boolean(config.deleteConversations),
+            },
+            conversations: historyConversations,
+            total: historyTotal,
+            filter: historyFilter,
+            loading: historyLoading,
+            error: historyError,
+            refresh: refreshHistory,
+            query: queryConversations,
+            rename: renameConversation,
+            update: updateConversations,
+            remove: removeConversations,
+            revision: historyRevision,
+        },
+        isLoadingConversation,
+        switchConversation,
+        startNewConversation,
+    };
+    const approvalDecision = {
+        pending: pendingApproval,
+        deciding: approvalDeciding,
+        error: approvalError,
+        decide: decideApproval,
+        dismiss: dismissApproval,
+    };
+    return React.createElement(AgentContext.Provider, { value: contextValue }, React.createElement(ApprovalDecisionContext.Provider, { value: approvalDecision }, children));
+}
+export function useAgent() {
+    const ctx = useContext(AgentContext);
+    if (!ctx)
+        throw new Error('useAgent must be used within an AgentProvider');
+    return ctx;
+}
+//# sourceMappingURL=AgentProvider.js.map