@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
@@ -0,0 +1,87 @@
1
+ /**
2
+ * SessionInbox — 给持锁的活跃 Run 接续消息。
3
+ *
4
+ * 原 Trigger 是唤醒/重试凭证:offer 未被活跃 Run 接收时,调用方照常 dispatch;
5
+ * 被接收后由活跃 Run 在下一个合法消息边界消费,Run 关闭仍未消费/未确认
6
+ * (ack = 已入父上下文且转录同步成功)则按原 Trigger 重投。
7
+ * 本队列不是第二执行引擎——不持锁不开箱,不改写已发出的模型请求。
8
+ */
9
+ import type { AgentEvent } from '@octopi-agent/core/primitives/event-bus.js';
10
+ import type { Message } from '@octopi-agent/core/types.js';
11
+ import type { Trigger } from './types.js';
12
+ export type InboxOfferResult = 'steered' | 'dispatched' | 'duplicate';
13
+ export interface SessionInboxSignal {
14
+ agentId: string;
15
+ sessionId: string;
16
+ message: Message;
17
+ /** trigger.id / delegationId 去重;同 id 只进一次父上下文。 */
18
+ entryId?: string;
19
+ /** 真人输入优先于机器结果。 */
20
+ human?: boolean;
21
+ triggerType?: Trigger['type'];
22
+ /** 消息级模型覆盖;与活跃 Run 同模型时仍可接续(会话级选择 ≠ 显式换模型)。 */
23
+ modelOverride?: string;
24
+ modelProvider?: string;
25
+ /** 原 Trigger:Run 关闭未确认时按它重投,保留附件等完整来源。 */
26
+ trigger?: Trigger;
27
+ /** 调用方的收尾通道(频道回复捕获等);消费时由 Runner 转发事件。 */
28
+ onEvent?: (event: AgentEvent) => void;
29
+ onAdmitted?: (delivery: 'steered') => void;
30
+ }
31
+ export interface SessionInboxEntry {
32
+ readonly id: string;
33
+ readonly agentId: string;
34
+ readonly sessionId: string;
35
+ readonly message: Message;
36
+ readonly human: boolean;
37
+ readonly triggerType?: Trigger['type'];
38
+ readonly modelOverride?: string;
39
+ readonly modelProvider?: string;
40
+ readonly trigger?: Trigger;
41
+ readonly onEvent?: (event: AgentEvent) => void;
42
+ readonly receivedAt: number;
43
+ }
44
+ export interface SessionInboxRun {
45
+ readonly runId: string;
46
+ readonly inbox: SessionInbox;
47
+ readonly closed: boolean;
48
+ drain(): SessionInboxEntry[];
49
+ take(entryId: string): SessionInboxEntry | undefined;
50
+ close(): void;
51
+ }
52
+ /** Dispatcher 创建;Runner 拿锁后 open,释放锁前 close(生命周期 ⊂ session 锁)。 */
53
+ export interface SessionInboxBinding {
54
+ readonly inbox: SessionInbox;
55
+ readonly runId: string;
56
+ readonly entries: SessionInboxEntry[];
57
+ }
58
+ interface RunModelFingerprint {
59
+ model?: string;
60
+ provider?: string;
61
+ }
62
+ export declare class SessionInbox {
63
+ private readonly redispatch;
64
+ private readonly idLimit;
65
+ private readonly active;
66
+ private readonly pending;
67
+ private readonly redispatching;
68
+ private readonly owned;
69
+ private readonly delivered;
70
+ /** drain/take 出队但尚未 ack 的条目;Run 关闭未确认时回队重投(at-least-once)。 */
71
+ private readonly unacked;
72
+ constructor(redispatch: (entry: SessionInboxEntry) => void | Promise<unknown>, idLimit?: number);
73
+ /**
74
+ * 有兼容的活跃接收端才接收(返回 steered);否则调用方继续原 Trigger。
75
+ * duplicate = 同 id 已被接收或已入上下文,不得再次执行。
76
+ * 兼容性:显式换模型(≠ 活跃 Run 模型)/ 带附件输入不接续,走完整新 Run。
77
+ */
78
+ offer(signal: SessionInboxSignal): InboxOfferResult;
79
+ /** 仅 Runner 持锁后调用;同 (agent, session) 同时只有一个接收端。 */
80
+ open(sessionId: string, agentId: string, runId: string, entries: SessionInboxEntry[], runModel?: RunModelFingerprint): SessionInboxRun;
81
+ /** 消息已进父上下文且转录同步成功才调用;送达去重与 surfaced 的因果锚点。 */
82
+ ack(entry: SessionInboxEntry): void;
83
+ isDelivered(entryId: string): boolean;
84
+ /** close 重投:每个待投项独立 await;重复投递由 offer 的 delivered 检查兜底。 */
85
+ private schedule;
86
+ }
87
+ export {};
@@ -0,0 +1,169 @@
1
+ /**
2
+ * SessionInbox — 给持锁的活跃 Run 接续消息。
3
+ *
4
+ * 原 Trigger 是唤醒/重试凭证:offer 未被活跃 Run 接收时,调用方照常 dispatch;
5
+ * 被接收后由活跃 Run 在下一个合法消息边界消费,Run 关闭仍未消费/未确认
6
+ * (ack = 已入父上下文且转录同步成功)则按原 Trigger 重投。
7
+ * 本队列不是第二执行引擎——不持锁不开箱,不改写已发出的模型请求。
8
+ */
9
+ import { randomUUID } from 'node:crypto';
10
+ function keyOf(agentId, sessionId) {
11
+ return JSON.stringify([agentId, sessionId]);
12
+ }
13
+ function compareEntries(a, b) {
14
+ // 人话先于机器结果;同来源保持到达顺序。
15
+ if (a.human !== b.human)
16
+ return a.human ? -1 : 1;
17
+ return a.receivedAt - b.receivedAt;
18
+ }
19
+ export class SessionInbox {
20
+ redispatch;
21
+ idLimit;
22
+ active = new Map();
23
+ pending = new Map();
24
+ redispatching = new Map();
25
+ owned = new Set();
26
+ delivered = new Set();
27
+ /** drain/take 出队但尚未 ack 的条目;Run 关闭未确认时回队重投(at-least-once)。 */
28
+ unacked = new Map();
29
+ constructor(redispatch, idLimit = 4096) {
30
+ this.redispatch = redispatch;
31
+ this.idLimit = idLimit;
32
+ }
33
+ /**
34
+ * 有兼容的活跃接收端才接收(返回 steered);否则调用方继续原 Trigger。
35
+ * duplicate = 同 id 已被接收或已入上下文,不得再次执行。
36
+ * 兼容性:显式换模型(≠ 活跃 Run 模型)/ 带附件输入不接续,走完整新 Run。
37
+ */
38
+ offer(signal) {
39
+ const id = signal.entryId ?? signal.trigger?.id ?? `inbox-${randomUUID()}`;
40
+ if (this.owned.has(id) || this.delivered.has(id))
41
+ return 'duplicate';
42
+ const active = this.active.get(keyOf(signal.agentId, signal.sessionId));
43
+ const modelSwitch = signal.modelOverride !== undefined &&
44
+ (signal.modelOverride !== active?.runModel?.model ||
45
+ signal.modelProvider !== active?.runModel?.provider);
46
+ if (!active || modelSwitch || signal.message.metadata?.attachmentIds != null) {
47
+ return 'dispatched';
48
+ }
49
+ const entry = {
50
+ id,
51
+ agentId: signal.agentId,
52
+ sessionId: signal.sessionId,
53
+ message: signal.message,
54
+ human: signal.human ?? false,
55
+ triggerType: signal.triggerType ?? signal.trigger?.type,
56
+ modelOverride: signal.modelOverride,
57
+ modelProvider: signal.modelProvider,
58
+ trigger: signal.trigger,
59
+ onEvent: signal.onEvent,
60
+ receivedAt: Date.now(),
61
+ };
62
+ this.owned.add(id);
63
+ active.state.pending.push(entry);
64
+ signal.onAdmitted?.('steered');
65
+ return 'steered';
66
+ }
67
+ /** 仅 Runner 持锁后调用;同 (agent, session) 同时只有一个接收端。 */
68
+ open(sessionId, agentId, runId, entries, runModel) {
69
+ const key = keyOf(agentId, sessionId);
70
+ if (this.active.has(key))
71
+ throw new Error(`inbox run already open: ${key}`);
72
+ const state = {
73
+ closed: false,
74
+ pending: entries.filter((entry) => !this.delivered.has(entry.id)),
75
+ };
76
+ for (const entry of state.pending)
77
+ this.owned.add(entry.id);
78
+ this.active.set(key, { runId, runModel, state });
79
+ const claim = (entry) => {
80
+ this.unacked.set(entry.id, { entry, runId });
81
+ return entry;
82
+ };
83
+ return {
84
+ runId,
85
+ inbox: this,
86
+ get closed() {
87
+ return state.closed;
88
+ },
89
+ drain: () => state.pending.splice(0).sort(compareEntries).map(claim),
90
+ take: (entryId) => {
91
+ const index = state.pending.findIndex((entry) => entry.id === entryId);
92
+ if (index < 0)
93
+ return undefined;
94
+ const entry = state.pending.splice(index, 1)[0];
95
+ // 初始输入由本次 Run 全权负责(失败走 RUN_FAILED/上层重试),
96
+ // 不进 unacked 重投;此处释放 owned 防首同步前退出时 id 残留(评审 F8)
97
+ this.owned.delete(entry.id);
98
+ return entry;
99
+ },
100
+ close: () => {
101
+ if (state.closed)
102
+ return;
103
+ state.closed = true;
104
+ this.active.delete(key);
105
+ // 未消费(pending)+ 已取走但未确认(unacked)都按原 Trigger 重投:
106
+ // ack 只认「已入父上下文且转录同步成功」,其余一律 at-least-once。
107
+ const requeue = [...state.pending.splice(0)];
108
+ for (const [id, record] of this.unacked) {
109
+ if (record.runId !== runId)
110
+ continue;
111
+ this.unacked.delete(id);
112
+ if (this.delivered.has(id))
113
+ continue;
114
+ requeue.push(record.entry);
115
+ }
116
+ for (const entry of requeue) {
117
+ this.owned.delete(entry.id);
118
+ if (this.delivered.has(entry.id))
119
+ continue;
120
+ const queue = this.pending.get(key) ?? [];
121
+ if (!queue.some((item) => item.id === entry.id))
122
+ queue.push(entry);
123
+ this.pending.set(key, queue);
124
+ }
125
+ this.schedule(key);
126
+ },
127
+ };
128
+ }
129
+ /** 消息已进父上下文且转录同步成功才调用;送达去重与 surfaced 的因果锚点。 */
130
+ ack(entry) {
131
+ this.unacked.delete(entry.id);
132
+ this.owned.delete(entry.id);
133
+ this.delivered.add(entry.id);
134
+ while (this.delivered.size > this.idLimit) {
135
+ const oldest = this.delivered.values().next().value;
136
+ if (oldest === undefined)
137
+ break;
138
+ this.delivered.delete(oldest);
139
+ }
140
+ }
141
+ isDelivered(entryId) {
142
+ return this.delivered.has(entryId);
143
+ }
144
+ /** close 重投:每个待投项独立 await;重复投递由 offer 的 delivered 检查兜底。 */
145
+ schedule(key) {
146
+ if (this.redispatching.has(key) || !this.pending.get(key)?.length)
147
+ return;
148
+ const task = (async () => {
149
+ while (true) {
150
+ const entry = this.pending.get(key)?.shift();
151
+ if (!entry)
152
+ break;
153
+ if (!this.pending.get(key)?.length)
154
+ this.pending.delete(key);
155
+ if (this.delivered.has(entry.id))
156
+ continue;
157
+ await this.redispatch(entry);
158
+ }
159
+ })()
160
+ .catch((error) => {
161
+ console.warn(`[SessionInbox] redispatch failed: ${error instanceof Error ? error.message : String(error)}`);
162
+ })
163
+ .finally(() => {
164
+ this.redispatching.delete(key);
165
+ this.schedule(key);
166
+ });
167
+ this.redispatching.set(key, task);
168
+ }
169
+ }
@@ -7,7 +7,6 @@
7
7
  * 设计:arch/agent-runtime.md
8
8
  */
9
9
  import type { EventBus } from '@octopi-agent/core/index.js';
10
- import type { AgentEvent } from '@octopi-agent/core/primitives/event-bus.js';
11
10
  import type { AgentRouter, DispatchResult, FanoutDispatchResult, RuntimeAgent, RuntimeEventListener, Trigger, TriggerSource } from './types.js';
12
11
  export interface AgentRuntimeConfig {
13
12
  events?: EventBus;
@@ -69,16 +68,18 @@ export declare class AgentRuntime {
69
68
  on(listener: RuntimeEventListener): () => void;
70
69
  on(type: string, listener: RuntimeEventListener): () => void;
71
70
  /** 串行 dispatch 多条 Trigger */
72
- dispatchMany(triggers: Trigger[], options?: {
73
- onEvent?: (event: AgentEvent) => void;
74
- }): Promise<Array<DispatchResult | FanoutDispatchResult>>;
71
+ dispatchMany(triggers: Trigger[], options?: import('./types.js').DispatchOptions): Promise<Array<DispatchResult | FanoutDispatchResult>>;
75
72
  /**
76
- * 模型 A:await 至 Run 结束(或 skipped / failed)
73
+ * 模型 A:await 至 Run 结束(或 skipped / failed / accepted)
77
74
  * @param options.onEvent - 转发 Run 事件流(Gateway 流式广播);不变量 #6
75
+ * @param options.onDelivery - 活跃 Run 接收即回执(早于 Run 结束)
78
76
  */
79
- dispatch(trigger: Trigger, options?: {
80
- onEvent?: (event: AgentEvent) => void;
81
- }): Promise<DispatchResult | FanoutDispatchResult>;
77
+ dispatch(trigger: Trigger, options?: import('./types.js').DispatchOptions): Promise<DispatchResult | FanoutDispatchResult>;
78
+ /**
79
+ * 路由目标的活跃 inbox 接收(human 与 delegation signal 共用)。
80
+ * 仅 message / agent_signal 可接续;其余类型与带附件/换模型输入走完整新 Run。
81
+ */
82
+ private offerToTarget;
82
83
  private dispatchToTarget;
83
84
  private executeTriggers;
84
85
  private emitRuntime;
@@ -7,7 +7,7 @@
7
7
  * 设计:arch/agent-runtime.md
8
8
  */
9
9
  import { CoalesceBuffer } from './coalesce.js';
10
- import { buildRunRequest, resolveSessionId } from './compiler.js';
10
+ import { buildRunRequest, compileMessages, resolveSessionId } from './compiler.js';
11
11
  import { ExplicitRouter } from './router.js';
12
12
  import { RuntimeEvents } from './types.js';
13
13
  /**
@@ -156,8 +156,9 @@ export class AgentRuntime {
156
156
  return results;
157
157
  }
158
158
  /**
159
- * 模型 A:await 至 Run 结束(或 skipped / failed)
159
+ * 模型 A:await 至 Run 结束(或 skipped / failed / accepted)
160
160
  * @param options.onEvent - 转发 Run 事件流(Gateway 流式广播);不变量 #6
161
+ * @param options.onDelivery - 活跃 Run 接收即回执(早于 Run 结束)
161
162
  */
162
163
  async dispatch(trigger, options) {
163
164
  if (!this.started) {
@@ -183,8 +184,22 @@ export class AgentRuntime {
183
184
  });
184
185
  return { status: 'skipped', reason: 'no_agent' };
185
186
  }
187
+ // 回执恒发一次:fan-out 多 target 时首个去向生效,其余静默
188
+ //(每 target 一帧 accepted 会与 channel/web 的「一次受理」契约冲突)
189
+ let deliveryFired = false;
190
+ const deliveryOptions = options
191
+ ? {
192
+ ...options,
193
+ onDelivery: (delivery) => {
194
+ if (deliveryFired)
195
+ return;
196
+ deliveryFired = true;
197
+ options.onDelivery?.(delivery);
198
+ },
199
+ }
200
+ : undefined;
186
201
  if (targets.length === 1) {
187
- const result = await this.dispatchToTarget(trigger, targets[0], options);
202
+ const result = await this.dispatchToTarget(trigger, targets[0], deliveryOptions);
188
203
  // 单目标丢弃也必须留下 TRIGGER_DROPPED(与 fan-out 对称):
189
204
  // 「trigger 未被受理必有 dropped 事件」是委派送达回执(delegation §7.1)
190
205
  // 依赖的不变量,缺事件 = 送达回执无法证伪。受理后 run 失败走 RUN_FAILED
@@ -201,11 +216,11 @@ export class AgentRuntime {
201
216
  // fan-out:串行;聚合为 FanoutDispatchResult(ran/aborted/failed 均不静默丢弃)
202
217
  const results = [];
203
218
  for (const target of targets) {
204
- const result = await this.dispatchToTarget(trigger, target, options);
219
+ const result = await this.dispatchToTarget(trigger, target, deliveryOptions);
205
220
  results.push({ agentId: target.agentId, result });
206
221
  }
207
222
  const anyFailed = results.some((r) => r.result.status === 'failed');
208
- const anyRan = results.some((r) => r.result.status === 'ran');
223
+ const anyRan = results.some((r) => r.result.status === 'ran' || r.result.status === 'accepted');
209
224
  const allSkipped = results.every((r) => r.result.status === 'skipped');
210
225
  if (anyFailed) {
211
226
  this.emitRuntime(RuntimeEvents.TRIGGER_DROPPED, {
@@ -234,6 +249,40 @@ export class AgentRuntime {
234
249
  }
235
250
  return { status: 'skipped', reason: 'no_agent' };
236
251
  }
252
+ /**
253
+ * 路由目标的活跃 inbox 接收(human 与 delegation signal 共用)。
254
+ * 仅 message / agent_signal 可接续;其余类型与带附件/换模型输入走完整新 Run。
255
+ */
256
+ offerToTarget(trigger, target, sessionId, onEvent) {
257
+ if (!target.dispatcher.inbox)
258
+ return 'dispatched';
259
+ if (trigger.type !== 'message' && trigger.type !== 'agent_signal')
260
+ return 'dispatched';
261
+ const [compiledMessage] = compileMessages([trigger]);
262
+ const human = trigger.type === 'message' && trigger.payload.kind === 'user_message';
263
+ const delegationId = trigger.metadata?.delegationId;
264
+ return target.dispatcher.inbox.offer({
265
+ agentId: target.agentId,
266
+ sessionId,
267
+ entryId: delegationId ?? trigger.id,
268
+ triggerType: trigger.type,
269
+ human,
270
+ modelOverride: trigger.metadata?.modelOverride,
271
+ modelProvider: trigger.metadata?.modelProvider,
272
+ trigger,
273
+ onEvent,
274
+ message: compiledMessage,
275
+ onAdmitted: (delivery) => {
276
+ this.emitRuntime(RuntimeEvents.INBOX_ADMITTED, {
277
+ triggerId: trigger.id,
278
+ agentId: target.agentId,
279
+ sessionId,
280
+ delegationId,
281
+ delivery,
282
+ });
283
+ },
284
+ });
285
+ }
237
286
  async dispatchToTarget(trigger, target, options) {
238
287
  const agent = this.agents.get(target.agentId);
239
288
  if (!agent) {
@@ -243,6 +292,14 @@ export class AgentRuntime {
243
292
  ...trigger,
244
293
  sessionId: target.sessionId ?? trigger.sessionId,
245
294
  });
295
+ // 单一 offer 点:活跃 Run 接收 = 不再开新 Run(原 Trigger 不 dispatch,
296
+ // Run 关闭未消费时由 inbox 按原 Trigger 重投)
297
+ const offerResult = this.offerToTarget(trigger, agent, sessionId, options?.onEvent);
298
+ if (offerResult === 'steered' || offerResult === 'duplicate') {
299
+ options?.onDelivery?.('steered');
300
+ return { status: 'accepted', agentId: agent.agentId, sessionId, delivery: 'steered' };
301
+ }
302
+ options?.onDelivery?.('run');
246
303
  if (trigger.coalesceKey) {
247
304
  this.emitRuntime(RuntimeEvents.RUN_SCHEDULED, {
248
305
  triggerId: trigger.id,
@@ -291,15 +348,46 @@ export class AgentRuntime {
291
348
  triggerType: triggers[0]?.type,
292
349
  });
293
350
  try {
351
+ // loop 终态如实镜像到 RUN_ENDED / DispatchResult:LLM 彻底失败以
352
+ // engine.error 事件收尾(不 throw),不得记成 completed——否则事故在
353
+ // 监控与 dispatch 结果里隐身(10-27 事故同族问题)
354
+ let endReason;
355
+ let endError;
294
356
  for await (const event of agent.dispatcher.execute(request, controller.signal)) {
357
+ // 所有 Trigger(含后台 signal)共用一个 run-event 出口;调用方的
358
+ // onEvent 只承担该次 dispatch 的业务收尾,不再是后台 Run 的唯一可见通道。
359
+ this.emitRuntime(RuntimeEvents.RUN_EVENT, {
360
+ requestId: request.requestId,
361
+ triggerId: triggers[0]?.id,
362
+ triggerType: triggers[0]?.type,
363
+ // 路由键必带:gateway 按 sessionId 扇出 WS(缺则整条流式/终态链路静默落空)
364
+ agentId: agent.agentId,
365
+ sessionId,
366
+ event,
367
+ });
368
+ if (event.type === 'engine.end') {
369
+ const reason = event.data?.reason;
370
+ if (endReason !== 'error') {
371
+ // error 粘滞:合批(coalesce)里前一条 entry 失败、后一条成功时
372
+ // 不得被翻回 completed——任一 entry 失败即整体失败
373
+ endReason = reason === 'should_stop' || reason === 'aborted' ? reason : 'completed';
374
+ }
375
+ }
376
+ else if (event.type === 'engine.error') {
377
+ endReason = 'error';
378
+ const rawError = event.data?.error;
379
+ // 与 runner 同口径取 message(自定义 dispatcher 直传 Error 时不留 "Error: " 前缀)
380
+ endError = rawError instanceof Error ? rawError.message : String(rawError ?? 'Unknown error');
381
+ }
295
382
  try {
296
383
  onEvent?.(event);
297
384
  }
298
385
  catch {
299
- // 消费者(WS 广播等)异常不中断 Run
386
+ // 消费者(频道最终回复等)异常不中断 Run
300
387
  }
301
388
  }
302
- if (controller.signal.aborted) {
389
+ // error 优先于 aborted:失败与中止同刻到达时,失败不得在监控里消失
390
+ if (controller.signal.aborted && endReason !== 'error') {
303
391
  this.emitRuntime(RuntimeEvents.RUN_ENDED, {
304
392
  requestId: request.requestId,
305
393
  agentId: agent.agentId,
@@ -312,8 +400,12 @@ export class AgentRuntime {
312
400
  requestId: request.requestId,
313
401
  agentId: agent.agentId,
314
402
  sessionId,
315
- reason: 'completed',
403
+ reason: endReason ?? 'completed',
404
+ ...(endError ? { error: endError } : {}),
316
405
  });
406
+ if (endReason === 'error') {
407
+ return { status: 'failed', error: endError ?? 'unknown' };
408
+ }
317
409
  return {
318
410
  status: 'ran',
319
411
  requestId: request.requestId,
@@ -95,6 +95,17 @@ export interface RunAuditRecord {
95
95
  }
96
96
  export interface RunDispatcher {
97
97
  execute(req: RunRequest, signal?: AbortSignal): AsyncIterable<AgentEvent>;
98
+ /** 可选:活跃 Run 接续;缺省保持原 Trigger 排队语义。 */
99
+ inbox?: {
100
+ offer(signal: import('./inbox.js').SessionInboxSignal): import('./inbox.js').InboxOfferResult;
101
+ };
102
+ }
103
+ /** dispatch 调用方选项 */
104
+ export interface DispatchOptions {
105
+ /** Run 事件流转发(频道回复捕获等);不变量 #6 */
106
+ onEvent?: (event: AgentEvent) => void;
107
+ /** 活跃 Run 接收即回执(早于 Run 结束);run = 走新 Run。 */
108
+ onDelivery?: (delivery: 'steered' | 'run') => void;
98
109
  }
99
110
  export interface RouteTarget {
100
111
  agentId: string;
@@ -127,6 +138,12 @@ export type DispatchResult = {
127
138
  requestId: string;
128
139
  agentId: string;
129
140
  sessionId: string;
141
+ } | {
142
+ /** 已交活跃 Run 在下一消息边界接续(不开新 Run)。 */
143
+ status: 'accepted';
144
+ agentId: string;
145
+ sessionId: string;
146
+ delivery: 'steered';
130
147
  } | {
131
148
  status: 'skipped';
132
149
  reason: 'no_agent' | 'filtered' | 'runtime_stopped' | 'aborted';
@@ -159,6 +176,8 @@ export declare const RuntimeEvents: {
159
176
  readonly RUN_FAILED: "runtime.run.failed";
160
177
  readonly AGENT_SIGNAL_EMITTED: "runtime.agent_signal.emitted";
161
178
  readonly TRIGGER_DROPPED: "runtime.trigger.dropped";
179
+ readonly RUN_EVENT: "runtime.run.event";
180
+ readonly INBOX_ADMITTED: "runtime.inbox.admitted";
162
181
  };
163
182
  export type RuntimeEventType = (typeof RuntimeEvents)[keyof typeof RuntimeEvents];
164
183
  export interface RuntimeEvent {
@@ -12,4 +12,6 @@ export const RuntimeEvents = {
12
12
  RUN_FAILED: 'runtime.run.failed',
13
13
  AGENT_SIGNAL_EMITTED: 'runtime.agent_signal.emitted',
14
14
  TRIGGER_DROPPED: 'runtime.trigger.dropped',
15
+ RUN_EVENT: 'runtime.run.event',
16
+ INBOX_ADMITTED: 'runtime.inbox.admitted',
15
17
  };
@@ -18,7 +18,8 @@ import type { ModelProvider } from '@octopi-agent/core/interfaces/model-provider
18
18
  import { Agent } from '../run/agent/index.js';
19
19
  import type { ReliabilityConfig, ReliabilityHarness } from '../run/reliability/run-agent.js';
20
20
  import type { ContextEngine, SummarizeFunction } from '../context/types.js';
21
- import type { ErrorStrategy } from '@octopi-agent/core/interfaces/error-strategy.js';
21
+ import type { ErrorStrategy, ClassifiedError, ErrorAction, OverflowAction } from '@octopi-agent/core/interfaces/error-strategy.js';
22
+ import type { SecurityViolation, SecurityAction } from '@octopi-agent/core/security-guard.js';
22
23
  import type { RunGuard } from '@octopi-agent/core/interfaces/run-guard.js';
23
24
  import type { RunGuardConfig } from '../run/run-guard/default-run-guard.js';
24
25
  import type { Observer } from '@octopi-agent/core/interfaces/observer.js';
@@ -31,6 +32,13 @@ import { SessionAwareRunner } from '../run/runner.js';
31
32
  import type { SessionAwareRunnerConfig } from '../run/runner.js';
32
33
  import type { McpClientFactory } from '../extension/plugin-ecosystem/mcp/manager.js';
33
34
  import type { McpServerConfig, McpManager } from '../extension/plugin-ecosystem/mcp/types.js';
35
+ /** 默认错误策略(按原因分级重试 + 中止;上限见 MODEL_ERROR_MAX_ATTEMPTS) */
36
+ export declare class DefaultErrorStrategy implements ErrorStrategy {
37
+ onModelError(error: ClassifiedError, attempt: number): ErrorAction;
38
+ onToolError(error: ClassifiedError, _call: any): ErrorAction;
39
+ onContextOverflow(_tokenCount: number, _limit: number): OverflowAction;
40
+ onSecurityViolation(violation: SecurityViolation): SecurityAction;
41
+ }
34
42
  /** 工具运行时上下文提供者 */
35
43
  export interface ToolContextProvider {
36
44
  get(): {
@@ -46,6 +54,12 @@ export interface ToolContextProvider {
46
54
  pathContainment?: 'strict' | 'soft' | 'none';
47
55
  confirmEffect?: import('@octopi-agent/core/types/tools.js').ToolExecutionContext['confirmEffect'];
48
56
  effectChannel?: 'engine' | 'host-gate';
57
+ /** 提权策略(ops P3/P4,resolved;与 core ToolExecutionContext 同源) */
58
+ escalation?: import('@octopi-agent/core/types/tools.js').ToolExecutionContext['escalation'];
59
+ /** 危险命令减速带 resolved(§6;与 core ToolExecutionContext 同源) */
60
+ dangerousCommands?: import('@octopi-agent/core/types/tools.js').ToolExecutionContext['dangerousCommands'];
61
+ /** 参与者身份(SEC-2 / ops P5;与 core ToolExecutionContext 同源) */
62
+ sessionParticipants?: import('@octopi-agent/core/types/tools.js').ToolExecutionContext['sessionParticipants'];
49
63
  processLimits?: boolean;
50
64
  shellEscape?: 'deny' | 'confirm' | 'allow';
51
65
  shellJournal?: 'snapshot' | 'off';
@@ -287,6 +301,7 @@ export declare class AgentBuilder {
287
301
  * 设置 Skill 目录(子目录内含 SKILL.md)
288
302
  *
289
303
  * build 时 discover,每轮以索引形式注入 system prompt(formatForPrompt)。
304
+ * `~` 形态在此展开(与 workspace / agentHome 同规,幂等)。
290
305
  */
291
306
  skillDirectory(dir: string): this;
292
307
  /** 直接注入 SkillManager(跳过目录 discover) */
@@ -421,9 +436,9 @@ export declare class AgentBuilder {
421
436
  /** 加载 persona 目录 */
422
437
  persona(workspace: string): this;
423
438
  persona(...workspaces: string[]): this;
424
- /** 设置 Agent 沙箱工作目录(注入到内置工具的 cwd) */
439
+ /** 设置 Agent 沙箱工作目录(注入到内置工具的 cwd);`~` 形态在此展开(trim → expand) */
425
440
  workspace(dir: string): this;
426
- /** agent 文件态 home:extract 落盘、与 persona 目录解耦 */
441
+ /** agent 文件态 home:extract 落盘、与 persona 目录解耦;`~` 形态在此展开(与 workspace 同规) */
427
442
  agentHome(dir: string): this;
428
443
  /** 逻辑 agentId(extract pending 扫描 / 观测) */
429
444
  agentId(id: string): this;