@adia-ai/a2ui-compose 0.0.1

package/engines/zettel/synthesizer.js

@@ -0,0 +1,343 @@
+/**
+ * LLM-powered composition synthesis for zettel.
+ *
+ * When pure retrieval fails (no composition match or weak top score), ask an
+ * LLM to assemble a composition from the fragment catalog. The LLM gets:
+ *   - the intent
+ *   - the fragment catalog (name, semantic_role, shape, slots, description)
+ *   - 2–3 existing compositions as in-context examples
+ *
+ * It must return JSON matching the composition schema — a template array where
+ * nodes either declare a component inline OR reference a fragment via $fragment
+ * with bindings. We validate the output against slots (required bindings present,
+ * fragment names exist) before feeding it to the composer.
+ *
+ * This is the reasoning layer on top of pure retrieval. It turns fragments into
+ * the LLM's typed vocabulary — smaller, more structured than a 97-pattern corpus.
+ */
+
+import { getAllFragments, getAllCompositions } from './fragment-library.js';
+import { resolveComposition, templateToMessages } from './composer.js';
+
+/**
+ * Build a fragment catalog summary for the LLM prompt — name, role, shape,
+ * slot contract, description, AND the internal template so the LLM can inline
+ * the fragment if it needs to edit interior nodes (technique B in the prompt).
+ */
+function buildFragmentCatalog() {
+  const frags = getAllFragments();
+  return frags.map((f) => ({
+    name: f.name,
+    semantic_role: f.semantic_role,
+    shape: f.shape,
+    description: f.description,
+    keywords: f.keywords || [],
+    slots: (f.slots || []).map((s) => ({
+      name: s.name,
+      attribute: s.attribute,
+      required: !!s.required,
+      defaultValue: s.defaultValue,
+      description: s.description,
+    })),
+    template: f.template,
+  }));
+}
+
+/**
+ * Pick 2–3 in-context example compositions. We want variety (different domains)
+ * so the LLM sees the composition shape across intents.
+ */
+function buildExamples(count = 3) {
+  const comps = getAllCompositions();
+  const byDomain = new Map();
+  for (const c of comps) {
+    if (!byDomain.has(c.domain)) byDomain.set(c.domain, c);
+    if (byDomain.size >= count) break;
+  }
+  return [...byDomain.values()].map((c) => ({
+    name: c.name,
+    domain: c.domain,
+    description: c.description,
+    template: c.template,
+  }));
+}
+
+const SYSTEM_PROMPT = `You are a UI composer. Given a user intent, you assemble a UI composition from a catalog of reusable fragments.
+
+⚠️ ABSOLUTE OUTPUT CONTRACT ⚠️
+Your ENTIRE response must be a single JSON object. No prose before or after. No clarifying
+questions. No "I'll add..." narration. No markdown fences. Just JSON.
+If a user request is ambiguous, make a best-guess decision and emit the JSON. Never ask.
+
+A composition is a flat-adjacency array of A2UI nodes. Each node either:
+  (a) declares a component inline:
+      { "id": "foo", "component": "Column", "children": ["a","b"], "gap": "3" }
+  (b) references a fragment by name with slot bindings:
+      { "id": "foo", "$fragment": "labeled-input",
+        "bindings": { "label": "Email", "name": "email", "type": "email" } }
+
+Rules:
+  1. Exactly one root node with id "root". Other nodes reference it via children arrays.
+  2. Every $fragment ref must name a fragment that exists in the catalog. Never invent fragment names.
+  3. Every required slot on a referenced fragment MUST appear in bindings.
+  4. Prefer fragments over inline nodes when an atom fits — they carry semantics and reuse.
+  5. Use inline nodes (Column/Row/Card/Section/Text/Button/etc.) for layout, glue, and gaps between fragments.
+  6. Keep compositions compact — 6 to 15 nodes is typical. Don't over-engineer.
+
+EXTENDING FRAGMENTS — four techniques when a fragment almost fits but needs more.
+STRONGLY PREFER technique (A) for "add X above/below the heading" requests — those
+are structurally OUTSIDE the header slot grid, not inside it.
+
+  A) Place content ABOVE/BELOW a fragment (outside it — MOST ROBUST).
+     When the user says "add a logo above the heading" in a form, place a new node
+     BEFORE the header fragment at the composition root:
+       { "id": "root", "component": "Card", "children": ["brand", "hdr", "sec", "ftr"] }
+       { "id": "brand", "component": "Row", "children": ["logo"], "justify": "center" }
+       { "id": "logo", "component": "Image", "src": "/logo.svg", "alt": "Brand" }
+       { "id": "hdr", "$fragment": "card-header-with-description", "bindings": { … } }
+     ⚠️ BUT: Card direct children are restricted to <header>, <section>, <footer>.
+     For logos above the header, prefer technique B (inline the header) OR slot
+     the logo into the header with slot="icon" via technique C.
+
+  B) Inject extra children INTO a fragment's root WITH a slot declaration.
+     A $fragment node can declare prependChildren or appendChildren (arrays of node
+     ids). Injected children should declare slot="…" when the host uses slot-grid
+     layout. Example — add a logo to a card-header:
+       { "id": "hdr", "$fragment": "card-header-with-description",
+         "bindings": { "heading": "Sign in", "description": "..." },
+         "prependChildren": ["logo"] }
+       { "id": "logo", "component": "Image", "src": "/logo.svg", "alt": "Brand",
+         "slot": "icon" }
+     Common host slots:
+       - Card <header>:   icon | heading | description | action
+       - Card <section>:  (default)
+       - Card <footer>:   (default)
+     Without a slot attribute, children flow to the default slot and may not lay
+     out as expected on slot-grid hosts.
+
+  C) Inline the fragment (when you need to edit INTERIOR nodes or restructure the
+     layout). Copy the fragment's own template nodes into your composition with
+     fresh ids. Bindings and slot indirection go away. Each fragment in the catalog
+     below shows its internal template so you know what to copy. Inlined nodes lose
+     reuse; use only when (A) and (B) can't solve the problem.
+
+  D) Compose fragments side by side (two fragments together make the shape).
+     Place multiple $fragment refs as siblings inside a layout node.
+
+When HISTORY is provided, the user is building on PRIOR turns. You MUST:
+  - Treat the latest turn's template as the starting point.
+  - Apply the user's new instruction as a MODIFICATION to that template (add, remove, replace, or edit bindings on existing nodes).
+  - Preserve node ids from the prior template wherever possible so the canvas edits look incremental, not regenerated from scratch.
+  - For additive requests inside a fragment ("add X"), prefer technique (B) WITH a slot declaration matching the host's slot vocabulary. If the host has no matching slot, fall back to (C) inlining.
+  - For structural/interior edits, use technique (C) inlining.
+  - Only generate a fully fresh template if the new intent is clearly a topic change.
+
+Return ONLY a JSON object: { "template": [...nodes] }. No prose, no markdown fences.`;
+
+function buildUserPrompt(intent, fragmentCatalog, examples, historySummary = null) {
+  const fragLines = fragmentCatalog.map((f) => {
+    const slotStr = f.slots.length
+      ? f.slots.map((s) => `${s.name}${s.required ? '*' : ''}`).join(', ')
+      : '(no slots)';
+    // Compact template skeleton for technique (B) — ids + component types only
+    const tpl = (f.template || []).map((n) => {
+      const bits = { id: n.id, component: n.component };
+      if (n.children) bits.children = n.children;
+      return bits;
+    });
+    return `  - ${f.name} [${f.semantic_role}] — ${f.description}
+    slots: ${slotStr}
+    template: ${JSON.stringify(tpl)}`;
+  }).join('\n');
+
+  const exLines = examples.map((ex) => {
+    return `--- example: ${ex.name} (${ex.domain}) ---\n${ex.description}\n${JSON.stringify({ template: ex.template }, null, 2)}`;
+  }).join('\n\n');
+
+  const historyBlock = historySummary
+    ? `\nHISTORY (most recent turn last — build on this):\n${historySummary}\n\n`
+    : '\n';
+
+  return `INTENT: ${intent}
+${historyBlock}FRAGMENT CATALOG:
+${fragLines}
+
+EXAMPLES:
+${exLines}
+
+Compose a UI for the intent. If HISTORY is present, build on the latest turn's template. Return { "template": [...] } only.`;
+}
+
+/**
+ * Extract the FIRST top-level JSON object from a possibly-messy LLM response.
+ * Handles markdown fences and leading/trailing prose.
+ */
+function extractJSON(text) {
+  if (!text) return null;
+  // Strip markdown fences
+  let t = text.trim();
+  const fence = t.match(/^```(?:json)?\s*([\s\S]*?)```$/m);
+  if (fence) t = fence[1].trim();
+  // Find first { and its matching }
+  const start = t.indexOf('{');
+  if (start === -1) return null;
+  let depth = 0;
+  let inStr = false;
+  let esc = false;
+  for (let i = start; i < t.length; i++) {
+    const c = t[i];
+    if (esc) { esc = false; continue; }
+    if (c === '\\') { esc = true; continue; }
+    if (c === '"') { inStr = !inStr; continue; }
+    if (inStr) continue;
+    if (c === '{') depth++;
+    else if (c === '}') {
+      depth--;
+      if (depth === 0) {
+        try { return JSON.parse(t.slice(start, i + 1)); } catch { return null; }
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Validate a synthesized template before we try to resolve it. Returns
+ * { ok: true, errors: [] } or { ok: false, errors: [msg, ...] }.
+ */
+function validateSynthesis(template, fragmentsByName) {
+  const errors = [];
+  if (!Array.isArray(template) || template.length === 0) {
+    return { ok: false, errors: ['template is empty or not an array'] };
+  }
+  const root = template.find((n) => n.id === 'root');
+  if (!root) errors.push('no node with id "root"');
+
+  const ids = new Set(template.map((n) => n.id).filter(Boolean));
+  for (const node of template) {
+    if (!node.id) errors.push('node is missing id');
+    if (node.$fragment) {
+      const frag = fragmentsByName.get(node.$fragment);
+      if (!frag) {
+        errors.push(`unknown $fragment: ${node.$fragment} (node ${node.id})`);
+        continue;
+      }
+      const bindings = node.bindings || {};
+      for (const slot of frag.slots || []) {
+        if (slot.required && !(slot.name in bindings) && slot.defaultValue === undefined) {
+          errors.push(`missing required binding "${slot.name}" on fragment ${node.$fragment} (node ${node.id})`);
+        }
+      }
+    } else if (node.component) {
+      // Inline node — children refs must resolve
+      const childArrays = [
+        node.children,
+      ];
+      for (const arr of childArrays) {
+        if (Array.isArray(arr)) {
+          for (const c of arr) {
+            if (typeof c === 'string' && !ids.has(c)) {
+              errors.push(`child "${c}" on node "${node.id}" does not resolve`);
+            }
+          }
+        }
+      }
+    } else {
+      errors.push(`node "${node.id}" has neither $fragment nor component`);
+    }
+    // prependChildren / appendChildren on fragment refs must resolve too
+    for (const key of ['prependChildren', 'appendChildren']) {
+      const arr = node[key];
+      if (!Array.isArray(arr)) continue;
+      for (const c of arr) {
+        if (typeof c === 'string' && !ids.has(c)) {
+          errors.push(`${key} ref "${c}" on node "${node.id}" does not resolve`);
+        }
+      }
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * Main entry: synthesize a composition from an intent using an LLM.
+ *
+ * @param {object} opts
+ * @param {string} opts.intent
+ * @param {object} opts.llmAdapter — must expose `complete({ messages, systemPrompt })`
+ * @param {string} [opts.historySummary] — optional prior-turn context (see session-store.js)
+ * @param {number} [opts.maxAttempts=2] — retry with feedback on validation failure
+ * @returns {Promise<{ template: Array, messages: Array, synthesis: object }>}
+ *          `synthesis` contains llmRawResponse, attempts, finalValidation for debugging.
+ */
+export async function synthesizeComposition({ intent, llmAdapter, historySummary = null, maxAttempts = 3 }) {
+  if (!llmAdapter?.complete) {
+    throw new Error('synthesizeComposition requires an llmAdapter with .complete()');
+  }
+
+  const fragmentCatalog = buildFragmentCatalog();
+  const fragmentsByName = new Map(getAllFragments().map((f) => [f.name, f]));
+  const examples = buildExamples(3);
+
+  const userPrompt = buildUserPrompt(intent, fragmentCatalog, examples, historySummary);
+  let lastError = null;
+  const attempts = [];
+
+  for (let i = 0; i < maxAttempts; i++) {
+    const retryNudge = lastError
+      ? `\n\nPREVIOUS ATTEMPT FAILED: ${lastError}. Return ONLY a JSON object shaped as { "template": [...] }. No prose, no questions, no clarifications — just JSON.`
+      : '';
+    const messages = [{ role: 'user', content: userPrompt + retryNudge }];
+    const response = await llmAdapter.complete({ messages, systemPrompt: SYSTEM_PROMPT });
+    const raw = response?.content || response?.text || (typeof response === 'string' ? response : '');
+    attempts.push({ attempt: i + 1, raw });
+
+    const parsed = extractJSON(raw);
+    if (!parsed || !Array.isArray(parsed.template)) {
+      // Detect prose / clarification-style responses specifically
+      const isProse = /^(I['’]ll |Sure|Certainly|To do this|Here's)/i.test(raw.trim());
+      lastError = isProse
+        ? 'Response was conversational prose, not JSON. Do not ask questions. Emit the composition directly with your best-guess defaults.'
+        : 'Response was not valid JSON with a template array.';
+      continue;
+    }
+
+    const { ok, errors } = validateSynthesis(parsed.template, fragmentsByName);
+    if (!ok) {
+      lastError = errors.slice(0, 3).join('; ');
+      continue;
+    }
+
+    // Resolve via the composer
+    try {
+      const resolved = resolveComposition({ template: parsed.template });
+      const messagesOut = [{
+        type: 'updateComponents',
+        components: resolved.map((n) => {
+          const {
+            id, component, children,
+            $fragment, bindings,
+            prependChildren, appendChildren,
+            ...rest
+          } = n;
+          return { id, component, children: children || [], ...rest };
+        }),
+      }];
+      return {
+        template: parsed.template,
+        messages: messagesOut,
+        synthesis: {
+          attempts: i + 1,
+          attemptsLog: attempts,
+          validation: { ok: true, errors: [] },
+          usedHistory: !!historySummary,
+        },
+      };
+    } catch (e) {
+      lastError = `Composer failed to resolve: ${e.message}`;
+    }
+  }
+
+  throw new Error(`Synthesis failed after ${maxAttempts} attempts: ${lastError}`);
+}

package/evals/harness.mjs

@@ -0,0 +1,193 @@
+/**
+ * Generator-agnostic eval harness.
+ *
+ * Contract (generator return):
+ *   {
+ *     messages?:   Array,                // A2UI messages (may be empty)
+ *     validation?: { score: number },    // 0-100 (or absent)
+ *     strategy?:   string,               // architecture-specific label
+ *     retrieval?:  {                     // optional retrieval metadata
+ *       hit: boolean,                    // top result considered relevant
+ *       rank: number|null,               // 1-indexed rank of first relevant candidate
+ *       candidate: string|null,          // name of chosen pattern/composition
+ *     },
+ *     fragments_used?: string[],         // zettel-only
+ *     ...extra
+ *   }
+ *
+ * Two runners:
+ *   - runHarness()   legacy shape — preserved byte-for-byte for back-compat
+ *   - runHarnessV2() augmented shape — coverage / avgScoreWhenEmitted /
+ *                    retrievalMRR / per-intent strategy & fragment data
+ */
+import { readFile } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export async function loadHeldOut() {
+  // held-out.jsonl lives in the sibling @adia-ai/a2ui-corpus package.
+  // Callers can still pass `intents` explicitly; this fallback is the default.
+  // Path from here: packages/a2ui/compose/evals/ → ../.. → packages/a2ui/
+  // → corpus/evals/held-out.jsonl.
+  const evalsPath = join(__dirname, '..', '..', 'corpus', 'evals', 'held-out.jsonl');
+  const raw = await readFile(evalsPath, 'utf8');
+  return raw.trim().split('\n').map((l) => JSON.parse(l));
+}
+
+function computeF1(result, evalItem) {
+  // Handle both message shapes:
+  //   mcp:    [{ components: [{ component: 'Card', ... }] }]
+  //   zettel: [{ messageType: 'beginComponent', componentType: 'Card', ... }]
+  const msgs = result.messages || [];
+  const types = new Set();
+  for (const m of msgs) {
+    if (Array.isArray(m.components)) {
+      for (const c of m.components) if (c.component) types.add(c.component);
+    }
+    if (m.componentType) types.add(m.componentType);
+  }
+  const expected = new Set(evalItem.expected_components || []);
+  const tp = [...expected].filter((t) => types.has(t)).length;
+  const precision = types.size ? tp / types.size : 0;
+  const recall = expected.size ? tp / expected.size : 0;
+  const f1 = precision + recall > 0 ? (2 * precision * recall) / (precision + recall) : 0;
+  return { precision, recall, f1 };
+}
+
+// ── Legacy runner (byte-compat with pre-2026-04-17 inline code) ──
+
+export async function runHarness({ generate, domain, limit, mode = 'instant', intents }) {
+  let items = intents || (await loadHeldOut());
+  if (domain) items = items.filter((i) => i.domain === domain);
+  if (limit) items = items.slice(0, limit);
+
+  const results = [];
+  for (const evalItem of items) {
+    try {
+      const result = await generate({ intent: evalItem.intent, mode });
+      const score = result.validation?.score || 0;
+      const { f1 } = computeF1(result, evalItem);
+      results.push({
+        id: evalItem.id,
+        intent: evalItem.intent,
+        score,
+        f1: Math.round(f1 * 100),
+        pass: score >= (evalItem.expected_validation_min || 70),
+      });
+    } catch (e) {
+      results.push({
+        id: evalItem.id,
+        intent: evalItem.intent,
+        score: 0,
+        f1: 0,
+        pass: false,
+        error: e.message,
+      });
+    }
+  }
+
+  const passCount = results.filter((r) => r.pass).length;
+  const avgScore = Math.round(
+    results.reduce((s, r) => s + r.score, 0) / (results.length || 1),
+  );
+  return {
+    total: results.length,
+    pass: passCount,
+    avgScore,
+    passRate: Math.round((passCount / (results.length || 1)) * 100),
+    results,
+  };
+}
+
+// ── V2 runner (coverage-aware, architecture-fair) ──
+
+export async function runHarnessV2({ generate, domain, limit, mode = 'instant', intents, label = 'generator' }) {
+  let items = intents || (await loadHeldOut());
+  if (domain) items = items.filter((i) => i.domain === domain);
+  if (limit) items = items.slice(0, limit);
+
+  const results = [];
+  for (const evalItem of items) {
+    const row = {
+      id: evalItem.id,
+      intent: evalItem.intent,
+      domain: evalItem.domain,
+      strategy: null,
+      messagesEmitted: false,
+      validationScore: null,
+      precision: null,
+      recall: null,
+      componentF1: null,
+      retrievalHit: null,
+      retrievalRank: null,
+      candidate: null,
+      fragmentsUsed: null,
+      pass: false,
+      error: null,
+    };
+    try {
+      const result = await generate({ intent: evalItem.intent, mode });
+      const emitted = Array.isArray(result.messages) && result.messages.length > 0;
+      row.messagesEmitted = emitted;
+      row.strategy = result.strategy || (emitted ? 'emitted' : 'miss');
+      if (emitted) {
+        row.validationScore = result.validation?.score ?? null;
+        const { precision, recall, f1 } = computeF1(result, evalItem);
+        row.precision = Math.round(precision * 100);
+        row.recall = Math.round(recall * 100);
+        row.componentF1 = Math.round(f1 * 100);
+        row.pass = (row.validationScore ?? 0) >= (evalItem.expected_validation_min || 70);
+      }
+      if (result.retrieval) {
+        row.retrievalHit = !!result.retrieval.hit;
+        row.retrievalRank = result.retrieval.rank ?? null;
+        row.candidate = result.retrieval.candidate ?? null;
+      }
+      if (Array.isArray(result.fragments_used)) {
+        row.fragmentsUsed = result.fragments_used;
+      }
+    } catch (e) {
+      row.error = e.message;
+    }
+    results.push(row);
+  }
+
+  // ── Aggregates ──
+  const emitted = results.filter((r) => r.messagesEmitted);
+  const coverage = results.length ? emitted.length / results.length : 0;
+  const avgScoreWhenEmitted = emitted.length
+    ? emitted.reduce((s, r) => s + (r.validationScore || 0), 0) / emitted.length
+    : 0;
+  const avgF1WhenEmitted = emitted.length
+    ? emitted.reduce((s, r) => s + (r.componentF1 || 0), 0) / emitted.length
+    : 0;
+  const passCount = results.filter((r) => r.pass).length;
+
+  // Mean reciprocal rank over intents with retrieval metadata
+  const withRetrieval = results.filter((r) => r.retrievalRank != null);
+  const retrievalMRR = withRetrieval.length
+    ? withRetrieval.reduce((s, r) => s + 1 / r.retrievalRank, 0) / withRetrieval.length
+    : null;
+
+  const strategyBreakdown = results.reduce((acc, r) => {
+    const k = r.strategy || 'unknown';
+    acc[k] = (acc[k] || 0) + 1;
+    return acc;
+  }, {});
+
+  return {
+    label,
+    total: results.length,
+    coverage: Math.round(coverage * 100),        // % intents that emitted
+    emitted: emitted.length,
+    pass: passCount,
+    passRate: Math.round((passCount / (results.length || 1)) * 100),
+    avgScoreWhenEmitted: Math.round(avgScoreWhenEmitted),
+    avgF1WhenEmitted: Math.round(avgF1WhenEmitted),
+    retrievalMRR: retrievalMRR == null ? null : Math.round(retrievalMRR * 1000) / 1000,
+    strategyBreakdown,
+    results,
+  };
+}

package/index.js

@@ -0,0 +1,16 @@
+/**
+ * @adia-ai/a2ui-compose — main entry.
+ *
+ * Re-exports the most common consumer surface. For deeper access, reach
+ * via subpaths:
+ *
+ *   import { generateUI }      from '@adia-ai/a2ui-compose';
+ *   import { pick, registerEngine } from '@adia-ai/a2ui-compose/engines/registry';
+ *   import { generateZettel }  from '@adia-ai/a2ui-compose/engines/zettel';
+ *   import { llmBridge }       from '@adia-ai/a2ui-compose/llm';
+ *
+ * See README for the full public surface.
+ */
+
+export { generateUI, generateUIStream } from './engine/generator.js';
+export { pick, listEngines, registerEngine, unregisterEngine, ENGINES } from './engines/registry.js';

package/llm/adapters/anthropic.js

@@ -0,0 +1,106 @@
+/**
+ * Anthropic Messages API adapter.
+ * Endpoint: https://api.anthropic.com/v1/messages
+ */
+
+import { readSSE } from './sse.js';
+
+const API_URL = 'https://api.anthropic.com/v1/messages';
+const API_VERSION = '2023-06-01';
+const DEFAULT_MAX_TOKENS = 4096;
+
+export const anthropic = {
+  name: 'anthropic',
+
+  buildRequest(opts) {
+    const body = {
+      model: opts.model,
+      max_tokens: opts.maxTokens || DEFAULT_MAX_TOKENS,
+      messages: opts.messages,
+      stream: !!opts.stream,
+    };
+    if (opts.system) {
+      // Prompt caching: the AdiaUI system prompt is ~23KB and constant across
+      // a session. Emitting it as a cached block marks it as a cache breakpoint
+      // (ephemeral, ~5 min TTL). First call = cache write (+25% cost), every
+      // subsequent call in the window = cache read (−90% cost). No-op below
+      // the model's minimum cacheable size (1024 tok Sonnet/Opus, 2048 Haiku).
+      body.system = opts.cache
+        ? [{ type: 'text', text: opts.system, cache_control: { type: 'ephemeral' } }]
+        : opts.system;
+    }
+    if (opts.temperature != null) body.temperature = opts.temperature;
+    if (opts.thinking) {
+      body.thinking = { type: 'enabled', budget_tokens: opts.thinkingBudget || 10000 };
+    }
+
+    return {
+      url: opts.proxyUrl || API_URL,
+      headers: {
+        'content-type': 'application/json',
+        'x-api-key': opts.apiKey,
+        'anthropic-version': API_VERSION,
+      },
+      body,
+    };
+  },
+
+  parseResponse(data) {
+    const text = data.content?.find(b => b.type === 'text')?.text ?? '';
+    return {
+      text,
+      usage: {
+        input: data.usage?.input_tokens ?? 0,
+        output: data.usage?.output_tokens ?? 0,
+        // Cache telemetry: non-zero cacheRead on turn 2+ is the signal that
+        // caching is actually kicking in. Recorded per-turn for hit-rate analysis.
+        cacheCreation: data.usage?.cache_creation_input_tokens ?? 0,
+        cacheRead: data.usage?.cache_read_input_tokens ?? 0,
+      },
+      stopReason: data.stop_reason ?? 'end',
+    };
+  },
+
+  async *parseStream(response) {
+    let snapshot = '';
+    let usage = { input: 0, output: 0, cacheCreation: 0, cacheRead: 0 };
+    let stopReason = 'end';
+
+    for await (const event of readSSE(response.body)) {
+      if (event.done) break;
+      let data;
+      try { data = JSON.parse(event.data); } catch { continue; }
+      const eventType = event.event ?? data.type;
+
+      switch (eventType) {
+        case 'message_start':
+          if (data.message?.usage) {
+            usage.input = data.message.usage.input_tokens ?? 0;
+            usage.cacheCreation = data.message.usage.cache_creation_input_tokens ?? 0;
+            usage.cacheRead = data.message.usage.cache_read_input_tokens ?? 0;
+          }
+          break;
+        case 'content_block_delta': {
+          const delta = data.delta;
+          if (delta?.type === 'text_delta') {
+            snapshot += delta.text;
+            yield { type: 'text', text: delta.text, snapshot };
+          } else if (delta?.type === 'thinking_delta') {
+            yield { type: 'thinking', text: delta.thinking };
+          }
+          break;
+        }
+        case 'message_delta':
+          if (data.delta?.stop_reason) stopReason = data.delta.stop_reason;
+          if (data.usage) usage.output = data.usage.output_tokens ?? 0;
+          break;
+        case 'message_stop':
+          yield { type: 'done', text: snapshot, usage, stopReason };
+          break;
+        case 'error':
+          yield { type: 'error', error: new Error(data.error?.message ?? 'Stream error') };
+          break;
+      }
+    }
+  },
+};