cortico 0.1.0

package/src/providers/llamacpp/strings.ts

@@ -0,0 +1,230 @@
+import { pick, type Language } from '../../core/language.ts';
+
+/** Server side: ConfigGroup titles, validation errors, runtime and server state details. */
+const zh = {
+  tierOff: '关闭',
+  tierOn: '开启',
+  releaseRequired: '版本 tag 不能为空',
+  backendUnsupported: (backend: string) => `本机平台没有后端 ${backend} 的官方构建`,
+  runtimeDirString: '自备运行时目录必须是字符串',
+  positiveInteger: (field: string) => `${field} 必须为正整数`,
+  nonNegativeInteger: (field: string) => `${field} 必须为非负整数`,
+  extraArgsString: '附加启动参数必须是字符串',
+  autoStartBoolean: '自动启动必须是布尔值',
+  notManaged: '这条端点没有开启托管',
+  runtimeNotInstalled: '运行时还没装好',
+  runtimeUnsupported: '本机平台没有这个后端的官方构建,填自备运行时目录',
+  runtimePanel: '运行时',
+  runtimePanelDescription: 'llama.cpp 官方二进制的下载、安装与 llama-server 进程的启停。',
+  modelsPanel: '模型',
+  modelsPanelDescription: 'llama-server 认得的模型:缓存里的、本机目录里的,以及正在下载的。',
+  unknownPanel: '未知面板',
+  unknownMethod: '未知操作',
+  instanceNameRequired: '需要端点名',
+  modelIdRequired: '需要模型 id',
+  bodyRequired: '需要请求体',
+  serverUnreachable: "llama-server 不可达；请检查端点地址与服务状态。",
+  externalServer: '端点已有服务在跑(外部启动),不接管',
+  starting: 'llama-server 启动中',
+  spawnFailed: (message: string) => `进程启动失败: ${message}`,
+  spawnBlocked: (exe: string) =>
+    `Windows 启动 ${exe} 失败（UNKNOWN）。` +
+    '启动失败时可在 Windows 安全中心核对拦截记录；若确认被拦截，请使用符合信任要求的运行时。',
+  exited: (code: number | null, tail: string) => `进程退出 code=${code};stderr 尾部: ${tail}`,
+  badBaseUrl: (baseUrl: string) => `baseUrl 无法解析出 host/port: ${baseUrl}`,
+  missingBinary: (exe: string) => `运行时目录里没有 ${exe}`,
+  healthTimeout: "/health 检查超时；请检查端点地址与服务状态。",
+  downloadFailed: (file: string, message: string) => `下载 ${file} 失败: ${message}`,
+  extractFailed: (file: string, message: string) => `解压 ${file} 失败: ${message}`,
+  installBusy: '正在安装另一份运行时',
+};
+const en: typeof zh = {
+  tierOff: 'Off',
+  tierOn: 'On',
+  releaseRequired: 'The release tag cannot be empty',
+  backendUnsupported: (backend: string) => `No official build of backend ${backend} for this platform`,
+  runtimeDirString: 'The own runtime directory must be a string',
+  positiveInteger: (field: string) => `${field} must be a positive integer`,
+  nonNegativeInteger: (field: string) => `${field} must be a non-negative integer`,
+  extraArgsString: 'Extra launch arguments must be a string',
+  autoStartBoolean: 'Auto start must be a boolean',
+  notManaged: 'This endpoint is not managed',
+  runtimeNotInstalled: 'The runtime is not installed yet',
+  runtimeUnsupported: 'No official build for this backend on this platform; set an own runtime directory',
+  runtimePanel: 'Runtime',
+  runtimePanelDescription: 'Download and install the official llama.cpp binaries; start and stop the llama-server process.',
+  modelsPanel: 'Models',
+  modelsPanelDescription: 'Models llama-server knows: cached, in the local directory, and downloading.',
+  unknownPanel: 'Unknown panel',
+  unknownMethod: 'Unknown action',
+  instanceNameRequired: 'An endpoint name is required',
+  modelIdRequired: 'A model id is required',
+  bodyRequired: 'A request body is required',
+  serverUnreachable: "llama-server is unreachable; check the endpoint URL and server status.",
+  externalServer: 'A server is already running at the endpoint (started externally); not taking over',
+  starting: 'llama-server starting',
+  spawnFailed: (message: string) => `Process failed to start: ${message}`,
+  spawnBlocked: (exe: string) =>
+    `Windows failed to start ${exe} (UNKNOWN). ` +
+    'If startup fails, check Windows Security for a block record. If a block is confirmed, use a runtime that meets the trust requirements.',
+  exited: (code: number | null, tail: string) => `Process exited code=${code}; stderr tail: ${tail}`,
+  badBaseUrl: (baseUrl: string) => `Cannot derive host/port from baseUrl: ${baseUrl}`,
+  missingBinary: (exe: string) => `No ${exe} in the runtime directory`,
+  healthTimeout: "The /health check timed out; check the endpoint URL and server status.",
+  downloadFailed: (file: string, message: string) => `Download of ${file} failed: ${message}`,
+  extractFailed: (file: string, message: string) => `Extraction of ${file} failed: ${message}`,
+  installBusy: 'Another runtime is being installed',
+};
+export type Text = typeof zh;
+export const text = (language: Language) => pick(language, { zh, en });
+
+/** Browser side: the two panels pick by `ctx.language`. */
+const panelZh = {
+  runtimeTitle: '运行时',
+  modelsTitle: '模型',
+  managedOff: "此端点由外部管理；开启托管后由 Cortico 管理 llama-server 进程。",
+  enable: '开启托管',
+  disable: '关闭托管',
+  release: '版本',
+  backend: '后端',
+  runtimeDir: '运行时目录',
+  ownRuntime: '自备',
+  installStatus: '安装',
+  installed: '已安装',
+  absent: '未安装',
+  downloading: '下载中',
+  extracting: '解压中',
+  install: '下载并安装',
+  reinstall: '重新安装',
+  sacWarning:
+    "检测到 Windows 智能应用控制处于强制模式。" +
+    '启动失败时可在 Windows 安全中心核对拦截记录；若确认被拦截，请使用符合信任要求的运行时。',
+  server: '服务进程',
+  serverSection: '服务进程与端点',
+  serverSectionDesc: '',
+  runtimeSection: '二进制运行环境',
+  runtimeSectionDesc: '',
+  releaseHint: '上游 release tag，如 b10930；换了要重新下载。',
+  backendHint: '按本机平台给出的官方构建;CUDA 版自动搭配上游的 cudart 包。',
+  runtimeDirHint: '填了就不下载:目录里要有 llama-server 及其动态库(自编译、Linux CUDA、签过名的构建)。',
+  browse: '选择目录',
+  launchSection: '启动参数',
+  launchSectionDesc: '在下一次启动 llama-server 时生效。',
+  contextSize: '上下文长度(-c)',
+  nGpuLayers: 'GPU 层数(-ngl)',
+  parallel: '并发槽位(--parallel)',
+  extraArgs: '附加启动参数',
+  extraArgsHint: '按空格拆开追加到 llama-server 命令行。',
+  autoStart: 'bot 启动时一并起 server',
+  copyEndpoint: '复制端点',
+  installRequired: '请先下载并安装运行时二进制，方可启动服务',
+  status: '状态',
+  endpoint: '端点',
+  reachable: '可达',
+  unreachable: '不可达',
+  pid: '进程 PID',
+  pendingNote: '启动参数已修改;停止并重新启动后生效。',
+  start: '启动',
+  stop: '停止',
+  refresh: '刷新',
+  phase: { stopped: '未运行', starting: '启动中', running: '运行中', error: '出错' } as Record<string, string>,
+  modelId: '模型 ID',
+  modelStatus: '状态',
+  modality: '输入',
+  path: '文件',
+  actions: '操作',
+  load: '加载',
+  unload: '卸载',
+  cancel: '取消',
+  reload: '重扫',
+  pull: '拉取',
+  pullPlaceholder: 'HuggingFace 仓库,如 ggml-org/Qwen2.5-Coder-7B-Instruct-GGUF',
+  localDir: '本机 GGUF 目录',
+  cacheDir: '缓存目录',
+  noModels: '暂无 GGUF 模型。可下载模型，或将 .gguf 文件放入本机目录后重新扫描。',
+  modelStatusLabel: {
+    loaded: '已加载',
+    loading: '加载中',
+    unloaded: '未加载',
+    downloading: '下载中',
+    sleeping: '休眠',
+    failed: '加载失败',
+    unknown: '在线',
+  } as Record<string, string>,
+  serverDown: "llama-server 不可达；请检查端点地址与服务状态。",
+};
+const panelEn: typeof panelZh = {
+  runtimeTitle: 'Runtime',
+  modelsTitle: 'Models',
+  managedOff: "This endpoint is externally managed. Enable hosting to manage its llama-server process through Cortico.",
+  enable: 'Enable hosting',
+  disable: 'Disable hosting',
+  release: 'Release',
+  backend: 'Backend',
+  runtimeDir: 'Runtime directory',
+  ownRuntime: 'own',
+  installStatus: 'Install',
+  installed: 'installed',
+  absent: 'not installed',
+  downloading: 'downloading',
+  extracting: 'extracting',
+  install: 'Download and install',
+  reinstall: 'Reinstall',
+  sacWarning:
+    "Windows Smart App Control is in enforced mode. " +
+    'If startup fails, check Windows Security for a block record. If a block is confirmed, use a runtime that meets the trust requirements.',
+  server: 'Server',
+  serverSection: 'Server Process & Endpoint',
+  serverSectionDesc: '',
+  runtimeSection: 'Binary Runtime Environment',
+  runtimeSectionDesc: '',
+  releaseHint: 'Upstream release tag, such as b10930; changing it downloads another build.',
+  backendHint: 'Official builds for this platform; CUDA builds are paired with the upstream cudart package.',
+  runtimeDirHint: 'When set nothing is downloaded: the directory holds llama-server and its shared libraries (self-built, Linux CUDA, signed builds).',
+  browse: 'Choose directory',
+  launchSection: 'Launch parameters',
+  launchSectionDesc: 'Applied on the next llama-server start.',
+  contextSize: 'Context size (-c)',
+  nGpuLayers: 'GPU layers (-ngl)',
+  parallel: 'Parallel slots (--parallel)',
+  extraArgs: 'Extra launch arguments',
+  extraArgsHint: 'Split on whitespace and appended to the llama-server command line.',
+  autoStart: 'Start the server with the bot',
+  copyEndpoint: 'Copy endpoint',
+  installRequired: 'Install the runtime binary before starting the server',
+  status: 'Status',
+  endpoint: 'Endpoint',
+  reachable: 'reachable',
+  unreachable: 'unreachable',
+  pid: 'Process PID',
+  pendingNote: 'Launch parameters changed; stop and start again to apply them.',
+  start: 'Start',
+  stop: 'Stop',
+  refresh: 'Refresh',
+  phase: { stopped: 'stopped', starting: 'starting', running: 'running', error: 'error' } as Record<string, string>,
+  modelId: 'Model ID',
+  modelStatus: 'Status',
+  modality: 'Input',
+  path: 'File',
+  actions: 'Actions',
+  load: 'Load',
+  unload: 'Unload',
+  cancel: 'Cancel',
+  reload: 'Rescan',
+  pull: 'Pull',
+  pullPlaceholder: 'HuggingFace repo, e.g. ggml-org/Qwen2.5-Coder-7B-Instruct-GGUF',
+  localDir: 'Local GGUF directory',
+  cacheDir: 'Cache directory',
+  noModels: 'No GGUF models. Download a model, or place GGUF files in the local directory and rescan.',
+  modelStatusLabel: {
+    loaded: 'loaded',
+    loading: 'loading',
+    unloaded: 'unloaded',
+    downloading: 'downloading',
+    sleeping: 'sleeping',
+    failed: 'load failed',
+    unknown: 'online',
+  } as Record<string, string>,
+  serverDown: "llama-server is unreachable; check the endpoint URL and server status.",
+};
+export const panel = { zh: panelZh, en: panelEn };

package/src/providers/openai-responses-compat/config.ts

@@ -0,0 +1,20 @@
+import type { ConfigGroup } from '../../core/config-schema.ts';
+import type { LLMProviderEntry } from '../../core/types.ts';
+import type { Language } from '../../core/language.ts';
+import { text } from './strings.ts';
+
+export function protocolConfig(name: string, entry: LLMProviderEntry, language: Language): ConfigGroup[] {
+  const S = text(language);
+  return [{
+    id: `llm.${entry.kind}.${name}.protocol`,
+    owner: `provider:${entry.kind}`,
+    schema: {
+      type: 'object', title: name,
+      properties: {
+        [`providers.${name}.options.endpointPath`]: {
+          type: 'string', title: S.endpointPath, description: S.endpointPathDescription, 'x-hot': true,
+        },
+      },
+    },
+  }];
+}

package/src/providers/openai-responses-compat/index.ts

@@ -0,0 +1,89 @@
+import type { ProviderModule } from '../base.ts';
+import type { LLMProviderEntry } from '../../core/types.ts';
+import { isContextOverflow } from '../transport/errors.ts';
+import { ModelCatalog, ResponsesProvider } from './native.ts';
+import { text } from './strings.ts';
+import { protocolConfig } from './config.ts';
+
+/** Suggested base URLs for the console field; operators may enter other URLs. */
+const BASE_URLS: readonly string[] = [
+  'https://api.openai.com/v1',
+  'https://api.deepseek.com',
+  'https://openrouter.ai/api/v1',
+  'https://api.x.ai/v1',
+];
+
+/** Reasoning-effort choices used by the console. */
+const EFFORTS: readonly string[] = ['none', 'low', 'medium', 'high', 'xhigh'];
+
+export interface CompatOptions {
+  endpointPath?: string;
+  extraHeaders?: Record<string, string>;
+  extraBody?: Record<string, unknown>;
+}
+export function compatOptions(entry: LLMProviderEntry): CompatOptions {
+  return (entry.options ?? {}) as CompatOptions;
+}
+
+/** Empty strings and empty objects are the console's "unset"; they do not reach the wire. */
+function normalizeCompat(entry: LLMProviderEntry): LLMProviderEntry {
+  const options: Record<string, unknown> = { ...entry.options };
+  if (options.endpointPath === '') delete options.endpointPath;
+  for (const key of ['extraHeaders', 'extraBody'] as const) {
+    const value = options[key];
+    if (value && typeof value === 'object' && !Array.isArray(value) && !Object.keys(value).length) delete options[key];
+  }
+  return { ...entry, options };
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+export default {
+  id: 'openai-responses-compat',
+  title: 'OpenAI Responses Compatible',
+  defaultBaseUrl: BASE_URLS[0],
+  baseUrlSuggestions: BASE_URLS,
+  normalize: normalizeCompat,
+  config: protocolConfig,
+  console: () => ({ config: [] }),
+  reasoningTiers: [],
+  effortSuggestions: EFFORTS,
+  serviceTiers: [],
+  validateEntry: (entry, language) => {
+    const S = text(language);
+    const options = compatOptions(entry);
+    if (options.endpointPath !== undefined && (typeof options.endpointPath !== 'string' || !options.endpointPath.startsWith('/')))
+      throw new Error(S.endpointPathSlash);
+    if (options.extraHeaders !== undefined && (!isPlainObject(options.extraHeaders)
+      || Object.values(options.extraHeaders).some((value) => typeof value !== 'string')))
+      throw new Error(S.extraHeadersObject);
+    if (options.extraBody !== undefined && !isPlainObject(options.extraBody)) throw new Error(S.extraBodyObject);
+  },
+  contextOverflow: isContextOverflow,
+  create(name, entry, host) {
+    const options = compatOptions(entry);
+    const apiKey = entry.secret ? host.secret(entry.secret) : undefined;
+    const headers = (): Record<string, string> => ({
+      ...options.extraHeaders,
+      ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+    });
+    const catalog = new ModelCatalog(() => ({ baseUrl: entry.baseUrl, headers: headers() }));
+    return {
+      listModels: () => catalog.list(),
+      contextWindow: (model) => catalog.contextWindow(model),
+      compatibilityKey: () => [options.endpointPath ?? '/responses', name],
+      client: new ResponsesProvider({
+        baseUrl: entry.baseUrl,
+        apiKey,
+        endpointPath: options.endpointPath,
+        extraHeaders: options.extraHeaders,
+        extraBody: options.extraBody,
+        log: host.log,
+        media: { enabled: () => entry.multimodal === true, read: host.readBlob },
+        keepThinking: host.keepThinking,
+      }),
+    };
+  },
+} satisfies ProviderModule;

package/src/providers/openai-responses-compat/native.ts

@@ -0,0 +1,127 @@
+/** Native Responses over any OpenAI-compatible endpoint: bearer key, stateless replay, no vendor branching. */
+import type { Logger } from '../../core/types.ts';
+import { nullLogger } from '../../core/util.ts';
+import { OpenAIHttpClient } from '../transport/chat.ts';
+import { ResponseProtocolError } from '../../protocol/open-responses/stream.ts';
+import { createResponse, type Request } from '../../protocol/open-responses/index.ts';
+import { standardUsage, type GenerateOptions } from '../../core/generation.ts';
+import { NativeResponseAssembly, type ResponseAssembly, type parseChatResponse } from '../transport/response-assembly.ts';
+import { responseMeters } from '../transport/response-meters.ts';
+import { responsesInput, type ResponsesInputOptions } from '../transport/responses-input.ts';
+
+type Item = Record<string, unknown>;
+
+export interface ResponsesProviderOptions {
+  baseUrl: string;
+  apiKey?: string;
+  /** Path appended to `baseUrl`; default `/responses`. */
+  endpointPath?: string;
+  extraHeaders?: Record<string, string>;
+  /** Merged into every request body last, so vendor-specific fields (`service_tier`, ...) win. */
+  extraBody?: Record<string, unknown>;
+  media?: ResponsesInputOptions['media'];
+  keepThinking?: () => boolean;
+  log?: Logger;
+}
+
+/**
+ * Send reasoning only when an effort is supplied; otherwise leave it to the endpoint.
+ * Requests set store=false and request encrypted reasoning content for local stateless replay.
+ * Endpoint extraBody fields are merged last.
+ */
+export function buildResponsesBody(
+  request: Request,
+  options: GenerateOptions,
+  input: ResponsesInputOptions,
+  extraBody: Record<string, unknown> = {},
+): Record<string, unknown> {
+  const replay = responsesInput(request, options, input);
+  const body: Item = {
+    ...request,
+    input: replay.input,
+    include: [...new Set([...(request.include ?? []), 'reasoning.encrypted_content'])],
+    store: false,
+    stream: Boolean(options.onEvent),
+  };
+  delete body.previous_response_id;
+  if (replay.instructions !== undefined) body.instructions = replay.instructions;
+  else delete body.instructions;
+  if (!request.reasoning?.effort) delete body.reasoning;
+  if (options.sessionId) body.prompt_cache_key = options.sessionId;
+  return { ...body, ...extraBody };
+}
+
+export class ResponsesProvider extends OpenAIHttpClient {
+  private readonly opts: ResponsesProviderOptions;
+
+  constructor(opts: ResponsesProviderOptions) {
+    super(opts.baseUrl, opts.log ?? nullLogger());
+    this.opts = opts;
+    this.chatPath = opts.endpointPath ?? '/responses';
+  }
+
+  protected override buildResponseBody(request: Request, options: GenerateOptions): Record<string, unknown> {
+    return buildResponsesBody(request, options, { media: this.opts.media, keepThinking: this.opts.keepThinking }, this.opts.extraBody);
+  }
+
+  /** The Chat body builder is unreachable here: `buildResponseBody` is overridden whole. */
+  protected buildBody(): never {
+    throw new Error('ResponsesProvider does not build Chat Completions bodies');
+  }
+
+  protected headers(): Record<string, string> {
+    const headers: Record<string, string> = { 'Content-Type': 'application/json', ...this.opts.extraHeaders };
+    if (this.opts.apiKey) headers.Authorization = `Bearer ${this.opts.apiKey}`;
+    return headers;
+  }
+
+  protected override responseAssembly(): ResponseAssembly {
+    return new NativeResponseAssembly();
+  }
+
+  protected override parseResponse(raw: unknown, request: Request): ReturnType<typeof parseChatResponse> {
+    const data = raw as Item;
+    if (typeof data.id !== 'string' || typeof data.model !== 'string' || !Array.isArray(data.output)
+      || !['completed', 'incomplete', 'failed'].includes(String(data.status))) throw new ResponseProtocolError('Invalid native Responses resource');
+    const meters = responseMeters(data.usage as Record<string, unknown> | null);
+    return {
+      response: { ...createResponse(data.id, request), ...data, usage: standardUsage(meters) },
+      meters,
+      serviceTier: typeof data.service_tier === 'string' ? data.service_tier : null,
+    };
+  }
+}
+
+export interface CatalogModel {
+  id: string;
+  contextWindow?: number;
+}
+
+/** `GET /models`: ids always; OpenRouter also states `context_length` per model. */
+export class ModelCatalog {
+  private known = new Map<string, number | undefined>();
+  constructor(
+    private readonly endpoint: () => { baseUrl: string; headers: Record<string, string> },
+    private readonly fetchImpl: typeof fetch = fetch,
+  ) {}
+
+  async list(): Promise<CatalogModel[]> {
+    const { baseUrl, headers } = this.endpoint();
+    const res = await this.fetchImpl(`${baseUrl.replace(/\/+$/, '')}/models`, { headers, signal: AbortSignal.timeout(15_000) });
+    if (!res.ok) throw new Error(`GET /models ${res.status}: ${(await res.text()).slice(0, 300)}`);
+    const json = (await res.json()) as { data?: Array<{ id?: unknown; context_length?: unknown }> };
+    if (!Array.isArray(json.data)) throw new Error('GET /models returned no data array');
+    const models: CatalogModel[] = [];
+    for (const row of json.data) {
+      if (typeof row.id !== 'string') continue;
+      const window = typeof row.context_length === 'number' && Number.isInteger(row.context_length) && row.context_length > 0 ? row.context_length : undefined;
+      this.known.set(row.id, window);
+      models.push(window ? { id: row.id, contextWindow: window } : { id: row.id });
+    }
+    return models.sort((a, b) => a.id.localeCompare(b.id));
+  }
+
+  contextWindow(model: string): number | undefined {
+    return this.known.get(model);
+  }
+}

package/src/providers/openai-responses-compat/strings.ts

@@ -0,0 +1,19 @@
+import { pick, type Language } from '../../core/language.ts';
+
+/** Server side: ConfigGroup titles and validation errors. */
+const zh = {
+  endpointPath: 'Responses 端点路径',
+  endpointPathDescription: '相对供应地址;默认 /responses。',
+  endpointPathSlash: '端点路径必须以 / 开头',
+  extraHeadersObject: '附加请求头必须是字符串到字符串的对象',
+  extraBodyObject: '附加请求体字段必须是对象',
+};
+const en: typeof zh = {
+  endpointPath: 'Responses endpoint path',
+  endpointPathDescription: 'Relative to the provider URL; default /responses.',
+  endpointPathSlash: 'The endpoint path must start with /',
+  extraHeadersObject: 'Extra headers must be an object of strings',
+  extraBodyObject: 'Extra body fields must be an object',
+};
+export type Text = typeof zh;
+export const text = (language: Language) => pick(language, { zh, en });

package/src/providers/pricebook.ts

@@ -0,0 +1,75 @@
+import { createHash } from 'node:crypto';
+import type { Request } from '../protocol/open-responses/index.ts';
+import type { LLMProviderEntry } from '../core/types.ts';
+import type { Language } from '../core/language.ts';
+import type { PriceSnapshot, PriceRule } from '../core/generation.ts';
+import { text } from './strings.ts';
+
+export interface PriceDefinition {
+  models: string[];
+  currency: string;
+  basis: 'marginal' | 'equivalent';
+  rules: PriceRule[];
+  inputBands?: Array<{ from: number; rules: PriceRule[] }>;
+  serviceTiers?: Record<string, { rules: PriceRule[]; inputBands?: Array<{ from: number; rules: PriceRule[] }> }>;
+  source: string;
+}
+export interface QuoteTime { startedAt: string; requestedServiceTier: string | null; }
+
+export function snapshotPrice(definition: PriceDefinition, at: QuoteTime): PriceSnapshot {
+  const { models: _models, ...definitionBody } = definition;
+  return { ...structuredClone(definitionBody), id: createHash('sha256').update(JSON.stringify(definition)).digest('hex').slice(0, 20), capturedAt: at.startedAt };
+}
+
+/** An explicit instance override replaces the module's quote for that cost basis. */
+export function quotePrices(entry: LLMProviderEntry, request: Request, at: QuoteTime, defaults: readonly PriceDefinition[]): PriceSnapshot[] {
+  const byBasis = new Map<string, PriceDefinition>();
+  for (const definition of [...defaults, ...(entry.pricing ?? [])]) {
+    if (definition.models.includes('*') || definition.models.includes(request.model ?? '')) byBasis.set(definition.basis, definition);
+  }
+  return [...byBasis.values()].map(definition => snapshotPrice(definition, at));
+}
+
+/** External configuration boundary for module-owned rate definitions. `language` picks the message wording. */
+export function validatePrices(value: unknown, language: Language = 'zh'): PriceDefinition[] {
+  const S = text(language);
+  if (!Array.isArray(value)) throw new Error(S.pricingArray);
+  const meters = new Set(['input', 'output', 'total', 'cachedInput', 'uncachedInput', 'reasoning']);
+  const rules = (raw: unknown): PriceRule[] => {
+    if (!Array.isArray(raw)) throw new Error(S.rulesArray);
+    return raw.map(rule => {
+      if (!rule || typeof rule !== 'object' || typeof rule.meter !== 'string' || (!meters.has(rule.meter) && !rule.meter.startsWith('detail:'))
+        || typeof rule.perMillion !== 'number' || !Number.isFinite(rule.perMillion) || rule.perMillion < 0) throw new Error(S.ruleShape);
+      if (rule.unit !== undefined && (typeof rule.unit !== 'string' || !rule.unit.trim())) throw new Error(S.unitRequired);
+      if (meters.has(rule.meter) && rule.unit !== undefined && rule.unit !== 'token') throw new Error(S.tokenUnit);
+      return { meter: rule.meter, perMillion: rule.perMillion, ...(rule.unit ? { unit: rule.unit } : {}) };
+    });
+  };
+  const bands = (raw: unknown) => {
+    if (raw === undefined) return undefined;
+    if (!Array.isArray(raw)) throw new Error(S.bandsArray);
+    let previous = 0;
+    return raw.map(band => {
+      if (!band || typeof band.from !== 'number' || !Number.isFinite(band.from) || band.from <= previous) throw new Error(S.bandsIncreasing);
+      previous = band.from;
+      return { from: band.from, rules: rules(band.rules) };
+    });
+  };
+  return value.map(raw => {
+    if (!raw || typeof raw !== 'object' || !Array.isArray(raw.models) || !raw.models.length || raw.models.some((model: unknown) => typeof model !== 'string' || !model.trim())) throw new Error(S.modelsRequired);
+    if (typeof raw.currency !== 'string' || !raw.currency.trim()) throw new Error(S.currencyRequired);
+    if (raw.basis !== 'marginal' && raw.basis !== 'equivalent') throw new Error(S.basisValue);
+    if (typeof raw.source !== 'string' || !raw.source.trim()) throw new Error(S.sourceRequired);
+    const tiers: PriceDefinition['serviceTiers'] = {};
+    if (raw.serviceTiers !== undefined) {
+      if (!raw.serviceTiers || typeof raw.serviceTiers !== 'object' || Array.isArray(raw.serviceTiers)) throw new Error(S.tiersObject);
+      for (const [tier, data] of Object.entries(raw.serviceTiers) as [string, any][]) {
+        if (!tier.trim()) throw new Error(S.tierNameRequired);
+        if (!data || typeof data !== 'object' || Array.isArray(data)) throw new Error(S.tierRules);
+        tiers[tier] = { rules: rules(data.rules), ...(data.inputBands ? { inputBands: bands(data.inputBands) } : {}) };
+      }
+    }
+    return { models: [...raw.models], currency: raw.currency.trim(), basis: raw.basis, source: raw.source.trim(), rules: rules(raw.rules),
+      ...(raw.inputBands ? { inputBands: bands(raw.inputBands) } : {}), ...(raw.serviceTiers ? { serviceTiers: tiers } : {}) };
+  });
+}