@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.
- package/dist/config/defaults.js +126 -3
- package/dist/config/env-overrides.d.ts +29 -0
- package/dist/config/env-overrides.js +155 -2
- package/dist/config/execution.d.ts +66 -0
- package/dist/config/execution.js +146 -0
- package/dist/config/index.d.ts +1 -0
- package/dist/config/index.js +1 -0
- package/dist/config/proxy.js +3 -1
- package/dist/config/resolve.d.ts +8 -8
- package/dist/config/resolve.js +7 -7
- package/dist/config/types.d.ts +1287 -4037
- package/dist/config/types.js +461 -68
- package/dist/i18n/index.d.ts +1 -1
- package/dist/i18n/index.js +277 -0
- package/dist/index.d.ts +14 -2
- package/dist/index.js +16 -2
- package/dist/model-metadata.d.ts +10 -0
- package/dist/schemas/index.d.ts +980 -2322
- package/dist/schemas/index.js +183 -22
- package/dist/types/analytics.d.ts +6 -6
- package/dist/types/analytics.js +4 -4
- package/dist/types/authority.d.ts +464 -0
- package/dist/types/authority.js +445 -0
- package/dist/types/background.d.ts +96 -0
- package/dist/types/background.js +24 -0
- package/dist/types/bus-events.d.ts +23 -1
- package/dist/types/catalog.d.ts +349 -0
- package/dist/types/catalog.js +393 -0
- package/dist/types/decision.d.ts +28 -337
- package/dist/types/egress.d.ts +1 -1
- package/dist/types/egress.js +1 -1
- package/dist/types/events.d.ts +54 -1
- package/dist/types/external-credentials.d.ts +352 -0
- package/dist/types/external-credentials.js +200 -0
- package/dist/types/hooks.d.ts +33 -12
- package/dist/types/index.d.ts +20 -0
- package/dist/types/index.js +50 -1
- package/dist/types/llm-filters.d.ts +150 -0
- package/dist/types/llm-filters.js +54 -0
- package/dist/types/mcp.d.ts +33 -2
- package/dist/types/mcp.js +44 -1
- package/dist/types/message.d.ts +45 -1
- package/dist/types/pack.d.ts +1102 -0
- package/dist/types/pack.js +1003 -0
- package/dist/types/permission.d.ts +25 -11
- package/dist/types/permission.js +1 -1
- package/dist/types/pipeline-engine.d.ts +453 -0
- package/dist/types/pipeline-engine.js +440 -0
- package/dist/types/pipeline.d.ts +275 -0
- package/dist/types/pipeline.js +212 -0
- package/dist/types/plugin-audit.d.ts +110 -0
- package/dist/types/plugin-audit.js +185 -0
- package/dist/types/plugin-hybrid.d.ts +85 -0
- package/dist/types/plugin-hybrid.js +68 -0
- package/dist/types/plugin-lock.d.ts +95 -0
- package/dist/types/plugin-lock.js +1 -0
- package/dist/types/plugin-protocol.d.ts +221 -0
- package/dist/types/plugin-protocol.js +322 -0
- package/dist/types/plugin-runtime.d.ts +25 -0
- package/dist/types/plugin-runtime.js +11 -0
- package/dist/types/plugin-scan.d.ts +159 -0
- package/dist/types/plugin-scan.js +166 -0
- package/dist/types/plugin-tools.d.ts +51 -0
- package/dist/types/plugin-tools.js +72 -0
- package/dist/types/project.d.ts +14 -0
- package/dist/types/prompt-blocks.d.ts +102 -0
- package/dist/types/prompt-blocks.js +24 -0
- package/dist/types/prompt.d.ts +45 -3
- package/dist/types/provider.d.ts +11 -0
- package/dist/types/question.d.ts +153 -0
- package/dist/types/question.js +65 -0
- package/dist/types/schedules.d.ts +26 -3
- package/dist/types/semver.d.ts +48 -0
- package/dist/types/semver.js +218 -0
- package/dist/types/service-keys.d.ts +41 -3
- package/dist/types/service-keys.js +44 -2
- package/dist/types/session.d.ts +54 -0
- package/dist/types/steering.d.ts +74 -0
- package/dist/types/steering.js +75 -0
- package/dist/types/tools.d.ts +125 -5
- package/dist/types/tools.js +75 -0
- package/dist/types/trust.d.ts +31 -0
- package/dist/types/trust.js +27 -0
- package/dist/types/worktree.d.ts +170 -0
- package/dist/types/worktree.js +101 -0
- package/dist/utils/index.d.ts +31 -1
- package/dist/utils/index.js +92 -12
- package/dist/utils/reasoning.d.ts +16 -0
- package/dist/utils/reasoning.js +37 -0
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/package.json +2 -2
|
@@ -0,0 +1,322 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* ADR-090 → «`out-of-process`»: wire-протокол плагина.
|
|
3
|
+
*
|
|
4
|
+
* Транспорт — HTTP/1.1 + JSON по образцу исполнителя
|
|
5
|
+
* (`packages/executor/src/protocol.ts`, ADR-077): `POST /invoke` (вызов точки
|
|
6
|
+
* расширения), `GET /capabilities` (что процесс умеет + версия протокола),
|
|
7
|
+
* `GET /health` (без токена — процесс жив).
|
|
8
|
+
*
|
|
9
|
+
* **Где живёт контракт.** Решение владельца (2026-10-22): контракт протокола —
|
|
10
|
+
* в `@itphx/synth-shared`, отдельный пакет `@itphx/synth-plugin-protocol`
|
|
11
|
+
* **не создаётся**. Модуль browser-safe: только типы, константы и чистые
|
|
12
|
+
* функции (без `node:*` и без `zod`).
|
|
13
|
+
*
|
|
14
|
+
* **Что пересекает границу.** Только сериализуемые DTO: вход/выход точек
|
|
15
|
+
* `promptBlocks` (`PromptBlockContext` → `PromptBlockContent`), `llmFilters`
|
|
16
|
+
* (`LlmFilterInput` → `LlmFilterVerdict`) и `tools`
|
|
17
|
+
* (`{ parameters, context }` → `{ content, isError? }`, как у MCP-инструментов).
|
|
18
|
+
* Порты хранилища, реестры ядра и `GatewayProvider` наружу не отдаются
|
|
19
|
+
* (ADR-090).
|
|
20
|
+
*
|
|
21
|
+
* **Точка `tools` (Ф4б-3).** Процесс объявляет инструменты в
|
|
22
|
+
* `points.tools[]` (`PluginCapabilitiesTool`: локальное имя, описание,
|
|
23
|
+
* JSON-Schema параметров и **обязательные** capabilities — без них тул невидим
|
|
24
|
+
* permission-слою и admin-отключению); вызов — `POST /invoke` с
|
|
25
|
+
* `id = <локальное имя>`. Namespace `plugin_<ns>_<tool>` составляет **хост**:
|
|
26
|
+
* по проводу идёт локальное имя, как в `provides.tools[]` манифеста.
|
|
27
|
+
*
|
|
28
|
+
* **Серверная сторона (Ф4б-2).** Контракт точки входа сервера
|
|
29
|
+
* (`PluginServerOptions`/`PluginServerHandle`/`PluginServerFactory`), строка
|
|
30
|
+
* готовности `PLUGIN_SERVER_READY_LINE` и её разбор
|
|
31
|
+
* (`parsePluginServerReadyLine`) живут здесь же: плагин и хост обязаны
|
|
32
|
+
* понимать формат одинаково, отдельный пакет не нужен.
|
|
33
|
+
*/
|
|
34
|
+
import { isLlmFilterFailMode, isLlmFilterPhase } from './llm-filters.js';
|
|
35
|
+
import { ToolCapability } from './tools.js';
|
|
36
|
+
/** Версия wire-протокола плагина (аналог `EXECUTOR_PROTOCOL_VERSION`). */
|
|
37
|
+
export const PLUGIN_PROTOCOL_VERSION = 1;
|
|
38
|
+
/** Пути эндпоинтов протокола (относительно базового адреса процесса). */
|
|
39
|
+
export const PLUGIN_PROTOCOL_PATHS = {
|
|
40
|
+
/** `POST` — вызов точки расширения. */
|
|
41
|
+
invoke: '/invoke',
|
|
42
|
+
/** `GET` — список поддерживаемых точек + версия протокола. */
|
|
43
|
+
capabilities: '/capabilities',
|
|
44
|
+
/** `GET` — процесс жив (без токена). */
|
|
45
|
+
health: '/health',
|
|
46
|
+
};
|
|
47
|
+
/**
|
|
48
|
+
* Строка готовности, которую сервер плагина печатает в **stdout** при старте
|
|
49
|
+
* (Ф4б-2). Хост читает stdout процесса до этой строки и берёт из неё порт.
|
|
50
|
+
*
|
|
51
|
+
* Формат: `SYNTH_PLUGIN_READY port=<n>` (разбор — {@link parsePluginServerReadyLine}).
|
|
52
|
+
* Только stdout: диагностика процесса идёт в stderr и на разбор не влияет.
|
|
53
|
+
*/
|
|
54
|
+
export const PLUGIN_SERVER_READY_LINE = 'SYNTH_PLUGIN_READY';
|
|
55
|
+
/**
|
|
56
|
+
* Разобрать строку готовности процесса плагина.
|
|
57
|
+
*
|
|
58
|
+
* **Строгая проверка** (fail-closed): принимается ровно
|
|
59
|
+
* `SYNTH_PLUGIN_READY port=<целое 1..65535>` (окружающие пробелы и `\r`
|
|
60
|
+
* допускаются — stdout приходит с `\n`/`\r\n`). Мусор, чужие поля, порт `0`,
|
|
61
|
+
* отрицательный или вне диапазона — `null` (хост считает, что готовности не
|
|
62
|
+
* было).
|
|
63
|
+
*
|
|
64
|
+
* @param line одна строка stdout (без завершающего перевода строки)
|
|
65
|
+
*/
|
|
66
|
+
export function parsePluginServerReadyLine(line) {
|
|
67
|
+
if (typeof line !== 'string')
|
|
68
|
+
return null;
|
|
69
|
+
const trimmed = line.replace(/\r$/, '').trim();
|
|
70
|
+
const match = /^SYNTH_PLUGIN_READY port=(\d{1,5})$/.exec(trimmed);
|
|
71
|
+
if (!match)
|
|
72
|
+
return null;
|
|
73
|
+
const port = Number(match[1]);
|
|
74
|
+
if (!Number.isInteger(port) || port < 1 || port > 65535)
|
|
75
|
+
return null;
|
|
76
|
+
return { port };
|
|
77
|
+
}
|
|
78
|
+
/**
|
|
79
|
+
* Точки, передаваемые по протоколу.
|
|
80
|
+
*
|
|
81
|
+
* `promptBlocks` (блок системного промпта), `llmFilters` (фильтр LLM-вызовов)
|
|
82
|
+
* и `tools` (инструмент плагина, Ф4б-3). Плагин, объявивший в манифесте
|
|
83
|
+
* `provides.tools`, обязан объявить те же **локальные** имена в
|
|
84
|
+
* `points.tools[]` — иначе сверка `provides` отклонит активацию
|
|
85
|
+
* (`plugin.provides_mismatch`).
|
|
86
|
+
*/
|
|
87
|
+
export const PLUGIN_PROTOCOL_POINTS = ['promptBlocks', 'llmFilters', 'tools'];
|
|
88
|
+
/** Причины отказа протокола. */
|
|
89
|
+
export const PLUGIN_PROTOCOL_ERROR_REASONS = [
|
|
90
|
+
/** Тело запроса невалидно (не JSON-объект, нет полей, неверные типы). */
|
|
91
|
+
'invalid_request',
|
|
92
|
+
/** Точка расширения не поддерживается процессом. */
|
|
93
|
+
'unknown_point',
|
|
94
|
+
/** Точка поддерживается, но запрошенного блока/фильтра в ней нет. */
|
|
95
|
+
'unknown_id',
|
|
96
|
+
/** Нет или неверный bearer-токен. */
|
|
97
|
+
'unauthorized',
|
|
98
|
+
/** Процесс не ответил в бюджет времени. */
|
|
99
|
+
'timeout',
|
|
100
|
+
/** Прочие ошибки процесса/плагина. */
|
|
101
|
+
'internal_error',
|
|
102
|
+
/** Версия протокола или идентичность плагина (имя/версия) не совпали. */
|
|
103
|
+
'protocol_mismatch',
|
|
104
|
+
];
|
|
105
|
+
/**
|
|
106
|
+
* HTTP-код ответа по причине отказа (как в исполнителе, ADR-077).
|
|
107
|
+
*
|
|
108
|
+
* - `400` — некорректный запрос, неизвестная точка/версия протокола;
|
|
109
|
+
* - `401` — нет/неверный токен;
|
|
110
|
+
* - `404` — неизвестный блок/фильтр;
|
|
111
|
+
* - `500` — таймаут и прочие ошибки процесса.
|
|
112
|
+
*/
|
|
113
|
+
export const PLUGIN_PROTOCOL_ERROR_STATUS = {
|
|
114
|
+
invalid_request: 400,
|
|
115
|
+
unknown_point: 400,
|
|
116
|
+
unknown_id: 404,
|
|
117
|
+
unauthorized: 401,
|
|
118
|
+
timeout: 500,
|
|
119
|
+
internal_error: 500,
|
|
120
|
+
protocol_mismatch: 400,
|
|
121
|
+
};
|
|
122
|
+
/** Значение — известная причина отказа протокола. */
|
|
123
|
+
export function isPluginProtocolErrorReason(value) {
|
|
124
|
+
return PLUGIN_PROTOCOL_ERROR_REASONS.includes(value);
|
|
125
|
+
}
|
|
126
|
+
/** Значение — известная точка протокола. */
|
|
127
|
+
export function isPluginProtocolPoint(value) {
|
|
128
|
+
return PLUGIN_PROTOCOL_POINTS.includes(value);
|
|
129
|
+
}
|
|
130
|
+
/** Статусы блока промпта, допустимые в ответе провайдера (`PromptManifestStatus`). */
|
|
131
|
+
const PROMPT_BLOCK_STATUSES = [
|
|
132
|
+
'loaded',
|
|
133
|
+
'truncated',
|
|
134
|
+
'empty',
|
|
135
|
+
'blocked',
|
|
136
|
+
'suppressed',
|
|
137
|
+
];
|
|
138
|
+
/** Известные capabilities тула (точка `tools`, `ToolCapability`). */
|
|
139
|
+
const KNOWN_TOOL_CAPABILITIES = new Set(Object.values(ToolCapability));
|
|
140
|
+
/** Предел символов содержимого блока в ответе (защита от «случайного» мегабайта). */
|
|
141
|
+
export const PLUGIN_PROTOCOL_MAX_PROMPT_BLOCK_CHARS = 64 * 1024;
|
|
142
|
+
/**
|
|
143
|
+
* Проверить ответ `GET /capabilities`.
|
|
144
|
+
*
|
|
145
|
+
* **Fail-closed:** мусор в ответе, чужая версия протокола и чужой плагин
|
|
146
|
+
* (имя/версия) — отказ. Успех возвращает **нормализованный** снимок: только
|
|
147
|
+
* известные поля, проверенные типы, без дублей ключей/идентификаторов.
|
|
148
|
+
*
|
|
149
|
+
* Точки: `promptBlocks` (тир `stable` запрещён, дубли ключей), `llmFilters`
|
|
150
|
+
* (фаза/`failMode`/`timeoutMs`, дубли id) и `tools` (Ф4б-3: непустые
|
|
151
|
+
* `name`/`description`, `capabilities` непусты и из набора `ToolCapability`,
|
|
152
|
+
* дубли локальных имён).
|
|
153
|
+
*
|
|
154
|
+
* @param payload — распарсенное тело ответа (неизвестной формы).
|
|
155
|
+
* @param expected — ожидаемые имя и версия плагина.
|
|
156
|
+
*/
|
|
157
|
+
export function checkPluginCapabilities(payload, expected) {
|
|
158
|
+
if (!isRecord(payload)) {
|
|
159
|
+
return fail('invalid_request', 'ответ /capabilities — не JSON-объект');
|
|
160
|
+
}
|
|
161
|
+
const protocol = payload.protocol;
|
|
162
|
+
if (typeof protocol !== 'number' || !Number.isFinite(protocol)) {
|
|
163
|
+
return fail('invalid_request', 'в ответе /capabilities нет числового поля protocol');
|
|
164
|
+
}
|
|
165
|
+
if (protocol !== PLUGIN_PROTOCOL_VERSION) {
|
|
166
|
+
return fail('protocol_mismatch', `плагин говорит по протоколу ${protocol}, а Synth — по протоколу ${PLUGIN_PROTOCOL_VERSION}`);
|
|
167
|
+
}
|
|
168
|
+
const name = payload.name;
|
|
169
|
+
const version = payload.version;
|
|
170
|
+
if (!isNonEmptyString(name) || !isNonEmptyString(version)) {
|
|
171
|
+
return fail('invalid_request', 'в ответе /capabilities нет имени/версии плагина');
|
|
172
|
+
}
|
|
173
|
+
if (name !== expected.name || version !== expected.version) {
|
|
174
|
+
return fail('protocol_mismatch', `процесс обслуживает плагин «${name}@${version}», ожидается «${expected.name}@${expected.version}»`);
|
|
175
|
+
}
|
|
176
|
+
const pointsRaw = payload.points;
|
|
177
|
+
if (pointsRaw !== undefined && !isRecord(pointsRaw)) {
|
|
178
|
+
return fail('invalid_request', 'поле points в /capabilities должно быть объектом');
|
|
179
|
+
}
|
|
180
|
+
const points = {};
|
|
181
|
+
if (pointsRaw) {
|
|
182
|
+
for (const key of Object.keys(pointsRaw)) {
|
|
183
|
+
if (!isPluginProtocolPoint(key)) {
|
|
184
|
+
return fail('unknown_point', `процесс объявил неизвестную точку «${key}»`);
|
|
185
|
+
}
|
|
186
|
+
}
|
|
187
|
+
if (pointsRaw.promptBlocks !== undefined) {
|
|
188
|
+
if (!Array.isArray(pointsRaw.promptBlocks)) {
|
|
189
|
+
return fail('invalid_request', 'points.promptBlocks должен быть массивом');
|
|
190
|
+
}
|
|
191
|
+
const blocks = [];
|
|
192
|
+
const seen = new Set();
|
|
193
|
+
for (const [index, raw] of pointsRaw.promptBlocks.entries()) {
|
|
194
|
+
if (!isRecord(raw)) {
|
|
195
|
+
return fail('invalid_request', `points.promptBlocks[${index}] — не объект`);
|
|
196
|
+
}
|
|
197
|
+
const blockKey = raw.key;
|
|
198
|
+
if (!isNonEmptyString(blockKey)) {
|
|
199
|
+
return fail('invalid_request', `points.promptBlocks[${index}].key обязателен`);
|
|
200
|
+
}
|
|
201
|
+
if (seen.has(blockKey)) {
|
|
202
|
+
return fail('invalid_request', `points.promptBlocks: ключ «${blockKey}» объявлен дважды`);
|
|
203
|
+
}
|
|
204
|
+
if (raw.tier !== 'context' && raw.tier !== 'volatile') {
|
|
205
|
+
return fail('invalid_request', `points.promptBlocks[${index}].tier: допустимы только context|volatile ` +
|
|
206
|
+
`(тир stable запрещён — граница prompt-cache, ADR-070)`);
|
|
207
|
+
}
|
|
208
|
+
if (typeof raw.order !== 'number' || !Number.isFinite(raw.order)) {
|
|
209
|
+
return fail('invalid_request', `points.promptBlocks[${index}].order должен быть числом`);
|
|
210
|
+
}
|
|
211
|
+
if (raw.title !== undefined && typeof raw.title !== 'string') {
|
|
212
|
+
return fail('invalid_request', `points.promptBlocks[${index}].title должен быть строкой`);
|
|
213
|
+
}
|
|
214
|
+
seen.add(blockKey);
|
|
215
|
+
blocks.push({
|
|
216
|
+
key: blockKey,
|
|
217
|
+
tier: raw.tier,
|
|
218
|
+
order: raw.order,
|
|
219
|
+
...(raw.title ? { title: raw.title } : {}),
|
|
220
|
+
});
|
|
221
|
+
}
|
|
222
|
+
points.promptBlocks = blocks;
|
|
223
|
+
}
|
|
224
|
+
if (pointsRaw.llmFilters !== undefined) {
|
|
225
|
+
if (!Array.isArray(pointsRaw.llmFilters)) {
|
|
226
|
+
return fail('invalid_request', 'points.llmFilters должен быть массивом');
|
|
227
|
+
}
|
|
228
|
+
const filters = [];
|
|
229
|
+
const seen = new Set();
|
|
230
|
+
for (const [index, raw] of pointsRaw.llmFilters.entries()) {
|
|
231
|
+
if (!isRecord(raw)) {
|
|
232
|
+
return fail('invalid_request', `points.llmFilters[${index}] — не объект`);
|
|
233
|
+
}
|
|
234
|
+
const id = raw.id;
|
|
235
|
+
if (!isNonEmptyString(id)) {
|
|
236
|
+
return fail('invalid_request', `points.llmFilters[${index}].id обязателен`);
|
|
237
|
+
}
|
|
238
|
+
if (seen.has(id)) {
|
|
239
|
+
return fail('invalid_request', `points.llmFilters: идентификатор «${id}» объявлен дважды`);
|
|
240
|
+
}
|
|
241
|
+
if (!isLlmFilterPhase(raw.phase)) {
|
|
242
|
+
return fail('invalid_request', `points.llmFilters[${index}].phase неизвестна`);
|
|
243
|
+
}
|
|
244
|
+
if (raw.failMode !== undefined && !isLlmFilterFailMode(raw.failMode)) {
|
|
245
|
+
return fail('invalid_request', `points.llmFilters[${index}].failMode: допустимы open|closed`);
|
|
246
|
+
}
|
|
247
|
+
if (raw.timeoutMs !== undefined &&
|
|
248
|
+
(typeof raw.timeoutMs !== 'number' || !Number.isInteger(raw.timeoutMs) || raw.timeoutMs <= 0)) {
|
|
249
|
+
return fail('invalid_request', `points.llmFilters[${index}].timeoutMs должно быть целым > 0`);
|
|
250
|
+
}
|
|
251
|
+
seen.add(id);
|
|
252
|
+
filters.push({
|
|
253
|
+
id,
|
|
254
|
+
phase: raw.phase,
|
|
255
|
+
...(raw.failMode ? { failMode: raw.failMode } : {}),
|
|
256
|
+
...(raw.timeoutMs !== undefined ? { timeoutMs: raw.timeoutMs } : {}),
|
|
257
|
+
});
|
|
258
|
+
}
|
|
259
|
+
points.llmFilters = filters;
|
|
260
|
+
}
|
|
261
|
+
if (pointsRaw.tools !== undefined) {
|
|
262
|
+
if (!Array.isArray(pointsRaw.tools)) {
|
|
263
|
+
return fail('invalid_request', 'points.tools должен быть массивом');
|
|
264
|
+
}
|
|
265
|
+
const tools = [];
|
|
266
|
+
const seen = new Set();
|
|
267
|
+
for (const [index, raw] of pointsRaw.tools.entries()) {
|
|
268
|
+
if (!isRecord(raw)) {
|
|
269
|
+
return fail('invalid_request', `points.tools[${index}] — не объект`);
|
|
270
|
+
}
|
|
271
|
+
const toolName = raw.name;
|
|
272
|
+
if (!isNonEmptyString(toolName)) {
|
|
273
|
+
return fail('invalid_request', `points.tools[${index}].name обязателен`);
|
|
274
|
+
}
|
|
275
|
+
if (seen.has(toolName)) {
|
|
276
|
+
return fail('invalid_request', `points.tools: имя «${toolName}» объявлено дважды`);
|
|
277
|
+
}
|
|
278
|
+
if (!isNonEmptyString(raw.description)) {
|
|
279
|
+
return fail('invalid_request', `points.tools[${index}].description обязателен (тул без описания бесполезен модели)`);
|
|
280
|
+
}
|
|
281
|
+
if (raw.parameters !== undefined && !isRecord(raw.parameters)) {
|
|
282
|
+
return fail('invalid_request', `points.tools[${index}].parameters должен быть JSON-Schema-объектом`);
|
|
283
|
+
}
|
|
284
|
+
const capabilities = raw.capabilities;
|
|
285
|
+
if (!Array.isArray(capabilities) || capabilities.length === 0) {
|
|
286
|
+
return fail('invalid_request', `points.tools[${index}].capabilities обязательны и непусты — иначе тул невидим ` +
|
|
287
|
+
'permission-слою и admin-отключению');
|
|
288
|
+
}
|
|
289
|
+
const unknown = capabilities.find((capability) => typeof capability !== 'string' || !KNOWN_TOOL_CAPABILITIES.has(capability));
|
|
290
|
+
if (unknown !== undefined) {
|
|
291
|
+
return fail('invalid_request', `points.tools[${index}].capabilities: неизвестная capability «${String(unknown)}»`);
|
|
292
|
+
}
|
|
293
|
+
seen.add(toolName);
|
|
294
|
+
tools.push({
|
|
295
|
+
name: toolName,
|
|
296
|
+
description: raw.description,
|
|
297
|
+
...(raw.parameters ? { parameters: raw.parameters } : {}),
|
|
298
|
+
capabilities: [...capabilities],
|
|
299
|
+
});
|
|
300
|
+
}
|
|
301
|
+
points.tools = tools;
|
|
302
|
+
}
|
|
303
|
+
}
|
|
304
|
+
return {
|
|
305
|
+
ok: true,
|
|
306
|
+
capabilities: { protocol, name, version, points },
|
|
307
|
+
};
|
|
308
|
+
}
|
|
309
|
+
/** Ответ `promptBlocks` — допустимый статус манифеста (экспорт для загрузчика core). */
|
|
310
|
+
export function isPluginPromptBlockStatus(value) {
|
|
311
|
+
return (typeof value === 'string' &&
|
|
312
|
+
PROMPT_BLOCK_STATUSES.includes(value));
|
|
313
|
+
}
|
|
314
|
+
function fail(reason, message) {
|
|
315
|
+
return { ok: false, reason, message };
|
|
316
|
+
}
|
|
317
|
+
function isRecord(value) {
|
|
318
|
+
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
319
|
+
}
|
|
320
|
+
function isNonEmptyString(value) {
|
|
321
|
+
return typeof value === 'string' && value.trim().length > 0;
|
|
322
|
+
}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* ADR-090: runtime-override включений/настроек плагинов (`plugins.json`).
|
|
3
|
+
*
|
|
4
|
+
* Файл лежит рядом с lock-файлом в раскладке `<home>/plugin/` (без home —
|
|
5
|
+
* `{dataDir}/plugin/`) и хранит **per-plugin** переопределения: включён ли
|
|
6
|
+
* плагин и его произвольные настройки. Инстансные политики слоя плагинов
|
|
7
|
+
* (`plugins.enabled`/`trustFloor`/`scan`/…) живут отдельно — в runtime-настройках
|
|
8
|
+
* (`RuntimeSettings.plugins`, `{dataDir}/settings.json`).
|
|
9
|
+
*/
|
|
10
|
+
/** Переопределение конкретного плагина (runtime). */
|
|
11
|
+
export interface PluginRuntimeOverride {
|
|
12
|
+
/** Включён ли плагин (`false` — выключен владельцем). */
|
|
13
|
+
enabled?: boolean;
|
|
14
|
+
/** Произвольные настройки плагина (схема — на стороне плагина). */
|
|
15
|
+
settings?: Record<string, unknown>;
|
|
16
|
+
}
|
|
17
|
+
/** Формат файла `plugins.json`. */
|
|
18
|
+
export interface PluginSettingsFile {
|
|
19
|
+
/** Версия формата (сейчас `1`). */
|
|
20
|
+
version: number;
|
|
21
|
+
/** Переопределения по имени плагина. */
|
|
22
|
+
plugins: Record<string, PluginRuntimeOverride>;
|
|
23
|
+
}
|
|
24
|
+
/** Текущая версия формата `plugins.json`. */
|
|
25
|
+
export declare const PLUGIN_SETTINGS_FILE_VERSION = 1;
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* ADR-090: runtime-override включений/настроек плагинов (`plugins.json`).
|
|
3
|
+
*
|
|
4
|
+
* Файл лежит рядом с lock-файлом в раскладке `<home>/plugin/` (без home —
|
|
5
|
+
* `{dataDir}/plugin/`) и хранит **per-plugin** переопределения: включён ли
|
|
6
|
+
* плагин и его произвольные настройки. Инстансные политики слоя плагинов
|
|
7
|
+
* (`plugins.enabled`/`trustFloor`/`scan`/…) живут отдельно — в runtime-настройках
|
|
8
|
+
* (`RuntimeSettings.plugins`, `{dataDir}/settings.json`).
|
|
9
|
+
*/
|
|
10
|
+
/** Текущая версия формата `plugins.json`. */
|
|
11
|
+
export const PLUGIN_SETTINGS_FILE_VERSION = 1;
|
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* PROP-068 §4.3 / ADR-090: контракты статического сканера расширений и
|
|
3
|
+
* матрица install-policy.
|
|
4
|
+
*
|
|
5
|
+
* Модуль browser-safe (`zod` не нужен — только типы и чистые функции), чтобы
|
|
6
|
+
* его можно было использовать и в UI (карточка плагина — Ф6), и в ядре
|
|
7
|
+
* (сканер, `PluginHost`).
|
|
8
|
+
*
|
|
9
|
+
* **Канон границ.** Таблица `severity → verdict` и значения квот зафиксированы
|
|
10
|
+
* в [PROP-068](../../../../docs/arch_decisions/prop-068-skills-agents-registry.md) §4.3
|
|
11
|
+
* (согласовано с владельцем 2026-10-22);
|
|
12
|
+
* [ADR-090](../../../../docs/arch_decisions/adr-090-extension-api.md) ссылается
|
|
13
|
+
* на неё и не дублирует. При изменении значений — правка обоих документов.
|
|
14
|
+
*/
|
|
15
|
+
import type { PluginScanVerdict } from './plugin-audit.js';
|
|
16
|
+
/**
|
|
17
|
+
* Версия правил сканера (`PLUGIN_SCAN_RULES` в ядре).
|
|
18
|
+
*
|
|
19
|
+
* Входит в **ключ кэша сканов**: при изменении правил (новые категории,
|
|
20
|
+
* другие severity) старый вердикт из кэша нельзя переиспользовать — иначе
|
|
21
|
+
* бандл, признанный безопасным по старым правилам, получил бы «зелёный»
|
|
22
|
+
* вердикт по новым. Правило: **любое изменение правил сканера поднимает
|
|
23
|
+
* версию**.
|
|
24
|
+
*/
|
|
25
|
+
export declare const PLUGIN_SCAN_RULES_VERSION = "1";
|
|
26
|
+
/**
|
|
27
|
+
* Категории находок сканера (PROP-068 §4.3).
|
|
28
|
+
*
|
|
29
|
+
* Шесть базовых категорий + отдельная `invisible_unicode` (скрытие инструкций
|
|
30
|
+
* для LLM). Категория — **ось классификации**, а не severity: severity
|
|
31
|
+
* определяет вердикт.
|
|
32
|
+
*/
|
|
33
|
+
export declare const PLUGIN_SCAN_CATEGORIES: readonly ["exfiltration", "injection", "destructive", "persistence", "network", "obfuscation", "invisible_unicode"];
|
|
34
|
+
export type PluginScanCategory = (typeof PLUGIN_SCAN_CATEGORIES)[number];
|
|
35
|
+
/** Уровни серьёзности находки (PROP-068 §4.3). */
|
|
36
|
+
export declare const PLUGIN_SCAN_SEVERITIES: readonly ["info", "low", "medium", "high", "critical"];
|
|
37
|
+
export type PluginScanSeverity = (typeof PLUGIN_SCAN_SEVERITIES)[number];
|
|
38
|
+
/**
|
|
39
|
+
* Одна находка сканера (PROP-068 §4.3).
|
|
40
|
+
*
|
|
41
|
+
* Форма — как у threat-scan проектных инструкций
|
|
42
|
+
* (`packages/core/src/engine/context/instructions.ts`): категория, серьёзность,
|
|
43
|
+
* файл, строка, описание.
|
|
44
|
+
*/
|
|
45
|
+
export interface PluginScanFinding {
|
|
46
|
+
/** Категория находки. */
|
|
47
|
+
category: PluginScanCategory;
|
|
48
|
+
/** Серьёзность находки. */
|
|
49
|
+
severity: PluginScanSeverity;
|
|
50
|
+
/** Относительный путь файла (в корне бандла). */
|
|
51
|
+
file: string;
|
|
52
|
+
/** Номер строки (1-based; `0` — находка не привязана к строке). */
|
|
53
|
+
line: number;
|
|
54
|
+
/** Человекочитаемое описание находки. */
|
|
55
|
+
description: string;
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* Границы `severity → verdict` (канон — PROP-068 §4.3).
|
|
59
|
+
*
|
|
60
|
+
* `info|low → safe`, `medium → caution`, `high|critical → dangerous`.
|
|
61
|
+
* Вердикт бандла — **максимум** severity по находкам.
|
|
62
|
+
*/
|
|
63
|
+
export declare const PLUGIN_SCAN_SEVERITY_VERDICTS: Readonly<Record<PluginScanSeverity, PluginScanVerdict>>;
|
|
64
|
+
/** Вердикт по серьёзности одной находки. */
|
|
65
|
+
export declare function severityToVerdict(severity: PluginScanSeverity): PluginScanVerdict;
|
|
66
|
+
/** Ранг вердикта (больше — жёстче). */
|
|
67
|
+
export declare function verdictRank(verdict: PluginScanVerdict): number;
|
|
68
|
+
/**
|
|
69
|
+
* Вердикт бандла — **максимум** severity по находкам (PROP-068 §4.3).
|
|
70
|
+
*
|
|
71
|
+
* Находок нет — `safe`.
|
|
72
|
+
*/
|
|
73
|
+
export declare function verdictFromFindings(findings: readonly PluginScanFinding[]): PluginScanVerdict;
|
|
74
|
+
/**
|
|
75
|
+
* Квоты структуры бандла (PROP-068 §4.3).
|
|
76
|
+
*
|
|
77
|
+
* - `maxFileCount` / `maxTotalSizeKb` — превышение → минимум `caution`;
|
|
78
|
+
* - `maxSingleFileKb` — превышение лимита **одного** файла → `dangerous`.
|
|
79
|
+
*/
|
|
80
|
+
export declare const PLUGIN_SCAN_QUOTAS: {
|
|
81
|
+
/** Максимум файлов в бандле. */
|
|
82
|
+
readonly maxFileCount: 50;
|
|
83
|
+
/** Максимум суммарного размера бандла, КиБ. */
|
|
84
|
+
readonly maxTotalSizeKb: 1024;
|
|
85
|
+
/** Максимум размера одного файла, КиБ. */
|
|
86
|
+
readonly maxSingleFileKb: 256;
|
|
87
|
+
};
|
|
88
|
+
/** Квоты сканера (с переопределением под тест/инстанс). */
|
|
89
|
+
export interface PluginScanQuotas {
|
|
90
|
+
maxFileCount: number;
|
|
91
|
+
maxTotalSizeKb: number;
|
|
92
|
+
maxSingleFileKb: number;
|
|
93
|
+
}
|
|
94
|
+
/** Квоты по умолчанию. */
|
|
95
|
+
export declare const DEFAULT_PLUGIN_SCAN_QUOTAS: PluginScanQuotas;
|
|
96
|
+
/**
|
|
97
|
+
* Вид нарушения квоты (канон — PROP-068 §4.3).
|
|
98
|
+
*
|
|
99
|
+
* Ключи не совпадают с именами полей `PluginScanQuotas` намеренно: здесь важно
|
|
100
|
+
* **что именно нарушено**, а не как называется лимит.
|
|
101
|
+
*/
|
|
102
|
+
export type PluginScanQuotaKind = 'fileCount' | 'totalSize' | 'singleFile';
|
|
103
|
+
/**
|
|
104
|
+
* Серьёзность нарушения квоты структуры бандла (PROP-068 §4.3).
|
|
105
|
+
*
|
|
106
|
+
* Канон — здесь, чтобы сканер (core) и проверки не разъезжались:
|
|
107
|
+
* - превышение **числа файлов** или **суммарного размера** → `medium`
|
|
108
|
+
* (вердикт не выше `caution` — подтверждение владельца);
|
|
109
|
+
* - превышение размера **одного** файла → `high` (вердикт `dangerous` —
|
|
110
|
+
* установка блокируется).
|
|
111
|
+
*/
|
|
112
|
+
export declare const PLUGIN_SCAN_QUOTA_SEVERITIES: {
|
|
113
|
+
/** Превышено число файлов в бандле. */
|
|
114
|
+
readonly fileCount: "medium";
|
|
115
|
+
/** Превышен суммарный размер бандла. */
|
|
116
|
+
readonly totalSize: "medium";
|
|
117
|
+
/** Превышен размер одного файла. */
|
|
118
|
+
readonly singleFile: "high";
|
|
119
|
+
};
|
|
120
|
+
/** Исход install-policy. */
|
|
121
|
+
export declare const INSTALL_POLICY_ACTIONS: readonly ["allow", "ask", "block"];
|
|
122
|
+
export type InstallPolicyAction = (typeof INSTALL_POLICY_ACTIONS)[number];
|
|
123
|
+
/**
|
|
124
|
+
* Уровни доверия в install-policy (PROP-068 §4.2).
|
|
125
|
+
*
|
|
126
|
+
* Шире `CATALOG_TRUST_LEVELS`: матрица включает `agent-created` (создано
|
|
127
|
+
* агентом) — в каталоге расширений этот уровень не используется, но в
|
|
128
|
+
* install-policy ячейка обязательна (PROP-068 §4.2).
|
|
129
|
+
*/
|
|
130
|
+
export declare const INSTALL_POLICY_TRUST_LEVELS: readonly ["builtin", "verified", "trusted", "community", "agent-created"];
|
|
131
|
+
export type InstallPolicyTrustLevel = (typeof INSTALL_POLICY_TRUST_LEVELS)[number];
|
|
132
|
+
/**
|
|
133
|
+
* Класс расширения, для которого считается install-policy.
|
|
134
|
+
*
|
|
135
|
+
* - `content` — контент-паки/скиллы/агенты (матрица PROP-068 §4.2);
|
|
136
|
+
* - `plugin` — плагины (ADR-090): **новая ячейка** матрицы.
|
|
137
|
+
*/
|
|
138
|
+
export type InstallPolicyKind = 'content' | 'plugin';
|
|
139
|
+
/** Вход решения install-policy. */
|
|
140
|
+
export interface InstallPolicyInput {
|
|
141
|
+
/** Фактический уровень доверия (резолвится по источнику). */
|
|
142
|
+
trust: InstallPolicyTrustLevel;
|
|
143
|
+
/** Вердикт сканера. */
|
|
144
|
+
verdict: PluginScanVerdict;
|
|
145
|
+
/** Класс расширения (по умолчанию — `content`). */
|
|
146
|
+
kind?: InstallPolicyKind;
|
|
147
|
+
}
|
|
148
|
+
/**
|
|
149
|
+
* Решение install-policy по матрице `trust × verdict`.
|
|
150
|
+
*
|
|
151
|
+
* Одна функция на оба класса расширений (плагины и, в перспективе,
|
|
152
|
+
* контент-паки) — матрица не дублируется по подсистемам.
|
|
153
|
+
*
|
|
154
|
+
* **Порядок вызовов (важно):** trust-floor проверяется **до** install-policy —
|
|
155
|
+
* плагин ниже `plugins.trustFloor` не активируется ни при каком вердикте
|
|
156
|
+
* (`plugin.trust_below_floor`). Матрица отвечает только на вопрос «можно ли
|
|
157
|
+
* ставить/активировать по вердикту скана».
|
|
158
|
+
*/
|
|
159
|
+
export declare function installPolicyDecision(input: InstallPolicyInput): InstallPolicyAction;
|