network-ai 4.15.3 → 5.1.0

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 (282) hide show
  1. package/INTEGRATION_GUIDE.md +12 -5
  2. package/QUICKSTART.md +32 -5
  3. package/README.md +42 -17
  4. package/bin/dashboard.ts +146 -0
  5. package/bin/mcp-server.ts +3 -2
  6. package/dist/adapters/adapter-registry.d.ts +33 -1
  7. package/dist/adapters/adapter-registry.d.ts.map +1 -1
  8. package/dist/adapters/adapter-registry.js +49 -0
  9. package/dist/adapters/adapter-registry.js.map +1 -1
  10. package/dist/adapters/anthropic-computer-use-adapter.d.ts +132 -0
  11. package/dist/adapters/anthropic-computer-use-adapter.d.ts.map +1 -0
  12. package/dist/adapters/anthropic-computer-use-adapter.js +180 -0
  13. package/dist/adapters/anthropic-computer-use-adapter.js.map +1 -0
  14. package/dist/adapters/browser-agent-adapter.d.ts +121 -0
  15. package/dist/adapters/browser-agent-adapter.d.ts.map +1 -0
  16. package/dist/adapters/browser-agent-adapter.js +219 -0
  17. package/dist/adapters/browser-agent-adapter.js.map +1 -0
  18. package/dist/adapters/copilot-adapter.d.ts +59 -0
  19. package/dist/adapters/copilot-adapter.d.ts.map +1 -0
  20. package/dist/adapters/copilot-adapter.js +132 -0
  21. package/dist/adapters/copilot-adapter.js.map +1 -0
  22. package/dist/adapters/custom-adapter.d.ts +1 -1
  23. package/dist/adapters/custom-adapter.js +1 -1
  24. package/dist/adapters/index.d.ts +17 -1
  25. package/dist/adapters/index.d.ts.map +1 -1
  26. package/dist/adapters/index.js +25 -1
  27. package/dist/adapters/index.js.map +1 -1
  28. package/dist/adapters/langchain-adapter.js +1 -1
  29. package/dist/adapters/langchain-adapter.js.map +1 -1
  30. package/dist/adapters/langgraph-adapter.d.ts +70 -0
  31. package/dist/adapters/langgraph-adapter.d.ts.map +1 -0
  32. package/dist/adapters/langgraph-adapter.js +119 -0
  33. package/dist/adapters/langgraph-adapter.js.map +1 -0
  34. package/dist/adapters/mcp-adapter.d.ts +1 -1
  35. package/dist/adapters/mcp-adapter.js +3 -3
  36. package/dist/adapters/mcp-adapter.js.map +1 -1
  37. package/dist/adapters/openai-agents-adapter.d.ts +100 -0
  38. package/dist/adapters/openai-agents-adapter.d.ts.map +1 -0
  39. package/dist/adapters/openai-agents-adapter.js +118 -0
  40. package/dist/adapters/openai-agents-adapter.js.map +1 -0
  41. package/dist/adapters/openclaw-adapter.d.ts +1 -1
  42. package/dist/adapters/openclaw-adapter.js +3 -3
  43. package/dist/adapters/openclaw-adapter.js.map +1 -1
  44. package/dist/adapters/orchestrator-adapter.d.ts +118 -0
  45. package/dist/adapters/orchestrator-adapter.d.ts.map +1 -0
  46. package/dist/adapters/orchestrator-adapter.js +219 -0
  47. package/dist/adapters/orchestrator-adapter.js.map +1 -0
  48. package/dist/adapters/pydantic-ai-adapter.d.ts +104 -0
  49. package/dist/adapters/pydantic-ai-adapter.d.ts.map +1 -0
  50. package/dist/adapters/pydantic-ai-adapter.js +163 -0
  51. package/dist/adapters/pydantic-ai-adapter.js.map +1 -0
  52. package/dist/adapters/vertex-ai-adapter.d.ts +122 -0
  53. package/dist/adapters/vertex-ai-adapter.d.ts.map +1 -0
  54. package/dist/adapters/vertex-ai-adapter.js +166 -0
  55. package/dist/adapters/vertex-ai-adapter.js.map +1 -0
  56. package/dist/bin/dashboard.d.ts +11 -0
  57. package/dist/bin/dashboard.d.ts.map +1 -0
  58. package/dist/bin/dashboard.js +135 -0
  59. package/dist/bin/dashboard.js.map +1 -0
  60. package/dist/bin/mcp-server.js +3 -2
  61. package/dist/bin/mcp-server.js.map +1 -1
  62. package/dist/demo-control-plane.d.ts +12 -0
  63. package/dist/demo-control-plane.d.ts.map +1 -0
  64. package/dist/demo-control-plane.js +147 -0
  65. package/dist/demo-control-plane.js.map +1 -0
  66. package/dist/demo-worktree-dashboard.d.ts +2 -0
  67. package/dist/demo-worktree-dashboard.d.ts.map +1 -0
  68. package/dist/demo-worktree-dashboard.js +131 -0
  69. package/dist/demo-worktree-dashboard.js.map +1 -0
  70. package/dist/examples/01-hello-swarm.d.ts +13 -0
  71. package/dist/examples/01-hello-swarm.d.ts.map +1 -0
  72. package/dist/examples/01-hello-swarm.js +165 -0
  73. package/dist/examples/01-hello-swarm.js.map +1 -0
  74. package/dist/examples/02-fsm-pipeline.d.ts +20 -0
  75. package/dist/examples/02-fsm-pipeline.d.ts.map +1 -0
  76. package/dist/examples/02-fsm-pipeline.js +189 -0
  77. package/dist/examples/02-fsm-pipeline.js.map +1 -0
  78. package/dist/examples/03-parallel-agents.d.ts +21 -0
  79. package/dist/examples/03-parallel-agents.d.ts.map +1 -0
  80. package/dist/examples/03-parallel-agents.js +192 -0
  81. package/dist/examples/03-parallel-agents.js.map +1 -0
  82. package/dist/examples/05-code-review-swarm.d.ts +21 -0
  83. package/dist/examples/05-code-review-swarm.d.ts.map +1 -0
  84. package/dist/examples/05-code-review-swarm.js +1177 -0
  85. package/dist/examples/05-code-review-swarm.js.map +1 -0
  86. package/dist/examples/06-ai-pipeline-demo.d.ts +24 -0
  87. package/dist/examples/06-ai-pipeline-demo.d.ts.map +1 -0
  88. package/dist/examples/06-ai-pipeline-demo.js +263 -0
  89. package/dist/examples/06-ai-pipeline-demo.js.map +1 -0
  90. package/dist/examples/07-full-showcase.d.ts +27 -0
  91. package/dist/examples/07-full-showcase.d.ts.map +1 -0
  92. package/dist/examples/07-full-showcase.js +946 -0
  93. package/dist/examples/07-full-showcase.js.map +1 -0
  94. package/dist/examples/08-control-plane-stress-demo.d.ts +19 -0
  95. package/dist/examples/08-control-plane-stress-demo.d.ts.map +1 -0
  96. package/dist/examples/08-control-plane-stress-demo.js +186 -0
  97. package/dist/examples/08-control-plane-stress-demo.js.map +1 -0
  98. package/dist/examples/09-real-langchain.d.ts +19 -0
  99. package/dist/examples/09-real-langchain.d.ts.map +1 -0
  100. package/dist/examples/09-real-langchain.js +231 -0
  101. package/dist/examples/09-real-langchain.js.map +1 -0
  102. package/dist/examples/10-nemoclaw-sandbox-swarm.d.ts +16 -0
  103. package/dist/examples/10-nemoclaw-sandbox-swarm.d.ts.map +1 -0
  104. package/dist/examples/10-nemoclaw-sandbox-swarm.js +270 -0
  105. package/dist/examples/10-nemoclaw-sandbox-swarm.js.map +1 -0
  106. package/dist/examples/demo-runner.d.ts +2 -0
  107. package/dist/examples/demo-runner.d.ts.map +1 -0
  108. package/dist/examples/demo-runner.js +119 -0
  109. package/dist/examples/demo-runner.js.map +1 -0
  110. package/dist/index.d.ts +113 -559
  111. package/dist/index.d.ts.map +1 -1
  112. package/dist/index.js +310 -1074
  113. package/dist/index.js.map +1 -1
  114. package/dist/lib/adapter-test-harness.d.ts +88 -0
  115. package/dist/lib/adapter-test-harness.d.ts.map +1 -0
  116. package/dist/lib/adapter-test-harness.js +118 -0
  117. package/dist/lib/adapter-test-harness.js.map +1 -0
  118. package/dist/lib/agent-conversation.d.ts +115 -0
  119. package/dist/lib/agent-conversation.d.ts.map +1 -0
  120. package/dist/lib/agent-conversation.js +155 -0
  121. package/dist/lib/agent-conversation.js.map +1 -0
  122. package/dist/lib/agent-debate.d.ts +115 -0
  123. package/dist/lib/agent-debate.d.ts.map +1 -0
  124. package/dist/lib/agent-debate.js +146 -0
  125. package/dist/lib/agent-debate.js.map +1 -0
  126. package/dist/lib/agent-memory.d.ts +157 -0
  127. package/dist/lib/agent-memory.d.ts.map +1 -0
  128. package/dist/lib/agent-memory.js +336 -0
  129. package/dist/lib/agent-memory.js.map +1 -0
  130. package/dist/lib/agent-vcr.d.ts +133 -0
  131. package/dist/lib/agent-vcr.d.ts.map +1 -0
  132. package/dist/lib/agent-vcr.js +218 -0
  133. package/dist/lib/agent-vcr.js.map +1 -0
  134. package/dist/lib/anomaly-detector.d.ts +112 -0
  135. package/dist/lib/anomaly-detector.d.ts.map +1 -0
  136. package/dist/lib/anomaly-detector.js +178 -0
  137. package/dist/lib/anomaly-detector.js.map +1 -0
  138. package/dist/lib/approval-inbox.d.ts +147 -0
  139. package/dist/lib/approval-inbox.d.ts.map +1 -0
  140. package/dist/lib/approval-inbox.js +385 -0
  141. package/dist/lib/approval-inbox.js.map +1 -0
  142. package/dist/lib/auth-guardian.d.ts +170 -0
  143. package/dist/lib/auth-guardian.d.ts.map +1 -0
  144. package/dist/lib/auth-guardian.js +604 -0
  145. package/dist/lib/auth-guardian.js.map +1 -0
  146. package/dist/lib/auth-validator.d.ts +70 -0
  147. package/dist/lib/auth-validator.d.ts.map +1 -0
  148. package/dist/lib/auth-validator.js +32 -0
  149. package/dist/lib/auth-validator.js.map +1 -0
  150. package/dist/lib/blackboard-validator.d.ts +56 -0
  151. package/dist/lib/blackboard-validator.d.ts.map +1 -1
  152. package/dist/lib/blackboard-validator.js +181 -4
  153. package/dist/lib/blackboard-validator.js.map +1 -1
  154. package/dist/lib/comparison-runner.d.ts +99 -0
  155. package/dist/lib/comparison-runner.d.ts.map +1 -0
  156. package/dist/lib/comparison-runner.js +138 -0
  157. package/dist/lib/comparison-runner.js.map +1 -0
  158. package/dist/lib/config-watcher.d.ts +109 -0
  159. package/dist/lib/config-watcher.d.ts.map +1 -0
  160. package/dist/lib/config-watcher.js +215 -0
  161. package/dist/lib/config-watcher.js.map +1 -0
  162. package/dist/lib/control-plane.d.ts +128 -0
  163. package/dist/lib/control-plane.d.ts.map +1 -0
  164. package/dist/lib/control-plane.js +527 -0
  165. package/dist/lib/control-plane.js.map +1 -0
  166. package/dist/lib/cost-governor.d.ts +105 -0
  167. package/dist/lib/cost-governor.d.ts.map +1 -0
  168. package/dist/lib/cost-governor.js +128 -0
  169. package/dist/lib/cost-governor.js.map +1 -0
  170. package/dist/lib/cost-heatmap.d.ts +104 -0
  171. package/dist/lib/cost-heatmap.d.ts.map +1 -0
  172. package/dist/lib/cost-heatmap.js +161 -0
  173. package/dist/lib/cost-heatmap.js.map +1 -0
  174. package/dist/lib/coverage-reporter.d.ts +92 -0
  175. package/dist/lib/coverage-reporter.d.ts.map +1 -0
  176. package/dist/lib/coverage-reporter.js +177 -0
  177. package/dist/lib/coverage-reporter.js.map +1 -0
  178. package/dist/lib/dashboard-server.d.ts +71 -0
  179. package/dist/lib/dashboard-server.d.ts.map +1 -0
  180. package/dist/lib/dashboard-server.js +403 -0
  181. package/dist/lib/dashboard-server.js.map +1 -0
  182. package/dist/lib/dry-run.d.ts +73 -0
  183. package/dist/lib/dry-run.d.ts.map +1 -0
  184. package/dist/lib/dry-run.js +130 -0
  185. package/dist/lib/dry-run.js.map +1 -0
  186. package/dist/lib/errors.d.ts +15 -0
  187. package/dist/lib/errors.d.ts.map +1 -1
  188. package/dist/lib/errors.js +38 -0
  189. package/dist/lib/errors.js.map +1 -1
  190. package/dist/lib/event-bus.d.ts +167 -0
  191. package/dist/lib/event-bus.d.ts.map +1 -0
  192. package/dist/lib/event-bus.js +229 -0
  193. package/dist/lib/event-bus.js.map +1 -0
  194. package/dist/lib/explainability.d.ts +85 -0
  195. package/dist/lib/explainability.d.ts.map +1 -0
  196. package/dist/lib/explainability.js +102 -0
  197. package/dist/lib/explainability.js.map +1 -0
  198. package/dist/lib/goal-dsl.d.ts +157 -0
  199. package/dist/lib/goal-dsl.d.ts.map +1 -0
  200. package/dist/lib/goal-dsl.js +391 -0
  201. package/dist/lib/goal-dsl.js.map +1 -0
  202. package/dist/lib/job-queue.d.ts +183 -0
  203. package/dist/lib/job-queue.d.ts.map +1 -0
  204. package/dist/lib/job-queue.js +310 -0
  205. package/dist/lib/job-queue.js.map +1 -0
  206. package/dist/lib/learning-loop.d.ts +113 -0
  207. package/dist/lib/learning-loop.d.ts.map +1 -0
  208. package/dist/lib/learning-loop.js +181 -0
  209. package/dist/lib/learning-loop.js.map +1 -0
  210. package/dist/lib/lifecycle-hooks.d.ts +116 -0
  211. package/dist/lib/lifecycle-hooks.d.ts.map +1 -0
  212. package/dist/lib/lifecycle-hooks.js +148 -0
  213. package/dist/lib/lifecycle-hooks.js.map +1 -0
  214. package/dist/lib/locked-blackboard.d.ts.map +1 -1
  215. package/dist/lib/locked-blackboard.js +9 -5
  216. package/dist/lib/locked-blackboard.js.map +1 -1
  217. package/dist/lib/mcp-tool-consumer.d.ts +153 -0
  218. package/dist/lib/mcp-tool-consumer.d.ts.map +1 -0
  219. package/dist/lib/mcp-tool-consumer.js +320 -0
  220. package/dist/lib/mcp-tool-consumer.js.map +1 -0
  221. package/dist/lib/metrics.d.ts +119 -0
  222. package/dist/lib/metrics.d.ts.map +1 -0
  223. package/dist/lib/metrics.js +284 -0
  224. package/dist/lib/metrics.js.map +1 -0
  225. package/dist/lib/orchestrator-types.d.ts +309 -0
  226. package/dist/lib/orchestrator-types.d.ts.map +1 -0
  227. package/dist/lib/orchestrator-types.js +61 -0
  228. package/dist/lib/orchestrator-types.js.map +1 -0
  229. package/dist/lib/otel-bridge.d.ts +74 -0
  230. package/dist/lib/otel-bridge.d.ts.map +1 -0
  231. package/dist/lib/otel-bridge.js +167 -0
  232. package/dist/lib/otel-bridge.js.map +1 -0
  233. package/dist/lib/playground.d.ts +76 -0
  234. package/dist/lib/playground.d.ts.map +1 -0
  235. package/dist/lib/playground.js +224 -0
  236. package/dist/lib/playground.js.map +1 -0
  237. package/dist/lib/quadtree.d.ts +114 -0
  238. package/dist/lib/quadtree.d.ts.map +1 -0
  239. package/dist/lib/quadtree.js +259 -0
  240. package/dist/lib/quadtree.js.map +1 -0
  241. package/dist/lib/shared-blackboard.d.ts +101 -0
  242. package/dist/lib/shared-blackboard.d.ts.map +1 -0
  243. package/dist/lib/shared-blackboard.js +249 -0
  244. package/dist/lib/shared-blackboard.js.map +1 -0
  245. package/dist/lib/speculative-executor.d.ts +89 -0
  246. package/dist/lib/speculative-executor.d.ts.map +1 -0
  247. package/dist/lib/speculative-executor.js +107 -0
  248. package/dist/lib/speculative-executor.js.map +1 -0
  249. package/dist/lib/swarm-transport.d.ts +150 -0
  250. package/dist/lib/swarm-transport.d.ts.map +1 -0
  251. package/dist/lib/swarm-transport.js +307 -0
  252. package/dist/lib/swarm-transport.js.map +1 -0
  253. package/dist/lib/task-decomposer.d.ts +41 -0
  254. package/dist/lib/task-decomposer.d.ts.map +1 -0
  255. package/dist/lib/task-decomposer.js +272 -0
  256. package/dist/lib/task-decomposer.js.map +1 -0
  257. package/dist/lib/timeline-scrubber.d.ts +84 -0
  258. package/dist/lib/timeline-scrubber.d.ts.map +1 -0
  259. package/dist/lib/timeline-scrubber.js +173 -0
  260. package/dist/lib/timeline-scrubber.js.map +1 -0
  261. package/dist/lib/topology.d.ts +361 -0
  262. package/dist/lib/topology.d.ts.map +1 -0
  263. package/dist/lib/topology.js +591 -0
  264. package/dist/lib/topology.js.map +1 -0
  265. package/dist/lib/work-tree-dashboard.d.ts +130 -0
  266. package/dist/lib/work-tree-dashboard.d.ts.map +1 -0
  267. package/dist/lib/work-tree-dashboard.js +583 -0
  268. package/dist/lib/work-tree-dashboard.js.map +1 -0
  269. package/dist/lib/work-tree-ui.d.ts +107 -0
  270. package/dist/lib/work-tree-ui.d.ts.map +1 -0
  271. package/dist/lib/work-tree-ui.js +333 -0
  272. package/dist/lib/work-tree-ui.js.map +1 -0
  273. package/dist/lib/work-tree.d.ts +184 -0
  274. package/dist/lib/work-tree.d.ts.map +1 -0
  275. package/dist/lib/work-tree.js +480 -0
  276. package/dist/lib/work-tree.js.map +1 -0
  277. package/dist/security.d.ts +95 -0
  278. package/dist/security.d.ts.map +1 -1
  279. package/dist/security.js +267 -4
  280. package/dist/security.js.map +1 -1
  281. package/package.json +8 -6
  282. package/types/agent-adapter.d.ts +5 -0
@@ -0,0 +1,84 @@
1
+ /**
2
+ * TimelineScrubber — Step through orchestrator history at any sequence point.
3
+ *
4
+ * Wraps an OrchestratorEventBus and reconstructs state at any point by
5
+ * loading the nearest snapshot and replaying events forward. Dashboard
6
+ * clients can "drag a slider" to any sequence and get the state at that
7
+ * moment.
8
+ *
9
+ * @module TimelineScrubber
10
+ */
11
+ import type { OrchestratorEventBus, BusEvent } from './event-bus';
12
+ /** Reconstructed state at a given point in time */
13
+ export interface TimelineFrame {
14
+ /** Sequence number this frame represents */
15
+ seq: number;
16
+ /** ISO 8601 timestamp of the event at this seq */
17
+ timestamp: string;
18
+ /** Base snapshot used (or null if before first snapshot) */
19
+ baseSnapshotSeq: number | null;
20
+ /** Events applied on top of the snapshot to reach this state */
21
+ appliedEvents: BusEvent[];
22
+ /** Reconstructed blackboard state */
23
+ blackboard: Record<string, unknown>;
24
+ /** Reconstructed agent statuses */
25
+ agents: Record<string, {
26
+ status: string;
27
+ tokensUsed: number;
28
+ }>;
29
+ /** Budget state if available */
30
+ budget?: Record<string, unknown>;
31
+ }
32
+ /** Range info for the timeline */
33
+ export interface TimelineRange {
34
+ /** Earliest available sequence number */
35
+ minSeq: number;
36
+ /** Latest available sequence number */
37
+ maxSeq: number;
38
+ /** Total events in the stream */
39
+ totalEvents: number;
40
+ /** Number of snapshots available */
41
+ snapshotCount: number;
42
+ /** Sequence numbers of all available snapshots */
43
+ snapshotSeqs: number[];
44
+ }
45
+ /**
46
+ * Reconstructs state at any point in the event stream.
47
+ *
48
+ * @example
49
+ * ```ts
50
+ * const scrubber = new TimelineScrubber(orchestrator.eventBus);
51
+ * const frame = scrubber.frameAt(42);
52
+ * // frame.blackboard — state of blackboard at seq 42
53
+ * // frame.agents — agent statuses at seq 42
54
+ *
55
+ * const range = scrubber.getRange();
56
+ * // range.minSeq, range.maxSeq — slider bounds
57
+ * ```
58
+ */
59
+ export declare class TimelineScrubber {
60
+ private bus;
61
+ constructor(bus: OrchestratorEventBus);
62
+ /**
63
+ * Reconstruct state at a specific sequence number.
64
+ */
65
+ frameAt(seq: number): TimelineFrame;
66
+ /**
67
+ * Get a range of frames (e.g. for scrubbing a window).
68
+ * Returns frames at evenly-spaced sequence numbers.
69
+ */
70
+ frameRange(fromSeq: number, toSeq: number, maxFrames?: number): TimelineFrame[];
71
+ /**
72
+ * Get the timeline range info (slider bounds).
73
+ */
74
+ getRange(): TimelineRange;
75
+ /**
76
+ * Step forward from a given frame by N events.
77
+ */
78
+ stepForward(currentSeq: number, steps?: number): TimelineFrame;
79
+ /**
80
+ * Step backward from a given frame by N events.
81
+ */
82
+ stepBackward(currentSeq: number, steps?: number): TimelineFrame;
83
+ }
84
+ //# sourceMappingURL=timeline-scrubber.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"timeline-scrubber.d.ts","sourceRoot":"","sources":["../../lib/timeline-scrubber.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,QAAQ,EAAiB,MAAM,aAAa,CAAC;AAMjF,mDAAmD;AACnD,MAAM,WAAW,aAAa;IAC5B,4CAA4C;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,gEAAgE;IAChE,aAAa,EAAE,QAAQ,EAAE,CAAC;IAC1B,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/D,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,kCAAkC;AAClC,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,kDAAkD;IAClD,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AA+DD;;;;;;;;;;;;;GAaG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,GAAG,CAAuB;gBAEtB,GAAG,EAAE,oBAAoB;IAIrC;;OAEG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa;IAuCnC;;;OAGG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,SAAK,GAAG,aAAa,EAAE;IAiB3E;;OAEG;IACH,QAAQ,IAAI,aAAa;IAazB;;OAEG;IACH,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,aAAa;IAIzD;;OAEG;IACH,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,aAAa;CAG3D"}
@@ -0,0 +1,173 @@
1
+ "use strict";
2
+ /**
3
+ * TimelineScrubber — Step through orchestrator history at any sequence point.
4
+ *
5
+ * Wraps an OrchestratorEventBus and reconstructs state at any point by
6
+ * loading the nearest snapshot and replaying events forward. Dashboard
7
+ * clients can "drag a slider" to any sequence and get the state at that
8
+ * moment.
9
+ *
10
+ * @module TimelineScrubber
11
+ */
12
+ Object.defineProperty(exports, "__esModule", { value: true });
13
+ exports.TimelineScrubber = void 0;
14
+ // ============================================================================
15
+ // STATE REDUCER
16
+ // ============================================================================
17
+ /** Apply a single bus event to mutable state. */
18
+ function applyEvent(state, event) {
19
+ switch (event.source) {
20
+ case 'blackboard': {
21
+ if (event.type === 'write' || event.type === 'commit') {
22
+ const key = event.data.key;
23
+ if (key)
24
+ state.blackboard[key] = event.data.value;
25
+ }
26
+ else if (event.type === 'delete') {
27
+ const key = event.data.key;
28
+ if (key)
29
+ delete state.blackboard[key];
30
+ }
31
+ break;
32
+ }
33
+ case 'orchestrator': {
34
+ if (event.type === 'delegation_start' && event.agentId) {
35
+ const target = event.data.targetAgent;
36
+ if (target && !state.agents[target]) {
37
+ state.agents[target] = { status: 'running', tokensUsed: 0 };
38
+ }
39
+ else if (target && state.agents[target]) {
40
+ state.agents[target].status = 'running';
41
+ }
42
+ }
43
+ if (event.type === 'delegation_failed' && event.data.targetAgent) {
44
+ const target = event.data.targetAgent;
45
+ if (state.agents[target])
46
+ state.agents[target].status = 'failed';
47
+ }
48
+ break;
49
+ }
50
+ case 'adapter': {
51
+ if (event.type === 'agent:execution:complete' && event.agentId) {
52
+ if (state.agents[event.agentId]) {
53
+ state.agents[event.agentId].status = 'completed';
54
+ }
55
+ }
56
+ break;
57
+ }
58
+ case 'quality': {
59
+ if (event.type === 'reject' && event.agentId) {
60
+ if (state.agents[event.agentId]) {
61
+ state.agents[event.agentId].status = 'failed';
62
+ }
63
+ }
64
+ break;
65
+ }
66
+ // Other sources: no state mutation needed for reconstruction
67
+ default:
68
+ break;
69
+ }
70
+ }
71
+ // ============================================================================
72
+ // SCRUBBER
73
+ // ============================================================================
74
+ /**
75
+ * Reconstructs state at any point in the event stream.
76
+ *
77
+ * @example
78
+ * ```ts
79
+ * const scrubber = new TimelineScrubber(orchestrator.eventBus);
80
+ * const frame = scrubber.frameAt(42);
81
+ * // frame.blackboard — state of blackboard at seq 42
82
+ * // frame.agents — agent statuses at seq 42
83
+ *
84
+ * const range = scrubber.getRange();
85
+ * // range.minSeq, range.maxSeq — slider bounds
86
+ * ```
87
+ */
88
+ class TimelineScrubber {
89
+ bus;
90
+ constructor(bus) {
91
+ this.bus = bus;
92
+ }
93
+ /**
94
+ * Reconstruct state at a specific sequence number.
95
+ */
96
+ frameAt(seq) {
97
+ // Find nearest snapshot at or before seq
98
+ const snapshot = this.bus.snapshotAt(seq);
99
+ // Determine replay start
100
+ const fromSeq = snapshot ? snapshot.atSeq + 1 : 0;
101
+ // Get events from snapshot to target seq
102
+ const replay = this.bus.replay({ fromSeq, toSeq: seq });
103
+ const appliedEvents = replay.events;
104
+ // Initialize state from snapshot or empty
105
+ const blackboard = snapshot
106
+ ? { ...snapshot.blackboard }
107
+ : {};
108
+ const agents = snapshot
109
+ ? Object.fromEntries(Object.entries(snapshot.agents).map(([k, v]) => [k, { ...v }]))
110
+ : {};
111
+ // Apply events forward
112
+ for (const event of appliedEvents) {
113
+ applyEvent({ blackboard, agents }, event);
114
+ }
115
+ // Find the event timestamp at this seq
116
+ const targetEvent = this.bus.getEvent(seq);
117
+ const timestamp = targetEvent?.timestamp ?? snapshot?.timestamp ?? new Date().toISOString();
118
+ return {
119
+ seq,
120
+ timestamp,
121
+ baseSnapshotSeq: snapshot?.atSeq ?? null,
122
+ appliedEvents,
123
+ blackboard,
124
+ agents,
125
+ budget: snapshot?.budget,
126
+ };
127
+ }
128
+ /**
129
+ * Get a range of frames (e.g. for scrubbing a window).
130
+ * Returns frames at evenly-spaced sequence numbers.
131
+ */
132
+ frameRange(fromSeq, toSeq, maxFrames = 50) {
133
+ const range = toSeq - fromSeq;
134
+ const step = Math.max(1, Math.floor(range / maxFrames));
135
+ const frames = [];
136
+ for (let s = fromSeq; s <= toSeq; s += step) {
137
+ frames.push(this.frameAt(s));
138
+ }
139
+ // Always include the last frame
140
+ if (frames.length === 0 || frames[frames.length - 1].seq !== toSeq) {
141
+ frames.push(this.frameAt(toSeq));
142
+ }
143
+ return frames;
144
+ }
145
+ /**
146
+ * Get the timeline range info (slider bounds).
147
+ */
148
+ getRange() {
149
+ const snapshots = this.bus.getSnapshots();
150
+ const replay = this.bus.replay();
151
+ return {
152
+ minSeq: replay.events.length > 0 ? replay.events[0].seq : 0,
153
+ maxSeq: this.bus.currentSeq - 1,
154
+ totalEvents: replay.totalEvents,
155
+ snapshotCount: snapshots.length,
156
+ snapshotSeqs: snapshots.map(s => s.atSeq),
157
+ };
158
+ }
159
+ /**
160
+ * Step forward from a given frame by N events.
161
+ */
162
+ stepForward(currentSeq, steps = 1) {
163
+ return this.frameAt(Math.min(currentSeq + steps, this.bus.currentSeq - 1));
164
+ }
165
+ /**
166
+ * Step backward from a given frame by N events.
167
+ */
168
+ stepBackward(currentSeq, steps = 1) {
169
+ return this.frameAt(Math.max(currentSeq - steps, 0));
170
+ }
171
+ }
172
+ exports.TimelineScrubber = TimelineScrubber;
173
+ //# sourceMappingURL=timeline-scrubber.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"timeline-scrubber.js","sourceRoot":"","sources":["../../lib/timeline-scrubber.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,361 @@
1
+ /**
2
+ * Live Agent Topology — Real-time agent graph and event tracking
3
+ *
4
+ * Maintains a live directed graph of agents (nodes) and their interactions
5
+ * (edges). Emits events for every state change so dashboards can render
6
+ * the topology in real time.
7
+ *
8
+ * @module Topology
9
+ * @version 1.0.0
10
+ */
11
+ import { EventEmitter } from 'events';
12
+ /** Operational status of an agent node */
13
+ export type AgentNodeStatus = 'idle' | 'running' | 'completed' | 'failed' | 'waiting' | 'spawning';
14
+ /** Visual group / role for clustering in the UI */
15
+ export type AgentRole = 'orchestrator' | 'worker' | 'validator' | 'planner' | 'aggregator' | 'custom';
16
+ /** A single agent node in the topology graph */
17
+ export interface AgentNode {
18
+ /** Unique agent identifier */
19
+ id: string;
20
+ /** Display label (defaults to id) */
21
+ label: string;
22
+ /** Current operational status */
23
+ status: AgentNodeStatus;
24
+ /** Adapter framework (e.g. 'langchain', 'crewai', 'custom') */
25
+ adapter?: string;
26
+ /** Visual grouping role */
27
+ role: AgentRole;
28
+ /** Current task description */
29
+ currentTask?: string;
30
+ /** Tokens consumed so far */
31
+ tokensUsed: number;
32
+ /** Budget cap for this agent (if any) */
33
+ tokenBudget?: number;
34
+ /** ISO 8601 timestamp when the agent was registered */
35
+ registeredAt: string;
36
+ /** ISO 8601 timestamp of last activity */
37
+ lastActivityAt: string;
38
+ /** Arbitrary metadata */
39
+ metadata: Record<string, unknown>;
40
+ }
41
+ /** Type of edge between agents */
42
+ export type EdgeType = 'blackboard_write' | 'blackboard_read' | 'delegation' | 'result' | 'dependency' | 'message';
43
+ /** A directed edge representing an interaction between agents */
44
+ export interface TopologyEdge {
45
+ /** Unique edge identifier */
46
+ id: string;
47
+ /** Source agent id */
48
+ from: string;
49
+ /** Target agent id (or '_blackboard' for board interactions) */
50
+ to: string;
51
+ /** Type of interaction */
52
+ type: EdgeType;
53
+ /** Edge label (e.g. blackboard key, task id) */
54
+ label?: string;
55
+ /** ISO 8601 timestamp */
56
+ timestamp: string;
57
+ /** Optional payload metadata */
58
+ metadata?: Record<string, unknown>;
59
+ }
60
+ /** A timestamped event in the topology stream */
61
+ export interface TopologyEvent {
62
+ /** Monotonic event counter */
63
+ seq: number;
64
+ /** ISO 8601 timestamp */
65
+ timestamp: string;
66
+ /** Event type */
67
+ type: TopologyEventType;
68
+ /** Event payload */
69
+ data: Record<string, unknown>;
70
+ }
71
+ /** All topology event types */
72
+ export type TopologyEventType = 'agent:added' | 'agent:removed' | 'agent:status' | 'agent:task' | 'agent:tokens' | 'edge:added' | 'edge:removed' | 'snapshot' | 'clear';
73
+ /** Full snapshot of the topology graph */
74
+ export interface TopologySnapshot {
75
+ /** All agent nodes */
76
+ nodes: AgentNode[];
77
+ /** All edges */
78
+ edges: TopologyEdge[];
79
+ /** Event log since last clear */
80
+ events: TopologyEvent[];
81
+ /** Snapshot timestamp */
82
+ timestamp: string;
83
+ /** Live narrative summary */
84
+ narrative: string;
85
+ /** Phase progress */
86
+ phase: PhaseProgress;
87
+ /** Attention-based status panel */
88
+ attention: AttentionPanel;
89
+ /** Agent activity timeline spans */
90
+ timeline: TimelineSpan[];
91
+ /** Agent clusters for scaled views (optional, populated by server) */
92
+ clusters?: AgentCluster[];
93
+ }
94
+ /** Events emitted by TopologyTracker */
95
+ export interface TopologyTrackerEvents {
96
+ 'agent:added': (node: AgentNode) => void;
97
+ 'agent:removed': (id: string) => void;
98
+ 'agent:status': (id: string, status: AgentNodeStatus, prev: AgentNodeStatus) => void;
99
+ 'agent:task': (id: string, task: string | undefined) => void;
100
+ 'agent:tokens': (id: string, tokens: number) => void;
101
+ 'edge:added': (edge: TopologyEdge) => void;
102
+ 'edge:removed': (edgeId: string) => void;
103
+ 'snapshot': (snapshot: TopologySnapshot) => void;
104
+ 'event': (event: TopologyEvent) => void;
105
+ 'clear': () => void;
106
+ }
107
+ /** Options for creating a TopologyTracker */
108
+ export interface TopologyTrackerOptions {
109
+ /** Maximum number of events to retain (default: 2000) */
110
+ maxEvents?: number;
111
+ /** Maximum number of edges to retain (default: 5000) */
112
+ maxEdges?: number;
113
+ /** Auto-prune edges older than this (ms). 0 = no pruning (default: 0) */
114
+ edgeTtlMs?: number;
115
+ /** Maximum timeline spans to retain (default: 50000) */
116
+ maxTimelineSpans?: number;
117
+ }
118
+ /** A phase milestone in the workflow */
119
+ export interface PhaseMilestone {
120
+ /** Phase name */
121
+ name: string;
122
+ /** Status */
123
+ status: 'pending' | 'active' | 'completed';
124
+ }
125
+ /** Phase progress for the progress bar */
126
+ export interface PhaseProgress {
127
+ /** Ordered milestones */
128
+ milestones: PhaseMilestone[];
129
+ /** 0-1 overall progress */
130
+ progress: number;
131
+ /** Current phase label */
132
+ currentPhase: string;
133
+ }
134
+ /** Attention-based panel items */
135
+ export interface AttentionItem {
136
+ /** Agent id */
137
+ agentId: string;
138
+ /** Agent label */
139
+ label: string;
140
+ /** Summary text */
141
+ summary: string;
142
+ /** Severity */
143
+ severity: 'critical' | 'active' | 'done';
144
+ /** Elapsed time in ms (for active items) */
145
+ elapsedMs?: number;
146
+ /** ISO timestamp */
147
+ timestamp: string;
148
+ }
149
+ /** Attention panel with categorized items */
150
+ export interface AttentionPanel {
151
+ /** Items needing attention (failures, budget overruns, stuck) */
152
+ needsAttention: AttentionItem[];
153
+ /** Currently active agents */
154
+ activeNow: AttentionItem[];
155
+ /** Recently finished */
156
+ recentlyCompleted: AttentionItem[];
157
+ }
158
+ /** A timeline span for Gantt chart visualization */
159
+ export interface TimelineSpan {
160
+ /** Agent id */
161
+ agentId: string;
162
+ /** Agent label */
163
+ label: string;
164
+ /** Status during this span */
165
+ status: AgentNodeStatus;
166
+ /** Start time in ms (epoch) */
167
+ startMs: number;
168
+ /** End time in ms (epoch), undefined if still active */
169
+ endMs?: number;
170
+ }
171
+ /** A cluster of agents for zoomed-out views */
172
+ export interface AgentCluster {
173
+ /** Cluster identifier */
174
+ id: string;
175
+ /** Role shared by agents in this cluster */
176
+ role: AgentRole;
177
+ /** Number of agents in this cluster */
178
+ count: number;
179
+ /** Status breakdown */
180
+ statusCounts: Record<AgentNodeStatus, number>;
181
+ /** Aggregate tokens used */
182
+ totalTokensUsed: number;
183
+ /** Aggregate token budget */
184
+ totalTokenBudget: number;
185
+ /** Representative agent ids (first few) */
186
+ sampleIds: string[];
187
+ }
188
+ /** Delta patch for incremental updates */
189
+ export interface TopologyDelta {
190
+ /** Sequence number this delta starts from */
191
+ sinceSeq: number;
192
+ /** Current sequence number */
193
+ currentSeq: number;
194
+ /** New or changed agent nodes */
195
+ nodesChanged: AgentNode[];
196
+ /** Removed agent ids */
197
+ nodesRemoved: string[];
198
+ /** New edges */
199
+ edgesAdded: TopologyEdge[];
200
+ /** Removed edge ids */
201
+ edgesRemoved: string[];
202
+ /** Updated summary fields */
203
+ narrative: string;
204
+ phase: PhaseProgress;
205
+ attention: AttentionPanel;
206
+ /** Only new timeline spans since sinceSeq */
207
+ timelineAdded: TimelineSpan[];
208
+ /** Aggregated clusters (sent with every delta for up-to-date cluster view) */
209
+ clusters?: AgentCluster[];
210
+ }
211
+ /**
212
+ * Tracks the live agent topology graph and emits real-time events.
213
+ *
214
+ * Usage:
215
+ * ```typescript
216
+ * const topo = new TopologyTracker();
217
+ *
218
+ * topo.addAgent({ id: 'planner', role: 'planner' });
219
+ * topo.addAgent({ id: 'worker-1', role: 'worker', adapter: 'langchain' });
220
+ *
221
+ * topo.setStatus('planner', 'running');
222
+ * topo.addEdge('planner', 'worker-1', 'delegation', 'analyze code');
223
+ *
224
+ * topo.on('agent:status', (id, status) => {
225
+ * console.log(`${id} → ${status}`);
226
+ * });
227
+ * ```
228
+ */
229
+ export declare class TopologyTracker extends EventEmitter {
230
+ private nodes;
231
+ private edges;
232
+ private eventLog;
233
+ private seq;
234
+ private readonly maxEvents;
235
+ private readonly maxEdges;
236
+ private readonly edgeTtlMs;
237
+ private readonly maxTimelineSpans;
238
+ private timelineSpans;
239
+ private deltaNodesChanged;
240
+ private deltaNodesRemoved;
241
+ private deltaEdgesAdded;
242
+ private deltaEdgesRemoved;
243
+ private deltaTimelineStart;
244
+ constructor(options?: TopologyTrackerOptions);
245
+ /**
246
+ * Add or update an agent node.
247
+ */
248
+ addAgent(opts: {
249
+ id: string;
250
+ label?: string;
251
+ role?: AgentRole;
252
+ adapter?: string;
253
+ status?: AgentNodeStatus;
254
+ tokenBudget?: number;
255
+ metadata?: Record<string, unknown>;
256
+ }): AgentNode;
257
+ /**
258
+ * Remove an agent node and all its edges.
259
+ */
260
+ removeAgent(id: string): boolean;
261
+ /**
262
+ * Update an agent's operational status.
263
+ */
264
+ setStatus(id: string, status: AgentNodeStatus): void;
265
+ /**
266
+ * Update or clear the agent's current task.
267
+ */
268
+ setTask(id: string, task?: string): void;
269
+ /**
270
+ * Add tokens consumed by an agent.
271
+ */
272
+ addTokens(id: string, tokens: number): void;
273
+ /**
274
+ * Get a single agent node.
275
+ */
276
+ getAgent(id: string): AgentNode | undefined;
277
+ /**
278
+ * Get all agent nodes.
279
+ */
280
+ getAgents(): AgentNode[];
281
+ /**
282
+ * Add a directed edge between agents.
283
+ */
284
+ addEdge(from: string, to: string, type: EdgeType, label?: string, metadata?: Record<string, unknown>): TopologyEdge;
285
+ /**
286
+ * Remove an edge by id.
287
+ */
288
+ removeEdge(edgeId: string): boolean;
289
+ /**
290
+ * Get all edges, optionally filtered by agent id.
291
+ */
292
+ getEdges(agentId?: string): TopologyEdge[];
293
+ /**
294
+ * Get edges between two specific agents.
295
+ */
296
+ getEdgesBetween(from: string, to: string): TopologyEdge[];
297
+ /**
298
+ * Generate a one-line narrative summary of the current topology state.
299
+ */
300
+ generateNarrative(): string;
301
+ /**
302
+ * Compute phase progress from agent roles and statuses.
303
+ */
304
+ computePhase(): PhaseProgress;
305
+ /**
306
+ * Compute the attention-based status panel.
307
+ */
308
+ computeAttention(): AttentionPanel;
309
+ /**
310
+ * Get all timeline spans for the Gantt chart.
311
+ */
312
+ getTimelineSpans(): TimelineSpan[];
313
+ /**
314
+ * Compute clusters by grouping agents by role.
315
+ * Returns an array of clusters with aggregate statistics.
316
+ */
317
+ computeClusters(): AgentCluster[];
318
+ /**
319
+ * Get a delta patch of changes since the last call to resetDelta().
320
+ * Use this for incremental WebSocket updates instead of full snapshots.
321
+ */
322
+ delta(sinceSeq: number): TopologyDelta;
323
+ /**
324
+ * Reset delta tracking. Call after sending a delta to a client.
325
+ */
326
+ resetDelta(): void;
327
+ /**
328
+ * Current sequence number for delta protocol.
329
+ */
330
+ currentSeq(): number;
331
+ /**
332
+ * Get a full snapshot of the current topology.
333
+ */
334
+ snapshot(): TopologySnapshot;
335
+ /**
336
+ * Return snapshot data without emitting events or logging.
337
+ * Used by the dashboard server's broadcast loop to avoid
338
+ * re-entrant event emission (snapshot → event → broadcast → snapshot).
339
+ */
340
+ snapshotQuiet(): TopologySnapshot;
341
+ /**
342
+ * Get the event log.
343
+ */
344
+ getEvents(since?: number): TopologyEvent[];
345
+ /**
346
+ * Number of agent nodes.
347
+ */
348
+ nodeCount(): number;
349
+ /**
350
+ * Number of edges.
351
+ */
352
+ edgeCount(): number;
353
+ /**
354
+ * Clear all nodes, edges, and events.
355
+ */
356
+ clear(): void;
357
+ private pushEvent;
358
+ private pruneExpiredEdges;
359
+ private trimTimeline;
360
+ }
361
+ //# sourceMappingURL=topology.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"topology.d.ts","sourceRoot":"","sources":["../../lib/topology.ts"],"names":[],"mappings":"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"}