ompchamber 2.0.2 → 3.1.0

package/src/server/lib/omp/config/models-config.ts

@@ -36,6 +36,12 @@ export interface NativeProviderInfo {
   slug: string;
   /** Base URL of the provider API, when configured. */
   baseUrl?: string;
+  /** Wire dialect from the entry's `api`, when it declares one. */
+  api?: string;
+  /** Auth mode from the entry's `auth`; `none` means keyless. */
+  auth?: string;
+  /** Discovery type from the entry's `discovery`, when omp lists its models. */
+  discovery?: string;
   /** Model ids registered under this provider in models.yml. */
   modelIds: string[];
   models: NativeModelInfo[];
@@ -69,6 +75,11 @@ export async function readNativeProviders(): Promise<NativeProviderInfo[]> {
       const info: NativeProviderInfo = { slug, modelIds: [], models: [] };
       if (isRecord(value)) {
         if (typeof value.baseUrl === 'string') info.baseUrl = value.baseUrl;
+        if (typeof value.api === 'string') info.api = value.api;
+        if (typeof value.auth === 'string') info.auth = value.auth;
+        if (isRecord(value.discovery) && typeof value.discovery.type === 'string') {
+          info.discovery = value.discovery.type;
+        }
         if (Array.isArray(value.models)) {
           info.models = value.models.flatMap((model) => {
             if (!isRecord(model) || typeof model.id !== 'string') return [];

package/src/server/lib/omp/config/models-validation.test.ts

@@ -0,0 +1,137 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Validation of the provider shapes the settings UI can now write.
+ *
+ * omp's failure mode is what makes these worth locking: one schema violation
+ * anywhere in `models.yml` makes it disable EVERY custom provider at once, so a
+ * dialect or auth value the UI let through takes the whole registry down. Each
+ * case below was verified against omp 18.3.0 by loading the document.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { validateModelsDocument } from '@/server/lib/omp/config/models-validation';
+
+describe('validateModelsDocument — dialect fields', () => {
+  test('accepts every api omp ships', () => {
+    const apis = [
+      'openai-completions', 'openai-responses', 'openai-codex-responses',
+      'azure-openai-responses', 'anthropic-messages', 'bedrock-converse-stream',
+      'google-generative-ai', 'google-gemini-cli', 'google-vertex',
+      'openrouter-decisions', 'typesafe',
+    ];
+    for (const api of apis) {
+      expect(validateModelsDocument({ providers: { p: { api, baseUrl: 'https://x/v1', apiKey: 'k' } } }))
+        .toEqual([]);
+    }
+  });
+
+  test('rejects an api omp does not know', () => {
+    const errors = validateModelsDocument({
+      providers: { p: { api: 'openai-completions-v2', baseUrl: 'https://x/v1', apiKey: 'k' } },
+    });
+    expect(errors.length).toBe(1);
+    expect(errors[0]).toContain('unknown "api" value');
+  });
+
+  test('accepts the three auth modes and rejects anything else', () => {
+    for (const auth of ['apiKey', 'none', 'oauth']) {
+      expect(validateModelsDocument({ providers: { p: { baseUrl: 'https://x/v1', auth } } })).toEqual([]);
+    }
+    const errors = validateModelsDocument({ providers: { p: { baseUrl: 'https://x/v1', auth: 'bearer' } } });
+    expect(errors.some((error) => error.includes('unknown "auth" value'))).toBe(true);
+  });
+
+  test('a keyless provider needs no apiKey even with models', () => {
+    // This is the shape a local server is registered with; demanding a key here
+    // is what made every keyless provider look unconfigured.
+    expect(validateModelsDocument({
+      providers: { local: { baseUrl: 'http://127.0.0.1:11434/v1', api: 'openai-responses', auth: 'none', models: [{ id: 'm' }] } },
+    })).toEqual([]);
+  });
+
+  test('a models-carrying provider without auth still requires a key', () => {
+    const errors = validateModelsDocument({
+      providers: { p: { baseUrl: 'https://x/v1', api: 'openai-completions', models: [{ id: 'm' }] } },
+    });
+    expect(errors.some((error) => error.includes('"apiKey" is required'))).toBe(true);
+  });
+});
+
+describe('validateModelsDocument — discovery', () => {
+  test('accepts a discovery shell with no models at all', () => {
+    // A discovery provider legitimately carries an empty model list; omp lists
+    // the models itself.
+    expect(validateModelsDocument({
+      providers: { disc: { baseUrl: 'http://127.0.0.1:11434', api: 'openai-responses', discovery: { type: 'ollama' } } },
+    })).toEqual([]);
+  });
+
+  test('accepts every discovery type omp ships', () => {
+    for (const type of ['ollama', 'llama.cpp', 'lm-studio', 'openai-models-list', 'litellm', 'apple-foundation-models']) {
+      expect(validateModelsDocument({
+        providers: { p: { baseUrl: 'https://x/v1', api: 'openai-completions', discovery: { type } } },
+      })).toEqual([]);
+    }
+    expect(validateModelsDocument({
+      providers: { p: { baseUrl: 'https://x/v1', api: 'openai-completions', discovery: { type: 'proxy' } } },
+    })).toEqual([]);
+  });
+
+  test('rejects an unknown discovery type', () => {
+    const errors = validateModelsDocument({
+      providers: { p: { baseUrl: 'https://x/v1', api: 'openai-completions', discovery: { type: 'vllm' } } },
+    });
+    expect(errors.some((error) => error.includes('unknown discovery type'))).toBe(true);
+  });
+
+  test('discovery without a provider api is refused, except for proxy', () => {
+    const withoutApi = validateModelsDocument({
+      providers: { p: { baseUrl: 'https://x/v1', discovery: { type: 'openai-models-list' } } },
+    });
+    expect(withoutApi.some((error) => error.includes('"api" is required when discovery'))).toBe(true);
+
+    const proxy = validateModelsDocument({
+      providers: { p: { baseUrl: 'https://x/v1', discovery: { type: 'proxy' } } },
+    });
+    expect(proxy).toEqual([]);
+  });
+
+  test('injectV1 is only allowed on openai-models-list', () => {
+    const errors = validateModelsDocument({
+      providers: { p: { baseUrl: 'https://x/v1', api: 'openai-completions', discovery: { type: 'ollama', injectV1: false } } },
+    });
+    expect(errors.some((error) => error.includes('injectV1 only on'))).toBe(true);
+  });
+});
+
+describe('validateModelsDocument — override-only providers', () => {
+  test('a bare endpoint override for a bundled provider is valid', () => {
+    // The documented way to point a bundled provider at a proxy: no models,
+    // just an endpoint. omp then keeps serving its own model list.
+    expect(validateModelsDocument({ providers: { anthropic: { baseUrl: 'https://proxy.example.com' } } }))
+      .toEqual([]);
+  });
+
+  test('a provider with no configuration at all is still refused', () => {
+    const errors = validateModelsDocument({ providers: { empty: {} } });
+    expect(errors.length).toBe(1);
+    expect(errors[0]).toContain('must specify');
+  });
+
+  test('an empty apiKey is refused — omp rejects it', () => {
+    const errors = validateModelsDocument({ providers: { p: { baseUrl: 'https://x/v1', apiKey: '' } } });
+    expect(errors.some((error) => error.includes('"apiKey" must be a non-empty string'))).toBe(true);
+  });
+
+  test('a map-form models entry is refused as a file-breaking shape', () => {
+    const errors = validateModelsDocument({
+      providers: { p: { baseUrl: 'https://x/v1', apiKey: 'k', models: { a: {} } } },
+    });
+    expect(errors).toEqual(['Provider p: "models" must be an array']);
+  });
+});

package/src/server/lib/omp/config/models-validation.ts

@@ -38,6 +38,70 @@ const API_VALUES = new Set([
 /** Auth modes that make an `apiKey` optional (omp: `ProviderAuthSchema`). */
 const KEYLESS_AUTH = new Set(['none', 'oauth']);
 
+/** Every value omp's `ProviderAuthSchema` accepts. */
+const AUTH_VALUES = new Set(['apiKey', 'none', 'oauth']);
+
+/** Every value omp's `ProviderDiscoverySchema.type` accepts. */
+const DISCOVERY_TYPES = new Set([
+  'ollama',
+  'llama.cpp',
+  'lm-studio',
+  'openai-models-list',
+  'proxy',
+  'litellm',
+  'apple-foundation-models',
+]);
+
+/** Every value omp's `ThinkingControlModeSchema` accepts. */
+const THINKING_MODES = new Set([
+  'effort',
+  'budget',
+  'google-level',
+  'anthropic-adaptive',
+  'anthropic-budget-effort',
+]);
+
+/** Every value omp's `EffortSchema` accepts. `off` is NOT one of them. */
+const EFFORT_VALUES = new Set(['minimal', 'low', 'medium', 'high', 'xhigh', 'max']);
+
+/**
+ * Every reason a `thinking` block would fail omp's `ModelThinkingSchema`.
+ *
+ * The block is written by the chamber whenever a user ticks an effort ladder,
+ * and omp's failure mode is unforgiving: a missing `mode` or an effort outside
+ * the vocabulary makes it disable EVERY custom provider in the file.
+ */
+function thinkingErrors(label: string, thinking: unknown): string[] {
+  const errors: string[] = [];
+  if (!isRecord(thinking)) return [`${label}: "thinking" must be a mapping`];
+  if (thinking.mode === undefined) {
+    errors.push(`${label}: "thinking.mode" is required`);
+  } else if (!THINKING_MODES.has(String(thinking.mode))) {
+    errors.push(`${label}: unknown thinking mode ${JSON.stringify(thinking.mode)}`);
+  }
+  const efforts = thinking.efforts;
+  if (efforts !== undefined) {
+    if (!Array.isArray(efforts)) {
+      errors.push(`${label}: "thinking.efforts" must be an array`);
+    } else {
+      for (const effort of efforts) {
+        if (!EFFORT_VALUES.has(String(effort))) {
+          errors.push(`${label}: unknown thinking effort ${JSON.stringify(effort)}`);
+        }
+      }
+    }
+  }
+  // `efforts` is what makes the ladder meaningful; omp requires one of the
+  // three vocabularies, so a block carrying none of them is rejected on load.
+  const hasLadder = Array.isArray(efforts)
+    || Array.isArray(thinking.levels)
+    || (thinking.minLevel !== undefined && thinking.maxLevel !== undefined);
+  if (!hasLadder) {
+    errors.push(`${label}: "thinking" needs "efforts" (or legacy "levels"/"minLevel"+"maxLevel")`);
+  }
+  return errors;
+}
+
 /** A finite number, which is what omp's `"number"` type means — `NaN` and `Infinity` are rejected. */
 function isFiniteNumber(value: unknown): value is number {
   return typeof value === 'number' && Number.isFinite(value);
@@ -75,6 +139,28 @@ export function validateModelsDocument(doc: Record<string, unknown> | null | und
     if (typeof value.apiKey === 'string' && value.apiKey.length === 0) {
       errors.push(`Provider ${slug}: "apiKey" must be a non-empty string`);
     }
+    if (value.auth !== undefined && !AUTH_VALUES.has(String(value.auth))) {
+      errors.push(`Provider ${slug}: unknown "auth" value ${JSON.stringify(value.auth)}`);
+    }
+    const discovery = value.discovery;
+    if (discovery !== undefined) {
+      if (!isRecord(discovery)) {
+        errors.push(`Provider ${slug}: "discovery" must be a mapping`);
+      } else {
+        const type = String(discovery.type);
+        if (!DISCOVERY_TYPES.has(type)) {
+          errors.push(`Provider ${slug}: unknown discovery type ${JSON.stringify(discovery.type)}`);
+        }
+        // omp needs a dialect to interpret the discovered entries; a proxy
+        // reports one per model instead, so it is the documented exception.
+        if (providerApi === undefined && type !== 'proxy') {
+          errors.push(`Provider ${slug}: "api" is required when discovery is enabled at provider level.`);
+        }
+        if (discovery.injectV1 !== undefined && type !== 'openai-models-list') {
+          errors.push(`Provider ${slug}: injectV1 only on openai-models-list discovery`);
+        }
+      }
+    }
 
     const models = value.models;
     if (models !== undefined && !Array.isArray(models)) {
@@ -94,8 +180,21 @@ export function validateModelsDocument(doc: Record<string, unknown> | null | und
       if (typeof value.apiKey !== 'string' && !KEYLESS_AUTH.has(auth)) {
         errors.push(`Provider ${slug}: "apiKey" is required when defining custom models unless auth is "none" or "oauth".`);
       }
-    } else if (!value.baseUrl && !value.apiKey && !value.discovery && value.auth !== 'none' && !value.modelOverrides) {
-      errors.push(`Provider ${slug}: must specify "baseUrl", "apiKey", "auth: none", "discovery", "modelOverrides", or "models"`);
+    } else if (
+      !value.baseUrl
+      && !value.apiKey
+      && !value.headers
+      && !value.compat
+      && !value.discovery
+      && !value.remoteCompaction
+      && !value.disableStrictTools
+      && !value.modelOverrides
+      && value.auth !== 'none'
+    ) {
+      errors.push(
+        `Provider ${slug}: must specify "baseUrl", "apiKey", "auth: none", "headers", "compat", `
+        + '"discovery", "remoteCompaction", "modelOverrides", or "models"',
+      );
     }
 
     for (const [index, model] of modelList.entries()) {
@@ -111,6 +210,9 @@ export function validateModelsDocument(doc: Record<string, unknown> | null | und
       if (model.api !== undefined && !API_VALUES.has(String(model.api))) {
         errors.push(`Provider ${slug}, model ${id}: unknown "api" value ${JSON.stringify(model.api)}`);
       }
+      if (model.thinking !== undefined) {
+        errors.push(...thinkingErrors(`Provider ${slug}, model ${id}`, model.thinking));
+      }
       if (providerApi === undefined && model.api === undefined) {
         errors.push(`Provider ${slug}, model ${id}: no "api" specified. Set at provider or model level.`);
       }
@@ -153,6 +255,13 @@ export function sanitizeModelEntry(model: Record<string, unknown>): Record<strin
       delete next.cost;
     }
   }
+  // An unusable ladder is dropped rather than written: a `thinking` block with
+  // no mode, or with an effort omp does not know, takes EVERY custom provider
+  // down with it. Dropping it leaves the model with omp's default ladder, which
+  // is the honest repair — the model still runs.
+  if (next.thinking !== undefined && thinkingErrors('model', next.thinking).length > 0) {
+    delete next.thinking;
+  }
   if (!isOptionalPositive(next.contextWindow)) delete next.contextWindow;
   if (!isOptionalPositive(next.maxTokens)) delete next.maxTokens;
   return next;

package/src/server/lib/omp/config/provider-seeds.test.ts

@@ -0,0 +1,167 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The seed a hand-entered model becomes.
+ *
+ * The Add Model dialog is the only writer whose values come from a person
+ * rather than a provider listing, so it is the only one that can carry a
+ * mistake into models.yml. omp's failure mode is what makes that expensive: one
+ * bad entry makes it disable EVERY custom provider in the file, so a
+ * non-positive limit or a half-filled price has to be dropped here rather than
+ * validated after the fact.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { manualModelSeed, toModelEntry } from '@/server/lib/omp/config/provider-seeds';
+import { validateModelsDocument, sanitizeModelEntry } from '@/server/lib/omp/config/models-validation';
+
+describe('manualModelSeed', () => {
+  test('keeps the metadata the user entered', () => {
+    expect(manualModelSeed({
+      id: 'my-model',
+      name: 'My Model',
+      contextWindow: 200000,
+      maxTokens: 8192,
+      reasoning: true,
+      imageInput: true,
+      costInput: 0.5,
+      costOutput: 1.5,
+      costCacheRead: 0.05,
+      costCacheWrite: 0.1,
+    })).toEqual({
+      id: 'my-model',
+      name: 'My Model',
+      reasoning: true,
+      imageInput: true,
+      contextWindow: 200000,
+      maxTokens: 8192,
+      cost: { input: 0.5, output: 1.5, cacheRead: 0.05, cacheWrite: 0.1 },
+    });
+  });
+
+  test('an id alone is a valid entry', () => {
+    // The common case is "add this id I know exists" — every other field is
+    // metadata omp can work without, so requiring them would block it.
+    expect(manualModelSeed({ id: '  bare-id  ' })).toEqual({ id: 'bare-id' });
+  });
+
+  test('drops non-positive limits instead of writing them', () => {
+    // omp rejects contextWindow/maxTokens <= 0 outright, which takes every
+    // custom provider down with it.
+    const seed = manualModelSeed({ id: 'm', contextWindow: 0, maxTokens: -1 });
+    expect(seed.contextWindow).toBeUndefined();
+    expect(seed.maxTokens).toBeUndefined();
+  });
+
+  test('rounds fractional token counts', () => {
+    expect(manualModelSeed({ id: 'm', contextWindow: 128000.7 }).contextWindow).toBe(128001);
+  });
+
+  test('writes a price only when both sides are known', () => {
+    // omp's schema requires all four cost fields together; half a price would
+    // be a schema violation, not a partial price.
+    expect(manualModelSeed({ id: 'm', costInput: 1 }).cost).toBeUndefined();
+    expect(manualModelSeed({ id: 'm', costOutput: 1 }).cost).toBeUndefined();
+    expect(manualModelSeed({ id: 'm', costInput: 1, costOutput: 2 }).cost)
+      .toEqual({ input: 1, output: 2, cacheRead: 0, cacheWrite: 0 });
+  });
+
+  test('a seed the user entered produces a document omp accepts', () => {
+    const seed = manualModelSeed({
+      id: 'my-model',
+      name: 'My Model',
+      contextWindow: 200000,
+      maxTokens: 8192,
+      reasoning: true,
+      costInput: 0,
+      costOutput: 0,
+    });
+    const entry = sanitizeModelEntry({
+      id: seed.id,
+      ...(seed.name ? { name: seed.name } : {}),
+      ...(seed.reasoning !== undefined ? { reasoning: seed.reasoning } : {}),
+      input: ['text'],
+      ...(seed.contextWindow ? { contextWindow: seed.contextWindow } : {}),
+      ...(seed.maxTokens ? { maxTokens: seed.maxTokens } : {}),
+      ...(seed.cost ? { cost: seed.cost } : {}),
+    });
+    expect(validateModelsDocument({
+      providers: {
+        p: { baseUrl: 'https://x/v1', apiKey: 'k', api: 'openai-completions', models: [entry] },
+      },
+    })).toEqual([]);
+  });
+});
+
+describe('manualModelSeed — reasoning ladder', () => {
+  test('declares the ladder the user ticked, in omp order', () => {
+    expect(manualModelSeed({
+      id: 'm',
+      reasoning: true,
+      efforts: ['high', 'low'],
+    }).efforts).toEqual(['high', 'low']);
+  });
+
+  test('an empty ladder is not declared', () => {
+    // omp already assumes its own default ladder for a reasoning model, so an
+    // empty list would write a block that changes nothing.
+    expect(manualModelSeed({ id: 'm', reasoning: true, efforts: [] }).efforts).toBeUndefined();
+  });
+
+  test('a ladder without reasoning is dropped', () => {
+    // A capability the user did not enable must not be declared; omp would
+    // advertise levels for a model it is told cannot reason.
+    expect(manualModelSeed({ id: 'm', efforts: ['high'] }).efforts).toBeUndefined();
+  });
+
+  test('a repeated level is collapsed', () => {
+    expect(manualModelSeed({ id: 'm', reasoning: true, efforts: ['low', 'low'] }).efforts).toEqual(['low']);
+  });
+
+  test('the written entry carries thinking.mode and omp accepts it', () => {
+    const seed = manualModelSeed({ id: 'm', reasoning: true, efforts: ['low', 'high'] });
+    const entry = toModelEntry(seed);
+    expect(entry.thinking).toEqual({ mode: 'effort', efforts: ['low', 'high'] });
+    expect(validateModelsDocument({
+      providers: { p: { baseUrl: 'https://x/v1', apiKey: 'k', api: 'openai-completions', models: [entry] } },
+    })).toEqual([]);
+  });
+
+  test('a model without a ladder writes no thinking block at all', () => {
+    expect(toModelEntry(manualModelSeed({ id: 'm', reasoning: true })).thinking).toBeUndefined();
+  });
+});
+
+describe('validateModelsDocument — thinking', () => {
+  test('refuses a ladder omp does not know', () => {
+    const errors = validateModelsDocument({
+      providers: {
+        p: { baseUrl: 'https://x/v1', apiKey: 'k', api: 'openai-completions',
+          models: [{ id: 'm', reasoning: true, thinking: { mode: 'effort', efforts: ['off'] } }] },
+      },
+    });
+    expect(errors.some((error) => error.includes('unknown thinking effort'))).toBe(true);
+  });
+
+  test('refuses a thinking block with no mode', () => {
+    // omp's own error for this is a schema failure that disables every custom
+    // provider, so it must never reach the file.
+    const errors = validateModelsDocument({
+      providers: {
+        p: { baseUrl: 'https://x/v1', apiKey: 'k', api: 'openai-completions',
+          models: [{ id: 'm', reasoning: true, thinking: { efforts: ['low'] } }] },
+      },
+    });
+    expect(errors.some((error) => error.includes('"thinking.mode" is required'))).toBe(true);
+  });
+
+  test('sanitize drops an unusable thinking block rather than the model', () => {
+    const entry = sanitizeModelEntry({ id: 'm', reasoning: true, thinking: { mode: 'nope', efforts: ['low'] } });
+    expect(entry.thinking).toBeUndefined();
+    expect(entry.id).toBe('m');
+  });
+});

package/src/server/lib/omp/config/provider-seeds.ts

@@ -0,0 +1,176 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Model-entry plumbing for the models.yml writer: the seed shape a provider
+ * listing produces, the YAML entry omp expects for it, and the backfill of
+ * metadata a bare existing entry is missing.
+ *
+ * Split from `./providers.ts` (the provider-level upsert) so each file stays
+ * under the repo's size ceiling; both are one write path.
+ */
+
+import type { Document, YAMLMap } from 'yaml';
+import { sanitizeModelEntry } from '@/server/lib/omp/config/models-validation';
+import { plainOf } from '@/server/lib/omp/config/document';
+import { isRecord } from '@/shared/lib/util/guards';
+import type { ProviderThinkingEffort } from '@/shared/lib/models/provider/dialect';
+
+/** One model entry destined for models.yml (cost numbers are USD per 1M tokens). */
+export interface OmpProviderModelSeed {
+  id: string;
+  name?: string;
+  reasoning?: boolean;
+  imageInput?: boolean;
+  contextWindow?: number;
+  maxTokens?: number;
+  cost?: { input: number; output: number; cacheRead: number; cacheWrite: number };
+  /**
+   * The reasoning ladder this model accepts, lowest first (`thinking.efforts`).
+   *
+   * Only written when the user picks a subset: an EMPTY list is what omp
+   * already assumes for a reasoning model, so writing `efforts: []` would add a
+   * block that changes nothing while claiming to be a configuration.
+   */
+  efforts?: ProviderThinkingEffort[];
+}
+
+/** The model ids already registered under `provider`, array form only. */
+export function knownModelIds(provider: Record<string, unknown> | undefined): Set<string> {
+  if (!Array.isArray(provider?.models)) return new Set();
+  return new Set(
+    provider.models
+      .map((model) => (isRecord(model) && typeof model.id === 'string' ? model.id : ''))
+      .filter(Boolean),
+  );
+}
+
+/** The model entry as omp expects it, omitting anything omp would reject. */
+export function toModelEntry(model: OmpProviderModelSeed): Record<string, unknown> {
+  // omp's `ModelThinkingSchema` requires `mode`; the only ladder the chamber
+  // writes is the effort one, which is what a chat model's `efforts` list means.
+  const efforts = model.efforts && model.efforts.length > 0 ? model.efforts : undefined;
+  return sanitizeModelEntry({
+    id: model.id,
+    ...(model.name ? { name: model.name } : {}),
+    ...(model.reasoning !== undefined ? { reasoning: model.reasoning } : {}),
+    ...(efforts ? { thinking: { mode: 'effort', efforts } } : {}),
+    ...(model.imageInput ? { input: ['text', 'image'] } : { input: ['text'] }),
+    ...(model.contextWindow && model.contextWindow > 0 ? { contextWindow: model.contextWindow } : {}),
+    ...(model.maxTokens && model.maxTokens > 0 ? { maxTokens: model.maxTokens } : {}),
+    ...(model.cost ? { cost: model.cost } : {}),
+  });
+}
+
+/**
+ * Metadata a bare existing entry is missing, taken from the freshly fetched
+ * seed. Values already present are never touched. Writes through the YAML node
+ * so the entry's own comments and key order stay as the user wrote them.
+ */
+export function backfillEntry(doc: Document, entry: YAMLMap, seed: OmpProviderModelSeed): void {
+  if (seed.name && !entry.has('name')) entry.set('name', seed.name);
+  if (seed.reasoning !== undefined && !entry.has('reasoning')) {
+    entry.set('reasoning', seed.reasoning);
+  }
+  const currentInput = plainOf<string[]>(doc, entry.get('input'));
+  if (seed.imageInput && (!Array.isArray(currentInput) || !currentInput.includes('image'))) {
+    entry.set('input', ['text', 'image']);
+  }
+  if (seed.contextWindow && seed.contextWindow > 0 && !plainOf(doc, entry.get('contextWindow'))) {
+    entry.set('contextWindow', seed.contextWindow);
+  }
+  if (seed.maxTokens && seed.maxTokens > 0 && !plainOf(doc, entry.get('maxTokens'))) {
+    entry.set('maxTokens', seed.maxTokens);
+  }
+  if (seed.cost && !entry.has('cost')) {
+    entry.set('cost', seed.cost);
+  }
+}
+
+/**
+ * A model seed built from MANUAL user input (the "Add model" dialog) rather
+ * than a provider listing.
+ *
+ * Numbers arrive as tokens, not as the compact labels a listing produces, so
+ * there is nothing to parse — but the same rules apply: omp rejects the whole
+ * file over a non-positive `contextWindow`/`maxTokens` or a partial `cost`, so
+ * anything not usable is dropped here rather than written and rejected later.
+ */
+export interface ManualModelInput {
+  id: string;
+  name?: string;
+  contextWindow?: number;
+  maxTokens?: number;
+  reasoning?: boolean;
+  imageInput?: boolean;
+  costInput?: number;
+  costOutput?: number;
+  costCacheRead?: number;
+  costCacheWrite?: number;
+  /** Subset of omp's effort ladder this model accepts; empty means "not declared". */
+  efforts?: ProviderThinkingEffort[];
+}
+
+export function manualModelSeed(input: ManualModelInput): OmpProviderModelSeed {
+  const positive = (value: unknown): number | undefined => (
+    typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.round(value) : undefined
+  );
+  const finite = (value: unknown): number | undefined => (
+    typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined
+  );
+  const costInput = finite(input.costInput);
+  const costOutput = finite(input.costOutput);
+  // omp requires all four cost fields together, so the two cache rates are
+  // written as 0 when the user left them out — that is "no cached-token
+  // discount", which is what an unlisted rate means.
+  const hasCost = costInput !== undefined && costOutput !== undefined;
+  // A ladder is a capability, so it is only declared for a reasoning model and
+  // only when the user chose a subset; an empty list is omp's own default.
+  const efforts = input.reasoning && input.efforts && input.efforts.length > 0
+    ? [...new Set(input.efforts)]
+    : undefined;
+  return {
+    id: input.id.trim(),
+    ...(input.name?.trim() ? { name: input.name.trim() } : {}),
+    ...(input.reasoning ? { reasoning: true } : {}),
+    ...(efforts ? { efforts } : {}),
+    ...(input.imageInput ? { imageInput: true } : {}),
+    ...(positive(input.contextWindow) ? { contextWindow: positive(input.contextWindow) } : {}),
+    ...(positive(input.maxTokens) ? { maxTokens: positive(input.maxTokens) } : {}),
+    ...(hasCost ? {
+      cost: {
+        input: costInput,
+        output: costOutput,
+        cacheRead: finite(input.costCacheRead) ?? 0,
+        cacheWrite: finite(input.costCacheWrite) ?? 0,
+      },
+    } : {}),
+  };
+}
+
+/**
+ * Existing entries worth backfilling: a bare id whose seed now carries
+ * metadata the entry lacks (context window, price, reasoning, image input).
+ */
+export function backfillableIds(
+  existingModels: unknown,
+  incomingById: Map<string, OmpProviderModelSeed>,
+): string[] {
+  if (!Array.isArray(existingModels)) return [];
+  return existingModels
+    .filter((model): model is Record<string, unknown> => {
+      if (!isRecord(model) || typeof model.id !== 'string') return false;
+      const seed = incomingById.get(model.id);
+      if (!seed) return false;
+      const missingContext = typeof model.contextWindow !== 'number' || !model.contextWindow;
+      return Boolean(
+        (missingContext && (seed.contextWindow || seed.maxTokens))
+        || (!model.cost && seed.cost)
+        || (seed.reasoning !== undefined && model.reasoning === undefined)
+        || (!Array.isArray(model.input) && seed.imageInput),
+      );
+    })
+    .map((model) => String(model.id));
+}