@octopi-agent/engine 0.86.38 → 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 (218) 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/agent.js +12 -5
  21. package/dist/config-schema/context.d.ts +7 -2
  22. package/dist/config-schema/context.js +8 -0
  23. package/dist/config-schema/engine.d.ts +110 -8
  24. package/dist/config-schema/governance.d.ts +43 -1
  25. package/dist/config-schema/governance.js +160 -2
  26. package/dist/config-schema/models.d.ts +7 -4
  27. package/dist/config-schema/models.js +4 -1
  28. package/dist/config-schema/observability.d.ts +9 -0
  29. package/dist/config-schema/observability.js +29 -0
  30. package/dist/config-schema/run.d.ts +3 -0
  31. package/dist/config-schema/run.js +14 -0
  32. package/dist/config-schema/shared.d.ts +3 -0
  33. package/dist/config-schema/shared.js +12 -0
  34. package/dist/config-schema/substrate.d.ts +1 -1
  35. package/dist/config.d.ts +60 -13
  36. package/dist/config.js +81 -78
  37. package/dist/harness/activation/dispatcher.d.ts +8 -2
  38. package/dist/harness/activation/dispatcher.js +33 -5
  39. package/dist/harness/activation/inbox.d.ts +87 -0
  40. package/dist/harness/activation/inbox.js +169 -0
  41. package/dist/harness/activation/runtime.d.ts +9 -8
  42. package/dist/harness/activation/runtime.js +100 -8
  43. package/dist/harness/activation/types.d.ts +19 -0
  44. package/dist/harness/activation/types.js +2 -0
  45. package/dist/harness/agent/builder.d.ts +18 -3
  46. package/dist/harness/agent/builder.js +42 -17
  47. package/dist/harness/agent/config-bridge.d.ts +5 -0
  48. package/dist/harness/agent/config-bridge.js +7 -1
  49. package/dist/harness/agent/config-integrity.d.ts +72 -0
  50. package/dist/harness/agent/config-integrity.js +146 -0
  51. package/dist/harness/agent/tool-purpose.d.ts +9 -1
  52. package/dist/harness/agent/tool-purpose.js +11 -2
  53. package/dist/harness/agent/wire-agent-builder.js +11 -3
  54. package/dist/harness/collaboration/autonomous-subsystem/boundary/validator.d.ts +11 -1
  55. package/dist/harness/collaboration/autonomous-subsystem/boundary/validator.js +11 -1
  56. package/dist/harness/collaboration/autonomous-subsystem/loader.d.ts +13 -0
  57. package/dist/harness/collaboration/autonomous-subsystem/loader.js +16 -1
  58. package/dist/harness/collaboration/autonomous-subsystem/runtime.d.ts +4 -0
  59. package/dist/harness/collaboration/autonomous-subsystem/runtime.js +3 -1
  60. package/dist/harness/collaboration/autonomous-subsystem/think/executor.js +3 -1
  61. package/dist/harness/collaboration/delegation/child-run.js +21 -5
  62. package/dist/harness/collaboration/delegation/notifier.js +4 -3
  63. package/dist/harness/collaboration/delegation/service.js +2 -3
  64. package/dist/harness/collaboration/delegation/wiring.js +6 -5
  65. package/dist/harness/collaboration/orchestration/reflector/llm-reflector.d.ts +1 -1
  66. package/dist/harness/collaboration/orchestration/reflector/llm-reflector.js +1 -1
  67. package/dist/harness/context/capabilities/compact/engine.d.ts +30 -0
  68. package/dist/harness/context/capabilities/compact/engine.js +198 -46
  69. package/dist/harness/context/capabilities/compact/handover.d.ts +78 -0
  70. package/dist/harness/context/capabilities/compact/handover.js +107 -0
  71. package/dist/harness/context/capabilities/compact/index.d.ts +3 -1
  72. package/dist/harness/context/capabilities/compact/index.js +2 -1
  73. package/dist/harness/context/capabilities/compact/types.d.ts +30 -1
  74. package/dist/harness/context/capabilities/summary/executor.js +2 -1
  75. package/dist/harness/context/capabilities/summary/policies.js +8 -5
  76. package/dist/harness/context/constitution/default-agents.md +11 -10
  77. package/dist/harness/context/default-context-engine.d.ts +34 -4
  78. package/dist/harness/context/default-context-engine.js +198 -53
  79. package/dist/harness/context/hybrid-compressor.js +6 -0
  80. package/dist/harness/context/layer-types.d.ts +36 -0
  81. package/dist/harness/context/layer-types.js +38 -0
  82. package/dist/harness/context/llm-summarizer.d.ts +2 -8
  83. package/dist/harness/context/llm-summarizer.js +69 -91
  84. package/dist/harness/context/message-selector.js +4 -3
  85. package/dist/harness/context/root-instructions.js +1 -1
  86. package/dist/harness/context/summarize.d.ts +2 -0
  87. package/dist/harness/context/summarize.js +7 -2
  88. package/dist/harness/context/system-prompt-assembler.js +10 -4
  89. package/dist/harness/context/tool-result-aging.js +2 -2
  90. package/dist/harness/context/truncate-compressor.js +7 -0
  91. package/dist/harness/context/turn-envelope.d.ts +4 -3
  92. package/dist/harness/context/turn-envelope.js +4 -3
  93. package/dist/harness/context/types.d.ts +33 -1
  94. package/dist/harness/extension/execution-environment/dangerous-commands.d.ts +28 -0
  95. package/dist/harness/extension/execution-environment/dangerous-commands.js +129 -0
  96. package/dist/harness/extension/execution-environment/effect-policy.d.ts +133 -4
  97. package/dist/harness/extension/execution-environment/effect-policy.js +263 -14
  98. package/dist/harness/extension/execution-environment/index.d.ts +4 -2
  99. package/dist/harness/extension/execution-environment/index.js +2 -1
  100. package/dist/harness/extension/execution-environment/isolation.js +5 -1
  101. package/dist/harness/extension/execution-environment/kill-switch.d.ts +34 -0
  102. package/dist/harness/extension/execution-environment/kill-switch.js +46 -0
  103. package/dist/harness/extension/execution-environment/ops-audit.d.ts +200 -0
  104. package/dist/harness/extension/execution-environment/ops-audit.js +338 -0
  105. package/dist/harness/extension/execution-environment/privileged-exec.d.ts +158 -0
  106. package/dist/harness/extension/execution-environment/privileged-exec.js +418 -0
  107. package/dist/harness/extension/execution-environment/process-info.d.ts +180 -0
  108. package/dist/harness/extension/execution-environment/process-info.js +466 -0
  109. package/dist/harness/extension/execution-environment/process-isolation.d.ts +7 -0
  110. package/dist/harness/extension/execution-environment/process-isolation.js +9 -0
  111. package/dist/harness/extension/execution-environment/sandbox.d.ts +109 -0
  112. package/dist/harness/extension/execution-environment/sandbox.js +264 -29
  113. package/dist/harness/extension/execution-environment/tool-capabilities.d.ts +1 -1
  114. package/dist/harness/extension/execution-environment/tool-capabilities.js +6 -0
  115. package/dist/harness/extension/execution-environment/types.d.ts +19 -0
  116. package/dist/harness/extension/plugin-ecosystem/channel-types.d.ts +5 -0
  117. package/dist/harness/extension/plugin-ecosystem/tools/allowlisted-run.d.ts +6 -0
  118. package/dist/harness/extension/plugin-ecosystem/tools/allowlisted-run.js +50 -0
  119. package/dist/harness/extension/plugin-ecosystem/tools/ask-user.d.ts +4 -5
  120. package/dist/harness/extension/plugin-ecosystem/tools/ask-user.js +5 -15
  121. package/dist/harness/extension/plugin-ecosystem/tools/builtin.d.ts +3 -0
  122. package/dist/harness/extension/plugin-ecosystem/tools/builtin.js +53 -2
  123. package/dist/harness/extension/plugin-ecosystem/tools/file-search.js +10 -17
  124. package/dist/harness/extension/plugin-ecosystem/tools/git-runner.d.ts +31 -0
  125. package/dist/harness/extension/plugin-ecosystem/tools/git-runner.js +104 -0
  126. package/dist/harness/extension/plugin-ecosystem/tools/git-status-snapshot.d.ts +111 -0
  127. package/dist/harness/extension/plugin-ecosystem/tools/git-status-snapshot.js +197 -0
  128. package/dist/harness/extension/plugin-ecosystem/tools/git-tools.d.ts +8 -8
  129. package/dist/harness/extension/plugin-ecosystem/tools/git-tools.js +9 -100
  130. package/dist/harness/extension/plugin-ecosystem/tools/index.d.ts +6 -0
  131. package/dist/harness/extension/plugin-ecosystem/tools/index.js +4 -0
  132. package/dist/harness/extension/plugin-ecosystem/tools/privileged-tool.d.ts +43 -0
  133. package/dist/harness/extension/plugin-ecosystem/tools/privileged-tool.js +350 -0
  134. package/dist/harness/extension/plugin-ecosystem/tools/process-tools.d.ts +30 -0
  135. package/dist/harness/extension/plugin-ecosystem/tools/process-tools.js +137 -0
  136. package/dist/harness/governance/human-in-the-loop/decision-cache.d.ts +54 -4
  137. package/dist/harness/governance/human-in-the-loop/decision-cache.js +42 -16
  138. package/dist/harness/governance/security/temp-path.d.ts +9 -0
  139. package/dist/harness/governance/security/temp-path.js +13 -2
  140. package/dist/harness/governance/session-acl/seed-roles.js +14 -0
  141. package/dist/harness/index.d.ts +4 -0
  142. package/dist/harness/index.js +3 -0
  143. package/dist/harness/knowledge/file-identity.d.ts +8 -0
  144. package/dist/harness/knowledge/file-identity.js +26 -1
  145. package/dist/harness/knowledge/fts.js +1 -2
  146. package/dist/harness/knowledge/grounding.js +5 -5
  147. package/dist/harness/knowledge/index-store.d.ts +31 -4
  148. package/dist/harness/knowledge/index-store.js +180 -48
  149. package/dist/harness/knowledge/ingest.d.ts +115 -115
  150. package/dist/harness/knowledge/ingest.js +150 -150
  151. package/dist/harness/knowledge/knowledge-serve-child.js +1 -1
  152. package/dist/harness/knowledge/purge.js +4 -1
  153. package/dist/harness/memory/backfill-coverage.js +3 -1
  154. package/dist/harness/memory/sqlite/keyword-search.d.ts +1 -0
  155. package/dist/harness/memory/sqlite/keyword-search.js +4 -3
  156. package/dist/harness/observability/observer/hub.js +38 -1
  157. package/dist/harness/observability/observer/run-snapshot.js +1 -0
  158. package/dist/harness/observability/observer/types.d.ts +27 -0
  159. package/dist/harness/run/agent/agent.d.ts +7 -0
  160. package/dist/harness/run/agent/agent.js +23 -1
  161. package/dist/harness/run/reliability/fallback-provider.d.ts +117 -5
  162. package/dist/harness/run/reliability/fallback-provider.js +262 -22
  163. package/dist/harness/run/reliability/harness-events.d.ts +24 -1
  164. package/dist/harness/run/reliability/model-error-policy.d.ts +32 -0
  165. package/dist/harness/run/reliability/model-error-policy.js +42 -0
  166. package/dist/harness/run/reliability/provider-wrapper.js +29 -2
  167. package/dist/harness/run/reliability/refusal-guard.d.ts +20 -0
  168. package/dist/harness/run/reliability/refusal-guard.js +102 -0
  169. package/dist/harness/run/reliability/run-agent.js +231 -33
  170. package/dist/harness/run/run-guard/default-run-guard.js +1 -1
  171. package/dist/harness/run/run-scope.d.ts +31 -0
  172. package/dist/harness/run/runner.d.ts +132 -2
  173. package/dist/harness/run/runner.js +679 -60
  174. package/dist/harness/session/attachments/llm-intent.js +2 -1
  175. package/dist/harness/session/history/port.js +15 -5
  176. package/dist/harness/session/in-memory-store.d.ts +5 -0
  177. package/dist/harness/session/in-memory-store.js +33 -2
  178. package/dist/harness/session/tasks/render.d.ts +4 -1
  179. package/dist/harness/session/tasks/render.js +10 -7
  180. package/dist/harness/session/title.js +25 -9
  181. package/dist/harness/shared/events/agent-event-map.d.ts +92 -0
  182. package/dist/harness/shared/events/agent-event-map.js +7 -0
  183. package/dist/index.d.ts +6 -4
  184. package/dist/index.js +4 -3
  185. package/dist/integration/agent-runtime/channel-message-source.js +19 -1
  186. package/dist/integration/index.d.ts +2 -0
  187. package/dist/integration/index.js +1 -0
  188. package/dist/integration/observability/loop-watchdog.d.ts +56 -0
  189. package/dist/integration/observability/loop-watchdog.js +177 -0
  190. package/dist/integration/observability/metrics.d.ts +3 -0
  191. package/dist/integration/observability/metrics.js +18 -7
  192. package/dist/integration/observability/run-telemetry.d.ts +8 -0
  193. package/dist/integration/observability/run-telemetry.js +31 -8
  194. package/dist/integration/observability/trace-collector.js +26 -4
  195. package/dist/integration/observability/trace-events.d.ts +1 -0
  196. package/dist/integration/observability/trace-events.js +2 -0
  197. package/dist/integration/observability/trace-logger.js +27 -17
  198. package/dist/integration/providers/anthropic.d.ts +23 -0
  199. package/dist/integration/providers/anthropic.js +97 -12
  200. package/dist/integration/providers/fetch-timeout.d.ts +42 -0
  201. package/dist/integration/providers/fetch-timeout.js +51 -0
  202. package/dist/integration/providers/openai.d.ts +10 -0
  203. package/dist/integration/providers/openai.js +58 -11
  204. package/dist/integration/providers/provider-diagnostics.d.ts +80 -0
  205. package/dist/integration/providers/provider-diagnostics.js +89 -0
  206. package/dist/integration/providers/timeout-coherence.d.ts +52 -0
  207. package/dist/integration/providers/timeout-coherence.js +68 -0
  208. package/dist/integration/providers/wire-dump.d.ts +62 -0
  209. package/dist/integration/providers/wire-dump.js +111 -2
  210. package/dist/integration/storage/jsonl.d.ts +19 -1
  211. package/dist/integration/storage/jsonl.js +100 -4
  212. package/dist/paths.d.ts +19 -0
  213. package/dist/paths.js +38 -1
  214. package/dist/subsystems/cognition-steward/conceptualize/handler.js +1 -1
  215. package/dist/subsystems/memory-steward/backfill/handler.js +1 -1
  216. package/dist/subsystems/safety-guard/config.yaml +3 -1
  217. package/dist/subsystems/wisdom-steward/formation/handler.js +1 -1
  218. package/package.json +3 -2
@@ -30,7 +30,7 @@ async function main() {
30
30
  throw new Error('knowledge-serve-child: missing boot file path');
31
31
  }
32
32
  const raw = await readFile(bootPath, 'utf8');
33
- const boot = JSON.parse(raw.replace(/^/, ''));
33
+ const boot = JSON.parse(raw.replace(/^\uFEFF/, ''));
34
34
  try {
35
35
  await unlink(bootPath);
36
36
  }
@@ -16,8 +16,11 @@ export class KnowledgePurger {
16
16
  * 单文件 purge(合规 / 用户要求抹掉)
17
17
  */
18
18
  purgePath(sourceId, path) {
19
- this.index.purgePath(sourceId, path);
19
+ const matched = this.index.purgePath(sourceId, path);
20
20
  this.hits.clearForPath(sourceId, path);
21
+ // 别名形态命中的存储字面也要清痕(query 字面可能与存储字面不同);clear 幂等
22
+ for (const stored of matched)
23
+ this.hits.clearForPath(sourceId, stored);
21
24
  const describeStale = this.markDescribeStale(sourceId);
22
25
  return { sourceId, path, purged: true, describeStale };
23
26
  }
@@ -7,6 +7,7 @@
7
7
  */
8
8
  import { createHash } from 'node:crypto';
9
9
  import { getTextContent } from '@octopi-agent/core/types.js';
10
+ import { isHumanSpeech } from '../context/layer-types.js';
10
11
  export const DEFAULT_PREFILTER = {
11
12
  minUserTurns: 2,
12
13
  minTotalChars: 200,
@@ -76,7 +77,8 @@ export function measureSessionDensity(messages) {
76
77
  const ts = typeof m.timestamp === 'number' ? m.timestamp : 0;
77
78
  if (ts > lastTs)
78
79
  lastTs = ts;
79
- if (m.role === 'user')
80
+ // 引擎载体(turn_end/runStopped…)也是 role=user,不计真实用户轮
81
+ if (isHumanSpeech(m))
80
82
  userTurns++;
81
83
  if (m.role === 'assistant')
82
84
  assistantTurns++;
@@ -12,6 +12,7 @@ export interface KeywordFields {
12
12
  anchors?: string[] | string | null;
13
13
  evidence?: string | null;
14
14
  }
15
+ export declare const CJK_RE: RegExp;
15
16
  /**
16
17
  * 查询分词:空白/标点切分;连续 CJK 片段额外产出二元组。
17
18
  *
@@ -4,7 +4,7 @@
4
4
  * 中英混合:空格/标点切词 + CJK 二元组,扩大「技术栈 vs 技术选型」类弱重叠召回。
5
5
  * 字段权重:content > future_use/tags > evidence/anchors。
6
6
  */
7
- const CJK_RE = /[㐀-䶿一-鿿豈-﫿぀-ヿ]/;
7
+ export const CJK_RE = /[㐀-䶿一-鿿豈-﫿぀-ヿ]/;
8
8
  function isCjk(ch) {
9
9
  return CJK_RE.test(ch);
10
10
  }
@@ -190,9 +190,10 @@ export function buildKeywordLikeSql(tokens) {
190
190
  const clauses = [];
191
191
  const params = [];
192
192
  for (const token of tokens) {
193
- const like = `%${token.toLowerCase()}%`;
193
+ // LIKE 通配符转义:`_`/`%` 对用户是字面量(get_user_id 不得命中 getXuserXid)
194
+ const like = `%${token.toLowerCase().replace(/[\\%_]/g, (c) => `\\${c}`)}%`;
194
195
  for (const col of columns) {
195
- clauses.push(`${col} LIKE ?`);
196
+ clauses.push(`${col} LIKE ? ESCAPE '\\'`);
196
197
  params.push(like);
197
198
  }
198
199
  }
@@ -50,6 +50,8 @@ const TIMELINE_TYPES = new Set([
50
50
  'engine.start',
51
51
  'engine.end',
52
52
  'engine.error',
53
+ // 模型重试:排查「为什么等了这么久」时,时间线必须能看出重试发生与次数
54
+ 'engine.model_retry',
53
55
  'iteration.start',
54
56
  'turn.end',
55
57
  'tool.exec.start',
@@ -60,6 +62,7 @@ const TIMELINE_TYPES = new Set([
60
62
  'context.compact.start',
61
63
  'context.compact.end',
62
64
  'context.compact.error',
65
+ 'context.compact.summarize_fallback',
63
66
  'context.layers.assembled',
64
67
  'persona.resolve.failed',
65
68
  'injection.detected',
@@ -67,6 +70,11 @@ const TIMELINE_TYPES = new Set([
67
70
  'sensitive_data.detected',
68
71
  'security.blocked',
69
72
  'security.behavior_blocked',
73
+ 'run.timing',
74
+ // ops P0/P2:jail 意图、降级申报、配置漂移——安全事件必须落 run timeline
75
+ 'ops.jail.state',
76
+ 'ops.policy.degraded',
77
+ 'ops.config.security_changed',
70
78
  ]);
71
79
  let runSeq = 0;
72
80
  /** Hub 兜底:scope 未带 runId 时使用(生产路径应由 Runner/createRunId 提供) */
@@ -449,7 +457,19 @@ export class ObserverHub {
449
457
  record.timeline.push(node);
450
458
  const max = this.config.retention.timelineEvents;
451
459
  if (record.timeline.length > max) {
452
- record.timeline.splice(0, record.timeline.length - max);
460
+ // 淘汰优先保留 run.timing(wait/build/run 分段是 run 级指标,不能随事件淘汰丢)
461
+ const excess = record.timeline.length - max;
462
+ let removed = 0;
463
+ for (let i = 0; i < record.timeline.length && removed < excess; i++) {
464
+ if (record.timeline[i].type !== 'run.timing') {
465
+ record.timeline.splice(i, 1);
466
+ i--;
467
+ removed++;
468
+ }
469
+ }
470
+ // 全是 run.timing 时按老规矩从头裁
471
+ if (removed < excess)
472
+ record.timeline.splice(0, excess - removed);
453
473
  }
454
474
  }
455
475
  const life = record.lifecycle;
@@ -512,6 +532,7 @@ export class ObserverHub {
512
532
  const effect = record.toolEffect;
513
533
  effect.cwd = effect.cwd ?? record.scope.toolRuntime?.cwd;
514
534
  effect.isolation = effect.isolation ?? record.scope.toolRuntime?.isolation;
535
+ effect.privileged = effect.privileged ?? record.scope.toolRuntime?.privileged;
515
536
  let row = effect.tools.find((t) => t.name === toolName);
516
537
  if (!row) {
517
538
  row = { name: toolName, calls: 0, errors: 0 };
@@ -915,6 +936,21 @@ function stripLayerPayload(snapshot, payload) {
915
936
  }
916
937
  function toTimelineNode(event) {
917
938
  const data = (event.data ?? {});
939
+ // F3 计时段:turn.end 带 llmTiming(LLM 调用计时);run.timing 带 wait/build/run_end 分段
940
+ const timing = data.llmTiming ??
941
+ (event.type === 'run.timing'
942
+ ? {
943
+ stage: data.stage,
944
+ waitMs: data.waitMs,
945
+ buildMs: data.buildMs,
946
+ durMs: data.durMs,
947
+ loopEnd: data.loopEnd,
948
+ stopReason: data.stopReason,
949
+ msgs: data.msgs,
950
+ sysChars: data.sysChars,
951
+ groundingTokens: data.groundingTokens,
952
+ }
953
+ : undefined);
918
954
  return {
919
955
  type: event.type,
920
956
  timestamp: event.timestamp,
@@ -925,5 +961,6 @@ function toTimelineNode(event) {
925
961
  durationMs: typeof data.durationMs === 'number' ? data.durationMs : undefined,
926
962
  reason: (data.reason ?? data.fallbackError),
927
963
  usage: data.usage,
964
+ timing,
928
965
  };
929
966
  }
@@ -29,6 +29,7 @@ export function buildRunScopeView(input) {
29
29
  messagesCount: scope.toolRuntime.messages?.length ?? 0,
30
30
  cwd: scope.toolRuntime.cwd,
31
31
  isolation: scope.toolRuntime.isolation,
32
+ privileged: scope.toolRuntime.privileged,
32
33
  }
33
34
  : undefined,
34
35
  resolvedModel: input.resolvedModel,
@@ -236,6 +236,8 @@ export interface RunToolRuntimeView {
236
236
  messagesCount: number;
237
237
  cwd?: string;
238
238
  isolation?: string;
239
+ /** ops P4:特权部署标记(jail=none / full 档 / root·elevated)——UI 常驻 `PRIVILEGED` */
240
+ privileged?: boolean;
239
241
  }
240
242
  export interface RunScopeView {
241
243
  sessionId: string;
@@ -264,6 +266,29 @@ export interface RunTimelineEventView {
264
266
  durationMs?: number;
265
267
  reason?: string;
266
268
  usage?: import('@octopi-agent/core/types/turn.js').TokenUsage;
269
+ /** F3 计时段(turn.end 的 LLM 计时 / run.timing 的 wait/build/run_end 分段) */
270
+ timing?: {
271
+ stage?: string;
272
+ waitMs?: number;
273
+ buildMs?: number;
274
+ durMs?: number;
275
+ /** LLM 调用总耗时(turn.end.llmTiming) */
276
+ durationMs?: number;
277
+ /** LLM 调用标识(可关联 model.call.end 行) */
278
+ callId?: string;
279
+ ttftMs?: number;
280
+ reqChars?: number;
281
+ toolChars?: number;
282
+ outChars?: number;
283
+ finishReason?: string;
284
+ /** run.timing=run_end 附带 */
285
+ loopEnd?: string;
286
+ stopReason?: string;
287
+ /** run.timing=context_ready 附带(sysChars 为稳定前缀规模,E8 后不含易变快照) */
288
+ msgs?: number;
289
+ sysChars?: number;
290
+ groundingTokens?: number;
291
+ };
267
292
  }
268
293
  export interface RunLifecycleView {
269
294
  startedAt?: number;
@@ -316,6 +341,8 @@ export interface RunToolEffectView {
316
341
  runId?: string;
317
342
  cwd?: string;
318
343
  isolation?: string;
344
+ /** ops P4:特权部署标记(同 RunToolRuntimeView.privileged) */
345
+ privileged?: boolean;
319
346
  tools: Array<{
320
347
  name: string;
321
348
  calls: number;
@@ -35,6 +35,7 @@ export interface AgentOptions {
35
35
  shouldStopAfterTurn?: AgentLoopConfig['shouldStopAfterTurn'];
36
36
  onTurnComplete?: AgentLoopConfig['onTurnComplete'];
37
37
  prepareNextTurn?: AgentLoopConfig['prepareNextTurn'];
38
+ onToolUpdate?: AgentLoopConfig['onToolUpdate'];
38
39
  onError?: AgentLoopConfig['onError'];
39
40
  getSteeringMessages?: AgentLoopConfig['getSteeringMessages'];
40
41
  getFollowUpMessages?: AgentLoopConfig['getFollowUpMessages'];
@@ -159,6 +160,12 @@ export declare class Agent {
159
160
  context?: AgentContext;
160
161
  /** 本 Run 身份(sessionId/agentId/systemPrompt/toolRuntime) */
161
162
  runScope?: import('../run-scope.js').RunScope;
163
+ /** 本 Run 的 steering/followUp 接续;与实例回调组合,不改共享配置。 */
164
+ consumeMessages?: () => Promise<Message[]>;
165
+ /** 只读运行期提示(如委派状态):只进 steering 接缝,绝不经 followUp 续命。 */
166
+ steeringExtras?: () => Promise<Message[]>;
167
+ /** 本 Run 的工具部分输出通道(tool.exec.update 展示事件的发射端) */
168
+ onToolUpdate?: AgentLoopConfig['onToolUpdate'];
162
169
  /** @deprecated 旧路径:仅绑定 provider */
163
170
  model?: ModelProvider;
164
171
  /** @deprecated 旧路径:仅窗口 */
@@ -41,6 +41,7 @@ export class Agent {
41
41
  transformContext: options.transformContext,
42
42
  beforeToolCall: options.beforeToolCall,
43
43
  afterToolCall: options.afterToolCall,
44
+ onToolUpdate: options.onToolUpdate,
44
45
  shouldStopAfterTurn: options.shouldStopAfterTurn,
45
46
  onTurnComplete: options.onTurnComplete,
46
47
  prepareNextTurn: options.prepareNextTurn,
@@ -202,7 +203,28 @@ export class Agent {
202
203
  }
203
204
  const resolved = options?.resolvedModel;
204
205
  const loopModel = resolved?.provider ?? options?.model;
205
- const config = loopModel ? { ...this._config, model: loopModel } : this._config;
206
+ const config = {
207
+ ...this._config,
208
+ ...(loopModel ? { model: loopModel } : {}),
209
+ ...(options?.onToolUpdate ? { onToolUpdate: options.onToolUpdate } : {}),
210
+ ...(options?.consumeMessages || options?.steeringExtras ? (() => {
211
+ const consume = options.consumeMessages;
212
+ const extras = options.steeringExtras;
213
+ return {
214
+ getSteeringMessages: async () => [
215
+ ...(consume ? await consume() : []),
216
+ ...(extras ? await extras() : []),
217
+ ...(this._config.getSteeringMessages ? await this._config.getSteeringMessages() : []),
218
+ ],
219
+ getFollowUpMessages: async () => [
220
+ // followUp 是「续命」接缝:只喂真实输入;只读提示(ephemeral)
221
+ // 绝不能出现在这里——否则 run 会被状态快照无限续命(评审 F1)
222
+ ...((consume ? await consume() : [])).filter((m) => m.ephemeral !== true),
223
+ ...(this._config.getFollowUpMessages ? await this._config.getFollowUpMessages() : []),
224
+ ],
225
+ };
226
+ })() : {}),
227
+ };
206
228
  const context = options?.context ?? this._context;
207
229
  const runScope = {
208
230
  sessionId: options?.runScope?.sessionId ?? this._contextSessionId,
@@ -1,40 +1,152 @@
1
1
  /**
2
2
  * FallbackProvider — 模型回退提供器
3
3
  *
4
- * 包装多个 ModelProvider,按顺序尝试。
5
- * 主 provider 失败时自动切换到下一个回退 provider。
4
+ * 包装多个 ModelProvider,按顺序尝试。主 provider 失败时自动切换到下一个回退 provider。
6
5
  *
7
6
  * 使用场景:
8
7
  * - 主模型不可用(circuit breaker open、限流、超时)
9
8
  * - 主模型返回错误
10
9
  * - 跨 provider 灾备(如 OpenAI -> Anthropic)
10
+ *
11
+ * ## 单节点首块预算(2026-10-27 修复)
12
+ *
13
+ * 引擎 watchdog(core/loop/call-model.ts)把**整条链**当作一次调用计时,只认内容 chunk。
14
+ * 于是主 provider 若「连上了但长期不产首块」(上游排队 / 长 prefill,期间只发 SSE ping),
15
+ * 会独占整个 watchdog 窗口,备选模型一次机会都拿不到——实测一次 52 分钟停滞即由此而来。
16
+ *
17
+ * 因此链内每个节点各有自己的「等首个内容 chunk」预算(`attemptTtftTimeoutMs`):
18
+ * - 仅在**还有下一个候选**时生效(最后一棒没有备选可切,交给外层 watchdog 兜底)
19
+ * - 超时即 abort 该次尝试(子 AbortController,不波及父 signal),切下一节点
20
+ * - 一旦首个 chunk 产出,本次调用完全委托该节点,预算不再起作用
21
+ * (流中途的静默由外层 idle watchdog 负责,见 stream() 注释)
22
+ *
23
+ * ## 失败节点降级
24
+ *
25
+ * 超时/失败过的节点进入降级窗口(`degradeTtlMs`,缺省等于首块预算),
26
+ * 后续调用把它排到最后。这使「重试」不再是原地重撞同一节点——
27
+ * 这也是条件化重试的落地方式:重试时条件(节点顺序)确实变了。
11
28
  */
12
29
  import type { ModelProvider, LLMRequest, LLMResponse, LLMStreamChunk } from '@octopi-agent/core/interfaces/model-provider.js';
13
30
  import type { ModelInfo } from '@octopi-agent/core/types/agent-definition.js';
14
31
  import type { ModelConfig } from '../../shared/types/agent-definition.js';
32
+ /**
33
+ * 单节点等待首个内容 chunk 的默认预算(毫秒)
34
+ *
35
+ * 依据:同一时段实测备选 provider 处理同体积请求 1–16s;
36
+ * 主 provider 出现 271s / 383s 级首块延迟。90s 足以放过正常抖动,
37
+ * 又不至于让一次用户提问白白等满 watchdog 窗口。
38
+ */
39
+ export declare const DEFAULT_FALLBACK_ATTEMPT_TTFT_MS = 90000;
40
+ /**
41
+ * 单节点非流式(chat)尝试的默认预算(毫秒)
42
+ *
43
+ * chat 没有「首块」概念,预算覆盖的是**整段响应**;复用 90s 的 TTFT 值会把
44
+ * 合法的长响应(推理型模型、长输出)误判为节点故障并降级。
45
+ * 取 240s:低于 undici `bodyTimeout` 的 300s,从而能在被 undici 以
46
+ * 含糊的 `terminated` 掐断之前把控制权交回引擎、切换下一节点。
47
+ */
48
+ export declare const DEFAULT_FALLBACK_CHAT_ATTEMPT_MS = 240000;
49
+ /** 构造选项 */
50
+ export interface FallbackProviderOptions {
51
+ /** 单节点等待首个内容 chunk 的上限(仅 stream);<=0 或未提供时用 DEFAULT_FALLBACK_ATTEMPT_TTFT_MS */
52
+ attemptTtftTimeoutMs?: number;
53
+ /** 单节点非流式整响应的上限(仅 chat);<=0 或未提供时用 DEFAULT_FALLBACK_CHAT_ATTEMPT_MS */
54
+ attemptChatTimeoutMs?: number;
55
+ /** 失败节点降级窗口;缺省等于 attemptTtftTimeoutMs */
56
+ degradeTtlMs?: number;
57
+ /** 时钟注入(测试用) */
58
+ now?: () => number;
59
+ }
15
60
  /**
16
61
  * 回退感知的 ModelProvider
17
62
  *
18
63
  * 尝试主 provider,失败后按 fallbackModels 顺序尝试备选。
19
- * 每次调用独立决策,不持久化状态。
64
+ * 每个节点有独立首块预算,失败节点在降级窗口内被排到最后。
20
65
  */
21
66
  export declare class FallbackProvider implements ModelProvider {
22
67
  readonly name: string;
23
68
  readonly defaultModel?: string;
24
69
  private chain;
25
- constructor(mainProvider: ModelProvider, mainModel: string, fallbackModels: ModelConfig[], providerMap: Map<string, ModelProvider>);
70
+ private readonly attemptTtftTimeoutMs;
71
+ private readonly attemptChatTimeoutMs;
72
+ private readonly degradeTtlMs;
73
+ private readonly now;
74
+ /** 节点下标 → 降级截止时间戳 */
75
+ private readonly degradedUntil;
76
+ constructor(mainProvider: ModelProvider, mainModel: string, fallbackModels: ModelConfig[], providerMap: Map<string, ModelProvider>, options?: FallbackProviderOptions);
77
+ /**
78
+ * 本次调用的尝试顺序:未降级节点保持原相对顺序在前,降级节点在后。
79
+ *
80
+ * @returns 带原下标与「是否仍有下一候选」的尝试序列
81
+ */
82
+ private attemptOrder;
83
+ /** 标记节点失败(进入降级窗口) */
84
+ private markDegraded;
85
+ /** 标记节点恢复(成功一次即解除降级) */
86
+ private markHealthy;
87
+ /**
88
+ * 仅在「节点健康类」错误上降级
89
+ *
90
+ * 401/403(鉴权)、400(上下文超长/请求非法)、billing 等是**请求级**问题,
91
+ * 换节点不会变好;把它们算作节点故障会让主节点被无谓地排后,
92
+ * 并在下一次调用里静默换到别的模型(计费/缓存口径随之错位)。
93
+ *
94
+ * @param index - 节点下标
95
+ * @param err - 该节点的错误
96
+ */
97
+ private degradeIfNodeUnhealthy;
98
+ /**
99
+ * 由备选节点服务时留下一行可检索的提示
100
+ *
101
+ * 换模型对调用方不可见(响应里的 model 由各 provider 自填,用量/计费口径仍在主模型名下),
102
+ * 若不显式记一笔,「为什么这次的回答风格/质量变了」将无从追查。
103
+ *
104
+ * @param entry - 实际服务的节点
105
+ * @param pos - 其在本次尝试顺序中的位置(0 = 主节点)
106
+ */
107
+ private warnIfServedByFallback;
108
+ /**
109
+ * 在预算内等待一个 promise;超时则 reject 预算耗尽标记
110
+ *
111
+ * @param work - 待等待的 promise
112
+ * @param budgetMs - 预算;undefined 表示不限(最后一个候选)
113
+ * @param onTimeout - 预算耗尽时的清理动作(abort 子 signal)
114
+ * @returns work 的结果
115
+ */
116
+ private withBudget;
26
117
  chat(request: LLMRequest): Promise<LLMResponse>;
27
118
  /**
28
119
  * 流式生成回复
29
120
  *
30
- * 尝试主 provider 的 stream(),失败则按 fallbackModels 顺序尝试备选。
121
+ * 每个节点在独立首块预算内等待首个 chunk;超时切下一节点。
31
122
  *
32
123
  * 注意:一旦某个 provider 成功产出第一个 chunk,后续就完全委托给该 provider。
33
124
  * 如果该 provider 在流中途抛异常,错误会直接传递给调用方,不会触发回退。
34
125
  * 这是流式生成的固有限制——已产出的内容无法撤回。
126
+ * 流中途的静默由外层 idle watchdog 负责(它会 abort 父 signal)。
35
127
  */
36
128
  stream(request: LLMRequest): AsyncGenerator<LLMStreamChunk>;
37
129
  isAvailable(): Promise<boolean>;
38
130
  getModelInfo(modelName: string): ModelInfo | null;
39
131
  getModelInfos(): ModelInfo[];
40
132
  }
133
+ /**
134
+ * 「单节点预算耗尽」标记(观测用,与 STREAM_DIAG 同属 Symbol 通道,不影响错误分类)
135
+ *
136
+ * 定义在 harness(产生方);`integration/providers/wire-dump` 作为外层读取它落盘。
137
+ */
138
+ export declare const ATTEMPT_BUDGET_EXHAUSTED_DIAG: unique symbol;
139
+ /**
140
+ * 在错误对象上标记「单节点预算耗尽」
141
+ *
142
+ * @param err - 待标记错误
143
+ * @param budgetMs - 被耗尽的预算
144
+ */
145
+ export declare function attachAttemptBudgetExhausted(err: unknown, budgetMs: number): void;
146
+ /**
147
+ * 读取「单节点预算耗尽」标记
148
+ *
149
+ * @param err - 任意错误
150
+ * @returns 被耗尽的预算毫秒数;未标记时 undefined
151
+ */
152
+ export declare function readAttemptBudgetExhausted(err: unknown): number | undefined;