@sema-agent/core 7.67.2 → 7.68.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 (505) hide show
  1. package/CHANGELOG.md +1533 -0
  2. package/README.md +18 -9
  3. package/README.zh-CN.md +16 -8
  4. package/dist/agents/agent-definition.d.ts +1 -1
  5. package/dist/agents/agent-definition.js +4 -1
  6. package/dist/agents/cascade.d.ts +2 -2
  7. package/dist/agents/cascade.js +3 -1
  8. package/dist/agents/cumulative-stats.d.ts +2 -1
  9. package/dist/agents/cumulative-stats.js +4 -1
  10. package/dist/agents/list-agents-tool.d.ts +30 -0
  11. package/dist/agents/list-agents-tool.js +45 -3
  12. package/dist/agents/peer-admission.d.ts +2 -2
  13. package/dist/agents/peer-session-drain.d.ts +2 -0
  14. package/dist/agents/peer-session-drain.js +1 -0
  15. package/dist/agents/repair-loop.js +3 -1
  16. package/dist/agents/retain-ledger.d.ts +61 -8
  17. package/dist/agents/retain-ledger.js +25 -3
  18. package/dist/agents/roster-store.d.ts +4 -2
  19. package/dist/agents/send-message-tool.d.ts +1 -1
  20. package/dist/agents/send-message-tool.js +20 -15
  21. package/dist/agents/subagent-steps.js +2 -10
  22. package/dist/agents/subagent.d.ts +3 -0
  23. package/dist/agents/subagent.js +106 -76
  24. package/dist/agents/tool-filter.d.ts +20 -11
  25. package/dist/agents/tool-filter.js +8 -4
  26. package/dist/agents/verify.d.ts +3 -1
  27. package/dist/agents/verify.js +2 -0
  28. package/dist/brain/anthropic.js +4 -4
  29. package/dist/brain/errors.d.ts +20 -0
  30. package/dist/brain/errors.js +114 -0
  31. package/dist/brain/open-responses.js +3 -1
  32. package/dist/brain/openai.js +3 -1
  33. package/dist/brain/provider-message.d.ts +5 -3
  34. package/dist/brain/provider-message.js +35 -8
  35. package/dist/brain/reasoning-request.d.ts +73 -19
  36. package/dist/brain/reasoning-request.js +164 -72
  37. package/dist/brain/reasoning-stamp.d.ts +26 -0
  38. package/dist/brain/reasoning-stamp.js +10 -0
  39. package/dist/brain/reasoning.d.ts +95 -162
  40. package/dist/brain/reasoning.js +31 -86
  41. package/dist/brain/route-adjudicator.d.ts +9 -7
  42. package/dist/brain/route-adjudicator.js +12 -10
  43. package/dist/brain/status-sink.d.ts +19 -64
  44. package/dist/brain/status-sink.js +5 -21
  45. package/dist/brain/stream-engine.d.ts +11 -2
  46. package/dist/brain/stream-engine.js +10 -0
  47. package/dist/core/a2a.d.ts +17 -5
  48. package/dist/core/a2a.js +11 -3
  49. package/dist/core/allow-entry.d.ts +35 -15
  50. package/dist/core/allow-entry.js +47 -60
  51. package/dist/core/ask-headline.d.ts +68 -0
  52. package/dist/core/ask-headline.js +23 -0
  53. package/dist/core/ask-origin.d.ts +36 -8
  54. package/dist/core/ask-origin.js +17 -10
  55. package/dist/core/ask-question.d.ts +34 -7
  56. package/dist/core/ask-question.js +10 -1
  57. package/dist/core/ask-unresolvable-notice.d.ts +7 -0
  58. package/dist/core/ask-unresolvable-notice.js +9 -3
  59. package/dist/core/auto-strip.d.ts +53 -0
  60. package/dist/core/auto-strip.js +76 -0
  61. package/dist/core/background-agent-store.d.ts +45 -5
  62. package/dist/core/background-agent-store.js +69 -15
  63. package/dist/core/background-shell.d.ts +2 -2
  64. package/dist/core/caller-text.js +2 -2
  65. package/dist/core/canonical-json.d.ts +13 -0
  66. package/dist/core/canonical-json.js +7 -0
  67. package/dist/core/checkpoint-features.d.ts +66 -20
  68. package/dist/core/checkpoint-features.js +12 -1
  69. package/dist/core/checkpoint-generation.d.ts +1 -1
  70. package/dist/core/checkpoint-queries.d.ts +1 -1
  71. package/dist/core/checkpoint-queries.js +4 -1
  72. package/dist/core/checkpoint-requirements.d.ts +25 -1
  73. package/dist/core/checkpoint-requirements.js +5 -1
  74. package/dist/core/checkpoint-row-verdict.d.ts +1 -0
  75. package/dist/core/checkpoint-row-verdict.js +4 -0
  76. package/dist/core/checkpoint-store.d.ts +66 -38
  77. package/dist/core/checkpoint-store.js +15 -6
  78. package/dist/core/child-clamp-seats.d.ts +6 -0
  79. package/dist/core/child-clamp-seats.js +1 -0
  80. package/dist/core/config-refusal-codes.d.ts +1 -1
  81. package/dist/core/config-refusal-codes.js +1 -0
  82. package/dist/core/delegation-frames.d.ts +9 -12
  83. package/dist/core/delegation-frames.js +9 -8
  84. package/dist/core/engine-capabilities.d.ts +21 -8
  85. package/dist/core/engine-capabilities.js +1 -1
  86. package/dist/core/engine-notice.d.ts +147 -34
  87. package/dist/core/engine-notice.js +27 -16
  88. package/dist/core/engine-storage-backend.d.ts +2 -1
  89. package/dist/core/env-budget.js +3 -3
  90. package/dist/core/env-knob-announce.d.ts +10 -10
  91. package/dist/core/env-knob-announce.js +3 -6
  92. package/dist/core/file-history-store.d.ts +29 -4
  93. package/dist/core/file-history-store.js +13 -0
  94. package/dist/core/frame-settlement.d.ts +2 -1
  95. package/dist/core/gate-fold.js +1 -1
  96. package/dist/core/gate-lanes.js +56 -49
  97. package/dist/core/governance-codes.d.ts +39 -3
  98. package/dist/core/governance-codes.js +61 -3
  99. package/dist/core/hooks.d.ts +29 -11
  100. package/dist/core/hooks.js +5 -2
  101. package/dist/core/human-input-projection.js +3 -3
  102. package/dist/core/input-author.d.ts +17 -3
  103. package/dist/core/input-author.js +15 -3
  104. package/dist/core/leg-identity.d.ts +10 -28
  105. package/dist/core/leg-identity.js +1 -21
  106. package/dist/core/lsp.d.ts +18 -13
  107. package/dist/core/lsp.js +30 -22
  108. package/dist/core/mailbox-store.d.ts +1 -1
  109. package/dist/core/mailbox-store.js +4 -4
  110. package/dist/core/mcp-connection-pool.d.ts +93 -4
  111. package/dist/core/mcp-connection-pool.js +104 -1
  112. package/dist/core/mcp-failure.d.ts +38 -12
  113. package/dist/core/mcp-failure.js +9 -13
  114. package/dist/core/mcp-probe.d.ts +4 -3
  115. package/dist/core/mcp-server-link.d.ts +4 -2
  116. package/dist/core/mcp-server-link.js +4 -5
  117. package/dist/core/mcp-server-spec.d.ts +3 -3
  118. package/dist/core/mcp-server-unavailable-notice.d.ts +22 -8
  119. package/dist/core/mcp-server-unavailable-notice.js +18 -4
  120. package/dist/core/mcp.d.ts +40 -6
  121. package/dist/core/mcp.js +39 -13
  122. package/dist/core/memory-engine/content-origin.js +2 -2
  123. package/dist/core/memory-engine/control-objects.d.ts +2 -4
  124. package/dist/core/memory-engine/control-objects.js +2 -10
  125. package/dist/core/memory-engine/delegation-settlement.js +6 -1
  126. package/dist/core/memory-engine/dual-root.js +3 -0
  127. package/dist/core/memory-engine/engine.d.ts +6 -4
  128. package/dist/core/memory-engine/engine.js +32 -29
  129. package/dist/core/memory-engine/file-backend.d.ts +20 -5
  130. package/dist/core/memory-engine/file-backend.js +21 -31
  131. package/dist/core/memory-engine/frontmatter.d.ts +2 -0
  132. package/dist/core/memory-engine/frontmatter.js +4 -0
  133. package/dist/core/memory-engine/layout.d.ts +114 -20
  134. package/dist/core/memory-engine/layout.js +340 -22
  135. package/dist/core/memory-engine/memory-deployment.d.ts +7 -5
  136. package/dist/core/memory-engine/mount-failed-notice.d.ts +19 -7
  137. package/dist/core/memory-engine/mount-failed-notice.js +43 -10
  138. package/dist/core/memory-engine/sync-client.js +4 -5
  139. package/dist/core/model-fallbacks.d.ts +5 -1
  140. package/dist/core/model-fallbacks.js +3 -3
  141. package/dist/core/model-receipt.d.ts +2 -1
  142. package/dist/core/model-receipt.js +12 -1
  143. package/dist/core/mods/kernel/dispatch.d.ts +2 -2
  144. package/dist/core/mods/kernel/dispatch.js +14 -6
  145. package/dist/core/mods/kernel/events.d.ts +8 -5
  146. package/dist/core/mods/kernel/events.js +2 -2
  147. package/dist/core/mods/kernel/index.d.ts +1 -1
  148. package/dist/core/mods/kernel/registration.d.ts +9 -0
  149. package/dist/core/mods/package.js +1 -1
  150. package/dist/core/mods/session-append.d.ts +4 -2
  151. package/dist/core/mods/session-append.js +3 -0
  152. package/dist/core/mods/stations.d.ts +7 -11
  153. package/dist/core/mods/stations.js +4 -7
  154. package/dist/core/mods/tool-call.d.ts +10 -8
  155. package/dist/core/mods/tool-call.js +15 -18
  156. package/dist/core/mounted-mcp.d.ts +0 -4
  157. package/dist/core/mounted-mcp.js +1 -1
  158. package/dist/core/park-noun.d.ts +24 -0
  159. package/dist/core/park-noun.js +21 -0
  160. package/dist/core/park-resumability.d.ts +60 -0
  161. package/dist/core/park-resumability.js +30 -0
  162. package/dist/core/permission-rule-provider.d.ts +24 -2
  163. package/dist/core/permission-rule-provider.js +11 -8
  164. package/dist/core/permission-rule-store.d.ts +8 -1
  165. package/dist/core/permission-rule-store.js +2 -3
  166. package/dist/core/permission-rules.d.ts +2 -1
  167. package/dist/core/permission-rules.js +8 -4
  168. package/dist/core/persisted-rule-arms.d.ts +3 -0
  169. package/dist/core/persisted-rule-arms.js +2 -1
  170. package/dist/core/present-plan-tool.d.ts +47 -3
  171. package/dist/core/present-plan-tool.js +62 -4
  172. package/dist/core/principal-name.d.ts +1 -1
  173. package/dist/core/principal-name.js +5 -5
  174. package/dist/core/process-identity.js +10 -5
  175. package/dist/core/protocol-http-auth.d.ts +30 -9
  176. package/dist/core/protocol-http-auth.js +113 -59
  177. package/dist/core/read-only-shell.js +9 -5
  178. package/dist/core/redaction-marks.d.ts +4 -26
  179. package/dist/core/redaction-marks.js +9 -21
  180. package/dist/core/remote-env.d.ts +43 -16
  181. package/dist/core/remote-env.js +1 -1
  182. package/dist/core/request-copy-projection.d.ts +1 -1
  183. package/dist/core/request-copy-projection.js +40 -50
  184. package/dist/core/resume-config-judge.js +1 -1
  185. package/dist/core/resume-startup-cause.d.ts +35 -18
  186. package/dist/core/resume-startup-cause.js +13 -10
  187. package/dist/core/retention.d.ts +167 -25
  188. package/dist/core/retention.js +100 -20
  189. package/dist/core/roles.d.ts +6 -0
  190. package/dist/core/roles.js +11 -5
  191. package/dist/core/rule-lane-reads.d.ts +3 -0
  192. package/dist/core/rule-lane-reads.js +5 -1
  193. package/dist/core/rule-store-fault.d.ts +70 -0
  194. package/dist/core/rule-store-fault.js +102 -0
  195. package/dist/core/runner/advertised-writable-dirs.js +16 -31
  196. package/dist/core/runner/announce-once-ledger.d.ts +19 -2
  197. package/dist/core/runner/announce-once-ledger.js +24 -2
  198. package/dist/core/runner/assemble-result.d.ts +6 -0
  199. package/dist/core/runner/assemble-result.js +1 -1
  200. package/dist/core/runner/auto-strip-notice.d.ts +36 -0
  201. package/dist/core/runner/auto-strip-notice.js +59 -0
  202. package/dist/core/runner/branch-window.d.ts +3 -0
  203. package/dist/core/runner/branch-window.js +37 -0
  204. package/dist/core/runner/caller-roster.d.ts +8 -3
  205. package/dist/core/runner/capability-withheld-seat.js +3 -9
  206. package/dist/core/runner/clock-and-limits.d.ts +22 -1
  207. package/dist/core/runner/clock-and-limits.js +30 -0
  208. package/dist/core/runner/contracts.d.ts +58 -35
  209. package/dist/core/runner/credential-refusal-seat.d.ts +2 -0
  210. package/dist/core/runner/credential-refusal-seat.js +47 -0
  211. package/dist/core/runner/cross-boundary-lane.js +6 -4
  212. package/dist/core/runner/decide-continuation.js +1 -1
  213. package/dist/core/runner/file-history-restore.d.ts +53 -2
  214. package/dist/core/runner/file-history-restore.js +29 -10
  215. package/dist/core/runner/forward-sink.d.ts +14 -1
  216. package/dist/core/runner/forward-sink.js +14 -12
  217. package/dist/core/runner/gate-exit.d.ts +8 -7
  218. package/dist/core/runner/gate-exit.js +13 -13
  219. package/dist/core/runner/git-status-frame.js +2 -4
  220. package/dist/core/runner/initial-run-state.js +1 -1
  221. package/dist/core/runner/main-call-account.d.ts +3 -1
  222. package/dist/core/runner/main-call-account.js +5 -3
  223. package/dist/core/runner/mcp-redial.d.ts +2 -5
  224. package/dist/core/runner/mcp-redial.js +2 -2
  225. package/dist/core/runner/nested-memory-content.d.ts +7 -1
  226. package/dist/core/runner/nested-memory-content.js +73 -13
  227. package/dist/core/runner/nested-memory-lane.d.ts +44 -19
  228. package/dist/core/runner/nested-memory-lane.js +152 -76
  229. package/dist/core/runner/park-commit.js +3 -1
  230. package/dist/core/runner/permission-rule-lanes.d.ts +8 -2
  231. package/dist/core/runner/permission-rule-lanes.js +29 -3
  232. package/dist/core/runner/person-path-rows.d.ts +3 -11
  233. package/dist/core/runner/person-path-rows.js +21 -24
  234. package/dist/core/runner/prepare-acquire-reconcile.js +3 -1
  235. package/dist/core/runner/prepare-artifact.d.ts +1 -1
  236. package/dist/core/runner/prepare-artifact.js +20 -14
  237. package/dist/core/runner/prepare-ask-lane.d.ts +9 -6
  238. package/dist/core/runner/prepare-ask-lane.js +6 -5
  239. package/dist/core/runner/prepare-boundary-parks.d.ts +7 -1
  240. package/dist/core/runner/prepare-boundary-parks.js +27 -24
  241. package/dist/core/runner/prepare-caps-and-workflow.d.ts +5 -2
  242. package/dist/core/runner/prepare-caps-and-workflow.js +4 -3
  243. package/dist/core/runner/prepare-config-doors.d.ts +9 -24
  244. package/dist/core/runner/prepare-config-doors.js +58 -41
  245. package/dist/core/runner/prepare-context-lane.d.ts +2 -2
  246. package/dist/core/runner/prepare-context-lane.js +3 -5
  247. package/dist/core/runner/prepare-defer-classify.d.ts +1 -1
  248. package/dist/core/runner/prepare-defer-classify.js +1 -1
  249. package/dist/core/runner/prepare-delegation-surface.d.ts +2 -2
  250. package/dist/core/runner/prepare-delegation-surface.js +3 -2
  251. package/dist/core/runner/prepare-file-history.d.ts +62 -26
  252. package/dist/core/runner/prepare-file-history.js +117 -46
  253. package/dist/core/runner/prepare-gate-stations.d.ts +4 -0
  254. package/dist/core/runner/prepare-gate-stations.js +6 -5
  255. package/dist/core/runner/prepare-hands-readface.d.ts +9 -4
  256. package/dist/core/runner/prepare-hands-readface.js +8 -4
  257. package/dist/core/runner/prepare-inherited-gate.d.ts +11 -4
  258. package/dist/core/runner/prepare-inherited-gate.js +6 -6
  259. package/dist/core/runner/prepare-listings.d.ts +1 -1
  260. package/dist/core/runner/prepare-listings.js +1 -1
  261. package/dist/core/runner/prepare-memory.js +2 -2
  262. package/dist/core/runner/prepare-offload-wrappers.d.ts +1 -1
  263. package/dist/core/runner/prepare-offload-wrappers.js +1 -1
  264. package/dist/core/runner/prepare-park-ask.d.ts +10 -3
  265. package/dist/core/runner/prepare-park-ask.js +7 -9
  266. package/dist/core/runner/prepare-policy-chain.d.ts +18 -9
  267. package/dist/core/runner/prepare-policy-chain.js +18 -13
  268. package/dist/core/runner/prepare-project-context.d.ts +1 -1
  269. package/dist/core/runner/prepare-project-context.js +5 -3
  270. package/dist/core/runner/prepare-prompt-assembly.js +2 -1
  271. package/dist/core/runner/prepare-prompt-inputs.d.ts +2 -2
  272. package/dist/core/runner/prepare-prompt-inputs.js +1 -1
  273. package/dist/core/runner/prepare-protocol-tools.d.ts +4 -5
  274. package/dist/core/runner/prepare-protocol-tools.js +7 -7
  275. package/dist/core/runner/prepare-question-face.d.ts +4 -2
  276. package/dist/core/runner/prepare-run-refs.d.ts +7 -2
  277. package/dist/core/runner/prepare-run-refs.js +8 -7
  278. package/dist/core/runner/prepare-safety-scan.d.ts +4 -3
  279. package/dist/core/runner/prepare-suspend-saga.d.ts +3 -7
  280. package/dist/core/runner/prepare-suspend-saga.js +4 -3
  281. package/dist/core/runner/prepare-task.js +66 -53
  282. package/dist/core/runner/prepare-tool-disclosure-mount.d.ts +3 -2
  283. package/dist/core/runner/prepare-tool-disclosure-mount.js +2 -1
  284. package/dist/core/runner/prepare-turn-wiring.d.ts +3 -1
  285. package/dist/core/runner/prepare-turn-wiring.js +1 -1
  286. package/dist/core/runner/prepare-wiring-manifest.d.ts +9 -4
  287. package/dist/core/runner/prepare-wiring-manifest.js +14 -6
  288. package/dist/core/runner/prepare-workspace-restore.d.ts +4 -4
  289. package/dist/core/runner/prepare-workspace-restore.js +15 -6
  290. package/dist/core/runner/remote-env-retry.d.ts +3 -3
  291. package/dist/core/runner/restore-seat.d.ts +41 -0
  292. package/dist/core/runner/restore-seat.js +38 -0
  293. package/dist/core/runner/resume-admission.js +1 -1
  294. package/dist/core/runner/resume-apply.js +4 -3
  295. package/dist/core/runner/resume-checkpoint-screen.js +2 -1
  296. package/dist/core/runner/resume-internals-and-config.js +2 -1
  297. package/dist/core/runner/resume-preflight.js +2 -1
  298. package/dist/core/runner/rewind-files.js +22 -6
  299. package/dist/core/runner/rule-store-unreadable-notice.d.ts +8 -0
  300. package/dist/core/runner/rule-store-unreadable-notice.js +11 -0
  301. package/dist/core/runner/run-brain-sinks.d.ts +3 -6
  302. package/dist/core/runner/run-brain-sinks.js +6 -6
  303. package/dist/core/runner/run-compaction-machinery.d.ts +2 -2
  304. package/dist/core/runner/run-git-lane.d.ts +2 -0
  305. package/dist/core/runner/run-git-lane.js +2 -1
  306. package/dist/core/runner/run-harness-handlers.js +5 -4
  307. package/dist/core/runner/run-identity-wiring.js +20 -12
  308. package/dist/core/runner/run-leg.js +31 -72
  309. package/dist/core/runner/run-notification-lane.d.ts +3 -0
  310. package/dist/core/runner/run-notification-lane.js +2 -4
  311. package/dist/core/runner/run-reasoning-seat.d.ts +5 -6
  312. package/dist/core/runner/run-reasoning-seat.js +13 -18
  313. package/dist/core/runner/run-settle-and-teardown.js +13 -9
  314. package/dist/core/runner/run-terminal-adoption.js +4 -8
  315. package/dist/core/runner/run-turn-boundary.js +6 -3
  316. package/dist/core/runner/runtask.d.ts +9 -4
  317. package/dist/core/runner/runtask.js +29 -22
  318. package/dist/core/runner/session-rule-policy.d.ts +11 -1
  319. package/dist/core/runner/shell-env-withheld.js +2 -7
  320. package/dist/core/runner/side-call-account.d.ts +5 -6
  321. package/dist/core/runner/side-call-account.js +2 -2
  322. package/dist/core/runner/stream-lifecycle-verbs.d.ts +3 -0
  323. package/dist/core/runner/stream-lifecycle-verbs.js +5 -3
  324. package/dist/core/runner/stream-settle-backstop.js +4 -6
  325. package/dist/core/runner/stream-steer-verb.d.ts +1 -1
  326. package/dist/core/runner/stream-steer-verb.js +4 -4
  327. package/dist/core/runner/sub-agent-deny-lists.d.ts +8 -3
  328. package/dist/core/runner/sub-agent-deny-lists.js +7 -4
  329. package/dist/core/runner/teardown-bounded.d.ts +7 -0
  330. package/dist/core/runner/teardown-bounded.js +7 -0
  331. package/dist/core/runner/terminal-account.js +41 -13
  332. package/dist/core/runner/terminal-projection.d.ts +1 -5
  333. package/dist/core/runner/tool-end-body.d.ts +9 -3
  334. package/dist/core/runner/tool-end-body.js +6 -3
  335. package/dist/core/runner/tool-output-projection.d.ts +13 -4
  336. package/dist/core/runner/tool-output-projection.js +10 -14
  337. package/dist/core/runner/turn-attachments.d.ts +3 -2
  338. package/dist/core/runner/turn-attachments.js +12 -5
  339. package/dist/core/runner-deps.d.ts +6 -6
  340. package/dist/core/runtime-caps.d.ts +2 -1
  341. package/dist/core/secret-env.d.ts +20 -3
  342. package/dist/core/secret-env.js +13 -15
  343. package/dist/core/session-checkout.d.ts +115 -15
  344. package/dist/core/session-checkout.js +435 -136
  345. package/dist/core/session-policy-store.js +21 -3
  346. package/dist/core/session-reconcile.js +1 -0
  347. package/dist/core/session-store.js +2 -0
  348. package/dist/core/session.d.ts +11 -1
  349. package/dist/core/shell-run-candidates.d.ts +1 -0
  350. package/dist/core/shell-run-candidates.js +1 -1
  351. package/dist/core/shutdown-debug.d.ts +6 -5
  352. package/dist/core/shutdown-debug.js +5 -1
  353. package/dist/core/skill-grant.js +4 -1
  354. package/dist/core/skills-directory.js +5 -3
  355. package/dist/core/spec-contract.d.ts +1 -1
  356. package/dist/core/store-contracts/checkpoint-store-contract.js +2 -7
  357. package/dist/core/store-contracts/file-history-store-contract.js +26 -2
  358. package/dist/core/store-contracts/session-deletion-cascade-contract.js +130 -14
  359. package/dist/core/store-contracts/task-list-store-contract.d.ts +2 -1
  360. package/dist/core/store-contracts/task-list-store-contract.js +28 -1
  361. package/dist/core/task-event.d.ts +48 -27
  362. package/dist/core/task-notification.d.ts +15 -9
  363. package/dist/core/task-notification.js +12 -0
  364. package/dist/core/task-registry-agent.d.ts +24 -22
  365. package/dist/core/task-registry-agent.js +65 -46
  366. package/dist/core/task-registry-shared.d.ts +17 -5
  367. package/dist/core/task-registry.d.ts +17 -6
  368. package/dist/core/task-registry.js +6 -1
  369. package/dist/core/task-result.d.ts +71 -25
  370. package/dist/core/task-spec-members.d.ts +0 -1
  371. package/dist/core/task-spec-members.js +1 -1
  372. package/dist/core/task-spec.d.ts +60 -52
  373. package/dist/core/task-stream.d.ts +45 -12
  374. package/dist/core/terminal-cause.d.ts +45 -8
  375. package/dist/core/terminal-cause.js +5 -0
  376. package/dist/core/tool-card-bound.d.ts +32 -0
  377. package/dist/core/tool-card-bound.js +33 -0
  378. package/dist/core/tool-catalog-entries.d.ts +9 -0
  379. package/dist/core/tool-catalog-entries.js +48 -0
  380. package/dist/core/tool-errors.d.ts +4 -3
  381. package/dist/core/tool-face.d.ts +3 -3
  382. package/dist/core/tool-mount-facts.d.ts +3 -2
  383. package/dist/core/tool-mount-facts.js +1 -1
  384. package/dist/core/tool-mount-static.js +7 -5
  385. package/dist/core/tool-policy.d.ts +21 -19
  386. package/dist/core/tool-policy.js +5 -6
  387. package/dist/core/tool-registry.d.ts +3 -1
  388. package/dist/core/tool-registry.js +15 -1
  389. package/dist/core/tool-result-store.d.ts +9 -3
  390. package/dist/core/tool-result-store.js +14 -1
  391. package/dist/core/tool-roster.d.ts +6 -0
  392. package/dist/core/tool-roster.js +18 -0
  393. package/dist/core/tool-spec.d.ts +17 -8
  394. package/dist/core/trace.d.ts +35 -31
  395. package/dist/core/types.d.ts +2 -2
  396. package/dist/core/untrusted-egress.d.ts +19 -7
  397. package/dist/core/untrusted-egress.js +26 -7
  398. package/dist/core/untrusted-text.d.ts +6 -18
  399. package/dist/core/untrusted-text.js +11 -4
  400. package/dist/core/user-attachment.d.ts +9 -6
  401. package/dist/core/user-attachment.js +12 -10
  402. package/dist/core/user-row-origin.d.ts +44 -25
  403. package/dist/core/user-row-origin.js +30 -20
  404. package/dist/core/wiring-manifest.d.ts +26 -7
  405. package/dist/core/wiring-manifest.js +14 -11
  406. package/dist/core/workspace-snapshot.d.ts +3 -1
  407. package/dist/core/workspace-snapshot.js +1 -0
  408. package/dist/engine/execution-env/node-execution-env.d.ts +23 -16
  409. package/dist/engine/execution-env/node-execution-env.js +127 -67
  410. package/dist/engine/harness/agent-harness.d.ts +4 -5
  411. package/dist/engine/harness/agent-harness.js +2 -7
  412. package/dist/engine/harness/types.d.ts +51 -19
  413. package/dist/engine/harness/types.js +28 -1
  414. package/dist/engine/llm/types.d.ts +26 -14
  415. package/dist/engine/llm/types.js +2 -2
  416. package/dist/engine/loop/agent-loop.d.ts +2 -2
  417. package/dist/engine/loop/agent-loop.js +51 -275
  418. package/dist/engine/loop/types.d.ts +0 -18
  419. package/dist/engine/session/import-validate.d.ts +3 -0
  420. package/dist/engine/session/import-validate.js +34 -2
  421. package/dist/engine/session/repo-utils.d.ts +42 -4
  422. package/dist/engine/session/repo-utils.js +33 -5
  423. package/dist/engine/session/session.d.ts +41 -14
  424. package/dist/engine/session/session.js +96 -25
  425. package/dist/index.d.ts +21 -16
  426. package/dist/index.js +16 -10
  427. package/dist/orchestration/run-spec.d.ts +1 -1
  428. package/dist/orchestration/run-workflow-tool.d.ts +12 -9
  429. package/dist/orchestration/run-workflow-tool.js +15 -19
  430. package/dist/orchestration/workflow-governance.js +13 -21
  431. package/dist/orchestration/workflow-observe.d.ts +4 -3
  432. package/dist/orchestration/workflow-primitives.d.ts +1 -1
  433. package/dist/orchestration/workflow-record-artifact.d.ts +14 -0
  434. package/dist/orchestration/workflow-record-artifact.js +32 -0
  435. package/dist/orchestration/workflow-script-store.d.ts +9 -0
  436. package/dist/orchestration/workflow-script-store.js +20 -1
  437. package/dist/orchestration/workflow-types.d.ts +33 -3
  438. package/dist/orchestration/workflow.d.ts +24 -14
  439. package/dist/orchestration/workflow.js +52 -23
  440. package/dist/prompt-assembly/artifact.js +4 -8
  441. package/dist/prompt-assembly/catalog/engine.d.ts +263 -0
  442. package/dist/prompt-assembly/catalog/engine.js +30 -0
  443. package/dist/prompt-assembly/catalog/index.d.ts +1 -1
  444. package/dist/prompt-assembly/catalog/index.js +2 -2
  445. package/dist/prompt-assembly/catalog/locales/zh-Hans/engine.d.ts +1 -1
  446. package/dist/prompt-assembly/catalog/locales/zh-Hans/engine.js +29 -0
  447. package/dist/prompt-assembly/epoch.js +6 -8
  448. package/dist/prompt-assembly/turn-snapshot.js +8 -9
  449. package/dist/stores/file/background-agent-store.js +5 -6
  450. package/dist/stores/file/checkpoint-store.d.ts +0 -4
  451. package/dist/stores/file/checkpoint-store.js +7 -3
  452. package/dist/stores/file/file-history-store.d.ts +8 -0
  453. package/dist/stores/file/file-history-store.js +72 -0
  454. package/dist/stores/file/fs-atomic.js +17 -12
  455. package/dist/stores/file/index.js +11 -5
  456. package/dist/stores/file/mailbox-store.js +13 -4
  457. package/dist/stores/file/permission-rule-store.js +14 -13
  458. package/dist/stores/file/shared-ledger.d.ts +4 -0
  459. package/dist/stores/file/shared-ledger.js +4 -0
  460. package/dist/stores/file/task-list-store.js +12 -3
  461. package/dist/stores/file/workflow-run-store.js +1 -0
  462. package/dist/tools/fs/bash-program-position.d.ts +4 -2
  463. package/dist/tools/fs/bash-program-position.js +1 -1
  464. package/dist/tools/fs/bash-readonly-classifier.js +1 -1
  465. package/dist/tools/fs/bound-open.d.ts +97 -0
  466. package/dist/tools/fs/bound-open.js +103 -0
  467. package/dist/tools/fs/containment-face.d.ts +2 -2
  468. package/dist/tools/fs/fs-pdf.d.ts +7 -1
  469. package/dist/tools/fs/fs-pdf.js +31 -23
  470. package/dist/tools/fs/fs-read.d.ts +24 -17
  471. package/dist/tools/fs/fs-read.js +84 -53
  472. package/dist/tools/fs/fs-shared.d.ts +14 -12
  473. package/dist/tools/fs/fs-shared.js +5 -4
  474. package/dist/tools/fs/fs-write.d.ts +2 -2
  475. package/dist/tools/fs/fs-write.js +20 -12
  476. package/dist/tools/fs/index.d.ts +4 -4
  477. package/dist/tools/fs/index.js +2 -2
  478. package/dist/tools/fs/notebook.d.ts +1 -1
  479. package/dist/tools/fs/pdf.d.ts +12 -3
  480. package/dist/tools/fs/pdf.js +22 -9
  481. package/dist/tools/fs/read-deny-home.d.ts +3 -2
  482. package/dist/tools/fs/read-deny-home.js +8 -11
  483. package/dist/tools/fs/safety.d.ts +3 -2
  484. package/dist/tools/fs/shell-read-check.js +10 -9
  485. package/dist/tools/monitor.d.ts +6 -5
  486. package/dist/tools/task-list.d.ts +16 -6
  487. package/dist/tools/task-list.js +4 -0
  488. package/dist/tools/web.d.ts +9 -1
  489. package/dist/tools/web.js +8 -3
  490. package/dist/tools/worktree.d.ts +7 -5
  491. package/dist/tools/worktree.js +4 -3
  492. package/package.json +4 -3
  493. package/test/export-surface.snapshot.json +93 -7
  494. package/wire-changes/core-stores-sql@7.67.3.json +39 -0
  495. package/wire-changes/core-stores-sql@7.68.0.json +39 -0
  496. package/wire-changes/core@7.67.3.json +65 -0
  497. package/wire-changes/core@7.68.0.json +4257 -0
  498. package/wire-changes/mods-kernel@7.67.3.json +39 -0
  499. package/wire-changes/mods-kernel@7.68.0.json +129 -0
  500. package/wire-changes/primitives@7.67.3.json +39 -0
  501. package/wire-changes/primitives@7.68.0.json +253 -0
  502. package/wire-changes/wiki-gate@7.67.3.json +39 -0
  503. package/wire-changes/wiki-gate@7.68.0.json +39 -0
  504. package/dist/core/runner/credential-origin-seat.d.ts +0 -2
  505. package/dist/core/runner/credential-origin-seat.js +0 -20
package/README.md CHANGED
@@ -40,8 +40,10 @@ const res = await runner.runTask({ objective: "...", model: "main" });
40
40
  behavior of Claude Code's tool contract, continuously verified against live probes.
41
41
  - **Durable checkpoints and human-in-the-loop.** Tasks can suspend on approval gates, budget
42
42
  limits, or explicit checkpoints and resume later — on another process or machine — via a
43
- pluggable `CheckpointStore` (in-memory and file-backed here; a database one is yours). Task statuses are explicit:
44
- `completed | blocked | failed | timeout | suspended | needs_review`.
43
+ pluggable `CheckpointStore` (in-memory and file-backed here; a database one is yours). A task's ending is explicit:
44
+ `terminal.kind` is `completed | failed | blocked | paused`, and a `paused` run carries the token that resumes it.
45
+ The result has no `status` member; the older five-word status (`completed | blocked | failed | suspended | needs_review`)
46
+ is derived on demand, as [02 – Runner and Tasks](docs/sdk/02-runner-and-tasks.md) shows.
45
47
  - **Memory engine.** Scoped long-term memory with a pluggable `MemoryBackend`
46
48
  (file-backed here; a database backend is yours), plus automatic in-context compaction that keeps long runs inside the
47
49
  model's context window without losing the thread.
@@ -60,10 +62,13 @@ const res = await runner.runTask({ objective: "...", model: "main" });
60
62
 
61
63
  ## Quick start (60 seconds)
62
64
 
63
- Requirements: Node ≥ 20 and an OpenAI-compatible gateway (streaming + function calling).
65
+ Requirements: Node ≥ 20.18.1 and an OpenAI-compatible gateway (streaming + function calling).
64
66
 
65
67
  ```bash
68
+ mkdir my-agent && cd my-agent
69
+ npm init -y && npm pkg set type=module # the example below uses top-level await
66
70
  npm install @sema-agent/core
71
+ npm install --save-dev tsx # runs the TypeScript file directly
67
72
  ```
68
73
 
69
74
  ```ts
@@ -74,14 +79,13 @@ const model: Model = {
74
79
  id: "qwen-3.5-35b", name: "Qwen3.5-35B",
75
80
  api: "openai-completions", provider: "vllm",
76
81
  baseUrl: "http://localhost:8000/v1", // your gateway; no trailing /chat/completions
77
- reasoning: true, input: ["text", "image"],
78
- cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
79
82
  contextWindow: 262144, maxTokens: 4096,
80
83
  };
81
84
 
82
85
  // 2) Build a Runner (brain = the external LLM; models = your catalog).
86
+ // The brain gets the same address as the model entry, and the key if your gateway wants one.
83
87
  const runner = new Runner({
84
- brain: createOpenAIBrain(),
88
+ brain: createOpenAIBrain({ baseUrl: model.baseUrl, apiKey: process.env.MODEL_API_KEY }),
85
89
  models: { main: model },
86
90
  });
87
91
 
@@ -89,13 +93,18 @@ const runner = new Runner({
89
93
  const res = await runner.runTask({
90
94
  objective: "Summarize the trade-offs between SSE and WebSockets in three bullet points.",
91
95
  model: "main",
92
- sessionId: "chat-42", // pass the same id to continue a conversation; omit for a fresh one
93
96
  });
94
97
 
95
- console.log(res.status); // "completed" | "blocked" | "failed" | "timeout" | "suspended" | "needs_review"
96
- console.log(res.result); // final assistant text
98
+ console.log(res.terminal.kind); // "completed" | "failed" | "blocked" | "paused"
99
+ console.log(res.result); // final assistant text
97
100
  ```
98
101
 
102
+ Save it as `main.ts` and run `npx tsx main.ts` (export `MODEL_API_KEY` first if your gateway wants a
103
+ key; if you load it with `--env-file=.env` instead, a `MODEL_API_KEY` your shell already has wins over
104
+ the file's). It prints `completed`, then the model's answer; if the first line is anything else, print
105
+ `res.terminal` to see why (a failure carries a `code` and a `message`). This page keeps the example to
106
+ the minimum.
107
+
99
108
  Add tools (`defineTool`, the built-in SQL tool, or task-scoped MCP servers), stream events
100
109
  token-by-token (`runTaskStream`: answer text is `text_delta`; thinking is `reasoning_delta` — the
101
110
  provider-level `thinking_delta` name is not on the task stream, and there is no thinking start / end
package/README.zh-CN.md CHANGED
@@ -38,7 +38,9 @@ const res = await runner.runTask({ objective: "...", model: "main" });
38
38
  并持续用活体探针验证。
39
39
  - **持久化检查点与人在环。**任务可以在审批闸、预算上限或显式检查点处挂起,稍后恢复——
40
40
  甚至在另一个进程或机器上——背后是可插拔的 `CheckpointStore`(内存/文件/Postgres)。
41
- 任务状态语义明确:`completed | blocked | failed | timeout | suspended | needs_review`。
41
+ 任务怎么结束是明确的:`terminal.kind` 取 `completed | failed | blocked | paused` 之一,`paused` 的任务带着续跑它的 token。
42
+ 结果对象上没有 `status` 成员;旧的五词状态(`completed | blocked | failed | suspended | needs_review`)
43
+ 需要时现场派生,做法见 [02 – Runner and Tasks](docs/sdk/02-runner-and-tasks.md)。
42
44
  - **记忆引擎。**带作用域的长期记忆,`MemoryBackend` 可插拔(文件或 Postgres);
43
45
  配合自动压缩,长任务不会撑爆上下文窗口,也不会丢线索。
44
46
  - **多 agent。**子 agent 委派、team 讨论、确定性的 `runWorkflow` 编排(带可恢复日志),
@@ -54,10 +56,13 @@ const res = await runner.runTask({ objective: "...", model: "main" });
54
56
 
55
57
  ## 60 秒上手
56
58
 
57
- 要求:Node ≥ 20,以及一个 OpenAI 兼容网关(流式 + function calling)。
59
+ 要求:Node ≥ 20.18.1,以及一个 OpenAI 兼容网关(流式 + function calling)。
58
60
 
59
61
  ```bash
62
+ mkdir my-agent && cd my-agent
63
+ npm init -y && npm pkg set type=module # 下面的例子用了顶层 await
60
64
  npm install @sema-agent/core
65
+ npm install --save-dev tsx # 直接运行 TypeScript 文件
61
66
  ```
62
67
 
63
68
  ```ts
@@ -68,14 +73,13 @@ const model: Model = {
68
73
  id: "qwen-3.5-35b", name: "Qwen3.5-35B",
69
74
  api: "openai-completions", provider: "vllm",
70
75
  baseUrl: "http://localhost:8000/v1", // 你的网关,结尾不带 /chat/completions
71
- reasoning: true, input: ["text", "image"],
72
- cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
73
76
  contextWindow: 262144, maxTokens: 4096,
74
77
  };
75
78
 
76
79
  // 2) 建 Runner(brain = 外部 LLM;models = 你的模型目录)
80
+ // brain 要拿到与模型条目相同的地址;网关要钥匙的话,钥匙也交给 brain
77
81
  const runner = new Runner({
78
- brain: createOpenAIBrain(),
82
+ brain: createOpenAIBrain({ baseUrl: model.baseUrl, apiKey: process.env.MODEL_API_KEY }),
79
83
  models: { main: model },
80
84
  });
81
85
 
@@ -83,13 +87,17 @@ const runner = new Runner({
83
87
  const res = await runner.runTask({
84
88
  objective: "用三个要点总结 SSE 与 WebSocket 的取舍。",
85
89
  model: "main",
86
- sessionId: "chat-42", // 传同一个 id 即继续对话;不传则开新会话
87
90
  });
88
91
 
89
- console.log(res.status); // "completed" | "blocked" | "failed" | "timeout" | "suspended" | "needs_review"
90
- console.log(res.result); // 最终回复文本
92
+ console.log(res.terminal.kind); // "completed" | "failed" | "blocked" | "paused"
93
+ console.log(res.result); // 最终回复文本
91
94
  ```
92
95
 
96
+ 存成 `main.ts`,运行 `npx tsx main.ts`(网关要钥匙的话,先导出 `MODEL_API_KEY`;改用 `--env-file=.env`
97
+ 载入时,shell 里已有的同名 `MODEL_API_KEY` 会压过文件里的)。它先打印
98
+ `completed`,再打印模型的回答;第一行若是别的,就打印 `res.terminal` 看原因(失败带着 `code` 与
99
+ `message`)。这里只留最小的例子。
100
+
93
101
  接下来:挂工具(`defineTool`、内置 SQL 工具、任务级 MCP)、逐 token 消费事件流、
94
102
  或把 Runner 暴露成 HTTP + SSE 服务——[SDK 指南](docs/sdk/README.md)按主题分章覆盖,
95
103
  从 [01 – Getting Started](docs/sdk/01-getting-started.md) 读起。
@@ -3,7 +3,7 @@ import type { AgentDefinition } from "../core/types.js";
3
3
  * A definition as the engine receives it — where it is handed to the delegation tool and where a task carries it: its two tool-name
4
4
  * lists replaced by their one copy (the copy every later reader takes instead of the host's container), and its MCP server declarations
5
5
  * by the copy the door that judges `TaskSpec.mcp` makes of them ({@link snapshotAndValidateMcpEntries}) — a declaration that door refuses
6
- * is refused here, by the same code and sentence.
6
+ * is refused here, by the same code and sentence — and its `thinking` is judged by the one tier judge (`judgeThinkingLevel`).
7
7
  */
8
8
  export declare function snapshotDefinitionLists(def: AgentDefinition): AgentDefinition;
9
9
  /**
@@ -1,14 +1,17 @@
1
1
  import { describeRejectedValue } from "../core/tool-search-setting.js";
2
2
  import { snapshotToolNameList } from "../core/tool-name-list.js";
3
3
  import { snapshotAndValidateMcpEntries } from "../core/locked-config.js";
4
+ import { judgeThinkingLevel } from "../brain/reasoning.js";
4
5
  export function snapshotDefinitionLists(def) {
5
6
  const copy = { ...def };
6
7
  if (copy.allowTools !== undefined)
7
8
  copy.allowTools = snapshotToolNameList(copy.allowTools);
8
9
  if (copy.denyTools !== undefined)
9
10
  copy.denyTools = snapshotToolNameList(copy.denyTools);
11
+ const named = typeof copy.name === "string" ? JSON.stringify(copy.name.slice(0, 80)) : "an unnamed definition";
10
12
  if (copy.mcp !== undefined)
11
- copy.mcp = snapshotAndValidateMcpEntries(copy.mcp, `AgentDefinition.mcp of ${typeof copy.name === "string" ? JSON.stringify(copy.name.slice(0, 80)) : "an unnamed definition"}`);
13
+ copy.mcp = snapshotAndValidateMcpEntries(copy.mcp, `AgentDefinition.mcp of ${named}`);
14
+ judgeThinkingLevel(copy.thinking, `AgentDefinition.thinking of ${named}`);
12
15
  return copy;
13
16
  }
14
17
  export function defineAgent(def) {
@@ -184,8 +184,8 @@ export declare function runCascade(runner: RunnerSelfSeat, spec: TaskSpec, confi
184
184
  * spawned it — its frames can arrive inside the next rung's segment.
185
185
  *
186
186
  * FAILURE-ISOLATED, by the same primitive as {@link CascadeConfig.onRung}: engine-invoked through a
187
- * run-scoped safe notifier — a throwing `onActivity` is contained (first failure per site disclosed
188
- * via `console.warn`, later ones counted) and never faults the rung. Uncontained, the fault
187
+ * run-scoped safe notifier — a throwing `onActivity` is contained (first failure per site told as
188
+ * `config.host_sink_failed` on the runner's notice seat, later ones counted) and never faults the rung. Uncontained, the fault
189
189
  * AMPLIFIES: the faulted rung is rejected by the gate, the cascade escalates, and a non-idempotent
190
190
  * tool the rung had ALREADY executed runs AGAIN on the next rung — the MEASURED HAZARD pin holds
191
191
  * containment.
@@ -70,7 +70,7 @@ async function climbLadder(entryName, runner, spec, config, internals, opening)
70
70
  let ceilingCostKnown = true;
71
71
  let ownTokens = 0, ownTurns = 0, ownPrompt = 0, ownCached = 0, ownOutput = 0, ownCostMicro = 0;
72
72
  let ownTotalInput = 0;
73
- let ownCacheWrite = 0, ownCacheWriteLong = 0;
73
+ let ownCacheWrite = 0, ownCacheWriteLong = 0, ownApiDuration = 0;
74
74
  const ownUsageFacts = emptyCumulativeUsageFacts();
75
75
  let nestedTokens = 0, nestedTurns = 0, nestedTasks = 0, nestedCostMicro = 0;
76
76
  let ownLlmRootMicro = 0, ownCompactionMicro = 0;
@@ -87,6 +87,7 @@ async function climbLadder(entryName, runner, spec, config, internals, opening)
87
87
  outputTokens: ownOutput,
88
88
  cacheWriteTokens: ownCacheWrite,
89
89
  cacheWriteTokensLong: ownCacheWriteLong,
90
+ apiDurationMs: ownApiDuration,
90
91
  costMicroUsd: ownCostMicro,
91
92
  anyLegUnpriced: anyRungUnpriced,
92
93
  llmRootMicroUsd: ownLlmRootMicro,
@@ -165,6 +166,7 @@ async function climbLadder(entryName, runner, spec, config, internals, opening)
165
166
  ownOutput += s.outputTokens ?? 0;
166
167
  ownCacheWrite += s.cacheWriteTokens ?? 0;
167
168
  ownCacheWriteLong += s.cacheWriteTokensLong ?? 0;
169
+ ownApiDuration += s.apiDurationMs ?? 0;
168
170
  foldUsageFacts(ownUsageFacts, s);
169
171
  ownCostMicro += s.costMicroUsd ?? 0;
170
172
  if (s.costMicroUsd === undefined)
@@ -36,7 +36,7 @@ export interface CumulativeHumanReviewTotals {
36
36
  }
37
37
  /** The usage sums a leg's stats may publish — each summed over the legs, and published on the cumulative stats exactly when some
38
38
  * leg published it (a leg's 0 is a measured 0 and is kept; a member no leg published stays absent). */
39
- declare const USAGE_SUM_KEYS: readonly ["promptTokens", "totalInputTokens", "cachedTokens", "outputTokens", "cacheWriteTokens", "cacheWriteTokensLong"];
39
+ declare const USAGE_SUM_KEYS: readonly ["promptTokens", "totalInputTokens", "cachedTokens", "outputTokens", "cacheWriteTokens", "cacheWriteTokensLong", "apiDurationMs"];
40
40
  type UsageSumKey = (typeof USAGE_SUM_KEYS)[number];
41
41
  /**
42
42
  * What the legs said about their usage beyond the sums, folded leg by leg ({@link foldUsageFacts}): which sums any leg published,
@@ -76,6 +76,7 @@ export interface CumulativeStatsAccumulator {
76
76
  outputTokens: number;
77
77
  cacheWriteTokens: number;
78
78
  cacheWriteTokensLong: number;
79
+ apiDurationMs: number;
79
80
  /**
80
81
  * Cumulative own LLM cost (micro-USD): a plain `0` when every leg was priced and cost nothing measurable.
81
82
  *
@@ -1,5 +1,5 @@
1
1
  import { cacheHitOperandsOf } from "../core/runner/cache-hit-account.js";
2
- const USAGE_SUM_KEYS = ["promptTokens", "totalInputTokens", "cachedTokens", "outputTokens", "cacheWriteTokens", "cacheWriteTokensLong"];
2
+ const USAGE_SUM_KEYS = ["promptTokens", "totalInputTokens", "cachedTokens", "outputTokens", "cacheWriteTokens", "cacheWriteTokensLong", "apiDurationMs"];
3
3
  export function emptyCumulativeUsageFacts() {
4
4
  return { published: new Set(), usageMissing: false, cacheReadUnreported: false, cacheWriteUnreported: false, cacheHitRateExcludes: new Map(), rateNumeratorShort: false };
5
5
  }
@@ -37,6 +37,7 @@ export function buildCumulativeStats(base, acc) {
37
37
  outputTokens: sum("outputTokens"),
38
38
  cacheWriteTokens: sum("cacheWriteTokens"),
39
39
  cacheWriteTokensLong: sum("cacheWriteTokensLong"),
40
+ apiDurationMs: sum("apiDurationMs"),
40
41
  cacheHitRate: !facts.rateNumeratorShort && operands.totalInputTokens > 0 ? Math.min(1, operands.cachedTokens / operands.totalInputTokens) : undefined,
41
42
  cacheHitRateExcludes: excludes.length > 0 ? excludes : undefined,
42
43
  usageMissing: facts.usageMissing ? true : undefined,
@@ -70,6 +71,7 @@ export function createCumulativeStatsTracker() {
70
71
  outputTokens: 0,
71
72
  cacheWriteTokens: 0,
72
73
  cacheWriteTokensLong: 0,
74
+ apiDurationMs: 0,
73
75
  costMicroUsd: 0,
74
76
  anyLegUnpriced: false,
75
77
  llmRootMicroUsd: 0,
@@ -92,6 +94,7 @@ export function createCumulativeStatsTracker() {
92
94
  acc.outputTokens += s.outputTokens ?? 0;
93
95
  acc.cacheWriteTokens += s.cacheWriteTokens ?? 0;
94
96
  acc.cacheWriteTokensLong += s.cacheWriteTokensLong ?? 0;
97
+ acc.apiDurationMs += s.apiDurationMs ?? 0;
95
98
  foldUsageFacts(acc.usageFacts, s);
96
99
  acc.costMicroUsd += s.costMicroUsd ?? 0;
97
100
  if (s.costMicroUsd === undefined)
@@ -1,5 +1,6 @@
1
1
  import { Type } from "typebox";
2
2
  import type { TaskAccess } from "../core/task-registry.js";
3
+ import { type RetainLedgerSeats } from "./retain-ledger.js";
3
4
  import { type RosterEntry } from "./roster-store.js";
4
5
  import { type PeerDirectory, type PeerPresence, type PeerSessionRecord, type PeerSessionWhere } from "./peer-directory.js";
5
6
  import type { SubagentTranscriptTier } from "../core/wiring-manifest.js";
@@ -39,15 +40,25 @@ export interface ListAgentsToolOptions {
39
40
  type: string;
40
41
  status: string;
41
42
  description?: string;
43
+ toolUseId?: string;
42
44
  }>;
43
45
  getAccessibleTask(id: string, access: TaskAccess): {
44
46
  name?: string;
45
47
  status: string;
48
+ agentType?: string;
46
49
  } | undefined;
47
50
  /** The live background-agent row's state facts ({@link import("../core/task-registry.js").TaskRegistry.agentStateSource}).
48
51
  * Absent on a registry that does not offer it ⇒ agent rows carry no `agentState` and no state columns. */
49
52
  agentStateSource?(id: string, access: TaskAccess): AgentStateSource | undefined;
53
+ /** Who stopped a killed agent — a user's stop is not continued. Absent ⇒ not known (read as not a user's stop). */
54
+ getStopAttribution?(id: string): string | undefined;
55
+ /** A probe confirming the agent's durable record exists (absent ⇒ the row has no durable lane). */
56
+ durableAgentRowProbe?(id: string): (() => Promise<boolean>) | undefined;
50
57
  };
58
+ /** The retain ledgers the SendMessage beside this tool continues agents from, read at each call (a session's ledger is
59
+ * minted by its first session-scoped spawn). With the registry facts above they answer each stopped agent's
60
+ * {@link AgentContinuation}; absent ⇒ no retained continuation is known to this listing. */
61
+ retainLedgers?: () => RetainLedgerSeats;
51
62
  access?: TaskAccess;
52
63
  /** design/147 S3a parity — a delegated child's TRUSTED parent view (owner = the parent's task id,
53
64
  * sessionId = the parent's session), so the siblings SendMessage can reach by name are listed too.
@@ -105,7 +116,26 @@ export interface ListAgentsRow {
105
116
  * render too); {@link state} is this status word through the lane table. Absent on peer rows and on a
106
117
  * roster row with no live row. */
107
118
  agentState?: AgentState;
119
+ /** Agent lanes, a stopped agent (`finished` / `failed` / `killed`) with a live row: whether, and until when, SendMessage
120
+ * can continue it. Absent on a live or parked agent (a message reaches it as it is) and on rows with no live row. */
121
+ continuation?: AgentContinuation;
108
122
  }
123
+ /**
124
+ * How long SendMessage can continue a stopped agent — the continuation ladder's own answer
125
+ * ({@link resumabilityClaim} over {@link liveRetainEntryOf}), with the retention window as a fact:
126
+ * · `retained` — this engine process holds its conversation until `until` (epoch ms: the retain entry's last settle plus its
127
+ * window, {@link import("./retain-ledger.js").SubagentRetainLedger.continuableUntil}); past it the entry is evicted;
128
+ * · `durable` — no retained conversation, but its durable record revives it by name (no deadline this engine sets);
129
+ * · `none` — SendMessage answers with a refusal (stopped by the user, resume budget spent, nothing retained or recorded).
130
+ */
131
+ export type AgentContinuation = {
132
+ readonly by: "retained";
133
+ readonly until: number;
134
+ } | {
135
+ readonly by: "durable";
136
+ } | {
137
+ readonly by: "none";
138
+ };
109
139
  export declare function createListAgentsTool(opts: ListAgentsToolOptions): import("../core/types.js").AgentTool<Type.TObject<{
110
140
  includeAll: Type.TOptional<Type.TBoolean>;
111
141
  }>, unknown>;
@@ -1,5 +1,6 @@
1
1
  import { Type } from "typebox";
2
2
  import { defineTool } from "../core/tools.js";
3
+ import { SUBAGENT_RESUME_CAP, liveRetainEntryOf, resumabilityClaim } from "./retain-ledger.js";
3
4
  import { inlineUntrusted } from "../core/untrusted-text.js";
4
5
  import { formatPeerNameRef } from "./cross-session-ref.js";
5
6
  import { entryAccessible } from "./roster-store.js";
@@ -25,6 +26,12 @@ export function cwdTail(cwd) {
25
26
  const parts = cwd.split(/[\\/]+/).filter((p) => p !== "");
26
27
  return parts.slice(-2).join("/");
27
28
  }
29
+ const FORK_AGENT_TYPE = "fork";
30
+ function continuationClause(c, now) {
31
+ if (c.by === "retained")
32
+ return `continuable for ${formatAgo(c.until - now)}`;
33
+ return c.by === "durable" ? "continuable (durable record)" : "not continuable";
34
+ }
28
35
  const AGENT_ROW_STATE = {
29
36
  pending: "running",
30
37
  running: "running",
@@ -70,7 +77,7 @@ export function createListAgentsTool(opts) {
70
77
  `pass includeAll: true to also list stale and offline ones. A peer that is offline or unlisted still accepts messages — they are parked ` +
71
78
  `durably in its session box and delivered when it next runs. `
72
79
  : `Peer sessions of this engine are not addressable on this mount (no session directory). `) +
73
- `Background agents you spawned are listed with their task_id, their status, when they last did anything, and — for one that is parked — what its park waits on (a person's approval, or a yield that continues when its owner runs again), the card id, state and deadline. ` +
80
+ `Background agents you spawned are listed with their task_id, their status, when they last did anything, and — for one that is parked — what its park waits on (a person's approval, or a yield that continues when its owner runs again), the card id, state and deadline; for one that stopped, whether SendMessage can still continue it and for how long. ` +
74
81
  `A ref is only valid against the listing (or disambiguation error) you read it from — do not invent one.`,
75
82
  parameters: Type.Object({
76
83
  includeAll: Type.Optional(Type.Boolean({ description: "Also list stale (no activity within the freshness window) and offline peer sessions. Default false." })),
@@ -115,6 +122,37 @@ export function createListAgentsTool(opts) {
115
122
  const src = opts.registry?.agentStateSource?.(id, view);
116
123
  return src === undefined ? undefined : readAgentState(src, opts.checkpointSeat, opts.now?.() ?? Date.now());
117
124
  };
125
+ const tier = opts.continuationTier ?? "none";
126
+ const retainSeats = opts.retainLedgers?.();
127
+ const continuationOf = async (id, status, toolUseId, agentType) => {
128
+ if (status !== "completed" && status !== "failed" && status !== "killed")
129
+ return undefined;
130
+ const live = toolUseId !== undefined && retainSeats !== undefined ? liveRetainEntryOf(retainSeats, toolUseId) : undefined;
131
+ const durableRungServes = agentType !== FORK_AGENT_TYPE;
132
+ let durableRow = false;
133
+ if (live === undefined && durableRungServes && tier !== "none") {
134
+ try {
135
+ durableRow = (await opts.registry?.durableAgentRowProbe?.(id)?.()) === true;
136
+ }
137
+ catch {
138
+ }
139
+ }
140
+ const stoppedBy = status === "killed" ? opts.registry?.getStopAttribution?.(id) : undefined;
141
+ const claim = resumabilityClaim({
142
+ status,
143
+ ...(stoppedBy !== undefined ? { stoppedBy } : {}),
144
+ liveRetainPresent: live !== undefined,
145
+ liveRetainHasBudget: live !== undefined && live.entry.resumeCount < SUBAGENT_RESUME_CAP,
146
+ durableRow,
147
+ durableRungServes,
148
+ });
149
+ if (!claim)
150
+ return { by: "none" };
151
+ if (live === undefined)
152
+ return { by: "durable" };
153
+ const until = live.ledger.continuableUntil(live.entry);
154
+ return until > now ? { by: "retained", until } : { by: "none" };
155
+ };
118
156
  const views = [opts.access, opts.parentAccess].filter((a) => a !== undefined);
119
157
  const seenIds = new Set();
120
158
  if (opts.registry !== undefined) {
@@ -128,12 +166,14 @@ export function createListAgentsTool(opts) {
128
166
  const full = opts.registry.getAccessibleTask(t.task_id, view);
129
167
  const stateRead = agentStateOf(t.task_id, view);
130
168
  const agentState = stateRead instanceof Promise ? await stateRead : stateRead;
169
+ const continuation = await continuationOf(t.task_id, agentState?.status ?? t.status, t.toolUseId, full?.agentType);
131
170
  rows.push({
132
171
  kind: "background_agent",
133
172
  name: full?.name ?? t.description ?? t.task_id,
134
173
  address: t.task_id,
135
174
  state: agentRowState(agentState?.status ?? t.status),
136
175
  ...(agentState !== undefined ? { agentState } : {}),
176
+ ...(continuation !== undefined ? { continuation } : {}),
137
177
  });
138
178
  }
139
179
  }
@@ -148,19 +188,20 @@ export function createListAgentsTool(opts) {
148
188
  const live = opts.registry?.getAccessibleTask(e.agentId, view);
149
189
  const stateRead = live === undefined ? undefined : agentStateOf(e.agentId, view);
150
190
  const agentState = stateRead instanceof Promise ? await stateRead : stateRead;
191
+ const continuation = live === undefined ? undefined : await continuationOf(e.agentId, agentState?.status ?? live.status, e.toolUseId, live.agentType);
151
192
  rows.push({
152
193
  kind: "roster",
153
194
  name: e.name,
154
195
  address: e.agentId,
155
196
  state: live === undefined ? "unknown" : agentRowState(agentState?.status ?? live.status),
156
197
  ...(agentState !== undefined ? { agentState } : {}),
198
+ ...(continuation !== undefined ? { continuation } : {}),
157
199
  });
158
200
  }
159
201
  }
160
202
  catch {
161
203
  }
162
204
  }
163
- const tier = opts.continuationTier ?? "none";
164
205
  const rosterLabel = tier === "full" ? "agent (durable record)" : tier === "rows" ? "agent (record kept; conversation not kept across restarts)" : "agent (recorded name)";
165
206
  const finishedReach = tier === "full"
166
207
  ? "while its session is retained or a durable record exists"
@@ -172,7 +213,8 @@ export function createListAgentsTool(opts) {
172
213
  const age = r.kind !== "peer_session" ? undefined : r.lastActiveAt !== undefined ? `active ${formatAgo(now - r.lastActiveAt)} ago` : r.offlineAt !== undefined ? `offline ${formatAgo(now - r.offlineAt)} ago` : "offline";
173
214
  const activity = r.agentState !== undefined ? agentActivityClause(r.agentState) : undefined;
174
215
  const park = r.agentState?.park !== undefined ? agentParkClause(r.agentState.park, r.agentState.readAt) : undefined;
175
- const cols = [label, r.state, age, activity, park, r.cwd !== undefined ? inlineUntrusted(r.cwd, 64) : undefined, r.presence !== undefined ? renderPresence(r.presence) : undefined, r.kind === "peer_session" ? `peer session ${PEER_SESSION_WHERE_LABELS[r.where]}` : r.kind === "roster" ? rosterLabel : "agent", r.address];
216
+ const continuation = r.continuation !== undefined ? continuationClause(r.continuation, now) : undefined;
217
+ const cols = [label, r.state, age, activity, park, continuation, r.cwd !== undefined ? inlineUntrusted(r.cwd, 64) : undefined, r.presence !== undefined ? renderPresence(r.presence) : undefined, r.kind === "peer_session" ? `peer session ${PEER_SESSION_WHERE_LABELS[r.where]}` : r.kind === "roster" ? rosterLabel : "agent", r.address];
176
218
  return cols.filter((c) => c !== undefined).join(" · ");
177
219
  });
178
220
  const finishedCount = rows.filter((r) => r.state === "finished").length;
@@ -55,8 +55,8 @@ export declare function __resetPeerLaneRangeAnnouncements(): void;
55
55
  * a value outside the legal window, and a value that is not a finite number at all (a string off an
56
56
  * untyped host's JSON wiring, `NaN`, `Infinity`). Two bad fields in one call are two notices — the
57
57
  * operator has two things to fix and folding them into one line would hide the second. `onNotice` is
58
- * the deployment's sink; absent, the announcement still reaches `console.warn` through the shared
59
- * delivery throat (an unwired host is not a silent one).
58
+ * the deployment's sink; absent, the announcement still reaches the process's default seat, else one process line,
59
+ * through the shared delivery throat (an unwired host is not a silent one).
60
60
  */
61
61
  export declare function resolvePeerLaneConfig(overrides?: Partial<PeerLaneConfig>, onNotice?: (notice: EngineNotice) => void): PeerLaneConfig;
62
62
  /** Hop-chain carrier sliding window: a chain keeps its most recent entries (upstream `Xbr`=32).
@@ -391,6 +391,8 @@ export declare function mountListAgents(args: {
391
391
  }>;
392
392
  /** The read faces' store seats, handed to the tool unchanged (see {@link ListAgentsReadSeats}). */
393
393
  readSeats?: ListAgentsReadSeats;
394
+ /** The retain ledgers of the SendMessage beside it (see the tool option), read at each call. */
395
+ retainLedgers?: NonNullable<Parameters<typeof createListAgentsTool>[0]["retainLedgers"]>;
394
396
  }): ReturnType<typeof createListAgentsTool> | undefined;
395
397
  type ListAgentsToolRegistry = NonNullable<Parameters<typeof createListAgentsTool>[0]["registry"]>;
396
398
  /** The harness surface the binding needs (structural — the machine itself never sees the harness). */
@@ -1086,6 +1086,7 @@ export function mountListAgents(args) {
1086
1086
  ...(args.parentTaskId !== undefined ? { parentAccess: { owner: args.parentTaskId, scope: args.scope, ...(args.parentSessionId !== undefined ? { sessionId: args.parentSessionId } : {}) } } : {}),
1087
1087
  ...(args.roster !== undefined ? { roster: args.roster } : {}),
1088
1088
  ...(args.continuationTier !== undefined ? { continuationTier: args.continuationTier } : {}),
1089
+ ...(args.retainLedgers !== undefined ? { retainLedgers: args.retainLedgers } : {}),
1089
1090
  ...(args.readSeats ?? {}),
1090
1091
  });
1091
1092
  }
@@ -103,7 +103,7 @@ export async function runRepairLoop(runner, implSpec, config) {
103
103
  const attemptIntakes = [];
104
104
  let lastOracle;
105
105
  let ownTokens = 0, ownTurns = 0, ownPrompt = 0, ownTotalInput = 0, ownCached = 0, ownOutput = 0;
106
- let ownCacheWrite = 0, ownCacheWriteLong = 0, ownCostMicro = 0;
106
+ let ownCacheWrite = 0, ownCacheWriteLong = 0, ownApiDuration = 0, ownCostMicro = 0;
107
107
  const ownUsageFacts = emptyCumulativeUsageFacts();
108
108
  let ownLlmRootMicro = 0, ownCompactionMicro = 0;
109
109
  let ownSideCallMicro;
@@ -121,6 +121,7 @@ export async function runRepairLoop(runner, implSpec, config) {
121
121
  ownOutput += s.outputTokens ?? 0;
122
122
  ownCacheWrite += s.cacheWriteTokens ?? 0;
123
123
  ownCacheWriteLong += s.cacheWriteTokensLong ?? 0;
124
+ ownApiDuration += s.apiDurationMs ?? 0;
124
125
  foldUsageFacts(ownUsageFacts, s);
125
126
  ownCostMicro += s.costMicroUsd ?? 0;
126
127
  if (s.costMicroUsd === undefined)
@@ -153,6 +154,7 @@ export async function runRepairLoop(runner, implSpec, config) {
153
154
  outputTokens: ownOutput,
154
155
  cacheWriteTokens: ownCacheWrite,
155
156
  cacheWriteTokensLong: ownCacheWriteLong,
157
+ apiDurationMs: ownApiDuration,
156
158
  costMicroUsd: ownCostMicro,
157
159
  anyLegUnpriced: anyAttemptUnpriced,
158
160
  llmRootMicroUsd: ownLlmRootMicro,
@@ -3,6 +3,62 @@ import type { TaskSpec } from "../core/types.js";
3
3
  import type { PeerDeclarationHold, PeerDeclarations } from "../core/peer-seat.js";
4
4
  /** design/122 D2 — per-child resume cap (default 8): a child can be revived at most this many times. */
5
5
  export declare const SUBAGENT_RESUME_CAP = 8;
6
+ /**
7
+ * Residual lane E — THE resumability claim, derived from the REVIVAL LADDER's own preconditions.
8
+ *
9
+ * `resumable` answers "what will the next SendMessage do with this child?", so the flat
10
+ * `status !== "killed"` it used to be was not a narrower answer, it was a different question. Only a
11
+ * USER stop is a hard refusal on that ladder; a parent teardown, a reap or a host death is exactly what
12
+ * the durable revival lane exists to recover from, and a named row with a durable record is revived
13
+ * through it whatever ended the run. A frame that says `false` there sends the parent to relaunch a
14
+ * child it could have continued — with the child's whole transcript still sitting in the store.
15
+ *
16
+ * The two lanes it reads are the two the ladder walks, in the ladder's own order:
17
+ * · the LIVE retain entry — a continuation in this process. A live entry WINS the ladder (retain holds
18
+ * the committed spawn snapshot and the cheaper same-process resume, so the durable lane is not even
19
+ * attempted while one exists), which cuts both ways: its refusals are final for the row, and an entry
20
+ * that has spent its per-child resume budget answers `false` with nothing behind it — however good
21
+ * the durable row looks. Whether a kill leaves an entry behind is the PRODUCER's fact, not this
22
+ * predicate's: the spawn cycle evicts on a kill, the resume cycle settles instead, so each passes
23
+ * what its own lane actually did rather than assuming a shared rule (they do not share one).
24
+ * · the DURABLE row — tier-3 lazy revival, reached only with NO live entry. It speaks only for NAMED
25
+ * rows (an anonymous one falls through to the pre-revival honest texts) and needs a confirmed
26
+ * record, not merely an armed lane.
27
+ *
28
+ * Its readers: the terminal frames of both background lanes (the producer — it claims nothing about the
29
+ * RECIPIENT side of the ladder, whether the parent's SendMessage mount was wired with a mailbox and a spawn
30
+ * face, so `durableRow` is the row-side fact alone), and the ListAgents listing (which is mounted beside that
31
+ * SendMessage and passes `durableRow` only when the mount's tier can revive).
32
+ */
33
+ export declare function resumabilityClaim(f: {
34
+ status: "completed" | "failed" | "killed";
35
+ stoppedBy?: string;
36
+ /** A live retain entry SURVIVES this settle — it OWNS the ladder while it does, so its own answer is
37
+ * the whole answer. The caller decides this per lane (a killed spawn cycle evicts; a killed resume
38
+ * cycle settles the entry and keeps it). */
39
+ liveRetainPresent: boolean;
40
+ /** …and it still has resume budget (below {@link SUBAGENT_RESUME_CAP}). */
41
+ liveRetainHasBudget: boolean;
42
+ durableRow: boolean;
43
+ /** The durable rung serves this row. SendMessage's tier-3 rung serves any row but a fork's (by handle, named or not);
44
+ * the terminal-frame producers answer for named rows only — a narrower claim than the rung, kept as it was. */
45
+ durableRungServes: boolean;
46
+ }): boolean;
47
+ /** The retain ledgers a continuation of an agent looks in: the session's (a session-scoped child outlives the run that
48
+ * spawned it), the run's own, and — for a delegated child reaching a sibling — the parent run's. */
49
+ export interface RetainLedgerSeats {
50
+ readonly session?: SubagentRetainLedger | undefined;
51
+ readonly run?: SubagentRetainLedger | undefined;
52
+ readonly sibling?: SubagentRetainLedger | undefined;
53
+ }
54
+ /** The live retain entry of one spawn (keyed by the spawn's tool-call id), read in the continuation ladder's order —
55
+ * session, run, sibling — with the ledger that holds it. The first ledger that KNOWS the spawn decides, a live entry or
56
+ * an eviction's tombstone alike: the ladder resumes through that ledger, so a tombstone ahead of a later ledger's entry
57
+ * answers "none live" here too. The one read SendMessage's ladder and the agent listing share. */
58
+ export declare function liveRetainEntryOf(seats: RetainLedgerSeats, toolUseId: string): {
59
+ ledger: SubagentRetainLedger;
60
+ entry: SubagentRetainEntry;
61
+ } | undefined;
6
62
  /** The one read of a seat's `holdDeclarations` — both retention registrations take their hold here. The member is required, so a typed host
7
63
  * is stopped by the compiler; a seat built by hand without it (untyped, cast) is refused by name, where the bare call was a TypeError
8
64
  * from the middle of a delegation. */
@@ -50,13 +106,6 @@ export interface SubagentRetainEntry {
50
106
  /** Last settle timestamp (epoch ms) — the retain-TTL base. */
51
107
  settledAt: number;
52
108
  resumeCount: number;
53
- /** design/144 §1.1 — the child's STOP-CYCLE number (207-equivalent per-stop notification identity).
54
- * Minted 1 at registration (the spawn run's settle notifies cycle 1); every resume that actually
55
- * LAUNCHES bumps it, so the resumed run's settle notifies 2, 3, … The background_agent notification
56
- * producers ride it as `TaskNotificationPayload.seq`, which uniquifies the `task_id:status[:seq]`
57
- * dedup key per stop cycle — without it a stop→wake→stop chain's second `completed` frame collided
58
- * with the first and was silently swallowed by the SystemInjectionQueue/inbox/shell dedup layers. */
59
- cycleSeq: number;
60
109
  /** design/144 §1.2 (child gate) — the PARKED completion notification of this child's spawn settle:
61
110
  * present while a `completed` frame sits deferred behind the child's still-running background tasks
62
111
  * (owner key = childSessionId). `seq` is the parked frame's stop-cycle number (park does not change
@@ -163,6 +212,10 @@ export declare class SubagentRetainLedger {
163
212
  private tombstone;
164
213
  /** fix-C5: an entry's own retain window when it carries one, the ledger default otherwise. */
165
214
  private effectiveTtlMs;
215
+ /** The instant (epoch ms) a settled, idle entry stops being continuable: its last settle plus its retain window. The one
216
+ * expiry fact — both reapers (the lazy sweep, the per-entry timer) evict past it, and a listing states the time left
217
+ * until it. While the entry runs it does not expire (its next settle moves this instant). */
218
+ continuableUntil(e: SubagentRetainEntry): number;
166
219
  get disposed(): boolean;
167
220
  get size(): number;
168
221
  get(parentToolCallId: string): SubagentRetainEntry | undefined;
@@ -179,7 +232,7 @@ export declare class SubagentRetainLedger {
179
232
  * evicted (unpin+release); when every slot is still running, the NEW child is NOT retained (tombstoned →
180
233
  * its resume rejects `resume.evicted`) and `undefined` is returned — the caller falls back to throwaway.
181
234
  * The entry's `declarations` hold is the ledger's from this call on: a row not taken releases it here. */
182
- register(parentToolCallId: string, entry: Omit<SubagentRetainEntry, "running" | "settled" | "settledAt" | "resumeCount" | "cycleSeq" | "activeAbort" | "deferredNotify">): SubagentRetainEntry | undefined;
235
+ register(parentToolCallId: string, entry: Omit<SubagentRetainEntry, "running" | "settled" | "settledAt" | "resumeCount" | "activeAbort" | "deferredNotify">): SubagentRetainEntry | undefined;
183
236
  /** Flip a child to settled (idle, resumable) — called when the initial run's stream drains.
184
237
  * fidelity R4-1: also (re-)arms the entry's own TTL timer, so the retain window expires by TIME,
185
238
  * not only at the next ledger touch. */