@flamingo-stack/openframe-frontend-core 0.0.508 → 0.0.509

package/src/chat-protocol/__tests__/ip-normalize.test.ts

@@ -0,0 +1,136 @@
+import { describe, it, expect } from 'vitest'
+import { normalizeIpForBucketKey, IP_BUCKET_KEY_MAX_LENGTH } from '../ip-normalize'
+
+describe('normalizeIpForBucketKey', () => {
+  it('passes plain IPv4 through', () => {
+    expect(normalizeIpForBucketKey('203.0.113.4')).toBe('203.0.113.4')
+    expect(normalizeIpForBucketKey('  203.0.113.4  ')).toBe('203.0.113.4')
+  })
+
+  it('range-checks IPv4 octets', () => {
+    expect(normalizeIpForBucketKey('203.0.113.256')).toBeNull()
+    expect(normalizeIpForBucketKey('203.0.113')).toBeNull()
+    expect(normalizeIpForBucketKey('203.0.113.4.5')).toBeNull()
+  })
+
+  it('unwraps IPv4-mapped IPv6 to the bare IPv4 (one peer, one bucket)', () => {
+    expect(normalizeIpForBucketKey('::ffff:203.0.113.4')).toBe('203.0.113.4')
+    // Written-out spelling of the SAME mapped address must land in the same
+    // bucket — a hop that formats without zero-compression would otherwise
+    // split one peer in two.
+    expect(normalizeIpForBucketKey('0:0:0:0:0:ffff:203.0.113.4')).toBe('203.0.113.4')
+    expect(normalizeIpForBucketKey('0:0:0:0:0:FFFF:203.0.113.4')).toBe('203.0.113.4')
+    expect(normalizeIpForBucketKey('0:0:0:0:0:ffff:203.0.113.999')).toBeNull()
+    expect(normalizeIpForBucketKey('::FFFF:203.0.113.4')).toBe('203.0.113.4')
+    expect(normalizeIpForBucketKey('[::ffff:203.0.113.4]:443')).toBe('203.0.113.4')
+    expect(normalizeIpForBucketKey('::ffff:203.0.113.999')).toBeNull()
+    // ZERO-PADDED groups are the fixed-width spelling of the same mapped
+    // address. Leading zeros inside an IPv6 group are cosmetic, so this must
+    // reach the same bucket as `::ffff:` — not fall through to the IPv6 path.
+    expect(normalizeIpForBucketKey('0000:0000:0000:0000:0000:ffff:203.0.113.4')).toBe(
+      '203.0.113.4',
+    )
+    expect(normalizeIpForBucketKey('0000:0000:0000:0000:0000:FFFF:203.0.113.4')).toBe(
+      '203.0.113.4',
+    )
+    // Mixed padding widths (a formatter that pads only some groups).
+    expect(normalizeIpForBucketKey('00:000:0:0000:0:ffff:203.0.113.4')).toBe('203.0.113.4')
+    // The embedded IPv4 is still range-checked in the padded spelling.
+    expect(normalizeIpForBucketKey('0000:0000:0000:0000:0000:ffff:203.0.113.999')).toBeNull()
+    // …and its octets still may not be zero-padded (two spellings of one host).
+    expect(normalizeIpForBucketKey('0000:0000:0000:0000:0000:ffff:203.0.113.04')).toBeNull()
+  })
+
+  it('strips brackets and a trailing port', () => {
+    expect(normalizeIpForBucketKey('[::1]:443')).toBe('::1')
+    expect(normalizeIpForBucketKey('[2001:db8::1]')).toBe('2001:db8::1')
+    // Unbalanced / junk trailer is not an address.
+    expect(normalizeIpForBucketKey('[::1')).toBeNull()
+    expect(normalizeIpForBucketKey('[::1]junk')).toBeNull()
+  })
+
+  it('strips the %zone scope id', () => {
+    expect(normalizeIpForBucketKey('fe80::1%eth0')).toBe('fe80::1')
+    expect(normalizeIpForBucketKey('[fe80::1%25eth0]:9000')).toBe('fe80::1')
+    expect(normalizeIpForBucketKey('%eth0')).toBeNull()
+  })
+
+  it('lower-cases IPv6 so casing cannot split a bucket', () => {
+    expect(normalizeIpForBucketKey('2001:DB8::AB')).toBe('2001:db8::ab')
+    expect(normalizeIpForBucketKey('2001:db8::ab')).toBe('2001:db8::ab')
+  })
+
+  it('accepts full and compressed IPv6 shapes', () => {
+    expect(normalizeIpForBucketKey('2001:0db8:0000:0000:0000:0000:0000:0001')).toBe(
+      '2001:0db8:0000:0000:0000:0000:0000:0001',
+    )
+    expect(normalizeIpForBucketKey('::')).toBe('::')
+    expect(normalizeIpForBucketKey('64:ff9b::203.0.113.4')).toBe('64:ff9b::203.0.113.4')
+  })
+
+  it('rejects malformed IPv6', () => {
+    expect(normalizeIpForBucketKey('2001:db8::1::2')).toBeNull()
+    expect(normalizeIpForBucketKey('2001:db8:::1')).toBeNull()
+    expect(normalizeIpForBucketKey('1:2:3:4:5:6:7:8:9')).toBeNull()
+    expect(normalizeIpForBucketKey('2001:db8:0:0:0:0:1')).toBeNull()
+    expect(normalizeIpForBucketKey('2001:zzzz::1')).toBeNull()
+  })
+
+  /**
+   * REGRESSION (round 4): Azure App Service / Front Door and several CDNs put
+   * `ip:port` in the XFF hop. Returning null there left the caller with NO
+   * candidate, collapsing every visitor into the single egress bucket.
+   */
+  it('strips a bare :port from an IPv4 hop, but not from an ambiguous IPv6', () => {
+    expect(normalizeIpForBucketKey('203.0.113.4:8080')).toBe('203.0.113.4')
+    expect(normalizeIpForBucketKey('203.0.113.4:0')).toBe('203.0.113.4')
+    expect(normalizeIpForBucketKey('  203.0.113.4:65535  ')).toBe('203.0.113.4')
+    // Not a port (6 digits) → not stripped, and the remainder is not an address.
+    expect(normalizeIpForBucketKey('203.0.113.4:123456')).toBeNull()
+    // Out-of-range head is still rejected once the port comes off.
+    expect(normalizeIpForBucketKey('203.0.113.256:8080')).toBeNull()
+    // Unbracketed IPv6 + bare port is genuinely ambiguous (`:1` is equally a
+    // final group), so the IPv6 reading wins and nothing is stripped.
+    expect(normalizeIpForBucketKey('2001:db8::1')).toBe('2001:db8::1')
+    expect(normalizeIpForBucketKey('::1:443')).toBe('::1:443')
+  })
+
+  it('rejects zero-padded IPv4 octets (one peer must not split two buckets)', () => {
+    expect(normalizeIpForBucketKey('203.0.113.04')).toBeNull()
+    expect(normalizeIpForBucketKey('203.0.113.004')).toBeNull()
+    expect(normalizeIpForBucketKey('203.00.113.4')).toBeNull()
+    expect(normalizeIpForBucketKey('203.0.113.04:8080')).toBeNull()
+    expect(normalizeIpForBucketKey('::ffff:203.0.113.04')).toBeNull()
+    // A lone `0` octet is not padding.
+    expect(normalizeIpForBucketKey('203.0.113.0')).toBe('203.0.113.0')
+  })
+
+  it('rejects a dangling separator and a misplaced embedded IPv4', () => {
+    expect(normalizeIpForBucketKey('2001:db8::1:')).toBeNull()
+    expect(normalizeIpForBucketKey(':2001:db8::1')).toBeNull()
+    expect(normalizeIpForBucketKey('1.2.3.4::1')).toBeNull()
+    expect(normalizeIpForBucketKey('::1.2.3.4:5')).toBeNull()
+    // The legitimate shapes still pass.
+    expect(normalizeIpForBucketKey('::')).toBe('::')
+    expect(normalizeIpForBucketKey('2001:db8::')).toBe('2001:db8::')
+    expect(normalizeIpForBucketKey('::1.2.3.4')).toBe('::1.2.3.4')
+  })
+
+  it('rejects oversized input rather than making an unbounded key', () => {
+    const oversized = 'a'.repeat(IP_BUCKET_KEY_MAX_LENGTH + 1)
+    expect(oversized.length).toBeGreaterThan(IP_BUCKET_KEY_MAX_LENGTH)
+    expect(normalizeIpForBucketKey(oversized)).toBeNull()
+    // A valid address padded past the cap is still refused.
+    expect(normalizeIpForBucketKey(`203.0.113.4${' '.repeat(200)}`)).toBe('203.0.113.4')
+    expect(normalizeIpForBucketKey(`${'0'.repeat(70)}.1.1.1`)).toBeNull()
+  })
+
+  it('rejects junk', () => {
+    expect(normalizeIpForBucketKey('')).toBeNull()
+    expect(normalizeIpForBucketKey('   ')).toBeNull()
+    expect(normalizeIpForBucketKey('unknown')).toBeNull()
+    expect(normalizeIpForBucketKey('example.com')).toBeNull()
+    expect(normalizeIpForBucketKey('203.0.113.4, 198.51.100.7')).toBeNull()
+    expect(normalizeIpForBucketKey(undefined as unknown as string)).toBeNull()
+  })
+})

package/src/chat-protocol/__tests__/nats-decoder-golden.test.ts

@@ -0,0 +1,237 @@
+/**
+ * GOLDEN CHARACTERIZATION TESTS — `decodeNatsChunk`.
+ *
+ * Pins the NATS chunk → `ChatStreamEvent` mapping for the whole recorded
+ * corpus of wire shapes (every MESSAGE_TYPE the decoder handles, plus the
+ * malformed/unknown tolerance cases). Retargeted from the deleted
+ * `parseChunkToAction` golden suite when the superseded legacy parser was
+ * removed — same corpus, now snapshotted against the ONE live decoder.
+ *
+ * Do NOT "fix" behaviors captured here — they are the recorded baseline.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { decodeNatsChunk } from '../nats-decoder'
+
+/** Recorded corpus of realistic NATS chunk shapes, keyed by scenario name. */
+const CORPUS: Record<string, unknown> = {
+  message_start: { type: 'MESSAGE_START' },
+  message_end: { type: 'MESSAGE_END' },
+
+  text: { type: 'TEXT', text: 'Hello, ' },
+  text_empty_string: { type: 'TEXT', text: '' },
+  text_missing_text_field: { type: 'TEXT' },
+
+  thinking: { type: 'THINKING', text: 'Considering options…' },
+  thinking_missing_text: { type: 'THINKING' },
+
+  guide: { type: 'GUIDE', text: '## Enroll a device\n1. Open Settings' },
+  guide_empty_string: { type: 'GUIDE', text: '' },
+  guide_missing_text: { type: 'GUIDE' },
+
+  ai_metadata_full: {
+    type: 'AI_METADATA',
+    modelDisplayName: 'Claude Sonnet',
+    modelName: 'claude-sonnet-x',
+    providerName: 'anthropic',
+    contextWindow: 200000,
+  },
+  // Legacy field name `provider` (not `providerName`) is accepted.
+  ai_metadata_legacy_provider_field: {
+    type: 'AI_METADATA',
+    modelName: 'gpt-x',
+    provider: 'openai',
+  },
+  ai_metadata_missing_model: { type: 'AI_METADATA', providerName: 'anthropic' },
+  ai_metadata_non_numeric_context_window: {
+    type: 'AI_METADATA',
+    modelName: 'claude-sonnet-x',
+    providerName: 'anthropic',
+    contextWindow: '200000',
+  },
+
+  executing_tool: {
+    type: 'EXECUTING_TOOL',
+    integratedToolType: 'TACTICAL_RMM',
+    toolFunction: 'run_script',
+    title: 'Run cleanup script',
+    // The card's body line. Carried by EXECUTING only — the EXECUTED chunk
+    // never repeats it, so losing it here blanks the tool card for the whole
+    // run. Every chunk in this corpus omitted it once, which is how a decoder
+    // that silently dropped the field shipped with the goldens still green.
+    toolExplanation: 'Discovering columns available in the system_info table for accurate querying.',
+    parameters: { script: 'cleanup.sh', timeout: 30 },
+    toolExecutionRequestId: 'exec-1',
+  },
+  executing_tool_minimal: { type: 'EXECUTING_TOOL' },
+
+  executed_tool: {
+    type: 'EXECUTED_TOOL',
+    integratedToolType: 'TACTICAL_RMM',
+    toolFunction: 'run_script',
+    parameters: { script: 'cleanup.sh' },
+    result: 'Freed 2.3 GB',
+    success: true,
+    toolExecutionRequestId: 'exec-1',
+  },
+  executed_tool_failure_no_exec_id: {
+    type: 'EXECUTED_TOOL',
+    integratedToolType: 'FLEET_MDM',
+    toolFunction: 'lock_device',
+    result: 'Device unreachable',
+    success: false,
+  },
+
+  approval_request_single: {
+    type: 'APPROVAL_REQUEST',
+    approvalRequestId: 'req-1',
+    approvalType: 'CLIENT',
+    command: 'systemctl restart nats',
+    explanation: 'Restart the message broker',
+  },
+  // snake_case id field (approval_request_id) is accepted as a fallback.
+  approval_request_snake_case_id: {
+    type: 'APPROVAL_REQUEST',
+    approval_request_id: 'req-2',
+    command: 'rm -rf /tmp/cache',
+  },
+  approval_request_batch: {
+    type: 'APPROVAL_REQUEST',
+    approvalRequestId: 'batch-1',
+    approvalType: 'ADMIN',
+    toolCalls: [
+      {
+        toolExecutionRequestId: 'exec-a',
+        toolName: 'create_ticket',
+        toolTitle: 'Create ticket',
+        toolExplanation: 'Opens a new support ticket',
+        toolType: 'WRITE',
+        requiresApproval: true,
+        approvalType: 'ADMIN',
+        toolCallArguments: { subject: 'Printer down' },
+      },
+      {
+        toolExecutionRequestId: 'exec-b',
+        toolName: 'read_kb',
+        requiresApproval: false,
+        approvalType: null,
+        toolCallArguments: null,
+      },
+    ],
+  },
+  // Malformed entries inside toolCalls are coerced/filtered by normalizeToolCalls.
+  approval_request_batch_malformed_entries: {
+    type: 'APPROVAL_REQUEST',
+    approvalRequestId: 'batch-2',
+    toolCalls: [
+      null,
+      'not-an-object',
+      { toolName: 42, requiresApproval: 'yes', toolCallArguments: 'nope' },
+    ],
+  },
+  // CHARACTERIZATION: an empty toolCalls array falls back to the SINGLE
+  // approval-request shape (batch requires length > 0).
+  approval_request_empty_tool_calls: {
+    type: 'APPROVAL_REQUEST',
+    approvalRequestId: 'req-3',
+    toolCalls: [],
+    command: 'echo hi',
+  },
+
+  approval_result_approved: {
+    type: 'APPROVAL_RESULT',
+    approvalRequestId: 'req-1',
+    approved: true,
+    approvalType: 'CLIENT',
+    displayName: 'Jane Admin',
+  },
+  approval_result_rejected_resolved_by_name: {
+    type: 'APPROVAL_RESULT',
+    approvalRequestId: 'req-1',
+    approved: false,
+    resolvedByName: 'Bob Tech',
+  },
+  // CHARACTERIZATION: approved must be === true; any other value → rejected.
+  approval_result_truthy_string_approved: {
+    type: 'APPROVAL_RESULT',
+    approvalRequestId: 'req-9',
+    approved: 'true',
+  },
+
+  error_full: { type: 'ERROR', error: 'Agent crashed', details: '{"error":{"message":"boom"}}' },
+  error_bare: { type: 'ERROR' },
+
+  message_request: {
+    type: 'MESSAGE_REQUEST',
+    text: 'open a ticket',
+    ownerType: 'CLIENT',
+    displayName: 'Alice',
+    userId: 'user-42',
+  },
+  message_request_with_context_items: {
+    type: 'MESSAGE_REQUEST',
+    text: 'diagnose this device',
+    contextItems: [
+      { type: 'device', id: 'dev-1' },
+      { type: 'ticket' }, // missing id → filtered
+      { id: 'orphan' }, // missing type → filtered
+    ],
+  },
+  message_request_no_text: { type: 'MESSAGE_REQUEST' },
+
+  token_usage: {
+    type: 'TOKEN_USAGE',
+    inputTokensSize: 1200,
+    outputTokensSize: 340,
+    totalTokensSize: 1540,
+    contextSize: 180000,
+  },
+  token_usage_empty_defaults: { type: 'TOKEN_USAGE' },
+
+  context_compaction_start: { type: 'CONTEXT_COMPACTION_START' },
+  context_compaction_end: { type: 'CONTEXT_COMPACTION_END', text: 'Compacted 34 messages' },
+  context_compaction_end_no_summary: { type: 'CONTEXT_COMPACTION_END' },
+
+  system: { type: 'SYSTEM', text: 'Technician joined the chat' },
+  system_no_text: { type: 'SYSTEM' },
+
+  direct_message: {
+    type: 'DIRECT_MESSAGE',
+    text: 'Hi, human here taking over',
+    ownerType: 'ADMIN',
+    displayName: 'Jane Admin',
+    userId: 'admin-7',
+  },
+  direct_message_no_text: { type: 'DIRECT_MESSAGE' },
+
+  dialog_closed: { type: 'DIALOG_CLOSED' },
+
+  // ---- Malformed / unknown chunks ------------------------------------
+  unknown_type: { type: 'SOMETHING_NEW' },
+  missing_type: { text: 'hello' },
+  null_chunk: null,
+  undefined_chunk: undefined,
+  string_chunk: 'TEXT',
+  number_chunk: 42,
+  empty_object: {},
+}
+
+describe('decodeNatsChunk — golden corpus', () => {
+  it('maps the full recorded corpus to normalized events (snapshot)', () => {
+    const results = Object.fromEntries(
+      Object.entries(CORPUS).map(([name, chunk]) => [name, decodeNatsChunk(chunk)]),
+    )
+    expect(results).toMatchSnapshot()
+  })
+})
+
+describe('decodeNatsChunk — seq envelope', () => {
+  it('lifts a numeric JetStream `streamSeq` into `seq`, and omits it otherwise (snapshot)', () => {
+    expect({
+      numeric: decodeNatsChunk({ type: 'TEXT', text: 'hi', streamSeq: 42 }),
+      absent: decodeNatsChunk({ type: 'TEXT', text: 'hi' }),
+      non_numeric: decodeNatsChunk({ type: 'TEXT', text: 'hi', streamSeq: '42' }),
+      zero: decodeNatsChunk({ type: 'MESSAGE_START', streamSeq: 0 }),
+    }).toMatchSnapshot()
+  })
+})

package/src/chat-protocol/decode.ts

@@ -0,0 +1,278 @@
+/**
+ * SSE wire-protocol decoder — a timer-free synchronous state machine,
+ * mechanically extracted from `useSseChatAdapter`'s inline
+ * `createDocStreamFn` parser. Byte-for-byte behavior parity with the
+ * legacy parser is the contract (the golden fixtures in
+ * `src/components/chat/hooks/__tests__/sse-stream-golden.test.ts` pin it
+ * through the full hook path), including its quirks:
+ *
+ *   - A leading `\0`-terminated block that fails JSON.parse flips the
+ *     stream into text mode and the WHOLE buffer (including the `\0`)
+ *     is emitted as answer text (legacy no-frame stream fallback). This
+ *     transition is marked `turn-start { implicit: true }`.
+ *   - In text mode only `\x1F` is scanned — literal `\0` / `\x1E` bytes
+ *     pass through into the answer; the FIRST literal `\x1F` flips into
+ *     trailer mode and everything after is captured as the trailer
+ *     (golden fixture (d) characterizes this mis-framing; the fix lives
+ *     in `encode.ts`'s sentinel stripping, NOT here).
+ *   - The `\x1E` sentinel and the `\x1F` trailer can arrive in ONE TCP
+ *     chunk (fixed-answer responses) — the post-sentinel slice is
+ *     re-scanned for the trailer sentinel.
+ *   - Multi-byte UTF-8 across chunk boundaries survives via a single
+ *     streaming TextDecoder (`{ stream: true }` on every push; no final
+ *     flush — a trailing partial code point is dropped, as legacy did).
+ *   - `end()` parses the accumulated trailer (malformed → silently
+ *     ignored) and drops any un-terminated leading buffer, as legacy did.
+ *     It is IDEMPOTENT (a deliberate deviation from legacy): repeat calls
+ *     emit nothing, so an adapter that ends in both its completion path
+ *     and its `finally` cannot double-count the usage frame.
+ *
+ * State flow: leading → (sentinel | parse-failure) → text → (\x1F) →
+ * trailer-accumulate → end().
+ *
+ * Server-safe: no React, no timers, TextDecoder only.
+ */
+
+import { FRAME_TERMINATOR, END_OF_LEADING, TRAILER_SENTINEL } from './frames'
+import type { ChatStreamEvent } from './events'
+
+export interface SseFrameDecoder {
+  /** Feed raw response bytes; returns the events they produced. */
+  push(bytes: Uint8Array): ChatStreamEvent[]
+  /**
+   * Signal end-of-stream; parses the trailing usage frame if present.
+   * IDEMPOTENT — every call after the first returns `[]`. Adapters
+   * routinely call this from BOTH their completion path and a `finally`,
+   * and a re-emitted `usage`/`stage:'end'` event would double-count token
+   * usage (displayed cost doubles).
+   */
+  end(): ChatStreamEvent[]
+}
+
+/**
+ * Escape `<` so markdown renderers that pass HTML through (rehypeRaw)
+ * don't treat XML-like tokens in Claude's thinking output as elements.
+ * `<` → `&lt;` preserves the visible character without breaking
+ * blockquote `>` markers. Per-character, so it distributes over
+ * concatenation: escape(a + b) === escape(a) + escape(b) — callers may
+ * apply it per-delta or on the accumulated string interchangeably.
+ */
+export function escapeThinkingTags(text: string): string {
+  return text.replace(/</g, '&lt;')
+}
+
+/**
+ * Map one parsed leading frame to normalized events, replicating the
+ * legacy parser's else-if chain ORDER and its exact truthiness/typeof
+ * gates. Frames that matched a branch but failed its inner validation
+ * (e.g. `routing` without a string `routedComplexity`) produce NO event,
+ * exactly like the legacy no-op.
+ */
+function mapLeadingFrame(meta: any, out: ChatStreamEvent[]): void {
+  if (meta.status === 'thinking') {
+    out.push({ type: 'status', phase: 'thinking' })
+  } else if (meta.kind === 'thinking-delta' && typeof meta.text === 'string') {
+    // Wire is ALREADY delta — emit verbatim, append-only contract.
+    out.push({ type: 'thinking-delta', text: meta.text })
+  } else if (meta.kind === 'usage' && meta.stage === 'start') {
+    out.push({
+      type: 'usage',
+      stage: 'start',
+      input_tokens: meta.input_tokens,
+      cache_read_input_tokens: meta.cache_read_input_tokens,
+      cache_creation_input_tokens: meta.cache_creation_input_tokens,
+    })
+  } else if (meta.kind === 'decision_resolved' && typeof meta.action === 'string') {
+    const status = meta.action === 'rejected' ? 'rejected' : 'approved'
+    const toolName = typeof meta.tool_name === 'string' ? meta.tool_name : undefined
+    const result = meta.result ?? null
+    const card = meta.card ?? null
+    out.push({
+      type: 'approval-resolved',
+      status,
+      ok: meta.ok === true,
+      willAutoContinue: meta.willAutoContinue === true,
+      ...(toolName ? { toolName } : {}),
+      ...(result ? { result } : {}),
+      ...(card?.marker ? { marker: card.marker } : {}),
+      ...(card?.ref ? { cardRef: card.ref } : {}),
+      ...(card?.type ? { cardType: card.type } : {}),
+      ...(typeof meta.receiptText === 'string' ? { receiptText: meta.receiptText } : {}),
+      requestId: typeof meta.proposalId === 'string' ? meta.proposalId : undefined,
+    })
+  } else if (meta.kind === 'approval_request' && meta.proposalId) {
+    const proposalId = String(meta.proposalId)
+    const toolName = String(meta.toolName ?? 'tool')
+    const headline =
+      typeof meta.title === 'string' && meta.title.length > 0 ? meta.title : toolName
+    const rawFields = Array.isArray(meta.fields)
+      ? (meta.fields as Array<{ label?: string; value?: string }>)
+      : []
+    const fields: Array<{ label: string; value: string }> = []
+    for (const f of rawFields) {
+      if (!f || !f.label || !f.value) continue
+      fields.push({ label: f.label, value: f.value })
+    }
+    out.push({
+      type: 'approval-request',
+      requestId: proposalId,
+      approvalType: toolName,
+      command: headline,
+      fields,
+      status: 'pending',
+    })
+  } else if (meta.kind === 'text-leading' && typeof meta.text === 'string') {
+    out.push({ type: 'text-delta', text: meta.text, leading: true })
+  } else if (meta.kind === 'tool_error') {
+    const msg =
+      typeof meta.message === 'string' && meta.message.length > 0
+        ? meta.message
+        : 'Could not complete the requested action right now.'
+    out.push({ type: 'error', title: msg })
+  } else if (meta.kind === 'routing') {
+    if (typeof meta.routedComplexity === 'string') {
+      out.push({
+        type: 'metadata',
+        routing: {
+          routedComplexity: meta.routedComplexity,
+          ...(typeof meta.routedModel === 'string' ? { routedModel: meta.routedModel } : {}),
+          routedThinkingBudget:
+            typeof meta.routedThinkingBudget === 'number' ? meta.routedThinkingBudget : null,
+        },
+      })
+    }
+  } else {
+    // Catch-all metadata-ish frame. Raw values pass through UNVALIDATED
+    // (possibly undefined) so the consumer can replicate the legacy
+    // presence/truthiness gates exactly — including the `model`-presence
+    // trigger whose value is never stored.
+    out.push({
+      type: 'metadata',
+      sources: meta.sources,
+      refs: meta.refs,
+      provider: meta.provider,
+      modelLabel: meta.modelLabel,
+      modelName: meta.model,
+      contextWindowMaxTokens: meta.contextWindowMaxTokens,
+      scrollAnchor: meta.scrollAnchor,
+      conversationId: meta.conversationId,
+    })
+  }
+}
+
+export function createSseFrameDecoder(): SseFrameDecoder {
+  const textDecoder = new TextDecoder()
+  let buffer = ''
+  let inText = false
+  let inTrailer = false
+  let trailerBuffer = ''
+  let ended = false
+
+  function push(bytes: Uint8Array): ChatStreamEvent[] {
+    const out: ChatStreamEvent[] = []
+    const chunk = textDecoder.decode(bytes, { stream: true })
+
+    if (!inText) {
+      buffer += chunk
+      while (!inText) {
+        const recIdx = buffer.indexOf(END_OF_LEADING)
+        const nullIdx = buffer.indexOf(FRAME_TERMINATOR)
+        if (recIdx !== -1 && (nullIdx === -1 || recIdx < nullIdx)) {
+          inText = true
+          out.push({ type: 'turn-start' })
+          const after = buffer.slice(recIdx + 1)
+          buffer = ''
+          if (after) {
+            // The `after` slice may ALSO contain the `\x1F` trailing-
+            // usage sentinel — common for fixed-answer responses where
+            // the whole frame sequence arrives in ONE TCP chunk.
+            const unitIdx = after.indexOf(TRAILER_SENTINEL)
+            if (unitIdx === -1) {
+              out.push({ type: 'text-delta', text: after })
+            } else {
+              const textBefore = after.slice(0, unitIdx)
+              const trailerAfter = after.slice(unitIdx + 1)
+              if (textBefore) {
+                out.push({ type: 'text-delta', text: textBefore })
+              }
+              inTrailer = true
+              trailerBuffer = trailerAfter
+            }
+          }
+          break
+        }
+        if (nullIdx === -1) break // need more bytes
+        const metaStr = buffer.slice(0, nullIdx)
+        const remaining = buffer.slice(nullIdx + 1)
+        let meta: any
+        try {
+          meta = JSON.parse(metaStr)
+        } catch {
+          // Not JSON — start of answer body. The WHOLE buffer (including
+          // the `\0`) becomes answer text; `implicit` tells consumers
+          // this was the fallback path, not the `\x1E` sentinel.
+          inText = true
+          out.push({ type: 'turn-start', implicit: true })
+          if (buffer.length > 0) {
+            out.push({ type: 'text-delta', text: buffer })
+            buffer = ''
+          }
+          break
+        }
+        mapLeadingFrame(meta, out)
+        buffer = remaining
+      }
+    } else if (inTrailer) {
+      trailerBuffer += chunk
+    } else {
+      // Text mode: only the `\x1F` trailer sentinel is scanned. The
+      // unconditional emit (even for an empty decode of a partial
+      // multi-byte code point) mirrors the legacy per-chunk yield.
+      const sepIdx = chunk.indexOf(TRAILER_SENTINEL)
+      if (sepIdx === -1) {
+        out.push({ type: 'text-delta', text: chunk })
+      } else {
+        const before = chunk.slice(0, sepIdx)
+        const after = chunk.slice(sepIdx + 1)
+        if (before) out.push({ type: 'text-delta', text: before })
+        inTrailer = true
+        trailerBuffer = after
+      }
+    }
+    return out
+  }
+
+  function end(): ChatStreamEvent[] {
+    // Idempotency guard: a second end() must emit NOTHING. The trailer is
+    // also cleared so no later push()/end() pair can replay it.
+    if (ended) return []
+    ended = true
+    const out: ChatStreamEvent[] = []
+    if (trailerBuffer.length > 0) {
+      const raw = trailerBuffer
+      trailerBuffer = ''
+      try {
+        const meta = JSON.parse(raw)
+        if (meta.kind === 'usage' && (meta.stage === 'end' || meta.stage === 'display')) {
+          out.push({
+            type: 'usage',
+            stage: 'end',
+            input_tokens: meta.input_tokens,
+            output_tokens: meta.output_tokens,
+            cache_read_input_tokens: meta.cache_read_input_tokens,
+            cache_creation_input_tokens: meta.cache_creation_input_tokens,
+            hit_rate_pct: meta.hit_rate_pct,
+            telemetry: meta.telemetry,
+            breakdown: meta.breakdown,
+            debug: meta.debug,
+          })
+        }
+      } catch {
+        // Malformed trailer — silently ignore (legacy parity).
+      }
+    }
+    return out
+  }
+
+  return { push, end }
+}