network-ai 5.10.2 → 5.12.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 (273) hide show
  1. package/INTEGRATION_GUIDE.md +2 -2
  2. package/QUICKSTART.md +10 -0
  3. package/README.md +32 -3
  4. package/SKILL.md +3 -3
  5. package/dist/esm/adapters/a2a-adapter.js +235 -0
  6. package/dist/esm/adapters/a2a-adapter.js.map +1 -0
  7. package/dist/esm/adapters/adapter-registry.js +613 -0
  8. package/dist/esm/adapters/adapter-registry.js.map +1 -0
  9. package/dist/esm/adapters/agno-adapter.js +140 -0
  10. package/dist/esm/adapters/agno-adapter.js.map +1 -0
  11. package/dist/esm/adapters/anthropic-computer-use-adapter.js +180 -0
  12. package/dist/esm/adapters/anthropic-computer-use-adapter.js.map +1 -0
  13. package/dist/esm/adapters/aps-adapter.js +289 -0
  14. package/dist/esm/adapters/aps-adapter.js.map +1 -0
  15. package/dist/esm/adapters/autogen-adapter.js +141 -0
  16. package/dist/esm/adapters/autogen-adapter.js.map +1 -0
  17. package/dist/esm/adapters/base-adapter.js +104 -0
  18. package/dist/esm/adapters/base-adapter.js.map +1 -0
  19. package/dist/esm/adapters/browser-agent-adapter.js +219 -0
  20. package/dist/esm/adapters/browser-agent-adapter.js.map +1 -0
  21. package/dist/esm/adapters/codex-adapter.js +318 -0
  22. package/dist/esm/adapters/codex-adapter.js.map +1 -0
  23. package/dist/esm/adapters/copilot-adapter.js +132 -0
  24. package/dist/esm/adapters/copilot-adapter.js.map +1 -0
  25. package/dist/esm/adapters/crewai-adapter.js +148 -0
  26. package/dist/esm/adapters/crewai-adapter.js.map +1 -0
  27. package/dist/esm/adapters/custom-adapter.js +142 -0
  28. package/dist/esm/adapters/custom-adapter.js.map +1 -0
  29. package/dist/esm/adapters/custom-streaming-adapter.js +181 -0
  30. package/dist/esm/adapters/custom-streaming-adapter.js.map +1 -0
  31. package/dist/esm/adapters/dspy-adapter.js +127 -0
  32. package/dist/esm/adapters/dspy-adapter.js.map +1 -0
  33. package/dist/esm/adapters/haystack-adapter.js +149 -0
  34. package/dist/esm/adapters/haystack-adapter.js.map +1 -0
  35. package/dist/esm/adapters/hermes-adapter.js +217 -0
  36. package/dist/esm/adapters/hermes-adapter.js.map +1 -0
  37. package/dist/esm/adapters/index.js +109 -0
  38. package/dist/esm/adapters/index.js.map +1 -0
  39. package/dist/esm/adapters/langchain-adapter.js +134 -0
  40. package/dist/esm/adapters/langchain-adapter.js.map +1 -0
  41. package/dist/esm/adapters/langchain-streaming-adapter.js +161 -0
  42. package/dist/esm/adapters/langchain-streaming-adapter.js.map +1 -0
  43. package/dist/esm/adapters/langgraph-adapter.js +119 -0
  44. package/dist/esm/adapters/langgraph-adapter.js.map +1 -0
  45. package/dist/esm/adapters/llamaindex-adapter.js +135 -0
  46. package/dist/esm/adapters/llamaindex-adapter.js.map +1 -0
  47. package/dist/esm/adapters/mcp-adapter.js +200 -0
  48. package/dist/esm/adapters/mcp-adapter.js.map +1 -0
  49. package/dist/esm/adapters/minimax-adapter.js +233 -0
  50. package/dist/esm/adapters/minimax-adapter.js.map +1 -0
  51. package/dist/esm/adapters/nemoclaw-adapter.js +465 -0
  52. package/dist/esm/adapters/nemoclaw-adapter.js.map +1 -0
  53. package/dist/esm/adapters/openai-agents-adapter.js +118 -0
  54. package/dist/esm/adapters/openai-agents-adapter.js.map +1 -0
  55. package/dist/esm/adapters/openai-assistants-adapter.js +130 -0
  56. package/dist/esm/adapters/openai-assistants-adapter.js.map +1 -0
  57. package/dist/esm/adapters/openclaw-adapter.js +107 -0
  58. package/dist/esm/adapters/openclaw-adapter.js.map +1 -0
  59. package/dist/esm/adapters/orchestrator-adapter.js +218 -0
  60. package/dist/esm/adapters/orchestrator-adapter.js.map +1 -0
  61. package/dist/esm/adapters/pydantic-ai-adapter.js +163 -0
  62. package/dist/esm/adapters/pydantic-ai-adapter.js.map +1 -0
  63. package/dist/esm/adapters/rlm-adapter.js +167 -0
  64. package/dist/esm/adapters/rlm-adapter.js.map +1 -0
  65. package/dist/esm/adapters/semantic-kernel-adapter.js +123 -0
  66. package/dist/esm/adapters/semantic-kernel-adapter.js.map +1 -0
  67. package/dist/esm/adapters/streaming-base-adapter.js +74 -0
  68. package/dist/esm/adapters/streaming-base-adapter.js.map +1 -0
  69. package/dist/esm/adapters/vertex-ai-adapter.js +166 -0
  70. package/dist/esm/adapters/vertex-ai-adapter.js.map +1 -0
  71. package/dist/esm/demo-control-plane.js +147 -0
  72. package/dist/esm/demo-control-plane.js.map +1 -0
  73. package/dist/esm/demo-worktree-dashboard.js +131 -0
  74. package/dist/esm/demo-worktree-dashboard.js.map +1 -0
  75. package/dist/esm/examples/01-hello-swarm.js +165 -0
  76. package/dist/esm/examples/01-hello-swarm.js.map +1 -0
  77. package/dist/esm/examples/02-fsm-pipeline.js +189 -0
  78. package/dist/esm/examples/02-fsm-pipeline.js.map +1 -0
  79. package/dist/esm/examples/03-parallel-agents.js +192 -0
  80. package/dist/esm/examples/03-parallel-agents.js.map +1 -0
  81. package/dist/esm/examples/05-code-review-swarm.js +1177 -0
  82. package/dist/esm/examples/05-code-review-swarm.js.map +1 -0
  83. package/dist/esm/examples/06-ai-pipeline-demo.js +263 -0
  84. package/dist/esm/examples/06-ai-pipeline-demo.js.map +1 -0
  85. package/dist/esm/examples/07-full-showcase.js +946 -0
  86. package/dist/esm/examples/07-full-showcase.js.map +1 -0
  87. package/dist/esm/examples/08-control-plane-stress-demo.js +186 -0
  88. package/dist/esm/examples/08-control-plane-stress-demo.js.map +1 -0
  89. package/dist/esm/examples/09-real-langchain.js +231 -0
  90. package/dist/esm/examples/09-real-langchain.js.map +1 -0
  91. package/dist/esm/examples/10-nemoclaw-sandbox-swarm.js +270 -0
  92. package/dist/esm/examples/10-nemoclaw-sandbox-swarm.js.map +1 -0
  93. package/dist/esm/examples/demo-runner.js +119 -0
  94. package/dist/esm/examples/demo-runner.js.map +1 -0
  95. package/dist/esm/index.js +1352 -0
  96. package/dist/esm/index.js.map +1 -0
  97. package/dist/esm/lib/adapter-hooks.js +216 -0
  98. package/dist/esm/lib/adapter-hooks.js.map +1 -0
  99. package/dist/esm/lib/adapter-test-harness.js +118 -0
  100. package/dist/esm/lib/adapter-test-harness.js.map +1 -0
  101. package/dist/esm/lib/agent-conversation.js +155 -0
  102. package/dist/esm/lib/agent-conversation.js.map +1 -0
  103. package/dist/esm/lib/agent-debate.js +146 -0
  104. package/dist/esm/lib/agent-debate.js.map +1 -0
  105. package/dist/esm/lib/agent-memory.js +336 -0
  106. package/dist/esm/lib/agent-memory.js.map +1 -0
  107. package/dist/esm/lib/agent-runtime.js +818 -0
  108. package/dist/esm/lib/agent-runtime.js.map +1 -0
  109. package/dist/esm/lib/agent-vcr.js +218 -0
  110. package/dist/esm/lib/agent-vcr.js.map +1 -0
  111. package/dist/esm/lib/anomaly-detector.js +178 -0
  112. package/dist/esm/lib/anomaly-detector.js.map +1 -0
  113. package/dist/esm/lib/approval-inbox.js +385 -0
  114. package/dist/esm/lib/approval-inbox.js.map +1 -0
  115. package/dist/esm/lib/auth-guardian.js +692 -0
  116. package/dist/esm/lib/auth-guardian.js.map +1 -0
  117. package/dist/esm/lib/auth-validator.js +32 -0
  118. package/dist/esm/lib/auth-validator.js.map +1 -0
  119. package/dist/esm/lib/blackboard-backend-crdt.js +251 -0
  120. package/dist/esm/lib/blackboard-backend-crdt.js.map +1 -0
  121. package/dist/esm/lib/blackboard-backend-redis.js +244 -0
  122. package/dist/esm/lib/blackboard-backend-redis.js.map +1 -0
  123. package/dist/esm/lib/blackboard-backend.js +141 -0
  124. package/dist/esm/lib/blackboard-backend.js.map +1 -0
  125. package/dist/esm/lib/blackboard-validator.js +985 -0
  126. package/dist/esm/lib/blackboard-validator.js.map +1 -0
  127. package/dist/esm/lib/circuit-breaker.js +164 -0
  128. package/dist/esm/lib/circuit-breaker.js.map +1 -0
  129. package/dist/esm/lib/claim-verifier.js +173 -0
  130. package/dist/esm/lib/claim-verifier.js.map +1 -0
  131. package/dist/esm/lib/comparison-runner.js +138 -0
  132. package/dist/esm/lib/comparison-runner.js.map +1 -0
  133. package/dist/esm/lib/compliance-monitor.js +261 -0
  134. package/dist/esm/lib/compliance-monitor.js.map +1 -0
  135. package/dist/esm/lib/confidence-filter.js +210 -0
  136. package/dist/esm/lib/confidence-filter.js.map +1 -0
  137. package/dist/esm/lib/config-watcher.js +215 -0
  138. package/dist/esm/lib/config-watcher.js.map +1 -0
  139. package/dist/esm/lib/consistency.js +274 -0
  140. package/dist/esm/lib/consistency.js.map +1 -0
  141. package/dist/esm/lib/console-ui.js +276 -0
  142. package/dist/esm/lib/console-ui.js.map +1 -0
  143. package/dist/esm/lib/context-throttler.js +171 -0
  144. package/dist/esm/lib/context-throttler.js.map +1 -0
  145. package/dist/esm/lib/control-plane.js +527 -0
  146. package/dist/esm/lib/control-plane.js.map +1 -0
  147. package/dist/esm/lib/cost-governor.js +128 -0
  148. package/dist/esm/lib/cost-governor.js.map +1 -0
  149. package/dist/esm/lib/cost-heatmap.js +161 -0
  150. package/dist/esm/lib/cost-heatmap.js.map +1 -0
  151. package/dist/esm/lib/coverage-gate.js +213 -0
  152. package/dist/esm/lib/coverage-gate.js.map +1 -0
  153. package/dist/esm/lib/coverage-reporter.js +177 -0
  154. package/dist/esm/lib/coverage-reporter.js.map +1 -0
  155. package/dist/esm/lib/crdt.js +141 -0
  156. package/dist/esm/lib/crdt.js.map +1 -0
  157. package/dist/esm/lib/dashboard-server.js +403 -0
  158. package/dist/esm/lib/dashboard-server.js.map +1 -0
  159. package/dist/esm/lib/dry-run.js +130 -0
  160. package/dist/esm/lib/dry-run.js.map +1 -0
  161. package/dist/esm/lib/env-manager.js +518 -0
  162. package/dist/esm/lib/env-manager.js.map +1 -0
  163. package/dist/esm/lib/errors.js +201 -0
  164. package/dist/esm/lib/errors.js.map +1 -0
  165. package/dist/esm/lib/event-bus.js +229 -0
  166. package/dist/esm/lib/event-bus.js.map +1 -0
  167. package/dist/esm/lib/explainability.js +102 -0
  168. package/dist/esm/lib/explainability.js.map +1 -0
  169. package/dist/esm/lib/fan-out.js +237 -0
  170. package/dist/esm/lib/fan-out.js.map +1 -0
  171. package/dist/esm/lib/federated-budget.js +322 -0
  172. package/dist/esm/lib/federated-budget.js.map +1 -0
  173. package/dist/esm/lib/fsm-journey.js +478 -0
  174. package/dist/esm/lib/fsm-journey.js.map +1 -0
  175. package/dist/esm/lib/goal-decomposer.js +698 -0
  176. package/dist/esm/lib/goal-decomposer.js.map +1 -0
  177. package/dist/esm/lib/goal-dsl.js +391 -0
  178. package/dist/esm/lib/goal-dsl.js.map +1 -0
  179. package/dist/esm/lib/job-queue.js +310 -0
  180. package/dist/esm/lib/job-queue.js.map +1 -0
  181. package/dist/esm/lib/landscape-agent.js +134 -0
  182. package/dist/esm/lib/landscape-agent.js.map +1 -0
  183. package/dist/esm/lib/learning-loop.js +181 -0
  184. package/dist/esm/lib/learning-loop.js.map +1 -0
  185. package/dist/esm/lib/lifecycle-hooks.js +148 -0
  186. package/dist/esm/lib/lifecycle-hooks.js.map +1 -0
  187. package/dist/esm/lib/locked-blackboard.js +1295 -0
  188. package/dist/esm/lib/locked-blackboard.js.map +1 -0
  189. package/dist/esm/lib/logger.js +150 -0
  190. package/dist/esm/lib/logger.js.map +1 -0
  191. package/dist/esm/lib/mcp-blackboard-tools.js +298 -0
  192. package/dist/esm/lib/mcp-blackboard-tools.js.map +1 -0
  193. package/dist/esm/lib/mcp-bridge.js +357 -0
  194. package/dist/esm/lib/mcp-bridge.js.map +1 -0
  195. package/dist/esm/lib/mcp-tool-consumer.js +287 -0
  196. package/dist/esm/lib/mcp-tool-consumer.js.map +1 -0
  197. package/dist/esm/lib/mcp-tools-control.js +392 -0
  198. package/dist/esm/lib/mcp-tools-control.js.map +1 -0
  199. package/dist/esm/lib/mcp-tools-extended.js +371 -0
  200. package/dist/esm/lib/mcp-tools-extended.js.map +1 -0
  201. package/dist/esm/lib/mcp-transport-http.js +528 -0
  202. package/dist/esm/lib/mcp-transport-http.js.map +1 -0
  203. package/dist/esm/lib/mcp-transport-sse.js +503 -0
  204. package/dist/esm/lib/mcp-transport-sse.js.map +1 -0
  205. package/dist/esm/lib/metrics.js +284 -0
  206. package/dist/esm/lib/metrics.js.map +1 -0
  207. package/dist/esm/lib/orchestrator-types.js +66 -0
  208. package/dist/esm/lib/orchestrator-types.js.map +1 -0
  209. package/dist/esm/lib/otel-bridge.js +167 -0
  210. package/dist/esm/lib/otel-bridge.js.map +1 -0
  211. package/dist/esm/lib/partition-planner.js +246 -0
  212. package/dist/esm/lib/partition-planner.js.map +1 -0
  213. package/dist/esm/lib/phase-pipeline.js +367 -0
  214. package/dist/esm/lib/phase-pipeline.js.map +1 -0
  215. package/dist/esm/lib/playground.js +224 -0
  216. package/dist/esm/lib/playground.js.map +1 -0
  217. package/dist/esm/lib/qa-orchestrator.js +296 -0
  218. package/dist/esm/lib/qa-orchestrator.js.map +1 -0
  219. package/dist/esm/lib/quadtree.js +259 -0
  220. package/dist/esm/lib/quadtree.js.map +1 -0
  221. package/dist/esm/lib/route-classifier.js +217 -0
  222. package/dist/esm/lib/route-classifier.js.map +1 -0
  223. package/dist/esm/lib/semantic-search.js +235 -0
  224. package/dist/esm/lib/semantic-search.js.map +1 -0
  225. package/dist/esm/lib/shared-blackboard.js +249 -0
  226. package/dist/esm/lib/shared-blackboard.js.map +1 -0
  227. package/dist/esm/lib/skill-composer.js +190 -0
  228. package/dist/esm/lib/skill-composer.js.map +1 -0
  229. package/dist/esm/lib/speculative-executor.js +107 -0
  230. package/dist/esm/lib/speculative-executor.js.map +1 -0
  231. package/dist/esm/lib/strategy-agent.js +626 -0
  232. package/dist/esm/lib/strategy-agent.js.map +1 -0
  233. package/dist/esm/lib/swarm-transport.js +307 -0
  234. package/dist/esm/lib/swarm-transport.js.map +1 -0
  235. package/dist/esm/lib/swarm-utils.js +510 -0
  236. package/dist/esm/lib/swarm-utils.js.map +1 -0
  237. package/dist/esm/lib/task-decomposer.js +272 -0
  238. package/dist/esm/lib/task-decomposer.js.map +1 -0
  239. package/dist/esm/lib/telemetry-provider.js +207 -0
  240. package/dist/esm/lib/telemetry-provider.js.map +1 -0
  241. package/dist/esm/lib/timeline-scrubber.js +173 -0
  242. package/dist/esm/lib/timeline-scrubber.js.map +1 -0
  243. package/dist/esm/lib/topology.js +591 -0
  244. package/dist/esm/lib/topology.js.map +1 -0
  245. package/dist/esm/lib/transport-agent.js +366 -0
  246. package/dist/esm/lib/transport-agent.js.map +1 -0
  247. package/dist/esm/lib/work-tree-dashboard.js +583 -0
  248. package/dist/esm/lib/work-tree-dashboard.js.map +1 -0
  249. package/dist/esm/lib/work-tree-ui.js +333 -0
  250. package/dist/esm/lib/work-tree-ui.js.map +1 -0
  251. package/dist/esm/lib/work-tree.js +480 -0
  252. package/dist/esm/lib/work-tree.js.map +1 -0
  253. package/dist/esm/run.js +144 -0
  254. package/dist/esm/run.js.map +1 -0
  255. package/dist/esm/security.js +1122 -0
  256. package/dist/esm/security.js.map +1 -0
  257. package/dist/index.d.ts +2 -0
  258. package/dist/index.d.ts.map +1 -1
  259. package/dist/index.js +6 -1
  260. package/dist/index.js.map +1 -1
  261. package/dist/lib/mcp-transport-http.d.ts +203 -0
  262. package/dist/lib/mcp-transport-http.d.ts.map +1 -0
  263. package/dist/lib/mcp-transport-http.js +528 -0
  264. package/dist/lib/mcp-transport-http.js.map +1 -0
  265. package/dist/lib/phase-pipeline.d.ts +31 -0
  266. package/dist/lib/phase-pipeline.d.ts.map +1 -1
  267. package/dist/lib/phase-pipeline.js +93 -1
  268. package/dist/lib/phase-pipeline.js.map +1 -1
  269. package/dist/lib/semantic-search.d.ts +42 -6
  270. package/dist/lib/semantic-search.d.ts.map +1 -1
  271. package/dist/lib/semantic-search.js +87 -6
  272. package/dist/lib/semantic-search.js.map +1 -1
  273. package/package.json +24 -4
@@ -0,0 +1,128 @@
1
+ "use strict";
2
+ /**
3
+ * CostGovernor — Pre-flight budget prediction for task DAGs.
4
+ *
5
+ * Walks a TaskDAG, estimates per-node token spend using a pluggable cost
6
+ * model, and checks the total against FederatedBudget before execution.
7
+ *
8
+ * @module CostGovernor
9
+ */
10
+ Object.defineProperty(exports, "__esModule", { value: true });
11
+ exports.CostGovernor = exports.LookupCostModel = void 0;
12
+ // ============================================================================
13
+ // DEFAULT COST MODEL
14
+ // ============================================================================
15
+ /**
16
+ * Lookup-based cost model. Register per-agent or per-action token estimates.
17
+ * Falls back to a configurable default.
18
+ */
19
+ class LookupCostModel {
20
+ agentDefaults = new Map();
21
+ actionOverrides = new Map();
22
+ defaultTokens;
23
+ constructor(defaultTokens = 500) {
24
+ this.defaultTokens = defaultTokens;
25
+ }
26
+ /** Set default token estimate for an agent */
27
+ setAgentDefault(agent, tokens) {
28
+ this.agentDefaults.set(agent, tokens);
29
+ }
30
+ /** Set token estimate for a specific agent:action pair */
31
+ setActionEstimate(agent, action, tokens) {
32
+ this.actionOverrides.set(`${agent}:${action}`, tokens);
33
+ }
34
+ estimate(agent, action, _params) {
35
+ const key = `${agent}:${action}`;
36
+ if (this.actionOverrides.has(key)) {
37
+ return { tokens: this.actionOverrides.get(key), confidence: 0.8 };
38
+ }
39
+ if (this.agentDefaults.has(agent)) {
40
+ return { tokens: this.agentDefaults.get(agent), confidence: 0.6 };
41
+ }
42
+ return { tokens: this.defaultTokens, confidence: 0.3 };
43
+ }
44
+ }
45
+ exports.LookupCostModel = LookupCostModel;
46
+ // ============================================================================
47
+ // COST GOVERNOR
48
+ // ============================================================================
49
+ /**
50
+ * Pre-flight budget check for task DAGs.
51
+ *
52
+ * @example
53
+ * ```ts
54
+ * const governor = new CostGovernor(budget, new LookupCostModel(1000));
55
+ * const prediction = governor.predict(dag.nodes);
56
+ * if (!prediction.withinBudget) {
57
+ * console.log('DAG would exceed budget by', -prediction.budgetRemaining, 'tokens');
58
+ * }
59
+ *
60
+ * // As approval callback:
61
+ * const options = { approvalCallback: (dag) => governor.approve(dag.nodes) };
62
+ * ```
63
+ */
64
+ class CostGovernor {
65
+ budget;
66
+ model;
67
+ constructor(budget, model) {
68
+ this.budget = budget;
69
+ this.model = model ?? new LookupCostModel();
70
+ }
71
+ /** Replace the cost model */
72
+ setCostModel(model) {
73
+ this.model = model;
74
+ }
75
+ /**
76
+ * Predict the total cost of a DAG and check against budget.
77
+ */
78
+ predict(nodes) {
79
+ const estimates = [];
80
+ const perAgent = {};
81
+ for (const node of nodes) {
82
+ const { tokens, confidence } = this.model.estimate(node.agent, node.action, node.params);
83
+ estimates.push({
84
+ taskId: node.id,
85
+ agent: node.agent,
86
+ action: node.action,
87
+ estimatedTokens: tokens,
88
+ confidence,
89
+ });
90
+ perAgent[node.agent] = (perAgent[node.agent] ?? 0) + tokens;
91
+ }
92
+ const totalTokens = estimates.reduce((sum, e) => sum + e.estimatedTokens, 0);
93
+ const budgetRemaining = this.budget.remaining() - totalTokens;
94
+ const budgetCeiling = this.budget.getCeiling();
95
+ const perAgentCeiling = this.budget.getPerAgentCeiling();
96
+ // Check per-agent overruns
97
+ const overBudgetAgents = [];
98
+ if (perAgentCeiling !== undefined) {
99
+ for (const [agent, predicted] of Object.entries(perAgent)) {
100
+ const alreadySpent = this.budget.getAgentSpent(agent);
101
+ if (alreadySpent + predicted > perAgentCeiling) {
102
+ overBudgetAgents.push(agent);
103
+ }
104
+ }
105
+ }
106
+ const avgConfidence = estimates.length > 0
107
+ ? estimates.reduce((s, e) => s + e.confidence, 0) / estimates.length
108
+ : 0;
109
+ return {
110
+ totalTokens,
111
+ nodes: estimates,
112
+ withinBudget: budgetRemaining >= 0 && overBudgetAgents.length === 0,
113
+ budgetRemaining,
114
+ budgetCeiling,
115
+ perAgent,
116
+ overBudgetAgents,
117
+ averageConfidence: avgConfidence,
118
+ };
119
+ }
120
+ /**
121
+ * Approval callback for TeamRunner — returns true if DAG fits budget.
122
+ */
123
+ async approve(nodes) {
124
+ return this.predict(nodes).withinBudget;
125
+ }
126
+ }
127
+ exports.CostGovernor = CostGovernor;
128
+ //# sourceMappingURL=cost-governor.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cost-governor.js","sourceRoot":"","sources":["../../../lib/cost-governor.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,161 @@
1
+ "use strict";
2
+ /**
3
+ * CostHeatmap — Per-agent cost & performance overlay for the topology graph.
4
+ *
5
+ * Tracks token spend (with configurable USD-per-token rates), latency
6
+ * percentiles, throughput, and error rates per agent so the dashboard can
7
+ * render a cost/performance heatmap on top of the topology view.
8
+ *
9
+ * @module CostHeatmap
10
+ */
11
+ Object.defineProperty(exports, "__esModule", { value: true });
12
+ exports.CostHeatmap = void 0;
13
+ // ============================================================================
14
+ // HEATMAP
15
+ // ============================================================================
16
+ /**
17
+ * Tracks per-agent cost and performance for heatmap rendering.
18
+ *
19
+ * @example
20
+ * ```ts
21
+ * const heatmap = new CostHeatmap();
22
+ * heatmap.setCostRate('gpt-4', { inputPer1k: 0.03, outputPer1k: 0.06 });
23
+ * heatmap.record('agent-1', { durationMs: 200, inputTokens: 500, outputTokens: 100, success: true });
24
+ * const snap = heatmap.getSnapshot();
25
+ * ```
26
+ */
27
+ class CostHeatmap {
28
+ samples = new Map();
29
+ costRates = new Map();
30
+ agentModels = new Map();
31
+ defaultRate = { inputPer1k: 0.01, outputPer1k: 0.03 };
32
+ maxSamplesPerAgent;
33
+ windowMs;
34
+ constructor(options) {
35
+ this.maxSamplesPerAgent = options?.maxSamplesPerAgent ?? 1000;
36
+ this.windowMs = options?.windowMs ?? 60_000;
37
+ if (options?.defaultRate)
38
+ this.defaultRate = options.defaultRate;
39
+ }
40
+ /** Set the cost rate for a model */
41
+ setCostRate(model, rate) {
42
+ this.costRates.set(model, rate);
43
+ }
44
+ /** Associate an agent with a model (for cost lookups) */
45
+ setAgentModel(agentId, model) {
46
+ this.agentModels.set(agentId, model);
47
+ }
48
+ /** Record an execution sample for an agent */
49
+ record(agentId, sample) {
50
+ let list = this.samples.get(agentId);
51
+ if (!list) {
52
+ list = [];
53
+ this.samples.set(agentId, list);
54
+ }
55
+ list.push({
56
+ timestamp: sample.timestamp ?? Date.now(),
57
+ durationMs: sample.durationMs,
58
+ inputTokens: sample.inputTokens,
59
+ outputTokens: sample.outputTokens,
60
+ success: sample.success,
61
+ });
62
+ // Evict oldest
63
+ if (list.length > this.maxSamplesPerAgent) {
64
+ list.splice(0, list.length - this.maxSamplesPerAgent);
65
+ }
66
+ }
67
+ /** Get the heatmap cell for a single agent */
68
+ getCell(agentId) {
69
+ const list = this.samples.get(agentId);
70
+ if (!list || list.length === 0)
71
+ return null;
72
+ return this.computeCell(agentId, list);
73
+ }
74
+ /** Get the full heatmap snapshot */
75
+ getSnapshot() {
76
+ const cells = [];
77
+ let totalCostUsd = 0;
78
+ let totalTokens = 0;
79
+ for (const [agentId, list] of this.samples) {
80
+ if (list.length === 0)
81
+ continue;
82
+ const cell = this.computeCell(agentId, list);
83
+ cells.push(cell);
84
+ totalCostUsd += cell.costUsd;
85
+ totalTokens += cell.totalTokens;
86
+ }
87
+ // Normalize heat values (relative to max cost in this snapshot)
88
+ const maxCost = Math.max(...cells.map(c => c.costUsd), 0.001);
89
+ const maxLatency = Math.max(...cells.map(c => c.p95LatencyMs), 1);
90
+ for (const cell of cells) {
91
+ // Heat = 60% cost weight + 40% latency weight
92
+ cell.heat = Math.min(1, 0.6 * (cell.costUsd / maxCost) + 0.4 * (cell.p95LatencyMs / maxLatency));
93
+ }
94
+ cells.sort((a, b) => b.heat - a.heat);
95
+ return {
96
+ timestamp: new Date().toISOString(),
97
+ cells,
98
+ totalCostUsd,
99
+ totalTokens,
100
+ hottestAgent: cells.length > 0 ? cells[0].agentId : null,
101
+ };
102
+ }
103
+ /** List all tracked agent IDs */
104
+ listAgents() {
105
+ return [...this.samples.keys()];
106
+ }
107
+ /** Clear all data */
108
+ clear() {
109
+ this.samples.clear();
110
+ }
111
+ /** Clear data for a specific agent */
112
+ clearAgent(agentId) {
113
+ this.samples.delete(agentId);
114
+ }
115
+ computeCell(agentId, list) {
116
+ const model = this.agentModels.get(agentId);
117
+ const rate = model ? (this.costRates.get(model) ?? this.defaultRate) : this.defaultRate;
118
+ let totalInputTokens = 0;
119
+ let totalOutputTokens = 0;
120
+ let totalDurationMs = 0;
121
+ let errors = 0;
122
+ const durations = [];
123
+ const now = Date.now();
124
+ let recentCount = 0;
125
+ for (const s of list) {
126
+ totalInputTokens += s.inputTokens;
127
+ totalOutputTokens += s.outputTokens;
128
+ totalDurationMs += s.durationMs;
129
+ durations.push(s.durationMs);
130
+ if (!s.success)
131
+ errors++;
132
+ if (now - s.timestamp <= this.windowMs)
133
+ recentCount++;
134
+ }
135
+ durations.sort((a, b) => a - b);
136
+ const totalTokens = totalInputTokens + totalOutputTokens;
137
+ const costUsd = (totalInputTokens / 1000) * rate.inputPer1k + (totalOutputTokens / 1000) * rate.outputPer1k;
138
+ return {
139
+ agentId,
140
+ costUsd,
141
+ totalTokens,
142
+ executions: list.length,
143
+ errors,
144
+ errorRate: list.length > 0 ? errors / list.length : 0,
145
+ avgLatencyMs: list.length > 0 ? totalDurationMs / list.length : 0,
146
+ p50LatencyMs: this.percentile(durations, 0.50),
147
+ p95LatencyMs: this.percentile(durations, 0.95),
148
+ p99LatencyMs: this.percentile(durations, 0.99),
149
+ throughputPerMin: this.windowMs > 0 ? (recentCount / this.windowMs) * 60_000 : 0,
150
+ heat: 0, // Will be normalized in getSnapshot()
151
+ };
152
+ }
153
+ percentile(sorted, p) {
154
+ if (sorted.length === 0)
155
+ return 0;
156
+ const idx = Math.ceil(p * sorted.length) - 1;
157
+ return sorted[Math.max(0, idx)];
158
+ }
159
+ }
160
+ exports.CostHeatmap = CostHeatmap;
161
+ //# sourceMappingURL=cost-heatmap.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cost-heatmap.js","sourceRoot":"","sources":["../../../lib/cost-heatmap.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,213 @@
1
+ "use strict";
2
+ /**
3
+ * Coverage Gate — Recursive Refinement Loop for Network-AI
4
+ *
5
+ * Prevents the system from finishing with incomplete data by acting as a
6
+ * gatekeeper before the `submit_final` action is allowed. An evaluator LLM
7
+ * scores the current Blackboard state against the original user goal and
8
+ * produces a gap list. If the score is below the configured threshold the
9
+ * orchestrator feeds the gaps back into GoalDecomposer to generate new
10
+ * sub-tasks. Execution only reaches the COMPLETE state when the score
11
+ * clears the threshold (or the maximum refinement count is reached).
12
+ *
13
+ * The EVALUATING FSM state (added to WORKFLOW_STATES) signals that a
14
+ * refinement loop is in progress.
15
+ *
16
+ * Zero external dependencies — the evaluator function is pluggable.
17
+ *
18
+ * @module CoverageGate
19
+ * @version 1.0.0
20
+ */
21
+ Object.defineProperty(exports, "__esModule", { value: true });
22
+ exports.CoverageGate = void 0;
23
+ exports.createKeywordEvaluator = createKeywordEvaluator;
24
+ exports.createLLMEvaluator = createLLMEvaluator;
25
+ // ============================================================================
26
+ // BUILT-IN EVALUATORS
27
+ // ============================================================================
28
+ /**
29
+ * A simple keyword-gap evaluator that checks whether each expected topic
30
+ * keyword appears anywhere in the stringified blackboard values.
31
+ *
32
+ * Useful for deterministic tests and quick smoke-tests without an LLM.
33
+ *
34
+ * @param expectedTopics - List of keywords/phrases that must appear in the board
35
+ */
36
+ function createKeywordEvaluator(expectedTopics) {
37
+ return async (goal, blackboardSummary) => {
38
+ const stateText = JSON.stringify(blackboardSummary).toLowerCase();
39
+ const gaps = [];
40
+ for (const topic of expectedTopics) {
41
+ if (!stateText.includes(topic.toLowerCase())) {
42
+ gaps.push(topic);
43
+ }
44
+ }
45
+ const covered = expectedTopics.length - gaps.length;
46
+ const score = expectedTopics.length === 0
47
+ ? 100
48
+ : Math.round((covered / expectedTopics.length) * 100);
49
+ return {
50
+ score,
51
+ gaps,
52
+ summary: `Covered ${covered}/${expectedTopics.length} expected topics. Missing: ${gaps.length === 0 ? 'none' : gaps.join(', ')}.`,
53
+ evaluatedAt: Date.now(),
54
+ };
55
+ };
56
+ }
57
+ /**
58
+ * Build an evaluator backed by an LLM via the Network-AI executor API.
59
+ *
60
+ * @param executor - Network-AI executor function
61
+ * @param evaluatorAgentId - Agent ID for the evaluator model
62
+ */
63
+ function createLLMEvaluator(executor, evaluatorAgentId) {
64
+ return async (goal, blackboardSummary) => {
65
+ const prompt = [
66
+ 'You are a coverage evaluator for a multi-agent AI system.',
67
+ 'Evaluate how completely the current state addresses the original goal.',
68
+ '',
69
+ `ORIGINAL GOAL: ${goal}`,
70
+ '',
71
+ 'CURRENT STATE (Blackboard summary):',
72
+ JSON.stringify(blackboardSummary, null, 2),
73
+ '',
74
+ 'Score the completeness from 0 to 100 and list any remaining gaps.',
75
+ '',
76
+ 'Respond with ONLY valid JSON:',
77
+ '{"score":0-100,"gaps":["gap 1","gap 2"],"summary":"..."}',
78
+ ].join('\n');
79
+ try {
80
+ const result = await executor(evaluatorAgentId, { action: 'evaluate', params: { prompt, goal } }, { agentId: evaluatorAgentId, taskId: `coverage-eval-${Date.now()}`, metadata: { type: 'coverage-evaluation' } });
81
+ if (!result.success || !result.data) {
82
+ return {
83
+ score: 0,
84
+ gaps: [result.error?.message ?? 'Evaluator returned no data'],
85
+ summary: 'Evaluation failed — treating as incomplete',
86
+ evaluatedAt: Date.now(),
87
+ };
88
+ }
89
+ const raw = typeof result.data === 'string' ? result.data : JSON.stringify(result.data);
90
+ // Strip markdown fences
91
+ let cleaned = raw.trim().replace(/```[a-z]*\n?/g, '').replace(/```/g, '').trim();
92
+ const start = cleaned.indexOf('{');
93
+ const end = cleaned.lastIndexOf('}');
94
+ if (start !== -1 && end > start)
95
+ cleaned = cleaned.substring(start, end + 1);
96
+ let parsed;
97
+ try {
98
+ parsed = JSON.parse(cleaned);
99
+ }
100
+ catch {
101
+ return {
102
+ score: 50,
103
+ gaps: ['Could not parse evaluator response'],
104
+ summary: 'Parse error — defaulting to score 50',
105
+ evaluatedAt: Date.now(),
106
+ };
107
+ }
108
+ return {
109
+ score: Math.min(100, Math.max(0, Number(parsed.score) || 0)),
110
+ gaps: Array.isArray(parsed.gaps) ? parsed.gaps.map(String) : [],
111
+ summary: String(parsed.summary ?? ''),
112
+ evaluatedAt: Date.now(),
113
+ };
114
+ }
115
+ catch (err) {
116
+ return {
117
+ score: 0,
118
+ gaps: [err.message],
119
+ summary: `Evaluator threw: ${err.message}`,
120
+ evaluatedAt: Date.now(),
121
+ };
122
+ }
123
+ };
124
+ }
125
+ // ============================================================================
126
+ // COVERAGE GATE (OOP interface)
127
+ // ============================================================================
128
+ /**
129
+ * CoverageGate is the final gatekeeper before `submit_final`.
130
+ *
131
+ * Call `evaluate()` after each execution round. If it returns `passed: false`,
132
+ * use `result.evaluation.gaps` to generate additional sub-tasks via
133
+ * GoalDecomposer, then re-run and evaluate again.
134
+ *
135
+ * @example
136
+ * ```typescript
137
+ * const gate = new CoverageGate(myLLMEvaluator, { threshold: 90, maxRefinements: 3 });
138
+ *
139
+ * let boardSnapshot = blackboard.snapshot();
140
+ * let gateResult = await gate.evaluate(goal, boardSnapshot);
141
+ *
142
+ * while (!gateResult.passed && !gateResult.maxRefinementsReached) {
143
+ * const gapGoal = `Fill these gaps: ${gateResult.evaluation.gaps.join(', ')}`;
144
+ * const gapDag = await decomposer.decompose(gapGoal, agents);
145
+ * await runner.run(gapDag, runOptions);
146
+ * boardSnapshot = blackboard.snapshot();
147
+ * gateResult = await gate.evaluate(goal, boardSnapshot);
148
+ * }
149
+ * ```
150
+ */
151
+ class CoverageGate {
152
+ evaluatorFn;
153
+ threshold;
154
+ maxRefinements;
155
+ _refinementsUsed = 0;
156
+ _history = [];
157
+ constructor(evaluatorFn, options = {}) {
158
+ this.evaluatorFn = evaluatorFn;
159
+ this.threshold = Math.min(100, Math.max(0, options.threshold ?? 90));
160
+ this.maxRefinements = Math.max(0, options.maxRefinements ?? 3);
161
+ }
162
+ /**
163
+ * Evaluate the current blackboard state against the original goal.
164
+ *
165
+ * Each call increments the internal refinement counter. When
166
+ * `maxRefinements` is reached the gate is treated as passed (fail-open)
167
+ * to prevent infinite loops, and `maxRefinementsReached` is set to true.
168
+ *
169
+ * @param goal - Original user goal
170
+ * @param blackboardSummary - Current blackboard snapshot (key → value)
171
+ */
172
+ async evaluate(goal, blackboardSummary) {
173
+ const evaluation = await this.evaluatorFn(goal, blackboardSummary);
174
+ const maxRefinementsReached = this._refinementsUsed >= this.maxRefinements;
175
+ const passed = evaluation.score >= this.threshold || maxRefinementsReached;
176
+ const round = {
177
+ round: this._refinementsUsed + 1,
178
+ evaluation,
179
+ passed,
180
+ gapsRequeued: passed ? [] : evaluation.gaps,
181
+ };
182
+ this._history.push(round);
183
+ if (!passed) {
184
+ this._refinementsUsed++;
185
+ }
186
+ return {
187
+ passed,
188
+ evaluation,
189
+ threshold: this.threshold,
190
+ refinementsUsed: this._refinementsUsed,
191
+ maxRefinementsReached,
192
+ };
193
+ }
194
+ /** Reset the refinement counter and history (allows reuse across separate goals). */
195
+ reset() {
196
+ this._refinementsUsed = 0;
197
+ this._history = [];
198
+ }
199
+ /** History of all refinement rounds evaluated so far. */
200
+ get history() {
201
+ return this._history;
202
+ }
203
+ /** Current refinement count (before this becomes a pass-through). */
204
+ get refinementsUsed() {
205
+ return this._refinementsUsed;
206
+ }
207
+ /** The configured threshold (0–100). */
208
+ get scoreThreshold() {
209
+ return this.threshold;
210
+ }
211
+ }
212
+ exports.CoverageGate = CoverageGate;
213
+ //# sourceMappingURL=coverage-gate.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"coverage-gate.js","sourceRoot":"","sources":["../../../lib/coverage-gate.ts"],"names":[],"mappings":"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"}