@sema-agent/core 7.58.0 → 7.60.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 (519) hide show
  1. package/CHANGELOG.md +1340 -0
  2. package/README.md +6 -4
  3. package/dist/agents/agent-definition.d.ts +7 -0
  4. package/dist/agents/agent-definition.js +12 -0
  5. package/dist/agents/agent-transcript-tool.d.ts +2 -1
  6. package/dist/agents/agent-transcript-tool.js +3 -1
  7. package/dist/agents/cc-peer-directory.js +8 -8
  8. package/dist/agents/child-model-seat.d.ts +4 -2
  9. package/dist/agents/child-model-seat.js +9 -4
  10. package/dist/agents/cumulative-stats.js +0 -1
  11. package/dist/agents/inherited-tool-pool.d.ts +26 -1
  12. package/dist/agents/inherited-tool-pool.js +22 -0
  13. package/dist/agents/peer-directory.d.ts +9 -0
  14. package/dist/agents/peer-directory.js +6 -2
  15. package/dist/agents/retain-ledger.d.ts +11 -1
  16. package/dist/agents/retain-ledger.js +13 -2
  17. package/dist/agents/roster-store.d.ts +1 -1
  18. package/dist/agents/roster-store.js +3 -1
  19. package/dist/agents/send-message-tool.d.ts +8 -19
  20. package/dist/agents/send-message-tool.js +32 -50
  21. package/dist/agents/subagent.d.ts +51 -17
  22. package/dist/agents/subagent.js +150 -112
  23. package/dist/agents/tool-filter.d.ts +1 -3
  24. package/dist/agents/tool-filter.js +4 -12
  25. package/dist/bench/metrics.d.ts +3 -5
  26. package/dist/bench/metrics.js +0 -1
  27. package/dist/brain/anthropic.js +161 -45
  28. package/dist/brain/degrading.js +3 -1
  29. package/dist/brain/errors.d.ts +9 -3
  30. package/dist/brain/errors.js +7 -1
  31. package/dist/brain/failover.js +2 -1
  32. package/dist/brain/open-responses.js +3 -3
  33. package/dist/brain/openai.js +103 -53
  34. package/dist/brain/provider-dialect.d.ts +11 -0
  35. package/dist/brain/provider-dialect.js +5 -2
  36. package/dist/brain/reasoning-request.js +5 -4
  37. package/dist/brain/reasoning.d.ts +19 -0
  38. package/dist/brain/reasoning.js +17 -2
  39. package/dist/brain/request-route.d.ts +4 -1
  40. package/dist/brain/request-route.js +4 -1
  41. package/dist/brain/route-adjudicator.d.ts +84 -18
  42. package/dist/brain/route-adjudicator.js +90 -22
  43. package/dist/brain/route-conformance.js +1 -1
  44. package/dist/brain/status-sink.d.ts +7 -1
  45. package/dist/brain/status-sink.js +6 -0
  46. package/dist/brain/stream-engine.js +84 -49
  47. package/dist/brain/stream-shared.d.ts +30 -0
  48. package/dist/brain/stream-shared.js +34 -1
  49. package/dist/brain/timeout.d.ts +65 -6
  50. package/dist/brain/timeout.js +111 -11
  51. package/dist/core/a2a.d.ts +15 -5
  52. package/dist/core/a2a.js +34 -19
  53. package/dist/core/account-row.d.ts +61 -0
  54. package/dist/core/account-row.js +51 -0
  55. package/dist/core/advisor-verdict.d.ts +2 -1
  56. package/dist/core/advisor-verdict.js +1 -1
  57. package/dist/core/agent-definition.d.ts +20 -0
  58. package/dist/core/allow-entry.d.ts +20 -6
  59. package/dist/core/allow-entry.js +17 -7
  60. package/dist/core/approval-object.d.ts +29 -15
  61. package/dist/core/approval-object.js +47 -19
  62. package/dist/core/artifact-host.d.ts +0 -2
  63. package/dist/core/artifact-host.js +0 -1
  64. package/dist/core/auto-compaction.js +1 -1
  65. package/dist/core/auto-mode-defaults.d.ts +8 -0
  66. package/dist/core/auto-mode-defaults.js +1 -0
  67. package/dist/core/auto-mode-rebuild.d.ts +2 -1
  68. package/dist/core/auto-mode.d.ts +39 -4
  69. package/dist/core/auto-mode.js +63 -12
  70. package/dist/core/background-agent-store.d.ts +26 -4
  71. package/dist/core/background-agent-store.js +3 -2
  72. package/dist/core/background-shell.d.ts +12 -1
  73. package/dist/core/background-shell.js +12 -0
  74. package/dist/core/checkpoint-requirements.d.ts +13 -1
  75. package/dist/core/checkpoint-requirements.js +3 -1
  76. package/dist/core/checkpoint-store.d.ts +66 -25
  77. package/dist/core/checkpoint-store.js +22 -9
  78. package/dist/core/child-clamp-seats.d.ts +29 -0
  79. package/dist/core/child-clamp-seats.js +56 -1
  80. package/dist/core/compliance.d.ts +3 -3
  81. package/dist/core/compliance.js +1 -1
  82. package/dist/core/credential-echo.d.ts +52 -0
  83. package/dist/core/credential-echo.js +65 -0
  84. package/dist/core/credential-vocabulary.d.ts +13 -3
  85. package/dist/core/credential-vocabulary.js +12 -4
  86. package/dist/core/cross-boundary-taint.d.ts +4 -5
  87. package/dist/core/effective-path-target.d.ts +8 -2
  88. package/dist/core/effective-path-target.js +8 -3
  89. package/dist/core/engine-notice.d.ts +156 -23
  90. package/dist/core/engine-notice.js +19 -5
  91. package/dist/core/frame-settlement.d.ts +5 -0
  92. package/dist/core/frame-settlement.js +4 -0
  93. package/dist/core/gate-fold.js +8 -6
  94. package/dist/core/gate-lanes.js +47 -12
  95. package/dist/core/gate-outcome.d.ts +32 -3
  96. package/dist/core/gate-outcome.js +19 -1
  97. package/dist/core/governance-codes.d.ts +17 -1
  98. package/dist/core/governance-codes.js +25 -0
  99. package/dist/core/hands-band-screen.js +0 -1
  100. package/dist/core/hands-band.d.ts +0 -3
  101. package/dist/core/hooks.d.ts +70 -59
  102. package/dist/core/hooks.js +125 -80
  103. package/dist/core/image-admission.d.ts +106 -52
  104. package/dist/core/image-admission.js +184 -56
  105. package/dist/core/image-downsample.d.ts +36 -69
  106. package/dist/core/image-downsample.js +111 -73
  107. package/dist/core/integer-option.d.ts +21 -0
  108. package/dist/core/integer-option.js +13 -0
  109. package/dist/core/locked-config.d.ts +59 -5
  110. package/dist/core/locked-config.js +82 -50
  111. package/dist/core/mailbox-store.d.ts +45 -1
  112. package/dist/core/mailbox-store.js +53 -9
  113. package/dist/core/mcp-call-meta.d.ts +2 -2
  114. package/dist/core/mcp-call-meta.js +9 -10
  115. package/dist/core/mcp-failure.d.ts +122 -20
  116. package/dist/core/mcp-failure.js +73 -5
  117. package/dist/core/mcp-host-seat.d.ts +92 -0
  118. package/dist/core/mcp-host-seat.js +131 -0
  119. package/dist/core/mcp-probe.d.ts +7 -2
  120. package/dist/core/mcp-probe.js +7 -2
  121. package/dist/core/mcp-server-link.d.ts +22 -1
  122. package/dist/core/mcp-server-link.js +25 -1
  123. package/dist/core/mcp-server-spec.d.ts +38 -9
  124. package/dist/core/mcp-server-spec.js +55 -21
  125. package/dist/core/mcp.d.ts +27 -12
  126. package/dist/core/mcp.js +105 -76
  127. package/dist/core/memory-admission.d.ts +23 -6
  128. package/dist/core/memory-admission.js +19 -9
  129. package/dist/core/memory-engine/consolidation-driver.d.ts +2 -4
  130. package/dist/core/memory-engine/consolidation-driver.js +3 -3
  131. package/dist/core/memory-engine/consolidation.d.ts +4 -0
  132. package/dist/core/memory-engine/consolidation.js +1 -0
  133. package/dist/core/memory-engine/content-origin.d.ts +13 -0
  134. package/dist/core/memory-engine/content-origin.js +21 -3
  135. package/dist/core/memory-engine/delegation-settlement.js +5 -12
  136. package/dist/core/memory-engine/distiller.js +2 -2
  137. package/dist/core/memory-engine/dual-root.d.ts +50 -1
  138. package/dist/core/memory-engine/dual-root.js +44 -1
  139. package/dist/core/memory-engine/engine.d.ts +67 -14
  140. package/dist/core/memory-engine/engine.js +384 -212
  141. package/dist/core/memory-engine/export-bundle.d.ts +23 -0
  142. package/dist/core/memory-engine/export-bundle.js +23 -4
  143. package/dist/core/memory-engine/file-backend.d.ts +128 -55
  144. package/dist/core/memory-engine/file-backend.js +290 -117
  145. package/dist/core/memory-engine/index.d.ts +3 -2
  146. package/dist/core/memory-engine/index.js +2 -1
  147. package/dist/core/memory-engine/layout.d.ts +59 -11
  148. package/dist/core/memory-engine/layout.js +190 -40
  149. package/dist/core/memory-engine/memory-backend-contract.d.ts +1 -1
  150. package/dist/core/memory-engine/memory-backend-contract.js +39 -2
  151. package/dist/core/memory-engine/scope-contract.d.ts +13 -3
  152. package/dist/core/memory-engine/scope-contract.js +2 -2
  153. package/dist/core/memory-engine/sync-client.d.ts +51 -9
  154. package/dist/core/memory-engine/sync-client.js +107 -13
  155. package/dist/core/memory-engine/sync-report.d.ts +103 -0
  156. package/dist/core/memory-engine/sync-report.js +119 -0
  157. package/dist/core/memory-engine/sync.d.ts +8 -1
  158. package/dist/core/memory-engine/types.d.ts +6 -0
  159. package/dist/core/mode-policy.d.ts +9 -1
  160. package/dist/core/mode-policy.js +11 -1
  161. package/dist/core/model-receipt.d.ts +39 -0
  162. package/dist/core/model-receipt.js +139 -0
  163. package/dist/core/mods/agent-stations.d.ts +65 -0
  164. package/dist/core/mods/agent-stations.js +105 -0
  165. package/dist/core/mods/classic-events.d.ts +5 -1
  166. package/dist/core/mods/kernel/dispatch.d.ts +5 -1
  167. package/dist/core/mods/kernel/dispatch.js +6 -5
  168. package/dist/core/mods/kernel/events.d.ts +11 -4
  169. package/dist/core/mods/kernel/events.js +11 -7
  170. package/dist/core/mods/kernel/receive.d.ts +5 -0
  171. package/dist/core/mods/kernel/receive.js +10 -0
  172. package/dist/core/mods/kernel/registration.d.ts +4 -0
  173. package/dist/core/mods/kernel/registration.js +3 -0
  174. package/dist/core/mods/lifecycle-stations.d.ts +41 -0
  175. package/dist/core/mods/lifecycle-stations.js +35 -0
  176. package/dist/core/mods/stations.d.ts +73 -60
  177. package/dist/core/mods/stations.js +64 -40
  178. package/dist/core/mods/tool-call.d.ts +10 -4
  179. package/dist/core/mods/tool-call.js +28 -12
  180. package/dist/core/mounted-mcp.d.ts +5 -0
  181. package/dist/core/mounted-mcp.js +2 -2
  182. package/dist/core/namespaced-rule-name.d.ts +7 -1
  183. package/dist/core/namespaced-rule-name.js +13 -2
  184. package/dist/core/oracle-isolation.js +1 -1
  185. package/dist/core/own-property-receipt.d.ts +3 -0
  186. package/dist/core/own-property-receipt.js +3 -0
  187. package/dist/core/parent-spec-seat.d.ts +8 -3
  188. package/dist/core/parent-spec-seat.js +2 -0
  189. package/dist/core/park-selfcheck.js +14 -8
  190. package/dist/core/peer-seat.d.ts +133 -16
  191. package/dist/core/peer-seat.js +319 -42
  192. package/dist/core/permission-rule-consent.d.ts +0 -21
  193. package/dist/core/permission-rule-consent.js +11 -6
  194. package/dist/core/permission-rule-model.d.ts +20 -2
  195. package/dist/core/permission-rule-model.js +8 -7
  196. package/dist/core/present-plan-tool.d.ts +11 -3
  197. package/dist/core/present-plan-tool.js +2 -2
  198. package/dist/core/protocol-http-auth.d.ts +14 -2
  199. package/dist/core/protocol-http-auth.js +16 -7
  200. package/dist/core/read-face-seats.d.ts +7 -5
  201. package/dist/core/read-face-seats.js +4 -1
  202. package/dist/core/redaction-marks.d.ts +4 -3
  203. package/dist/core/redaction-marks.js +2 -2
  204. package/dist/core/remote-env.d.ts +146 -98
  205. package/dist/core/remote-env.js +113 -14
  206. package/dist/core/resume-startup-cause.js +1 -0
  207. package/dist/core/retention.js +37 -12
  208. package/dist/core/retired-keys.d.ts +6 -1
  209. package/dist/core/retired-keys.js +4 -1
  210. package/dist/core/rewrite-rejudge.d.ts +13 -5
  211. package/dist/core/rewrite-rejudge.js +9 -5
  212. package/dist/core/roles.d.ts +69 -3
  213. package/dist/core/roles.js +167 -80
  214. package/dist/core/rule-owner.d.ts +3 -0
  215. package/dist/core/runner/announce-once-ledger.d.ts +5 -4
  216. package/dist/core/runner/announce-once-ledger.js +4 -2
  217. package/dist/core/runner/assemble-result.d.ts +0 -5
  218. package/dist/core/runner/assemble-result.js +0 -1
  219. package/dist/core/runner/call-hook-stations.d.ts +17 -10
  220. package/dist/core/runner/call-hook-stations.js +23 -12
  221. package/dist/core/runner/child-tree.d.ts +7 -8
  222. package/dist/core/runner/child-tree.js +6 -6
  223. package/dist/core/runner/classifier-ladder.d.ts +10 -2
  224. package/dist/core/runner/classifier-ladder.js +39 -8
  225. package/dist/core/runner/construction-doors.js +5 -0
  226. package/dist/core/runner/contracts.d.ts +82 -57
  227. package/dist/core/runner/credential-origin-seat.js +4 -3
  228. package/dist/core/runner/cross-boundary-lane.d.ts +3 -5
  229. package/dist/core/runner/cross-boundary-lane.js +11 -2
  230. package/dist/core/runner/cwd-alignment-probe.d.ts +20 -0
  231. package/dist/core/runner/cwd-alignment-probe.js +21 -0
  232. package/dist/core/runner/decide-continuation.d.ts +2 -2
  233. package/dist/core/runner/env-capability-census.d.ts +15 -20
  234. package/dist/core/runner/env-capability-census.js +25 -34
  235. package/dist/core/runner/file-history-request.d.ts +2 -2
  236. package/dist/core/runner/file-history-request.js +0 -8
  237. package/dist/core/runner/gate-exit.d.ts +87 -11
  238. package/dist/core/runner/gate-exit.js +30 -8
  239. package/dist/core/runner/git-status-frame.d.ts +5 -2
  240. package/dist/core/runner/git-status-frame.js +3 -4
  241. package/dist/core/runner/image-removed-seat.d.ts +12 -0
  242. package/dist/core/runner/image-removed-seat.js +19 -0
  243. package/dist/core/runner/image.d.ts +7 -2
  244. package/dist/core/runner/image.js +14 -8
  245. package/dist/core/runner/inline-image.d.ts +10 -8
  246. package/dist/core/runner/inline-image.js +11 -9
  247. package/dist/core/runner/memory-consolidation-driver.js +5 -5
  248. package/dist/core/runner/park-commit.d.ts +1 -1
  249. package/dist/core/runner/park-commit.js +3 -0
  250. package/dist/core/runner/permission-rule-lanes.js +1 -1
  251. package/dist/core/runner/prepare-ask-lane.d.ts +1 -1
  252. package/dist/core/runner/prepare-ask-lane.js +2 -1
  253. package/dist/core/runner/prepare-boundary-parks.d.ts +2 -2
  254. package/dist/core/runner/prepare-boundary-parks.js +5 -5
  255. package/dist/core/runner/prepare-caps-and-workflow.d.ts +7 -5
  256. package/dist/core/runner/prepare-caps-and-workflow.js +6 -3
  257. package/dist/core/runner/prepare-config-doors.d.ts +6 -1
  258. package/dist/core/runner/prepare-config-doors.js +16 -9
  259. package/dist/core/runner/prepare-context-lane.js +2 -0
  260. package/dist/core/runner/prepare-delegation-surface.d.ts +9 -3
  261. package/dist/core/runner/prepare-delegation-surface.js +5 -4
  262. package/dist/core/runner/prepare-file-history.d.ts +10 -12
  263. package/dist/core/runner/prepare-file-history.js +3 -12
  264. package/dist/core/runner/prepare-gate-stations.d.ts +4 -3
  265. package/dist/core/runner/prepare-gate-stations.js +4 -3
  266. package/dist/core/runner/prepare-hands-readface.d.ts +7 -1
  267. package/dist/core/runner/prepare-hands-readface.js +19 -6
  268. package/dist/core/runner/prepare-inherited-gate.d.ts +6 -7
  269. package/dist/core/runner/prepare-inherited-gate.js +22 -31
  270. package/dist/core/runner/prepare-memory-engine-session.js +1 -1
  271. package/dist/core/runner/prepare-memory.d.ts +2 -2
  272. package/dist/core/runner/prepare-memory.js +12 -19
  273. package/dist/core/runner/prepare-park-ask.d.ts +4 -6
  274. package/dist/core/runner/prepare-park-ask.js +5 -9
  275. package/dist/core/runner/prepare-policy-chain.d.ts +8 -7
  276. package/dist/core/runner/prepare-policy-chain.js +136 -121
  277. package/dist/core/runner/prepare-project-context.d.ts +2 -2
  278. package/dist/core/runner/prepare-project-context.js +10 -7
  279. package/dist/core/runner/prepare-prompt-inputs.d.ts +5 -2
  280. package/dist/core/runner/prepare-prompt-inputs.js +10 -20
  281. package/dist/core/runner/prepare-protocol-tools.d.ts +5 -3
  282. package/dist/core/runner/prepare-protocol-tools.js +17 -2
  283. package/dist/core/runner/prepare-run-refs.d.ts +2 -3
  284. package/dist/core/runner/prepare-run-refs.js +4 -1
  285. package/dist/core/runner/prepare-suspend-saga.d.ts +0 -2
  286. package/dist/core/runner/prepare-suspend-saga.js +5 -7
  287. package/dist/core/runner/prepare-task.js +44 -28
  288. package/dist/core/runner/prepare-turn-wiring.d.ts +2 -0
  289. package/dist/core/runner/prepare-turn-wiring.js +7 -2
  290. package/dist/core/runner/prepare-wiring-manifest.d.ts +5 -4
  291. package/dist/core/runner/prepare-wiring-manifest.js +34 -19
  292. package/dist/core/runner/prepare-workspace-restore.js +3 -3
  293. package/dist/core/runner/reply-pricing.d.ts +30 -0
  294. package/dist/core/runner/reply-pricing.js +19 -0
  295. package/dist/core/runner/resume-admission.js +4 -2
  296. package/dist/core/runner/resume-apply.js +6 -1
  297. package/dist/core/runner/resume-checkpoint-screen.js +4 -4
  298. package/dist/core/runner/resume-policy-outcome.js +5 -5
  299. package/dist/core/runner/retired-runner-deps.js +4 -1
  300. package/dist/core/runner/role-seat-defaulted.d.ts +44 -0
  301. package/dist/core/runner/role-seat-defaulted.js +40 -0
  302. package/dist/core/runner/run-attachment-seats.js +3 -3
  303. package/dist/core/runner/run-brain-sinks.js +3 -0
  304. package/dist/core/runner/run-git-lane.d.ts +3 -1
  305. package/dist/core/runner/run-git-lane.js +1 -1
  306. package/dist/core/runner/run-harness-handlers.d.ts +3 -1
  307. package/dist/core/runner/run-harness-handlers.js +3 -1
  308. package/dist/core/runner/run-identity-wiring.d.ts +2 -5
  309. package/dist/core/runner/run-identity-wiring.js +6 -5
  310. package/dist/core/runner/run-leg.d.ts +2 -0
  311. package/dist/core/runner/run-leg.js +63 -56
  312. package/dist/core/runner/run-notification-lane.d.ts +3 -1
  313. package/dist/core/runner/run-notification-lane.js +16 -10
  314. package/dist/core/runner/run-settle-and-teardown.js +5 -1
  315. package/dist/core/runner/run-stop-and-final-verify.d.ts +4 -0
  316. package/dist/core/runner/run-stop-and-final-verify.js +14 -6
  317. package/dist/core/runner/run-terminal-adoption.d.ts +2 -5
  318. package/dist/core/runner/run-terminal-adoption.js +9 -3
  319. package/dist/core/runner/run-turn-boundary.js +89 -77
  320. package/dist/core/runner/runtask.d.ts +8 -5
  321. package/dist/core/runner/runtask.js +21 -13
  322. package/dist/core/runner/side-call-account.d.ts +1 -1
  323. package/dist/core/runner/side-call-account.js +3 -18
  324. package/dist/core/runner/skills-seat.js +2 -2
  325. package/dist/core/runner/sub-agent-deny-lists.d.ts +24 -0
  326. package/dist/core/runner/sub-agent-deny-lists.js +20 -7
  327. package/dist/core/runner/synthetic-tools.js +2 -2
  328. package/dist/core/runner/tool-disclosure.js +0 -2
  329. package/dist/core/runner/tool-end-body.js +2 -2
  330. package/dist/core/runner/tool-face-overlay.d.ts +1 -1
  331. package/dist/core/runner/tool-face-overlay.js +26 -19
  332. package/dist/core/runner/tool-occurrence.d.ts +1 -1
  333. package/dist/core/runner/tool-occurrence.js +2 -2
  334. package/dist/core/runner/tool-result-media-seat.d.ts +9 -1
  335. package/dist/core/runner/tool-result-media-seat.js +17 -1
  336. package/dist/core/runner/turn-attachments.d.ts +29 -27
  337. package/dist/core/runner/turn-attachments.js +27 -42
  338. package/dist/core/runner-deps.d.ts +32 -19
  339. package/dist/core/secret-env.d.ts +35 -4
  340. package/dist/core/secret-env.js +65 -3
  341. package/dist/core/sensitive-path-policy.js +3 -3
  342. package/dist/core/session-policy-store.d.ts +12 -3
  343. package/dist/core/session-policy-store.js +29 -10
  344. package/dist/core/session-store.d.ts +5 -7
  345. package/dist/core/session-store.js +50 -11
  346. package/dist/core/side-query.d.ts +11 -1
  347. package/dist/core/side-query.js +9 -0
  348. package/dist/core/skill-grant-binding.d.ts +31 -2
  349. package/dist/core/skill-grant-binding.js +31 -1
  350. package/dist/core/skill-grant.d.ts +17 -5
  351. package/dist/core/skill-grant.js +24 -6
  352. package/dist/core/store-contracts/background-agent-store-contract.js +27 -0
  353. package/dist/core/store-contracts/checkpoint-store-contract.js +3 -2
  354. package/dist/core/store-contracts/mailbox-store-contract.js +31 -1
  355. package/dist/core/store-contracts/tool-result-store-contract.d.ts +1 -1
  356. package/dist/core/store-contracts/tool-result-store-contract.js +37 -0
  357. package/dist/core/stub-env.d.ts +5 -5
  358. package/dist/core/stub-env.js +11 -1
  359. package/dist/core/swappable-deps.d.ts +17 -43
  360. package/dist/core/swappable-deps.js +15 -5
  361. package/dist/core/synthetic-read-verdict.d.ts +1 -1
  362. package/dist/core/synthetic-read-verdict.js +2 -1
  363. package/dist/core/task-event.d.ts +50 -10
  364. package/dist/core/task-notification.d.ts +88 -5
  365. package/dist/core/task-notification.js +146 -17
  366. package/dist/core/task-registry-agent.d.ts +18 -12
  367. package/dist/core/task-registry-agent.js +19 -6
  368. package/dist/core/task-registry-monitor.d.ts +7 -0
  369. package/dist/core/task-registry-monitor.js +28 -1
  370. package/dist/core/task-registry-shared.d.ts +43 -3
  371. package/dist/core/task-registry-shared.js +21 -7
  372. package/dist/core/task-registry-workflow.js +1 -1
  373. package/dist/core/task-registry.d.ts +50 -35
  374. package/dist/core/task-registry.js +64 -23
  375. package/dist/core/task-result.d.ts +3 -12
  376. package/dist/core/task-spec.d.ts +15 -7
  377. package/dist/core/task-stream.d.ts +1 -1
  378. package/dist/core/terminal-cause.d.ts +10 -0
  379. package/dist/core/tool-catalog-entries.js +1 -1
  380. package/dist/core/tool-check-reading.d.ts +1 -0
  381. package/dist/core/tool-check-reading.js +3 -3
  382. package/dist/core/tool-face-reader.d.ts +7 -6
  383. package/dist/core/tool-face-reader.js +4 -3
  384. package/dist/core/tool-name-aliases.d.ts +19 -0
  385. package/dist/core/tool-name-aliases.js +54 -2
  386. package/dist/core/tool-policy.d.ts +21 -4
  387. package/dist/core/tool-policy.js +1 -1
  388. package/dist/core/tool-registry.d.ts +5 -5
  389. package/dist/core/tool-registry.js +2 -2
  390. package/dist/core/tool-result-store.d.ts +88 -5
  391. package/dist/core/tool-result-store.js +51 -12
  392. package/dist/core/tool-roster.d.ts +112 -5
  393. package/dist/core/tool-roster.js +42 -1
  394. package/dist/core/tool-spec.d.ts +23 -5
  395. package/dist/core/trace.d.ts +0 -1
  396. package/dist/core/types.d.ts +5 -5
  397. package/dist/core/types.js +2 -2
  398. package/dist/core/untrusted-text.js +1 -1
  399. package/dist/core/user-attachment.d.ts +10 -5
  400. package/dist/core/user-attachment.js +15 -7
  401. package/dist/core/wiring-manifest.d.ts +6 -3
  402. package/dist/engine/compaction/compaction.js +29 -3
  403. package/dist/engine/execution-env/node-execution-env.d.ts +11 -5
  404. package/dist/engine/execution-env/node-execution-env.js +21 -13
  405. package/dist/engine/harness/agent-harness.d.ts +26 -3
  406. package/dist/engine/harness/agent-harness.js +49 -16
  407. package/dist/engine/harness/messages.d.ts +3 -1
  408. package/dist/engine/harness/messages.js +3 -2
  409. package/dist/engine/harness/types.d.ts +119 -28
  410. package/dist/engine/llm/rejected-images.d.ts +46 -0
  411. package/dist/engine/llm/rejected-images.js +54 -0
  412. package/dist/engine/llm/tool-turns.d.ts +2 -1
  413. package/dist/engine/llm/types.d.ts +18 -7
  414. package/dist/engine/loop/agent-loop.d.ts +20 -12
  415. package/dist/engine/loop/agent-loop.js +205 -36
  416. package/dist/engine/loop/types.d.ts +12 -3
  417. package/dist/engine/lsp/node-lsp-manager.d.ts +3 -3
  418. package/dist/engine/lsp/node-lsp-manager.js +32 -13
  419. package/dist/engine/session/path-to-root.d.ts +38 -0
  420. package/dist/engine/session/path-to-root.js +39 -0
  421. package/dist/engine/session/storage-base.js +4 -21
  422. package/dist/index.d.ts +35 -21
  423. package/dist/index.js +26 -17
  424. package/dist/internal/harness-types.d.ts +1 -1
  425. package/dist/internal/harness.d.ts +1 -0
  426. package/dist/internal/llm.d.ts +1 -0
  427. package/dist/orchestration/run-workflow-tool.d.ts +9 -3
  428. package/dist/orchestration/run-workflow-tool.js +59 -29
  429. package/dist/orchestration/workflow-governance.d.ts +1 -1
  430. package/dist/orchestration/workflow-governance.js +2 -1
  431. package/dist/orchestration/workflow-observe.d.ts +17 -1
  432. package/dist/orchestration/workflow-observe.js +20 -0
  433. package/dist/orchestration/workflow-types.d.ts +32 -7
  434. package/dist/orchestration/workflow.d.ts +4 -0
  435. package/dist/orchestration/workflow.js +762 -491
  436. package/dist/prompts/default.d.ts +1 -10
  437. package/dist/prompts/default.js +0 -2
  438. package/dist/shell/counting-pass.d.ts +50 -0
  439. package/dist/shell/counting-pass.js +502 -0
  440. package/dist/shell/lex.d.ts +4 -2
  441. package/dist/shell/lex.js +93 -34
  442. package/dist/shell/shell-words.d.ts +1 -1
  443. package/dist/shell/shell-words.js +7 -6
  444. package/dist/stores/file/background-agent-store.d.ts +1 -1
  445. package/dist/stores/file/background-agent-store.js +3 -1
  446. package/dist/stores/file/checkpoint-store.d.ts +127 -2
  447. package/dist/stores/file/checkpoint-store.js +19 -14
  448. package/dist/stores/file/file-history-store.d.ts +1 -1
  449. package/dist/stores/file/file-history-store.js +3 -1
  450. package/dist/stores/file/index.d.ts +4 -3
  451. package/dist/stores/file/index.js +17 -8
  452. package/dist/stores/file/mailbox-store.d.ts +1 -1
  453. package/dist/stores/file/mailbox-store.js +9 -11
  454. package/dist/stores/file/memory-store.d.ts +1 -1
  455. package/dist/stores/file/memory-store.js +3 -1
  456. package/dist/stores/file/session-policy-store.d.ts +1 -1
  457. package/dist/stores/file/session-policy-store.js +3 -1
  458. package/dist/stores/file/session-store.d.ts +1 -1
  459. package/dist/stores/file/session-store.js +3 -1
  460. package/dist/stores/file/shared-ledger.d.ts +26 -0
  461. package/dist/stores/file/shared-ledger.js +38 -9
  462. package/dist/stores/file/tool-result-store.d.ts +20 -2
  463. package/dist/stores/file/tool-result-store.js +74 -6
  464. package/dist/stores/file/usage-window-store.d.ts +1 -1
  465. package/dist/stores/file/usage-window-store.js +3 -1
  466. package/dist/stores/file/workflow-journal-store.d.ts +1 -11
  467. package/dist/stores/file/workflow-journal-store.js +3 -2
  468. package/dist/tools/fs/containment-face.d.ts +5 -0
  469. package/dist/tools/fs/encoding.d.ts +13 -4
  470. package/dist/tools/fs/encoding.js +17 -2
  471. package/dist/tools/fs/fs-bash-background-text.d.ts +7 -0
  472. package/dist/tools/fs/fs-bash-background-text.js +1 -0
  473. package/dist/tools/fs/fs-bash.d.ts +14 -4
  474. package/dist/tools/fs/fs-bash.js +29 -35
  475. package/dist/tools/fs/fs-pdf.d.ts +2 -2
  476. package/dist/tools/fs/fs-pdf.js +26 -21
  477. package/dist/tools/fs/fs-read.d.ts +5 -4
  478. package/dist/tools/fs/fs-read.js +35 -18
  479. package/dist/tools/fs/fs-search-tools.js +4 -1
  480. package/dist/tools/fs/fs-shared.d.ts +11 -13
  481. package/dist/tools/fs/fs-shared.js +11 -7
  482. package/dist/tools/fs/fs-write.js +5 -5
  483. package/dist/tools/fs/index.d.ts +14 -8
  484. package/dist/tools/fs/index.js +13 -5
  485. package/dist/tools/fs/program-read-model.d.ts +13 -0
  486. package/dist/tools/fs/program-read-model.js +15 -0
  487. package/dist/tools/fs/program-read-model.rows.js +1 -1
  488. package/dist/tools/fs/read-deny.d.ts +13 -10
  489. package/dist/tools/fs/read-deny.js +25 -5
  490. package/dist/tools/fs/read-floor.d.ts +62 -0
  491. package/dist/tools/fs/read-floor.js +58 -0
  492. package/dist/tools/fs/removal-targets.d.ts +9 -4
  493. package/dist/tools/fs/removal-targets.js +17 -9
  494. package/dist/tools/fs/search.d.ts +3 -3
  495. package/dist/tools/fs/search.js +4 -4
  496. package/dist/tools/fs/shell-read-check.d.ts +1 -1
  497. package/dist/tools/fs/shell-read-check.js +2 -1
  498. package/dist/tools/fs/shell-read-judge.d.ts +16 -8
  499. package/dist/tools/fs/shell-read-judge.js +10 -6
  500. package/dist/tools/fs/shell-read-plan.d.ts +6 -1
  501. package/dist/tools/fs/shell-read-plan.js +22 -15
  502. package/dist/tools/fs/shell-read-start.js +1 -0
  503. package/dist/tools/fs/shell-reentry-text.d.ts +15 -1
  504. package/dist/tools/fs/shell-reentry-text.js +25 -3
  505. package/dist/tools/monitor.d.ts +9 -4
  506. package/dist/tools/monitor.js +17 -8
  507. package/dist/tools/scheduler-tools.js +42 -4
  508. package/dist/tools/web.d.ts +0 -10
  509. package/dist/tools/web.js +1 -4
  510. package/package.json +5 -2
  511. package/test/export-surface.snapshot.json +161 -21
  512. package/wire-changes/core-stores-sql@7.59.0.json +29 -0
  513. package/wire-changes/core-stores-sql@7.60.0.json +30 -0
  514. package/wire-changes/core@7.59.0.json +2459 -0
  515. package/wire-changes/core@7.60.0.json +3274 -0
  516. package/wire-changes/mods-kernel@7.59.0.json +29 -0
  517. package/wire-changes/mods-kernel@7.60.0.json +62 -0
  518. package/wire-changes/primitives@7.59.0.json +29 -0
  519. package/wire-changes/primitives@7.60.0.json +30 -0
@@ -255,6 +255,14 @@ async function sleepAnnouncingRetry(totalMs, signal, frame) {
255
255
  return;
256
256
  }
257
257
  }
258
+ function suspendedFailure(wait, sleptMs) {
259
+ return {
260
+ kind: "suspended",
261
+ wait,
262
+ sleptMs,
263
+ err: new BrainError("network", `the host was suspended for ${Math.round(sleptMs / 1000)}s during the ${wait} wait; the connection it was waiting on was abandoned`, undefined, { apiError: true }),
264
+ };
265
+ }
258
266
  const RETRY_PHASE_OF_ERR_CLASS = {
259
267
  connect_refused: "reconnecting",
260
268
  transport: "reconnecting",
@@ -267,6 +275,9 @@ const RETRY_PHASE_OF_ERR_CLASS = {
267
275
  Object.freeze(RETRY_PHASE_OF_ERR_CLASS);
268
276
  const TRANSPORT_RETRY_DETAIL = "connection lost, reconnecting";
269
277
  function retryAnnouncement(failure) {
278
+ if (failure.kind === "suspended") {
279
+ return { errClass: "stall", detail: `the host was suspended for ${Math.round(failure.sleptMs / 1000)}s during the ${failure.wait} wait, reconnecting on a fresh connection`, sleptMs: failure.sleptMs };
280
+ }
270
281
  if (failure.kind !== "stalled")
271
282
  return { errClass: "transport", detail: TRANSPORT_RETRY_DETAIL };
272
283
  const knob = failure.allowanceMs !== undefined && failure.allowanceMs > 0
@@ -326,7 +337,7 @@ export function runStreamingBrain(args) {
326
337
  if (failure.code !== undefined) {
327
338
  if (failure.errorKind !== undefined)
328
339
  errorMsg.errorKind = failure.errorKind;
329
- else if (failure.inputTooLongRuledOut === true)
340
+ if (failure.inputTooLongRuledOut === true)
330
341
  errorMsg.inputTooLongRuledOut = true;
331
342
  if (readMember(err, "errorBodyIncomplete") === true)
332
343
  errorMsg.errorBodyIncomplete = true;
@@ -396,7 +407,7 @@ export function runStreamingBrain(args) {
396
407
  const firstTokenTimeoutMs = resolveWatchdogMs(config.firstTokenTimeoutMs, stallTimeouts?.firstTokenMs, STALL_FIRST_TOKEN_MS, "firstTokenTimeoutMs");
397
408
  const idleTimeoutMs = resolveWatchdogMs(config.idleTimeoutMs, stallTimeouts?.idleMs, STALL_IDLE_MS, "idleTimeoutMs");
398
409
  const firstByteRetryBudget = resolveFirstByteRetries(config.firstByteRetries);
399
- const armWaitDisclosure = (ceilingMs) => {
410
+ const armWaitDisclosure = (ceilingMs, waitSegment) => {
400
411
  if (!(ceilingMs >= WAITING_FIRST_TOKEN_AFTER_MS))
401
412
  return { stop: () => undefined, expire: () => undefined };
402
413
  const startedAt = Date.now();
@@ -407,7 +418,7 @@ export function runStreamingBrain(args) {
407
418
  const disclose = () => {
408
419
  disclosed = true;
409
420
  announcedWait = true;
410
- emitWaitFrame({ phase: "waiting_first_token", detail: "waiting for the first token", elapsedMs: Date.now() - startedAt, timeoutMs: ceilingMs });
421
+ emitWaitFrame({ phase: "waiting_first_token", detail: "waiting for the first token", elapsedMs: Date.now() - startedAt, timeoutMs: ceilingMs, waitSegment });
411
422
  };
412
423
  const schedule = (delayMs) => {
413
424
  timer = setTimeout(() => {
@@ -434,6 +445,20 @@ export function runStreamingBrain(args) {
434
445
  },
435
446
  };
436
447
  };
448
+ const waitAnnouncingRetry = async (announcement, lane) => {
449
+ emitBrainTelemetry({ kind: "retry", attempt: lane.attempt, phase: lane.phase, errClass: announcement.errClass, nextDelayMs: lane.delayMs });
450
+ announcedRetry = true;
451
+ await sleepAnnouncingRetry(lane.delayMs, signal, (remainingMs) => ({
452
+ phase: RETRY_PHASE_OF_ERR_CLASS[announcement.errClass],
453
+ detail: announcement.detail,
454
+ retryInSec: Math.ceil(remainingMs / 1000),
455
+ retryInMs: remainingMs,
456
+ attempt: lane.attempt,
457
+ maxRetries: lane.maxRetries,
458
+ errClass: announcement.errClass,
459
+ ...(announcement.sleptMs !== undefined ? { sleptMs: announcement.sleptMs } : {}),
460
+ }));
461
+ };
437
462
  let attempt = 0;
438
463
  let thinkingRetries = 0;
439
464
  let firstByteStalls = 0;
@@ -449,11 +474,12 @@ export function runStreamingBrain(args) {
449
474
  throw e;
450
475
  }
451
476
  const window = firstByteWindow(firstByteTimeoutMs, Buffer.byteLength(req.body), firstByteStalls);
452
- const headerWait = armWaitDisclosure(window.windowMs);
477
+ const headerWait = armWaitDisclosure(window.windowMs, "response_headers");
453
478
  const cc = createAttemptController(window.windowMs, signal);
454
479
  let r;
455
480
  let netErr;
456
481
  let firstByteStall;
482
+ let suspendedAtHeaders;
457
483
  requestIdSeen = undefined;
458
484
  attemptPartial = undefined;
459
485
  attemptOutput = undefined;
@@ -477,11 +503,20 @@ export function runStreamingBrain(args) {
477
503
  requestIdSeen = undefined;
478
504
  firstByteStall = stalledAtFirstByte();
479
505
  }
506
+ else if (cc.suspendedMs() !== undefined) {
507
+ discardResponseBody(r);
508
+ r = undefined;
509
+ requestIdSeen = undefined;
510
+ suspendedAtHeaders = suspendedFailure("response-header", cc.suspendedMs());
511
+ }
480
512
  }
481
513
  catch (e) {
482
514
  if (cc.timedOut()) {
483
515
  firstByteStall = stalledAtFirstByte();
484
516
  }
517
+ else if (cc.suspendedMs() !== undefined && !signal?.aborted) {
518
+ suspendedAtHeaders = suspendedFailure("response-header", cc.suspendedMs());
519
+ }
485
520
  else if (isAbortError(e) || signal?.aborted) {
486
521
  cc.dispose();
487
522
  throw e;
@@ -515,25 +550,24 @@ export function runStreamingBrain(args) {
515
550
  }
516
551
  cc.clearTimer();
517
552
  try {
553
+ if (suspendedAtHeaders !== undefined) {
554
+ if (attempt >= maxRetries)
555
+ throw suspendedAtHeaders.err;
556
+ const delayMs = retryBackoffMs(baseDelay, attempt);
557
+ attempt++;
558
+ cc.abort();
559
+ cc.dispose();
560
+ await waitAnnouncingRetry(retryAnnouncement(suspendedAtHeaders), { phase: "connect", attempt, maxRetries, delayMs });
561
+ continue;
562
+ }
518
563
  if (firstByteStall !== undefined) {
519
564
  if (firstByteStalls >= firstByteRetryBudget)
520
565
  throw firstByteStall.err;
521
566
  firstByteStalls++;
522
- const announcement = retryAnnouncement(firstByteStall);
523
567
  const delayMs = retryBackoffMs(baseDelay, firstByteStalls - 1);
524
- emitBrainTelemetry({ kind: "retry", attempt: firstByteStalls, phase: "connect", errClass: announcement.errClass, nextDelayMs: delayMs });
525
- announcedRetry = true;
526
568
  cc.abort();
527
569
  cc.dispose();
528
- await sleepAnnouncingRetry(delayMs, signal, (remainingMs) => ({
529
- phase: RETRY_PHASE_OF_ERR_CLASS[announcement.errClass],
530
- detail: announcement.detail,
531
- retryInSec: Math.ceil(remainingMs / 1000),
532
- retryInMs: remainingMs,
533
- attempt: firstByteStalls,
534
- maxRetries: firstByteRetryBudget,
535
- errClass: announcement.errClass,
536
- }));
570
+ await waitAnnouncingRetry(retryAnnouncement(firstByteStall), { phase: "connect", attempt: firstByteStalls, maxRetries: firstByteRetryBudget, delayMs });
537
571
  continue;
538
572
  }
539
573
  let errorBody;
@@ -661,6 +695,7 @@ export function runStreamingBrain(args) {
661
695
  throw new BrainError(classifyHttp(status), `${httpLabel} HTTP ${status || "ERR"}: ${detail.slice(0, 500)}${overflowDeclineNote}`, status, {
662
696
  apiError: true,
663
697
  ...(itl === "yes" ? { inputTooLong: true } : itl === "no" ? { inputTooLongRuledOut: true } : {}),
698
+ ...(terminalVerdict?.imageUnprocessable === true ? { imageUnprocessable: true } : {}),
664
699
  ...(providerCode !== undefined ? { providerCode } : {}),
665
700
  ...(terminalVerdict !== undefined ? { verdict: { condition: terminalVerdict.condition, source: terminalVerdict.source, ...(terminalVerdict.resetAtMs !== undefined ? { resetAtMs: terminalVerdict.resetAtMs } : {}) } } : {}),
666
701
  ...(errorBody !== undefined && !errorBody.endedNormally ? { errorBodyIncomplete: true } : {}),
@@ -684,9 +719,19 @@ export function runStreamingBrain(args) {
684
719
  let firedFirstTokenDeadlineMs;
685
720
  let ftTimer;
686
721
  let firstTokenWait = { stop: () => undefined, expire: () => undefined };
722
+ const streamSuspend = connect.suspend;
723
+ let suspendedInStream;
724
+ const cutOnSuspend = (wait) => (sleptMs) => {
725
+ suspendedInStream = suspendedFailure(wait, sleptMs);
726
+ void reader.cancel().catch(() => undefined);
727
+ };
687
728
  if (firstTokenTimeoutMs && firstTokenTimeoutMs > 0) {
688
- firstTokenWait = armWaitDisclosure(firstTokenTimeoutMs);
729
+ firstTokenWait = armWaitDisclosure(firstTokenTimeoutMs, "first_token");
730
+ streamSuspend.arm(firstTokenTimeoutMs, cutOnSuspend("first-token"));
689
731
  ftTimer = setTimeout(() => {
732
+ if (streamSuspend.check())
733
+ return;
734
+ streamSuspend.disarm();
690
735
  firedFirstTokenDeadlineMs = firstTokenTimeoutMs;
691
736
  firstTokenWait.expire();
692
737
  void reader.cancel().catch(() => undefined);
@@ -698,25 +743,32 @@ export function runStreamingBrain(args) {
698
743
  if (!idleTimeoutMs || idleTimeoutMs <= 0)
699
744
  return;
700
745
  firedIdleDeadlineMs = undefined;
746
+ suspendedInStream = undefined;
701
747
  if (idleTimer)
702
748
  clearTimeout(idleTimer);
749
+ streamSuspend.arm(idleTimeoutMs, cutOnSuspend("stream idle"));
703
750
  idleTimer = setTimeout(() => {
751
+ if (streamSuspend.check())
752
+ return;
753
+ streamSuspend.disarm();
704
754
  firedIdleDeadlineMs = idleTimeoutMs;
705
755
  void reader.cancel().catch(() => undefined);
706
756
  }, idleTimeoutMs);
707
757
  };
708
758
  const sawContentToken = () => {
709
- bumpIdle();
710
- if (firstTokenSeen)
711
- return;
712
- firstTokenSeen = true;
713
- firstTokenArrived = true;
714
- firedFirstTokenDeadlineMs = undefined;
715
- if (ftTimer) {
716
- clearTimeout(ftTimer);
717
- ftTimer = undefined;
759
+ if (!firstTokenSeen) {
760
+ firstTokenSeen = true;
761
+ firstTokenArrived = true;
762
+ firedFirstTokenDeadlineMs = undefined;
763
+ suspendedInStream = undefined;
764
+ if (ftTimer) {
765
+ clearTimeout(ftTimer);
766
+ ftTimer = undefined;
767
+ }
768
+ firstTokenWait.stop();
769
+ streamSuspend.disarm();
718
770
  }
719
- firstTokenWait.stop();
771
+ bumpIdle();
720
772
  };
721
773
  cleanup = () => {
722
774
  if (ftTimer) {
@@ -806,6 +858,9 @@ export function runStreamingBrain(args) {
806
858
  clearTimeout(idleTimer);
807
859
  idleTimer = undefined;
808
860
  }
861
+ streamSuspend.disarm();
862
+ if (!failure && suspendedInStream !== undefined)
863
+ failure = suspendedInStream;
809
864
  if (!failure && firedFirstTokenDeadlineMs !== undefined) {
810
865
  failure = {
811
866
  kind: "stalled",
@@ -855,34 +910,14 @@ export function runStreamingBrain(args) {
855
910
  thinkingRetries++;
856
911
  parser.sealForRetry();
857
912
  const delayMs = 100 * thinkingRetries;
858
- emitBrainTelemetry({ kind: "retry", attempt: thinkingRetries, phase: "midstream", errClass: announcement.errClass, nextDelayMs: delayMs });
859
- announcedRetry = true;
860
- await sleepAnnouncingRetry(delayMs, signal, (remainingMs) => ({
861
- phase: RETRY_PHASE_OF_ERR_CLASS[announcement.errClass],
862
- detail: announcement.detail,
863
- retryInSec: Math.ceil(remainingMs / 1000),
864
- retryInMs: remainingMs,
865
- attempt: thinkingRetries,
866
- maxRetries: THINKING_RETRY_BUDGET,
867
- errClass: announcement.errClass,
868
- }));
913
+ await waitAnnouncingRetry(announcement, { phase: "midstream", attempt: thinkingRetries, maxRetries: THINKING_RETRY_BUDGET, delayMs });
869
914
  continue;
870
915
  }
871
916
  if (attempt >= maxRetries)
872
917
  throw failure.err;
873
918
  const delayMs = retryBackoffMs(baseDelay, attempt);
874
919
  attempt++;
875
- emitBrainTelemetry({ kind: "retry", attempt, phase: "midstream", errClass: announcement.errClass, nextDelayMs: delayMs });
876
- announcedRetry = true;
877
- await sleepAnnouncingRetry(delayMs, signal, (remainingMs) => ({
878
- phase: RETRY_PHASE_OF_ERR_CLASS[announcement.errClass],
879
- detail: announcement.detail,
880
- retryInSec: Math.ceil(remainingMs / 1000),
881
- retryInMs: remainingMs,
882
- attempt,
883
- maxRetries,
884
- errClass: announcement.errClass,
885
- }));
920
+ await waitAnnouncingRetry(announcement, { phase: "midstream", attempt, maxRetries, delayMs });
886
921
  }
887
922
  }
888
923
  }
@@ -93,6 +93,36 @@ export interface TurnCapFacts {
93
93
  outputTokens: number | undefined;
94
94
  capTokens: number | undefined;
95
95
  }
96
+ /**
97
+ * The door's reading of a stream frame's members, one reading for every lane's frame decoder: a member the
98
+ * lane reads is taken only in the shape the wire defines — an object (non-null, non-array), an array, a string (`word`),
99
+ * a count. `null` and absent state nothing (`undefined`, not recorded). Any other value is a member in no shape: it reads
100
+ * as `undefined` — never coerced, never dereferenced — and the reader records it (`outOfShape`), so the lane says the loss
101
+ * where that member's loss is already said. A lane keeps one reader per outlet (the frame, the call stream, the usage), so
102
+ * one outlet's record never speaks for another's.
103
+ */
104
+ export interface MemberReader {
105
+ object(v: unknown): Record<string, unknown> | undefined;
106
+ array(v: unknown): readonly unknown[] | undefined;
107
+ word(v: unknown): string | undefined;
108
+ count(v: unknown): number | undefined;
109
+ /** Did a member this reader read hold a value in no shape? */
110
+ readonly outOfShape: boolean;
111
+ }
112
+ export declare function memberReader(): MemberReader;
113
+ /** The word a seat reads when something arrived there in no word shape — the echo seat's placeholder: an ending in no
114
+ * word, a late frame the door could not read. */
115
+ export declare const NO_WORD = "?";
116
+ /** The stream's ending seat as both wires read it (`finish_reason`, `stop_reason`), before AND after the end, by one rule:
117
+ * a falsy value states no ending (as it always read); a string is the provider's word; any other value (a number, `true`,
118
+ * an object) is an ending in no word the engine reads — {@link NO_WORD}. */
119
+ export declare function endingWordOf(raw: unknown): string | null;
120
+ /** Did the ending seat hold a non-word ({@link endingWordOf}'s third answer) — not a provider that spelled `?`? */
121
+ export declare function endingInNoWord(raw: unknown): boolean;
122
+ /** The one sentence a turn's dropped frames are stated in (the `bad_frame` note), for the three lanes: `data:` frames that
123
+ * were not valid JSON, or that held members in no shape the stream defines ({@link MemberReader}) — counted together, the
124
+ * first one's bytes as the sample. */
125
+ export declare function droppedFramesNote(count: number, sample: string | undefined): string;
96
126
  /**
97
127
  * The structured account of a turn that FAILED for its dropped tool calls (`AssistantMessage.modelOutputInvalid`) —
98
128
  * the lane calls it on the arm whose message is the dropped-calls sentence. `cause` is `truncated` when any call's
@@ -48,7 +48,40 @@ export function truncationCauseClause(facts) {
48
48
  }
49
49
  return terminalFrameSeen ? "" : "; the stream ended before its stop frame — the connection closed mid-response";
50
50
  }
51
- const countOf = (v) => (typeof v === "number" && Number.isInteger(v) && v >= 0 ? v : undefined);
51
+ const isCount = (v) => typeof v === "number" && Number.isInteger(v) && v >= 0;
52
+ const countOf = (v) => (isCount(v) ? v : undefined);
53
+ export function memberReader() {
54
+ let outOfShape = false;
55
+ const take = (v, inShape) => {
56
+ if (v === null || v === undefined)
57
+ return undefined;
58
+ if (inShape(v))
59
+ return v;
60
+ outOfShape = true;
61
+ return undefined;
62
+ };
63
+ return {
64
+ object: (v) => take(v, (x) => typeof x === "object" && !Array.isArray(x)),
65
+ array: (v) => take(v, Array.isArray),
66
+ word: (v) => take(v, (x) => typeof x === "string"),
67
+ count: (v) => take(v, isCount),
68
+ get outOfShape() {
69
+ return outOfShape;
70
+ },
71
+ };
72
+ }
73
+ export const NO_WORD = "?";
74
+ export function endingWordOf(raw) {
75
+ if (!raw)
76
+ return null;
77
+ return typeof raw === "string" ? raw : NO_WORD;
78
+ }
79
+ export function endingInNoWord(raw) {
80
+ return endingWordOf(raw) === NO_WORD && raw !== NO_WORD;
81
+ }
82
+ export function droppedFramesNote(count, sample) {
83
+ return `\n[note: ${count} provider stream frame(s) were not valid JSON or not in the stream's frame shape; what could not be read was dropped — the streamed output may be missing content (first sample: ${JSON.stringify(sample)})]`;
84
+ }
52
85
  export function modelOutputInvalidOf(drops, cap) {
53
86
  if (drops.truncated > 0) {
54
87
  const outputTokens = countOf(cap.outputTokens);
@@ -47,7 +47,8 @@ export declare function resolveStallTimeoutMs(value: number | undefined, knob: s
47
47
  * prefill BEFORE writing headers is silent here for minutes and healthy; the 30s "connect" clock
48
48
  * this replaces cut that prefill and re-sent the same body ten times. 300s is the reference
49
49
  * implementation's window for a non-first-party route; the window grows with the request body
50
- * ({@link firstByteWindow}) and the one retry is widened ({@link FIRST_BYTE_RETRY_WINDOW_FACTOR}).
50
+ * up to {@link FIRST_BYTE_WINDOW_CAP_MS} ({@link firstByteWindow}) and the one retry is widened
51
+ * ({@link FIRST_BYTE_RETRY_WINDOW_FACTOR}).
51
52
  * - first-token 600s: bounds the headers→first-delta wait, NOT the model's thought (the first
52
53
  * THINKING delta already counts as the first token, design/17 O5), so a slow reasoner is safe. A
53
54
  * minutes-scale bound is FALSE for a self-hosted server working through a long prefill AFTER
@@ -86,8 +87,17 @@ export declare const RETIRED_TIMEOUT_KNOBS: {
86
87
  export declare function refuseRetiredTimeoutKnobs(holder: object | undefined, level: keyof typeof RETIRED_TIMEOUT_KNOBS, where: string): void;
87
88
  /** The first-byte window grows with the request body: one second per this many bytes, rounded up (the
88
89
  * reference implementation's allowance) — a large context on a slow uplink is still UPLOADING when a
89
- * fixed window would call the gateway silent. */
90
+ * fixed window would call the gateway silent. The growth stops at {@link FIRST_BYTE_WINDOW_CAP_MS}. */
90
91
  export declare const FIRST_BYTE_UPLOAD_BYTES_PER_SECOND = 32768;
92
+ /**
93
+ * The most the upload allowance may grow a first-byte window to: 599 s, the reference implementation's
94
+ * default (its request timeout, 600 s, less one second). Without it the window grew with the body without
95
+ * bound — a 40 MB request (a context full of screenshots) armed 300 s + 1 280 s, so a gateway that never
96
+ * answered was given up on after ~26 minutes. The cap bounds the ALLOWANCE only: a knob (or its widened
97
+ * retry) already at or above it is the window as set and gains no allowance — a deployment that chose a
98
+ * longer wait is never shortened behind its back.
99
+ */
100
+ export declare const FIRST_BYTE_WINDOW_CAP_MS = 599000;
91
101
  /** A first-byte stall is re-sent at most this many times by default ({@link BrainTimeoutConfig.firstByteRetries}),
92
102
  * out of its OWN budget rather than `maxRetries` (the reference implementation: "normally one retry, not the
93
103
  * session budget"); the shared ladder counts transport failures, and this is not one. */
@@ -106,7 +116,9 @@ export declare function resolveWatchdogMs(configured: number | undefined, adviso
106
116
  export interface FirstByteWindow {
107
117
  /** The knob's value for THIS attempt (the configured value, widened on the retry). */
108
118
  knobMs: number;
109
- /** The upload allowance added for the request body, ms (0 for an empty body). */
119
+ /** The upload allowance granted for the request body, ms: one second per
120
+ * {@link FIRST_BYTE_UPLOAD_BYTES_PER_SECOND} bytes, granted up to {@link FIRST_BYTE_WINDOW_CAP_MS} and no
121
+ * further (0 for an empty body, and for a knob already at the cap). */
110
122
  allowanceMs: number;
111
123
  /** What is actually armed: `knobMs + allowanceMs`, capped at {@link MAX_TIMER_DELAY_MS}. `0` = off. */
112
124
  windowMs: number;
@@ -127,8 +139,9 @@ export interface BrainTimeoutConfig {
127
139
  /**
128
140
  * `fetch()` call → response headers, ms: the window a gateway has to START answering (until 7.33.0 a
129
141
  * knob named `connectTimeoutMs` bounded this wait; it is gone — the connect clock is the transport's). Absent ⇒
130
- * {@link STALL_FIRST_BYTE_MS}; the armed window grows with the request body ({@link firstByteWindow});
131
- * a stall earns ONE retry at a widened window ({@link firstByteRetries}), then fails naming this knob.
142
+ * {@link STALL_FIRST_BYTE_MS}; the armed window grows with the request body up to
143
+ * {@link FIRST_BYTE_WINDOW_CAP_MS} ({@link firstByteWindow}); a value at or above that cap is the window
144
+ * as set. A stall earns ONE retry at a widened window ({@link firstByteRetries}), then fails naming this knob.
132
145
  * Fires as a `stall` (this process cancelled its own request), never as a transport fault. `0` ⇒ off.
133
146
  */
134
147
  firstByteTimeoutMs?: number;
@@ -157,16 +170,60 @@ export interface BrainTimeoutConfig {
157
170
  */
158
171
  idleTimeoutMs?: number;
159
172
  }
173
+ /** How often the wall clock is read while a wait is judged for a host suspend (the reference
174
+ * implementation's sampling period). */
175
+ export declare const SUSPEND_SAMPLE_MS = 1000;
176
+ /** A gap between two samples longer than this is time this process did not run — the host slept, or the
177
+ * process was stopped — and is counted as slept, whole (the reference implementation's threshold). A
178
+ * shorter gap is a busy event loop, not a suspend. */
179
+ export declare const SUSPEND_GAP_MS = 5000;
180
+ /**
181
+ * The ONE host-suspend judgment every model-call wait reads — the response headers, the first token, the
182
+ * silence between deltas. A host that sleeps (a laptop lid closed over lunch) stops every timer; on waking,
183
+ * the connection the wait was on is usually gone, and a timer clock that did not count the sleep would
184
+ * leave the wait to run out its whole window on it. So while a wait is armed the wall clock is read every
185
+ * {@link SUSPEND_SAMPLE_MS}: the sampler is SCHEDULED on the timer clock, so a gap between two readings
186
+ * longer than {@link SUSPEND_GAP_MS} is time the timers did not run, and it is counted as slept. The armed
187
+ * wait ends — `onSuspend(sleptMs)`, once — at the first sample where the sleep it has seen exceeds half its
188
+ * window; a deadline calls {@link SuspendWatch.check} before it judges, so a deadline that runs before the
189
+ * next sample names the same suspend.
190
+ *
191
+ * The wall clock alone, not a monotonic reading beside it: a monotonic clock that counts sleep (the host's
192
+ * choice, not the engine's) cannot see a suspend at all, while a gap between samples scheduled on the timer
193
+ * clock is visible whichever way the host counts. A forward step of the wall clock reads as a suspend and
194
+ * costs one reconnect; a backward step is not counted.
195
+ */
196
+ export interface SuspendWatch {
197
+ /** Judge a new wait of `windowMs` from now — the sleep seen before this call is not its sleep. Replaces any
198
+ * armed wait; `0` (a watchdog that is off) judges nothing. */
199
+ arm(windowMs: number, onSuspend: (sleptMs: number) => void): void;
200
+ /** The armed wait ended (headers, the first token, the attempt). */
201
+ disarm(): void;
202
+ /** Read the clock now: `true` when this reading ended the armed wait as a suspend (its `onSuspend` ran). */
203
+ check(): boolean;
204
+ /** Stop for good (the attempt is over). */
205
+ dispose(): void;
206
+ }
207
+ export declare function watchSuspend(): SuspendWatch;
160
208
  /**
161
209
  * A per-attempt abort controller that fires at the first-byte deadline while still forwarding an
162
210
  * outer (task) abort. The returned `signal` governs the **whole** request including the streamed body
163
211
  * — so once headers arrive, call `clearTimer()` (NOT `dispose()`) to stop the deadline while keeping
164
212
  * the outer-abort link alive for the body read; call `dispose()` only when the request is fully done
165
213
  * or being discarded.
214
+ *
215
+ * The header wait is also judged for a host suspend ({@link SuspendWatch}, armed with the same window):
216
+ * a suspend aborts the signal like the deadline does, and is told apart by {@link suspendedMs} rather than
217
+ * {@link timedOut}. The same watch is handed on (`suspend`) for the waits after the headers; `dispose()`
218
+ * ends it.
166
219
  */
167
220
  export declare function createAttemptController(firstByteWindowMs: number | undefined, outerSignal: AbortSignal | undefined): {
168
221
  signal: AbortSignal;
169
222
  timedOut: () => boolean;
223
+ /** How long the host was suspended across the header wait, when that is what ended it; else undefined. */
224
+ suspendedMs: () => number | undefined;
225
+ /** The attempt's suspend judgment, for the waits after the headers (first token, idle). */
226
+ suspend: SuspendWatch;
170
227
  clearTimer: () => void;
171
228
  /** Abort this attempt's signal. The signal handed to `doFetch` is how an injected fetch wrapper
172
229
  * learns it may release its transport, so an attempt being ABANDONED (its error body cut short by
@@ -221,6 +278,8 @@ export interface BrainCallGuardrailRef {
221
278
  *
222
279
  * `return()` on the wrapped iterator forwards the inner cleanup WITHOUT awaiting it: the whole point
223
280
  * is that the engine stops waiting on a brain, so releasing the iterator must not re-introduce a wait
224
- * on the same hung code.
281
+ * on the same hung code. A `return()` before the brain's terminal event abandons the call: the signal the
282
+ * brain holds is aborted first, since a stream's own `return()` need not cancel its request and, once the
283
+ * gate is disarmed, no outer abort reaches the brain any more.
225
284
  */
226
285
  export declare function withBrainCallGuardrail(streamFn: StreamFn, limitMs: number, ref: BrainCallGuardrailRef): StreamFn;
@@ -34,6 +34,7 @@ export function refuseRetiredTimeoutKnobs(holder, level, where) {
34
34
  }
35
35
  }
36
36
  export const FIRST_BYTE_UPLOAD_BYTES_PER_SECOND = 32_768;
37
+ export const FIRST_BYTE_WINDOW_CAP_MS = 599_000;
37
38
  export const FIRST_BYTE_RETRY_BUDGET = 1;
38
39
  export function resolveFirstByteRetries(value) {
39
40
  if (value === undefined)
@@ -53,7 +54,8 @@ export function firstByteWindow(knobMs, bodyBytes, retryIndex) {
53
54
  if (knobMs === undefined || knobMs <= 0)
54
55
  return { knobMs: 0, allowanceMs: 0, windowMs: 0 };
55
56
  const widened = knobMs * FIRST_BYTE_RETRY_WINDOW_FACTOR ** Math.max(0, retryIndex);
56
- const allowanceMs = Math.ceil(Math.max(0, bodyBytes) / FIRST_BYTE_UPLOAD_BYTES_PER_SECOND) * 1000;
57
+ const uploadMs = Math.ceil(Math.max(0, bodyBytes) / FIRST_BYTE_UPLOAD_BYTES_PER_SECOND) * 1000;
58
+ const allowanceMs = Math.min(uploadMs, Math.max(0, FIRST_BYTE_WINDOW_CAP_MS - widened));
57
59
  return { knobMs: widened, allowanceMs, windowMs: Math.min(widened + allowanceMs, MAX_TIMER_DELAY_MS) };
58
60
  }
59
61
  export function firstByteLaneKnobMs(knobMs) {
@@ -62,6 +64,76 @@ export function firstByteLaneKnobMs(knobMs) {
62
64
  total += firstByteWindow(knobMs, 0, retryIndex).knobMs;
63
65
  return total;
64
66
  }
67
+ export const SUSPEND_SAMPLE_MS = 1_000;
68
+ export const SUSPEND_GAP_MS = 5_000;
69
+ export function watchSuspend() {
70
+ let readAt = 0;
71
+ let sleptMs = 0;
72
+ let wait;
73
+ let timer;
74
+ let disposed = false;
75
+ const read = () => {
76
+ const now = Date.now();
77
+ const gap = now - readAt;
78
+ readAt = now;
79
+ if (gap > SUSPEND_GAP_MS)
80
+ sleptMs += gap;
81
+ };
82
+ const stopSampling = () => {
83
+ if (timer !== undefined)
84
+ clearTimeout(timer);
85
+ timer = undefined;
86
+ };
87
+ const check = () => {
88
+ if (wait === undefined)
89
+ return false;
90
+ read();
91
+ const slept = sleptMs - wait.sleptAtArm;
92
+ if (!(slept > wait.windowMs / 2))
93
+ return false;
94
+ const { onSuspend } = wait;
95
+ wait = undefined;
96
+ stopSampling();
97
+ onSuspend(slept);
98
+ return true;
99
+ };
100
+ const sample = () => {
101
+ timer = setTimeout(() => {
102
+ timer = undefined;
103
+ if (!check() && wait !== undefined)
104
+ sample();
105
+ }, SUSPEND_SAMPLE_MS);
106
+ timer.unref?.();
107
+ };
108
+ return {
109
+ arm(windowMs, onSuspend) {
110
+ if (disposed)
111
+ return;
112
+ if (timer !== undefined)
113
+ read();
114
+ else
115
+ readAt = Date.now();
116
+ if (!(windowMs > 0)) {
117
+ wait = undefined;
118
+ stopSampling();
119
+ return;
120
+ }
121
+ wait = { windowMs, sleptAtArm: sleptMs, onSuspend };
122
+ if (timer === undefined)
123
+ sample();
124
+ },
125
+ disarm() {
126
+ wait = undefined;
127
+ stopSampling();
128
+ },
129
+ check,
130
+ dispose() {
131
+ disposed = true;
132
+ wait = undefined;
133
+ stopSampling();
134
+ },
135
+ };
136
+ }
65
137
  export function createAttemptController(firstByteWindowMs, outerSignal) {
66
138
  const ac = new AbortController();
67
139
  let timedOut = false;
@@ -73,24 +145,39 @@ export function createAttemptController(firstByteWindowMs, outerSignal) {
73
145
  outerSignal.addEventListener("abort", onAbort, { once: true });
74
146
  }
75
147
  let timer;
148
+ let suspendedMs;
149
+ const suspend = watchSuspend();
150
+ const clearTimer = () => {
151
+ if (timer)
152
+ clearTimeout(timer);
153
+ timer = undefined;
154
+ suspend.disarm();
155
+ };
76
156
  if (firstByteWindowMs && firstByteWindowMs > 0) {
157
+ suspend.arm(firstByteWindowMs, (slept) => {
158
+ suspendedMs = slept;
159
+ clearTimer();
160
+ ac.abort();
161
+ });
77
162
  timer = setTimeout(() => {
163
+ timer = undefined;
164
+ if (suspend.check())
165
+ return;
166
+ suspend.disarm();
78
167
  timedOut = true;
79
168
  ac.abort();
80
169
  }, firstByteWindowMs);
81
170
  }
82
- const clearTimer = () => {
83
- if (timer)
84
- clearTimeout(timer);
85
- timer = undefined;
86
- };
87
171
  return {
88
172
  signal: ac.signal,
89
173
  timedOut: () => timedOut,
174
+ suspendedMs: () => suspendedMs,
175
+ suspend,
90
176
  clearTimer,
91
177
  abort: () => ac.abort(),
92
178
  dispose: () => {
93
179
  clearTimer();
180
+ suspend.dispose();
94
181
  if (outerSignal)
95
182
  outerSignal.removeEventListener("abort", onAbort);
96
183
  },
@@ -137,6 +224,7 @@ function armCallGuardrail(limitMs, outerSignal, ref) {
137
224
  outerSignal.addEventListener("abort", forwardAbort, { once: true });
138
225
  }
139
226
  let expired;
227
+ let over = false;
140
228
  let rejectExpiry = () => undefined;
141
229
  const expiry = new Promise((_resolve, reject) => {
142
230
  rejectExpiry = reject;
@@ -159,12 +247,22 @@ function armCallGuardrail(limitMs, outerSignal, ref) {
159
247
  throw expired;
160
248
  return value;
161
249
  },
162
- disarm: () => {
163
- clearTimeout(timer);
164
- if (outerSignal !== undefined)
165
- outerSignal.removeEventListener("abort", forwardAbort);
250
+ disarm,
251
+ answered: () => {
252
+ over = true;
253
+ },
254
+ abandon: () => {
255
+ if (!over)
256
+ ac.abort();
257
+ disarm();
166
258
  },
167
259
  };
260
+ function disarm() {
261
+ over = true;
262
+ clearTimeout(timer);
263
+ if (outerSignal !== undefined)
264
+ outerSignal.removeEventListener("abort", forwardAbort);
265
+ }
168
266
  }
169
267
  export function withBrainCallGuardrail(streamFn, limitMs, ref) {
170
268
  return async (model, context, options) => {
@@ -192,10 +290,12 @@ export function withBrainCallGuardrail(streamFn, limitMs, ref) {
192
290
  }
193
291
  if (step.done === true)
194
292
  gate.disarm();
293
+ else if (step.value.type === "done" || step.value.type === "error")
294
+ gate.answered();
195
295
  return step;
196
296
  },
197
297
  return: async () => {
198
- gate.disarm();
298
+ gate.abandon();
199
299
  const release = it.return;
200
300
  if (release !== undefined) {
201
301
  Promise.resolve(release.call(it)).catch(() => undefined);