@itphx/synth-shared 0.13.8 → 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 (71) hide show
  1. package/dist/config/defaults.js +74 -2
  2. package/dist/config/env-overrides.d.ts +16 -0
  3. package/dist/config/env-overrides.js +103 -3
  4. package/dist/config/execution-runtime.d.ts +89 -0
  5. package/dist/config/execution-runtime.js +506 -0
  6. package/dist/config/execution.d.ts +202 -1
  7. package/dist/config/execution.js +459 -3
  8. package/dist/config/index.d.ts +2 -0
  9. package/dist/config/index.js +2 -0
  10. package/dist/config/security.d.ts +77 -0
  11. package/dist/config/security.js +116 -0
  12. package/dist/config/types.d.ts +466 -34
  13. package/dist/config/types.js +317 -33
  14. package/dist/i18n/index.d.ts +1 -1
  15. package/dist/i18n/index.js +196 -13
  16. package/dist/index.d.ts +5 -4
  17. package/dist/index.js +15 -2
  18. package/dist/schemas/index.d.ts +156 -19
  19. package/dist/schemas/index.js +126 -15
  20. package/dist/skills/frontmatter.js +1 -1
  21. package/dist/types/agent.d.ts +29 -1
  22. package/dist/types/authority.d.ts +10 -0
  23. package/dist/types/authority.js +8 -0
  24. package/dist/types/bus-events.d.ts +87 -1
  25. package/dist/types/catalog.d.ts +1 -1
  26. package/dist/types/catalog.js +1 -1
  27. package/dist/types/command-audit.d.ts +91 -0
  28. package/dist/types/command-audit.js +44 -0
  29. package/dist/types/commands.d.ts +29 -11
  30. package/dist/types/commands.js +2 -2
  31. package/dist/types/egress.d.ts +18 -3
  32. package/dist/types/egress.js +18 -3
  33. package/dist/types/events.d.ts +23 -2
  34. package/dist/types/execution.d.ts +424 -0
  35. package/dist/types/execution.js +355 -0
  36. package/dist/types/file-kind.d.ts +3 -2
  37. package/dist/types/file-kind.js +11 -2
  38. package/dist/types/git.d.ts +48 -0
  39. package/dist/types/index.d.ts +6 -0
  40. package/dist/types/index.js +18 -2
  41. package/dist/types/mentions.d.ts +96 -0
  42. package/dist/types/mentions.js +9 -0
  43. package/dist/types/message.d.ts +24 -1
  44. package/dist/types/message.js +13 -0
  45. package/dist/types/pack.d.ts +21 -21
  46. package/dist/types/pack.js +4 -4
  47. package/dist/types/permission.d.ts +8 -1
  48. package/dist/types/pipeline.d.ts +2 -2
  49. package/dist/types/plugin-protocol.d.ts +203 -4
  50. package/dist/types/plugin-protocol.js +77 -4
  51. package/dist/types/project-access.d.ts +94 -0
  52. package/dist/types/project-access.js +140 -0
  53. package/dist/types/project.d.ts +59 -2
  54. package/dist/types/project.js +20 -0
  55. package/dist/types/schedules.d.ts +49 -3
  56. package/dist/types/schedules.js +50 -1
  57. package/dist/types/scripts.d.ts +98 -0
  58. package/dist/types/scripts.js +14 -0
  59. package/dist/types/service-keys.d.ts +12 -2
  60. package/dist/types/service-keys.js +13 -0
  61. package/dist/types/session.d.ts +60 -3
  62. package/dist/types/skills.d.ts +15 -11
  63. package/dist/types/skills.js +6 -6
  64. package/dist/types/timers.d.ts +402 -0
  65. package/dist/types/timers.js +166 -0
  66. package/dist/types/tools.d.ts +124 -1
  67. package/dist/types/tools.js +22 -0
  68. package/dist/types/user.d.ts +17 -0
  69. package/dist/version.d.ts +1 -1
  70. package/dist/version.js +1 -1
  71. package/package.json +2 -2
@@ -0,0 +1,9 @@
1
+ /**
2
+ * ADR-126 §2/§2: контракты «поверхности ввода» — упоминания (`@`), скиллы
3
+ * (`$`) и сниппеты (`#`).
4
+ *
5
+ * Модуль **browser-safe** (без `node:*`): типы читают и ядро (парсер
6
+ * `engine/input-surface/parser.ts`), и UI (подсветка токенов в композере).
7
+ * Разбор текста живёт в core — здесь только контракты (ADR-095: типы в shared).
8
+ */
9
+ export {};
@@ -2,6 +2,20 @@ import type { TokenUsage } from './llm.js';
2
2
  import type { PromptMeta } from './prompt.js';
3
3
  import type { AuthorityPrincipal } from './authority.js';
4
4
  import type { MessageStatus } from './message-stream.js';
5
+ import type { InputMention } from './mentions.js';
6
+ /**
7
+ * Маркер восстановления истории: ключ `metadata.repaired` и значение
8
+ * `orphan_tool_calls` (ADR-144).
9
+ *
10
+ * У assistant-шага с `toolCalls`, у которых нет парных `tool`-сообщений,
11
+ * восстановление (`recoverStreamingMessages`) ставит `disabled: true` +
12
+ * `metadata.repaired = ORPHAN_TOOL_CALLS_REPAIRED`. Это **не** прерывание хода:
13
+ * шаг не прерывался, у него разорвана цепочка вызовов, поэтому
14
+ * `metadata.interrupted` для такого шага не ставится (он остаётся только у
15
+ * реального steer-interrupt и у недописанного стрима после рестарта).
16
+ */
17
+ export declare const MESSAGE_REPAIRED_METADATA_KEY = "repaired";
18
+ export declare const ORPHAN_TOOL_CALLS_REPAIRED = "orphan_tool_calls";
5
19
  export declare enum MessageRole {
6
20
  SYSTEM = "system",
7
21
  USER = "user",
@@ -94,7 +108,7 @@ export interface Message {
94
108
  pinned: boolean;
95
109
  hidden: boolean;
96
110
  /**
97
- * ADR-046 §7.1: сообщение локальной `/`-команды (builtin-ответ) — видно в
111
+ * ADR-126 §14: сообщение локальной `/`-команды (builtin-ответ) — видно в
98
112
  * истории, но исключается из LLM-контекста.
99
113
  */
100
114
  ephemeral?: boolean;
@@ -153,4 +167,13 @@ export interface Message {
153
167
  * объекта сообщения.
154
168
  */
155
169
  status?: MessageStatus;
170
+ /**
171
+ * ADR-126 §2: упоминания сообщения (`@`-упоминания).
172
+ *
173
+ * Аддитивное поле: у сообщений без упоминаний его нет. Для
174
+ * **user-directed** сообщения (`metadata.userDirected === true`) содержит
175
+ * упоминания пользователей (`kind: 'user'`); span'ы — индексы в тексте
176
+ * **этого** сообщения.
177
+ */
178
+ mentions?: InputMention[];
156
179
  }
@@ -1,3 +1,16 @@
1
+ /**
2
+ * Маркер восстановления истории: ключ `metadata.repaired` и значение
3
+ * `orphan_tool_calls` (ADR-144).
4
+ *
5
+ * У assistant-шага с `toolCalls`, у которых нет парных `tool`-сообщений,
6
+ * восстановление (`recoverStreamingMessages`) ставит `disabled: true` +
7
+ * `metadata.repaired = ORPHAN_TOOL_CALLS_REPAIRED`. Это **не** прерывание хода:
8
+ * шаг не прерывался, у него разорвана цепочка вызовов, поэтому
9
+ * `metadata.interrupted` для такого шага не ставится (он остаётся только у
10
+ * реального steer-interrupt и у недописанного стрима после рестарта).
11
+ */
12
+ export const MESSAGE_REPAIRED_METADATA_KEY = 'repaired';
13
+ export const ORPHAN_TOOL_CALLS_REPAIRED = 'orphan_tool_calls';
1
14
  // --- Message role ---
2
15
  export var MessageRole;
3
16
  (function (MessageRole) {
@@ -80,8 +80,8 @@ export declare const packHostSchema: z.ZodString;
80
80
  export declare const packMcpProvideSchema: z.ZodObject<{
81
81
  name: z.ZodString;
82
82
  transport: z.ZodEnum<{
83
- stdio: "stdio";
84
83
  http: "http";
84
+ stdio: "stdio";
85
85
  }>;
86
86
  port: z.ZodOptional<z.ZodNumber>;
87
87
  path: z.ZodOptional<z.ZodString>;
@@ -91,14 +91,14 @@ export declare const packMcpProvideSchema: z.ZodObject<{
91
91
  }, z.core.$strip>;
92
92
  export type PackMcpProvide = z.infer<typeof packMcpProvideSchema>;
93
93
  /**
94
- * Метаданные скилла в манифесте. Блок `metadata.synth` (ADR-046 §6.2:
94
+ * Метаданные скилла в манифесте. Блок `metadata.synth` (ADR-126 §9:
95
95
  * `agents`/`requires_capabilities`/`scope`/`trigger`/`groups`) произвольный по
96
96
  * составу — схема его не детализирует, но и не отбрасывает.
97
97
  */
98
98
  export declare const packSkillMetadataSchema: z.ZodObject<{
99
99
  synth: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
100
100
  }, z.core.$catchall<z.ZodUnknown>>;
101
- /** Скилл-предоставление (ADR-046): каталог скилла внутри пака. */
101
+ /** Скилл-предоставление (ADR-126): каталог скилла внутри пака. */
102
102
  export declare const packSkillProvideSchema: z.ZodObject<{
103
103
  name: z.ZodString;
104
104
  path: z.ZodString;
@@ -188,8 +188,8 @@ export declare const packPipelineProvideSchema: z.ZodObject<{
188
188
  timeoutSec: z.ZodOptional<z.ZodNumber>;
189
189
  }, z.core.$strip>>;
190
190
  onError: z.ZodOptional<z.ZodEnum<{
191
- fail: "fail";
192
191
  retry: "retry";
192
+ fail: "fail";
193
193
  rollback: "rollback";
194
194
  }>>;
195
195
  maxAttempts: z.ZodOptional<z.ZodNumber>;
@@ -208,8 +208,8 @@ export type PackPipelineProvide = z.infer<typeof packPipelineProvideSchema>;
208
208
  export declare const packMcpProvidesSchema: z.ZodPipe<z.ZodUnion<readonly [z.ZodArray<z.ZodObject<{
209
209
  name: z.ZodString;
210
210
  transport: z.ZodEnum<{
211
- stdio: "stdio";
212
211
  http: "http";
212
+ stdio: "stdio";
213
213
  }>;
214
214
  port: z.ZodOptional<z.ZodNumber>;
215
215
  path: z.ZodOptional<z.ZodString>;
@@ -219,8 +219,8 @@ export declare const packMcpProvidesSchema: z.ZodPipe<z.ZodUnion<readonly [z.Zod
219
219
  }, z.core.$strip>>, z.ZodObject<{
220
220
  name: z.ZodString;
221
221
  transport: z.ZodEnum<{
222
- stdio: "stdio";
223
222
  http: "http";
223
+ stdio: "stdio";
224
224
  }>;
225
225
  port: z.ZodOptional<z.ZodNumber>;
226
226
  path: z.ZodOptional<z.ZodString>;
@@ -229,7 +229,7 @@ export declare const packMcpProvidesSchema: z.ZodPipe<z.ZodUnion<readonly [z.Zod
229
229
  headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
230
230
  }, z.core.$strip>]>, z.ZodTransform<{
231
231
  name: string;
232
- transport: "stdio" | "http";
232
+ transport: "http" | "stdio";
233
233
  port?: number | undefined;
234
234
  path?: string | undefined;
235
235
  url?: string | undefined;
@@ -237,7 +237,7 @@ export declare const packMcpProvidesSchema: z.ZodPipe<z.ZodUnion<readonly [z.Zod
237
237
  headers?: Record<string, string> | undefined;
238
238
  }[], {
239
239
  name: string;
240
- transport: "stdio" | "http";
240
+ transport: "http" | "stdio";
241
241
  port?: number | undefined;
242
242
  path?: string | undefined;
243
243
  url?: string | undefined;
@@ -245,7 +245,7 @@ export declare const packMcpProvidesSchema: z.ZodPipe<z.ZodUnion<readonly [z.Zod
245
245
  headers?: Record<string, string> | undefined;
246
246
  } | {
247
247
  name: string;
248
- transport: "stdio" | "http";
248
+ transport: "http" | "stdio";
249
249
  port?: number | undefined;
250
250
  path?: string | undefined;
251
251
  url?: string | undefined;
@@ -520,8 +520,8 @@ export declare const packProvidesSchema: z.ZodObject<{
520
520
  mcp: z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodArray<z.ZodObject<{
521
521
  name: z.ZodString;
522
522
  transport: z.ZodEnum<{
523
- stdio: "stdio";
524
523
  http: "http";
524
+ stdio: "stdio";
525
525
  }>;
526
526
  port: z.ZodOptional<z.ZodNumber>;
527
527
  path: z.ZodOptional<z.ZodString>;
@@ -531,8 +531,8 @@ export declare const packProvidesSchema: z.ZodObject<{
531
531
  }, z.core.$strip>>, z.ZodObject<{
532
532
  name: z.ZodString;
533
533
  transport: z.ZodEnum<{
534
- stdio: "stdio";
535
534
  http: "http";
535
+ stdio: "stdio";
536
536
  }>;
537
537
  port: z.ZodOptional<z.ZodNumber>;
538
538
  path: z.ZodOptional<z.ZodString>;
@@ -541,7 +541,7 @@ export declare const packProvidesSchema: z.ZodObject<{
541
541
  headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
542
542
  }, z.core.$strip>]>, z.ZodTransform<{
543
543
  name: string;
544
- transport: "stdio" | "http";
544
+ transport: "http" | "stdio";
545
545
  port?: number | undefined;
546
546
  path?: string | undefined;
547
547
  url?: string | undefined;
@@ -549,7 +549,7 @@ export declare const packProvidesSchema: z.ZodObject<{
549
549
  headers?: Record<string, string> | undefined;
550
550
  }[], {
551
551
  name: string;
552
- transport: "stdio" | "http";
552
+ transport: "http" | "stdio";
553
553
  port?: number | undefined;
554
554
  path?: string | undefined;
555
555
  url?: string | undefined;
@@ -557,7 +557,7 @@ export declare const packProvidesSchema: z.ZodObject<{
557
557
  headers?: Record<string, string> | undefined;
558
558
  } | {
559
559
  name: string;
560
- transport: "stdio" | "http";
560
+ transport: "http" | "stdio";
561
561
  port?: number | undefined;
562
562
  path?: string | undefined;
563
563
  url?: string | undefined;
@@ -634,8 +634,8 @@ export declare const packProvidesSchema: z.ZodObject<{
634
634
  timeoutSec: z.ZodOptional<z.ZodNumber>;
635
635
  }, z.core.$strip>>;
636
636
  onError: z.ZodOptional<z.ZodEnum<{
637
- fail: "fail";
638
637
  retry: "retry";
638
+ fail: "fail";
639
639
  rollback: "rollback";
640
640
  }>>;
641
641
  maxAttempts: z.ZodOptional<z.ZodNumber>;
@@ -744,8 +744,8 @@ export declare const packManifestSchema: z.ZodObject<{
744
744
  mcp: z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodArray<z.ZodObject<{
745
745
  name: z.ZodString;
746
746
  transport: z.ZodEnum<{
747
- stdio: "stdio";
748
747
  http: "http";
748
+ stdio: "stdio";
749
749
  }>;
750
750
  port: z.ZodOptional<z.ZodNumber>;
751
751
  path: z.ZodOptional<z.ZodString>;
@@ -755,8 +755,8 @@ export declare const packManifestSchema: z.ZodObject<{
755
755
  }, z.core.$strip>>, z.ZodObject<{
756
756
  name: z.ZodString;
757
757
  transport: z.ZodEnum<{
758
- stdio: "stdio";
759
758
  http: "http";
759
+ stdio: "stdio";
760
760
  }>;
761
761
  port: z.ZodOptional<z.ZodNumber>;
762
762
  path: z.ZodOptional<z.ZodString>;
@@ -765,7 +765,7 @@ export declare const packManifestSchema: z.ZodObject<{
765
765
  headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
766
766
  }, z.core.$strip>]>, z.ZodTransform<{
767
767
  name: string;
768
- transport: "stdio" | "http";
768
+ transport: "http" | "stdio";
769
769
  port?: number | undefined;
770
770
  path?: string | undefined;
771
771
  url?: string | undefined;
@@ -773,7 +773,7 @@ export declare const packManifestSchema: z.ZodObject<{
773
773
  headers?: Record<string, string> | undefined;
774
774
  }[], {
775
775
  name: string;
776
- transport: "stdio" | "http";
776
+ transport: "http" | "stdio";
777
777
  port?: number | undefined;
778
778
  path?: string | undefined;
779
779
  url?: string | undefined;
@@ -781,7 +781,7 @@ export declare const packManifestSchema: z.ZodObject<{
781
781
  headers?: Record<string, string> | undefined;
782
782
  } | {
783
783
  name: string;
784
- transport: "stdio" | "http";
784
+ transport: "http" | "stdio";
785
785
  port?: number | undefined;
786
786
  path?: string | undefined;
787
787
  url?: string | undefined;
@@ -858,8 +858,8 @@ export declare const packManifestSchema: z.ZodObject<{
858
858
  timeoutSec: z.ZodOptional<z.ZodNumber>;
859
859
  }, z.core.$strip>>;
860
860
  onError: z.ZodOptional<z.ZodEnum<{
861
- fail: "fail";
862
861
  retry: "retry";
862
+ fail: "fail";
863
863
  rollback: "rollback";
864
864
  }>>;
865
865
  maxAttempts: z.ZodOptional<z.ZodNumber>;
@@ -105,16 +105,16 @@ export const packMcpProvideSchema = z.object({
105
105
  headers: z.record(z.string(), z.string()).optional(),
106
106
  });
107
107
  /**
108
- * Метаданные скилла в манифесте. Блок `metadata.synth` (ADR-046 §6.2:
108
+ * Метаданные скилла в манифесте. Блок `metadata.synth` (ADR-126 §9:
109
109
  * `agents`/`requires_capabilities`/`scope`/`trigger`/`groups`) произвольный по
110
110
  * составу — схема его не детализирует, но и не отбрасывает.
111
111
  */
112
112
  export const packSkillMetadataSchema = z
113
113
  .object({ synth: z.record(z.string(), z.unknown()).optional() })
114
114
  .catchall(z.unknown());
115
- /** Скилл-предоставление (ADR-046): каталог скилла внутри пака. */
115
+ /** Скилл-предоставление (ADR-126): каталог скилла внутри пака. */
116
116
  export const packSkillProvideSchema = z.object({
117
- /** Имя скилла (совпадает с `SKILL_NAME_REGEX` конвенцией ADR-046 §3.2). */
117
+ /** Имя скилла (совпадает с `SKILL_NAME_REGEX` конвенцией ADR-126 §13). */
118
118
  name: z.string().min(1),
119
119
  /** Путь к каталогу скилла относительно корня расширения. */
120
120
  path: z.string().min(1),
@@ -163,7 +163,7 @@ export const packAgentProvideSchema = z.object({
163
163
  provider: z.string().optional(),
164
164
  /** Модель по умолчанию. */
165
165
  model: z.string().optional(),
166
- /** Группы агентов (ADR-046 §6.2: привязка скиллов к агентам). */
166
+ /** Группы агентов (ADR-126 §9: привязка скиллов к агентам). */
167
167
  groups: z.array(z.string()).optional(),
168
168
  /** Лимит шагов агента (`0` — без ограничений). */
169
169
  maxSteps: z.number().int().min(0).optional(),
@@ -57,7 +57,14 @@ export interface PermissionDecision {
57
57
  * (непроверяемая динамика, защищённый путь, мутация вне периметра,
58
58
  * неразрешённый cwd) — без разбора текста причины.
59
59
  */
60
- askKind?: 'dynamic' | 'protected' | 'mutation' | 'cwd';
60
+ askKind?: 'dynamic' | 'protected' | 'mutation' | 'cwd' | 'external';
61
+ /**
62
+ * Аддитивно: абсолютные пути **фактических** совпадений glob'а/внешнего
63
+ * доступа, из-за которых возник `ask`. По ним резолвится правило
64
+ * `permission.rules.external_directory` и считается сессионный грант
65
+ * каталогом (`<dir>/*`). Пусто/не задано — совпадения не определены.
66
+ */
67
+ askPaths?: string[];
61
68
  /**
62
69
  * ADR-070 §2.9.1: тул недоступен не по жёсткому запрету, а из-за текущего
63
70
  * режима (`mode`), роли агента (`role`), отсутствия внешней программы
@@ -113,8 +113,8 @@ export declare const pipelineStepSchema: z.ZodObject<{
113
113
  export type PipelineStep = z.infer<typeof pipelineStepSchema>;
114
114
  /** Политика пайплайна при ошибке шага. */
115
115
  export declare const pipelineErrorPolicySchema: z.ZodEnum<{
116
- fail: "fail";
117
116
  retry: "retry";
117
+ fail: "fail";
118
118
  rollback: "rollback";
119
119
  }>;
120
120
  export type PipelineErrorPolicy = z.infer<typeof pipelineErrorPolicySchema>;
@@ -157,8 +157,8 @@ export declare const pipelineDefinitionSchema: z.ZodObject<{
157
157
  timeoutSec: z.ZodOptional<z.ZodNumber>;
158
158
  }, z.core.$strip>>;
159
159
  onError: z.ZodOptional<z.ZodEnum<{
160
- fail: "fail";
161
160
  retry: "retry";
161
+ fail: "fail";
162
162
  rollback: "rollback";
163
163
  }>>;
164
164
  maxAttempts: z.ZodOptional<z.ZodNumber>;
@@ -1,8 +1,36 @@
1
1
  import type { LlmFilterFailMode, LlmFilterPhase } from './llm-filters.js';
2
2
  import type { PromptManifestStatus } from './prompt.js';
3
3
  import type { ToolCapability as ToolCapabilityValue } from './tools.js';
4
- /** Версия wire-протокола плагина (аналог `EXECUTOR_PROTOCOL_VERSION`). */
5
- export declare const PLUGIN_PROTOCOL_VERSION = 1;
4
+ /**
5
+ * Версия wire-протокола плагина (аналог `EXECUTOR_PROTOCOL_VERSION`).
6
+ *
7
+ * **v2** (PROP-138, Ф2) — добавлен runtime-контур: плагин, объявивший
8
+ * `protocol: 2` в `/capabilities`, умеет работать с `ctx.runtime` по проводу
9
+ * (`POST /runtime/*` через хост). Плагин v1 (runtime по проводу нет)
10
+ * принимается хостом как раньше — см. {@link PLUGIN_PROTOCOL_SUPPORTED_VERSIONS}.
11
+ */
12
+ export declare const PLUGIN_PROTOCOL_VERSION = 2;
13
+ /**
14
+ * Старшая версия протокола, которую хост принимает (v1 — без runtime).
15
+ *
16
+ * Совместимость: хост говорит и с плагином v1 (поведение прежнее), и с
17
+ * плагином v2 (runtime по проводу). Вне перечня — отказ
18
+ * `protocol_mismatch` (fail-closed).
19
+ */
20
+ export declare const PLUGIN_PROTOCOL_MIN_VERSION = 1;
21
+ /**
22
+ * Версии wire-протокола, которые принимает хост.
23
+ *
24
+ * Единственный источник истины для проверки ответа `/capabilities`
25
+ * ({@link checkPluginCapabilities}) — и для выбора поведения: плагин v2
26
+ * получает runtime-контур, плагин v1 — нет.
27
+ */
28
+ export declare const PLUGIN_PROTOCOL_SUPPORTED_VERSIONS: readonly [1, 2];
29
+ /**
30
+ * Минимальная версия протокола, в которой есть runtime-контур
31
+ * (`ctx.runtime` по проводу, PROP-138 Ф2).
32
+ */
33
+ export declare const PLUGIN_PROTOCOL_RUNTIME_MIN_VERSION = 2;
6
34
  /** Пути эндпоинтов протокола (относительно базового адреса процесса). */
7
35
  export declare const PLUGIN_PROTOCOL_PATHS: {
8
36
  /** `POST` — вызов точки расширения. */
@@ -12,6 +40,150 @@ export declare const PLUGIN_PROTOCOL_PATHS: {
12
40
  /** `GET` — процесс жив (без токена). */
13
41
  readonly health: "/health";
14
42
  };
43
+ /**
44
+ * Пути runtime-контура (PROP-138, Ф2).
45
+ *
46
+ * Адреса **не** на базовом адресе процесса плагина, а на адресе
47
+ * host-side прокси (`SYNTH_RUNTIME_URL` в окружении процесса): плагин
48
+ * **не ходит** к исполнителю напрямую — единственная точка — хост.
49
+ */
50
+ export declare const PLUGIN_RUNTIME_PATHS: {
51
+ /** `POST` — команда (argv без shell) в контуре исполнителя сессии. */
52
+ readonly exec: "/runtime/exec";
53
+ /** `POST` — прочитать файл (base64). */
54
+ readonly fsRead: "/runtime/fs/read";
55
+ /** `POST` — записать файл (base64). */
56
+ readonly fsWrite: "/runtime/fs/write";
57
+ /** `POST` — сведения о файле/каталоге. */
58
+ readonly fsStat: "/runtime/fs/stat";
59
+ /** `POST` — записи каталога. */
60
+ readonly fsReaddir: "/runtime/fs/readdir";
61
+ /** `POST` — канонический путь. */
62
+ readonly fsRealpath: "/runtime/fs/realpath";
63
+ };
64
+ /**
65
+ * Контекст вызова тула, который едет по проводу (точка `tools`).
66
+ *
67
+ * `invocationId` — **привязка runtime к вызову** (протокол v2): хост
68
+ * регистрирует порт/поверхность исполнения под этим id на время вызова и
69
+ * снимает привязку после. Плагин подставляет `invocation_id` в запросы
70
+ * `POST /runtime/*` — иначе хост отклоняет их (`404`).
71
+ */
72
+ export interface PluginToolsInvokeContext {
73
+ /** id сессии (в пайплайне — `pipeline:<runId>`). */
74
+ sessionId: string;
75
+ /** id сообщения/вызова. */
76
+ messageId: string;
77
+ /** Рабочий каталог (workspace проекта). */
78
+ workingDir: string;
79
+ /** id invocation'а (протокол v2); в v1 — не приходит. */
80
+ invocationId?: string;
81
+ }
82
+ /** Вход точки `tools` (протокол v1/v2). */
83
+ export interface PluginToolsInvokeInput {
84
+ /** Аргументы тула (валидирует удалённая сторона). */
85
+ parameters: unknown;
86
+ /** Контекст вызова (см. {@link PluginToolsInvokeContext}). */
87
+ context: PluginToolsInvokeContext;
88
+ }
89
+ /** Запрос `POST /runtime/exec`. */
90
+ export interface PluginRuntimeExecRequest {
91
+ /** id invocation'а (привязка к вызову). */
92
+ invocation_id: string;
93
+ /** argv **без shell**: `[file, ...args]`. */
94
+ argv: string[];
95
+ /** Рабочий каталог команды (опционален). */
96
+ cwd?: string;
97
+ /** Таймаут вызова, мс (опционален). */
98
+ timeout_ms?: number;
99
+ }
100
+ /** Ответ `POST /runtime/exec`. */
101
+ export interface PluginRuntimeExecResponse {
102
+ /** Стандартный вывод. */
103
+ stdout: string;
104
+ /** Стандартный вывод ошибок. */
105
+ stderr: string;
106
+ /** Код завершения. */
107
+ exit_code: number;
108
+ }
109
+ /** Запрос `POST /runtime/fs/read`. */
110
+ export interface PluginRuntimeFsReadRequest {
111
+ /** id invocation'а (привязка к вызову). */
112
+ invocation_id: string;
113
+ /** Абсолютный путь на точке исполнения. */
114
+ path: string;
115
+ /** Потолок размера (опционален). */
116
+ max_bytes?: number;
117
+ }
118
+ /** Ответ `POST /runtime/fs/read` (байты — в base64). */
119
+ export interface PluginRuntimeFsReadResponse {
120
+ /** Содержимое файла в base64 (без `data:`-префикса). */
121
+ data_base64: string;
122
+ }
123
+ /** Запрос `POST /runtime/fs/write`. */
124
+ export interface PluginRuntimeFsWriteRequest {
125
+ /** id invocation'а (привязка к вызову). */
126
+ invocation_id: string;
127
+ /** Абсолютный путь на точке исполнения. */
128
+ path: string;
129
+ /** Содержимое в base64 (без `data:`-префикса). */
130
+ data_base64: string;
131
+ /**
132
+ * Что делать, если файл уже существует.
133
+ *
134
+ * `overwrite` (по умолчанию) — перезаписать (как в inline-контуре);
135
+ * `fail` — отказать, если файл есть (в inline-контуре такого режима нет:
136
+ * runtime перезаписывает всегда).
137
+ */
138
+ if_exists?: 'fail' | 'overwrite';
139
+ }
140
+ /** Вид объекта ФС на точке исполнения. */
141
+ export type PluginRuntimeFsKind = 'file' | 'directory' | 'other';
142
+ /** Ответ `POST /runtime/fs/stat`. */
143
+ export interface PluginRuntimeFsStatResponse {
144
+ /** Вид объекта. */
145
+ kind: PluginRuntimeFsKind;
146
+ /** Размер в байтах (у каталога — `0`). */
147
+ size: number;
148
+ /** Время последнего изменения, мс (Unix epoch). */
149
+ mtime_ms: number;
150
+ }
151
+ /** Запись каталога (ответ `POST /runtime/fs/readdir`). */
152
+ export interface PluginRuntimeFsDirEntry {
153
+ /** Имя записи (без пути). */
154
+ name: string;
155
+ /** Вид объекта. */
156
+ kind: PluginRuntimeFsKind;
157
+ /** Размер в байтах. */
158
+ size: number;
159
+ }
160
+ /** Ответ `POST /runtime/fs/readdir`. */
161
+ export interface PluginRuntimeFsReaddirResponse {
162
+ /** Записи каталога (в файловом порядке). */
163
+ entries: PluginRuntimeFsDirEntry[];
164
+ }
165
+ /** Ответ `POST /runtime/fs/realpath`. */
166
+ export interface PluginRuntimeFsRealpathResponse {
167
+ /** Канонический путь (симлинки разыменованы). */
168
+ path: string;
169
+ }
170
+ /**
171
+ * Тело ошибки runtime-контура: `{ error: { code, message } }`.
172
+ *
173
+ * `code` — машиночитаемый код (`not_found`/`permission`/`too_large`/
174
+ * `exists`/`invalid`/`unresolvable` — коды FS-порта; `nonzero_exit`/
175
+ * `timeout`/`spawn_failed`/`policy_denied` — причины исполнения;
176
+ * `internal_error`/`invalid_request`/`unauthorized`/`unknown_invocation` —
177
+ * ошибки самого прокси). `message` — текст без секретов.
178
+ */
179
+ export interface PluginRuntimeErrorBody {
180
+ error: {
181
+ /** Машиночитаемый код. */
182
+ code: string;
183
+ /** Человекочитаемое сообщение (без секретов). */
184
+ message: string;
185
+ };
186
+ }
15
187
  /**
16
188
  * Строка готовности, которую сервер плагина печатает в **stdout** при старте
17
189
  * (Ф4б-2). Хост читает stdout процесса до этой строки и берёт из неё порт.
@@ -118,7 +290,13 @@ export interface PluginCapabilitiesTool {
118
290
  }
119
291
  /** Ответ `GET /capabilities`: версия протокола + поддерживаемые точки. */
120
292
  export interface PluginCapabilities {
121
- /** Версия wire-протокола (`PLUGIN_PROTOCOL_VERSION`). */
293
+ /**
294
+ * Версия wire-протокола, на которой говорит плагин.
295
+ *
296
+ * `1` — без runtime-контура (прежнее поведение); `2` — с runtime-контуром
297
+ * (`ctx.runtime` по проводу, PROP-138 Ф2). Хост принимает обе версии
298
+ * ({@link PLUGIN_PROTOCOL_SUPPORTED_VERSIONS}).
299
+ */
122
300
  protocol: number;
123
301
  /** Имя плагина (сверяется с ожидаемым — процесс обязан быть тем же плагином). */
124
302
  name: string;
@@ -133,7 +311,13 @@ export interface PluginCapabilities {
133
311
  }
134
312
  /** Тело запроса `POST /invoke`. */
135
313
  export interface PluginInvokeRequest {
136
- /** Версия wire-протокола. */
314
+ /**
315
+ * Версия wire-протокола, по которой хост говорит с этим плагином.
316
+ *
317
+ * Хост **эхом** повторяет версию, объявленную плагином в `/capabilities`:
318
+ * так плагин v1 получает привычное `protocol: 1` (прежнее поведение), а
319
+ * плагин v2 — `protocol: 2`.
320
+ */
137
321
  protocol: number;
138
322
  /** Точка расширения. */
139
323
  point: PluginProtocolPoint;
@@ -185,6 +369,21 @@ export type PluginProtocolErrorReason = (typeof PLUGIN_PROTOCOL_ERROR_REASONS)[n
185
369
  export declare const PLUGIN_PROTOCOL_ERROR_STATUS: Record<PluginProtocolErrorReason, number>;
186
370
  /** Значение — известная причина отказа протокола. */
187
371
  export declare function isPluginProtocolErrorReason(value: unknown): value is PluginProtocolErrorReason;
372
+ /**
373
+ * Версия протокола, которую принимает хост (fail-closed вне перечня).
374
+ *
375
+ * Единственная точка проверки: и `checkPluginCapabilities`, и выбор
376
+ * runtime-контура (плагин v2) опираются на неё.
377
+ */
378
+ export declare function isSupportedPluginProtocolVersion(value: unknown): value is number;
379
+ /**
380
+ * Понимает ли плагин runtime-контур (PROP-138, Ф2).
381
+ *
382
+ * `true` — плагин объявил версию протокола с runtime-контуром: хот может
383
+ * отдавать `ctx.runtime` по проводу. `false` — плагин v1: поведение прежнее
384
+ * (runtime по проводу нет).
385
+ */
386
+ export declare function pluginProtocolSupportsRuntime(protocol: number): boolean;
188
387
  /** Значение — известная точка протокола. */
189
388
  export declare function isPluginProtocolPoint(value: unknown): value is PluginProtocolPoint;
190
389
  /** Предел символов содержимого блока в ответе (защита от «случайного» мегабайта). */