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

package/server/lib/small-model/opencode-session.js

@@ -0,0 +1,339 @@
+import fs from 'fs';
+import fsPromises from 'fs/promises';
+import os from 'os';
+import path from 'path';
+import { createOpencodeClient } from '@opencode-ai/sdk/v2';
+
+// Temporary OpenCode session path for providers that lack a dedicated
+// small-model adapter (plugin providers, region/credential-chain, …).
+// Auth, endpoint rewrite, and token refresh stay inside the OpenCode runtime.
+
+export const SMALL_MODEL_AGENT_NAME = 'openchamber-smallmodel';
+export const SESSION_SETTLE_TIMEOUT_MS = 60_000;
+const SESSION_SETTLE_POLL_MS = 1_000;
+const ARCHIVE_RETRY_MS = 25;
+const INCOMPLETE_ASSISTANT_SETTLE_PROBES = 2;
+
+const AGENT_MARKDOWN = `---
+mode: primary
+hidden: true
+permissions:
+  - action: "*"
+    resource: "*"
+    effect: deny
+---
+
+You are a utility text generator. Reply with only the requested text. Do not use tools.
+`;
+
+/** @type {string | null} */
+let tempDirectory = null;
+/** @type {Promise<string> | null} */
+let tempDirectoryInflight = null;
+
+const isMissing = (result) =>
+  result?.error?.status === 404
+  || result?.error?.statusCode === 404
+  || result?.error?.code === 'not_found'
+  || result?.status === 404;
+
+const promptAdmitted = (result) =>
+  !result?.error
+  && (result?.response?.status === 204
+    || result?.status === 204
+    || result?.data !== undefined
+    || result?.response?.ok === true);
+
+const sleep = (ms, signal) => new Promise((resolve, reject) => {
+  if (signal?.aborted) {
+    reject(signal.reason instanceof Error ? signal.reason : new Error('aborted'));
+    return;
+  }
+  const timer = setTimeout(resolve, ms);
+  const onAbort = () => {
+    clearTimeout(timer);
+    reject(signal.reason instanceof Error ? signal.reason : new Error('aborted'));
+  };
+  signal?.addEventListener?.('abort', onAbort, { once: true });
+});
+
+const sdkErrorMessage = (result, fallback) => {
+  const status = result?.error?.status ?? result?.error?.statusCode ?? result?.status;
+  const message = result?.error?.message || result?.error?.data?.message || fallback;
+  return status ? `${message} (${status})` : message;
+};
+
+const readMessageInfo = (message) => {
+  if (!message || typeof message !== 'object') return null;
+  if (message.info && typeof message.info === 'object') return message.info;
+  return message;
+};
+
+const assistantTextFromMessages = (messages) => {
+  if (!Array.isArray(messages) || messages.length === 0) return '';
+  for (let i = messages.length - 1; i >= 0; i -= 1) {
+    const message = messages[i];
+    const info = readMessageInfo(message);
+    if (info?.role !== 'assistant') continue;
+    if (info.error) {
+      const detail = typeof info.error === 'string'
+        ? info.error
+        : (info.error?.message || JSON.stringify(info.error));
+      throw new Error(`OpenCode small-model session assistant error: ${detail}`);
+    }
+    const parts = Array.isArray(message?.parts) ? message.parts : [];
+    const text = parts
+      .map((part) => (part?.type === 'text' && typeof part.text === 'string' ? part.text : ''))
+      .filter(Boolean)
+      .join('');
+    return text;
+  }
+  return '';
+};
+
+const ensureTempDirectory = async () => {
+  if (tempDirectory) return tempDirectory;
+  if (!tempDirectoryInflight) {
+    tempDirectoryInflight = (async () => {
+      const root = await fsPromises.mkdtemp(path.join(os.tmpdir(), 'openchamber-smallmodel-'));
+      const agentDir = path.join(root, '.opencode', 'agent');
+      await fsPromises.mkdir(agentDir, { recursive: true });
+      await fsPromises.writeFile(
+        path.join(agentDir, `${SMALL_MODEL_AGENT_NAME}.md`),
+        AGENT_MARKDOWN,
+        'utf8',
+      );
+      tempDirectory = root;
+      return root;
+    })().finally(() => {
+      tempDirectoryInflight = null;
+    });
+  }
+  return tempDirectoryInflight;
+};
+
+const createClient = ({ buildOpenCodeUrl, getOpenCodeAuthHeaders, directory }) => {
+  const baseUrl = buildOpenCodeUrl('/', '').replace(/\/$/, '');
+  return createOpencodeClient({
+    baseUrl,
+    directory,
+    headers: getOpenCodeAuthHeaders(),
+  });
+};
+
+const archiveCreatedSession = async (client, sessionID, directory) => {
+  const archiveAt = Date.now();
+  const update = () => client.session.update({
+    sessionID,
+    directory,
+    time: { archived: archiveAt },
+  });
+  let result = await update();
+  if (isMissing(result)) {
+    await sleep(ARCHIVE_RETRY_MS);
+    result = await update();
+  }
+  if (result?.error || isMissing(result)) {
+    throw new Error(`OpenCode small-model session archive failed: ${sdkErrorMessage(result, 'archive failed')}`);
+  }
+};
+
+const waitForIdleAssistant = async ({ client, sessionID, directory, signal }) => {
+  let incompleteAssistantProbes = 0;
+  let emptyIdleProbes = 0;
+
+  for (;;) {
+    signal?.throwIfAborted?.();
+
+    let sessionBusy = false;
+    try {
+      const statusResult = await client.session.status({ directory }, { signal });
+      if (!statusResult?.error && statusResult?.data && typeof statusResult.data === 'object') {
+        const statusValue = statusResult.data[sessionID];
+        const type = statusValue?.type ?? statusValue?.status;
+        sessionBusy = type === 'busy' || type === 'retry';
+      }
+    } catch (error) {
+      if (signal?.aborted) throw error;
+    }
+
+    if (sessionBusy) {
+      incompleteAssistantProbes = 0;
+      emptyIdleProbes = 0;
+      await sleep(SESSION_SETTLE_POLL_MS, signal);
+      continue;
+    }
+
+    try {
+      const messagesResult = await client.session.messages({
+        sessionID,
+        directory,
+        limit: 20,
+      }, { signal });
+      if (!messagesResult?.error && Array.isArray(messagesResult?.data)) {
+        const lastInfo = readMessageInfo(messagesResult.data.at(-1));
+        if (lastInfo?.role === 'assistant') {
+          emptyIdleProbes = 0;
+          if (lastInfo.error) {
+            const detail = typeof lastInfo.error === 'string'
+              ? lastInfo.error
+              : (lastInfo.error?.message || JSON.stringify(lastInfo.error));
+            throw new Error(`OpenCode small-model session assistant error: ${detail}`);
+          }
+          if (lastInfo.time?.completed) {
+            return messagesResult.data;
+          }
+          incompleteAssistantProbes += 1;
+          if (incompleteAssistantProbes >= INCOMPLETE_ASSISTANT_SETTLE_PROBES) {
+            return messagesResult.data;
+          }
+        } else {
+          incompleteAssistantProbes = 0;
+          emptyIdleProbes += 1;
+          if (emptyIdleProbes >= 5 && lastInfo?.role === 'user') {
+            throw new Error('OpenCode small-model session ended without assistant response');
+          }
+        }
+      }
+    } catch (error) {
+      if (signal?.aborted) throw error;
+      if (error instanceof Error && error.message.startsWith('OpenCode small-model')) throw error;
+    }
+
+    await sleep(SESSION_SETTLE_POLL_MS, signal);
+  }
+};
+
+/**
+ * Generate text via a throwaway OpenCode session (deny-all hidden agent).
+ * Errors are never masked as empty success.
+ *
+ * @param {{
+ *   buildOpenCodeUrl: (pathname: string, search?: string) => string,
+ *   getOpenCodeAuthHeaders: () => Record<string, string>,
+ *   providerID: string,
+ *   modelID: string,
+ *   prompt: string,
+ *   system?: string,
+ *   purpose?: string,
+ *   directory?: string,
+ * }} options
+ */
+export async function generateViaOpenCodeSession({
+  buildOpenCodeUrl,
+  getOpenCodeAuthHeaders,
+  providerID,
+  modelID,
+  prompt,
+  system,
+  purpose,
+  settleTimeoutMs = SESSION_SETTLE_TIMEOUT_MS,
+}) {
+  if (typeof prompt !== 'string' || !prompt.trim()) {
+    throw new Error('OpenCode small-model session requires a prompt');
+  }
+  if (typeof providerID !== 'string' || !providerID.trim() || typeof modelID !== 'string' || !modelID.trim()) {
+    throw new Error('OpenCode small-model session requires providerID and modelID');
+  }
+
+  const purposeLabel = typeof purpose === 'string' && purpose.trim() ? purpose.trim() : 'utility';
+  const budgetMs = Number(settleTimeoutMs) > 0 ? Number(settleTimeoutMs) : SESSION_SETTLE_TIMEOUT_MS;
+  const workingDirectory = await ensureTempDirectory();
+  const client = createClient({
+    buildOpenCodeUrl,
+    getOpenCodeAuthHeaders,
+    directory: workingDirectory,
+  });
+
+  let sessionID = null;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => {
+    controller.abort(new Error(`OpenCode small-model session timed out after ${budgetMs}ms`));
+  }, budgetMs);
+
+  try {
+    const createResult = await client.session.create({
+      directory: workingDirectory,
+      title: `[small-model] ${purposeLabel}`,
+      agent: SMALL_MODEL_AGENT_NAME,
+      metadata: {
+        openchamber: {
+          smallModel: { purpose: purposeLabel },
+        },
+      },
+    }, { signal: controller.signal });
+
+    sessionID = createResult?.data?.id;
+    if (createResult?.error || !sessionID) {
+      throw new Error(`OpenCode small-model session create failed: ${sdkErrorMessage(createResult, 'create failed')}`);
+    }
+
+    // Archive before prompting so ordinary session lists never flash system sessions.
+    await archiveCreatedSession(client, sessionID, workingDirectory);
+
+    const promptResult = await client.session.promptAsync({
+      sessionID,
+      directory: workingDirectory,
+      agent: SMALL_MODEL_AGENT_NAME,
+      model: { providerID, modelID },
+      ...(typeof system === 'string' && system.trim() ? { system: system.trim() } : {}),
+      parts: [{ type: 'text', text: prompt, synthetic: false }],
+    }, { signal: controller.signal });
+
+    if (!promptAdmitted(promptResult)) {
+      throw new Error(`OpenCode small-model prompt_async failed: ${sdkErrorMessage(promptResult, 'prompt_async failed')}`);
+    }
+
+    const messages = await waitForIdleAssistant({
+      client,
+      sessionID,
+      directory: workingDirectory,
+      signal: controller.signal,
+    });
+    const text = assistantTextFromMessages(messages);
+    if (!text.trim()) {
+      throw new Error('OpenCode small-model session returned no assistant text');
+    }
+    return text;
+  } finally {
+    clearTimeout(timeout);
+    if (sessionID) {
+      try {
+        await client.session.delete({ sessionID, directory: workingDirectory });
+      } catch (error) {
+        console.warn(
+          '[small-model] failed to delete temporary OpenCode session:',
+          error?.message || error,
+        );
+      }
+    }
+  }
+};
+
+/** Best-effort cleanup of the lazy temp directory (agent markdown + empty root). */
+export async function stop() {
+  const dir = tempDirectory;
+  tempDirectory = null;
+  tempDirectoryInflight = null;
+  if (!dir) return;
+  try {
+    await fsPromises.rm(dir, { recursive: true, force: true });
+  } catch (error) {
+    // Sync fallback if async rm races a partially-created tree.
+    try {
+      fs.rmSync(dir, { recursive: true, force: true });
+    } catch {
+      console.warn('[small-model] failed to remove temp directory:', error?.message || error);
+    }
+  }
+}
+
+/** @internal test helpers */
+export const _test = {
+  getTempDirectory: () => tempDirectory,
+  resetTempDirectory: () => {
+    tempDirectory = null;
+    tempDirectoryInflight = null;
+  },
+  AGENT_MARKDOWN,
+};

package/server/lib/small-model/opencode-session.test.js

@@ -0,0 +1,177 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import fsPromises from 'fs/promises';
+import path from 'path';
+
+vi.mock('@opencode-ai/sdk/v2', () => ({
+  createOpencodeClient: vi.fn(),
+}));
+
+const { createOpencodeClient } = await import('@opencode-ai/sdk/v2');
+const {
+  generateViaOpenCodeSession,
+  stop,
+  SMALL_MODEL_AGENT_NAME,
+  _test,
+} = await import('./opencode-session.js');
+
+const buildOpenCodeUrl = () => 'http://127.0.0.1:4096/';
+const getOpenCodeAuthHeaders = () => ({ authorization: 'Bearer test' });
+
+const completedAssistant = (text) => ({
+  info: {
+    role: 'assistant',
+    time: { completed: Date.now() },
+  },
+  parts: [{ type: 'text', text }],
+});
+
+const createMockClient = ({
+  create = vi.fn(async () => ({ data: { id: 'ses_small_1' } })),
+  update = vi.fn(async () => ({ data: { id: 'ses_small_1' } })),
+  promptAsync = vi.fn(async () => ({ response: { status: 204 } })),
+  status = vi.fn(async () => ({ data: { ses_small_1: { type: 'idle' } } })),
+  messages = vi.fn(async () => ({ data: [completedAssistant('Hello from session')] })),
+  deleteSession = vi.fn(async () => ({ data: true })),
+} = {}) => {
+  const client = {
+    session: {
+      create,
+      update,
+      promptAsync,
+      status,
+      messages,
+      delete: deleteSession,
+    },
+  };
+  createOpencodeClient.mockReturnValue(client);
+  return { client, create, update, promptAsync, status, messages, deleteSession };
+};
+
+describe('generateViaOpenCodeSession', () => {
+  beforeEach(() => {
+    createOpencodeClient.mockReset();
+    _test.resetTempDirectory();
+  });
+
+  afterEach(async () => {
+    await stop();
+    _test.resetTempDirectory();
+  });
+
+  it('creates a marked archived session, prompts, returns assistant text, and deletes', async () => {
+    const { create, update, promptAsync, deleteSession } = createMockClient();
+
+    const text = await generateViaOpenCodeSession({
+      buildOpenCodeUrl,
+      getOpenCodeAuthHeaders,
+      providerID: 'codebuddy',
+      modelID: 'codebuddy-flash',
+      prompt: 'Summarize this',
+      system: 'Be brief',
+      purpose: 'session-title',
+    });
+
+    expect(text).toBe('Hello from session');
+    expect(createOpencodeClient).toHaveBeenCalledWith(expect.objectContaining({
+      baseUrl: 'http://127.0.0.1:4096',
+      headers: { authorization: 'Bearer test' },
+    }));
+
+    const tempDir = create.mock.calls[0][0].directory;
+    expect(tempDir).toMatch(/openchamber-smallmodel-/);
+    expect(await fsPromises.readFile(
+      path.join(tempDir, '.opencode', 'agent', `${SMALL_MODEL_AGENT_NAME}.md`),
+      'utf8',
+    )).toContain('effect: deny');
+
+    expect(create).toHaveBeenCalledWith(expect.objectContaining({
+      directory: tempDir,
+      title: '[small-model] session-title',
+      agent: SMALL_MODEL_AGENT_NAME,
+      metadata: {
+        openchamber: {
+          smallModel: { purpose: 'session-title' },
+        },
+      },
+    }), expect.any(Object));
+
+    expect(update).toHaveBeenCalledWith(expect.objectContaining({
+      sessionID: 'ses_small_1',
+      directory: tempDir,
+      time: { archived: expect.any(Number) },
+    }));
+
+    expect(promptAsync).toHaveBeenCalledWith(expect.objectContaining({
+      sessionID: 'ses_small_1',
+      directory: tempDir,
+      agent: SMALL_MODEL_AGENT_NAME,
+      model: { providerID: 'codebuddy', modelID: 'codebuddy-flash' },
+      system: 'Be brief',
+      parts: [{ type: 'text', text: 'Summarize this', synthetic: false }],
+    }), expect.any(Object));
+
+    expect(deleteSession).toHaveBeenCalledWith({
+      sessionID: 'ses_small_1',
+      directory: tempDir,
+    });
+  });
+
+  it('throws on settle timeout and still best-effort deletes the session', async () => {
+    const { deleteSession } = createMockClient({
+      status: vi.fn(async () => ({ data: { ses_small_1: { type: 'busy' } } })),
+      messages: vi.fn(async () => ({ data: [] })),
+    });
+
+    await expect(generateViaOpenCodeSession({
+      buildOpenCodeUrl,
+      getOpenCodeAuthHeaders,
+      providerID: 'codebuddy',
+      modelID: 'codebuddy-flash',
+      prompt: 'hang',
+      purpose: 'commit',
+      settleTimeoutMs: 80,
+    })).rejects.toThrow(/timed out/);
+    expect(deleteSession).toHaveBeenCalled();
+  });
+
+  it('does not swallow a successful result when session.delete fails', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    createMockClient({
+      deleteSession: vi.fn(async () => {
+        throw new Error('delete boom');
+      }),
+    });
+
+    const text = await generateViaOpenCodeSession({
+      buildOpenCodeUrl,
+      getOpenCodeAuthHeaders,
+      providerID: 'codebuddy',
+      modelID: 'codebuddy-flash',
+      prompt: 'ok',
+      purpose: 'commit',
+    });
+
+    expect(text).toBe('Hello from session');
+    expect(warn).toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it('throws when the assistant returns empty text', async () => {
+    createMockClient({
+      messages: vi.fn(async () => ({
+        data: [{
+          info: { role: 'assistant', time: { completed: Date.now() } },
+          parts: [{ type: 'text', text: '   ' }],
+        }],
+      })),
+    });
+
+    await expect(generateViaOpenCodeSession({
+      buildOpenCodeUrl,
+      getOpenCodeAuthHeaders,
+      providerID: 'codebuddy',
+      modelID: 'codebuddy-flash',
+      prompt: 'empty',
+    })).rejects.toThrow(/no assistant text/);
+  });
+});

package/server/lib/small-model/resolve.js

@@ -1,15 +1,38 @@
 import { getCatalogProvider } from './catalog.js';
 
-// Mirrors OpenCode's getSmallModel fallback chain:
+// Mirrors OpenCode's getSmallModel fallback chain, with OpenChamber's own
+// keyword + cheapest-first default when no session/family match applies:
 // 1. `small_model` from the merged config layers ("provider/model").
-// 2. GitHub Copilot's hidden utility models when Copilot is logged in.
-// 3. Family-priority scan of the authenticated providers' catalog models.
+// 2. Family-priority / keyword scan of authenticated providers' catalog models.
+// 3. GitHub Copilot's hidden utility models when Copilot is logged in.
 const FAMILY_PRIORITY = ['gemini-flash', 'gpt-nano', 'claude-haiku'];
 const COPILOT_UTILITY_MODELS = ['gpt-5.4-nano', 'gpt-4.1', 'gpt-4o', 'gpt-4o-mini'];
 // The ChatGPT-plan codex backend only accepts a small allowlist of models
 // (nano/API-key models are rejected with 400) — this is its cheapest one.
 const OPENAI_OAUTH_SMALL_MODEL = 'gpt-5.4-mini';
 
+// Tokenize model ids so "mini" does not match inside "gemini".
+const modelIdTokens = (id) => String(id || '')
+  .toLowerCase()
+  .split(/[^a-z0-9]+/i)
+  .filter(Boolean);
+
+const idHasToken = (id, token) => modelIdTokens(id).includes(token);
+
+// Small-model keyword tiers (lower = better). Known OpenCode families stay
+// highest; broader name tokens cover plugin / catalog models without a family.
+const SMALL_MODEL_KEYWORD_TIERS = Object.freeze([
+  { tier: 0, test: (id, family) => family === 'gemini-flash' || idHasToken(id, 'flash') },
+  { tier: 1, test: (id, family) => family === 'gpt-nano' || idHasToken(id, 'nano') },
+  { tier: 2, test: (id, family) => family === 'claude-haiku' || idHasToken(id, 'haiku') },
+  { tier: 3, test: (id) => idHasToken(id, 'mini') },
+  { tier: 4, test: (id) => idHasToken(id, 'lite') },
+  { tier: 5, test: (id) => idHasToken(id, 'turbo') },
+  { tier: 6, test: (id) => idHasToken(id, 'instant') },
+  { tier: 7, test: (id) => idHasToken(id, 'small') },
+  { tier: 8, test: (id) => idHasToken(id, 'chat') },
+]);
+
 const AUTH_PROVIDER_ALIASES = {
   'github-copilot': ['github-copilot', 'copilot'],
 };
@@ -51,10 +74,47 @@ const pickByFamily = (models, family) => {
   const matches = Object.values(models)
     .filter((model) => model && typeof model === 'object' && model.family === family);
   if (matches.length === 0) return null;
-  matches.sort((a, b) => String(b.release_date || '').localeCompare(String(a.release_date || '')));
+  matches.sort(compareSmallModelCandidates);
   return matches[0];
 };
 
+const smallModelKeywordTier = (model) => {
+  const id = typeof model?.id === 'string' ? model.id : '';
+  const family = typeof model?.family === 'string' ? model.family : '';
+  for (const entry of SMALL_MODEL_KEYWORD_TIERS) {
+    if (entry.test(id, family)) return entry.tier;
+  }
+  return Number.POSITIVE_INFINITY;
+};
+
+const costInputOrLast = (model) => {
+  const input = model?.cost?.input;
+  return Number.isFinite(input) ? input : Number.POSITIVE_INFINITY;
+};
+
+/** Cheapest input cost first; missing cost last; newer release_date wins ties. */
+export function compareSmallModelCandidates(a, b) {
+  const costDiff = costInputOrLast(a) - costInputOrLast(b);
+  if (costDiff !== 0) return costDiff;
+  return String(b.release_date || '').localeCompare(String(a.release_date || ''));
+}
+
+/**
+ * Rank catalog models for the default (no explicit config) small-model pick:
+ * keyword tier → cost.input asc (missing last) → release_date desc.
+ */
+export function rankSmallModelCandidates(models) {
+  return Object.values(models || {})
+    .filter((model) => model && typeof model === 'object' && typeof model.id === 'string' && model.id)
+    .map((model) => ({ model, tier: smallModelKeywordTier(model) }))
+    .filter((entry) => Number.isFinite(entry.tier))
+    .sort((a, b) => {
+      if (a.tier !== b.tier) return a.tier - b.tier;
+      return compareSmallModelCandidates(a.model, b.model);
+    })
+    .map((entry) => entry.model);
+}
+
 // Small-model candidates within ONE provider, by family priority. Copilot and
 // ChatGPT-plan OpenAI have fixed small models that never appear in the
 // catalog; everyone else is scanned through the catalog families.
@@ -89,6 +149,47 @@ const pickWithinProvider = (providerID, auth, catalog, family) => {
   return model?.id ? { providerID, modelID: model.id, source: 'family-scan' } : null;
 };
 
+const pickKeywordDefault = (auth, catalog, excludeProviderID) => {
+  /** @type {Array<{ providerID: string, model: object }>} */
+  const candidates = [];
+  const providerIDs = Object.keys(auth || {}).filter((providerID) => {
+    if (providerID === 'copilot') return false;
+    if (excludeProviderID && providerID === excludeProviderID) return false;
+    return isUsableAuthEntry(getAuthEntryForProvider(auth, providerID));
+  });
+  // Surface github-copilot when only the `copilot` alias is present.
+  if (
+    !providerIDs.includes('github-copilot')
+    && isUsableAuthEntry(getAuthEntryForProvider(auth, 'github-copilot'))
+    && excludeProviderID !== 'github-copilot'
+  ) {
+    providerIDs.push('github-copilot');
+  }
+
+  for (const providerID of providerIDs) {
+    if (providerID === 'openai' && auth.openai?.type === 'oauth') continue;
+    if (providerID === 'github-copilot') continue;
+    if (providerID === 'openai' && (auth.openai?.type !== 'api' || !isUsableAuthEntry(auth.openai))) continue;
+    if (providerID === 'anthropic' && (auth.anthropic?.type !== 'api' || !isUsableAuthEntry(auth.anthropic))) continue;
+    if (providerID === 'google' && (auth.google?.type !== 'api' || !isUsableAuthEntry(auth.google))) continue;
+
+    const provider = getCatalogProvider(catalog, providerID);
+    if (!provider?.models) continue;
+    for (const model of rankSmallModelCandidates(provider.models)) {
+      candidates.push({ providerID, model });
+    }
+  }
+
+  if (candidates.length === 0) return null;
+  candidates.sort((a, b) => {
+    const tierDiff = smallModelKeywordTier(a.model) - smallModelKeywordTier(b.model);
+    if (tierDiff !== 0) return tierDiff;
+    return compareSmallModelCandidates(a.model, b.model);
+  });
+  const best = candidates[0];
+  return { providerID: best.providerID, modelID: best.model.id, source: 'keyword-scan' };
+};
+
 export function resolveSmallModel({ auth, catalog, settingsSmallModel, configSmallModel, preferredProviderID, preferredModelID }) {
   // OpenChamber's own setting (Settings → Sessions → Small Model override)
   // outranks everything, including the OpenCode config.
@@ -114,13 +215,20 @@ export function resolveSmallModel({ auth, catalog, settingsSmallModel, configSma
       const match = pickWithinProvider(preferred, auth, catalog, family);
       if (match) return match;
     }
+    const preferredCatalog = getCatalogProvider(catalog, preferred);
+    if (preferredCatalog?.models) {
+      const ranked = rankSmallModelCandidates(preferredCatalog.models);
+      if (ranked[0]?.id) {
+        return { providerID: preferred, modelID: ranked[0].id, source: 'keyword-scan' };
+      }
+    }
     if (typeof preferredModelID === 'string' && preferredModelID) {
       return { providerID: preferred, modelID: preferredModelID, source: 'session-model' };
     }
   }
 
   // No session context (or its provider has no usable login): scan all
-  // authenticated providers by family priority.
+  // authenticated providers by family priority, then keyword+cost default.
   const authedProviders = Object.keys(auth || {}).filter((providerID) =>
     providerID !== preferred && isUsableAuthEntry(auth[providerID]));
 
@@ -131,6 +239,9 @@ export function resolveSmallModel({ auth, catalog, settingsSmallModel, configSma
     }
   }
 
+  const keywordDefault = pickKeywordDefault(auth, catalog, preferred);
+  if (keywordDefault) return keywordDefault;
+
   // Copilot's utility fallback for legacy auth aliases the loop above missed.
   const copilotEntry = getAuthEntryForProvider(auth, 'github-copilot');
   if (isUsableAuthEntry(copilotEntry)) {