import { useCallback, useEffect, useMemo, useRef, useState } from 'react'; import { v4 } from 'uuid'; import { useAtom, useSetAtom, useStore } from 'jotai'; import { Clock, OctagonPause, X, Zap } from 'lucide-react'; import { dataService, ForkOptions } from 'librechat-data-provider'; import { Alert, Button, Composer, ControlCombobox, useMediaQuery, useToastContext, } from '@librechat/client'; import type { ParentSubagentTaskSummary, SubagentControlAction, SubagentControlReceipt, SubagentControlRequest, } from 'librechat-data-provider'; import type { ComposerKeyVerdict, ComposerStopProps, SendAction } from '@librechat/client'; import type { KeyboardEvent as ReactKeyboardEvent, ReactNode } from 'react'; import type { ActiveSubagentPanel, SubagentControlUiState } from './state'; import type { ComposerKeyAction } from '~/utils/shortcuts'; import type { OptionWithIcon } from '~/common'; import { ACTIVE_THREAD_REFRESH_MS, subagentThreadHasTaskEvidence, useForkConvoMutation, useToolCallPartQuery, useSubagentControlMutation, useSubagentThreadQuery, } from '~/data-provider'; import { adaptDurableThreadActivity, adaptDurableThreadConversation, adaptLivePersistedActivity, mergeChildConversationTurns, retainBoundedMovingWindowTurns, } from './adapters'; import { agentAuthor, resolveSubagentAuthor, isSelfSpawn as isSelfSpawnType, resolveChildAgent, readableSubagentType, useParentAuthor, } from './author'; import { activeSubagentPanel, subagentControlStateByTask, subagentControlStateKey, subagentProgressKey, useSubagentProgress, } from './state'; import useSubagentActivityStream from '~/data-provider/Subagents/useSubagentActivityStream'; import SubagentActivity, { SubagentActivityScrollSurface } from './SubagentActivity'; import ApprovalProvider from '~/components/Chat/Messages/Content/ApprovalContext'; import { isMacPlatform, resolveComposerKeyDown } from '~/utils/shortcuts'; import { useFocusTrap, useLocalize, useNavigateToConvo } from '~/hooks'; import { ARTIFACTS_SHEET_MAX_WIDTH } from '~/utils/breakpoints'; import { useConfiguredFooter } from '~/components/Chat/Footer'; import { useParentSubagents } from './ParentSubagentsProvider'; import useScaledMaxWidth from '~/hooks/useScaledMaxWidth'; import SubagentConversation from './SubagentConversation'; import { eventSubagentSelection } from './eventSelection'; import { resolveSubagentAgentId } from './identity'; import { useAgentsMapContext } from '~/Providers'; import { isLiveSubagentStatus } from './status'; import { cn, renderAgentAvatar } from '~/utils'; import { getSubagentPrompt } from './prompt'; import { useChatSurface } from './surface'; const EVENT_TASK_PAGE_SIZE = 3; const TERMINAL_CONTROL_REASONS = new Set([ 'task_not_running', 'task_completed', 'task_cancelled', 'task_failed', ]); const isTerminalControlReason = (reason?: string): boolean => reason != null && TERMINAL_CONTROL_REASONS.has(reason); const closesTaskControls = (receipt: SubagentControlReceipt): boolean => isTerminalControlReason(receipt.reason) || (receipt.action === 'cancel' && receipt.status === 'applied'); const responseStatus = (error: unknown): number | undefined => typeof error === 'object' && error != null && 'response' in error && typeof error.response === 'object' && error.response != null && 'status' in error.response && typeof error.response.status === 'number' ? error.response.status : undefined; const failedControlReason = ( inaccessible: boolean, retryable: boolean, ): 'task_inaccessible' | 'owner_unavailable' | 'invalid_command' => { if (inaccessible) return 'task_inaccessible'; if (retryable) return 'owner_unavailable'; return 'invalid_command'; }; /** Which control a during-run verdict asks for. `submit` is whatever the * reader's own key policy treats as the default — with Enter-to-send off that * is ⌘/Ctrl+Enter, which is why the chord is never read raw. */ const CONTROL_FOR_ACTION = { submit: 'steer', other: 'queue', interrupt: 'interrupt', preempt: 'interrupt', } as const satisfies Partial>; const failedControlLocaleKey = (reason?: string) => { if (reason === 'task_inaccessible') return 'com_ui_subagent_control_reason_task_inaccessible'; if (reason === 'owner_unavailable') return 'com_ui_subagent_control_reason_owner_unavailable'; return 'com_ui_subagent_control_reason_invalid_command'; }; export default function SubagentThreadPanel({ selection }: { selection: ActiveSubagentPanel }) { /** The shell carries the deployment's answer, so this surface lays out once, * like the composer beside it. */ const clearsFooter = useConfiguredFooter(); const localize = useLocalize(); const panelStore = useStore(); const { showToast } = useToastContext(); const { navigateToConvo } = useNavigateToConvo(); const panelRef = useRef(null); const isMobile = useScaledMaxWidth(ARTIFACTS_SHEET_MAX_WIDTH); /** Two reasons the send control's action list cannot be used where it hangs. * Without hover, a tap on its anchor submits instead of opening it. And * while the panel is a focus-trapped modal, the list is portaled outside the * `aside` the trap knows, so Tab never reaches it. Either way those readers * get the same actions as controls of their own, inside the panel. */ const coarsePointer = useMediaQuery('(hover: none)'); const { enterToSend, handOffComposerText, composerBindings: { shortcutsEnabled, submitOverride, yieldedChords }, } = useChatSurface(); const [actorPickerOpen, setActorPickerOpen] = useState(false); /** A continuation is out. Declared here because the selection-advance effect * below has to defer to it, well before the mutation itself exists. */ const [continuationPending, setContinuationPending] = useState(false); const [controlMessage, setControlMessage] = useState(''); /** Unsent words in the composer are enough on their own: whatever put them * there, an advance would change the control identity and wipe them. */ const selectionHeldForDraft = continuationPending || controlMessage.trim() !== ''; const setSelection = useSetAtom(activeSubagentPanel); const resetSelection = useCallback(() => setSelection(null), [setSelection]); const agentsMap = useAgentsMapContext(); const { byMessageId, byThreadId, refresh } = useParentSubagents(); const progress = useSubagentProgress( subagentProgressKey( selection.parentMessageId, selection.event?.progressKey ?? selection.toolCallId, selection.partIndex, ), ); const parentAuthor = useParentAuthor( selection.parentConversationId, selection.parentMessageId, localize('com_ui_subagent_parent_agent'), selection.toolCallId, selection.partIndex, selection.durable?.threadId, ); const threadId = selection.durable?.threadId ?? ''; const taskId = selection.durable?.taskId ?? ''; const controlIdentity = subagentControlStateKey(selection.parentConversationId, threadId, taskId); const [controlState, setControlState] = useAtom(subagentControlStateByTask(controlIdentity)); const setControlStateForIdentity = useCallback( (identity: string, state: SubagentControlUiState | null) => panelStore.set(subagentControlStateByTask(identity), state), [panelStore], ); const transientControl = controlState?.receipt ?? null; const retryControl = controlState?.retry ?? null; const eventSummary = selection.event == null ? undefined : byThreadId.get(threadId); const eventTaskCount = eventSummary?.tasks.length ?? 0; const [eventTaskWindow, setEventTaskWindow] = useState(() => ({ threadId, count: EVENT_TASK_PAGE_SIZE, taskCount: eventSummary == null ? null : eventTaskCount, })); useEffect(() => { setEventTaskWindow((current) => { if (current.threadId !== threadId || current.taskCount == null) { return { threadId, count: EVENT_TASK_PAGE_SIZE, taskCount: eventTaskCount }; } const appended = Math.max(0, eventTaskCount - current.taskCount); return { threadId, count: Math.min(eventTaskCount, current.count + appended), taskCount: eventTaskCount, }; }); }, [eventTaskCount, threadId]); const visibleEventTaskCount = Math.min( eventTaskCount, eventTaskWindow.threadId === threadId ? eventTaskWindow.count : EVENT_TASK_PAGE_SIZE, ); const visibleEventTasks = useMemo( () => (eventSummary?.tasks ?? []).slice(0, visibleEventTaskCount).reverse(), [eventSummary?.tasks, visibleEventTaskCount], ); const hasEarlierRetainedTasks = visibleEventTaskCount < eventTaskCount; const eventTaskRunning = eventSummary?.tasks.find((task) => task.taskId === taskId)?.status === 'running'; const eventSiblings = useMemo(() => { if (selection.event == null) return []; const seen = new Set(); return (selection.event.siblingParentMessageIds ?? [selection.parentMessageId]) .flatMap((parentMessageId) => byMessageId.get(parentMessageId) ?? []) .filter((child) => { if (seen.has(child.threadId)) return false; seen.add(child.threadId); return true; }); }, [byMessageId, selection.event, selection.parentMessageId]); const selectedEventActor = eventSiblings.find((child) => child.threadId === threadId); const { data, isLoading, isError, isPreviousData, isReadinessPending, refetch } = useSubagentThreadQuery(selection.parentConversationId, threadId, taskId, { /** A new delivery re-keys this query to its task. Keeping the previous * thread view mounted while the fresh one loads stops the whole panel * from flashing back to a loading dot on every incoming event. */ keepPreviousData: true, ...(eventTaskRunning ? { refetchInterval: ACTIVE_THREAD_REFRESH_MS } : {}), }); /** Retention crosses every key change, including actor switches. A retained * view is only meaningful while it describes the SAME child thread; within * that thread its turn/history rows stay valid across task re-keys, while * task-scoped fields (selected activity, status, control receipts) must not * be attributed to the newly selected task. */ const threadView = data?.threadId === threadId ? data : undefined; const childKind = threadView?.subagentKind ?? progress?.subagentKind ?? selection.subagentIdentity?.subagentKind ?? byThreadId.get(threadId)?.subagentKind; const isSelfSpawn = isSelfSpawnType(selection.subagentType, childKind); const foregroundAgentId = childKind === 'graph' ? undefined : (resolveSubagentAgentId(progress, selection.subagentIdentity) ?? byThreadId.get(threadId)?.agentId); const foregroundAgent = foregroundAgentId == null ? undefined : agentsMap?.[foregroundAgentId]; /** Named the way main chat names an agent turn — never by its id. A * self-spawn is the parent agent working on its own behalf. */ const foregroundTitle = foregroundAgent?.name || (isSelfSpawn ? parentAuthor.name : readableSubagentType(selection.subagentType, foregroundAgentId, childKind)) || localize('com_ui_subagent_actor'); const selectedEventActorName = (selectedEventActor?.agentId == null ? undefined : agentsMap?.[selectedEventActor.agentId]?.name) ?? selectedEventActor?.actorId ?? eventSummary?.actorId ?? selection.event?.actorId ?? foregroundTitle; const taskView = isPreviousData ? undefined : threadView; const latestHistoryGeneration = JSON.stringify([ threadView?.nextCursor ?? null, ...(threadView?.turns?.map((turn) => turn.taskId) ?? []), ]); const latestHistoryGenerationRef = useRef(latestHistoryGeneration); latestHistoryGenerationRef.current = latestHistoryGeneration; const durableTerminal = subagentThreadHasTaskEvidence(taskView, taskId) && (taskView?.status === 'completed' || taskView?.status === 'failed' || taskView?.status === 'interrupted' || taskView?.status === 'cancelled'); const priorTerminalRef = useRef(false); useSubagentActivityStream(selection, !durableTerminal || eventTaskRunning); useEffect(() => { if (selection.event == null) return; void refresh(); }, [refresh, selection.event, threadId]); useEffect(() => { priorTerminalRef.current = false; }, [taskId, threadId]); useEffect(() => { if (selection.event == null) return; if (durableTerminal && !priorTerminalRef.current) void refresh(); priorTerminalRef.current = durableTerminal; }, [durableTerminal, refresh, selection.event]); useEffect(() => { if (selection.event == null || !eventTaskRunning || !durableTerminal) return; void refetch(); }, [durableTerminal, eventTaskRunning, refetch, selection.event]); useEffect(() => { if ( selection.event == null || selection.event.pinnedTask === true || /** An advance changes the control identity, which empties the composer. * Defer while anything unsent is in it — a draft not yet submitted, one * travelling with a continuation in flight, or one left behind by a * continuation that failed and is waiting to be retried. The hold * releases itself once the draft is sent or cleared. */ selectionHeldForDraft || eventSummary?.latestTaskId == null || eventSummary.latestTaskId === taskId ) { return; } const nextSelection = eventSubagentSelection( selection.parentConversationId, eventSummary, selection.event.siblingParentMessageIds, ); if (nextSelection != null) setSelection(nextSelection); }, [eventSummary, selection, selectionHeldForDraft, setSelection, taskId]); const detachedLiveSubmitting = selection.durable != null && progress != null && progress.status !== 'stop' && progress.status !== 'error'; const controlMessageRef = useRef(controlMessage); controlMessageRef.current = controlMessage; /** The continuation in flight, bound to the selection that asked for it. The * fork lands a round trip later and the panel stays live for it, so the live * field is the better source — but ONLY while it still belongs to the actor * that made the request. Switch actors mid-flight and the words in the field * are the new actor's, so this falls back to what was there at submission. */ const continuationRef = useRef<{ identity: string; text: string } | null>(null); const continueChat = useForkConvoMutation({ onSuccess: (result) => { const continuedConversationId = result.conversation?.conversationId; /** The server keeps child threads view-only (`CHILD_THREAD_READ_ONLY_ERROR`), * so a continuation is a real conversation forked from the thread. Hand * what the reader typed to that conversation's composer instead of * dropping it with this panel — in memory, since an unsent draft must not * be written to storage the reader may have asked not to use. */ const continuation = continuationRef.current; continuationRef.current = null; setContinuationPending(false); /** While the field still belongs to this continuation it IS the draft, * verbatim — including when the reader has emptied it since, which is * them withdrawing the words rather than leaving them behind. Only a * composer that has moved to another selection falls back to what was * captured at submission. */ const stillItsOwnComposer = continuation?.identity === controlSelectionRef.current; const draft = stillItsOwnComposer ? controlMessageRef.current.trim() : (continuation?.text ?? ''); if (continuedConversationId != null && draft !== '') { handOffComposerText(continuedConversationId, draft); } if (stillItsOwnComposer) setControlMessage(''); resetSelection(); navigateToConvo(result.conversation); }, onError: () => { /** The panel stays open on a failed continuation, and the composer still * holds the words, so there is nothing to restore. */ continuationRef.current = null; setContinuationPending(false); showToast({ message: localize('com_ui_continue_chat_error'), status: 'error' }); }, }); const [turnDetailOverrides, setTurnDetailOverrides] = useState( () => new Map>(), ); const [turnDetailStates, setTurnDetailStates] = useState( () => new Map(), ); const [olderTurns, setOlderTurns] = useState>( [], ); const [movingWindowTurns, setMovingWindowTurns] = useState< ReturnType >([]); const [rebaseTurns, setRebaseTurns] = useState>( [], ); const [postRebaseTurns, setPostRebaseTurns] = useState< ReturnType >([]); const postRebaseTurnsRef = useRef(postRebaseTurns); const [historyRebaseActive, setHistoryRebaseActive] = useState(false); const historyRebaseActiveRef = useRef(historyRebaseActive); const [historyCursor, setHistoryCursor] = useState(undefined); const [historyCursorGeneration, setHistoryCursorGeneration] = useState(); const [historyState, setHistoryState] = useState<'idle' | 'loading' | 'error'>('idle'); const [historyBoundaryUnavailable, setHistoryBoundaryUnavailable] = useState(false); const activeThreadRef = useRef(threadId); const selectionThreadRef = useRef(threadId); const selectionGenerationRef = useRef(0); /** Locally retained turn buffers reset in a passive effect; until it has run * for the current thread they still hold the previous thread's turns and * must not render. Stamped inside that reset effect. */ const retainedTurnsGenerationRef = useRef(0); const turnDetailRequestsRef = useRef(new Set()); const historyRequestRef = useRef(null); const historyHasLoadedRef = useRef(false); if (selectionThreadRef.current !== threadId) { selectionThreadRef.current = threadId; selectionGenerationRef.current += 1; } activeThreadRef.current = threadId; const [controlInaccessible, setControlInaccessible] = useState(false); const [controlsClosed, setControlsClosed] = useState(false); const controlInFlightRef = useRef(false); const controlSelectionRef = useRef(controlIdentity); useEffect(() => { controlSelectionRef.current = controlIdentity; setControlMessage(''); setControlInaccessible(false); setControlsClosed(false); controlInFlightRef.current = false; return () => { controlSelectionRef.current = ''; }; }, [controlIdentity]); useEffect(() => { setTurnDetailOverrides(new Map()); setTurnDetailStates(new Map()); setOlderTurns([]); setMovingWindowTurns([]); setRebaseTurns([]); setPostRebaseTurns([]); retainedTurnsGenerationRef.current = selectionGenerationRef.current; postRebaseTurnsRef.current = []; setHistoryRebaseActive(false); historyRebaseActiveRef.current = false; setHistoryCursor(undefined); setHistoryCursorGeneration(undefined); setHistoryState('idle'); setHistoryBoundaryUnavailable(false); turnDetailRequestsRef.current.clear(); historyRequestRef.current = null; historyHasLoadedRef.current = false; }, [threadId]); useEffect(() => { if ( threadView != null && (threadView.historyUnavailable === true || (threadView.historyTruncated === true && threadView.nextCursor == null)) ) { setHistoryBoundaryUnavailable(true); } }, [threadView]); const loadTurnDetails = useCallback( async (detailTaskId: string) => { const requestedThreadId = threadId; const requestedGeneration = selectionGenerationRef.current; const requestKey = `${requestedGeneration}\u0000${requestedThreadId}\u0000${detailTaskId}`; if ( turnDetailStates.get(detailTaskId) === 'loading' || turnDetailRequestsRef.current.has(requestKey) ) { return; } turnDetailRequestsRef.current.add(requestKey); setTurnDetailStates((current) => new Map(current).set(detailTaskId, 'loading')); try { const exact = await dataService.getSubagentThread( selection.parentConversationId, requestedThreadId, detailTaskId, ); if ( activeThreadRef.current !== requestedThreadId || selectionGenerationRef.current !== requestedGeneration ) { return; } if (!subagentThreadHasTaskEvidence(exact, detailTaskId)) { setTurnDetailStates((current) => new Map(current).set(detailTaskId, 'unavailable')); return; } const detail = adaptDurableThreadActivity(exact, detailTaskId); setTurnDetailOverrides((current) => new Map(current).set(detailTaskId, detail)); setTurnDetailStates((current) => new Map(current).set( detailTaskId, detail.activityTruncated === true ? 'unavailable' : 'idle', ), ); } catch { if ( activeThreadRef.current !== requestedThreadId || selectionGenerationRef.current !== requestedGeneration ) { return; } setTurnDetailStates((current) => new Map(current).set(detailTaskId, 'error')); } finally { turnDetailRequestsRef.current.delete(requestKey); } }, [selection.parentConversationId, threadId, turnDetailStates], ); const loadEarlierHistory = useCallback(async () => { const requestedThreadId = threadId; const requestedSelectionGeneration = selectionGenerationRef.current; const requestedGeneration = historyRebaseActive ? (historyCursorGeneration ?? latestHistoryGeneration) : latestHistoryGeneration; const startsRebase = !historyRebaseActive && historyCursor !== undefined && historyCursorGeneration !== requestedGeneration; const recoveringRebase = startsRebase || historyRebaseActive; const cursor = historyCursor === undefined || startsRebase ? threadView?.nextCursor : historyCursor; const requestKey = `${requestedSelectionGeneration}\u0000${requestedThreadId}\u0000${cursor ?? ''}\u0000${requestedGeneration}`; if (cursor == null || historyState === 'loading' || historyRequestRef.current != null) { return; } historyRequestRef.current = requestKey; setHistoryState('loading'); try { const page = await dataService.getSubagentThread( selection.parentConversationId, requestedThreadId, undefined, cursor, ); if ( activeThreadRef.current !== requestedThreadId || selectionGenerationRef.current !== requestedSelectionGeneration ) { return; } if (!historyRebaseActive && latestHistoryGenerationRef.current !== requestedGeneration) { setHistoryState('idle'); return; } const pageTurns = adaptDurableThreadConversation(page); let recoveryCompleted = false; if (recoveringRebase) { const bridgeTurns = startsRebase ? retainBoundedMovingWindowTurns(movingWindowTurns, rebaseTurns) : movingWindowTurns; const nextRebaseTurns = mergeChildConversationTurns( pageTurns, startsRebase ? [] : rebaseTurns, ); const retainedTaskIds = new Set( mergeChildConversationTurns(olderTurns, bridgeTurns, postRebaseTurnsRef.current).map( (turn) => turn.taskId, ), ); const reconnected = pageTurns.some((turn) => retainedTaskIds.has(turn.taskId)); const recoveryComplete = reconnected || page.nextCursor == null; if (recoveryComplete) { recoveryCompleted = true; const retainedPostRebaseTurns = postRebaseTurnsRef.current; postRebaseTurnsRef.current = []; setOlderTurns((current) => mergeChildConversationTurns( current, bridgeTurns, nextRebaseTurns, retainedPostRebaseTurns, ), ); setMovingWindowTurns([]); setRebaseTurns([]); setPostRebaseTurns([]); setHistoryRebaseActive(false); historyRebaseActiveRef.current = false; } else { if (startsRebase) setMovingWindowTurns(bridgeTurns); setRebaseTurns(nextRebaseTurns); setHistoryRebaseActive(true); historyRebaseActiveRef.current = true; } } else { setOlderTurns((current) => mergeChildConversationTurns(pageTurns, current)); } historyHasLoadedRef.current = true; setHistoryCursor(page.nextCursor ?? null); setHistoryCursorGeneration( recoveryCompleted ? latestHistoryGenerationRef.current : requestedGeneration, ); setHistoryBoundaryUnavailable( (current) => current || page.historyUnavailable === true || (page.historyTruncated && page.nextCursor == null), ); setHistoryState('idle'); } catch { if ( activeThreadRef.current !== requestedThreadId || selectionGenerationRef.current !== requestedSelectionGeneration ) { return; } setHistoryState('error'); } finally { if (historyRequestRef.current === requestKey) historyRequestRef.current = null; } }, [ threadView?.nextCursor, historyCursor, historyCursorGeneration, historyRebaseActive, historyState, latestHistoryGeneration, movingWindowTurns, olderTurns, rebaseTurns, selection.parentConversationId, threadId, ]); const controlTask = useSubagentControlMutation({ onSuccess: ({ receipt }, variables) => { const submittedSelection = subagentControlStateKey( variables.parentConversationId, variables.threadId, variables.command.taskId, ); setControlStateForIdentity(submittedSelection, { receipt }); if (controlSelectionRef.current !== submittedSelection) return; controlInFlightRef.current = false; if (closesTaskControls(receipt)) setControlsClosed(true); if ( variables.command.action !== 'cancel_message' && (receipt.status === 'accepted' || receipt.status === 'applied') ) { setControlMessage(''); } }, onError: (error, variables) => { const status = responseStatus(error); const inaccessible = status === 404; const retryable = status == null || status >= 500; const command = variables.command; const submittedSelection = subagentControlStateKey( variables.parentConversationId, variables.threadId, command.taskId, ); setControlStateForIdentity(submittedSelection, { receipt: { invocationId: command.invocationId, ...(command.controlId == null ? {} : { controlId: command.controlId }), action: command.action, status: 'failed', createdAt: variables.submittedAt, updatedAt: new Date().toISOString(), ...(command.message == null ? {} : { message: command.message }), reason: failedControlReason(inaccessible, retryable), }, ...(retryable ? { retry: command } : {}), }); if (controlSelectionRef.current !== submittedSelection) return; controlInFlightRef.current = false; if (inaccessible) { setControlInaccessible(true); setControlsClosed(true); } }, }); useEffect(() => { if (transientControl == null) return; const durableReceipt = taskView?.controlReceipts?.find( (receipt) => receipt.invocationId === transientControl.invocationId, ); if (durableReceipt == null) return; /** The durable view is authoritative after refresh. Drop mutation-only state * once the same invocation appears there so stale failure/retry UI cannot * outlive a successfully persisted receipt. */ if ( retryControl != null && retryControl.action !== 'cancel' && retryControl.action !== 'cancel_message' && (durableReceipt.status === 'accepted' || durableReceipt.status === 'applied') ) { setControlMessage((current) => (current === retryControl.message ? '' : current)); } if (closesTaskControls(durableReceipt)) setControlsClosed(true); setControlState(null); }, [retryControl, setControlState, taskView?.controlReceipts, transientControl]); useEffect(() => { if (taskView?.controlReceipts?.some(closesTaskControls)) { setControlsClosed(true); } }, [taskView?.controlReceipts]); const submitControl = useCallback( (action: SubagentControlAction, controlId?: string, retry?: SubagentControlRequest) => { if ( selection.durable == null || controlTask.isLoading || controlInFlightRef.current || (retryControl != null && retry == null) ) { return; } let command: SubagentControlRequest; if (retry != null) { command = retry; } else if (action === 'cancel_message') { command = { taskId: selection.durable.taskId, invocationId: v4(), action, controlId, }; } else if (action === 'cancel') { command = { taskId: selection.durable.taskId, invocationId: v4(), action, }; } else { command = { taskId: selection.durable.taskId, invocationId: v4(), action, message: controlMessage.trim(), }; } if ( action !== 'cancel' && action !== 'cancel_message' && (command.message == null || command.message === '') ) { return; } const now = new Date().toISOString(); setControlState({ receipt: { invocationId: command.invocationId, ...(command.controlId == null ? {} : { controlId: command.controlId }), action: command.action, status: 'submitted', createdAt: now, updatedAt: now, ...(command.message == null ? {} : { message: command.message }), }, retry: command, }); controlInFlightRef.current = true; controlTask.mutate({ parentConversationId: selection.parentConversationId, threadId: selection.durable.threadId, command, submittedAt: now, }); }, [ controlMessage, controlTask, retryControl, selection.durable, selection.parentConversationId, setControlState, ], ); const close = useCallback(() => { resetSelection(); requestAnimationFrame(() => { const trigger = Array.from( document.querySelectorAll('[data-subagent-tool-call]'), ).find( (element) => element.dataset.subagentToolCall === selection.toolCallId && element.dataset.subagentParentMessage === selection.parentMessageId && element.dataset.subagentPartIndex === String(selection.partIndex), ); trigger?.focus(); }); }, [resetSelection, selection.parentMessageId, selection.partIndex, selection.toolCallId]); /** Escape is handled on the element rather than through the trap's own * native listener: that listener sits on this `aside`, so it runs BEFORE any * React handler inside it and would close the whole panel out from under a * nested popover that meant to dismiss only itself. As a React handler it * bubbles in DOM order, so an inner control can stop it or mark it handled. */ useFocusTrap(panelRef, isMobile); const handlePanelKeyDown = useCallback( (event: ReactKeyboardEvent) => { if (!isMobile || event.key !== 'Escape' || event.defaultPrevented) return; event.preventDefault(); close(); }, [close, isMobile], ); useEffect(() => { const activeElement = document.activeElement; if (!isMobile || !(activeElement instanceof HTMLElement)) return; return () => { if (activeElement.isConnected) activeElement.focus(); }; }, [isMobile]); /** A previewed call renders nothing until its stored part arrives: the preview's output is a * shortened copy and its transcript is absent, so neither may stand in for the activity. */ const awaitsStoredPart = selection.contentPreview != null; const storedPart = useToolCallPartQuery( { conversationId: selection.parentConversationId, messageId: selection.parentMessageId, partIndex: selection.partIndex, toolCallId: selection.toolCallId || undefined, stepId: selection.contentPreview?.stepId, agentId: selection.contentPreview?.agentId, }, { enabled: awaitsStoredPart }, selection.contentPreview?.revision, ); const storedToolCall = awaitsStoredPart ? storedPart.data?.tool_call : undefined; const persistedContent = storedToolCall?.subagent_content ?? selection.persistedContent; const prompt = (storedToolCall == null ? undefined : getSubagentPrompt(storedToolCall.args)) ?? selection.prompt; let legacyOutput = selection.legacyOutput; if (awaitsStoredPart && legacyOutput != null) { legacyOutput = storedToolCall?.output; } const liveActivity = useMemo( () => adaptLivePersistedActivity({ title: foregroundTitle, prompt, progress, persistedContent, isDetached: selection.durable != null, legacyOutput, // A detached parent tool step closes as soon as dispatch succeeds; // its terminal status does not describe the still-running child. initialProgress: selection.durable == null ? selection.initialProgress : 0, isSubmitting: selection.durable == null ? selection.isSubmitting : detachedLiveSubmitting, runStepStatus: selection.durable == null ? selection.runStepStatus : undefined, }), [ detachedLiveSubmitting, foregroundTitle, legacyOutput, persistedContent, progress, prompt, selection, ], ); const activity = useMemo(() => { if (selection.durable == null) return liveActivity; if (taskView == null) { const activityWithoutData = progress == null ? { ...liveActivity, status: 'dispatched' as const } : liveActivity; return transientControl == null ? activityWithoutData : { ...activityWithoutData, controls: [transientControl] }; } const durable = adaptDurableThreadActivity(taskView, selection.durable.taskId); const useLiveItems = (durable.status === 'running' || durable.status === 'dispatched') && liveActivity.items.length > 0; const mergedItems = !useLiveItems && durable.items.length > 0 ? durable.items : liveActivity.items; const merged = { ...durable, prompt: durable.prompt ?? liveActivity.prompt, items: mergedItems, }; if ( transientControl == null || (merged.controls ?? []).some( (receipt) => receipt.invocationId === transientControl.invocationId, ) ) { return merged; } return { ...merged, controls: [...(merged.controls ?? []), transientControl] }; }, [liveActivity, progress, selection.durable, taskView, transientControl]); const selectedActorAgentId = selectedEventActor?.agentId ?? threadView?.agentId ?? foregroundAgentId; const selectedActorAgent = resolveChildAgent( selectedActorAgentId, selection.subagentType, parentAuthor.agent, agentsMap, childKind, ); /** One author for the header, the composer and every child turn, so the three * can never name the child differently. */ const childAuthor = useMemo( () => selection.event != null ? agentAuthor(selectedActorAgent, selectedEventActorName) : resolveSubagentAuthor( { agentId: selectedActorAgentId, subagentType: selection.subagentType, subagentKind: childKind, title: threadView?.title ?? byThreadId.get(threadId)?.title, }, parentAuthor, agentsMap, localize('com_ui_subagent_actor'), ), [ agentsMap, byThreadId, childKind, localize, parentAuthor, selectedActorAgent, selectedActorAgentId, selectedEventActorName, selection.event, selection.subagentType, threadId, threadView?.title, ], ); const panelTitle = childAuthor.name; const actorOptions = useMemo(() => { if (selection.event == null) return []; return ( eventSiblings /** An actor with no task has nothing to open, and this list has no * disabled state — leave it out rather than offering a dead row. The * selected thread stays listed whatever the index currently says. */ .filter((child) => child.latestTaskId != null || child.threadId === threadId) .map((child) => { const agent = child.agentId == null ? undefined : agentsMap?.[child.agentId]; const name = agent?.name || child.actorId || readableSubagentType(child.subagentType, child.agentId, child.subagentKind) || localize('com_ui_subagent_actor'); return { value: child.threadId, label: agent?.name != null && child.actorId != null ? `${name} · ${child.actorId}` : name, icon: renderAgentAvatar(agent, { size: 'icon', showBorder: false }), }; }) ); }, [agentsMap, eventSiblings, localize, selection.event, threadId]); const selectedActorLabel = actorOptions.find((option) => option.value === threadId)?.label ?? panelTitle; /** The picker's own glyph, matching the rows it lists. */ const selectedActorIcon = renderAgentAvatar(selectedActorAgent, { size: 'icon', showBorder: false, }); const latestConversationTurns = useMemo( () => (threadView == null ? [] : adaptDurableThreadConversation(threadView)), [threadView], ); const previousLatestTurnsRef = useRef({ threadId, generation: latestHistoryGeneration, turns: latestConversationTurns, }); useEffect(() => { if (threadView == null) return; const previous = previousLatestTurnsRef.current; if (previous.threadId === threadId) { const latestTaskIds = new Set(latestConversationTurns.map((turn) => turn.taskId)); const displaced = previous.turns.filter((turn) => !latestTaskIds.has(turn.taskId)); if (displaced.length > 0 && historyHasLoadedRef.current) { if (historyRebaseActiveRef.current) { const retained = retainBoundedMovingWindowTurns(postRebaseTurnsRef.current, displaced); postRebaseTurnsRef.current = retained; setPostRebaseTurns(retained); } else { setMovingWindowTurns((current) => retainBoundedMovingWindowTurns(current, displaced)); } } } previousLatestTurnsRef.current = { threadId, generation: latestHistoryGeneration, turns: latestConversationTurns, }; }, [historyRebaseActive, latestConversationTurns, latestHistoryGeneration, threadId, threadView]); const retainedTurnsValid = retainedTurnsGenerationRef.current === selectionGenerationRef.current; const conversationTurns = useMemo(() => { const durableTurns = retainedTurnsValid ? mergeChildConversationTurns( olderTurns, movingWindowTurns, rebaseTurns, postRebaseTurns, latestConversationTurns, ) : mergeChildConversationTurns(latestConversationTurns); if (durableTurns.length > 0) { const selectedTurnIndex = durableTurns.findIndex((turn) => turn.taskId === taskId); if (selectedTurnIndex >= 0) { return durableTurns.map((turn, index) => { const selected = index === selectedTurnIndex ? { ...turn, activity } : turn; const override = turnDetailOverrides.get(turn.taskId); return override == null ? selected : { ...selected, activity: override }; }); } /** A turn absent from the durable window is either the thread's newest * delivery whose fetch has not landed yet (place it at the END, where * it will settle — a new event must not appear at the top and then * jump to the bottom) or an older selection displaced from the bounded * window (keep it ahead of the retained newer continuation). */ const indexedChild = byThreadId.get(threadId); const selectedTaskCreatedAt = indexedChild?.tasks.find( (task) => task.taskId === taskId, )?.createdAt; const synthesizedTurn = { taskId: taskId || `${selection.parentMessageId}:${selection.toolCallId}`, trigger: { kind: selection.event == null ? ('parent_continuation' as const) : ('external_event' as const), summary: prompt ?? activity.prompt ?? '', ...(selectedTaskCreatedAt == null ? {} : { createdAt: selectedTaskCreatedAt }), }, activity, }; /** Order by trigger time when both sides carry one; the separately * polled discovery index is only the fallback authority, since it can * briefly lag or lead the thread view. */ const lastDurableCreatedAt = durableTurns[durableTurns.length - 1]?.trigger.createdAt; const appendSynthesized = selectedTaskCreatedAt != null && lastDurableCreatedAt != null ? selectedTaskCreatedAt >= lastDurableCreatedAt : indexedChild?.latestTaskId === taskId; const retained = appendSynthesized ? [...durableTurns, synthesizedTurn] : [synthesizedTurn, ...durableTurns]; return retained.map((turn) => { const override = turnDetailOverrides.get(turn.taskId); return override == null ? turn : { ...turn, activity: override }; }); } return [ { taskId: taskId || `${selection.parentMessageId}:${selection.toolCallId}`, trigger: { kind: selection.event == null ? ('parent_dispatch' as const) : ('external_event' as const), summary: prompt ?? activity.prompt ?? '', }, activity, }, ]; }, [ activity, byThreadId, latestConversationTurns, movingWindowTurns, olderTurns, postRebaseTurns, prompt, rebaseTurns, retainedTurnsValid, threadId, selection, taskId, turnDetailOverrides, ]); const effectiveTurnDetailStates = useMemo(() => { const states = new Map(turnDetailStates); if (activity.activityTruncated === true && taskId !== '') states.set(taskId, 'unavailable'); return states; }, [activity.activityTruncated, taskId, turnDetailStates]); const historyCursorUsesLatest = !historyRebaseActive && (historyCursor === undefined || historyCursorGeneration !== latestHistoryGeneration); const effectiveHistoryCursor = historyCursorUsesLatest ? threadView?.nextCursor : historyCursor; const showUnavailableHistoryBoundary = historyBoundaryUnavailable || threadView?.historyUnavailable === true || (historyCursorUsesLatest && threadView?.historyTruncated === true && threadView.nextCursor == null); /** During a rolling deployment an older API replica can omit `turns`. Keep * that response readable through the same deep activity renderer; every * current host otherwise enters the conversation-native rendering seam. */ const hasConversationProjection = selection.durable == null || threadView == null || Array.isArray(threadView.turns); const taskInaccessible = controlInaccessible || transientControl?.reason === 'task_inaccessible'; const taskIsLive = taskView != null && isLiveSubagentStatus(taskView.status); /** A command can only be addressed once the task has a durable input row or a * live lease — `control.ts` answers 404 otherwise, which this panel reads as * an inaccessible task and closes its controls for good. A `dispatched` task * without that evidence is live but not yet controllable: the composer stays * (withdrawing it as a run starts is the swap this panel exists to avoid), * while submission waits. */ const controlAddressable = taskView != null && (taskView.status === 'running' || (taskView.status === 'dispatched' && subagentThreadHasTaskEvidence(taskView, taskId))); const controlAvailable = selection.durable != null && controlAddressable && !taskInaccessible && !controlsClosed; const controlPending = controlTask.isLoading || transientControl?.status === 'submitted' || retryControl != null; const showControlFooter = controlAvailable || retryControl != null || transientControl?.reason === 'task_inaccessible'; const canContinueAsChat = selection.host === 'conversation' && selection.durable != null && taskView?.subagentKind === 'agent' && taskView.agentId != null && taskView.status === 'completed' && subagentThreadHasTaskEvidence(taskView, taskId) && taskView.messages.some((message) => message.messageId === `${taskId}:assistant`); const continueAsChat = useCallback(() => { if (!canContinueAsChat || selection.durable == null || continueChat.isLoading) return; continuationRef.current = { identity: controlIdentity, text: controlMessage.trim() }; setContinuationPending(true); continueChat.mutate({ conversationId: selection.durable.threadId, messageId: `${selection.durable.taskId}:assistant`, option: ForkOptions.DIRECT_PATH, }); }, [canContinueAsChat, continueChat, controlIdentity, controlMessage, selection.durable]); /** `control` steers the live run, `continue` carries the thread into a chat * of the reader's own. Both compose into the same field, with the same * placeholder the main chat composer shows for this agent. */ let liveComposerMode: 'control' | 'continue' | null = null; if (controlAvailable) { liveComposerMode = 'control'; } else if (canContinueAsChat) { liveComposerMode = 'continue'; } /** A delivery re-keys the query to its new task, and the task view blanks for * the render or two that takes — deliberately, so task-scoped fields are * never attributed to the wrong task. Presence must not follow it down: the * composer would unmount and remount within the same tenth of a second, * taking focus and the reader's half-typed words with it. The last mode this * thread showed carries the surface across that gap, holding submission * until the new task's own view arrives. */ const retainedModeRef = useRef<{ threadId: string; mode: 'control' | 'continue' } | null>(null); if (liveComposerMode != null) { retainedModeRef.current = { threadId, mode: liveComposerMode }; } else if (retainedModeRef.current != null && retainedModeRef.current.threadId !== threadId) { retainedModeRef.current = null; } /** Hold the surface both while a delivery re-keys the view and while a live * task is not yet addressable; submission waits in either case. A task whose * controls are definitively closed holds nothing — there is no command left * for the field to carry. */ const composerSettling = liveComposerMode == null && (taskView == null || (taskIsLive && !controlsClosed && !taskInaccessible)); /** While settling, the surface the thread last showed — or, on a first render * that has never had one, the surface a live task would have. */ let composerMode: 'control' | 'continue' | null = liveComposerMode; if (composerMode == null && composerSettling) { composerMode = retainedModeRef.current?.mode ?? (taskIsLive ? 'control' : null); } const actionsInline = coarsePointer || isMobile; const composerPlaceholder = localize('com_endpoint_message_new', { 0: panelTitle }); /** The send control names what IT does, distinct from the `Steer` row it * offers — the same pairing main chat uses for its during-run send. */ const composerSubmitLabel = composerMode === 'control' ? localize('com_ui_steer_send') : localize('com_ui_subagent_continue_new_chat'); const cancelTask = useCallback(() => submitControl('cancel'), [submitControl]); /** Handler and label travel as one value, so the Stop control can never * render without an accessible name. */ const stopProps: ComposerStopProps = controlAvailable && !controlPending ? { onStop: cancelTask, stopLabel: localize('com_ui_subagent_cancel_task') } : {}; const controlModeRef = useRef(false); const chordControlRef = useRef<{ event: ReactKeyboardEvent; control: SubagentControlAction; } | null>(null); controlModeRef.current = composerMode === 'control'; let composerCanSubmit: boolean; if (composerSettling) { composerCanSubmit = false; } else if (composerMode === 'control') { composerCanSubmit = !controlPending && controlMessage.trim() !== ''; } else { composerCanSubmit = !continueChat.isLoading; } /** The alternate submissions, offered from the send control exactly as main * chat offers its during-run actions — never as a row of controls beside the * field repeating what submitting already does. Each chord is advertised * only while it still reaches its action, read from the same decision table * that will execute it. */ const submitActions = useMemo(() => { if (composerMode !== 'control') return []; const context = { isComposing: false, isSubmitting: true, allowSubmitWhileGenerating: true, hasDuringRunModifier: true, shortcutsEnabled, enterToSend, submitOverride, yieldedChords, }; const base = { key: 'Enter', altKey: false, ctrlKey: false, metaKey: false, shiftKey: false }; const plainEnter = resolveComposerKeyDown(base, context); const modEnter = resolveComposerKeyDown( { ...base, ctrlKey: !isMacPlatform, metaKey: isMacPlatform }, context, ); const altEnter = resolveComposerKeyDown({ ...base, altKey: true }, context); const modSymbol = isMacPlatform ? '\u2318\u23CE' : 'Ctrl \u23CE'; const altSymbol = isMacPlatform ? '\u2325\u23CE' : 'Alt \u23CE'; let steerKbd: string | undefined; if (plainEnter === 'submit') { steerKbd = '\u23CE'; } else if (modEnter === 'submit') { steerKbd = modSymbol; } /** The same gate the send button answers to: a retained surface over a task * the server cannot address yet must not offer a command through any of * its doors — every 404 here closes this task's controls for good. */ const blocked = !controlAvailable || controlPending || controlMessage.trim() === ''; return [ { key: 'steer', label: localize('com_ui_steer'), kbd: steerKbd, icon: