@openchambery/web 1.19.7-beta.9 → 1.19.8-beta.1

package/server/lib/event-stream/reasoning-projection.test.js

@@ -0,0 +1,300 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  createReasoningOutboundFilter,
+  createSseBlockSplitter,
+  filterSseBlock,
+  projectMessagesPayloadForReasoning,
+  projectMessagesPayloadWithoutReasoning,
+  readIncludeReasoningFromUrl,
+  readIncludeReasoningQuery,
+  shouldIncludeReasoning,
+  stripIncludeReasoningParam,
+} from './reasoning-projection.js';
+
+describe('shouldIncludeReasoning / query helpers', () => {
+  it('only treats the strict string false as disabled', () => {
+    expect(shouldIncludeReasoning(undefined)).toBe(true);
+    expect(shouldIncludeReasoning(null)).toBe(true);
+    expect(shouldIncludeReasoning('')).toBe(true);
+    expect(shouldIncludeReasoning('true')).toBe(true);
+    expect(shouldIncludeReasoning('0')).toBe(true);
+    expect(shouldIncludeReasoning('False')).toBe(true);
+    expect(shouldIncludeReasoning(false)).toBe(true);
+    expect(shouldIncludeReasoning('false')).toBe(false);
+    expect(shouldIncludeReasoning(['false'])).toBe(false);
+  });
+
+  it('reads Express query and URL forms', () => {
+    expect(readIncludeReasoningQuery({ includeReasoning: 'false' })).toBe(false);
+    expect(readIncludeReasoningQuery({})).toBe(true);
+    expect(readIncludeReasoningFromUrl('/api/event?includeReasoning=false')).toBe(false);
+    expect(readIncludeReasoningFromUrl('/api/event')).toBe(true);
+  });
+
+  it('strips includeReasoning from upstream paths', () => {
+    expect(stripIncludeReasoningParam('/event?directory=/tmp&includeReasoning=false&x=1'))
+      .toBe('/event?directory=%2Ftmp&x=1');
+    expect(stripIncludeReasoningParam('/event?directory=/tmp')).toBe('/event?directory=/tmp');
+  });
+});
+
+describe('HTTP snapshot projection', () => {
+  it('drops reasoning parts and keeps tokens.reasoning', () => {
+    const record = {
+      info: { id: 'msg_1', tokens: { input: 1, output: 2, reasoning: 99 } },
+      parts: [
+        { id: 'p_r', type: 'reasoning', text: 'secret chain' },
+        { id: 'p_t', type: 'text', text: 'hello' },
+      ],
+    };
+    const projected = projectMessagesPayloadWithoutReasoning(record);
+    expect(projected.info.tokens.reasoning).toBe(99);
+    expect(projected.parts).toEqual([{ id: 'p_t', type: 'text', text: 'hello' }]);
+    expect(JSON.stringify(projected)).not.toContain('secret chain');
+    expect(record.parts).toHaveLength(2);
+  });
+
+  it('projects list / records / cache envelopes with identity when unchanged', () => {
+    const withReasoning = {
+      info: { id: 'm1', tokens: { reasoning: 3 } },
+      parts: [{ type: 'reasoning', text: 'nope' }, { type: 'text', text: 'ok' }],
+    };
+    expect(projectMessagesPayloadWithoutReasoning([withReasoning])[0].parts).toEqual([
+      { type: 'text', text: 'ok' },
+    ]);
+    const page = projectMessagesPayloadWithoutReasoning({ records: [withReasoning], turnCount: 1 });
+    expect(page.records[0].parts).toHaveLength(1);
+    expect(page.turnCount).toBe(1);
+
+    const cache = projectMessagesPayloadWithoutReasoning({
+      available: true,
+      record: withReasoning,
+      records: [withReasoning],
+    });
+    expect(cache.record.parts).toHaveLength(1);
+    expect(projectMessagesPayloadForReasoning(withReasoning, true)).toBe(withReasoning);
+
+    const plain = { info: { id: 'm' }, parts: [{ type: 'text', text: 'x' }] };
+    const list = [plain];
+    expect(projectMessagesPayloadWithoutReasoning(list)).toBe(list);
+    expect(projectMessagesPayloadWithoutReasoning(plain)).toBe(plain);
+  });
+});
+
+describe('stateful stream filter', () => {
+  it('strips version suffixes for dispatch but keeps original type on kept events', () => {
+    const filter = createReasoningOutboundFilter();
+
+    expect(filter.projectEvent({
+      type: 'session.next.reasoning.delta.1',
+      properties: { delta: 'think' },
+    })).toBeNull();
+    expect(filter.projectEvent({
+      type: 'session.next.reasoning.delta',
+      data: { delta: 'think' },
+    })).toBeNull();
+
+    // properties envelope + versioned type
+    expect(filter.projectEvent({
+      type: 'message.part.updated.1',
+      properties: {
+        part: { id: 'p_r', messageID: 'm1', type: 'reasoning', text: 'chain' },
+      },
+    })).toBeNull();
+
+    // data envelope + versioned type — learn text, keep original type string
+    const textUpdated = {
+      type: 'message.part.updated.1',
+      data: {
+        part: { id: 'p_t', messageID: 'm1', type: 'text', text: 'hi' },
+      },
+    };
+    expect(filter.projectEvent(textUpdated)).toBe(textUpdated);
+    expect(textUpdated.type).toBe('message.part.updated.1');
+
+    const textDelta = {
+      type: 'message.part.delta.1',
+      data: { messageID: 'm1', partID: 'p_t', field: 'text', delta: '!' },
+    };
+    expect(filter.projectEvent(textDelta)).toBe(textDelta);
+
+    // reasoning learned via properties; delta via data still drops
+    filter.projectEvent({
+      type: 'message.part.updated',
+      properties: { part: { id: 'p_r2', messageID: 'm1', type: 'reasoning', text: '' } },
+    });
+    expect(filter.projectEvent({
+      type: 'message.part.delta.1',
+      data: { messageID: 'm1', partID: 'p_r2', field: 'text', delta: 'secret' },
+    })).toBeNull();
+  });
+
+  it('drops explicit reasoning fields and unknown part deltas', () => {
+    const filter = createReasoningOutboundFilter();
+    expect(filter.projectEvent({
+      type: 'message.part.delta',
+      properties: { messageID: 'm1', partID: 'u', field: 'reasoning_content', delta: 'x' },
+    })).toBeNull();
+    expect(filter.projectEvent({
+      type: 'message.part.delta',
+      properties: { messageID: 'm1', partID: 'never', field: 'text', delta: 'leak?' },
+    })).toBeNull();
+  });
+
+  it('forgets classification and bounds the map', () => {
+    const filter = createReasoningOutboundFilter();
+    filter.projectEvent({
+      type: 'message.part.updated',
+      properties: { part: { id: 'p1', messageID: 'm1', type: 'text' } },
+    });
+    expect(filter.knownPartCount()).toBe(1);
+    filter.projectEvent({
+      type: 'message.part.removed',
+      properties: { messageID: 'm1', partID: 'p1' },
+    });
+    expect(filter.knownPartCount()).toBe(0);
+
+    for (let i = 0; i < 8200; i += 1) {
+      filter.projectEvent({
+        type: 'message.part.updated',
+        properties: { part: { id: `p_${i}`, messageID: 'm_big', type: 'text' } },
+      });
+    }
+    expect(filter.knownPartCount()).toBeLessThanOrEqual(8192);
+    filter.dispose();
+    expect(filter.knownPartCount()).toBe(0);
+  });
+
+  it('does not mutate original objects when stripping embedded parts', () => {
+    const filter = createReasoningOutboundFilter();
+    const original = {
+      type: 'message.updated',
+      properties: {
+        info: { id: 'm1', tokens: { reasoning: 7 } },
+        parts: [
+          { id: 'r', type: 'reasoning', text: 'hidden' },
+          { id: 't', type: 'text', text: 'visible' },
+        ],
+      },
+    };
+    const projected = filter.projectEvent(original);
+    expect(projected).not.toBe(original);
+    expect(original.properties.parts).toHaveLength(2);
+    expect(projected.properties.parts).toEqual([{ id: 't', type: 'text', text: 'visible' }]);
+  });
+});
+
+describe('SSE filter + CR-safe splitter', () => {
+  it('preserves wire identity for kept events and drops reasoning', () => {
+    const filter = createReasoningOutboundFilter();
+    const keptBlock = 'id: evt-1\ndata: {"type":"message.part.updated","properties":{"part":{"id":"p","messageID":"m","type":"text","text":"hi"}}}';
+    const droppedBlock = 'id: evt-2\ndata: {"type":"session.next.reasoning.delta","properties":{"delta":"no"}}';
+    const wrappedDrop = 'id: evt-3\ndata: {"directory":"/repo","payload":{"type":"session.next.reasoning.delta.1","properties":{"delta":"x"}}}';
+    const wrappedKeep = 'id: evt-4\ndata: {"directory":"/repo","payload":{"type":"server.connected","properties":{}}}';
+
+    expect(filterSseBlock(keptBlock, filter)).toBe(`${keptBlock}\n\n`);
+    expect(filterSseBlock(droppedBlock, filter)).toBeNull();
+    expect(filterSseBlock(wrappedDrop, filter)).toBeNull();
+    expect(filterSseBlock(wrappedKeep, filter)).toContain('"directory":"/repo"');
+  });
+
+  it('does not split one event when CRLF straddles chunk boundaries', () => {
+    const splitter = createSseBlockSplitter();
+    // Multi-line data event with CRLF, split after lone CR of first line ending.
+    const full = 'id: 1\r\ndata: {"type":"text","n":1}\r\ndata: more\r\n\r\n';
+    const cut = full.indexOf('\r') + 1; // after first CR of first line's CRLF
+    expect(full[cut - 1]).toBe('\r');
+    expect(full[cut]).toBe('\n');
+
+    const first = splitter.push(full.slice(0, cut));
+    expect(first).toEqual([]); // must not complete on lone CR→LF
+    const second = splitter.push(full.slice(cut));
+    expect(second).toHaveLength(1);
+    expect(second[0]).toContain('id: 1');
+    expect(second[0]).toContain('data: more');
+    expect(second[0]).not.toMatch(/^\s*$/);
+  });
+
+  it('handles per-character chunking and UTF-8 multi-byte without leaking reasoning', () => {
+    const filter = createReasoningOutboundFilter();
+    const splitter = createSseBlockSplitter();
+    const stream =
+      'id: a\ndata: {"type":"message.part.updated","properties":{"part":{"id":"t","messageID":"m","type":"text","text":"你好"}}}\n\n'
+      + 'id: b\ndata: {"type":"session.next.reasoning.delta","properties":{"delta":"secret"}}\n\n'
+      + 'id: c\ndata: {"type":"message.part.delta","properties":{"messageID":"m","partID":"t","field":"text","delta":"!"}}\n\n';
+
+    const bytes = new TextEncoder().encode(stream);
+    const out = [];
+    for (let i = 0; i < bytes.length; i += 1) {
+      for (const block of splitter.push(bytes.subarray(i, i + 1))) {
+        const filtered = filterSseBlock(block, filter);
+        if (filtered) out.push(filtered);
+      }
+    }
+    for (const block of splitter.finish()) {
+      const filtered = filterSseBlock(block, filter);
+      if (filtered) out.push(filtered);
+    }
+
+    expect(out).toHaveLength(2);
+    expect(out.join('')).toContain('"type":"message.part.updated"');
+    expect(out.join('')).toContain('"type":"message.part.delta"');
+    expect(out.join('')).toContain('你好');
+    expect(out.join('')).not.toContain('reasoning');
+    expect(out.join('')).not.toContain('secret');
+  });
+
+  it('keeps event order across mixed CRLF chunk splits', () => {
+    const splitter = createSseBlockSplitter();
+    const chunks = [
+      'id: 1\r\ndata: {"n":1}\r',
+      '\n\r\nid: 2\r\ndata: {"n":2}\r\n\r\n',
+    ];
+    const blocks = [];
+    for (const chunk of chunks) blocks.push(...splitter.push(chunk));
+    blocks.push(...splitter.finish());
+    expect(blocks.map((b) => JSON.parse(b.split('\n').find((l) => l.startsWith('data:')).slice(5)).n))
+      .toEqual([1, 2]);
+  });
+});
+
+describe('performance: 10k reasoning deltas', () => {
+  it('drops 10k reasoning deltas while still emitting known text deltas', () => {
+    const disabled = createReasoningOutboundFilter();
+    disabled.projectEvent({
+      type: 'message.part.updated',
+      properties: { part: { id: 'p_text', messageID: 'm1', type: 'text', text: '' } },
+    });
+    disabled.projectEvent({
+      type: 'message.part.updated',
+      properties: { part: { id: 'p_reason', messageID: 'm1', type: 'reasoning', text: '' } },
+    });
+
+    let disabledEvents = 0;
+    let disabledBodyBytes = 0;
+    for (let i = 0; i < 10_000; i += 1) {
+      const out = disabled.projectEvent({
+        type: 'message.part.delta',
+        properties: {
+          messageID: 'm1',
+          partID: 'p_reason',
+          field: 'text',
+          delta: `reasoning-token-${i}-xxxxxxxx`,
+        },
+      });
+      if (out != null) {
+        disabledEvents += 1;
+        disabledBodyBytes += JSON.stringify(out).length;
+      }
+    }
+
+    const textDelta = {
+      type: 'message.part.delta',
+      properties: { messageID: 'm1', partID: 'p_text', field: 'text', delta: 'hello-world' },
+    };
+    expect(disabled.projectEvent(textDelta)).toBe(textDelta);
+    expect(disabledEvents).toBe(0);
+    expect(disabledBodyBytes).toBe(0);
+  });
+});

package/server/lib/event-stream/runtime.js

@@ -10,6 +10,10 @@ import {
 import { createGlobalMessageStreamHub } from './global-hub.js';
 import { createGlobalMessageStreamWsBridge } from './global-ws-bridge.js';
 import { acceptDirectoryMessageStreamWsConnection } from './directory-ws-bridge.js';
+import {
+  createReasoningOutboundFilter,
+  shouldIncludeReasoning,
+} from './reasoning-projection.js';
 import {
   DEFAULT_UPSTREAM_RECONNECT_DELAY_MS,
   DEFAULT_UPSTREAM_STALL_TIMEOUT_MS,
@@ -95,10 +99,15 @@ export function createMessageStreamWsRuntime({
     const isGlobalStream = pathname === MESSAGE_STREAM_GLOBAL_WS_PATH;
     const requestedLastEventId = requestUrl.searchParams.get('lastEventId')?.trim() || '';
     const requestedDirectory = requestUrl.searchParams.get('directory')?.trim() || '';
+    // OpenChamber projection only — never forwarded to OpenCode upstream URLs.
+    // Default (include) path keeps reasoningFilter null for zero send-path overhead.
+    const includeReasoning = shouldIncludeReasoning(requestUrl.searchParams.get('includeReasoning'));
+    const reasoningFilter = includeReasoning ? null : createReasoningOutboundFilter();
 
     if (isGlobalStream) {
       globalBridge.accept(socket, {
         requestedLastEventId,
+        reasoningFilter,
       });
       return;
     }
@@ -107,6 +116,7 @@ export function createMessageStreamWsRuntime({
       socket,
       requestedLastEventId,
       requestedDirectory,
+      reasoningFilter,
       buildOpenCodeUrl,
       getOpenCodeAuthHeaders,
       processForwardedEventPayload,

package/server/lib/event-stream/runtime.test.js

@@ -127,6 +127,59 @@ describe('event stream broadcaster', () => {
 });
 
 describe('message stream websocket runtime', () => {
+  it('filters reasoning events per connection when includeReasoning=false', async () => {
+    const server = new EventEmitter();
+    const wsClients = new Set();
+
+    const runtime = createMessageStreamWsRuntime({
+      server,
+      uiAuthController: null,
+      isRequestOriginAllowed: async () => true,
+      rejectWebSocketUpgrade() {
+        throw new Error('upgrade should not be used in this test');
+      },
+      buildOpenCodeUrl: (path) => `http://127.0.0.1:4096${path}`,
+      getOpenCodeAuthHeaders: () => ({}),
+      processForwardedEventPayload() {},
+      wsClients,
+      upstreamReconnectDelayMs: 0,
+      fetchImpl: async (_url, options) => createSseResponse({
+        signal: options.signal,
+        holdOpen: true,
+        blocks: [
+          'id: evt-1\ndata: {"type":"message.part.updated","properties":{"part":{"id":"p_r","messageID":"m1","type":"reasoning","text":"secret"}}}\n\n',
+          'id: evt-2\ndata: {"type":"message.part.updated","properties":{"part":{"id":"p_t","messageID":"m1","type":"text","text":"hi"}}}\n\n',
+          'id: evt-3\ndata: {"type":"session.next.reasoning.delta","properties":{"delta":"nope"}}\n\n',
+          'id: evt-4\ndata: {"type":"message.part.delta","properties":{"messageID":"m1","partID":"p_t","field":"text","delta":"!"}}\n\n',
+        ],
+      }),
+    });
+
+    const filtered = new FakeSocket();
+    const full = new FakeSocket();
+    runtime.wsServer.emit('connection', filtered, { url: '/api/global/event/ws?includeReasoning=false' });
+    runtime.wsServer.emit('connection', full, { url: '/api/global/event/ws' });
+
+    await new Promise((resolve) => setTimeout(resolve, 20));
+
+    const filteredEvents = filtered.sent.filter((frame) => frame.type === 'event');
+    const fullEvents = full.sent.filter((frame) => frame.type === 'event');
+
+    expect(filteredEvents.some((frame) => frame.payload?.type === 'session.next.reasoning.delta')).toBe(false);
+    expect(filteredEvents.some((frame) => frame.payload?.properties?.part?.type === 'reasoning')).toBe(false);
+    expect(JSON.stringify(filteredEvents)).not.toContain('secret');
+    expect(filteredEvents.some((frame) => frame.payload?.type === 'message.part.updated'
+      && frame.payload?.properties?.part?.type === 'text')).toBe(true);
+    expect(filteredEvents.some((frame) => frame.payload?.type === 'message.part.delta')).toBe(true);
+
+    expect(fullEvents.some((frame) => frame.payload?.properties?.part?.type === 'reasoning')).toBe(true);
+    expect(fullEvents.some((frame) => frame.payload?.type === 'session.next.reasoning.delta')).toBe(true);
+
+    filtered.close();
+    full.close();
+    await runtime.close();
+  });
+
   it('shares one global upstream SSE reader across multiple websocket clients', async () => {
     const server = new EventEmitter();
     const wsClients = new Set();

package/server/lib/llm/DOCUMENTATION.md

@@ -0,0 +1,84 @@
+# OpenChamber LLM Gateway
+
+OpenAI-shaped Chat Completions for the in-app Assistant contact. This is the
+only model path the Assistant harness (`pi-agent-core` `streamFn`) talks to.
+
+## Contract
+
+- `GET /api/openchamber/llm/models` — connected `{providerID, modelID}` catalog
+  from OpenCode `GET /provider` (`connected`) plus `GET /config/providers`.
+  Plugin adapter formats stay inside OpenCode; this route does not parse them.
+- `POST /api/openchamber/llm/chat/completions` — `{ model, messages, stream?,
+  providerID?, modelID? }` → OpenAI `chat.completion` JSON.
+  This **public** gateway is **non-streaming**. Bundled OpenCode 1.18.4 generate
+  (`POST /generate` when present, otherwise throwaway `session.promptAsync`
+  plus idle wait) returns a full assistant turn. `stream: true` is rejected with
+  `validation_error` (HTTP 400). Do not emit fake SSE after the fact on this
+  route (never typewrite a completed string into tokens over HTTP).
+  The contact UI may stream later via a **server-internal** path only (below).
+
+`model` may be `providerID/modelID` or a bare `modelID` paired with `providerID`.
+
+## Internals (verified on bundled `@opencode-ai/sdk` 1.18.4)
+
+The 1.18.4 client exposes `GET /provider`, `GET /config/providers`, and
+`session.prompt` / `session.promptAsync`. It does **not** expose
+`POST /api/generate` or any other sessionless generate method.
+
+1. Probe `POST /generate` (and SDK `generate` if present). Use it only when
+   the response is JSON (`Content-Type` or a JSON object body). SPA / OpenCode
+   HTML `200 <!doctype` is not generate — fall through to the throwaway path.
+   Bundled 1.18.4 has no sessionless generate.
+2. Otherwise create a throwaway archived OpenCode session, deny every tool
+   (`client.tool.ids()` → `{ [id]: false }`), send our messages as
+   `system` + user text via `session.promptAsync` (v2 `session.prompt` only
+   forwards `{ id, prompt, delivery, resume }` and drops `model`/`parts` —
+   that produced empty assistant text and a 502). Contact file parts reuse the
+   existing OpenCode `{ type: 'file', mime, url, filename? }` delivery shape
+   (data URLs in the contact SQLite store — not a second attachment store) and
+   are forwarded on `promptAsync` only when the connected catalog marks that
+   model as image-capable (`modalities.input`, `input`, or `attachment`).
+   Non-vision models (for example deepseek-v4-flash) keep the `[image: …]`
+   description and any text-file bytes, and skip image data URLs so generate
+   cannot stall on unsupported vision parts. Non-image
+   text files are also inlined into the flattened prompt. Wait for idle via
+   `session.status` + `session.messages`, then delete the session. This is a
+    text generator only — never the contact transcript and never a coding
+    SessionPrompt loop. Upstream `info.error.message` is forwarded on 502.
+
+### Internal token callback (in-process only)
+
+`generateOpenCodeText` / `createChatCompletion` accept optional
+`onTextDelta(text: string)` and `globalEventHub` (the shared
+`globalMessageStreamHub` / `subscribeEvent` surface).
+
+- **Throwaway session path:** after archive, before `promptAsync`, subscribe to
+  the hub. Forward real OpenCode `message.part.delta` events whose
+  `properties.sessionID` matches this throwaway session, `field` is `text`
+  (or omitted), and `messageID` matches the first assistant message locked for
+  that generate. Still wait for idle and return the **full** text (strip/parse
+  needs the complete string). Unsubscribe in `finally` so failed generates
+  cannot leak listeners.
+- **Sessionless `/generate` JSON path:** cannot emit live deltas — skip
+  `onTextDelta` honestly (no fake typewriter of the completed string).
+- **HTTP `POST .../chat/completions`:** does not pass these options and still
+  rejects `stream: true`. Token deltas never leave the server as SSE on that
+  route.
+
+Bundled OpenCode 1.18.4 emits `message.part.delta` on the global event stream
+for normal session prompts (same events the UI transcript already consumes).
+Throwaway LLM sessions use the same `session.promptAsync` path, so they are
+expected to emit the same delta events when the model streams tokens.
+
+Credentials stay in OpenCode. This module does not read `auth.json`, does not
+call Anthropic/OpenAI/plugin SDKs, and does not use the `openai` npm package.
+
+No connected provider → `no_provider` (HTTP 400). Upstream failure is never
+an empty success. The 502 body includes `{ error, message }`.
+
+## Ownership
+
+The Assistant contact harness owns system prompt, OpenChamber transcript,
+bubble splitting, and OpenChamber API tools (`assign_session`). Those tools
+deliver through contact **cards**, not this completions payload. The gateway
+stays a text generator: OpenCode coding tools stay denied.

package/server/lib/llm/catalog.js

@@ -0,0 +1,100 @@
+const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+const stringID = (value) => (typeof value === 'string' && value.trim() ? value.trim() : '');
+
+const listIncludesImage = (value) => Array.isArray(value)
+  && value.some((item) => String(item).toLowerCase() === 'image');
+
+function modelAcceptsImages(model) {
+  if (!isRecord(model)) return false;
+  if (isRecord(model.modalities) && listIncludesImage(model.modalities.input)) return true;
+  if (listIncludesImage(model.input)) return true;
+  return model.attachment === true;
+}
+
+/**
+ * Merge OpenCode `GET /provider` (connected ids) with `GET /config/providers`
+ * (model catalog). Do not interpret plugin-specific provider configs.
+ *
+ * @param {{
+ *   connected?: unknown,
+ *   providers?: unknown,
+ * }} source
+ */
+export function projectConnectedModels(source) {
+  const connected = new Set(
+    Array.isArray(source?.connected)
+      ? source.connected.map(stringID).filter(Boolean)
+      : [],
+  );
+  const models = [];
+  const providers = [];
+  const list = Array.isArray(source?.providers) ? source.providers : [];
+  for (const provider of list) {
+    if (!isRecord(provider)) continue;
+    const providerID = stringID(provider.id);
+    if (!providerID || !connected.has(providerID)) continue;
+    const providerModels = [];
+    const rawModels = isRecord(provider.models) ? Object.values(provider.models) : [];
+    for (const model of rawModels) {
+      if (!isRecord(model)) continue;
+      const modelID = stringID(model.id);
+      if (!modelID) continue;
+      const entry = { providerID, modelID, name: stringID(model.name) || modelID, acceptsImages: modelAcceptsImages(model) };
+      models.push(entry);
+      providerModels.push({ id: modelID, name: entry.name });
+    }
+    providers.push({
+      id: providerID,
+      name: stringID(provider.name) || providerID,
+      models: providerModels,
+    });
+  }
+  return { connected: [...connected], providers, models };
+}
+
+export function parseModelRef(model, providerID, modelID) {
+  const explicitProvider = stringID(providerID);
+  const explicitModel = stringID(modelID);
+  if (explicitProvider && explicitModel) {
+    return { providerID: explicitProvider, modelID: explicitModel };
+  }
+  const raw = stringID(model);
+  if (!raw) return null;
+  const slash = raw.indexOf('/');
+  if (slash > 0) {
+    return { providerID: raw.slice(0, slash), modelID: raw.slice(slash + 1) };
+  }
+  if (explicitProvider && raw) {
+    return { providerID: explicitProvider, modelID: raw };
+  }
+  return null;
+}
+
+export function isConnectedModel(catalog, providerID, modelID) {
+  if (!catalog || !stringID(providerID) || !stringID(modelID)) return false;
+  return catalog.models.some((entry) => entry.providerID === providerID && entry.modelID === modelID);
+}
+
+/**
+ * Load the connected catalog from an OpenCode SDK client.
+ * Failure is distinct from a successful empty catalog.
+ */
+export async function loadConnectedCatalog(client) {
+  const listed = await client.provider.list({});
+  if (listed?.error || !isRecord(listed?.data)) {
+    const error = new Error('OpenCode provider list is unavailable');
+    error.code = 'upstream_error';
+    throw error;
+  }
+  const configured = await client.config.providers({});
+  if (configured?.error || !isRecord(configured?.data)) {
+    const error = new Error('OpenCode provider catalog is unavailable');
+    error.code = 'upstream_error';
+    throw error;
+  }
+  return projectConnectedModels({
+    connected: listed.data.connected,
+    providers: configured.data.providers,
+  });
+}

package/server/lib/llm/catalog.test.js

@@ -0,0 +1,78 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { loadConnectedCatalog, parseModelRef, projectConnectedModels } from './catalog.js'
+
+describe('parseModelRef', () => {
+  it('splits provider/model refs', () => {
+    expect(parseModelRef('openai/gpt-5.2')).toEqual({
+      providerID: 'openai',
+      modelID: 'gpt-5.2',
+    })
+  })
+
+  it('prefers explicit providerID/modelID', () => {
+    expect(parseModelRef('ignored', 'anthropic', 'claude-sonnet-4')).toEqual({
+      providerID: 'anthropic',
+      modelID: 'claude-sonnet-4',
+    })
+  })
+
+  it('returns null for invalid refs', () => {
+    expect(parseModelRef('')).toBeNull()
+    expect(parseModelRef('openai')).toBeNull()
+  })
+})
+
+describe('projectConnectedModels', () => {
+  it('projects only connected providers', () => {
+    const catalog = projectConnectedModels({
+      connected: ['openai'],
+      providers: [
+        {
+          id: 'openai',
+          name: 'OpenAI',
+          models: {
+            'gpt-5.2': { id: 'gpt-5.2', name: 'GPT-5.2' },
+          },
+        },
+        {
+          id: 'anthropic',
+          name: 'Anthropic',
+          models: { 'claude-sonnet-4': { id: 'claude-sonnet-4', name: 'Claude' } },
+        },
+      ],
+    })
+    expect(catalog.models).toEqual([
+      { providerID: 'openai', modelID: 'gpt-5.2', name: 'GPT-5.2', acceptsImages: false },
+    ])
+  })
+
+  it('marks vision models from modalities or attachment', () => {
+    const catalog = projectConnectedModels({
+      connected: ['openai'],
+      providers: [{
+        id: 'openai',
+        name: 'OpenAI',
+        models: {
+          'gpt-4o': { id: 'gpt-4o', name: 'GPT-4o', modalities: { input: ['text', 'image'] } },
+          'deepseek-v4-flash': { id: 'deepseek-v4-flash', name: 'deepseek-v4-flash' },
+        },
+      }],
+    })
+    expect(catalog.models.find((model) => model.modelID === 'gpt-4o')?.acceptsImages).toBe(true)
+    expect(catalog.models.find((model) => model.modelID === 'deepseek-v4-flash')?.acceptsImages).toBe(false)
+    expect(catalog.connected).toEqual(['openai'])
+  })
+})
+
+describe('loadConnectedCatalog', () => {
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('requires both /provider and /config/providers', async () => {
+    await expect(loadConnectedCatalog({
+      provider: { list: async () => ({ data: { connected: ['openai'] } }) },
+      config: { providers: async () => ({ error: { status: 500 } }) },
+    })).rejects.toThrow(/provider catalog/)
+  })
+})