🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
feat(transcript): expose current turn nesting level (#18011)
marliessophied50d19c5f80c
diff --git a/packages/shared/AGENTS.md b/packages/shared/AGENTS.mdindex 973dbb7109..c670099c1a 100644--- a/packages/shared/AGENTS.md+++ b/packages/shared/AGENTS.md@@ -22,6 +22,10 @@call `flushMetricsToCloudWatch` from the server barrel after recording tosubmit them before the next gauge replaces the cached value.- Server cache utilities: `src/server/cache/*`+- Transcript assembly: pass the enriched result of `orderObservations` into+ `assembleTranscript`. `currentTurn.nestingLevel` uses the first contributing+ generation after history is split off; it is not the depth of the first+ generation in the full thread.- Domain model types: `src/domain/*`- Repository layer: `src/server/repositories/*`- Queue payload schemas: `src/server/queues.ts`diff --git a/packages/shared/src/server/transcript/README.md b/packages/shared/src/server/transcript/README.mdindex fd0decf35a..f11a5c924b 100644--- a/packages/shared/src/server/transcript/README.md+++ b/packages/shared/src/server/transcript/README.md@@ -12,8 +12,8 @@ Status: generation-led builder with tool responses matched by ID or name and ord## Interface```ts-orderObservations(observations: Observation[]): Observation[];-assembleTranscript(orderedObservations: Observation[]): Transcript | null;+orderObservations<T extends TranscriptObservation>(observations: T[]): Array<T & { nestingLevel: number }>;+assembleTranscript(orderedObservations: OrderedObservation[]): Transcript | null;type Transcript = { threads: Thread[] };@@ -23,6 +23,7 @@ type Thread = {};type Turn = {+ nestingLevel: number;messages: ThreadMessage[];observations: { id: string; traceId: string }[]; // observations that contributed, in order};@@ -30,6 +31,8 @@ type Turn = {type ThreadMessage = NormalizedMessage & {observationId: string; // observation that first emitted the messagetraceId: string;+ startTime: Date; // source observation start, not an individual message timestamp+ endTime: Date | null; // source observation end, when available};```@@ -235,3 +238,10 @@ Run with console output enabled to see it:```bashpnpm --filter @langfuse/shared run test src/server/transcript --disableConsoleIntercept```++`currentTurn.nestingLevel` is the observation-tree depth of the first GENERATION+that contributes retained messages to the current turn. All ancestor types count;+fetched roots and observations with missing parents are level 0. Cyclic rows+that cannot be reached by the tree walk also use level 0. Earlier conversation+history, replay-only generations, later generations, and TOOL contributors do+not determine the value. Ordering attaches depth without changing source observations.diff --git a/packages/shared/src/server/transcript/fixtures/fixtures.test.ts b/packages/shared/src/server/transcript/fixtures/fixtures.test.tsindex be9772c61c..097c4de0da 100644--- a/packages/shared/src/server/transcript/fixtures/fixtures.test.ts+++ b/packages/shared/src/server/transcript/fixtures/fixtures.test.ts@@ -11,8 +11,8 @@ import { formatTranscript } from "./format-transcript";*/describe("transcript fixtures", () => {const traceId = "trace";- const generation = (id: string, input: string[], output: string[]) =>- convertObservation(+ const generation = (id: string, input: string[], output: string[]) => ({+ ...convertObservation(createObservation({id,trace_id: traceId,@@ -25,7 +25,9 @@ describe("transcript fixtures", () => {output.map((content) => ({ role: "user", content })),),}),- );+ ),+ nestingLevel: 0,+ });it("skips generations without messages", () => {const empty = generation("1", [], []);@@ -37,6 +39,18 @@ describe("transcript fixtures", () => {]);});+ it("preserves an unfinished generation's null end time", () => {+ const observation = generation("1", ["A"], ["B"]);+ observation.endTime = null;+ const transcript = assembleTranscript([observation]);++ expect(transcript?.threads[0].currentTurn.messages).toHaveLength(2);+ for (const message of transcript!.threads[0].currentTurn.messages) {+ expect(message.startTime).toEqual(observation.startTime);+ expect(message.endTime).toBeNull();+ }+ });+it("continues the newest matching thread without duplicating history", () => {const transcript = assembleTranscript([generation("1", ["A"], []),@@ -70,6 +84,52 @@ describe("transcript fixtures", () => {]);});+ it("uses the first current-turn generation depth, excluding history and later generations", () => {+ const previous = {+ ...generation("1", ["A"], []),+ traceId: "previous-trace",+ startTime: new Date("2025-12-31T12:00:00Z"),+ output: [{ role: "assistant", content: "B" }],+ };+ const first = {+ ...generation("2", [], []),+ parentObservationId: "agent",+ input: [+ { role: "user", content: "A" },+ { role: "assistant", content: "B" },+ { role: "user", content: "C" },+ ],+ output: [{ role: "assistant", content: "D" }],+ };+ const later = {+ ...generation("3", [], []),+ parentObservationId: "root",+ input: [...first.input, ...first.output],+ output: [{ role: "assistant", content: "E" }],+ };+ const root = {+ ...generation("0", [], []),+ id: "root",+ type: "SPAN" as const,+ parentObservationId: null,+ };+ const agent = {+ ...root,+ id: "agent",+ type: "AGENT" as const,+ parentObservationId: "root",+ };+ const transcript = assembleTranscript(+ orderObservations([previous, root, agent, first, later]),+ );+ expect(transcript?.threads).toHaveLength(1);+ expect(transcript?.threads[0].currentTurn.nestingLevel).toBe(2);+ expect(+ transcript?.threads[0].currentTurn.observations.map(({ id }) => id),+ ).toEqual(["2", "3"]);+ expect(transcript?.threads[0].conversationHistory).toHaveLength(2);+ });+it("have unique names", () => {const names = transcriptFixtures.map((fixture) => fixture.name);expect(new Set(names).size).toBe(names.length);diff --git a/packages/shared/src/server/transcript/fixtures/trace/inherited-conversation-history.ts b/packages/shared/src/server/transcript/fixtures/trace/inherited-conversation-history.tsindex f8a4b414b3..0dc36656d0 100644--- a/packages/shared/src/server/transcript/fixtures/trace/inherited-conversation-history.ts+++ b/packages/shared/src/server/transcript/fixtures/trace/inherited-conversation-history.ts@@ -45,12 +45,15 @@ export const inheritedConversationHistoryFixture = {},],currentTurn: {+ nestingLevel: 0,messages: [{role: "user",parts: [{ type: "text", text: "Follow-up request" }],source: "input",observationId: "inherited-history-generation",+ startTime: new Date("2026-01-01T12:01:00.000Z"),+ endTime: new Date("2026-01-01T12:01:01.000Z"),traceId: "inherited-history-trace",},{@@ -58,6 +61,8 @@ export const inheritedConversationHistoryFixture = {parts: [{ type: "text", text: "Second response" }],source: "output",observationId: "inherited-history-generation",+ startTime: new Date("2026-01-01T12:01:00.000Z"),+ endTime: new Date("2026-01-01T12:01:01.000Z"),traceId: "inherited-history-trace",},],diff --git a/packages/shared/src/server/transcript/fixtures/trace/openai-agents-joke-and-rating.ts b/packages/shared/src/server/transcript/fixtures/trace/openai-agents-joke-and-rating.tsindex fbfc35397e..c82c250508 100644--- a/packages/shared/src/server/transcript/fixtures/trace/openai-agents-joke-and-rating.ts+++ b/packages/shared/src/server/transcript/fixtures/trace/openai-agents-joke-and-rating.ts@@ -372,6 +372,7 @@ export const openaiAgentsJokeAndRatingFixture = {{conversationHistory: [],currentTurn: {+ nestingLevel: 3,messages: [{role: "user",@@ -383,6 +384,8 @@ export const openaiAgentsJokeAndRatingFixture = {],source: "input",observationId: "f8fdd8164d6f8dbe",+ startTime: new Date("2025-09-30T09:04:06.682Z"),+ endTime: new Date("2025-09-30T09:04:07.517Z"),traceId: "afa1ae379b6c3a5333e2bab357f31cdc",},{@@ -399,6 +402,8 @@ export const openaiAgentsJokeAndRatingFixture = {],source: "output",observationId: "f8fdd8164d6f8dbe",+ startTime: new Date("2025-09-30T09:04:06.682Z"),+ endTime: new Date("2025-09-30T09:04:07.517Z"),traceId: "afa1ae379b6c3a5333e2bab357f31cdc",},],@@ -413,6 +418,7 @@ export const openaiAgentsJokeAndRatingFixture = {{conversationHistory: [],currentTurn: {+ nestingLevel: 3,messages: [{role: "user",@@ -424,6 +430,8 @@ export const openaiAgentsJokeAndRatingFixture = {],source: "input",observationId: "496efdc060a5399b",+ startTime: new Date("2025-09-30T09:04:07.522Z"),+ endTime: new Date("2025-09-30T09:04:09.029Z"),traceId: "afa1ae379b6c3a5333e2bab357f31cdc",},{@@ -440,6 +448,8 @@ export const openaiAgentsJokeAndRatingFixture = {],source: "output",observationId: "496efdc060a5399b",+ startTime: new Date("2025-09-30T09:04:07.522Z"),+ endTime: new Date("2025-09-30T09:04:09.029Z"),traceId: "afa1ae379b6c3a5333e2bab357f31cdc",},],diff --git a/packages/shared/src/server/transcript/fixtures/trace/openai-agents-spanish-handoff.ts b/packages/shared/src/server/transcript/fixtures/trace/openai-agents-spanish-handoff.tsindex 5bacf2e97a..9af7a59029 100644--- a/packages/shared/src/server/transcript/fixtures/trace/openai-agents-spanish-handoff.ts+++ b/packages/shared/src/server/transcript/fixtures/trace/openai-agents-spanish-handoff.ts@@ -470,6 +470,7 @@ export const openaiAgentsSpanishHandoffFixture = {{conversationHistory: [],currentTurn: {+ nestingLevel: 3,messages: [{role: "user",@@ -481,6 +482,8 @@ export const openaiAgentsSpanishHandoffFixture = {],source: "input",observationId: "94a1dc00d7067ae8",+ startTime: new Date("2025-09-30T09:03:51.192Z"),+ endTime: new Date("2025-09-30T09:03:52.756Z"),traceId: "c376e44920527b875add9d97b4ed9312",},{@@ -499,6 +502,8 @@ export const openaiAgentsSpanishHandoffFixture = {],source: "output",observationId: "94a1dc00d7067ae8",+ startTime: new Date("2025-09-30T09:03:51.192Z"),+ endTime: new Date("2025-09-30T09:03:52.756Z"),traceId: "c376e44920527b875add9d97b4ed9312",},{@@ -514,6 +519,8 @@ export const openaiAgentsSpanishHandoffFixture = {},],observationId: "a0391ae77593ad0c",+ startTime: new Date("2025-09-30T09:03:52.760Z"),+ endTime: new Date("2025-09-30T09:03:54.433Z"),traceId: "c376e44920527b875add9d97b4ed9312",},{@@ -530,6 +537,8 @@ export const openaiAgentsSpanishHandoffFixture = {],source: "output",observationId: "a0391ae77593ad0c",+ startTime: new Date("2025-09-30T09:03:52.760Z"),+ endTime: new Date("2025-09-30T09:03:54.433Z"),traceId: "c376e44920527b875add9d97b4ed9312",},],diff --git a/packages/shared/src/server/transcript/fixtures/trace/standalone-tool-observation.ts b/packages/shared/src/server/transcript/fixtures/trace/standalone-tool-observation.tsindex 347ebc465e..c15bcadc99 100644--- a/packages/shared/src/server/transcript/fixtures/trace/standalone-tool-observation.ts+++ b/packages/shared/src/server/transcript/fixtures/trace/standalone-tool-observation.ts@@ -42,12 +42,15 @@ export const standaloneToolObservationFixture = {{conversationHistory: [],currentTurn: {+ nestingLevel: 0,messages: [{role: "user",parts: [{ type: "text", text: "Find my orders." }],source: "input",observationId: "standalone-generation",+ startTime: new Date("2026-01-01T12:00:00.000Z"),+ endTime: new Date("2026-01-01T12:00:01.000Z"),traceId: "standalone-tool-trace",},{@@ -55,6 +58,8 @@ export const standaloneToolObservationFixture = {parts: [{ type: "text", text: "I'll look up your orders." }],source: "output",observationId: "standalone-generation",+ startTime: new Date("2026-01-01T12:00:00.000Z"),+ endTime: new Date("2026-01-01T12:00:01.000Z"),traceId: "standalone-tool-trace",},],diff --git a/packages/shared/src/server/transcript/fixtures/trace/support-copilot-follow-up.ts b/packages/shared/src/server/transcript/fixtures/trace/support-copilot-follow-up.tsindex 0527d0f515..4e8838d405 100644--- a/packages/shared/src/server/transcript/fixtures/trace/support-copilot-follow-up.ts+++ b/packages/shared/src/server/transcript/fixtures/trace/support-copilot-follow-up.ts@@ -154,11 +154,16 @@ export const supportCopilotFollowUpFixture = {{conversationHistory: replayedHistory,currentTurn: {+ nestingLevel: 2,messages: followUpCopy(firstThread.currentTurn.messages.filter((message) => message.role !== "system",),- ),+ ).map((message) => ({+ ...message,+ startTime: new Date(message.startTime),+ endTime: message.endTime ? new Date(message.endTime) : null,+ })),observations: followUpCopy(firstThread.currentTurn.observations),},},diff --git a/packages/shared/src/server/transcript/fixtures/trace/support-copilot-refund-loop.ts b/packages/shared/src/server/transcript/fixtures/trace/support-copilot-refund-loop.tsindex 62a553f6e3..b96cc8613d 100644--- a/packages/shared/src/server/transcript/fixtures/trace/support-copilot-refund-loop.ts+++ b/packages/shared/src/server/transcript/fixtures/trace/support-copilot-refund-loop.ts@@ -383,6 +383,7 @@ export const supportCopilotRefundLoopFixture = {{conversationHistory: [],currentTurn: {+ nestingLevel: 2,observations: ["cls","llm1",@@ -397,6 +398,8 @@ export const supportCopilotRefundLoopFixture = {role: "system",source: "input",observationId: "sa2026083102o-cls",+ startTime: new Date("2026-08-31T12:33:14.205Z"),+ endTime: new Date("2026-08-31T12:33:14.818Z"),traceId,parts: [{ type: "text", text: copilotSystemPrompt }],},@@ -404,6 +407,8 @@ export const supportCopilotRefundLoopFixture = {role: "user",source: "input",observationId: "sa2026083102o-cls",+ startTime: new Date("2026-08-31T12:33:14.205Z"),+ endTime: new Date("2026-08-31T12:33:14.818Z"),traceId,parts: [{ type: "text", text: customerMessage }],},@@ -411,6 +416,8 @@ export const supportCopilotRefundLoopFixture = {role: "assistant",source: "output",observationId: "sa2026083102o-cls",+ startTime: new Date("2026-08-31T12:33:14.205Z"),+ endTime: new Date("2026-08-31T12:33:14.818Z"),traceId,parts: [{ type: "text", text: classification.content }],},@@ -418,6 +425,8 @@ export const supportCopilotRefundLoopFixture = {role: "assistant",source: "output",observationId: "sa2026083102o-llm1",+ startTime: new Date("2026-08-31T12:33:16.561Z"),+ endTime: new Date("2026-08-31T12:33:17.389Z"),traceId,parts: [{@@ -433,6 +442,8 @@ export const supportCopilotRefundLoopFixture = {role: "tool",source: "output",observationId: "sa2026083102o-find",+ startTime: new Date("2026-08-31T12:33:17.441Z"),+ endTime: new Date("2026-08-31T12:33:18.118Z"),traceId,parts: [{ type: "data", value: charges }],},@@ -440,6 +451,8 @@ export const supportCopilotRefundLoopFixture = {role: "assistant",source: "output",observationId: "sa2026083102o-llm2",+ startTime: new Date("2026-08-31T12:33:18.172Z"),+ endTime: new Date("2026-08-31T12:33:19.924Z"),traceId,parts: [{@@ -455,6 +468,8 @@ export const supportCopilotRefundLoopFixture = {role: "tool",source: "output",observationId: "sa2026083102o-ref",+ startTime: new Date("2026-08-31T12:33:19.978Z"),+ endTime: new Date("2026-08-31T12:33:20.893Z"),traceId,parts: [{ type: "data", value: refund }],},@@ -462,6 +477,8 @@ export const supportCopilotRefundLoopFixture = {role: "assistant",source: "output",observationId: "sa2026083102o-llm3",+ startTime: new Date("2026-08-31T12:33:20.947Z"),+ endTime: new Date("2026-08-31T12:33:22.731Z"),traceId,parts: [{ type: "text", text: "Resolution complete." }],},@@ -469,6 +486,8 @@ export const supportCopilotRefundLoopFixture = {role: "user",source: "input",observationId: "sa2026083102o-drf",+ startTime: new Date("2026-08-31T12:33:22.790Z"),+ endTime: new Date("2026-08-31T12:33:24.377Z"),traceId,parts: [{ type: "text", text: "Draft the reply." }],},@@ -476,6 +495,8 @@ export const supportCopilotRefundLoopFixture = {role: "assistant",source: "output",observationId: "sa2026083102o-drf",+ startTime: new Date("2026-08-31T12:33:22.790Z"),+ endTime: new Date("2026-08-31T12:33:24.377Z"),traceId,parts: [{ type: "text", text: finalReply }],},diff --git a/packages/shared/src/server/transcript/fixtures/trace/vercel-ai-sdk-docs-tool-loop.ts b/packages/shared/src/server/transcript/fixtures/trace/vercel-ai-sdk-docs-tool-loop.tsindex 1fa4218bcf..bce6997033 100644--- a/packages/shared/src/server/transcript/fixtures/trace/vercel-ai-sdk-docs-tool-loop.ts+++ b/packages/shared/src/server/transcript/fixtures/trace/vercel-ai-sdk-docs-tool-loop.ts@@ -706,6 +706,7 @@ export const vercelAiSdkDocsToolLoopFixture: TranscriptFixture = {{conversationHistory: [],currentTurn: {+ nestingLevel: 3,messages: [{role: "user",@@ -717,6 +718,8 @@ export const vercelAiSdkDocsToolLoopFixture: TranscriptFixture = {],source: "input",observationId: "1bbf3edb8ef95ab6",+ startTime: new Date("2026-09-09T08:26:57.837Z"),+ endTime: new Date("2026-09-09T08:27:02.699Z"),traceId: "75b336f98e39e275a823b0a7ec1ba794",},{@@ -750,6 +753,8 @@ export const vercelAiSdkDocsToolLoopFixture: TranscriptFixture = {},source: "output",observationId: "1bbf3edb8ef95ab6",+ startTime: new Date("2026-09-09T08:26:57.837Z"),+ endTime: new Date("2026-09-09T08:27:02.699Z"),traceId: "75b336f98e39e275a823b0a7ec1ba794",},{@@ -762,6 +767,8 @@ export const vercelAiSdkDocsToolLoopFixture: TranscriptFixture = {},],observationId: "3dbf50cbf2036387",+ startTime: new Date("2026-09-09T08:27:02.700Z"),+ endTime: new Date("2026-09-09T08:27:08.255Z"),traceId: "75b336f98e39e275a823b0a7ec1ba794",},{@@ -792,6 +799,8 @@ export const vercelAiSdkDocsToolLoopFixture: TranscriptFixture = {},source: "output",observationId: "0c13b686b4cf6ccc",+ startTime: new Date("2026-09-09T08:27:08.267Z"),+ endTime: new Date("2026-09-09T08:27:19.089Z"),traceId: "75b336f98e39e275a823b0a7ec1ba794",},],diff --git a/packages/shared/src/server/transcript/ordering.test.ts b/packages/shared/src/server/transcript/ordering.test.tsindex 1f7b045dd1..e38ffd2d13 100644--- a/packages/shared/src/server/transcript/ordering.test.ts+++ b/packages/shared/src/server/transcript/ordering.test.ts@@ -22,7 +22,12 @@ describe("orderObservations", () => {observation("g1", 5, "A"),observation("A", 0),]);- expect(ordered.map(({ id }) => id)).toEqual(["A", "g1", "B", "g2"]);+ expect(ordered.map(({ id, nestingLevel }) => [id, nestingLevel])).toEqual([+ ["A", 0],+ ["g1", 1],+ ["B", 0],+ ["g2", 1],+ ]);});it("keeps the earliest row per id and roots rows without a known parent", () => {@@ -31,6 +36,7 @@ describe("orderObservations", () => {observation("x", 1),observation("orphan", 2, "missing"),]);+ expect(ordered.map(({ nestingLevel }) => nestingLevel)).toEqual([0, 0]);expect(ordered.map(({ id, startTime }) => [id, startTime.getUTCSeconds()]),).toEqual([diff --git a/packages/shared/src/server/transcript/ordering.ts b/packages/shared/src/server/transcript/ordering.tsindex 509fb0d2be..392dbaad43 100644--- a/packages/shared/src/server/transcript/ordering.ts+++ b/packages/shared/src/server/transcript/ordering.ts@@ -1,4 +1,8 @@-import type { Observation } from "../../domain";+import type { TranscriptObservation } from "./types";++export type OrderedObservation = TranscriptObservation & {+ nestingLevel: number;+};/*** Order observations the way the trace tree walks them: depth first, with@@ -6,8 +10,10 @@ import type { Observation } from "../../domain";* row per id where the earliest start wins, and a row whose parent is not in* the list becomes a root. For a flat trace this is plain start-time order.*/-export function orderObservations(observations: Observation[]): Observation[] {- const byId = new Map<string, Observation>();+export function orderObservations<T extends TranscriptObservation>(+ observations: T[],+): Array<T & { nestingLevel: number }> {+ const byId = new Map<string, T>();for (const observation of observations) {const existing = byId.get(observation.id);if (!existing || observation.startTime < existing.startTime) {@@ -15,7 +21,7 @@ export function orderObservations(observations: Observation[]): Observation[] {}}- const children = new Map<string | null, Observation[]>();+ const children = new Map<string | null, T[]>();for (const observation of byId.values()) {const parentId =observation.parentObservationId !== null &&@@ -25,24 +31,25 @@ export function orderObservations(observations: Observation[]): Observation[] {children.set(parentId, [...(children.get(parentId) ?? []), observation]);}- const byStartTime = (a: Observation, b: Observation) =>+ const byStartTime = (a: T, b: T) =>a.startTime.getTime() - b.startTime.getTime();- const ordered: Observation[] = [];+ const ordered: Array<T & { nestingLevel: number }> = [];const visited = new Set<string>();- const walk = (parentId: string | null) => {+ const walk = (parentId: string | null, nestingLevel: number) => {for (const observation of (children.get(parentId) ?? []).sort(byStartTime,)) {if (visited.has(observation.id)) continue;visited.add(observation.id);- ordered.push(observation);- walk(observation.id);+ ordered.push({ ...observation, nestingLevel });+ walk(observation.id, nestingLevel + 1);}};- walk(null);+ walk(null, 0);// Rows inside a parent cycle are unreachable from any root; keep them.for (const observation of [...byId.values()].sort(byStartTime)) {- if (!visited.has(observation.id)) ordered.push(observation);+ if (!visited.has(observation.id))+ ordered.push({ ...observation, nestingLevel: 0 });}return ordered;}diff --git a/packages/shared/src/server/transcript/threads.ts b/packages/shared/src/server/transcript/threads.tsindex 296ec0a705..cb2283ca37 100644--- a/packages/shared/src/server/transcript/threads.ts+++ b/packages/shared/src/server/transcript/threads.ts@@ -1,17 +1,24 @@-import type { Observation } from "../../domain";import type { NormalizedMessage } from "../../utils/normalized-io";import type { Thread, ThreadMessage, Turn } from "./types";+import type { OrderedObservation } from "./ordering";import type { createToolCallRegistry } from "./tool-calls";-export type TranscriptObservation = Observation & { traceId: string };+export type TranscriptObservation = OrderedObservation & { traceId: string };export type KeyedMessage = {message: NormalizedMessage;key: string;};+export type AssembledTurn = Pick<Turn, "messages"> & {+ observations: Pick<+ TranscriptObservation,+ "id" | "traceId" | "type" | "nestingLevel"+ >[];+};+export type ThreadState = {/** Every message of the thread in one list; `splitTurn` derives the public shape. */- thread: Turn;+ thread: AssembledTurn;messages: KeyedMessage[];shownCounts: Map<string, number>;};@@ -76,6 +83,8 @@ export function append(parts: [],observationId: observation.id,traceId: observation.traceId,+ startTime: observation.startTime,+ endTime: observation.endTime,};// Anchor output calls before attaching any results carried by the same message.if (isOutput) thread.messages.push(emitted);@@ -113,7 +122,7 @@ export function append(}export function addContributor(- thread: Turn,+ thread: AssembledTurn,observation: TranscriptObservation,) {if (@@ -125,12 +134,14 @@ export function addContributor(thread.observations.push({id: observation.id,traceId: observation.traceId,+ type: observation.type,+ nestingLevel: observation.nestingLevel,});}}/** Split a thread into replayed history and the turn the last trace added. */-export function splitTurn(thread: Turn): Thread {+export function splitTurn(thread: AssembledTurn): Thread {const { messages, observations } = thread;// Earlier traces of a session are history; the last contributing trace is// the current turn.@@ -149,18 +160,27 @@ export function splitTurn(thread: Turn): Thread {) +1;const current = messages.slice(turnStart);+ const currentObservations = observations.filter(({ id, traceId }) =>+ current.some(+ (message) => message.observationId === id && message.traceId === traceId,+ ),+ );+ const firstGeneration = currentObservations.find(+ ({ type }) => type === "GENERATION",+ );return {conversationHistory: messages.slice(0, turnStart)- .map(({ observationId, traceId, ...message }) => message),+ .map(+ ({ observationId, traceId, startTime, endTime, ...message }) => message,+ ),currentTurn: {messages: current,- observations: observations.filter(({ id, traceId }) =>- current.some(- (message) =>- message.observationId === id && message.traceId === traceId,- ),- ),+ nestingLevel: firstGeneration?.nestingLevel ?? 0,+ observations: currentObservations.map(({ id, traceId }) => ({+ id,+ traceId,+ })),},};}diff --git a/packages/shared/src/server/transcript/tool-calls.ts b/packages/shared/src/server/transcript/tool-calls.tsindex 3a36e00f05..379e9711ef 100644--- a/packages/shared/src/server/transcript/tool-calls.ts+++ b/packages/shared/src/server/transcript/tool-calls.ts@@ -2,15 +2,16 @@ import type {NormalizedMessage,ToolCallPart,} from "../../utils/normalized-io";-import type { Turn, ThreadMessage } from "./types";+import type { ThreadMessage } from "./types";import {addContributor,+ type AssembledTurn,type KeyedMessage,type TranscriptObservation,} from "./threads";type Call = {- thread: Turn;+ thread: AssembledTurn;message: ThreadMessage;response?: ThreadMessage;fromTool?: boolean;@@ -19,14 +20,14 @@ const key = (traceId: string, id: string) => JSON.stringify([traceId, id]);export function createToolCallRegistry() {const calls = new Map<string, Call>();- const callsByThread = new WeakMap<Turn, Map<string, Call[]>>();+ const callsByThread = new WeakMap<AssembledTurn, Map<string, Call[]>>();const pending = new Map<string, { calls: Call[]; next: number }>();const responseTails = new WeakMap<ThreadMessage, ThreadMessage>();function register(observation: TranscriptObservation,part: ToolCallPart,- thread: Turn,+ thread: AssembledTurn,message: ThreadMessage,) {const id = part.toolCallId@@ -60,6 +61,8 @@ export function createToolCallRegistry() {parts,observationId: observation.id,traceId: observation.traceId,+ startTime: observation.startTime,+ endTime: observation.endTime,};if (call.response) Object.assign(call.response, response);else {@@ -80,7 +83,7 @@ export function createToolCallRegistry() {function consumePart(observation: TranscriptObservation,part: NormalizedMessage["parts"][number],- thread: Turn,+ thread: AssembledTurn,message: ThreadMessage,replayCalls: Map<string, number>,replayTotals: Map<string, number>,diff --git a/packages/shared/src/server/transcript/topics-renderer.test.ts b/packages/shared/src/server/transcript/topics-renderer.test.tsindex ad4f4298cf..6bca1aa99e 100644--- a/packages/shared/src/server/transcript/topics-renderer.test.ts+++ b/packages/shared/src/server/transcript/topics-renderer.test.ts@@ -130,12 +130,15 @@ describe("Topics transcript renderer", () => {{conversationHistory: [],currentTurn: {+ nestingLevel: 0,messages: [{role: "user",source: "input",parts: [{ type: "text", text: "Task" }],observationId: first.id,+ startTime: first.startTime,+ endTime: first.endTime,traceId: "trace",},{@@ -143,6 +146,8 @@ describe("Topics transcript renderer", () => {source: "output",parts: [{ type: "text", text: "Draft" }],observationId: first.id,+ startTime: first.startTime,+ endTime: first.endTime,traceId: "trace",},],@@ -158,12 +163,15 @@ describe("Topics transcript renderer", () => {},],currentTurn: {+ nestingLevel: 0,messages: [{role: "assistant",source: "output",parts: [{ type: "text", text: "Second" }],observationId: second.id,+ startTime: second.startTime,+ endTime: second.endTime,traceId: "trace",},],@@ -214,12 +222,15 @@ describe("Topics transcript renderer", () => {{conversationHistory: [],currentTurn: {+ nestingLevel: 0,messages: [{role: "system",source: "input",parts: [{ type: "text", text: "Summarize the data" }],observationId: generation.id,+ startTime: generation.startTime,+ endTime: generation.endTime,traceId: "trace",},{@@ -227,6 +238,8 @@ describe("Topics transcript renderer", () => {source: "output",parts: [{ type: "text", text: "Draft" }],observationId: generation.id,+ startTime: generation.startTime,+ endTime: generation.endTime,traceId: "trace",},],@@ -266,6 +279,8 @@ describe("Topics transcript renderer", () => {source: "output" as const,parts: [{ type: "text" as const, text: value }],observationId,+ startTime: new Date("2026-01-01T00:00:00Z"),+ endTime: null,traceId: "trace",});const transcript: Transcript = {@@ -273,6 +288,7 @@ describe("Topics transcript renderer", () => {{conversationHistory: [],currentTurn: {+ nestingLevel: 0,messages: [message(first.id, "First"),message(second.id, "Second"),@@ -286,6 +302,7 @@ describe("Topics transcript renderer", () => {{conversationHistory: [],currentTurn: {+ nestingLevel: 0,messages: [message(other.id, "Other")],observations: [{ id: other.id, traceId: "trace" }],},@@ -319,6 +336,8 @@ describe("Topics transcript renderer", () => {source: "input",parts: [{ type: "text", text: "Search" }],observationId: generation.id,+ startTime: generation.startTime,+ endTime: generation.endTime,traceId: "trace",},{@@ -333,6 +352,8 @@ describe("Topics transcript renderer", () => {},],observationId: generation.id,+ startTime: generation.startTime,+ endTime: generation.endTime,traceId: "trace",},{@@ -348,6 +369,8 @@ describe("Topics transcript renderer", () => {},],observationId: tool.id,+ startTime: tool.startTime,+ endTime: tool.endTime,traceId: "trace",},];@@ -356,6 +379,7 @@ describe("Topics transcript renderer", () => {{conversationHistory: [],currentTurn: {+ nestingLevel: 0,messages,observations: [{ id: generation.id, traceId: "trace" },@@ -381,6 +405,7 @@ describe("Topics transcript renderer", () => {{conversationHistory: [],currentTurn: {+ nestingLevel: 0,messages: messages.slice(0, 2),observations: [{ id: generation.id, traceId: "trace" }],},@@ -405,12 +430,15 @@ describe("Topics transcript renderer", () => {{conversationHistory: [],currentTurn: {+ nestingLevel: 0,messages: [{role: "system",source: "input",parts: [{ type: "text", text: "System instructions" }],observationId: generation.id,+ startTime: generation.startTime,+ endTime: generation.endTime,traceId: "trace",},{@@ -418,6 +446,8 @@ describe("Topics transcript renderer", () => {source: "input",parts: [{ type: "text", text: "Project data" }],observationId: generation.id,+ startTime: generation.startTime,+ endTime: generation.endTime,traceId: "trace",},{@@ -425,6 +455,8 @@ describe("Topics transcript renderer", () => {source: "input",parts: [{ type: "text", text: "Find the errors" }],observationId: generation.id,+ startTime: generation.startTime,+ endTime: generation.endTime,traceId: "trace",},{@@ -432,6 +464,8 @@ describe("Topics transcript renderer", () => {source: "output",parts: [{ type: "text", text: "Done" }],observationId: generation.id,+ startTime: generation.startTime,+ endTime: generation.endTime,traceId: "trace",},],@@ -465,12 +499,15 @@ describe("Topics transcript renderer", () => {{conversationHistory: [],currentTurn: {+ nestingLevel: 0,messages: [{role: "user",source: "input",parts: [{ type: "text", text: "Summarize the import" }],observationId: generation.id,+ startTime: generation.startTime,+ endTime: generation.endTime,traceId: "trace",},{@@ -478,6 +515,8 @@ describe("Topics transcript renderer", () => {source: "output",parts: [{ type: "text", text: "Summary" }],observationId: generation.id,+ startTime: generation.startTime,+ endTime: generation.endTime,traceId: "trace",},],@@ -511,6 +550,7 @@ describe("Topics transcript renderer", () => {{conversationHistory: [],currentTurn: {+ nestingLevel: 0,messages: [{role: "assistant",@@ -524,6 +564,8 @@ describe("Topics transcript renderer", () => {},],observationId: generation.id,+ startTime: generation.startTime,+ endTime: generation.endTime,traceId: "trace",},{@@ -538,6 +580,8 @@ describe("Topics transcript renderer", () => {},],observationId: tool.id,+ startTime: tool.startTime,+ endTime: tool.endTime,traceId: "trace",},],@@ -584,12 +628,15 @@ describe("Topics transcript renderer", () => {},],currentTurn: {+ nestingLevel: 0,messages: [{role: "assistant",source: "output",parts: [call],observationId: generation.id,+ startTime: generation.startTime,+ endTime: generation.endTime,traceId: "trace",},{@@ -604,6 +651,8 @@ describe("Topics transcript renderer", () => {},],observationId: tool.id,+ startTime: tool.startTime,+ endTime: tool.endTime,traceId: "trace",},],diff --git a/packages/shared/src/server/transcript/transcript.ts b/packages/shared/src/server/transcript/transcript.tsindex 55afea5b76..6d1bea8f51 100644--- a/packages/shared/src/server/transcript/transcript.ts+++ b/packages/shared/src/server/transcript/transcript.ts@@ -1,5 +1,5 @@import { partition } from "lodash";-import type { Observation } from "../../domain";+import type { OrderedObservation } from "./ordering";import { normalizeIO } from "../normalized-io";import type { Transcript } from "./types";import {@@ -8,19 +8,18 @@ import {messageKey,splitTurn,type ThreadState,- type TranscriptObservation,} from "./threads";import { createToolCallRegistry } from "./tool-calls";/** Check if an observation is relevant for the transcript. */const isRelevantObservation = (- observation: Observation,-): observation is TranscriptObservation =>+ observation: OrderedObservation,+): observation is OrderedObservation & { traceId: string } =>(observation.type === "GENERATION" || observation.type === "TOOL") &&observation.traceId !== null;/** Normalize original I/O without interpreting provider-specific envelopes. */-function normalize(observation: TranscriptObservation) {+function normalize(observation: OrderedObservation) {const isTool = observation.type === "TOOL";const { messages } = normalizeIO({kind: "io",@@ -45,7 +44,7 @@ function normalize(observation: TranscriptObservation) {* keys) from remaining assembly work, excluding caller-owned observation ordering.*/export function assembleTranscript(- orderedObservations: Observation[],+ orderedObservations: OrderedObservation[],onTimings?: (timings: {normalizationMs: number;matchingMs: number;@@ -82,7 +81,9 @@ export function assembleTranscript(}const transcript = states.length- ? { threads: states.map(({ thread }) => splitTurn(thread)) }+ ? {+ threads: states.map(({ thread }) => splitTurn(thread)),+ }: null;onTimings?.({normalizationMs,diff --git a/packages/shared/src/server/transcript/types.ts b/packages/shared/src/server/transcript/types.tsindex 0859148689..e7f57be6f3 100644--- a/packages/shared/src/server/transcript/types.ts+++ b/packages/shared/src/server/transcript/types.ts@@ -1,15 +1,37 @@+import type { Observation } from "../../domain";import type { NormalizedMessage } from "../../utils/normalized-io/types";+/** Observation fields consumed by ordering and transcript assembly. */+export type TranscriptObservation = Pick<+ Observation,+ | "id"+ | "traceId"+ | "parentObservationId"+ | "type"+ | "name"+ | "startTime"+ | "endTime"+ | "input"+ | "output"+ | "metadata"+>;+export type ThreadMessage = NormalizedMessage & {/** Observation that first emitted this message. */observationId: string;/** Trace the emitting observation belongs to. Helpful when the transcript* spans several traces, for example one session. */traceId: string;+ /** Start time of the source observation, not the individual message. */+ startTime: Date;+ /** End time of the source observation; null while unavailable. */+ endTime: Date | null;};/** Messages of one turn with the observations that emitted them. */export type Turn = {+ /** Tree depth of the first contributing generation; fetched roots are level 0. */+ nestingLevel: number;messages: ThreadMessage[];/** Observations that contributed to this turn, in contribution order. */observations: { id: string; traceId: string }[];