@octopi-agent/engine 0.65.0 → 0.86.38

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 (421) hide show
  1. package/LICENSE +201 -201
  2. package/NOTICE +7 -7
  3. package/README.md +64 -26
  4. package/dist/config-schema/agent.d.ts +89 -1
  5. package/dist/config-schema/agent.js +69 -0
  6. package/dist/config-schema/context.d.ts +23 -4
  7. package/dist/config-schema/context.js +28 -1
  8. package/dist/config-schema/engine.d.ts +285 -9
  9. package/dist/config-schema/engine.js +35 -3
  10. package/dist/config-schema/governance.d.ts +95 -0
  11. package/dist/config-schema/governance.js +91 -0
  12. package/dist/config-schema/models.d.ts +1 -1
  13. package/dist/config-schema/observability.d.ts +6 -0
  14. package/dist/config-schema/observability.js +16 -0
  15. package/dist/config-schema/run.d.ts +10 -0
  16. package/dist/config-schema/run.js +18 -0
  17. package/dist/config-schema/shared.d.ts +10 -0
  18. package/dist/config-schema/shared.js +10 -0
  19. package/dist/config-schema/substrate.d.ts +87 -1
  20. package/dist/config-schema/substrate.js +114 -0
  21. package/dist/config-schema/subsystems.d.ts +1 -1
  22. package/dist/config-schema/subsystems.js +2 -1
  23. package/dist/config.d.ts +249 -7
  24. package/dist/config.js +113 -3
  25. package/dist/harness/activation/compiler.js +3 -0
  26. package/dist/harness/activation/runtime.d.ts +7 -0
  27. package/dist/harness/activation/runtime.js +60 -2
  28. package/dist/harness/activation/sources/agent-signal.d.ts +11 -0
  29. package/dist/harness/activation/sources/agent-signal.js +33 -0
  30. package/dist/harness/activation/types.d.ts +6 -1
  31. package/dist/harness/agent/builder.d.ts +48 -4
  32. package/dist/harness/agent/builder.js +206 -55
  33. package/dist/harness/agent/config-bridge.d.ts +33 -25
  34. package/dist/harness/agent/config-bridge.js +83 -280
  35. package/dist/harness/agent/index.d.ts +3 -1
  36. package/dist/harness/agent/index.js +2 -1
  37. package/dist/harness/agent/tool-purpose.d.ts +38 -0
  38. package/dist/harness/agent/tool-purpose.js +118 -0
  39. package/dist/harness/agent/wire-agent-builder.d.ts +133 -0
  40. package/dist/harness/agent/wire-agent-builder.js +363 -0
  41. package/dist/harness/collaboration/autonomous-subsystem/runtime.d.ts +4 -1
  42. package/dist/harness/collaboration/autonomous-subsystem/runtime.js +14 -8
  43. package/dist/harness/collaboration/autonomous-subsystem/sense/metrics.d.ts +12 -0
  44. package/dist/harness/collaboration/autonomous-subsystem/sense/metrics.js +19 -0
  45. package/dist/harness/collaboration/autonomous-subsystem/sense/session-lifecycle-bridge.d.ts +6 -0
  46. package/dist/harness/collaboration/autonomous-subsystem/sense/session-lifecycle-bridge.js +24 -7
  47. package/dist/harness/collaboration/autonomous-subsystem/think/executor.d.ts +5 -2
  48. package/dist/harness/collaboration/autonomous-subsystem/think/executor.js +11 -3
  49. package/dist/harness/collaboration/autonomous-subsystem/think/index.d.ts +1 -1
  50. package/dist/harness/collaboration/autonomous-subsystem/think/index.js +1 -1
  51. package/dist/harness/collaboration/autonomous-subsystem/think/llm-port.d.ts +7 -4
  52. package/dist/harness/collaboration/autonomous-subsystem/think/llm-port.js +8 -9
  53. package/dist/harness/collaboration/autonomous-subsystem/think/model-resolver.d.ts +36 -10
  54. package/dist/harness/collaboration/autonomous-subsystem/think/model-resolver.js +60 -7
  55. package/dist/harness/collaboration/delegation/child-run.d.ts +144 -0
  56. package/dist/harness/collaboration/delegation/child-run.js +241 -0
  57. package/dist/harness/collaboration/delegation/index.d.ts +26 -0
  58. package/dist/harness/collaboration/delegation/index.js +25 -0
  59. package/dist/harness/collaboration/delegation/notifier.d.ts +46 -0
  60. package/dist/harness/collaboration/delegation/notifier.js +84 -0
  61. package/dist/harness/collaboration/delegation/registry-types.d.ts +200 -0
  62. package/dist/harness/collaboration/delegation/registry-types.js +61 -0
  63. package/dist/harness/collaboration/delegation/registry.d.ts +110 -0
  64. package/dist/harness/collaboration/delegation/registry.js +220 -0
  65. package/dist/harness/collaboration/delegation/service.d.ts +249 -0
  66. package/dist/harness/collaboration/delegation/service.js +499 -0
  67. package/dist/harness/collaboration/delegation/store.d.ts +155 -0
  68. package/dist/harness/collaboration/delegation/store.js +271 -0
  69. package/dist/harness/collaboration/delegation/transport.d.ts +73 -0
  70. package/dist/harness/collaboration/delegation/transport.js +61 -0
  71. package/dist/harness/collaboration/delegation/types.d.ts +231 -0
  72. package/dist/harness/collaboration/delegation/types.js +70 -0
  73. package/dist/harness/collaboration/delegation/wiring.d.ts +111 -0
  74. package/dist/harness/collaboration/delegation/wiring.js +145 -0
  75. package/dist/harness/collaboration/orchestration/index.d.ts +11 -13
  76. package/dist/harness/collaboration/orchestration/index.js +11 -11
  77. package/dist/harness/context/assembler.d.ts +2 -2
  78. package/dist/harness/context/assembler.js +12 -7
  79. package/dist/harness/context/capabilities/compact/engine.js +80 -38
  80. package/dist/harness/context/capabilities/compact/types.d.ts +12 -1
  81. package/dist/harness/context/capabilities/summary/gate.js +2 -2
  82. package/dist/harness/context/capabilities/summary/policies.js +5 -5
  83. package/dist/harness/context/capabilities/summary/registry.js +39 -24
  84. package/dist/harness/context/constitution/default-agents.md +230 -228
  85. package/dist/harness/context/default-context-engine.d.ts +101 -23
  86. package/dist/harness/context/default-context-engine.js +483 -172
  87. package/dist/harness/context/hybrid-compressor.d.ts +3 -3
  88. package/dist/harness/context/hybrid-compressor.js +18 -23
  89. package/dist/harness/context/index.d.ts +5 -1
  90. package/dist/harness/context/index.js +2 -0
  91. package/dist/harness/context/layer-health.js +3 -2
  92. package/dist/harness/context/layer-snapshot.d.ts +4 -0
  93. package/dist/harness/context/layer-snapshot.js +30 -18
  94. package/dist/harness/context/layer-types.d.ts +49 -1
  95. package/dist/harness/context/layer-types.js +72 -4
  96. package/dist/harness/context/layers.d.ts +32 -15
  97. package/dist/harness/context/layers.js +87 -71
  98. package/dist/harness/context/llm-summarizer.d.ts +15 -1
  99. package/dist/harness/context/llm-summarizer.js +107 -56
  100. package/dist/harness/context/message-selector.js +6 -2
  101. package/dist/harness/context/root-instructions.d.ts +72 -0
  102. package/dist/harness/context/root-instructions.js +227 -0
  103. package/dist/harness/context/runtime-datetime.d.ts +34 -7
  104. package/dist/harness/context/runtime-datetime.js +66 -10
  105. package/dist/harness/context/smart-router.d.ts +1 -1
  106. package/dist/harness/context/smart-router.js +1 -1
  107. package/dist/harness/context/system-prompt-assembler.d.ts +33 -0
  108. package/dist/harness/context/system-prompt-assembler.js +78 -7
  109. package/dist/harness/context/token-constants.d.ts +2 -2
  110. package/dist/harness/context/token-constants.js +2 -2
  111. package/dist/harness/context/token-estimate-fns.d.ts +1 -3
  112. package/dist/harness/context/token-estimate-fns.js +2 -4
  113. package/dist/harness/context/token-estimator.d.ts +1 -1
  114. package/dist/harness/context/token-estimator.js +14 -6
  115. package/dist/harness/context/tool-result-aging.d.ts +140 -0
  116. package/dist/harness/context/tool-result-aging.js +331 -0
  117. package/dist/harness/context/tool-result-body.d.ts +10 -0
  118. package/dist/harness/context/tool-result-body.js +27 -0
  119. package/dist/harness/context/turn-envelope.d.ts +123 -0
  120. package/dist/harness/context/turn-envelope.js +188 -0
  121. package/dist/harness/context/types.d.ts +35 -47
  122. package/dist/harness/extension/execution-environment/effect-policy.d.ts +248 -0
  123. package/dist/harness/extension/execution-environment/effect-policy.js +334 -0
  124. package/dist/harness/extension/execution-environment/index.d.ts +18 -2
  125. package/dist/harness/extension/execution-environment/index.js +11 -2
  126. package/dist/harness/extension/execution-environment/memory-undo.d.ts +101 -0
  127. package/dist/harness/extension/execution-environment/memory-undo.js +192 -0
  128. package/dist/harness/extension/execution-environment/process-isolation.d.ts +84 -0
  129. package/dist/harness/extension/execution-environment/process-isolation.js +315 -0
  130. package/dist/harness/extension/execution-environment/resource-limits.d.ts +36 -0
  131. package/dist/harness/extension/execution-environment/resource-limits.js +84 -0
  132. package/dist/harness/extension/execution-environment/sandbox.d.ts +125 -4
  133. package/dist/harness/extension/execution-environment/sandbox.js +493 -51
  134. package/dist/harness/extension/execution-environment/shell-journal.d.ts +100 -0
  135. package/dist/harness/extension/execution-environment/shell-journal.js +299 -0
  136. package/dist/harness/extension/execution-environment/tool-capabilities.d.ts +45 -0
  137. package/dist/harness/extension/execution-environment/tool-capabilities.js +126 -0
  138. package/dist/harness/extension/execution-environment/types.d.ts +67 -39
  139. package/dist/harness/extension/execution-environment/types.js +2 -2
  140. package/dist/harness/extension/execution-environment/undo-log.d.ts +203 -0
  141. package/dist/harness/extension/execution-environment/undo-log.js +627 -0
  142. package/dist/harness/extension/execution-environment/undo-merge.d.ts +40 -0
  143. package/dist/harness/extension/execution-environment/undo-merge.js +167 -0
  144. package/dist/harness/extension/plugin-ecosystem/client-tools/index.d.ts +4 -0
  145. package/dist/harness/extension/plugin-ecosystem/client-tools/index.js +3 -0
  146. package/dist/harness/extension/plugin-ecosystem/client-tools/invoke.d.ts +56 -0
  147. package/dist/harness/extension/plugin-ecosystem/client-tools/invoke.js +281 -0
  148. package/dist/harness/extension/plugin-ecosystem/client-tools/registry.d.ts +98 -0
  149. package/dist/harness/extension/plugin-ecosystem/client-tools/registry.js +250 -0
  150. package/dist/harness/extension/plugin-ecosystem/client-tools/stream.d.ts +124 -0
  151. package/dist/harness/extension/plugin-ecosystem/client-tools/stream.js +372 -0
  152. package/dist/harness/extension/plugin-ecosystem/client-tools/types.d.ts +118 -0
  153. package/dist/harness/extension/plugin-ecosystem/client-tools/types.js +8 -0
  154. package/dist/harness/extension/plugin-ecosystem/index.d.ts +1 -0
  155. package/dist/harness/extension/plugin-ecosystem/index.js +1 -0
  156. package/dist/harness/extension/plugin-ecosystem/mcp/bridge.js +2 -0
  157. package/dist/harness/extension/plugin-ecosystem/plugins/api.d.ts +1 -6
  158. package/dist/harness/extension/plugin-ecosystem/plugins/api.js +3 -8
  159. package/dist/harness/extension/plugin-ecosystem/plugins/capability.d.ts +0 -3
  160. package/dist/harness/extension/plugin-ecosystem/plugins/capability.js +0 -3
  161. package/dist/harness/extension/plugin-ecosystem/plugins/entry.d.ts +2 -10
  162. package/dist/harness/extension/plugin-ecosystem/plugins/entry.js +2 -9
  163. package/dist/harness/extension/plugin-ecosystem/plugins/index.d.ts +1 -3
  164. package/dist/harness/extension/plugin-ecosystem/plugins/index.js +1 -3
  165. package/dist/harness/extension/plugin-ecosystem/plugins/loader.d.ts +2 -4
  166. package/dist/harness/extension/plugin-ecosystem/plugins/loader.js +4 -21
  167. package/dist/harness/extension/plugin-ecosystem/plugins/manager.d.ts +3 -9
  168. package/dist/harness/extension/plugin-ecosystem/plugins/manager.js +4 -8
  169. package/dist/harness/extension/plugin-ecosystem/plugins/manifest.d.ts +1 -4
  170. package/dist/harness/extension/plugin-ecosystem/plugins/manifest.js +1 -3
  171. package/dist/harness/extension/plugin-ecosystem/skills/manager.d.ts +1 -1
  172. package/dist/harness/extension/plugin-ecosystem/skills/manager.js +1 -1
  173. package/dist/harness/extension/plugin-ecosystem/tools/allowlisted-run.d.ts +45 -0
  174. package/dist/harness/extension/plugin-ecosystem/tools/allowlisted-run.js +136 -0
  175. package/dist/harness/extension/plugin-ecosystem/tools/ask-user.js +1 -0
  176. package/dist/harness/extension/plugin-ecosystem/tools/builtin.d.ts +18 -3
  177. package/dist/harness/extension/plugin-ecosystem/tools/builtin.js +278 -82
  178. package/dist/harness/extension/plugin-ecosystem/tools/delegation.d.ts +31 -0
  179. package/dist/harness/extension/plugin-ecosystem/tools/delegation.js +291 -0
  180. package/dist/harness/extension/plugin-ecosystem/tools/document-tools.js +10 -2
  181. package/dist/harness/extension/plugin-ecosystem/tools/env-info.js +1 -0
  182. package/dist/harness/extension/plugin-ecosystem/tools/eol.d.ts +35 -0
  183. package/dist/harness/extension/plugin-ecosystem/tools/eol.js +43 -0
  184. package/dist/harness/extension/plugin-ecosystem/tools/file-edit.js +40 -9
  185. package/dist/harness/extension/plugin-ecosystem/tools/file-ops.d.ts +33 -0
  186. package/dist/harness/extension/plugin-ecosystem/tools/file-ops.js +376 -0
  187. package/dist/harness/extension/plugin-ecosystem/tools/file-search.d.ts +12 -2
  188. package/dist/harness/extension/plugin-ecosystem/tools/file-search.js +239 -61
  189. package/dist/harness/extension/plugin-ecosystem/tools/git-tools.d.ts +27 -0
  190. package/dist/harness/extension/plugin-ecosystem/tools/git-tools.js +554 -0
  191. package/dist/harness/extension/plugin-ecosystem/tools/http.d.ts +10 -6
  192. package/dist/harness/extension/plugin-ecosystem/tools/http.js +41 -47
  193. package/dist/harness/extension/plugin-ecosystem/tools/index.d.ts +2 -0
  194. package/dist/harness/extension/plugin-ecosystem/tools/index.js +2 -0
  195. package/dist/harness/extension/plugin-ecosystem/tools/knowledge.js +4 -0
  196. package/dist/harness/extension/plugin-ecosystem/tools/memory.d.ts +11 -1
  197. package/dist/harness/extension/plugin-ecosystem/tools/memory.js +39 -1
  198. package/dist/harness/extension/plugin-ecosystem/tools/package-tools.d.ts +13 -0
  199. package/dist/harness/extension/plugin-ecosystem/tools/package-tools.js +391 -0
  200. package/dist/harness/extension/plugin-ecosystem/tools/platform.d.ts +51 -2
  201. package/dist/harness/extension/plugin-ecosystem/tools/platform.js +151 -12
  202. package/dist/harness/extension/plugin-ecosystem/tools/session-history.js +2 -0
  203. package/dist/harness/extension/plugin-ecosystem/tools/tool-bus.d.ts +10 -1
  204. package/dist/harness/extension/plugin-ecosystem/tools/tool-bus.js +35 -19
  205. package/dist/harness/extension/plugin-ecosystem/tools/tool-set.d.ts +8 -0
  206. package/dist/harness/extension/plugin-ecosystem/tools/tool-set.js +5 -0
  207. package/dist/harness/extension/plugin-ecosystem/tools/web-search.js +1 -0
  208. package/dist/harness/governance/credentials/index.d.ts +1 -1
  209. package/dist/harness/governance/credentials/store.d.ts +16 -4
  210. package/dist/harness/governance/credentials/store.js +33 -6
  211. package/dist/harness/governance/credentials/types.d.ts +11 -0
  212. package/dist/harness/governance/human-in-the-loop/decision-cache.d.ts +105 -0
  213. package/dist/harness/governance/human-in-the-loop/decision-cache.js +184 -0
  214. package/dist/harness/governance/human-in-the-loop/index.d.ts +5 -5
  215. package/dist/harness/governance/human-in-the-loop/index.js +3 -3
  216. package/dist/harness/governance/human-in-the-loop/types.d.ts +7 -62
  217. package/dist/harness/governance/human-in-the-loop/types.js +6 -2
  218. package/dist/harness/governance/security/capability-enforcer.d.ts +9 -1
  219. package/dist/harness/governance/security/capability-enforcer.js +31 -8
  220. package/dist/harness/governance/security/degradation.js +5 -7
  221. package/dist/harness/governance/security/risk-evaluator.d.ts +1 -1
  222. package/dist/harness/governance/security/risk-evaluator.js +4 -82
  223. package/dist/harness/governance/security/temp-path.d.ts +41 -0
  224. package/dist/harness/governance/security/temp-path.js +117 -0
  225. package/dist/harness/governance/session-acl/index.d.ts +1 -0
  226. package/dist/harness/governance/session-acl/index.js +1 -0
  227. package/dist/harness/governance/session-acl/rights.d.ts +12 -0
  228. package/dist/harness/governance/session-acl/rights.js +89 -7
  229. package/dist/harness/governance/session-acl/seed-roles.js +9 -1
  230. package/dist/harness/governance/session-acl/service.js +21 -29
  231. package/dist/harness/governance/session-acl/tool-rights.d.ts +81 -0
  232. package/dist/harness/governance/session-acl/tool-rights.js +238 -0
  233. package/dist/harness/governance/session-acl/types.d.ts +22 -0
  234. package/dist/harness/index.d.ts +18 -15
  235. package/dist/harness/index.js +11 -7
  236. package/dist/harness/knowledge/file-index-store.js +11 -11
  237. package/dist/harness/knowledge/grounding.d.ts +2 -1
  238. package/dist/harness/knowledge/grounding.js +6 -3
  239. package/dist/harness/knowledge/index.d.ts +2 -2
  240. package/dist/harness/knowledge/index.js +1 -1
  241. package/dist/harness/knowledge/ingest.js +4 -1
  242. package/dist/harness/knowledge/job-control-state.js +4 -4
  243. package/dist/harness/knowledge/job-control.js +11 -11
  244. package/dist/harness/knowledge/membership-store.js +11 -11
  245. package/dist/harness/knowledge/network-guard.d.ts +61 -4
  246. package/dist/harness/knowledge/network-guard.js +390 -113
  247. package/dist/harness/knowledge/query-service.js +8 -8
  248. package/dist/harness/knowledge/retriever.js +1 -1
  249. package/dist/harness/knowledge/source-store.d.ts +17 -2
  250. package/dist/harness/knowledge/source-store.js +6 -5
  251. package/dist/harness/knowledge/writer-service.d.ts +2 -0
  252. package/dist/harness/knowledge/writer-service.js +14 -13
  253. package/dist/harness/memory/backfill-trigger.d.ts +2 -2
  254. package/dist/harness/memory/backfill-trigger.js +4 -4
  255. package/dist/harness/memory/cognition-decay.d.ts +36 -0
  256. package/dist/harness/memory/cognition-decay.js +55 -0
  257. package/dist/harness/memory/cognition-gates.d.ts +60 -0
  258. package/dist/harness/memory/cognition-gates.js +191 -0
  259. package/dist/harness/memory/cognition-trigger.d.ts +30 -0
  260. package/dist/harness/memory/cognition-trigger.js +41 -0
  261. package/dist/harness/memory/cognition-types.d.ts +1 -1
  262. package/dist/harness/memory/cognition.d.ts +40 -8
  263. package/dist/harness/memory/cognition.js +432 -79
  264. package/dist/harness/memory/conceptualizer.d.ts +66 -0
  265. package/dist/harness/memory/conceptualizer.js +246 -0
  266. package/dist/harness/memory/index.d.ts +17 -2
  267. package/dist/harness/memory/index.js +12 -1
  268. package/dist/harness/memory/sqlite/agent-db.d.ts +9 -0
  269. package/dist/harness/memory/sqlite/agent-db.js +120 -15
  270. package/dist/harness/memory/sqlite/cognition-store.d.ts +55 -16
  271. package/dist/harness/memory/sqlite/cognition-store.js +591 -144
  272. package/dist/harness/memory/sqlite/memory-store.d.ts +1 -0
  273. package/dist/harness/memory/sqlite/memory-store.js +14 -4
  274. package/dist/harness/memory/sqlite/wisdom-store.d.ts +33 -14
  275. package/dist/harness/memory/sqlite/wisdom-store.js +257 -44
  276. package/dist/harness/memory/store.d.ts +1 -0
  277. package/dist/harness/memory/store.js +3 -0
  278. package/dist/harness/memory/time-format.d.ts +28 -0
  279. package/dist/harness/memory/time-format.js +52 -0
  280. package/dist/harness/memory/types.d.ts +343 -16
  281. package/dist/harness/memory/types.js +49 -0
  282. package/dist/harness/memory/wisdom-formation.d.ts +101 -0
  283. package/dist/harness/memory/wisdom-formation.js +304 -0
  284. package/dist/harness/memory/wisdom-gates.d.ts +50 -0
  285. package/dist/harness/memory/wisdom-gates.js +204 -0
  286. package/dist/harness/memory/wisdom-policy.d.ts +107 -0
  287. package/dist/harness/memory/wisdom-policy.js +220 -0
  288. package/dist/harness/memory/wisdom-types.d.ts +3 -2
  289. package/dist/harness/memory/wisdom-types.js +2 -2
  290. package/dist/harness/memory/wisdom.d.ts +27 -0
  291. package/dist/harness/memory/wisdom.js +181 -0
  292. package/dist/harness/observability/observer/hub.js +23 -1
  293. package/dist/harness/observability/observer/index.d.ts +2 -2
  294. package/dist/harness/observability/observer/index.js +1 -1
  295. package/dist/harness/observability/observer/types.d.ts +57 -0
  296. package/dist/harness/observability/observer/types.js +118 -9
  297. package/dist/harness/run/agent/agent.d.ts +27 -0
  298. package/dist/harness/run/agent/agent.js +45 -0
  299. package/dist/harness/run/concurrency/tool-loop-detection-core.d.ts +1 -1
  300. package/dist/harness/run/concurrency/tool-loop-detection-core.js +1 -1
  301. package/dist/harness/run/reliability/harness-events.d.ts +4 -0
  302. package/dist/harness/run/reliability/run-agent.js +116 -20
  303. package/dist/harness/run/reliability/run-metrics-collector.d.ts +28 -2
  304. package/dist/harness/run/reliability/run-metrics-collector.js +92 -2
  305. package/dist/harness/run/run-guard/default-run-guard.d.ts +0 -5
  306. package/dist/harness/run/run-guard/default-run-guard.js +104 -44
  307. package/dist/harness/run/run-scope.d.ts +52 -0
  308. package/dist/harness/run/runner.d.ts +101 -16
  309. package/dist/harness/run/runner.js +557 -158
  310. package/dist/harness/session/attachments/llm-intent.js +17 -17
  311. package/dist/harness/session/history/port.js +1 -0
  312. package/dist/harness/session/in-memory-store.d.ts +1 -0
  313. package/dist/harness/session/in-memory-store.js +22 -1
  314. package/dist/harness/session/index.d.ts +1 -0
  315. package/dist/harness/session/index.js +1 -0
  316. package/dist/harness/session/schedules/index.d.ts +10 -0
  317. package/dist/harness/session/schedules/index.js +10 -0
  318. package/dist/harness/session/schedules/render.d.ts +13 -0
  319. package/dist/harness/session/schedules/render.js +63 -0
  320. package/dist/harness/session/schedules/service.d.ts +179 -0
  321. package/dist/harness/session/schedules/service.js +695 -0
  322. package/dist/harness/session/schedules/store.d.ts +119 -0
  323. package/dist/harness/session/schedules/store.js +323 -0
  324. package/dist/harness/session/schedules/tools.d.ts +39 -0
  325. package/dist/harness/session/schedules/tools.js +442 -0
  326. package/dist/harness/session/schedules/types.d.ts +104 -0
  327. package/dist/harness/session/schedules/types.js +97 -0
  328. package/dist/harness/session/tasks/tools.js +22 -0
  329. package/dist/harness/session/title.d.ts +86 -0
  330. package/dist/harness/session/title.js +268 -0
  331. package/dist/harness/session/types.d.ts +35 -0
  332. package/dist/harness/shared/events/agent-event-map.d.ts +21 -0
  333. package/dist/harness/shared/events/agent-event-map.js +1 -0
  334. package/dist/harness/shared/types/agent-definition.d.ts +23 -0
  335. package/dist/index.d.ts +25 -9
  336. package/dist/index.js +11 -2
  337. package/dist/integration/providers/anthropic.d.ts +10 -0
  338. package/dist/integration/providers/anthropic.js +44 -1
  339. package/dist/integration/providers/openai.d.ts +10 -0
  340. package/dist/integration/providers/openai.js +58 -2
  341. package/dist/integration/providers/wire-dump-diff.d.ts +191 -0
  342. package/dist/integration/providers/wire-dump-diff.js +351 -0
  343. package/dist/integration/providers/wire-dump.d.ts +178 -0
  344. package/dist/integration/providers/wire-dump.js +396 -0
  345. package/dist/integration/storage/jsonl.d.ts +11 -0
  346. package/dist/integration/storage/jsonl.js +148 -39
  347. package/dist/integration/storage/session-index.js +63 -8
  348. package/dist/subsystems/cognition-steward/conceptualize/SUBSYSTEM.md +43 -0
  349. package/dist/subsystems/cognition-steward/conceptualize/config.yaml +50 -0
  350. package/dist/subsystems/cognition-steward/conceptualize/handler.d.ts +9 -0
  351. package/dist/subsystems/cognition-steward/conceptualize/handler.js +125 -0
  352. package/dist/subsystems/cognition-steward/consolidate/SUBSYSTEM.md +6 -0
  353. package/dist/subsystems/cognition-steward/consolidate/config.yaml +54 -0
  354. package/dist/subsystems/cognition-steward/consolidate/handler.d.ts +12 -0
  355. package/dist/subsystems/cognition-steward/consolidate/handler.js +93 -0
  356. package/dist/subsystems/memory-steward/backfill/handler.js +9 -0
  357. package/dist/subsystems/wisdom-steward/evaluate/config.yaml +50 -0
  358. package/dist/subsystems/wisdom-steward/evaluate/handler.d.ts +18 -0
  359. package/dist/subsystems/wisdom-steward/evaluate/handler.js +91 -0
  360. package/dist/subsystems/wisdom-steward/formation/SUBSYSTEM.md +42 -0
  361. package/dist/subsystems/wisdom-steward/formation/config.yaml +54 -0
  362. package/dist/subsystems/wisdom-steward/formation/handler.d.ts +18 -0
  363. package/dist/subsystems/wisdom-steward/formation/handler.js +212 -0
  364. package/dist/subsystems/wisdom-steward/govern/config.yaml +55 -0
  365. package/dist/subsystems/wisdom-steward/govern/handler.d.ts +17 -0
  366. package/dist/subsystems/wisdom-steward/govern/handler.js +68 -0
  367. package/package.json +115 -115
  368. package/dist/harness/collaboration/multi-agent/agent-registry-types.d.ts +0 -144
  369. package/dist/harness/collaboration/multi-agent/agent-registry-types.js +0 -25
  370. package/dist/harness/collaboration/multi-agent/index.d.ts +0 -17
  371. package/dist/harness/collaboration/multi-agent/index.js +0 -15
  372. package/dist/harness/collaboration/multi-agent/process.d.ts +0 -167
  373. package/dist/harness/collaboration/multi-agent/process.js +0 -256
  374. package/dist/harness/collaboration/multi-agent/registry.d.ts +0 -36
  375. package/dist/harness/collaboration/multi-agent/registry.js +0 -137
  376. package/dist/harness/collaboration/multi-agent/swarm.d.ts +0 -135
  377. package/dist/harness/collaboration/multi-agent/swarm.js +0 -317
  378. package/dist/harness/collaboration/multi-agent/types.d.ts +0 -66
  379. package/dist/harness/collaboration/multi-agent/types.js +0 -15
  380. package/dist/harness/collaboration/orchestration/async-task-store.d.ts +0 -107
  381. package/dist/harness/collaboration/orchestration/async-task-store.js +0 -12
  382. package/dist/harness/collaboration/orchestration/async-task.d.ts +0 -156
  383. package/dist/harness/collaboration/orchestration/async-task.js +0 -359
  384. package/dist/harness/collaboration/orchestration/planner/hybrid-planner.d.ts +0 -47
  385. package/dist/harness/collaboration/orchestration/planner/hybrid-planner.js +0 -61
  386. package/dist/harness/collaboration/orchestration/planner/index.d.ts +0 -9
  387. package/dist/harness/collaboration/orchestration/planner/index.js +0 -6
  388. package/dist/harness/collaboration/orchestration/planner/llm-planner.d.ts +0 -54
  389. package/dist/harness/collaboration/orchestration/planner/llm-planner.js +0 -167
  390. package/dist/harness/collaboration/orchestration/planner/rule-planner.d.ts +0 -85
  391. package/dist/harness/collaboration/orchestration/planner/rule-planner.js +0 -175
  392. package/dist/harness/collaboration/orchestration/quality/classifier.d.ts +0 -21
  393. package/dist/harness/collaboration/orchestration/quality/classifier.js +0 -235
  394. package/dist/harness/collaboration/orchestration/quality/gate.d.ts +0 -29
  395. package/dist/harness/collaboration/orchestration/quality/gate.js +0 -409
  396. package/dist/harness/collaboration/orchestration/quality/index.d.ts +0 -9
  397. package/dist/harness/collaboration/orchestration/quality/index.js +0 -8
  398. package/dist/harness/collaboration/orchestration/quality/types.d.ts +0 -159
  399. package/dist/harness/collaboration/orchestration/quality/types.js +0 -33
  400. package/dist/harness/collaboration/orchestration/scheduler/index.d.ts +0 -5
  401. package/dist/harness/collaboration/orchestration/scheduler/index.js +0 -4
  402. package/dist/harness/collaboration/orchestration/scheduler/task-scheduler.d.ts +0 -143
  403. package/dist/harness/collaboration/orchestration/scheduler/task-scheduler.js +0 -297
  404. package/dist/harness/collaboration/orchestration/strategy/classifier.d.ts +0 -12
  405. package/dist/harness/collaboration/orchestration/strategy/classifier.js +0 -81
  406. package/dist/harness/collaboration/orchestration/strategy/index.d.ts +0 -3
  407. package/dist/harness/collaboration/orchestration/strategy/index.js +0 -2
  408. package/dist/harness/collaboration/orchestration/strategy/router.d.ts +0 -28
  409. package/dist/harness/collaboration/orchestration/strategy/router.js +0 -105
  410. package/dist/harness/collaboration/orchestration/strategy/types.d.ts +0 -49
  411. package/dist/harness/collaboration/orchestration/strategy/types.js +0 -4
  412. package/dist/harness/collaboration/orchestration/workflow/engine.d.ts +0 -86
  413. package/dist/harness/collaboration/orchestration/workflow/engine.js +0 -298
  414. package/dist/harness/collaboration/orchestration/workflow/index.d.ts +0 -9
  415. package/dist/harness/collaboration/orchestration/workflow/index.js +0 -7
  416. package/dist/harness/collaboration/orchestration/workflow/types.d.ts +0 -143
  417. package/dist/harness/collaboration/orchestration/workflow/types.js +0 -7
  418. package/dist/harness/governance/human-in-the-loop/approval-manager.d.ts +0 -32
  419. package/dist/harness/governance/human-in-the-loop/approval-manager.js +0 -93
  420. /package/dist/harness/collaboration/{multi-agent → delegation}/message-channel-types.d.ts +0 -0
  421. /package/dist/harness/collaboration/{multi-agent → delegation}/message-channel-types.js +0 -0
@@ -0,0 +1,167 @@
1
+ /**
2
+ * Turn 文件 undo 合并 — 补丁逆放(文本)/ 整文件策略(二进制)
3
+ *
4
+ * 逆放语义:把 agent 的 before→after 差分 **逆向** 打到 current 上,
5
+ * 只动仍与 after 对齐的行;用户改过/插入的行原样保留。
6
+ * 不做对称 diff3(会把「用户插行」误判成与「agent 改行」冲突)。
7
+ */
8
+ const isWin = process.platform === 'win32';
9
+ /** 是否可按文本处理 */
10
+ export function isProbablyText(buf) {
11
+ if (buf.includes(0))
12
+ return false;
13
+ try {
14
+ new TextDecoder('utf-8', { fatal: true }).decode(buf);
15
+ return true;
16
+ }
17
+ catch {
18
+ return false;
19
+ }
20
+ }
21
+ function splitLines(s) {
22
+ if (s === '')
23
+ return [];
24
+ return s.split('\n');
25
+ }
26
+ function joinLines(lines) {
27
+ return lines.join('\n');
28
+ }
29
+ function linesEqual(a, b) {
30
+ return a.length === b.length && a.every((x, i) => x === b[i]);
31
+ }
32
+ function lcsPairs(a, b) {
33
+ const n = a.length;
34
+ const m = b.length;
35
+ if (n === 0 || m === 0)
36
+ return [];
37
+ if (n * m > 4_000_000)
38
+ return [];
39
+ const dp = Array.from({ length: n + 1 }, () => new Int32Array(m + 1));
40
+ for (let i = n - 1; i >= 0; i--) {
41
+ for (let j = m - 1; j >= 0; j--) {
42
+ dp[i][j] = a[i] === b[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
43
+ }
44
+ }
45
+ const pairs = [];
46
+ let i = 0;
47
+ let j = 0;
48
+ while (i < n && j < m) {
49
+ if (a[i] === b[j]) {
50
+ pairs.push([i, j]);
51
+ i++;
52
+ j++;
53
+ }
54
+ else if (dp[i + 1][j] >= dp[i][j + 1]) {
55
+ i++;
56
+ }
57
+ else {
58
+ j++;
59
+ }
60
+ }
61
+ return pairs;
62
+ }
63
+ /** after → before 的编辑块 */
64
+ function computeEdits(after, before) {
65
+ if (linesEqual(after, before))
66
+ return [];
67
+ const pairs = lcsPairs(after, before);
68
+ const edits = [];
69
+ let ai = 0;
70
+ let bi = 0;
71
+ const flush = (aEnd, bEnd) => {
72
+ if (aEnd > ai || bEnd > bi) {
73
+ edits.push({
74
+ afterLines: after.slice(ai, aEnd),
75
+ beforeLines: before.slice(bi, bEnd),
76
+ });
77
+ }
78
+ };
79
+ for (const [a, b] of pairs) {
80
+ flush(a, b);
81
+ ai = a + 1;
82
+ bi = b + 1;
83
+ }
84
+ flush(after.length, before.length);
85
+ return edits;
86
+ }
87
+ function indexOfSlice(hay, needle, from) {
88
+ if (needle.length === 0)
89
+ return from;
90
+ for (let i = from; i + needle.length <= hay.length; i++) {
91
+ if (needle.every((line, k) => line === hay[i + k]))
92
+ return i;
93
+ }
94
+ return -1;
95
+ }
96
+ /**
97
+ * 逆放 agent overwrite(补丁逆放)。
98
+ *
99
+ * @param before - 写前文本
100
+ * @param after - 写后文本
101
+ * @param current - 磁盘现状文本
102
+ * @returns 逆放结果
103
+ */
104
+ export function reverseAgentOverwrite(before, after, current) {
105
+ if (current === after || current === before) {
106
+ return { kind: 'restored', content: before, skippedHunks: 0 };
107
+ }
108
+ const afterL = splitLines(after);
109
+ const beforeL = splitLines(before);
110
+ const currentL = splitLines(current);
111
+ const edits = computeEdits(afterL, beforeL);
112
+ if (edits.length === 0) {
113
+ return { kind: 'restored', content: before, skippedHunks: 0 };
114
+ }
115
+ const located = [];
116
+ const occupied = [];
117
+ const overlaps = (start, end) => occupied.some((o) => start < o.end && end > o.start);
118
+ for (const edit of edits) {
119
+ if (edit.afterLines.length === 0 && edit.beforeLines.length === 0)
120
+ continue;
121
+ let idx = indexOfSlice(currentL, edit.afterLines, 0);
122
+ while (idx >= 0) {
123
+ const end = idx + edit.afterLines.length;
124
+ if (!overlaps(idx, end)) {
125
+ located.push({ idx, afterLines: edit.afterLines, beforeLines: edit.beforeLines });
126
+ occupied.push({ start: idx, end });
127
+ break;
128
+ }
129
+ idx = indexOfSlice(currentL, edit.afterLines, idx + 1);
130
+ }
131
+ }
132
+ located.sort((a, b) => a.idx - b.idx);
133
+ const result = [];
134
+ let cursor = 0;
135
+ let skippedHunks = 0;
136
+ const matched = located.length;
137
+ for (const h of located) {
138
+ if (h.idx < cursor) {
139
+ skippedHunks += 1;
140
+ continue;
141
+ }
142
+ result.push(...currentL.slice(cursor, h.idx));
143
+ result.push(...h.beforeLines);
144
+ cursor = h.idx + h.afterLines.length;
145
+ }
146
+ result.push(...currentL.slice(cursor));
147
+ // 未能定位的 edit 记 skipped(用户改掉了 after 痕迹)
148
+ skippedHunks += edits.filter((e) => e.afterLines.length > 0 || e.beforeLines.length > 0).length - matched;
149
+ return { kind: 'restored', content: joinLines(result), skippedHunks: Math.max(0, skippedHunks) };
150
+ }
151
+ /** 路径比较键(Windows 忽略大小写) */
152
+ export function pathKey(p) {
153
+ const norm = p.replace(/\\/g, '/');
154
+ return isWin ? norm.toLowerCase() : norm;
155
+ }
156
+ /**
157
+ * 保留兼容入口:补丁逆放(行级)。
158
+ *
159
+ * @param after - agent 写后
160
+ * @param current - 现状
161
+ * @param before - agent 写前
162
+ * @returns 合并行;失败 null
163
+ */
164
+ export function merge3Lines(after, current, before) {
165
+ const r = reverseAgentOverwrite(joinLines(before), joinLines(after), joinLines(current));
166
+ return r.kind === 'restored' ? splitLines(r.content) : null;
167
+ }
@@ -0,0 +1,4 @@
1
+ export type { ClientToolCall, ClientToolCallId, ClientToolCallOutcome, ClientToolClientFilter, ClientToolDescriptor, ClientToolDeviceMeta, ClientToolErrorReason, ClientToolInteraction, ClientToolName, ClientToolProvider, ClientToolFileRef, ClientToolResult, ClientToolSensitivity, } from './types.js';
2
+ export { createClientTool, makeClientToolCallId, DEFAULT_CLIENT_TOOL_TIMEOUT_MS, validateClientToolArgs, validateClientToolDescriptor, validateClientToolOutcome, requireDevicePurpose, type ClientToolInvoker, type ClientToolInvokeRequest, } from './invoke.js';
3
+ export { ClientToolRegistry, type ClientToolRouteDecision, } from './registry.js';
4
+ export { ClientStreamTransport, createSinkStreamTool, createSourceStreamTool, createStreamStopTool, type ClientStreamChannel, type ClientStreamDirection, type ClientStreamEvent, type ClientStreamEventType, type ClientStreamSampleInput, type ClientStreamTransportDeps, type OpenStreamInput, type StreamDomainToolDeps, type StreamStopToolDeps, } from './stream.js';
@@ -0,0 +1,3 @@
1
+ export { createClientTool, makeClientToolCallId, DEFAULT_CLIENT_TOOL_TIMEOUT_MS, validateClientToolArgs, validateClientToolDescriptor, validateClientToolOutcome, requireDevicePurpose, } from './invoke.js';
2
+ export { ClientToolRegistry, } from './registry.js';
3
+ export { ClientStreamTransport, createSinkStreamTool, createSourceStreamTool, createStreamStopTool, } from './stream.js';
@@ -0,0 +1,56 @@
1
+ /**
2
+ * createClientTool — 把 ClientToolDescriptor 装成 RegisteredTool
3
+ *
4
+ * 与 createAskUserTool 同模式:handler 经 invoker 闭包注入,
5
+ * Host(Gateway)负责路由到客户端并等待 ClientToolCallOutcome。
6
+ *
7
+ * 返回值约定(LLM 可见):
8
+ * - ok+value → { kind:'value', data }
9
+ * - ok+asset → { kind:'asset', assetId, mime, sizeBytes, ... }
10
+ * - error → { error: reason, hint? } (显式失败,禁止空成功)
11
+ */
12
+ import type { RegisteredTool, ToolExecutionContext, ToolParameter } from '@octopi-agent/core/types/tools.js';
13
+ import type { ClientToolCallOutcome, ClientToolDescriptor } from './types.js';
14
+ export interface ClientToolInvokeRequest {
15
+ name: string;
16
+ args: Record<string, unknown>;
17
+ sessionId: string;
18
+ agentId: string;
19
+ /** 生成的 callId,Host 可用于挂 pending */
20
+ callId: string;
21
+ ttlAt: number;
22
+ /** 与 Loop toolCallId 对齐(可选;Host 可回填) */
23
+ toolCallId?: string;
24
+ runId?: string;
25
+ /** Run 中止信号;Host 应据此取消 pending */
26
+ abortSignal?: AbortSignal;
27
+ }
28
+ /** Client tool 在 LLM tool 面上的可见性(会话级) */
29
+ export type ClientToolVisibility = (sessionId: string, toolName: string) => boolean;
30
+ /**
31
+ * Host 侧执行:路由到 client、等待 UI/设备、返回结局。
32
+ */
33
+ export type ClientToolInvoker = (request: ClientToolInvokeRequest, context: ToolExecutionContext) => Promise<ClientToolCallOutcome>;
34
+ /** 默认工具等待上限(与 definition.timeoutMs 对齐) */
35
+ export declare const DEFAULT_CLIENT_TOOL_TIMEOUT_MS = 300000;
36
+ /** 生成 callId(Host 也可覆盖) */
37
+ export declare function makeClientToolCallId(): string;
38
+ /** 按 ToolParameter 校验调用参数(LLM 直呼 handler 时 ToolBus 不代验) */
39
+ export declare function validateClientToolArgs(parameters: Record<string, ToolParameter>, args: Record<string, unknown>): string | null;
40
+ /** 敏感 device 必须带 purpose(§6 红线:禁止无理由采集) */
41
+ export declare function requireDevicePurpose(descriptor: ClientToolDescriptor, args: Record<string, unknown>): string | null;
42
+ /** 注册前描述符校验(REST/插件入口防污染 tool 面) */
43
+ export declare function validateClientToolDescriptor(raw: unknown): string | null;
44
+ /** resolve 入参校验:禁止 ok 空 result / 未知 reason(§14.2 无空成功) */
45
+ export declare function validateClientToolOutcome(raw: unknown): string | null;
46
+ /**
47
+ * 创建可注册进 ToolBus 的 Client Tool
48
+ *
49
+ * @param descriptor - 客户端注册的能力契约
50
+ * @param invoker - Host 执行体(路由 + 等待 + TTL)
51
+ * @param options.timeoutMs - **仅** standalone 时作本地兜底超时;Host 路径不要传,避免双定时器
52
+ */
53
+ export declare function createClientTool(descriptor: ClientToolDescriptor, invoker: ClientToolInvoker, options?: {
54
+ timeoutMs?: number;
55
+ makeCallId?: () => string;
56
+ }): RegisteredTool;
@@ -0,0 +1,281 @@
1
+ /**
2
+ * createClientTool — 把 ClientToolDescriptor 装成 RegisteredTool
3
+ *
4
+ * 与 createAskUserTool 同模式:handler 经 invoker 闭包注入,
5
+ * Host(Gateway)负责路由到客户端并等待 ClientToolCallOutcome。
6
+ *
7
+ * 返回值约定(LLM 可见):
8
+ * - ok+value → { kind:'value', data }
9
+ * - ok+asset → { kind:'asset', assetId, mime, sizeBytes, ... }
10
+ * - error → { error: reason, hint? } (显式失败,禁止空成功)
11
+ */
12
+ /** 默认工具等待上限(与 definition.timeoutMs 对齐) */
13
+ export const DEFAULT_CLIENT_TOOL_TIMEOUT_MS = 300_000;
14
+ /** 生成 callId(Host 也可覆盖) */
15
+ export function makeClientToolCallId() {
16
+ return `ctc_${Math.random().toString(36).slice(2, 10)}${Date.now().toString(36)}`;
17
+ }
18
+ /** 按 ToolParameter 校验调用参数(LLM 直呼 handler 时 ToolBus 不代验) */
19
+ export function validateClientToolArgs(parameters, args) {
20
+ for (const [key, param] of Object.entries(parameters)) {
21
+ const value = args[key];
22
+ if (value === undefined || value === null) {
23
+ if (param.required)
24
+ return `missing required argument "${key}"`;
25
+ continue;
26
+ }
27
+ const actual = Array.isArray(value) ? 'array' : typeof value;
28
+ const expected = param.type === 'object' && actual === 'object' ? 'object' : param.type;
29
+ if (param.type === 'object' ? actual !== 'object' || Array.isArray(value) : actual !== expected) {
30
+ return `argument "${key}" must be ${param.type}, got ${actual}`;
31
+ }
32
+ if (param.enum && !param.enum.includes(value)) {
33
+ return `argument "${key}" must be one of: ${param.enum.join(', ')}`;
34
+ }
35
+ if (param.type === 'string' && typeof value === 'string') {
36
+ if (param.minLength != null && value.length < param.minLength) {
37
+ return `argument "${key}" minLength=${param.minLength}`;
38
+ }
39
+ if (param.maxLength != null && value.length > param.maxLength) {
40
+ return `argument "${key}" maxLength=${param.maxLength}`;
41
+ }
42
+ }
43
+ }
44
+ return null;
45
+ }
46
+ /** 敏感 device 必须带 purpose(§6 红线:禁止无理由采集) */
47
+ export function requireDevicePurpose(descriptor, args) {
48
+ if (descriptor.interaction !== 'device')
49
+ return null;
50
+ const sensitivity = descriptor.device?.sensitivity ?? 'personal';
51
+ if (sensitivity === 'public')
52
+ return null;
53
+ const purpose = args.purpose;
54
+ if (typeof purpose !== 'string' || purpose.trim().length === 0) {
55
+ return 'purpose is required for device tools with personal/sensitive data';
56
+ }
57
+ return null;
58
+ }
59
+ /** 注册前描述符校验(REST/插件入口防污染 tool 面) */
60
+ export function validateClientToolDescriptor(raw) {
61
+ if (!raw || typeof raw !== 'object' || Array.isArray(raw))
62
+ return 'descriptor must be an object';
63
+ const d = raw;
64
+ if (typeof d.name !== 'string' || d.name.trim().length === 0)
65
+ return 'name must be a non-empty string';
66
+ if (typeof d.description !== 'string' || d.description.trim().length === 0) {
67
+ return `descriptor "${String(d.name)}": description must be a non-empty string`;
68
+ }
69
+ if (!d.parameters || typeof d.parameters !== 'object' || Array.isArray(d.parameters)) {
70
+ return `descriptor "${d.name}": parameters must be an object`;
71
+ }
72
+ if (d.interaction != null && !['silent', 'ui', 'device'].includes(String(d.interaction))) {
73
+ return `descriptor "${d.name}": interaction must be silent|ui|device`;
74
+ }
75
+ if (d.processing != null && !['server', 'local'].includes(String(d.processing))) {
76
+ return `descriptor "${d.name}": processing must be server|local`;
77
+ }
78
+ if (d.clientFilter != null) {
79
+ if (typeof d.clientFilter !== 'object' || Array.isArray(d.clientFilter)) {
80
+ return `descriptor "${d.name}": clientFilter must be an object`;
81
+ }
82
+ const f = d.clientFilter;
83
+ if (f.platforms != null && !Array.isArray(f.platforms)) {
84
+ return `descriptor "${d.name}": clientFilter.platforms must be an array`;
85
+ }
86
+ if (f.instanceId != null && typeof f.instanceId !== 'string') {
87
+ return `descriptor "${d.name}": clientFilter.instanceId must be a string`;
88
+ }
89
+ }
90
+ if (d.stream != null) {
91
+ if (typeof d.stream !== 'object' || Array.isArray(d.stream)) {
92
+ return `descriptor "${d.name}": stream must be an object`;
93
+ }
94
+ const s = d.stream;
95
+ if (!['source', 'sink', 'stop'].includes(String(s.direction))) {
96
+ return `descriptor "${d.name}": stream.direction must be source|sink|stop`;
97
+ }
98
+ if (s.handleKey != null && typeof s.handleKey !== 'string') {
99
+ return `descriptor "${d.name}": stream.handleKey must be a string`;
100
+ }
101
+ }
102
+ if (d.device &&
103
+ typeof d.device === 'object' &&
104
+ !Array.isArray(d.device) &&
105
+ d.device.sensitivity === 'sensitive' &&
106
+ d.device.consent === 'none') {
107
+ return `descriptor "${d.name}": sensitive device must not use consent=none`;
108
+ }
109
+ return null;
110
+ }
111
+ /** resolve 入参校验:禁止 ok 空 result / 未知 reason(§14.2 无空成功) */
112
+ export function validateClientToolOutcome(raw) {
113
+ if (!raw || typeof raw !== 'object' || Array.isArray(raw))
114
+ return 'outcome must be an object';
115
+ const o = raw;
116
+ if (o.processing != null && !['server', 'local'].includes(String(o.processing))) {
117
+ return 'outcome.processing must be server|local';
118
+ }
119
+ if (o.status === 'ok') {
120
+ const result = o.result;
121
+ if (!result || typeof result !== 'object')
122
+ return 'outcome.ok requires result';
123
+ if (result.kind === 'value') {
124
+ if (!('data' in result))
125
+ return 'outcome.ok.value requires data';
126
+ return null;
127
+ }
128
+ if (result.kind === 'asset') {
129
+ if (typeof result.assetId !== 'string' || !result.assetId)
130
+ return 'asset requires assetId';
131
+ if (typeof result.mime !== 'string' || !result.mime)
132
+ return 'asset requires mime';
133
+ if (typeof result.sizeBytes !== 'number')
134
+ return 'asset requires sizeBytes';
135
+ return null;
136
+ }
137
+ return 'result.kind must be value|asset';
138
+ }
139
+ if (o.status === 'error') {
140
+ const allowed = [
141
+ 'invalid_arguments',
142
+ 'client_unavailable',
143
+ 'consent_denied',
144
+ 'permission_denied',
145
+ 'expired',
146
+ 'cancelled',
147
+ 'unsupported',
148
+ 'internal',
149
+ ];
150
+ if (typeof o.reason !== 'string' || !allowed.includes(o.reason)) {
151
+ return `outcome.error.reason must be one of: ${allowed.join(', ')}`;
152
+ }
153
+ return null;
154
+ }
155
+ return 'outcome.status must be ok|error';
156
+ }
157
+ function outcomeToLlmResult(outcome) {
158
+ if (outcome.status === 'ok') {
159
+ return toLlmSuccess(outcome.result);
160
+ }
161
+ return { error: outcome.reason, hint: outcome.hint };
162
+ }
163
+ function toLlmSuccess(result) {
164
+ if (result.kind === 'value') {
165
+ return { kind: 'value', data: result.data };
166
+ }
167
+ return {
168
+ kind: 'asset',
169
+ assetId: result.assetId,
170
+ mime: result.mime,
171
+ sizeBytes: result.sizeBytes,
172
+ name: result.name,
173
+ preview: result.preview,
174
+ };
175
+ }
176
+ /**
177
+ * 创建可注册进 ToolBus 的 Client Tool
178
+ *
179
+ * @param descriptor - 客户端注册的能力契约
180
+ * @param invoker - Host 执行体(路由 + 等待 + TTL)
181
+ * @param options.timeoutMs - **仅** standalone 时作本地兜底超时;Host 路径不要传,避免双定时器
182
+ */
183
+ export function createClientTool(descriptor, invoker, options) {
184
+ const makeCallId = options?.makeCallId ?? makeClientToolCallId;
185
+ const fallbackTimeoutMs = options?.timeoutMs;
186
+ return {
187
+ definition: {
188
+ name: descriptor.name,
189
+ description: descriptor.description,
190
+ parameters: descriptor.parameters,
191
+ // Host 负责 TTL;此处不写 timeoutMs,避免与 Host 双定时器分叉
192
+ version: descriptor.version,
193
+ requiresConfirmation: descriptor.interaction === 'device' &&
194
+ (descriptor.device?.consent ?? 'prompt') !== 'none',
195
+ },
196
+ handler: async (args, context) => {
197
+ if (context?.abortSignal?.aborted) {
198
+ return { error: 'cancelled', hint: 'aborted before client tool invoke' };
199
+ }
200
+ const sessionId = context?.sessionId;
201
+ const agentId = context?.agentId;
202
+ if (!sessionId || !agentId) {
203
+ return {
204
+ error: 'invalid_arguments',
205
+ hint: 'sessionId and agentId are required in tool context',
206
+ };
207
+ }
208
+ const argError = validateClientToolArgs(descriptor.parameters ?? {}, args);
209
+ if (argError) {
210
+ return { error: 'invalid_arguments', hint: argError };
211
+ }
212
+ const purposeError = requireDevicePurpose(descriptor, args);
213
+ if (purposeError) {
214
+ return { error: 'invalid_arguments', hint: purposeError };
215
+ }
216
+ const callId = makeCallId();
217
+ const ttlMs = fallbackTimeoutMs ?? DEFAULT_CLIENT_TOOL_TIMEOUT_MS;
218
+ const ttlAt = Date.now() + ttlMs;
219
+ const abortSignal = context?.abortSignal;
220
+ let timer;
221
+ const outcome = await new Promise((resolve, reject) => {
222
+ const cleanup = () => {
223
+ if (timer !== undefined)
224
+ clearTimeout(timer);
225
+ abortSignal?.removeEventListener('abort', onAbort);
226
+ };
227
+ const onAbort = () => {
228
+ cleanup();
229
+ resolve({
230
+ status: 'error',
231
+ reason: 'cancelled',
232
+ hint: 'run aborted while waiting for client tool',
233
+ processing: descriptor.processing ?? 'server',
234
+ });
235
+ };
236
+ if (abortSignal) {
237
+ abortSignal.addEventListener('abort', onAbort, { once: true });
238
+ if (abortSignal.aborted) {
239
+ onAbort();
240
+ return;
241
+ }
242
+ }
243
+ if (fallbackTimeoutMs !== undefined) {
244
+ timer = setTimeout(() => {
245
+ cleanup();
246
+ resolve({
247
+ status: 'error',
248
+ reason: 'expired',
249
+ hint: `client tool timed out after ${fallbackTimeoutMs}ms`,
250
+ processing: descriptor.processing ?? 'server',
251
+ });
252
+ }, fallbackTimeoutMs);
253
+ }
254
+ invoker({
255
+ name: descriptor.name,
256
+ args,
257
+ sessionId,
258
+ agentId,
259
+ callId,
260
+ ttlAt,
261
+ abortSignal,
262
+ }, context).then((value) => {
263
+ cleanup();
264
+ resolve({
265
+ ...value,
266
+ processing: value.processing ?? descriptor.processing ?? 'server',
267
+ });
268
+ }, (err) => {
269
+ cleanup();
270
+ resolve({
271
+ status: 'error',
272
+ reason: 'internal',
273
+ hint: err instanceof Error ? err.message : String(err),
274
+ processing: descriptor.processing ?? 'server',
275
+ });
276
+ });
277
+ });
278
+ return outcomeToLlmResult(outcome);
279
+ },
280
+ };
281
+ }
@@ -0,0 +1,98 @@
1
+ /**
2
+ * ClientToolRegistry — 会话内客户端能力注册表
3
+ *
4
+ * - 多个 client 可注册同名 tool;默认路由「最近活跃」,成功后 session sticky
5
+ * - `clientFilter` 可钉 platform / instance
6
+ * - 敏感 device:候选必须唯一(或 filter 钉端),否则拒绝
7
+ * - 某名字最后一家下线时,由调用方 unregister 对应 RegisteredTool
8
+ */
9
+ import type { ClientToolDescriptor, ClientToolName, ClientToolProvider } from './types.js';
10
+ export type ClientToolRouteDecision = {
11
+ ok: true;
12
+ clientInstanceId: string;
13
+ descriptor: ClientToolDescriptor;
14
+ } | {
15
+ ok: false;
16
+ reason: 'unsupported' | 'ambiguous' | 'client_unavailable';
17
+ hint?: string;
18
+ };
19
+ export declare class ClientToolRegistry {
20
+ /** sessionId → clientInstanceId → provider */
21
+ private bySession;
22
+ /** session sticky:sessionId|name → 最近成功端 */
23
+ private preferred;
24
+ /** 在线性:超过该时长未心跳的 provider 视为离线(不进 tool 面、不可路由) */
25
+ private readonly liveTtlMs;
26
+ /** 可注入时钟(测试用);默认 Date.now */
27
+ private readonly clock;
28
+ constructor(options?: {
29
+ liveTtlMs?: number;
30
+ clock?: () => number;
31
+ });
32
+ private at;
33
+ private isLive;
34
+ private stickyKey;
35
+ /** 某 tool 在 session 内成功后钉偏好端(在线期间优先) */
36
+ notePreferred(sessionId: string, name: ClientToolName, clientInstanceId: string): void;
37
+ /** 清理失效 sticky(provider 不再 live 或已不声明该 tool) */
38
+ private dropStalePreferred;
39
+ /**
40
+ * 剔除超时未心跳的 provider(在线性打底)
41
+ *
42
+ * @returns 各 session 上消失的 tool 名(可能重复)
43
+ */
44
+ expireStaleProviders(now?: number): Array<{
45
+ sessionId: string;
46
+ removedNames: ClientToolName[];
47
+ }>;
48
+ private collectNames;
49
+ /**
50
+ * 注册/更新某客户端在某会话上的能力(能力快照)
51
+ *
52
+ * @returns 本次新出现的 tool 名(调用方据此 register 进 ToolBus)
53
+ */
54
+ registerClientProviders(input: {
55
+ sessionId: string;
56
+ clientInstanceId: string;
57
+ platform?: string;
58
+ principalId?: string;
59
+ descriptors: ClientToolDescriptor[];
60
+ now?: number;
61
+ }): {
62
+ addedNames: ClientToolName[];
63
+ allNames: ClientToolName[];
64
+ };
65
+ /**
66
+ * 客户端下线/撤回能力
67
+ *
68
+ * @returns 会话中已无任何 provider 的 tool 名(调用方 unregister)
69
+ */
70
+ unregisterClientProviders(input: {
71
+ sessionId: string;
72
+ clientInstanceId: string;
73
+ }): {
74
+ removedNames: ClientToolName[];
75
+ };
76
+ /** 心跳 / 任意客户端活动:续期在线 */
77
+ touchClient(sessionId: string, clientInstanceId: string, now?: number): boolean;
78
+ /** 会话内仍在线且声明的 tool 名 */
79
+ sessionToolNames(sessionId: string, now?: number): ClientToolName[];
80
+ /** 会话内在线 provider */
81
+ listProviders(sessionId: string, now?: number): ClientToolProvider[];
82
+ /** 会话内是否有 live provider(tool 面过滤用) */
83
+ hasLiveProvider(sessionId: string, name: ClientToolName, now?: number): boolean;
84
+ /** 全局是否仍有任一 live provider(决定能否 uninstall) */
85
+ hasAnyProvider(name: ClientToolName, now?: number): boolean;
86
+ getDescriptor(sessionId: string, name: ClientToolName, now?: number): ClientToolDescriptor | undefined;
87
+ private matchesFilter;
88
+ /** 会话内某 tool 的 live 候选(已过 clientFilter) */
89
+ listCandidates(sessionId: string, name: ClientToolName, now?: number): Array<{
90
+ provider: ClientToolProvider;
91
+ descriptor: ClientToolDescriptor;
92
+ }>;
93
+ /**
94
+ * 解析执行端。仅 live provider;clientFilter → sticky → 最近活跃。
95
+ * 敏感 device:候选必须唯一,否则拒绝。
96
+ */
97
+ resolveTarget(sessionId: string, name: ClientToolName, now?: number): ClientToolRouteDecision;
98
+ }