@openchambery/web 1.19.21-beta.1 → 2.0.0-beta.1

package/server/lib/llm/DOCUMENTATION.md

@@ -5,103 +5,85 @@ 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.
+- `GET /api/openchamber/llm/models` — available `{providerID, modelID}` catalog
+  from official `@opencode/client` `provider.list` + `model.list`
+  (`{ location, data }`). `ModelInfo.id` is the external modelID used in
+  generate/session refs (`ModelInfo.modelID` is a separate internal field).
+  Vision prefers `capabilities.input.image === true` (SDK object shape), then
+  v2 list `capabilities.input` containing `"image"`, then legacy
+  modalities/input/attachment. Catalog loads use a bounded AbortSignal
+  (default 8s) so a pending provider call cannot stall a contact lane.
 - `POST /api/openchamber/llm/chat/completions` — `{ model, messages, stream?,
   providerID?, modelID?, variant? }` → 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
+  This **public** gateway is **non-streaming**. `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).
+  route. The contact UI may stream later via a **server-internal** path only.
 
 `model` may be `providerID/modelID` or a bare `modelID` paired with `providerID`.
 
 `variant` is an optional OpenCode model variant string. Null, omitted, or empty
 values preserve the provider default. Other types fail validation before a model
-call. A selected variant is forwarded unchanged to sessionless generate and to
-the throwaway `session.promptAsync` body. OpenCode owns provider-specific variant
+call. A selected variant is forwarded unchanged on `generate.text` and on the
+attachment-session `model` ref. OpenCode owns provider-specific variant
 semantics. Variant selection changes inference configuration only; completion
 output continues to include text parts and keeps reasoning parts private.
 
-## 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 under a hidden
-   `openchamber-llm` agent whose frontmatter uses OpenCode 1.18
-   `permission: { "*": deny }` (not legacy `action`/`resource`/`effect` lists —
-   those load without a terminal `*` deny). `session.create` also sets
-   `permission: [{ permission: '*', pattern: '*', action: 'deny' }]` (SDK
-   PermissionRuleset; verified to round-trip on the session object). Deny every
-   catalog tool via `client.tool.ids()` → `{ [id]: false }` on `promptAsync`;
-   a `tool.ids` SDK/transport error fails generate (never silent empty deny).
-   Send 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`; a deterministic `session.messages` SDK error (for example
-    HTTP 400) fails generate immediately. The generator deadline is a **stall**
-    timer (`GENERATE_TIMEOUT_MS` = 90s), not a wall-clock cap. Busy / retry
-    session status, an incomplete assistant message, and throwaway
-    `message.part.delta` tokens reset the stall timer — a live model must not
-    look like "no response".
-    Then delete the session and surface
-   delete SDK errors in diagnostics without erasing a successful text result.
-    Throwaway sessions use `metadata.openchamber.llm.purpose = 'chat-completions'`
-    (and archived immediately) so sidebar visibility, session-index, session-title,
-    and notification/push fanout treat them as system-owned — same contract as
-    non-empty `smallModel.purpose`. This is a text generator only — never the
-    contact transcript and never a coding SessionPrompt loop. Upstream
-    `info.error.message` is forwarded on 502.
-    `ensureLlmTempDirectory` keeps one process-wide throwaway root (`openchamber-llm-…`).
-    Concurrent first callers share a single `mkdtemp` inflight; every caller still
-    writes/refreshes `.opencode/agent/<name>.md` after settle so a mid-flight ensure
-    cannot skip a newer agent body. Concurrent warm refreshes serialize through one
-    write chain (last committed body wins; no interleaved partial writes).
-    `stopLlmTempDirectory` clears the singleton for shutdown/tests.
+## Internals (official `@opencode/client`)
+
+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.
+
+### Text path (no vision image bytes)
+
+`client.generate.text({ location?, prompt, model: { id, providerID, variant? } },
+{ signal })` → `{ text }`. No session. System text is prepended into `prompt`.
+`onTextDelta` is skipped honestly (no fake typewriter).
+
+### Attachment / vision path
+
+When the catalog marks the model vision-capable and the request includes image
+data-URL file parts:
+
+1. Ensure the throwaway temp directory agent markdown (`openchamber-llm`,
+   permissions array ending in `action:* resource:* effect:deny`).
+2. `agent.get({ agentID: 'openchamber-llm', location })` and require the **final**
+   permissions rule to be deny-all. Failure → `llm_attachment_generation_unavailable`
+   **before** any `session.prompt`. Title is never treated as permission isolation.
+3. `session.create({ location, agent, model: { id, providerID, variant? } })`
+   (bare session id).
+4. Optional `session.instructions.entry.put` for the system prompt.
+5. Subscribe for `session.text.delta` (`data.sessionID` / `assistantMessageID` /
+   `ordinal` / `delta`) before prompt; unsubscribe in `finally`.
+6. `session.prompt({ sessionID, text, files: [{ uri, name? }], delivery })`.
+7. `session.wait` then `message.list({ order: 'desc' })`; verify newest assistant
+   `finish` / `error`; extract text content.
+8. On timeout/abort: `session.interrupt({ continue: false })` and always
+   `session.remove` in `finally`.
+
+Non-vision models keep the `[image: …]` description strategy and never forward
+image bytes. Data URLs are strictly validated; a single attachment is capped at
+20 MiB (plus existing inline text-file limits). An external/temp workspace that
+OpenCode cannot see fails explicitly (`llm_attachment_generation_unavailable`).
+
+`ensureLlmTempDirectory` keeps one process-wide throwaway root (`openchamber-llm-…`).
+Concurrent first callers share a single `mkdtemp` inflight; every caller still
+writes/refreshes `.opencode/agent/<name>.md` after settle so a mid-flight ensure
+cannot skip a newer agent body. Concurrent warm refreshes serialize through one
+write chain (last committed body wins; no interleaved partial writes).
+`stopLlmTempDirectory` clears the singleton for shutdown/tests.
+
+There is no `/generate` probe, no `tool.ids` deny map, and no `promptAsync` path.
+There is no `config.providers` catalog path.
 
 ### 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.
+`onTextDelta(text: string)` and `globalEventHub`.
 
-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.
+- **Attachment session path:** real `session.text.delta` tokens for this session.
+- **`generate.text` path:** cannot emit live deltas — skip `onTextDelta`.
+- **HTTP `POST .../chat/completions`:** does not pass these options and still
+  rejects `stream: true`.
 
 No connected provider → `no_provider` (HTTP 400). Upstream failure is never
 an empty success. The 502 body includes `{ error, message }`.
@@ -117,6 +99,11 @@ application tool catalog and actual results.
 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.
-
-Internal completion/generate calls accept an optional AbortSignal from the contact continuation. It is combined with the stall generator deadline and passed to upstream requests and settle polling. Cancellation still runs throwaway-session cleanup; it must not turn a late model response into a new tool operation.
+stays a text generator: OpenCode coding tools stay denied on the attachment path
+via the verified agent permissions ruleset.
+
+Internal completion/generate calls accept an optional AbortSignal from the
+contact continuation. It is combined with the generator deadline and passed to
+upstream requests. Cancellation still runs throwaway-session cleanup
+(`interrupt` + `remove`); it must not turn a late model response into a new
+tool operation.

package/server/lib/llm/catalog.js

@@ -7,8 +7,10 @@ const listIncludesImage = (value) => Array.isArray(value)
 
 /**
  * Vision capability projection.
- * Prefer authoritative OpenCode SDK Model.capabilities (`input.image` / `attachment`),
- * then fall back to legacy modalities/input/attachment shapes used by older fixtures.
+ * Prefer authoritative OpenCode Model.capabilities (`input.image` boolean /
+ * `attachment`, or v2 list `input` containing `"image"`), then fall back to
+ * legacy modalities/input/attachment shapes used by older fixtures.
+ * Do not treat model titles or unrelated flags as vision isolation.
  */
 export function modelAcceptsImages(model) {
   if (!isRecord(model)) return false;
@@ -16,6 +18,7 @@ export function modelAcceptsImages(model) {
     if (isRecord(model.capabilities.input) && typeof model.capabilities.input.image === 'boolean') {
       return model.capabilities.input.image === true;
     }
+    if (listIncludesImage(model.capabilities.input)) return true;
     if (model.capabilities.attachment === true) return true;
   }
   if (isRecord(model.modalities) && listIncludesImage(model.modalities.input)) return true;
@@ -24,49 +27,76 @@ export function modelAcceptsImages(model) {
 }
 
 /**
- * Merge OpenCode `GET /provider` (connected ids) with `GET /config/providers`
- * (model catalog). Do not interpret plugin-specific provider configs.
+ * Project official v2 provider.list + model.list into the LLM gateway catalog.
+ *
+ * ModelInfo.id is the external modelID used in generate/session model refs.
+ * ModelInfo.modelID is a separate internal field and must not be preferred.
  *
  * @param {{
- *   connected?: unknown,
  *   providers?: unknown,
+ *   models?: 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) {
+  const providersIn = Array.isArray(source?.providers) ? source.providers : [];
+  const modelsIn = Array.isArray(source?.models) ? source.models : [];
+
+  const providerMeta = new Map();
+  for (const provider of providersIn) {
     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({
+    if (!providerID) continue;
+    providerMeta.set(providerID, {
       id: providerID,
       name: stringID(provider.name) || providerID,
+    });
+  }
+
+  const models = [];
+  const modelsByProvider = new Map();
+  for (const model of modelsIn) {
+    if (!isRecord(model)) continue;
+    const providerID = stringID(model.providerID);
+    // External model id for generate.text / session model refs.
+    const modelID = stringID(model.id);
+    if (!providerID || !modelID) continue;
+    if (providerMeta.size > 0 && !providerMeta.has(providerID)) continue;
+    const name = stringID(model.name) || modelID;
+    const entry = {
+      providerID,
+      modelID,
+      name,
+      acceptsImages: modelAcceptsImages(model),
+    };
+    models.push(entry);
+    if (!modelsByProvider.has(providerID)) modelsByProvider.set(providerID, []);
+    modelsByProvider.get(providerID).push({ id: modelID, name });
+  }
+
+  const connected = [];
+  const providers = [];
+  const providerIDs = providerMeta.size > 0
+    ? [...providerMeta.keys()]
+    : [...modelsByProvider.keys()];
+  for (const providerID of providerIDs) {
+    const meta = providerMeta.get(providerID) || { id: providerID, name: providerID };
+    const providerModels = modelsByProvider.get(providerID) || [];
+    if (providerModels.length === 0 && providerMeta.size > 0) {
+      // Provider listed with zero models is still "connected" but contributes no entries.
+      connected.push(providerID);
+      providers.push({ id: meta.id, name: meta.name, models: [] });
+      continue;
+    }
+    if (providerModels.length === 0) continue;
+    connected.push(providerID);
+    providers.push({
+      id: meta.id,
+      name: meta.name,
       models: providerModels,
     });
   }
-  return { connected: [...connected], providers, models };
+
+  return { connected, providers, models };
 }
 
 export function parseModelRef(model, providerID, modelID) {
@@ -92,7 +122,7 @@ export function isConnectedModel(catalog, providerID, modelID) {
   return catalog.models.some((entry) => entry.providerID === providerID && entry.modelID === modelID);
 }
 
-/** Bound provider/config catalog loads so a pending SDK call cannot stall a contact lane. */
+/** Bound provider/model catalog loads so a pending SDK call cannot stall a contact lane. */
 export const CONNECTED_CATALOG_TIMEOUT_MS = 8_000;
 
 const isAbortError = (error) => (
@@ -101,18 +131,41 @@ const isAbortError = (error) => (
   || (typeof error?.message === 'string' && /aborted|timed out/i.test(error.message))
 );
 
+const resolveCatalogLocation = (options) => {
+  if (!options || typeof options !== 'object') return undefined;
+  if (isRecord(options.location)) return options.location;
+  if (options.directory || options.workspace) {
+    return {
+      ...(options.directory ? { directory: options.directory } : {}),
+      ...(options.workspace ? { workspace: options.workspace } : {}),
+    };
+  }
+  return undefined;
+};
+
 /**
- * Load the connected catalog from an OpenCode SDK client.
+ * Load the connected catalog from an official `@opencode/client`.
+ * Uses model.list + provider.list only (no config.providers).
  * Failure is distinct from a successful empty catalog.
- * Uses a bounded AbortSignal (default 8s) on provider.list + config.providers.
+ *
+ * Real client returns `{ location, data }` and throws declared JSON errors
+ * (no `{ error }` envelope). Uses a bounded AbortSignal (default 8s).
  *
  * @param {object} client
- * @param {{ signal?: AbortSignal, timeoutMs?: number }} [options]
+ * @param {{
+ *   location?: { directory?: string, workspace?: string },
+ *   directory?: string,
+ *   workspace?: string,
+ *   signal?: AbortSignal,
+ *   timeoutMs?: number,
+ * }} [options]
  */
 export async function loadConnectedCatalog(client, options = {}) {
   const timeoutMs = Number.isFinite(options.timeoutMs) && options.timeoutMs > 0
     ? Math.trunc(options.timeoutMs)
     : CONNECTED_CATALOG_TIMEOUT_MS;
+  const location = resolveCatalogLocation(options);
+  const request = location ? { location } : undefined;
   const parentSignal = options.signal;
   const controller = new AbortController();
   const onParentAbort = () => {
@@ -139,21 +192,34 @@ export async function loadConnectedCatalog(client, options = {}) {
 
   const requestOptions = { signal: controller.signal };
   try {
-    const listed = await client.provider.list({}, requestOptions);
-    if (listed?.error || !isRecord(listed?.data)) {
-      const error = new Error('OpenCode provider list is unavailable');
-      error.code = 'upstream_error';
-      throw error;
+    let providersResult;
+    let modelsResult;
+    try {
+      [providersResult, modelsResult] = await Promise.all([
+        client.provider.list(request, requestOptions),
+        client.model.list(request, requestOptions),
+      ]);
+    } catch (error) {
+      if (controller.signal.aborted || isAbortError(error)) {
+        throw error;
+      }
+      const upstream = new Error(
+        typeof error?.message === 'string' && error.message.trim()
+          ? error.message
+          : 'OpenCode provider catalog is unavailable',
+      );
+      upstream.code = 'upstream_error';
+      upstream.cause = error;
+      throw upstream;
     }
-    const configured = await client.config.providers({}, requestOptions);
-    if (configured?.error || !isRecord(configured?.data)) {
+    if (!Array.isArray(providersResult?.data) || !Array.isArray(modelsResult?.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,
+      providers: providersResult.data,
+      models: modelsResult.data,
     });
   } catch (error) {
     if (controller.signal.aborted || isAbortError(error)) {