@octopi-agent/engine 0.90.11 → 0.97.15

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 (169) hide show
  1. package/dist/config-admin/agent-presets.d.ts +70 -0
  2. package/dist/config-admin/agent-presets.js +243 -0
  3. package/dist/config-admin/discover.d.ts +30 -0
  4. package/dist/config-admin/discover.js +48 -0
  5. package/dist/config-admin/env.d.ts +22 -0
  6. package/dist/config-admin/env.js +41 -0
  7. package/dist/config-admin/index.d.ts +20 -0
  8. package/dist/config-admin/index.js +15 -0
  9. package/dist/config-admin/model-presets.d.ts +75 -0
  10. package/dist/config-admin/model-presets.js +249 -0
  11. package/dist/config-admin/name-guard.d.ts +14 -0
  12. package/dist/config-admin/name-guard.js +24 -0
  13. package/dist/config-admin/patch.d.ts +56 -0
  14. package/dist/config-admin/patch.js +201 -0
  15. package/dist/config-admin/port.d.ts +68 -0
  16. package/dist/config-admin/port.js +21 -0
  17. package/dist/config-admin/redact.d.ts +39 -0
  18. package/dist/config-admin/redact.js +42 -0
  19. package/dist/config-schema/agent.d.ts +43 -1
  20. package/dist/config-schema/context.d.ts +6 -1
  21. package/dist/config-schema/context.js +8 -0
  22. package/dist/config-schema/engine.d.ts +106 -4
  23. package/dist/config-schema/governance.d.ts +43 -1
  24. package/dist/config-schema/governance.js +157 -0
  25. package/dist/config-schema/models.d.ts +5 -2
  26. package/dist/config-schema/models.js +4 -1
  27. package/dist/config-schema/observability.d.ts +9 -0
  28. package/dist/config-schema/observability.js +29 -0
  29. package/dist/config-schema/run.d.ts +3 -0
  30. package/dist/config-schema/run.js +14 -0
  31. package/dist/config.d.ts +29 -4
  32. package/dist/config.js +15 -4
  33. package/dist/harness/activation/dispatcher.d.ts +8 -2
  34. package/dist/harness/activation/dispatcher.js +33 -5
  35. package/dist/harness/activation/inbox.d.ts +87 -0
  36. package/dist/harness/activation/inbox.js +169 -0
  37. package/dist/harness/activation/runtime.d.ts +9 -8
  38. package/dist/harness/activation/runtime.js +100 -8
  39. package/dist/harness/activation/types.d.ts +19 -0
  40. package/dist/harness/activation/types.js +2 -0
  41. package/dist/harness/agent/builder.d.ts +15 -1
  42. package/dist/harness/agent/builder.js +31 -10
  43. package/dist/harness/agent/config-bridge.d.ts +5 -0
  44. package/dist/harness/agent/config-bridge.js +3 -0
  45. package/dist/harness/agent/config-integrity.d.ts +72 -0
  46. package/dist/harness/agent/config-integrity.js +146 -0
  47. package/dist/harness/agent/wire-agent-builder.js +2 -1
  48. package/dist/harness/collaboration/autonomous-subsystem/think/executor.js +3 -1
  49. package/dist/harness/collaboration/delegation/child-run.js +21 -5
  50. package/dist/harness/collaboration/delegation/notifier.js +4 -3
  51. package/dist/harness/collaboration/delegation/service.js +2 -3
  52. package/dist/harness/collaboration/delegation/wiring.js +6 -5
  53. package/dist/harness/collaboration/orchestration/reflector/llm-reflector.d.ts +1 -1
  54. package/dist/harness/collaboration/orchestration/reflector/llm-reflector.js +1 -1
  55. package/dist/harness/context/capabilities/compact/engine.d.ts +30 -0
  56. package/dist/harness/context/capabilities/compact/engine.js +198 -46
  57. package/dist/harness/context/capabilities/compact/handover.d.ts +78 -0
  58. package/dist/harness/context/capabilities/compact/handover.js +107 -0
  59. package/dist/harness/context/capabilities/compact/index.d.ts +3 -1
  60. package/dist/harness/context/capabilities/compact/index.js +2 -1
  61. package/dist/harness/context/capabilities/compact/types.d.ts +30 -1
  62. package/dist/harness/context/capabilities/summary/executor.js +2 -1
  63. package/dist/harness/context/capabilities/summary/policies.js +8 -5
  64. package/dist/harness/context/constitution/default-agents.md +11 -10
  65. package/dist/harness/context/default-context-engine.d.ts +34 -4
  66. package/dist/harness/context/default-context-engine.js +194 -49
  67. package/dist/harness/context/hybrid-compressor.js +6 -0
  68. package/dist/harness/context/llm-summarizer.d.ts +2 -8
  69. package/dist/harness/context/llm-summarizer.js +69 -91
  70. package/dist/harness/context/message-selector.js +4 -3
  71. package/dist/harness/context/summarize.d.ts +2 -0
  72. package/dist/harness/context/summarize.js +7 -2
  73. package/dist/harness/context/truncate-compressor.js +7 -0
  74. package/dist/harness/context/turn-envelope.d.ts +3 -2
  75. package/dist/harness/context/turn-envelope.js +3 -2
  76. package/dist/harness/context/types.d.ts +33 -1
  77. package/dist/harness/extension/execution-environment/dangerous-commands.d.ts +28 -0
  78. package/dist/harness/extension/execution-environment/dangerous-commands.js +129 -0
  79. package/dist/harness/extension/execution-environment/effect-policy.d.ts +127 -8
  80. package/dist/harness/extension/execution-environment/effect-policy.js +244 -19
  81. package/dist/harness/extension/execution-environment/index.d.ts +4 -2
  82. package/dist/harness/extension/execution-environment/index.js +2 -1
  83. package/dist/harness/extension/execution-environment/kill-switch.d.ts +34 -0
  84. package/dist/harness/extension/execution-environment/kill-switch.js +46 -0
  85. package/dist/harness/extension/execution-environment/ops-audit.d.ts +200 -0
  86. package/dist/harness/extension/execution-environment/ops-audit.js +338 -0
  87. package/dist/harness/extension/execution-environment/privileged-exec.d.ts +158 -0
  88. package/dist/harness/extension/execution-environment/privileged-exec.js +418 -0
  89. package/dist/harness/extension/execution-environment/process-info.d.ts +180 -0
  90. package/dist/harness/extension/execution-environment/process-info.js +466 -0
  91. package/dist/harness/extension/execution-environment/process-isolation.d.ts +7 -0
  92. package/dist/harness/extension/execution-environment/process-isolation.js +9 -0
  93. package/dist/harness/extension/execution-environment/sandbox.d.ts +109 -0
  94. package/dist/harness/extension/execution-environment/sandbox.js +228 -21
  95. package/dist/harness/extension/execution-environment/tool-capabilities.d.ts +1 -1
  96. package/dist/harness/extension/execution-environment/tool-capabilities.js +6 -0
  97. package/dist/harness/extension/execution-environment/types.d.ts +19 -0
  98. package/dist/harness/extension/plugin-ecosystem/channel-types.d.ts +5 -0
  99. package/dist/harness/extension/plugin-ecosystem/tools/allowlisted-run.js +33 -0
  100. package/dist/harness/extension/plugin-ecosystem/tools/ask-user.d.ts +4 -5
  101. package/dist/harness/extension/plugin-ecosystem/tools/ask-user.js +5 -15
  102. package/dist/harness/extension/plugin-ecosystem/tools/builtin.d.ts +3 -0
  103. package/dist/harness/extension/plugin-ecosystem/tools/builtin.js +53 -2
  104. package/dist/harness/extension/plugin-ecosystem/tools/index.d.ts +2 -0
  105. package/dist/harness/extension/plugin-ecosystem/tools/index.js +2 -0
  106. package/dist/harness/extension/plugin-ecosystem/tools/privileged-tool.d.ts +43 -0
  107. package/dist/harness/extension/plugin-ecosystem/tools/privileged-tool.js +350 -0
  108. package/dist/harness/extension/plugin-ecosystem/tools/process-tools.d.ts +30 -0
  109. package/dist/harness/extension/plugin-ecosystem/tools/process-tools.js +137 -0
  110. package/dist/harness/governance/human-in-the-loop/decision-cache.d.ts +54 -4
  111. package/dist/harness/governance/human-in-the-loop/decision-cache.js +42 -16
  112. package/dist/harness/governance/security/temp-path.d.ts +9 -0
  113. package/dist/harness/governance/security/temp-path.js +13 -2
  114. package/dist/harness/governance/session-acl/seed-roles.js +14 -0
  115. package/dist/harness/index.d.ts +2 -0
  116. package/dist/harness/index.js +2 -0
  117. package/dist/harness/knowledge/fts.js +1 -2
  118. package/dist/harness/knowledge/index-store.js +59 -9
  119. package/dist/harness/memory/sqlite/keyword-search.d.ts +1 -0
  120. package/dist/harness/memory/sqlite/keyword-search.js +4 -3
  121. package/dist/harness/observability/observer/hub.js +8 -0
  122. package/dist/harness/observability/observer/run-snapshot.js +1 -0
  123. package/dist/harness/observability/observer/types.d.ts +4 -0
  124. package/dist/harness/run/agent/agent.d.ts +7 -0
  125. package/dist/harness/run/agent/agent.js +23 -1
  126. package/dist/harness/run/reliability/fallback-provider.d.ts +117 -5
  127. package/dist/harness/run/reliability/fallback-provider.js +262 -22
  128. package/dist/harness/run/reliability/harness-events.d.ts +24 -1
  129. package/dist/harness/run/reliability/model-error-policy.d.ts +32 -0
  130. package/dist/harness/run/reliability/model-error-policy.js +42 -0
  131. package/dist/harness/run/reliability/provider-wrapper.js +29 -2
  132. package/dist/harness/run/reliability/refusal-guard.d.ts +20 -0
  133. package/dist/harness/run/reliability/refusal-guard.js +102 -0
  134. package/dist/harness/run/reliability/run-agent.js +231 -33
  135. package/dist/harness/run/run-guard/default-run-guard.js +1 -1
  136. package/dist/harness/run/run-scope.d.ts +31 -0
  137. package/dist/harness/run/runner.d.ts +116 -2
  138. package/dist/harness/run/runner.js +547 -41
  139. package/dist/harness/session/attachments/llm-intent.js +2 -1
  140. package/dist/harness/session/tasks/render.d.ts +4 -1
  141. package/dist/harness/session/tasks/render.js +10 -7
  142. package/dist/harness/shared/events/agent-event-map.d.ts +66 -0
  143. package/dist/harness/shared/events/agent-event-map.js +5 -0
  144. package/dist/index.d.ts +3 -3
  145. package/dist/index.js +2 -2
  146. package/dist/integration/agent-runtime/channel-message-source.js +19 -1
  147. package/dist/integration/index.d.ts +2 -0
  148. package/dist/integration/index.js +1 -0
  149. package/dist/integration/observability/loop-watchdog.d.ts +56 -0
  150. package/dist/integration/observability/loop-watchdog.js +177 -0
  151. package/dist/integration/observability/metrics.d.ts +3 -0
  152. package/dist/integration/observability/metrics.js +18 -7
  153. package/dist/integration/providers/anthropic.d.ts +23 -0
  154. package/dist/integration/providers/anthropic.js +97 -12
  155. package/dist/integration/providers/fetch-timeout.d.ts +42 -0
  156. package/dist/integration/providers/fetch-timeout.js +51 -0
  157. package/dist/integration/providers/openai.d.ts +10 -0
  158. package/dist/integration/providers/openai.js +58 -11
  159. package/dist/integration/providers/provider-diagnostics.d.ts +80 -0
  160. package/dist/integration/providers/provider-diagnostics.js +89 -0
  161. package/dist/integration/providers/timeout-coherence.d.ts +52 -0
  162. package/dist/integration/providers/timeout-coherence.js +68 -0
  163. package/dist/integration/providers/wire-dump.d.ts +62 -0
  164. package/dist/integration/providers/wire-dump.js +111 -2
  165. package/dist/integration/storage/jsonl.js +4 -1
  166. package/dist/subsystems/cognition-steward/conceptualize/handler.js +1 -1
  167. package/dist/subsystems/memory-steward/backfill/handler.js +1 -1
  168. package/dist/subsystems/wisdom-steward/formation/handler.js +1 -1
  169. package/package.json +3 -2
@@ -0,0 +1,249 @@
1
+ /**
2
+ * provider 预设清单 —「生成器 + 表单默认值」(arch/config-hot-reload.md §5.1)
3
+ *
4
+ * 核心原则:预设只在**创建时**把表单预填成 `ModelProviderConfig` 片段,
5
+ * 确认后展开写入 octopi.json,与手写配置完全同构。预设不是运行时配置源,
6
+ * 不引入第二真相源——运行时不感知本模块。
7
+ *
8
+ * 模型参数(contextWindow / maxTokens)为**参考值**,以厂商文档为准;
9
+ * 表单允许逐字段覆盖,错了不致命(只影响路由与截断预算)。
10
+ *
11
+ * @module
12
+ */
13
+ /** 内置预设清单(随发行版维护;新增厂商直接扩表) */
14
+ export const BUILTIN_MODEL_PRESETS = [
15
+ {
16
+ id: 'openai',
17
+ label: 'OpenAI',
18
+ api: 'openai-completions',
19
+ baseUrl: 'https://api.openai.com/v1',
20
+ apiKeyEnvHint: 'OPENAI_API_KEY',
21
+ docsUrl: 'https://platform.openai.com/docs/models',
22
+ models: [
23
+ {
24
+ id: 'gpt-5.5',
25
+ name: 'GPT-5.5',
26
+ reasoning: true,
27
+ input: ['text', 'image'],
28
+ contextWindow: 256000,
29
+ maxTokens: 32768,
30
+ },
31
+ {
32
+ id: 'gpt-5-mini',
33
+ name: 'GPT-5 Mini',
34
+ reasoning: true,
35
+ input: ['text', 'image'],
36
+ contextWindow: 128000,
37
+ maxTokens: 16384,
38
+ },
39
+ ],
40
+ },
41
+ {
42
+ id: 'anthropic',
43
+ label: 'Anthropic',
44
+ api: 'anthropic-messages',
45
+ baseUrl: 'https://api.anthropic.com',
46
+ apiKeyEnvHint: 'ANTHROPIC_API_KEY',
47
+ docsUrl: 'https://docs.anthropic.com/en/docs/about-claude/models',
48
+ models: [
49
+ {
50
+ id: 'claude-sonnet-4-6',
51
+ name: 'Claude Sonnet 4.6',
52
+ reasoning: true,
53
+ input: ['text', 'image'],
54
+ contextWindow: 200000,
55
+ maxTokens: 16000,
56
+ },
57
+ {
58
+ id: 'claude-opus-4-6',
59
+ name: 'Claude Opus 4.6',
60
+ reasoning: true,
61
+ input: ['text', 'image'],
62
+ contextWindow: 200000,
63
+ maxTokens: 32000,
64
+ },
65
+ ],
66
+ },
67
+ {
68
+ id: 'deepseek',
69
+ label: 'DeepSeek',
70
+ api: 'openai-completions',
71
+ baseUrl: 'https://api.deepseek.com/v1',
72
+ apiKeyEnvHint: 'DEEPSEEK_API_KEY',
73
+ docsUrl: 'https://api-docs.deepseek.com/',
74
+ models: [
75
+ {
76
+ id: 'deepseek-chat',
77
+ name: 'DeepSeek Chat',
78
+ input: ['text'],
79
+ contextWindow: 131072,
80
+ maxTokens: 8192,
81
+ },
82
+ {
83
+ id: 'deepseek-reasoner',
84
+ name: 'DeepSeek Reasoner',
85
+ reasoning: true,
86
+ input: ['text'],
87
+ contextWindow: 131072,
88
+ maxTokens: 8192,
89
+ },
90
+ ],
91
+ },
92
+ {
93
+ id: 'qwen',
94
+ label: '通义千问(百炼 DashScope)',
95
+ api: 'openai-completions',
96
+ baseUrl: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
97
+ apiKeyEnvHint: 'DASHSCOPE_API_KEY',
98
+ docsUrl: 'https://help.aliyun.com/zh/model-studio',
99
+ models: [
100
+ {
101
+ id: 'qwen-max',
102
+ name: 'Qwen Max',
103
+ input: ['text'],
104
+ contextWindow: 32768,
105
+ maxTokens: 8192,
106
+ },
107
+ {
108
+ id: 'qwen-plus',
109
+ name: 'Qwen Plus',
110
+ input: ['text'],
111
+ contextWindow: 131072,
112
+ maxTokens: 8192,
113
+ },
114
+ {
115
+ id: 'qwen-turbo',
116
+ name: 'Qwen Turbo',
117
+ input: ['text'],
118
+ contextWindow: 131072,
119
+ maxTokens: 8192,
120
+ },
121
+ ],
122
+ },
123
+ {
124
+ id: 'kimi',
125
+ label: 'Kimi(月之暗面)',
126
+ api: 'openai-completions',
127
+ baseUrl: 'https://api.moonshot.cn/v1',
128
+ apiKeyEnvHint: 'MOONSHOT_API_KEY',
129
+ docsUrl: 'https://platform.moonshot.cn/docs',
130
+ models: [
131
+ {
132
+ id: 'kimi-latest',
133
+ name: 'Kimi Latest',
134
+ reasoning: true,
135
+ input: ['text', 'image'],
136
+ contextWindow: 131072,
137
+ maxTokens: 16384,
138
+ },
139
+ ],
140
+ },
141
+ {
142
+ id: 'glm',
143
+ label: '智谱 GLM',
144
+ api: 'openai-completions',
145
+ baseUrl: 'https://open.bigmodel.cn/api/paas/v4',
146
+ apiKeyEnvHint: 'ZHIPU_API_KEY',
147
+ docsUrl: 'https://open.bigmodel.cn/dev',
148
+ models: [
149
+ {
150
+ id: 'glm-4.6',
151
+ name: 'GLM-4.6',
152
+ reasoning: true,
153
+ input: ['text'],
154
+ contextWindow: 200000,
155
+ maxTokens: 16384,
156
+ },
157
+ ],
158
+ },
159
+ {
160
+ id: 'gemini',
161
+ label: 'Google Gemini(OpenAI 兼容端点)',
162
+ api: 'openai-completions',
163
+ baseUrl: 'https://generativelanguage.googleapis.com/v1beta/openai',
164
+ apiKeyEnvHint: 'GEMINI_API_KEY',
165
+ docsUrl: 'https://ai.google.dev/gemini-api/docs',
166
+ models: [
167
+ {
168
+ id: 'gemini-3-pro',
169
+ name: 'Gemini 3 Pro',
170
+ reasoning: true,
171
+ input: ['text', 'image', 'audio', 'video'],
172
+ contextWindow: 1000000,
173
+ maxTokens: 65536,
174
+ },
175
+ {
176
+ id: 'gemini-3-flash',
177
+ name: 'Gemini 3 Flash',
178
+ input: ['text', 'image', 'audio', 'video'],
179
+ contextWindow: 1000000,
180
+ maxTokens: 65536,
181
+ },
182
+ ],
183
+ },
184
+ {
185
+ id: 'ollama',
186
+ label: 'Ollama(本地)',
187
+ api: 'openai-completions',
188
+ baseUrl: 'http://localhost:11434/v1',
189
+ apiKeyEnvHint: '',
190
+ docsUrl: 'https://ollama.com/library',
191
+ models: [
192
+ { id: 'qwen3', name: 'Qwen3(本地)', input: ['text'], contextWindow: 32768, maxTokens: 8192 },
193
+ { id: 'llama3.3', name: 'Llama 3.3(本地)', input: ['text'], contextWindow: 32768, maxTokens: 8192 },
194
+ ],
195
+ },
196
+ {
197
+ id: 'custom',
198
+ label: '自定义(OpenAI 兼容)',
199
+ api: 'openai-completions',
200
+ baseUrl: '',
201
+ apiKeyEnvHint: 'API_KEY',
202
+ models: [],
203
+ custom: true,
204
+ },
205
+ ];
206
+ /**
207
+ * 按 id 取预设
208
+ *
209
+ * @param id - 预设 id
210
+ * @returns 预设条目;未知 id 返回 undefined
211
+ */
212
+ export function getProviderPreset(id) {
213
+ return BUILTIN_MODEL_PRESETS.find((p) => p.id === id);
214
+ }
215
+ /**
216
+ * 列出全部内置预设
217
+ *
218
+ * @returns 预设清单(只读)
219
+ */
220
+ export function listProviderPresets() {
221
+ return BUILTIN_MODEL_PRESETS;
222
+ }
223
+ /**
224
+ * 预设展开为 `ModelProviderConfig` 表单默认值(生成器语义)
225
+ *
226
+ * - apiKey 缺省给 `${ENV_HINT}` 引用形态(写回保留占位符,见 arch/config-hot-reload.md §0);
227
+ * 无 env 提示(如 ollama)时为 `''`(不发鉴权)。
228
+ * - `custom` 预设不带默认 models(表单强制用户填写)。
229
+ * - `overrides` 为用户已编辑的表单值,逐字段覆盖预设默认值。
230
+ *
231
+ * @param presetId - 预设 id
232
+ * @param overrides - 用户表单覆盖值(可选)
233
+ * @returns 可写入 octopi.json 的 provider 配置片段
234
+ * @throws 未知 presetId 时抛错(fail-loud,不做静默空对象)
235
+ */
236
+ export function expandProviderPreset(presetId, overrides) {
237
+ const preset = getProviderPreset(presetId);
238
+ if (!preset) {
239
+ throw new Error(`unknown model preset: ${presetId}`);
240
+ }
241
+ const apiKeyDefault = preset.apiKeyEnvHint ? `\${${preset.apiKeyEnvHint}}` : '';
242
+ return {
243
+ baseUrl: preset.baseUrl,
244
+ apiKey: apiKeyDefault,
245
+ api: preset.api,
246
+ models: preset.custom ? [] : preset.models.map((m) => ({ ...m })),
247
+ ...overrides,
248
+ };
249
+ }
@@ -0,0 +1,14 @@
1
+ /**
2
+ * 配置名安全守卫 — provider 名 / agent id 通用(router 与 ConfigApplyService 单一实现点)
3
+ *
4
+ * 拒:路径穿越(`.` / `..` / 点开头)、原型污染键、Windows 尾点/尾空格形态。
5
+ *
6
+ * @module
7
+ */
8
+ /**
9
+ * 断言配置名合法(路径段安全 + JSON 键安全)
10
+ *
11
+ * @param name - provider 名或 agent id
12
+ * @throws 非法名抛错(调用方映射业务 400)
13
+ */
14
+ export declare function assertSafeConfigName(name: string): void;
@@ -0,0 +1,24 @@
1
+ /**
2
+ * 配置名安全守卫 — provider 名 / agent id 通用(router 与 ConfigApplyService 单一实现点)
3
+ *
4
+ * 拒:路径穿越(`.` / `..` / 点开头)、原型污染键、Windows 尾点/尾空格形态。
5
+ *
6
+ * @module
7
+ */
8
+ /**
9
+ * 断言配置名合法(路径段安全 + JSON 键安全)
10
+ *
11
+ * @param name - provider 名或 agent id
12
+ * @throws 非法名抛错(调用方映射业务 400)
13
+ */
14
+ export function assertSafeConfigName(name) {
15
+ const validShape = /^[A-Za-z0-9_-][A-Za-z0-9._-]{0,63}$/.test(name) &&
16
+ !name.endsWith('.') &&
17
+ !name.endsWith(' ');
18
+ if (!validShape ||
19
+ name === '.' ||
20
+ name === '..' ||
21
+ ['__proto__', 'constructor', 'prototype'].includes(name)) {
22
+ throw new Error(`invalid config name: ${name}`);
23
+ }
24
+ }
@@ -0,0 +1,56 @@
1
+ /**
2
+ * 配置修补原语 — raw JSON(未展开 `${ENV}`)段级读写 + 乐观锁 hash + 引用完整性
3
+ *
4
+ * 语义对齐 doctor --fix 写回先例:操作 **raw** 对象,占位符原样保留。
5
+ * 文件 IO(备份/原子写)在根包 FileConfigService,本模块纯函数无 IO。
6
+ *
7
+ * @module
8
+ */
9
+ /**
10
+ * 配置内容 hash(乐观锁)
11
+ *
12
+ * WebUI 保存前带 `expectedHash`;与当前盘上内容 hash 不一致 = 并发编辑冲突,
13
+ * 拒绝写入让用户选择(arch/config-hot-reload.md §0)。对**原始文本**做 hash,
14
+ * 相同语义不同缩进也算冲突——保守正确。
15
+ *
16
+ * @param rawText - 配置文件原始文本
17
+ * @returns sha256 hex
18
+ */
19
+ export declare function computeConfigHash(rawText: string): string;
20
+ /**
21
+ * 按路径读取 raw JSON 值
22
+ *
23
+ * @param raw - raw 对象
24
+ * @param path - 路径段(对象键名或数组下标)
25
+ * @returns 命中的值;任一段缺失返回 undefined
26
+ */
27
+ export declare function getJsonPath(raw: unknown, path: Array<string | number>): unknown;
28
+ /**
29
+ * 按路径写入 raw JSON 值(中间缺失的对象自动创建;数组下标越界即抛错)
30
+ *
31
+ * @param raw - raw 对象(就地修改)
32
+ * @param path - 路径段
33
+ * @param value - 写入值
34
+ * @throws 路径中间为原始值、或数组下标越界时抛错(fail-loud)
35
+ */
36
+ export declare function setJsonPath(raw: Record<string, unknown>, path: Array<string | number>, value: unknown): void;
37
+ /**
38
+ * 按路径删除 raw JSON 值(对象键 delete;数组下标 splice)
39
+ *
40
+ * @param raw - raw 对象(就地修改)
41
+ * @param path - 路径段
42
+ * @throws 路径未命中时抛错(fail-loud,避免静默 no-op 造成「以为删了」)
43
+ */
44
+ export declare function deleteJsonPath(raw: Record<string, unknown>, path: Array<string | number>): void;
45
+ /**
46
+ * provider 引用完整性:找出引用了指定 provider 的配置点
47
+ *
48
+ * 用于删除 provider 前的拒绝检查(arch/config-hot-reload.md §5.1)。**保守扫描**:
49
+ * 覆盖 `agents[].model`(字符串 / 对象 / fallbackModels)与 `models.level.*`
50
+ * (primary / fallback);宁可多报疑似引用,不可漏报造成断链。
51
+ *
52
+ * @param raw - raw 配置对象
53
+ * @param providerName - 待检查的 provider 名
54
+ * @returns 引用点描述数组(如 `agents[assistant].model`);无引用返回空数组
55
+ */
56
+ export declare function findProviderReferences(raw: Record<string, unknown>, providerName: string): string[];
@@ -0,0 +1,201 @@
1
+ /**
2
+ * 配置修补原语 — raw JSON(未展开 `${ENV}`)段级读写 + 乐观锁 hash + 引用完整性
3
+ *
4
+ * 语义对齐 doctor --fix 写回先例:操作 **raw** 对象,占位符原样保留。
5
+ * 文件 IO(备份/原子写)在根包 FileConfigService,本模块纯函数无 IO。
6
+ *
7
+ * @module
8
+ */
9
+ import { createHash } from 'node:crypto';
10
+ /**
11
+ * 配置内容 hash(乐观锁)
12
+ *
13
+ * WebUI 保存前带 `expectedHash`;与当前盘上内容 hash 不一致 = 并发编辑冲突,
14
+ * 拒绝写入让用户选择(arch/config-hot-reload.md §0)。对**原始文本**做 hash,
15
+ * 相同语义不同缩进也算冲突——保守正确。
16
+ *
17
+ * @param rawText - 配置文件原始文本
18
+ * @returns sha256 hex
19
+ */
20
+ export function computeConfigHash(rawText) {
21
+ return createHash('sha256').update(rawText, 'utf8').digest('hex');
22
+ }
23
+ /**
24
+ * 按路径读取 raw JSON 值
25
+ *
26
+ * @param raw - raw 对象
27
+ * @param path - 路径段(对象键名或数组下标)
28
+ * @returns 命中的值;任一段缺失返回 undefined
29
+ */
30
+ export function getJsonPath(raw, path) {
31
+ let cur = raw;
32
+ for (const key of path) {
33
+ if (cur === null || typeof cur !== 'object')
34
+ return undefined;
35
+ cur = cur[key];
36
+ }
37
+ return cur;
38
+ }
39
+ /**
40
+ * 按路径写入 raw JSON 值(中间缺失的对象自动创建;数组下标越界即抛错)
41
+ *
42
+ * @param raw - raw 对象(就地修改)
43
+ * @param path - 路径段
44
+ * @param value - 写入值
45
+ * @throws 路径中间为原始值、或数组下标越界时抛错(fail-loud)
46
+ */
47
+ export function setJsonPath(raw, path, value) {
48
+ if (path.length === 0)
49
+ throw new Error('setJsonPath: empty path');
50
+ let cur = raw;
51
+ for (let i = 0; i < path.length - 1; i++) {
52
+ const key = path[i];
53
+ const next = cur[key];
54
+ if (next === null || typeof next !== 'object') {
55
+ cur[key] = typeof path[i + 1] === 'number' ? [] : {};
56
+ }
57
+ cur = cur[key];
58
+ }
59
+ const last = path[path.length - 1];
60
+ if (Array.isArray(cur) && typeof last === 'number' && (last < 0 || last > cur.length)) {
61
+ throw new Error(`setJsonPath: array index out of range: ${last}`);
62
+ }
63
+ if (Array.isArray(cur) && typeof last === 'number' && last === cur.length) {
64
+ cur.push(value);
65
+ }
66
+ else {
67
+ cur[last] = value;
68
+ }
69
+ }
70
+ /**
71
+ * 按路径删除 raw JSON 值(对象键 delete;数组下标 splice)
72
+ *
73
+ * @param raw - raw 对象(就地修改)
74
+ * @param path - 路径段
75
+ * @throws 路径未命中时抛错(fail-loud,避免静默 no-op 造成「以为删了」)
76
+ */
77
+ export function deleteJsonPath(raw, path) {
78
+ if (path.length === 0)
79
+ throw new Error('deleteJsonPath: empty path');
80
+ const parentPath = path.slice(0, -1);
81
+ const last = path[path.length - 1];
82
+ const parent = parentPath.length === 0 ? raw : getJsonPath(raw, parentPath);
83
+ if (parent === null || typeof parent !== 'object') {
84
+ throw new Error(`deleteJsonPath: path not found: ${path.join('.')}`);
85
+ }
86
+ if (Array.isArray(parent)) {
87
+ if (typeof last !== 'number' || last < 0 || last >= parent.length) {
88
+ throw new Error(`deleteJsonPath: array index out of range: ${last}`);
89
+ }
90
+ parent.splice(last, 1);
91
+ return;
92
+ }
93
+ const record = parent;
94
+ if (!(last in record)) {
95
+ throw new Error(`deleteJsonPath: key not found: ${path.join('.')}`);
96
+ }
97
+ delete record[last];
98
+ }
99
+ /**
100
+ * 解析 model 引用中的 provider 名
101
+ *
102
+ * 与 resolveModelConfig 同一约定:`provider/model` 取斜杠前段;裸名/level 名
103
+ * 无法直接归 provider,交 `findProviderReferences` 的 levelMap 递归处理。
104
+ *
105
+ * @param ref - model 引用字符串
106
+ * @returns provider 名;裸名返回 null
107
+ */
108
+ function parseProviderFromRef(ref) {
109
+ const idx = ref.indexOf('/');
110
+ return idx > 0 ? ref.slice(0, idx) : null;
111
+ }
112
+ /**
113
+ * provider 引用完整性:找出引用了指定 provider 的配置点
114
+ *
115
+ * 用于删除 provider 前的拒绝检查(arch/config-hot-reload.md §5.1)。**保守扫描**:
116
+ * 覆盖 `agents[].model`(字符串 / 对象 / fallbackModels)与 `models.level.*`
117
+ * (primary / fallback);宁可多报疑似引用,不可漏报造成断链。
118
+ *
119
+ * @param raw - raw 配置对象
120
+ * @param providerName - 待检查的 provider 名
121
+ * @returns 引用点描述数组(如 `agents[assistant].model`);无引用返回空数组
122
+ */
123
+ export function findProviderReferences(raw, providerName) {
124
+ const hits = [];
125
+ const models = raw.models;
126
+ const levelMap = models?.level;
127
+ /** levelName → 该 level 是否引用 provider(缓存;预置 false 防循环引用) */
128
+ const levelRefs = new Map();
129
+ const checkLevel = (level, where) => {
130
+ if (typeof level.primary === 'string')
131
+ checkModelValue(level.primary, `${where}.primary`);
132
+ if (Array.isArray(level.fallback)) {
133
+ level.fallback.forEach((f, i) => checkModelValue(f, `${where}.fallback[${i}]`));
134
+ }
135
+ };
136
+ /** 判断 level 是否引用 provider(命中时记 level 内部位置;调用方记引用者位置) */
137
+ const levelRefCheck = (levelName) => {
138
+ const cached = levelRefs.get(levelName);
139
+ if (cached !== undefined)
140
+ return cached;
141
+ levelRefs.set(levelName, false); // 防循环引用
142
+ const level = levelMap?.[levelName];
143
+ let found = false;
144
+ if (level && typeof level === 'object') {
145
+ const before = hits.length;
146
+ checkLevel(level, `models.level.${levelName}`);
147
+ found = hits.length > before;
148
+ }
149
+ levelRefs.set(levelName, found);
150
+ return found;
151
+ };
152
+ const checkModelValue = (value, where) => {
153
+ if (typeof value === 'string') {
154
+ if (parseProviderFromRef(value) === providerName) {
155
+ hits.push(where);
156
+ return;
157
+ }
158
+ // 裸名:可能是 level 引用,命中则引用点一并记录
159
+ if (levelMap && levelRefCheck(value)) {
160
+ hits.push(where);
161
+ }
162
+ return;
163
+ }
164
+ if (value && typeof value === 'object') {
165
+ const obj = value;
166
+ if (obj.provider === providerName)
167
+ hits.push(where);
168
+ }
169
+ };
170
+ const agents = Array.isArray(raw.agents) ? raw.agents : [];
171
+ agents.forEach((agent, i) => {
172
+ const id = typeof agent.id === 'string' ? agent.id : String(i);
173
+ const where = `agents[${id}]`;
174
+ checkModelValue(agent.model, `${where}.model`);
175
+ const model = agent.model;
176
+ if (model && Array.isArray(model.fallbackModels)) {
177
+ model.fallbackModels.forEach((f, j) => checkModelValue(f, `${where}.model.fallbackModels[${j}]`));
178
+ }
179
+ });
180
+ if (levelMap) {
181
+ for (const levelName of Object.keys(levelMap)) {
182
+ levelRefCheck(levelName);
183
+ }
184
+ }
185
+ // models.embedding.provider 也是真实引用(漏扫会静默断 embedding)
186
+ const embedding = models?.embedding;
187
+ if (embedding && typeof embedding.provider === 'string' && embedding.provider === providerName) {
188
+ hits.push('models.embedding.provider');
189
+ }
190
+ // concurrency.providerPool.slots[].provider(slot 引用)
191
+ const concurrency = raw.concurrency;
192
+ const pool = concurrency?.providerPool;
193
+ if (Array.isArray(pool?.slots)) {
194
+ pool.slots.forEach((slot, i) => {
195
+ if (slot?.provider === providerName) {
196
+ hits.push(`concurrency.providerPool.slots[${i}].provider`);
197
+ }
198
+ });
199
+ }
200
+ return hits;
201
+ }
@@ -0,0 +1,68 @@
1
+ /**
2
+ * ConfigAdminPort — 配置管理面写回端口(arch/config-hot-reload.md §2)
3
+ *
4
+ * gateway 只依赖本接口;文件实现(FileConfigService)在根包组合根注入。
5
+ * 语义对齐 doctor --fix 写回先例:操作 raw(`${ENV}` 占位符原样保留)。
6
+ *
7
+ * @module
8
+ */
9
+ /** 一次读取快照 */
10
+ export interface ConfigAdminSnapshot {
11
+ /** raw JSON(未展开 `${ENV}`) */
12
+ raw: Record<string, unknown>;
13
+ /** 内容 hash(乐观锁,见 computeConfigHash) */
14
+ hash: string;
15
+ }
16
+ /** 写回结果 */
17
+ export interface ConfigAdminWriteResult {
18
+ /** 写后内容 hash(供后续编辑做乐观锁) */
19
+ hash: string;
20
+ /** 备份文件路径 */
21
+ backupPath: string;
22
+ /** 运行时会忽略的未知键路径(告警不阻断,UI 提供手动清理) */
23
+ warnings: string[];
24
+ }
25
+ /** 并发编辑冲突(expectedHash 与盘上内容不一致) */
26
+ export declare class ConfigConflictError extends Error {
27
+ /** 当前盘上内容 hash */
28
+ readonly currentHash: string;
29
+ /**
30
+ * @param currentHash - 当前盘上内容 hash
31
+ */
32
+ constructor(currentHash: string);
33
+ }
34
+ /** 配置管理面写回端口 */
35
+ export interface ConfigAdminPort {
36
+ /**
37
+ * 读取当前盘上配置快照
38
+ *
39
+ * @returns raw 配置 + 内容 hash
40
+ */
41
+ read(): ConfigAdminSnapshot;
42
+ /**
43
+ * 写回配置:hash 比对(乐观锁)→ mutate → 全量校验 → 备份 → 原子写
44
+ *
45
+ * @param mutate - 就地修改 raw 的补丁函数
46
+ * @param expectedHash - 调用方读到的 hash(乐观锁)
47
+ * @returns 写后 hash + 备份路径
48
+ * @throws {@link ConfigConflictError} 并发冲突;校验失败亦抛错且盘上内容不变
49
+ */
50
+ write(mutate: (raw: Record<string, unknown>) => void, expectedHash: string): Promise<ConfigAdminWriteResult>;
51
+ /**
52
+ * 列出配置备份(时间倒序;回滚 UI 用)
53
+ *
54
+ * @returns 备份清单;实现不支持时缺省空数组
55
+ */
56
+ listBackups?(): Array<{
57
+ path: string;
58
+ mtimeMs: number;
59
+ size: number;
60
+ }>;
61
+ /**
62
+ * 读备份内容(回滚源)
63
+ *
64
+ * @param backupPath - 备份路径
65
+ * @returns 备份原文
66
+ */
67
+ readBackup?(backupPath: string): string;
68
+ }
@@ -0,0 +1,21 @@
1
+ /**
2
+ * ConfigAdminPort — 配置管理面写回端口(arch/config-hot-reload.md §2)
3
+ *
4
+ * gateway 只依赖本接口;文件实现(FileConfigService)在根包组合根注入。
5
+ * 语义对齐 doctor --fix 写回先例:操作 raw(`${ENV}` 占位符原样保留)。
6
+ *
7
+ * @module
8
+ */
9
+ /** 并发编辑冲突(expectedHash 与盘上内容不一致) */
10
+ export class ConfigConflictError extends Error {
11
+ /** 当前盘上内容 hash */
12
+ currentHash;
13
+ /**
14
+ * @param currentHash - 当前盘上内容 hash
15
+ */
16
+ constructor(currentHash) {
17
+ super(`config conflict: file changed since read (current hash ${currentHash.slice(0, 12)}…)`);
18
+ this.name = 'ConfigConflictError';
19
+ this.currentHash = currentHash;
20
+ }
21
+ }
@@ -0,0 +1,39 @@
1
+ /**
2
+ * 配置脱敏 — WebUI 回显形态(arch/config-hot-reload.md §0)
3
+ *
4
+ * apiKey 只回显「是否已配置 + 引用形态」,绝不回显明文值。
5
+ * `${VAR}` 形态给变量名;明文形态只标记 `literal`。
6
+ *
7
+ * @module
8
+ */
9
+ /** 脱敏后的密钥视图 */
10
+ export interface RedactedSecret {
11
+ /** 是否已配置非空值 */
12
+ configured: boolean;
13
+ /** `${VAR}` 形态 → 变量名;明文 → `'literal'`;未配置 → null */
14
+ ref: string | null;
15
+ }
16
+ /** 脱敏后的 provider 视图(WebUI 表单回显) */
17
+ export interface RedactedProvider {
18
+ name: string;
19
+ baseUrl: string;
20
+ api: string;
21
+ models: Array<Record<string, unknown>>;
22
+ timeoutSeconds?: number;
23
+ apiKey: RedactedSecret;
24
+ }
25
+ /**
26
+ * 把 apiKey 字符串脱敏为 `RedactedSecret`
27
+ *
28
+ * @param value - 原始 apiKey(可能为 `${VAR}` 形态、明文或空)
29
+ * @returns 脱敏视图(不含明文)
30
+ */
31
+ export declare function redactSecret(value: string | undefined): RedactedSecret;
32
+ /**
33
+ * 脱敏单个 provider 配置
34
+ *
35
+ * @param name - provider 名
36
+ * @param pc - provider 配置(已展开 `${ENV}` 的运行时形态或 raw 形态均可)
37
+ * @returns 脱敏视图
38
+ */
39
+ export declare function redactProvider(name: string, pc: Record<string, unknown>): RedactedProvider;