<!-- source-hash: cbf092b126eb212162fd68f7341c0c6d -->
A React hook that manages Server-Sent Events (SSE) streaming for chat messages, handling abort control, error states, and async generator-based chunk processing.

## Key Components

### Types & Interfaces

| Export | Description |
|--------|-------------|
| `StreamFnExtraOptions` | Per-call options: `commandOverride`, `approvalAction` (tool approval/rejection routing), `pendingAttachments` (chat file uploads) |
| `StreamFn` | Async generator signature `(message, signal?, extra?) => AsyncGenerator<MessageSegment>` |
| `UseSSEOptions` | Hook config: `useMock`, `debugMode`, `streamFn` |

### Hook Return Values

| Value | Type | Description |
|-------|------|-------------|
| `streamMessage` | `AsyncGenerator fn` | Initiates streaming with fresh `AbortController` per call |
| `isStreaming` | `boolean` | Streaming in-progress state |
| `error` | `string \| null` | Last error message (AbortErrors are suppressed) |
| `abort` | `() => void` | Cancels active stream and terminates upstream fetch |
| `reset` | `() => void` | Resets hook state |

## Usage Example

```typescript
import { useSSE } from './use-sse'
import { createDocStreamFn } from './use-embedded-chat'

function ChatComponent() {
  const streamFn = createDocStreamFn({ sessionId: 'abc123' })
  const { streamMessage, isStreaming, error, abort } = useSSE({
    useMock: false,
    streamFn,
  })

  const handleSend = async (message: string) => {
    for await (const chunk of streamMessage(message, {
      commandOverride: { command: '/discuss', payload: cardId },
      pendingAttachments: stagedFiles,
    })) {
      appendChunk(chunk)
    }
  }

  return (
    <>
      <button onClick={() => handleSend('Hello')}>Send</button>
      {isStreaming && <button onClick={abort}>Stop</button>}
      {error && <p>{error}</p>}
    </>
  )
}
```

## Notes

- `useMock: true` without a `streamFn` throws loudly by design — mock implementations must be provided by the host application
- `AbortController` is created fresh per `streamMessage` call; the ref guards against race conditions in rapid send→stop→send sequences
- `approvalAction` routes to `/api/chat/agent/confirm-tool` instead of `/api/docs/chat` for tool approval flows