@itphx/synth-shared 0.12.3 → 0.13.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/dist/config/defaults.js +97 -4
  2. package/dist/config/env-overrides.js +29 -0
  3. package/dist/config/resolve.d.ts +17 -0
  4. package/dist/config/resolve.js +40 -1
  5. package/dist/config/types.d.ts +394 -7
  6. package/dist/config/types.js +275 -6
  7. package/dist/i18n/index.d.ts +1 -1
  8. package/dist/i18n/index.js +188 -3
  9. package/dist/index.d.ts +2 -2
  10. package/dist/index.js +2 -2
  11. package/dist/schemas/index.d.ts +90 -10
  12. package/dist/schemas/index.js +55 -4
  13. package/dist/types/agent.d.ts +8 -1
  14. package/dist/types/bus-events.d.ts +59 -1
  15. package/dist/types/egress.d.ts +1 -1
  16. package/dist/types/egress.js +1 -1
  17. package/dist/types/file-kind.d.ts +40 -0
  18. package/dist/types/file-kind.js +157 -0
  19. package/dist/types/fs.d.ts +54 -1
  20. package/dist/types/fs.js +43 -0
  21. package/dist/types/git.d.ts +5 -0
  22. package/dist/types/index.d.ts +2 -0
  23. package/dist/types/index.js +6 -0
  24. package/dist/types/llm.d.ts +95 -0
  25. package/dist/types/llm.js +58 -0
  26. package/dist/types/message-stream.d.ts +348 -0
  27. package/dist/types/message-stream.js +41 -0
  28. package/dist/types/message.d.ts +49 -0
  29. package/dist/types/pack.d.ts +6 -6
  30. package/dist/types/permission.d.ts +26 -0
  31. package/dist/types/pipeline-engine.d.ts +2 -2
  32. package/dist/types/provider.d.ts +280 -0
  33. package/dist/types/provider.js +289 -0
  34. package/dist/types/session.d.ts +170 -3
  35. package/dist/types/tools.d.ts +21 -0
  36. package/dist/types/tools.js +1 -1
  37. package/dist/utils/reasoning.d.ts +18 -2
  38. package/dist/utils/reasoning.js +16 -7
  39. package/dist/version.d.ts +1 -1
  40. package/dist/version.js +1 -1
  41. package/package.json +2 -2
@@ -23,6 +23,266 @@ export type CurrencyInputResult = {
23
23
  export declare function parseCurrencyInput(raw: unknown, existing?: Currency): CurrencyInputResult;
24
24
  /** Присутствуют ли в теле запроса ценовые поля (snake_case или camelCase). */
25
25
  export declare function hasPriceInput(body: unknown): boolean;
26
+ /**
27
+ * Поле лимита вывода в теле запроса OpenAI-совместимого протокола.
28
+ *
29
+ * Наш дефолт — `max_tokens` (намеренное отличие от opencode, где дефолт
30
+ * `max_completion_tokens`): локальные и кастомные OpenAI-совместимые серверы
31
+ * часто не знают `max_completion_tokens`, и молчаливая смена дефолта ломала бы
32
+ * их. `max_completion_tokens` отправляется только при **явном** значении.
33
+ */
34
+ export type MaxTokensField = 'max_tokens' | 'max_completion_tokens';
35
+ /**
36
+ * Формат inline-маркеров prompt-cache в теле OpenAI-совместимого запроса
37
+ * (`cache_control: { type: 'ephemeral' }` на частях контента и на
38
+ * tool-дефинишнах) — аналог `cacheFormat` в opencode
39
+ * (`packages/ai/src/cache-policy.ts`).
40
+ *
41
+ * - `anthropic` — полный AUTO-набор: последний tool-дефинишн, system-блок и
42
+ * граница последнего сообщения (`tail: 1`);
43
+ * - `alibaba` — QWEN-набор: system-блок и граница последнего сообщения,
44
+ * **без** маркера на tools (Qwen кеширует tools вместе с system-промптом и
45
+ * игнорирует маркеры на дефинишнах).
46
+ *
47
+ * Не задан — inline-маркеры не ставятся, работает прежний механизм:
48
+ * implicit prefix caching через `prompt_cache_key`.
49
+ */
50
+ export type CacheFormat = 'anthropic' | 'alibaba';
51
+ /** Канонические значения `cacheFormat` (для валидации входных данных API). */
52
+ export declare const CACHE_FORMATS: readonly ["anthropic", "alibaba"];
53
+ /** Проверка, что значение — допустимый формат inline-маркеров кэша. */
54
+ export declare function isCacheFormat(value: unknown): value is CacheFormat;
55
+ /**
56
+ * Аудио-контейнеры, которые транспорт провайдера принимает **нативно**
57
+ * (блок `input_audio`/`audio` в теле запроса — без aux-модели и конвертации).
58
+ *
59
+ * ADR-115 × ADR-117: перечень приходит **данными** (`compatibility`), а не из
60
+ * URL провайдера. Значение по умолчанию — эвристика по типу/хосту, но любая
61
+ * запись каталога может перекрыть его явно.
62
+ */
63
+ export type NativeAudioFormat = 'wav' | 'mp3' | 'ogg';
64
+ /** Канонический набор нативных аудио-форматов (для валидации и UI). */
65
+ export declare const NATIVE_AUDIO_FORMATS: readonly ["wav", "mp3", "ogg"];
66
+ /**
67
+ * Явные особенности протокола провайдера/модели (аналог `Compatibility` в
68
+ * opencode, `packages/schema/src/model-compatibility.ts`).
69
+ *
70
+ * Один и тот же контракт объявлен на двух уровнях: `ProviderConfig.compatibility`
71
+ * (дефолты для всех моделей провайдера) и `ModelConfig.compatibility`
72
+ * (перекрывает провайдерские поля точечно).
73
+ */
74
+ export interface ModelCompatibility {
75
+ /**
76
+ * Имя поля reasoning в assistant-сообщениях openai-chat.
77
+ * По умолчанию `'reasoning_content'` (DeepSeek); OpenRouter/RouterAI — `'reasoning'`.
78
+ */
79
+ reasoningField?: string;
80
+ /**
81
+ * Требовать поле reasoning у **каждого** assistant-сообщения, даже пустым
82
+ * (thinking-режим DeepSeek: `reasoning_content` обязателен в истории).
83
+ */
84
+ requireReasoning?: boolean;
85
+ /** Поле лимита вывода: `max_tokens` (дефолт) | `max_completion_tokens` (только явно). */
86
+ maxTokensField?: MaxTokensField;
87
+ /** Провайдеру нужен assistant-турн после tool-результатов (Mistral-семейство). */
88
+ requireAssistantAfterTool?: boolean;
89
+ /**
90
+ * Отправлять `stream_options: {include_usage: true}` в стриме
91
+ * (OpenAI-совместимые). Дефолт `true` — как в opencode.
92
+ */
93
+ streamUsage?: boolean;
94
+ /**
95
+ * Провайдер понимает `tool_choice`. Дефолт `true`; для нативного Ollama
96
+ * `/api/chat` — `false` (эвристика по `type: 'ollama'`).
97
+ */
98
+ supportsToolChoice?: boolean;
99
+ /**
100
+ * Формат inline-маркеров prompt-cache (`cache_control`). Не задан — маркеры
101
+ * не ставятся, кэш работает через implicit prefix caching
102
+ * (`prompt_cache_key`). Задан — маркеры ставятся, а `prompt_cache_key` **не
103
+ * отправляется**: это разные механизмы, и провайдер, ориентированный на
104
+ * inline-маркеры, полагается только на них (как в opencode).
105
+ *
106
+ * Бюджет — не больше 4 breakpoint'ов на запрос (как `BREAKPOINT_CAP`).
107
+ */
108
+ cacheFormat?: CacheFormat;
109
+ /**
110
+ * Требовать `finish_reason` в стриме OpenAI-совместимого протокола.
111
+ * Дефолт **`true`** (как в opencode, `packages/ai/src/protocols/openai-chat.ts`):
112
+ * провайдер, закрывший стрим без `finish_reason`, — недописанный ответ
113
+ * (incomplete-stream). `false` — прежнее толерантное поведение (стрим
114
+ * считается завершённым).
115
+ */
116
+ requireFinishReason?: boolean;
117
+ /**
118
+ * Anthropic 5.x: модель принимает `output_config.effort` (тир усилия,
119
+ * `EffortLevel`). Включение — **только явным значением** (дефолт `false`,
120
+ * авто-эвристики нет): иначе существующие записи каталога начали бы слать
121
+ * поле шлюзам, которые его не знают. При `true` провайдер отправляет
122
+ * `output_config.effort` (из `ChatOptions.effort` либо из `reasoningLevel`)
123
+ * и **не** отправляет `thinking` — у effort-моделей это другой режим
124
+ * (ADR-117).
125
+ */
126
+ supportsEffortUpdates?: boolean;
127
+ /**
128
+ * ADR-115 × ADR-117: транспорт принимает **видеофайл** нативно (блок
129
+ * `video_url` в OpenAI-протоколе), без разбивки на кадры через aux-модель.
130
+ *
131
+ * Дефолт — эвристика по типу/хосту провайдера (RouterAI-совместимые шлюзы);
132
+ * явное `true`/`false` перекрывает её (в т.ч. для не-routerai прокси, который
133
+ * видео тоже понимает — например `itphx`, проверено живым тестом 2026-11-03).
134
+ */
135
+ supportsNativeVideo?: boolean;
136
+ /**
137
+ * ADR-115 × ADR-117: аудио-контейнеры, которые транспорт принимает нативно
138
+ * (блок `input_audio`/`audio`).
139
+ *
140
+ * Явный **пустой массив** — осмысленное значение «ни одного формата» (не
141
+ * «не задано»): перекрывает эвристику, аудио уходит только через aux-модель.
142
+ */
143
+ nativeAudioFormats?: NativeAudioFormat[];
144
+ }
145
+ /**
146
+ * Дефолты провайдера, наследуемые моделями. Набор полей совпадает с
147
+ * `ModelCompatibility`; отдельный алиас оставлен, чтобы смысл был явным.
148
+ */
149
+ export type ProviderCompatibility = ModelCompatibility;
150
+ /**
151
+ * Полностью разрешённая совместимость: каждое поле заполнено — явное значение
152
+ * модели → явное значение провайдера → эвристика (или встроенный дефолт).
153
+ */
154
+ export interface ResolvedModelCompatibility {
155
+ reasoningField: string;
156
+ requireReasoning: boolean;
157
+ maxTokensField: MaxTokensField;
158
+ requireAssistantAfterTool: boolean;
159
+ streamUsage: boolean;
160
+ supportsToolChoice: boolean;
161
+ requireFinishReason: boolean;
162
+ /**
163
+ * Anthropic: слать `output_config.effort` вместо `thinking`. Дефолт `false`
164
+ * (только явное включение — ADR-117).
165
+ */
166
+ supportsEffortUpdates: boolean;
167
+ /**
168
+ * Формат inline-маркеров кэша; `undefined` — маркеры не ставятся (в отличие
169
+ * от прочих полей, «не задано» здесь — осмысленное состояние, а не дефолт).
170
+ */
171
+ cacheFormat?: CacheFormat;
172
+ /**
173
+ * ADR-115: транспорт принимает видеофайл нативно (`video_url`).
174
+ * Дефолт — эвристика (RouterAI-совместимые шлюзы), иначе `false`.
175
+ */
176
+ supportsNativeVideo: boolean;
177
+ /**
178
+ * ADR-115: аудио-контейнеры нативного пути (`input_audio`/`audio`).
179
+ * Дефолт — эвристика; пустой массив — «ни одного формата».
180
+ */
181
+ nativeAudioFormats: NativeAudioFormat[];
182
+ }
183
+ /** Контекст, по которому считаются эвристики совместимости. */
184
+ export interface CompatibilityContext {
185
+ /** Тип провайдера (`openai`/`ollama`/`deepseek`/…). */
186
+ providerType?: string;
187
+ /** Имя провайдера как в конфиге. */
188
+ providerName?: string;
189
+ /** Базовый URL (для эвристик вида `deepseek.com`). */
190
+ baseUrl?: string;
191
+ /** Идентификатор модели. */
192
+ modelId?: string;
193
+ }
194
+ /** Эвристические значения совместимости (применяются только без явных). */
195
+ export type CompatibilityHeuristics = Partial<ResolvedModelCompatibility>;
196
+ /** Ключи контракта — для валидации входных данных API. */
197
+ export declare const MODEL_COMPATIBILITY_KEYS: readonly ["reasoningField", "requireReasoning", "maxTokensField", "requireAssistantAfterTool", "streamUsage", "supportsToolChoice", "cacheFormat", "requireFinishReason", "supportsEffortUpdates", "supportsNativeVideo", "nativeAudioFormats"];
198
+ /**
199
+ * RouterAI — прокси с расширениями протоколов (нативное аудио/видео).
200
+ *
201
+ * Единственный носитель host-знания в слое совместимости: **эвристика**
202
+ * умолчания для `supportsNativeVideo`/`nativeAudioFormats`. Сами значения
203
+ * приходят данными (`compatibility`) — этот предикат лишь задаёт дефолт,
204
+ * который любая запись каталога перекрывает явно (ADR-117).
205
+ *
206
+ * Функция чистая (только строка) — `node:*` в shared не тащим.
207
+ */
208
+ export declare function isRouterAiUrl(url: string): boolean;
209
+ /**
210
+ * Нативный аудио-контейнер по MIME (ADR-115): `wav`/`mp3`/`ogg`.
211
+ * Прочие MIME (в т.ч. не-аудио) → `null`.
212
+ */
213
+ export declare function nativeAudioFormatForMime(mime: string): NativeAudioFormat | null;
214
+ /**
215
+ * Эвристики совместимости — те же, что в opencode
216
+ * (`packages/ai/src/protocols/openai-chat.ts`):
217
+ *
218
+ * - `requireReasoning`: тип/имя провайдера `deepseek`, URL ~ `deepseek.com`,
219
+ * модель ~ `deepseek`; провайдер `minimax` или URL ~ `minimax`
220
+ * (adaptive thinking у MiniMax идёт в тот же бюджет вывода);
221
+ * - `requireAssistantAfterTool`: Mistral-семейство (`mistral`, `devstral`,
222
+ * `codestral`, `pixtral`, `mixtral`);
223
+ * - `supportsToolChoice`: `false` для нативного Ollama (`type: 'ollama'`).
224
+ *
225
+ * `maxTokensField` намеренно **не** эвристируется: наш дефолт — `max_tokens`,
226
+ * `max_completion_tokens` только при явном значении (локальные серверы).
227
+ *
228
+ * **Нативные медиа (ADR-115 × ADR-117).** Матрица «тип провайдера ×
229
+ * RouterAI-совместимый хост» — дефолт для `nativeAudioFormats`/
230
+ * `supportsNativeVideo`:
231
+ *
232
+ * | тип | RouterAI | nativeAudioFormats | supportsNativeVideo |
233
+ * |--------------|----------|--------------------|---------------------|
234
+ * | openai/generic| да | wav, mp3, ogg | `true` |
235
+ * | openai/generic| нет | wav, mp3 | `false` |
236
+ * | anthropic | да | wav | `false` |
237
+ * | anthropic | нет | — | `false` |
238
+ * | прочие | любой | — | `false` |
239
+ *
240
+ * Основание — прежнее поведение по хосту: `anthropic` принимает аудио только в
241
+ * `wav` и только у RouterAI (Anthropic-совместимый шлюз на ogg/mp3 отвечает 200,
242
+ * но модель аудио не слышит — такие форматы идут через aux-модель); OpenAI-протокол
243
+ * принимает wav/mp3 всегда, ogg — расширение RouterAI; блок `video_url` знает
244
+ * только RouterAI-совместимый OpenAI-протокол.
245
+ *
246
+ * Живой тест 2026-11-03: не-routerai прокси `itphx`
247
+ * (`https://ai.itphx.ru/api/`) нативное видео **умеет** — старый предикат по
248
+ * хосту давал ложноотрицательный ответ. Отсюда правило: дефолт по хосту —
249
+ * лишь эвристика, а решение принимают **данные** (`compatibility`), которыми
250
+ * провайдер/модель перекрывают эвристику явно.
251
+ */
252
+ export declare function detectCompatibilityHeuristics(context: CompatibilityContext): CompatibilityHeuristics;
253
+ /**
254
+ * Наложение слоёв совместимости: `undefined`-поля не перетирают значение.
255
+ * Поздние слои приоритетнее (провайдер → shorthand → модель).
256
+ */
257
+ export declare function mergeModelCompatibility(...layers: Array<ModelCompatibility | undefined>): ModelCompatibility;
258
+ /**
259
+ * Разрешение итоговой совместимости.
260
+ *
261
+ * Порядок: **явное значение модели → явное значение провайдера → эвристика →
262
+ * встроенный дефолт**. `reasoningField`, заданный явно на любом уровне, сам по
263
+ * себе означает `requireReasoning: true` (как в opencode) — если
264
+ * `requireReasoning` не переопределён явно (в т.ч. `false`).
265
+ */
266
+ export declare function resolveModelCompatibility(providerCompat?: ModelCompatibility, modelCompat?: ModelCompatibility, heuristics?: CompatibilityHeuristics): ResolvedModelCompatibility;
267
+ /** Результат строгого разбора поля `compatibility` из тела запроса. */
268
+ export type CompatibilityInputResult = {
269
+ ok: true;
270
+ value: ModelCompatibility | undefined;
271
+ } | {
272
+ ok: false;
273
+ reason: string;
274
+ };
275
+ /**
276
+ * Строгий разбор `compatibility` из тела API. Семантика — **замена**:
277
+ * - `undefined` — поле не передано (сохранить existing);
278
+ * - `null` — явно сбросить;
279
+ * - объект — **заменить** значение целиком (UI присылает полный объект из
280
+ * черновика, поэтому отсутствующее в объекте поле означает «авто», а не
281
+ * «оставить как было»); пустой объект равнозначен сбросу;
282
+ * - неизвестные поля и значения неверного типа — ошибка (не терять опечатки
283
+ * молча); иное — ошибка.
284
+ */
285
+ export declare function parseModelCompatibilityInput(raw: unknown, existing?: ModelCompatibility): CompatibilityInputResult;
26
286
  export interface ProviderConfig {
27
287
  name: string;
28
288
  type: string;
@@ -40,6 +300,12 @@ export interface ProviderConfig {
40
300
  * путём Ollama (`/api/chat`).
41
301
  */
42
302
  numCtx?: number;
303
+ /**
304
+ * Особенности протокола провайдера (дефолты для всех его моделей):
305
+ * поле reasoning, лимит вывода, `stream_options`, поддержка `tool_choice`.
306
+ * Модель перекрывает поля точечно (`ModelConfig.compatibility`).
307
+ */
308
+ compatibility?: ModelCompatibility;
43
309
  }
44
310
  export type ContextSource = 'api' | 'reference' | 'manual' | 'unknown';
45
311
  /**
@@ -92,4 +358,18 @@ export interface ModelConfig {
92
358
  * захардкоженного справочника модальностей нет (решение 2026-10-27).
93
359
  */
94
360
  modalities?: AttachmentModality[];
361
+ /**
362
+ * Особенности протокола модели (перекрывает `ProviderConfig.compatibility`
363
+ * по каждому полю). Например, для одной модели провайдера нужен
364
+ * `max_completion_tokens`, для остальных — дефолт.
365
+ */
366
+ compatibility?: ModelCompatibility;
367
+ /**
368
+ * Shorthand для `compatibility.requireReasoning` (thinking-модели DeepSeek):
369
+ * провайдер требует `reasoning_content` у assistant-сообщений;
370
+ * `undefined` — автоопределение по провайдеру/имени модели, `false` —
371
+ * принудительно выключить. Нормализация:
372
+ * `compatibility.requireReasoning ?? requiresReasoning`.
373
+ */
374
+ requiresReasoning?: boolean;
95
375
  }
@@ -33,3 +33,292 @@ export function hasPriceInput(body) {
33
33
  || 'cache_read_price' in b || 'cacheReadPrice' in b
34
34
  || 'cache_write_price' in b || 'cacheWritePrice' in b;
35
35
  }
36
+ /** Канонические значения `cacheFormat` (для валидации входных данных API). */
37
+ export const CACHE_FORMATS = ['anthropic', 'alibaba'];
38
+ /** Проверка, что значение — допустимый формат inline-маркеров кэша. */
39
+ export function isCacheFormat(value) {
40
+ return typeof value === 'string' && CACHE_FORMATS.includes(value);
41
+ }
42
+ /** Канонический набор нативных аудио-форматов (для валидации и UI). */
43
+ export const NATIVE_AUDIO_FORMATS = ['wav', 'mp3', 'ogg'];
44
+ /** Ключи контракта — для валидации входных данных API. */
45
+ export const MODEL_COMPATIBILITY_KEYS = [
46
+ 'reasoningField',
47
+ 'requireReasoning',
48
+ 'maxTokensField',
49
+ 'requireAssistantAfterTool',
50
+ 'streamUsage',
51
+ 'supportsToolChoice',
52
+ 'cacheFormat',
53
+ 'requireFinishReason',
54
+ 'supportsEffortUpdates',
55
+ 'supportsNativeVideo',
56
+ 'nativeAudioFormats',
57
+ ];
58
+ /**
59
+ * RouterAI — прокси с расширениями протоколов (нативное аудио/видео).
60
+ *
61
+ * Единственный носитель host-знания в слое совместимости: **эвристика**
62
+ * умолчания для `supportsNativeVideo`/`nativeAudioFormats`. Сами значения
63
+ * приходят данными (`compatibility`) — этот предикат лишь задаёт дефолт,
64
+ * который любая запись каталога перекрывает явно (ADR-117).
65
+ *
66
+ * Функция чистая (только строка) — `node:*` в shared не тащим.
67
+ */
68
+ export function isRouterAiUrl(url) {
69
+ try {
70
+ const host = new URL(url).hostname.toLowerCase();
71
+ return host === 'routerai.ru' || host.endsWith('.routerai.ru');
72
+ }
73
+ catch {
74
+ return false;
75
+ }
76
+ }
77
+ /**
78
+ * Нативный аудио-контейнер по MIME (ADR-115): `wav`/`mp3`/`ogg`.
79
+ * Прочие MIME (в т.ч. не-аудио) → `null`.
80
+ */
81
+ export function nativeAudioFormatForMime(mime) {
82
+ const normalized = (mime ?? '').toLowerCase().split(';')[0].trim();
83
+ if (normalized === 'audio/wav' || normalized === 'audio/x-wav' || normalized === 'audio/wave')
84
+ return 'wav';
85
+ if (normalized === 'audio/mpeg' || normalized === 'audio/mp3')
86
+ return 'mp3';
87
+ if (normalized === 'audio/ogg' || normalized === 'audio/opus' || normalized === 'audio/oga')
88
+ return 'ogg';
89
+ return null;
90
+ }
91
+ /**
92
+ * Эвристики совместимости — те же, что в opencode
93
+ * (`packages/ai/src/protocols/openai-chat.ts`):
94
+ *
95
+ * - `requireReasoning`: тип/имя провайдера `deepseek`, URL ~ `deepseek.com`,
96
+ * модель ~ `deepseek`; провайдер `minimax` или URL ~ `minimax`
97
+ * (adaptive thinking у MiniMax идёт в тот же бюджет вывода);
98
+ * - `requireAssistantAfterTool`: Mistral-семейство (`mistral`, `devstral`,
99
+ * `codestral`, `pixtral`, `mixtral`);
100
+ * - `supportsToolChoice`: `false` для нативного Ollama (`type: 'ollama'`).
101
+ *
102
+ * `maxTokensField` намеренно **не** эвристируется: наш дефолт — `max_tokens`,
103
+ * `max_completion_tokens` только при явном значении (локальные серверы).
104
+ *
105
+ * **Нативные медиа (ADR-115 × ADR-117).** Матрица «тип провайдера ×
106
+ * RouterAI-совместимый хост» — дефолт для `nativeAudioFormats`/
107
+ * `supportsNativeVideo`:
108
+ *
109
+ * | тип | RouterAI | nativeAudioFormats | supportsNativeVideo |
110
+ * |--------------|----------|--------------------|---------------------|
111
+ * | openai/generic| да | wav, mp3, ogg | `true` |
112
+ * | openai/generic| нет | wav, mp3 | `false` |
113
+ * | anthropic | да | wav | `false` |
114
+ * | anthropic | нет | — | `false` |
115
+ * | прочие | любой | — | `false` |
116
+ *
117
+ * Основание — прежнее поведение по хосту: `anthropic` принимает аудио только в
118
+ * `wav` и только у RouterAI (Anthropic-совместимый шлюз на ogg/mp3 отвечает 200,
119
+ * но модель аудио не слышит — такие форматы идут через aux-модель); OpenAI-протокол
120
+ * принимает wav/mp3 всегда, ogg — расширение RouterAI; блок `video_url` знает
121
+ * только RouterAI-совместимый OpenAI-протокол.
122
+ *
123
+ * Живой тест 2026-11-03: не-routerai прокси `itphx`
124
+ * (`https://ai.itphx.ru/api/`) нативное видео **умеет** — старый предикат по
125
+ * хосту давал ложноотрицательный ответ. Отсюда правило: дефолт по хосту —
126
+ * лишь эвристика, а решение принимают **данные** (`compatibility`), которыми
127
+ * провайдер/модель перекрывают эвристику явно.
128
+ */
129
+ export function detectCompatibilityHeuristics(context) {
130
+ const type = (context.providerType ?? '').toLowerCase();
131
+ const name = (context.providerName ?? '').toLowerCase();
132
+ const url = (context.baseUrl ?? '').toLowerCase();
133
+ const model = (context.modelId ?? '').toLowerCase();
134
+ const requireReasoning = type === 'deepseek'
135
+ || name === 'deepseek'
136
+ || url.includes('deepseek.com')
137
+ || model.includes('deepseek')
138
+ // MiniMax: adaptive thinking включён на стороне модели и расходует тот же
139
+ // `max_tokens` — без запаса вывода ответ приходит пустым. Определяем по
140
+ // провайдеру/URL, а не по модели: имя `minimax` носят сторонние видео-модели.
141
+ || name === 'minimax'
142
+ || url.includes('minimax');
143
+ const mistral = ['mistral', 'devstral', 'codestral', 'pixtral', 'mixtral']
144
+ .some((family) => model.includes(family));
145
+ // ADR-115: нативные медиа — дефолт по типу протокола и RouterAI-совместимому
146
+ // хосту (см. матрицу в докстринге). Явные значения `compatibility` перекрывают.
147
+ const routerAi = isRouterAiUrl(context.baseUrl ?? '');
148
+ const openAiLike = type === 'openai' || type === 'generic';
149
+ const nativeAudioFormats = openAiLike
150
+ ? (routerAi ? ['wav', 'mp3', 'ogg'] : ['wav', 'mp3'])
151
+ : type === 'anthropic'
152
+ ? (routerAi ? ['wav'] : [])
153
+ : [];
154
+ const supportsNativeVideo = openAiLike && routerAi;
155
+ return {
156
+ requireReasoning,
157
+ requireAssistantAfterTool: mistral,
158
+ supportsToolChoice: type !== 'ollama',
159
+ nativeAudioFormats,
160
+ supportsNativeVideo,
161
+ };
162
+ }
163
+ /**
164
+ * Наложение слоёв совместимости: `undefined`-поля не перетирают значение.
165
+ * Поздние слои приоритетнее (провайдер → shorthand → модель).
166
+ */
167
+ export function mergeModelCompatibility(...layers) {
168
+ const merged = {};
169
+ for (const layer of layers) {
170
+ if (!layer)
171
+ continue;
172
+ for (const [key, value] of Object.entries(layer)) {
173
+ if (value !== undefined)
174
+ merged[key] = value;
175
+ }
176
+ }
177
+ return merged;
178
+ }
179
+ /**
180
+ * Разрешение итоговой совместимости.
181
+ *
182
+ * Порядок: **явное значение модели → явное значение провайдера → эвристика →
183
+ * встроенный дефолт**. `reasoningField`, заданный явно на любом уровне, сам по
184
+ * себе означает `requireReasoning: true` (как в opencode) — если
185
+ * `requireReasoning` не переопределён явно (в т.ч. `false`).
186
+ */
187
+ export function resolveModelCompatibility(providerCompat, modelCompat, heuristics = {}) {
188
+ const explicitReasoningField = modelCompat?.reasoningField ?? providerCompat?.reasoningField;
189
+ const explicitRequireReasoning = modelCompat?.requireReasoning ?? providerCompat?.requireReasoning;
190
+ const requireReasoning = explicitRequireReasoning
191
+ ?? (explicitReasoningField !== undefined ? true : (heuristics.requireReasoning ?? false));
192
+ return {
193
+ reasoningField: explicitReasoningField ?? heuristics.reasoningField ?? 'reasoning_content',
194
+ requireReasoning,
195
+ maxTokensField: modelCompat?.maxTokensField
196
+ ?? providerCompat?.maxTokensField
197
+ ?? heuristics.maxTokensField
198
+ ?? 'max_tokens',
199
+ requireAssistantAfterTool: modelCompat?.requireAssistantAfterTool
200
+ ?? providerCompat?.requireAssistantAfterTool
201
+ ?? heuristics.requireAssistantAfterTool
202
+ ?? false,
203
+ streamUsage: modelCompat?.streamUsage
204
+ ?? providerCompat?.streamUsage
205
+ ?? heuristics.streamUsage
206
+ ?? true,
207
+ supportsToolChoice: modelCompat?.supportsToolChoice
208
+ ?? providerCompat?.supportsToolChoice
209
+ ?? heuristics.supportsToolChoice
210
+ ?? true,
211
+ // Дефолт — `true` (как в opencode): стрим без `finish_reason` считается
212
+ // недописанным. Явный `false` возвращает толерантное поведение.
213
+ requireFinishReason: modelCompat?.requireFinishReason
214
+ ?? providerCompat?.requireFinishReason
215
+ ?? heuristics.requireFinishReason
216
+ ?? true,
217
+ // Effort-режим Anthropic — только явным значением (без авто-эвристики):
218
+ // включение меняет тело запроса (output_config вместо thinking), и
219
+ // угадывание по модели сломало бы шлюзы без поддержки поля.
220
+ supportsEffortUpdates: modelCompat?.supportsEffortUpdates
221
+ ?? providerCompat?.supportsEffortUpdates
222
+ ?? heuristics.supportsEffortUpdates
223
+ ?? false,
224
+ // Inline-маркеры кэша — только явным значением: эвристики по типу
225
+ // провайдера не ставятся, иначе менялось бы поведение существующих записей.
226
+ cacheFormat: modelCompat?.cacheFormat ?? providerCompat?.cacheFormat ?? heuristics.cacheFormat,
227
+ // ADR-115: нативные медиа — тот же порядок «модель → провайдер → эвристика».
228
+ // Важно: `??` не схлопывает пустой массив (`[]` — не null/undefined), поэтому
229
+ // явный пустой перечень форматов перекрывает эвристику («ни одного»).
230
+ nativeAudioFormats: modelCompat?.nativeAudioFormats
231
+ ?? providerCompat?.nativeAudioFormats
232
+ ?? heuristics.nativeAudioFormats
233
+ ?? [],
234
+ supportsNativeVideo: modelCompat?.supportsNativeVideo
235
+ ?? providerCompat?.supportsNativeVideo
236
+ ?? heuristics.supportsNativeVideo
237
+ ?? false,
238
+ };
239
+ }
240
+ /**
241
+ * Строгий разбор `compatibility` из тела API. Семантика — **замена**:
242
+ * - `undefined` — поле не передано (сохранить existing);
243
+ * - `null` — явно сбросить;
244
+ * - объект — **заменить** значение целиком (UI присылает полный объект из
245
+ * черновика, поэтому отсутствующее в объекте поле означает «авто», а не
246
+ * «оставить как было»); пустой объект равнозначен сбросу;
247
+ * - неизвестные поля и значения неверного типа — ошибка (не терять опечатки
248
+ * молча); иное — ошибка.
249
+ */
250
+ export function parseModelCompatibilityInput(raw, existing) {
251
+ if (raw === undefined)
252
+ return { ok: true, value: existing };
253
+ if (raw === null)
254
+ return { ok: true, value: undefined };
255
+ if (typeof raw !== 'object' || Array.isArray(raw)) {
256
+ return { ok: false, reason: 'compatibility должен быть объектом или null' };
257
+ }
258
+ const input = raw;
259
+ for (const key of Object.keys(input)) {
260
+ if (!MODEL_COMPATIBILITY_KEYS.includes(key)) {
261
+ return { ok: false, reason: `compatibility: неизвестное поле «${key}»` };
262
+ }
263
+ }
264
+ // Присланный объект — полное новое значение: прежние поля не наследуются.
265
+ const replaced = {};
266
+ if ('reasoningField' in input) {
267
+ const value = input.reasoningField;
268
+ if (typeof value !== 'string' || value.trim() === '') {
269
+ return { ok: false, reason: 'compatibility.reasoningField должен быть непустой строкой' };
270
+ }
271
+ replaced.reasoningField = value.trim();
272
+ }
273
+ if ('maxTokensField' in input) {
274
+ const value = input.maxTokensField;
275
+ if (value !== 'max_tokens' && value !== 'max_completion_tokens') {
276
+ return { ok: false, reason: 'compatibility.maxTokensField должен быть max_tokens или max_completion_tokens' };
277
+ }
278
+ replaced.maxTokensField = value;
279
+ }
280
+ if ('cacheFormat' in input) {
281
+ const value = input.cacheFormat;
282
+ if (!isCacheFormat(value)) {
283
+ return { ok: false, reason: 'compatibility.cacheFormat должен быть anthropic или alibaba' };
284
+ }
285
+ replaced.cacheFormat = value;
286
+ }
287
+ for (const key of [
288
+ 'requireReasoning',
289
+ 'requireAssistantAfterTool',
290
+ 'streamUsage',
291
+ 'supportsToolChoice',
292
+ 'requireFinishReason',
293
+ 'supportsEffortUpdates',
294
+ 'supportsNativeVideo',
295
+ ]) {
296
+ if (!(key in input))
297
+ continue;
298
+ const value = input[key];
299
+ if (typeof value !== 'boolean') {
300
+ return { ok: false, reason: `compatibility.${key} должен быть boolean` };
301
+ }
302
+ replaced[key] = value;
303
+ }
304
+ if ('nativeAudioFormats' in input) {
305
+ const value = input.nativeAudioFormats;
306
+ if (!Array.isArray(value)) {
307
+ return { ok: false, reason: 'compatibility.nativeAudioFormats должен быть массивом' };
308
+ }
309
+ const formats = [];
310
+ for (const item of value) {
311
+ if (typeof item !== 'string' || !NATIVE_AUDIO_FORMATS.includes(item)) {
312
+ return {
313
+ ok: false,
314
+ reason: `compatibility.nativeAudioFormats: неизвестный формат «${String(item)}» (допустимы ${NATIVE_AUDIO_FORMATS.join(', ')})`,
315
+ };
316
+ }
317
+ if (!formats.includes(item))
318
+ formats.push(item);
319
+ }
320
+ // Пустой массив — валидное явное значение («ни одного формата»).
321
+ replaced.nativeAudioFormats = formats;
322
+ }
323
+ return { ok: true, value: Object.keys(replaced).length > 0 ? replaced : undefined };
324
+ }