@itphx/synth-backend 0.13.4 → 0.13.10

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 (67) hide show
  1. package/dist/app/deps.d.ts +22 -1
  2. package/dist/app/deps.js +743 -63
  3. package/dist/app/listen.js +30 -35
  4. package/dist/app/mount-routes.js +405 -46
  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.js +2 -0
  8. package/dist/app.d.ts +8 -1
  9. package/dist/app.js +45 -11
  10. package/dist/auth/api-key.d.ts +19 -0
  11. package/dist/auth/api-key.js +56 -0
  12. package/dist/auth/middleware.js +11 -15
  13. package/dist/auth/oidc.d.ts +46 -4
  14. package/dist/auth/oidc.js +55 -8
  15. package/dist/events/hub.d.ts +36 -2
  16. package/dist/events/hub.js +66 -4
  17. package/dist/events/visible-session-ids.d.ts +35 -0
  18. package/dist/events/visible-session-ids.js +29 -0
  19. package/dist/init.d.ts +1 -0
  20. package/dist/init.js +96 -0
  21. package/dist/lib/app-config.js +42 -1
  22. package/dist/lib/bind-host.d.ts +10 -0
  23. package/dist/lib/bind-host.js +32 -0
  24. package/dist/lib/i18n.js +24 -0
  25. package/dist/lib/principal-identity.d.ts +35 -0
  26. package/dist/lib/principal-identity.js +43 -0
  27. package/dist/lib/project-principal.d.ts +27 -0
  28. package/dist/lib/project-principal.js +27 -0
  29. package/dist/lib/recalc-can-summarize.js +8 -5
  30. package/dist/main.js +9 -2
  31. package/dist/middleware/rate-limiter.d.ts +4 -1
  32. package/dist/middleware/rate-limiter.js +15 -2
  33. package/dist/routes/agents.d.ts +3 -3
  34. package/dist/routes/agents.js +6 -2
  35. package/dist/routes/auth.js +38 -20
  36. package/dist/routes/llm.js +65 -7
  37. package/dist/routes/mcp-remote.d.ts +23 -0
  38. package/dist/routes/mcp-remote.js +152 -0
  39. package/dist/routes/mcp.d.ts +11 -6
  40. package/dist/routes/mcp.js +35 -6
  41. package/dist/routes/project-access.d.ts +61 -0
  42. package/dist/routes/project-access.js +62 -0
  43. package/dist/routes/projects.d.ts +42 -5
  44. package/dist/routes/projects.js +128 -17
  45. package/dist/routes/providers.d.ts +4 -1
  46. package/dist/routes/providers.js +19 -99
  47. package/dist/routes/queue.d.ts +7 -1
  48. package/dist/routes/queue.js +7 -1
  49. package/dist/routes/schedules.d.ts +46 -0
  50. package/dist/routes/schedules.js +10 -0
  51. package/dist/routes/sessions.d.ts +67 -6
  52. package/dist/routes/sessions.js +348 -208
  53. package/dist/routes/users.d.ts +14 -1
  54. package/dist/routes/users.js +91 -1
  55. package/package.json +5 -5
  56. package/dist/routes/audit.d.ts +0 -17
  57. package/dist/routes/audit.js +0 -64
  58. package/dist/routes/context.d.ts +0 -4
  59. package/dist/routes/context.js +0 -93
  60. package/dist/routes/debug.d.ts +0 -3
  61. package/dist/routes/debug.js +0 -30
  62. package/dist/routes/gateway-patterns.d.ts +0 -9
  63. package/dist/routes/gateway-patterns.js +0 -57
  64. package/dist/routes/logs.d.ts +0 -24
  65. package/dist/routes/logs.js +0 -100
  66. package/dist/routes/mcp-registry.d.ts +0 -28
  67. package/dist/routes/mcp-registry.js +0 -483
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, stopMediaTempPruner } = handle;
22
+ const { app, dataDir, port, config, auth, eventHub, queueManager, sessionManager, stopEphemeralSweeper, stopEventJournalPruner, stopAnalyticsRollupPruner, stopScheduler, stopTimerService, stopWebhookService, stopWebhookDeliveryPruner, stopMetrics, stopQuestionPruner, stopBackgroundRunPruner, stopProcessLogPruner, stopAttachmentPruner, stopMediaTempPruner, stopTerminalService } = handle;
20
23
  // ADR-090 (Ф5б-1): старт-активация установленных плагинов.
21
24
  // `plugins.lock.json` — источник истины; `plugins.executionEnabled=false`
22
25
  // (дефолт) → no-op. Ошибка плагина/рантайма **не роняет старт** (только
@@ -85,11 +88,15 @@ async function gracefulShutdown(signal, exitCode = 0) {
85
88
  stopAttachmentPruner();
86
89
  // ADR-115 × ADR-077: остановить уборку временных каталогов медиа-раннера.
87
90
  stopMediaTempPruner();
91
+ // PROP-132 (Ф3в): остановить сервис терминалов (живые PTY гасятся).
92
+ stopTerminalService();
88
93
  // ADR-094: остановить процессные метрики и фоновые доменные коллекторы
89
94
  // (таймеры сессий/хранилища, подписка шины, decision/journal).
90
95
  stopMetrics();
91
96
  // ADR-051 (срез): остановить планировщик расписаний.
92
97
  stopScheduler();
98
+ // PROP-141 (Часть B): остановить движок таймеров/будильников.
99
+ stopTimerService();
93
100
  // ADR-052 (этап II): остановить движок исходящих webhooks и retention-очистку.
94
101
  stopWebhookService();
95
102
  stopWebhookDeliveryPruner();
@@ -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();
@@ -2,14 +2,14 @@ import { Hono } from 'hono';
2
2
  import type { AuthKit } from '../auth/middleware.js';
3
3
  import type { JsonStoreLike } from '@itphx/synth-core';
4
4
  import type { AgentDefinition } from '@itphx/synth-shared';
5
- import type { AgentRegistry, ContextFileRepository } from '@itphx/synth-core';
5
+ import type { AgentRegistry, ContextFileRepository, ExecutionProfileCatalog } from '@itphx/synth-core';
6
6
  /**
7
7
  * Backend-обёртка над core-фабрикой агентов: добавляет только RBAC
8
8
  * (админ-эндпоинты — ADMIN) и i18n-сообщения. Логика роутов
9
9
  * (GET /, GET /all, POST /, GET /:id, DELETE /:id, PATCH /:id/enabled) — в core.
10
10
  *
11
11
  * `contextFiles` — порт файлов контекста: запись ролевого промпта агента
12
- * вместе с агентом (ADR-046/ADR-089, поле `role_prompt` в теле POST).
12
+ * вместе с агентом (ADR-126/ADR-089, поле `role_prompt` в теле POST).
13
13
  * Роль пишется тем же guard'ом, что и создание агента (ADMIN).
14
14
  *
15
15
  * ADR-052: запись агентов (создание + ролевой промпт) — «роль ADMIN **или**
@@ -17,4 +17,4 @@ import type { AgentRegistry, ContextFileRepository } from '@itphx/synth-core';
17
17
  * расширений). Guard `requireAdminRoleOrScope` учитывает и роль ADMIN в
18
18
  * service-key, и scope — прежние права не отбираются, новые добавляются.
19
19
  */
20
- export declare function createAgentRoutes(kit: AuthKit, agentStore: JsonStoreLike<AgentDefinition>, agentRegistry?: AgentRegistry, getDefaultAgentId?: () => string | Promise<string>, contextFiles?: ContextFileRepository): Hono;
20
+ export declare function createAgentRoutes(kit: AuthKit, agentStore: JsonStoreLike<AgentDefinition>, agentRegistry?: AgentRegistry, getDefaultAgentId?: () => string | Promise<string>, contextFiles?: ContextFileRepository, executionProfileCatalog?: ExecutionProfileCatalog, browserProfileCatalog?: ExecutionProfileCatalog): Hono;
@@ -8,7 +8,7 @@ import { t } from '../lib/i18n.js';
8
8
  * (GET /, GET /all, POST /, GET /:id, DELETE /:id, PATCH /:id/enabled) — в core.
9
9
  *
10
10
  * `contextFiles` — порт файлов контекста: запись ролевого промпта агента
11
- * вместе с агентом (ADR-046/ADR-089, поле `role_prompt` в теле POST).
11
+ * вместе с агентом (ADR-126/ADR-089, поле `role_prompt` в теле POST).
12
12
  * Роль пишется тем же guard'ом, что и создание агента (ADMIN).
13
13
  *
14
14
  * ADR-052: запись агентов (создание + ролевой промпт) — «роль ADMIN **или**
@@ -16,13 +16,17 @@ import { t } from '../lib/i18n.js';
16
16
  * расширений). Guard `requireAdminRoleOrScope` учитывает и роль ADMIN в
17
17
  * service-key, и scope — прежние права не отбираются, новые добавляются.
18
18
  */
19
- export function createAgentRoutes(kit, agentStore, agentRegistry, getDefaultAgentId, contextFiles) {
19
+ export function createAgentRoutes(kit, agentStore, agentRegistry, getDefaultAgentId, contextFiles, executionProfileCatalog, browserProfileCatalog) {
20
20
  const app = new Hono();
21
21
  app.route('/', createCoreAgentRoutes({ requireAuth: kit.requireAuth }, agentStore, agentRegistry, getDefaultAgentId, {
22
22
  writeGuard: requireAdminRoleOrScope('automation:install'),
23
23
  allGuard: kit.requireAdmin,
24
24
  detailGuard: kit.requireAdmin,
25
25
  roleFiles: contextFiles,
26
+ // PROP-135 Ф6a: каталог профилей — проверка профиля агента при записи.
27
+ ...(executionProfileCatalog ? { executionProfileCatalog } : {}),
28
+ // PROP-135 (браузерный контур): каталог браузерных профилей агента.
29
+ ...(browserProfileCatalog ? { browserProfileCatalog } : {}),
26
30
  messages: {
27
31
  idRequired: (c) => t('errors.validation.idRequired', undefined, c),
28
32
  invalidAgentId: (c) => t('errors.validation.invalidAgentId', undefined, c),
@@ -4,22 +4,24 @@ 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';
10
+ import { ensurePrincipalIdentity } from '../lib/principal-identity.js';
9
11
  const OIDC_STATE_COOKIE = 'oidc_state';
12
+ /**
13
+ * ADR-140: группы пользователя в ответах `/auth/*`.
14
+ *
15
+ * Поле добавляется **только при непустом списке** — у пользователя без групп
16
+ * `groups` в ответе отсутствует (аддитивно, старый клиент не ломается).
17
+ */
18
+ function groupsField(user) {
19
+ return user.groups && user.groups.length > 0 ? { groups: user.groups } : {};
20
+ }
10
21
  // Встроенные умолчания оформления (совпадают с тем, что использует UI
11
- // по умолчанию: packages/ui/src/lib/defaults.ts + uiScale.ts).
12
- // `null` — «умолчание не задано»: UI берёт встроенный дефолт.
13
- const BUILT_IN_DEFAULTS = {
14
- themeMode: 'system',
15
- theme: 'synthesis',
16
- uiScaleMobile: null,
17
- uiScaleDesktop: null,
18
- chatViewMode: null,
19
- chatDensity: null,
20
- chatScaleMobile: null,
21
- chatScaleDesktop: null,
22
- };
22
+ // по умолчанию: packages/ui/src/lib/defaults.ts + uiScale.ts) живут в core —
23
+ // один источник для standalone (`GET /auth/defaults`) и managed (здесь),
24
+ // поэтому ответы сборок не расходятся (аудит F13).
23
25
  /**
24
26
  * Поля умолчаний оформления, которые принимает `PUT /defaults`.
25
27
  * Whitelist на границе: тело запроса не должно попадать в стор целиком
@@ -32,6 +34,8 @@ const DEFAULT_FIELDS = [
32
34
  'uiScaleDesktop',
33
35
  'chatViewMode',
34
36
  'chatDensity',
37
+ 'userMessageMarkdown',
38
+ 'mermaidRenderingMode',
35
39
  'chatScaleMobile',
36
40
  'chatScaleDesktop',
37
41
  ];
@@ -66,15 +70,23 @@ pluginPolicySignal) {
66
70
  return full.startsWith(avatarsRoot + sep) ? full : null;
67
71
  };
68
72
  // Сохранённые умолчания перекрывают встроенные; uiScaleMobile/uiScaleDesktop: null — умолчание не задано.
69
- const resolveDefaults = async () => {
70
- const stored = defaultsStore ? await defaultsStore.loadDefaults() : {};
71
- return {
72
- locale: getDefaultLang(),
73
- ...BUILT_IN_DEFAULTS,
74
- ...stored,
75
- };
76
- };
73
+ const resolveDefaults = async () => resolveAppearanceDefaults(defaultsStore, getDefaultLang());
77
74
  const getOidcClient = createLazyOidcClient(config.oidc);
75
+ /**
76
+ * ADR-140: привязать auth-идентичность пользователя (id из токена) к его
77
+ * профилю при входе — чтобы ACL-id (каталог, передача владения) совпадал с
78
+ * принципалом. Best-effort: ошибка привязки логируется, вход не ломается.
79
+ */
80
+ const linkPrincipalIdentity = async (user) => {
81
+ if (!profiles)
82
+ return;
83
+ try {
84
+ await ensurePrincipalIdentity(profiles, user);
85
+ }
86
+ catch (err) {
87
+ console.warn('[auth] привязка auth-идентичности не удалась:', err instanceof Error ? err.message : String(err));
88
+ }
89
+ };
78
90
  // GET /auth/login — редирект на Keycloak authorize endpoint
79
91
  app.get('/login', async (c) => {
80
92
  const client = getOidcClient();
@@ -109,6 +121,7 @@ pluginPolicySignal) {
109
121
  const user = oidcUserToUser(oidcUser);
110
122
  const sessionId = kit.createSession(user);
111
123
  kit.setSessionCookie(c, sessionId);
124
+ await linkPrincipalIdentity(user);
112
125
  return c.json({ deployment: 'managed', user: { id: user.id, username: user.username, email: user.email, roles: user.roles } });
113
126
  }
114
127
  catch (err) {
@@ -135,6 +148,7 @@ pluginPolicySignal) {
135
148
  const user = oidcUserToUser(oidcUser);
136
149
  const sessionId = kit.createSession(user);
137
150
  kit.setSessionCookie(c, sessionId);
151
+ await linkPrincipalIdentity(user);
138
152
  return c.redirect('/');
139
153
  }
140
154
  catch (err) {
@@ -157,6 +171,7 @@ pluginPolicySignal) {
157
171
  username: user.username,
158
172
  email: user.email,
159
173
  roles: user.roles,
174
+ ...groupsField(user),
160
175
  } : null,
161
176
  });
162
177
  });
@@ -191,6 +206,7 @@ pluginPolicySignal) {
191
206
  username: user.username,
192
207
  email: user.email,
193
208
  roles: user.roles,
209
+ ...groupsField(user),
194
210
  },
195
211
  });
196
212
  });
@@ -205,6 +221,7 @@ pluginPolicySignal) {
205
221
  username: user.username,
206
222
  email: user.email,
207
223
  roles: user.roles,
224
+ ...groupsField(user),
208
225
  });
209
226
  });
210
227
  // POST /auth/spa-login — SPA-логин
@@ -251,6 +268,7 @@ pluginPolicySignal) {
251
268
  }
252
269
  const sessionId = kit.createSession(user);
253
270
  kit.setSessionCookie(c, sessionId);
271
+ await linkPrincipalIdentity(user);
254
272
  return c.json({
255
273
  deployment: 'managed',
256
274
  user: {
@@ -73,13 +73,44 @@ function mapProviderError(err) {
73
73
  }
74
74
  return { status: 502, code: 'PROVIDER_ERROR', message };
75
75
  }
76
- /** 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
+ */
77
89
  function toOpenAiUsage(usage) {
78
- return {
90
+ const result = {
79
91
  prompt_tokens: usage.inputTokens ?? 0,
80
92
  completion_tokens: usage.outputTokens ?? 0,
81
93
  total_tokens: usage.totalTokens ?? 0,
82
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;
83
114
  }
84
115
  /**
85
116
  * Конвертация OpenAI-сообщений в LLMMessage ядра. Из tool-полей заполняются
@@ -254,6 +285,11 @@ export function createLlmRoutes(kit, deps) {
254
285
  });
255
286
  return app;
256
287
  }
288
+ /**
289
+ * Интервал SSE keepalive-комментариев прокси (15 с): не даёт idle-таймаутам
290
+ * посредников закрыть поток, пока провайдер молчит (в т.ч. до первого чанка).
291
+ */
292
+ const KEEPALIVE_INTERVAL_MS = 15_000;
257
293
  /**
258
294
  * SSE-стрим в OpenAI-формате (text/event-stream).
259
295
  * Каждая строка: data: {id, object: 'chat.completion.chunk', created, model,
@@ -279,7 +315,31 @@ function streamCompletions(c, provider, messages, tools, model, transientMap, ch
279
315
  return new Response(new ReadableStream({
280
316
  async start(controller) {
281
317
  const encoder = new TextEncoder();
282
- 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'));
283
343
  let finalUsage;
284
344
  // Накопленные tool_calls: провайдер (OpenAIProvider) отдаёт полный массив в
285
345
  // каждом content-чанке и в финальном чанке. Прокси шлёт их ОДИН раз отдельным
@@ -357,10 +417,8 @@ function streamCompletions(c, provider, messages, tools, model, transientMap, ch
357
417
  send({ error: { code: mapped.code, message: mapped.message } });
358
418
  }
359
419
  finally {
360
- try {
361
- controller.enqueue(encoder.encode('data: [DONE]\n\n'));
362
- }
363
- catch { /* client disconnected */ }
420
+ clearInterval(keepalive);
421
+ enqueue(encoder.encode('data: [DONE]\n\n'));
364
422
  try {
365
423
  controller.close();
366
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
+ }
@@ -1,12 +1,17 @@
1
1
  import { Hono } from 'hono';
2
2
  import type { AuthKit } from '../auth/middleware.js';
3
3
  import type { SessionManager, McpManager } from '@itphx/synth-core';
4
- import type { McpRoutesOptions } from './mcp-registry.js';
5
- export type { McpRoutesOptions } from './mcp-registry.js';
4
+ import type { McpRegistryRoutesOptions } from '@itphx/synth-core';
5
+ export type { McpRegistryRoutesOptions as McpRoutesOptions } from '@itphx/synth-core';
6
+ export type { McpRemoteRoutesOptions } from './mcp-remote.js';
7
+ export { createMcpRemoteRoutes } from './mcp-remote.js';
6
8
  /**
7
9
  * Backend MCP: probe (`POST /probe`) — общая логика core-фабрики; legacy
8
- * `/servers*`, `/session/:id` и единый реестр `/registry*` (ADR-071) —
9
- * backend-only (см. `mcp-registry.ts`). Порядок монтирования: core probe
10
- * первым, затем backend-only.
10
+ * `/servers*`, `/session/:id` и единый реестр `/registry*` (ADR-071) — общая
11
+ * core-фабрика `createMcpRegistryRoutes` (backend передаёт RBAC-guard'ы и
12
+ * i18n-сообщения, логика — одна); `/remote/*` — backend-контракт удалённого MCP
13
+ * в режиме `tools` (PROP-125 §1, см. `mcp-remote.ts`); `/relay/*` — серверный
14
+ * MCP-relay, режим `relay` (PROP-125 §1, фабрика `createMcpRelayRoutes` в core).
15
+ * Порядок монтирования: core probe первым, затем backend-only.
11
16
  */
12
- export declare function createMcpRoutes(kit: AuthKit, mcpManager: McpManager | null, sessionManager: SessionManager | null, options: McpRoutesOptions): Hono;
17
+ export declare function createMcpRoutes(kit: AuthKit, mcpManager: McpManager | null, sessionManager: SessionManager | null, options: McpRegistryRoutesOptions): Hono;
@@ -1,15 +1,44 @@
1
1
  import { Hono } from 'hono';
2
- import { createMcpRoutes as createCoreMcpRoutes } from '@itphx/synth-core';
3
- import { createMcpRegistryRoutes } from './mcp-registry.js';
2
+ import { createMcpRoutes as createCoreMcpRoutes, createMcpRelayRoutes as createCoreMcpRelayRoutes, createMcpRegistryRoutes as createCoreMcpRegistryRoutes, } from '@itphx/synth-core';
3
+ import { createMcpRemoteRoutes } from './mcp-remote.js';
4
+ import { requireAdminOrScope, requireScopeForServiceKey } from '../auth/guards.js';
5
+ import { t } from '../lib/i18n.js';
6
+ export { createMcpRemoteRoutes } from './mcp-remote.js';
4
7
  /**
5
8
  * Backend MCP: probe (`POST /probe`) — общая логика core-фабрики; legacy
6
- * `/servers*`, `/session/:id` и единый реестр `/registry*` (ADR-071) —
7
- * backend-only (см. `mcp-registry.ts`). Порядок монтирования: core probe
8
- * первым, затем backend-only.
9
+ * `/servers*`, `/session/:id` и единый реестр `/registry*` (ADR-071) — общая
10
+ * core-фабрика `createMcpRegistryRoutes` (backend передаёт RBAC-guard'ы и
11
+ * i18n-сообщения, логика — одна); `/remote/*` — backend-контракт удалённого MCP
12
+ * в режиме `tools` (PROP-125 §1, см. `mcp-remote.ts`); `/relay/*` — серверный
13
+ * MCP-relay, режим `relay` (PROP-125 §1, фабрика `createMcpRelayRoutes` в core).
14
+ * Порядок монтирования: core probe первым, затем backend-only.
9
15
  */
10
16
  export function createMcpRoutes(kit, mcpManager, sessionManager, options) {
11
17
  const app = new Hono();
12
18
  app.route('/', createCoreMcpRoutes({ requireAuth: kit.requireAuth }, { mcpManager }));
13
- app.route('/', createMcpRegistryRoutes(kit, mcpManager, sessionManager, options));
19
+ app.route('/', createCoreMcpRegistryRoutes({ requireAuth: kit.requireAuth, isAdmin: (c) => kit.isAdmin(c) }, mcpManager, sessionManager, {
20
+ ...options,
21
+ // Managed RBAC (ADR-052/O1): `POST /servers` — только ADMIN; мутации
22
+ // legacy-сервера — ADMIN или scope `addons:install`; `POST /registry` —
23
+ // service-key обязан нести scope `addons:install` (интерактив — без
24
+ // изменений).
25
+ requireAdmin: kit.requireAdmin,
26
+ requireAdminOrScope: requireAdminOrScope('addons:install'),
27
+ requireScopeForServiceKey: requireScopeForServiceKey('addons:install'),
28
+ // i18n (ADR-041): тексты ошибок — через `t()`.
29
+ messages: {
30
+ sessionNotFound: (c) => t('errors.notFound.session', undefined, c),
31
+ forbidden: (c) => t('auth.forbidden', undefined, c),
32
+ credentialNotFound: (c) => t('errors.notFound.credential', undefined, c),
33
+ },
34
+ }));
35
+ app.route('/', createMcpRemoteRoutes(kit, mcpManager, { registry: options.registry }));
36
+ // PROP-125 §1: relay — полноценный MCP-endpoint одного серверного сервера.
37
+ // Авторизация: интерактив — `requireAuth`; service-key — scope `mcp:invoke`.
38
+ app.route('/', createCoreMcpRelayRoutes({ requireAuth: kit.requireAuth }, {
39
+ mcpManager,
40
+ getEntry: (name) => options.registry.getByName(name),
41
+ authorize: requireScopeForServiceKey('mcp:invoke'),
42
+ }));
14
43
  return app;
15
44
  }