@openchambery/web 1.19.7-beta.2 → 1.19.7-beta.21

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/)
+  })
+})

package/server/lib/llm/completions.js

@@ -0,0 +1,151 @@
+import { isConnectedModel, loadConnectedCatalog, parseModelRef } from './catalog.js';
+import { generateOpenCodeText } from './generate.js';
+
+const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+export class LlmError extends Error {
+  constructor(code, statusCode, message) {
+    super(message || code);
+    this.code = code;
+    this.statusCode = statusCode;
+  }
+}
+
+const normalizeCompletionFilePart = (part) => {
+  if (!isRecord(part) || part.type !== 'file') return null;
+  if (typeof part.mime !== 'string' || !part.mime.trim()) return null;
+  if (typeof part.url !== 'string' || !part.url.trim()) return null;
+  return {
+    type: 'file',
+    mime: part.mime.trim(),
+    url: part.url.trim(),
+    ...(typeof part.filename === 'string' && part.filename.trim() ? { filename: part.filename.trim() } : {}),
+  };
+};
+
+const normalizeMessages = (messages) => {
+  if (!Array.isArray(messages) || messages.length === 0) {
+    throw new LlmError('validation_error', 400, 'messages is required');
+  }
+  return messages.map((message) => {
+    if (!isRecord(message) || typeof message.content !== 'string') {
+      throw new LlmError('validation_error', 400, 'each message needs role and string content');
+    }
+    const role = message.role;
+    if (role !== 'system' && role !== 'user' && role !== 'assistant') {
+      throw new LlmError('validation_error', 400, 'message role must be system, user, or assistant');
+    }
+    const parts = Array.isArray(message.parts)
+      ? message.parts.map(normalizeCompletionFilePart).filter(Boolean)
+      : [];
+    return parts.length > 0 ? { role, content: message.content, parts } : { role, content: message.content };
+  });
+};
+
+const completionId = () => `chatcmpl_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`;
+
+export function toOpenAICompletion({ id, model, text, created = Math.floor(Date.now() / 1000) }) {
+  return {
+    id,
+    object: 'chat.completion',
+    created,
+    model,
+    choices: [{
+      index: 0,
+      message: { role: 'assistant', content: text },
+      finish_reason: 'stop',
+    }],
+    usage: { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 },
+  };
+}
+
+/**
+ * OpenAI-shaped completions against OpenCode's already-connected providers.
+ *
+ * Public HTTP stays non-streaming (`stream: true` → validation_error).
+ * In-process callers (Assistant contact harness) may pass `onTextDelta` and
+ * `globalEventHub`; those are forwarded to generate for real throwaway-session
+ * `message.part.delta` tokens only — never as fake post-hoc SSE on this route.
+ */
+export async function createChatCompletion({
+  body,
+  buildOpenCodeUrl,
+  getOpenCodeAuthHeaders,
+  clientFactory,
+  loadCatalog = loadConnectedCatalog,
+  generateText = generateOpenCodeText,
+  ensureTempDirectory,
+  fetchImpl,
+  onTextDelta = null,
+  globalEventHub = null,
+}) {
+  if (!isRecord(body)) throw new LlmError('validation_error', 400, 'JSON body is required');
+  // Bundled OpenCode 1.18.4 generate is a full-turn JSON reply (sessionless
+  // generate or throwaway session.promptAsync). This HTTP gateway does not
+  // token-stream. Do not emit fake SSE after the fact.
+  // In-process onTextDelta (optional) is a separate internal callback path.
+  if (body.stream === true) {
+    throw new LlmError(
+      'validation_error',
+      400,
+      'This gateway is non-streaming; omit stream or set stream:false',
+    );
+  }
+  const resolved = parseModelRef(body.model, body.providerID, body.modelID);
+  if (!resolved) throw new LlmError('validation_error', 400, 'model or providerID/modelID is required');
+  const messages = normalizeMessages(body.messages);
+
+  const client = clientFactory?.() ?? null;
+  const catalog = await loadCatalog(client ?? {
+    provider: { list: async () => ({ error: { status: 500 } }) },
+    config: { providers: async () => ({ error: { status: 500 } }) },
+  });
+  if (!isConnectedModel(catalog, resolved.providerID, resolved.modelID)) {
+    throw new LlmError(
+      'no_provider',
+      400,
+      `No connected OpenCode provider for ${resolved.providerID}/${resolved.modelID}`,
+    );
+  }
+
+  let generated;
+  try {
+    generated = await generateText({
+      buildOpenCodeUrl,
+      getOpenCodeAuthHeaders,
+      providerID: resolved.providerID,
+      modelID: resolved.modelID,
+      messages,
+      fetchImpl,
+      clientFactory,
+      ensureTempDirectory,
+      forwardImageParts: Boolean(catalog.models.find((entry) => (
+        entry.providerID === resolved.providerID && entry.modelID === resolved.modelID
+      ))?.acceptsImages),
+      onTextDelta,
+      globalEventHub,
+    });
+  } catch (error) {
+    if (error instanceof LlmError) throw error;
+    if (error?.code === 'validation_error') {
+      throw new LlmError('validation_error', 400, error.message || 'validation_error');
+    }
+    throw new LlmError(
+      'upstream_error',
+      502,
+      typeof error?.message === 'string' && error.message.trim()
+        ? error.message
+        : 'OpenCode generate failed',
+    );
+  }
+  const text = typeof generated?.text === 'string' ? generated.text.trim() : '';
+  if (!text) throw new LlmError('upstream_error', 502, 'OpenCode returned no assistant text');
+
+  const model = `${resolved.providerID}/${resolved.modelID}`;
+  return {
+    completion: toOpenAICompletion({ id: completionId(), model, text }),
+    providerID: resolved.providerID,
+    modelID: resolved.modelID,
+    source: generated.source,
+  };
+}

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

@@ -0,0 +1,127 @@
+import { describe, expect, it, vi } from 'vitest'
+import { LlmError, createChatCompletion } from './completions.js'
+
+describe('createChatCompletion', () => {
+  it('rejects when the requested model is not connected', async () => {
+    const generateText = vi.fn()
+    await expect(createChatCompletion({
+      generateText,
+      loadCatalog: async () => ({
+        models: [{ providerID: 'openai', modelID: 'gpt-5.2' }],
+        connected: ['openai'],
+      }),
+      body: { model: 'anthropic/claude-sonnet-4', messages: [{ role: 'user', content: 'hi' }] },
+    })).rejects.toMatchObject({ code: 'no_provider' })
+    expect(generateText).not.toHaveBeenCalled()
+  })
+
+  it('rejects stream:true instead of faking SSE after a full generate', async () => {
+    const generateText = vi.fn()
+    await expect(createChatCompletion({
+      generateText,
+      loadCatalog: async () => ({
+        models: [{ providerID: 'openai', modelID: 'gpt-5.2' }],
+        connected: ['openai'],
+      }),
+      body: {
+        model: 'openai/gpt-5.2',
+        stream: true,
+        messages: [{ role: 'user', content: 'hi' }],
+      },
+    })).rejects.toMatchObject({ code: 'validation_error', statusCode: 400 })
+    expect(generateText).not.toHaveBeenCalled()
+  })
+
+  it('returns a non-stream completion from generateText', async () => {
+    const generateText = vi.fn(async () => ({ text: 'done', source: 'throwaway-session' }))
+    const result = await createChatCompletion({
+      generateText,
+      loadCatalog: async () => ({
+        models: [{ providerID: 'openai', modelID: 'gpt-5.2' }],
+        connected: ['openai'],
+      }),
+      body: { model: 'openai/gpt-5.2', messages: [{ role: 'user', content: 'hi' }] },
+    })
+    expect(result.completion.choices[0].message.content).toBe('done')
+    expect(result.providerID).toBe('openai')
+    expect(result.modelID).toBe('gpt-5.2')
+  })
+
+  it('forwards in-process onTextDelta and globalEventHub to generateText', async () => {
+    const generateText = vi.fn(async () => ({ text: 'streamed', source: 'throwaway-session' }))
+    const onTextDelta = vi.fn()
+    const globalEventHub = { subscribeEvent: vi.fn() }
+    await createChatCompletion({
+      generateText,
+      loadCatalog: async () => ({
+        models: [{ providerID: 'openai', modelID: 'gpt-5.2' }],
+        connected: ['openai'],
+      }),
+      body: { model: 'openai/gpt-5.2', messages: [{ role: 'user', content: 'hi' }] },
+      onTextDelta,
+      globalEventHub,
+    })
+    expect(generateText.mock.calls[0][0].onTextDelta).toBe(onTextDelta)
+    expect(generateText.mock.calls[0][0].globalEventHub).toBe(globalEventHub)
+  })
+
+  it('forwards optional file parts on user messages', async () => {
+    const generateText = vi.fn(async () => ({ text: 'saw it', source: 'throwaway-session' }))
+    const image = { type: 'file', mime: 'image/png', url: 'data:image/png;base64,aa', filename: 'shot.png' }
+    await createChatCompletion({
+      generateText,
+      loadCatalog: async () => ({
+        models: [{ providerID: 'openai', modelID: 'gpt-5.2', acceptsImages: true }],
+        connected: ['openai'],
+      }),
+      body: {
+        model: 'openai/gpt-5.2',
+        messages: [{ role: 'user', content: 'look', parts: [image] }],
+      },
+    })
+    expect(generateText.mock.calls[0][0].messages).toEqual([
+      { role: 'user', content: 'look', parts: [image] },
+    ])
+    expect(generateText.mock.calls[0][0].forwardImageParts).toBe(true)
+  })
+
+  it('asks generate to skip image bytes when the catalog model is not vision-capable', async () => {
+    const generateText = vi.fn(async () => ({ text: 'ok', source: 'throwaway-session' }))
+    await createChatCompletion({
+      generateText,
+      loadCatalog: async () => ({
+        models: [{ providerID: 'opencode', modelID: 'deepseek-v4-flash', acceptsImages: false }],
+        connected: ['opencode'],
+      }),
+      body: { model: 'opencode/deepseek-v4-flash', messages: [{ role: 'user', content: 'look' }] },
+    })
+    expect(generateText.mock.calls[0][0].forwardImageParts).toBe(false)
+  })
+
+  it('LlmError carries a stable code', () => {
+    expect(new LlmError('no_provider', 400, 'missing')).toMatchObject({
+      code: 'no_provider',
+      statusCode: 400,
+    })
+  })
+
+  it('wraps generate failures as 502 with the OpenCode error message', async () => {
+    const generateText = vi.fn(async () => {
+      const error = new Error('model refused the request')
+      error.code = 'upstream_error'
+      throw error
+    })
+    await expect(createChatCompletion({
+      generateText,
+      loadCatalog: async () => ({
+        models: [{ providerID: 'opencode', modelID: 'gpt-5-nano' }],
+        connected: ['opencode'],
+      }),
+      body: { model: 'opencode/gpt-5-nano', messages: [{ role: 'user', content: 'hi' }] },
+    })).rejects.toMatchObject({
+      code: 'upstream_error',
+      statusCode: 502,
+      message: 'model refused the request',
+    })
+  })
+})