@genesislcap/ai-assistant 14.497.0 → 14.499.0

package/src/components/chat-driver/chat-driver.test.ts

@@ -1462,6 +1462,221 @@ interactionPresentation('presentation is absent when the option is omitted', asy
 
 interactionPresentation.run();
 
+// ---------------------------------------------------------------------------
+// external diagnostics harvest (GENC-1461) — a widget may return an out-of-band
+// engine's collated debug log on `InteractionResult.diagnostics` (e.g. a
+// server-side ChatDriver's). Those entries carry the SOURCE engine's own 0-based
+// index space, which would collide with this host's forward-capture cursors and
+// be dropped: the persister dedups `turn` entries by `turnIndex` and `event`
+// entries by an `index` high-water mark. So the driver decomposes the harvest by
+// kind — events fold into the session's meta-event registry (re-indexed onto the
+// host's monotonic counter), turns are re-keyed into a per-batch namespace, and
+// messages pass through unchanged (the persister already keys those by content).
+// ---------------------------------------------------------------------------
+
+const externalDiagnostics = createLogicSuite('ChatDriver external diagnostics harvest');
+
+/** A `diagnostics` payload as a headless engine would collate it — one of each kind,
+ * all carrying that engine's own 0-based indices (`turnIndex: '0'`, event `index: 0`). */
+const harvestPayload = (marker: string) => [
+  { kind: 'message', timestamp: '2026-07-23T10:00:00.000Z', role: 'assistant', content: marker },
+  { kind: 'turn', timestamp: '2026-07-23T10:00:01.000Z', turnIndex: '0', systemPrompt: 'sys' },
+  {
+    kind: 'event',
+    index: 0,
+    timestamp: '2026-07-23T10:00:02.000Z',
+    type: 'turn.error',
+    importance: 'high',
+    detail: { marker },
+  },
+];
+
+externalDiagnostics(
+  'routes harvested events to the meta-event registry (re-indexed) and keeps turns + messages',
+  async () => {
+    clearMetaEventRegistry();
+    const sessionKey = 'external-diag-harvest';
+    const driver = makeDriver(agent({ name: 'a' }), scriptedProvider([]), sessionKey);
+
+    // Requesting the interaction records a host `interaction.requested` meta-event, so the
+    // registry's index counter is already advanced when the harvested event is merged — exactly
+    // the condition that made the foreign 0-based `index` lose the persister's high-water race.
+    const pending = driver.requestInteraction('w', {});
+    const { interactionId } = driver.getHistory().at(-1)!.interaction!;
+    const requestedIndex = getMetaEvents(sessionKey).find(
+      (e) => e.type === 'interaction.requested',
+    )!.index;
+
+    driver.resolveInteraction(interactionId, {
+      status: 'approved',
+      diagnostics: harvestPayload('m1'),
+    });
+    await pending;
+
+    // The event left the external buffer and landed in the registry, re-indexed ABOVE the host's
+    // prior event (so it beats the persister's `index <= lastEventIndex` high-water), timestamp kept.
+    const external = driver.getExternalDiagnostics();
+    assert.is(
+      external.filter((e) => e.kind === 'event').length,
+      0,
+      'events do not stay in the buffer',
+    );
+    const merged = getMetaEvents(sessionKey).find((e) => e.detail?.marker === 'm1');
+    assert.ok(merged, 'the harvested event is folded into the session registry');
+    assert.ok(
+      merged!.index > requestedIndex,
+      're-indexed onto the host counter, above prior events',
+    );
+    assert.is(
+      merged!.timestamp,
+      '2026-07-23T10:00:02.000Z',
+      'original timestamp preserved for ordering',
+    );
+
+    // The turn is kept in the buffer but re-keyed out of the host's bare-integer turn-key space,
+    // and the message passes through untouched.
+    const turn = external.find((e) => e.kind === 'turn');
+    assert.ok(turn, 'the harvested turn is kept in the external buffer');
+    assert.is(turn!.turnIndex, 'server-generation.1:0', 'turnIndex namespaced per batch');
+    const message = external.find((e) => e.kind === 'message');
+    assert.ok(message, 'the harvested message is kept in the external buffer');
+    assert.is(message!.content, 'm1', 'message passes through unchanged');
+
+    // A single manifest event records the fold's provenance — the fragile boundary this feature
+    // guards is now observable: a dropped generation shows up as a zero/absent manifest.
+    const manifest = getMetaEvents(sessionKey).find(
+      (e) => e.type === 'external-diagnostics.folded',
+    );
+    assert.ok(manifest, 'a manifest meta-event is recorded for the fold');
+    assert.is(manifest!.detail?.interactionId, interactionId);
+    assert.equal(manifest!.detail?.counts, { turn: 1, event: 1, message: 1 });
+  },
+);
+
+externalDiagnostics(
+  'namespaces each batch so distinct server generations cannot collide on turnIndex',
+  async () => {
+    clearMetaEventRegistry();
+    const driver = makeDriver(agent({ name: 'a' }), scriptedProvider([]), 'external-diag-batches');
+
+    const first = driver.requestInteraction('w', {});
+    const firstId = driver.getHistory().at(-1)!.interaction!.interactionId;
+    driver.resolveInteraction(firstId, { status: 'approved', diagnostics: harvestPayload('a') });
+    await first;
+
+    const second = driver.requestInteraction('w', {});
+    const secondId = driver.getHistory().at(-1)!.interaction!.interactionId;
+    driver.resolveInteraction(secondId, { status: 'approved', diagnostics: harvestPayload('b') });
+    await second;
+
+    // Both harvests carried `turnIndex: '0'`; the per-batch namespace keeps them distinct, so the
+    // persister's `emittedTurnKeys` can't fold the second generation's turn into the first.
+    const turnKeys = driver
+      .getExternalDiagnostics()
+      .filter((e) => e.kind === 'turn')
+      .map((e) => e.turnIndex);
+    assert.equal(turnKeys, ['server-generation.1:0', 'server-generation.2:0']);
+  },
+);
+
+externalDiagnostics(
+  'keys turns by local position so several server runs in one harvest do not collide',
+  async () => {
+    clearMetaEventRegistry();
+    const driver = makeDriver(agent({ name: 'a' }), scriptedProvider([]), 'external-diag-multirun');
+
+    // One interaction carrying two independent server runs (e.g. a consolidator's consolidator-code
+    // run and its table-code run) — each numbers its own turns from 0, so the harvest has two
+    // `turnIndex: '0'` entries. Keying by source index would collapse them; local position keeps
+    // both, so the persister's per-turnIndex dedup drops neither.
+    const pending = driver.requestInteraction('w', {});
+    const { interactionId } = driver.getHistory().at(-1)!.interaction!;
+    driver.resolveInteraction(interactionId, {
+      status: 'approved',
+      diagnostics: [
+        {
+          kind: 'turn',
+          timestamp: '2026-07-23T10:00:00.000Z',
+          turnIndex: '0',
+          systemPrompt: 'run1',
+        },
+        {
+          kind: 'turn',
+          timestamp: '2026-07-23T10:00:01.000Z',
+          turnIndex: '1',
+          systemPrompt: 'run1',
+        },
+        {
+          kind: 'turn',
+          timestamp: '2026-07-23T10:00:02.000Z',
+          turnIndex: '0',
+          systemPrompt: 'run2',
+        },
+      ],
+    });
+    await pending;
+
+    const turnKeys = driver
+      .getExternalDiagnostics()
+      .filter((e) => e.kind === 'turn')
+      .map((e) => e.turnIndex);
+    assert.equal(turnKeys, [
+      'server-generation.1:0',
+      'server-generation.1:1',
+      'server-generation.1:2',
+    ]);
+    // All distinct — no key repeats despite the repeated source `turnIndex: '0'`.
+    assert.is(new Set(turnKeys).size, 3, 'every harvested turn gets a distinct key');
+  },
+);
+
+externalDiagnostics(
+  'tolerates malformed entries and does not fold or miscount non-standard kinds',
+  async () => {
+    clearMetaEventRegistry();
+    const sessionKey = 'external-diag-malformed';
+    const driver = makeDriver(agent({ name: 'a' }), scriptedProvider([]), sessionKey);
+
+    const pending = driver.requestInteraction('w', {});
+    const { interactionId } = driver.getHistory().at(-1)!.interaction!;
+    // The harvest is untrusted `unknown[]`: primitives/null and an object without a string `kind`
+    // must be skipped (not throw), and a `meta-snapshot` (host-owned, never emitted by a sibling)
+    // must be dropped rather than folded or miscounted as a message.
+    driver.resolveInteraction(interactionId, {
+      status: 'approved',
+      diagnostics: [
+        null,
+        'oops',
+        42,
+        { timestamp: '2026-07-23T10:00:00.000Z' }, // no kind
+        {
+          kind: 'message',
+          timestamp: '2026-07-23T10:00:01.000Z',
+          role: 'assistant',
+          content: 'real',
+        },
+        { kind: 'meta-snapshot', timestamp: '2026-07-23T10:00:02.000Z', meta: { host: 'foreign' } },
+      ],
+    });
+    await pending;
+
+    // Only the one real message survives the buffer; the meta-snapshot is not folded.
+    const external = driver.getExternalDiagnostics();
+    assert.equal(
+      external.map((e) => e.kind),
+      ['message'],
+    );
+    assert.is(external[0].content, 'real');
+    // Manifest counts only the three real kinds — the meta-snapshot is not miscounted as a message.
+    const manifest = getMetaEvents(sessionKey).find(
+      (e) => e.type === 'external-diagnostics.folded',
+    );
+    assert.equal(manifest!.detail?.counts, { turn: 0, event: 0, message: 1 });
+  },
+);
+
+externalDiagnostics.run();
+
 // ---------------------------------------------------------------------------
 // interaction context lifecycle (GENC-1390) — the driver creates a live
 // InteractionContext on requestInteraction and disposes+drops it on resolve, so

package/src/components/chat-driver/chat-driver.ts

@@ -44,6 +44,7 @@ import { resolveChatProvider } from '../../config/validate-providers';
 import {
   clearSession,
   getMetaEvents,
+  type MetaEvent,
   mergeMetaEvents,
   type MetaEventType,
   recordMetaEvent,
@@ -54,6 +55,7 @@ import {
   createInteractionContext,
   type InteractionContextHandle,
 } from '../../state/interaction-context';
+import type { DiagnosticEntry } from '../../state/persistence/diagnostics';
 import type { InteractionContext } from '../../types/interaction-context';
 import { applyCondensation, type RegisteredCondensePolicy } from '../../utils/condense-history';
 import {
@@ -435,6 +437,23 @@ export class ChatDriver extends EventTarget implements AiDriver {
    * arrive. See {@link TurnSnapshot} for the captured shape.
    */
   private turnSnapshots: TurnSnapshot[] = [];
+  /**
+   * `turn` + `message` diagnostic-log entries harvested from an out-of-band source (a resolved
+   * interaction whose widget returned `InteractionResult.diagnostics` — e.g. a server-side
+   * ChatDriver's debug log). `event` entries are NOT kept here — they're folded into the session's
+   * meta-event registry via `mergeMetaEvents` (see `resolveInteraction`) so they inherit fresh host
+   * indices, and reach the log through `getMetaEvents`. Append-only; the host folds these into its
+   * debug log alongside this driver's own timeline. Not cleared here — it lives with the driver
+   * instance, like `turnSnapshots`, so a new chat (fresh driver) starts empty while a compaction
+   * (same instance) keeps it. (GENC-1461.)
+   */
+  private readonly externalDiagnostics: DiagnosticEntry[] = [];
+  /**
+   * Monotonic count of external-diagnostics batches harvested this driver-lifetime. Namespaces each
+   * batch's re-keyed `turn` entries so distinct server generations in one chat session can't collide
+   * on `turnIndex` in the forward-capture persister (which dedups turns by that key). (GENC-1461.)
+   */
+  private externalDiagnosticsBatches = 0;
   /** Monotonic counter that survives agent swaps — useful for cross-referencing with history. */
   private globalTurnIndex = 0;
   /** Captured from `applyAgent` so we don't store the whole `AgentConfig`. */
@@ -971,6 +990,18 @@ export class ChatDriver extends EventTarget implements AiDriver {
     return this.turnSnapshots;
   }
 
+  /**
+   * The `turn` + `message` diagnostic-log entries harvested from resolved interactions'
+   * `InteractionResult.diagnostics` (e.g. a server-side ChatDriver's collated debug log). The host
+   * concatenates these into its own debug log so `downloadDebugLog`/the persisted diagnostics stream
+   * include external-engine logs; `event` entries are excluded here because they're merged into the
+   * session's meta-event registry instead (see `resolveInteraction`) and reach the log via
+   * `getMetaEvents`. Opaque, chronologically sorted by the host at assemble time. (GENC-1461.)
+   */
+  getExternalDiagnostics(): ReadonlyArray<DiagnosticEntry> {
+    return this.externalDiagnostics;
+  }
+
   /**
    * Merge a sub-agent's turn snapshots into this driver's buffer so they surface
    * as `kind:'turn'` entries in the exported debug log. The child runs as a
@@ -1391,6 +1422,84 @@ export class ChatDriver extends EventTarget implements AiDriver {
       // Clear the timeout so a user resolution doesn't later fire a stale
       // timeout (and a timeout firing here clears its own already-fired handle).
       if (interaction.timeoutHandle) clearTimeout(interaction.timeoutHandle);
+      // Harvest any out-of-band diagnostic entries the widget collated (e.g. from a server-side
+      // ChatDriver) so the host's debug log + persisted diagnostics include them. Independent of the
+      // message `idx` below — they describe the widget's own work, not this message.
+      //
+      // The harvested entries carry the SOURCE engine's own index space (0-based turns/events), which
+      // would collide with this host's cursors in the forward-capture persister — turns dedup by
+      // `turnIndex`, events by an `index` high-water mark — so foreign entries get silently dropped
+      // from the persisted stream. Route each kind through the host's own collision-safe machinery,
+      // mirroring how a sub-agent's log is folded in (see `invokeSubAgent`):
+      //   • `event`   → `mergeMetaEvents`, which re-indexes them onto this session's monotonic event
+      //                 counter (clearing the high-water) while preserving their timestamps; they then
+      //                 reach the log via `getMetaEvents` in `buildTimelineEntries`, not this buffer.
+      //   • `turn`    → re-key `turnIndex` to the turn's local position within a per-batch namespace,
+      //                 so turns stay unique even when one interaction folds in several independent
+      //                 server runs that each number their own turns from 0 (a consolidator carries a
+      //                 consolidator-code run AND a table-code run), and never collide with the host's
+      //                 own bare-integer turn keys.
+      //   • `message` → kept as-is; the persister already keys messages by content, so they survive.
+      // TODO(GENC-1461, option 2 / streaming): expose an imperative `appendDiagnostics(entries)` on
+      // the handler context (see buildHandlerContext) that runs this same decomposition as SSE ticks
+      // arrive, so a streaming widget can surface its external engine's log live rather than only at
+      // resolve time. Batch-at-resolve (here) is the current, non-streaming path.
+      const harvestedDiagnostics = (result as { diagnostics?: readonly unknown[] } | undefined)
+        ?.diagnostics;
+      if (Array.isArray(harvestedDiagnostics) && harvestedDiagnostics.length) {
+        const batch = (this.externalDiagnosticsBatches += 1);
+        const externalEvents: MetaEvent[] = [];
+        let turnCount = 0;
+        let messageCount = 0;
+        for (const raw of harvestedDiagnostics) {
+          // The harvest is external and typed `unknown[]`, so an element could be a primitive, null,
+          // or an object without a string `kind`. Guard before reading `.kind` so a malformed entry
+          // can't throw here (and gets skipped rather than derailing the whole fold).
+          if (
+            !raw ||
+            typeof raw !== 'object' ||
+            typeof (raw as { kind?: unknown }).kind !== 'string'
+          ) {
+            continue;
+          }
+          const entry = raw as DiagnosticEntry;
+          if (entry.kind === 'event') {
+            const { kind: _kind, ...event } = entry;
+            externalEvents.push(event as unknown as MetaEvent);
+          } else if (entry.kind === 'turn') {
+            // Local position within THIS harvest, not the source engine's own `turnIndex`: one
+            // interaction can carry several independent server runs (a consolidator folds in its
+            // consolidator-code run and its table-code run), each numbering its turns from 0, so
+            // keying by the source index would collide them. The local position keeps every turn key
+            // distinct within the batch, so the persister's per-`turnIndex` dedup keeps them all.
+            this.externalDiagnostics.push({
+              ...entry,
+              turnIndex: `server-generation.${batch}:${turnCount}`,
+            });
+            turnCount += 1;
+          } else if (entry.kind === 'message') {
+            messageCount += 1;
+            this.externalDiagnostics.push(entry);
+          }
+          // Any other kind is intentionally dropped, not folded. A sibling's `buildTimelineEntries`
+          // only ever emits message/turn/event; `meta-snapshot` is host/DOM-owned (latest-wins on
+          // reassembly, plus its own persister dedup), so folding a foreign one would pollute this
+          // host's timeline and meta cursor. Restricting to the three real kinds also keeps the
+          // manifest counts accurate (nothing miscounted as a `message`).
+        }
+        if (externalEvents.length) mergeMetaEvents(this.sessionKey, externalEvents);
+        // Manifest: one provenance marker for the fold itself — records that an out-of-band engine's
+        // log crossed into this session and how much of each kind, so a regression that silently
+        // drops a generation's diagnostics (e.g. a new path that forgets to thread them across the
+        // boundary) surfaces as a zero/absent manifest rather than only by diffing a download. Also
+        // the natural seed for the streaming PR's open/close bracket. Stamped at resolve, so it
+        // closes the block on the sorted timeline. (GENC-1461.)
+        recordMetaEvent(this.sessionKey, 'external-diagnostics.folded', {
+          interactionId,
+          batch,
+          counts: { turn: turnCount, event: externalEvents.length, message: messageCount },
+        });
+      }
       const idx = this.history.findIndex((m) => m.interaction?.interactionId === interactionId);
       if (idx !== -1) {
         // Fold any widget-reported external (non-LLM) cost onto the message, so

package/src/components/orchestrating-driver/orchestrating-driver.ts

@@ -15,6 +15,7 @@ import type {
 } from '../../config/config';
 import { validateStaticAgentProviders } from '../../config/validate-providers';
 import { recordMetaEvent } from '../../state/debug-event-log';
+import type { DiagnosticEntry } from '../../state/persistence/diagnostics';
 import type { InteractionContext } from '../../types/interaction-context';
 import { transformHistoryForAgent } from '../../utils/history-transform';
 import { logger } from '../../utils/logger';
@@ -269,6 +270,11 @@ export class OrchestratingDriver extends EventTarget implements AiDriver {
     return this.chatDriver.getTurnSnapshots();
   }
 
+  /** Delegates to the inner {@link ChatDriver} — interactions resolve there, so it holds the buffer. */
+  getExternalDiagnostics(): ReadonlyArray<DiagnosticEntry> {
+    return this.chatDriver.getExternalDiagnostics();
+  }
+
   async getSuggestions(
     history: ChatMessage[],
     prompt: string,

package/src/main/main.ts

@@ -74,6 +74,7 @@ import {
   getDriverAgentsKey,
   deleteDriver,
 } from '../state/driver-registry';
+import { buildTimelineEntries } from '../state/persistence/build-timeline-entries';
 import { assembleDebugLog } from '../state/persistence/diagnostics';
 import type { DebugLog, DiagnosticEntry } from '../state/persistence/diagnostics';
 import {
@@ -122,7 +123,6 @@ import {
   deriveCostSessionTitleFromMessages,
   resolveCostSessionTitle,
 } from '../utils/derive-cost-session-title';
-import { flattenSubAgentMessages } from '../utils/flatten-sub-agent-messages';
 import { logger } from '../utils/logger';
 import { filterVisibleMessages, trailingInteractionRow } from '../utils/message-partition';
 import {
@@ -2698,36 +2698,15 @@ export class FoundationAiAssistant extends GenesisElement {
         : undefined;
     const stateKey = this.getStateKey();
 
-    // Collapse repeated system prompts across consecutive turns. A stateful
-    // agent's prompt changes between turns, but a stable agent repeats the same
-    // (often multi-KB) prompt every turn — so replace a turn's `systemPrompt`
-    // with a sentinel when it's byte-identical to the previous turn's. The
-    // prompt is still shown in full whenever it changes, so prompt evolution
-    // stays visible.
-    let lastFullPrompt: string | undefined;
-    let lastFullIndex = '';
-    const turns = (this.driver?.getTurnSnapshots?.() ?? []).map((t) => {
-      let { systemPrompt } = t;
-      if (systemPrompt != null && systemPrompt === lastFullPrompt) {
-        systemPrompt = `<repeated — identical to turn ${lastFullIndex}>`;
-      } else if (systemPrompt != null) {
-        lastFullPrompt = systemPrompt;
-        lastFullIndex = t.turnIndex;
-      }
-      return { kind: 'turn' as const, ...t, systemPrompt };
+    // The message/turn/event timeline entries — built by the shared, pure `buildTimelineEntries`
+    // (the same helper a headless consumer uses to harvest its own log), from the driver's pull
+    // surfaces. Prefer the driver's raw history (carries sub-agent traces) over the redux projection.
+    const timelineEntries = buildTimelineEntries({
+      turnSnapshots: this.driver?.getTurnSnapshots?.() ?? [],
+      messages: this.driver?.getRawHistory?.() ?? this.messages,
+      metaEvents: stateKey ? getMetaEvents(stateKey) : [],
     });
 
-    // Sub-agent conversations are stored nested on the parent tool call's
-    // `subAgentTrace`; `flattenSubAgentMessages` hoists them to top-level
-    // `kind: 'message'` entries (breadcrumbed + correlated, the nested copy moved
-    // out — not duplicated) so the timeline reads as one chronological sequence.
-    const messages = this.driver?.getRawHistory?.() ?? this.messages;
-    const messageEntries = flattenSubAgentMessages(messages);
-    const eventEntries = (stateKey ? getMetaEvents(stateKey) : []).map((e) => ({
-      kind: 'event' as const,
-      ...e,
-    }));
-
     // The export-time `meta` block, carried on a `meta-snapshot` entry so it lives
     // in the same forward stream (the latest one wins on reassembly, and the
     // accumulated history exposes config/state evolution across the lifetime).
@@ -2797,7 +2776,15 @@ export class FoundationAiAssistant extends GenesisElement {
       activeFoldStack: m.activeFoldStack,
     });
 
-    return [...messageEntries, ...turns, ...eventEntries, metaSnapshot] as DiagnosticEntry[];
+    // Fold in any external diagnostics harvested from an out-of-band driver (e.g. a server-side
+    // ChatDriver whose collated log an interaction widget returned on its result). They ride the
+    // same download + persisted-diagnostics path; `assembleDebugLog` sorts the whole timeline by
+    // timestamp so they interleave chronologically. (GENC-1461 unified diagnostics.)
+    return [
+      ...timelineEntries,
+      ...(this.driver?.getExternalDiagnostics?.() ?? []),
+      metaSnapshot,
+    ] as DiagnosticEntry[];
   }
 
   async downloadDebugLog(): Promise<void> {

package/src/state/debug-event-log.ts

@@ -59,6 +59,8 @@ export type MetaEventType =
   // Blocking interactions
   | 'interaction.requested'
   | 'interaction.resolved'
+  // External / unified diagnostics (GENC-1461) — an out-of-band engine's log folded into this session
+  | 'external-diagnostics.folded'
   // Context / cost
   | 'context.updated'
   | 'context.threshold-crossed'
@@ -125,6 +127,7 @@ export const META_EVENT_IMPORTANCE: Record<MetaEventType, MetaEventImportance> =
   'provider.selected': 'normal',
   'interaction.requested': 'normal',
   'interaction.resolved': 'normal',
+  'external-diagnostics.folded': 'normal',
   'session.cleared': 'normal',
   'session.switched': 'low',
   'session.switch-deferred': 'low',

package/src/state/persistence/build-timeline-entries.ts

@@ -0,0 +1,66 @@
+/**
+ * Shared, pure builder for the debug-log timeline entries (`message` / `turn` / `event`) — the
+ * common core of the host element's `buildDiagnosticEntries` and any HEADLESS consumer that drives
+ * a `ChatDriver` of its own (e.g. `ai-service` running the engine server-side) and needs to harvest
+ * that engine's debug log for the client to fold into its own download / persisted stream
+ * (GENC-1461 unified diagnostics). DOM-clean and dependency-light so it works in bare Node.
+ *
+ * It deliberately excludes the `meta-snapshot` entry: that block is host/DOM-specific (it reads
+ * `window.location.host`, the element's agent list, live context/cost), and a merged log keeps only
+ * the newest snapshot anyway — a headless source's agent/prompt/tools are already captured in its
+ * `turn` entries.
+ *
+ * @packageDocumentation
+ */
+
+import type { ChatMessage } from '@genesislcap/foundation-ai';
+import { flattenSubAgentMessages } from '../../utils/flatten-sub-agent-messages';
+import type { MetaEvent } from '../debug-event-log';
+import type { DiagnosticEntry } from './diagnostics';
+
+/**
+ * The minimal shape this builder reads off a turn snapshot. The driver's full `TurnSnapshot` is a
+ * structural superset, so it assigns to this without the builder depending on the component layer.
+ */
+export interface TurnSnapshotLike {
+  turnIndex: string;
+  systemPrompt?: string;
+}
+
+/**
+ * Build the `message` / `turn` / `event` timeline entries from a driver's pull surfaces
+ * (`getRawHistory()` / `getTurnSnapshots()` / `getMetaEvents(sessionKey)`). Order within the array
+ * is message → turn → event; the caller (`assembleDebugLog`) sorts the whole timeline by timestamp,
+ * so this ordering only sets the co-timestamp tie-break. Pure.
+ */
+export function buildTimelineEntries(input: {
+  turnSnapshots: readonly TurnSnapshotLike[];
+  messages: readonly ChatMessage[];
+  metaEvents: readonly MetaEvent[];
+}): DiagnosticEntry[] {
+  const { turnSnapshots, messages, metaEvents } = input;
+
+  // Collapse a turn's systemPrompt when byte-identical to the previous turn's — a stable agent
+  // repeats the same (often multi-KB) prompt every turn, while a stateful agent's changes. The
+  // prompt is shown in full whenever it changes, so prompt evolution stays visible.
+  let lastFullPrompt: string | undefined;
+  let lastFullIndex = '';
+  const turns = turnSnapshots.map((t) => {
+    let { systemPrompt } = t;
+    if (systemPrompt != null && systemPrompt === lastFullPrompt) {
+      systemPrompt = `<repeated — identical to turn ${lastFullIndex}>`;
+    } else if (systemPrompt != null) {
+      lastFullPrompt = systemPrompt;
+      lastFullIndex = t.turnIndex;
+    }
+    return { kind: 'turn' as const, ...t, systemPrompt };
+  });
+
+  // Sub-agent conversations are stored nested on the parent tool call's `subAgentTrace`;
+  // `flattenSubAgentMessages` hoists them to top-level `kind: 'message'` entries (breadcrumbed +
+  // correlated, the nested copy moved out — not duplicated) so the timeline reads chronologically.
+  const messageEntries = flattenSubAgentMessages(messages);
+  const eventEntries = metaEvents.map((e) => ({ kind: 'event' as const, ...e }));
+
+  return [...messageEntries, ...turns, ...eventEntries] as DiagnosticEntry[];
+}