@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
@@ -49,6 +49,10 @@ export declare class AnthropicProvider implements ModelProvider {
49
49
  private baseUrl;
50
50
  private version;
51
51
  private timeoutMs;
52
+ /** 与 timeoutMs 对齐的 fetch dispatcher(transport 不得在配置值之下提前掐断) */
53
+ private dispatcher;
54
+ /** HTTP transport(可注入替换供测试;默认 undici fetch,错误形态与内置 fetch 一致) */
55
+ private fetch;
52
56
  readonly defaultModel: string;
53
57
  constructor(config: AnthropicProviderConfig);
54
58
  /**
@@ -72,6 +76,12 @@ export declare class AnthropicProvider implements ModelProvider {
72
76
  * 检查 provider 是否可用
73
77
  */
74
78
  isAvailable(): Promise<boolean>;
79
+ /**
80
+ * 释放 transport 资源(keep-alive dispatcher 的连接池)
81
+ *
82
+ * 热更替换(gateway.registerProvider)或宿主显式收口时调用;重复调用安全。
83
+ */
84
+ dispose(): Promise<void>;
75
85
  /**
76
86
  * 构造实际发送的请求体(wire dump 观测用)
77
87
  *
@@ -86,6 +96,19 @@ export declare class AnthropicProvider implements ModelProvider {
86
96
  * OpenAI 格式 → Anthropic 格式
87
97
  */
88
98
  private toAnthropicRequest;
99
+ /**
100
+ * 将消息列表转换为 Anthropic 消息列表(含 tool_result 聚合)
101
+ *
102
+ * Anthropic 协议要求:一个 assistant 回合发出的全部 `tool_use`,其 `tool_result`
103
+ * 必须位于**紧随其后的同一条 user 消息**内。引擎里并行工具调用的结果是一条 tool
104
+ * 消息携带多个 `toolResults`,而历史中相邻的 tool 消息也可能出现;逐条转换会产出
105
+ * 多条连续 user 消息,导致前面的 tool_use 无配对结果而被拒(火山等严格端点只回
106
+ * 通用 InvalidParameter,不指出 param)。
107
+ *
108
+ * @param messages - 非 system 消息列表
109
+ * @returns Anthropic 消息列表(连续 tool 消息已聚合为一条 user 消息)
110
+ */
111
+ private toAnthropicMessages;
89
112
  /**
90
113
  * 将 OpenAI 消息格式转换为 Anthropic 消息格式
91
114
  */
@@ -18,6 +18,8 @@
18
18
  * 实现 ModelProvider 接口。
19
19
  */
20
20
  import { tokenUsageFromAnthropic } from './usage.js';
21
+ import { attachHttpStatus, attachStreamDiag, createStreamDiag, recordWireBytes, } from './provider-diagnostics.js';
22
+ import { createTimeoutDispatcher, providerFetch } from './fetch-timeout.js';
21
23
  /**
22
24
  * Anthropic Messages Provider
23
25
  *
@@ -31,6 +33,10 @@ export class AnthropicProvider {
31
33
  baseUrl;
32
34
  version;
33
35
  timeoutMs;
36
+ /** 与 timeoutMs 对齐的 fetch dispatcher(transport 不得在配置值之下提前掐断) */
37
+ dispatcher;
38
+ /** HTTP transport(可注入替换供测试;默认 undici fetch,错误形态与内置 fetch 一致) */
39
+ fetch = providerFetch;
34
40
  defaultModel;
35
41
  constructor(config) {
36
42
  this.name = config.name ?? 'anthropic';
@@ -38,6 +44,7 @@ export class AnthropicProvider {
38
44
  this.baseUrl = (config.baseUrl ?? 'https://api.anthropic.com').replace(/\/$/, '');
39
45
  this.version = config.version ?? '2023-06-01';
40
46
  this.timeoutMs = config.timeoutMs ?? 120_000;
47
+ this.dispatcher = createTimeoutDispatcher(this.timeoutMs);
41
48
  // 仅使用用户配置的 ModelInfo;不合并 builtin 猜测 contextWindow
42
49
  const rawModels = config.models ?? [];
43
50
  this.models = [];
@@ -47,11 +54,12 @@ export class AnthropicProvider {
47
54
  }
48
55
  else {
49
56
  this.models.push(entry.name);
50
- if (entry.contextWindow != null || entry.maxOutputTokens != null) {
57
+ if (entry.contextWindow != null || entry.maxOutputTokens != null || entry.temperature != null) {
51
58
  this.modelInfoMap.set(entry.name, {
52
59
  name: entry.name,
53
60
  contextWindow: entry.contextWindow,
54
61
  maxOutputTokens: entry.maxOutputTokens,
62
+ temperature: entry.temperature,
55
63
  });
56
64
  }
57
65
  }
@@ -85,19 +93,22 @@ export class AnthropicProvider {
85
93
  request.signal.addEventListener('abort', () => controller.abort(), { once: true });
86
94
  }
87
95
  try {
88
- const response = await fetch(`${this.baseUrl}/v1/messages`, {
96
+ const response = await this.fetch(`${this.baseUrl}/v1/messages`, {
89
97
  method: 'POST',
90
98
  headers: {
91
99
  'Content-Type': 'application/json',
92
- 'x-api-key': this.apiKey,
100
+ ...(this.apiKey ? { 'x-api-key': this.apiKey } : {}),
93
101
  'anthropic-version': this.version,
94
102
  },
95
103
  body: JSON.stringify(anthropicRequest),
96
104
  signal: controller.signal,
105
+ dispatcher: this.dispatcher,
97
106
  });
98
107
  if (!response.ok) {
99
108
  const error = await response.text();
100
- throw new Error(`Anthropic API error (${response.status}): ${error}`);
109
+ const httpError = new Error(`Anthropic API error (${response.status}): ${error}`);
110
+ attachHttpStatus(httpError, response.status);
111
+ throw httpError;
101
112
  }
102
113
  const data = await response.json();
103
114
  return this.fromAnthropicResponse(data, request.model ?? this.defaultModel);
@@ -127,15 +138,16 @@ export class AnthropicProvider {
127
138
  const connectTimer = setTimeout(() => controller.abort(), this.timeoutMs);
128
139
  let response;
129
140
  try {
130
- response = await fetch(`${this.baseUrl}/v1/messages`, {
141
+ response = await this.fetch(`${this.baseUrl}/v1/messages`, {
131
142
  method: 'POST',
132
143
  headers: {
133
144
  'Content-Type': 'application/json',
134
- 'x-api-key': this.apiKey,
145
+ ...(this.apiKey ? { 'x-api-key': this.apiKey } : {}),
135
146
  'anthropic-version': this.version,
136
147
  },
137
148
  body: JSON.stringify(anthropicRequest),
138
149
  signal: controller.signal,
150
+ dispatcher: this.dispatcher,
139
151
  });
140
152
  }
141
153
  catch (err) {
@@ -146,7 +158,9 @@ export class AnthropicProvider {
146
158
  clearTimeout(connectTimer);
147
159
  if (!response.ok) {
148
160
  const error = await response.text();
149
- throw new Error(`Anthropic API error (${response.status}): ${error}`);
161
+ const httpError = new Error(`Anthropic API error (${response.status}): ${error}`);
162
+ attachHttpStatus(httpError, response.status);
163
+ throw httpError;
150
164
  }
151
165
  const reader = response.body?.getReader();
152
166
  if (!reader) {
@@ -154,6 +168,8 @@ export class AnthropicProvider {
154
168
  }
155
169
  const decoder = new TextDecoder();
156
170
  let buffer = '';
171
+ // 流内观测:ping 心跳 vs 内容 chunk 的区分是「上游活着但不产出」与「连接已死」的唯一依据
172
+ const diag = createStreamDiag();
157
173
  let currentToolId = '';
158
174
  let currentToolName = '';
159
175
  let toolArgsBuffer = '';
@@ -172,18 +188,30 @@ export class AnthropicProvider {
172
188
  try {
173
189
  while (true) {
174
190
  const { done, value } = await reader.read();
175
- if (done)
191
+ if (done) {
192
+ diag.sawEnd = true;
176
193
  break;
194
+ }
177
195
  resetIdleTimer();
196
+ recordWireBytes(diag, value.byteLength);
178
197
  buffer += decoder.decode(value, { stream: true });
179
198
  const lines = buffer.split('\n');
180
199
  buffer = lines.pop() ?? '';
181
200
  for (const line of lines) {
201
+ // SSE 注释行也是心跳(与 openai 侧同口径:trim 后判 `:`);`event:` 行是帧头,不算心跳
202
+ const trimmedLine = line.trim();
203
+ if (trimmedLine.startsWith(':') && trimmedLine.length > 1)
204
+ diag.keepalives += 1;
182
205
  if (line.startsWith('event: ') || !line.startsWith('data: '))
183
206
  continue;
184
207
  try {
185
208
  const data = JSON.parse(line.slice(6));
186
- if (data.type === 'content_block_start') {
209
+ if (data.type === 'ping') {
210
+ // 上游保活心跳:连接仍活着,但没有任何产出。engine watchdog 只认内容 chunk,
211
+ // 因此这里单独计数,供失败留痕区分「排队/长 prefill」与「连接已死」。
212
+ diag.keepalives += 1;
213
+ }
214
+ else if (data.type === 'content_block_start') {
187
215
  const block = data.content_block;
188
216
  if (block?.type === 'tool_use') {
189
217
  currentToolId = block.id;
@@ -194,9 +222,11 @@ export class AnthropicProvider {
194
222
  else if (data.type === 'content_block_delta') {
195
223
  const delta = data.delta;
196
224
  if (delta?.type === 'text_delta') {
225
+ diag.contentChunks += 1;
197
226
  yield { type: 'content', content: delta.text ?? '' };
198
227
  }
199
228
  else if (delta?.type === 'thinking_delta') {
229
+ diag.contentChunks += 1;
200
230
  yield { type: 'reasoning', content: delta.thinking ?? '' };
201
231
  }
202
232
  else if (delta?.type === 'input_json_delta') {
@@ -210,6 +240,7 @@ export class AnthropicProvider {
210
240
  args = JSON.parse(toolArgsBuffer);
211
241
  }
212
242
  catch { /* ignore */ }
243
+ diag.contentChunks += 1;
213
244
  yield {
214
245
  type: 'tool_call',
215
246
  toolCall: {
@@ -245,6 +276,7 @@ export class AnthropicProvider {
245
276
  }
246
277
  }
247
278
  else if (data.type === 'message_stop') {
279
+ diag.sawEnd = true;
248
280
  yield { type: 'done', usage: streamUsage, finishReason };
249
281
  return;
250
282
  }
@@ -255,6 +287,12 @@ export class AnthropicProvider {
255
287
  }
256
288
  }
257
289
  }
290
+ catch (err) {
291
+ // 异常收尾把观测事实随错误带走:读取方在同一个 catch 窗口内取值,
292
+ // 不保留引用,避免长时间持有诊断对象。
293
+ attachStreamDiag(err, diag);
294
+ throw err;
295
+ }
258
296
  finally {
259
297
  if (idleTimer)
260
298
  clearTimeout(idleTimer);
@@ -266,11 +304,11 @@ export class AnthropicProvider {
266
304
  */
267
305
  async isAvailable() {
268
306
  try {
269
- const response = await fetch(`${this.baseUrl}/v1/messages`, {
307
+ const response = await this.fetch(`${this.baseUrl}/v1/messages`, {
270
308
  method: 'POST',
271
309
  headers: {
272
310
  'Content-Type': 'application/json',
273
- 'x-api-key': this.apiKey,
311
+ ...(this.apiKey ? { 'x-api-key': this.apiKey } : {}),
274
312
  'anthropic-version': this.version,
275
313
  },
276
314
  body: JSON.stringify({
@@ -278,6 +316,9 @@ export class AnthropicProvider {
278
316
  max_tokens: 1,
279
317
  messages: [{ role: 'user', content: 'hi' }],
280
318
  }),
319
+ // 探活与 openai 侧同口径:5s 上限 + 对齐 dispatcher,不挂到 provider 超时量级
320
+ signal: AbortSignal.timeout(5000),
321
+ dispatcher: this.dispatcher,
281
322
  });
282
323
  return response.ok || response.status === 400;
283
324
  }
@@ -285,6 +326,14 @@ export class AnthropicProvider {
285
326
  return false;
286
327
  }
287
328
  }
329
+ /**
330
+ * 释放 transport 资源(keep-alive dispatcher 的连接池)
331
+ *
332
+ * 热更替换(gateway.registerProvider)或宿主显式收口时调用;重复调用安全。
333
+ */
334
+ async dispose() {
335
+ await this.dispatcher.close();
336
+ }
288
337
  // ===== 格式转换 =====
289
338
  /**
290
339
  * 构造实际发送的请求体(wire dump 观测用)
@@ -306,7 +355,7 @@ export class AnthropicProvider {
306
355
  const systemMessages = request.messages.filter((m) => m.role === 'system');
307
356
  const nonSystemMessages = request.messages.filter((m) => m.role !== 'system');
308
357
  const systemPrompt = systemMessages.map((m) => String(m.content ?? '')).join('\n\n');
309
- const messages = nonSystemMessages.map((m) => this.toAnthropicMessage(m));
358
+ const messages = this.toAnthropicMessages(nonSystemMessages);
310
359
  const tools = request.tools?.map((t) => this.toAnthropicTool(t));
311
360
  // max_tokens: 请求值与模型能力取较小值,默认从 ModelInfo 取
312
361
  const modelName = request.model || this.defaultModel;
@@ -326,11 +375,47 @@ export class AnthropicProvider {
326
375
  if (request.temperature !== undefined) {
327
376
  anthropicRequest.temperature = request.temperature;
328
377
  }
378
+ else if (modelInfo?.temperature !== undefined) {
379
+ // 请求未指定时采用模型级配置;两者都未配置则不发送该参数(交给服务端默认)
380
+ anthropicRequest.temperature = modelInfo.temperature;
381
+ }
329
382
  if (tools && tools.length > 0) {
330
383
  anthropicRequest.tools = tools;
331
384
  }
332
385
  return anthropicRequest;
333
386
  }
387
+ /**
388
+ * 将消息列表转换为 Anthropic 消息列表(含 tool_result 聚合)
389
+ *
390
+ * Anthropic 协议要求:一个 assistant 回合发出的全部 `tool_use`,其 `tool_result`
391
+ * 必须位于**紧随其后的同一条 user 消息**内。引擎里并行工具调用的结果是一条 tool
392
+ * 消息携带多个 `toolResults`,而历史中相邻的 tool 消息也可能出现;逐条转换会产出
393
+ * 多条连续 user 消息,导致前面的 tool_use 无配对结果而被拒(火山等严格端点只回
394
+ * 通用 InvalidParameter,不指出 param)。
395
+ *
396
+ * @param messages - 非 system 消息列表
397
+ * @returns Anthropic 消息列表(连续 tool 消息已聚合为一条 user 消息)
398
+ */
399
+ toAnthropicMessages(messages) {
400
+ const result = [];
401
+ for (let i = 0; i < messages.length; i++) {
402
+ const msg = messages[i];
403
+ if (msg.role !== 'tool') {
404
+ result.push(this.toAnthropicMessage(msg));
405
+ continue;
406
+ }
407
+ // 连续 tool 消息合并:各条转换结果的内容块拼进同一条 user 消息
408
+ const blocks = [];
409
+ while (i < messages.length && messages[i].role === 'tool') {
410
+ const converted = this.toAnthropicMessage(messages[i]);
411
+ blocks.push(...converted.content);
412
+ i++;
413
+ }
414
+ i--;
415
+ result.push({ role: 'user', content: blocks });
416
+ }
417
+ return result;
418
+ }
334
419
  /**
335
420
  * 将 OpenAI 消息格式转换为 Anthropic 消息格式
336
421
  */
@@ -0,0 +1,42 @@
1
+ /**
2
+ * 模型调用 HTTP transport 超时对齐
3
+ *
4
+ * 背景(2026-10-27 事故):Node 内置 fetch(undici)的 `headersTimeout` /
5
+ * `bodyTimeout` 默认各 300s,不受 provider `timeoutSeconds` 影响。非流式 chat
6
+ * 一次超过 300s 的正常长生成(实测 380–447s)必被 transport 掐死成
7
+ * `TypeError: fetch failed`,sync fallback 对长生成模型恢复率为 0。
8
+ *
9
+ * 方案:provider 为 fetch 显式传入 dispatcher,把 transport 两级超时对齐到
10
+ * provider 自身的 `timeoutMs`(= `timeoutSeconds`)。引擎层(modelCall
11
+ * idle/absolute watchdog、sync fallback 预算)仍是上位预算;transport 只保证
12
+ * 不再在配置值之下提前掐断连接。
13
+ *
14
+ * @module integration/providers/fetch-timeout
15
+ */
16
+ import { Agent, fetch as undiciFetch } from 'undici';
17
+ /**
18
+ * 模型调用专用 fetch
19
+ *
20
+ * 必须用 undici 自带 fetch:Node 内置 fetch 的 dispatcher 接口与 npm undici 的
21
+ * Agent 版本不兼容(直接报 `invalid onRequestStart method` / `UND_ERR_INVALID_ARG`),
22
+ * 自定义 dispatcher 只能搭配 undici 自己的 fetch 使用。错误形态与内置 fetch 一致
23
+ * (`TypeError: fetch failed` + cause),错误分类行为不变。
24
+ */
25
+ export declare const providerFetch: typeof undiciFetch;
26
+ /**
27
+ * 创建与 provider 超时对齐的 fetch dispatcher
28
+ *
29
+ * 显式关闭 HTTP/2(`allowH2: false`)。undici 8.x 的 `allowH2` 默认为 true,
30
+ * 只要端点 ALPN 协商到 h2 就走 `client-h2.js`;2026-10-30 网关僵死事故即由该
31
+ * 路径触发:进程 footprint 涨到 30.5G,主线程冻结在原生
32
+ * `Http2Session::SendPendingData → CopyDataIntoOutgoing` 的
33
+ * `std::vector<NgHttp2StreamWrite>` 扩容循环里,事件循环再未恢复。
34
+ *
35
+ * 该路径的代价在任何配置下都不划算:模型调用是「单请求 + 单条流式响应」,
36
+ * 用不到 h2 的多路复用,却要承担首部压缩/流控窗口状态机带来的额外失败面;
37
+ * HTTP/1.1 路径有成熟且线性的 socket 背压。
38
+ *
39
+ * @param timeoutMs - provider 级超时毫秒数(headers / body 同值)
40
+ * @returns undici Agent,作为 fetch 的 `dispatcher` 传入
41
+ */
42
+ export declare function createTimeoutDispatcher(timeoutMs: number): Agent;
@@ -0,0 +1,51 @@
1
+ /**
2
+ * 模型调用 HTTP transport 超时对齐
3
+ *
4
+ * 背景(2026-10-27 事故):Node 内置 fetch(undici)的 `headersTimeout` /
5
+ * `bodyTimeout` 默认各 300s,不受 provider `timeoutSeconds` 影响。非流式 chat
6
+ * 一次超过 300s 的正常长生成(实测 380–447s)必被 transport 掐死成
7
+ * `TypeError: fetch failed`,sync fallback 对长生成模型恢复率为 0。
8
+ *
9
+ * 方案:provider 为 fetch 显式传入 dispatcher,把 transport 两级超时对齐到
10
+ * provider 自身的 `timeoutMs`(= `timeoutSeconds`)。引擎层(modelCall
11
+ * idle/absolute watchdog、sync fallback 预算)仍是上位预算;transport 只保证
12
+ * 不再在配置值之下提前掐断连接。
13
+ *
14
+ * @module integration/providers/fetch-timeout
15
+ */
16
+ import { Agent, fetch as undiciFetch } from 'undici';
17
+ /**
18
+ * 模型调用专用 fetch
19
+ *
20
+ * 必须用 undici 自带 fetch:Node 内置 fetch 的 dispatcher 接口与 npm undici 的
21
+ * Agent 版本不兼容(直接报 `invalid onRequestStart method` / `UND_ERR_INVALID_ARG`),
22
+ * 自定义 dispatcher 只能搭配 undici 自己的 fetch 使用。错误形态与内置 fetch 一致
23
+ * (`TypeError: fetch failed` + cause),错误分类行为不变。
24
+ */
25
+ export const providerFetch = undiciFetch;
26
+ /**
27
+ * 创建与 provider 超时对齐的 fetch dispatcher
28
+ *
29
+ * 显式关闭 HTTP/2(`allowH2: false`)。undici 8.x 的 `allowH2` 默认为 true,
30
+ * 只要端点 ALPN 协商到 h2 就走 `client-h2.js`;2026-10-30 网关僵死事故即由该
31
+ * 路径触发:进程 footprint 涨到 30.5G,主线程冻结在原生
32
+ * `Http2Session::SendPendingData → CopyDataIntoOutgoing` 的
33
+ * `std::vector<NgHttp2StreamWrite>` 扩容循环里,事件循环再未恢复。
34
+ *
35
+ * 该路径的代价在任何配置下都不划算:模型调用是「单请求 + 单条流式响应」,
36
+ * 用不到 h2 的多路复用,却要承担首部压缩/流控窗口状态机带来的额外失败面;
37
+ * HTTP/1.1 路径有成熟且线性的 socket 背压。
38
+ *
39
+ * @param timeoutMs - provider 级超时毫秒数(headers / body 同值)
40
+ * @returns undici Agent,作为 fetch 的 `dispatcher` 传入
41
+ */
42
+ export function createTimeoutDispatcher(timeoutMs) {
43
+ return new Agent({
44
+ headersTimeout: timeoutMs,
45
+ bodyTimeout: timeoutMs,
46
+ // 见上方事故说明:h2 发送路径曾无对应输入地放大到 30.5G,禁用优先于调参
47
+ allowH2: false,
48
+ // connect 保持 undici 默认(10s):死主机/不可达端点要快速失败进入重试,
49
+ // 而不是把连接建立也拖到 provider 超时量级
50
+ });
51
+ }
@@ -54,6 +54,10 @@ export declare class OpenAIProvider implements ModelProvider {
54
54
  private baseUrl;
55
55
  readonly defaultModel: string;
56
56
  private timeoutMs;
57
+ /** 与 timeoutMs 对齐的 fetch dispatcher(transport 不得在配置值之下提前掐断) */
58
+ private dispatcher;
59
+ /** HTTP transport(可注入替换供测试;默认 undici fetch,错误形态与内置 fetch 一致) */
60
+ private fetch;
57
61
  constructor(config: OpenAIProviderConfig);
58
62
  /**
59
63
  * 查询模型能力声明
@@ -76,6 +80,12 @@ export declare class OpenAIProvider implements ModelProvider {
76
80
  * 检查 provider 是否可用
77
81
  */
78
82
  isAvailable(): Promise<boolean>;
83
+ /**
84
+ * 释放 transport 资源(keep-alive dispatcher 的连接池)
85
+ *
86
+ * 热更替换(gateway.registerProvider)或宿主显式收口时调用;重复调用安全。
87
+ */
88
+ dispose(): Promise<void>;
79
89
  /**
80
90
  * 构造实际发送的请求体(wire dump 观测用)
81
91
  *
@@ -17,6 +17,8 @@
17
17
  * ```
18
18
  */
19
19
  import { tokenUsageFromOpenAi } from './usage.js';
20
+ import { attachHttpStatus, attachStreamDiag, createStreamDiag, recordWireBytes, } from './provider-diagnostics.js';
21
+ import { createTimeoutDispatcher, providerFetch } from './fetch-timeout.js';
20
22
  /**
21
23
  * OpenAI 兼容 LLM Provider
22
24
  *
@@ -30,11 +32,16 @@ export class OpenAIProvider {
30
32
  baseUrl;
31
33
  defaultModel;
32
34
  timeoutMs;
35
+ /** 与 timeoutMs 对齐的 fetch dispatcher(transport 不得在配置值之下提前掐断) */
36
+ dispatcher;
37
+ /** HTTP transport(可注入替换供测试;默认 undici fetch,错误形态与内置 fetch 一致) */
38
+ fetch = providerFetch;
33
39
  constructor(config) {
34
40
  this.name = config.name ?? 'openai';
35
41
  this.apiKey = config.apiKey;
36
42
  this.baseUrl = (config.baseUrl ?? 'https://api.openai.com/v1').replace(/\/$/, '');
37
43
  this.timeoutMs = config.timeoutMs ?? 60_000;
44
+ this.dispatcher = createTimeoutDispatcher(this.timeoutMs);
38
45
  // 仅使用用户配置的 ModelInfo;不合并 builtin 猜测 contextWindow
39
46
  const rawModels = config.models ?? [];
40
47
  this.models = [];
@@ -44,11 +51,12 @@ export class OpenAIProvider {
44
51
  }
45
52
  else {
46
53
  this.models.push(entry.name);
47
- if (entry.contextWindow != null || entry.maxOutputTokens != null) {
54
+ if (entry.contextWindow != null || entry.maxOutputTokens != null || entry.temperature != null) {
48
55
  this.modelInfoMap.set(entry.name, {
49
56
  name: entry.name,
50
57
  contextWindow: entry.contextWindow,
51
58
  maxOutputTokens: entry.maxOutputTokens,
59
+ temperature: entry.temperature,
52
60
  });
53
61
  }
54
62
  }
@@ -82,18 +90,22 @@ export class OpenAIProvider {
82
90
  request.signal.addEventListener('abort', () => controller.abort(), { once: true });
83
91
  }
84
92
  try {
85
- const response = await fetch(`${this.baseUrl}/chat/completions`, {
93
+ const response = await this.fetch(`${this.baseUrl}/chat/completions`, {
86
94
  method: 'POST',
87
95
  headers: {
88
96
  'Content-Type': 'application/json',
89
- 'Authorization': `Bearer ${this.apiKey}`,
97
+ // keyless 端点(apiKey 空)不发 Authorization
98
+ ...(this.apiKey ? { 'Authorization': `Bearer ${this.apiKey}` } : {}),
90
99
  },
91
100
  body: JSON.stringify(body),
92
101
  signal: controller.signal,
102
+ dispatcher: this.dispatcher,
93
103
  });
94
104
  if (!response.ok) {
95
105
  const errorText = await response.text().catch(() => 'unknown error');
96
- throw new Error(`OpenAI API error ${response.status}: ${errorText}`);
106
+ const httpError = new Error(`OpenAI API error ${response.status}: ${errorText}`);
107
+ attachHttpStatus(httpError, response.status);
108
+ throw httpError;
97
109
  }
98
110
  const data = await response.json();
99
111
  return this.parseResponse(data);
@@ -120,14 +132,16 @@ export class OpenAIProvider {
120
132
  const connectTimer = setTimeout(() => controller.abort(), this.timeoutMs);
121
133
  let response;
122
134
  try {
123
- response = await fetch(`${this.baseUrl}/chat/completions`, {
135
+ response = await this.fetch(`${this.baseUrl}/chat/completions`, {
124
136
  method: 'POST',
125
137
  headers: {
126
138
  'Content-Type': 'application/json',
127
- 'Authorization': `Bearer ${this.apiKey}`,
139
+ // keyless 端点(apiKey 空)不发 Authorization
140
+ ...(this.apiKey ? { 'Authorization': `Bearer ${this.apiKey}` } : {}),
128
141
  },
129
142
  body: JSON.stringify(body),
130
143
  signal: controller.signal,
144
+ dispatcher: this.dispatcher,
131
145
  });
132
146
  }
133
147
  catch (err) {
@@ -138,7 +152,9 @@ export class OpenAIProvider {
138
152
  clearTimeout(connectTimer);
139
153
  if (!response.ok) {
140
154
  const errorText = await response.text().catch(() => 'unknown error');
141
- throw new Error(`OpenAI API error ${response.status}: ${errorText}`);
155
+ const httpError = new Error(`OpenAI API error ${response.status}: ${errorText}`);
156
+ attachHttpStatus(httpError, response.status);
157
+ throw httpError;
142
158
  }
143
159
  const reader = response.body?.getReader();
144
160
  if (!reader) {
@@ -146,6 +162,8 @@ export class OpenAIProvider {
146
162
  }
147
163
  const decoder = new TextDecoder();
148
164
  let buffer = '';
165
+ // 流内观测:SSE 注释保活 vs 内容 chunk 的区分是「上游活着但不产出」与「连接已死」的唯一依据
166
+ const diag = createStreamDiag();
149
167
  const lastUsage = { current: undefined };
150
168
  const lastFinishReason = { current: undefined };
151
169
  // 空闲超时:如果服务端在 timeoutMs 内没有发送数据,中断读取
@@ -163,24 +181,38 @@ export class OpenAIProvider {
163
181
  while (true) {
164
182
  const readPromise = reader.read();
165
183
  const { done, value } = await readPromise;
166
- if (done)
184
+ if (done) {
185
+ diag.sawEnd = true;
167
186
  break;
187
+ }
168
188
  resetIdleTimer();
189
+ recordWireBytes(diag, value.byteLength);
169
190
  buffer += decoder.decode(value, { stream: true });
170
191
  const lines = buffer.split('\n');
171
192
  buffer = lines.pop() ?? '';
172
193
  for (const line of lines) {
194
+ // SSE 注释行(`: keepalive`)是标准保活手段:有字节到达但不构成内容
195
+ const trimmed = line.trim();
196
+ if (trimmed.startsWith(':') && trimmed.length > 1)
197
+ diag.keepalives += 1;
173
198
  const chunks = this.parseSSELine(line, toolCallBuffers, lastUsage, lastFinishReason);
174
199
  for (const chunk of chunks) {
175
200
  if (chunk.type === 'done') {
201
+ diag.sawEnd = true;
176
202
  yield chunk;
177
203
  return;
178
204
  }
205
+ diag.contentChunks += 1;
179
206
  yield chunk;
180
207
  }
181
208
  }
182
209
  }
183
210
  }
211
+ catch (err) {
212
+ // 异常收尾把观测事实随错误带走(与 anthropic provider 对称)
213
+ attachStreamDiag(err, diag);
214
+ throw err;
215
+ }
184
216
  finally {
185
217
  if (idleTimer)
186
218
  clearTimeout(idleTimer);
@@ -190,9 +222,11 @@ export class OpenAIProvider {
190
222
  const chunks = this.parseSSELine(line, toolCallBuffers, lastUsage, lastFinishReason);
191
223
  for (const chunk of chunks) {
192
224
  if (chunk.type === 'done') {
225
+ diag.sawEnd = true;
193
226
  yield chunk;
194
227
  return;
195
228
  }
229
+ diag.contentChunks += 1;
196
230
  yield chunk;
197
231
  }
198
232
  }
@@ -204,9 +238,10 @@ export class OpenAIProvider {
204
238
  */
205
239
  async isAvailable() {
206
240
  try {
207
- const response = await fetch(`${this.baseUrl}/models`, {
241
+ const response = await this.fetch(`${this.baseUrl}/models`, {
208
242
  headers: { 'Authorization': `Bearer ${this.apiKey}` },
209
243
  signal: AbortSignal.timeout(5000),
244
+ dispatcher: this.dispatcher,
210
245
  });
211
246
  return response.ok;
212
247
  }
@@ -215,6 +250,14 @@ export class OpenAIProvider {
215
250
  }
216
251
  }
217
252
  // ================================================================
253
+ /**
254
+ * 释放 transport 资源(keep-alive dispatcher 的连接池)
255
+ *
256
+ * 热更替换(gateway.registerProvider)或宿主显式收口时调用;重复调用安全。
257
+ */
258
+ async dispose() {
259
+ await this.dispatcher.close();
260
+ }
218
261
  // 内部方法
219
262
  // ================================================================
220
263
  /**
@@ -240,11 +283,15 @@ export class OpenAIProvider {
240
283
  model: request.model ?? this.defaultModel,
241
284
  messages: this.flattenMessages(request.messages).map((msg) => this.sanitizeMessage(msg)),
242
285
  };
286
+ // maxTokens: 请求值与模型能力取较小值
287
+ const modelInfo = this.modelInfoMap.get(body.model);
243
288
  if (request.temperature !== undefined) {
244
289
  body.temperature = request.temperature;
245
290
  }
246
- // maxTokens: 请求值与模型能力取较小值
247
- const modelInfo = this.modelInfoMap.get(body.model);
291
+ else if (modelInfo?.temperature !== undefined) {
292
+ // 请求未指定时采用模型级配置;两者都未配置则不发送该参数(交给服务端默认)
293
+ body.temperature = modelInfo.temperature;
294
+ }
248
295
  const cap = modelInfo?.maxOutputTokens;
249
296
  if (request.maxTokens !== undefined) {
250
297
  body.max_tokens = cap ? Math.min(request.maxTokens, cap) : request.maxTokens;