claude-translator 1.3.0

package/scripts/providers/anthropic.mjs

@@ -0,0 +1,118 @@
+/**
+ * Anthropic Claude — the default provider.
+ *
+ * ── Structured output ────────────────────────────────────────────────────────
+ * `output_config.format` with a JSON schema. Two constraints shape the schema:
+ * every object needs `additionalProperties: false`, and the documented form takes an
+ * object at the root — so the units are wrapped in `{ "translations": [...] }` and
+ * unwrapped here. (Assistant prefill, the old way of forcing a JSON array, returns a
+ * 400 on current models. It is not an option.)
+ *
+ * ── Why the capability table exists ──────────────────────────────────────────
+ * Claude models do not take the same parameters, and guessing wrong is not a silent
+ * no-op — it either errors or spends money:
+ *
+ *   claude-haiku-4-5   `output_config.effort` is REJECTED. Thinking is off unless
+ *                      explicitly enabled. Send neither. This is the default model
+ *                      because bulk segment translation is a low-reasoning task and
+ *                      Haiku is the only tier priced for it.
+ *   opus-5 / sonnet-5  Adaptive thinking; on Opus 5 it is ON BY DEFAULT. Left alone,
+ *   opus-4-8 / fable-5 a large translation run would silently pay for reasoning it
+ *                      does not need, so these get `effort: 'low'`.
+ *
+ * Low effort is used rather than `thinking: {type:'disabled'}` because disabling has
+ * known failure modes on Opus 5 — it can write a tool call into visible text and leak
+ * thinking tags.
+ */
+
+const API = 'https://api.anthropic.com/v1';
+const VERSION_HEADER = '2023-06-01';
+
+export const id = 'anthropic';
+export const label = 'Anthropic Claude';
+export const defaultModel = 'claude-haiku-4-5';
+export const envKeys = ['ANTHROPIC_API_KEY'];
+
+const RESPONSE_SCHEMA = {
+  type: 'object',
+  properties: {
+    translations: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: { id: { type: 'integer' }, text: { type: 'string' } },
+        required: ['id', 'text'],
+        additionalProperties: false,
+      },
+    },
+  },
+  required: ['translations'],
+  additionalProperties: false,
+};
+
+/** Models that accept output_config.effort. Haiku 4.5 rejects it outright. */
+const ACCEPTS_EFFORT = [/^claude-opus-/, /^claude-sonnet-5/, /^claude-fable-/, /^claude-mythos-/];
+const acceptsEffort = (model) => ACCEPTS_EFFORT.some((re) => re.test(model));
+
+export function request({ model, system, items, temperature, key, baseUrl }) {
+  const body = {
+    model,
+    max_tokens: 16000,
+    system,
+    messages: [{ role: 'user', content: JSON.stringify(items) }],
+    output_config: { format: { type: 'json_schema', schema: RESPONSE_SCHEMA } },
+  };
+
+  // Keep the reasoning budget off the bill for a task that does not need it.
+  if (acceptsEffort(model)) body.output_config.effort = 'low';
+  else body.temperature = temperature; // Haiku-class models still take sampling params
+
+  return {
+    url: `${(baseUrl ?? API).replace(/\/$/, '')}/messages`,
+    headers: {
+      'x-api-key': key,
+      'anthropic-version': VERSION_HEADER,
+      'content-type': 'application/json',
+    },
+    body,
+  };
+}
+
+export function parse(data) {
+  const usage = data?.usage ?? {};
+  const norm = { inTok: usage.input_tokens ?? 0, outTok: usage.output_tokens ?? 0 };
+
+  // A safety decline arrives as HTTP 200 with stop_reason "refusal" — the analogue of
+  // Gemini's blockReason, and handled the same way: split the batch so the blast radius
+  // is the offending unit rather than all forty.
+  if (data?.stop_reason === 'refusal') {
+    return {
+      text: null,
+      usage: norm,
+      retryable: 'safety',
+      detail: data?.stop_details?.category ?? 'refusal',
+    };
+  }
+
+  const text = (data?.content ?? []).find((b) => b?.type === 'text')?.text;
+  if (!text) return { text: null, usage: norm, retryable: null, detail: data?.stop_reason };
+
+  return {
+    text,
+    usage: norm,
+    retryable: data?.stop_reason === 'max_tokens' ? 'truncated' : null,
+    detail: data?.stop_reason,
+  };
+}
+
+/** The schema wraps the array in an object; the pipeline wants the array. */
+export const unwrap = (parsed) => parsed?.translations ?? parsed;
+
+/** USD per million tokens [input, output]. Checked 2026-08-25. */
+export function pricing(model) {
+  if (model.startsWith('claude-haiku-4-5')) return [1, 5];
+  if (model.startsWith('claude-sonnet-5')) return [3, 15];
+  if (model.startsWith('claude-opus-')) return [5, 25];
+  if (model.startsWith('claude-fable-') || model.startsWith('claude-mythos-')) return [10, 50];
+  return null;
+}

package/scripts/providers/gemini.mjs

@@ -0,0 +1,72 @@
+/**
+ * Google Gemini.
+ *
+ * This adapter is a straight lift of the call that shipped in 1.0 and 1.1, and its
+ * behaviour must stay identical: it is the only path with a ten-thousand-unit
+ * production run behind it. In particular the response schema stays in Gemini's own
+ * uppercase type dialect, and the units come back as a bare top-level array — the
+ * other adapters wrap theirs in an object because their APIs require it, but changing
+ * this one would be a change for symmetry's sake against proven code.
+ */
+
+const API = 'https://generativelanguage.googleapis.com/v1beta/models';
+
+export const id = 'gemini';
+export const label = 'Google Gemini';
+export const defaultModel = 'gemini-2.5-flash-lite';
+export const envKeys = ['GEMINI_API_KEY', 'GOOGLE_API_KEY'];
+
+/** Gemini's schema dialect: uppercase type names, no additionalProperties. */
+const RESPONSE_SCHEMA = {
+  type: 'ARRAY',
+  items: {
+    type: 'OBJECT',
+    properties: { id: { type: 'INTEGER' }, text: { type: 'STRING' } },
+    required: ['id', 'text'],
+  },
+};
+
+export function request({ model, system, items, temperature, key, baseUrl }) {
+  return {
+    url: `${(baseUrl ?? API).replace(/\/$/, '')}/${model}:generateContent`,
+    headers: { 'x-goog-api-key': key, 'content-type': 'application/json' },
+    body: {
+      systemInstruction: { parts: [{ text: system }] },
+      contents: [{ role: 'user', parts: [{ text: JSON.stringify(items) }] }],
+      generationConfig: {
+        temperature,
+        responseMimeType: 'application/json',
+        responseSchema: RESPONSE_SCHEMA,
+      },
+    },
+  };
+}
+
+export function parse(data) {
+  const text = data?.candidates?.[0]?.content?.parts?.[0]?.text;
+  const usage = data?.usageMetadata ?? {};
+  const norm = { inTok: usage.promptTokenCount ?? 0, outTok: usage.candidatesTokenCount ?? 0 };
+
+  // The safety filter blocks the WHOLE request, so one string it dislikes takes the
+  // other 39 in the batch with it. Reported as 'safety' so the caller can split.
+  if (!text) {
+    const blocked = data?.promptFeedback?.blockReason;
+    if (blocked) return { text: null, usage: norm, retryable: 'safety', detail: blocked };
+    return { text: null, usage: norm, retryable: null };
+  }
+
+  const finish = data?.candidates?.[0]?.finishReason;
+  return {
+    text,
+    usage: norm,
+    retryable: finish === 'MAX_TOKENS' ? 'truncated' : null,
+    detail: finish,
+  };
+}
+
+/** USD per million tokens [input, output]. Checked 2026-08-25. */
+export function pricing(model) {
+  if (model.includes('flash-lite')) return [0.1, 0.4];
+  if (model.includes('flash')) return [0.3, 2.5];
+  return null;
+}

package/scripts/providers/index.mjs

@@ -0,0 +1,95 @@
+/**
+ * Provider resolution.
+ *
+ * Three built-ins, plus any local file: set `provider` to a path ending in `.mjs` and
+ * it is imported as-is. The interface is four exports — see references/providers.md.
+ *
+ * ── Why inference exists ─────────────────────────────────────────────────────
+ * 1.2 changed the default provider from Gemini to Claude. Configs written against 1.0
+ * and 1.1 pin `"model": "gemini-2.5-flash-lite"` and have no `provider` key, so a bare
+ * default would send a Gemini model id to Anthropic and fail with something unhelpful
+ * about an unknown model. Inferring the provider from the model id keeps every existing
+ * config working untouched; only a config with NEITHER key gets the new default.
+ */
+
+import { pathToFileURL } from 'url';
+import { resolve } from 'path';
+
+import * as gemini from './gemini.mjs';
+import * as anthropic from './anthropic.mjs';
+import * as openai from './openai.mjs';
+
+export const BUILTIN = { gemini, anthropic, openai };
+
+/** The provider used when a config names neither a provider nor a model. */
+export const DEFAULT_PROVIDER = 'anthropic';
+
+/** model id → provider, for configs that predate the `provider` key. */
+const INFERENCE = [
+  [/^gemini[-.]/i, 'gemini'],
+  [/^(models\/)?gemini/i, 'gemini'],
+  [/^claude[-.]/i, 'anthropic'],
+  [/^(gpt|o[1-9]|chatgpt|text-davinci)/i, 'openai'],
+];
+
+export function inferProvider(model) {
+  if (!model) return null;
+  for (const [re, id] of INFERENCE) if (re.test(model)) return id;
+  return null;
+}
+
+const isPath = (name) => name.endsWith('.mjs') || name.includes('/');
+
+/**
+ * Resolve a provider module from an explicit name, or infer one from the model.
+ * Returns the module; the caller supplies the model and key.
+ */
+export async function loadProvider({ provider, model, root }) {
+  const name = provider ?? inferProvider(model) ?? DEFAULT_PROVIDER;
+
+  if (isPath(name)) {
+    const abs = resolve(root ?? process.cwd(), name);
+    let mod;
+    try {
+      mod = await import(pathToFileURL(abs).href);
+    } catch (err) {
+      console.error(`Could not load custom provider "${name}" (${abs}):\n  ${err.message}`);
+      process.exit(1);
+    }
+    for (const fn of ['request', 'parse']) {
+      if (typeof mod[fn] !== 'function') {
+        console.error(`Custom provider "${name}" does not export ${fn}(). See references/providers.md.`);
+        process.exit(1);
+      }
+    }
+    return mod;
+  }
+
+  const mod = BUILTIN[name];
+  if (!mod) {
+    console.error(
+      `Unknown provider "${name}". Built-ins: ${Object.keys(BUILTIN).join(', ')}.\n` +
+        `For anything else, point "provider" at a .mjs file — see references/providers.md.`
+    );
+    process.exit(1);
+  }
+  return mod;
+}
+
+/**
+ * Strip a markdown code fence before parsing. Hosted models with a schema never need
+ * this; local and smaller models wrap JSON in ```json fences constantly, and that one
+ * habit accounts for most of the "it just fails on Ollama" reports.
+ */
+export function extractJson(text) {
+  const t = String(text).trim();
+  const fenced = /^```(?:json|JSON)?\s*\n([\s\S]*?)\n?```$/.exec(t);
+  if (fenced) return fenced[1].trim();
+  // Some models prepend a sentence before the JSON. Fall back to the outermost bracket.
+  if (!t.startsWith('{') && !t.startsWith('[')) {
+    const first = t.search(/[[{]/);
+    const last = Math.max(t.lastIndexOf(']'), t.lastIndexOf('}'));
+    if (first !== -1 && last > first) return t.slice(first, last + 1);
+  }
+  return t;
+}

package/scripts/providers/openai.mjs

@@ -0,0 +1,120 @@
+/**
+ * Any OpenAI-compatible chat-completions endpoint.
+ *
+ * This is one adapter and a very long list of providers, because `/v1/chat/completions`
+ * is the de-facto interface: OpenAI, Azure OpenAI, Groq, DeepSeek, Mistral, OpenRouter,
+ * Together and Fireworks all speak it — and so do Ollama, LM Studio and vLLM, which is
+ * how this pipeline runs on a local model at no marginal cost:
+ *
+ *   "provider": "openai",
+ *   "baseUrl":  "http://localhost:11434/v1",
+ *   "model":    "qwen2.5:14b"
+ *
+ * ── Structured output is a ladder, not a feature ─────────────────────────────
+ * Support varies wildly across that list, so the adapter asks for the strongest form
+ * the server advertises and degrades rather than failing:
+ *
+ *   1. `response_format: {type:'json_schema', …, strict:true}`  — OpenAI, Azure, vLLM
+ *   2. `response_format: {type:'json_object'}`                  — most gateways, Ollama
+ *   3. nothing but the prompt                                   — everything else
+ *
+ * `translate.mjs` already validates every unit's placeholders and retries what fails,
+ * so a weaker guarantee here costs retries, not correctness. The rung is chosen by
+ * config (`jsonMode`) and falls back automatically when the server rejects a request
+ * for mentioning `response_format`.
+ */
+
+const API = 'https://api.openai.com/v1';
+
+export const id = 'openai';
+export const label = 'OpenAI-compatible';
+export const defaultModel = 'gpt-4o-mini';
+export const envKeys = ['OPENAI_API_KEY', 'OPENAI_COMPATIBLE_API_KEY'];
+
+/** Local servers accept any key, but some reject a missing Authorization header. */
+export const keyOptional = true;
+
+const RESPONSE_SCHEMA = {
+  type: 'object',
+  properties: {
+    translations: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: { id: { type: 'integer' }, text: { type: 'string' } },
+        required: ['id', 'text'],
+        additionalProperties: false,
+      },
+    },
+  },
+  required: ['translations'],
+  additionalProperties: false,
+};
+
+export function request({ model, system, items, temperature, key, baseUrl, jsonMode }) {
+  const body = {
+    model,
+    temperature,
+    messages: [
+      { role: 'system', content: system },
+      { role: 'user', content: JSON.stringify(items) },
+    ],
+  };
+
+  const mode = jsonMode ?? 'schema';
+  if (mode === 'schema') {
+    body.response_format = {
+      type: 'json_schema',
+      json_schema: { name: 'translations', strict: true, schema: RESPONSE_SCHEMA },
+    };
+  } else if (mode === 'object') {
+    body.response_format = { type: 'json_object' };
+  }
+
+  return {
+    url: `${(baseUrl ?? API).replace(/\/$/, '')}/chat/completions`,
+    headers: {
+      ...(key ? { authorization: `Bearer ${key}` } : {}),
+      'content-type': 'application/json',
+    },
+    body,
+  };
+}
+
+export function parse(data) {
+  const choice = data?.choices?.[0];
+  const usage = data?.usage ?? {};
+  const norm = { inTok: usage.prompt_tokens ?? 0, outTok: usage.completion_tokens ?? 0 };
+
+  const finish = choice?.finish_reason;
+  if (finish === 'content_filter') {
+    return { text: null, usage: norm, retryable: 'safety', detail: 'content_filter' };
+  }
+
+  const text = choice?.message?.content;
+  if (!text) return { text: null, usage: norm, retryable: null, detail: finish };
+
+  return {
+    text,
+    usage: norm,
+    retryable: finish === 'length' ? 'truncated' : null,
+    detail: finish,
+  };
+}
+
+export const unwrap = (parsed) => parsed?.translations ?? parsed;
+
+/**
+ * A rejection caused by response_format rather than by the request being wrong.
+ * Lets translate.mjs drop one rung of the ladder instead of failing the run — the
+ * difference between "this server is older than I assumed" and "this is broken".
+ */
+export function unsupportedJsonMode(status, errText) {
+  if (status !== 400 && status !== 404 && status !== 422) return false;
+  return /response_format|json_schema|json_object|not supported|unrecognized|unknown.*field/i.test(errText);
+}
+
+/** Unknown by design: this adapter points at dozens of providers, and local ones are free. */
+export function pricing() {
+  return null;
+}

package/scripts/providers/providers.test.mjs

@@ -0,0 +1,214 @@
+/**
+ * Contract tests for the provider adapters.
+ *
+ *   node --test scripts/providers/
+ *
+ * These assert the two things an adapter is responsible for: the exact shape of the
+ * request it builds, and what it makes of a response. They use no network and no key,
+ * so they run in CI and on a contributor's laptop.
+ *
+ * What they do NOT prove is that a remote server accepts the request — only a live call
+ * does that. What they DO catch is the class of bug that is otherwise invisible until
+ * someone spends money: a misspelled header, a field nested one level too deep, a usage
+ * counter read from the wrong key, a safety block that fails to trigger the batch split.
+ */
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import * as gemini from './gemini.mjs';
+import * as anthropic from './anthropic.mjs';
+import * as openai from './openai.mjs';
+import { inferProvider, extractJson } from './index.mjs';
+
+const ITEMS = [{ id: 0, text: 'With <0>Acme</0>, hello.' }];
+const ARGS = { system: 'You are a translator.', items: ITEMS, temperature: 0.2, key: 'test-key' };
+
+// ── Gemini ───────────────────────────────────────────────────────────────────
+
+test('gemini: request targets generateContent with the key header', () => {
+  const r = gemini.request({ ...ARGS, model: 'gemini-2.5-flash-lite' });
+  assert.equal(r.url, 'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite:generateContent');
+  assert.equal(r.headers['x-goog-api-key'], 'test-key');
+  assert.equal(r.body.systemInstruction.parts[0].text, ARGS.system);
+  assert.equal(r.body.contents[0].parts[0].text, JSON.stringify(ITEMS));
+  assert.equal(r.body.generationConfig.responseMimeType, 'application/json');
+  // Gemini's own dialect: uppercase types, bare array at the root.
+  assert.equal(r.body.generationConfig.responseSchema.type, 'ARRAY');
+});
+
+test('gemini: parses text and normalises usage', () => {
+  const out = gemini.parse({
+    candidates: [{ content: { parts: [{ text: '[]' }] }, finishReason: 'STOP' }],
+    usageMetadata: { promptTokenCount: 11, candidatesTokenCount: 22 },
+  });
+  assert.equal(out.text, '[]');
+  assert.deepEqual(out.usage, { inTok: 11, outTok: 22 });
+  assert.equal(out.retryable, null);
+});
+
+test('gemini: a block reason asks for a split', () => {
+  const out = gemini.parse({ promptFeedback: { blockReason: 'PROHIBITED_CONTENT' } });
+  assert.equal(out.retryable, 'safety');
+  assert.equal(out.detail, 'PROHIBITED_CONTENT');
+});
+
+test('gemini: MAX_TOKENS asks for a split', () => {
+  const out = gemini.parse({
+    candidates: [{ content: { parts: [{ text: '[{' }] }, finishReason: 'MAX_TOKENS' }],
+    usageMetadata: {},
+  });
+  assert.equal(out.retryable, 'truncated');
+});
+
+// ── Anthropic ────────────────────────────────────────────────────────────────
+
+test('anthropic: request matches the Messages API contract', () => {
+  const r = anthropic.request({ ...ARGS, model: 'claude-haiku-4-5' });
+  assert.equal(r.url, 'https://api.anthropic.com/v1/messages');
+  assert.equal(r.headers['x-api-key'], 'test-key');
+  assert.equal(r.headers['anthropic-version'], '2023-06-01');
+  assert.equal(r.body.model, 'claude-haiku-4-5');
+  assert.ok(r.body.max_tokens > 0, 'max_tokens is required by this API');
+  assert.equal(r.body.system, ARGS.system);
+  assert.equal(r.body.messages[0].role, 'user');
+  assert.equal(r.body.output_config.format.type, 'json_schema');
+  // Structured outputs need a root object and additionalProperties:false everywhere.
+  assert.equal(r.body.output_config.format.schema.type, 'object');
+  assert.equal(r.body.output_config.format.schema.additionalProperties, false);
+});
+
+test('anthropic: haiku gets no effort parameter (the API rejects it there)', () => {
+  const r = anthropic.request({ ...ARGS, model: 'claude-haiku-4-5' });
+  assert.equal(r.body.output_config.effort, undefined);
+});
+
+test('anthropic: thinking-capable tiers get low effort so a bulk run is not billed for reasoning', () => {
+  for (const model of ['claude-opus-5', 'claude-sonnet-5', 'claude-opus-4-8']) {
+    const r = anthropic.request({ ...ARGS, model });
+    assert.equal(r.body.output_config.effort, 'low', `${model} should pin low effort`);
+    assert.equal(r.body.temperature, undefined, `${model} does not accept sampling params`);
+  }
+});
+
+test('anthropic: reads text and usage, and unwraps the schema envelope', () => {
+  const out = anthropic.parse({
+    content: [{ type: 'text', text: '{"translations":[]}' }],
+    stop_reason: 'end_turn',
+    usage: { input_tokens: 7, output_tokens: 9 },
+  });
+  assert.equal(out.text, '{"translations":[]}');
+  assert.deepEqual(out.usage, { inTok: 7, outTok: 9 });
+  assert.deepEqual(anthropic.unwrap({ translations: [1, 2] }), [1, 2]);
+});
+
+test('anthropic: a refusal asks for a split, like a Gemini block', () => {
+  const out = anthropic.parse({
+    stop_reason: 'refusal',
+    stop_details: { type: 'refusal', category: 'cyber' },
+    usage: { input_tokens: 1, output_tokens: 0 },
+  });
+  assert.equal(out.retryable, 'safety');
+  assert.equal(out.detail, 'cyber');
+});
+
+test('anthropic: max_tokens asks for a split', () => {
+  const out = anthropic.parse({
+    content: [{ type: 'text', text: '{"translations":[{' }],
+    stop_reason: 'max_tokens',
+    usage: {},
+  });
+  assert.equal(out.retryable, 'truncated');
+});
+
+// ── OpenAI-compatible ────────────────────────────────────────────────────────
+
+test('openai: default host and bearer auth', () => {
+  const r = openai.request({ ...ARGS, model: 'gpt-4o-mini' });
+  assert.equal(r.url, 'https://api.openai.com/v1/chat/completions');
+  assert.equal(r.headers.authorization, 'Bearer test-key');
+  assert.equal(r.body.messages[0].role, 'system');
+  assert.equal(r.body.messages[1].content, JSON.stringify(ITEMS));
+});
+
+test('openai: a custom host is used verbatim — this is how local models work', () => {
+  const r = openai.request({ ...ARGS, model: 'qwen2.5:14b', baseUrl: 'http://localhost:11434/v1' });
+  assert.equal(r.url, 'http://localhost:11434/v1/chat/completions');
+});
+
+test('openai: a local server needs no key, and no Authorization header is sent', () => {
+  const r = openai.request({ ...ARGS, key: null, baseUrl: 'http://localhost:11434/v1', model: 'x' });
+  assert.equal(r.headers.authorization, undefined);
+});
+
+test('openai: the json-mode ladder produces three distinct requests', () => {
+  const schema = openai.request({ ...ARGS, model: 'x', jsonMode: 'schema' });
+  assert.equal(schema.body.response_format.type, 'json_schema');
+  assert.equal(schema.body.response_format.json_schema.strict, true);
+
+  const object = openai.request({ ...ARGS, model: 'x', jsonMode: 'object' });
+  assert.equal(object.body.response_format.type, 'json_object');
+
+  const none = openai.request({ ...ARGS, model: 'x', jsonMode: 'none' });
+  assert.equal(none.body.response_format, undefined);
+});
+
+test('openai: parses choices and normalises usage', () => {
+  const out = openai.parse({
+    choices: [{ message: { content: '{"translations":[]}' }, finish_reason: 'stop' }],
+    usage: { prompt_tokens: 3, completion_tokens: 4 },
+  });
+  assert.equal(out.text, '{"translations":[]}');
+  assert.deepEqual(out.usage, { inTok: 3, outTok: 4 });
+});
+
+test('openai: length and content_filter map to the split reasons', () => {
+  assert.equal(
+    openai.parse({ choices: [{ message: { content: 'x' }, finish_reason: 'length' }] }).retryable,
+    'truncated'
+  );
+  assert.equal(
+    openai.parse({ choices: [{ finish_reason: 'content_filter' }] }).retryable,
+    'safety'
+  );
+});
+
+test('openai: a response_format rejection is recognised as a capability gap, not a failure', () => {
+  assert.equal(openai.unsupportedJsonMode(400, "Unknown field 'response_format'"), true);
+  assert.equal(openai.unsupportedJsonMode(400, 'json_schema is not supported'), true);
+  // A genuine bad request must NOT be mistaken for one.
+  assert.equal(openai.unsupportedJsonMode(400, 'model not found'), false);
+  assert.equal(openai.unsupportedJsonMode(401, 'invalid api key'), false);
+});
+
+// ── Resolution and parsing helpers ───────────────────────────────────────────
+
+test('provider is inferred from the model id, so pre-1.2 configs keep working', () => {
+  assert.equal(inferProvider('gemini-2.5-flash-lite'), 'gemini');
+  assert.equal(inferProvider('claude-haiku-4-5'), 'anthropic');
+  assert.equal(inferProvider('gpt-4o-mini'), 'openai');
+  assert.equal(inferProvider('qwen2.5:14b'), null, 'unknown ids must not guess');
+  assert.equal(inferProvider(null), null);
+});
+
+test('extractJson survives what small and local models actually emit', () => {
+  const want = [{ id: 0, text: 'hi' }];
+  for (const raw of [
+    '[{"id":0,"text":"hi"}]',
+    '```json\n[{"id":0,"text":"hi"}]\n```',
+    '```\n[{"id":0,"text":"hi"}]\n```',
+    'Sure! Here you go:\n[{"id":0,"text":"hi"}]',
+  ]) {
+    assert.deepEqual(JSON.parse(extractJson(raw)), want, `failed on: ${raw.slice(0, 30)}`);
+  }
+});
+
+test('every built-in adapter satisfies the interface', async () => {
+  for (const mod of [gemini, anthropic, openai]) {
+    assert.equal(typeof mod.id, 'string');
+    assert.equal(typeof mod.defaultModel, 'string');
+    assert.ok(Array.isArray(mod.envKeys));
+    assert.equal(typeof mod.request, 'function');
+    assert.equal(typeof mod.parse, 'function');
+  }
+});