π OpenHands: AI-Driven Development
import React, {
createContext,
useContext,
useEffect,
useLayoutEffect,
useState,
useCallback,
useMemo,
useRef,
} from "react";
import { ConversationClient } from "@openhands/typescript-client/clients";
import { useQueryClient } from "@tanstack/react-query";
import { useWebSocket, WebSocketHookOptions } from "#/hooks/use-websocket";
import { usePageVisibilityReconnect } from "#/hooks/use-page-visibility-reconnect";
import { SERVER_CONNECTION_ERROR_MESSAGE } from "#/constants/server-connection-error";
import { useEventStore } from "#/stores/use-event-store";
import { useErrorMessageStore } from "#/stores/error-message-store";
import { useOptimisticUserMessageStore } from "#/stores/optimistic-user-message-store";
import { useConversationStateStore } from "#/stores/conversation-state-store";
import { useCommandStore } from "#/stores/command-store";
import { useBrowserStore } from "#/stores/browser-store";
import { useGoalStore } from "#/stores/goal-store";
import {
isAgentServerEvent,
isAgentErrorEvent,
isUserMessageEvent,
isActionEvent,
isConversationStateUpdateEvent,
isFullStateConversationStateUpdateEvent,
isAgentStatusConversationStateUpdateEvent,
isStatsConversationStateUpdateEvent,
isGoalConversationStateUpdateEvent,
isExecuteBashActionEvent,
isExecuteBashObservationEvent,
isDisplayableErrorEvent,
isPlanningFileEditorObservationEvent,
isBrowserObservationEvent,
isBrowserNavigateActionEvent,
isSwitchLLMObservationEvent,
isClassifyAndSwitchLLMObservationEvent,
isCanvasUIActionEvent,
isAutomationFormUpdateActionEvent,
isLaunchChildConversationActionEvent,
isRequestSecretActionEvent,
} from "#/types/agent-server/type-guards";
import {
asSessionFrame,
type SessionFrame,
} from "#/types/agent-server/session-frames";
import {
createStreamingDeltaBatcher,
StreamingDeltaBatcher,
} from "#/utils/streaming-delta-batcher";
import { handleCanvasUIAction } from "#/services/canvas-ui";
import { handleAutomationFormUpdateAction } from "#/services/automation-form";
import { handleLaunchChildConversationAction } from "#/services/child-conversation-launch";
import { handleRequestSecretAction } from "#/services/secret-request";
import { ConversationStateUpdateEventStats } from "#/types/agent-server/core/events/conversation-state-event";
import type {
ConversationErrorEvent,
ServerErrorEvent,
} from "#/types/agent-server/core/events/conversation-state-event";
import { handleActionEventCacheInvalidation } from "#/utils/cache-utils";
import { buildWebSocketUrl } from "#/utils/websocket-url";
import { createSeqCursor, type SeqCursor } from "#/utils/session-seq-cursor";
import type {
AppConversation,
SendMessageRequest,
} from "#/api/conversation-service/agent-server-conversation-service.types";
import EventService from "#/api/event-service/event-service.api";
import { getAgentServerClientOptions } from "#/api/agent-server-client-options";
import { getActiveBackend } from "#/api/backend-registry/active-store";
import { useConversationStore } from "#/stores/conversation-store";
import { trackError } from "#/utils/error-handler";
import { matchesPendingConversationId } from "#/utils/pending-task-message-link";
import { useReadConversationFile } from "#/hooks/mutation/use-read-conversation-file";
import useMetricsStore, { type MetricsState } from "#/stores/metrics-store";
import { useConversationHistory } from "#/hooks/query/use-conversation-history";
import { setConversationState } from "#/utils/conversation-local-storage";
import {
recordModelSwitchMessage,
seedModelSwitchesFromHistory,
stampActiveLlmProfile,
} from "#/hooks/chat/record-model-switch-message";
import {
invalidateConversationQueries,
updateConversationLlmModelInCache,
} from "#/hooks/mutation/conversation-mutation-utils";
import { isPlanFilePath } from "#/utils/plan-file";
export type WebSocketConnectionState =
| "CONNECTING"
| "OPEN"
| "CLOSED"
| "CLOSING";
/**
* A message submitted while its cloud conversation had no runtime URL yet
* (sandbox PAUSED/STARTING). Held until that conversation's socket opens.
*/
interface HeldMessage {
message: SendMessageRequest;
/** Whether an optimistic "sending" bubble existed when the message was held. */
hadBubble: boolean;
}
const heldMessageText = (message: SendMessageRequest): string =>
message.content
.map((item) => (item.type === "text" ? item.text : ""))
.join("");
interface SendMessageResult {
queued: boolean; // true if message was queued for later delivery, false if sent immediately
}
interface ConversationWebSocketContextType {
connectionState: WebSocketConnectionState;
/**
* The main connection's own state, unmerged with the planning connection β
* see `useMainWebSocketStatus`.
*/
mainConnectionState: WebSocketConnectionState;
sendMessage: (message: SendMessageRequest) => Promise<SendMessageResult>;
isLoadingHistory: boolean;
reconnect: () => void;
/**
* True once the main or planning socket has opened at least once for the
* current conversation. Lets the UI say "Reconnecting" instead of the
* first-connect "Connecting" β see `getStatusCode`.
*/
hasConnectedOnce: boolean;
}
const ConversationWebSocketContext = createContext<
ConversationWebSocketContextType | undefined
>(undefined);
/**
* Extract the text body of an echoed user `MessageEvent` for matching against
* the optimistic pending-message queue. The server wraps the original
* `args.content` string in one or more `TextContent` entries (alongside any
* `ImageContent` entries for inline images), so concatenating the `text`
* fields gives us back the exact prompt we sent.
*/
function extractMessageEventText(
event: import("#/types/agent-server/core/events/message-event").MessageEvent,
): string {
return event.llm_message.content
.filter(
(part): part is { type: "text"; text: string } => part.type === "text",
)
.map((part) => part.text)
.join("");
}
/**
* Route one frame of `/sockets/session/{id}`.
*
* Progress frames (`item_started` / `delta` / `item_aborted`) are applied to
* the streaming slot here and produce no event. Durable and transient frames
* are unwrapped and returned for the caller's normal event handling; a durable
* frame also advances the resume cursor and stamps its `seq` on the event, so
* the UI can place a slot relative to it.
*/
const routeSessionFrame = (
raw: unknown,
batcher: StreamingDeltaBatcher | null,
/** Report a durable frame's `seq` to this socket's resume cursor. */
advanceCursor: (seq: number) => void,
slotMeta: { isFromPlanningAgent?: boolean } = {},
): unknown | null => {
const frame: SessionFrame | null = asSessionFrame(raw);
if (!frame) {
return null;
}
if (frame.type === "delta") {
batcher?.enqueue(frame);
return null;
}
// Nothing else may overtake text that was streamed ahead of it.
batcher?.flush();
switch (frame.type) {
case "item_started":
useEventStore.getState().openStreamingSlot(frame, slotMeta);
return null;
case "item_aborted":
// Nothing durable is coming to supersede the provisional text.
useEventStore.getState().abortStreamingSlot(frame.item_id, frame.attempt);
return null;
case "durable":
advanceCursor(frame.seq);
return { ...frame.event, seq: frame.seq };
case "transient":
return frame.event;
case "error":
// The server answers a rejected inbound message with an ErrorFrame and
// keeps the socket open ("not worth dropping over"), so there is no
// reconnect and nothing else will ever surface this to the user.
useErrorMessageStore
.getState()
.setErrorMessage(frame.detail, "conversation", frame.code);
return null;
default:
// `sync` needs nothing: the cursor advances on durable frames.
return null;
}
};
export function ConversationWebSocketProvider({
children,
conversationId,
conversationUrl,
sessionApiKey,
subConversations,
subConversationIds,
}: {
children: React.ReactNode;
conversationId?: string;
conversationUrl?: string | null;
sessionApiKey?: string | null;
subConversations?: AppConversation[];
subConversationIds?: string[];
}) {
// Separate connection state tracking for each WebSocket
const [mainConnectionState, setMainConnectionState] =
useState<WebSocketConnectionState>("CONNECTING");
const [planningConnectionState, setPlanningConnectionState] =
useState<WebSocketConnectionState>("CONNECTING");
// Track if we've ever successfully connected for each connection
// Don't show errors until after first successful connection
const hasConnectedRefMain = React.useRef(false);
const hasConnectedRefPlanning = React.useRef(false);
const queryClient = useQueryClient();
const addEvent = useEventStore((state) => state.addEvent);
const addEvents = useEventStore((state) => state.addEvents);
const clearEventsForConversation = useEventStore(
(state) => state.clearEventsForConversation,
);
const { setErrorMessage, removeErrorMessage, clearConnectionError } =
useErrorMessageStore();
const consumeMatchingPendingMessage = useOptimisticUserMessageStore(
(state) => state.consumeMatchingPendingMessage,
);
const { setExecutionStatus } = useConversationStateStore();
const { appendInput, appendOutput } = useCommandStore();
const resetBrowserStore = useBrowserStore((state) => state.reset);
// Coalesce streaming deltas to β€1 store commit/render per frame.
// Separate batchers keep the main and planning streams from ever merging.
const mainDeltaBatcherRef = useRef<StreamingDeltaBatcher | null>(null);
if (mainDeltaBatcherRef.current === null) {
mainDeltaBatcherRef.current = createStreamingDeltaBatcher((frames) => {
useEventStore.getState().appendStreamingDeltas(frames);
// A delta means connectivity recovered β mirror handleNonErrorEvent.
useErrorMessageStore.getState().clearConnectionError();
});
}
const planningDeltaBatcherRef = useRef<StreamingDeltaBatcher | null>(null);
if (planningDeltaBatcherRef.current === null) {
planningDeltaBatcherRef.current = createStreamingDeltaBatcher((frames) => {
useEventStore
.getState()
.appendStreamingDeltas(frames, { isFromPlanningAgent: true });
useErrorMessageStore.getState().clearConnectionError();
});
}
// Resume cursors, one per socket. Started at connect time (see the lazy
// `queryParams` below) and advanced per durable frame without re-rendering.
const mainCursorRef = useRef<SeqCursor>(createSeqCursor());
const planningCursorRef = useRef<SeqCursor>(createSeqCursor());
// History loading state.
// - Main conversation history is now loaded via REST (`useConversationHistory`),
// so its loading state mirrors the REST query state (see below).
// - Planning sub-conversation history still streams over the WebSocket using
// `resend_mode='all'`, so we keep the count-based detection for it.
const [isLoadingHistoryPlanning, setIsLoadingHistoryPlanning] =
useState(true);
const [expectedEventCountPlanning, setExpectedEventCountPlanning] = useState<
number | null
>(null);
const { setPlanContent } = useConversationStore();
useEffect(() => {
setPlanContent(null);
}, [conversationId, setPlanContent]);
const { mutate: readConversationFile } = useReadConversationFile();
// Track planning-agent received events (still WS-driven).
const receivedEventCountRefPlanning = useRef(0);
// Track the latest PlanningFileEditorObservation for Plan.md during history replay
const latestPlanningFileEventRef = useRef<{
path: string;
conversationId: string;
} | null>(null);
const handleNonErrorEvent = useCallback(() => {
// A normal event means connectivity recovered: clear a transient connection
// error, but keep sticky conversation errors (e.g. a wrong API key).
clearConnectionError();
}, [clearConnectionError]);
// Helper function to update metrics from stats event
const updateMetricsFromStats = useCallback(
(event: ConversationStateUpdateEventStats) => {
const usageToMetrics = event.value.usage_to_metrics;
if (!usageToMetrics) {
return;
}
// usage_to_metrics is keyed by arbitrary LLM usage ids ("default",
// "condenser", "profile:<name>:<uuid>", β¦) β combine across all of
// them, mirroring getCombinedMetrics on the REST path.
const combined = Object.values(usageToMetrics).reduce<{
cost: number;
maxBudgetPerTask: number | null;
usage: MetricsState["usage"];
}>(
(acc, metrics) => {
acc.cost += metrics.accumulated_cost;
if (
acc.maxBudgetPerTask === null &&
metrics.max_budget_per_task !== null
) {
acc.maxBudgetPerTask = metrics.max_budget_per_task;
}
const tokenUsage = metrics.accumulated_token_usage;
if (tokenUsage) {
acc.usage = {
prompt_tokens:
(acc.usage?.prompt_tokens ?? 0) + tokenUsage.prompt_tokens,
completion_tokens:
(acc.usage?.completion_tokens ?? 0) +
tokenUsage.completion_tokens,
cache_read_tokens:
(acc.usage?.cache_read_tokens ?? 0) +
tokenUsage.cache_read_tokens,
cache_write_tokens:
(acc.usage?.cache_write_tokens ?? 0) +
tokenUsage.cache_write_tokens,
context_window: Math.max(
acc.usage?.context_window ?? 0,
tokenUsage.context_window,
),
per_turn_token: Math.max(
acc.usage?.per_turn_token ?? 0,
tokenUsage.per_turn_token,
),
};
}
return acc;
},
{ cost: 0, maxBudgetPerTask: null, usage: null },
);
useMetricsStore.getState().setMetrics({
cost: combined.cost,
max_budget_per_task: combined.maxBudgetPerTask,
usage: combined.usage,
});
},
[],
);
// Initial REST history load: fetch the most recent events and seed the
// store. Older events are paginated in via `useLoadOlderEvents` when the
// user scrolls to the top of the chat. The WebSocket connection waits for
// this query so it can subscribe with `resend_mode='since'` and avoid
// re-streaming everything REST already returned.
const { data: preloadedHistory, isPending: isPreloadingHistory } =
useConversationHistory(conversationId);
// Skeleton only on the genuine first load (no cached data yet). On return the
// cached page is present, so `isPending` is false and we render the
// last-known discussion immediately while the tail refetch runs in the
// background β the socket gate below also keys on `isPending`, so that
// refetch never drops a live socket.
const isLoadingHistoryMain = !!conversationId && isPreloadingHistory;
// First-connect cursor from the REST page (see `afterSeq`). Read lazily by
// the socket's `queryParams`; after the first connect the socket's own
// cursor takes over.
const historyAfterSeqRef = useRef<number | null>(null);
useEffect(() => {
historyAfterSeqRef.current = preloadedHistory?.afterSeq ?? null;
}, [preloadedHistory]);
// The planner has its own log: reset its cursor when it is a different one.
const planningSocketConversationId = subConversations?.[0]?.id ?? null;
useEffect(() => {
planningCursorRef.current.clear();
}, [planningSocketConversationId]);
// Clear the (global, not conversation-scoped) event store when the active
// conversation changes, BEFORE the preloaded-history effect below re-seeds
// it. This MUST live here rather than in the route component: a parent's
// passive effect runs *after* this child's layout effects, so clearing from
// the route would wipe the freshly seeded history. On a conversation switch
// the history page is already cached, so `preloadedHistory` is available
// synchronously β without ordering the clear first, the user's already-echoed
// message gets seeded then immediately wiped, leaving only the `since`
// WebSocket resend (the agent's reply). Re-entering the same conversation is
// a no-op, so the store survives navigating away to Settings and back.
useLayoutEffect(() => {
const nextId = conversationId ?? null;
if (useEventStore.getState().loadedConversationId === nextId) {
return;
}
// Single atomic action: clears the previous conversation's events and
// records the new loaded id in one `set`, so no subscriber can observe a
// half-applied state (events gone but the old id still reported).
clearEventsForConversation(nextId);
resetBrowserStore();
// The metrics store is conversation-scoped state too: without a reset the
// previous conversation's usage/cost keeps rendering in the new
// conversation's meter until fresh WS stats arrive β and a brand-new
// conversation sends none, so the stale figure stuck indefinitely.
useMetricsStore.getState().resetMetrics();
}, [conversationId, clearEventsForConversation, resetBrowserStore]);
useLayoutEffect(() => {
if (!preloadedHistory || preloadedHistory.events.length === 0) {
return;
}
addEvents(preloadedHistory.events);
// The first user message of a cloud start-task conversation is persisted
// server-side and reaches us via this REST preload, not over the WebSocket
// (which subscribes with resend_mode='since' after the latest preloaded
// timestamp). Consume any matching optimistic "Sendingβ¦" bubble here too β
// mirroring the WS handler β so it doesn't linger as a duplicate of the echo.
if (conversationId) {
// Rebuild inline "Switched to" messages from the REST-preloaded history.
// The live store writers (WS handler / user action) never see preloaded
// events, so without this past model switches wouldn't render on reload.
// Read the post-`addEvents` `uiEvents` (actions replaced by observations,
// Think/Finish observations dropped) β not the raw history β so anchors
// match the ids the renderer actually mounts.
seedModelSwitchesFromHistory(
conversationId,
useEventStore.getState().uiEvents,
);
for (const event of preloadedHistory.events) {
if (isUserMessageEvent(event)) {
consumeMatchingPendingMessage(
conversationId,
extractMessageEventText(event),
event,
);
}
}
}
}, [
preloadedHistory,
addEvents,
conversationId,
consumeMatchingPendingMessage,
]);
// Build WebSocket URL from props.
//
// We deliberately wait for the FIRST history load (`isPending`: no data for
// this query key yet) before opening the socket, so the WS subscription can
// use `resend_mode='since'` with a meaningful `after_timestamp` instead of
// falling back to `resend_mode='all'`. The gate is intentionally NOT on
// `isFetching`: background refetches (e.g. the `refetchOnMount` fired when
// returning to a conversation) must never tear a live socket down β on a
// flaky link that caused a refetch β teardown β reconnect β refetch loop
// that kept the conversation stuck at "Connecting" for minutes. Connecting
// during a background refetch anchors `since` to the cached tail; the
// overlap with the refetched page is deduped by the event store and the
// `isDuplicateEvent` guards in the message handlers. A query-key reset
// (backend swap / new session key) makes `isPending` true again, so a
// genuine reset still re-gates. If the initial load errors, `isPending`
// flips false and we fall through to connect with `resend_mode='all'` so
// the user still sees live events.
const wsUrl = useMemo(() => {
if (!conversationId || !conversationUrl) {
return null;
}
if (isPreloadingHistory) {
return null;
}
return buildWebSocketUrl(conversationId, conversationUrl);
}, [conversationId, conversationUrl, isPreloadingHistory]);
// Derived from `subConversationIds` (the pre-filtered, tag-verified id
// list) rather than the resolved `subConversations` entry, which lands a
// tick later β routing on it would leave a window where the first prompt
// sent in plan mode fell through to the parent (the code agent) instead of
// the planner.
const planningConversationId = useMemo(
() => subConversationIds?.[0] ?? null,
[subConversationIds],
);
const planningAgentWsUrl = useMemo(() => {
if (!subConversations?.length) {
return null;
}
// Currently, there is only one sub-conversation and it uses the planning agent.
const planningAgentConversation = subConversations[0];
if (
!planningAgentConversation?.id ||
!planningAgentConversation.conversation_url
) {
return null;
}
return buildWebSocketUrl(
planningAgentConversation.id,
planningAgentConversation.conversation_url,
);
}, [subConversations]);
// Merged connection state - reflects combined status of both connections
const connectionState = useMemo<WebSocketConnectionState>(() => {
// If planning agent connection doesn't exist, use main connection state
if (!planningAgentWsUrl) {
return mainConnectionState;
}
// If either is connecting, merged state is connecting
if (
mainConnectionState === "CONNECTING" ||
planningConnectionState === "CONNECTING"
) {
return "CONNECTING";
}
// If both are open, merged state is open
if (mainConnectionState === "OPEN" && planningConnectionState === "OPEN") {
return "OPEN";
}
// If both are closed, merged state is closed
if (
mainConnectionState === "CLOSED" &&
planningConnectionState === "CLOSED"
) {
return "CLOSED";
}
// If either is closing, merged state is closing
if (
mainConnectionState === "CLOSING" ||
planningConnectionState === "CLOSING"
) {
return "CLOSING";
}
// Default to closed if states don't match expected patterns
return "CLOSED";
}, [mainConnectionState, planningConnectionState, planningAgentWsUrl]);
useEffect(() => {
if (
expectedEventCountPlanning !== null &&
receivedEventCountRefPlanning.current >= expectedEventCountPlanning &&
isLoadingHistoryPlanning
) {
setIsLoadingHistoryPlanning(false);
}
}, [
expectedEventCountPlanning,
isLoadingHistoryPlanning,
receivedEventCountRefPlanning,
]);
// Call API once after history loading completes if we tracked any PlanningFileEditorObservation events
useEffect(() => {
if (!isLoadingHistoryPlanning && latestPlanningFileEventRef.current) {
const { path, conversationId: currentPlanningConversationId } =
latestPlanningFileEventRef.current;
readConversationFile(
{
conversationId: currentPlanningConversationId,
filePath: path,
},
{
onSuccess: (fileContent) => {
setPlanContent(fileContent);
},
onError: (error) => {
console.warn("Failed to read conversation file:", error);
},
},
);
// Clear the ref after calling the API
latestPlanningFileEventRef.current = null;
}
}, [isLoadingHistoryPlanning, readConversationFile, setPlanContent]);
useEffect(() => {
hasConnectedRefMain.current = false;
setIsLoadingHistoryPlanning(!!subConversationIds?.length);
setExpectedEventCountPlanning(null);
receivedEventCountRefPlanning.current = 0;
// Reset the tracked event ref when sub-conversations change
latestPlanningFileEventRef.current = null;
}, [subConversationIds]);
// Reset hasConnected flags when the conversation changes.
useEffect(() => {
hasConnectedRefMain.current = false;
hasConnectedRefPlanning.current = false;
// A cursor is a position in one conversation's log; carrying it into the
// next would skip that conversation's events below it.
mainCursorRef.current.clear();
// Reset the tracked event ref when conversation changes
latestPlanningFileEventRef.current = null;
}, [conversationId]);
// Drop buffered deltas on conversation switch/unmount: the store is cleared on
// switch, so flushing them would leak into the next conversation.
useEffect(() => {
const mainBatcher = mainDeltaBatcherRef.current;
const planningBatcher = planningDeltaBatcherRef.current;
return () => {
mainBatcher?.reset();
planningBatcher?.reset();
};
}, [conversationId]);
// Merged loading history state - true if either connection is still loading
const isLoadingHistory = useMemo(
() => isLoadingHistoryMain || isLoadingHistoryPlanning,
[isLoadingHistoryMain, isLoadingHistoryPlanning],
);
// Separate message handlers for each connection
const handleMainMessage = useCallback(
(messageEvent: MessageEvent) => {
try {
const event = routeSessionFrame(
JSON.parse(messageEvent.data),
mainDeltaBatcherRef.current,
mainCursorRef.current.observe,
);
// History loading for the main conversation is REST-driven now;
// every durable frame is a new event we add to the store.
// Use type guard to validate v1 event structure
if (isAgentServerEvent(event)) {
// A reconnect replays the backlog from a stale anchor. The store
// dedups by id, but the side-effects below aren't idempotent, so skip
// them for replayed events (#1656).
const isDuplicateEvent = useEventStore
.getState()
.eventIds.has(event.id ?? "");
const switchLLMObservation = isSwitchLLMObservationEvent(event)
? event
: null;
const classifyAndSwitchLLMObservation =
isClassifyAndSwitchLLMObservationEvent(event) ? event : null;
addEvent(event);
if (isDuplicateEvent) {
return;
}
// Handle displayable error events - show error banner
// AgentErrorEvent errors are displayed inline in the chat, not as banners
if (isDisplayableErrorEvent(event)) {
const errorEvent = event as
| ConversationErrorEvent
| ServerErrorEvent;
const classification =
"classification" in errorEvent ? errorEvent.classification : null;
trackError({
source: "conversation",
metadata: {
eventId: errorEvent.id,
errorCode: errorEvent.code,
},
classification,
});
setErrorMessage(
errorEvent.detail,
"conversation",
errorEvent.code,
classification,
);
} else {
handleNonErrorEvent();
}
// LLM errors render inline in the chat (see ErrorEventMessage); track
// them for analytics but keep them out of the banner above the chat box.
if (isAgentErrorEvent(event)) {
trackError({
source: "agent",
metadata: {
eventId: event.id,
toolName: event.tool_name,
toolCallId: event.tool_call_id,
},
classification: event.classification,
});
}
// Clear optimistic user message when a user message is confirmed.
// History and live delivery share the same timestamp/identity checks.
if (isUserMessageEvent(event)) {
if (conversationId) {
consumeMatchingPendingMessage(
conversationId,
extractMessageEventText(event),
event,
);
// Clear draft from localStorage - message was successfully delivered
setConversationState(conversationId, { draftMessage: null });
}
}
// Handle cache invalidation for ActionEvent. The main WebSocket only
// opens when `conversationId` is present (see `wsUrl` below), so it
// is always defined for events arriving over this socket.
if (isActionEvent(event) && conversationId) {
handleActionEventCacheInvalidation(
event,
conversationId,
queryClient,
);
}
// Handle conversation state updates
if (isConversationStateUpdateEvent(event)) {
if (
isFullStateConversationStateUpdateEvent(event) &&
conversationId
) {
setExecutionStatus(conversationId, event.value.execution_status);
}
if (
isAgentStatusConversationStateUpdateEvent(event) &&
conversationId
) {
setExecutionStatus(conversationId, event.value);
}
if (isStatsConversationStateUpdateEvent(event)) {
updateMetricsFromStats(event);
}
// Mirror goal status into the store. Intentionally duplicated across
// the main and planning WebSocket handlers (like the execution_status
// and stats branches above), not a merge artifact.
if (isGoalConversationStateUpdateEvent(event) && conversationId) {
useGoalStore.getState().setStatus(conversationId, event.value);
}
}
// Handle ExecuteBashAction events - add command as input to terminal
if (isExecuteBashActionEvent(event)) {
appendInput(event.action.command);
}
// Handle ExecuteBashObservation events - add output to terminal
if (isExecuteBashObservationEvent(event)) {
// Extract text content from the observation content array
const textContent = event.observation.content
.filter((c) => c.type === "text")
.map((c) => c.text)
.join("\n");
appendOutput(textContent);
}
// Handle BrowserObservation events - update browser store with screenshot
if (isBrowserObservationEvent(event)) {
const { screenshot_data: screenshotData } = event.observation;
if (screenshotData) {
const screenshotSrc = screenshotData.startsWith("data:")
? screenshotData
: `data:image/png;base64,${screenshotData}`;
useBrowserStore.getState().setScreenshotSrc(screenshotSrc);
}
}
// Handle BrowserNavigateAction events - update browser store with URL
if (isBrowserNavigateActionEvent(event)) {
useBrowserStore.getState().setUrl(event.action.url);
}
if (
conversationId &&
switchLLMObservation &&
!switchLLMObservation.observation.is_error
) {
recordModelSwitchMessage(
conversationId,
switchLLMObservation.observation.profile_name,
);
// Mirror the user-driven `/model` path: persist the profile so the
// chat-header switcher shows the right name after a reload, even
// when several profiles share a model (#1082). Stamp with the
// observation's own timestamp so a later history seed of this same
// event can't roll it back (or needlessly rewrite it).
stampActiveLlmProfile(
conversationId,
switchLLMObservation.observation.profile_name,
switchLLMObservation.timestamp,
);
if (switchLLMObservation.observation.active_model) {
updateConversationLlmModelInCache(
queryClient,
conversationId,
switchLLMObservation.observation.active_model,
);
}
invalidateConversationQueries(queryClient, conversationId);
}
// Router-driven model switch (Router/meta-profile classifier).
// Same UI semantics as SwitchLLMObservation: update the combobox,
// stamp the active profile, record the inline "Switched to"
// message. Per the SDK wire contract, `model` is the saved LLM
// profile name that was activated and `active_model` is the
// underlying model string β so the profile stamp and inline
// message use `model` (mirroring SwitchLLMObservation.profile_name),
// while the combobox cache update uses `active_model`.
if (
conversationId &&
classifyAndSwitchLLMObservation &&
!classifyAndSwitchLLMObservation.observation.is_error &&
classifyAndSwitchLLMObservation.observation.model
) {
const profileName =
classifyAndSwitchLLMObservation.observation.model;
recordModelSwitchMessage(conversationId, profileName);
stampActiveLlmProfile(
conversationId,
profileName,
classifyAndSwitchLLMObservation.timestamp,
);
if (classifyAndSwitchLLMObservation.observation.active_model) {
updateConversationLlmModelInCache(
queryClient,
conversationId,
classifyAndSwitchLLMObservation.observation.active_model,
);
}
invalidateConversationQueries(queryClient, conversationId);
}
// Handle canvas_ui ActionEvents from both the legacy Python tool and
// the client-defined JSON tool. The server acknowledges immediately;
// the actual UI change happens here on the client.
if (isCanvasUIActionEvent(event)) {
handleCanvasUIAction(event.action, conversationId ?? null);
}
if (isAutomationFormUpdateActionEvent(event)) {
handleAutomationFormUpdateAction(
event.action,
conversationId ?? null,
event.id,
event.timestamp,
);
}
// Same client-tool pattern, but the work is a network call: launch
// the requested child conversation and post the outcome back so the
// agent learns the id the server-side acknowledgement can't carry.
if (conversationId && isLaunchChildConversationActionEvent(event)) {
void handleLaunchChildConversationAction(
event.action,
conversationId,
event.tool_call_id,
);
}
// Same pattern again: the user answers in a chat card, and the
// outcome is posted back once they save or cancel it.
if (conversationId && isRequestSecretActionEvent(event)) {
void handleRequestSecretAction(
event.action,
conversationId,
event.tool_call_id,
);
}
}
} catch (error) {
console.warn("Failed to parse WebSocket message as JSON:", error);
}
},
[
addEvent,
setErrorMessage,
consumeMatchingPendingMessage,
queryClient,
conversationId,
setExecutionStatus,
appendInput,
appendOutput,
updateMetricsFromStats,
handleNonErrorEvent,
],
);
const handlePlanningMessage = useCallback(
(messageEvent: MessageEvent) => {
try {
const event = routeSessionFrame(
JSON.parse(messageEvent.data),
planningDeltaBatcherRef.current,
planningCursorRef.current.observe,
{ isFromPlanningAgent: true },
);
if (event === null) {
return;
}
// Track received events for history loading. Only events count:
// progress frames are not part of the replayed log.
if (isLoadingHistoryPlanning) {
receivedEventCountRefPlanning.current += 1;
if (
expectedEventCountPlanning !== null &&
receivedEventCountRefPlanning.current >= expectedEventCountPlanning
) {
setIsLoadingHistoryPlanning(false);
}
}
// Use type guard to validate v1 event structure
if (isAgentServerEvent(event)) {
// Skip non-idempotent side-effects for replayed events, as in the
// main handler (#1656).
const isDuplicateEvent = useEventStore
.getState()
.eventIds.has(event.id ?? "");
// Mark this event as coming from the planning agent
const eventWithPlanningFlag = {
...event,
isFromPlanningAgent: true,
};
addEvent(eventWithPlanningFlag);
if (isDuplicateEvent) {
return;
}
// Handle displayable error events - show error banner
// AgentErrorEvent errors are displayed inline in the chat, not as banners
if (isDisplayableErrorEvent(event)) {
const errorEvent = event as
| ConversationErrorEvent
| ServerErrorEvent;
const classification =
"classification" in errorEvent ? errorEvent.classification : null;
trackError({
source: "planning_conversation",
metadata: {
eventId: errorEvent.id,
errorCode: errorEvent.code,
},
classification,
});
setErrorMessage(
errorEvent.detail,
"conversation",
errorEvent.code,
classification,
);
} else {
handleNonErrorEvent();
}
// LLM errors render inline in the chat (see ErrorEventMessage); track
// them for analytics but keep them out of the banner above the chat box.
if (isAgentErrorEvent(event)) {
trackError({
source: "planning_agent",
metadata: {
eventId: event.id,
toolName: event.tool_name,
toolCallId: event.tool_call_id,
},
classification: event.classification,
});
}
// Clear optimistic user message when a user message is confirmed.
// Always scope to the main `conversationId` (where the user types)
// and match on the echoed content so the planning sub-agent's own
// events can never consume a main-conversation pending entry.
if (isUserMessageEvent(event)) {
if (conversationId) {
consumeMatchingPendingMessage(
conversationId,
extractMessageEventText(event),
event,
);
setConversationState(conversationId, { draftMessage: null });
}
}
// Handle cache invalidation for ActionEvent. The planning socket only
// opens when the first sub-conversation has an id (see
// `planningAgentWsUrl` below), so it is always defined here.
if (isActionEvent(event)) {
const planningAgentConversation = subConversations?.[0];
if (planningAgentConversation?.id) {
handleActionEventCacheInvalidation(
event,
planningAgentConversation.id,
queryClient,
);
}
}
// Handle conversation state updates
if (isConversationStateUpdateEvent(event)) {
// Scope to the planning agent's own conversation id, not the main
// `conversationId` β this socket reports the planning helper
// conversation's run/idle transitions, which must never overwrite
// the main conversation's status in the shared store.
if (
isFullStateConversationStateUpdateEvent(event) &&
planningConversationId
) {
setExecutionStatus(
planningConversationId,
event.value.execution_status,
);
}
if (
isAgentStatusConversationStateUpdateEvent(event) &&
planningConversationId
) {
setExecutionStatus(planningConversationId, event.value);
}
if (isStatsConversationStateUpdateEvent(event)) {
updateMetricsFromStats(event);
}
// Mirror goal status into the store. Intentionally duplicated across
// the main and planning WebSocket handlers (like the execution_status
// and stats branches above), not a merge artifact.
if (isGoalConversationStateUpdateEvent(event) && conversationId) {
useGoalStore.getState().setStatus(conversationId, event.value);
}
}
// Handle ExecuteBashAction events - add command as input to terminal
if (isExecuteBashActionEvent(event)) {
appendInput(event.action.command);
}
// Handle ExecuteBashObservation events - add output to terminal
if (isExecuteBashObservationEvent(event)) {
// Extract text content from the observation content array
const textContent = event.observation.content
.filter((c) => c.type === "text")
.map((c) => c.text)
.join("\n");
appendOutput(textContent);
}
// Handle PlanningFileEditorObservation - only update plan for Plan.md
if (isPlanningFileEditorObservationEvent(event)) {
const { path } = event.observation;
if (isPlanFilePath(path)) {
const planningAgentConversation = subConversations?.[0];
const planningConversationId = planningAgentConversation?.id;
if (planningConversationId && path) {
if (isLoadingHistoryPlanning) {
latestPlanningFileEventRef.current = {
path,
conversationId: planningConversationId,
};
} else {
readConversationFile(
{
conversationId: planningConversationId,
filePath: path,
},
{
onSuccess: (fileContent) => {
setPlanContent(fileContent);
},
onError: (error) => {
console.warn(
"Failed to read conversation file:",
error,
);
},
},
);
}
}
}
}
}
} catch (error) {
console.warn("Failed to parse WebSocket message as JSON:", error);
}
},
[
addEvent,
isLoadingHistoryPlanning,
expectedEventCountPlanning,
setErrorMessage,
consumeMatchingPendingMessage,
queryClient,
subConversations,
planningConversationId,
conversationId,
setExecutionStatus,
appendInput,
appendOutput,
readConversationFile,
setPlanContent,
updateMetricsFromStats,
handleNonErrorEvent,
],
);
// Separate WebSocket options for main connection
const mainWebsocketOptions: WebSocketHookOptions = useMemo(() => {
// `after_seq` replaces the legacy resend_mode/after_timestamp pair, which
// compared naive local timestamps. Resolved lazily so a reconnect resumes
// from the newest `seq` this socket actually saw rather than from a value
// captured at render. The first connect has no cursor and asks for the
// whole log (`-1`); the REST preload (`useConversationHistory`) still
// renders instantly and the event store dedupes the overlap by id.
const queryParams = () => {
const cursor = mainCursorRef.current;
cursor.start(cursor.value ?? historyAfterSeqRef.current ?? -1);
return { after_seq: String(cursor.value) };
};
return {
queryParams,
sessionApiKey,
reconnect: { enabled: true },
onOpen: () => {
setMainConnectionState("OPEN");
hasConnectedRefMain.current = true; // Mark that we've successfully connected
clearConnectionError(); // Clear a previous connection error; keep sticky conversation errors
// Progress frames are never replayed, so any slot left open across the
// gap can never be retired. Discard and wait: the durable message is
// coming on the cursor regardless.
mainDeltaBatcherRef.current?.reset();
useEventStore.getState().clearStreamingSlots();
},
onClose: () => {
setMainConnectionState("CLOSED");
mainDeltaBatcherRef.current?.reset();
useEventStore.getState().clearStreamingSlots();
},
onError: () => {
setMainConnectionState("CLOSED");
// Only show an error if we've previously connected successfully, and
// the page is actually visible: a hidden tab is never watching this
// banner, and a background-caused drop (mobile freezing the tab) is
// about to be cleaned up and silently retried by
// `usePageVisibilityReconnect` the moment the tab is foregrounded β
// surfacing "Unable to connect" for it would just be a stale flash
// the user sees on return instead of "Reconnecting".
if (
hasConnectedRefMain.current &&
document.visibilityState !== "hidden"
) {
setErrorMessage(SERVER_CONNECTION_ERROR_MESSAGE, "connection");
}
},
onMessage: handleMainMessage,
};
}, [handleMainMessage, setErrorMessage, clearConnectionError, sessionApiKey]);
// Separate WebSocket options for planning agent connection
const planningWebsocketOptions: WebSocketHookOptions = useMemo(() => {
// The planner's history is not preloaded over REST, so it always replays
// from the start on a first connect and from its cursor after that.
const queryParams = () => {
const cursor = planningCursorRef.current;
cursor.start(cursor.value ?? -1);
return { after_seq: String(cursor.value) };
};
const planningAgentConversation = subConversations?.[0];
const planningApiKey =
planningAgentConversation?.session_api_key ?? sessionApiKey;
return {
queryParams,
sessionApiKey: planningApiKey,
reconnect: { enabled: true },
onOpen: async () => {
setPlanningConnectionState("OPEN");
hasConnectedRefPlanning.current = true; // Mark that we've successfully connected
clearConnectionError(); // Clear a previous connection error; keep sticky conversation errors
// See the main socket: an open slot cannot survive the gap.
planningDeltaBatcherRef.current?.reset();
useEventStore.getState().clearStreamingSlots(true);
// Fetch expected event count for history loading detection
if (
planningAgentConversation?.id &&
planningAgentConversation.conversation_url
) {
try {
const count = await EventService.getEventCount(
planningAgentConversation.id,
planningAgentConversation.conversation_url,
planningAgentConversation.session_api_key,
);
setExpectedEventCountPlanning(count);
// If no events expected, mark as loaded immediately
if (count === 0) {
setIsLoadingHistoryPlanning(false);
}
} catch (error) {
// Fall back to marking as loaded to avoid infinite loading state
setIsLoadingHistoryPlanning(false);
}
}
},
onClose: () => {
setPlanningConnectionState("CLOSED");
planningDeltaBatcherRef.current?.reset();
useEventStore.getState().clearStreamingSlots(true);
},
onError: () => {
setPlanningConnectionState("CLOSED");
// See the main socket's onError: skip the banner for a hidden-tab
// drop, which is about to be silently retried on foreground.
if (
hasConnectedRefPlanning.current &&
document.visibilityState !== "hidden"
) {
setErrorMessage(SERVER_CONNECTION_ERROR_MESSAGE, "connection");
}
},
onMessage: handlePlanningMessage,
};
}, [
handlePlanningMessage,
setErrorMessage,
clearConnectionError,
sessionApiKey,
subConversations,
]);
// Only attempt WebSocket connection when we have a valid URL
// This prevents connection attempts during task polling phase
const websocketUrl = wsUrl;
const {
socket: mainSocket,
reconnect: reconnectMain,
disconnect: disconnectMain,
} = useWebSocket(websocketUrl || "", mainWebsocketOptions);
const {
socket: planningAgentSocket,
reconnect: reconnectPlanning,
disconnect: disconnectPlanning,
} = useWebSocket(planningAgentWsUrl || "", planningWebsocketOptions);
// Messages submitted on a cloud backend while the target conversation has
// no runtime URL (sandbox PAUSED/STARTING) have nowhere to go: the V1 agent
// server only exists once the sandbox is RUNNING. Hold them per target
// conversation and send them when that conversation's socket opens. The
// caller's optimistic bubble stays in "sending" until the echo lands.
const heldMessagesRef = useRef(new Map<string, HeldMessage[]>());
const hasSendingBubble = useCallback(
(targetConversationId: string, message: SendMessageRequest) => {
const text = heldMessageText(message).trim();
return useOptimisticUserMessageStore
.getState()
.pendingMessages.some(
(pending) =>
pending.status === "sending" &&
matchesPendingConversationId(
targetConversationId,
pending.conversationId,
) &&
pending.content.trim() === text,
);
},
[],
);
const flushHeldMessages = useCallback(
(targetConversationId: string, socket: WebSocket) => {
if (socket.readyState !== WebSocket.OPEN) return;
const held = heldMessagesRef.current.get(targetConversationId);
if (!held?.length) return;
heldMessagesRef.current.delete(targetConversationId);
held.forEach(({ message, hadBubble }) => {
// A bubble the user stopped (or that timed out into Retry) withdraws
// its message; everything else goes out exactly as a live send would.
if (hadBubble && !hasSendingBubble(targetConversationId, message)) {
return;
}
socket.send(JSON.stringify({ ...message, run: true }));
});
},
[hasSendingBubble],
);
useEffect(() => {
if (mainConnectionState !== "OPEN" || !mainSocket || !conversationId) {
return;
}
flushHeldMessages(conversationId, mainSocket);
}, [mainConnectionState, mainSocket, conversationId, flushHeldMessages]);
useEffect(() => {
if (
planningConnectionState !== "OPEN" ||
!planningAgentSocket ||
!planningConversationId
) {
return;
}
flushHeldMessages(planningConversationId, planningAgentSocket);
}, [
planningConnectionState,
planningAgentSocket,
planningConversationId,
flushHeldMessages,
]);
const reconnect = useCallback(() => {
removeErrorMessage();
const currentMode = useConversationStore.getState().conversationMode;
if (currentMode === "plan" && planningAgentWsUrl) {
reconnectPlanning();
return;
}
reconnectMain();
}, [
planningAgentWsUrl,
reconnectMain,
reconnectPlanning,
removeErrorMessage,
]);
// Mobile browsers freeze and discard backgrounded tabs, silently killing
// the socket; this pre-empts that with a clean close on the way out and an
// immediate, explicit reconnect on the way back β see
// `usePageVisibilityReconnect` for the full rationale. Both sockets are
// covered regardless of `conversationMode`: a mode switch while
// backgrounded must not leave the *other* one stale.
const disconnectForBackground = useCallback(() => {
disconnectMain();
disconnectPlanning();
}, [disconnectMain, disconnectPlanning]);
const reconnectStaleOnForeground = useCallback(() => {
// Drop any "Unable to connect" banner left over from a background-caused
// close the instant the tab is foregrounded, so the UI reads
// "Reconnecting" (via `hasConnectedOnce`) rather than a stale error while
// the reconnect below is in flight. `clearConnectionError` only clears
// the connection-classified message, leaving any unrelated sticky error
// (e.g. a misconfigured API key) untouched.
clearConnectionError();
if (websocketUrl && mainConnectionState !== "OPEN") {
reconnectMain();
}
if (planningAgentWsUrl && planningConnectionState !== "OPEN") {
reconnectPlanning();
}
}, [
websocketUrl,
mainConnectionState,
planningAgentWsUrl,
planningConnectionState,
reconnectMain,
reconnectPlanning,
clearConnectionError,
]);
usePageVisibilityReconnect({
enabled: !!(websocketUrl || planningAgentWsUrl),
disconnect: disconnectForBackground,
reconnectIfStale: reconnectStaleOnForeground,
});
// V1 send message function via WebSocket.
// When the socket is not connected: on a cloud backend whose runtime has
// no URL yet, hold the message until the socket opens; otherwise post it
// straight to the runtime.
const sendMessage = useCallback(
async (message: SendMessageRequest): Promise<SendMessageResult> => {
const currentMode = useConversationStore.getState().conversationMode;
const currentSocket =
currentMode === "plan" ? planningAgentSocket : mainSocket;
const targetConversationId =
currentMode === "plan" ? planningConversationId : conversationId;
if (currentSocket?.readyState !== WebSocket.OPEN) {
// WebSocket not connected.
if (!targetConversationId) {
// Never fall back to the parent in plan mode: without a planner
// target the message would run in the code agent, which is exactly
// the boundary plan mode exists to enforce.
const error = new Error(
currentMode === "plan"
? "Planning conversation is not ready yet"
: "No conversation ID available",
);
setErrorMessage(error.message);
throw error;
}
// Runtime coordinates for the target. A cloud runtime only has a URL
// (and session key) while its sandbox is RUNNING.
const planningAgentConversation = subConversations?.[0];
const runtimeUrl =
currentMode === "plan"
? planningAgentConversation?.conversation_url
: conversationUrl;
const runtimeApiKey =
currentMode === "plan"
? planningAgentConversation?.session_api_key
: sessionApiKey;
if (getActiveBackend().backend.kind === "cloud" && !runtimeUrl) {
// Nothing to deliver to yet (sandbox PAUSED/STARTING). Hold the
// message for `flushHeldMessages`; the caller's bubble stays in
// "sending". Not an error, so no banner.
const held = heldMessagesRef.current.get(targetConversationId) ?? [];
const serialized = JSON.stringify(message);
if (
!held.some((entry) => JSON.stringify(entry.message) === serialized)
) {
held.push({
message,
hadBubble: hasSendingBubble(targetConversationId, message),
});
heldMessagesRef.current.set(targetConversationId, held);
}
return { queued: true };
}
// The runtime is reachable: post the message to it directly. It is
// delivered immediately and shows up in the socket's history replay.
try {
await new ConversationClient(
getAgentServerClientOptions({
conversationUrl: runtimeUrl,
sessionApiKey: runtimeApiKey,
}),
).sendEvent(
targetConversationId,
{
role: "user",
content: message.content,
},
{ run: true },
);
// Return queued: true so the caller knows the socket did not carry it
return { queued: true };
} catch (error) {
const errorMessage =
error instanceof Error
? error.message
: "Failed to queue message for delivery";
setErrorMessage(errorMessage);
throw error;
}
}
try {
// Send message through WebSocket as JSON with run: true so the
// agent loop starts automatically in async mode.
currentSocket.send(JSON.stringify({ ...message, run: true }));
return { queued: false };
} catch (error) {
const errorMessage =
error instanceof Error ? error.message : "Failed to send message";
setErrorMessage(errorMessage);
throw error;
}
},
[
mainSocket,
planningAgentSocket,
setErrorMessage,
conversationId,
planningConversationId,
conversationUrl,
sessionApiKey,
subConversations,
hasSendingBubble,
],
);
// Track main socket state changes
useEffect(() => {
// Only process socket updates if we have a valid URL and socket
if (mainSocket && wsUrl) {
// Update state based on socket readyState
const updateState = () => {
switch (mainSocket.readyState) {
case WebSocket.CONNECTING:
setMainConnectionState("CONNECTING");
break;
case WebSocket.OPEN:
setMainConnectionState("OPEN");
break;
case WebSocket.CLOSING:
setMainConnectionState("CLOSING");
break;
case WebSocket.CLOSED:
setMainConnectionState("CLOSED");
break;
default:
setMainConnectionState("CLOSED");
break;
}
};
updateState();
}
}, [mainSocket, wsUrl]);
// Track planning agent socket state changes
useEffect(() => {
// Only process socket updates if we have a valid URL and socket
if (planningAgentSocket && planningAgentWsUrl) {
// Update state based on socket readyState
const updateState = () => {
switch (planningAgentSocket.readyState) {
case WebSocket.CONNECTING:
setPlanningConnectionState("CONNECTING");
break;
case WebSocket.OPEN:
setPlanningConnectionState("OPEN");
break;
case WebSocket.CLOSING:
setPlanningConnectionState("CLOSING");
break;
case WebSocket.CLOSED:
setPlanningConnectionState("CLOSED");
break;
default:
setPlanningConnectionState("CLOSED");
break;
}
};
updateState();
}
}, [planningAgentSocket, planningAgentWsUrl]);
const contextValue = useMemo(
() => ({
connectionState,
mainConnectionState,
sendMessage,
isLoadingHistory,
reconnect,
hasConnectedOnce:
hasConnectedRefMain.current || hasConnectedRefPlanning.current,
}),
[
connectionState,
mainConnectionState,
planningConnectionState,
sendMessage,
isLoadingHistory,
reconnect,
],
);
return (
<ConversationWebSocketContext.Provider value={contextValue}>
{children}
</ConversationWebSocketContext.Provider>
);
}
export const useConversationWebSocket =
(): ConversationWebSocketContextType | null => {
const context = useContext(ConversationWebSocketContext);
// Return null instead of throwing when not in provider
// This allows the hook to be called conditionally based on conversation version
return context || null;
};