<!-- source-hash: abb044a6e8d133979dfd31cca4044960 -->
Transforms raw `HistoricalMessage` arrays from GraphQL/API responses into display-ready `ProcessedMessage` objects, handling message grouping, approval state resolution, and tool call rendering.

## Key Components

### `processHistoricalMessages(messages, options)`
Main export. Iterates over historical messages, groups consecutive assistant turns into single display messages, and returns a `ProcessHistoricalMessagesResult` containing:
- `messages` — fully rendered `ProcessedMessage[]` ready for UI consumption
- `escalatedApprovals` — approvals filtered out by `displayApprovalTypes` that the consumer handles separately (e.g., admin-side approvals in a client-facing view)

### `processMessageData(data, accumulator, approvalStatuses, options, escalatedApprovals)`
Internal dispatcher. Routes each `MessageData` item by `MESSAGE_TYPE` to the correct accumulator method:

| Type | Action |
|---|---|
| `TEXT` | `appendText` |
| `THINKING` | `appendThinking` |
| `EXECUTING_TOOL` / `EXECUTED_TOOL` | `addToolExecution` |
| `APPROVAL_REQUEST` | Batch or legacy approval card, or escalate |
| `APPROVAL_RESULT` | Resolves pending/escalated approvals |

### `flushAssistantMessage()` *(internal closure)*
Drains the segment accumulator into a single assistant `ProcessedMessage`. Uses the **last** message ID in the group as the React key for stable pagination behavior.

### `ProcessHistoricalMessagesResult`
```typescript
export interface ProcessHistoricalMessagesResult {
  messages: ProcessedMessage[]
  escalatedApprovals: Map<
    string,
    { command: string; explanation?: string; approvalType: string; toolCalls?: PendingToolCallData[] }
  >
}
```

## Usage Example

```typescript
import { processHistoricalMessages } from './process-historical-messages'

const { messages, escalatedApprovals } = processHistoricalMessages(
  rawMessages,
  {
    assistantName: 'Fae',
    assistantType: 'fae',
    approvalStatuses: { 'req-123': 'approved' },
    displayApprovalTypes: ['CLIENT'],
    batchApprovalsEnabled: true,
    onApprove: (id) => handleApprove(id),
    onReject: (id) => handleReject(id),
  }
)

// escalatedApprovals contains ADMIN-type approvals for separate rendering
```

> **Note on `batchApprovalsEnabled`:** Defaults to `true`. Pass `false` to unfold batch approval requests into individual legacy approval cards — useful when the consuming UI has not yet adopted the batch approval component.