@itphx/synth-shared 0.11.3 → 0.12.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 (92) hide show
  1. package/dist/config/defaults.js +126 -3
  2. package/dist/config/env-overrides.d.ts +29 -0
  3. package/dist/config/env-overrides.js +155 -2
  4. package/dist/config/execution.d.ts +66 -0
  5. package/dist/config/execution.js +146 -0
  6. package/dist/config/index.d.ts +1 -0
  7. package/dist/config/index.js +1 -0
  8. package/dist/config/proxy.js +3 -1
  9. package/dist/config/resolve.d.ts +8 -8
  10. package/dist/config/resolve.js +7 -7
  11. package/dist/config/types.d.ts +1287 -4037
  12. package/dist/config/types.js +461 -68
  13. package/dist/i18n/index.d.ts +1 -1
  14. package/dist/i18n/index.js +277 -0
  15. package/dist/index.d.ts +14 -2
  16. package/dist/index.js +16 -2
  17. package/dist/model-metadata.d.ts +10 -0
  18. package/dist/schemas/index.d.ts +980 -2322
  19. package/dist/schemas/index.js +183 -22
  20. package/dist/types/analytics.d.ts +6 -6
  21. package/dist/types/analytics.js +4 -4
  22. package/dist/types/authority.d.ts +464 -0
  23. package/dist/types/authority.js +445 -0
  24. package/dist/types/background.d.ts +96 -0
  25. package/dist/types/background.js +24 -0
  26. package/dist/types/bus-events.d.ts +23 -1
  27. package/dist/types/catalog.d.ts +349 -0
  28. package/dist/types/catalog.js +393 -0
  29. package/dist/types/decision.d.ts +28 -337
  30. package/dist/types/egress.d.ts +1 -1
  31. package/dist/types/egress.js +1 -1
  32. package/dist/types/events.d.ts +54 -1
  33. package/dist/types/external-credentials.d.ts +352 -0
  34. package/dist/types/external-credentials.js +200 -0
  35. package/dist/types/hooks.d.ts +33 -12
  36. package/dist/types/index.d.ts +20 -0
  37. package/dist/types/index.js +50 -1
  38. package/dist/types/llm-filters.d.ts +150 -0
  39. package/dist/types/llm-filters.js +54 -0
  40. package/dist/types/mcp.d.ts +33 -2
  41. package/dist/types/mcp.js +44 -1
  42. package/dist/types/message.d.ts +45 -1
  43. package/dist/types/pack.d.ts +1102 -0
  44. package/dist/types/pack.js +1003 -0
  45. package/dist/types/permission.d.ts +25 -11
  46. package/dist/types/permission.js +1 -1
  47. package/dist/types/pipeline-engine.d.ts +453 -0
  48. package/dist/types/pipeline-engine.js +440 -0
  49. package/dist/types/pipeline.d.ts +275 -0
  50. package/dist/types/pipeline.js +212 -0
  51. package/dist/types/plugin-audit.d.ts +110 -0
  52. package/dist/types/plugin-audit.js +185 -0
  53. package/dist/types/plugin-hybrid.d.ts +85 -0
  54. package/dist/types/plugin-hybrid.js +68 -0
  55. package/dist/types/plugin-lock.d.ts +95 -0
  56. package/dist/types/plugin-lock.js +1 -0
  57. package/dist/types/plugin-protocol.d.ts +221 -0
  58. package/dist/types/plugin-protocol.js +322 -0
  59. package/dist/types/plugin-runtime.d.ts +25 -0
  60. package/dist/types/plugin-runtime.js +11 -0
  61. package/dist/types/plugin-scan.d.ts +159 -0
  62. package/dist/types/plugin-scan.js +166 -0
  63. package/dist/types/plugin-tools.d.ts +51 -0
  64. package/dist/types/plugin-tools.js +72 -0
  65. package/dist/types/project.d.ts +14 -0
  66. package/dist/types/prompt-blocks.d.ts +102 -0
  67. package/dist/types/prompt-blocks.js +24 -0
  68. package/dist/types/prompt.d.ts +45 -3
  69. package/dist/types/provider.d.ts +11 -0
  70. package/dist/types/question.d.ts +153 -0
  71. package/dist/types/question.js +65 -0
  72. package/dist/types/schedules.d.ts +26 -3
  73. package/dist/types/semver.d.ts +48 -0
  74. package/dist/types/semver.js +218 -0
  75. package/dist/types/service-keys.d.ts +41 -3
  76. package/dist/types/service-keys.js +44 -2
  77. package/dist/types/session.d.ts +54 -0
  78. package/dist/types/steering.d.ts +74 -0
  79. package/dist/types/steering.js +75 -0
  80. package/dist/types/tools.d.ts +125 -5
  81. package/dist/types/tools.js +75 -0
  82. package/dist/types/trust.d.ts +31 -0
  83. package/dist/types/trust.js +27 -0
  84. package/dist/types/worktree.d.ts +170 -0
  85. package/dist/types/worktree.js +101 -0
  86. package/dist/utils/index.d.ts +31 -1
  87. package/dist/utils/index.js +92 -12
  88. package/dist/utils/reasoning.d.ts +16 -0
  89. package/dist/utils/reasoning.js +37 -0
  90. package/dist/version.d.ts +1 -1
  91. package/dist/version.js +1 -1
  92. package/package.json +2 -2
@@ -0,0 +1,185 @@
1
+ /**
2
+ * Виды операций журнала плагинов (ADR-090).
3
+ *
4
+ * Ф1 реализовал `activate`/`deactivate`; Ф2 добавил `scan` (сканер и
5
+ * install-policy — вердикт и число находок пишутся отдельной записью, чтобы по
6
+ * журналу было видно, **чем** решена активация); Ф3б добавил `filter` —
7
+ * события решений фильтров LLM-вызовов (точка `llmFilters`): понижение вето
8
+ * недоверенного фильтра, блокировка вызова доверенным фильтром, сбой/таймаут
9
+ * фильтра. Ф5а добавил `install`/`uninstall` — события установки
10
+ * (`PluginInstaller`: манифест → скан → trust-floor → install-policy →
11
+ * раскладка → lock) и снятия (деактивация → lock → каталог). Долги Д2
12
+ * добавили `rollback` — явный откат на предыдущую версию (в журнале он
13
+ * отличается от установки: `install` фиксирует новую версию, `rollback` —
14
+ * возврат). Ф7 добавил `token` — выдача server-scoped токена плагину (Уровень 2
15
+ * гибридного режима): в журнале — имя плагина и факт выдачи, секрет токена не
16
+ * пишется (инвариант 13).
17
+ *
18
+ * Порядок — жизненный цикл расширения: установка → активация → деактивация →
19
+ * откат версии → снятие, затем диагностические действия (`scan`/`filter`) и
20
+ * выдача токена (`token`).
21
+ */
22
+ export const PLUGIN_AUDIT_ACTIONS = [
23
+ 'install',
24
+ 'activate',
25
+ 'deactivate',
26
+ 'rollback',
27
+ 'uninstall',
28
+ 'scan',
29
+ 'filter',
30
+ 'token',
31
+ ];
32
+ /**
33
+ * Итог операции журнала плагинов:
34
+ * - `ok` — плагин активен (активация состоялась / деактивация выполнена);
35
+ * - `rejected` — активация **не состоялась** (отказ по гейту или остановка).
36
+ */
37
+ export const PLUGIN_AUDIT_OUTCOMES = ['ok', 'rejected'];
38
+ /**
39
+ * Вердикт статического сканера (PROP-068 §4.3: `severity → verdict`).
40
+ * Сканер появляется в Ф2; перечень verdict'ов уже зафиксирован канонически.
41
+ */
42
+ export const PLUGIN_SCAN_VERDICTS = ['safe', 'caution', 'dangerous'];
43
+ /**
44
+ * Машиночитаемые коды причин в журнале плагинов.
45
+ *
46
+ * Источник истины — загрузчик `PluginHost`
47
+ * (`packages/core/src/engine/plugins/plugin-host.ts`): каждый отказ пайплайна
48
+ * активации даёт свой код, поэтому по журналу видно, **на каком гейте**
49
+ * плагин не прошёл.
50
+ */
51
+ export const PLUGIN_AUDIT_REASONS = [
52
+ /** Плагин не найден (resolve). */
53
+ 'plugin.not_found',
54
+ /**
55
+ * Д1 (2026-10-22): источник бандла недоступен или не прошёл проверку
56
+ * целостности — архив не распакован, npm-пакет не скачан/не совпал SRI,
57
+ * URL не ответил или sha256 не совпал, локальный путь не является бандлом.
58
+ * Отказ **до** гейтов установщика: разбирать нечего.
59
+ */
60
+ 'plugin.source_unavailable',
61
+ /**
62
+ * Д2 (2026-10-22): откат невозможен — у записи lock нет `previous` (плагин
63
+ * ни разу не обновлялся) либо каталог предыдущей версии отсутствует (убран
64
+ * вручную/почищен). Состояние не изменилось: клиенту нужно поставить
65
+ * нужную версию установкой, а не откатом.
66
+ */
67
+ 'plugin.rollback_unavailable',
68
+ /** Манифест не прошёл проверку целостности (`validatePackManifest`). */
69
+ 'plugin.manifest_invalid',
70
+ /** Content-hash бандла не совпал с ожидаемым. */
71
+ 'plugin.integrity_mismatch',
72
+ /** Ожидаемый content-hash задан, а проверить его нечем (нет файлов). */
73
+ 'plugin.integrity_unverifiable',
74
+ /** Несовместимая версия контракта точки расширения. */
75
+ 'plugin.contract_mismatch',
76
+ /** Несовместимая версия host-приложения (SemVer). */
77
+ 'plugin.host_mismatch',
78
+ /** Уровень доверия ниже trust-floor инстанса. */
79
+ 'plugin.trust_below_floor',
80
+ /** Сканер/политика установки отклонили плагин (Ф2). */
81
+ 'plugin.scan_rejected',
82
+ /**
83
+ * Вердикт сканера `caution` — требуется **явное подтверждение** владельца
84
+ * (install-policy: `ask`, Ф2). Это не блокировка: активация прерывается с
85
+ * требованием подтверждения, а не запрещается.
86
+ */
87
+ 'plugin.approval_required',
88
+ /**
89
+ * ADR-090 п. 9 (2026-10-24): подтверждение установки **просрочено** — срок
90
+ * 24 ч с момента выдачи истёк. Состояние не изменилось: бандл остаётся в
91
+ * карантине, подтверждение надо выдать заново (поставить бандл заново).
92
+ */
93
+ 'plugin.approval_expired',
94
+ /**
95
+ * ADR-090 п. 9 (2026-10-24): подтверждение **недействительно** — бандл в
96
+ * карантине изменился после выдачи подтверждения (content-hash не совпал).
97
+ * Состояние не изменилось: подтверждение к другому содержимому не относится.
98
+ */
99
+ 'plugin.approval_stale',
100
+ /** Слой плагинов выключен мастер-выключателем (`plugins.enabled=false`). */
101
+ 'plugin.disabled',
102
+ /** Плагин не входит в `plugins.allowlist` (список задан — разрешены только перечисленные). */
103
+ 'plugin.not_allowlisted',
104
+ /** Плагин входит в `plugins.denylist`. */
105
+ 'plugin.denylisted',
106
+ /** Установка во время работы инстанса запрещена (`plugins.runtimeInstall=deny`). */
107
+ 'plugin.runtime_install_denied',
108
+ /**
109
+ * Сканирование выключено (`plugins.scan='disabled'`), а исполнение кода
110
+ * плагинов включено (`plugins.executionEnabled=true`) — **fail-closed**:
111
+ * исполняемый код обязан быть просканирован. Решение владельца (Ф3а,
112
+ * 2026-10-22).
113
+ */
114
+ 'plugin.scan_disabled_with_execution',
115
+ /** Исполнение кода выключено (`plugins.executionEnabled=false`). */
116
+ 'plugin.execution_disabled',
117
+ /**
118
+ * Загрузчик кода недоступен (`PluginHost` без `loader`, Ф1) или загрузка
119
+ * бандла сорвалась (Ф4а: нет `rootDir`, файл вне `rootDir`, не `.js`/`.mjs`,
120
+ * превышен размер, ошибка `import()`).
121
+ */
122
+ 'plugin.loader_unavailable',
123
+ /**
124
+ * Ф4а: модуль **загружен**, но не выполнил контракт `PluginModule` — нет
125
+ * `apply(facade)` (ни `module.apply`, ни `module.default.apply`, ни
126
+ * `module.default`-функции). Исполнять нечего: активация отклонена
127
+ * (`engine/plugins/inline-loader.ts` → `PluginLoadError`).
128
+ */
129
+ 'plugin.module_invalid',
130
+ /**
131
+ * Ф4б-2: режим исполнения `remote`, но в бандле нет серверной точки входа
132
+ * `dist/server.js` — поднимать нечего. Установка/активация отклоняется
133
+ * (`PluginInstaller.installFromDirectory`/`approve`), в lock `remote_entry`
134
+ * не записывается.
135
+ */
136
+ 'plugin.remote_entry_missing',
137
+ /** Плагин уже активен — повторная активация отклонена. */
138
+ 'plugin.already_active',
139
+ /** Плагин не активен — деактивация нечего снимать. */
140
+ 'plugin.not_active',
141
+ /** Сбой disposer'а при обратной прокрутке (остальные disposer'ы выполнены). */
142
+ 'plugin.disposer_failed',
143
+ /**
144
+ * Ф3б: фактические регистрации вкладов не совпали с `provides` манифеста
145
+ * (`diffPackProvides`: объявлено, но не зарегистрировано — или наоборот).
146
+ * ADR-090: расхождение — **отказ активации**
147
+ * (признак несогласованной сборки). Проверяются точки, реализованные в Ф3:
148
+ * `provides.promptBlocks[]` и `provides.llmFilters[]`; `provides.tools[]`
149
+ * присоединится вместе с точкой `tools` (Ф3в).
150
+ */
151
+ 'plugin.provides_mismatch',
152
+ /**
153
+ * Ф3б (точка `llmFilters`): фильтр вернул блокирующий вердикт (`deny`/
154
+ * `redact`), но доверие его владельца ниже `trusted` — **хост понизил
155
+ * вердикт до `allow`**. Право вето — только у доверенных (ADR-090
156
+ * §«Кто вправе блокировать»).
157
+ */
158
+ 'plugin_filter.deny_downgraded',
159
+ /**
160
+ * Ф3б: фильтр доверенного плагина заблокировал LLM-вызов (`deny`) —
161
+ * вызов не ушёл провайдеру.
162
+ */
163
+ 'plugin_filter.denied',
164
+ /**
165
+ * Ф3б: фильтр завершился ошибкой или не уложился в бюджет времени —
166
+ * по `failMode` вызов либо заблокирован (`closed`), либо прошёл (`open`).
167
+ */
168
+ 'plugin_filter.unavailable',
169
+ /**
170
+ * Ф5в: плагин управляется развёртыванием (`plugins.deployDir`; lock-запись
171
+ * с `source: 'deploy'` или `identifier` внутри deploy-каталога) — снятие и
172
+ * переустановка через API/CLI запрещены (`plugins.managedReadonly`, дефолт
173
+ * `true`). Состояние не изменилось: плагин меняется только новым образом/
174
+ * переразвёртыванием каталога.
175
+ */
176
+ 'plugin.managed_readonly',
177
+ /**
178
+ * Ф7 (2026-10-23): серверная политика гибридного режима запрещает плагину
179
+ * работать — режим `plugins.hybrid.mode='allowlist'`, а плагина нет в
180
+ * `plugins.hybrid.allow`. Локальный core в гибриде сверяется с политикой
181
+ * сервера **перед активацией** и отклоняет активацию (Уровень 1 —
182
+ * cooperative: сервер известен и запретил).
183
+ */
184
+ 'plugin.hybrid_not_allowed',
185
+ ];
@@ -0,0 +1,85 @@
1
+ /**
2
+ * ADR-090 Ф7: гибридная политика плагинов — контракт серверной стороны.
3
+ *
4
+ * Три уровня силы (ADR-090):
5
+ * - **Уровень 1 — cooperative** (красный): allow-list сервера как политика
6
+ * соответствия. Локальный core сверяется с политикой сервера перед
7
+ * активацией плагина; сервер недоступен или политика неизвестна — плагин
8
+ * работает, но помечен «не проверен сервером»;
9
+ * - **Уровень 2 — server-scoped токены** (зелёный): плагин получает доступ к
10
+ * серверу только с токеном, привязанным к его `plugin_id`; сервер применяет
11
+ * политику и отвергает чужую привязку;
12
+ * - **Уровень 3 — attestation** — вне объёма.
13
+ *
14
+ * Модуль browser-safe: только типы и чистые функции (его читает и UI).
15
+ */
16
+ /**
17
+ * Режим серверной политики плагинов:
18
+ * - `off` — сервер **не ограничивает** плагины (политика соответствия не
19
+ * применяется, allow-list не запрашивается);
20
+ * - `allowlist` — сервер ограничивает: разрешены только плагины из списка
21
+ * `allow` (пустой список — не разрешён никто).
22
+ */
23
+ export declare const PLUGIN_HYBRID_MODES: readonly ["off", "allowlist"];
24
+ export type PluginHybridMode = (typeof PLUGIN_HYBRID_MODES)[number];
25
+ /**
26
+ * Сигнал о слое плагинов в **публичном** дискавери (`GET /auth/oidc-meta`).
27
+ *
28
+ * Список имён в сигнале **не публичен** — он живёт в аутентифицированном
29
+ * роуте `GET /api/v2/settings/plugins` (блок `hybrid`). Старые серверы без
30
+ * поля → клиент трактует состояние как «неизвестно».
31
+ */
32
+ export interface PluginPolicySignal {
33
+ /** Включён ли слой плагинов на сервере (`plugins.enabled`). */
34
+ enabled: boolean;
35
+ /** Режим серверной политики. */
36
+ mode: PluginHybridMode;
37
+ }
38
+ /**
39
+ * Эффективная серверная политика плагинов (allow-list).
40
+ *
41
+ * `allow` наполнен только при `mode: 'allowlist'` — в режиме `off` список не
42
+ * имеет силы и наружу не отдаётся.
43
+ */
44
+ export interface PluginServerPolicy {
45
+ /** Режим политики. */
46
+ mode: PluginHybridMode;
47
+ /** Имена плагинов, которым сервер разрешает работать. */
48
+ allow: string[];
49
+ }
50
+ /**
51
+ * Статус проверки плагина сервером:
52
+ * - `allowed` — сервер подтвердил (политика `off` или плагин в allow-list);
53
+ * - `denied` — сервер запретил (плагина нет в allow-list при `allowlist`);
54
+ * - `unverified` — сервер недоступен или политика неизвестна (cooperative).
55
+ */
56
+ export type PluginServerPolicyStatus = 'unverified' | 'allowed' | 'denied';
57
+ /**
58
+ * Заголовок, которым плагин объявляет свою привязку (`plugin_id`) при обращении
59
+ * к серверу с server-scoped токеном (Уровень 2).
60
+ */
61
+ export declare const PLUGIN_ID_HEADER = "X-Synth-Plugin-Id";
62
+ /**
63
+ * Scope service-key для server-scoped токена плагина (Уровень 2): без него
64
+ * сервер отвергает plugin-bound ключ (fail-closed).
65
+ */
66
+ export declare const PLUGIN_INVOKE_SCOPE = "plugins:invoke";
67
+ /**
68
+ * Статус плагина по серверной политике.
69
+ *
70
+ * `policy` не задана (сервера нет / политика неизвестна) → `unverified`:
71
+ * локальный плагин работает (cooperative), но помечается в UI и API.
72
+ */
73
+ export declare function evaluatePluginServerPolicy(policy: PluginServerPolicy | undefined | null, pluginName: string): PluginServerPolicyStatus;
74
+ /**
75
+ * `true`, если серверная политика разрешает плагину работать.
76
+ *
77
+ * Политика неизвестна → `true` (cooperative: сервер не подтвердил, но и не
78
+ * запретил — решение остаётся за владельцем локального инстанса).
79
+ */
80
+ export declare function isPluginAllowedByServerPolicy(policy: PluginServerPolicy | undefined | null, pluginName: string): boolean;
81
+ /**
82
+ * Нормализация сигнала дискавери (сервер может прислать что угодно):
83
+ * неизвестный режим → `undefined` (политика неизвестна → cooperative).
84
+ */
85
+ export declare function parsePluginPolicySignal(raw: unknown): PluginPolicySignal | undefined;
@@ -0,0 +1,68 @@
1
+ /**
2
+ * ADR-090 Ф7: гибридная политика плагинов — контракт серверной стороны.
3
+ *
4
+ * Три уровня силы (ADR-090):
5
+ * - **Уровень 1 — cooperative** (красный): allow-list сервера как политика
6
+ * соответствия. Локальный core сверяется с политикой сервера перед
7
+ * активацией плагина; сервер недоступен или политика неизвестна — плагин
8
+ * работает, но помечен «не проверен сервером»;
9
+ * - **Уровень 2 — server-scoped токены** (зелёный): плагин получает доступ к
10
+ * серверу только с токеном, привязанным к его `plugin_id`; сервер применяет
11
+ * политику и отвергает чужую привязку;
12
+ * - **Уровень 3 — attestation** — вне объёма.
13
+ *
14
+ * Модуль browser-safe: только типы и чистые функции (его читает и UI).
15
+ */
16
+ /**
17
+ * Режим серверной политики плагинов:
18
+ * - `off` — сервер **не ограничивает** плагины (политика соответствия не
19
+ * применяется, allow-list не запрашивается);
20
+ * - `allowlist` — сервер ограничивает: разрешены только плагины из списка
21
+ * `allow` (пустой список — не разрешён никто).
22
+ */
23
+ export const PLUGIN_HYBRID_MODES = ['off', 'allowlist'];
24
+ /**
25
+ * Заголовок, которым плагин объявляет свою привязку (`plugin_id`) при обращении
26
+ * к серверу с server-scoped токеном (Уровень 2).
27
+ */
28
+ export const PLUGIN_ID_HEADER = 'X-Synth-Plugin-Id';
29
+ /**
30
+ * Scope service-key для server-scoped токена плагина (Уровень 2): без него
31
+ * сервер отвергает plugin-bound ключ (fail-closed).
32
+ */
33
+ export const PLUGIN_INVOKE_SCOPE = 'plugins:invoke';
34
+ /**
35
+ * Статус плагина по серверной политике.
36
+ *
37
+ * `policy` не задана (сервера нет / политика неизвестна) → `unverified`:
38
+ * локальный плагин работает (cooperative), но помечается в UI и API.
39
+ */
40
+ export function evaluatePluginServerPolicy(policy, pluginName) {
41
+ if (!policy)
42
+ return 'unverified';
43
+ if (policy.mode === 'off')
44
+ return 'allowed';
45
+ return policy.allow.includes(pluginName) ? 'allowed' : 'denied';
46
+ }
47
+ /**
48
+ * `true`, если серверная политика разрешает плагину работать.
49
+ *
50
+ * Политика неизвестна → `true` (cooperative: сервер не подтвердил, но и не
51
+ * запретил — решение остаётся за владельцем локального инстанса).
52
+ */
53
+ export function isPluginAllowedByServerPolicy(policy, pluginName) {
54
+ return evaluatePluginServerPolicy(policy, pluginName) !== 'denied';
55
+ }
56
+ /**
57
+ * Нормализация сигнала дискавери (сервер может прислать что угодно):
58
+ * неизвестный режим → `undefined` (политика неизвестна → cooperative).
59
+ */
60
+ export function parsePluginPolicySignal(raw) {
61
+ if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
62
+ return undefined;
63
+ const body = raw;
64
+ const mode = body.mode;
65
+ if (mode !== 'off' && mode !== 'allowlist')
66
+ return undefined;
67
+ return { enabled: body.enabled === true, mode };
68
+ }
@@ -0,0 +1,95 @@
1
+ /**
2
+ * PROP-068 §4.4 / ADR-090: запись lock-файла плагинов (`plugins.lock.json`).
3
+ *
4
+ * **Источник истины для update/uninstall** (PROP-068 §4.4). Pin обязателен:
5
+ * `ref` (sha/тег) + `content_hash`; автоматического «взять latest» нет —
6
+ * update только явной операцией.
7
+ *
8
+ * **Откат.** Update сохраняет предыдущую версию рядом (`previous`), а
9
+ * `rollback` меняет местами текущую и предыдущую — ровно одна ступень, явная
10
+ * операция (ADR-090).
11
+ *
12
+ * Имена полей — snake_case (как в модели `lock.json` из PROP-068 §4.4).
13
+ */
14
+ import type { PluginScanVerdict } from './plugin-audit.js';
15
+ import type { PackPluginMode } from './pack.js';
16
+ import type { CatalogTrustLevel } from './trust.js';
17
+ /**
18
+ * Предыдущая установленная версия плагина — **одна ступень** для отката
19
+ * (`PluginInstaller.rollback`, ADR-090).
20
+ *
21
+ * Хранится только то, что нужно для отката: версия, content-hash, точка входа
22
+ * и время установки. Источник/pin/доверие/вердикт скана — свойства плагина, а
23
+ * не версии: они остаются в основной записи lock.
24
+ *
25
+ * **Откат — явная операция** (как и обновление): автоматического «предыдущая
26
+ * версия подхватится сама» нет. Ступень ровно одна: следующее обновление
27
+ * перезаписывает `previous`, поэтому «откат на две версии назад» — это два
28
+ * последовательных `rollback`.
29
+ */
30
+ export interface PluginLockPrevious {
31
+ /** Версия, с которой был выполнен переход. */
32
+ version: string;
33
+ /** Content-hash этой версии (sha256 от отсортированного набора файлов). */
34
+ content_hash: string;
35
+ /** Точка входа бандла этой версии (например `dist/index.js`). */
36
+ entry?: string;
37
+ /** ISO-время установки этой версии. */
38
+ installed_at: string;
39
+ }
40
+ /** Запись lock-файла плагинов. */
41
+ export interface PluginLockEntry {
42
+ /** Имя плагина (из манифеста `synth.pack`). */
43
+ name: string;
44
+ /** Версия плагина (semver). */
45
+ version: string;
46
+ /** Источник установки (`npm`/`local`/`catalog`/`builtin`/…). */
47
+ source: string;
48
+ /** Идентификатор источника (`owner/repo`, URL, npm-пакет…). */
49
+ identifier?: string;
50
+ /** Фактический уровень доверия (резолвится по источнику, не по манифесту). */
51
+ trust_level: CatalogTrustLevel;
52
+ /** Вердикт последнего скана. */
53
+ scan_verdict: PluginScanVerdict;
54
+ /** Content-hash бандла (sha256 от отсортированного набора файлов). */
55
+ content_hash: string;
56
+ /** Pin: sha/тег источника. */
57
+ ref?: string;
58
+ /** Точка входа бандла (например `dist/index.js`). */
59
+ entry?: string;
60
+ /**
61
+ * Ф4б-2: режим исполнения из манифеста (`inline`/`remote`/`both`).
62
+ *
63
+ * Записывается установкой (эффективный режим: `mode` манифеста, иначе
64
+ * `inline`). Активация выбирает транспорт по этому полю, а не перечитывая
65
+ * манифест; у legacy-записей поле отсутствует — трактуется как `inline`.
66
+ */
67
+ mode?: PackPluginMode;
68
+ /**
69
+ * Ф4б-2: серверная точка входа удалённого плагина (`dist/server.js`).
70
+ *
71
+ * Пишется, если режим `remote`/`both` и файл есть в бандле. Именно её
72
+ * запускает `PluginProcessManager`; в дескриптор активации попадает как
73
+ * `remoteEntry`.
74
+ */
75
+ remote_entry?: string;
76
+ /** ISO-время установки. */
77
+ installed_at: string;
78
+ /** ISO-время последней записи. */
79
+ updated_at: string;
80
+ /**
81
+ * Предыдущая установленная версия (одна ступень — для `rollback`).
82
+ *
83
+ * Заполняется `PluginInstaller.update` (и переставляется `rollback` —
84
+ * текущая версия становится предыдущей). У записи, поставленной обычной
85
+ * установкой, поля нет.
86
+ */
87
+ previous?: PluginLockPrevious;
88
+ }
89
+ /** Формат файла `plugins.lock.json` (общий формат JSON-коллекций слоя хранения). */
90
+ export interface PluginLockFile {
91
+ /** Версия схемы файла (на будущее — миграции хранилища, ADR-092). */
92
+ schemaVersion: number;
93
+ /** Записи установленных плагинов. */
94
+ plugins: PluginLockEntry[];
95
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,221 @@
1
+ import type { LlmFilterFailMode, LlmFilterPhase } from './llm-filters.js';
2
+ import type { PromptManifestStatus } from './prompt.js';
3
+ import type { ToolCapability as ToolCapabilityValue } from './tools.js';
4
+ /** Версия wire-протокола плагина (аналог `EXECUTOR_PROTOCOL_VERSION`). */
5
+ export declare const PLUGIN_PROTOCOL_VERSION = 1;
6
+ /** Пути эндпоинтов протокола (относительно базового адреса процесса). */
7
+ export declare const PLUGIN_PROTOCOL_PATHS: {
8
+ /** `POST` — вызов точки расширения. */
9
+ readonly invoke: "/invoke";
10
+ /** `GET` — список поддерживаемых точек + версия протокола. */
11
+ readonly capabilities: "/capabilities";
12
+ /** `GET` — процесс жив (без токена). */
13
+ readonly health: "/health";
14
+ };
15
+ /**
16
+ * Строка готовности, которую сервер плагина печатает в **stdout** при старте
17
+ * (Ф4б-2). Хост читает stdout процесса до этой строки и берёт из неё порт.
18
+ *
19
+ * Формат: `SYNTH_PLUGIN_READY port=<n>` (разбор — {@link parsePluginServerReadyLine}).
20
+ * Только stdout: диагностика процесса идёт в stderr и на разбор не влияет.
21
+ */
22
+ export declare const PLUGIN_SERVER_READY_LINE = "SYNTH_PLUGIN_READY";
23
+ /** Опции, с которыми хост запускает сервер плагина (`dist/server.js`). */
24
+ export interface PluginServerOptions {
25
+ /** Порт, который должен занять сервер (0 — выбрать свободный и сообщить). */
26
+ port: number;
27
+ /** Bearer-токен, который сервер обязан проверять на `/capabilities` и `/invoke`. */
28
+ token: string;
29
+ }
30
+ /** Дескриптор запущенного сервера плагина (возвращает фабрика `dist/server.js`). */
31
+ export interface PluginServerHandle {
32
+ /** Остановить сервер. */
33
+ close(): void | Promise<void>;
34
+ /** Порт, на котором сервер слушает (после `listen`). */
35
+ readonly port?: number;
36
+ }
37
+ /**
38
+ * Фабрика сервера плагина: `dist/server.js` экспортирует её (или `default`).
39
+ *
40
+ * Хост вызывает фабрику с {@link PluginServerOptions}, сервер занимает порт,
41
+ * печатает {@link PLUGIN_SERVER_READY_LINE} и обслуживает `/health`,
42
+ * `/capabilities`, `/invoke`. Процесс завершается сигналом (`SIGTERM`), поэтому
43
+ * `close()` нужен для аккуратной остановки в тестах и при явном shutdown.
44
+ */
45
+ export type PluginServerFactory = (options: PluginServerOptions) => PluginServerHandle | Promise<PluginServerHandle>;
46
+ /**
47
+ * Разобрать строку готовности процесса плагина.
48
+ *
49
+ * **Строгая проверка** (fail-closed): принимается ровно
50
+ * `SYNTH_PLUGIN_READY port=<целое 1..65535>` (окружающие пробелы и `\r`
51
+ * допускаются — stdout приходит с `\n`/`\r\n`). Мусор, чужие поля, порт `0`,
52
+ * отрицательный или вне диапазона — `null` (хост считает, что готовности не
53
+ * было).
54
+ *
55
+ * @param line одна строка stdout (без завершающего перевода строки)
56
+ */
57
+ export declare function parsePluginServerReadyLine(line: string): {
58
+ port: number;
59
+ } | null;
60
+ /**
61
+ * Точки, передаваемые по протоколу.
62
+ *
63
+ * `promptBlocks` (блок системного промпта), `llmFilters` (фильтр LLM-вызовов)
64
+ * и `tools` (инструмент плагина, Ф4б-3). Плагин, объявивший в манифесте
65
+ * `provides.tools`, обязан объявить те же **локальные** имена в
66
+ * `points.tools[]` — иначе сверка `provides` отклонит активацию
67
+ * (`plugin.provides_mismatch`).
68
+ */
69
+ export declare const PLUGIN_PROTOCOL_POINTS: readonly ["promptBlocks", "llmFilters", "tools"];
70
+ export type PluginProtocolPoint = (typeof PLUGIN_PROTOCOL_POINTS)[number];
71
+ /** Описание плагинного блока промпта в `/capabilities`. */
72
+ export interface PluginCapabilitiesPromptBlock {
73
+ /** Ключ блока (`plugin.<pluginName>.<slot>`). */
74
+ key: string;
75
+ /** Тир блока: `stable` запрещён (граница prompt-cache, ADR-070). */
76
+ tier: 'context' | 'volatile';
77
+ /** Порядок внутри тира. */
78
+ order: number;
79
+ /** Подпись блока для манифеста промпта. */
80
+ title?: string;
81
+ }
82
+ /** Описание фильтра LLM-вызовов в `/capabilities`. */
83
+ export interface PluginCapabilitiesLlmFilter {
84
+ /** Идентификатор фильтра (`plugin:<pluginName>:<filterName>`). */
85
+ id: string;
86
+ /** Фаза вызова фильтра. */
87
+ phase: LlmFilterPhase;
88
+ /** Поведение при сбое/таймауте (не задано — по классу фильтра). */
89
+ failMode?: LlmFilterFailMode;
90
+ /** Бюджет времени на вызов фильтра, мс. */
91
+ timeoutMs?: number;
92
+ }
93
+ /**
94
+ * Описание инструмента плагина в `/capabilities` (точка `tools`, Ф4б-3).
95
+ *
96
+ * `name` — **локальное** имя (без namespace): полное имя `plugin_<ns>_<tool>`
97
+ * составляет хост, поэтому по проводу идёт то же имя, что в
98
+ * `provides.tools[]` манифеста.
99
+ */
100
+ export interface PluginCapabilitiesTool {
101
+ /** Локальное имя инструмента (`[A-Za-z0-9_-]`, без префикса `plugin_`). */
102
+ name: string;
103
+ /** Описание для модели (непустое). */
104
+ description: string;
105
+ /**
106
+ * JSON-Schema параметров (для модели). Не задана — хост подставит
107
+ * минимальную `{type:'object', properties:{}, additionalProperties:true}` и
108
+ * **не** будет выдумывать схему.
109
+ */
110
+ parameters?: Record<string, unknown>;
111
+ /**
112
+ * Capabilities инструмента — **обязательны** и непусты: без них тул был бы
113
+ * невидим permission-слою (группа `plugin`, ADR-029) и admin-отключению.
114
+ * Значения — из известного набора `ToolCapability`; `mcp` и `runtime`
115
+ * зарезервированы и отклоняются реестром хоста.
116
+ */
117
+ capabilities: ToolCapabilityValue[];
118
+ }
119
+ /** Ответ `GET /capabilities`: версия протокола + поддерживаемые точки. */
120
+ export interface PluginCapabilities {
121
+ /** Версия wire-протокола (`PLUGIN_PROTOCOL_VERSION`). */
122
+ protocol: number;
123
+ /** Имя плагина (сверяется с ожидаемым — процесс обязан быть тем же плагином). */
124
+ name: string;
125
+ /** Версия плагина (сверяется с ожидаемой). */
126
+ version: string;
127
+ /** Поддерживаемые точки расширения. */
128
+ points: {
129
+ promptBlocks?: PluginCapabilitiesPromptBlock[];
130
+ llmFilters?: PluginCapabilitiesLlmFilter[];
131
+ tools?: PluginCapabilitiesTool[];
132
+ };
133
+ }
134
+ /** Тело запроса `POST /invoke`. */
135
+ export interface PluginInvokeRequest {
136
+ /** Версия wire-протокола. */
137
+ protocol: number;
138
+ /** Точка расширения. */
139
+ point: PluginProtocolPoint;
140
+ /**
141
+ * `promptBlocks` — ключ блока; `llmFilters` — id фильтра; `tools` —
142
+ * **локальное** имя инструмента (без namespace).
143
+ */
144
+ id: string;
145
+ /**
146
+ * Вход точки: `PromptBlockContext` | `LlmFilterInput` |
147
+ * `{ parameters, context }` для `tools` (валидирует плагин).
148
+ */
149
+ input: unknown;
150
+ }
151
+ /**
152
+ * Тело успешного ответа `POST /invoke`.
153
+ *
154
+ * `output` — `PromptBlockContent` (или строка) для `promptBlocks`,
155
+ * `LlmFilterVerdict` для `llmFilters`, `{ content: string; isError?: boolean }`
156
+ * для `tools` (как у MCP-инструментов).
157
+ */
158
+ export type PluginInvokeResponse = {
159
+ ok: true;
160
+ output: unknown;
161
+ } | {
162
+ ok: false;
163
+ error: PluginProtocolError;
164
+ };
165
+ /** Ошибка протокола в теле ответа (`{ error: { reason, code?, message? } }`). */
166
+ export interface PluginProtocolError {
167
+ /** Машиночитаемая причина. */
168
+ reason: PluginProtocolErrorReason;
169
+ /** Код плагина (свободная строка, в журнал не пишется). */
170
+ code?: string;
171
+ /** Человекочитаемое сообщение (без секретов). */
172
+ message?: string;
173
+ }
174
+ /** Причины отказа протокола. */
175
+ export declare const PLUGIN_PROTOCOL_ERROR_REASONS: readonly ["invalid_request", "unknown_point", "unknown_id", "unauthorized", "timeout", "internal_error", "protocol_mismatch"];
176
+ export type PluginProtocolErrorReason = (typeof PLUGIN_PROTOCOL_ERROR_REASONS)[number];
177
+ /**
178
+ * HTTP-код ответа по причине отказа (как в исполнителе, ADR-077).
179
+ *
180
+ * - `400` — некорректный запрос, неизвестная точка/версия протокола;
181
+ * - `401` — нет/неверный токен;
182
+ * - `404` — неизвестный блок/фильтр;
183
+ * - `500` — таймаут и прочие ошибки процесса.
184
+ */
185
+ export declare const PLUGIN_PROTOCOL_ERROR_STATUS: Record<PluginProtocolErrorReason, number>;
186
+ /** Значение — известная причина отказа протокола. */
187
+ export declare function isPluginProtocolErrorReason(value: unknown): value is PluginProtocolErrorReason;
188
+ /** Значение — известная точка протокола. */
189
+ export declare function isPluginProtocolPoint(value: unknown): value is PluginProtocolPoint;
190
+ /** Предел символов содержимого блока в ответе (защита от «случайного» мегабайта). */
191
+ export declare const PLUGIN_PROTOCOL_MAX_PROMPT_BLOCK_CHARS: number;
192
+ /** Итог проверки ответа `/capabilities`. */
193
+ export type PluginCapabilitiesCheck = {
194
+ ok: true;
195
+ capabilities: PluginCapabilities;
196
+ } | {
197
+ ok: false;
198
+ reason: PluginProtocolErrorReason;
199
+ message: string;
200
+ };
201
+ /**
202
+ * Проверить ответ `GET /capabilities`.
203
+ *
204
+ * **Fail-closed:** мусор в ответе, чужая версия протокола и чужой плагин
205
+ * (имя/версия) — отказ. Успех возвращает **нормализованный** снимок: только
206
+ * известные поля, проверенные типы, без дублей ключей/идентификаторов.
207
+ *
208
+ * Точки: `promptBlocks` (тир `stable` запрещён, дубли ключей), `llmFilters`
209
+ * (фаза/`failMode`/`timeoutMs`, дубли id) и `tools` (Ф4б-3: непустые
210
+ * `name`/`description`, `capabilities` непусты и из набора `ToolCapability`,
211
+ * дубли локальных имён).
212
+ *
213
+ * @param payload — распарсенное тело ответа (неизвестной формы).
214
+ * @param expected — ожидаемые имя и версия плагина.
215
+ */
216
+ export declare function checkPluginCapabilities(payload: unknown, expected: {
217
+ name: string;
218
+ version: string;
219
+ }): PluginCapabilitiesCheck;
220
+ /** Ответ `promptBlocks` — допустимый статус манифеста (экспорт для загрузчика core). */
221
+ export declare function isPluginPromptBlockStatus(value: unknown): value is PromptManifestStatus;