DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
"use client";
import {
useCallback,
useEffect,
useMemo,
useRef,
useState,
type ReactNode,
} from "react";
import { useTranslation } from "react-i18next";
import MarkdownRenderer from "@/components/common/MarkdownRenderer";
import { formatTurnDuration, getTurnDurationSeconds } from "@/lib/trace-timing";
import { describeProviderTool, type ToolProvider } from "@/lib/trace-tools";
import type { StreamEvent } from "@/features/chat/model/protocol";
import {
ActivityDetailGrid,
ActivityDivider,
ActivityFold,
ActivityHeader,
ActivityRow,
ActivityStack,
argumentRows,
type ActivityState,
type DetailRow,
} from "@/components/activity";
import { MODE_SPEED, MODE_TO_ORB } from "./ActivityOrb";
import { AnswererMark } from "./AnswererMark";
import type { Answerer } from "./answerer";
import type {
ResearchStageCard,
ResearchStageId,
TraceDisplayItem,
TraceItem,
TraceMetadata,
} from "./model";
import {
getCallProvider,
getLatestToolProgress,
getToolProvider,
getTraceCallKind,
getTraceGroup,
getTraceMeta,
getTraceRole,
groupTraceEvents,
hasRenderableCallTrace as selectHasRenderableCallTrace,
hasSettledFinalRound,
isChatLoopAnswerContent,
isTracePending,
selectTraceDisplayItems,
} from "./selectors";
// `title` and `hint` are i18n keys resolved via `t(...)` at render time so the
// stage banner follows the active UI language instead of being locked to one.
const RESEARCH_STAGE_SPECS: Array<{
id: ResearchStageId;
titleKey: string;
hintKey: string;
}> = [
{
id: "understand",
titleKey: "research.stage.understand.title",
hintKey: "research.stage.understand.hint",
},
{
id: "decompose",
titleKey: "research.stage.decompose.title",
hintKey: "research.stage.decompose.hint",
},
{
id: "evidence",
titleKey: "research.stage.evidence.title",
hintKey: "research.stage.evidence.hint",
},
{
id: "result",
titleKey: "research.stage.result.title",
hintKey: "research.stage.result.hint",
},
];
/* ------------------------------------------------------------------ */
/* Helpers */
/* ------------------------------------------------------------------ */
function titleCase(value: string) {
return value.replaceAll("_", " ").replace(/\b\w/g, (c) => c.toUpperCase());
}
/** Collapse whitespace and clip to ``max`` chars with an ellipsis. */
/**
* Flatten markdown-ish prose into one line of plain text for a folded row.
*
* Not a markdown parser — it strips the few marks that would otherwise show
* up as literal punctuation in a preview (emphasis, headings, list bullets,
* code fences) and collapses whitespace. Anything it misses degrades to
* showing the raw character, which is acceptable in a one-line teaser.
*/
function plainPreview(value: string, max = 140) {
const flat = value
.replace(/```[\s\S]*?```/g, " ")
.replace(/`([^`]*)`/g, "$1")
.replace(/^\s{0,3}#{1,6}\s+/gm, "")
.replace(/^\s{0,3}[-*+]\s+/gm, "")
.replace(/\*\*([^*]*)\*\*/g, "$1")
.replace(/[*_]{1,2}([^*_]*)[*_]{1,2}/g, "$1")
.replace(/\s+/g, " ")
.trim();
return flat.length > max ? `${flat.slice(0, max)}…` : flat;
}
function clip(value: string, max = 56) {
const text = value.replace(/\s+/g, " ").trim();
return text.length > max ? `${text.slice(0, max - 1)}…` : text;
}
/** Last path segment (handles both / and \\ separators). */
function basename(path: string) {
const trimmed = path.replace(/[/\\]+$/, "");
const parts = trimmed.split(/[/\\]/);
return parts[parts.length - 1] || trimmed;
}
/** A trace-row glyph: either a hand-drawn Mark or a lucide icon. Both accept
* this prop subset, so the row renders them uniformly. */
type ToolDescriptor = {
/** Human action verb (already translated). */
verb: string;
/** The concrete artifact this call touched (file, query, …), or null. */
chip: string | null;
/** Render the chip in a mono face (code / paths / commands). */
mono: boolean;
};
/**
* Maps a tool call to the activity-row vocabulary: a hand-drawn glyph (the
* same organic mark family as the status header — see {@link CommandMark}
* &c.), a human action verb ("Running command", "Reading skill"), and a
* compact chip naming the artifact it acted on (the command, the file, the
* query). Falls back to a humanized tool name + generic mark for unknown
* tools so new tools still read sensibly without a code change.
*
* `provider` short-circuits the switch for tools that come from an MCP server
* or an installed CLI app. Their names are *generated*, so the fallback would
* title-case a machine string — "Mcp Wolfram Wolframalpha" — and tell the reader
* neither which service is being used nor what it was asked to do.
*/
function describeToolCall(
toolName: string,
args: Record<string, unknown> | undefined,
t: (key: string, opts?: Record<string, unknown>) => string,
provider?: ToolProvider | null,
): ToolDescriptor {
const a = args ?? {};
const str = (value: unknown) =>
typeof value === "string" ? value.trim() : "";
// An external provider's row is decided in `lib/trace-tools` — the whole
// decision is data there, so it is unit-tested; only the glyph is resolved
// here, where the marks live.
const providerRow = describeProviderTool(toolName, args, provider, t);
if (providerRow) {
return {
verb: providerRow.verb,
chip: providerRow.chip,
mono: providerRow.mono,
};
}
const host = (url: string) => {
if (!url) return "";
try {
return new URL(url).hostname.replace(/^www\./, "");
} catch {
return url;
}
};
switch (toolName) {
case "exec":
return {
verb: a.language === "shell" ? t("Running command") : t("Running code"),
chip:
a.language === "shell"
? clip(str(a.code), 48) || null
: str(a.language) || t("Python"),
mono: true,
};
case "rag":
return {
verb: t("Searching knowledge"),
chip: clip(str(a.query)) || null,
mono: false,
};
case "kb_files":
return {
verb: t("Listing knowledge base files"),
chip: str(a.kb_name) || null,
mono: false,
};
case "web_search":
return {
verb: t("Searching the web"),
chip: clip(str(a.query)) || null,
mono: false,
};
case "paper_search":
return {
verb: t("Searching papers"),
chip: clip(str(a.query)) || null,
mono: false,
};
case "web_fetch":
return {
verb: t("Fetching page"),
chip: host(str(a.url)) || null,
mono: true,
};
case "read_skill":
return {
verb: t("Reading skill"),
chip: str(a.name) || null,
mono: false,
};
case "load_tools": {
const names = Array.isArray(a.names)
? (a.names as unknown[]).map((n) => String(n))
: [];
return {
verb: t("Loading tools"),
chip: names.join(", ") || null,
mono: true,
};
}
case "read_source":
return {
verb: t("Reading source"),
chip: str(a.source_id) || null,
mono: false,
};
case "read_file":
return {
verb: t("Reading file"),
chip: basename(str(a.path)) || null,
mono: true,
};
case "write_file":
return {
verb: t("Writing file"),
chip: basename(str(a.path)) || null,
mono: true,
};
case "edit_file":
return {
verb: t("Editing file"),
chip: basename(str(a.path)) || null,
mono: true,
};
case "list_dir":
return {
verb: t("Listing files"),
chip: basename(str(a.path)) || null,
mono: true,
};
case "write_note":
return {
verb: t("Writing note"),
chip: clip(str(a.title), 40) || null,
mono: false,
};
case "read_memory":
return {
verb: t("Recalling memory"),
chip: null,
mono: false,
};
case "write_memory":
return {
verb: t("Saving memory"),
chip: null,
mono: false,
};
case "reason":
return {
verb: t("Reasoning"),
chip: clip(str(a.query)) || null,
mono: false,
};
case "brainstorm":
return {
verb: t("Brainstorming"),
chip: clip(str(a.topic)) || null,
mono: false,
};
case "ask_user":
return {
verb: t("Asking you"),
chip: null,
mono: false,
};
case "invoke_other":
return {
verb: t("Proposing a Partner follow-up"),
chip: str(a.target_partner_id)
? `@${str(a.target_partner_id).replace(/^@/, "")}`
: null,
mono: false,
};
case "github":
return {
verb: t("Querying GitHub"),
chip: str(a.target) || null,
mono: true,
};
case "geogebra_analysis":
return {
verb: t("Analyzing figure"),
chip: null,
mono: false,
};
case "visualize":
return {
verb: t("Visualizing"),
chip: null,
mono: false,
};
case "math_animator":
return { verb: t("Animating"), chip: null, mono: false };
default:
return {
verb: titleCase(toolName),
chip: null,
mono: false,
};
}
}
function humanizeQuestionId(
value: string,
t?: (key: string, opts?: Record<string, unknown>) => string,
) {
return value.replace(/\bq_(\d+)\b/gi, (_match, n) =>
t ? t("Question {{n}}", { n }) : `Question ${n}`,
);
}
function getTraceLabel(
events: StreamEvent[],
t?: (key: string, opts?: Record<string, unknown>) => string,
) {
for (const event of events) {
const meta = getTraceMeta(event);
if (meta.label) return humanizeQuestionId(String(meta.label), t);
}
const fallback = events[0]?.stage || "trace";
return humanizeQuestionId(titleCase(fallback), t);
}
/**
* The external provider this trace's tool belongs to, or null for a built-in.
*
* Exported for tests: this and {@link getLatestToolProgress} are the wiring
* between what the backend stamps on a turn's events and what the row shows, and
* they are checked against events recorded from a real LLM turn
* (`tests/fixtures/provider-trace-events.json`).
*
* Scanned across the group rather than read off the `tool_call` event alone: the
* status and progress events carry it too, and a group whose opening event was
* dropped (a reconnect mid-turn) should still be labelled correctly.
*/
export { getLatestToolProgress, getToolProvider } from "./selectors";
function getTraceHeader(
events: StreamEvent[],
nested?: boolean,
t: (key: string, opts?: Record<string, unknown>) => string = (k) => k,
) {
const label = getTraceLabel(events, t);
const role = getTraceRole(events);
const group = getTraceGroup(events);
const kind = getTraceCallKind(events);
const meta = getTraceMeta(events[0]);
let title = label;
if (
[
"math_concept_analysis",
"math_concept_design",
"math_code_generation",
"math_code_retry",
"math_summary",
"math_render_output",
].includes(kind)
) {
title = label;
} else if (kind === "context_exploration") {
// The pre-pass that investigates the turn's attached sources before
// answering. Noun header for the trace row — the turn-level status row
// carries the verb form ("Exploring your context…") so the two never
// read as the same label stacked on itself.
title = t("Context exploration");
} else if (role === "retrieve") {
title = t("Retrieve");
} else if (role === "explore" || kind === "agent_loop_round") {
title = t("Exploring");
} else if (kind === "tool_planning") {
title = t("Tool call");
} else if (group === "react_round") {
if (nested) {
title = meta.round ? t("Round {{n}}", { n: meta.round }) : label;
} else {
const step = meta.step_id ? t("Step {{n}}", { n: meta.step_id }) : "";
const round = meta.round ? t("Round {{n}}", { n: meta.round }) : label;
title = [step, round].filter(Boolean).join(" · ");
}
} else if (role === "plan" && kind === "llm_planning") {
title = t("Plan");
} else if (role === "observe" || kind === "llm_observation") {
title = t("Observe");
} else if (role === "quiz_question" || kind === "quiz_question_emitted") {
// Each quiz question gets its own sub-trace card; index is 0-based in
// metadata, so display as 1-based for the user.
const idx = Number(meta.question_index);
title = Number.isFinite(idx)
? t("Question {{n}}", { n: idx + 1 })
: t("Question");
} else if (role === "response" || kind === "llm_final_response") {
title = t("Response");
} else if (role === "reflection" || kind === "tool_result_reflection") {
// Tool Summarizer sub-trace (Phase 1 of the question pipeline). The
// top-level status row carries the verbose "DeepTutor Reflecting…"
// wording; the sub-trace just labels itself "Reflecting" so the card
// header stays short.
title = t("Reflecting");
} else if (role === "thought" || kind === "llm_reasoning") {
title = t("Thought");
} else if (kind === "llm_generation") {
if (/^generate\s+/i.test(label)) {
title = t("Generating {{label}}", {
label: label.replace(/^generate\s+/i, ""),
});
} else if (/^write\s+/i.test(label)) {
title = t("Writing {{label}}", {
label: label.replace(/^write\s+/i, ""),
});
}
}
return title;
}
// Chat-loop prose belongs to the answer and must not be duplicated in the trace.
function getTraceText(
events: StreamEvent[],
eventTypes: Array<StreamEvent["type"]>,
) {
const textEvents = events.filter(
(event) =>
eventTypes.includes(event.type) &&
event.content.trim().length > 0 &&
!isChatLoopAnswerContent(event),
);
if (!textEvents.length) return "";
const explicitOutputs = textEvents.filter(
(event) => String(getTraceMeta(event).trace_kind || "") === "llm_output",
);
if (explicitOutputs.length > 0) {
return explicitOutputs[explicitOutputs.length - 1].content;
}
return textEvents.map((event) => event.content).join("");
}
// Long string values in tool args are almost always base64 payloads
// (image bytes, file blobs) the LLM never typed itself — they were
// server-injected by the chat pipeline. Pretty-printing the raw value
// fills the trace with megabytes of noise, so we elide anything past
// this many characters down to a short summary.
const TRACE_ARGS_MAX_STRING_CHARS = 200;
function elideLongStrings(value: unknown): unknown {
if (typeof value === "string") {
if (value.length > TRACE_ARGS_MAX_STRING_CHARS) {
const head = value.slice(0, 40);
return `${head}… <${value.length.toLocaleString()} chars elided>`;
}
return value;
}
if (Array.isArray(value)) {
return value.map(elideLongStrings);
}
if (value && typeof value === "object") {
const out: Record<string, unknown> = {};
for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
out[k] = elideLongStrings(v);
}
return out;
}
return value;
}
function formatTraceArgs(args: unknown) {
if (args == null) return "";
try {
return JSON.stringify(elideLongStrings(args), null, 2);
} catch {
return String(args);
}
}
/**
* Per-tool nice rendering for ``tool_call`` args. Some tools (notably
* ``ask_user``) have args that are large structured payloads which the
* UI also renders as a dedicated card below the trace — dumping the raw
* JSON twice is just noise. Returning ``null`` falls back to the
* generic JSON ``<pre>`` block.
*/
function renderNiceToolArgs(
toolName: string | undefined,
rawArgs: unknown,
): ReactNode | null {
if (toolName !== "ask_user" || !rawArgs || typeof rawArgs !== "object") {
return null;
}
const obj = rawArgs as Record<string, unknown>;
const questions = Array.isArray(obj.questions)
? (obj.questions as Array<Record<string, unknown>>)
: [];
if (questions.length === 0) return null;
return (
<ul className="ml-3 mt-0.5 space-y-0.5 text-[10.5px] leading-[1.5] not-italic">
{questions.map((q, idx) => {
const prompt = String(q.prompt ?? q.question ?? "").trim();
if (!prompt) return null;
return (
<li
key={idx}
className="flex items-start gap-1.5 text-[var(--muted-foreground)]"
>
<span className="shrink-0 tabular-nums opacity-50">{idx + 1}.</span>
<span className="min-w-0 flex-1">{prompt}</span>
</li>
);
})}
</ul>
);
}
/**
* Display name for a retrieval / search engine slug.
*
* The backend keeps the authoritative label table (`provider_runtime.py`),
* but it is only reachable through the settings endpoints and a trace row has
* no business calling those. `titleCase` handles most slugs; this table is
* only the ones whose capitalisation it cannot guess.
*/
const PROVIDER_LABELS: Record<string, string> = {
lightrag: "LightRAG",
raganything: "RAGAnything",
pageindex: "PageIndex",
llamaindex: "LlamaIndex",
graphrag: "GraphRAG",
duckduckgo: "DuckDuckGo",
ddg: "DuckDuckGo",
openai: "OpenAI",
aliyun_iqs: "Aliyun IQS",
iqs: "IQS",
bocha: "Bocha",
zhipu: "Zhipu",
};
function providerLabel(slug: string): string {
return PROVIDER_LABELS[slug.toLowerCase()] ?? titleCase(slug);
}
/**
* Tools whose row names its engine.
*
* Only the ones the user picks a provider for. Which engine answered is the
* whole difference between two calls that otherwise render identically, and
* it is the part of the pipeline the reader configured themselves — so
* "Perplexity 联网搜索" says more than "联网搜索" at no extra width.
*/
const ENGINE_NAMED_TOOLS = new Set([
"web_search",
"rag_search",
"rag",
"paper_search",
]);
/** A tool call together with its result, once one arrives. */
type ToolExchange = { call: StreamEvent; result: StreamEvent | null };
/**
* Pair each `tool_call` with the `tool_result` that follows it.
*
* Needed because the two arrive as separate events, and rendering them as
* separate blocks is what made the old detail body read as a list of
* fragments rather than as one exchange.
*/
function pairToolEvents(events: StreamEvent[]): ToolExchange[] {
const out: ToolExchange[] = [];
for (const event of events) {
if (event.type === "tool_call") {
out.push({ call: event, result: null });
continue;
}
const open = out[out.length - 1];
if (open && !open.result) open.result = event;
// A result with no call ahead of it — a resumed turn, or a call event
// filtered upstream — still has to render, so it stands alone.
else out.push({ call: event, result: null });
}
return out;
}
/**
* The second level of a tool row: what went in, and what came back.
*
* Laid out as one label/value grid, because that is what the content is —
* `query`, then `result`, on a shared left edge. The previous version put the
* arguments in a pretty-printed JSON block and the result in a separately
* ruled box below it, which spent most of its area on braces, quotes and a
* second vertical rule. The row's own first level already names the action in
* human terms, so this level never restates it either.
*/
function ToolExchangeDetail({
exchange,
showToolName,
}: {
exchange: ToolExchange;
showToolName: boolean;
}) {
const { call, result } = exchange;
const toolName = (call.metadata?.tool as string | undefined) ?? undefined;
const isCall = call.type === "tool_call";
const niceArgs = isCall
? renderNiceToolArgs(toolName, call.metadata?.args)
: null;
const rawArgs = isCall ? call.metadata?.args : undefined;
const entries = niceArgs ? [] : argumentRows(rawArgs);
// Non-object args (a bare string, an array) have no keys to lay out; they
// land under a generic label rather than inventing a shape for them.
const fallback =
!niceArgs && entries.length === 0 && rawArgs && typeof rawArgs !== "object"
? formatTraceArgs(rawArgs)
: "";
const resultText = result?.content?.trim() || (!isCall ? call.content : "");
const rows: DetailRow[] = [];
if (showToolName && (toolName || call.content)) {
rows.push({ key: "tool", value: toolName || call.content, mono: true });
}
rows.push(...entries);
if (fallback) rows.push({ key: "args", value: fallback, mono: true });
if (resultText) {
rows.push({
key: "result",
value: <MarkdownRenderer content={resultText} variant="trace" />,
});
}
if (!rows.length && !niceArgs) return null;
return (
<div>
<ActivityDetailGrid rows={rows} />
{niceArgs ?? null}
</div>
);
}
/* ------------------------------------------------------------------ */
/* Display-item grouping (step-level) */
/* ------------------------------------------------------------------ */
/* ------------------------------------------------------------------ */
/* Primitive UI pieces */
/* ------------------------------------------------------------------ */
function ScrollableTraceBody({
children,
autoScroll,
className = "ml-5 mr-3 mt-0.5 max-h-[180px] overflow-y-auto px-3 py-1",
}: {
children: React.ReactNode;
autoScroll?: boolean;
className?: string;
}) {
const ref = useRef<HTMLDivElement>(null);
const stickRef = useRef(true);
useEffect(() => {
if (!autoScroll || !stickRef.current) return;
const el = ref.current;
if (el) el.scrollTop = el.scrollHeight;
});
useEffect(() => {
if (autoScroll) stickRef.current = true;
}, [autoScroll]);
const handleScroll = useCallback(() => {
const el = ref.current;
if (!el) return;
stickRef.current = el.scrollHeight - el.scrollTop - el.clientHeight < 30;
}, []);
return (
<div ref={ref} onScroll={handleScroll} className={className}>
{children}
</div>
);
}
function TraceSection({
title,
children,
}: {
title: string;
children: React.ReactNode;
}) {
if (!children) return null;
return (
<div className="space-y-0.5">
<div className="not-italic text-[10px] font-semibold tracking-[0.04em] text-[var(--muted-foreground)]/70">
{title}
</div>
{children}
</div>
);
}
/* ------------------------------------------------------------------ */
/* Per-trace rendering */
/* ------------------------------------------------------------------ */
function TraceRowBody({
callId,
callEvents,
group,
role,
kind,
t,
}: {
callId: string;
callEvents: StreamEvent[];
group: string;
role: string;
kind: string;
t: (key: string) => string;
}) {
const progressEvents = callEvents.filter((event) => {
if (event.type !== "progress") return false;
const traceKind = String(getTraceMeta(event).trace_kind || "");
if (traceKind === "call_status") return false;
return event.content.trim().length > 0;
});
const toolEvents = callEvents.filter(
(event) => event.type === "tool_call" || event.type === "tool_result",
);
const summaryProgressEvents = progressEvents.filter(
(event) => String(getTraceMeta(event).trace_layer || "summary") !== "raw",
);
const rawProgressEvents = progressEvents.filter(
(event) => String(getTraceMeta(event).trace_layer || "") === "raw",
);
const errorEvents = callEvents.filter(
(event) => event.type === "error" && event.content.trim().length > 0,
);
const thoughtText = getTraceText(callEvents, ["thinking"]);
const observationText = getTraceText(callEvents, ["observation"]);
// Chat-loop reasoning belongs in the trace; its public prose stays in the answer.
const isChatRound = kind === "agent_loop_round";
const contentText = getTraceText(callEvents, ["content"]);
const bodyBlocks =
role === "observe"
? [observationText]
: role === "retrieve"
? []
: isChatRound
? [thoughtText, contentText]
: [thoughtText || contentText];
const renderableBodyBlocks = bodyBlocks.filter(
(text): text is string => Boolean(text) && text.trim().length > 0,
);
// A connected subagent's native run streams in as ``subagent_event`` progress
// lines, but those are shown in the side viewer's per-agent tab — keep the
// inline trace compact (the question + the agent's final reply).
const plainSummaryEvents = summaryProgressEvents.filter(
(event) => getTraceMeta(event).trace_kind !== "subagent_event",
);
const inlineSources = callEvents.flatMap(
(event) => getTraceMeta(event).sources ?? [],
);
return (
<div className="text-[11.5px] leading-[1.6] text-[var(--muted-foreground)]">
{group === "react_round" ? (
<div className="space-y-2">
<TraceSection title={t("Thought")}>
{thoughtText ? (
<MarkdownRenderer content={thoughtText} variant="trace" />
) : null}
</TraceSection>
<TraceSection title={t("Tool")}>
{toolEvents.length > 0 ? (
<div className="space-y-0.5">
{pairToolEvents(toolEvents).map((exchange, idx) => (
<ToolExchangeDetail
key={`${callId}-tool-${idx}`}
exchange={exchange}
// Inside a round's "Tool" section the name is the only
// thing identifying which tool ran.
showToolName
/>
))}
</div>
) : null}
</TraceSection>
<TraceSection title={t("Observe")}>
{observationText ? (
<MarkdownRenderer content={observationText} variant="trace" />
) : null}
</TraceSection>
</div>
) : (
<div className="space-y-1">
{plainSummaryEvents.length > 0 && (
<div className="space-y-0.5">
{plainSummaryEvents.map((event, idx) => (
<div key={`${callId}-progress-${idx}`} className="opacity-70">
{event.content}
</div>
))}
</div>
)}
{(role === "retrieve" || kind === "math_render_output") &&
rawProgressEvents.length > 0 && (
<div className="space-y-0.5">
<div className="not-italic text-[11px] font-medium uppercase tracking-[0.08em] text-[var(--muted-foreground)]">
{t("Raw logs")}
</div>
<div className="max-h-[200px] overflow-y-auto rounded-md border border-[var(--border)] bg-[#292524] px-3 py-2 font-mono text-[10px] leading-[1.55] text-[#D6D3D1] shadow-inner">
{rawProgressEvents.map((event, idx) => (
<div
key={`${callId}-raw-${idx}`}
className="whitespace-pre-wrap break-words"
>
{event.content}
</div>
))}
</div>
</div>
)}
{toolEvents.length > 0 && (
<div className="space-y-1">
{pairToolEvents(toolEvents).map((exchange, idx) => (
<ToolExchangeDetail
key={`${callId}-tool-${idx}`}
exchange={exchange}
// The row's own first level already spells the action out,
// so repeating the raw tool name here is noise.
showToolName={false}
/>
))}
</div>
)}
{renderableBodyBlocks.length > 0 && (
<div className="mt-1 space-y-1.5">
{renderableBodyBlocks.map((text, idx) => (
<MarkdownRenderer
key={`${callId}-body-${idx}`}
content={text}
variant="trace"
/>
))}
</div>
)}
</div>
)}
{inlineSources.length > 0 && (
<div className="mt-1 opacity-50">
{t("Sources")}:{" "}
{inlineSources.map((source, idx) => (
<span key={`${callId}-source-${idx}`}>
{idx > 0 && " · "}
{String(source.title || source.query || source.type || "source")}
</span>
))}
</div>
)}
{errorEvents.length > 0 && (
<div className="mt-1 space-y-0.5">
{errorEvents.map((event, idx) => (
<div key={`${callId}-error-${idx}`} className="text-red-400/80">
✗ {event.content}
</div>
))}
</div>
)}
</div>
);
}
function hasExpandableContent(
callEvents: StreamEvent[],
group: string,
role: string,
) {
const progressEvents = callEvents.filter((event) => {
if (event.type !== "progress") return false;
const traceKind = String(getTraceMeta(event).trace_kind || "");
if (traceKind === "call_status") return false;
return event.content.trim().length > 0;
});
const toolEvents = callEvents.filter(
(event) => event.type === "tool_call" || event.type === "tool_result",
);
const summaryProgressEvents = progressEvents.filter(
(event) => String(getTraceMeta(event).trace_layer || "summary") !== "raw",
);
const rawProgressEvents = progressEvents.filter(
(event) => String(getTraceMeta(event).trace_layer || "") === "raw",
);
const errorEvents = callEvents.filter(
(event) => event.type === "error" && event.content.trim().length > 0,
);
const thoughtText = getTraceText(callEvents, ["thinking"]);
const observationText = getTraceText(callEvents, ["observation"]);
const contentText = getTraceText(callEvents, ["content"]);
const genericBodyText =
role === "observe"
? observationText
: role === "retrieve"
? ""
: thoughtText || contentText;
const inlineSources = callEvents.flatMap(
(event) => getTraceMeta(event).sources ?? [],
);
return (
toolEvents.length > 0 ||
summaryProgressEvents.length > 0 ||
rawProgressEvents.length > 0 ||
errorEvents.length > 0 ||
Boolean(genericBodyText) ||
inlineSources.length > 0 ||
(group === "react_round" &&
(Boolean(thoughtText) || Boolean(observationText)))
);
}
/* ------------------------------------------------------------------ */
/* Inline trace rows */
/* ------------------------------------------------------------------ */
/**
* One trace = one Claude-style flat activity line in the message flow:
* a small icon + the meaningful text of this step (reasoning / narration,
* or a tool action with a tool-name chip) shown inline. There is no boxed
* header and no always-visible chevron — a faint chevron only appears on
* hover for rows that carry extra detail.
*
* The live step is auto-expanded so its reasoning streams in full; once it
* completes it folds to a one-line preview (the activity-feed look). A
* manual toggle pins the row from then on.
*/
function TraceRowItem({
trace,
active,
nested,
}: {
trace: TraceItem;
active: boolean;
nested: boolean;
}) {
const { t } = useTranslation();
const [userOpen, setUserOpen] = useState<boolean | null>(null);
const { callId, events: callEvents } = trace;
const first = callEvents[0];
const meta = getTraceMeta(first);
const phase = String(meta.phase || first?.stage || "");
const role = getTraceRole(callEvents);
const group = getTraceGroup(callEvents);
const kind = getTraceCallKind(callEvents);
const header = getTraceHeader(callEvents, nested, t);
if (kind === "llm_final_response") return null;
const expandable = hasExpandableContent(callEvents, group, role);
if (!expandable && !active) return null;
const isToolRow = kind === "tool_planning" || group === "tool_call";
const isChatRound = kind === "agent_loop_round";
const isRetrieve = role === "retrieve";
// The model's own text-form deliberation — chat-loop reasoning/narration and
// pipeline "Thought"/"Plan" rounds. Unlike a tool call (whose result is
// secondary detail worth folding away), here the text IS the substance, so
// it always streams in full and is never collapsed behind a chevron.
const isThinking =
isChatRound ||
role === "thought" ||
kind === "llm_reasoning" ||
kind === "llm_planning";
// The first level IS the default view: no row opens its own detail on its
// own. The single exception is the model's own deliberation, which streams
// in place while its round is live and folds itself away once the round
// settles — watching it think is the point, re-reading it afterwards is
// not. The context-exploration pre-pass opts out even of that: its
// briefing runs long enough to walk the trace up the viewport while the
// page is pinned to the bottom.
const isContextExploration = kind === "context_exploration";
const answering =
isChatRound &&
callEvents.some(isChatLoopAnswerContent);
const autoOpen =
isThinking && !isContextExploration && !answering ? active : false;
const open = expandable && (userOpen ?? autoOpen);
// Every row with detail is clickable now, deliberation included — it has to
// be, since a settled round folds itself and the text has to be reachable.
const canToggle = expandable;
const toolCallEvent = callEvents.find((event) => event.type === "tool_call");
const toolName = String(
(toolCallEvent &&
(getTraceMeta(toolCallEvent).tool_name ||
toolCallEvent.metadata?.tool)) ||
toolCallEvent?.content ||
"",
).trim();
const toolArgs = toolCallEvent?.metadata?.args as
| Record<string, unknown>
| undefined;
const thoughtText = getTraceText(callEvents, ["thinking"]).trim();
const contentText = getTraceText(callEvents, ["content"]).trim();
// Resolve every row into a uniform { icon, headline, chip } triple so the
// activity feed reads consistently across pipelines. Tool calls get a human
// action verb + an artifact chip (the Claude-cowork pattern); retrieval
// surfaces its query; chat reasoning rounds ARE their text (rendered inline
// when open, clamped to a preview when folded).
const provider = getToolProvider(callEvents);
const descriptor =
isToolRow && toolName
? describeToolCall(toolName, toolArgs, t, provider)
: null;
// What the provider last said about its own progress. Only MCP servers and
// CLI apps publish these, and only while the call is open.
const liveStatus = active ? getLatestToolProgress(callEvents) : "";
let headline: string;
let chip: { text: string; mono: boolean } | null = null;
const engine = getCallProvider(callEvents);
if (descriptor) {
headline =
engine && ENGINE_NAMED_TOOLS.has(toolName)
? `${providerLabel(engine)} ${descriptor.verb}`
: descriptor.verb;
chip = descriptor.chip
? { text: descriptor.chip, mono: descriptor.mono }
: null;
// While it runs, how far along it is displaces what it is: the identity is
// already in the verb, and "fetching pages (30%)" is the only thing that
// distinguishes a working call from a hung one. It reverts once settled.
if (liveStatus) chip = { text: liveStatus, mono: false };
// Name the consult after the agent it targets (e.g. "Consult Subagent
// test-cc"); the name rides on the streamed subagent events in the group.
if (toolName === "consult_subagent") {
const agentName = String(
callEvents.map((e) => getTraceMeta(e).subagent_name).find(Boolean) ||
"",
);
const kind = callEvents.map((event) => getTraceMeta(event).subagent_kind).find(Boolean);
const action = kind === "partner_group" ? t("Organize partner discussion")
: kind === "partner" ? t("Ask partner") : t("Ask subagent");
headline = agentName ? `${action} ${agentName}` : action;
}
} else if (isRetrieve) {
headline = engine ? `${providerLabel(engine)} ${header}` : header;
const query = clip(
String(callEvents.map((e) => getTraceMeta(e).query).find(Boolean) || ""),
);
chip = query ? { text: query, mono: false } : null;
} else if (isChatRound) {
// The label, not the prose. A chat round used to title itself with its
// own reasoning, which forced the row to clamp onto two or three lines
// and made it the only row shaped differently from its neighbours. The
// reasoning now trails the label as this row's content, same as a query
// trails a search.
headline = header;
} else {
headline = header;
}
// What the dot has to say. Deliberately about state, not category: the
// row's own text already names the category ("联网搜索 …", "检索", or the
// model's own sentence), so a glyph repeating it spent the one pre-text
// position in the row on something the reader can already see. Where the
// step stands is the part the text never says.
const rowState: ActivityState = callEvents.some(
(event) => event.type === "error" && event.content.trim().length > 0,
)
? "error"
: toolName === "ask_user"
? "awaiting"
: active
? "running"
: "done";
// The model's own deliberation is the one case where the substance lives at
// level one: a chat round's text IS the row, so an open one renders its
// markdown inline rather than a structured detail body.
const deliberation = isChatRound
? [thoughtText, contentText].filter(Boolean)
: [thoughtText || contentText].filter(Boolean);
return (
<ActivityRow
state={rowState}
// Every row is one line: an action, then what it acted on. For a tool
// that is verb + query; for deliberation it is the phase label + the
// opening of the reasoning. The full text is level two.
title={headline}
detail={
chip?.text ??
// The preview is what stands in for the text while the row is folded.
// An open row already shows that text in full below, so repeating its
// opening on the title line prints the same sentence twice — which is
// what a short deliberation looks like the whole time it streams.
(isThinking && deliberation.length && !open
? plainPreview(deliberation[0])
: undefined)
}
detailMono={chip?.mono ?? false}
breathing={active}
followOpen={autoOpen}
autoScrollDetail={active}
className={isChatRound ? "italic" : ""}
>
{isThinking ? (
deliberation.length ? (
<div
className={`space-y-1.5 leading-[1.6] ${isChatRound ? "italic" : ""}`}
>
{deliberation.map((text, idx) => (
<MarkdownRenderer
key={`${callId}-say-${idx}`}
content={text}
variant="trace"
/>
))}
</div>
) : null
) : (
<TraceRowBody
callId={callId}
callEvents={callEvents}
group={group}
role={role}
kind={kind}
t={t}
/>
)}
</ActivityRow>
);
}
export function CallTracePanel({
events,
isStreaming,
nested = false,
}: {
events: StreamEvent[];
isStreaming?: boolean;
// Kept for callers that render the rows inside their own framed shell;
// rows are inline either way, ``nested`` only affects sub-row layout.
nested?: boolean;
}) {
const { t } = useTranslation();
const traceGroups = useMemo(() => groupTraceEvents(events), [events]);
const displayItems: TraceDisplayItem[] = useMemo(
() => selectTraceDisplayItems(traceGroups),
[traceGroups],
);
// Hide the outer container entirely when no sub-trace ends up being
// rendered. ``traceGroups`` can be non-empty even when every group is
// filtered out by ``selectTraceDisplayItems`` (final-response groups and groups
// tagged ``absorbed_into_final``) — in that case we used to draw an
// empty bordered box. Check the materialised displayItems instead.
if (!displayItems.length) return null;
// Rows flow inline with the message — no outer card, no shared scroll
// region. Each row manages its own fold state (live-follow + manual pin)
// and its expanded body has its own bounded scroll area.
return (
<ActivityStack className="mb-3">
{displayItems.map((item, displayIdx) => {
const isLastDisplayItem = displayIdx === displayItems.length - 1;
if (item.kind === "step") {
const lastTrace = item.traces[item.traces.length - 1];
const isActiveStep =
Boolean(isStreaming) &&
isLastDisplayItem &&
isTracePending(lastTrace.events);
// A step is a divider, not a level.
//
// It used to be a third fold wrapping its own hand-written
// Round/Thought/Tool/Observe tree — a second renderer for the same
// trace data, two levels deeper than the flat rows beside it, and
// auto-expanded while live. Now it just labels the group and its
// traces are ordinary first-level rows, so every trace in a turn
// reads, folds and looks the same regardless of which pipeline
// produced it.
return (
<div key={item.stepId} className={displayIdx > 0 ? "mt-2" : ""}>
<ActivityDivider
label={t("Step {{n}}", { n: item.stepId })}
active={isActiveStep}
/>
<ActivityStack alignUnderOrb={false}>
{item.traces.map((trace, idx) => (
<TraceRowItem
key={trace.callId}
trace={trace}
active={
Boolean(isStreaming) &&
isLastDisplayItem &&
idx === item.traces.length - 1 &&
isTracePending(trace.events)
}
nested={nested}
/>
))}
</ActivityStack>
</div>
);
}
const active =
Boolean(isStreaming) &&
isLastDisplayItem &&
isTracePending(item.trace.events);
return (
<TraceRowItem
key={item.trace.callId}
trace={item.trace}
active={active}
nested={nested}
/>
);
})}
</ActivityStack>
);
}
/* ------------------------------------------------------------------ */
/* StreamingStatus — breathing "reasoning" / "tool using" indicator */
/* ------------------------------------------------------------------ */
/* ---- Trace-row glyphs (same hand-drawn family as the status marks) ---- */
type StreamingMode =
| "reasoning"
| "tool_using"
| "responding"
| "responded"
| "planning"
| "exploring"
| "quizzing"
| "reflecting";
/**
* Picks the status label shown above the trace card.
*
* We scan in reverse so each round's latest signal wins — a tool result
* mid-iteration flips the label back to reasoning, a planning chunk
* arriving after a tool flips it to planning, etc. Per-mode mapping:
*
* ``agent_loop_round`` → exploring (chat exploring loop)
* ``llm_planning`` chunks → planning (solve plan / replan / pre-retrieve)
* ``tool_call`` event → tool_using (any explicit tool call)
* ``llm_final_response``
* stage=``writing`` → responding (solve synthesize, also chat default)
* ``llm_reasoning`` chunks → reasoning (generic reasoning trace)
*
* Falls back to ``reasoning`` while events are still warming up.
*/
function detectStreamingMode(
events: StreamEvent[],
hasFinalContent: boolean,
isStreaming: boolean,
): StreamingMode {
if (!isStreaming) return "responded";
for (let idx = events.length - 1; idx >= 0; idx -= 1) {
const event = events[idx];
const meta = (event.metadata ?? {}) as Record<string, unknown>;
const callKind = String(meta.call_kind ?? "");
if (event.type === "tool_call") {
// Tool calls inherit the active stage so the top-level status stays
// coherent (e.g., a rag call during explore reads as "Exploring",
// not generic "Tool Calling").
if (event.stage === "exploring") return "exploring";
if (event.stage === "quizzing") return "quizzing";
return "tool_using";
}
if (event.type === "tool_result") {
// Tool finished — keep scanning for the iteration's actual mode.
continue;
}
// Quiz pipeline emits one ``quiz_question_emitted`` content event per
// question with the structured qa_pair in metadata — that's the signal
// the quizzing phase is active.
if (callKind === "agent_loop_round") {
// The chat loop streams user-facing text as `content` (commentary
// before a tool call, or the closing answer): show "responding" while
// text is flowing; thinking keeps "exploring".
return event.type === "content" ? "responding" : "exploring";
}
if (callKind === "quiz_question_emitted") return "quizzing";
// Question pipeline's Tool Summarizer (Phase 1 reflection over a raw
// tool result) streams chunks under ``call_kind="tool_result_reflection"``.
// While those chunks are arriving — and until the next reasoning / tool
// event flips the mode again — the top-level status row reads
// "DeepTutor Reflecting…".
if (callKind === "tool_result_reflection") return "reflecting";
if (event.type === "content" && callKind === "llm_final_response") {
// Some pipelines stream response text while an exploration stage is
// still open; keep the top-level title on "DeepTutor Exploring…" until
// the bus moves on.
if (event.stage === "exploring") return "exploring";
if (event.stage === "writing") return "responding";
return "responding";
}
if (callKind === "llm_planning") return "planning";
if (event.type === "thinking" && callKind === "llm_reasoning") {
if (event.stage === "exploring") return "exploring";
if (event.stage === "quizzing") return "quizzing";
return "reasoning";
}
}
if (hasFinalContent) return "responding";
return "reasoning";
}
function parsePositiveInt(value: unknown): number | null {
if (typeof value === "number" && Number.isFinite(value) && value > 0) {
return Math.floor(value);
}
if (typeof value === "string") {
const parsed = Number.parseInt(value, 10);
if (Number.isFinite(parsed) && parsed > 0) return parsed;
}
return null;
}
function getResearchTopicIndex(meta: TraceMetadata): number | null {
const explicit = parsePositiveInt(meta.topic_index);
if (explicit) return explicit;
const searchable = [meta.block_id, meta.call_id, meta.trace_id]
.map((value) => String(value || ""))
.join(" ");
const match = /\bblock_(\d+)\b/.exec(searchable);
return match ? parsePositiveInt(match[1]) : null;
}
function getDeepResearchStatusLabel(
events: StreamEvent[],
t: (key: string, opts?: Record<string, unknown>) => string,
isStreaming: boolean,
) {
if (!isStreaming) return null;
for (let idx = events.length - 1; idx >= 0; idx -= 1) {
const event = events[idx];
if (event.source !== "deep_research") continue;
const meta = getTraceMeta(event);
const key = String(meta.research_status_key || "");
if (key === "decompose_target" || event.stage === "decomposing") {
return t("Decomposing Target");
}
if (key === "research_topic" || event.stage === "researching") {
const topicIndex = getResearchTopicIndex(meta);
return topicIndex
? t("Researching Topic #{{n}}", { n: topicIndex })
: t("Researching Topic");
}
if (key === "report_intro") return t("Reporting Intro");
if (key === "report_outline") return t("Reporting Outline");
if (key === "report_conclusion") return t("Reporting Conclusion");
if (key === "report_section") {
const sectionIndex = parsePositiveInt(meta.section_index);
return sectionIndex
? t("Reporting Section #{{n}}", { n: sectionIndex })
: t("Reporting Section");
}
if (event.stage === "reporting") {
const label = String(meta.label || "").toLowerCase();
if (label.includes("intro") || label.includes("引言")) {
return t("Reporting Intro");
}
if (label.includes("conclusion") || label.includes("结论")) {
return t("Reporting Conclusion");
}
if (label.includes("section") || label.includes("章节")) {
const sectionIndex = parsePositiveInt(meta.section_index);
return sectionIndex
? t("Reporting Section #{{n}}", { n: sectionIndex })
: t("Reporting Section");
}
return t("Reporting");
}
}
return null;
}
// While the explore_context pre-pass is the most recent activity, the
// turn-level status reads "Exploring Your Contexts" instead of the generic
// reasoning label. Mirrors getDeepResearchStatusLabel: a backward scan that
// bails as soon as a later (answer-phase) activity is seen.
function getExploreContextStatusLabel(
events: StreamEvent[],
t: (key: string, opts?: Record<string, unknown>) => string,
isStreaming: boolean,
) {
if (!isStreaming) return null;
for (let idx = events.length - 1; idx >= 0; idx -= 1) {
const event = events[idx];
const meta = getTraceMeta(event);
const kind = String(meta.call_kind || "");
const stage = String(event.stage || meta.phase || "");
// Anything still inside the explore pre-pass — its reasoning rounds AND the
// read_source tool calls it fires (stage="context_exploration") — keeps the
// status on the explore verb, so it doesn't flicker to "Tool Calling…".
if (kind === "context_exploration" || stage === "context_exploration") {
return t("Exploring your context…");
}
// The answer loop has taken over — let the normal mode label win.
if (
kind === "agent_loop_round" ||
kind === "llm_final_response" ||
event.type === "tool_call" ||
event.type === "content"
) {
return null;
}
}
return null;
}
function getReasoningProgressStatusLabel(
events: StreamEvent[],
t: (key: string, opts?: Record<string, unknown>) => string,
isStreaming: boolean,
) {
if (!isStreaming) return null;
for (let idx = events.length - 1; idx >= 0; idx -= 1) {
const event = events[idx];
const meta = getTraceMeta(event);
if (meta.trace_kind === "reasoning_progress") {
return t("Still reasoning before acting…");
}
if (
meta.trace_kind === "call_status" &&
(meta.call_state === "running" || meta.call_state === "complete")
) {
return null;
}
if (event.type === "content" || event.type === "tool_call") return null;
}
return null;
}
export function StreamingStatus({
events,
isStreaming,
content,
className = "",
expandable = false,
expanded = false,
onToggle,
summary,
agentName,
answerer,
showMark = true,
traceBounds,
}: {
events: StreamEvent[];
isStreaming?: boolean;
content?: string;
/** A turn handed to a partner or an agent: they own the line, mark and all. */
answerer?: Answerer;
/** The turn's real span, when ``events`` is only a preview of it. */
traceBounds?: { started_at?: number | null; ended_at?: number | null } | null;
// Extra layout classes from the call site (e.g. ``mt-3`` when the row
// sits at the bottom of the assistant output).
className?: string;
// When ``expandable`` the row becomes a disclosure toggle (a trailing
// chevron rotates with ``expanded``) — used by ``AssistantActivity`` to
// fold the trace nested beneath it.
expandable?: boolean;
expanded?: boolean;
onToggle?: () => void;
// What the folded stack holds, shown while it is closed.
summary?: ReactNode;
// Who is doing the thinking — partner chat passes the partner's name so
// the status reads "Ada Exploring…" instead of the product name.
agentName?: string;
// Partner chat shows the partner avatar beside this row, which already
// signals "who / working", so it hides the activity mark to avoid two
// icons fighting on one line.
showMark?: boolean;
}) {
const { t } = useTranslation();
const hasFinalContent = Boolean(content && content.trim().length > 0);
const [nowSeconds, setNowSeconds] = useState(() => Date.now() / 1000);
useEffect(() => {
if (!isStreaming) return;
const timer = window.setInterval(
() => setNowSeconds(Date.now() / 1000),
1000,
);
return () => window.clearInterval(timer);
}, [isStreaming]);
// Only render once we either have a streaming turn, a completed turn that
// produced visible content, or a completed turn whose trace is still worth
// disclosing — empty placeholders (e.g. system message shells) shouldn't
// show a status row. A turn that ran tools and then ended without a
// user-facing answer belongs in that third case: dropping the row there
// also drops the only affordance for opening the trace, so the whole
// activity block renders as an invisible collapsed shell and the turn looks
// like it never happened.
if (!isStreaming && !hasFinalContent && !expandable) return null;
const mode = detectStreamingMode(
events,
hasFinalContent,
Boolean(isStreaming),
);
const name = agentName?.trim() || "DeepTutor";
let modeLabel = t("{{name}} Reasoning…", { name });
if (mode === "tool_using") modeLabel = t("Tool Calling…");
else if (mode === "planning") modeLabel = t("{{name}} Planning…", { name });
// ``responding`` remains a useful transport/trace distinction, but it is
// not a second user-facing phase. Keep the one continuous activity surface
// the conversation already established instead of adding a competing
// "Responding…" label beside the composer.
else if (mode === "responding")
modeLabel = t("{{name}} Exploring…", { name });
else if (mode === "exploring") modeLabel = t("{{name}} Exploring…", { name });
else if (mode === "quizzing") modeLabel = t("{{name}} Quizzing…", { name });
else if (mode === "reflecting")
modeLabel = t("{{name}} Reflecting…", { name });
else if (mode === "responded") modeLabel = t("DeepTutor responded.");
const label =
getExploreContextStatusLabel(events, t, Boolean(isStreaming)) ??
getDeepResearchStatusLabel(events, t, Boolean(isStreaming)) ??
getReasoningProgressStatusLabel(events, t, Boolean(isStreaming)) ??
modeLabel;
// Single turn-level clock. Ticks every second while the turn is in
// flight and freezes on the final elapsed time once the answer ends —
// replaces the per-sub-trace duration chips that used to live inside
// the trace card.
const turnSeconds = getTurnDurationSeconds(
events,
nowSeconds,
Boolean(isStreaming),
traceBounds,
);
const durationLabel =
turnSeconds != null ? formatTurnDuration(turnSeconds) : null;
if (answerer) {
// Their mark where the orb would be, their name held still, and what
// they are doing breathing beside it — "Paul is thinking…", "Paul
// answered". DeepTutor's own phase words do not apply to someone else.
const doing =
mode === "responded"
? t("trace.answerer.done")
: mode === "tool_using"
? t("trace.answerer.tools")
: hasFinalContent
? t("trace.answerer.answering")
: t("trace.answerer.thinking");
return (
<ActivityHeader
orb={MODE_TO_ORB[mode]}
mark={<AnswererMark answerer={answerer} working={mode !== "responded"} />}
lead={<span className="dt-answerer-name">{answerer.name}</span>}
label={doing}
duration={durationLabel}
settled={mode === "responded"}
expandable={expandable}
expanded={expanded}
onToggle={onToggle}
summary={summary}
className={className}
/>
);
}
// Static label after the answer is done — no breathing animation. Every
// other state is live, so the label breathes to signal ongoing work while
// the orb beside it runs its own motion.
return (
<ActivityHeader
orb={MODE_TO_ORB[mode]}
orbSpeed={MODE_SPEED[mode] ?? 1}
label={label}
duration={durationLabel}
settled={mode === "responded"}
expandable={expandable}
expanded={expanded}
onToggle={onToggle}
summary={summary}
showOrb={showMark}
className={className}
/>
);
}
/**
* Whether ``events`` contain at least one renderable trace group — i.e. a
* call_id whose group is NOT a pure final-response and NOT absorbed into the
* final answer. Mirrors the gate ``TraceFlow``/``CallTracePanel`` use to
* decide whether anything will actually render, so callers (e.g. the
* activity header) can show a disclosure affordance only when there is a
* trace to disclose.
*/
function hasRenderableCallTrace(events: StreamEvent[]): boolean {
return selectHasRenderableCallTrace(events);
}
/**
* Inline trace rows for the assistant message flow: each trace renders as
* its own one-line, expandable, live-streaming row — there is no outer
* trace card. Group-level fold (open while working, collapsed once the
* final answer lands) is handled by ``AssistantActivity``, which nests this
* directly under the status header.
*/
export function TraceFlow({
events,
isStreaming,
}: {
events: StreamEvent[];
isStreaming?: boolean;
}) {
// Mount only when at least one renderable trace group exists — groups
// that CallTracePanel would discard (final-response only, or reasoning
// sub-traces absorbed into the final answer) must not leave a stray
// margin behind.
const hasCallTrace = useMemo(() => hasRenderableCallTrace(events), [events]);
if (!hasCallTrace) return null;
return <CallTracePanel events={events} isStreaming={isStreaming} />;
}
/**
* Trace rows hanging from the guide line that aligns them under the activity
* mark, so they read as "nested below" whatever they belong to. Shared by the
* status header's own trace and by the resumed-round trace the chat surface
* renders under an ``ask_user`` card.
*/
export function NestedTraceFlow({
events,
isStreaming,
}: {
events: StreamEvent[];
isStreaming?: boolean;
}) {
return (
<div className="pt-2 [&>div]:mb-0">
<TraceFlow events={events} isStreaming={isStreaming} />
</div>
);
}
/**
* Has the turn entered its final-answer phase? Used to auto-collapse the
* reasoning trace once DeepTutor stops working and starts (or has finished)
* its answer.
*
* - turn complete (``!isStreaming``) → final
* - a pipeline streaming its final write (solve/research) → final
* (``detectStreamingMode`` → responding / responded)
* - chat single loop: the latest completed round settled as terminal
*
* The chat loop streams its final answer as ``agent_loop_round`` content
* (which ``detectStreamingMode`` reads as "exploring"), so a round's own
* completion marker — emitted when it lands — is the chat-path signal.
*/
function isChatLoopTurn(events: StreamEvent[]): boolean {
for (const event of events) {
if (String(getTraceMeta(event).call_kind || "") === "agent_loop_round") {
return true;
}
}
return false;
}
function isFinalAnswerPhase(
events: StreamEvent[],
isStreaming: boolean,
hasFinalContent: boolean,
): boolean {
if (!isStreaming) return true;
if (hasSettledFinalRound(events)) return true;
const mode = detectStreamingMode(events, hasFinalContent, true);
if (mode === "responding" || mode === "responded") {
// Chat's single loop streams commentary mid-loop, which also reads as
// "responding" — there only a settled round marker (above) settles the
// phase; trusting the mode would flap the trace shut on every line of
// commentary and open again on the next tool call.
return !isChatLoopTurn(events);
}
return false;
}
/**
* The assistant activity block: the status header
* ("DeepTutor Exploring… · 8s", settling to "DeepTutor responded. · 10s")
* with the exploring trace nested directly beneath it.
*
* The trace is expanded by default while DeepTutor is still reasoning /
* exploring, and collapses once the turn resolves into its final answer.
* The header doubles as a disclosure toggle, so the user can re-open a
* collapsed trace (or fold an expanded one) at any time.
*/
/**
* Shown while a persisted trace is being fetched.
*
* The header can now open before its rows exist, so without this the panel
* would expand onto nothing and read as broken rather than as loading.
*/
function TraceLoadingRow() {
const { t } = useTranslation();
return (
<div className="flex items-center gap-2 py-1 pl-1 text-xs text-[var(--muted-foreground)]">
<span className="size-1.5 animate-pulse rounded-full bg-[var(--muted-foreground)]" />
{t("Loading the full trace…")}
</div>
);
}
export function AssistantActivity({
events,
traceEvents,
isStreaming,
content,
className = "",
agentName,
answerer,
showMark = true,
headerClassName = "",
onTraceToggle,
traceBounds,
hasStoredTrace = false,
processContent,
processSummary,
}: {
events: StreamEvent[];
/**
* The subset of ``events`` whose trace rows belong under this header.
* Defaults to all of them. The chat surface narrows it to the rounds
* before the first ``ask_user`` card, because the rounds after one render
* below that card instead — this block is pinned to the top of the
* message, so anything appended here after the user answers lands above
* content they have already read.
*/
traceEvents?: StreamEvent[];
isStreaming?: boolean;
content?: string;
className?: string;
/** Forwarded to StreamingStatus — names the thinker in the status row. */
agentName?: string;
/** Forwarded to StreamingStatus — the partner or agent a turn was handed to. */
answerer?: Answerer;
/** Hide the activity mark (partner chat shows its avatar instead). */
showMark?: boolean;
/** Extra classes on the status header row (e.g. a min-height so the row
* vertically centers against an adjacent avatar). */
headerClassName?: string;
/** Notified when a persisted trace is opened or collapsed. */
onTraceToggle?: (open: boolean) => void;
/** The turn's real span, when ``events`` is only a preview of it. */
traceBounds?: { started_at?: number | null; ended_at?: number | null } | null;
/**
* Whether the server still holds trace rows this preview dropped.
*
* A finished turn keeps only a compact preview in memory, and that preview
* discards ``thinking`` — which for a round that called no tools is the
* entire trace. The header then had nothing renderable, so it rendered as
* *not expandable*, so the click that would have fetched the full trace
* could never happen: no rows, therefore no way to ever get rows. This flag
* breaks that circle by letting the header open on the promise of rows.
*/
hasStoredTrace?: boolean;
/**
* The turn's working-out, already laid out by the caller: what it said it
* was about to do, the steps it took, what each one turned up. Given this,
* the header folds THAT away rather than a bare stack of trace rows — the
* whole process becomes one line once the answer lands, and one click
* brings it back.
*
* The chat surface passes it because its process is prose interleaved with
* rows. Surfaces with nothing but rows pass nothing and keep the old
* behaviour.
*/
processContent?: ReactNode;
/** One line naming what ``processContent`` holds, for the folded header. */
processSummary?: ReactNode;
}) {
const shownTraceEvents = traceEvents ?? events;
const hasTrace = useMemo(
() => hasRenderableCallTrace(shownTraceEvents),
[shownTraceEvents],
);
const hasFinalContent = Boolean(content && content.trim().length > 0);
const finalPhase = useMemo(
() => isFinalAnswerPhase(events, Boolean(isStreaming), hasFinalContent),
[events, isStreaming, hasFinalContent],
);
// null = follow the phase automatically (open while working, collapsed
// once answered). A click pins the user's choice for this message.
const [userOpen, setUserOpen] = useState<boolean | null>(null);
// Openable either because rows are already here, or because the server has
// rows to hand over once asked. Auto-open still follows the phase only when
// there is something to show right now: a settled turn stays collapsed until
// the reader asks for it.
const hasProcess = processContent != null;
const expandable = hasProcess || hasTrace || hasStoredTrace;
const open =
expandable && (userOpen ?? ((hasProcess || hasTrace) && !finalPhase));
// Match StreamingStatus's own null-guard — it takes ``expandable`` into
// account for exactly this case, so both surfaces appear or neither does.
if (!isStreaming && !hasFinalContent && !expandable) return null;
return (
<div className={className}>
<StreamingStatus
events={events}
isStreaming={isStreaming}
content={content}
expandable={expandable}
expanded={open}
onToggle={() => {
const next = !open;
setUserOpen(next);
onTraceToggle?.(next);
}}
summary={processSummary}
agentName={agentName}
answerer={answerer}
showMark={showMark}
className={headerClassName}
traceBounds={traceBounds}
/>
{expandable ? (
<ActivityFold open={open}>
{/* The process hangs from a faint guide line on the header's own
left edge — where the activity mark sits — with its content
indented past it, so the working-out reads as nested inside the
turn while the answer below stays at the top level. pt-2 = gap
below the header when open; [&>div]:mb-0 strips CallTracePanel's
own bottom margin so the single gap to the body comes from this
block's outer ``mb-3`` in both states. */}
{hasProcess ? (
<div className="pt-2">{processContent}</div>
) : hasTrace ? (
<NestedTraceFlow
events={shownTraceEvents}
isStreaming={isStreaming}
/>
) : (
<TraceLoadingRow />
)}
</ActivityFold>
) : null}
</div>
);
}
/* ------------------------------------------------------------------ */
/* ResearchStagePanel */
/* ------------------------------------------------------------------ */
function getResearchStageId(event: StreamEvent): ResearchStageCard["id"] {
const meta = getTraceMeta(event);
const explicitStage = String(
(event.metadata as Record<string, unknown> | undefined)
?.research_stage_card || "",
);
if (
explicitStage === "understand" ||
explicitStage === "decompose" ||
explicitStage === "evidence" ||
explicitStage === "result"
) {
return explicitStage;
}
const stage = String(event.stage || meta.phase || "");
const text = String(event.content || "").toLowerCase();
const agent = String(
(event.metadata as Record<string, unknown> | undefined)?.agent_name || "",
);
if (stage === "reporting") return "result";
if (stage === "decomposing" || agent === "decompose_agent")
return "decompose";
if (stage === "rephrasing" || agent === "rephrase_agent") return "understand";
if (stage === "planning") {
if (text.includes("decompose") || text.includes("queue"))
return "decompose";
return "understand";
}
return "evidence";
}
function formatResearchStageSummary(events: StreamEvent[], fallback: string) {
const progressEvents = events.filter(
(event) => event.type === "progress" && event.content.trim().length > 0,
);
const lastProgress = progressEvents.at(-1)?.content.trim();
if (lastProgress) {
return humanizeQuestionId(titleCase(lastProgress.replaceAll("-", "_")));
}
const thought = getTraceText(events, ["thinking"]);
if (thought) return thought.slice(0, 120);
const content = getTraceText(events, ["content"]);
if (content) return content.slice(0, 120);
return fallback;
}
export function ResearchStagePanel({
events,
isStreaming,
}: {
events: StreamEvent[];
isStreaming?: boolean;
}) {
const { t } = useTranslation();
const cards = useMemo<ResearchStageCard[]>(() => {
return RESEARCH_STAGE_SPECS.map((spec) => ({
id: spec.id,
title: t(spec.titleKey),
hint: t(spec.hintKey),
events: events.filter((event) => getResearchStageId(event) === spec.id),
})).filter((card) => card.events.length > 0);
}, [events, t]);
if (!cards.length) return null;
return (
<ActivityStack className="mb-3">
{cards.map((card, index) => {
const hasTrace = card.events.some((event) =>
Boolean(getTraceMeta(event).call_id),
);
const active =
Boolean(isStreaming) &&
index === cards.length - 1 &&
card.events.some(
(event) => isTracePending([event]) || event.type === "progress",
);
const summary = formatResearchStageSummary(card.events, card.hint);
return (
// A research stage is one activity row whose second level is the
// trace of the calls it made. It used to be a bespoke header with
// its own spinner beside a separately-rendered trace panel; going
// through `ActivityRow` means a stage folds, aligns and signals
// exactly like every other line of work in the product.
<ActivityRow
key={card.id}
state={active ? "running" : "done"}
title={card.title}
detail={summary}
breathing={active}
followOpen={active}
autoScrollDetail={active}
>
{hasTrace ? (
<CallTracePanel events={card.events} isStreaming={isStreaming} />
) : null}
</ActivityRow>
);
})}
</ActivityStack>
);
}