@itphx/synth-backend 0.12.4 → 0.13.8

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 (57) hide show
  1. package/dist/app/deps.d.ts +15 -1
  2. package/dist/app/deps.js +553 -34
  3. package/dist/app/listen.js +56 -7
  4. package/dist/app/mount-routes.js +273 -32
  5. package/dist/app/public-routes.d.ts +2 -0
  6. package/dist/app/public-routes.js +11 -0
  7. package/dist/app/sse-events.d.ts +4 -0
  8. package/dist/app/sse-events.js +53 -6
  9. package/dist/app.d.ts +3 -1
  10. package/dist/app.js +33 -0
  11. package/dist/auth/api-key.d.ts +19 -0
  12. package/dist/auth/api-key.js +56 -0
  13. package/dist/auth/middleware.js +7 -3
  14. package/dist/events/hub.d.ts +17 -0
  15. package/dist/events/hub.js +50 -15
  16. package/dist/init.d.ts +1 -0
  17. package/dist/init.js +96 -0
  18. package/dist/lib/app-config.d.ts +4 -0
  19. package/dist/lib/app-config.js +16 -3
  20. package/dist/lib/bind-host.d.ts +10 -0
  21. package/dist/lib/bind-host.js +32 -0
  22. package/dist/lib/defaults-store.d.ts +1 -1
  23. package/dist/lib/defaults-store.js +1 -1
  24. package/dist/lib/i18n.js +26 -0
  25. package/dist/lib/recalc-can-summarize.js +8 -3
  26. package/dist/main.js +7 -2
  27. package/dist/middleware/rate-limiter.d.ts +4 -1
  28. package/dist/middleware/rate-limiter.js +15 -2
  29. package/dist/routes/agents.js +1 -0
  30. package/dist/routes/auth.js +29 -16
  31. package/dist/routes/llm.js +92 -12
  32. package/dist/routes/mcp-remote.d.ts +23 -0
  33. package/dist/routes/mcp-remote.js +152 -0
  34. package/dist/routes/mcp.d.ts +11 -6
  35. package/dist/routes/mcp.js +35 -6
  36. package/dist/routes/messages.js +2 -0
  37. package/dist/routes/projects.d.ts +9 -3
  38. package/dist/routes/projects.js +32 -3
  39. package/dist/routes/providers.d.ts +4 -1
  40. package/dist/routes/providers.js +19 -99
  41. package/dist/routes/queue.d.ts +4 -1
  42. package/dist/routes/queue.js +4 -1
  43. package/dist/routes/sessions.d.ts +49 -9
  44. package/dist/routes/sessions.js +299 -256
  45. package/package.json +6 -6
  46. package/dist/routes/audit.d.ts +0 -17
  47. package/dist/routes/audit.js +0 -64
  48. package/dist/routes/context.d.ts +0 -4
  49. package/dist/routes/context.js +0 -93
  50. package/dist/routes/debug.d.ts +0 -3
  51. package/dist/routes/debug.js +0 -30
  52. package/dist/routes/gateway-patterns.d.ts +0 -9
  53. package/dist/routes/gateway-patterns.js +0 -57
  54. package/dist/routes/logs.d.ts +0 -24
  55. package/dist/routes/logs.js +0 -100
  56. package/dist/routes/mcp-registry.d.ts +0 -28
  57. package/dist/routes/mcp-registry.js +0 -483
package/dist/lib/i18n.js CHANGED
@@ -20,6 +20,7 @@ const en = {
20
20
  'errors.validation.idRequired': 'id is required',
21
21
  'errors.validation.invalidAgentId': 'Agent ID may contain only Latin letters, digits, hyphen and underscore',
22
22
  'errors.validation.invalidRoleFile': 'Role file name must be a plain file name without paths and ".."',
23
+ 'errors.validation.invalidEffort': 'Invalid effort tier (allowed: low, medium, high, xhigh, max)',
23
24
  'errors.validation.urlRequired': 'url is required',
24
25
  'errors.validation.invalidUrl': 'Invalid URL',
25
26
  'errors.validation.apiKeyRequired': 'api_key is required',
@@ -28,6 +29,11 @@ const en = {
28
29
  'errors.validation.expectedFilesArray': 'expected { files: string[] }',
29
30
  'errors.validation.claimCodeRequired': 'Confirmation code is required',
30
31
  'errors.validation.invalidUsername': 'Invalid username',
32
+ // PROP-054: точечные операции плана/журнала/инвариантов проекта
33
+ 'errors.validation.invalidPlanBody': 'Invalid plan request payload',
34
+ 'errors.validation.invalidLogBody': 'Invalid project log request payload',
35
+ 'errors.validation.invalidInvariantsBody': 'Invalid project invariants payload',
36
+ 'errors.unavailable.remoteProject': 'The operation is not available for a remote project',
31
37
  // ADR-089: приём внешних событий
32
38
  'errors.validation.invalidEvent': 'Invalid event payload',
33
39
  'errors.validation.invalidBinding': 'Invalid binding payload',
@@ -152,9 +158,16 @@ const en = {
152
158
  'locales.ru.nativeName': 'Russian',
153
159
  // Chat
154
160
  'errors.chat.queueFull': 'Queue is full (max {max} messages)',
161
+ // Отключённые провайдер/модель — отказ до постановки в очередь.
162
+ 'errors.chat.providerDisabled': 'Provider "{provider}" is disabled — choose another model',
163
+ 'errors.chat.modelDisabled': 'Model {provider}/{model} is disabled — choose another model',
155
164
  'errors.chat.steerLimitExceeded': 'Steering limit reached (max {max} injected messages per turn)',
156
165
  // ADR-106 Ф3: подтверждение не принято (нет гранта / повторный ответ / чужой ход).
157
166
  'errors.chat.approvalDenied': 'Approval was not accepted: {reason}',
167
+ // Лимиты заметок сессии (`context.stickyNotes`).
168
+ 'errors.notFound.note': 'Note not found',
169
+ 'errors.validation.noteTooLong': 'Note text is too long (max {max} characters)',
170
+ 'errors.conflict.noteLimitReached': 'Session note limit reached (max {max})',
158
171
  // Stub
159
172
  'stub.llmNotConnected': '[Stub] You said: "{content}". LLM engine is not connected yet.',
160
173
  };
@@ -180,6 +193,7 @@ const ru = {
180
193
  'errors.validation.idRequired': 'id обязателен',
181
194
  'errors.validation.invalidAgentId': 'ID агента может содержать только латиницу, цифры, дефис и подчёркивание',
182
195
  'errors.validation.invalidRoleFile': 'Имя файла роли должно быть именем файла без путей и «..»',
196
+ 'errors.validation.invalidEffort': 'Некорректный тир усилия (effort): допустимые значения — low, medium, high, xhigh, max',
183
197
  'errors.validation.urlRequired': 'URL не указан',
184
198
  'errors.validation.invalidUrl': 'Некорректный URL',
185
199
  'errors.validation.apiKeyRequired': 'api_key обязателен',
@@ -188,6 +202,11 @@ const ru = {
188
202
  'errors.validation.expectedFilesArray': 'expected { files: string[] }',
189
203
  'errors.validation.claimCodeRequired': 'Укажите код подтверждения',
190
204
  'errors.validation.invalidUsername': 'Некорректное имя пользователя',
205
+ // PROP-054: точечные операции плана/журнала/инвариантов проекта
206
+ 'errors.validation.invalidPlanBody': 'Некорректное тело запроса плана',
207
+ 'errors.validation.invalidLogBody': 'Некорректное тело запроса журнала проекта',
208
+ 'errors.validation.invalidInvariantsBody': 'Некорректное тело запроса инвариантов проекта',
209
+ 'errors.unavailable.remoteProject': 'Операция недоступна для удалённого проекта',
191
210
  // ADR-089: приём внешних событий
192
211
  'errors.validation.invalidEvent': 'Некорректное тело события',
193
212
  'errors.validation.invalidBinding': 'Некорректное тело биндинга',
@@ -313,9 +332,16 @@ const ru = {
313
332
  'locales.ru.nativeName': 'Русский',
314
333
  // Chat
315
334
  'errors.chat.queueFull': 'Очередь переполнена (максимум {max} сообщений)',
335
+ // Отключённые провайдер/модель — отказ до постановки в очередь.
336
+ 'errors.chat.providerDisabled': 'Провайдер «{provider}» отключён — выберите другую модель',
337
+ 'errors.chat.modelDisabled': 'Модель {provider}/{model} отключена — выберите другую модель',
316
338
  'errors.chat.steerLimitExceeded': 'Достигнут лимит вмешательств в ход (максимум {max} сообщений на ход)',
317
339
  // ADR-106 Ф3: подтверждение не принято (нет гранта / повторный ответ / чужой ход).
318
340
  'errors.chat.approvalDenied': 'Подтверждение не принято: {reason}',
341
+ // Лимиты заметок сессии (`context.stickyNotes`).
342
+ 'errors.notFound.note': 'Заметка не найдена',
343
+ 'errors.validation.noteTooLong': 'Текст заметки слишком длинный (максимум {max} символов)',
344
+ 'errors.conflict.noteLimitReached': 'Достигнут лимит заметок сессии (максимум {max})',
319
345
  // Stub
320
346
  'stub.llmNotConnected': '[Заглушка] Вы сказали: "{content}". LLM-движок ещё не подключён.',
321
347
  };
@@ -16,9 +16,14 @@ export function createRecalcCanSummarize({ sessionManager, contextOptimizer, eve
16
16
  const can = contextOptimizer.canSummarize(s);
17
17
  // Перепроверить флаг summarizationPending при toggle/pin/delete
18
18
  let shouldClearPending = false;
19
- if (s.summarizationPending && s.settings.summarizationEnabled) {
20
- const sumResult = contextOptimizer.shouldSummarize(s);
21
- if (!sumResult.triggered) {
19
+ if (s.summarizationPending) {
20
+ const compression = typeof contextOptimizer.shouldCompress === 'function'
21
+ ? contextOptimizer.shouldCompress(s)
22
+ : { ...contextOptimizer.shouldSummarize(s), mode: 'summarization' };
23
+ if (!compression.triggered || !compression.mode) {
24
+ shouldClearPending = true;
25
+ }
26
+ else if (typeof contextOptimizer.canCompress === 'function' && !contextOptimizer.canCompress(s)) {
22
27
  shouldClearPending = true;
23
28
  }
24
29
  }
package/dist/main.js CHANGED
@@ -4,8 +4,11 @@
4
4
  // живёт в app.ts — это позволяет поднимать backend in-process в интеграционных
5
5
  // тестах без запуска процесса.
6
6
  import { createBackendApp } from './app.js';
7
+ import { detectContainer, resolveBindHost } from './lib/bind-host.js';
7
8
  import { configureRestart, resolveRestartMode, RESTART_EXIT_CODE, setSynthReady, } from '@itphx/synth-core';
8
- const host = process.env.SYNTH_HOST || '0.0.0.0';
9
+ // Аудит F5: вне контейнера слушаем loopback (наружу — только явным SYNTH_HOST);
10
+ // в контейнере/K8s — 0.0.0.0, иначе порт недоступен снаружи.
11
+ const host = resolveBindHost(process.env, detectContainer(process.env));
9
12
  // ADR-077: fail-closed на старте (неверный `execution.mode` или `remote` —
10
13
  // удалённый исполнитель ещё не реализован, шаг 7 плана) — с понятным текстом.
11
14
  let handle;
@@ -16,7 +19,7 @@ catch (err) {
16
19
  console.error(err instanceof Error ? err.message : String(err));
17
20
  process.exit(1);
18
21
  }
19
- const { app, dataDir, port, config, auth, eventHub, queueManager, sessionManager, stopEphemeralSweeper, stopEventJournalPruner, stopAnalyticsRollupPruner, stopScheduler, stopWebhookService, stopWebhookDeliveryPruner, stopMetrics, stopQuestionPruner, stopBackgroundRunPruner, stopProcessLogPruner, stopAttachmentPruner } = handle;
22
+ const { app, dataDir, port, config, auth, eventHub, queueManager, sessionManager, stopEphemeralSweeper, stopEventJournalPruner, stopAnalyticsRollupPruner, stopScheduler, stopWebhookService, stopWebhookDeliveryPruner, stopMetrics, stopQuestionPruner, stopBackgroundRunPruner, stopProcessLogPruner, stopAttachmentPruner, stopMediaTempPruner } = handle;
20
23
  // ADR-090 (Ф5б-1): старт-активация установленных плагинов.
21
24
  // `plugins.lock.json` — источник истины; `plugins.executionEnabled=false`
22
25
  // (дефолт) → no-op. Ошибка плагина/рантайма **не роняет старт** (только
@@ -83,6 +86,8 @@ async function gracefulShutdown(signal, exitCode = 0) {
83
86
  stopProcessLogPruner();
84
87
  // ADR-115: остановить GC осиротевших вложений сообщений.
85
88
  stopAttachmentPruner();
89
+ // ADR-115 × ADR-077: остановить уборку временных каталогов медиа-раннера.
90
+ stopMediaTempPruner();
86
91
  // ADR-094: остановить процессные метрики и фоновые доменные коллекторы
87
92
  // (таймеры сессий/хранилища, подписка шины, decision/journal).
88
93
  stopMetrics();
@@ -2,10 +2,13 @@ import type { Context } from 'hono';
2
2
  /**
3
3
  * In-memory rate limiter.
4
4
  * Ключ — Authorization header (уникален для каждого пользователя/ключа).
5
+ * `maxRequests` — число запросов в окно; может быть **геттером** — тогда порог
6
+ * вычисляется на каждый запрос (runtime-настройка без рестарта). `<= 0` —
7
+ * без ограничения (счётчик не ведётся).
5
8
  * `message` — опциональный резолвер локализованного текста (i18n); по умолчанию —
6
9
  * общий русский текст (обратная совместимость).
7
10
  */
8
- export declare function createRateLimiter(maxRequests?: number, windowMs?: number, message?: (c: Context) => string): import("hono").MiddlewareHandler<any, string, {}, Response | (Response & import("hono").TypedResponse<{
11
+ export declare function createRateLimiter(maxRequests?: number | (() => number), windowMs?: number, message?: (c: Context) => string): import("hono").MiddlewareHandler<any, string, {}, Response | (Response & import("hono").TypedResponse<{
9
12
  error: {
10
13
  code: string;
11
14
  message: string;
@@ -2,6 +2,9 @@ import { createMiddleware } from 'hono/factory';
2
2
  /**
3
3
  * In-memory rate limiter.
4
4
  * Ключ — Authorization header (уникален для каждого пользователя/ключа).
5
+ * `maxRequests` — число запросов в окно; может быть **геттером** — тогда порог
6
+ * вычисляется на каждый запрос (runtime-настройка без рестарта). `<= 0` —
7
+ * без ограничения (счётчик не ведётся).
5
8
  * `message` — опциональный резолвер локализованного текста (i18n); по умолчанию —
6
9
  * общий русский текст (обратная совместимость).
7
10
  */
@@ -13,8 +16,15 @@ export function createRateLimiter(maxRequests = 20, windowMs = 60_000, message)
13
16
  if (entry.resetAt <= now)
14
17
  hits.delete(key);
15
18
  }
16
- }, windowMs);
19
+ }, windowMs).unref?.();
17
20
  return createMiddleware(async (c, next) => {
21
+ // Порог вычисляется на каждый запрос: динамический геттер позволяет
22
+ // применять runtime-изменение из админки без пересоздания middleware.
23
+ const limit = typeof maxRequests === 'function' ? maxRequests() : maxRequests;
24
+ if (limit <= 0) {
25
+ await next();
26
+ return;
27
+ }
18
28
  const key = c.req.header('Authorization')
19
29
  || c.req.header('x-forwarded-for')
20
30
  || 'anonymous';
@@ -25,7 +35,10 @@ export function createRateLimiter(maxRequests = 20, windowMs = 60_000, message)
25
35
  hits.set(key, entry);
26
36
  }
27
37
  entry.count += 1;
28
- if (entry.count > maxRequests) {
38
+ if (entry.count > limit) {
39
+ // Аддитивный заголовок: клиенту полезно знать, когда пробовать снова.
40
+ const retryAfter = Math.max(1, Math.ceil((entry.resetAt - Date.now()) / 1000));
41
+ c.header('Retry-After', String(retryAfter));
29
42
  return c.json({ error: { code: 'RATE_LIMITED', message: message ? message(c) : 'Превышен лимит запросов' } }, 429);
30
43
  }
31
44
  await next();
@@ -27,6 +27,7 @@ export function createAgentRoutes(kit, agentStore, agentRegistry, getDefaultAgen
27
27
  idRequired: (c) => t('errors.validation.idRequired', undefined, c),
28
28
  invalidAgentId: (c) => t('errors.validation.invalidAgentId', undefined, c),
29
29
  invalidRoleFile: (c) => t('errors.validation.invalidRoleFile', undefined, c),
30
+ invalidEffort: (c) => t('errors.validation.invalidEffort', undefined, c),
30
31
  agentNotFound: (c) => t('errors.notFound.agent', undefined, c),
31
32
  agentOverrideNotFound: (c) => t('errors.notFound.agentOverride', undefined, c),
32
33
  },
@@ -4,17 +4,29 @@ import { createLazyOidcClient, oidcUserToUser } from '../auth/oidc.js';
4
4
  import { getCookie, setCookie, deleteCookie } from 'hono/cookie';
5
5
  import { t } from '../lib/i18n.js';
6
6
  import { getDefaultLang, setDefaultLang } from '../lib/i18n-config.js';
7
+ import { resolveAppearanceDefaults } from '@itphx/synth-core';
7
8
  import { readFile, writeFile, unlink } from 'node:fs/promises';
8
9
  import { join, resolve, sep } from 'node:path';
9
10
  const OIDC_STATE_COOKIE = 'oidc_state';
10
11
  // Встроенные умолчания оформления (совпадают с тем, что использует UI
11
- // по умолчанию: packages/ui/src/lib/defaults.ts + uiScale.ts).
12
- const BUILT_IN_DEFAULTS = {
13
- themeMode: 'system',
14
- theme: 'synthesis',
15
- uiScaleMobile: null,
16
- uiScaleDesktop: null,
17
- };
12
+ // по умолчанию: packages/ui/src/lib/defaults.ts + uiScale.ts) живут в core —
13
+ // один источник для standalone (`GET /auth/defaults`) и managed (здесь),
14
+ // поэтому ответы сборок не расходятся (аудит F13).
15
+ /**
16
+ * Поля умолчаний оформления, которые принимает `PUT /defaults`.
17
+ * Whitelist на границе: тело запроса не должно попадать в стор целиком
18
+ * (запись валидирует store, но лишние ключи там не нужны).
19
+ */
20
+ const DEFAULT_FIELDS = [
21
+ 'themeMode',
22
+ 'theme',
23
+ 'uiScaleMobile',
24
+ 'uiScaleDesktop',
25
+ 'chatViewMode',
26
+ 'chatDensity',
27
+ 'chatScaleMobile',
28
+ 'chatScaleDesktop',
29
+ ];
18
30
  export function createAuthRoutes(kit, config, profiles, dataDir, defaultsStore,
19
31
  /**
20
32
  * ADR-090 Ф7: сигнал о серверной политике плагинов для публичного
@@ -46,14 +58,7 @@ pluginPolicySignal) {
46
58
  return full.startsWith(avatarsRoot + sep) ? full : null;
47
59
  };
48
60
  // Сохранённые умолчания перекрывают встроенные; uiScaleMobile/uiScaleDesktop: null — умолчание не задано.
49
- const resolveDefaults = async () => {
50
- const stored = defaultsStore ? await defaultsStore.loadDefaults() : {};
51
- return {
52
- locale: getDefaultLang(),
53
- ...BUILT_IN_DEFAULTS,
54
- ...stored,
55
- };
56
- };
61
+ const resolveDefaults = async () => resolveAppearanceDefaults(defaultsStore, getDefaultLang());
57
62
  const getOidcClient = createLazyOidcClient(config.oidc);
58
63
  // GET /auth/login — редирект на Keycloak authorize endpoint
59
64
  app.get('/login', async (c) => {
@@ -404,7 +409,15 @@ pluginPolicySignal) {
404
409
  setDefaultLang(locale);
405
410
  }
406
411
  if (defaultsStore) {
407
- const patch = { ...body };
412
+ // Whitelist полей: остальное тело запроса игнорируется, а валидация
413
+ // значений (enum/диапазоны) — в `DefaultsStore.sanitize`.
414
+ const patch = {};
415
+ const rest = body;
416
+ for (const field of DEFAULT_FIELDS) {
417
+ if (field in rest) {
418
+ patch[field] = rest[field];
419
+ }
420
+ }
408
421
  if (patch.locale === undefined && (locale === 'en' || locale === 'ru')) {
409
422
  patch.locale = locale;
410
423
  }
@@ -1,7 +1,8 @@
1
1
  import { Hono } from 'hono';
2
2
  import { z } from 'zod';
3
3
  import { scopeGuard } from '../auth/service-scope.js';
4
- import { ContextLengthExceededError, deobfuscateSecrets, GatewayProvider, ProviderError, ProviderFactory, RateLimitError, createLlmCallRecorder, } from '@itphx/synth-core';
4
+ import { EFFORT_LEVELS, mergeModelCompatibility } from '@itphx/synth-shared';
5
+ import { buildChatOptions, ContextLengthExceededError, deobfuscateSecrets, GatewayProvider, ProviderError, ProviderFactory, RateLimitError, createLlmCallRecorder, } from '@itphx/synth-core';
5
6
  /**
6
7
  * LLM Proxy endpoint (гибридный режим, Часть 5).
7
8
  * OpenAI-совместимый POST /api/v2/llm/chat/completions, через который локальный
@@ -29,12 +30,22 @@ const chatCompletionsSchema = z.object({
29
30
  temperature: z.number().optional(),
30
31
  max_tokens: z.number().int().positive().optional(),
31
32
  top_p: z.number().optional(),
33
+ /**
34
+ * ADR-117: тир усилия модели в OpenAI-совместимом поле (`EffortLevel`).
35
+ * Прокидывается провайдеру как `ChatOptions.effort`; отправляется он только
36
+ * при `compatibility.supportsEffortUpdates` (guard остаётся в провайдере).
37
+ * Невалидное значение — 400 (контракт запроса, а не «тихий» игнор).
38
+ */
39
+ reasoning_effort: z.enum(EFFORT_LEVELS).optional(),
32
40
  stream: z.boolean().optional(),
33
41
  // ADR-070: remote-зеркала (RemoteProvider) просят usage в стриме. Внутренний
34
42
  // OpenAIProvider всегда шлёт stream_options.include_usage, но поле принимаем
35
43
  // явно, чтобы Zod его не срезал (контракт запроса).
36
44
  stream_options: z.object({ include_usage: z.boolean().optional() }).optional(),
37
45
  tools: z.array(z.record(z.string(), z.unknown())).optional(),
46
+ // Управление вызовом инструментов на шаге: `none` — финальный шаг-отчёт по
47
+ // лимиту шагов (инструменты остаются в запросе ради кэшированного префикса).
48
+ tool_choice: z.enum(['auto', 'none', 'required']).optional(),
38
49
  session_id: z.string().optional(),
39
50
  // Имя серверного провайдера (шлют remote-зеркала RemoteProvider в гибриде).
40
51
  // Опционально — старые клиенты без поля работают как раньше (резолв по модели).
@@ -62,13 +73,44 @@ function mapProviderError(err) {
62
73
  }
63
74
  return { status: 502, code: 'PROVIDER_ERROR', message };
64
75
  }
65
- /** OpenAI-формат usage из TokenUsage ядра. */
76
+ /**
77
+ * OpenAI-формат usage из TokenUsage ядра — **без потерь**.
78
+ *
79
+ * Гибридный `RemoteProvider` (`providers/remote.ts`) читает из ответа прокси
80
+ * `prompt_tokens_details.cached_tokens`, `cache_creation_input_tokens`
81
+ * (Anthropic-совместимый fallback), `completion_tokens_details.reasoning_tokens`
82
+ * и провайдерскую стоимость (`parseUsageCost`). Если прокси отдаёт только
83
+ * `prompt/completion/total_tokens`, локальная статистика в гибриде показывает
84
+ * нули по кэшу/размышлениям/стоимости — поэтому передаём всё.
85
+ *
86
+ * Детали-объекты добавляются только при заданном значении > 0: у провайдера без
87
+ * кэша/размышлений ответ остаётся прежним (`{prompt,completion,total}_tokens`).
88
+ */
66
89
  function toOpenAiUsage(usage) {
67
- return {
90
+ const result = {
68
91
  prompt_tokens: usage.inputTokens ?? 0,
69
92
  completion_tokens: usage.outputTokens ?? 0,
70
93
  total_tokens: usage.totalTokens ?? 0,
71
94
  };
95
+ // ADR-070 §2.3: cache read — та же точка, что читает RemoteProvider.
96
+ if (usage.cacheReadTokens && usage.cacheReadTokens > 0) {
97
+ result.prompt_tokens_details = { cached_tokens: usage.cacheReadTokens };
98
+ }
99
+ if (usage.reasoningTokens && usage.reasoningTokens > 0) {
100
+ result.completion_tokens_details = { reasoning_tokens: usage.reasoningTokens };
101
+ }
102
+ // Anthropic-совместимый fallback: `RemoteProvider._parseUsage` берёт
103
+ // cache write именно отсюда (в OpenAI-формате своего поля нет).
104
+ if (usage.cacheWriteTokens && usage.cacheWriteTokens > 0) {
105
+ result.cache_creation_input_tokens = usage.cacheWriteTokens;
106
+ }
107
+ // Стоимость провайдера приоритетнее каталожной цены (`parseUsageCost`).
108
+ // `0` — достоверная нулевая стоимость, поэтому проверяем само наличие.
109
+ if (usage.cost && Number.isFinite(usage.cost.amount)) {
110
+ result.cost = usage.cost.amount;
111
+ result.currency = usage.cost.currency;
112
+ }
113
+ return result;
72
114
  }
73
115
  /**
74
116
  * Конвертация OpenAI-сообщений в LLMMessage ядра. Из tool-полей заполняются
@@ -156,6 +198,10 @@ export function createLlmRoutes(kit, deps) {
156
198
  }, 400);
157
199
  }
158
200
  // 2. Создаём провайдер (модель из ModelConfig.name — реальное имя для LLM API).
201
+ // ADR-117: совместимость протокола собирается теми же слоями, что и в
202
+ // сессионном вызове — провайдер → shorthand модели (`requiresReasoning`) →
203
+ // модель. Без этого у прокси не работали `requireReasoning`,
204
+ // `maxTokensField`, `cacheFormat`, `supportsEffortUpdates`.
159
205
  let inner;
160
206
  try {
161
207
  inner = ProviderFactory.create(providerName, {
@@ -167,6 +213,9 @@ export function createLlmRoutes(kit, deps) {
167
213
  timeout: providerConfig.timeout ?? 120,
168
214
  maxTokens: body.max_tokens,
169
215
  numCtx: providerConfig.numCtx,
216
+ compatibility: mergeModelCompatibility(providerConfig.compatibility, modelConfig.requiresReasoning !== undefined
217
+ ? { requireReasoning: modelConfig.requiresReasoning }
218
+ : undefined, modelConfig.compatibility),
170
219
  }, body.temperature, body.top_p);
171
220
  }
172
221
  catch (e) {
@@ -201,12 +250,16 @@ export function createLlmRoutes(kit, deps) {
201
250
  });
202
251
  const messages = toLlmMessages(body.messages);
203
252
  const tools = body.tools && body.tools.length > 0 ? body.tools : undefined;
253
+ // `tool_choice` уходит провайдеру только когда задан в теле (иначе поведение
254
+ // прежнее — решение за моделью); `reasoning_effort` — тем же объектом опций
255
+ // (`buildChatOptions` не создаёт пустой `{}`).
256
+ const chatOptions = buildChatOptions(body.reasoning_effort, body.tool_choice);
204
257
  if (body.stream) {
205
- return streamCompletions(c, provider, messages, tools, body.model, transientMap);
258
+ return streamCompletions(c, provider, messages, tools, body.model, transientMap, chatOptions);
206
259
  }
207
260
  // 4. Non-stream: полный ответ в OpenAI-формате.
208
261
  try {
209
- const response = await provider.chat(messages, undefined, tools, false);
262
+ const response = await provider.chat(messages, undefined, tools, false, undefined, chatOptions);
210
263
  const map = transientMap.get('proxy') ?? {};
211
264
  const content = deobfuscateSecrets(response.content, map);
212
265
  // Симметрично OpenAIProvider._parseResponse: tool_calls → message.tool_calls,
@@ -232,6 +285,11 @@ export function createLlmRoutes(kit, deps) {
232
285
  });
233
286
  return app;
234
287
  }
288
+ /**
289
+ * Интервал SSE keepalive-комментариев прокси (15 с): не даёт idle-таймаутам
290
+ * посредников закрыть поток, пока провайдер молчит (в т.ч. до первого чанка).
291
+ */
292
+ const KEEPALIVE_INTERVAL_MS = 15_000;
235
293
  /**
236
294
  * SSE-стрим в OpenAI-формате (text/event-stream).
237
295
  * Каждая строка: data: {id, object: 'chat.completion.chunk', created, model,
@@ -240,7 +298,7 @@ export function createLlmRoutes(kit, deps) {
240
298
  * Ошибки провайдера в середине стрима (статус уже 200) шлём объектом error
241
299
  * в потоке, затем [DONE] и закрываем.
242
300
  */
243
- function streamCompletions(c, provider, messages, tools, model, transientMap) {
301
+ function streamCompletions(c, provider, messages, tools, model, transientMap, chatOptions) {
244
302
  const signal = c.req.raw.signal;
245
303
  const cancellationToken = {
246
304
  cancelled: false,
@@ -257,7 +315,31 @@ function streamCompletions(c, provider, messages, tools, model, transientMap) {
257
315
  return new Response(new ReadableStream({
258
316
  async start(controller) {
259
317
  const encoder = new TextEncoder();
260
- const send = (obj) => controller.enqueue(encoder.encode(`data: ${JSON.stringify(obj)}\n\n`));
318
+ // `enqueue` после закрытия контроллера бросает — глушим: клиент мог
319
+ // отключиться, и это не ошибка прокси.
320
+ const enqueue = (chunk) => {
321
+ try {
322
+ controller.enqueue(chunk);
323
+ }
324
+ catch {
325
+ /* stream closed by client */
326
+ }
327
+ };
328
+ const send = (obj) => enqueue(encoder.encode(`data: ${JSON.stringify(obj)}\n\n`));
329
+ // SSE keepalive-комментарии: backend отвечает 200 сразу (только
330
+ // заголовки), а провайдер может долго не прислать первый чанк. Без
331
+ // комментариев посредники рвут соединение по idle-таймауту
332
+ // (nginx `proxy_read_timeout` 300s, Traefik idle) — локальный core
333
+ // видит `fetch failed` на длинных сессиях. Комментарий не является
334
+ // `data:`-кадром и не меняет контракт потока.
335
+ const keepalive = setInterval(() => {
336
+ enqueue(encoder.encode(':\n\n'));
337
+ }, KEEPALIVE_INTERVAL_MS);
338
+ // Таймер не должен держать процесс живым после закрытия потока.
339
+ keepalive.unref?.();
340
+ // Один комментарий сразу при старте: заголовки уже отданы, и
341
+ // соединение активно до первого чанка провайдера.
342
+ enqueue(encoder.encode(':\n\n'));
261
343
  let finalUsage;
262
344
  // Накопленные tool_calls: провайдер (OpenAIProvider) отдаёт полный массив в
263
345
  // каждом content-чанке и в финальном чанке. Прокси шлёт их ОДИН раз отдельным
@@ -269,7 +351,7 @@ function streamCompletions(c, provider, messages, tools, model, transientMap) {
269
351
  // отдаём дельту, чтобы клиент (RemoteProvider) накапливал как content.
270
352
  let sentReasoningLen = 0;
271
353
  try {
272
- for await (const chunk of provider.chatAsync(messages, undefined, tools, undefined, cancellationToken)) {
354
+ for await (const chunk of provider.chatAsync(messages, undefined, tools, undefined, cancellationToken, chatOptions)) {
273
355
  if (chunk.usage)
274
356
  finalUsage = chunk.usage;
275
357
  if (chunk.toolCalls && chunk.toolCalls.length > 0)
@@ -335,10 +417,8 @@ function streamCompletions(c, provider, messages, tools, model, transientMap) {
335
417
  send({ error: { code: mapped.code, message: mapped.message } });
336
418
  }
337
419
  finally {
338
- try {
339
- controller.enqueue(encoder.encode('data: [DONE]\n\n'));
340
- }
341
- catch { /* client disconnected */ }
420
+ clearInterval(keepalive);
421
+ enqueue(encoder.encode('data: [DONE]\n\n'));
342
422
  try {
343
423
  controller.close();
344
424
  }
@@ -0,0 +1,23 @@
1
+ import { Hono } from 'hono';
2
+ import type { AuthKit } from '../auth/middleware.js';
3
+ import type { McpManager, McpRegistryRepository } from '@itphx/synth-core';
4
+ /**
5
+ * PROP-125 §1: backend-контракт удалённого MCP в режиме `tools`.
6
+ *
7
+ * Локальный core гибрида ходит сюда вместо прямого egress к MCP-серверу:
8
+ * секреты и сеть остаются на сервере (ADR-105/ADR-099), а локальная сессия
9
+ * получает тот же шейп результата, что и протокол исполнителя 5.
10
+ *
11
+ * Маршруты:
12
+ * - `GET /remote/servers` — состав серверов реестра (все записи, решение 10);
13
+ * - `GET /remote/tools?server=…` — схемы инструментов + `instructions`;
14
+ * - `POST /remote/call` — вызов инструмента `{server, tool, arguments?, meta?}`.
15
+ *
16
+ * Авторизация: интерактивный пользователь — `requireAuth` (ADR-043);
17
+ * service-key — scope `mcp:invoke` (решение 9 владельца).
18
+ */
19
+ export interface McpRemoteRoutesOptions {
20
+ /** Единый реестр MCP-серверов (ADR-071 §2.5) — источник истины для `/remote/*`. */
21
+ registry: McpRegistryRepository;
22
+ }
23
+ export declare function createMcpRemoteRoutes(kit: AuthKit, mcpManager: McpManager | null, options: McpRemoteRoutesOptions): Hono;
@@ -0,0 +1,152 @@
1
+ import { Hono } from 'hono';
2
+ import { z } from 'zod';
3
+ import { requireScopeForServiceKey } from '../auth/guards.js';
4
+ /** Тело `POST /remote/call` — поля контракта `RemoteMcpCallRequest`. */
5
+ const remoteCallSchema = z.object({
6
+ server: z.string().min(1),
7
+ tool: z.string().min(1),
8
+ arguments: z.record(z.string(), z.unknown()).optional(),
9
+ meta: z.record(z.string(), z.unknown()).optional(),
10
+ });
11
+ /** Текст ошибки: только текст исключения — без конфига, URL и секретов. */
12
+ function errorMessage(err) {
13
+ return err instanceof Error ? err.message : String(err);
14
+ }
15
+ export function createMcpRemoteRoutes(kit, mcpManager, options) {
16
+ const app = new Hono();
17
+ const registry = options.registry;
18
+ /**
19
+ * Транспортный статус сервера для локального клиента:
20
+ * `connected` → `up`, `disconnected` → `idle`, `error`/`circuit-open` → `down`.
21
+ */
22
+ const remoteStatus = (name) => {
23
+ if (!mcpManager)
24
+ return 'idle';
25
+ const status = mcpManager.getServerStatus(name);
26
+ if (status === 'connected')
27
+ return 'up';
28
+ if (status === 'disconnected')
29
+ return 'idle';
30
+ return 'down';
31
+ };
32
+ /** Подключить сервер, если он ещё не подключён (иначе — успех). */
33
+ const ensureConnected = async (name) => {
34
+ if (!mcpManager)
35
+ return;
36
+ if (mcpManager.getServerStatus(name) === 'connected')
37
+ return;
38
+ await mcpManager.connectServer(name);
39
+ };
40
+ // --- Список серверных MCP-серверов (все записи реестра) ---
41
+ app.get('/remote/servers', kit.requireAuth, requireScopeForServiceKey('mcp:invoke'), async (c) => {
42
+ const entries = await registry.list();
43
+ const servers = entries.map((entry) => {
44
+ const instructions = mcpManager?.getServerInstructions(entry.name);
45
+ return {
46
+ name: entry.name,
47
+ type: entry.config.type,
48
+ origin: entry.origin,
49
+ trust: entry.trust,
50
+ enabled: entry.enabled,
51
+ enabledByDefault: entry.enabledByDefault,
52
+ remoteMode: entry.remoteMode ?? 'auto',
53
+ status: remoteStatus(entry.name),
54
+ toolCount: mcpManager?.getServerTools(entry.name)?.length ?? 0,
55
+ ...(instructions ? { instructions } : {}),
56
+ };
57
+ });
58
+ return c.json(servers);
59
+ });
60
+ // --- Схемы инструментов сервера ---
61
+ app.get('/remote/tools', kit.requireAuth, requireScopeForServiceKey('mcp:invoke'), async (c) => {
62
+ // Имя сервера ищем в реестре **как есть** (без trim): имя записи реестра —
63
+ // точный ключ. Пустое/пробельное значение — «параметр не задан».
64
+ const name = c.req.query('server') ?? '';
65
+ if (!name.trim()) {
66
+ return c.json({
67
+ error: { code: 'VALIDATION_ERROR', message: 'Параметр server обязателен' },
68
+ }, 400);
69
+ }
70
+ const entry = await registry.getByName(name);
71
+ if (!entry) {
72
+ return c.json({
73
+ error: { code: 'MCP_REMOTE_SERVER_NOT_FOUND', message: `MCP-сервер "${name}" не найден` },
74
+ }, 404);
75
+ }
76
+ if (!mcpManager) {
77
+ return c.json({
78
+ error: { code: 'MCP_REMOTE_UNAVAILABLE', message: 'MCP-менеджер недоступен' },
79
+ }, 503);
80
+ }
81
+ try {
82
+ await ensureConnected(name);
83
+ }
84
+ catch (err) {
85
+ return c.json({
86
+ error: { code: 'MCP_REMOTE_SERVER_DOWN', message: errorMessage(err) },
87
+ }, 502);
88
+ }
89
+ const body = {
90
+ server: name,
91
+ instructions: mcpManager.getServerInstructions(name),
92
+ tools: (mcpManager.getServerTools(name) ?? []).map((tool) => ({ server: name, ...tool })),
93
+ };
94
+ return c.json(body);
95
+ });
96
+ // --- Вызов инструмента серверного MCP-сервера ---
97
+ app.post('/remote/call', kit.requireAuth, requireScopeForServiceKey('mcp:invoke'), async (c) => {
98
+ const raw = await c.req.json().catch(() => null);
99
+ const parsed = remoteCallSchema.safeParse(raw);
100
+ if (!parsed.success) {
101
+ return c.json({
102
+ error: { code: 'VALIDATION_ERROR', message: parsed.error.message },
103
+ }, 400);
104
+ }
105
+ const { server, tool, arguments: args, meta } = parsed.data;
106
+ const entry = await registry.getByName(server);
107
+ if (!entry) {
108
+ return c.json({
109
+ error: { code: 'MCP_REMOTE_SERVER_NOT_FOUND', message: `MCP-сервер "${server}" не найден` },
110
+ }, 404);
111
+ }
112
+ // Системный мастер-флаг: выключенный администратором сервер недоступен нигде.
113
+ if (entry.enabled === false) {
114
+ return c.json({
115
+ error: { code: 'MCP_SERVER_DISABLED', message: 'MCP-сервер отключён администратором' },
116
+ }, 409);
117
+ }
118
+ if (!mcpManager) {
119
+ return c.json({
120
+ error: { code: 'MCP_REMOTE_UNAVAILABLE', message: 'MCP-менеджер недоступен' },
121
+ }, 503);
122
+ }
123
+ try {
124
+ await ensureConnected(server);
125
+ }
126
+ catch (err) {
127
+ return c.json({
128
+ error: { code: 'MCP_REMOTE_SERVER_DOWN', message: errorMessage(err) },
129
+ }, 502);
130
+ }
131
+ try {
132
+ const result = await mcpManager.callServerTool(server, tool, args ?? {}, meta);
133
+ const attachments = result.attachments?.map((item) => ({
134
+ mime: item.mime,
135
+ ...(item.name ? { name: item.name } : {}),
136
+ base64: item.base64,
137
+ }));
138
+ const payload = {
139
+ content: result.content,
140
+ isError: result.isError,
141
+ ...(attachments && attachments.length > 0 ? { attachments } : {}),
142
+ };
143
+ return c.json(payload);
144
+ }
145
+ catch (err) {
146
+ return c.json({
147
+ error: { code: 'MCP_REMOTE_CALL_FAILED', message: errorMessage(err) },
148
+ }, 502);
149
+ }
150
+ });
151
+ return app;
152
+ }