Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
import { EventType } from '@agentscope-ai/agentscope/event';
import type {
AgentEvent,
CustomEvent,
DataBlockStartEvent,
DataBlockDeltaEvent,
DataBlockEndEvent,
ExternalExecutionResultEvent,
ReplyStartEvent,
ToolResultEndEvent,
UserConfirmResultEvent,
} from '@agentscope-ai/agentscope/event';
import { AssistantMsg, UserMsg } from '@agentscope-ai/agentscope/message';
import type { Msg, ContentBlock } from '@agentscope-ai/agentscope/message';
import type { ToolCallBlock, ToolResultBlock } from '@agentscope-ai/agentscope/message';
import { useState, useCallback, useRef, useEffect, useMemo, useLayoutEffect } from 'react';
import { toast } from 'sonner';
import { chatApi, sessionApi, takeFreshlyCreated } from '@/api';
import type { ChatQueueItem } from '@/api/chat';
import { useAudioManager } from '@/context/AudioContext';
import {
getQueueMessages,
type ChatInputStartedValue,
type ChatInputTerminalValue,
useChatQueue,
} from '@/hooks/useChatQueue';
import { useTranslation } from '@/i18n/useI18n';
import { ASK_USER_TOOL_NAME, formatAskUserOutput, parseAskUserResult } from '@/lib/ask-user';
import type { ClientExternalToolResult } from '@/lib/client-external-tools';
import { appendMessageEvent } from '@/lib/message-events';
import { getPendingHitlCalls } from '@/lib/pendingToolCalls';
/**
* One pending subagent HITL request, projected from a team *member*
* session onto its *leader* session so the leader UI can render and
* resolve it. Mirrors the Python payload written by
* ``SubagentHitlProjector`` and pushed/replayed as a ``CustomEvent``
* (``name="subagent_require_user_confirm"``).
*/
export type SubagentHitlEntry = {
worker_session_id: string;
worker_agent_id: string;
worker_agent_name: string;
reply_id: string;
event_type: 'require_user_confirm' | 'require_external_execution';
/** The original ``RequireUserConfirmEvent`` payload (serialized). */
event: { tool_calls?: ToolCallBlock[] } & Record<string, unknown>;
created_at: string;
};
const hitlKey = (e: { worker_session_id: string; reply_id: string }) =>
`${e.worker_session_id}:${e.reply_id}`;
/**
* Lifecycle phase of the reply currently owned by this session.
*
* - ``idle`` — no in-flight reply; the send button is enabled.
* - ``streaming`` — a reply is in progress (either actively producing
* events or parked awaiting HITL). A separate Stop button is shown,
* while Send remains available to enqueue another turn. The
* parked-vs-generating distinction is not tracked here; HITL cards
* render themselves from message content when a
* ``RequireUserConfirmEvent`` block is present.
* - ``interrupting`` — the user has requested a stop and we are
* waiting for the backend's terminating ``ReplyEndEvent``. Stop
* button is shown but disabled so users cannot spam it. Falls back
* to ``idle`` after a 10s safety timeout in case the terminating
* event never arrives (dropped SSE frame, backend bug, etc.).
*/
export type ReplyPhase = 'idle' | 'streaming' | 'interrupting';
/** Safety fallback: force phase back to idle if REPLY_END is not seen. */
const INTERRUPT_TIMEOUT_MS = 10_000;
/**
* Manages messages for a single ``(agentId, sessionId)`` pair.
*
* Event delivery has two independent channels:
*
* - **History** — ``GET /sessions/{sid}/messages`` fetches persisted
* ``Msg`` objects (each a complete reply).
* - **Live stream** — ``GET /sessions/{sid}/stream`` is a long-lived
* SSE connection that pushes ``AgentEvent`` deltas as they are
* produced by any chat run on this session (user-triggered,
* background retrigger, team member message, …).
*
* The hook opens the SSE connection immediately after fetching
* history. Ordinary user input is accepted into the backend FIFO.
* Human-in-the-loop confirmations use the active realtime control
* channel during voice mode and ``POST /chat/`` otherwise. Resulting
* events arrive through the already-open SSE connection.
*
* ``phase`` is driven by event content, not HTTP lifecycle: it moves
* to ``streaming`` on ``ReplyStartEvent`` and back to ``idle`` on
* ``ReplyEndEvent``. Calling ``interrupt()`` moves it to
* ``interrupting`` until the terminating ``ReplyEndEvent`` arrives (or
* a 10s safety timeout fires).
*
* @param agentId - The agent whose session to subscribe. ``null`` to
* skip.
* @param sessionId - The session to subscribe. ``null`` to skip.
* @returns Message/reply state, editable queue state and mutations, HITL
* handlers, send/interrupt actions, loading state, and the latest error.
* ``loading`` stays true until history for the current session lands.
*/
export function useMessages(
agentId: string | null,
sessionId: string | null,
options?: {
/**
* Called when a ``CUSTOM`` event with ``name="team_updated"``
* arrives — the team membership has changed (TeamCreate /
* AgentCreate / TeamDelete ran). The typical response is to
* refetch the session list so the team sidebar updates.
*/
onTeamUpdated?: () => void;
/**
* Called when a ``CUSTOM`` event with ``name="state_updated"``
* arrives — agent state (tasks / permission) changed during a
* tool call. The ``value`` payload contains the latest
* ``tasks_context`` and ``permission_context``.
*/
onStateUpdated?: (value: Record<string, unknown>) => void;
/**
* Called when a ``CUSTOM`` event with ``name="session_updated"``
* arrives — the session record changed server-side, currently
* only when auto-naming replaced its placeholder name. Refetch
* the session list to pick the new one up.
*/
onSessionUpdated?: () => void;
/** True when a dedicated realtime transport already plays PCM audio. */
isRealtimeAudioActive?: () => boolean;
/** Send a tool confirmation over the active realtime transport. */
sendRealtimeUserConfirm?: (event: UserConfirmResultEvent) => Promise<void>;
/** Return an external tool result over the realtime transport. */
sendRealtimeExternalExecutionResult?: (
event: ExternalExecutionResultEvent,
) => Promise<void>;
},
) {
const { t } = useTranslation();
// A new identity for each visit also rejects late responses after A -> B -> A.
const session = useMemo(() => ({ agentId, sessionId }), [agentId, sessionId]);
const externalSubmissionsRef = useRef(
new Map<
string,
{
replyId: string;
toolCallIds: Set<string>;
resolve: () => void;
reject: (error: Error) => void;
}
>(),
);
const activeSessionRef = useRef<typeof session | null>(null);
useLayoutEffect(() => {
activeSessionRef.current = session;
const externalSubmissions = externalSubmissionsRef.current;
return () => {
activeSessionRef.current = null;
for (const pending of externalSubmissions.values()) {
pending.reject(new Error('The session closed before the result was acknowledged.'));
}
externalSubmissions.clear();
};
}, [session]);
const [msgs, setMsgs] = useState<Msg[]>([]);
// The (agent, session) pair `msgs` actually belongs to. Loading is
// derived from it rather than set inside the fetch effect: an effect
// runs *after* the render that changed `sessionId`, so a flag it owns
// is still `false` for one frame — long enough to paint the empty
// state over a session that does have messages.
const [loadedKey, setLoadedKey] = useState<string | null>(null);
const [phase, setPhase] = useState<ReplyPhase>('idle');
// Only a running reply accepts steering. Parked replies retain their
// streaming phase and currentReplyRef for confirmation and Stop.
const [activeReplyId, setActiveReplyId] = useState<string | null>(null);
const [error, setError] = useState<Error | null>(null);
// Pending subagent HITL cards projected onto this (leader) session.
const [subagentHitl, setSubagentHitl] = useState<SubagentHitlEntry[]>([]);
const {
items: queuedItems,
visibleCount: queuedCount,
pendingCount: pendingQueueCount,
reorderDisabled: queueReorderDisabled,
addOptimistic,
acceptOptimistic,
rollbackOptimistic,
applyQueueSnapshot,
startItem,
finishItem,
updateQueued,
deleteQueued,
steerQueued,
moveQueued,
reorderQueued,
} = useChatQueue(agentId, sessionId, setError);
const msgsRef = useRef<Msg[]>([]);
const currentReplyRef = useRef<Msg | null>(null);
const ttsConfigurationWarningsRef = useRef(new Set<string>());
const abortRef = useRef<AbortController | null>(null);
const rafRef = useRef<number | null>(null);
// Timer that reverts ``interrupting`` back to ``idle`` if the
// terminating REPLY_END never arrives (dropped SSE frame, etc.).
const interruptTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
const clearInterruptTimer = useCallback(() => {
if (interruptTimerRef.current !== null) {
clearTimeout(interruptTimerRef.current);
interruptTimerRef.current = null;
}
}, []);
const audioManager = useAudioManager();
const optionsRef = useRef(options);
useEffect(() => {
optionsRef.current = options;
}, [options]);
const scheduleUpdate = useCallback(() => {
if (rafRef.current !== null) return;
rafRef.current = requestAnimationFrame(() => {
rafRef.current = null;
setMsgs([...msgsRef.current]);
});
}, []);
/** Apply a single AgentEvent to the in-progress reply. */
const processEvent = useCallback(
(event: AgentEvent) => {
// Custom events are service-layer notifications, not agent
// reply content — route them to callbacks and skip appendEvent.
if (event.type === EventType.CUSTOM) {
const custom = event as CustomEvent;
if (custom.name === 'external_execution_result_rejected') {
const failure = custom.value as {
request_id: string;
reply_id: string;
tool_call_ids: string[];
};
const pending = externalSubmissionsRef.current.get(failure.request_id);
if (
pending?.replyId === failure.reply_id &&
failure.tool_call_ids.some((id) => pending.toolCallIds.has(id))
) {
externalSubmissionsRef.current.delete(failure.request_id);
const error = new Error(t('chat.externalExecution.rejected'));
pending.reject(error);
toast.error(error.message);
}
} else if (custom.name === 'tts_error') {
const failure = custom.value as { stage?: string; reply_id?: string };
const sessionKey = JSON.stringify([agentId, sessionId]);
if (failure.stage === 'configuration') {
if (ttsConfigurationWarningsRef.current.has(sessionKey)) return;
ttsConfigurationWarningsRef.current.add(sessionKey);
}
toast.warning(t('chat.ttsFailed'), {
id: `tts-error-${sessionKey}-${failure.reply_id ?? custom.id}`,
});
} else if (custom.name === 'team_updated') {
optionsRef.current?.onTeamUpdated?.();
} else if (custom.name === 'state_updated' && custom.value) {
optionsRef.current?.onStateUpdated?.(custom.value as Record<string, unknown>);
} else if (custom.name === 'session_updated') {
optionsRef.current?.onSessionUpdated?.();
} else if (custom.name === 'subagent_require_user_confirm') {
// A team member is asking for confirmation; show (or
// refresh) its card on this leader view. Dedup by
// (worker_session_id, reply_id).
const e = custom.value as unknown as SubagentHitlEntry;
setSubagentHitl((prev) => [
...prev.filter((x) => hitlKey(x) !== hitlKey(e)),
e,
]);
} else if (custom.name === 'subagent_user_confirm_result') {
// The member resolved (or its run ended); clear the card.
const v = custom.value as { worker_session_id: string; reply_id: string };
setSubagentHitl((prev) => prev.filter((x) => hitlKey(x) !== hitlKey(v)));
} else if (custom.name === 'chat_input_started') {
const startedItem = startItem(custom.value as ChatInputStartedValue);
if (startedItem) {
const existingIds = new Set(msgsRef.current.map((msg) => msg.id));
msgsRef.current = [
...msgsRef.current,
...getQueueMessages([startedItem]).filter(
(msg) => !existingIds.has(msg.id),
),
];
scheduleUpdate();
}
} else if (custom.name === 'chat_queue_changed') {
const value = custom.value as { items?: ChatQueueItem[] };
applyQueueSnapshot(value.items ?? []);
} else if (custom.name === 'chat_input_failed') {
const value = custom.value as ChatInputTerminalValue;
finishItem(value);
const failure = new Error(value.message ?? t('chatQueue.processFailed'));
clearInterruptTimer();
currentReplyRef.current = null;
setPhase('idle');
setActiveReplyId(null);
setError(failure);
toast.error(failure.message);
} else if (custom.name === 'chat_input_cancelled') {
const value = custom.value as ChatInputTerminalValue;
finishItem(value);
const message = value.message ?? t('chatQueue.processingCancelled');
clearInterruptTimer();
currentReplyRef.current = null;
setPhase('idle');
setActiveReplyId(null);
toast.info(message);
} else if (custom.name === 'chat_input_injected') {
const value = custom.value as ChatInputTerminalValue;
finishItem(value);
toast.success(t('chatQueue.injected'));
} else if (custom.name === 'chat_input_steer_failed') {
const value = custom.value as ChatInputTerminalValue;
toast.error(value.message ?? t('chatQueue.steerFailed'));
}
return;
}
if (event.type === EventType.TOOL_RESULT_END) {
const result = event as ToolResultEndEvent;
for (const [requestId, pending] of externalSubmissionsRef.current) {
if (pending.replyId !== result.reply_id) continue;
pending.toolCallIds.delete(result.tool_call_id);
if (pending.toolCallIds.size === 0) {
externalSubmissionsRef.current.delete(requestId);
pending.resolve();
}
}
} else if (event.type === EventType.REPLY_END) {
for (const [requestId, pending] of externalSubmissionsRef.current) {
if (pending.replyId !== event.reply_id) continue;
externalSubmissionsRef.current.delete(requestId);
pending.reject(new Error(t('chat.externalExecution.rejected')));
}
}
if (event.type === EventType.REPLY_START) {
const e = event as ReplyStartEvent;
// A continuation (the run resuming after a confirmation or an
// external execution result) re-emits REPLY_START with the
// *same* reply_id. Re-point at the existing reply instead of
// appending a second msg under that id: a duplicate would
// collide on React keys, strand the original bubble in its
// running state, and hide any still-pending confirmation card
// — those are read off the tail msg, which would be the empty
// duplicate.
const existing = msgsRef.current.find((m) => m.id === e.reply_id);
if (existing) {
currentReplyRef.current = existing;
} else {
audioManager?.stopAllPlayback();
const msg =
e.role === 'user'
? UserMsg({ id: e.reply_id, name: e.name, content: [] })
: AssistantMsg({ id: e.reply_id, name: e.name, content: [] });
msgsRef.current = [...msgsRef.current, msg];
currentReplyRef.current = msg;
}
setActiveReplyId(e.reply_id);
clearInterruptTimer();
setPhase('streaming');
} else {
// Realtime providers may start the assistant response before the
// user's final transcription arrives. Route every identified event
// to its own reply instead of assuming event streams never overlap.
const reply = event.reply_id
? currentReplyRef.current?.id === event.reply_id
? currentReplyRef.current
: (msgsRef.current.find((message) => message.id === event.reply_id) ?? null)
: currentReplyRef.current;
if (reply) {
appendMessageEvent(reply, event);
// ``appendEvent`` mutates in place, which would leave
// every Msg identical across renders and force the whole
// list to re-render on each delta. Republish just the
// reply that changed under a fresh identity, so the
// memoised bubbles of the other messages can skip the
// render. Anything holding a Msg reference across events
// must re-read it from here — ``currentReplyRef`` below,
// everything else looks the reply up by id.
const updated = { ...reply, content: [...reply.content] };
msgsRef.current = msgsRef.current.map((m) => (m === reply ? updated : m));
if (currentReplyRef.current?.id === reply.id) {
currentReplyRef.current = updated;
}
}
if (
event.type === EventType.REQUIRE_USER_CONFIRM ||
event.type === EventType.REQUIRE_EXTERNAL_EXECUTION
) {
setActiveReplyId((active) =>
!event.reply_id || active === event.reply_id ? null : active,
);
}
if (
event.type === EventType.REPLY_END &&
(!event.reply_id ||
currentReplyRef.current === null ||
currentReplyRef.current.id === event.reply_id)
) {
clearInterruptTimer();
setPhase('idle');
setActiveReplyId(null);
currentReplyRef.current = null;
}
}
// Route streaming audio DataBlocks to the audio manager. They still
// flow through `appendEvent` above (which builds up `source.data`
// in the Msg), but MessageBubble reads playback state from the
// manager so it can show progress and autoplay on completion.
if (audioManager) {
if (event.type === EventType.DATA_BLOCK_START) {
const e = event as DataBlockStartEvent;
if (e.media_type.startsWith('audio/')) {
audioManager.start(e.block_id, e.media_type);
}
} else if (event.type === EventType.DATA_BLOCK_DELTA) {
const e = event as DataBlockDeltaEvent;
if (e.media_type.startsWith('audio/')) {
audioManager.append(e.block_id, e.data);
}
} else if (event.type === EventType.DATA_BLOCK_END) {
const e = event as DataBlockEndEvent;
// `end` is a no-op when the block isn't being tracked, so
// we can call it unconditionally.
audioManager.end(e.block_id);
}
}
scheduleUpdate();
},
[
scheduleUpdate,
audioManager,
clearInterruptTimer,
startItem,
applyQueueSnapshot,
finishItem,
t,
agentId,
sessionId,
],
);
// ── Lifecycle: fetch history + open SSE stream ──────────────────
useEffect(() => {
setLoadedKey(null);
msgsRef.current = [];
currentReplyRef.current = null;
setMsgs([]);
setError(null);
clearInterruptTimer();
setPhase('idle');
setActiveReplyId(null);
setSubagentHitl([]);
audioManager?.disposeAll();
if (!agentId || !sessionId) return;
const controller = new AbortController();
abortRef.current = controller;
let cancelled = false;
(async () => {
let eventCursor: string | null = null;
// 1. Fetch persisted history — unless this tab just created the
// session, in which case there is provably none.
if (takeFreshlyCreated(sessionId)) {
if (!cancelled) setLoadedKey(`${agentId}:${sessionId}`);
} else {
try {
const { messages, is_running, event_cursor } = await sessionApi.messages(
sessionId,
agentId,
);
if (cancelled) return;
eventCursor = event_cursor;
msgsRef.current = messages;
// If a reply is in flight (running on a worker) OR any
// persisted msg is parked on a pending tool_call (awaiting
// user confirmation / external execution), initialise the
// phase to ``streaming`` so the interrupt button is
// available immediately — otherwise a fresh page load
// while parked leaves the UI stuck on ``idle`` with no
// way to abort.
const tail = messages[messages.length - 1];
const pendingHitl = getPendingHitlCalls(messages)[0];
if (is_running || pendingHitl) {
setPhase('streaming');
if (is_running && !pendingHitl && tail?.role === 'assistant') {
setActiveReplyId(tail.id);
}
if (pendingHitl) {
// Prime the ref so continuation events (which
// arrive without a fresh REPLY_START) apply to
// the right msg.
currentReplyRef.current =
messages.find((message) => message.id === pendingHitl.replyId) ??
null;
}
}
// Published synchronously, not through `scheduleUpdate`:
// its requestAnimationFrame batching exists for
// high-frequency streaming deltas, and deferring here
// would let `loadedKey` below clear `loading` a frame
// before the messages land — painting the empty-session
// greeting over a conversation that does have history.
// Both setters now land in the same React batch.
setMsgs([...msgsRef.current]);
} catch (e) {
if (!cancelled) setError(e as Error);
return;
} finally {
// Marks the load done whether it succeeded or threw —
// an error surfaces through `error`, and leaving
// `loading` stuck on would hide it behind a spinner
// forever.
if (!cancelled) setLoadedKey(`${agentId}:${sessionId}`);
}
}
// 2. Open SSE long connection for live events
try {
for await (const event of sessionApi.streamEvents(
sessionId,
agentId,
controller.signal,
eventCursor,
)) {
if (cancelled) break;
processEvent(event);
}
} catch (e) {
if ((e as Error).name !== 'AbortError' && !cancelled) {
setError(e as Error);
}
}
})();
return () => {
cancelled = true;
controller.abort();
abortRef.current = null;
clearInterruptTimer();
};
}, [agentId, sessionId, scheduleUpdate, processEvent, audioManager, clearInterruptTimer]);
/**
* Send a user message. The first idle input appears in the conversation
* immediately (with its matching queue row hidden); later inputs remain
* in the editable queue until ``chat_input_started`` arrives.
*
* @param content - The message content blocks.
*/
const send = useCallback(
async (content: ContentBlock[]) => {
if (!agentId || !sessionId || activeSessionRef.current !== session) return;
const userMsg = UserMsg({ name: 'user', content });
const showInConversationImmediately = phase === 'idle' && pendingQueueCount === 0;
if (showInConversationImmediately) {
msgsRef.current = [...msgsRef.current, userMsg];
scheduleUpdate();
}
const optimisticId = addOptimistic(userMsg, showInConversationImmediately);
try {
const response = await chatApi.trigger({
agent_id: agentId,
session_id: sessionId,
input: userMsg,
});
if (activeSessionRef.current !== session) return;
acceptOptimistic(optimisticId, response.queue_item_id);
} catch (e) {
if (activeSessionRef.current !== session) return;
// The server never accepted this input. Remove the
// optimistic queue row and restore the caller's draft.
rollbackOptimistic(optimisticId, userMsg.id);
if (showInConversationImmediately) {
msgsRef.current = msgsRef.current.filter((msg) => msg.id !== userMsg.id);
scheduleUpdate();
}
setError(e as Error);
throw e;
}
},
[
agentId,
sessionId,
phase,
pendingQueueCount,
session,
scheduleUpdate,
addOptimistic,
acceptOptimistic,
rollbackOptimistic,
],
);
/**
* Confirm or deny a tool call (human-in-the-loop). Sends a
* ``UserConfirmResultEvent`` through realtime control while voice mode
* is active, or through ``POST /chat/`` otherwise. Events arrive via
* SSE in both cases.
*
* @param toolCall - The tool call block to confirm/deny.
* @param confirm - Whether the user confirmed.
* @param replyId - The reply id the tool call belongs to.
* @param rules - Optional permission rules to attach.
*/
const onUserConfirm = useCallback(
async (
toolCall: ToolCallBlock,
confirm: boolean,
replyId: string,
rules?: ToolCallBlock['suggested_rules'],
) => {
if (!agentId || !sessionId) return;
// Restore the ref so continuation events (no REPLY_START)
// have a target.
currentReplyRef.current = msgsRef.current.find((m) => m.id === replyId) ?? null;
const event: UserConfirmResultEvent = {
type: EventType.USER_CONFIRM_RESULT,
id: crypto.randomUUID(),
created_at: new Date().toISOString(),
reply_id: replyId,
confirm_results: [
{ confirmed: confirm, tool_call: toolCall, rules: rules ?? null },
],
};
try {
if (
optionsRef.current?.isRealtimeAudioActive?.() &&
optionsRef.current.sendRealtimeUserConfirm
) {
await optionsRef.current.sendRealtimeUserConfirm(event);
} else {
await chatApi.trigger({
agent_id: agentId,
session_id: sessionId,
input: event,
});
}
} catch (e) {
setError(e as Error);
throw e;
}
},
[agentId, sessionId],
);
const onExternalExecutionResult = useCallback(
async (event: ExternalExecutionResultEvent) => {
if (!agentId || !sessionId || activeSessionRef.current !== session) return;
try {
if (
optionsRef.current?.isRealtimeAudioActive?.() &&
optionsRef.current.sendRealtimeExternalExecutionResult
) {
// Sending a DataChannel frame does not acknowledge its result.
// Register first so even an immediate SSE response is matched.
const receipt = new Promise<void>((resolve, reject) => {
externalSubmissionsRef.current.set(event.id, {
replyId: event.reply_id,
toolCallIds: new Set(
event.execution_results.map((result) => result.id),
),
resolve,
reject,
});
});
await Promise.all([
receipt,
optionsRef.current.sendRealtimeExternalExecutionResult(event),
]);
} else {
await chatApi.trigger({
agent_id: agentId,
session_id: sessionId,
input: event,
});
}
} catch (e) {
if (activeSessionRef.current === session) setError(e as Error);
throw e;
} finally {
externalSubmissionsRef.current.delete(event.id);
}
},
[agentId, sessionId, session],
);
/** Return a client-executed tool result and resume the parked reply. */
const onClientExternalToolResult = useCallback(
async (toolCall: ToolCallBlock, result: ClientExternalToolResult, replyId: string) => {
if (!agentId || !sessionId || activeSessionRef.current !== session) return;
currentReplyRef.current = msgsRef.current.find((msg) => msg.id === replyId) ?? null;
const createdAt = new Date().toISOString();
const nativeResult =
toolCall.name === ASK_USER_TOOL_NAME ? parseAskUserResult(result) : null;
if (toolCall.name === ASK_USER_TOOL_NAME && !nativeResult) {
throw new Error('Invalid AskUser answers');
}
const toolResult: ToolResultBlock = {
type: 'tool_result',
id: toolCall.id,
name: toolCall.name,
output: [
{
type: 'text',
id: crypto.randomUUID(),
text: nativeResult
? formatAskUserOutput(nativeResult)
: typeof result === 'string'
? result
: JSON.stringify(result),
created_at: createdAt,
finished_at: createdAt,
},
],
state: 'success',
metadata: nativeResult ?? {},
created_at: createdAt,
finished_at: createdAt,
};
const event: ExternalExecutionResultEvent = {
type: EventType.EXTERNAL_EXECUTION_RESULT,
id: crypto.randomUUID(),
created_at: createdAt,
reply_id: replyId,
execution_results: [toolResult],
};
await onExternalExecutionResult(event);
},
[agentId, sessionId, session, onExternalExecutionResult],
);
/** Abort the current SSE connection. */
const abort = useCallback(() => {
abortRef.current?.abort();
}, []);
/**
* Request interruption of the in-progress reply (running or parked
* on HITL). Optimistically moves ``phase`` to ``interrupting`` so
* the UI can disable the Stop button; the phase reverts to
* ``idle`` when the backend's terminating ``ReplyEndEvent``
* arrives via SSE (or after a 10s safety timeout, in case that
* event is lost).
*
* Backend contract:
* - 202: interrupt was accepted (cancel signal broadcast for a
* running reply, or wakeup enqueued for a parked one). The
* resulting ``ReplyEndEvent`` arrives through the SSE stream and
* drives the phase transition.
* - Idle sessions are a silent no-op at the agent layer, so
* spamming this callback is safe.
*/
const interrupt = useCallback(async () => {
if (!agentId || !sessionId) return;
// Only escalate to ``interrupting`` if a reply is actually in
// flight; if we're already idle (SSE completed just before the
// click) leave the phase alone.
setPhase((prev) => (prev === 'streaming' ? 'interrupting' : prev));
clearInterruptTimer();
interruptTimerRef.current = setTimeout(() => {
interruptTimerRef.current = null;
setPhase((prev) => (prev === 'interrupting' ? 'idle' : prev));
}, INTERRUPT_TIMEOUT_MS);
try {
await sessionApi.interrupt(sessionId, agentId);
} catch (e) {
clearInterruptTimer();
setPhase((prev) => (prev === 'interrupting' ? 'idle' : prev));
setError(e as Error);
}
}, [agentId, sessionId, clearInterruptTimer]);
/**
* Confirm or deny a tool call that a *team member* is awaiting,
* from this leader view (design §3.6 — backend routing).
*
* The result is POSTed to the **leader** session (the
* ``(agentId, sessionId)`` this hook is bound to), NOT the worker.
* The backend resolves ``reply_id`` → worker session via the
* leader's pending hash and forwards the event to the worker's
* continuation. The client never addresses the worker directly —
* ``entry.worker_*`` ids are used only for local dedup / clearing.
*
* @param entry - The pending subagent HITL entry being resolved.
* @param toolCall - The tool call block to confirm/deny.
* @param confirm - Whether the user confirmed.
* @param rules - Optional permission rules to attach.
*/
const onSubagentConfirm = useCallback(
async (
entry: SubagentHitlEntry,
toolCall: ToolCallBlock,
confirm: boolean,
rules?: ToolCallBlock['suggested_rules'],
) => {
if (!agentId || !sessionId) return;
const event: UserConfirmResultEvent = {
type: EventType.USER_CONFIRM_RESULT,
id: crypto.randomUUID(),
created_at: new Date().toISOString(),
reply_id: entry.reply_id, // worker's reply_id; backend maps it
confirm_results: [
{ confirmed: confirm, tool_call: toolCall, rules: rules ?? null },
],
};
try {
// Post to the leader front door — backend routes to the
// worker session (§3.6). Do NOT address the worker here.
await chatApi.trigger({
agent_id: agentId,
session_id: sessionId,
input: event,
});
} catch (e) {
setError(e as Error);
// Rethrow so the card can re-enable itself and be retried.
throw e;
}
// Drop only the call just answered — an entry can carry several
// pending tool calls, and clearing the whole entry would take the
// unanswered siblings' cards down with it. The backend's clear
// event removes whatever is left.
setSubagentHitl((prev) =>
prev.flatMap((x) => {
if (hitlKey(x) !== hitlKey(entry)) return [x];
const remaining = (x.event.tool_calls ?? []).filter(
(tc) => tc.id !== toolCall.id,
);
return remaining.length > 0
? [{ ...x, event: { ...x.event, tool_calls: remaining } }]
: [];
}),
);
},
[agentId, sessionId],
);
const currentKey = agentId !== null && sessionId !== null ? `${agentId}:${sessionId}` : null;
const ownsConversation = currentKey !== null && loadedKey === currentKey;
const loading = currentKey !== null && !ownsConversation;
return {
msgs: ownsConversation ? msgs : [],
loading,
queuedItems: ownsConversation ? queuedItems : [],
queuedCount: ownsConversation ? queuedCount : 0,
queueReorderDisabled: !ownsConversation || queueReorderDisabled,
updateQueued,
deleteQueued,
moveQueued,
reorderQueued,
phase: ownsConversation ? phase : ('idle' as ReplyPhase),
error: ownsConversation ? error : null,
activeReplyId: ownsConversation && phase === 'streaming' ? activeReplyId : null,
steerQueued,
send,
onUserConfirm,
onClientExternalToolResult,
onExternalExecutionResult,
onSubagentConfirm,
subagentHitl: ownsConversation ? subagentHitl : [],
abort,
interrupt,
};
}