<!-- source-hash: 637d22f77dbdb02b04013632095ddfdb -->
Utilities for parsing raw NATS message chunks into typed, structured action objects consumed by the AI message pipeline.

## Key Components

### `parseChunkToAction(chunk)`
Core export that maps a raw `ChunkData` object to a `ParsedChunkAction` union type. Uses a `switch` on `MESSAGE_TYPE` to handle all supported message variants:

| Action | Description |
|---|---|
| `message_start` / `message_end` | Lifecycle control signals |
| `metadata` | AI model/provider info |
| `text` / `thinking` / `system` | Content streaming |
| `tool_execution` | Tool start/completion events |
| `approval_request` / `approval_batch` | Single or multi-tool approval flows |
| `approval_result` | Approval outcome |
| `token_usage` | Token consumption stats |
| `context_compaction_start/end` | Context window management |
| `direct_message` | Owner-attributed messages |
| `dialog_closed` | Session termination |

Returns `null` for unknown or malformed chunks.

### `normalizeToolCalls(raw)` *(internal)*
Coerces an unknown array into `PendingToolCallData[]`, safely defaulting missing fields and enforcing correct types.

### Guard Helpers
Lightweight boolean checks for common chunk classifications:

- `isControlChunk(chunk)` — start/end signals
- `isErrorChunk(chunk)` — error type
- `isMetadataChunk(chunk)` — AI metadata
- `extractTextFromChunk(chunk)` — returns text content or `null`

## Usage Example

```typescript
import { parseChunkToAction, isErrorChunk } from './chunk-parser'

// Incoming NATS message payload
const raw = { type: 'TEXT', text: 'Hello from Mingo AI' }

if (isErrorChunk(raw)) {
  console.error('Stream error received')
}

const action = parseChunkToAction(raw)
if (action?.action === 'text') {
  renderText(action.text) // "Hello from Mingo AI"
}
```