Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: stop a generation recovery deleting the turn's tool calls (#10584)

Michael Han7436c103e9c0
diff --git a/studio/frontend/src/features/chat/api/chat-adapter.ts b/studio/frontend/src/features/chat/api/chat-adapter.ts
index 5994e2e8d8f..dca408f18c9 100644
--- a/studio/frontend/src/features/chat/api/chat-adapter.ts
+++ b/studio/frontend/src/features/chat/api/chat-adapter.ts
@@ -299,6 +299,12 @@ import {
useResearchRunStore,
watchResearchRun,
} from "../stores/research-run-store";
+import {
+ documentCitationToSource,
+ isSafeNavigableSourceUrl,
+ parseSourcesFromResult,
+} from "../utils/document-citation-source";
+import { mergeGoogleNativeParts } from "../utils/google-native-parts";
import { cancelResearchRun, createResearchRun } from "./research-api";
import {
cancelChatGenerationRun,
@@ -662,118 +668,6 @@ async function updateStoredChatThreadEventually(
}
}
-/** Return `raw` when it is a safe http(s) URL, else "": rejects CR/LF and javascript:/data:/
- * vbscript: so provider strings cannot land in an <a href>. */
-function isSafeNavigableSourceUrl(raw: unknown): string {
- if (typeof raw !== "string") return "";
- const value = raw.trim();
- if (!value || /[\r\n]/.test(value)) return "";
- try {
- const parsed = new URL(value);
- if (parsed.protocol === "http:" || parsed.protocol === "https:") {
- return value;
- }
- } catch {
- }
- return "";
-}
-
-/** Convert an Anthropic document citation dict into a Sources-panel source. */
-function documentCitationToSource(
- cit: Record<string, unknown>,
- fallbackIdx: number,
-): {
- type: "source";
- sourceType: "url";
- id: string;
- url: string;
- title: string;
- metadata?: { description: string };
-} | null {
- const source = typeof cit.source === "string" && cit.source ? cit.source : "";
- const docTitle =
- (typeof cit.document_title === "string" && cit.document_title) ||
- (typeof cit.title === "string" && cit.title) ||
- "";
- const docIndex =
- typeof cit.document_index === "number" ? cit.document_index : undefined;
- // search_result_location `source` can be a free-form id or a hostile scheme; fall back to a
- // doc anchor unless it is real http(s).
- const url =
- isSafeNavigableSourceUrl(source) ||
- `#anthropic-doc-${docIndex ?? fallbackIdx}`;
- const title = docTitle || source || `Document ${fallbackIdx + 1}`;
- const cited = typeof cit.cited_text === "string" ? cit.cited_text.trim() : "";
- const description = cited.length > 240 ? `${cited.slice(0, 240)}...` : cited;
- // Anthropic numbers inline [N] per citation, so fold citation type and position into the id.
- const citationType = typeof cit.type === "string" ? String(cit.type) : "";
- const positionParts = [
- cit.search_result_index,
- cit.start_char_index,
- cit.end_char_index,
- cit.start_page_number,
- cit.end_page_number,
- cit.start_block_index,
- cit.end_block_index,
- ]
- .filter((v) => typeof v === "number")
- .map((v) => String(v))
- .join(":");
- const idAnchor = positionParts
- ? `${citationType}:${positionParts}`
- : `${citationType}:${fallbackIdx}`;
- const id = `${url}#${idAnchor}`;
- return {
- type: "source" as const,
- sourceType: "url" as const,
- id,
- url,
- title,
- ...(description ? { metadata: { description } } : {}),
- };
-}
-
-/** Parse "Title: ...\nURL: ...\nSnippet: ..." blocks into source content parts. */
-function parseSourcesFromResult(raw: string): {
- type: "source";
- sourceType: "url";
- id: string;
- url: string;
- title: string;
- metadata?: { description: string };
-}[] {
- if (!raw) return [];
- const blocks = raw.split(/\n---\n/).filter(Boolean);
- const sources: {
- type: "source";
- sourceType: "url";
- id: string;
- url: string;
- title: string;
- metadata?: { description: string };
- }[] = [];
- for (const block of blocks) {
- const titleMatch = block.match(/Title:\s*(.+)/);
- const urlMatch = block.match(/URL:\s*(.+)/);
- const snippetMatch = block.match(/Snippet:\s*(.+)/);
- if (titleMatch && urlMatch) {
- // Provider output is attacker-controllable: a non-http(s) URL must not reach the Sources panel <a href>.
- const url = isSafeNavigableSourceUrl(urlMatch[1]);
- if (!url) continue;
- const snippet = snippetMatch?.[1]?.trim();
- sources.push({
- type: "source" as const,
- sourceType: "url" as const,
- id: url,
- url,
- title: titleMatch[1].trim(),
- ...(snippet ? { metadata: { description: snippet } } : {}),
- });
- }
- }
- return sources;
-}
-
function estimateTokenCount(text: string): number | undefined {
const trimmed = text.trim();
if (!trimmed) {
@@ -5241,6 +5135,9 @@ export function createOpenAIStreamAdapter(
[key: string]: unknown;
};
type PositionedToolCallPart = ToolCallMessagePart & {
+ backendToolCallId?: string;
+ generationToolCallId?: string;
+ toolApprovalId?: string;
textCursor?: number;
_delta_index?: number;
_has_stable_id?: boolean;
@@ -6675,6 +6572,15 @@ export function createOpenAIStreamAdapter(
toolEvent.arguments_text,
toolArgs,
);
+ const toolIdentity = {
+ backendToolCallId,
+ ...(generationRunId
+ ? {
+ generationToolCallId: `${generationRunId}:${generationSeq}`,
+ }
+ : {}),
+ ...(approvalId ? { toolApprovalId: approvalId } : {}),
+ };
const idx = toolCallParts.findIndex(
(p) => p.toolCallId === id,
);
@@ -6684,6 +6590,7 @@ export function createOpenAIStreamAdapter(
] as PositionedToolCallPart;
toolCallParts[idx] = {
...existing,
+ ...toolIdentity,
toolName: toolEvent.tool_name as string,
argsText: toolArgsText,
args: toolArgs,
@@ -6696,6 +6603,7 @@ export function createOpenAIStreamAdapter(
toolCallParts.push({
type: "tool-call" as const,
toolCallId: id,
+ ...toolIdentity,
toolName: toolEvent.tool_name as string,
argsText: toolArgsText,
args: toolArgs,
@@ -6858,86 +6766,12 @@ export function createOpenAIStreamAdapter(
typeof toolEvent.arguments === "object"
? (toolEvent.arguments as ToolCallMessagePart["args"])
: undefined;
- const mergedArgs: ToolCallMessagePart["args"] = {
- ...(toolCallParts[idx].args ?? {}),
- ...(nextArgs ?? {}),
- } as ToolCallMessagePart["args"];
+ const mergedArgs = mergeGoogleNativeParts(
+ { ...(toolCallParts[idx].args ?? {}), ...(nextArgs ?? {}) },
+ toolEvent.google,
+ ) as ToolCallMessagePart["args"];
const overwrittenArgumentKeys =
nextArgs !== undefined ? Object.keys(nextArgs) : [];
- // Merge tool_end native_part into args.google so the
- // outbound translator replays both start (executableCode)
- // and end (result / inlineData) on the same turn.
- // Concatenate so each part keeps its own thoughtSignature.
- const endGoogle = (
- toolEvent as { google?: { native_part?: unknown } }
- ).google;
- if (
- endGoogle &&
- typeof endGoogle === "object" &&
- endGoogle.native_part &&
- typeof endGoogle.native_part === "object"
- ) {
- const argsObj = mergedArgs as Record<string, unknown>;
- const existingGoogle = (argsObj.google ?? {}) as Record<
- string,
- unknown
- >;
- const existingNative =
- (existingGoogle.native_part as Record<
- string,
- unknown
- >) ?? {};
- const endNative = endGoogle.native_part as Record<
- string,
- unknown
- >;
- // Extract part entries from parts:[...] or a legacy single-object native_part; a legacy
- // thoughtSignature always belongs on executableCode.
- const collectParts = (
- native: Record<string, unknown>,
- ): Record<string, unknown>[] => {
- if (Array.isArray(native.parts)) {
- return (native.parts as unknown[]).filter(
- (entry): entry is Record<string, unknown> =>
- Boolean(entry) &&
- typeof entry === "object" &&
- !Array.isArray(entry),
- );
- }
- const out: Record<string, unknown>[] = [];
- const legacySig =
- typeof native.thoughtSignature === "string"
- ? native.thoughtSignature
- : typeof native.thought_signature === "string"
- ? (native.thought_signature as string)
- : null;
- for (const key of [
- "executableCode",
- "codeExecutionResult",
- "inlineData",
- ] as const) {
- const sub = native[key];
- if (sub && typeof sub === "object") {
- const entry: Record<string, unknown> = {
- [key]: sub,
- };
- if (key === "executableCode" && legacySig) {
- entry.thoughtSignature = legacySig;
- }
- out.push(entry);
- }
- }
- return out;
- };
- const mergedParts = [
- ...collectParts(existingNative),
- ...collectParts(endNative),
- ];
- argsObj.google = {
- ...existingGoogle,
- native_part: { parts: mergedParts },
- };
- }
const existing = toolCallParts[
idx
] as PositionedToolCallPart;
diff --git a/studio/frontend/src/features/chat/runtime-provider.tsx b/studio/frontend/src/features/chat/runtime-provider.tsx
index 0f153230446..7e1f51c3b9c 100644
--- a/studio/frontend/src/features/chat/runtime-provider.tsx
+++ b/studio/frontend/src/features/chat/runtime-provider.tsx
@@ -113,6 +113,7 @@ import {
generationIsCorroboratedLive,
threadHasDurableGenerationRun,
generationNeedsRecovery,
+ restoreCarriedPartsFromRaw,
isLiveGenerationRun,
generationRawContent,
loadGenerationOverlaySnapshot,
@@ -126,6 +127,7 @@ import {
shouldPreserveGenerationMetadata,
subscribeGenerationRecoveryTriggers,
} from "./utils/chat-generation-recovery";
+import { createGenerationToolRecovery } from "./utils/generation-tool-recovery";
import { mergeContextTruncation } from "./utils/context-truncation";
import {
extractDeltaText,
@@ -866,7 +868,10 @@ function scheduleGenerationRecovery(
const recovery = (async () => {
let cursor = Number(metadata.generationSeq ?? 0);
if (!Number.isSafeInteger(cursor) || cursor < 0) cursor = 0;
- let { raw, reasoningOpen } = generationRawContent(storedMessage.content);
+ const stored = generationRawContent(storedMessage.content);
+ const carried = stored.carried;
+ const toolRecovery = createGenerationToolRecovery(carried, runId, cursor);
+ let { raw, reasoningOpen } = stored;
let completionTokens: number | undefined;
let recoveryUsage:
| {
@@ -898,6 +903,22 @@ function scheduleGenerationRecovery(
owner: serverCancel,
});
+ // Save and finalisation share ONE rebuild: derived apart, the names lag a publish or are empty.
+ const rebuild = () =>
+ toolRecovery.withSources(
+ restoreCarriedPartsFromRaw(
+ reasoningOpen ? `${raw}</think>` : raw,
+ carried,
+ ),
+ ) as MessageRecord["content"];
+ const toolNames = (content: MessageRecord["content"]): string[] =>
+ (Array.isArray(content) ? content : []).flatMap((part) => {
+ const card = part as { type?: string; toolName?: unknown };
+ return card.type === "tool-call" && typeof card.toolName === "string"
+ ? [card.toolName]
+ : [];
+ });
+
/** Write one state of the reply to storage and to every view showing it. `running` is the
* caller's, not derived here: a follow that hit its no-progress deadline settles the message
* while its persisted run status is still non-terminal. */
@@ -906,9 +927,7 @@ function scheduleGenerationRecovery(
running: boolean,
) => {
currentMetadata = nextMetadata;
- const content = parseAssistantContent(
- reasoningOpen ? `${raw}</think>` : raw,
- ) as MessageRecord["content"];
+ const content = rebuild();
await saveStoredChatMessage({
id: storedMessage.id,
threadId,
@@ -988,6 +1007,7 @@ function scheduleGenerationRecovery(
timings: recoveryTimings,
firstChunkAt,
totalChunks,
+ toolCalls: toolNames(rebuild()),
});
}
await commit(nextMetadata, generationNeedsRecovery(nextMetadata));
@@ -1001,7 +1021,7 @@ function scheduleGenerationRecovery(
let followStalled = false;
try {
for await (const update of followChatGenerationRun(runId, {
- replayFrom: cursor,
+ replayFrom: toolRecovery.replayFrom,
})) {
if (!identityValidated) {
if (
@@ -1027,7 +1047,18 @@ function scheduleGenerationRecovery(
}
identityValidated = true;
}
+ // Replay from 0 re-delivers already-saved chunks: apply them, but publish nothing.
+ let advanced = false;
+ if (update.event?.type === "chunk") {
+ toolRecovery.apply(
+ update.event.payload,
+ raw.length,
+ update.event.seq,
+ update.run.requestPayload.session_id,
+ );
+ }
if (update.event && update.event.seq > cursor) {
+ advanced = true;
cursor = update.event.seq;
if (update.event.type === "chunk") {
const chunk = update.event.payload as {
@@ -1097,7 +1128,7 @@ function scheduleGenerationRecovery(
}
}
const shouldPublish =
- update.event?.type === "chunk" ||
+ (update.event?.type === "chunk" && advanced) ||
update.run.status !== lastPublishedStatus ||
(["cancelled", "completed", "failed"].includes(update.run.status) &&
cursor >= update.run.lastEventSeq);
diff --git a/studio/frontend/src/features/chat/utils/chat-generation-recovery.ts b/studio/frontend/src/features/chat/utils/chat-generation-recovery.ts
index 52a4982f885..8356a95cacb 100644
--- a/studio/frontend/src/features/chat/utils/chat-generation-recovery.ts
+++ b/studio/frontend/src/features/chat/utils/chat-generation-recovery.ts
@@ -2,7 +2,11 @@
// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
import type { ChatGenerationStatus } from "../api/chat-generation-api";
-import { extractDeltaText } from "./parse-assistant-content";
+import {
+ createThinkTagTracker,
+ extractDeltaText,
+ parseAssistantContent,
+} from "./parse-assistant-content";
export type StoredGenerationStatus = ChatGenerationStatus;
@@ -138,6 +142,7 @@ export function recoveredGenerationFinalMetadata(options: {
timings?: RecoveryTimings;
firstChunkAt?: number;
totalChunks: number;
+ toolCalls?: string[];
}): Record<string, unknown> {
const { current, run, usage, timings, firstChunkAt, totalChunks } = options;
const modelId =
@@ -197,7 +202,7 @@ export function recoveredGenerationFinalMetadata(options: {
finishedAt,
durationMs: Math.max(0, finishedAt - startedAt),
cancelId: run.id,
- toolCalls: [],
+ toolCalls: options.toolCalls ?? [],
};
}
if (next.timing === undefined) {
@@ -209,57 +214,312 @@ export function recoveredGenerationFinalMetadata(options: {
tokenCount: completionTokens,
tokensPerSecond,
totalChunks,
- toolCallCount: 0,
+ toolCallCount: options.toolCalls?.length ?? 0,
};
}
return next;
}
-/** The reply as one string, with reasoning back inside `<think>` tags. The recovery replays a
- * run's chunk events, so it keeps the reply as the text those chunks carried rather than as
- * parts. Inverse of `parseAssistantContent`, so a parts body can be compared to a delta one. */
+// Keep offsets aligned with parseAssistantContent's tags.
+const THINK_OPEN = "<think>";
+const THINK_CLOSE = "</think>";
+
+/** A part the raw projection cannot express, kept with the offset it sat at. */
+export type CarriedPart = { at: number; part: unknown };
+
export function generationRawContent(content: unknown): {
raw: string;
reasoningOpen: boolean;
+ carried: CarriedPart[];
} {
if (typeof content === "string") {
- return { raw: content, reasoningOpen: false };
+ return { raw: content, reasoningOpen: false, carried: [] };
+ }
+ if (!Array.isArray(content)) {
+ return { raw: "", reasoningOpen: false, carried: [] };
}
- if (!Array.isArray(content)) return { raw: "", reasoningOpen: false };
let raw = "";
let reasoningOpen = false;
+ const carried: CarriedPart[] = [];
for (const part of content) {
if (!part || typeof part !== "object") continue;
const record = part as { type?: string; text?: unknown };
const text = typeof record.text === "string" ? record.text : "";
if (record.type === "reasoning") {
if (reasoningOpen) raw += text;
- else raw += `<think>${text}`;
+ else raw += `${THINK_OPEN}${text}`;
reasoningOpen = true;
} else if (record.type === "text") {
- if (reasoningOpen) raw += "</think>";
+ if (reasoningOpen) raw += THINK_CLOSE;
raw += text;
reasoningOpen = false;
+ } else {
+ carried.push({ at: raw.length, part });
+ }
+ }
+ return { raw, reasoningOpen, carried };
+}
+
+export function restoreCarriedParts<TPart>(
+ parts: readonly TPart[],
+ carried: readonly CarriedPart[],
+): TPart[] {
+ if (carried.length === 0) return [...parts];
+ const pending = [...carried].sort((a, b) => a.at - b.at);
+ const out: TPart[] = [];
+ let next = 0;
+ let offset = 0;
+ let reasoningOpen = false;
+ const flushUpTo = (limit: number) => {
+ while (next < pending.length && pending[next].at <= limit) {
+ out.push(pending[next].part as TPart);
+ next += 1;
+ }
+ };
+ for (const part of parts) {
+ const record = part as { type?: string; text?: unknown };
+ const text = typeof record.text === "string" ? record.text : "";
+ flushUpTo(offset);
+ if (record.type === "reasoning") {
+ if (!reasoningOpen) offset += THINK_OPEN.length;
+ reasoningOpen = true;
+ } else if (record.type === "text") {
+ if (reasoningOpen) offset += THINK_CLOSE.length;
+ reasoningOpen = false;
+ } else {
+ out.push(part);
+ continue;
+ }
+ flushUpTo(offset);
+ let cut = 0;
+ while (next < pending.length && pending[next].at < offset + text.length) {
+ const at = pending[next].at - offset;
+ if (at > cut) out.push({ ...record, text: text.slice(cut, at) } as TPart);
+ out.push(pending[next].part as TPart);
+ cut = at;
+ next += 1;
+ }
+ if (cut === 0) out.push(part);
+ else if (cut < text.length) {
+ out.push({ ...record, text: text.slice(cut) } as TPart);
+ }
+ offset += text.length;
+ }
+ while (next < pending.length) {
+ out.push(pending[next].part as TPart);
+ next += 1;
+ }
+ return out;
+}
+
+/** A card offset is the raw length at a chunk boundary, and a think tag can arrive split
+ * across two chunks, so an offset can land inside one. Cutting there leaves the tag's halves
+ * as text AND lets the tracker reopen the block, so the reply projects back with the tag
+ * twice. A tag is atomic: put the card past it. */
+function pastThinkTag(raw: string, at: number): number {
+ for (const tag of [THINK_OPEN, THINK_CLOSE]) {
+ const start = raw.lastIndexOf(tag, at);
+ if (start !== -1 && at > start && at < start + tag.length) {
+ return start + tag.length;
}
}
- return { raw, reasoningOpen };
+ return at;
+}
+
+/** Split raw replay before parsing, since parsing can coalesce separate think blocks. */
+export function restoreCarriedPartsFromRaw(
+ raw: string,
+ carried: readonly CarriedPart[],
+): ReturnType<typeof parseAssistantContent> {
+ if (carried.length === 0) return parseAssistantContent(raw);
+ const out: ReturnType<typeof parseAssistantContent> = [];
+ const tracker = createThinkTagTracker();
+ let cursor = 0;
+ const appendUntil = (end: number) => {
+ const text = raw.slice(cursor, end);
+ out.push(
+ ...parseAssistantContent(
+ tracker.endsInsideThink() ? `${THINK_OPEN}${text}` : text,
+ ),
+ );
+ tracker.append(text);
+ cursor = end;
+ };
+ for (const entry of [...carried].sort((a, b) => a.at - b.at)) {
+ appendUntil(
+ Math.max(cursor, pastThinkTag(raw, Math.min(entry.at, raw.length))),
+ );
+ out.push(entry.part as (typeof out)[number]);
+ }
+ appendUntil(raw.length);
+ return out;
+}
+
+function carriedPartKey({ at, part }: CarriedPart): string {
+ const record = part as { type?: string; toolCallId?: string; id?: string };
+ const id = record.toolCallId ?? record.id;
+ return id === undefined
+ ? JSON.stringify([at, part])
+ : JSON.stringify([record.type, id]);
+}
+
+type ToolIdentity = {
+ type?: string;
+ toolCallId?: string;
+ toolName?: string;
+ backendToolCallId?: string;
+ generationToolCallId?: string;
+ toolApprovalId?: string;
+};
+
+function followingCarriedMatches(matches: (number | undefined)[]) {
+ let next: number | undefined;
+ const following = matches.map(() => undefined as number | undefined);
+ for (let i = matches.length - 1; i >= 0; i--) {
+ following[i] = next;
+ next = matches[i] ?? next;
+ }
+ return following;
+}
+
+function carriedPartMatches(view: CarriedPart[], recovered: CarriedPart[]) {
+ // Every occurrence, not the last: sources are not deduplicated, so a repeated url needs a slot each.
+ const byId = new Map<string, number[]>();
+ recovered.forEach((entry, i) => {
+ const key = carriedPartKey(entry);
+ const seen = byId.get(key);
+ if (seen) seen.push(i);
+ else byId.set(key, [i]);
+ });
+ const byGeneration = new Map<string, number>();
+ recovered.forEach(({ part }, i) => {
+ const id = (part as ToolIdentity).generationToolCallId;
+ if (id) byGeneration.set(id, i);
+ });
+ const used = new Set<number>();
+ const matches = view.map((entry) => {
+ const id = (entry.part as ToolIdentity).generationToolCallId;
+ const index =
+ byId.get(carriedPartKey(entry))?.shift() ??
+ (id ? byGeneration.get(id) : undefined);
+ if (index === undefined || used.has(index)) return undefined;
+ used.add(index);
+ return index;
+ });
+ // Legacy cards lack replay ids. Pair occurrences at the same position one to one.
+ const following = followingCarriedMatches(matches);
+ let previous: number | undefined;
+ view.forEach((entry, i) => {
+ const live = entry.part as ToolIdentity;
+ if (matches[i] !== undefined) {
+ previous = matches[i];
+ return;
+ }
+ if (live.type !== "tool-call" || live.generationToolCallId) return;
+ const next = following[i];
+ const index = recovered.findIndex((candidate, j) => {
+ const saved = candidate.part as ToolIdentity;
+ if (
+ used.has(j) ||
+ (previous !== undefined && j <= previous) ||
+ (next !== undefined && j >= next) ||
+ candidate.at !== entry.at ||
+ saved.type !== "tool-call" ||
+ !saved.generationToolCallId ||
+ saved.toolName !== live.toolName
+ )
+ return false;
+ if (
+ saved.toolApprovalId &&
+ (live.toolApprovalId === saved.toolApprovalId ||
+ live.toolCallId === saved.toolApprovalId ||
+ live.toolCallId?.endsWith(`:${saved.toolApprovalId}`))
+ )
+ return true;
+ if (saved.toolApprovalId && live.toolApprovalId) return false;
+ const backendId = saved.backendToolCallId;
+ return (
+ Boolean(backendId) &&
+ (live.backendToolCallId !== undefined
+ ? live.backendToolCallId === backendId
+ : live.toolCallId === backendId ||
+ live.toolCallId?.startsWith(`${backendId}:`))
+ );
+ });
+ if (index < 0) return;
+ matches[i] = index;
+ previous = index;
+ used.add(index);
+ });
+ return matches;
+}
+
+function mergeCarriedParts(
+ view: CarriedPart[],
+ recovered: CarriedPart[],
+ matches: (number | undefined)[],
+): CarriedPart[] {
+ const before = new Map<number, CarriedPart[]>();
+ const after = new Map<number, CarriedPart[]>();
+ let previous: number | undefined;
+ const following = followingCarriedMatches(matches);
+ view.forEach((entry, i) => {
+ const match = matches[i];
+ if (match !== undefined) {
+ previous = match;
+ return;
+ }
+ const buckets = previous === undefined ? before : after;
+ const anchor = previous ?? following[i] ?? 0;
+ const bucket = buckets.get(anchor) ?? [];
+ bucket.push(entry);
+ buckets.set(anchor, bucket);
+ });
+ if (recovered.length === 0) return view;
+ return recovered.flatMap((entry, i) => [
+ ...(before.get(i) ?? []),
+ entry,
+ ...(after.get(i) ?? []),
+ ]);
}
-/** Which body a recovery publish should show. A recovery replays the run's events from the
- * last saved cursor, one publish per event, each paying a storage write. When the replayed
- * run is also the one this tab is streaming, that walk is far behind the live stream and
- * its body is a PREFIX of what the reader sees, so importing it rewinds the reply twice a
- * second. Prefix, not length: a body that genuinely disagrees is the server's and wins,
- * since storage is authoritative. Only a body carrying nothing new is refused. */
export function recoveredContentToImport<TContent>(
viewContent: TContent,
recoveredContent: TContent,
): TContent {
- const view = generationRawContent(viewContent).raw;
- const recovered = generationRawContent(recoveredContent).raw;
- if (recovered.length < view.length && view.startsWith(recovered)) {
+ const view = generationRawContent(viewContent);
+ const recovered = generationRawContent(recoveredContent);
+ if (
+ recovered.raw.length < view.raw.length &&
+ view.raw.startsWith(recovered.raw)
+ ) {
return viewContent;
}
+ if (
+ view.carried.length > 0 &&
+ recovered.raw.startsWith(view.raw) &&
+ Array.isArray(recoveredContent)
+ ) {
+ const matches = carriedPartMatches(view.carried, recovered.carried);
+ if (matches.every((index) => index !== undefined)) {
+ return recoveredContent;
+ }
+ // Only a recovered reply that HAS text disagrees: an empty projection is a prefix of every
+ // reply, and with both text-free an unmatched view card is as likely a call replay has not
+ // reached as a stale one.
+ if (!view.raw && recovered.raw) {
+ return recoveredContent;
+ }
+ const spoken = recoveredContent.filter(
+ (part) =>
+ (part as { type?: string })?.type === "text" ||
+ (part as { type?: string })?.type === "reasoning",
+ );
+ return restoreCarriedParts(
+ spoken,
+ mergeCarriedParts(view.carried, recovered.carried, matches),
+ ) as TContent;
+ }
return recoveredContent;
}
diff --git a/studio/frontend/src/features/chat/utils/document-citation-source.ts b/studio/frontend/src/features/chat/utils/document-citation-source.ts
new file mode 100644
index 00000000000..64dad31a9a3
--- /dev/null
+++ b/studio/frontend/src/features/chat/utils/document-citation-source.ts
@@ -0,0 +1,107 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+export function isSafeNavigableSourceUrl(raw: unknown): string {
+ if (typeof raw !== "string") return "";
+ const value = raw.trim();
+ if (!value || /[\r\n]/.test(value)) return "";
+ try {
+ const parsed = new URL(value);
+ if (parsed.protocol === "http:" || parsed.protocol === "https:") {
+ return value;
+ }
+ } catch {}
+ return "";
+}
+
+export function documentCitationToSource(
+ cit: Record<string, unknown>,
+ fallbackIdx: number,
+): {
+ type: "source";
+ sourceType: "url";
+ id: string;
+ url: string;
+ title: string;
+ metadata?: { description: string };
+} | null {
+ const source = typeof cit.source === "string" && cit.source ? cit.source : "";
+ const docTitle =
+ (typeof cit.document_title === "string" && cit.document_title) ||
+ (typeof cit.title === "string" && cit.title) ||
+ "";
+ const docIndex =
+ typeof cit.document_index === "number" ? cit.document_index : undefined;
+ const url =
+ isSafeNavigableSourceUrl(source) ||
+ `#anthropic-doc-${docIndex ?? fallbackIdx}`;
+ const title = docTitle || source || `Document ${fallbackIdx + 1}`;
+ const cited = typeof cit.cited_text === "string" ? cit.cited_text.trim() : "";
+ const description = cited.length > 240 ? `${cited.slice(0, 240)}...` : cited;
+ // Position in the id, so distinct citations of one document stay separate footnotes.
+ const citationType = typeof cit.type === "string" ? String(cit.type) : "";
+ const positionParts = [
+ cit.search_result_index,
+ cit.start_char_index,
+ cit.end_char_index,
+ cit.start_page_number,
+ cit.end_page_number,
+ cit.start_block_index,
+ cit.end_block_index,
+ ]
+ .filter((v) => typeof v === "number")
+ .map((v) => String(v))
+ .join(":");
+ const idAnchor = positionParts
+ ? `${citationType}:${positionParts}`
+ : `${citationType}:${fallbackIdx}`;
+ const id = `${url}#${idAnchor}`;
+ return {
+ type: "source" as const,
+ sourceType: "url" as const,
+ id,
+ url,
+ title,
+ ...(description ? { metadata: { description } } : {}),
+ };
+}
+
+export function parseSourcesFromResult(raw: string): {
+ type: "source";
+ sourceType: "url";
+ id: string;
+ url: string;
+ title: string;
+ metadata?: { description: string };
+}[] {
+ if (!raw) return [];
+ const blocks = raw.split(/\n---\n/).filter(Boolean);
+ const sources: {
+ type: "source";
+ sourceType: "url";
+ id: string;
+ url: string;
+ title: string;
+ metadata?: { description: string };
+ }[] = [];
+ for (const block of blocks) {
+ const titleMatch = block.match(/Title:\s*(.+)/);
+ const urlMatch = block.match(/URL:\s*(.+)/);
+ const snippetMatch = block.match(/Snippet:\s*(.+)/);
+ if (titleMatch && urlMatch) {
+ // Attacker-controllable: a non-http(s) URL must not reach the Sources panel <a href>.
+ const url = isSafeNavigableSourceUrl(urlMatch[1]);
+ if (!url) continue;
+ const snippet = snippetMatch?.[1]?.trim();
+ sources.push({
+ type: "source" as const,
+ sourceType: "url" as const,
+ id: url,
+ url,
+ title: titleMatch[1].trim(),
+ ...(snippet ? { metadata: { description: snippet } } : {}),
+ });
+ }
+ }
+ return sources;
+}
diff --git a/studio/frontend/src/features/chat/utils/generation-tool-recovery.ts b/studio/frontend/src/features/chat/utils/generation-tool-recovery.ts
new file mode 100644
index 00000000000..09a19a82fcf
--- /dev/null
+++ b/studio/frontend/src/features/chat/utils/generation-tool-recovery.ts
@@ -0,0 +1,435 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import {
+ SANDBOX_FILE_TOOLS,
+ extractCreatedFiles,
+} from "@/components/assistant-ui/sandbox-files";
+import {
+ SEARCH_IMAGE_TOOL,
+ extractSearchImages,
+ searchResultText,
+} from "../search-images/search-images";
+import {
+ mergedToolCallArgumentsText,
+ toolCallArgumentsText,
+} from "../tool-call-arguments";
+import type { CarriedPart } from "./chat-generation-recovery";
+import {
+ newDeepResearchHandoff,
+ readDeepResearchToolEvent,
+} from "./deep-research-handoff";
+import {
+ documentCitationToSource,
+ parseSourcesFromResult,
+} from "./document-citation-source";
+import { mergeGoogleNativeParts } from "./google-native-parts";
+
+function record(value: unknown): Record<string, unknown> | undefined {
+ return value !== null && typeof value === "object" && !Array.isArray(value)
+ ? (value as Record<string, unknown>)
+ : undefined;
+}
+
+function recoveredToolResult(
+ event: Record<string, unknown>,
+ toolName: unknown,
+ sessionId: string,
+): unknown {
+ if (toolName === "image_generation" && typeof event.image_b64 === "string") {
+ return {
+ image_b64: event.image_b64,
+ image_mime: event.image_mime ?? "image/png",
+ size: event.size,
+ quality: event.quality,
+ background: event.background,
+ prompt: event.prompt,
+ };
+ }
+ if (typeof event.result !== "string") {
+ return event.result ?? "";
+ }
+ const sandbox =
+ typeof toolName === "string" && SANDBOX_FILE_TOOLS.has(toolName);
+ const { text, files } = sandbox
+ ? extractCreatedFiles(event.result)
+ : { text: event.result, files: [] };
+ const mcpMarker = "\n__MCP_IMAGES__:";
+ const mcpAt = text.lastIndexOf(mcpMarker);
+ if (mcpAt !== -1) {
+ try {
+ const images: unknown = JSON.parse(text.slice(mcpAt + mcpMarker.length));
+ if (
+ Array.isArray(images) &&
+ images.length > 0 &&
+ images.every(
+ (image) =>
+ typeof record(image)?.data === "string" &&
+ typeof record(image)?.mimeType === "string",
+ )
+ ) {
+ return { text: text.slice(0, mcpAt), images };
+ }
+ } catch {
+ // Keep malformed envelopes as text.
+ }
+ }
+ const imageMarker = "\n__IMAGES__:";
+ const imageAt = text.lastIndexOf(imageMarker);
+ if (imageAt !== -1) {
+ try {
+ const images: unknown = JSON.parse(
+ text.slice(imageAt + imageMarker.length),
+ );
+ if (
+ Array.isArray(images) &&
+ images.every((image) => typeof image === "string")
+ ) {
+ return { text: text.slice(0, imageAt), images, sessionId, files };
+ }
+ } catch {
+ // Keep malformed envelopes as text.
+ }
+ }
+ if (sandbox) {
+ return { text, images: [], sessionId, files };
+ }
+ if (toolName === SEARCH_IMAGE_TOOL) {
+ const search = extractSearchImages(text);
+ if (search.images.length > 0) {
+ return { text: search.text, webImages: search.images };
+ }
+ }
+ return text;
+}
+
+export function createGenerationToolRecovery(
+ carried: CarriedPart[],
+ runId: string,
+ snapshotSeq = 0,
+) {
+ const pending = new Map<string, CarriedPart>();
+ const researchHandoff = newDeepResearchHandoff();
+ /** The sources a finished search card yields, parsed once per card rather than per publish.
+ * Every rebuild used to re-run the parse over every finished search result in the turn,
+ * which measured as the bulk of a recovery's per-publish cost on a long tool-using reply.
+ * `apply` replaces a card object wholesale rather than editing one, so an entry that is
+ * still the same object still holds the same result; the result is compared as well, so
+ * an in-place edit somewhere else could not make this serve a stale list either. */
+ const parsedSources = new WeakMap<
+ object,
+ { result: unknown; sources: ReturnType<typeof parseSourcesFromResult> }
+ >();
+ const searchCard = (part: unknown) => {
+ const card = record(part);
+ return card?.type === "tool-call" &&
+ card.result !== undefined &&
+ (card.toolName === "web_search" || card.toolName === "web_fetch")
+ ? card
+ : undefined;
+ };
+ const cardSources = (card: Record<string, unknown>) => {
+ const hit = parsedSources.get(card);
+ if (hit && hit.result === card.result) return hit.sources;
+ const sources = parseSourcesFromResult(searchResultText(card.result));
+ parsedSources.set(card, { result: card.result, sources });
+ return sources;
+ };
+ // A source a previous recovery appended is carried at the offset it was appended AT, so text
+ // replayed after it lands behind it and cuts the reply in two, breaking any markdown that
+ // spans the cut. `withSources` rebuilds these from the card, so drop them and let every
+ // rebuild re-append them, which is also where the live adapter puts them. A citation source
+ // is anchored where it arrived and has no card to rebuild it, so it stays.
+ const rebuildableSourceIds = new Set(
+ carried.flatMap(({ part }) => {
+ const card = searchCard(part);
+ return card ? cardSources(card).map((source) => source.id) : [];
+ }),
+ );
+ for (let i = carried.length - 1; i >= 0; i--) {
+ const part = record(carried[i].part);
+ if (
+ part?.type === "source" &&
+ typeof part.id === "string" &&
+ rebuildableSourceIds.has(part.id)
+ ) {
+ carried.splice(i, 1);
+ }
+ }
+ const sourceIds = new Set(
+ carried.flatMap(({ part }) => {
+ const source = record(part);
+ return source?.type === "source" && typeof source.id === "string"
+ ? [source.id]
+ : [];
+ }),
+ );
+ const savedPending = carried.filter((entry) => {
+ const part = record(entry.part);
+ return part?.type === "tool-call" && part.result === undefined;
+ });
+ // Id-less cards share the empty id: one slot each, else all but the last stay running forever.
+ let savedIdless = 0;
+ for (const entry of savedPending) {
+ const id = record(entry.part)?.backendToolCallId;
+ if (typeof id === "string") {
+ pending.set(id || `#idless:saved:${savedIdless++}`, entry);
+ }
+ }
+ const replayFrom = savedPending.some(
+ (entry) => typeof record(entry.part)?.backendToolCallId !== "string",
+ )
+ ? 0
+ : snapshotSeq;
+ const legacyPending = savedPending.filter(
+ (entry) => typeof record(entry.part)?.backendToolCallId !== "string",
+ );
+ const claimLegacy = (entry: CarriedPart | undefined) => {
+ const at = entry ? legacyPending.indexOf(entry) : -1;
+ if (at !== -1) legacyPending.splice(at, 1);
+ return entry;
+ };
+ // Seeded from saves: a reload between two completions of one card leaves it in no other lookup.
+ const completed = new Map<string, CarriedPart>();
+ /** Most recent finished card a provider gave no id, for a repeated id-less ending. */
+ let lastIdless: CarriedPart | undefined;
+ for (const entry of carried) {
+ const part = record(entry.part);
+ const id = part?.backendToolCallId;
+ if (part?.type !== "tool-call" || part.result === undefined) continue;
+ if (typeof id === "string" && id) completed.set(id, entry);
+ else if (id === "") lastIdless = entry;
+ }
+ /** A card the previous frontend saved carries its backend id inside toolCallId and nowhere
+ * else, so a later completion has to recognise it the way the pending lookup already does. */
+ const findCompletedLegacy = (backendId: string) => {
+ if (!backendId) return undefined;
+ for (let i = carried.length - 1; i >= 0; i--) {
+ const part = record(carried[i].part);
+ const id = part?.toolCallId;
+ if (
+ part?.type !== "tool-call" ||
+ part.result === undefined ||
+ part.backendToolCallId !== undefined ||
+ typeof id !== "string"
+ ) {
+ continue;
+ }
+ if (id === backendId || id.startsWith(`${backendId}:`)) return carried[i];
+ }
+ return undefined;
+ };
+ const findSavedEntry = (backendId: string, approvalId: unknown) => {
+ const matches = savedPending.filter((entry) => {
+ const part = record(entry.part);
+ const id = part?.toolCallId;
+ if (!part || typeof id !== "string" || part.result !== undefined)
+ return false;
+ if (typeof approvalId === "string" && approvalId) {
+ return (
+ part.toolApprovalId === approvalId ||
+ id === approvalId ||
+ id.endsWith(`:${approvalId}`)
+ );
+ }
+ return (
+ Boolean(backendId) &&
+ (id === backendId || id.startsWith(`${backendId}:`))
+ );
+ });
+ return matches.length === 1 ? matches[0] : undefined;
+ };
+ let appliedSeq = 0;
+ const apply = (
+ payload: unknown,
+ at: number,
+ seq: number,
+ sessionId = "_default",
+ ) => {
+ const chunk = record(payload);
+ const event = record(chunk?._toolEvent) ?? chunk;
+ if (
+ event?.type !== "tool_start" &&
+ event?.type !== "tool_end" &&
+ event?.type !== "document_citations"
+ ) {
+ return;
+ }
+ if (seq <= appliedSeq) return;
+ appliedSeq = seq;
+ const backendId =
+ typeof event.tool_call_id === "string" ? event.tool_call_id : "";
+ if (event.tool_name === "deep_research") {
+ if (event.type === "tool_start")
+ researchHandoff.hiddenCallIds.delete(backendId);
+ if (readDeepResearchToolEvent(researchHandoff, event)) return;
+ }
+ // Older approval cards need their original start event to recover the backend id.
+ if (seq <= snapshotSeq) {
+ const entry =
+ event.type === "tool_start"
+ ? claimLegacy(
+ findSavedEntry(backendId, event.approval_id) ??
+ (backendId ? undefined : legacyPending[0]),
+ )
+ : undefined;
+ if (entry) {
+ entry.part = {
+ ...record(entry.part),
+ backendToolCallId: backendId,
+ generationToolCallId: `${runId}:${seq}`,
+ };
+ pending.set(backendId || `#idless:legacy:${seq}`, entry);
+ }
+ return;
+ }
+ if (event.type === "document_citations") {
+ if (Array.isArray(event.citations)) {
+ event.citations.forEach((value, index) => {
+ const citation = record(value);
+ const part = citation
+ ? documentCitationToSource(citation, index)
+ : null;
+ if (!part || sourceIds.has(part.id)) return;
+ carried.push({ at, part });
+ sourceIds.add(part.id);
+ });
+ }
+ return;
+ }
+ const toolName = typeof event.tool_name === "string" ? event.tool_name : "";
+ let entry =
+ (backendId ? pending.get(backendId) : undefined) ??
+ findSavedEntry(backendId, event.approval_id);
+ // Id-less end closes the most recent start, as the adapter does; else two calls recover as one.
+ if (
+ event.type === "tool_end" &&
+ !(entry || backendId) &&
+ pending.size > 0
+ ) {
+ for (const active of pending.values()) entry = active;
+ }
+ // OpenAI Responses ends a web search twice (placeholder, then citations); a start clears this.
+ if (!entry && event.type === "tool_end") {
+ entry = backendId
+ ? (completed.get(backendId) ?? findCompletedLegacy(backendId))
+ : lastIdless;
+ }
+ // Gemini can emit a second completion carrying a generated image.
+ if (
+ !entry &&
+ event.type === "tool_end" &&
+ record(record(event.google)?.native_part)
+ ) {
+ for (let i = carried.length - 1; i >= 0; i--) {
+ const candidate = record(carried[i].part);
+ if (
+ candidate?.type !== "tool-call" ||
+ !record(record(record(candidate.args)?.google)?.native_part)
+ )
+ continue;
+ const id = candidate.toolCallId;
+ if (
+ backendId &&
+ (candidate.backendToolCallId === backendId ||
+ (candidate.backendToolCallId === undefined &&
+ typeof id === "string" &&
+ (id === backendId || id.startsWith(`${backendId}:`))))
+ ) {
+ entry = carried[i];
+ break;
+ }
+ }
+ }
+ if (event.type === "tool_start") {
+ if (!toolName) {
+ return;
+ }
+ if (!entry) {
+ entry = {
+ at,
+ part: {
+ type: "tool-call",
+ toolCallId: `${backendId || "tool"}:${runId}:${seq}`,
+ },
+ };
+ carried.push(entry);
+ }
+ const args = record(event.arguments) ?? {};
+ entry.part = {
+ ...record(entry.part),
+ backendToolCallId: backendId,
+ generationToolCallId: `${runId}:${seq}`,
+ ...(typeof event.approval_id === "string" && event.approval_id
+ ? { toolApprovalId: event.approval_id }
+ : {}),
+ toolName,
+ args,
+ argsText: toolCallArgumentsText(event.arguments_text, args),
+ ...(record(event.provenance) ? { provenance: event.provenance } : {}),
+ };
+ pending.set(backendId || `#idless:${runId}:${seq}`, entry);
+ if (backendId) completed.delete(backendId);
+ else lastIdless = undefined;
+ return;
+ }
+ if (!entry) {
+ return;
+ }
+ const part = record(entry.part);
+ if (!part) {
+ return;
+ }
+ const nextArgs = record(event.arguments);
+ const args = mergeGoogleNativeParts(
+ { ...record(part.args), ...nextArgs },
+ event.google,
+ );
+ entry.part = {
+ ...part,
+ args,
+ argsText: mergedToolCallArgumentsText(
+ part.argsText,
+ args,
+ Object.keys(nextArgs ?? {}),
+ ),
+ result: recoveredToolResult(event, part.toolName, sessionId),
+ ...(record(event.provenance)
+ ? {
+ provenance: {
+ ...record(part.provenance),
+ ...record(event.provenance),
+ },
+ }
+ : {}),
+ };
+ for (const [id, active] of pending) {
+ if (active === entry) {
+ pending.delete(id);
+ }
+ }
+ if (backendId) completed.set(backendId, entry);
+ else lastIdless = entry;
+ };
+ // Recovery never reaches the live path's end-of-stream source yield, so rebuild those entries.
+ // Per occurrence, not per url, because the live path flat-maps the cards: two rounds finding
+ // the same page carry their own title and snippet, and the Sources panel lists both.
+ const withSources = <TPart>(parts: TPart[]): TPart[] => {
+ const out: TPart[] = [...parts];
+ for (const { part } of carried) {
+ const card = searchCard(part);
+ if (!card) continue;
+ for (const source of cardSources(card)) {
+ // Copied rather than handed out from the cache, `metadata` included: before the
+ // cache each rebuild yielded its own objects all the way down, and a caller that
+ // edits a part it was given must not reach back into what the next rebuild yields.
+ out.push({
+ ...source,
+ ...(source.metadata ? { metadata: { ...source.metadata } } : {}),
+ } as TPart);
+ }
+ }
+ return out;
+ };
+ return { replayFrom, apply, withSources };
+}
diff --git a/studio/frontend/src/features/chat/utils/google-native-parts.ts b/studio/frontend/src/features/chat/utils/google-native-parts.ts
new file mode 100644
index 00000000000..f0bc7c7f363
--- /dev/null
+++ b/studio/frontend/src/features/chat/utils/google-native-parts.ts
@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+function record(value: unknown): Record<string, unknown> | undefined {
+ return value !== null && typeof value === "object" && !Array.isArray(value)
+ ? (value as Record<string, unknown>)
+ : undefined;
+}
+
+function collectParts(value: unknown): Record<string, unknown>[] {
+ const native = record(value);
+ if (!native) return [];
+ if (Array.isArray(native.parts)) {
+ return native.parts.filter(
+ (part): part is Record<string, unknown> => record(part) !== undefined,
+ );
+ }
+ const signature =
+ typeof native.thoughtSignature === "string"
+ ? native.thoughtSignature
+ : native.thought_signature;
+ return ["executableCode", "codeExecutionResult", "inlineData"].flatMap(
+ (key) => {
+ const part = record(native[key]);
+ if (!part) return [];
+ return [
+ {
+ [key]: part,
+ ...(key === "executableCode" &&
+ typeof signature === "string" &&
+ signature
+ ? { thoughtSignature: signature }
+ : {}),
+ },
+ ];
+ },
+ );
+}
+
+export function mergeGoogleNativeParts(
+ args: Record<string, unknown>,
+ endGoogle: unknown,
+): Record<string, unknown> {
+ const endNative = record(record(endGoogle)?.native_part);
+ if (!endNative) return args;
+ const google = record(args.google) ?? {};
+ return {
+ ...args,
+ google: {
+ ...google,
+ native_part: {
+ parts: [
+ ...collectParts(google.native_part),
+ ...collectParts(endNative),
+ ],
+ },
+ },
+ };
+}
diff --git a/studio/frontend/tests/generation-recovery-invariants.test.ts b/studio/frontend/tests/generation-recovery-invariants.test.ts
new file mode 100644
index 00000000000..2a9f886c4d1
--- /dev/null
+++ b/studio/frontend/tests/generation-recovery-invariants.test.ts
@@ -0,0 +1,310 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import type { CarriedPart } from "../src/features/chat/utils/chat-generation-recovery.ts";
+import { registerBundlerResolver } from "./helpers/kit.ts";
+
+registerBundlerResolver();
+
+const {
+ generationRawContent,
+ restoreCarriedParts,
+ restoreCarriedPartsFromRaw,
+ recoveredContentToImport,
+} = await import("../src/features/chat/utils/chat-generation-recovery.ts");
+const { createGenerationToolRecovery } = await import(
+ "../src/features/chat/utils/generation-tool-recovery.ts"
+);
+
+type Part = Record<string, unknown>;
+
+/** xorshift, so a failing seed replays exactly. */
+function rng(seed: number) {
+ let state = seed >>> 0 || 1;
+ return () => {
+ state ^= state << 13;
+ state ^= state >>> 17;
+ state ^= state << 5;
+ state >>>= 0;
+ return state / 0x100000000;
+ };
+}
+
+// Astral pairs, since offsets are UTF-16 code units. No angle brackets: a think tag is a parser question.
+const ALPHABET = [
+ "a",
+ "b",
+ " ",
+ "\n",
+ "\t",
+ "é",
+ "👍🏽",
+ "😀",
+ "中",
+ "​",
+ "'",
+ '"',
+ "\\",
+ "&",
+ "0",
+];
+
+function randomText(next: () => number): string {
+ const length = Math.floor(next() * 12);
+ let out = "";
+ for (let i = 0; i < length; i++) {
+ out += ALPHABET[Math.floor(next() * ALPHABET.length)];
+ }
+ return out;
+}
+
+const CARRIED_KINDS = ["tool-call", "source", "file", "image"] as const;
+
+function randomContent(next: () => number, seed: number): Part[] {
+ const length = Math.floor(next() * 12);
+ const parts: Part[] = [];
+ for (let i = 0; i < length; i++) {
+ const roll = next();
+ if (roll < 0.38) {
+ parts.push({ type: "text", text: randomText(next) });
+ } else if (roll < 0.68) {
+ parts.push({ type: "reasoning", text: randomText(next) });
+ } else {
+ const kind = CARRIED_KINDS[Math.floor(next() * CARRIED_KINDS.length)];
+ parts.push(
+ kind === "tool-call"
+ ? {
+ type: "tool-call",
+ toolCallId: `c${seed}_${i}`,
+ toolName: "edit_file",
+ args: {},
+ argsText: "{}",
+ ...(next() < 0.5 ? { result: "ok" } : {}),
+ }
+ : { type: kind, id: `p${seed}_${i}`, url: "https://example.com" },
+ );
+ }
+ }
+ return parts;
+}
+
+const isSpoken = (part: Part) =>
+ part.type === "text" || part.type === "reasoning";
+const spokenText = (parts: Part[], type: string) =>
+ parts
+ .filter((part) => part.type === type)
+ .map((part) => String(part.text ?? ""))
+ .join("");
+const identify = (part: Part) => String(part.toolCallId ?? part.id ?? "?");
+const carriedIds = (parts: Part[]) =>
+ parts.filter((part) => !isSpoken(part)).map(identify);
+
+function prefixLengths(parts: Part[]): [string, number][] {
+ const out: [string, number][] = [];
+ let seen = 0;
+ for (const part of parts) {
+ if (isSpoken(part)) seen += String(part.text ?? "").length;
+ else out.push([identify(part), seen]);
+ }
+ return out.sort();
+}
+
+const roundTrip = (content: Part[]) => {
+ const { raw, reasoningOpen, carried } = generationRawContent(content);
+ return restoreCarriedPartsFromRaw(
+ reasoningOpen ? `${raw}</think>` : raw,
+ carried,
+ ) as unknown as Part[];
+};
+
+test("a raw round trip keeps every card, its order, its position and the words", () => {
+ for (let seed = 1; seed <= 4000; seed++) {
+ const content = randomContent(rng(seed * 2654435761), seed);
+ const where = () => `seed ${seed}: ${JSON.stringify(content)}`;
+ const out = roundTrip(content);
+
+ assert.deepEqual(carriedIds(out), carriedIds(content), where());
+ assert.equal(
+ spokenText(out, "text"),
+ spokenText(content, "text"),
+ `text ${where()}`,
+ );
+ assert.equal(
+ spokenText(out, "reasoning"),
+ spokenText(content, "reasoning"),
+ `reasoning ${where()}`,
+ );
+ assert.deepEqual(prefixLengths(out), prefixLengths(content), where());
+
+ const shape = (parts: Part[]) =>
+ parts.map((part) => [part.type, identify(part), part.text]);
+ assert.deepEqual(shape(roundTrip(out)), shape(out), `twice ${where()}`);
+ }
+});
+
+test("restoring onto parsed parts keeps the same properties", () => {
+ for (let seed = 1; seed <= 3000; seed++) {
+ const content = randomContent(rng(seed * 40503), seed);
+ const where = () => `seed ${seed}: ${JSON.stringify(content)}`;
+ const { carried } = generationRawContent(content);
+ const out = restoreCarriedParts(
+ content.filter(isSpoken),
+ carried,
+ ) as Part[];
+
+ assert.deepEqual(carriedIds(out), carriedIds(content), where());
+ assert.equal(
+ spokenText(out, "text"),
+ spokenText(content, "text"),
+ `text ${where()}`,
+ );
+ assert.equal(
+ spokenText(out, "reasoning"),
+ spokenText(content, "reasoning"),
+ `reasoning ${where()}`,
+ );
+ assert.deepEqual(prefixLengths(out), prefixLengths(content), where());
+ }
+});
+
+type Event = Record<string, unknown>;
+
+/** `cards` counts what the adapter would draw: a start on an already-open id reuses its card. */
+function randomEvents(next: () => number): { events: Event[]; cards: number } {
+ const rounds = 1 + Math.floor(next() * 5);
+ const events: Event[] = [];
+ const open: string[] = [];
+ let cards = 0;
+ for (let i = 0; i < rounds; i++) {
+ const roll = next();
+ const id = roll < 0.25 ? "" : roll < 0.5 ? "call_0" : `call_${i}`;
+ events.push({
+ type: "tool_start",
+ tool_call_id: id,
+ tool_name: "edit_file",
+ arguments: { path: `f${i}.ts` },
+ });
+ const reused = Boolean(id) && open.includes(id);
+ if (!reused) cards += 1;
+ if (id && !reused) open.push(id);
+ if (next() < 0.75) {
+ events.push({ type: "tool_end", tool_call_id: id, result: `r${i}` });
+ const at = open.indexOf(id);
+ if (at !== -1) open.splice(at, 1);
+ }
+ }
+ return { events, cards };
+}
+
+test("replay opens one card per call and lands each result once", () => {
+ for (let seed = 1; seed <= 4000; seed++) {
+ const { events, cards } = randomEvents(rng(seed * 2246822519));
+ const where = () => `seed ${seed}: ${JSON.stringify(events)}`;
+
+ const carried: CarriedPart[] = [];
+ const replay = createGenerationToolRecovery(carried, "run", 0).apply;
+ events.forEach((event, i) => replay(event, i, i + 1));
+ assert.equal(carried.length, cards, where());
+
+ const results = carried
+ .map(({ part }) => (part as Part).result)
+ .filter((value) => value !== undefined);
+ assert.equal(new Set(results).size, results.length, `twice ${where()}`);
+
+ // The follow stream can deliver an update more than once.
+ const doubled: CarriedPart[] = [];
+ const again = createGenerationToolRecovery(doubled, "run", 0).apply;
+ events.forEach((event, i) => {
+ again(event, i, i + 1);
+ again(event, i, i + 1);
+ });
+ assert.deepEqual(
+ doubled.map(({ part }) => part),
+ carried.map(({ part }) => part),
+ `repeated ${where()}`,
+ );
+
+ const seeded: CarriedPart[] = [
+ { at: 0, part: { type: "source", id: "kept", url: "https://e.com" } },
+ ];
+ const third = createGenerationToolRecovery(seeded, "run", 0).apply;
+ events.forEach((event, i) => third(event, i, i + 1));
+ assert.ok(
+ seeded.some(({ part }) => (part as Part).id === "kept"),
+ `kept ${where()}`,
+ );
+ }
+});
+
+test("an import that is not the view keeps the recovered body whole", () => {
+ for (let seed = 1; seed <= 3000; seed++) {
+ const next = rng(seed * 22695477);
+ const view = randomContent(next, seed);
+ const recovered =
+ next() < 0.5
+ ? randomContent(next, seed + 100000)
+ : [...view, { type: "text", text: randomText(next) }];
+ const out = recoveredContentToImport(view, recovered) as Part[];
+ if (out === view) continue;
+ const where = () => `seed ${seed}`;
+ for (const id of carriedIds(recovered)) {
+ assert.ok(carriedIds(out).includes(id), `dropped ${id} ${where()}`);
+ }
+ assert.equal(
+ spokenText(out, "text"),
+ spokenText(recovered, "text"),
+ `text ${where()}`,
+ );
+ }
+});
+
+// A think tag can arrive split across two chunks, so a card offset -- the raw length at a
+// chunk boundary -- can land inside one. The generator above keeps angle brackets out, so
+// these two are spelled out.
+test("a card offset inside a split think tag lands past the tag, not in it", () => {
+ const raw = "<think>\n\nreasoned";
+ const card: Part = {
+ type: "tool-call",
+ toolCallId: "c1",
+ toolName: "edit_file",
+ args: {},
+ };
+ const out = restoreCarriedPartsFromRaw(raw, [
+ { at: "<thi".length, part: card },
+ ]) as unknown as Part[];
+
+ assert.deepEqual(
+ out.map((part) => part.type),
+ ["tool-call", "reasoning"],
+ );
+ assert.equal(out[1].text, "\n\nreasoned");
+ assert.equal(generationRawContent(out).raw, raw);
+});
+
+test("cards on both sides of a split think tag do not duplicate it", () => {
+ const raw = "<think>\n\nreasoned";
+ const carried: CarriedPart[] = [
+ { at: "<thi".length, part: { type: "source", id: "s1" } },
+ {
+ at: "<think>".length,
+ part: {
+ type: "tool-call",
+ toolCallId: "c1",
+ toolName: "edit_file",
+ args: {},
+ },
+ },
+ ];
+ const out = restoreCarriedPartsFromRaw(raw, carried) as unknown as Part[];
+
+ assert.deepEqual(
+ out.map((part) => part.type),
+ ["source", "tool-call", "reasoning"],
+ );
+ // The tag survives exactly once: projecting the reply back has to give the raw it came from,
+ // or the next publish compares the reply against a body it never streamed.
+ assert.equal(generationRawContent(out).raw, raw);
+});
diff --git a/studio/frontend/tests/generation-recovery-keeps-tool-cards.test.ts b/studio/frontend/tests/generation-recovery-keeps-tool-cards.test.ts
new file mode 100644
index 00000000000..1ae014cb141
--- /dev/null
+++ b/studio/frontend/tests/generation-recovery-keeps-tool-cards.test.ts
@@ -0,0 +1,298 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { registerBundlerResolver } from "./helpers/kit.ts";
+
+registerBundlerResolver();
+
+const { generationRawContent, recoveredContentToImport, restoreCarriedParts } =
+ await import("../src/features/chat/utils/chat-generation-recovery.ts");
+const { parseAssistantContent } = await import(
+ "../src/features/chat/utils/parse-assistant-content.ts"
+);
+
+type Part = {
+ type: string;
+ text?: string;
+ toolName?: string;
+ toolCallId?: string;
+};
+
+function recoverBody(content: Part[]): Part[] {
+ const { raw, reasoningOpen, carried } = generationRawContent(content);
+ return restoreCarriedParts(
+ parseAssistantContent(reasoningOpen ? `${raw}</think>` : raw) as Part[],
+ carried,
+ );
+}
+
+const TURN: Part[] = [
+ { type: "reasoning", text: "planning the GLSL repair" },
+ {
+ type: "text",
+ text: "That patch mangled the GLSL line, repairing properly:",
+ },
+ { type: "tool-call", toolCallId: "call_0", toolName: "edit_file" },
+ { type: "reasoning", text: "checking the result" },
+ { type: "text", text: "Run 7, the Drowned Nave:" },
+ { type: "tool-call", toolCallId: "call_1", toolName: "render_html" },
+];
+
+test("a recovered turn keeps the tool calls it was streamed with", () => {
+ const recovered = recoverBody(TURN);
+
+ assert.deepEqual(
+ recovered.map((part) => part.type),
+ TURN.map((part) => part.type),
+ );
+ assert.deepEqual(
+ recovered
+ .filter((part) => part.type === "tool-call")
+ .map((p) => p.toolCallId),
+ ["call_0", "call_1"],
+ );
+});
+
+test("the text a recovery rebuilds is unchanged by carrying the parts", () => {
+ // The projection is what the follower compares and stores against, so it must not move.
+ assert.equal(
+ generationRawContent(recoverBody(TURN)).raw,
+ generationRawContent(TURN).raw,
+ );
+});
+
+test("a call between two runs of text splits the text it sits in", () => {
+ // The rebuild coalesces "A" and "B" into one part, so the call has to land by offset.
+ const body: Part[] = [
+ { type: "text", text: "A" },
+ { type: "tool-call", toolCallId: "call_0", toolName: "python" },
+ { type: "text", text: "B" },
+ ];
+ assert.deepEqual(recoverBody(body), body);
+});
+
+test("a turn with no tool calls rebuilds exactly as before", () => {
+ const body: Part[] = [
+ { type: "reasoning", text: "thinking" },
+ { type: "text", text: "answer" },
+ ];
+ assert.deepEqual(recoverBody(body), body);
+});
+
+test("an unfinished reply keeps its calls and its open reasoning", () => {
+ const body: Part[] = [
+ { type: "text", text: "one moment:" },
+ { type: "tool-call", toolCallId: "call_0", toolName: "web_search" },
+ { type: "reasoning", text: "still going" },
+ ];
+ const recovered = recoverBody(body);
+ assert.deepEqual(
+ recovered.map((part) => part.type),
+ ["text", "tool-call", "reasoning"],
+ );
+});
+
+test("a publish cannot swap a body that has cards for one that lost them", () => {
+ // The prefix guard compares projections, which hide tool calls: a stripped body used to win.
+ const stripped = TURN.filter((part) => part.type !== "tool-call");
+ const kept = recoveredContentToImport(TURN, stripped) as Part[];
+
+ assert.deepEqual(
+ kept.filter((part) => part.type === "tool-call").map((p) => p.toolCallId),
+ ["call_0", "call_1"],
+ );
+ assert.equal(
+ generationRawContent(kept).raw,
+ generationRawContent(stripped).raw,
+ );
+});
+
+test("a publish that is genuinely behind is still refused", () => {
+ const behind: Part[] = [{ type: "text", text: "That patch" }];
+ const full: Part[] = [{ type: "text", text: "That patch mangled the line" }];
+ assert.deepEqual(recoveredContentToImport(full, behind), full);
+});
+
+test("a publish carrying new text still wins", () => {
+ const view: Part[] = [{ type: "text", text: "That patch" }];
+ const ahead: Part[] = [{ type: "text", text: "That patch mangled the line" }];
+ assert.deepEqual(recoveredContentToImport(view, ahead), ahead);
+});
+
+test("calls split reasoning into the original groups", () => {
+ const body: Part[] = [
+ { type: "reasoning", text: "before" },
+ { type: "tool-call", toolCallId: "one", toolName: "edit_file" },
+ { type: "reasoning", text: "between" },
+ { type: "tool-call", toolCallId: "two", toolName: "web_search" },
+ { type: "reasoning", text: "after" },
+ { type: "text", text: "done" },
+ ];
+ assert.deepEqual(recoverBody(body), body);
+ assert.deepEqual(recoverBody(recoverBody(body)), body);
+});
+
+test("cards at shared offsets retain their order", () => {
+ const body: Part[] = [
+ { type: "text", text: "A\u{1D11E}" },
+ { type: "tool-call", toolCallId: "one" },
+ { type: "tool-call", toolCallId: "two" },
+ { type: "text", text: "B" },
+ ];
+ assert.deepEqual(recoverBody(body), body);
+ assert.deepEqual(
+ recoveredContentToImport(
+ body,
+ body.filter((p) => p.toolCallId !== "one"),
+ ),
+ body,
+ );
+});
+
+test("a divergent recovered reply does not inherit old cards or attachments", () => {
+ for (const type of ["tool-call", "source", "file", "image"]) {
+ const view: Part[] = [{ type: "text", text: "old response" }, { type }];
+ const recovered: Part[] = [
+ { type: "text", text: "server repaired response" },
+ ];
+ assert.equal(recoveredContentToImport(view, recovered), recovered);
+ }
+});
+
+test("compatible replies retain recovered cards and their authoritative results", () => {
+ const old = { type: "tool-call", toolCallId: "shared", result: "old" };
+ const current = { ...old, result: "new" };
+ const missing = { type: "tool-call", toolCallId: "missing" };
+ const added = { type: "tool-call", toolCallId: "added" };
+ const view = [{ type: "text", text: "A" }, old, missing];
+ const recovered = [
+ { type: "text", text: "A" },
+ current,
+ added,
+ { type: "text", text: "B" },
+ ];
+ const merged = recoveredContentToImport(view, recovered);
+ assert.deepEqual(merged, [
+ { type: "text", text: "A" },
+ current,
+ missing,
+ added,
+ { type: "text", text: "B" },
+ ]);
+});
+
+test("missing cards stay beside shared anchors without reordering recovered cards", () => {
+ const card = (toolCallId: string) => ({ type: "tool-call", toolCallId });
+ for (const [liveIds, recoveredIds, expected] of [
+ [
+ ["b", "c"],
+ ["a", "b"],
+ ["a", "b", "c"],
+ ],
+ [["a", "b"], ["b"], ["a", "b"]],
+ [
+ ["b", "c", "d"],
+ ["a", "b", "e"],
+ ["a", "b", "c", "d", "e"],
+ ],
+ [
+ ["b", "c", "a"],
+ ["a", "b"],
+ ["a", "b", "c"],
+ ],
+ [
+ ["a", "b", "c"],
+ ["c", "a"],
+ ["c", "a", "b"],
+ ],
+ ]) {
+ const view = [{ type: "text", text: "Working:" }, ...liveIds.map(card)];
+ const recovered = [
+ { type: "text", text: "Working:" },
+ ...recoveredIds.map(card),
+ { type: "text", text: "Done" },
+ ];
+ const merged = recoveredContentToImport(view, recovered);
+ assert.equal(generationRawContent(merged).raw, "Working:Done");
+ assert.deepEqual(
+ merged
+ .filter((part) => part.type === "tool-call")
+ .map((part) => (part as Part).toolCallId),
+ expected,
+ );
+ }
+});
+
+test("replay identities match provider cards without merging different rounds", () => {
+ const card = {
+ type: "tool-call",
+ toolName: "edit_file",
+ backendToolCallId: "call_0",
+ generationToolCallId: "run:1",
+ toolCallId: "provider-id",
+ };
+ const recovered = [{ ...card, toolCallId: "call_0:run:1", result: "ok" }];
+ assert.equal(recoveredContentToImport([card], recovered), recovered);
+ const next = {
+ ...card,
+ toolCallId: "next-id",
+ generationToolCallId: "run:3",
+ };
+ assert.equal(recoveredContentToImport([next], recovered).length, 2);
+});
+
+test("legacy calls at different positions remain separate", () => {
+ const card = {
+ type: "tool-call",
+ toolName: "edit_file",
+ toolCallId: "call_0:live",
+ };
+ const recovered = [
+ {
+ ...card,
+ toolCallId: "call_0:run:1",
+ backendToolCallId: "call_0",
+ generationToolCallId: "run:1",
+ },
+ { type: "text", text: "Done" },
+ ];
+ const merged = recoveredContentToImport(
+ [{ type: "text", text: "Done" }, card],
+ recovered,
+ );
+ assert.equal(merged.filter((part) => part.type === "tool-call").length, 2);
+});
+
+test("legacy matching cannot cross a shared card into another round", () => {
+ const card = (toolCallId: string) => ({
+ type: "tool-call",
+ toolName: "edit_file",
+ toolCallId,
+ });
+ const first = card("call_0:live-0");
+ const shared = card("call_0:live-1");
+ const last = {
+ ...card("call_0:run:5"),
+ backendToolCallId: "call_0",
+ generationToolCallId: "run:5",
+ };
+ assert.deepEqual(recoveredContentToImport([first, shared], [shared, last]), [
+ first,
+ shared,
+ last,
+ ]);
+ const replayedFirst = {
+ ...first,
+ toolCallId: "call_0:run:1",
+ backendToolCallId: "call_0",
+ generationToolCallId: "run:1",
+ };
+ const liveLast = card("call_0:live-2");
+ assert.deepEqual(
+ recoveredContentToImport([shared, liveLast], [replayedFirst, shared]),
+ [replayedFirst, shared, liveLast],
+ );
+});
diff --git a/studio/frontend/tests/generation-tool-recovery.test.ts b/studio/frontend/tests/generation-tool-recovery.test.ts
new file mode 100644
index 00000000000..2b08652a849
--- /dev/null
+++ b/studio/frontend/tests/generation-tool-recovery.test.ts
@@ -0,0 +1,1290 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import test from "node:test";
+import vm from "node:vm";
+import ts from "typescript";
+import type { CarriedPart as Carried } from "../src/features/chat/utils/chat-generation-recovery.ts";
+import { registerBundlerResolver } from "./helpers/kit.ts";
+
+registerBundlerResolver();
+
+const recovery = await import(
+ "../src/features/chat/utils/chat-generation-recovery.ts"
+);
+const parser = await import(
+ "../src/features/chat/utils/parse-assistant-content.ts"
+);
+const { createGenerationToolRecovery } = await import(
+ "../src/features/chat/utils/generation-tool-recovery.ts"
+);
+
+const start = (id = "call_0") => ({
+ type: "tool_start",
+ tool_call_id: id,
+ tool_name: "edit_file",
+ arguments: { path: "scene.glsl" },
+});
+const end = (id = "call_0") => ({
+ type: "tool_end",
+ tool_call_id: id,
+ result: "ok",
+});
+
+test("replay adds new cards and applies their results", () => {
+ const carried: Carried[] = [];
+ const replay = createGenerationToolRecovery(carried, "run").apply;
+ replay(start(), 12, 1);
+ const pending = carried[0].part as Record<string, unknown>;
+ assert.equal(pending.result, undefined);
+ replay(end(), 20, 2);
+ assert.equal(carried.length, 1);
+ assert.equal(carried[0].at, 12);
+ assert.deepEqual(carried[0].part, { ...pending, result: "ok" });
+ assert.equal(
+ pending.result,
+ undefined,
+ "published snapshots must not be mutated",
+ );
+});
+
+test("replay resumes an existing card without duplicating it", () => {
+ const saved = {
+ type: "tool-call",
+ toolCallId: "call_0:saved-id",
+ toolName: "edit_file",
+ args: { path: "scene.glsl" },
+ argsText: '{"path":"scene.glsl"}',
+ };
+ const carried = [{ at: 12, part: saved }];
+ createGenerationToolRecovery(carried, "run").apply(end(), 20, 2);
+ assert.deepEqual(carried, [{ at: 12, part: { ...saved, result: "ok" } }]);
+});
+
+test("reused backend ids get separate cards across rounds and reloads", () => {
+ const carried: Carried[] = [];
+ let replay = createGenerationToolRecovery(carried, "run").apply;
+ replay(start(), 0, 1);
+ replay(end(), 0, 2);
+ replay(start(), 10, 3);
+ replay = createGenerationToolRecovery(carried, "run").apply;
+ replay({ ...end(), result: "second" }, 10, 4);
+ assert.equal(carried.length, 2);
+ const parts = carried.map((entry) => entry.part as Record<string, unknown>);
+ assert.notEqual(parts[0].toolCallId, parts[1].toolCallId);
+ assert.deepEqual(
+ parts.map((part) => part.result),
+ ["ok", "second"],
+ );
+});
+
+test("wrapped events preserve exact arguments and completion argument updates", () => {
+ const carried: Carried[] = [];
+ const replay = createGenerationToolRecovery(carried, "run").apply;
+ replay(
+ {
+ _toolEvent: {
+ ...start(),
+ arguments: { id: Number("9007199254740993"), path: "old" },
+ arguments_text: '{"id":9007199254740993,"path":"old"}',
+ },
+ },
+ 0,
+ 1,
+ );
+ replay({ _toolEvent: { ...end(), arguments: { path: "new" } } }, 0, 2);
+ assert.equal(
+ (carried[0].part as Record<string, unknown>).argsText,
+ '{"id":9007199254740993,"path":"new"}',
+ );
+});
+
+test("sandbox results retain files, images and the run's session", () => {
+ const carried: Carried[] = [];
+ const replay = createGenerationToolRecovery(carried, "run").apply;
+ replay({ ...start(), tool_name: "python" }, 0, 1);
+ replay(
+ {
+ ...end(),
+ result:
+ 'done\n__FILES__:[{"name":"plot.png","size":7}]\n__IMAGES__:["plot.png"]',
+ },
+ 0,
+ 2,
+ "saved-session",
+ );
+ assert.deepEqual((carried[0].part as Record<string, unknown>).result, {
+ text: "done",
+ files: [{ name: "plot.png", size: 7 }],
+ images: ["plot.png"],
+ sessionId: "saved-session",
+ });
+});
+
+test("MCP image results remain structured and malformed envelopes remain readable", () => {
+ for (const [result, expected] of [
+ [
+ 'done\n__MCP_IMAGES__:[{"data":"abc","mimeType":"image/png"}]',
+ { text: "done", images: [{ data: "abc", mimeType: "image/png" }] },
+ ],
+ ["done\n__MCP_IMAGES__:invalid", "done\n__MCP_IMAGES__:invalid"],
+ ]) {
+ const carried: Carried[] = [];
+ const replay = createGenerationToolRecovery(carried, "run").apply;
+ replay(start(), 0, 1);
+ replay({ ...end(), result }, 0, 2);
+ assert.deepEqual(
+ (carried[0].part as Record<string, unknown>).result,
+ expected,
+ );
+ }
+});
+
+test("unrelated events and unmatched completions cannot alter saved cards", () => {
+ const carried: Carried[] = [];
+ const replay = createGenerationToolRecovery(carried, "run").apply;
+ replay(end(), 0, 1);
+ replay({ type: "tool_start" }, 0, 2);
+ replay(null, 0, 3);
+ assert.deepEqual(carried, []);
+});
+
+test("explicit backend ids retain colons when a saved card completes", () => {
+ const carried = [
+ {
+ at: 0,
+ part: {
+ type: "tool-call",
+ toolCallId: "session:thread:approval",
+ backendToolCallId: "provider:call_0",
+ toolName: "edit_file",
+ args: {},
+ },
+ },
+ ];
+ const replay = createGenerationToolRecovery(carried, "run", 3);
+ assert.equal(replay.replayFrom, 3);
+ replay.apply(end("provider:call_0"), 0, 4);
+ assert.equal((carried[0].part as Record<string, unknown>).result, "ok");
+});
+
+test("approval history distinguishes pending calls with the same tool name", () => {
+ const carried: Carried[] = ["one", "two"].map((id) => ({
+ at: 0,
+ part: {
+ type: "tool-call",
+ toolCallId: `session:thread:${id}`,
+ toolName: "edit_file",
+ args: {},
+ },
+ }));
+ const replay = createGenerationToolRecovery(carried, "run", 2);
+ assert.equal(replay.replayFrom, 0);
+ replay.apply({ ...start("call_0"), approval_id: "one" }, 0, 1);
+ replay.apply({ ...start("call_1"), approval_id: "two" }, 0, 2);
+ replay.apply({ ...end("call_1"), result: "second" }, 0, 3);
+ replay.apply({ ...end("call_0"), result: "first" }, 0, 4);
+ assert.deepEqual(
+ carried.map(({ part }) => (part as Record<string, unknown>).result),
+ ["first", "second"],
+ );
+});
+
+test("an unmatched completion cannot guess an approval card by tool name", () => {
+ const saved = {
+ type: "tool-call",
+ toolCallId: "session:thread:approval",
+ toolName: "edit_file",
+ };
+ const carried = [{ at: 0, part: saved }];
+ createGenerationToolRecovery(carried, "run").apply(
+ { ...end(), tool_name: "edit_file" },
+ 0,
+ 1,
+ );
+ assert.equal(carried[0].part, saved);
+});
+
+test("the live adapter saves identities for ordinary, approval and provider cards", () => {
+ const adapter = readFileSync(
+ new URL("../src/features/chat/api/chat-adapter.ts", import.meta.url),
+ "utf8",
+ );
+ const startAt = adapter.indexOf('if (toolEvent.type === "tool_start") {');
+ const endAt = adapter.indexOf(
+ '} else if (toolEvent.type === "tool_end") {',
+ startAt,
+ );
+ assert.ok(startAt >= 0 && endAt > startAt);
+ const source = `function receive(toolEvent) { ${adapter.slice(startAt, endAt)} } }`;
+ const compiled = ts.transpileModule(source, {
+ compilerOptions: { target: ts.ScriptTarget.ES2022 },
+ }).outputText;
+ for (const generationRunId of [null, "run"]) {
+ for (const kind of ["ordinary", "approval", "provider"]) {
+ const parts: Record<string, unknown>[] =
+ kind === "provider"
+ ? [
+ {
+ type: "tool-call",
+ toolCallId: "provider-id",
+ toolName: "edit_file",
+ args: {},
+ },
+ ]
+ : [];
+ const confirmed: string[] = [];
+ const context = vm.createContext({
+ toolCallParts: parts,
+ toolPartIdByBackendId: new Map(
+ kind === "provider" ? [["call_0", "provider-id"]] : [],
+ ),
+ toolConfirmationIdsByBackendId: new Map(),
+ toolConfirmationScopeId: "session:thread",
+ sandboxSessionId: "session",
+ generationRunId,
+ generationSeq: 7,
+ cumulativeText: "",
+ toolProvenance: undefined,
+ resolveToolPartId: () =>
+ kind === "provider" ? "provider-id" : "call_0:live-id",
+ scopedToolOutputKey: (id: string) => id,
+ toolCallArgumentsText: (_text: unknown, args: unknown) =>
+ JSON.stringify(args),
+ mergeToolProvenance: () => undefined,
+ useChatRuntimeStore: {
+ getState: () => ({
+ clearToolLiveOutput() {},
+ clearToolFullOutput() {},
+ setToolConfirmation: (id: string) => confirmed.push(id),
+ }),
+ },
+ });
+ vm.runInContext(compiled, context);
+ const event = {
+ ...start(),
+ ...(kind === "approval"
+ ? { awaiting_confirmation: true, approval_id: "approval-1" }
+ : {}),
+ };
+ context.receive(event);
+ assert.equal(parts.length, 1);
+ const saved = parts[0];
+ assert.equal(saved.backendToolCallId, "call_0");
+ assert.equal(
+ saved.generationToolCallId,
+ generationRunId ? "run:7" : undefined,
+ );
+ assert.equal(
+ saved.toolCallId,
+ kind === "approval"
+ ? "session:thread:approval-1"
+ : kind === "provider"
+ ? "provider-id"
+ : "call_0:live-id",
+ );
+ assert.equal(
+ saved.toolApprovalId,
+ kind === "approval" ? "approval-1" : undefined,
+ );
+ assert.deepEqual(
+ confirmed,
+ kind === "approval" ? [saved.toolCallId] : [],
+ );
+ const carried = [{ at: 0, part: saved }];
+ const replay = createGenerationToolRecovery(carried, "run", 7);
+ assert.equal(replay.replayFrom, 7);
+ replay.apply(end(), 0, 8);
+ assert.equal(carried[0].part.result, "ok");
+ }
+ }
+});
+
+const provider = readFileSync(
+ new URL("../src/features/chat/runtime-provider.tsx", import.meta.url),
+ "utf8",
+);
+const scheduler = provider.slice(
+ provider.indexOf("function scheduleGenerationRecovery("),
+ provider.indexOf("\nexport async function ensureThreadRecord("),
+);
+const executable = ts.transpileModule(scheduler, {
+ compilerOptions: {
+ target: ts.ScriptTarget.ES2022,
+ module: ts.ModuleKind.ESNext,
+ },
+}).outputText;
+
+async function recoverRun(
+ content: unknown[],
+ payloads: unknown[],
+ options: { cursor?: number; viewContent?: unknown[] } = {},
+) {
+ let shown = {
+ messages: [
+ { message: { id: "msg", content: options.viewContent ?? content } },
+ ],
+ };
+ const imports: unknown[][] = [];
+ let replayFrom: number | undefined;
+ const snapshots: Array<{
+ content: Record<string, unknown>[];
+ metadata: Record<string, unknown>;
+ }> = [];
+ const generationRecoveries = new Map();
+ const runtime = {
+ models: [],
+ registerThreadServerCancel() {},
+ setThreadRunning() {},
+ clearThreadServerCancel() {},
+ };
+ const run = {
+ id: "run",
+ threadId: "thread",
+ assistantMessageId: "msg",
+ status: "completed",
+ lastEventSeq: payloads.length,
+ requestPayload: { model: "test", session_id: "saved-session" },
+ createdAt: 1,
+ startedAt: 1,
+ completedAt: 100,
+ };
+ const context = vm.createContext({
+ ...recovery,
+ ...parser,
+ createGenerationToolRecovery,
+ generationRecoveries,
+ useChatRuntimeStore: { getState: () => runtime },
+ cancelChatGenerationRun: async () => {},
+ budgetImpliesTruncation: () => false,
+ saveStoredChatMessage: async (message: (typeof snapshots)[number]) => {
+ snapshots.push(structuredClone(message));
+ },
+ followChatGenerationRun: async function* (
+ _id: string,
+ followOptions: { replayFrom: number },
+ ) {
+ replayFrom = followOptions.replayFrom;
+ for (let i = followOptions.replayFrom; i < payloads.length; i++) {
+ const update = {
+ run,
+ event: {
+ seq: i + 1,
+ type: "chunk",
+ payload: payloads[i],
+ createdAt: i + 1,
+ },
+ };
+ yield update;
+ yield update;
+ }
+ },
+ restoredAssistantStatus: () => ({ type: "complete", reason: "stop" }),
+ isTerminalChatGenerationRun: () => true,
+ forgetServerActiveGenerationRun() {},
+ ChatGenerationStalledError: class extends Error {},
+ });
+ vm.runInContext(executable, context);
+ context.scheduleGenerationRecovery(
+ "thread",
+ {
+ id: "msg",
+ content,
+ createdAt: 1,
+ metadata: {
+ generationRunId: "run",
+ generationSeq: options.cursor ?? 0,
+ generationStatus: "running",
+ generationSettled: false,
+ },
+ },
+ {
+ threadListItem: () => ({ getState: () => ({ remoteId: "thread" }) }),
+ thread: () => ({
+ export: () => shown,
+ import: (value: typeof shown) => {
+ shown = value;
+ imports.push(value.messages[0].message.content);
+ },
+ }),
+ },
+ );
+ await generationRecoveries.get("run").promise;
+ const final = snapshots.at(-1);
+ assert.ok(final);
+ assert.equal(final.metadata.generationSettled, true);
+ assert.equal(final.metadata.generationSeq, payloads.length);
+ return {
+ content: final.content,
+ shown: shown.messages[0].message.content,
+ imports,
+ replayFrom,
+ snapshots,
+ };
+}
+
+test("the recovery scheduler persists later tool events between reasoning groups", async () => {
+ const { content } = await recoverRun(
+ [],
+ [
+ { choices: [{ delta: { reasoning_content: "before" } }] },
+ start(),
+ end(),
+ { choices: [{ delta: { reasoning_content: "after" } }] },
+ { choices: [{ delta: { content: "done" } }] },
+ ],
+ );
+ assert.deepEqual(
+ content.map((part) => part.type),
+ ["reasoning", "tool-call", "reasoning", "text"],
+ );
+ assert.equal(content[1].result, "ok");
+ assert.deepEqual(
+ content
+ .filter((part) => part.type === "reasoning")
+ .map((part) => part.text),
+ ["before", "after"],
+ );
+});
+
+test("the recovery scheduler completes a saved pending card", async () => {
+ const { content } = await recoverRun(
+ [
+ {
+ type: "tool-call",
+ toolCallId: "call_0:saved-id",
+ toolName: "python",
+ args: {},
+ },
+ ],
+ [end()],
+ );
+ assert.equal(content.length, 1);
+ assert.equal(content[0].toolCallId, "call_0:saved-id");
+ assert.deepEqual(content[0].result, {
+ text: "ok",
+ images: [],
+ files: [],
+ sessionId: "saved-session",
+ });
+});
+
+test("explicit think tags do not shift replayed tool offsets", async () => {
+ const { content } = await recoverRun(
+ [],
+ [
+ { choices: [{ delta: { content: "<think>before</think>" } }] },
+ start(),
+ end(),
+ { choices: [{ delta: { content: "<think>after</think>done" } }] },
+ ],
+ );
+ assert.deepEqual(
+ content.map((part) => part.type),
+ ["reasoning", "tool-call", "reasoning", "text"],
+ );
+ assert.deepEqual(
+ content
+ .filter((part) => part.type === "reasoning")
+ .map((part) => part.text),
+ ["before", "after"],
+ );
+});
+
+test("the scheduler recovers old approval identities without replaying saved text", async () => {
+ const saved = {
+ type: "tool-call",
+ toolCallId: "session:thread:approval-1",
+ toolName: "edit_file",
+ args: { path: "scene.glsl" },
+ };
+ const result = await recoverRun(
+ [{ type: "text", text: "Working:" }, saved],
+ [
+ { choices: [{ delta: { content: "Working:" } }] },
+ { ...start(), approval_id: "approval-1", awaiting_confirmation: true },
+ end(),
+ ],
+ { cursor: 2 },
+ );
+ assert.equal(result.replayFrom, 0);
+ assert.equal(recovery.generationRawContent(result.content).raw, "Working:");
+ assert.equal(result.content.length, 2);
+ assert.equal(result.content[1].toolCallId, saved.toolCallId);
+ assert.equal(result.content[1].result, "ok");
+ assert.deepEqual(result.shown, result.content);
+});
+
+test("the scheduler imports each live call once across reused backend ids", async () => {
+ for (const approval of [false, true]) {
+ const viewContent = [0, 1].map((i) => ({
+ type: "tool-call",
+ toolCallId: approval
+ ? `session:thread:approval-${i}`
+ : `call_0:live-${i}`,
+ toolName: "edit_file",
+ args: { path: "scene.glsl" },
+ result: `result-${i}`,
+ }));
+ const result = await recoverRun(
+ [],
+ [
+ { ...start(), ...(approval ? { approval_id: "approval-0" } : {}) },
+ { ...end(), result: "result-0" },
+ { ...start(), ...(approval ? { approval_id: "approval-1" } : {}) },
+ { ...end(), result: "result-1" },
+ ],
+ { viewContent },
+ );
+ assert.equal(result.content.length, 2);
+ assert.deepEqual(result.shown, result.content);
+ assert.deepEqual(
+ result.content.map((part) => part.result),
+ ["result-0", "result-1"],
+ );
+ assert.ok(result.imports.length > 0);
+ assert.ok(result.imports.every((parts) => parts.length === 2));
+ }
+});
+
+test("replay persists document citations without duplicate sources", async () => {
+ const citation = {
+ type: "page_location",
+ document_title: "Report",
+ document_index: 0,
+ start_page_number: 1,
+ end_page_number: 2,
+ cited_text: "Supporting passage",
+ };
+ const event = { type: "document_citations", citations: [citation] };
+ const result = await recoverRun(
+ [],
+ [
+ { choices: [{ delta: { content: "Answer [1]" } }] },
+ { _toolEvent: event },
+ event,
+ ],
+ );
+ assert.equal(recovery.generationRawContent(result.content).raw, "Answer [1]");
+ assert.deepEqual(
+ result.content.filter((part) => part.type === "source"),
+ [
+ {
+ type: "source",
+ sourceType: "url",
+ id: "#anthropic-doc-0#page_location:1:2",
+ url: "#anthropic-doc-0",
+ title: "Report",
+ metadata: { description: "Supporting passage" },
+ },
+ ],
+ );
+ assert.deepEqual(result.shown, result.content);
+ const resumed = await recoverRun(result.content, [event, event], {
+ cursor: 1,
+ });
+ assert.equal(
+ resumed.content.filter((part) => part.type === "source").length,
+ 1,
+ );
+});
+
+test("research handoffs stay hidden and approval cards finish", async () => {
+ for (const gated of [false, true]) {
+ const event = {
+ ...start(),
+ tool_name: "deep_research",
+ arguments: { question: "Research this" },
+ ...(gated
+ ? { awaiting_confirmation: true, approval_id: "approval" }
+ : {}),
+ };
+ const result = await recoverRun(
+ [],
+ [
+ event,
+ {
+ ...end(),
+ tool_name: "deep_research",
+ result: "Deep Research has started",
+ },
+ ],
+ );
+ assert.equal(result.content.length, gated ? 1 : 0);
+ if (gated)
+ assert.equal(result.content[0].result, "Deep Research has started");
+ }
+});
+
+test("Gemini native results and later images survive reloads", async () => {
+ const code = {
+ executableCode: { language: "PYTHON", code: "print(1)" },
+ thoughtSignature: "code-signature",
+ };
+ const output = {
+ codeExecutionResult: { outcome: "OUTCOME_OK", output: "1" },
+ };
+ const image = {
+ inlineData: { mimeType: "image/png", data: "cGxvdA==" },
+ thoughtSignature: "image-signature",
+ };
+ const event = {
+ ...start(),
+ tool_name: "code_execution",
+ arguments: { google: { native_part: { parts: [code] } } },
+ };
+ const completion = {
+ ...end(),
+ tool_name: "code_execution",
+ google: { native_part: { parts: [output] } },
+ };
+ const saved = {
+ type: "tool-call",
+ toolCallId: "call_0:saved",
+ backendToolCallId: "call_0",
+ toolName: "code_execution",
+ args: event.arguments,
+ };
+ const result = await recoverRun([saved], [event, completion], { cursor: 1 });
+ const args = result.content[0].args as typeof event.arguments;
+ assert.deepEqual(args.google.native_part.parts, [code, output]);
+ const resumed = await recoverRun(
+ result.content,
+ [
+ event,
+ completion,
+ {
+ ...end(),
+ tool_name: "code_execution",
+ google: { native_part: { parts: [image] } },
+ result: '1\n__IMAGES__:["plot.png"]',
+ },
+ ],
+ { cursor: 2 },
+ );
+ assert.equal(resumed.content.length, 1);
+ const merged = resumed.content[0].args as typeof event.arguments;
+ assert.deepEqual(merged.google.native_part.parts, [code, output, image]);
+ assert.deepEqual(
+ JSON.parse(String(resumed.content[0].argsText)).google.native_part.parts,
+ [code, output, image],
+ );
+ assert.deepEqual(saved.args.google.native_part.parts, [code]);
+});
+
+test("legacy Gemini signatures and image calls retain exact arguments", () => {
+ const code = {
+ executableCode: { code: "print(1)" },
+ thought_signature: "legacy-signature",
+ };
+ const image = {
+ inlineData: { mimeType: "image/png", data: "aW1hZ2U=" },
+ thoughtSignature: "image-signature",
+ };
+ for (const toolName of ["code_execution", "image_generation"]) {
+ const carried: Carried[] = [];
+ const replay = createGenerationToolRecovery(carried, "run").apply;
+ const argsText = `{"id":9007199254740993,"google":{"native_part":${JSON.stringify(toolName === "code_execution" ? code : {})}}}`;
+ replay(
+ {
+ ...start(),
+ tool_name: toolName,
+ arguments: JSON.parse(argsText),
+ arguments_text: argsText,
+ },
+ 0,
+ 1,
+ );
+ replay(
+ {
+ ...end(),
+ tool_name: toolName,
+ google: { native_part: { parts: [image] } },
+ ...(toolName === "image_generation"
+ ? { image_b64: "aW1hZ2U=", image_mime: "image/png" }
+ : {}),
+ },
+ 0,
+ 2,
+ );
+ const part = carried[0].part as Record<string, unknown>;
+ const expected =
+ toolName === "code_execution"
+ ? [
+ {
+ executableCode: code.executableCode,
+ thoughtSignature: "legacy-signature",
+ },
+ image,
+ ]
+ : [image];
+ assert.deepEqual(
+ JSON.parse(String(part.argsText)).google.native_part.parts,
+ expected,
+ );
+ assert.match(String(part.argsText), /9007199254740993/);
+ if (toolName === "image_generation")
+ assert.equal(
+ (part.result as Record<string, unknown>).image_b64,
+ "aW1hZ2U=",
+ );
+ }
+});
+
+test("citations retain safe URLs and distinct footnotes", async () => {
+ const base = {
+ type: "char_location",
+ document_index: 2,
+ start_char_index: 0,
+ end_char_index: 10,
+ cited_text: "x".repeat(300),
+ };
+ const result = await recoverRun(
+ [],
+ [
+ {
+ type: "document_citations",
+ citations: [
+ null,
+ [],
+ { ...base, source: "javascript:alert(1)" },
+ { ...base, source: "https://example.com/report" },
+ {
+ ...base,
+ source: "https://example.com/report",
+ start_char_index: 10,
+ end_char_index: 20,
+ },
+ ],
+ },
+ ],
+ );
+ assert.equal(result.content.length, 3);
+ assert.deepEqual(
+ result.content.map((part) => part.url),
+ [
+ "#anthropic-doc-2",
+ "https://example.com/report",
+ "https://example.com/report",
+ ],
+ );
+ assert.equal(new Set(result.content.map((part) => part.id)).size, 3);
+ assert.ok(
+ result.content.every(
+ (part) =>
+ (part.metadata as { description: string }).description.length === 243,
+ ),
+ );
+});
+
+test("calls a provider gave no id to open one card each", async () => {
+ const call = (name: string) => ({
+ type: "tool_start",
+ tool_call_id: "",
+ tool_name: name,
+ arguments: { path: `${name}.ts` },
+ });
+ const { content } = await recoverRun(
+ [],
+ [call("read_file"), call("edit_file")],
+ );
+ const cards = content.filter((part) => part.type === "tool-call");
+ assert.deepEqual(
+ cards.map((part) => part.toolName),
+ ["read_file", "edit_file"],
+ );
+ assert.equal(new Set(cards.map((part) => part.toolCallId)).size, 2);
+});
+
+test("an id-less completion closes the most recent open card", async () => {
+ const { content } = await recoverRun(
+ [],
+ [
+ { type: "tool_start", tool_call_id: "", tool_name: "read_file" },
+ { type: "tool_start", tool_call_id: "", tool_name: "edit_file" },
+ { type: "tool_end", tool_call_id: "", result: "wrote it" },
+ ],
+ );
+ const cards = content.filter((part) => part.type === "tool-call");
+ assert.deepEqual(
+ cards.map((part) => [part.toolName, part.result]),
+ [
+ ["read_file", undefined],
+ ["edit_file", "wrote it"],
+ ],
+ );
+});
+
+test("saved id-less cards each keep their own pending slot", async () => {
+ const saved = (name: string) => ({
+ type: "tool-call",
+ toolCallId: `${name}:saved`,
+ backendToolCallId: "",
+ toolName: name,
+ args: {},
+ argsText: "{}",
+ });
+ const { content } = await recoverRun(
+ [saved("read_file"), saved("edit_file")],
+ [
+ { type: "tool_end", tool_call_id: "", result: "second" },
+ { type: "tool_end", tool_call_id: "", result: "first" },
+ ],
+ );
+ const cards = content.filter((part) => part.type === "tool-call");
+ assert.deepEqual(
+ cards.map((part) => [part.toolName, part.result]),
+ [
+ ["read_file", "first"],
+ ["edit_file", "second"],
+ ],
+ );
+});
+
+test("a full identity replay does not republish the saved history", async () => {
+ const legacy = {
+ type: "tool-call",
+ toolCallId: "call_7:legacy",
+ toolName: "edit_file",
+ args: {},
+ argsText: "{}",
+ };
+ const history = Array.from({ length: 12 }, (_, i) => ({
+ choices: [{ delta: { content: `t${i}` } }],
+ }));
+ const { replayFrom, imports } = await recoverRun(
+ [legacy],
+ [
+ ...history,
+ { type: "tool_start", tool_call_id: "call_7", tool_name: "edit_file" },
+ { type: "tool_end", tool_call_id: "call_7", result: "done" },
+ ],
+ { cursor: 12 },
+ );
+ assert.equal(replayFrom, 0, "a legacy card still replays from the start");
+ assert.ok(
+ imports.length <= 4,
+ `history must not be republished, got ${imports.length} imports`,
+ );
+});
+
+test("recovery rebuilds the Sources panel from a replayed web search", async () => {
+ const result = [
+ "Title: Unsloth docs",
+ "URL: https://docs.unsloth.ai/",
+ "Snippet: fine-tuning guide",
+ ].join("\n");
+ const { content } = await recoverRun(
+ [],
+ [
+ { type: "tool_start", tool_call_id: "ws_1", tool_name: "web_search" },
+ { type: "tool_end", tool_call_id: "ws_1", result },
+ ],
+ );
+ const sources = content.filter((part) => part.type === "source");
+ assert.deepEqual(
+ sources.map((part) => [part.url, part.title]),
+ [["https://docs.unsloth.ai/", "Unsloth docs"]],
+ );
+ assert.equal(
+ content.at(-1)?.type,
+ "source",
+ "sources trail the reply, as the live path yields them",
+ );
+});
+
+test("rebuilt sources do not duplicate ones already saved", async () => {
+ const result = "Title: Docs\nURL: https://docs.unsloth.ai/\nSnippet: guide";
+ const saved = [
+ {
+ type: "tool-call",
+ toolCallId: "ws_1:saved",
+ backendToolCallId: "ws_1",
+ toolName: "web_search",
+ args: {},
+ argsText: "{}",
+ result,
+ },
+ {
+ type: "source",
+ sourceType: "url",
+ id: "https://docs.unsloth.ai/",
+ url: "https://docs.unsloth.ai/",
+ title: "Docs",
+ },
+ ];
+ const { content } = await recoverRun(saved, [
+ { choices: [{ delta: { content: "more" } }] },
+ ]);
+ assert.equal(content.filter((part) => part.type === "source").length, 1);
+});
+
+test("an unsafe search URL never reaches the Sources panel", async () => {
+ const { content } = await recoverRun(
+ [],
+ [
+ { type: "tool_start", tool_call_id: "ws_2", tool_name: "web_fetch" },
+ {
+ type: "tool_end",
+ tool_call_id: "ws_2",
+ result: "Title: Bad\nURL: javascript:alert(1)\nSnippet: no",
+ },
+ ],
+ );
+ assert.equal(content.filter((part) => part.type === "source").length, 0);
+});
+
+test("a web search completed twice keeps the citation list", async () => {
+ const citations = [
+ "Title: Unsloth docs",
+ "URL: https://docs.unsloth.ai/",
+ "Snippet: guide",
+ ].join("\n");
+ const { content } = await recoverRun(
+ [],
+ [
+ { type: "tool_start", tool_call_id: "ws_0", tool_name: "web_search" },
+ { type: "tool_end", tool_call_id: "ws_0", result: "Searching: unsloth" },
+ { type: "tool_end", tool_call_id: "ws_0", result: citations },
+ ],
+ );
+ const card = content.find((part) => part.type === "tool-call");
+ assert.equal(card?.result, citations);
+ assert.deepEqual(
+ content.filter((part) => part.type === "source").map((part) => part.url),
+ ["https://docs.unsloth.ai/"],
+ );
+});
+
+test("a start on the same id still opens a second round", async () => {
+ const { content } = await recoverRun(
+ [],
+ [
+ { type: "tool_start", tool_call_id: "call_0", tool_name: "edit_file" },
+ { type: "tool_end", tool_call_id: "call_0", result: "first" },
+ { type: "tool_start", tool_call_id: "call_0", tool_name: "edit_file" },
+ { type: "tool_end", tool_call_id: "call_0", result: "second" },
+ ],
+ );
+ assert.deepEqual(
+ content
+ .filter((part) => part.type === "tool-call")
+ .map((part) => part.result),
+ ["first", "second"],
+ );
+});
+
+test("a legacy id-less pending card is matched through replay", async () => {
+ const legacy = {
+ type: "tool-call",
+ toolCallId: "edit_file_1757000000000",
+ toolName: "edit_file",
+ args: {},
+ argsText: "{}",
+ };
+ const { content, replayFrom } = await recoverRun(
+ [legacy],
+ [
+ { type: "tool_start", tool_call_id: "", tool_name: "edit_file" },
+ { type: "tool_end", tool_call_id: "", result: "done" },
+ ],
+ { cursor: 1 },
+ );
+ assert.equal(replayFrom, 0, "an identity-less card replays from the start");
+ const cards = content.filter((part) => part.type === "tool-call");
+ assert.equal(
+ cards.length,
+ 1,
+ "the historical start must not open a second card",
+ );
+ assert.equal(cards[0].result, "done");
+});
+
+test("a citation result reaches a card whose placeholder was already saved", async () => {
+ const citations = [
+ "Title: Unsloth docs",
+ "URL: https://docs.unsloth.ai/",
+ "Snippet: guide",
+ ].join("\n");
+ const saved = {
+ type: "tool-call",
+ toolCallId: "ws_0:saved",
+ backendToolCallId: "ws_0",
+ toolName: "web_search",
+ args: {},
+ argsText: "{}",
+ result: "Searching: unsloth",
+ };
+ const { content } = await recoverRun(
+ [saved],
+ [{ type: "tool_end", tool_call_id: "ws_0", result: citations }],
+ );
+ const cards = content.filter((part) => part.type === "tool-call");
+ assert.equal(cards.length, 1);
+ assert.equal(cards[0].result, citations);
+ assert.deepEqual(
+ content.filter((part) => part.type === "source").map((part) => part.url),
+ ["https://docs.unsloth.ai/"],
+ );
+});
+
+test("a saved completed card still yields to a new round on its id", async () => {
+ const saved = {
+ type: "tool-call",
+ toolCallId: "call_0:saved",
+ backendToolCallId: "call_0",
+ toolName: "edit_file",
+ args: {},
+ argsText: "{}",
+ result: "first",
+ };
+ const { content } = await recoverRun(
+ [saved],
+ [
+ { type: "tool_start", tool_call_id: "call_0", tool_name: "edit_file" },
+ { type: "tool_end", tool_call_id: "call_0", result: "second" },
+ ],
+ );
+ assert.deepEqual(
+ content
+ .filter((part) => part.type === "tool-call")
+ .map((part) => part.result),
+ ["first", "second"],
+ );
+});
+
+test("a settled recovery reports the tool calls it restored", async () => {
+ const { content, snapshots } = await recoverRun(
+ [],
+ [
+ { type: "tool_start", tool_call_id: "call_0", tool_name: "edit_file" },
+ { type: "tool_end", tool_call_id: "call_0", result: "ok" },
+ ],
+ );
+ assert.equal(content.filter((part) => part.type === "tool-call").length, 1);
+ const final = snapshots.at(-1);
+ const details = final?.metadata.responseDetails as { toolCalls: string[] };
+ const timing = final?.metadata.timing as { toolCallCount: number };
+ assert.deepEqual(details.toolCalls, ["edit_file"]);
+ assert.equal(timing.toolCallCount, 1);
+});
+
+test("repeated source ids pair one to one instead of multiplying", () => {
+ const url = "https://docs.unsloth.ai/";
+ const source = () => ({ type: "source", sourceType: "url", id: url, url });
+ const view = [{ type: "text", text: "answer" }, source(), source()];
+ const recovered = [{ type: "text", text: "answer" }, source(), source()];
+ let carriedView = view;
+ // Every publish re-imports; a duplicate that reads as missing would grow each round.
+ for (let round = 0; round < 3; round++) {
+ carriedView = recovery.recoveredContentToImport(
+ carriedView,
+ recovered,
+ ) as typeof view;
+ assert.equal(
+ carriedView.filter((part) => part.type === "source").length,
+ 2,
+ `round ${round}`,
+ );
+ }
+});
+
+test("a legacy completed card takes its citation result", async () => {
+ const citations = "Title: Docs\nURL: https://docs.unsloth.ai/\nSnippet: g";
+ const legacy = {
+ type: "tool-call",
+ toolCallId: "ws_0:9f1c-legacy-uuid",
+ toolName: "web_search",
+ args: {},
+ argsText: "{}",
+ result: "Searching: unsloth",
+ };
+ const { content } = await recoverRun(
+ [legacy],
+ [{ type: "tool_end", tool_call_id: "ws_0", result: citations }],
+ );
+ const cards = content.filter((part) => part.type === "tool-call");
+ assert.equal(cards.length, 1);
+ assert.equal(cards[0].result, citations);
+ assert.deepEqual(
+ content.filter((part) => part.type === "source").map((part) => part.url),
+ ["https://docs.unsloth.ai/"],
+ );
+});
+
+test("a repeated id-less ending replaces the card it already finished", async () => {
+ const { content } = await recoverRun(
+ [],
+ [
+ { type: "tool_start", tool_call_id: "", tool_name: "web_search" },
+ { type: "tool_end", tool_call_id: "", result: "Searching: unsloth" },
+ { type: "tool_end", tool_call_id: "", result: "final answer" },
+ ],
+ );
+ const cards = content.filter((part) => part.type === "tool-call");
+ assert.equal(cards.length, 1);
+ assert.equal(cards[0].result, "final answer");
+});
+
+test("a divergent reply wins over a view that is only a tool card", () => {
+ const view: Record<string, unknown>[] = [
+ {
+ type: "tool-call",
+ toolCallId: "old:card",
+ toolName: "edit_file",
+ result: "stale",
+ },
+ ];
+ const recovered: Record<string, unknown>[] = [
+ { type: "text", text: "server repaired response" },
+ ];
+ assert.deepEqual(
+ recovery.recoveredContentToImport(view, recovered),
+ recovered,
+ );
+});
+
+test("the id-less sentinel keeps the file searchable and cannot collide", () => {
+ const src = readFileSync(
+ new URL(
+ "../src/features/chat/utils/generation-tool-recovery.ts",
+ import.meta.url,
+ ),
+ "utf8",
+ );
+ assert.ok(!src.includes("\0"), "a NUL byte makes the file read as binary");
+ // A backend tool call id must satisfy ^[a-zA-Z0-9_-]+$, so '#' can never appear in one.
+ for (const key of src.matchAll(/`(#idless:[^`]*)`/g)) {
+ assert.ok(/^#/.test(key[1]), key[1]);
+ }
+ assert.equal(src.match(/`#idless:/g)?.length, 3);
+});
+
+test("a source an earlier recovery saved stays behind text replayed after it", async () => {
+ const citations = "Title: Docs\nURL: https://docs.unsloth.ai/\nSnippet: g";
+ // What a previous recovery session persisted: the card, then the source it appended.
+ const saved = [
+ { type: "text", text: "Searching." },
+ {
+ type: "tool-call",
+ toolCallId: "ws_0:run:1",
+ backendToolCallId: "ws_0",
+ toolName: "web_search",
+ args: {},
+ argsText: "{}",
+ result: citations,
+ },
+ {
+ type: "source",
+ sourceType: "url",
+ id: "https://docs.unsloth.ai/",
+ url: "https://docs.unsloth.ai/",
+ title: "Docs",
+ },
+ ];
+ const { content } = await recoverRun(saved, [
+ { choices: [{ delta: { content: " Here is **what" } }] },
+ { choices: [{ delta: { content: " I found** next." } }] },
+ ]);
+
+ // Carried at its old offset the source would split the reply, and the emphasis with it.
+ assert.equal(content.at(-1)?.type, "source");
+ assert.deepEqual(
+ content.filter((part) => part.type === "source").map((part) => part.url),
+ ["https://docs.unsloth.ai/"],
+ );
+ assert.equal(
+ content
+ .filter((part) => part.type === "text")
+ .map((part) => part.text)
+ .join(""),
+ "Searching. Here is **what I found** next.",
+ );
+ assert.equal(
+ content.filter((part) => part.type === "text").length,
+ 2,
+ "the text either side of the card, not cut again by the source",
+ );
+});
+
+test("two rounds finding the same page keep a source each, with their own titles", async () => {
+ const first = "Title: Docs v1\nURL: https://docs.unsloth.ai/\nSnippet: first";
+ const second = "Title: Docs v2\nURL: https://docs.unsloth.ai/\nSnippet: second";
+ const { content } = await recoverRun(
+ [],
+ [
+ { type: "tool_start", tool_call_id: "ws_0", tool_name: "web_search" },
+ { type: "tool_end", tool_call_id: "ws_0", result: first },
+ { type: "tool_start", tool_call_id: "ws_1", tool_name: "web_search" },
+ { type: "tool_end", tool_call_id: "ws_1", result: second },
+ ],
+ );
+ // The live path flat-maps the cards, so the panel lists the page once per round.
+ assert.deepEqual(
+ content.filter((part) => part.type === "source").map((part) => part.title),
+ ["Docs v1", "Docs v2"],
+ );
+});
+
+test("a card that finishes twice rebuilds its sources from the newer result", () => {
+ // Sources are parsed once per card rather than once per rebuild, so the cache key has to
+ // move whenever the result does. Keying it on the card's backend id instead, which reads
+ // as the obvious choice, breaks exactly here: OpenAI Responses ends a web search twice,
+ // a placeholder and then the citations, and the panel would keep the placeholder's.
+ const carried: Carried[] = [];
+ const { apply, withSources } = createGenerationToolRecovery(carried, "run");
+ apply({ type: "tool_start", tool_call_id: "ws_0", tool_name: "web_search" }, 0, 1);
+ apply(
+ {
+ type: "tool_end",
+ tool_call_id: "ws_0",
+ result: "Title: Placeholder\nURL: https://example.com/a\nSnippet: first",
+ },
+ 0,
+ 2,
+ );
+ assert.deepEqual(
+ withSources<Record<string, unknown>>([]).map((part) => part.title),
+ ["Placeholder"],
+ );
+ apply(
+ {
+ type: "tool_end",
+ tool_call_id: "ws_0",
+ result: "Title: Cited\nURL: https://example.com/b\nSnippet: second",
+ },
+ 0,
+ 3,
+ );
+ assert.deepEqual(
+ withSources<Record<string, unknown>>([]).map((part) => part.title),
+ ["Cited"],
+ "the second completion's sources, not the ones parsed for the first",
+ );
+});
+
+test("each rebuild yields its own source objects", () => {
+ // Same reason: the parse is shared between rebuilds, the objects must not be. A caller
+ // that edits a part it was handed would otherwise change what the next rebuild returns.
+ const carried: Carried[] = [];
+ const { apply, withSources } = createGenerationToolRecovery(carried, "run");
+ apply({ type: "tool_start", tool_call_id: "ws_0", tool_name: "web_search" }, 0, 1);
+ apply(
+ {
+ type: "tool_end",
+ tool_call_id: "ws_0",
+ result: "Title: Docs\nURL: https://example.com/a\nSnippet: only",
+ },
+ 0,
+ 2,
+ );
+ const first = withSources<Record<string, unknown>>([])[0];
+ first.title = "edited";
+ (first.metadata as Record<string, unknown>).description = "edited";
+ const second = withSources<Record<string, unknown>>([])[0];
+ assert.notEqual(first, second);
+ assert.equal(second.title, "Docs");
+ assert.deepEqual(second.metadata, { description: "only" });
+});