<!-- source-hash: dab060497e2fa3825072e74aa1f72abf -->
Manages the accumulation and lifecycle of streaming message segments in a chat interface, handling text, tool executions, and approval workflows during real-time or historical message processing.

## Key Components

### `MessageSegmentAccumulator` (class)
Core class managing segment state across the message lifecycle.

| Method | Description |
|---|---|
| `appendText(text)` | Appends to the last text segment or creates a new one |
| `appendThinking(text)` | Same coalescing logic for `thinking`-type segments |
| `addToolExecution(segment)` | Routes `EXECUTING_TOOL` / `EXECUTED_TOOL` events; patches batch approvals or standalone segments |
| `addApprovalRequest(...)` | Pushes a single `approval_request` segment with callbacks |
| `addApprovalBatch(...)` | Upserts an `approval_batch` segment by `approvalRequestId` |
| `initializeWithState(state)` | Restores segments, pending approvals, and executing tool maps (e.g. after page refresh) |
| `getState()` | Returns serializable `AccumulatorState` snapshot |
| `reset()` / `resetSegments()` | Clears all state or only segments |

### `AccumulatorCallbacks` (interface)
Optional `onApprove` / `onReject` async callbacks injected into approval segments.

### Private helpers
- `applyExecutionToBatch` — merges tool execution results into an existing `approval_batch` segment
- `resolvePendingApprovalForExecution` — implicitly marks the latest pending `approval_request` as approved when a tool execution arrives (handles observer sessions that never receive `APPROVAL_RESULT`)

## Usage Example

```typescript
import { MessageSegmentAccumulator } from './message-segment-accumulator'

const accumulator = new MessageSegmentAccumulator({
  onApprove: async (requestId) => { /* handle approval */ },
  onReject: async (requestId) => { /* handle rejection */ },
})

// Streaming text chunks
accumulator.appendText('Hello, ')
accumulator.appendText('world!')

// Tool execution lifecycle
accumulator.addToolExecution({
  type: 'tool_execution',
  data: { type: 'EXECUTING_TOOL', toolFunction: 'runScript', integratedToolType: 'shell', toolExecutionRequestId: 'req-1' }
})

accumulator.addToolExecution({
  type: 'tool_execution',
  data: { type: 'EXECUTED_TOOL', toolFunction: 'runScript', integratedToolType: 'shell', toolExecutionRequestId: 'req-1', result: 'ok', success: true }
})

// Serialize and restore across reconnects
const state = accumulator.getState()
const restored = new MessageSegmentAccumulator()
restored.initializeWithState(state)

console.log(restored.getSegments())
```

## Source

[`message-segment-accumulator.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/message-segment-accumulator.ts)