@adia-ai/llm 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -8,6 +8,62 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 _No pending changes._
 
+## [0.3.3] - 2026-05-07
+
+**Lockstep cut.** All 9 published `@adia-ai/*` packages now share version `0.3.3`, governed by [`docs/specs/package-architecture.md` § 15](../../../docs/specs/package-architecture.md#15-versioning-policy). Internal `@adia-ai/*` ranges stay at `^0.3.0` (patch-cut asymmetry — caret floats `0.3.x`).
+
+### Fixed
+
+- **Browser proxy 401 in passthrough mode** (`c639bda8`, post-v0.3.2).
+  `chat()` and `streamChat()` always routed `proxyUrl` through
+  `proxyRequest()` which sends a provider-neutral body — that contract
+  fits the smart proxy at `packages/llm/server.js` but breaks the
+  Vite-dev passthrough proxy (`/api/llm/<provider>/<rest>` → real
+  upstream URL), which expects the adapter's real upstream body shape
+  + auth headers. Added `isPassthroughProxy(proxyUrl)` URL-shape
+  detection (regex `/\/api\/llm\/[a-z]+(\/|$)/`) and a new
+  `passthroughRequest()` that calls `adapter.buildRequest()` (real
+  upstream body + adapter auth) with the URL replaced. Smart-proxy
+  routes continue to use `proxyRequest()`. Documented in
+  `packages/llm/README.md` § Browser proxy mode.
+
+### Documentation
+
+- README expanded to document the dual-proxy architecture (smart vs.
+  passthrough), with side-by-side comparison table and Vite-proxy
+  example for the passthrough case (`b00542d7`).
+
+### Tests
+
+- **86 unit tests landed** across 6 files (closes backlog #15 — the
+  package previously had zero coverage):
+  - `models.test.js` (7) — MODELS shape contract that 3 apps depend on
+  - `adapters/router.test.js` (26) — detectProvider, isPassthroughProxy,
+    smart-proxy vs passthrough dispatch, error paths
+  - `adapters/build-request.test.js` (28) — anthropic prompt-cache,
+    thinking budget, openai system-prepend, gemini systemInstruction +
+    role:assistant→model + endpoint switching
+  - `adapters/sse.test.js` (13) — partial-line buffering, double-newline
+    splits across chunk boundaries, [DONE] sentinel, \\r\\n line endings
+  - `adapters/client.test.js` (4) — createClient defaults + override
+  - `llm-stub.test.js` (8) — StubLLMAdapter contract for free-tier evals
+- New `npm run test:llm` script for package-scoped runs.
+
+## [0.3.2] - 2026-05-06
+
+**9-package lockstep patch cut to v0.3.2.** All lockstep members share
+one version per [`docs/specs/package-architecture.md` § 15](../../docs/specs/package-architecture.md#15-versioning-policy).
+Internal `@adia-ai/*` dep ranges unchanged at `^0.3.0`.
+
+### No source changes
+
+This package's source is byte-identical to v0.3.1. The cut bumps
+version only.
+
+### Changed
+
+- `version`: `0.3.1` → `0.3.2`.
+
 ## [0.3.1] - 2026-05-06
 
 **9-package lockstep patch cut.** All 9 published `@adia-ai/*` packages bump 0.3.0 → 0.3.1 per [`docs/specs/package-architecture.md` § 15](../../docs/specs/package-architecture.md#15-versioning-policy). Internal `@adia-ai/*` dep ranges remain at `^0.3.0` (covers `0.3.1` under semver — patch-cut asymmetry).

package/README.md

@@ -25,8 +25,16 @@ for await (const chunk of streamChat({
 
 ## Browser proxy mode
 
-Pass `proxyUrl` to route through your server-side proxy (which holds the
-API key). The client speaks a provider-neutral protocol to the proxy:
+`proxyUrl` routes through a server-side proxy so the API key never
+reaches the browser. The client supports **two proxy shapes** and
+auto-detects which to use based on the URL:
+
+### Smart proxy (provider-neutral body)
+
+The default. Send any `proxyUrl` that doesn't match the passthrough
+pattern below — typically your own backend route like `/api/chat`. The
+client speaks a single provider-neutral protocol; the proxy holds the
+API key and dispatches internally to the right upstream adapter.
 
 ```js
 for await (const chunk of streamChat({
@@ -51,9 +59,69 @@ The body sent to the proxy:
 }
 ```
 
-The proxy reformats per upstream provider and pipes the SSE bytes
-verbatim. The reference proxy implementation is at `server.js` in the
-chat-ui repo root.
+The proxy reformats per upstream provider and pipes SSE bytes
+verbatim. The reference smart-proxy implementation is at
+`packages/llm/server.js` in the chat-ui repo (route: `POST /api/chat`,
+plus `/api/generate`, `/api/generate/reset`, `/api/convert-html` for
+the A2UI generation pipeline). It is **not** shipped with the npm
+package — it's a development convenience for the in-repo apps.
+
+### Passthrough proxy (real upstream body)
+
+When `proxyUrl` matches `/api/llm/<provider>/<rest>` (the Vite-dev
+shape used by `chat-ui` apps), the client switches to passthrough
+mode. The proxy is "dumb" — it just rewrites the URL to the real
+upstream (`https://api.<provider>.com/<rest>`) and forwards bytes
+unchanged. The client sends the **real upstream body shape** plus the
+adapter's normal auth headers.
+
+This is auto-detected — you don't pick it explicitly. If you mounted
+a Vite proxy like:
+
+```js
+// vite.config.js
+server: {
+  proxy: {
+    '/api/llm/anthropic': {
+      target: 'https://api.anthropic.com',
+      rewrite: (p) => p.replace(/^\/api\/llm\/anthropic/, ''),
+    },
+  },
+},
+```
+
+…then passing `proxyUrl: '/api/llm/anthropic/v1/messages'` will
+produce a request the upstream understands directly.
+
+| Shape | URL pattern | Body | Auth header | Use when |
+|---|---|---|---|---|
+| Smart | `/api/chat` (anything non-passthrough) | provider-neutral | none (server holds key) | You control the proxy and want one route across providers |
+| Passthrough | `/api/llm/<provider>/<rest>` | real upstream shape | adapter's own (e.g. `x-api-key`) | You're using Vite/nginx URL-rewrite and don't want server-side dispatch |
+
+Detection lives in `adapters/index.js` — regex
+`/\/api\/llm\/[a-z]+(\/|$)/`.
+
+### Production deployment
+
+Neither `server.js` (smart proxy reference) nor any Vite/nginx URL
+rewrite (passthrough reference) is shipped by the npm package — both
+are development-time conveniences for the in-repo apps. Production
+consumers must **deploy their own proxy**: a small server that holds
+your provider API key(s) and either:
+
+1. **Speaks the smart-proxy contract** — accepts the provider-neutral
+   body documented above and dispatches per-provider. See
+   `packages/llm/server.js` for a reference implementation (Express +
+   `chat`/`streamChat` from this package, ~150 LOC).
+2. **Speaks the passthrough contract** — exposes
+   `/api/llm/<provider>/<rest>` and forwards to
+   `https://api.<provider>.com/<rest>` with the real API-key header
+   injected server-side. See the Vite config snippet above for the
+   shape; a 50-line nginx or Express proxy works fine.
+
+Either contract works — the client auto-detects which one your proxy
+implements by URL shape. Pick the one that matches your existing
+infrastructure.
 
 ## Subpath exports
 

package/adapters/build-request.test.js

@@ -0,0 +1,258 @@
+/**
+ * Adapter buildRequest contracts — the per-provider body/header shapes.
+ *
+ * These are the boundaries the bridge depends on (exposed via passthroughRequest()
+ * and as the source of truth for direct-mode requests). Regression-test the
+ * subtle defaults the README + skill claim:
+ *   - Anthropic: max_tokens defaulted, prompt-cache when opts.cache=true
+ *   - OpenAI: stream_options when streaming, system → first message
+ *   - Gemini: API key in URL, role 'model' for assistant
+ */
+
+import { describe, it, expect } from 'vitest';
+import { anthropic } from '../adapters/anthropic.js';
+import { openai } from '../adapters/openai.js';
+import { gemini } from '../adapters/gemini.js';
+
+describe('anthropic.buildRequest', () => {
+  it('returns the canonical Anthropic Messages endpoint', () => {
+    const r = anthropic.buildRequest({ apiKey: 'sk-ant', model: 'claude-haiku-4-5', messages: [] });
+    expect(r.url).toBe('https://api.anthropic.com/v1/messages');
+  });
+
+  it('sets x-api-key + anthropic-version + content-type headers', () => {
+    const r = anthropic.buildRequest({ apiKey: 'sk-ant-key', model: 'claude-haiku-4-5', messages: [] });
+    expect(r.headers['x-api-key']).toBe('sk-ant-key');
+    expect(r.headers['anthropic-version']).toBeTruthy();
+    expect(r.headers['content-type']).toBe('application/json');
+  });
+
+  it('defaults max_tokens to a non-zero value', () => {
+    // The README + skill assert a default. Regress if someone removes it.
+    const r = anthropic.buildRequest({ apiKey: 'k', model: 'claude-haiku-4-5', messages: [] });
+    expect(r.body.max_tokens).toBeGreaterThan(0);
+  });
+
+  it('caller-supplied maxTokens overrides default', () => {
+    const r = anthropic.buildRequest({ apiKey: 'k', model: 'claude-haiku-4-5', messages: [], maxTokens: 4096 });
+    expect(r.body.max_tokens).toBe(4096);
+  });
+
+  it('omits system when not provided', () => {
+    const r = anthropic.buildRequest({ apiKey: 'k', model: 'claude-haiku-4-5', messages: [] });
+    expect(r.body).not.toHaveProperty('system');
+  });
+
+  it('passes plain string system when cache=false (default)', () => {
+    const r = anthropic.buildRequest({
+      apiKey: 'k',
+      model: 'claude-haiku-4-5',
+      messages: [],
+      system: 'You are helpful.',
+    });
+    expect(r.body.system).toBe('You are helpful.');
+  });
+
+  it('wraps system in cache-control block when cache=true', () => {
+    const r = anthropic.buildRequest({
+      apiKey: 'k',
+      model: 'claude-haiku-4-5',
+      messages: [],
+      system: 'You are helpful.',
+      cache: true,
+    });
+    expect(Array.isArray(r.body.system)).toBe(true);
+    expect(r.body.system[0]).toMatchObject({
+      type: 'text',
+      text: 'You are helpful.',
+      cache_control: { type: 'ephemeral' },
+    });
+  });
+
+  it('emits thinking config when opts.thinking=true', () => {
+    const r = anthropic.buildRequest({
+      apiKey: 'k',
+      model: 'claude-sonnet-4-6',
+      messages: [],
+      thinking: true,
+    });
+    expect(r.body.thinking).toMatchObject({ type: 'enabled' });
+    expect(r.body.thinking.budget_tokens).toBeGreaterThan(0);
+  });
+
+  it('respects custom thinkingBudget', () => {
+    const r = anthropic.buildRequest({
+      apiKey: 'k',
+      model: 'claude-sonnet-4-6',
+      messages: [],
+      thinking: true,
+      thinkingBudget: 25000,
+    });
+    expect(r.body.thinking.budget_tokens).toBe(25000);
+  });
+
+  it('reflects stream:true in body', () => {
+    const r = anthropic.buildRequest({ apiKey: 'k', model: 'claude-haiku-4-5', messages: [], stream: true });
+    expect(r.body.stream).toBe(true);
+  });
+});
+
+describe('anthropic.parseResponse', () => {
+  it('extracts text + usage + stopReason', () => {
+    const out = anthropic.parseResponse({
+      content: [{ type: 'text', text: 'hello' }],
+      usage: { input_tokens: 10, output_tokens: 5 },
+      stop_reason: 'end_turn',
+    });
+    expect(out.text).toBe('hello');
+    expect(out.usage.input).toBe(10);
+    expect(out.usage.output).toBe(5);
+    expect(out.stopReason).toBe('end_turn');
+  });
+
+  it('records cache telemetry (cacheCreation, cacheRead) when present', () => {
+    const out = anthropic.parseResponse({
+      content: [{ type: 'text', text: 'x' }],
+      usage: {
+        input_tokens: 100,
+        output_tokens: 5,
+        cache_creation_input_tokens: 80,
+        cache_read_input_tokens: 0,
+      },
+      stop_reason: 'end_turn',
+    });
+    expect(out.usage.cacheCreation).toBe(80);
+    expect(out.usage.cacheRead).toBe(0);
+  });
+
+  it('defaults cache telemetry to 0 when absent (back-compat)', () => {
+    const out = anthropic.parseResponse({
+      content: [{ type: 'text', text: 'x' }],
+      usage: { input_tokens: 1, output_tokens: 1 },
+      stop_reason: 'end_turn',
+    });
+    expect(out.usage.cacheCreation).toBe(0);
+    expect(out.usage.cacheRead).toBe(0);
+  });
+
+  it('returns empty text when content is missing', () => {
+    const out = anthropic.parseResponse({ usage: {}, stop_reason: 'end_turn' });
+    expect(out.text).toBe('');
+  });
+});
+
+describe('openai.buildRequest', () => {
+  it('targets the Chat Completions endpoint with Bearer auth', () => {
+    const r = openai.buildRequest({ apiKey: 'sk-key', model: 'gpt-4o', messages: [] });
+    expect(r.url).toBe('https://api.openai.com/v1/chat/completions');
+    expect(r.headers.authorization).toBe('Bearer sk-key');
+  });
+
+  it('prepends system as the first message (OpenAI shape)', () => {
+    const r = openai.buildRequest({
+      apiKey: 'k',
+      model: 'gpt-4o',
+      messages: [{ role: 'user', content: 'hi' }],
+      system: 'You are concise.',
+    });
+    expect(r.body.messages[0]).toEqual({ role: 'system', content: 'You are concise.' });
+    expect(r.body.messages[1]).toEqual({ role: 'user', content: 'hi' });
+  });
+
+  it('does NOT prepend system when omitted', () => {
+    const r = openai.buildRequest({
+      apiKey: 'k',
+      model: 'gpt-4o',
+      messages: [{ role: 'user', content: 'hi' }],
+    });
+    expect(r.body.messages).toEqual([{ role: 'user', content: 'hi' }]);
+  });
+
+  it('emits stream_options.include_usage when streaming', () => {
+    const r = openai.buildRequest({ apiKey: 'k', model: 'gpt-4o', messages: [], stream: true });
+    expect(r.body.stream).toBe(true);
+    expect(r.body.stream_options).toEqual({ include_usage: true });
+  });
+
+  it('omits stream_options when not streaming', () => {
+    const r = openai.buildRequest({ apiKey: 'k', model: 'gpt-4o', messages: [] });
+    expect(r.body.stream_options).toBeUndefined();
+  });
+
+  it('forwards temperature when specified (including 0)', () => {
+    const r = openai.buildRequest({ apiKey: 'k', model: 'gpt-4o', messages: [], temperature: 0 });
+    expect(r.body.temperature).toBe(0);
+  });
+});
+
+describe('openai.parseResponse', () => {
+  it('maps stop_reason "stop" → "end" (normalized)', () => {
+    const out = openai.parseResponse({
+      choices: [{ message: { content: 'hi' }, finish_reason: 'stop' }],
+      usage: { prompt_tokens: 3, completion_tokens: 1 },
+    });
+    expect(out.stopReason).toBe('end');
+  });
+
+  it('preserves non-"stop" finish_reasons (e.g. length)', () => {
+    const out = openai.parseResponse({
+      choices: [{ message: { content: 'hi' }, finish_reason: 'length' }],
+      usage: {},
+    });
+    expect(out.stopReason).toBe('length');
+  });
+});
+
+describe('gemini.buildRequest', () => {
+  it('targets generativelanguage.googleapis.com with the model in the URL path', () => {
+    const r = gemini.buildRequest({ apiKey: 'AIza-xyz', model: 'gemini-2.5-flash', messages: [] });
+    expect(r.url).toContain('generativelanguage.googleapis.com');
+    expect(r.url).toContain('gemini-2.5-flash');
+  });
+
+  it('uses x-goog-api-key header for auth (not Authorization Bearer or x-api-key)', () => {
+    const r = gemini.buildRequest({ apiKey: 'AIza-xyz', model: 'gemini-2.5-flash', messages: [] });
+    expect(r.headers['x-goog-api-key']).toBe('AIza-xyz');
+    expect(r.headers.authorization).toBeUndefined();
+    expect(r.headers['x-api-key']).toBeUndefined();
+  });
+
+  it('maps role:assistant → role:model (Gemini convention)', () => {
+    const r = gemini.buildRequest({
+      apiKey: 'k',
+      model: 'gemini-2.5-flash',
+      messages: [
+        { role: 'user', content: 'hi' },
+        { role: 'assistant', content: 'hello' },
+      ],
+    });
+    expect(r.body.contents[0].role).toBe('user');
+    expect(r.body.contents[1].role).toBe('model');
+  });
+
+  it('wraps system in systemInstruction (not first message)', () => {
+    const r = gemini.buildRequest({
+      apiKey: 'k',
+      model: 'gemini-2.5-flash',
+      messages: [{ role: 'user', content: 'hi' }],
+      system: 'You are concise.',
+    });
+    expect(r.body.systemInstruction).toEqual({ parts: [{ text: 'You are concise.' }] });
+    // System must NOT be in contents (different from OpenAI shape)
+    expect(r.body.contents.find((c) => c.parts?.[0]?.text === 'You are concise.')).toBeUndefined();
+  });
+
+  it('switches to streamGenerateContent endpoint when streaming', () => {
+    const direct = gemini.buildRequest({ apiKey: 'k', model: 'gemini-2.5-flash', messages: [] });
+    const stream = gemini.buildRequest({ apiKey: 'k', model: 'gemini-2.5-flash', messages: [], stream: true });
+    expect(direct.url).toContain(':generateContent');
+    expect(direct.url).not.toContain('stream');
+    expect(stream.url).toContain('streamGenerateContent');
+    expect(stream.url).toContain('alt=sse');
+  });
+
+  it('puts maxTokens into generationConfig.maxOutputTokens (Gemini-specific name)', () => {
+    const r = gemini.buildRequest({ apiKey: 'k', model: 'gemini-2.5-flash', messages: [], maxTokens: 4096 });
+    expect(r.body.generationConfig.maxOutputTokens).toBe(4096);
+  });
+});

package/adapters/client.test.js

@@ -0,0 +1,71 @@
+/**
+ * createClient — defaults baked in, per-call overrides.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { createClient } from '../adapters/index.js';
+
+let lastFetch;
+
+function ok(body) {
+  return new Response(JSON.stringify(body), { status: 200, headers: { 'content-type': 'application/json' } });
+}
+
+beforeEach(() => {
+  lastFetch = null;
+  globalThis.fetch = vi.fn(async (url, init) => {
+    lastFetch = { url, init, body: init?.body ? JSON.parse(init.body) : null };
+    // Anthropic-shaped response (default)
+    return ok({ content: [{ type: 'text', text: 'ok' }], usage: { input_tokens: 1, output_tokens: 1 }, stop_reason: 'end_turn' });
+  });
+});
+
+afterEach(() => vi.restoreAllMocks());
+
+describe('createClient', () => {
+  it('returns { chat, stream } functions', () => {
+    const client = createClient({ provider: 'anthropic', apiKey: 'k' });
+    expect(typeof client.chat).toBe('function');
+    expect(typeof client.stream).toBe('function');
+  });
+
+  it('bakes defaults into chat() calls', async () => {
+    const client = createClient({
+      provider: 'anthropic',
+      apiKey: 'sk-baked',
+      model: 'claude-haiku-4-5',
+    });
+    await client.chat({ messages: [{ role: 'user', content: 'hi' }] });
+    expect(lastFetch.url).toContain('api.anthropic.com');
+    expect(lastFetch.init.headers['x-api-key']).toBe('sk-baked');
+    expect(lastFetch.body.model).toBe('claude-haiku-4-5');
+  });
+
+  it('per-call options override defaults', async () => {
+    const client = createClient({
+      provider: 'anthropic',
+      apiKey: 'sk-default',
+      model: 'claude-haiku-4-5',
+    });
+    await client.chat({
+      apiKey: 'sk-override',
+      model: 'claude-sonnet-4-6',
+      messages: [{ role: 'user', content: 'hi' }],
+    });
+    expect(lastFetch.init.headers['x-api-key']).toBe('sk-override');
+    expect(lastFetch.body.model).toBe('claude-sonnet-4-6');
+  });
+
+  it('default proxyUrl is forwarded to chat()', async () => {
+    const client = createClient({
+      provider: 'anthropic',
+      apiKey: 'k',
+      model: 'claude-haiku-4-5',
+      proxyUrl: '/api/chat',
+    });
+    await client.chat({ messages: [{ role: 'user', content: 'hi' }] });
+    expect(lastFetch.url).toBe('/api/chat');
+    // proxyRequest body shape
+    expect(lastFetch.body).toHaveProperty('provider', 'anthropic');
+  });
+});

package/adapters/index.js

@@ -62,12 +62,32 @@ function resolveAdapter(opts) {
 
 // ── Proxy mode ──
 //
-// When `proxyUrl` is set, the client speaks a provider-neutral protocol
-// to the proxy: { provider, model, messages, system?, maxTokens?,
-// temperature?, thinking?, stream }. The proxy holds the real API key
-// and reformats per upstream provider. Each adapter still parses the
-// upstream's streamed body via its own parseStream — the proxy pipes
-// the SSE bytes verbatim.
+// Two proxy flavors are supported:
+//
+//   1. Smart proxy (e.g. packages/llm/server.js on :3456) — speaks a
+//      provider-neutral protocol: { provider, model, messages, system?,
+//      maxTokens?, temperature?, thinking?, stream }. The proxy holds
+//      the real API key and reformats per upstream provider.
+//
+//   2. Passthrough proxy (e.g. Vite dev server's /api/llm/<provider>/...)
+//      — dumb URL rewriter that forwards the request body + headers
+//      verbatim to the upstream API. The client must send the real
+//      upstream body shape AND the real auth header (x-api-key for
+//      Anthropic, Authorization: Bearer for OpenAI/Gemini).
+//
+// We distinguish by URL shape: anything matching `/api/llm/<provider>/`
+// is treated as a passthrough proxy and routed through buildRequest()
+// with the URL replaced. Everything else is assumed to be a smart proxy.
+//
+// Each adapter still parses the upstream's streamed body via its own
+// parseStream — passthrough proxies pipe SSE bytes verbatim, smart
+// proxies must do the same.
+
+const PASSTHROUGH_PROXY_RE = /\/api\/llm\/[a-z]+(\/|$)/;
+
+function isPassthroughProxy(url) {
+  return typeof url === 'string' && PASSTHROUGH_PROXY_RE.test(url);
+}
 
 function proxyRequest(opts, stream) {
   const provider = opts.provider || detectProvider(opts.model);
@@ -88,6 +108,16 @@ function proxyRequest(opts, stream) {
   };
 }
 
+/**
+ * Build a passthrough-proxy request: real upstream body + real auth
+ * header, but URL pointed at the proxy. The proxy forwards verbatim.
+ */
+function passthroughRequest(opts, stream) {
+  const adapter = resolveAdapter(opts);
+  const built = adapter.buildRequest({ ...opts, stream });
+  return { ...built, url: opts.proxyUrl };
+}
+
 // ── Standalone functions ──
 
 /**
@@ -97,7 +127,7 @@ function proxyRequest(opts, stream) {
 export async function chat(opts) {
   const adapter = resolveAdapter(opts);
   const { url, headers, body } = opts.proxyUrl
-    ? proxyRequest(opts, false)
+    ? (isPassthroughProxy(opts.proxyUrl) ? passthroughRequest(opts, false) : proxyRequest(opts, false))
     : adapter.buildRequest({ ...opts, stream: false });
 
   const res = await fetch(url, {
@@ -122,7 +152,7 @@ export async function chat(opts) {
 export async function* streamChat(opts) {
   const adapter = resolveAdapter(opts);
   const { url, headers, body } = opts.proxyUrl
-    ? proxyRequest(opts, true)
+    ? (isPassthroughProxy(opts.proxyUrl) ? passthroughRequest(opts, true) : proxyRequest(opts, true))
     : adapter.buildRequest({ ...opts, stream: true });
 
   let res;

package/adapters/router.test.js

@@ -0,0 +1,228 @@
+/**
+ * Adapter router internals — detectProvider, isPassthroughProxy, body shapes.
+ *
+ * These functions are not exported but are tested through the public chat()/
+ * streamChat() surface. We exercise them by intercepting fetch() and asserting
+ * on the request URL/headers/body shape.
+ *
+ * Critical invariants:
+ *   - detectProvider correctly routes Claude/GPT/Gemini model names
+ *   - explicit `provider` overrides detection
+ *   - unknown model + no provider throws
+ *   - passthrough URLs trigger adapter.buildRequest() (real upstream shape + auth)
+ *   - smart-proxy URLs trigger proxyRequest() (provider-neutral body, no auth)
+ *   - The PASSTHROUGH_PROXY_RE regex only matches /api/llm/<provider>/ shapes
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { chat } from '../adapters/index.js';
+
+let fetchMock;
+let lastFetch;
+
+function ok(body) {
+  return new Response(JSON.stringify(body), { status: 200, headers: { 'content-type': 'application/json' } });
+}
+
+beforeEach(() => {
+  lastFetch = null;
+  fetchMock = vi.fn(async (url, init) => {
+    lastFetch = { url, init, body: init?.body ? JSON.parse(init.body) : null };
+    // Generic minimal valid response per provider — chat() parseResponse only
+    // needs minimal fields here since we're testing routing, not parsing.
+    if (typeof url === 'string' && url.includes('anthropic')) {
+      return ok({ content: [{ type: 'text', text: 'ok' }], usage: { input_tokens: 1, output_tokens: 1 }, stop_reason: 'end_turn' });
+    }
+    if (typeof url === 'string' && url.includes('openai')) {
+      return ok({ choices: [{ message: { content: 'ok' }, finish_reason: 'stop' }], usage: { prompt_tokens: 1, completion_tokens: 1 } });
+    }
+    if (typeof url === 'string' && url.includes('googleapis') || (typeof url === 'string' && url.includes('gemini'))) {
+      return ok({ candidates: [{ content: { parts: [{ text: 'ok' }] }, finishReason: 'STOP' }], usageMetadata: { promptTokenCount: 1, candidatesTokenCount: 1 } });
+    }
+    // Smart-proxy / generic — return anthropic-shaped (default)
+    return ok({ content: [{ type: 'text', text: 'ok' }], usage: { input_tokens: 1, output_tokens: 1 }, stop_reason: 'end_turn' });
+  });
+  globalThis.fetch = fetchMock;
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('detectProvider (via chat() routing)', () => {
+  const cases = [
+    { model: 'claude-haiku-4-5-20251001', expectUrl: 'api.anthropic.com' },
+    { model: 'claude-sonnet-4-6',          expectUrl: 'api.anthropic.com' },
+    { model: 'anthropic/claude-foo',       expectUrl: 'api.anthropic.com' },
+    { model: 'gpt-4o-mini',                expectUrl: 'api.openai.com' },
+    { model: 'gpt-4o',                     expectUrl: 'api.openai.com' },
+    { model: 'o1-preview',                 expectUrl: 'api.openai.com' },
+    { model: 'o3-mini',                    expectUrl: 'api.openai.com' },
+    { model: 'o4-mini',                    expectUrl: 'api.openai.com' },
+    { model: 'openai/gpt-foo',             expectUrl: 'api.openai.com' },
+    { model: 'gemini-2.5-flash',           expectUrl: 'generativelanguage' },
+    { model: 'google/gemini-pro',          expectUrl: 'generativelanguage' },
+  ];
+
+  for (const c of cases) {
+    it(`routes ${c.model} → ${c.expectUrl}`, async () => {
+      await chat({ apiKey: 'k', model: c.model, messages: [{ role: 'user', content: 'hi' }] });
+      expect(lastFetch.url).toContain(c.expectUrl);
+    });
+  }
+
+  it('throws when model is unrecognized and no provider given', async () => {
+    await expect(
+      chat({ apiKey: 'k', model: 'totally-fake-model', messages: [] })
+    ).rejects.toThrow(/Cannot detect provider/);
+  });
+
+  it('explicit provider overrides model-name detection', async () => {
+    // 'gpt-style' name but force anthropic provider — should hit anthropic URL
+    await chat({ provider: 'anthropic', apiKey: 'k', model: 'gpt-fake', messages: [{ role: 'user', content: 'hi' }] });
+    expect(lastFetch.url).toContain('api.anthropic.com');
+  });
+
+  it('throws on unknown explicit provider', async () => {
+    await expect(
+      chat({ provider: 'notreal', apiKey: 'k', model: 'gpt-4o', messages: [] })
+    ).rejects.toThrow(/Unknown provider/);
+  });
+});
+
+describe('isPassthroughProxy URL routing', () => {
+  it('passthrough URL → adapter buildRequest (real upstream body + auth header)', async () => {
+    await chat({
+      apiKey: 'sk-ant-abc',
+      model: 'claude-haiku-4-5-20251001',
+      messages: [{ role: 'user', content: 'hi' }],
+      proxyUrl: '/api/llm/anthropic/v1/messages',
+    });
+    // URL should be the passthrough URL (not api.anthropic.com)
+    expect(lastFetch.url).toBe('/api/llm/anthropic/v1/messages');
+    // Headers should include x-api-key (anthropic adapter auth)
+    expect(lastFetch.init.headers['x-api-key']).toBe('sk-ant-abc');
+    expect(lastFetch.init.headers['anthropic-version']).toBeDefined();
+    // Body should be Anthropic-shaped (max_tokens, not maxTokens)
+    expect(lastFetch.body).toHaveProperty('max_tokens');
+    expect(lastFetch.body).not.toHaveProperty('provider'); // no provider-neutral key
+  });
+
+  it('smart-proxy URL → proxyRequest (provider-neutral body, no auth header)', async () => {
+    await chat({
+      apiKey: 'sk-ant-abc',
+      model: 'claude-haiku-4-5-20251001',
+      messages: [{ role: 'user', content: 'hi' }],
+      proxyUrl: '/api/chat',
+    });
+    expect(lastFetch.url).toBe('/api/chat');
+    // No upstream auth headers — proxy holds the key
+    expect(lastFetch.init.headers['x-api-key']).toBeUndefined();
+    expect(lastFetch.init.headers['authorization']).toBeUndefined();
+    // Body should be provider-neutral
+    expect(lastFetch.body).toMatchObject({
+      provider: 'anthropic',
+      model: 'claude-haiku-4-5-20251001',
+      messages: [{ role: 'user', content: 'hi' }],
+    });
+    // No upstream-specific keys
+    expect(lastFetch.body).not.toHaveProperty('max_tokens');
+  });
+
+  it('passthrough regex distinguishes /api/llm/<provider>/ from /api/llm-foo/', async () => {
+    // '/api/llm-foo' is NOT a passthrough — should go through proxyRequest
+    await chat({
+      apiKey: 'k',
+      model: 'gpt-4o',
+      messages: [{ role: 'user', content: 'hi' }],
+      proxyUrl: '/api/llm-similar/something',
+    });
+    // proxyRequest body has 'provider' key
+    expect(lastFetch.body).toHaveProperty('provider');
+  });
+
+  const passthroughShapes = [
+    '/api/llm/anthropic/v1/messages',
+    '/api/llm/openai/v1/chat/completions',
+    '/api/llm/gemini/foo',
+    '/api/llm/anthropic',          // bare provider, end of string
+  ];
+  for (const url of passthroughShapes) {
+    it(`recognizes ${url} as passthrough`, async () => {
+      await chat({
+        apiKey: 'k',
+        model: 'claude-haiku-4-5-20251001',
+        messages: [{ role: 'user', content: 'hi' }],
+        proxyUrl: url,
+      });
+      expect(lastFetch.url).toBe(url);
+      // Passthrough body: anthropic-shaped (no `provider` key)
+      expect(lastFetch.body).not.toHaveProperty('provider');
+    });
+  }
+});
+
+describe('proxyRequest body shape', () => {
+  it('forwards optional fields when present', async () => {
+    await chat({
+      apiKey: 'k',
+      model: 'gpt-4o-mini',
+      messages: [{ role: 'user', content: 'hi' }],
+      proxyUrl: '/api/chat',
+      system: 'You are concise.',
+      maxTokens: 1024,
+      temperature: 0.5,
+      thinking: true,
+    });
+    expect(lastFetch.body).toMatchObject({
+      provider: 'openai',
+      system: 'You are concise.',
+      maxTokens: 1024,
+      temperature: 0.5,
+      thinking: true,
+      stream: false,
+    });
+  });
+
+  it('omits optional fields when undefined (no null pollution)', async () => {
+    await chat({
+      apiKey: 'k',
+      model: 'gpt-4o',
+      messages: [{ role: 'user', content: 'hi' }],
+      proxyUrl: '/api/chat',
+    });
+    expect(lastFetch.body).not.toHaveProperty('system');
+    expect(lastFetch.body).not.toHaveProperty('maxTokens');
+    expect(lastFetch.body).not.toHaveProperty('temperature');
+    expect(lastFetch.body).not.toHaveProperty('thinking');
+  });
+
+  it('temperature: 0 is forwarded (not coerced to omitted)', async () => {
+    await chat({
+      apiKey: 'k',
+      model: 'gpt-4o',
+      messages: [{ role: 'user', content: 'hi' }],
+      proxyUrl: '/api/chat',
+      temperature: 0,
+    });
+    expect(lastFetch.body.temperature).toBe(0);
+  });
+});
+
+describe('error handling', () => {
+  it('rejects on upstream error response with adapter-tagged message', async () => {
+    fetchMock.mockResolvedValueOnce(
+      new Response(JSON.stringify({ error: { message: 'boom' } }), { status: 400 })
+    );
+    await expect(
+      chat({ apiKey: 'k', model: 'claude-haiku-4-5-20251001', messages: [] })
+    ).rejects.toThrow('boom');
+  });
+
+  it('falls back to "API error <status>" when upstream JSON missing error.message', async () => {
+    fetchMock.mockResolvedValueOnce(new Response('not json', { status: 500 }));
+    await expect(
+      chat({ apiKey: 'k', model: 'claude-haiku-4-5-20251001', messages: [] })
+    ).rejects.toThrow(/anthropic API error 500/);
+  });
+});

package/adapters/sse.test.js

@@ -0,0 +1,108 @@
+/**
+ * SSE parser — partial-line buffering, double-newline splitting, [DONE] detection.
+ *
+ * The SSE parser is consumed by all 3 adapter parseStream functions so a bug
+ * here would silently corrupt streaming for every provider. The parser is
+ * exercised against synthetic ReadableStreams that emulate real upstream
+ * chunking patterns (split mid-line, split mid-data, [DONE] termination).
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readSSE } from '../adapters/sse.js';
+
+/** Helper: build a Response.body-like ReadableStream from a list of byte chunks. */
+function streamOf(...chunks) {
+  const encoder = new TextEncoder();
+  return new ReadableStream({
+    start(controller) {
+      for (const c of chunks) controller.enqueue(encoder.encode(c));
+      controller.close();
+    },
+  });
+}
+
+async function collect(stream) {
+  const events = [];
+  for await (const ev of readSSE(stream)) events.push(ev);
+  return events;
+}
+
+describe('readSSE', () => {
+  it('parses a single complete event', async () => {
+    const events = await collect(streamOf('data: hello\n\n'));
+    expect(events).toEqual([{ event: undefined, data: 'hello', done: false }]);
+  });
+
+  it('parses event-typed messages', async () => {
+    const events = await collect(streamOf('event: ping\ndata: {}\n\n'));
+    expect(events).toEqual([{ event: 'ping', data: '{}', done: false }]);
+  });
+
+  it('strips the optional leading space after data:', async () => {
+    const events = await collect(streamOf('data: leading-space\n\ndata:no-space\n\n'));
+    expect(events.map((e) => e.data)).toEqual(['leading-space', 'no-space']);
+  });
+
+  it('joins multi-line data with newlines', async () => {
+    const events = await collect(streamOf('data: line1\ndata: line2\n\n'));
+    expect(events).toEqual([{ event: undefined, data: 'line1\nline2', done: false }]);
+  });
+
+  it('skips comment lines (lines starting with ":")', async () => {
+    const events = await collect(streamOf(': keep-alive\ndata: payload\n\n'));
+    expect(events).toEqual([{ event: undefined, data: 'payload', done: false }]);
+  });
+
+  it('detects [DONE] sentinel', async () => {
+    const events = await collect(streamOf('data: [DONE]\n\n'));
+    expect(events[0]).toMatchObject({ data: '[DONE]', done: true });
+  });
+
+  it('does not flag [DONE] in the middle of arbitrary data', async () => {
+    const events = await collect(streamOf('data: not-quite[DONE]\n\n'));
+    expect(events[0].done).toBe(false);
+  });
+
+  it('handles partial-line buffering across chunk boundaries', async () => {
+    // One event split across THREE chunks at arbitrary points.
+    const events = await collect(streamOf('data: he', 'l', 'lo\n\n'));
+    expect(events).toEqual([{ event: undefined, data: 'hello', done: false }]);
+  });
+
+  it('handles double-newline split across chunk boundary', async () => {
+    // Event terminator split between chunks.
+    const events = await collect(streamOf('data: a\n', '\ndata: b\n\n'));
+    expect(events.map((e) => e.data)).toEqual(['a', 'b']);
+  });
+
+  it('handles \\r\\n line endings (Windows-style upstream)', async () => {
+    const events = await collect(streamOf('event: x\r\ndata: y\r\n\r\n'));
+    expect(events).toEqual([{ event: 'x', data: 'y', done: false }]);
+  });
+
+  it('flushes a trailing event without final \\n\\n', async () => {
+    // Some upstreams close the stream without a final blank line.
+    const events = await collect(streamOf('data: trailing'));
+    expect(events).toEqual([{ event: undefined, data: 'trailing', done: false }]);
+  });
+
+  it('skips empty-data events', async () => {
+    // event: foo with no data: should NOT yield (no dataLines)
+    const events = await collect(streamOf('event: foo\n\ndata: real\n\n'));
+    expect(events).toEqual([{ event: undefined, data: 'real', done: false }]);
+  });
+
+  it('handles a long stream of mixed events', async () => {
+    const events = await collect(
+      streamOf(
+        'data: 1\n\n',
+        ': keep-alive\n\n',
+        'event: tick\ndata: 2\n\n',
+        'data: 3\n\n',
+        'data: [DONE]\n\n'
+      )
+    );
+    expect(events.map((e) => e.data)).toEqual(['1', '2', '3', '[DONE]']);
+    expect(events.at(-1).done).toBe(true);
+  });
+});

package/index.js

@@ -6,6 +6,7 @@
  * consumer that needs to talk to anthropic / openai / gemini.
  *
  *   import { chat, streamChat, createClient } from '@adia-ai/llm';
+ *   import { MODELS, DEFAULT_MODEL } from '@adia-ai/llm/models';
  *   import { createAdapter } from '@adia-ai/llm/bridge';
  *   import { StubLLMAdapter } from '@adia-ai/llm/stub';
  */
@@ -15,3 +16,8 @@ export {
   streamChat,
   createClient,
 } from './adapters/index.js';
+
+export {
+  MODELS,
+  DEFAULT_MODEL,
+} from './models.js';

package/models.js

@@ -0,0 +1,38 @@
+/**
+ * Shared model catalog — chat-input-ui grouped-options shape.
+ *
+ * Three consumers (as of 2026-05-06): apps/chat/, apps/genui/gen-ui-ux/,
+ * apps/genui/gen-ui/. Each previously carried a near-identical literal
+ * array; this module promotes them to one source.
+ *
+ * Format matches `<chat-input-ui>.models` setter (a 2D grouped-options
+ * structure consumed by an internal `<select-ui>` with `<optgroup>`s).
+ *
+ *   import { MODELS, DEFAULT_MODEL } from '@adia-ai/llm/models';
+ *   chatInput.models = MODELS;
+ *   chatInput.model = DEFAULT_MODEL;
+ */
+
+export const MODELS = [
+  {
+    label: 'Anthropic',
+    options: [
+      { value: 'claude-haiku-4-5-20251001', label: 'Haiku 4.5' },
+      { value: 'claude-sonnet-4-6',          label: 'Sonnet 4.6' },
+    ],
+  },
+  {
+    label: 'OpenAI',
+    options: [
+      { value: 'gpt-4o-mini', label: 'GPT-4o Mini' },
+    ],
+  },
+  {
+    label: 'Google',
+    options: [
+      { value: 'gemini-2.5-flash', label: 'Gemini 2.5 Flash' },
+    ],
+  },
+];
+
+export const DEFAULT_MODEL = 'claude-haiku-4-5-20251001';

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@adia-ai/llm",
-  "version": "0.3.1",
-  "description": "Provider-agnostic LLM client — anthropic / openai / gemini adapters with a unified chat() + streamChat() facade. Used by AdiaUI's chat-shell and the A2UI generation pipeline; works in browser (with proxyUrl) and Node.",
+  "version": "0.3.3",
+  "description": "Provider-agnostic LLM client \u2014 anthropic / openai / gemini adapters with a unified chat() + streamChat() facade. Used by AdiaUI's chat-shell and the A2UI generation pipeline; works in browser (with proxyUrl) and Node.",
   "type": "module",
   "exports": {
     ".": "./index.js",
     "./adapters/*": "./adapters/*.js",
     "./bridge": "./llm-bridge.js",
+    "./models": "./models.js",
     "./stub": "./llm-stub.js",
     "./package.json": "./package.json"
   },
@@ -14,6 +15,7 @@
     "adapters/",
     "llm-bridge.js",
     "llm-stub.js",
+    "models.js",
     "index.js",
     "README.md",
     "CHANGELOG.md"