@sema-agent/core 7.67.3 → 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 (496) hide show
  1. package/CHANGELOG.md +1516 -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/open-responses.js +3 -1
  30. package/dist/brain/openai.js +3 -1
  31. package/dist/brain/reasoning-request.d.ts +73 -19
  32. package/dist/brain/reasoning-request.js +164 -72
  33. package/dist/brain/reasoning-stamp.d.ts +26 -0
  34. package/dist/brain/reasoning-stamp.js +10 -0
  35. package/dist/brain/reasoning.d.ts +95 -162
  36. package/dist/brain/reasoning.js +31 -86
  37. package/dist/brain/route-adjudicator.d.ts +9 -7
  38. package/dist/brain/route-adjudicator.js +12 -10
  39. package/dist/brain/status-sink.d.ts +19 -64
  40. package/dist/brain/status-sink.js +5 -21
  41. package/dist/brain/stream-engine.d.ts +11 -2
  42. package/dist/brain/stream-engine.js +10 -0
  43. package/dist/core/a2a.d.ts +17 -5
  44. package/dist/core/a2a.js +11 -3
  45. package/dist/core/allow-entry.d.ts +35 -15
  46. package/dist/core/allow-entry.js +47 -60
  47. package/dist/core/ask-headline.d.ts +68 -0
  48. package/dist/core/ask-headline.js +23 -0
  49. package/dist/core/ask-origin.d.ts +36 -8
  50. package/dist/core/ask-origin.js +17 -10
  51. package/dist/core/ask-question.d.ts +34 -7
  52. package/dist/core/ask-question.js +10 -1
  53. package/dist/core/ask-unresolvable-notice.d.ts +7 -0
  54. package/dist/core/ask-unresolvable-notice.js +9 -3
  55. package/dist/core/auto-strip.d.ts +53 -0
  56. package/dist/core/auto-strip.js +76 -0
  57. package/dist/core/background-agent-store.d.ts +45 -5
  58. package/dist/core/background-agent-store.js +69 -15
  59. package/dist/core/background-shell.d.ts +2 -2
  60. package/dist/core/caller-text.js +2 -2
  61. package/dist/core/canonical-json.d.ts +13 -0
  62. package/dist/core/canonical-json.js +7 -0
  63. package/dist/core/checkpoint-features.d.ts +66 -20
  64. package/dist/core/checkpoint-features.js +12 -1
  65. package/dist/core/checkpoint-generation.d.ts +1 -1
  66. package/dist/core/checkpoint-queries.d.ts +1 -1
  67. package/dist/core/checkpoint-queries.js +4 -1
  68. package/dist/core/checkpoint-requirements.d.ts +25 -1
  69. package/dist/core/checkpoint-requirements.js +5 -1
  70. package/dist/core/checkpoint-row-verdict.d.ts +1 -0
  71. package/dist/core/checkpoint-row-verdict.js +4 -0
  72. package/dist/core/checkpoint-store.d.ts +66 -38
  73. package/dist/core/checkpoint-store.js +15 -6
  74. package/dist/core/child-clamp-seats.d.ts +6 -0
  75. package/dist/core/child-clamp-seats.js +1 -0
  76. package/dist/core/config-refusal-codes.d.ts +1 -1
  77. package/dist/core/config-refusal-codes.js +1 -0
  78. package/dist/core/delegation-frames.d.ts +9 -12
  79. package/dist/core/delegation-frames.js +9 -8
  80. package/dist/core/engine-capabilities.d.ts +21 -8
  81. package/dist/core/engine-capabilities.js +1 -1
  82. package/dist/core/engine-notice.d.ts +147 -34
  83. package/dist/core/engine-notice.js +27 -16
  84. package/dist/core/engine-storage-backend.d.ts +2 -1
  85. package/dist/core/env-budget.js +3 -3
  86. package/dist/core/env-knob-announce.d.ts +10 -10
  87. package/dist/core/env-knob-announce.js +3 -6
  88. package/dist/core/file-history-store.d.ts +29 -4
  89. package/dist/core/file-history-store.js +13 -0
  90. package/dist/core/frame-settlement.d.ts +2 -1
  91. package/dist/core/gate-fold.js +1 -1
  92. package/dist/core/gate-lanes.js +56 -49
  93. package/dist/core/governance-codes.d.ts +39 -3
  94. package/dist/core/governance-codes.js +61 -3
  95. package/dist/core/hooks.d.ts +29 -11
  96. package/dist/core/hooks.js +5 -2
  97. package/dist/core/human-input-projection.js +3 -3
  98. package/dist/core/input-author.d.ts +17 -3
  99. package/dist/core/input-author.js +15 -3
  100. package/dist/core/leg-identity.d.ts +10 -28
  101. package/dist/core/leg-identity.js +1 -21
  102. package/dist/core/lsp.d.ts +18 -13
  103. package/dist/core/lsp.js +30 -22
  104. package/dist/core/mailbox-store.d.ts +1 -1
  105. package/dist/core/mailbox-store.js +4 -4
  106. package/dist/core/mcp-connection-pool.d.ts +93 -4
  107. package/dist/core/mcp-connection-pool.js +104 -1
  108. package/dist/core/mcp-failure.d.ts +38 -12
  109. package/dist/core/mcp-failure.js +9 -13
  110. package/dist/core/mcp-probe.d.ts +4 -3
  111. package/dist/core/mcp-server-link.d.ts +4 -2
  112. package/dist/core/mcp-server-link.js +4 -5
  113. package/dist/core/mcp-server-spec.d.ts +3 -3
  114. package/dist/core/mcp-server-unavailable-notice.d.ts +22 -8
  115. package/dist/core/mcp-server-unavailable-notice.js +18 -4
  116. package/dist/core/mcp.d.ts +40 -6
  117. package/dist/core/mcp.js +39 -13
  118. package/dist/core/memory-engine/content-origin.js +2 -2
  119. package/dist/core/memory-engine/control-objects.d.ts +2 -4
  120. package/dist/core/memory-engine/control-objects.js +2 -10
  121. package/dist/core/memory-engine/delegation-settlement.js +6 -1
  122. package/dist/core/memory-engine/dual-root.js +3 -0
  123. package/dist/core/memory-engine/engine.d.ts +6 -4
  124. package/dist/core/memory-engine/engine.js +32 -29
  125. package/dist/core/memory-engine/file-backend.d.ts +20 -5
  126. package/dist/core/memory-engine/file-backend.js +21 -31
  127. package/dist/core/memory-engine/frontmatter.d.ts +2 -0
  128. package/dist/core/memory-engine/frontmatter.js +4 -0
  129. package/dist/core/memory-engine/layout.d.ts +114 -20
  130. package/dist/core/memory-engine/layout.js +340 -22
  131. package/dist/core/memory-engine/memory-deployment.d.ts +7 -5
  132. package/dist/core/memory-engine/mount-failed-notice.d.ts +19 -7
  133. package/dist/core/memory-engine/mount-failed-notice.js +43 -10
  134. package/dist/core/memory-engine/sync-client.js +4 -5
  135. package/dist/core/model-fallbacks.d.ts +5 -1
  136. package/dist/core/model-fallbacks.js +3 -3
  137. package/dist/core/model-receipt.d.ts +2 -1
  138. package/dist/core/model-receipt.js +12 -1
  139. package/dist/core/mods/kernel/dispatch.d.ts +2 -2
  140. package/dist/core/mods/kernel/dispatch.js +14 -6
  141. package/dist/core/mods/kernel/events.d.ts +8 -5
  142. package/dist/core/mods/kernel/events.js +2 -2
  143. package/dist/core/mods/kernel/index.d.ts +1 -1
  144. package/dist/core/mods/kernel/registration.d.ts +9 -0
  145. package/dist/core/mods/package.js +1 -1
  146. package/dist/core/mods/session-append.d.ts +4 -2
  147. package/dist/core/mods/session-append.js +3 -0
  148. package/dist/core/mods/stations.d.ts +7 -11
  149. package/dist/core/mods/stations.js +4 -7
  150. package/dist/core/mods/tool-call.d.ts +10 -8
  151. package/dist/core/mods/tool-call.js +15 -18
  152. package/dist/core/mounted-mcp.d.ts +0 -4
  153. package/dist/core/mounted-mcp.js +1 -1
  154. package/dist/core/park-noun.d.ts +24 -0
  155. package/dist/core/park-noun.js +21 -0
  156. package/dist/core/park-resumability.d.ts +60 -0
  157. package/dist/core/park-resumability.js +30 -0
  158. package/dist/core/permission-rule-provider.d.ts +24 -2
  159. package/dist/core/permission-rule-provider.js +11 -8
  160. package/dist/core/permission-rule-store.d.ts +8 -1
  161. package/dist/core/permission-rule-store.js +2 -3
  162. package/dist/core/permission-rules.d.ts +2 -1
  163. package/dist/core/permission-rules.js +8 -4
  164. package/dist/core/persisted-rule-arms.d.ts +3 -0
  165. package/dist/core/persisted-rule-arms.js +2 -1
  166. package/dist/core/present-plan-tool.d.ts +47 -3
  167. package/dist/core/present-plan-tool.js +62 -4
  168. package/dist/core/principal-name.d.ts +1 -1
  169. package/dist/core/principal-name.js +5 -5
  170. package/dist/core/process-identity.js +10 -5
  171. package/dist/core/protocol-http-auth.d.ts +20 -14
  172. package/dist/core/protocol-http-auth.js +70 -50
  173. package/dist/core/read-only-shell.js +9 -5
  174. package/dist/core/redaction-marks.d.ts +4 -26
  175. package/dist/core/redaction-marks.js +9 -21
  176. package/dist/core/remote-env.d.ts +43 -16
  177. package/dist/core/remote-env.js +1 -1
  178. package/dist/core/request-copy-projection.d.ts +1 -1
  179. package/dist/core/request-copy-projection.js +40 -50
  180. package/dist/core/resume-config-judge.js +1 -1
  181. package/dist/core/resume-startup-cause.d.ts +35 -18
  182. package/dist/core/resume-startup-cause.js +13 -10
  183. package/dist/core/retention.d.ts +167 -25
  184. package/dist/core/retention.js +100 -20
  185. package/dist/core/roles.d.ts +6 -0
  186. package/dist/core/roles.js +11 -5
  187. package/dist/core/rule-lane-reads.d.ts +3 -0
  188. package/dist/core/rule-lane-reads.js +5 -1
  189. package/dist/core/rule-store-fault.d.ts +70 -0
  190. package/dist/core/rule-store-fault.js +102 -0
  191. package/dist/core/runner/advertised-writable-dirs.js +16 -31
  192. package/dist/core/runner/announce-once-ledger.d.ts +19 -2
  193. package/dist/core/runner/announce-once-ledger.js +24 -2
  194. package/dist/core/runner/assemble-result.d.ts +6 -0
  195. package/dist/core/runner/assemble-result.js +1 -1
  196. package/dist/core/runner/auto-strip-notice.d.ts +36 -0
  197. package/dist/core/runner/auto-strip-notice.js +59 -0
  198. package/dist/core/runner/branch-window.d.ts +3 -0
  199. package/dist/core/runner/branch-window.js +37 -0
  200. package/dist/core/runner/caller-roster.d.ts +8 -3
  201. package/dist/core/runner/capability-withheld-seat.js +3 -9
  202. package/dist/core/runner/clock-and-limits.d.ts +22 -1
  203. package/dist/core/runner/clock-and-limits.js +30 -0
  204. package/dist/core/runner/contracts.d.ts +58 -35
  205. package/dist/core/runner/credential-refusal-seat.d.ts +2 -0
  206. package/dist/core/runner/credential-refusal-seat.js +47 -0
  207. package/dist/core/runner/cross-boundary-lane.js +6 -4
  208. package/dist/core/runner/decide-continuation.js +1 -1
  209. package/dist/core/runner/file-history-restore.d.ts +53 -2
  210. package/dist/core/runner/file-history-restore.js +29 -10
  211. package/dist/core/runner/forward-sink.d.ts +14 -1
  212. package/dist/core/runner/forward-sink.js +14 -12
  213. package/dist/core/runner/gate-exit.d.ts +8 -7
  214. package/dist/core/runner/gate-exit.js +13 -13
  215. package/dist/core/runner/git-status-frame.js +2 -4
  216. package/dist/core/runner/initial-run-state.js +1 -1
  217. package/dist/core/runner/main-call-account.d.ts +3 -1
  218. package/dist/core/runner/main-call-account.js +5 -3
  219. package/dist/core/runner/mcp-redial.d.ts +2 -5
  220. package/dist/core/runner/mcp-redial.js +2 -2
  221. package/dist/core/runner/nested-memory-content.d.ts +7 -1
  222. package/dist/core/runner/nested-memory-content.js +73 -13
  223. package/dist/core/runner/nested-memory-lane.d.ts +44 -19
  224. package/dist/core/runner/nested-memory-lane.js +152 -76
  225. package/dist/core/runner/park-commit.js +3 -1
  226. package/dist/core/runner/permission-rule-lanes.d.ts +8 -2
  227. package/dist/core/runner/permission-rule-lanes.js +29 -3
  228. package/dist/core/runner/person-path-rows.d.ts +3 -11
  229. package/dist/core/runner/person-path-rows.js +21 -24
  230. package/dist/core/runner/prepare-acquire-reconcile.js +3 -1
  231. package/dist/core/runner/prepare-artifact.d.ts +1 -1
  232. package/dist/core/runner/prepare-artifact.js +20 -14
  233. package/dist/core/runner/prepare-ask-lane.d.ts +9 -6
  234. package/dist/core/runner/prepare-ask-lane.js +6 -5
  235. package/dist/core/runner/prepare-boundary-parks.d.ts +7 -1
  236. package/dist/core/runner/prepare-boundary-parks.js +27 -24
  237. package/dist/core/runner/prepare-caps-and-workflow.d.ts +5 -2
  238. package/dist/core/runner/prepare-caps-and-workflow.js +4 -3
  239. package/dist/core/runner/prepare-config-doors.d.ts +9 -24
  240. package/dist/core/runner/prepare-config-doors.js +58 -41
  241. package/dist/core/runner/prepare-context-lane.d.ts +2 -2
  242. package/dist/core/runner/prepare-context-lane.js +3 -5
  243. package/dist/core/runner/prepare-defer-classify.d.ts +1 -1
  244. package/dist/core/runner/prepare-defer-classify.js +1 -1
  245. package/dist/core/runner/prepare-delegation-surface.d.ts +2 -2
  246. package/dist/core/runner/prepare-delegation-surface.js +3 -2
  247. package/dist/core/runner/prepare-file-history.d.ts +62 -26
  248. package/dist/core/runner/prepare-file-history.js +117 -46
  249. package/dist/core/runner/prepare-gate-stations.d.ts +4 -0
  250. package/dist/core/runner/prepare-gate-stations.js +6 -5
  251. package/dist/core/runner/prepare-hands-readface.d.ts +9 -4
  252. package/dist/core/runner/prepare-hands-readface.js +8 -4
  253. package/dist/core/runner/prepare-inherited-gate.d.ts +11 -4
  254. package/dist/core/runner/prepare-inherited-gate.js +6 -6
  255. package/dist/core/runner/prepare-listings.d.ts +1 -1
  256. package/dist/core/runner/prepare-listings.js +1 -1
  257. package/dist/core/runner/prepare-memory.js +2 -2
  258. package/dist/core/runner/prepare-offload-wrappers.d.ts +1 -1
  259. package/dist/core/runner/prepare-offload-wrappers.js +1 -1
  260. package/dist/core/runner/prepare-park-ask.d.ts +10 -3
  261. package/dist/core/runner/prepare-park-ask.js +7 -9
  262. package/dist/core/runner/prepare-policy-chain.d.ts +18 -9
  263. package/dist/core/runner/prepare-policy-chain.js +18 -13
  264. package/dist/core/runner/prepare-project-context.d.ts +1 -1
  265. package/dist/core/runner/prepare-project-context.js +5 -3
  266. package/dist/core/runner/prepare-prompt-assembly.js +2 -1
  267. package/dist/core/runner/prepare-prompt-inputs.d.ts +2 -2
  268. package/dist/core/runner/prepare-prompt-inputs.js +1 -1
  269. package/dist/core/runner/prepare-protocol-tools.d.ts +4 -5
  270. package/dist/core/runner/prepare-protocol-tools.js +7 -7
  271. package/dist/core/runner/prepare-question-face.d.ts +4 -2
  272. package/dist/core/runner/prepare-run-refs.d.ts +7 -2
  273. package/dist/core/runner/prepare-run-refs.js +8 -7
  274. package/dist/core/runner/prepare-safety-scan.d.ts +4 -3
  275. package/dist/core/runner/prepare-suspend-saga.d.ts +3 -7
  276. package/dist/core/runner/prepare-suspend-saga.js +4 -3
  277. package/dist/core/runner/prepare-task.js +66 -53
  278. package/dist/core/runner/prepare-tool-disclosure-mount.d.ts +3 -2
  279. package/dist/core/runner/prepare-tool-disclosure-mount.js +2 -1
  280. package/dist/core/runner/prepare-turn-wiring.d.ts +3 -1
  281. package/dist/core/runner/prepare-turn-wiring.js +1 -1
  282. package/dist/core/runner/prepare-wiring-manifest.d.ts +9 -4
  283. package/dist/core/runner/prepare-wiring-manifest.js +14 -6
  284. package/dist/core/runner/prepare-workspace-restore.d.ts +4 -4
  285. package/dist/core/runner/prepare-workspace-restore.js +15 -6
  286. package/dist/core/runner/remote-env-retry.d.ts +3 -3
  287. package/dist/core/runner/restore-seat.d.ts +41 -0
  288. package/dist/core/runner/restore-seat.js +38 -0
  289. package/dist/core/runner/resume-admission.js +1 -1
  290. package/dist/core/runner/resume-apply.js +4 -3
  291. package/dist/core/runner/resume-checkpoint-screen.js +2 -1
  292. package/dist/core/runner/resume-internals-and-config.js +2 -1
  293. package/dist/core/runner/resume-preflight.js +2 -1
  294. package/dist/core/runner/rewind-files.js +22 -6
  295. package/dist/core/runner/rule-store-unreadable-notice.d.ts +8 -0
  296. package/dist/core/runner/rule-store-unreadable-notice.js +11 -0
  297. package/dist/core/runner/run-brain-sinks.d.ts +3 -6
  298. package/dist/core/runner/run-brain-sinks.js +6 -6
  299. package/dist/core/runner/run-compaction-machinery.d.ts +2 -2
  300. package/dist/core/runner/run-git-lane.d.ts +2 -0
  301. package/dist/core/runner/run-git-lane.js +2 -1
  302. package/dist/core/runner/run-harness-handlers.js +5 -4
  303. package/dist/core/runner/run-identity-wiring.js +20 -12
  304. package/dist/core/runner/run-leg.js +31 -72
  305. package/dist/core/runner/run-notification-lane.d.ts +3 -0
  306. package/dist/core/runner/run-notification-lane.js +2 -4
  307. package/dist/core/runner/run-reasoning-seat.d.ts +5 -6
  308. package/dist/core/runner/run-reasoning-seat.js +13 -18
  309. package/dist/core/runner/run-settle-and-teardown.js +13 -9
  310. package/dist/core/runner/run-terminal-adoption.js +4 -8
  311. package/dist/core/runner/run-turn-boundary.js +6 -3
  312. package/dist/core/runner/runtask.d.ts +9 -4
  313. package/dist/core/runner/runtask.js +29 -22
  314. package/dist/core/runner/session-rule-policy.d.ts +11 -1
  315. package/dist/core/runner/shell-env-withheld.js +2 -7
  316. package/dist/core/runner/side-call-account.d.ts +5 -6
  317. package/dist/core/runner/side-call-account.js +2 -2
  318. package/dist/core/runner/stream-lifecycle-verbs.d.ts +3 -0
  319. package/dist/core/runner/stream-lifecycle-verbs.js +5 -3
  320. package/dist/core/runner/stream-settle-backstop.js +4 -6
  321. package/dist/core/runner/stream-steer-verb.d.ts +1 -1
  322. package/dist/core/runner/stream-steer-verb.js +4 -4
  323. package/dist/core/runner/sub-agent-deny-lists.d.ts +8 -3
  324. package/dist/core/runner/sub-agent-deny-lists.js +7 -4
  325. package/dist/core/runner/teardown-bounded.d.ts +7 -0
  326. package/dist/core/runner/teardown-bounded.js +7 -0
  327. package/dist/core/runner/terminal-account.js +41 -13
  328. package/dist/core/runner/terminal-projection.d.ts +1 -5
  329. package/dist/core/runner/tool-end-body.d.ts +9 -3
  330. package/dist/core/runner/tool-end-body.js +6 -3
  331. package/dist/core/runner/tool-output-projection.d.ts +13 -4
  332. package/dist/core/runner/tool-output-projection.js +10 -14
  333. package/dist/core/runner/turn-attachments.d.ts +3 -2
  334. package/dist/core/runner/turn-attachments.js +12 -5
  335. package/dist/core/runner-deps.d.ts +6 -6
  336. package/dist/core/runtime-caps.d.ts +2 -1
  337. package/dist/core/secret-env.d.ts +20 -3
  338. package/dist/core/secret-env.js +13 -15
  339. package/dist/core/session-checkout.d.ts +115 -15
  340. package/dist/core/session-checkout.js +435 -136
  341. package/dist/core/session-policy-store.js +21 -3
  342. package/dist/core/session-reconcile.js +1 -0
  343. package/dist/core/session-store.js +2 -0
  344. package/dist/core/session.d.ts +11 -1
  345. package/dist/core/shell-run-candidates.d.ts +1 -0
  346. package/dist/core/shell-run-candidates.js +1 -1
  347. package/dist/core/shutdown-debug.d.ts +6 -5
  348. package/dist/core/shutdown-debug.js +5 -1
  349. package/dist/core/skill-grant.js +4 -1
  350. package/dist/core/skills-directory.js +5 -3
  351. package/dist/core/spec-contract.d.ts +1 -1
  352. package/dist/core/store-contracts/checkpoint-store-contract.js +2 -7
  353. package/dist/core/store-contracts/file-history-store-contract.js +26 -2
  354. package/dist/core/store-contracts/session-deletion-cascade-contract.js +130 -14
  355. package/dist/core/store-contracts/task-list-store-contract.d.ts +2 -1
  356. package/dist/core/store-contracts/task-list-store-contract.js +28 -1
  357. package/dist/core/task-event.d.ts +48 -27
  358. package/dist/core/task-notification.d.ts +15 -9
  359. package/dist/core/task-notification.js +12 -0
  360. package/dist/core/task-registry-agent.d.ts +24 -22
  361. package/dist/core/task-registry-agent.js +65 -46
  362. package/dist/core/task-registry-shared.d.ts +17 -5
  363. package/dist/core/task-registry.d.ts +17 -6
  364. package/dist/core/task-registry.js +6 -1
  365. package/dist/core/task-result.d.ts +71 -25
  366. package/dist/core/task-spec-members.d.ts +0 -1
  367. package/dist/core/task-spec-members.js +1 -1
  368. package/dist/core/task-spec.d.ts +60 -52
  369. package/dist/core/task-stream.d.ts +45 -12
  370. package/dist/core/terminal-cause.d.ts +45 -8
  371. package/dist/core/terminal-cause.js +5 -0
  372. package/dist/core/tool-card-bound.d.ts +32 -0
  373. package/dist/core/tool-card-bound.js +33 -0
  374. package/dist/core/tool-catalog-entries.d.ts +9 -0
  375. package/dist/core/tool-catalog-entries.js +48 -0
  376. package/dist/core/tool-errors.d.ts +4 -3
  377. package/dist/core/tool-face.d.ts +3 -3
  378. package/dist/core/tool-mount-facts.d.ts +3 -2
  379. package/dist/core/tool-mount-facts.js +1 -1
  380. package/dist/core/tool-mount-static.js +7 -5
  381. package/dist/core/tool-policy.d.ts +21 -19
  382. package/dist/core/tool-policy.js +5 -6
  383. package/dist/core/tool-registry.d.ts +3 -1
  384. package/dist/core/tool-registry.js +15 -1
  385. package/dist/core/tool-result-store.d.ts +9 -3
  386. package/dist/core/tool-result-store.js +14 -1
  387. package/dist/core/tool-roster.d.ts +6 -0
  388. package/dist/core/tool-roster.js +18 -0
  389. package/dist/core/tool-spec.d.ts +17 -8
  390. package/dist/core/trace.d.ts +35 -31
  391. package/dist/core/types.d.ts +2 -2
  392. package/dist/core/untrusted-egress.d.ts +10 -9
  393. package/dist/core/untrusted-egress.js +9 -9
  394. package/dist/core/untrusted-text.d.ts +0 -18
  395. package/dist/core/untrusted-text.js +7 -3
  396. package/dist/core/user-attachment.d.ts +9 -6
  397. package/dist/core/user-attachment.js +12 -10
  398. package/dist/core/user-row-origin.d.ts +44 -25
  399. package/dist/core/user-row-origin.js +30 -20
  400. package/dist/core/wiring-manifest.d.ts +26 -7
  401. package/dist/core/wiring-manifest.js +14 -11
  402. package/dist/core/workspace-snapshot.d.ts +3 -1
  403. package/dist/core/workspace-snapshot.js +1 -0
  404. package/dist/engine/execution-env/node-execution-env.d.ts +23 -16
  405. package/dist/engine/execution-env/node-execution-env.js +127 -67
  406. package/dist/engine/harness/agent-harness.d.ts +4 -5
  407. package/dist/engine/harness/agent-harness.js +2 -7
  408. package/dist/engine/harness/types.d.ts +51 -19
  409. package/dist/engine/harness/types.js +28 -1
  410. package/dist/engine/llm/types.d.ts +26 -14
  411. package/dist/engine/llm/types.js +2 -2
  412. package/dist/engine/loop/agent-loop.d.ts +2 -2
  413. package/dist/engine/loop/agent-loop.js +51 -275
  414. package/dist/engine/loop/types.d.ts +0 -18
  415. package/dist/engine/session/import-validate.d.ts +3 -0
  416. package/dist/engine/session/import-validate.js +34 -2
  417. package/dist/engine/session/repo-utils.d.ts +42 -4
  418. package/dist/engine/session/repo-utils.js +33 -5
  419. package/dist/engine/session/session.d.ts +41 -14
  420. package/dist/engine/session/session.js +96 -25
  421. package/dist/index.d.ts +21 -16
  422. package/dist/index.js +16 -10
  423. package/dist/orchestration/run-spec.d.ts +1 -1
  424. package/dist/orchestration/run-workflow-tool.d.ts +12 -9
  425. package/dist/orchestration/run-workflow-tool.js +15 -19
  426. package/dist/orchestration/workflow-governance.js +13 -21
  427. package/dist/orchestration/workflow-observe.d.ts +4 -3
  428. package/dist/orchestration/workflow-primitives.d.ts +1 -1
  429. package/dist/orchestration/workflow-record-artifact.d.ts +14 -0
  430. package/dist/orchestration/workflow-record-artifact.js +32 -0
  431. package/dist/orchestration/workflow-script-store.d.ts +9 -0
  432. package/dist/orchestration/workflow-script-store.js +20 -1
  433. package/dist/orchestration/workflow-types.d.ts +33 -3
  434. package/dist/orchestration/workflow.d.ts +24 -14
  435. package/dist/orchestration/workflow.js +52 -23
  436. package/dist/prompt-assembly/artifact.js +4 -8
  437. package/dist/prompt-assembly/catalog/engine.d.ts +263 -0
  438. package/dist/prompt-assembly/catalog/engine.js +30 -0
  439. package/dist/prompt-assembly/catalog/index.d.ts +1 -1
  440. package/dist/prompt-assembly/catalog/index.js +2 -2
  441. package/dist/prompt-assembly/catalog/locales/zh-Hans/engine.d.ts +1 -1
  442. package/dist/prompt-assembly/catalog/locales/zh-Hans/engine.js +29 -0
  443. package/dist/prompt-assembly/epoch.js +6 -8
  444. package/dist/prompt-assembly/turn-snapshot.js +8 -9
  445. package/dist/stores/file/background-agent-store.js +5 -6
  446. package/dist/stores/file/checkpoint-store.d.ts +0 -4
  447. package/dist/stores/file/checkpoint-store.js +7 -3
  448. package/dist/stores/file/file-history-store.d.ts +8 -0
  449. package/dist/stores/file/file-history-store.js +72 -0
  450. package/dist/stores/file/fs-atomic.js +17 -12
  451. package/dist/stores/file/index.js +11 -5
  452. package/dist/stores/file/mailbox-store.js +13 -4
  453. package/dist/stores/file/permission-rule-store.js +14 -13
  454. package/dist/stores/file/shared-ledger.d.ts +4 -0
  455. package/dist/stores/file/shared-ledger.js +4 -0
  456. package/dist/stores/file/task-list-store.js +12 -3
  457. package/dist/stores/file/workflow-run-store.js +1 -0
  458. package/dist/tools/fs/bash-program-position.d.ts +4 -2
  459. package/dist/tools/fs/bash-program-position.js +1 -1
  460. package/dist/tools/fs/bash-readonly-classifier.js +1 -1
  461. package/dist/tools/fs/bound-open.d.ts +97 -0
  462. package/dist/tools/fs/bound-open.js +103 -0
  463. package/dist/tools/fs/containment-face.d.ts +2 -2
  464. package/dist/tools/fs/fs-pdf.d.ts +7 -1
  465. package/dist/tools/fs/fs-pdf.js +31 -23
  466. package/dist/tools/fs/fs-read.d.ts +24 -17
  467. package/dist/tools/fs/fs-read.js +84 -53
  468. package/dist/tools/fs/fs-shared.d.ts +14 -12
  469. package/dist/tools/fs/fs-shared.js +5 -4
  470. package/dist/tools/fs/fs-write.d.ts +2 -2
  471. package/dist/tools/fs/fs-write.js +20 -12
  472. package/dist/tools/fs/index.d.ts +4 -4
  473. package/dist/tools/fs/index.js +2 -2
  474. package/dist/tools/fs/notebook.d.ts +1 -1
  475. package/dist/tools/fs/pdf.d.ts +12 -3
  476. package/dist/tools/fs/pdf.js +22 -9
  477. package/dist/tools/fs/read-deny-home.d.ts +3 -2
  478. package/dist/tools/fs/read-deny-home.js +8 -11
  479. package/dist/tools/fs/safety.d.ts +3 -2
  480. package/dist/tools/fs/shell-read-check.js +10 -9
  481. package/dist/tools/monitor.d.ts +6 -5
  482. package/dist/tools/task-list.d.ts +16 -6
  483. package/dist/tools/task-list.js +4 -0
  484. package/dist/tools/web.d.ts +9 -1
  485. package/dist/tools/web.js +8 -3
  486. package/dist/tools/worktree.d.ts +7 -5
  487. package/dist/tools/worktree.js +4 -3
  488. package/package.json +4 -3
  489. package/test/export-surface.snapshot.json +93 -7
  490. package/wire-changes/core-stores-sql@7.68.0.json +39 -0
  491. package/wire-changes/core@7.68.0.json +4257 -0
  492. package/wire-changes/mods-kernel@7.68.0.json +129 -0
  493. package/wire-changes/primitives@7.68.0.json +253 -0
  494. package/wire-changes/wiki-gate@7.68.0.json +39 -0
  495. package/dist/core/runner/credential-origin-seat.d.ts +0 -2
  496. package/dist/core/runner/credential-origin-seat.js +0 -20
@@ -2,15 +2,19 @@ import { randomBytes } from "node:crypto";
2
2
  import { describeRejectedValue } from "./tool-search-setting.js";
3
3
  import { receiveRetentionPolicy } from "./retention-policy.js";
4
4
  import { commitCompletionIdIfEmpty, completionIdCandidate, mintCompletionId } from "./completion-id.js";
5
- import { assertDelegationRoot, BACKGROUND_AGENT_REAP_KNOBS, canAccessAgentRecord, delegationRootOf, BackgroundAgentStoreError, clearRevivedRowTerminalPayload, REVIVED_ROW_CLEARED_FIELDS, STALE_RUNNING_REAP_ATTRIBUTION, } from "./background-agent-store.js";
5
+ import { assertDelegationRoot, BACKGROUND_AGENT_REAP_KNOBS, canAccessAgentRecord, delegationRootOf, BackgroundAgentStoreError, clearRevivedRowTerminalPayload, nextCycleSeq, REVIVED_ROW_CLEARED_FIELDS, STALE_RUNNING_REAP_ATTRIBUTION, parkedCardState, } from "./background-agent-store.js";
6
6
  import { shutdownDebug } from "./shutdown-debug.js";
7
7
  import { delimitUntrusted } from "./untrusted-text.js";
8
8
  import { boundedRedactedSummary } from "./untrusted-egress.js";
9
9
  import { clipTaskOutput, assertOwnership, sleepPollStep, alreadyTerminalStopNote, canAccess, isLiveSessionResidentAgent, normalizeAgentName, engineAgentName, chosenAgentName, DURABLE_AGENT_HEARTBEAT_MS, DURABLE_AGENT_HANDLE_RE, BG_AGENT_REAP_STOP_ERROR, activityStamp, isActivityInstant, monotonicNow, stampActivity, } from "./task-registry-shared.js";
10
- import { thrownLabel } from "./thrown-value.js";
10
+ import { codedRefusal, thrownLabel } from "./thrown-value.js";
11
11
  import { readExtensionRequester } from "./extension-requester.js";
12
12
  import { closestName } from "./closest-name.js";
13
13
  import { agentStateSourceOfHandle, agentStateSummary, readAgentState } from "./agent-state.js";
14
+ import { deliverEngineNotice } from "./engine-notice.js";
15
+ function sayDurableRowUnpersisted(kind, handle, line) {
16
+ deliverEngineNotice(undefined, { code: "delegation.durable_row_unpersisted", message: line, detail: { kind, handle } });
17
+ }
14
18
  export function activeDelegationHandlesLane(core, scope, rootSessionId) {
15
19
  return activeDelegationOccupantsLane(core, scope, rootSessionId).map((o) => o.id);
16
20
  }
@@ -64,7 +68,7 @@ export function ensureDurableHeartbeatLane(core) {
64
68
  else if (bh.durable.flushFailed) {
65
69
  if ((bh.durable.redrives = (bh.durable.redrives ?? 0) + 1) > 60) {
66
70
  bh.durable.poisoned = true;
67
- process.emitWarning(`sema durable-agents: terminal flush for ${bh.durable.record.handle} unrecoverable after 60 heartbeat re-drives — durable writes for this row stop here`);
71
+ sayDurableRowUnpersisted("terminal_unrecoverable", bh.durable.record.handle, `sema durable-agents: terminal flush for ${bh.durable.record.handle} unrecoverable after 60 heartbeat re-drives — durable writes for this row stop here`);
68
72
  continue;
69
73
  }
70
74
  liveLanes++;
@@ -93,7 +97,7 @@ export function durableAgentWriteLane(handle, patch, clear) {
93
97
  lane.record.updatedAt = Date.now();
94
98
  const poison = (why) => {
95
99
  lane.poisoned = true;
96
- process.emitWarning(`sema durable-agents: ${why} for ${lane.record.handle} — durable writes for this row stop here`);
100
+ sayDurableRowUnpersisted("poisoned", lane.record.handle, `sema durable-agents: ${why} for ${lane.record.handle} — durable writes for this row stop here`);
97
101
  };
98
102
  const adoptOwnRow = async () => {
99
103
  try {
@@ -346,17 +350,31 @@ export function releaseDurableTranscriptAnchorLane(core, id, sessionId) {
346
350
  delete handle.sessionStore;
347
351
  durableAgentWriteLane(handle, {}, ["sessionId"]);
348
352
  }
353
+ function bindRefusal(problem) {
354
+ return codedRefusal("config.invalid_argument", `TaskRegistry: ${problem}`);
355
+ }
356
+ const INVISIBLE_CHARACTER = /[\p{Z}\p{Cc}\p{Cf}]/u;
357
+ function notAnAnchorWord(sessionId) {
358
+ if (typeof sessionId !== "string")
359
+ return `a ${sessionId === null ? "null" : typeof sessionId}`;
360
+ if (sessionId === "")
361
+ return "an empty string";
362
+ if (INVISIBLE_CHARACTER.test(sessionId))
363
+ return "a string with an invisible character";
364
+ return undefined;
365
+ }
349
366
  export function bindBackgroundAgentSessionLane(core, id, sessionId, store) {
350
- if (typeof sessionId !== "string" || sessionId === "")
351
- throw new Error(`TaskRegistry: a background-agent session anchor must be a non-empty session id (got ${typeof sessionId === "string" ? "an empty string" : `a ${sessionId === null ? "null" : typeof sessionId}`})`);
367
+ const notAnAnchor = notAnAnchorWord(sessionId);
368
+ if (notAnAnchor !== undefined)
369
+ throw bindRefusal(`a background-agent session anchor must be a non-empty session id with no invisible character — no separator, control or format character (got ${notAnAnchor})`);
352
370
  const handle = core.handles.get(id);
353
371
  if (!handle || handle.type !== "background_agent")
354
- return;
372
+ throw bindRefusal(`no background-agent row ${typeof id === "string" ? JSON.stringify(id.length > 80 ? `${id.slice(0, 80)}…` : id) : `(a ${id === null ? "null" : typeof id})`} to anchor a session to`);
355
373
  const anchored = childSessionAnchorOf(handle)?.sessionId;
356
374
  if (anchored === sessionId)
357
375
  return;
358
376
  if (anchored !== undefined)
359
- throw new Error(`TaskRegistry: background-agent row ${id} is anchored to a session already — release that anchor before binding another (the row keeps its anchor)`);
377
+ throw bindRefusal(`background-agent row ${id} is anchored to a session already — release that anchor before binding another (the row keeps its anchor)`);
360
378
  handle.sessionId = sessionId;
361
379
  handle.sessionStore = store;
362
380
  durableAgentWriteLane(handle, { sessionId });
@@ -369,7 +387,7 @@ export function recordBackgroundAgentOrgAdmissionLane(core, id, verdict) {
369
387
  if (lane === undefined)
370
388
  return;
371
389
  const disclose = (why) => {
372
- process.emitWarning(`sema durable-agents: org-admission record for ${lane.record.handle} was not persisted (${why}) — the row keeps the previously recorded verdict, which a later revival will seed from`);
390
+ sayDurableRowUnpersisted("admission", lane.record.handle, `sema durable-agents: org-admission record for ${lane.record.handle} was not persisted (${why}) — the row keeps the previously recorded verdict, which a later revival will seed from`);
373
391
  };
374
392
  if (lane.poisoned) {
375
393
  disclose("durable lane poisoned");
@@ -477,6 +495,7 @@ export function registerBackgroundAgentLane(core, input) {
477
495
  ...(input.policyFloor !== undefined ? { policyFloor: input.policyFloor } : {}),
478
496
  writerId: core.writerId,
479
497
  writerEpoch: 1,
498
+ seq: 1,
480
499
  spawnedAt: now,
481
500
  updatedAt: now,
482
501
  status: "running",
@@ -510,14 +529,11 @@ export function parkBackgroundAgentLane(core, id, park) {
510
529
  r({ ok: false, reason: "not_running" });
511
530
  handle.inFlightDirect = undefined;
512
531
  stampActivity(handle);
513
- if (park.seq !== undefined)
514
- handle.cycleSeq = park.seq;
515
532
  core.pokeBgQuiescence(handle.owner);
516
533
  durableAgentWriteLane(handle, {
517
534
  status: "parked",
518
535
  parkedCheckpointToken: park.checkpointToken,
519
536
  parkedAt: Date.now(),
520
- ...(park.seq !== undefined ? { seq: park.seq } : {}),
521
537
  }, ["parkClaimId"]);
522
538
  return "parked";
523
539
  }
@@ -529,18 +545,8 @@ export async function reconcileParkedAgentsLane(core, stores, scope, now, opts)
529
545
  if (handle.scope !== undefined && handle.scope !== scope)
530
546
  continue;
531
547
  const token = handle.parkedCheckpointToken;
532
- let state;
533
- if (token === undefined)
534
- state = "missing";
535
- else {
536
- try {
537
- const cp = await stores.checkpointStore.get(token);
538
- state = cp === null ? "missing" : cp.status;
539
- }
540
- catch {
541
- state = "unreadable";
542
- }
543
- }
548
+ const cardOf = (t) => ({ token: t, handle: handle.id, scope, sessionId: childSessionAnchorOf(handle)?.sessionId });
549
+ const state = token === undefined ? "missing" : await parkedCardState(stores.checkpointStore, cardOf(token));
544
550
  let error;
545
551
  if (state === "expired" || state === "missing") {
546
552
  error = `approval checkpoint ${state} while parked (reconciled)`;
@@ -555,14 +561,8 @@ export async function reconcileParkedAgentsLane(core, stores, scope, now, opts)
555
561
  }
556
562
  if (row === null || row.status !== "parked" || row.parkClaimId !== undefined)
557
563
  continue;
558
- try {
559
- const reread = (await stores.checkpointStore.get(token));
560
- if (reread === null || reread.status !== "resolved")
561
- continue;
562
- }
563
- catch {
564
+ if (token === undefined || (await parkedCardState(stores.checkpointStore, cardOf(token))) !== "resolved")
564
565
  continue;
565
- }
566
566
  error =
567
567
  "approval checkpoint resolved outside the registry's claim path while parked — the decision was " +
568
568
  "redeemed by another leg and this row's outcome is unknown (reconciled)";
@@ -764,7 +764,7 @@ export async function rollbackParkedClaimLane(core, stores, ticket) {
764
764
  export async function consumeParkedFlipLane(core, id, stores, ticket) {
765
765
  const handle = core.handles.get(id);
766
766
  if (!handle || handle.type !== "background_agent" || handle.status !== "parked")
767
- return false;
767
+ return undefined;
768
768
  const lane = handle.durable;
769
769
  const doFlip = async () => {
770
770
  let live;
@@ -781,7 +781,7 @@ export async function consumeParkedFlipLane(core, id, stores, ticket) {
781
781
  flipped.writerId = core.writerId;
782
782
  flipped.writerEpoch = (live.writerEpoch ?? 0) + 1;
783
783
  flipped.updatedAt = Date.now();
784
- flipped.seq = (live.seq ?? 1) + 1;
784
+ flipped.seq = nextCycleSeq(live);
785
785
  delete flipped.parkedCheckpointToken;
786
786
  delete flipped.parkedAt;
787
787
  try {
@@ -815,7 +815,7 @@ export async function consumeParkedFlipLane(core, id, stores, ticket) {
815
815
  flipped = await doFlip();
816
816
  }
817
817
  if (flipped === undefined)
818
- return false;
818
+ return undefined;
819
819
  handle.status = "running";
820
820
  handle.parkedCheckpointToken = undefined;
821
821
  handle.resolveParkedStop = undefined;
@@ -823,9 +823,8 @@ export async function consumeParkedFlipLane(core, id, stores, ticket) {
823
823
  stampActivity(handle);
824
824
  handle.completionId = undefined;
825
825
  handle.terminalNotified = undefined;
826
- if (flipped.seq !== undefined)
827
- handle.cycleSeq = flipped.seq;
828
- return true;
826
+ handle.cycleSeq = flipped.seq;
827
+ return flipped.seq;
829
828
  }
830
829
  export function finalizeParkedResumeLane(core, id) {
831
830
  const handle = core.handles.get(id);
@@ -885,6 +884,8 @@ export function settleBackgroundAgentLane(core, id, outcome) {
885
884
  }
886
885
  if (outcome.result !== undefined)
887
886
  handle.result = outcome.result;
887
+ if (outcome.refusedAsks !== undefined && outcome.refusedAsks.length > 0)
888
+ handle.refusedAsks = [...outcome.refusedAsks];
888
889
  if (outcome.resultFull !== undefined)
889
890
  handle.resultFull = outcome.resultFull;
890
891
  if (outcome.status === "killed" && outcome.result !== undefined && outcome.result !== "") {
@@ -902,12 +903,9 @@ export function settleBackgroundAgentLane(core, id, outcome) {
902
903
  handle.errorRetryAfterMs = outcome.retryAfterMs;
903
904
  }
904
905
  stampActivity(handle);
905
- if (outcome.seq !== undefined)
906
- handle.cycleSeq = outcome.seq;
907
906
  core.pokeBgQuiescence(handle.owner);
908
907
  durableAgentWriteLane(handle, {
909
908
  status: outcome.status,
910
- ...(outcome.seq !== undefined ? { seq: outcome.seq } : {}),
911
909
  settledAt: Date.now(),
912
910
  ...(handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
913
911
  ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
@@ -915,6 +913,7 @@ export function settleBackgroundAgentLane(core, id, outcome) {
915
913
  ...(handle.resultFull !== undefined ? { finalOutputFull: handle.resultFull } : {}),
916
914
  ...(handle.resultIsPartial ? { resultIsPartial: true } : {}),
917
915
  ...(handle.error !== undefined ? { error: handle.error } : {}),
916
+ ...(handle.refusedAsks !== undefined ? { refusedAsks: [...handle.refusedAsks] } : {}),
918
917
  ...(handle.errorCode !== undefined ? { errorCode: handle.errorCode } : {}),
919
918
  ...(handle.errorRetryable !== undefined ? { errorRetryable: handle.errorRetryable } : {}),
920
919
  ...(handle.errorKind !== undefined ? { errorKind: handle.errorKind } : {}),
@@ -1018,6 +1017,24 @@ export function resolveBackgroundAgentByNameLane(core, name, access, opts) {
1018
1017
  const closest = closestName(key, byKey.keys());
1019
1018
  return { status: "not_found", ...(closest !== undefined ? { suggestion: byKey.get(closest) } : {}) };
1020
1019
  }
1020
+ const SPAWN_NAME_MAX = 64;
1021
+ export function claimBackgroundAgentNameLane(core, requested, access) {
1022
+ const taken = new Set();
1023
+ for (const h of core.handles.values()) {
1024
+ if (h.type === "background_agent" && canAccess(h, access))
1025
+ taken.add(normalizeAgentName(h.name));
1026
+ }
1027
+ for (const c of core.agentNameClaims) {
1028
+ if (c.scope === access.scope && (c.owner === access.owner || (c.sessionId !== undefined && c.sessionId === access.sessionId)))
1029
+ taken.add(c.key);
1030
+ }
1031
+ let name = requested;
1032
+ for (let n = 2; taken.has(normalizeAgentName(name)); n++)
1033
+ name = `${requested.slice(0, SPAWN_NAME_MAX - `-${n}`.length)}-${n}`;
1034
+ const claim = { key: normalizeAgentName(name), scope: access.scope, owner: access.owner, sessionId: access.sessionId };
1035
+ core.agentNameClaims.add(claim);
1036
+ return { name, release: () => void core.agentNameClaims.delete(claim) };
1037
+ }
1021
1038
  export function markRetainedContinuationLane(core, id) {
1022
1039
  const handle = core.handles.get(id);
1023
1040
  if (handle && handle.type === "background_agent")
@@ -1027,7 +1044,7 @@ export function backgroundAgentCycleSeqLane(core, id) {
1027
1044
  const handle = core.handles.get(id);
1028
1045
  if (handle === undefined || handle.type !== "background_agent")
1029
1046
  return undefined;
1030
- return handle.status === "parked" ? (handle.cycleSeq ?? 1) + 1 : handle.cycleSeq;
1047
+ return handle.cycleSeq;
1031
1048
  }
1032
1049
  async function claimTerminalRowForRevive(core, store, handle, scope) {
1033
1050
  for (let attempt = 0; attempt < 3; attempt++) {
@@ -1047,6 +1064,7 @@ async function claimTerminalRowForRevive(core, store, handle, scope) {
1047
1064
  clearRevivedRowTerminalPayload(claimed);
1048
1065
  claimed.writerId = core.writerId;
1049
1066
  claimed.writerEpoch = (live.writerEpoch ?? 0) + 1;
1067
+ claimed.seq = nextCycleSeq(live);
1050
1068
  claimed.updatedAt = Date.now();
1051
1069
  let won = false;
1052
1070
  try {
@@ -1096,6 +1114,7 @@ export async function reviveBackgroundAgentLane(core, id, access, abort) {
1096
1114
  return { ok: false, reason: "still_running" };
1097
1115
  const lane = handle.durable;
1098
1116
  let plainDurableWrite = lane === undefined;
1117
+ let claimedSeq;
1099
1118
  if (lane !== undefined) {
1100
1119
  core.claimingHandles.add(id);
1101
1120
  let claim;
@@ -1134,9 +1153,8 @@ export async function reviveBackgroundAgentLane(core, id, access, abort) {
1134
1153
  return { ok: false, reason: "still_running" };
1135
1154
  }
1136
1155
  ensureDurableHeartbeatLane(core);
1137
- if (claim.status === "claimed" && typeof claim.row.seq === "number" && (handle.cycleSeq ?? 1) < claim.row.seq) {
1138
- handle.cycleSeq = claim.row.seq;
1139
- }
1156
+ if (claim.status === "claimed")
1157
+ claimedSeq = claim.row.seq;
1140
1158
  }
1141
1159
  handle.status = "running";
1142
1160
  handle.channelState = "attaching";
@@ -1152,16 +1170,17 @@ export async function reviveBackgroundAgentLane(core, id, access, abort) {
1152
1170
  handle.errorKind = undefined;
1153
1171
  handle.errorRetryAfterMs = undefined;
1154
1172
  handle.resultIsPartial = undefined;
1173
+ handle.refusedAsks = undefined;
1155
1174
  handle.stopSource = undefined;
1156
1175
  handle.stoppedBy = undefined;
1157
1176
  handle.completionId = undefined;
1158
1177
  handle.terminalNotified = undefined;
1159
1178
  handle.yieldSeat = { lane: "no_park_lane" };
1160
1179
  handle.reviveCycle = (handle.reviveCycle ?? 0) + 1;
1161
- handle.cycleSeq = (handle.cycleSeq ?? 1) + 1;
1180
+ handle.cycleSeq = claimedSeq ?? nextCycleSeq({ seq: handle.cycleSeq });
1162
1181
  stampActivity(handle);
1163
1182
  if (plainDurableWrite)
1164
- durableAgentWriteLane(handle, { status: "running" }, REVIVED_ROW_CLEARED_FIELDS);
1183
+ durableAgentWriteLane(handle, { status: "running", seq: handle.cycleSeq }, REVIVED_ROW_CLEARED_FIELDS);
1165
1184
  return { ok: true, cycle: handle.reviveCycle };
1166
1185
  }
1167
1186
  export function settleRevivedAgentLane(core, id, cycle, outcome) {
@@ -321,11 +321,10 @@ export interface BackgroundAgentTaskHandle extends SemaTaskHandle {
321
321
  /** S2b RB-27② — revive-cycle stamp (see reviveBackgroundAgent): attach/settle from a resume leg
322
322
  * carry it so a stale cycle's late calls no-op instead of clobbering the newer cycle. */
323
323
  reviveCycle?: number;
324
- /** The CURRENT stop-cycle number in settle-generation terms (spawn run = 1; each
325
- * revival — 1.332 retained or tier-3 seeded — opens the next). Served by the LIVE poll/stop
326
- * projection under the SAME `seq` key as the durable-fallback arm, so a tail consumer keys
327
- * revive cycles identically whichever arm answered. Re-aligned to the settle's authoritative
328
- * `outcome.seq` at settle time (the ledger's cycleSeq is the mint; this is its projection). */
324
+ /** The row's stop-cycle number (spawn run = 1; each wake — retained, tier-3 seeded, drain, consume flip — opens the
325
+ * next, `nextCycleSeq`): the number the last WON claim wrote on the durable row, or, with no stored row, this
326
+ * handle's own step. Served by the LIVE poll/stop projection under the SAME `seq` key as the durable-fallback arm,
327
+ * which reads the row's `seq` — one number, so a tail consumer keys cycles identically whichever arm answered. */
329
328
  cycleSeq?: number;
330
329
  /** The yield seat (see {@link RegisterBackgroundAgentInput.yieldLane} and {@link TaskRegistry.yieldBackground}): what the
331
330
  * spawner can park (`lane`), the RUNNING leg's own yield controller and its readiness as its prepare reported them (`leg`,
@@ -428,6 +427,8 @@ export interface BackgroundAgentTaskHandle extends SemaTaskHandle {
428
427
  /** fidelity-sweep A1: `result` arrived AFTER a kill won the status race — it is the child's partial
429
428
  * work (produced before/while being stopped), backfilled by the refused settle. Poll frames label it. */
430
429
  resultIsPartial?: boolean;
430
+ /** The child's refused asks (`TaskResult.refusedAsks`), set by the settle that carries them — what the agent did not get done. */
431
+ refusedAsks?: readonly import("./task-result.js").RefusedAsk[];
431
432
  /** design/134 §3.3 (R3): the PENDING attribution marker, written by {@link TaskRegistry.markStopSource}
432
433
  * at the kill INITIATION site, strictly BEFORE the abort/status flip (once the handle leaves "running"
433
434
  * the marker is refused and attribution falls back to "system"). First-marker-wins. */
@@ -929,6 +930,15 @@ export declare function isLiveSessionResidentAgent(handle: RegisteredTaskHandle)
929
930
  * same cached-view field, upgraded with lazy getter/setter proxies (an IIFE capturing `this`) so
930
931
  * field declaration ORDER no longer constrains it — `writerId`/`reapingHandles` 등 are read at
931
932
  * call time, after construction completes. */
933
+ /** A spawn name held by a launch whose background-agent row does not exist yet: `key` is the normalized
934
+ * name, and the seat (scope, owner, session) is the spawner's own view. It holds the name against other
935
+ * launches from that seat until the launch ends, so two launches running side by side cannot both bind it. */
936
+ export interface AgentNameClaim {
937
+ readonly key: string;
938
+ readonly scope: string | undefined;
939
+ readonly owner: string | undefined;
940
+ readonly sessionId: string | undefined;
941
+ }
932
942
  export interface DurableAgentCore extends RegistryCore {
933
943
  readonly writerId: string;
934
944
  readonly reapingHandles: Set<string>;
@@ -939,6 +949,8 @@ export interface DurableAgentCore extends RegistryCore {
939
949
  * versus "it is gone, relaunch". A subset of `reapingHandles`, cleared with it. */
940
950
  readonly reapedHandles: Set<string>;
941
951
  readonly claimingHandles: Set<string>;
952
+ /** Spawn names a launch in flight holds before its row exists ({@link AgentNameClaim}). */
953
+ readonly agentNameClaims: Set<AgentNameClaim>;
942
954
  /** get/set proxy — `ensureDurableHeartbeatLane` both reads AND writes the timer slot. */
943
955
  durableHeartbeatTimer: ReturnType<typeof setInterval> | undefined;
944
956
  readonly deliverConfirmTimeoutMs: number;
@@ -294,7 +294,6 @@ export declare class TaskRegistry {
294
294
  recordBackgroundAgentOrgAdmission(id: string, verdict: import("./memory-admission.js").OwnOrgAdmissionVerdict): void;
295
295
  parkBackgroundAgent(id: string, park: {
296
296
  checkpointToken: string;
297
- seq?: number;
298
297
  resolveStop?: () => Promise<boolean>;
299
298
  completionSink?: BackgroundAgentTaskHandle["parkedCompletionSink"];
300
299
  }): "parked" | undefined;
@@ -303,7 +302,7 @@ export declare class TaskRegistry {
303
302
  parkedCompletionSink(id: string): BackgroundAgentTaskHandle["parkedCompletionSink"];
304
303
  reconcileParkedAgents(stores: {
305
304
  agentStore: import("./background-agent-store.js").BackgroundAgentStore;
306
- checkpointStore: Pick<import("./checkpoint-store.js").CheckpointStore, "get">;
305
+ checkpointStore: import("./background-agent-store.js").ParkedCardStore;
307
306
  }, scope: string, now: number, opts?: {
308
307
  staleClaimMaxAgeMs?: number;
309
308
  }): Promise<{
@@ -324,9 +323,11 @@ export declare class TaskRegistry {
324
323
  agentStore: import("./background-agent-store.js").BackgroundAgentStore;
325
324
  checkpointStore: Pick<import("./checkpoint-store.js").CheckpointStore, "get">;
326
325
  }, ticket: ParkedClaimTicket): Promise<ParkedClaimRollback>;
326
+ /** The consume flip (parked → running): the stop-cycle number it wrote on the row — the resumed cycle's — or
327
+ * `undefined` when the row moved and the resume must abort. See {@link consumeParkedFlipLane}. */
327
328
  consumeParkedFlip(id: string, stores: {
328
329
  agentStore: import("./background-agent-store.js").BackgroundAgentStore;
329
- }, ticket: ParkedClaimTicket): Promise<boolean>;
330
+ }, ticket: ParkedClaimTicket): Promise<number | undefined>;
330
331
  finalizeParkedResume(id: string): void;
331
332
  /** `outcome.cycle` names the revive cycle this settle speaks for (absent = 0 = the original
332
333
  * spawn cycle). A spawn leg never passes it; a caller that settles by LIFECYCLE AUTHORITY (reap /
@@ -342,8 +343,8 @@ export declare class TaskRegistry {
342
343
  errorKind?: string;
343
344
  retryAfterMs?: number;
344
345
  stoppedBy?: StopSource;
345
- seq?: number;
346
346
  cycle?: number;
347
+ refusedAsks?: readonly import("./task-result.js").RefusedAsk[];
347
348
  }): "completed" | "failed" | "killed" | undefined;
348
349
  /** design/164 — record one tool-lifecycle beat on a running background-agent row; see
349
350
  * {@link noteBackgroundAgentActivityLane} for why the in-memory row needed a stall signal at all. `atMono` is an instant on the
@@ -379,9 +380,16 @@ export declare class TaskRegistry {
379
380
  status: "not_found";
380
381
  suggestion?: string;
381
382
  };
383
+ /** Bind a spawn name for a launch from the seat `access` names: the requested name, or the first free `<name>-N` when an
384
+ * agent this seat can see (any status) or another launch from it already answers to it. The claim holds the name until
385
+ * `release()` (see {@link claimBackgroundAgentNameLane}). */
386
+ claimAgentName(requested: string, access: TaskAccess): {
387
+ name: string;
388
+ release(): void;
389
+ };
382
390
  markRetainedContinuation(id: string): void;
383
- /** The row's current stop-cycle counter, read by the spawn lanes right after registering to
384
- * thread into the child's `RunInternals.cycleSeq`; see {@link backgroundAgentCycleSeqLane}. */
391
+ /** The row's stop-cycle number as its last won claim left it (a parked row: the cycle that parked) — the one number
392
+ * every frame, notification, tick and poll of the row reads; see {@link backgroundAgentCycleSeqLane}. */
385
393
  backgroundAgentCycleSeq(id: string): number | undefined;
386
394
  /** Subagent transcript persistence (delegation entry caps) — one delegation tree's ACTIVE
387
395
  * (running/pending) a* handles in THIS process, keyed `(scope, rootSessionId)`; SYNCHRONOUS by
@@ -415,6 +423,7 @@ export declare class TaskRegistry {
415
423
  retryable?: boolean;
416
424
  errorKind?: string;
417
425
  retryAfterMs?: number;
426
+ refusedAsks?: readonly import("./task-result.js").RefusedAsk[];
418
427
  }): "completed" | "failed" | "killed" | undefined;
419
428
  unmarkRetainedContinuation(id: string): void;
420
429
  attachAgentNotify(id: string, notify: NonNullable<BackgroundAgentTaskHandle["notify"]>, cycle?: number): void;
@@ -473,6 +482,8 @@ export declare class TaskRegistry {
473
482
  * terminal-handle GC skips it — so the revival lanes, the reaper and the GC can never adjudicate the
474
483
  * same handle concurrently in-process. */
475
484
  private claimingHandles;
485
+ /** Spawn names held by launches whose rows do not exist yet ({@link claimAgentName}). */
486
+ private agentNameClaims;
476
487
  private durableHeartbeatTimer;
477
488
  mintTaskId(type: SemaTaskType): string;
478
489
  registerBackgroundBash(input: RegisterBackgroundBashInput): string;
@@ -15,7 +15,7 @@ import { taskReadHandleText, canAccessWorkflowRun, formatWorkflowRun, clipTaskOu
15
15
  export { normalizeAgentName, DURABLE_AGENT_HEARTBEAT_MS, DURABLE_AGENT_HANDLE_RE, BG_AGENT_REAP_STOP_ERROR, engineAgentName, chosenAgentName, PARKED_CLAIM_ROLLBACKS, PARKED_CLAIM_ROLLBACK_FACE } from "./task-registry-shared.js";
16
16
  import { attachYieldLegLane, requestYieldLane, yieldCovers, yieldPopulationLane, yieldPopulationLeftRunning, yieldPopulationWrites, yieldRequested } from "./task-registry-yield.js";
17
17
  import { TASK_STOP_TOOL_NAME, TASK_STOP_MISSING_ID_MESSAGE, TASK_STOP_PARAMS, TASK_STOP_DESCRIPTION, resolveTaskIdArg } from "./task-tool-shape.js";
18
- import { durableAgentArmedLane, durableAgentRowProbeLane, beginDurableClaimLane, endDurableClaimLane, reapDurableAgentsLane, noteBackgroundAgentActivityLane, reapStaleSessionBackgroundAgentsLane, announceLandedAgentTerminal, releaseDurableTranscriptAnchorLane, bindBackgroundAgentSessionLane, childSessionAnchorOf, registerBackgroundAgentLane, recordBackgroundAgentOrgAdmissionLane, parkBackgroundAgentLane, reconcileParkedAgentsLane, claimParkedAgentLane, rollbackParkedClaimLane, consumeParkedFlipLane, finalizeParkedResumeLane, settleBackgroundAgentLane, abortBackgroundAgentsForOwnerLane, serveDurableAgentRowLane, resolveBackgroundAgentByNameLane, backgroundAgentCycleSeqLane, activeDelegationHandlesLane, activeDelegationHandlesByRootLane, activeDelegationOccupantsLane, markRetainedContinuationLane, reviveBackgroundAgentLane, settleRevivedAgentLane, unmarkRetainedContinuationLane, attachAgentNotifyLane, deliverToRunningAgentLane, runningBackgroundAgentLabelsLane, runningAgentFooterLane, notFoundRunningAgentsTail, pollBackgroundAgentLane, stopBackgroundAgentLane, } from "./task-registry-agent.js";
18
+ import { durableAgentArmedLane, durableAgentRowProbeLane, beginDurableClaimLane, endDurableClaimLane, reapDurableAgentsLane, noteBackgroundAgentActivityLane, reapStaleSessionBackgroundAgentsLane, announceLandedAgentTerminal, releaseDurableTranscriptAnchorLane, bindBackgroundAgentSessionLane, childSessionAnchorOf, registerBackgroundAgentLane, recordBackgroundAgentOrgAdmissionLane, parkBackgroundAgentLane, reconcileParkedAgentsLane, claimParkedAgentLane, rollbackParkedClaimLane, consumeParkedFlipLane, finalizeParkedResumeLane, settleBackgroundAgentLane, abortBackgroundAgentsForOwnerLane, serveDurableAgentRowLane, resolveBackgroundAgentByNameLane, claimBackgroundAgentNameLane, backgroundAgentCycleSeqLane, activeDelegationHandlesLane, activeDelegationHandlesByRootLane, activeDelegationOccupantsLane, markRetainedContinuationLane, reviveBackgroundAgentLane, settleRevivedAgentLane, unmarkRetainedContinuationLane, attachAgentNotifyLane, deliverToRunningAgentLane, runningBackgroundAgentLabelsLane, runningAgentFooterLane, notFoundRunningAgentsTail, pollBackgroundAgentLane, stopBackgroundAgentLane, } from "./task-registry-agent.js";
19
19
  import { mountRuleFace, toolFace } from "./tool-catalog-entries.js";
20
20
  import { thrownText } from "./thrown-value.js";
21
21
  import { agentStateSourceOfHandle, agentStateSourceOfRecord, agentStateSummary, readAgentState } from "./agent-state.js";
@@ -170,6 +170,7 @@ export class TaskRegistry {
170
170
  get reapingHandles() { return self.reapingHandles; },
171
171
  get reapedHandles() { return self.reapedHandles; },
172
172
  get claimingHandles() { return self.claimingHandles; },
173
+ get agentNameClaims() { return self.agentNameClaims; },
173
174
  get durableHeartbeatTimer() { return self.durableHeartbeatTimer; },
174
175
  set durableHeartbeatTimer(v) { self.durableHeartbeatTimer = v; },
175
176
  get deliverConfirmTimeoutMs() { return self.deliverConfirmTimeoutMs; },
@@ -304,6 +305,9 @@ export class TaskRegistry {
304
305
  resolveBackgroundAgentByName(name, access, opts) {
305
306
  return resolveBackgroundAgentByNameLane(this.core, name, access, opts);
306
307
  }
308
+ claimAgentName(requested, access) {
309
+ return claimBackgroundAgentNameLane(this.core, requested, access);
310
+ }
307
311
  markRetainedContinuation(id) {
308
312
  return markRetainedContinuationLane(this.core, id);
309
313
  }
@@ -368,6 +372,7 @@ export class TaskRegistry {
368
372
  reapingHandles = new Set();
369
373
  reapedHandles = new Set();
370
374
  claimingHandles = new Set();
375
+ agentNameClaims = new Set();
371
376
  durableHeartbeatTimer;
372
377
  mintTaskId(type) {
373
378
  const prefix = TASK_PREFIX[type];
@@ -65,8 +65,9 @@ export interface HumanReviewGateRow {
65
65
  export interface RemoteEnvFailureNote {
66
66
  /** Which VM-lifecycle call failed. */
67
67
  op: "suspendVM" | "resumeVM" | "postResumeInit";
68
- /** The adapter's verbatim code — the whole point of this note. */
69
- code: import("./remote-env.js").RemoteExecutionErrorCode;
68
+ /** The adapter's verbatim code — the whole point of this note (`RemoteExecutionError.code`: a closed-set word, or a
69
+ * deployment's own `env.` code). */
70
+ code: import("./remote-env.js").RemoteExecutionError["code"];
70
71
  /** `code` is in the retryable family (`RETRYABLE_REMOTE_ERROR_CODES`) — a re-attempt can plausibly work. */
71
72
  retryable: boolean;
72
73
  /** How many times the engine called `op` before giving up (1 = it did not retry). */
@@ -159,6 +160,15 @@ export type EffectiveMemoryScopes = {
159
160
  writeScope: null;
160
161
  materializedResidue?: never;
161
162
  };
163
+ /** One ask a run could not have answered and refused ({@link TaskResult.refusedAsks}): the call, why nobody answered it (the closed
164
+ * set the `delegation.ask_unresolvable` notice carries), and the way out the refusal named — the headless remedy's sentence, a
165
+ * binding's own, or the way out of a leg whose parks cannot be resumed; absent when the refusal named none. */
166
+ export interface RefusedAsk {
167
+ readonly toolName: string;
168
+ readonly toolCallId: string;
169
+ readonly cause: import("./ask-unresolvable-notice.js").AskUnresolvableCause;
170
+ readonly remedy?: string;
171
+ }
162
172
  export interface TaskResult {
163
173
  taskId: string;
164
174
  /**
@@ -229,28 +239,25 @@ export interface TaskResult {
229
239
  responseModel?: string;
230
240
  /**
231
241
  * The leg's effective REASONING resolution: the result-face twin of {@link model} for the thinking
232
- * knob. How the requested tier resolved against the serving model's real capability
233
- * (`requested`/`effective`/`graded`/`clamped`/`format`/`endpoint`, plus `dropped:true` when a
234
- * non-reasoning model dropped the request entirely — field semantics on
235
- * {@link import("../brain/reasoning.js").ResolvedReasoning}). It is the SAME resolver output the
236
- * `reasoning.resolved` trace frame carries — the two faces cannot tell different stories; this seat
237
- * serves consumers without a tracer (the trace frame is the deployment-observability face, this is the
238
- * caller face).
242
+ * knob. How the requested tier resolved on the leg's request (`requested`/`effective`/`graded`/`clamped`/`format`/
243
+ * `endpoint`, plus `dropped:true` exactly when `effective` is `"provider_default"`) — `effective` is what the request's
244
+ * thinking keys say: a tier, `"on"` (thinking on, no tier named), or `"provider_default"` (no thinking key at all); field
245
+ * semantics on {@link import("../brain/reasoning.js").ResolvedReasoning}. It is the SAME value the `reasoning.resolved`
246
+ * trace frame carries — the two faces cannot tell different stories; this seat serves consumers without a tracer (the
247
+ * trace frame is the deployment-observability face, this is the caller face).
239
248
  *
240
249
  * **In-presence condition** — mirrors the trace frame exactly: present on every terminal of a leg that ran
241
- * with a REQUESTED thinking tier other than off/unset (the `spec > role > model.defaultThinking` chain);
242
- * absent when thinking was off/unset for the leg, and on prepare failures (the resolution is minted after
243
- * prepare). On a resumed task each leg re-resolves against the leg's own serving model.
244
- *
245
- * **Per-request correction** — the leg-entry mint runs before any request exists, so it can only
246
- * describe the model's CAPABILITY. When the leg's FIRST committed request reports wire facts that change
247
- * that answer, the seat is re-resolved against them by the same resolver and the trace twin is re-emitted
248
- * with it. Today that is one arm: the anthropic budget path's cap-wins skip — a HARD per-request output
249
- * cap too small to host a legal thinking budget deletes the thinking block, so a leg capped that way now
250
- * reports `effective:"off"`/`dropped:true` instead of claiming the gradient the wire never carried. Only
251
- * the FIRST committed request is consumed: the seat stays a leg-ENTRY snapshot (see the degradation law
252
- * below), and the leg's nested internal brain calls (compaction summary, tool-invoked side query) carry
253
- * their own caps and must never restate the leg's posture.
250
+ * with a REQUESTED thinking tier, `off` included (the `spec > role > model.defaultThinking` chain); absent when the leg had
251
+ * no tier, and on prepare failures (the resolution is minted after prepare). On a resumed task each leg re-resolves against
252
+ * the leg's own serving model.
253
+ *
254
+ * **First-request correction** — the leg-entry value is the wire applier's answer before any request exists, so it cannot
255
+ * see what only the brain holds (a budget knob from the brain's construction config, the request's own output cap). The
256
+ * leg's first request whose terminal message reaches the leg — its own model object's request, a success or a failure
257
+ * the stream engine ended — carries its own answer on that message, and the seat takes it once (the trace twin is
258
+ * re-emitted when it differs). Requests a mod, a tool or an internal lane makes never reach the leg's messages, so they
259
+ * cannot restate the leg's posture. A terminal minted outside the engine (a guardrail timeout, a first-token deadline, a
260
+ * cut turn, a deployment Brain's own message) carries no answer: the seat keeps the entry value and waits for the next.
254
261
  *
255
262
  * **Degradation law** — same as {@link model}, whose resolution this is: the seat describes the leg's
256
263
  * PRIMARY serving model at leg entry. A mid-run degradation (reactive fallback / near-budget switch)
@@ -367,7 +374,7 @@ export interface TaskResult {
367
374
  * never do it" had nothing but a string to parse.
368
375
  *
369
376
  * - `op` — which lifecycle call failed.
370
- * - `code` — the adapter's verbatim `RemoteExecutionErrorCode`.
377
+ * - `code` — the adapter's verbatim code (`RemoteExecutionError.code`).
371
378
  * - `retryable` — whether `code` is in the retryable family (`RETRYABLE_REMOTE_ERROR_CODES`). For the
372
379
  * IDEMPOTENT restore ops the engine has already spent its own bounded retries (see `attempts`); this
373
380
  * flag is what a caller acts on for the ops the engine deliberately does not retry — a `suspendVM`
@@ -377,9 +384,18 @@ export interface TaskResult {
377
384
  *
378
385
  * Present only when at least one lifecycle call failed (absent = nothing to report), so a consumer that
379
386
  * ignores the field is unchanged. It is DIAGNOSTIC: {@link terminal} keeps its existing meaning —
380
- * a failed suspend still ends the task the way it always did, it is just no longer anonymous.
387
+ * a failed suspend still ends the task the way it always did, it is just no longer anonymous. A `resumeVM` the
388
+ * environment refused standing (a code outside the retryable family, other than `unknown` and `aborted`) is no note
389
+ * here: the leg's restore seat fails it with that code as {@link terminal}'s own.
381
390
  */
382
391
  remoteEnvFailures?: RemoteEnvFailureNote[];
392
+ /**
393
+ * The asks of this run that nobody could answer and that were refused — one entry per refused call, in refusal order, minted at
394
+ * the gate's one deny exit beside the `delegation.ask_unresolvable` notice (the same facts). The run's terminal is unchanged (a
395
+ * refused ask is a tool result the run went on from); this is what the leg did NOT get done. Present only when at least one ask
396
+ * was refused — never an empty array.
397
+ */
398
+ refusedAsks?: readonly RefusedAsk[];
383
399
  /**
384
400
  * Present when this run's terminal failure came from the PROVIDER BOUNDARY — the transport or the
385
401
  * provider failed the model call, as opposed to this deployment refusing to send one, a limit being
@@ -481,7 +497,8 @@ export interface TaskResult {
481
497
  * ignores the field is unchanged. A rewind that could NOT be delivered as asked is NOT a note — it is a
482
498
  * terminal failure (`rewind_snapshot.unresolvable` / `rewind.store_unconfigured` /
483
499
  * `rewind.restore_failed` / `rewind.invalid_spec` /
484
- * `rewind.conflicting_targets` / `rewind.child_scope_unsupported` / `rewind.capture_disabled`).
500
+ * `rewind.conflicting_targets` / `rewind.child_scope_unsupported` / `rewind.capture_disabled`; `config.invalid_argument`
501
+ * when the session's id ends like a file-history address on a row outside the address epoch — `fileHistoryScopeOf`).
485
502
  *
486
503
  * - `conversation_only` — {@link TaskSpec.resumeAt} branched the transcript WITHOUT
487
504
  * {@link TaskSpec.restoreFiles}, so the working tree was deliberately left where it was (CC's
@@ -615,6 +632,27 @@ export interface TaskResult {
615
632
  * disclosed by one `task.halt_unconsumed` (`detail.source: "extension"`).
616
633
  */
617
634
  turnAbortedBy?: string;
635
+ /**
636
+ * Present exactly when the run COMPLETED strictly past a ceiling the caller declared (`TaskSpec.limits`): its last turn answered and owed no
637
+ * further request, so nothing was cut and nothing is owed — the verdict is `completed`, and this says the ceiling was crossed on the way (the
638
+ * figures were never on the result: `stats` holds the spend, not the ceiling). The same fact rides one `operator` notice,
639
+ * `task.completed_past_limit`, from one evaluation — branch on this member, never on the notice's sentence.
640
+ * - `axis` — which ceiling, in the words of a parked run's `resource_limit` reason: `budget_tokens`, `budget_cost`, `walltime`. There is no
641
+ * `turns` word: a run that answers on the turn its cap allows used its allowance, and one that reached the cap with a turn owed fails or
642
+ * parks — a completed run is never past its turn cap. When several ceilings are crossed it names the first of tokens, cost, walltime.
643
+ * - `limit` — the ceiling the engine compared, in the axis's unit: tokens (`budget_tokens`; for a resource-slice run the smaller of the
644
+ * slice window and what the cross-slice allocation had left), MICRO-USD (`budget_cost`, the unit of `stats.costMicroUsd`), MILLISECONDS
645
+ * (`walltime`).
646
+ * - `observed` — the run's figure against it, same unit and strictly greater: `stats.tokens`, `stats.costMicroUsd`, and for the walltime axis
647
+ * the ms elapsed when the turn boundary found the window passed (work after the answer does not move it).
648
+ * Absent on every other terminal (a run that owed another request fails or parks on its crossed axis as before), when a ceiling was only met,
649
+ * and when no ceiling was crossed.
650
+ */
651
+ limitCrossed?: {
652
+ axis: Exclude<import("./checkpoint-store.js").ResourceLimitReason, import("./checkpoint-store.js").PlatformLimitReason | "turns">;
653
+ limit: number;
654
+ observed: number;
655
+ };
618
656
  /**
619
657
  * The deliveries of AskUserQuestion calls a person ANSWERED but whose call never executed to collect
620
658
  * the answer (the leg ended first — abort, batch teardown, or a loop failure). Rides EVERY terminal
@@ -846,6 +884,14 @@ export interface TaskResult {
846
884
  * rather than a fabricated 0, so "no price table" stays distinguishable from "declared free"
847
885
  * (an explicit all-zero `Model.cost` still reports 0). `costBreakdown` is omitted with it. */
848
886
  costMicroUsd?: number;
887
+ /** Wall time, in milliseconds, of this run's own main-loop model calls (the reference result's `duration_api_ms`), summed over its turns — the sum of the per-turn
888
+ * `turn_end.usage.apiDurationMs` and of the `brain.call` trace rows' `ts − callStartedAt` (one measurement, three faces). Each call
889
+ * is timed from the moment the engine hands the request to the brain to its final message; a call with no stamp adds 0 (a hop a
890
+ * fallback walk left behind), and the compaction / classifier / mod / advisor calls are not timed at all. A
891
+ * delegated sub-run's time is its own leg's `apiDurationMs`: {@link nested} carries tokens, turns, tasks and cost, not time. A
892
+ * resumed leg reports its own calls (unlike `tokens`, no prior slice is folded in). On a composition's stats (cascade, repair
893
+ * loop, verify) it is the sum over its legs. Present on every result of a leg that ran; absent where no leg ran. */
894
+ apiDurationMs?: number;
849
895
  nested?: NestedUsage;
850
896
  /**
851
897
  * Post-task memory-consolidation usage (design/41), when consolidation ran. Its own line item —
@@ -126,7 +126,6 @@ declare const SPEC_MEMBER_TABLE: {
126
126
  forwardSubagentEvents: 0;
127
127
  retainSubagentSessions: 0;
128
128
  retainBackgroundProcesses: 0;
129
- streamingToolExecution: 0;
130
129
  outputSchema: 0;
131
130
  outputRetries: 0;
132
131
  tracer: 0;
@@ -14,7 +14,7 @@ const SPEC_MEMBER_TABLE = {
14
14
  additionalDirectories: 0, additionalReadDirectories: 0, readDenyPatterns: 0, writeProtectedAdditions: 0, complianceAdditionalDenies: 0, readFace: 0, writeFace: 0, enablePlanMode: 0,
15
15
  planFile: 0, interactiveTools: 0, enableFork: 0, shellGate: 0, permissionMode: 0, classifyAllShell: 0, mcp: 0, a2a: 0,
16
16
  skills: 0, userInvokedSkills: 0, allowedTools: 0, skillListingBudgetFraction: 0, skillListingMaxDescChars: 0, backgroundScope: 0, sandbox: 0, envFacts: 0, limits: 0,
17
- configOverrides: 0, forwardSubagentEvents: 0, retainSubagentSessions: 0, retainBackgroundProcesses: 0, streamingToolExecution: 0, outputSchema: 0, outputRetries: 0, tracer: 0,
17
+ configOverrides: 0, forwardSubagentEvents: 0, retainSubagentSessions: 0, retainBackgroundProcesses: 0, outputSchema: 0, outputRetries: 0, tracer: 0,
18
18
  toolResultThresholdChars: 0, compaction: 0, attachments: 0, enableBlockedReport: 0, selfOrchestration: 0, getApiKeyAndHeaders: 0, signal: 0,
19
19
  language: 0,
20
20
  };