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

package/server/lib/conversations/DOCUMENTATION.md

@@ -33,7 +33,7 @@ The service calls `waitForOpenCodeReady(6000, 75)` (6s, matching proxy gate `REA
 - `packages/web/server/lib/conversations/validation.js`
   - Request validation and sanitization with strict whitelist
   - Required: `input.type='prompt'`, `directory`, `messageID`, `model` (providerID/modelID), `parts` (non-empty array)
-  - Optional: `title`, `parentID`, `agent`, `variant`, `metadata`
+   - Optional: `title`, `parentID`, `agent`, `variant`, `metadata`, `skills` (array of `{ id }`, sanitized before forwarding as native V2 skill attachments)
   - **Rejected**: `delivery`, `format`, unknown top-level keys (whitelist enforcement)
   - Part types: `text` (requires non-empty `text`), `file` (requires `mime`+`url`), `agent` (requires `name`)
   - At least one content-carrying part (text/file/agent) required

package/server/lib/conversations/service.js

@@ -55,6 +55,7 @@ const toV2PromptInput = (sanitizedInput, sessionID) => {
     text,
     ...(files.length > 0 ? { files } : {}),
     ...(agents.length > 0 ? { agents } : {}),
+    ...(sanitizedInput.skills?.length ? { skills: sanitizedInput.skills.map(({ id }) => ({ id, name: id })) } : {}),
     ...(sanitizedInput.metadata ? { metadata: sanitizedInput.metadata } : {}),
     delivery: 'steer',
   };

package/server/lib/conversations/service.test.js

@@ -393,6 +393,22 @@ describe('conversations service', () => {
 
   // --- success ---
 
+  it('validates and forwards skill ids with the first prompt', async () => {
+    const validated = validateConversationInput({
+      input: { type: 'prompt' },
+      ...baseInput({ parts: [{ type: 'text', text: '[skill:release] prepare notes' }], skills: [{ id: 'release', text: 'untrusted body' }] }),
+    });
+    expect(validated.valid).toBe(true);
+    expect(validated.sanitized.skills).toEqual([{ id: 'release' }]);
+    const prompt = vi.fn(async () => undefined);
+    mockMake.mockReturnValue({ session: { create: async () => ({ id: 'ses_skill' }), prompt } });
+    const result = await createService().createAndPrompt({ sanitizedInput: validated.sanitized });
+    expect(result.ok).toBe(true);
+    expect(prompt.mock.calls[0][0]).toMatchObject({
+      text: '[skill:release] prepare notes', skills: [{ id: 'release', name: 'release' }], delivery: 'steer',
+    });
+  });
+
   it('returns success when create + prompt succeed', async () => {
     const sessionData = { id: 'ses_created', title: 'Test' };
     mockMake.mockReturnValue({

package/server/lib/conversations/validation.js

@@ -1,6 +1,6 @@
 const ALLOWED_TOP_LEVEL_KEYS = new Set([
   'input', 'directory', 'messageID', 'model', 'parts',
-  'title', 'parentID', 'agent', 'variant', 'metadata',
+  'title', 'parentID', 'agent', 'variant', 'metadata', 'skills',
 ]);
 const ALLOWED_PART_TYPES = new Set(['text', 'file', 'agent']);
 
@@ -139,6 +139,15 @@ export const validateConversationInput = (body) => {
   }
 
   // Optional fields
+  let skills;
+  if (body.skills !== undefined) {
+    if (!Array.isArray(body.skills) || body.skills.some((skill) =>
+      !skill || typeof skill.id !== 'string' || !skill.id.trim())) {
+      errors.push('skills must be an array of non-empty skill ids');
+    } else {
+      skills = body.skills.map((skill) => ({ id: skill.id }));
+    }
+  }
   const title = asOptionalNonEmptyString(body.title);
   if (title === null) errors.push('title must be a non-empty string if provided');
 
@@ -168,6 +177,7 @@ export const validateConversationInput = (body) => {
         modelID: body.model.modelID.trim(),
       },
       parts: sanitizedParts,
+      ...(skills?.length ? { skills } : {}),
       title,
       parentID,
       agent,

package/server/lib/event-stream/DOCUMENTATION.md

@@ -33,7 +33,7 @@ The following APIs are exported by their owning modules. `event-stream/index.js`
 ### Reasoning projection helpers (`reasoning-projection.js`)
 Import from the module file (not the event-stream barrel). Public surface:
 - `shouldIncludeReasoning` / `readIncludeReasoningQuery` / `readIncludeReasoningFromUrl` / `stripIncludeReasoningParam`
-- `projectMessagesPayloadForReasoning` / `projectMessagesPayloadWithoutReasoning` — array / `{ records }` / `{ record }` / `{ parts }` only
+- `projectMessagesPayloadForReasoning` / `projectMessagesPayloadWithoutReasoning` — array / `{ records }` / `{ record }` / `{ parts }`, plus native v2 `{ data }` list/context envelopes and assistant `content[]`. Filtering preserves message identities, cursor, text/tool content and token totals.
 - `createReasoningOutboundFilter` — per-connection stream filter (version-suffix-aware type match; preserves original `type` on kept events)
 - `filterSseBlock` / `createSseBlockSplitter` — SSE disabled path (CR-safe chunk boundaries)
 
@@ -49,6 +49,8 @@ Import from the module file (not the event-stream barrel). Public surface:
 - `createUpstreamSseReader(...)`: creates a start/stop reader for OpenCode SSE streams. The reader parses SSE blocks, tracks the latest `Last-Event-ID`, reconnects after closed or stalled upstream streams, and reports events through callbacks.
 
 ## Runtime behavior
+
+Native v2 `session.reasoning.*` events are filtered at the same outbound boundary as legacy `session.next.reasoning.*`. Both `/api/session/:id/message` and `/api/session/:id/context` use the snapshot projection before relay encryption.
 - Browser clients connect to the WS endpoints above.
 - OpenChamber still fetches OpenCode upstream event streams over SSE.
 - The web server creates one shared global message-stream hub. OpenCode watcher side effects and global WS clients subscribe to that hub, so there is one upstream `/global/event` SSE reader for both server-side processing and browser fan-out.

package/server/lib/event-stream/directory-ws-bridge.js

@@ -21,6 +21,8 @@ export function acceptDirectoryMessageStreamWsConnection({
   buildOpenCodeUrl,
   getOpenCodeAuthHeaders,
   processForwardedEventPayload,
+  /** Optional Host archive/metadata projection for session lifecycle events. */
+  projectOutboundSessionPayload = null,
   wsClients,
   triggerHealthCheck,
   heartbeatIntervalMs,
@@ -78,14 +80,23 @@ export function acceptDirectoryMessageStreamWsConnection({
   const run = async () => {
     const forwardEvent = ({ envelope, payload }) => {
       const directory = requestedDirectory || envelope?.directory || 'global';
+      let outbound = payload;
+      if (typeof projectOutboundSessionPayload === 'function') {
+        try {
+          const projected = projectOutboundSessionPayload(payload);
+          if (projected != null) outbound = projected;
+        } catch (error) {
+          console.warn('[event-stream] directory session projection failed:', error?.message ?? error);
+        }
+      }
 
-      sendMessageStreamWsEvent(socket, payload, {
+      sendMessageStreamWsEvent(socket, outbound, {
         directory,
         eventId: typeof envelope?.eventId === 'string' && envelope.eventId.length > 0 ? envelope.eventId : undefined,
         reasoningFilter,
       });
 
-      processForwardedEventPayload(payload, (syntheticPayload) => {
+      processForwardedEventPayload(outbound, (syntheticPayload) => {
         sendMessageStreamWsEvent(socket, syntheticPayload, {
           directory: 'global',
           reasoningFilter,

package/server/lib/event-stream/global-hub.js

@@ -64,6 +64,13 @@ export function createGlobalMessageStreamHub({
   upstreamReconnectDelayMs,
   replayLimit = MESSAGE_STREAM_GLOBAL_REPLAY_LIMIT,
   getRuntimeIdentity = null,
+  /**
+   * Optional Host authority projection for session.created / session.updated
+   * (and GlobalEvent wrap). Applied before fan-out and replay so browser and
+   * server subscribers share the same archive view. Must be sync and cheap.
+   * @type {((payload: unknown) => unknown) | null}
+   */
+  projectOutboundSessionPayload = null,
 }) {
   const eventSubscribers = new Set();
   const statusSubscribers = new Set();
@@ -97,12 +104,19 @@ export function createGlobalMessageStreamHub({
     }
   };
 
+  let sessionPayloadProjector = typeof projectOutboundSessionPayload === 'function'
+    ? projectOutboundSessionPayload
+    : null;
+
+  /**
+   * Diff-summarize only. Host archive projection is applied at fan-out and
+   * replayAfter time against the *current* committed store — never baked into
+   * the replay buffer (stale archive stamps must not stick after Host writes).
+   */
   const normalizeEvent = ({ envelope, payload, connectionContext }) => {
     const directory =
       typeof envelope?.directory === 'string' && envelope.directory.length > 0 ? envelope.directory : 'global';
     const eventId = typeof envelope?.eventId === 'string' && envelope.eventId.length > 0 ? envelope.eventId : undefined;
-    // Summarize FileDiff bodies before fan-out and replay buffering so reconnect
-    // replay cannot re-amplify full patch frames into >64KB WS payloads.
     const outboundPayload = summarizeOutboundEventPayload(payload);
     return {
       envelope,
@@ -113,6 +127,19 @@ export function createGlobalMessageStreamHub({
     };
   };
 
+  const projectForOutbound = (payload) => {
+    if (typeof sessionPayloadProjector !== 'function') return payload;
+    try {
+      const projected = sessionPayloadProjector(payload);
+      // null = Host not ready; suppress this lifecycle frame.
+      if (projected == null) return null;
+      return projected;
+    } catch (error) {
+      console.warn('[event-stream] session payload projection failed:', error?.message ?? error);
+      return payload;
+    }
+  };
+
   const start = () => {
     if (reader) {
       return;
@@ -161,6 +188,7 @@ export function createGlobalMessageStreamHub({
           ...event,
           connectionContext: event?.connectionContext ?? activeConnectionRuntimeIdentity,
         });
+        // Buffer the unprojected payload so reconnect replay uses current Host authority.
         if (normalized.eventId) {
           replay.push(normalized);
           if (replay.length > replayLimit) {
@@ -168,8 +196,14 @@ export function createGlobalMessageStreamHub({
           }
         }
 
+        const projectedPayload = projectForOutbound(normalized.payload);
+        if (projectedPayload == null) return;
+        const outbound = projectedPayload === normalized.payload
+          ? normalized
+          : { ...normalized, payload: projectedPayload };
+
         for (const subscriber of Array.from(eventSubscribers)) {
-          notifySubscriber('event', subscriber, normalized);
+          notifySubscriber('event', subscriber, outbound);
         }
       },
       onError(error) {
@@ -227,10 +261,21 @@ export function createGlobalMessageStreamHub({
       }
 
       const index = replay.findIndex((entry) => entry.eventId === eventId);
-      return index === -1 ? [] : replay.slice(index + 1);
+      if (index === -1) return [];
+      // Re-project with current committed Host authority at replay time.
+      const out = [];
+      for (const entry of replay.slice(index + 1)) {
+        const projectedPayload = projectForOutbound(entry.payload);
+        if (projectedPayload == null) continue;
+        out.push(projectedPayload === entry.payload ? entry : { ...entry, payload: projectedPayload });
+      }
+      return out;
     },
     setRuntimeIdentityProvider(provider) {
       runtimeIdentityProvider = typeof provider === 'function' ? provider : null;
     },
+    setSessionPayloadProjector(projector) {
+      sessionPayloadProjector = typeof projector === 'function' ? projector : null;
+    },
   };
 }

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

@@ -96,6 +96,10 @@ function projectParts(parts) {
  * @param {unknown} record
  */
 function projectRecord(record) {
+  if (isPlainObject(record) && record.type === 'assistant' && Array.isArray(record.content)) {
+    const content = projectParts(record.content);
+    return content === record.content ? record : { ...record, content };
+  }
   if (!isPlainObject(record) || !Array.isArray(record.parts)) return record;
   const parts = projectParts(record.parts);
   return parts === record.parts ? record : { ...record, parts };
@@ -126,6 +130,17 @@ export function projectMessagesPayloadWithoutReasoning(payload) {
   let next = payload;
   let changed = false;
 
+  if (Array.isArray(payload.data)) {
+    const data = projectMessagesPayloadWithoutReasoning(payload.data);
+    if (data !== payload.data) {
+      next = { ...next, data };
+      changed = true;
+    }
+  }
+  if (payload.type === 'assistant' && Array.isArray(payload.content)) {
+    return projectRecord(payload);
+  }
+
   if (Array.isArray(payload.records)) {
     const records = projectMessagesPayloadWithoutReasoning(payload.records);
     if (records !== payload.records) {
@@ -222,7 +237,7 @@ export function createReasoningOutboundFilter() {
     const type = baseEventType(rawType);
 
     // session.next.reasoning.* (incl. versioned …reasoning.delta.1)
-    if (type.startsWith('session.next.reasoning.')) return null;
+    if (type.startsWith('session.next.reasoning.') || type.startsWith('session.reasoning.')) return null;
 
     if (type === 'message.part.updated') {
       const body = eventBodyOf(payload);

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

@@ -13,6 +13,21 @@ import {
 } from './reasoning-projection.js';
 
 describe('shouldIncludeReasoning / query helpers', () => {
+  it('projects v2 list/context and exact snapshots without dropping rows or cursor', () => {
+    const row = { id: 'm', type: 'assistant', tokens: { reasoning: 12 }, content: [
+      { type: 'reasoning', text: 'hidden' }, { type: 'text', text: 'visible' },
+    ] };
+    const payload = { data: [row], cursor: { next: 'older' } };
+    const projected = projectMessagesPayloadForReasoning(payload, false);
+    expect(projected).toEqual({ data: [{ ...row, content: [row.content[1]] }], cursor: payload.cursor });
+    expect(projectMessagesPayloadForReasoning(row, false)).toEqual(projected.data[0]);
+    expect(projectMessagesPayloadForReasoning(payload, true)).toBe(payload);
+    expect(row.content).toHaveLength(2);
+    const filter = createReasoningOutboundFilter();
+    expect(filter.projectEvent({ type: 'session.reasoning.delta.1', data: { delta: 'hidden' } })).toBeNull();
+    const text = { type: 'session.text.delta', data: { delta: 'visible' } };
+    expect(filter.projectEvent(text)).toBe(text);
+  });
   it('only treats the strict string false as disabled', () => {
     expect(shouldIncludeReasoning(undefined)).toBe(true);
     expect(shouldIncludeReasoning(null)).toBe(true);

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

@@ -6,6 +6,7 @@ import {
   MESSAGE_STREAM_GLOBAL_WS_PATH,
   MESSAGE_STREAM_WS_HEARTBEAT_INTERVAL_MS,
   sendMessageStreamWsEvent,
+  sendMessageStreamWsFrame,
 } from './protocol.js';
 import { createGlobalMessageStreamHub } from './global-hub.js';
 import { createGlobalMessageStreamWsBridge } from './global-ws-bridge.js';
@@ -62,6 +63,9 @@ export function createMessageStreamWsRuntime({
   buildOpenCodeUrl,
   getOpenCodeAuthHeaders,
   processForwardedEventPayload,
+  projectOutboundSessionPayload = null,
+  /** Await Host metadata ready before directory WS attaches upstream. */
+  ensureSessionMetadataReady = null,
   wsClients,
   triggerHealthCheck,
   heartbeatIntervalMs = MESSAGE_STREAM_WS_HEARTBEAT_INTERVAL_MS,
@@ -104,29 +108,62 @@ export function createMessageStreamWsRuntime({
     const includeReasoning = shouldIncludeReasoning(requestUrl.searchParams.get('includeReasoning'));
     const reasoningFilter = includeReasoning ? null : createReasoningOutboundFilter();
 
-    if (isGlobalStream) {
-      globalBridge.accept(socket, {
+    // Host metadata readiness gates *both* global and directory streams before
+    // accept/hub.start — otherwise globalBridge.accept → hub.start bypasses the
+    // gate and lifecycle frames can fan out while the store is still unknown.
+    void (async () => {
+      if (typeof ensureSessionMetadataReady === 'function') {
+        try {
+          const ready = await ensureSessionMetadataReady();
+          if (!ready) {
+            sendMessageStreamWsFrame(socket, {
+              type: 'error',
+              message: 'session metadata is unavailable',
+              code: 'session_metadata_unavailable',
+              retryable: true,
+            });
+            socket.close(1013, 'session metadata unavailable');
+            return;
+          }
+        } catch {
+          sendMessageStreamWsFrame(socket, {
+            type: 'error',
+            message: 'session metadata is unavailable',
+            code: 'session_metadata_unavailable',
+            retryable: true,
+          });
+          socket.close(1013, 'session metadata unavailable');
+          return;
+        }
+      }
+
+      if (socket.readyState !== 1) return;
+
+      if (isGlobalStream) {
+        globalBridge.accept(socket, {
+          requestedLastEventId,
+          reasoningFilter,
+        });
+        return;
+      }
+
+      acceptDirectoryMessageStreamWsConnection({
+        socket,
         requestedLastEventId,
+        requestedDirectory,
         reasoningFilter,
+        buildOpenCodeUrl,
+        getOpenCodeAuthHeaders,
+        processForwardedEventPayload,
+        projectOutboundSessionPayload,
+        wsClients,
+        triggerHealthCheck,
+        heartbeatIntervalMs,
+        upstreamStallTimeoutMs,
+        upstreamReconnectDelayMs,
+        fetchImpl,
       });
-      return;
-    }
-
-    acceptDirectoryMessageStreamWsConnection({
-      socket,
-      requestedLastEventId,
-      requestedDirectory,
-      reasoningFilter,
-      buildOpenCodeUrl,
-      getOpenCodeAuthHeaders,
-      processForwardedEventPayload,
-      wsClients,
-      triggerHealthCheck,
-      heartbeatIntervalMs,
-      upstreamStallTimeoutMs,
-      upstreamReconnectDelayMs,
-      fetchImpl,
-    });
+    })();
   });
 
   const upgradeHandler = (req, socket, head) => {

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

@@ -126,6 +126,118 @@ describe('event stream broadcaster', () => {
   });
 });
 
+describe('message stream websocket runtime Host metadata readiness', () => {
+  it('does not accept/start global hub while metadata load is pending', async () => {
+    const server = new EventEmitter();
+    const wsClients = new Set();
+    let fetchCalls = 0;
+    let releaseReady;
+    const readyGate = new Promise((resolve) => { releaseReady = resolve; });
+
+    const runtime = createMessageStreamWsRuntime({
+      server,
+      uiAuthController: null,
+      isRequestOriginAllowed: async () => true,
+      rejectWebSocketUpgrade() {},
+      buildOpenCodeUrl: (path) => `http://127.0.0.1:4096${path}`,
+      getOpenCodeAuthHeaders: () => ({}),
+      processForwardedEventPayload() {},
+      ensureSessionMetadataReady: async () => {
+        await readyGate;
+        return true;
+      },
+      wsClients,
+      upstreamReconnectDelayMs: 0,
+      fetchImpl: async (_url, options) => {
+        fetchCalls += 1;
+        return createSseResponse({
+          signal: options.signal,
+          holdOpen: true,
+          blocks: [
+            'id: evt-1\ndata: {"type":"session.updated","properties":{"info":{"id":"ses_1","time":{}}}}\n\n',
+          ],
+        });
+      },
+    });
+
+    const socket = new FakeSocket();
+    runtime.wsServer.emit('connection', socket, { url: '/api/global/event/ws' });
+    await new Promise((resolve) => setTimeout(resolve, 15));
+
+    // Still pending → no hub.start → no upstream fetch, no accept frames yet.
+    expect(fetchCalls).toBe(0);
+    expect(socket.closeCalls).toEqual([]);
+    expect(socket.sent.some((f) => f.type === 'event')).toBe(false);
+
+    releaseReady(true);
+    await new Promise((resolve) => setTimeout(resolve, 30));
+
+    expect(fetchCalls).toBe(1);
+    expect(socket.sent.some((f) => f.type === 'event'
+      && f.payload?.type === 'session.updated')).toBe(true);
+
+    socket.close();
+    await runtime.close();
+  });
+
+  it('rejects global connection when metadata ready fails', async () => {
+    const server = new EventEmitter();
+    const runtime = createMessageStreamWsRuntime({
+      server,
+      uiAuthController: null,
+      isRequestOriginAllowed: async () => true,
+      rejectWebSocketUpgrade() {},
+      buildOpenCodeUrl: (path) => `http://127.0.0.1:4096${path}`,
+      getOpenCodeAuthHeaders: () => ({}),
+      processForwardedEventPayload() {},
+      ensureSessionMetadataReady: async () => false,
+      wsClients: new Set(),
+      upstreamReconnectDelayMs: 0,
+      fetchImpl: async () => {
+        throw new Error('upstream must not start');
+      },
+    });
+
+    const socket = new FakeSocket();
+    runtime.wsServer.emit('connection', socket, { url: '/api/global/event/ws' });
+    await new Promise((resolve) => setTimeout(resolve, 15));
+
+    expect(socket.sent.some((f) => f.type === 'error'
+      && f.code === 'session_metadata_unavailable'
+      && f.retryable === true)).toBe(true);
+    expect(socket.closeCalls.some((c) => c.code === 1013)).toBe(true);
+
+    await runtime.close();
+  });
+
+  it('gates directory stream the same way as global', async () => {
+    const server = new EventEmitter();
+    const runtime = createMessageStreamWsRuntime({
+      server,
+      uiAuthController: null,
+      isRequestOriginAllowed: async () => true,
+      rejectWebSocketUpgrade() {},
+      buildOpenCodeUrl: (path) => `http://127.0.0.1:4096${path}`,
+      getOpenCodeAuthHeaders: () => ({}),
+      processForwardedEventPayload() {},
+      ensureSessionMetadataReady: async () => false,
+      wsClients: new Set(),
+      upstreamReconnectDelayMs: 0,
+      fetchImpl: async () => {
+        throw new Error('upstream must not start');
+      },
+    });
+
+    const socket = new FakeSocket();
+    runtime.wsServer.emit('connection', socket, { url: '/api/event/ws?directory=/repo' });
+    await new Promise((resolve) => setTimeout(resolve, 15));
+
+    expect(socket.sent.some((f) => f.code === 'session_metadata_unavailable')).toBe(true);
+    expect(socket.closeCalls.some((c) => c.code === 1013)).toBe(true);
+    await runtime.close();
+  });
+});
+
 describe('message stream websocket runtime', () => {
   it('filters reasoning events per connection when includeReasoning=false', async () => {
     const server = new EventEmitter();

package/server/lib/llm/DOCUMENTATION.md

@@ -23,8 +23,8 @@ only model path the Assistant harness (`pi-agent-core` `streamFn`) talks to.
 
 `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 on `generate.text` and on the
-attachment-session `model` ref. OpenCode owns provider-specific variant
+call. A selected variant is forwarded unchanged on the throwaway session's
+`model` ref (both paths). OpenCode owns provider-specific variant
 semantics. Variant selection changes inference configuration only; completion
 output continues to include text parts and keeps reasoning parts private.
 
@@ -35,10 +35,26 @@ 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`.
+`session.generate` inside a throwaway session owned by the hidden deny-all
+`openchamber-text` agent (same temp root, same deny-all verification and
+`session.create` / `session.remove` lifecycle as the attachment path below):
+
+1. Ensure `.opencode/agent/openchamber-text.md` and verify its final
+   permission rule is deny-all before creating the session.
+2. `session.create({ location, agent: 'openchamber-text', model, metadata })`.
+3. `session.generate({ sessionID, prompt })` → `{ text }`. One model call with
+   the session's provider context, no tool loop, no messages written. System
+   text is prepended into `prompt`.
+4. Always `session.remove` in `finally` (interrupt first on abort/timeout).
+
+`generate.text` (sessionless) is not used: session-scoped providers such as
+OpenCode Go reject calls without a session (`x-opencode-session`).
 `onTextDelta` is skipped honestly (no fake typewriter).
 
+OpenCode loads a fresh location's config lazily, so `agent.get` can report the
+agent as missing on the first read. Deny-all verification polls within a
+bounded window (5s) before failing.
+
 ### Attachment / vision path
 
 When the catalog marks the model vision-capable and the request includes image
@@ -49,8 +65,11 @@ data-URL file parts:
 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).
+3. `session.create({ location, agent, model: { id, providerID, variant? },
+   metadata: { openchamber: { llm: { purpose: 'chat-completions' } } } })`
+   (bare session id). Host `persistSessionMetadata` then commits the same
+   isolation patch; `onSystemSessionPersisted` drops the throwaway session
+   from the sidebar index. Create-time `metadata` is a hint only.
 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`.
@@ -81,7 +100,7 @@ There is no `config.providers` catalog path.
 `onTextDelta(text: string)` and `globalEventHub`.
 
 - **Attachment session path:** real `session.text.delta` tokens for this session.
-- **`generate.text` path:** cannot emit live deltas — skip `onTextDelta`.
+- **`session.generate` text path:** cannot emit live deltas — skip `onTextDelta`.
 - **HTTP `POST .../chat/completions`:** does not pass these options and still
   rejects `stream: true`.
 
@@ -99,8 +118,13 @@ 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 on the attachment path
-via the verified agent permissions ruleset.
+stays a text generator: OpenCode coding tools stay denied on both paths via the
+verified agent permissions ruleset.
+
+The gateway is also the single OpenCode-backed path for server utility calls
+(`small-model`: commit messages, session titles, goal audits, scheduled-task
+distill, TTS summaries, PR descriptions). No server module calls provider APIs
+directly with OpenCode credentials.
 
 Internal completion/generate calls accept an optional AbortSignal from the
 contact continuation. It is combined with the generator deadline and passed to

package/server/lib/llm/catalog.js

@@ -57,7 +57,7 @@ export function projectConnectedModels(source) {
   for (const model of modelsIn) {
     if (!isRecord(model)) continue;
     const providerID = stringID(model.providerID);
-    // External model id for generate.text / session model refs.
+    // External model id for session model refs.
     const modelID = stringID(model.id);
     if (!providerID || !modelID) continue;
     if (providerMeta.size > 0 && !providerMeta.has(providerID)) continue;

package/server/lib/llm/completions.js

@@ -96,11 +96,13 @@ export async function createChatCompletion({
   ensureTempDirectory,
   onTextDelta = null,
   globalEventHub = null,
+  persistSessionMetadata = null,
+  onSystemSessionPersisted = null,
   signal = null,
 }) {
   signal?.throwIfAborted();
   if (!isRecord(body)) throw new LlmError('validation_error', 400, 'JSON body is required');
-  // generate.text / attachment-session return a full turn. This HTTP gateway
+  // session.generate / attachment-session return a full turn. 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) {
@@ -148,6 +150,8 @@ export async function createChatCompletion({
       ))?.acceptsImages),
       onTextDelta,
       globalEventHub,
+      persistSessionMetadata,
+      onSystemSessionPersisted,
       signal,
     });
   } catch (error) {

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

@@ -52,7 +52,7 @@ describe('createChatCompletion', () => {
   })
 
   it('returns a non-stream completion from generateText', async () => {
-    const generateText = vi.fn(async () => ({ text: 'done', source: 'generate.text' }))
+    const generateText = vi.fn(async () => ({ text: 'done', source: 'session.generate' }))
     const result = await createChatCompletion({
       generateText,
       loadCatalog: async () => ({
@@ -64,7 +64,7 @@ describe('createChatCompletion', () => {
     expect(result.completion.choices[0].message.content).toBe('done')
     expect(result.providerID).toBe('openai')
     expect(result.modelID).toBe('gpt-5.2')
-    expect(result.source).toBe('generate.text')
+    expect(result.source).toBe('session.generate')
   })
 
   it('forwards in-process onTextDelta and globalEventHub to generateText', async () => {
@@ -109,7 +109,7 @@ describe('createChatCompletion', () => {
   })
 
   it('asks generate to skip image bytes when the catalog model is not vision-capable', async () => {
-    const generateText = vi.fn(async () => ({ text: 'ok', source: 'generate.text' }))
+    const generateText = vi.fn(async () => ({ text: 'ok', source: 'session.generate' }))
     await createChatCompletion({
       generateText,
       loadCatalog: async () => ({