nexus-ai-pro 1.25.0 → 2.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 (366) hide show
  1. package/API_STABILITY.md +71 -4
  2. package/CHANGELOG.md +242 -1
  3. package/MIGRATING.md +200 -66
  4. package/README.md +30 -9
  5. package/dist/agent/create-agent.d.ts +15 -1
  6. package/dist/agent/create-agent.js +43 -3
  7. package/dist/agent/index.d.ts +1 -1
  8. package/dist/agent/index.js +1 -1
  9. package/dist/agent/loop.js +2 -2
  10. package/dist/agent/tool.d.ts +14 -1
  11. package/dist/agent/tool.js +17 -0
  12. package/dist/batch/manager.d.ts +7 -0
  13. package/dist/batch/manager.js +13 -2
  14. package/dist/capabilities/negotiate.js +9 -2
  15. package/dist/cli/graph.d.ts +9 -0
  16. package/dist/cli/graph.js +47 -0
  17. package/dist/cli/migrate.js +101 -1
  18. package/dist/cli/root-moves.d.ts +6 -2
  19. package/dist/cli/root-moves.js +1 -1
  20. package/dist/cli.js +9 -1
  21. package/dist/context/window.js +2 -0
  22. package/dist/core/lifecycle.d.ts +106 -0
  23. package/dist/core/lifecycle.js +257 -0
  24. package/dist/core/nexus.d.ts +66 -19
  25. package/dist/core/nexus.js +271 -273
  26. package/dist/core/response-format.d.ts +6 -1
  27. package/dist/core/response-format.js +44 -18
  28. package/dist/core/secure-stream.js +0 -1
  29. package/dist/core/usage.d.ts +3 -3
  30. package/dist/core/usage.js +2 -6
  31. package/dist/embeddings/auto-providers.d.ts +6 -0
  32. package/dist/embeddings/auto-providers.js +14 -0
  33. package/dist/embeddings/engine.d.ts +52 -0
  34. package/dist/embeddings/engine.js +560 -0
  35. package/dist/embeddings/manager.d.ts +20 -34
  36. package/dist/embeddings/manager.js +17 -536
  37. package/dist/embeddings/register.js +12 -29
  38. package/dist/evals/judge.d.ts +11 -0
  39. package/dist/evals/judge.js +33 -0
  40. package/dist/evaluate/index.d.ts +1 -0
  41. package/dist/evaluate/index.js +1 -0
  42. package/dist/evaluate/provenance.d.ts +22 -0
  43. package/dist/evaluate/provenance.js +10 -0
  44. package/dist/evaluate/run.js +20 -4
  45. package/dist/graph/checkpoint-migration.d.ts +21 -17
  46. package/dist/graph/checkpoint-migration.js +8 -4
  47. package/dist/graph/checkpointer.d.ts +6 -3
  48. package/dist/graph/checkpointer.js +7 -3
  49. package/dist/graph/durability.d.ts +27 -0
  50. package/dist/graph/durability.js +66 -0
  51. package/dist/graph/errors.d.ts +30 -4
  52. package/dist/graph/errors.js +18 -2
  53. package/dist/graph/event-stream.d.ts +75 -0
  54. package/dist/graph/event-stream.js +289 -0
  55. package/dist/graph/functional.d.ts +6 -0
  56. package/dist/graph/functional.js +12 -8
  57. package/dist/graph/graph.d.ts +50 -4
  58. package/dist/graph/graph.js +339 -79
  59. package/dist/graph/index.d.ts +5 -3
  60. package/dist/graph/index.js +4 -2
  61. package/dist/graph/lint.d.ts +57 -0
  62. package/dist/graph/lint.js +141 -0
  63. package/dist/graph/run-control.d.ts +28 -0
  64. package/dist/graph/run-control.js +26 -0
  65. package/dist/images/dimensions.d.ts +5 -0
  66. package/dist/images/dimensions.js +9 -0
  67. package/dist/images/index.d.ts +1 -1
  68. package/dist/images/manager.d.ts +0 -11
  69. package/dist/images/manager.js +11 -379
  70. package/dist/images/operation.d.ts +17 -0
  71. package/dist/images/operation.js +367 -0
  72. package/dist/index.d.ts +17 -1089
  73. package/dist/index.js +8 -80
  74. package/dist/jobs/queue.d.ts +6 -0
  75. package/dist/jobs/queue.js +2 -1
  76. package/dist/lifecycle/budget.d.ts +55 -0
  77. package/dist/lifecycle/budget.js +70 -0
  78. package/dist/lifecycle/index.d.ts +8 -0
  79. package/dist/lifecycle/index.js +2 -0
  80. package/dist/lifecycle/run.d.ts +10 -0
  81. package/dist/lifecycle/run.js +14 -0
  82. package/dist/models/registry.d.ts +4 -5
  83. package/dist/models/registry.js +16 -7
  84. package/dist/operations/runner.js +13 -15
  85. package/dist/ops/audit-logger.d.ts +2 -0
  86. package/dist/ops/audit-logger.js +3 -0
  87. package/dist/ops/family-telemetry.d.ts +32 -21
  88. package/dist/ops/family-telemetry.js +24 -52
  89. package/dist/ops/health.d.ts +24 -6
  90. package/dist/ops/health.js +38 -12
  91. package/dist/ops/index.d.ts +1 -1
  92. package/dist/ops/index.js +1 -1
  93. package/dist/ops/metrics.d.ts +4 -6
  94. package/dist/ops/metrics.js +9 -3
  95. package/dist/ops/rate-limit-adapters.d.ts +23 -0
  96. package/dist/ops/rate-limit-adapters.js +34 -0
  97. package/dist/ops/rate-limiter.d.ts +12 -2
  98. package/dist/ops/rate-limiter.js +29 -0
  99. package/dist/optimizer/index.js +0 -2
  100. package/dist/pipeline/index.d.ts +1 -1
  101. package/dist/pipeline/pipeline.d.ts +17 -11
  102. package/dist/pipeline/pipeline.js +15 -7
  103. package/dist/pipeline/types.d.ts +36 -18
  104. package/dist/providers/anthropic.d.ts +4 -2
  105. package/dist/providers/anthropic.js +168 -42
  106. package/dist/providers/base.d.ts +8 -4
  107. package/dist/providers/base.js +0 -1
  108. package/dist/providers/cohere.d.ts +0 -1
  109. package/dist/providers/cohere.js +11 -25
  110. package/dist/providers/content.d.ts +29 -0
  111. package/dist/providers/content.js +79 -0
  112. package/dist/providers/google.d.ts +2 -0
  113. package/dist/providers/google.js +61 -18
  114. package/dist/providers/groq.d.ts +8 -3
  115. package/dist/providers/groq.js +17 -21
  116. package/dist/providers/lazy.d.ts +32 -0
  117. package/dist/providers/lazy.js +154 -0
  118. package/dist/providers/mistral.d.ts +8 -3
  119. package/dist/providers/mistral.js +17 -21
  120. package/dist/providers/ollama.js +0 -2
  121. package/dist/providers/openai.d.ts +15 -2
  122. package/dist/providers/openai.js +137 -44
  123. package/dist/providers/openrouter.d.ts +3 -2
  124. package/dist/providers/openrouter.js +4 -4
  125. package/dist/realtime/session.d.ts +5 -0
  126. package/dist/realtime/session.js +32 -0
  127. package/dist/realtime/types.d.ts +6 -0
  128. package/dist/router/auto-router.js +10 -20
  129. package/dist/router/failover.d.ts +6 -0
  130. package/dist/router/failover.js +14 -10
  131. package/dist/security/index.js +0 -5
  132. package/dist/security/schema-validator.d.ts +6 -230
  133. package/dist/security/schema-validator.js +142 -56
  134. package/dist/security/upload-scanner.d.ts +2 -2
  135. package/dist/security/upload-scanner.js +1 -1
  136. package/dist/server/assistant.d.ts +40 -0
  137. package/dist/server/assistant.js +31 -0
  138. package/dist/server/runs.d.ts +4 -0
  139. package/dist/server/runs.js +21 -1
  140. package/dist/server/tenancy.d.ts +2 -4
  141. package/dist/server/tenancy.js +1 -30
  142. package/dist/telephony/manager.d.ts +5 -2
  143. package/dist/telephony/manager.js +24 -49
  144. package/dist/testing/provider-conformance.js +4 -4
  145. package/dist/testing/record.d.ts +42 -0
  146. package/dist/testing/record.js +57 -5
  147. package/dist/tracing/index.d.ts +3 -3
  148. package/dist/tracing/index.js +2 -2
  149. package/dist/tracing/instrument.js +28 -0
  150. package/dist/tracing/otlp.d.ts +91 -0
  151. package/dist/tracing/otlp.js +124 -0
  152. package/dist/tracing/rollups.d.ts +100 -0
  153. package/dist/tracing/rollups.js +139 -0
  154. package/dist/tracing/stores.d.ts +17 -0
  155. package/dist/tracing/stores.js +23 -0
  156. package/dist/tracing/tracer.d.ts +50 -4
  157. package/dist/tracing/tracer.js +85 -6
  158. package/dist/types/batch.d.ts +7 -8
  159. package/dist/types/config.d.ts +39 -22
  160. package/dist/types/embeddings.d.ts +6 -12
  161. package/dist/types/evaluate.d.ts +37 -0
  162. package/dist/types/graph.d.ts +390 -25
  163. package/dist/types/graph.js +3 -1
  164. package/dist/types/images.d.ts +6 -14
  165. package/dist/types/lifecycle.d.ts +163 -0
  166. package/dist/types/lifecycle.js +1 -0
  167. package/dist/types/messages.d.ts +41 -2
  168. package/dist/types/operations.d.ts +16 -2
  169. package/dist/types/optimizer.d.ts +0 -6
  170. package/dist/types/providers.d.ts +11 -20
  171. package/dist/types/providers.js +326 -203
  172. package/dist/types/response.d.ts +12 -5
  173. package/dist/types/security.d.ts +0 -12
  174. package/dist/types/server.d.ts +9 -0
  175. package/dist/types/telephony.d.ts +7 -6
  176. package/dist/types/tracing.d.ts +11 -0
  177. package/dist/types/voice.d.ts +5 -4
  178. package/dist/utils/deprecation.d.ts +0 -2
  179. package/dist/utils/deprecation.js +0 -4
  180. package/dist/utils/periods.d.ts +7 -0
  181. package/dist/utils/periods.js +30 -0
  182. package/dist/utils/tokenizer.js +2 -0
  183. package/dist/version.d.ts +5 -0
  184. package/dist/version.js +1 -0
  185. package/dist/voice/manager.js +6 -6
  186. package/dist-cjs/agent/create-agent.d.ts +15 -1
  187. package/dist-cjs/agent/create-agent.js +42 -2
  188. package/dist-cjs/agent/index.d.ts +1 -1
  189. package/dist-cjs/agent/index.js +4 -1
  190. package/dist-cjs/agent/loop.js +1 -1
  191. package/dist-cjs/agent/tool.d.ts +14 -1
  192. package/dist-cjs/agent/tool.js +20 -0
  193. package/dist-cjs/batch/manager.d.ts +7 -0
  194. package/dist-cjs/batch/manager.js +13 -2
  195. package/dist-cjs/capabilities/negotiate.js +9 -2
  196. package/dist-cjs/cli/graph.d.ts +9 -0
  197. package/dist-cjs/cli/graph.js +50 -0
  198. package/dist-cjs/cli/migrate.js +101 -1
  199. package/dist-cjs/cli/root-moves.d.ts +6 -2
  200. package/dist-cjs/cli/root-moves.js +1 -1
  201. package/dist-cjs/context/window.js +2 -0
  202. package/dist-cjs/core/lifecycle.d.ts +106 -0
  203. package/dist-cjs/core/lifecycle.js +263 -0
  204. package/dist-cjs/core/nexus.d.ts +66 -19
  205. package/dist-cjs/core/nexus.js +315 -284
  206. package/dist-cjs/core/response-format.d.ts +6 -1
  207. package/dist-cjs/core/response-format.js +77 -21
  208. package/dist-cjs/core/secure-stream.js +0 -1
  209. package/dist-cjs/core/usage.d.ts +3 -3
  210. package/dist-cjs/core/usage.js +1 -5
  211. package/dist-cjs/embeddings/auto-providers.d.ts +6 -0
  212. package/dist-cjs/embeddings/auto-providers.js +17 -0
  213. package/dist-cjs/embeddings/engine.d.ts +52 -0
  214. package/dist-cjs/embeddings/engine.js +564 -0
  215. package/dist-cjs/embeddings/manager.d.ts +20 -34
  216. package/dist-cjs/embeddings/manager.js +53 -539
  217. package/dist-cjs/embeddings/register.js +12 -29
  218. package/dist-cjs/evals/judge.d.ts +11 -0
  219. package/dist-cjs/evals/judge.js +33 -0
  220. package/dist-cjs/evaluate/index.d.ts +1 -0
  221. package/dist-cjs/evaluate/index.js +3 -1
  222. package/dist-cjs/evaluate/provenance.d.ts +22 -0
  223. package/dist-cjs/evaluate/provenance.js +14 -0
  224. package/dist-cjs/evaluate/run.js +20 -4
  225. package/dist-cjs/graph/checkpoint-migration.d.ts +21 -17
  226. package/dist-cjs/graph/checkpoint-migration.js +9 -4
  227. package/dist-cjs/graph/checkpointer.d.ts +6 -3
  228. package/dist-cjs/graph/checkpointer.js +7 -3
  229. package/dist-cjs/graph/durability.d.ts +27 -0
  230. package/dist-cjs/graph/durability.js +70 -0
  231. package/dist-cjs/graph/errors.d.ts +30 -4
  232. package/dist-cjs/graph/errors.js +20 -3
  233. package/dist-cjs/graph/event-stream.d.ts +75 -0
  234. package/dist-cjs/graph/event-stream.js +295 -0
  235. package/dist-cjs/graph/functional.d.ts +6 -0
  236. package/dist-cjs/graph/functional.js +12 -8
  237. package/dist-cjs/graph/graph.d.ts +50 -4
  238. package/dist-cjs/graph/graph.js +338 -78
  239. package/dist-cjs/graph/index.d.ts +5 -3
  240. package/dist-cjs/graph/index.js +8 -1
  241. package/dist-cjs/graph/lint.d.ts +57 -0
  242. package/dist-cjs/graph/lint.js +144 -0
  243. package/dist-cjs/graph/run-control.d.ts +28 -0
  244. package/dist-cjs/graph/run-control.js +30 -0
  245. package/dist-cjs/images/dimensions.d.ts +5 -0
  246. package/dist-cjs/images/dimensions.js +12 -0
  247. package/dist-cjs/images/index.d.ts +1 -1
  248. package/dist-cjs/images/manager.d.ts +0 -11
  249. package/dist-cjs/images/manager.js +44 -379
  250. package/dist-cjs/images/operation.d.ts +17 -0
  251. package/dist-cjs/images/operation.js +370 -0
  252. package/dist-cjs/index.d.ts +17 -1089
  253. package/dist-cjs/index.js +11 -299
  254. package/dist-cjs/jobs/queue.d.ts +6 -0
  255. package/dist-cjs/jobs/queue.js +2 -1
  256. package/dist-cjs/lifecycle/budget.d.ts +55 -0
  257. package/dist-cjs/lifecycle/budget.js +75 -0
  258. package/dist-cjs/lifecycle/index.d.ts +8 -0
  259. package/dist-cjs/lifecycle/index.js +11 -0
  260. package/dist-cjs/lifecycle/run.d.ts +10 -0
  261. package/dist-cjs/lifecycle/run.js +17 -0
  262. package/dist-cjs/models/registry.d.ts +4 -5
  263. package/dist-cjs/models/registry.js +16 -7
  264. package/dist-cjs/operations/runner.js +13 -15
  265. package/dist-cjs/ops/audit-logger.d.ts +2 -0
  266. package/dist-cjs/ops/audit-logger.js +3 -0
  267. package/dist-cjs/ops/family-telemetry.d.ts +32 -21
  268. package/dist-cjs/ops/family-telemetry.js +24 -52
  269. package/dist-cjs/ops/health.d.ts +24 -6
  270. package/dist-cjs/ops/health.js +38 -12
  271. package/dist-cjs/ops/index.d.ts +1 -1
  272. package/dist-cjs/ops/metrics.d.ts +4 -6
  273. package/dist-cjs/ops/metrics.js +9 -3
  274. package/dist-cjs/ops/rate-limit-adapters.d.ts +23 -0
  275. package/dist-cjs/ops/rate-limit-adapters.js +35 -1
  276. package/dist-cjs/ops/rate-limiter.d.ts +12 -2
  277. package/dist-cjs/ops/rate-limiter.js +30 -0
  278. package/dist-cjs/optimizer/index.js +0 -2
  279. package/dist-cjs/pipeline/index.d.ts +1 -1
  280. package/dist-cjs/pipeline/pipeline.d.ts +17 -11
  281. package/dist-cjs/pipeline/pipeline.js +15 -7
  282. package/dist-cjs/pipeline/types.d.ts +36 -18
  283. package/dist-cjs/providers/anthropic.d.ts +4 -2
  284. package/dist-cjs/providers/anthropic.js +168 -42
  285. package/dist-cjs/providers/base.d.ts +8 -4
  286. package/dist-cjs/providers/base.js +0 -1
  287. package/dist-cjs/providers/cohere.d.ts +0 -1
  288. package/dist-cjs/providers/cohere.js +11 -25
  289. package/dist-cjs/providers/content.d.ts +29 -0
  290. package/dist-cjs/providers/content.js +88 -0
  291. package/dist-cjs/providers/google.d.ts +2 -0
  292. package/dist-cjs/providers/google.js +61 -18
  293. package/dist-cjs/providers/groq.d.ts +8 -3
  294. package/dist-cjs/providers/groq.js +17 -21
  295. package/dist-cjs/providers/lazy.d.ts +32 -0
  296. package/dist-cjs/providers/lazy.js +192 -0
  297. package/dist-cjs/providers/mistral.d.ts +8 -3
  298. package/dist-cjs/providers/mistral.js +17 -21
  299. package/dist-cjs/providers/ollama.js +0 -2
  300. package/dist-cjs/providers/openai.d.ts +15 -2
  301. package/dist-cjs/providers/openai.js +137 -44
  302. package/dist-cjs/providers/openrouter.d.ts +3 -2
  303. package/dist-cjs/providers/openrouter.js +4 -4
  304. package/dist-cjs/realtime/session.d.ts +5 -0
  305. package/dist-cjs/realtime/session.js +32 -0
  306. package/dist-cjs/realtime/types.d.ts +6 -0
  307. package/dist-cjs/router/auto-router.js +9 -19
  308. package/dist-cjs/router/failover.d.ts +6 -0
  309. package/dist-cjs/router/failover.js +14 -10
  310. package/dist-cjs/security/index.js +0 -5
  311. package/dist-cjs/security/schema-validator.d.ts +6 -230
  312. package/dist-cjs/security/schema-validator.js +143 -57
  313. package/dist-cjs/security/upload-scanner.d.ts +2 -2
  314. package/dist-cjs/security/upload-scanner.js +1 -1
  315. package/dist-cjs/server/assistant.d.ts +40 -0
  316. package/dist-cjs/server/assistant.js +31 -0
  317. package/dist-cjs/server/runs.d.ts +4 -0
  318. package/dist-cjs/server/runs.js +21 -1
  319. package/dist-cjs/server/tenancy.d.ts +2 -4
  320. package/dist-cjs/server/tenancy.js +5 -34
  321. package/dist-cjs/telephony/manager.d.ts +5 -2
  322. package/dist-cjs/telephony/manager.js +24 -49
  323. package/dist-cjs/testing/provider-conformance.js +4 -4
  324. package/dist-cjs/testing/record.d.ts +42 -0
  325. package/dist-cjs/testing/record.js +57 -5
  326. package/dist-cjs/tracing/index.d.ts +3 -3
  327. package/dist-cjs/tracing/index.js +4 -1
  328. package/dist-cjs/tracing/instrument.js +28 -0
  329. package/dist-cjs/tracing/otlp.d.ts +91 -0
  330. package/dist-cjs/tracing/otlp.js +129 -0
  331. package/dist-cjs/tracing/rollups.d.ts +100 -0
  332. package/dist-cjs/tracing/rollups.js +147 -0
  333. package/dist-cjs/tracing/stores.d.ts +17 -0
  334. package/dist-cjs/tracing/stores.js +24 -0
  335. package/dist-cjs/tracing/tracer.d.ts +50 -4
  336. package/dist-cjs/tracing/tracer.js +87 -6
  337. package/dist-cjs/types/batch.d.ts +7 -8
  338. package/dist-cjs/types/config.d.ts +39 -22
  339. package/dist-cjs/types/embeddings.d.ts +6 -12
  340. package/dist-cjs/types/evaluate.d.ts +37 -0
  341. package/dist-cjs/types/graph.d.ts +390 -25
  342. package/dist-cjs/types/graph.js +3 -1
  343. package/dist-cjs/types/images.d.ts +6 -14
  344. package/dist-cjs/types/lifecycle.d.ts +163 -0
  345. package/dist-cjs/types/lifecycle.js +2 -0
  346. package/dist-cjs/types/messages.d.ts +41 -2
  347. package/dist-cjs/types/operations.d.ts +16 -2
  348. package/dist-cjs/types/optimizer.d.ts +0 -6
  349. package/dist-cjs/types/providers.d.ts +11 -20
  350. package/dist-cjs/types/providers.js +326 -203
  351. package/dist-cjs/types/response.d.ts +12 -5
  352. package/dist-cjs/types/security.d.ts +0 -12
  353. package/dist-cjs/types/server.d.ts +9 -0
  354. package/dist-cjs/types/telephony.d.ts +7 -6
  355. package/dist-cjs/types/tracing.d.ts +11 -0
  356. package/dist-cjs/types/voice.d.ts +5 -4
  357. package/dist-cjs/utils/deprecation.d.ts +0 -2
  358. package/dist-cjs/utils/deprecation.js +0 -5
  359. package/dist-cjs/utils/periods.d.ts +7 -0
  360. package/dist-cjs/utils/periods.js +35 -0
  361. package/dist-cjs/utils/tokenizer.js +2 -0
  362. package/dist-cjs/version.d.ts +5 -0
  363. package/dist-cjs/version.js +4 -0
  364. package/dist-cjs/voice/manager.js +6 -6
  365. package/llms.txt +61 -0
  366. package/package.json +82 -13
package/API_STABILITY.md CHANGED
@@ -1,12 +1,13 @@
1
1
  # API Stability Policy
2
2
 
3
- This policy describes compatibility guarantees for `nexus-ai-pro`. The 1.x compatibility guarantees
4
- apply beginning with version 1.0.0.
3
+ This policy describes compatibility guarantees for `nexus-ai-pro`. The 2.x guarantees apply beginning
4
+ with version 2.0.0, as the 1.x guarantees applied from 1.0.0. The sections for the 1.x stages below
5
+ still describe each surface; where they say "the 1.x rules", read the rules of the current major line.
5
6
 
6
7
  ## Release stages
7
8
 
8
- The package follows semantic versioning. Within the 1.x line, incompatible changes to stable public
9
- APIs require a major release. Minor releases may add backward-compatible features, and patch releases
9
+ The package follows semantic versioning. Within a major line, incompatible changes to stable public
10
+ APIs require the next major release. Minor releases may add backward-compatible features, and patch releases
10
11
  are intended to remain backward compatible.
11
12
 
12
13
  The following surfaces are public and covered by this policy:
@@ -40,6 +41,72 @@ Both are covered by this policy:
40
41
  Deep imports into `dist`, `dist-cjs`, or `src` are not supported. Import only from `nexus-ai-pro` or
41
42
  one of its explicit subpaths.
42
43
 
44
+ ## 2.1 stage (2.1.0)
45
+
46
+ Everything 2.1 adds is stable from the start and additive: no default changes meaning.
47
+
48
+ - graph durability modes, `flush()`, `maxPendingWrites`, `onError` with `NodeFailure` and
49
+ `RecoveredFailure`, `nodeDefaults`, `NodeTimeout`, `context.heartbeat()`, `SendOptions`,
50
+ `RunControl` and `RunControlLike`, and `GraphDrainedError` (`nexus-ai-pro/graph`);
51
+ - `lintGraph()` and its finding types (`nexus-ai-pro/graph/lint`). New rules may be added in a minor
52
+ release; a rule's code and severity do not change within 2.x;
53
+ - `OperationContext.previousHeartbeat` and `OperationRecord.heartbeatDetails`;
54
+ - `AssistantRunContext.control`;
55
+ - the graph event stream: `events()`, `resumeEvents()`, `continueEvents()`, `GraphEventStream`, its
56
+ event and option types, `GraphStreamOverflowError`, `context.message()` and `context.tool()`, and
57
+ `subgraphEvents`. New projections may be added in a minor release;
58
+ - `TracerOptions.incremental` and `exporters`, `TraceExporter`, `traceparent` in and out, `flush()`,
59
+ `closeAbandonedRuns()`, `w3cTraceId()` and `w3cSpanId()` (`nexus-ai-pro/tracing`);
60
+ - `OtlpTraceExporter` and `runToOtlpSpan()` (`nexus-ai-pro/tracing/otlp`). Attributes may be added as
61
+ the GenAI conventions settle; the ones listed in the tracing guide stay;
62
+ - rollups (`nexus-ai-pro/tracing/rollups`), timed replay (`timing`, `pace`), evaluator provenance
63
+ (`withProvenance()`, `Experiment.evaluators` and `framework`, `LLMJudge.asEvaluator()`),
64
+ `createAgent({ streamTokens })`, and `graphAssistant(graph, { events })`;
65
+ - `rateLimit.algorithm` and `burst`, `RateLimitStore.gcra()`, `RateLimitDecision`, and `gcraDecide()`;
66
+ `health.observationTtlMs`, `ProviderHealthStatus`, a snapshot's `status` and `stale`, and
67
+ `checkProviders({ staleOnly })`.
68
+
69
+ The studio's `rollups` source follows the studio's experimental label.
70
+
71
+ ## 2.0 stage (2.0.0)
72
+
73
+ 2.0 removes what 1.x deprecated and promotes the surfaces that have settled.
74
+
75
+ **Promoted to stable.** These follow the 2.x rules without an experimental label:
76
+
77
+ - graphs, with their advanced APIs: `Send`, `Command`, breakpoints, `updateState()`, `fork()`, node
78
+ caching, and functional workflows (`nexus-ai-pro/graph`, `/graph/functional`, `/graph/visualize`);
79
+ - the store (`nexus-ai-pro/store`, `/store/redis`), agents (`nexus-ai-pro/agent`), and tracing
80
+ (`nexus-ai-pro/tracing`);
81
+ - evaluation (`nexus-ai-pro/evaluate`) and prompts (`nexus-ai-pro/prompts` and `/postgres/prompts`);
82
+ - the agent server (`nexus-ai-pro/server`): its routes, `RunRecord`, `ThreadRecord`, `RunEvent`, and
83
+ recovery.
84
+
85
+ **New in 2.0, and stable from the start:**
86
+
87
+ - the operation lifecycle: the stage order, `LifecycleConfig`, `LifecycleHooks`, the
88
+ `OperationDescriptor`, `OperationOutcome`, and `OperationTicket` shapes, the `BudgetLedger`
89
+ contract, and `ProviderCallContext`. New families and stages may be added in a minor release;
90
+ existing ones keep their names;
91
+ - mixed content: `AssetContent`, `ToolOutput`, and `response.assets`;
92
+ - checkpoint schema version 2. Both checkpointers read version 1 throughout 2.x.
93
+
94
+ **Still experimental in production readiness**, each following the 2.x rules all the same:
95
+
96
+ - images, until recorded live conformance passes on all three backends;
97
+ - the studio package;
98
+ - deployments, tenant limits, and the server's worker queue (1.24);
99
+ - the context hub, insights, and the studio's accounts (1.23);
100
+ - the loaders, the vector stores added in 1.20 and 1.22, the retrievers, and the MCP registry;
101
+ - the SQLite adapters (1.21).
102
+
103
+ **Root import.** The root exports the core client, its config builders, its types, the errors it
104
+ throws, the lifecycle, and `tool()` and `toolOutput()`. Adding anything else to the root waits for a
105
+ major release, and a check in CI fails when the root grows.
106
+
107
+ **Dependencies.** The package has no required dependency. `zod`, `ajv`, `ajv-formats`, and
108
+ `@types/node` are optional peers; making any of them required again would need a major release.
109
+
43
110
  ## Capability negotiation stage
44
111
 
45
112
  `negotiateCompletionRequest()`, `NexusCapabilityError`, `CapabilityPolicy`, `CapabilityWarning`, and
package/CHANGELOG.md CHANGED
@@ -4,6 +4,245 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
4
4
 
5
5
  ## [Unreleased]
6
6
 
7
+ ## [2.1.0] - 2026-10-04
8
+
9
+ Fault-tolerant graphs and crash-safe observability. A graph now chooses when its checkpoints are
10
+ written, recovers from a node whose retries ran out, tells a hung task from a slow one, and stops
11
+ cleanly when its worker has to go. Traces survive the process that wrote them and reach any
12
+ OpenTelemetry backend, every consumer of a run reads one event stream, and dashboards read hourly
13
+ totals instead of every trace. Nothing changes until it is opted into: the defaults keep their 2.0
14
+ meaning.
15
+
16
+ Two pieces planned for 2.3 come early: a rate limiter with no window edge to burst across, and
17
+ provider health that expires.
18
+
19
+ ### Added
20
+
21
+ - **Durability modes.** `compile({ durability })` takes `sync` (the default), `async`, or `exit`.
22
+ `async` writes checkpoints in the background, in order, while the next superstep runs, and waits
23
+ for them before the run returns, pauses, fails, or drains. `maxPendingWrites` (8) bounds the writes
24
+ in flight. `exit` writes only where the run stops. `flush()` waits for every run's writes.
25
+ - **Recovery after retries.** A node's `onError` receives a `NodeFailure` once its retries run out
26
+ and returns an update or a `Command`, such as a route to a refund node. The decision is
27
+ checkpointed, as `recovered` on the next checkpoint, before anything it routes to runs, so a crash
28
+ after it resumes into the same path. `compile({ nodeDefaults })` sets retries, timeouts, and
29
+ `onError` for every node.
30
+ - **Run and idle timeouts.** `timeout: { runMs, idleMs }` caps an attempt and the time between signs
31
+ of progress. `context.heartbeat()`, `emit()`, and `report()` refresh the idle timer.
32
+ `GraphNodeTimeoutError.kind` says which limit fired. A `Send` can override the timeout of the task
33
+ it creates, and the override is checkpointed with the task.
34
+ - **Cooperative drain.** `RunControl`, passed as `control` to a run, stops it after its current
35
+ superstep with its checkpoint written, ending in `GraphDrainedError`; `continue()` resumes it
36
+ anywhere. The agent server drains its graph runs this way when a replica drains with a queue, so
37
+ they are handed off at once instead of after the drain timeout.
38
+ - **`lintGraph()`** on the new `nexus-ai-pro/graph/lint`, and `nexus graph lint`: static cycles,
39
+ retried nodes that are not `idempotent` or have no timeout, deferred durability with side effects,
40
+ an in-process checkpointer under a deployment, unbounded concurrency, and unchecked routes. Nodes
41
+ can declare `idempotent: true`, and `describe()` reports durability, the checkpointer, and each
42
+ node's retries, timeouts, and recovery.
43
+ - **Progress that survives a retry.** An operation's `context.heartbeat(details)` stores `details` as
44
+ `heartbeatDetails`, and the next attempt reads them as `context.previousHeartbeat`.
45
+ - A `task_failed` graph event, and a semantics table in the graph guide that says what each
46
+ execution primitive repeats after a crash.
47
+ - **Crash-safe traces.** `new Tracer({ incremental: true })` writes each run when it starts and when it
48
+ ends, so a crashed run stays in the store with every run beneath it that finished, and a live run
49
+ can be watched. Sampling is decided at the root's start, and an unsampled trace is still kept whole
50
+ when tail sampling wants it. `closeAbandonedRuns()` closes what a dead process left running, as a
51
+ `RunAbandoned` error. `tracer.flush()` waits for writes and exports.
52
+ - **Traces across processes.** `handle.traceparent()` and `StartRunOptions.traceparent` carry a trace
53
+ through a W3C `traceparent` header: an operation's `traceContext`, a remote call, any OpenTelemetry
54
+ service. `w3cTraceId()` and `w3cSpanId()` give the ids every process derives alike.
55
+ - **OpenTelemetry export**, on the new `nexus-ai-pro/tracing/otlp`. `TracerOptions.exporters` takes any
56
+ `TraceExporter`, and `OtlpTraceExporter` sends runs to a collector as OTLP/HTTP JSON with no SDK:
57
+ model calls as `chat <model>` client spans with the GenAI semantic conventions, tools, agents, and
58
+ graph nodes with theirs, and Nexus-only facts under `nexus.*`. `runToOtlpSpan()` is the conversion.
59
+ - **One event stream.** `graph.events()`, `resumeEvents()`, and `continueEvents()` run a graph as
60
+ typed events with projections — `values`, `updates`, `messages`, `tools`, `tasks`, `checkpoints`,
61
+ `custom` — read together or one at a time through `messages()`, `tools()`, `values()`, and
62
+ `updates()`, with `result` for the outcome. Nodes stream model output with `context.message()`
63
+ and report tool calls with `context.tool()`. Subgraph events come through with a `namespace` when
64
+ asked, and `GraphRunOptions.subgraphEvents` does the same for `onEvent`.
65
+ - **Bounded readers.** Every reader of a stream has its own buffer (`maxBuffered`, 1,000), and the run
66
+ waits for the slowest at each superstep. Within a step, `overflow` coalesces model chunks and state
67
+ snapshots (the default), drops the oldest or newest, or fails with `GraphStreamOverflowError`.
68
+ `streamStats()` reports the peak and what was merged or dropped.
69
+ - **Agents stream.** `createAgent()` reports its model's output and every tool call on the stream,
70
+ token by token with `streamTokens` and a client with `stream()`. `traceGraph()` records the tool
71
+ calls as `tool` runs inside their node. `graphAssistant(graph, { events })` records chosen
72
+ projections on each server run.
73
+ - **Rollups**, on the new `nexus-ai-pro/tracing/rollups`: `rollupTraceStore()` adds every finished run
74
+ to hourly rows per kind, model, provider, and tenant, in `MemoryRollupStore` or any `RollupStore`,
75
+ with latency buckets for `rollupPercentile()` and `sumRollups()` to total them. The studio's costs
76
+ view reads them when given `rollups`.
77
+ - **Timed replay.** `recordingFetch({ timing: true })` keeps each chunk of a response and when it came,
78
+ and `replayFetch({ pace })` replays it at once, at the original pace, scaled, or released chunk by
79
+ chunk by a function.
80
+ - **GCRA rate limiting.** `rateLimit.algorithm: 'gcra'` spreads calls at `maxRequests` per `windowMs`
81
+ with at most `burst` at once, so a burst across a window edge can no longer pass twice the limit.
82
+ Both stores decide it through `gcra()`; `RedisRateLimitStore` runs it as one Lua script on Redis's
83
+ clock. `gcraDecide()` is the arithmetic, for a store of your own.
84
+ - **Health that expires.** `health.observationTtlMs` makes a provider with no recent calls `unknown`,
85
+ routed to as one never seen instead of kept down by an old failure or up by an old success.
86
+ Snapshots carry a `status` (`healthy`, `degraded`, `unhealthy`, `unknown`) and `stale`, and
87
+ `ai.checkProviders({ staleOnly: true })` refreshes the unknown ones.
88
+ - **Evaluator provenance.** An experiment records each evaluator's position, name, the score keys it
89
+ produced, and what `withProvenance()` declared — version, judge model, prompt version, temperature,
90
+ and rubric — and the framework version that ran it. `LLMJudge.asEvaluator()` brings the judge to
91
+ `evaluate()`, declaring its own provenance.
92
+ - A weekly `live-providers` workflow runs real conformance against every provider with a key in the
93
+ repository's secrets, DeepSeek included, and opens an issue when one breaks.
94
+
95
+ ### Fixed
96
+
97
+ - **A manual operation heartbeat no longer strands the result.** `context.heartbeat()` wrote the
98
+ record behind the runner's back, so the runner's final write failed its sequence check and a
99
+ successful result was not saved. Heartbeats now go through the runner, one at a time.
100
+ - `continue()` on a finished thread left it marked `running` with an empty result. It now leaves it
101
+ completed and returns its state.
102
+ - A run started under a parent from another tracer, or another process, was never written: its trace
103
+ waited for a root that was not there. It is now written as its trace's root in this process.
104
+
105
+ ### Proof
106
+
107
+ - A crash-injection suite kills a run before, during, and after every checkpoint write and inside
108
+ nodes, before and after their side effects, in `sync` and `async` mode, on the memory, operation
109
+ store, SQLite, Postgres, and Redis checkpointers. A fresh process always reaches the state of an
110
+ uninterrupted run.
111
+ - A saga test: a charge exhausts its retries, `onError` routes to a refund, the process dies during
112
+ the refund, and the resumed run refunds without charging again.
113
+ - A property test generates 40 graphs with branches, loops, `Send`, retries, and interrupts, and
114
+ replays each from every checkpoint of its history to the same state.
115
+ - The graph benchmark runs 50 supersteps against an 8 ms store: `async` finishes in about half the
116
+ time of `sync`, in the same state, and CI fails if it stops beating it by a quarter.
117
+ - A long agent's process dies at its fourteenth step: a second process reads every finished step from
118
+ the same JSONL store, and `closeAbandonedRuns()` closes the rest.
119
+ - A server and a worker each export to a local OTLP collector, and the collector receives one trace,
120
+ the worker's run under the server's, with the GenAI attributes on the model call.
121
+ - A reader a hundred times slower than a node that streams 100,000 chunks never holds more than its
122
+ buffer, under every overflow policy, and coalescing loses no text.
123
+ - The studio's costs view answers over a month of a million runs, held as rollups, in under 200 ms,
124
+ reading the traces once.
125
+ - In the two milliseconds around a window's edge, fixed windows pass 199 calls of a 100-call limit and
126
+ GCRA passes 100. A provider down on Monday and idle since is `unknown`, and routed to, on Wednesday.
127
+
128
+ ## [2.0.0] - 2026-10-02
129
+
130
+ Consolidation. One lifecycle runs every call of every family, the root import holds the core client
131
+ and nothing else, and the package installs with no required dependency. Everything removed here was
132
+ deprecated in 1.x; [MIGRATING.md](./MIGRATING.md) covers each change with before-and-after code, and
133
+ `nexus migrate` rewrites the imports.
134
+
135
+ ### Breaking
136
+
137
+ - **The root import keeps only the core**: the client, its config builders, its types, the errors it
138
+ throws, the lifecycle, and the tool helpers. The 498 other names it re-exported are on their
139
+ subpaths; `nexus migrate` moves 1.x imports there. Importing the root costs 323 KB, down from 572 KB.
140
+ - **`zod`, `ajv`, `ajv-formats`, and `@types/node` are optional peer dependencies.** A zod shape is
141
+ checked through its own `safeParse`; a JSON Schema response format loads ajv on its first check, and
142
+ says what to install when it is missing. A production install is 5.3 MB, the package alone, down
143
+ from 12.3 MB.
144
+ - **A response's `estimatedCost` string is removed**, for the numeric `cost`. A plan's
145
+ `estimatedCost` object stays.
146
+ - **Modalities say which way they flow.** `ModelCapabilities.inputModalities` and `outputModalities`
147
+ are required on every entry, bundled or registered; `modalities`, the `Modality` type, and the
148
+ `modalities` routing requirement are removed.
149
+ - **Checkpoint schema version 2.** A checkpoint has its `version`, an `id`, its `tasks` always, and its
150
+ questions only in `interrupts`; `interrupt` is gone. Both checkpointers read version 1 for the whole
151
+ 2.x line, so threads 1.x left waiting resume. A checkpointer's `get()` and `history()` return a
152
+ `StoredGraphCheckpoint` of either version.
153
+ - **Options that were never read are removed**: `GoogleProviderConfig.projectId`,
154
+ `OllamaProviderConfig.timeout`, `MetricsConfig.prometheus`, `DensificationConfig.preserveMarkdown`,
155
+ `HealthConfig.latencyHalfLife`, `InjectionDetectionConfig.sensitivity`, and
156
+ `ToolPolicyConfig.requiresApproval`.
157
+ - **`ImageManagerConfig` is removed**, for `ImageConfig`.
158
+ - **`PipelineStepName` is a closed list.** A custom step is recorded as `customStep`, with its own name
159
+ in `PipelineTraceStep.custom`. The `auditLog` step is replaced by the lifecycle's `audit`.
160
+ - **`ai.stream()` opens on its first read**, so authorization, rate-limit, guardrail, and budget errors
161
+ come out of the loop rather than from the call.
162
+ - **What the lifecycle records changed**: metrics carry `family` and `operation` for every family, the
163
+ image family is labelled `image`, audit events carry `family` and `operation` and add an `error`
164
+ event, and `response.meta.requestId` is the operation's id.
165
+ - **The model registry is current as of 2026-10-02.** Models their providers shut down are removed:
166
+ Claude 3.x and 4.0 to 4.1, `gpt-4.5-preview`, `o1-mini`, `gpt-5-codex`, Gemini 1.5 and 2.0 and the
167
+ shut-down 3.x previews, Groq Compound, Llama 4 Scout, and Qwen3 32B, Mistral's 2024 models, Devstral,
168
+ and Magistral, and DeepSeek's `deepseek-chat`, `deepseek-reasoner`, V3, and R1. Four names no
169
+ provider served are gone too: `claude-sonnet-5-0`, `claude-haiku-5-0`, `claude-fable-5-0`, and
170
+ `gemini-3.5-pro`. Cohere's `command-r` and `command-r-plus` are filed under their dated names, and
171
+ `mistral-medium-3-5` under `mistral-medium-2604`. Every intent alias points at a current model.
172
+
173
+ ### Added
174
+
175
+ - **One lifecycle for every operation.** Completions, streams, embeddings, voice, telephony, images,
176
+ realtime sessions, graphs, agents, queued jobs, and provider batches pass through the same stages:
177
+ validate, authorize, input policy, resolve assets, route, reserve budget, execute, output policy,
178
+ persist, reconcile cost, and audit. `lifecycle` on the client configures what they share: an
179
+ `authorize` callback that can refuse any call, a `budget` every family draws on, and `hooks` that see
180
+ each call start and finish, cache hits included. `ai.lifecycle` makes graphs, agents, workflows,
181
+ realtime sessions, job queues, and batches operations of the client too.
182
+ - **A shared spend budget**: `budgetLedger()` on the new `nexus-ai-pro/lifecycle` holds each call's
183
+ estimate before it runs and charges what it cost after, per tenant and per period, so concurrent calls
184
+ cannot overshoot together. It keeps totals in memory or in any tenant usage store, Redis included.
185
+ - **`ProviderCallContext`**, handed to every provider call of every family: the request id, the abort
186
+ signal, the deadline, trace headers, and the idempotency key. The OpenAI and Anthropic adapters send
187
+ the key and the headers on. Requests take `requestId`, `tenantId`, and `idempotencyKey`.
188
+ - **Mixed text-and-asset content.** `toolOutput()` lets a tool return text, images, and asset
189
+ references, sent as the tool message itself instead of base64 JSON. An `asset` content part names an
190
+ asset by reference, an image part can carry an asset, and a model that produces images returns them
191
+ on `response.assets`.
192
+ - **Typed pipelines**: `PipelineContext` and the runner are generic over the request and response, with
193
+ `PipelineShapes` for another family's types.
194
+ - **New models**: OpenAI GPT-6 Astra, GPT-6.1 Sol, GPT-6 Sol, GPT-6 Luna, GPT-5 Pro, o3-pro, and
195
+ GPT-5.3 Codex; Claude Fable 5.1, Opus 5.5, Sonnet 5.5, Fable 5, Opus 5, Sonnet 5, and Sonnet 4.5;
196
+ Gemini 3.8, 3.7, and 3.6 Flash, 3.5 Flash-Lite, 3.1 Flash-Lite, 3 Pro Image, and 3.1 Flash Image;
197
+ Groq's Qwen3.8 27B and MiniMax M2.7; Mistral Medium 3.5 and Ministral 3 14B, 8B, and 3B; DeepSeek
198
+ Flash and V4 Pro; and Cohere Command A Plus, North Mini Code, North Small Translate, and three Tiny
199
+ Aya models.
200
+ - `ModelCapabilities.sampling`, false for a model that accepts only its default temperature and top-p.
201
+ Negotiation drops a non-default value for it.
202
+ - `nexus migrate` lists each model name the 2.0 registry dropped, with what to use instead.
203
+ - Anthropic responses report thinking tokens in `usage.reasoningTokens`.
204
+ - **`llms.txt` and `llms-full.txt`** for AI assistants and coding agents: an index of every guide with
205
+ the facts an assistant needs to recommend the package correctly, and the guides in one file.
206
+ `llms.txt` ships in the package. Both are generated from the README and the guides, and CI fails
207
+ when they fall behind.
208
+ - `toCheckpoint()` and `CheckpointDraft` for building a version 2 checkpoint by hand.
209
+ - A `cache_hits` metric, and `routingDecision.provider` and `.model` on a response.
210
+
211
+ ### Changed
212
+
213
+ - Provider adapters, and the agent, verification, evaluation, workflow, semantic-cache, image, and
214
+ embedding engines, load on first use, so importing the client never loads them.
215
+ - A context-window summary is an operation of its own, authorized, budgeted, and audited.
216
+ - `getCall()`, `listPhoneNumbers()`, and `updatePhoneNumber()` run through the lifecycle, so they are
217
+ rate-limited and audited like `createCall()`.
218
+ - `nexus migrate` lists the options and model entries 2.0 removed, and keeps a single moved name on
219
+ one line.
220
+ - **Prices and limits follow the providers.** GPT-5.6, GPT-5.2 Pro, Mistral Large 3, and Mistral
221
+ Small 4 cost less. Gemini 3.5 Flash costs $1.50 and $9 per million tokens, not $0.10 and $0.40.
222
+ Claude Opus 4.5 has a 200K context and 64K output, not 1M and 128K, and Codestral a 128K context.
223
+ Models with an announced shutdown are `deprecated`, with the date and the replacement in their
224
+ notes, and an alias that resolves to one is deprecated too.
225
+ - `toolChoice: false` now means a call cannot be forced: negotiation drops `required` or a named tool
226
+ and lets `auto` and `none` through.
227
+
228
+ ### Fixed
229
+
230
+ - **Claude 4.6 onward get adaptive thinking.** The Anthropic adapter sent every model a thinking
231
+ budget, which Claude rejects after 4.6, so a request with `reasoning` failed on current models. It
232
+ now sends adaptive thinking and `output_config.effort` from 4.6 on, and turns thinking off the way
233
+ each model allows. It drops sampling values that Claude 4.7 and later reject, and leaves room for
234
+ thinking when no output limit is set.
235
+ - **Tool calls reach providers whole.** The OpenAI chat and Responses, Anthropic, and Google adapters
236
+ dropped a conversation's tool calls and the ids that link results to them, so a real tool loop could
237
+ fail on its second turn. Each now sends both the way its API expects, images in results included.
238
+ - **Responses are priced on the model they were routed to.** A provider that echoed a dated snapshot
239
+ name priced the call at nothing; Groq, Mistral, and Cohere models filed under a prefix did too.
240
+ - `resolveModel('google/gemini-2.5-flash')` found no capabilities for a provider-prefixed name. It now
241
+ finds the entry filed without the prefix, when that entry belongs to the same provider.
242
+ - Streams honour the circuit breaker, the cost budget, audit, and metrics, as completions always did.
243
+ - A cache hit is audited and counted.
244
+ - The upload scanner's types no longer need Node's: `content` takes text or any `Uint8Array`.
245
+
7
246
  ## [1.25.0] - 2026-10-01
8
247
 
9
248
  The bridge to 2.0. Everything 2.0 removes is deprecated now, every capability has a subpath of its
@@ -1255,7 +1494,9 @@ shared policy vocabulary is in place for a future release that revisits this.
1255
1494
  - URL fetching rejects unsafe private-network targets and limits response reads.
1256
1495
  - CLI and audit findings no longer disclose detected secret values.
1257
1496
 
1258
- [Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.25.0...HEAD
1497
+ [Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.1.0...HEAD
1498
+ [2.1.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.0.0...v2.1.0
1499
+ [2.0.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.25.0...v2.0.0
1259
1500
  [1.25.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.24.0...v1.25.0
1260
1501
  [1.24.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.23.0...v1.24.0
1261
1502
  [1.23.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.22.0...v1.23.0