@flamingo-stack/openframe-frontend-core 0.0.489 → 0.0.490-1506.3944.1

package/src/components/chat/utils/__tests__/process-historical-messages-golden.test.ts

@@ -0,0 +1,317 @@
+/**
+ * Phase-0 GOLDEN CHARACTERIZATION TESTS — `processHistoricalMessages`.
+ *
+ * Pins the CURRENT GraphQL-history → ProcessedMessage[] transformation
+ * before the stream-reader unification. A recorded corpus of messageData
+ * rows is processed and the FULL output array is snapshotted.
+ *
+ * NOTE: `process-historical-messages-approvals.test.ts` already guards
+ * displayApprovalTypes semantics — this file deliberately does not
+ * duplicate it and instead records the full-output shape.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { processHistoricalMessages, extractErrorMessages, processHistoricalMessagesWithErrors } from '../process-historical-messages'
+import type { HistoricalMessage } from '../../types'
+
+// Deterministic Date.now for the `pending-approvals-${Date.now()}` synthetic
+// message id + its `new Date()` timestamp.
+const FIXED_NOW = new Date('2026-07-20T10:00:00.000Z')
+
+beforeEach(() => {
+  vi.useFakeTimers()
+  vi.setSystemTime(FIXED_NOW)
+})
+
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+/** Recorded corpus — one realistic dialog covering every row shape. */
+const CORPUS: HistoricalMessage[] = [
+  // 1. User message with contextItems (CLIENT owner).
+  {
+    id: 'u1',
+    chatType: 'CLIENT_CHAT',
+    createdAt: '2026-07-19T09:00:00Z',
+    owner: { type: 'CLIENT', userId: 'user-42' },
+    lastChunkStreamSeq: 10,
+    messageData: [
+      {
+        type: 'TEXT',
+        text: 'diagnose this device please',
+        // wire shape: [{ type, id }] — label falls back to id
+        contextItems: [
+          { type: 'device', id: 'dev-1' },
+          { type: 'bad' }, // missing id → filtered
+        ],
+      } as any,
+    ],
+  },
+  // 2. Assistant: thinking + text (grouped into one bubble).
+  {
+    id: 'a1',
+    chatType: 'CLIENT_CHAT',
+    createdAt: '2026-07-19T09:00:05Z',
+    owner: { type: 'ASSISTANT', model: 'claude-sonnet-x' },
+    lastChunkStreamSeq: 20,
+    messageData: [
+      { type: 'THINKING', text: 'Checking device state… ' },
+      { type: 'THINKING', text: 'looks like disk pressure.' },
+      { type: 'TEXT', text: 'The device is low on disk. ' },
+    ],
+  },
+  // 3. Assistant continued: EXECUTING + EXECUTED tool pair merges in place.
+  {
+    id: 'a2',
+    chatType: 'CLIENT_CHAT',
+    createdAt: '2026-07-19T09:00:10Z',
+    owner: { type: 'ASSISTANT' },
+    lastChunkStreamSeq: 15, // lower than a1's — MAX (20) must win on the flushed turn
+    messageData: [
+      {
+        type: 'EXECUTING_TOOL',
+        integratedToolType: 'TACTICAL_RMM',
+        toolFunction: 'run_script',
+        title: 'Run cleanup script',
+        parameters: { script: 'cleanup.sh' },
+        toolExecutionRequestId: 'exec-1',
+      },
+      {
+        type: 'EXECUTED_TOOL',
+        integratedToolType: 'TACTICAL_RMM',
+        toolFunction: 'run_script',
+        parameters: { script: 'cleanup.sh' },
+        result: 'Freed 2.3 GB',
+        success: true,
+        toolExecutionRequestId: 'exec-1',
+      },
+      { type: 'TEXT', text: 'Cleanup done.' },
+    ],
+  },
+  // 4. ADMIN-owned user message (owner-type author resolution: display name from user).
+  {
+    id: 'u2',
+    chatType: 'CLIENT_CHAT',
+    createdAt: '2026-07-19T09:01:00Z',
+    owner: {
+      type: 'ADMIN',
+      user: {
+        id: 'admin-7',
+        firstName: 'Jane',
+        lastName: 'Admin',
+        image: { imageUrl: '/avatars/jane.png' },
+      },
+    },
+    messageData: [{ type: 'TEXT', text: 'please restart the broker' }],
+  },
+  // 5. Assistant: single approval request + result (resolved in-history).
+  {
+    id: 'a3',
+    chatType: 'CLIENT_CHAT',
+    createdAt: '2026-07-19T09:01:05Z',
+    owner: { type: 'ASSISTANT' },
+    lastChunkStreamSeq: 30,
+    messageData: [
+      { type: 'TEXT', text: 'I need approval to restart it.' },
+      {
+        type: 'APPROVAL_REQUEST',
+        approvalRequestId: 'req-1',
+        approvalType: 'CLIENT',
+        command: 'systemctl restart nats',
+        explanation: 'Restart the message broker',
+      },
+      {
+        type: 'APPROVAL_RESULT',
+        approvalRequestId: 'req-1',
+        approved: true,
+        approvalType: 'CLIENT',
+        resolvedByName: 'Jane Admin',
+      },
+    ],
+  },
+  // 6. Assistant: batch approval + per-tool executions merged into the batch.
+  {
+    id: 'a4',
+    chatType: 'CLIENT_CHAT',
+    createdAt: '2026-07-19T09:02:00Z',
+    owner: { type: 'ASSISTANT' },
+    messageData: [
+      {
+        type: 'APPROVAL_REQUEST',
+        approvalRequestId: 'batch-1',
+        approvalType: 'CLIENT',
+        toolCalls: [
+          {
+            toolExecutionRequestId: 'exec-a',
+            toolName: 'create_ticket',
+            toolTitle: 'Create ticket',
+            requiresApproval: true,
+            approvalType: 'CLIENT',
+            toolCallArguments: { subject: 'Printer down' },
+          },
+          {
+            toolExecutionRequestId: 'exec-b',
+            toolName: 'read_kb',
+            requiresApproval: false,
+          },
+        ],
+      },
+      {
+        type: 'APPROVAL_RESULT',
+        approvalRequestId: 'batch-1',
+        approved: true,
+        resolvedByName: 'Alice Client',
+      },
+      {
+        type: 'EXECUTING_TOOL',
+        integratedToolType: 'PSA',
+        toolFunction: 'create_ticket',
+        toolExecutionRequestId: 'exec-a',
+      },
+      {
+        type: 'EXECUTED_TOOL',
+        integratedToolType: 'PSA',
+        toolFunction: 'create_ticket',
+        result: 'Ticket #77 created',
+        success: true,
+        toolExecutionRequestId: 'exec-a',
+      },
+    ],
+  },
+  // 7. Standalone SYSTEM message row — flushes the assistant turn and
+  //    renders as a system-authored row.
+  {
+    id: 's1',
+    chatType: 'CLIENT_CHAT',
+    createdAt: '2026-07-19T09:03:00Z',
+    owner: { type: 'ASSISTANT' },
+    lastChunkStreamSeq: 40,
+    messageData: [{ type: 'SYSTEM', text: 'Technician joined the chat' } as any],
+  },
+  // 8. DIRECT_MESSAGE row. CHARACTERIZATION: DIRECT_MESSAGE is a
+  //    realtime-only concept — the history processors have NO branch for
+  //    it. This ADMIN-owned row takes the user-message path, which only
+  //    renders TEXT data, so it contributes NOTHING to the output (the
+  //    bubble is lost on reload). Recording current behavior as-is; see
+  //    unification plan.
+  {
+    id: 'd1',
+    chatType: 'CLIENT_CHAT',
+    createdAt: '2026-07-19T09:03:30Z',
+    owner: { type: 'ADMIN', user: { id: 'admin-7', firstName: 'Jane' } },
+    messageData: [{ type: 'DIRECT_MESSAGE', text: 'Human here, taking over' } as any],
+  },
+  // 9. Error row inside an assistant turn.
+  {
+    id: 'a5',
+    chatType: 'CLIENT_CHAT',
+    createdAt: '2026-07-19T09:04:00Z',
+    owner: { type: 'ASSISTANT' },
+    messageData: [
+      { type: 'TEXT', text: 'Attempting one more thing… ' },
+      { type: 'ERROR', error: 'Agent crashed', details: '{"error":{"message":"boom"}}' },
+    ],
+  },
+]
+
+describe('processHistoricalMessages — golden corpus', () => {
+  it('processes the full recorded dialog (snapshot)', () => {
+    const result = processHistoricalMessages(CORPUS, {
+      assistantName: 'Mingo AI',
+      assistantType: 'mingo',
+      assistantAvatar: '/avatars/mingo.png',
+    })
+    expect({
+      messages: result.messages,
+      escalatedApprovals: Array.from(result.escalatedApprovals.entries()),
+    }).toMatchSnapshot()
+  })
+
+  it('unresolved single approval is resurrected as a synthetic pending-approvals bubble', () => {
+    const result = processHistoricalMessages([
+      {
+        id: 'a1',
+        createdAt: '2026-07-19T09:00:00Z',
+        owner: { type: 'ASSISTANT' },
+        messageData: [
+          {
+            type: 'APPROVAL_REQUEST',
+            approvalRequestId: 'req-pending',
+            approvalType: 'CLIENT',
+            command: 'reboot server',
+          },
+        ],
+      },
+    ])
+    // Date.now is frozen → deterministic synthetic id.
+    expect(result.messages).toMatchSnapshot()
+  })
+
+  it('owner-type author resolution: CLIENT vs ADMIN vs ADMIN-without-name display names/avatars', () => {
+    const rows: HistoricalMessage[] = [
+      {
+        id: 'u-client',
+        createdAt: '2026-07-19T09:00:00Z',
+        owner: { type: 'CLIENT', userId: 'user-1' },
+        messageData: [{ type: 'TEXT', text: 'from client' }],
+      },
+      {
+        id: 'u-admin-named',
+        createdAt: '2026-07-19T09:00:01Z',
+        owner: {
+          type: 'ADMIN',
+          user: { id: 'adm', firstName: 'Jane', lastName: 'Admin', image: { imageUrl: '/a.png' } },
+        },
+        messageData: [{ type: 'TEXT', text: 'from named admin' }],
+      },
+      {
+        id: 'u-admin-anon',
+        createdAt: '2026-07-19T09:00:02Z',
+        owner: { type: 'ADMIN' },
+        messageData: [{ type: 'TEXT', text: 'from anonymous admin' }],
+      },
+    ]
+    expect(processHistoricalMessages(rows).messages).toMatchSnapshot()
+  })
+
+  it('chatTypeFilter drops rows of other chat types', () => {
+    const rows: HistoricalMessage[] = [
+      {
+        id: 'u1',
+        chatType: 'CLIENT_CHAT',
+        createdAt: '2026-07-19T09:00:00Z',
+        owner: { type: 'CLIENT' },
+        messageData: [{ type: 'TEXT', text: 'visible' }],
+      },
+      {
+        id: 'u2',
+        chatType: 'ADMIN_AI_CHAT',
+        createdAt: '2026-07-19T09:00:01Z',
+        owner: { type: 'CLIENT' },
+        messageData: [{ type: 'TEXT', text: 'filtered out' }],
+      },
+    ]
+    expect(
+      processHistoricalMessages(rows, { chatTypeFilter: 'CLIENT_CHAT' }).messages,
+    ).toMatchSnapshot()
+  })
+})
+
+describe('extractErrorMessages / processHistoricalMessagesWithErrors — golden', () => {
+  it('extractErrorMessages surfaces ERROR rows as standalone error-role messages', () => {
+    expect(extractErrorMessages(CORPUS, { assistantName: 'Mingo AI', assistantType: 'mingo' })).toMatchSnapshot()
+  })
+
+  it('processHistoricalMessagesWithErrors output parity on the same corpus (snapshot)', () => {
+    const result = processHistoricalMessagesWithErrors(CORPUS, {
+      assistantName: 'Mingo AI',
+      assistantType: 'mingo',
+      assistantAvatar: '/avatars/mingo.png',
+    })
+    expect({
+      messages: result.messages,
+      escalatedApprovals: Array.from(result.escalatedApprovals.entries()),
+    }).toMatchSnapshot()
+  })
+})

package/src/components/chat/utils/__tests__/segment-accumulator-golden.test.ts

@@ -0,0 +1,270 @@
+/**
+ * Phase-0 GOLDEN CHARACTERIZATION TESTS — `MessageSegmentAccumulator`.
+ *
+ * Pins the CURRENT segment-accumulation semantics before the stream-reader
+ * unification. Each test drives the accumulator through a recorded event
+ * sequence and snapshots the final segment array. Behaviors captured here
+ * (including the implicit approval-flip on tool execution and the batch
+ * no-downgrade rule) are the recorded baseline the future reducer must match.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { createMessageSegmentAccumulator } from '../message-segment-accumulator'
+import type { ToolExecutionSegment, PendingToolCallData } from '../../types'
+
+const executing = (
+  execId: string | undefined,
+  overrides: Partial<ToolExecutionSegment['data']> = {},
+): ToolExecutionSegment => ({
+  type: 'tool_execution',
+  data: {
+    type: 'EXECUTING_TOOL',
+    integratedToolType: 'TACTICAL_RMM',
+    toolFunction: 'run_script',
+    toolTitle: 'Run cleanup script',
+    parameters: { script: 'cleanup.sh' },
+    ...(execId ? { toolExecutionRequestId: execId } : {}),
+    ...overrides,
+  },
+})
+
+const executed = (
+  execId: string | undefined,
+  overrides: Partial<ToolExecutionSegment['data']> = {},
+): ToolExecutionSegment => ({
+  type: 'tool_execution',
+  data: {
+    type: 'EXECUTED_TOOL',
+    integratedToolType: 'TACTICAL_RMM',
+    toolFunction: 'run_script',
+    // Backend omits toolTitle on EXECUTED_TOOL — the accumulator restores it.
+    result: 'Freed 2.3 GB',
+    success: true,
+    ...(execId ? { toolExecutionRequestId: execId } : {}),
+    ...overrides,
+  },
+})
+
+const batchToolCalls: PendingToolCallData[] = [
+  {
+    toolExecutionRequestId: 'exec-a',
+    toolName: 'create_ticket',
+    toolTitle: 'Create ticket',
+    toolExplanation: 'Opens a support ticket',
+    requiresApproval: true,
+    approvalType: 'CLIENT',
+    toolCallArguments: { subject: 'Printer down' },
+  },
+  {
+    toolExecutionRequestId: 'exec-b',
+    toolName: 'read_kb',
+    requiresApproval: false,
+    approvalType: null,
+    toolCallArguments: null,
+  },
+]
+
+describe('MessageSegmentAccumulator — golden sequences', () => {
+  it('coalesces consecutive text deltas into one text segment', () => {
+    const acc = createMessageSegmentAccumulator()
+    acc.appendText('Hello')
+    acc.appendText(', ')
+    acc.appendText('world')
+    expect(acc.getSegments()).toMatchSnapshot()
+  })
+
+  it('coalesces thinking deltas, and text after thinking starts a NEW segment', () => {
+    const acc = createMessageSegmentAccumulator()
+    acc.appendThinking('Let me think')
+    acc.appendThinking('… ok.')
+    acc.appendText('Answer: ')
+    acc.appendText('42')
+    // A late thinking delta after text starts ANOTHER thinking segment
+    // (append-to-last only merges into a trailing segment of the same type).
+    acc.appendThinking('post-answer thought')
+    expect(acc.getSegments()).toMatchSnapshot()
+  })
+
+  it('merges EXECUTING_TOOL → EXECUTED_TOOL in place by toolExecutionRequestId (title restored)', () => {
+    const acc = createMessageSegmentAccumulator()
+    acc.appendText('Running a cleanup now.')
+    acc.addToolExecution(executing('exec-1'))
+    acc.addToolExecution(executed('exec-1'))
+    expect(acc.getSegments()).toMatchSnapshot()
+  })
+
+  it('pairs by (integratedToolType, toolFunction) when no exec id is present (older backends)', () => {
+    const acc = createMessageSegmentAccumulator()
+    acc.addToolExecution(executing(undefined))
+    acc.addToolExecution(executed(undefined))
+    expect(acc.getSegments()).toMatchSnapshot()
+  })
+
+  it('EXECUTED with no prior EXECUTING lands as a standalone completed segment', () => {
+    const acc = createMessageSegmentAccumulator()
+    acc.addToolExecution(executed('exec-orphan'))
+    expect(acc.getSegments()).toMatchSnapshot()
+  })
+
+  it('CHARACTERIZATION: a LATE standalone EXECUTING after its EXECUTED pushes a NEW executing segment (no in-place downgrade, but a duplicate card appears)', () => {
+    // The no-downgrade rule is enforced INSIDE approval batches
+    // (applyExecutionToBatch); for standalone segments a redelivered
+    // EXECUTING after EXECUTED does NOT downgrade the merged segment —
+    // it appends a fresh EXECUTING segment. Recording as-is, see
+    // unification plan.
+    const acc = createMessageSegmentAccumulator()
+    acc.addToolExecution(executing('exec-1'))
+    acc.addToolExecution(executed('exec-1'))
+    acc.addToolExecution(executing('exec-1'))
+    expect(acc.getSegments()).toMatchSnapshot()
+  })
+
+  it('single approval request → updateApprovalStatus flips status and stamps resolvedByName only on batches', () => {
+    const acc = createMessageSegmentAccumulator({
+      onApprove: async () => {},
+      onReject: async () => {},
+    })
+    acc.addApprovalRequest('req-1', 'systemctl restart nats', 'Restart broker', 'CLIENT')
+    acc.updateApprovalStatus('req-1', 'approved', 'Jane Admin')
+    expect(acc.getSegments()).toMatchSnapshot()
+  })
+
+  it('tracked (pending) approval + processApprovalResult appends a resolved segment', () => {
+    const acc = createMessageSegmentAccumulator()
+    acc.trackApprovalRequest('req-2', {
+      command: 'rm -rf /tmp/cache',
+      explanation: 'Clear caches',
+      approvalType: 'CLIENT',
+    })
+    const result = acc.processApprovalResult('req-2', false, 'CLIENT')
+    expect({
+      segments: acc.getSegments(),
+      pendingData: result?.pendingData ?? null,
+      hasPendingAfter: acc.hasPendingApprovals(),
+    }).toMatchSnapshot()
+  })
+
+  it('batch approval with per-tool executions merged into the batch (no standalone segments)', () => {
+    const acc = createMessageSegmentAccumulator()
+    acc.addApprovalBatch('batch-1', 'CLIENT', batchToolCalls)
+    acc.updateApprovalStatus('batch-1', 'approved', 'Jane Admin')
+    // Executions matching the batch's toolExecutionRequestIds merge into
+    // `executions` instead of pushing standalone tool_execution segments.
+    acc.addToolExecution(executing('exec-a', { toolFunction: 'create_ticket' }))
+    acc.addToolExecution(
+      executed('exec-a', { toolFunction: 'create_ticket', result: 'Ticket #77 created' }),
+    )
+    acc.addToolExecution(executing('exec-b', { toolFunction: 'read_kb' }))
+    expect(acc.getSegments()).toMatchSnapshot()
+  })
+
+  it('batch no-downgrade rule: a redelivered EXECUTING after EXECUTED keeps the done slot', () => {
+    const acc = createMessageSegmentAccumulator()
+    acc.addApprovalBatch('batch-1', 'CLIENT', batchToolCalls, 'approved')
+    acc.addToolExecution(executed('exec-a', { result: 'done!' }))
+    // Late/redelivered EXECUTING for the same exec id — must NOT flip
+    // the slot back to 'executing'.
+    acc.addToolExecution(executing('exec-a'))
+    expect(acc.getSegments()).toMatchSnapshot()
+  })
+
+  it('addApprovalBatch upserts by approvalRequestId (replay path produces ONE batch segment)', () => {
+    const acc = createMessageSegmentAccumulator()
+    acc.addApprovalBatch('batch-1', 'CLIENT', batchToolCalls, 'pending')
+    acc.addApprovalBatch('batch-1', 'CLIENT', batchToolCalls, 'approved', {
+      'exec-a': { status: 'done', result: 'ok', success: true },
+    }, 'Jane Admin')
+    expect(acc.getSegments()).toMatchSnapshot()
+  })
+
+  it('implicit resolvePendingApprovalForExecution: a tool execution flips the LATEST pending single approval (NATS-observer behavior)', () => {
+    // An observer (technician mirroring a client chat) may never receive
+    // APPROVAL_RESULT — only the tool's EXECUTING/EXECUTED events. The
+    // accumulator treats a tool execution as implicit approval of the most
+    // recent still-pending single approval gate. Pinning explicitly.
+    const acc = createMessageSegmentAccumulator()
+    acc.addApprovalRequest('req-old', 'echo old', undefined, 'CLIENT', 'rejected')
+    acc.addApprovalRequest('req-1', 'systemctl restart nats', undefined, 'CLIENT', 'pending')
+    acc.addToolExecution(executing('exec-9'))
+    expect(acc.getSegments()).toMatchSnapshot()
+  })
+
+  it('implicit approval flips ONLY the latest pending gate, earlier pending gates stay pending', () => {
+    const acc = createMessageSegmentAccumulator()
+    acc.addApprovalRequest('req-1', 'first', undefined, 'CLIENT', 'pending')
+    acc.addApprovalRequest('req-2', 'second', undefined, 'CLIENT', 'pending')
+    acc.addToolExecution(executing('exec-1'))
+    expect(acc.getSegments()).toMatchSnapshot()
+  })
+
+  it('implicit approval does NOT touch approval_batch segments (handled by applyExecutionToBatch only)', () => {
+    const acc = createMessageSegmentAccumulator()
+    acc.addApprovalBatch('batch-1', 'CLIENT', batchToolCalls, 'pending')
+    // exec id NOT in the batch → standalone segment path; batch stays pending.
+    acc.addToolExecution(executing('exec-unrelated'))
+    expect(acc.getSegments()).toMatchSnapshot()
+  })
+
+  it('context compaction start → complete replaces the started segment in place', () => {
+    const acc = createMessageSegmentAccumulator()
+    acc.appendText('Before compaction')
+    acc.addContextCompaction()
+    acc.completeContextCompaction('Summarized 34 messages')
+    acc.appendText('After compaction')
+    expect(acc.getSegments()).toMatchSnapshot()
+  })
+
+  it('completeContextCompaction with no started segment pushes a completed one', () => {
+    const acc = createMessageSegmentAccumulator()
+    acc.completeContextCompaction(undefined)
+    expect(acc.getSegments()).toMatchSnapshot()
+  })
+
+  it('error segments append verbatim', () => {
+    const acc = createMessageSegmentAccumulator()
+    acc.appendText('partial answer')
+    acc.addError('Agent crashed', 'boom')
+    expect(acc.getSegments()).toMatchSnapshot()
+  })
+
+  it('flushPendingApprovals emits pending cards for every tracked-but-unresolved approval', () => {
+    const acc = createMessageSegmentAccumulator()
+    acc.trackApprovalRequest('req-1', { command: 'cmd-1', approvalType: 'CLIENT' })
+    acc.trackApprovalRequest('req-2', { command: 'cmd-2', explanation: 'why', approvalType: 'ADMIN' })
+    expect(acc.flushPendingApprovals()).toMatchSnapshot()
+  })
+
+  it('replaySegments reproduces a mixed recorded segment array (idempotent replay)', () => {
+    const acc = createMessageSegmentAccumulator()
+    acc.appendThinking('hmm')
+    acc.appendText('Sure — ')
+    acc.addToolExecution(executing('exec-1'))
+    acc.addToolExecution(executed('exec-1'))
+    acc.addApprovalBatch('batch-1', 'CLIENT', batchToolCalls, 'approved', {
+      'exec-a': { status: 'done', result: 'ok', success: true },
+    })
+    acc.appendText('done.')
+    const recorded = acc.getSegments()
+
+    const replayed = createMessageSegmentAccumulator().replaySegments(recorded)
+    expect(replayed).toMatchSnapshot()
+  })
+
+  it('initializeWithState continues an incomplete message across reconnect', () => {
+    const first = createMessageSegmentAccumulator()
+    first.appendText('partial ')
+    first.addToolExecution(executing('exec-1'))
+    const state = first.getState()
+
+    const resumed = createMessageSegmentAccumulator()
+    resumed.initializeWithState({
+      existingSegments: state.segments,
+      pendingApprovals: state.pendingApprovals,
+      executingTools: state.executingTools,
+    })
+    // The EXECUTED for the pre-reconnect EXECUTING merges into it.
+    resumed.addToolExecution(executed('exec-1'))
+    resumed.appendText('and the rest.')
+    expect(resumed.getSegments()).toMatchSnapshot()
+  })
+})

package/src/components/chat/utils/extract-incomplete-message-state.ts

@@ -9,6 +9,18 @@ import type {
   PendingApproval,
   ExecutingToolState,
 } from '../types'
+import type { InitializeExtras } from '../stream/chat-stream-reducer'
+
+/**
+ * What the realtime accumulator needs to RESUME an unfinished turn.
+ *
+ * DERIVED, not restated: this is exactly the reducer's `InitializeExtras`
+ * minus `escalatedApprovals` (which only the live stream can produce — it has
+ * no historical representation to extract). Hosts pass the result straight
+ * into `reducer.initializeWithState(messages, extras)`, so the two must not
+ * drift; a structural coincidence is not a contract.
+ */
+export type IncompleteMessageState = Omit<InitializeExtras, 'escalatedApprovals'>
 
 /**
  * Extract incomplete message state from the last historical assistant message
@@ -16,11 +28,7 @@ import type {
  */
 export function extractIncompleteMessageState(
   lastMessage: ProcessedMessage | undefined
-): {
-  existingSegments?: MessageSegment[]
-  pendingApprovals?: Map<string, PendingApproval>
-  executingTools?: Map<string, ExecutingToolState>
-} | undefined {
+): IncompleteMessageState | undefined {
   if (!lastMessage || lastMessage.role !== 'assistant' || typeof lastMessage.content === 'string') {
     return undefined
   }
@@ -92,4 +100,54 @@ export function extractIncompleteMessageState(
     pendingApprovals: pendingApprovals.size > 0 ? pendingApprovals : undefined,
     executingTools: executingTools.size > 0 ? executingTools : undefined,
   }
+}
+
+/**
+ * THREAD-level generalization of `extractIncompleteMessageState`: given a
+ * processed thread, look at the TRAILING RUN of consecutive assistant
+ * messages (not just the very last row), flatten it to one segment list, and
+ * ask the single-message extractor whether that tail is unfinished.
+ *
+ * Why the run and not the last row: the backend can split one logical turn
+ * across several assistant messages (a preamble bubble, then the approval
+ * card, then the continuation). The unfinished artifact — a pending approval,
+ * an EXECUTING_TOOL with no result, an open compaction — can therefore sit in
+ * an EARLIER bubble of the same trailing run, and a last-row-only check
+ * reports "complete" while the turn is very much still in flight.
+ *
+ * SSOT for every "is the tail incomplete?" question — the NATS adapter (which
+ * used to inline the single-row check) and hosts replaying a stored thread
+ * both call this instead of re-deriving the walk.
+ *
+ * A trailing non-assistant row (user / error) means the last turn closed →
+ * `undefined`.
+ */
+export function extractIncompleteTailState(
+  messages: readonly ProcessedMessage[] | undefined,
+): IncompleteMessageState | undefined {
+  if (!messages || messages.length === 0) return undefined
+
+  // Walk back over the trailing consecutive assistant run.
+  let start = messages.length
+  while (start > 0 && messages[start - 1]?.role === 'assistant') start -= 1
+  if (start === messages.length) return undefined
+
+  const segments: MessageSegment[] = []
+  for (let i = start; i < messages.length; i += 1) {
+    const content = messages[i]?.content
+    // A string-content assistant row is a plain-text bubble with nothing to
+    // resume; skip it rather than aborting — a later row in the same run may
+    // still hold the unfinished segment.
+    if (Array.isArray(content)) segments.push(...(content as MessageSegment[]))
+  }
+  if (segments.length === 0) return undefined
+
+  // Reuse the single-message extractor verbatim by handing it a synthetic
+  // assistant row carrying the flattened run — one incompleteness rule set,
+  // not two.
+  return extractIncompleteMessageState({
+    ...messages[messages.length - 1],
+    role: 'assistant',
+    content: segments,
+  } as ProcessedMessage)
 }