Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

feat(transcript): expose current turn nesting level (#18011)

marliessophied50d19c5f80c
diff --git a/packages/shared/AGENTS.md b/packages/shared/AGENTS.md
index 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 to
submit 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.md
index 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 message
traceId: 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:
```bash
pnpm --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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 }[];