@sema-agent/core 7.66.1 → 7.67.1

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 (904) hide show
  1. package/CHANGELOG.md +3518 -0
  2. package/LICENSE +2 -1
  3. package/dist/agents/agent-definition.js +2 -1
  4. package/dist/agents/agent-transcript-tool.d.ts +1 -1
  5. package/dist/agents/agent-transcript-tool.js +4 -3
  6. package/dist/agents/builtin-agents.d.ts +10 -7
  7. package/dist/agents/builtin-agents.js +1 -0
  8. package/dist/agents/cascade.d.ts +24 -11
  9. package/dist/agents/cascade.js +21 -9
  10. package/dist/agents/child-failure.d.ts +30 -0
  11. package/dist/agents/child-failure.js +25 -1
  12. package/dist/agents/composition-placement.d.ts +6 -2
  13. package/dist/agents/composition-placement.js +7 -3
  14. package/dist/agents/cross-session-envelope.d.ts +10 -1
  15. package/dist/agents/cross-session-envelope.js +6 -2
  16. package/dist/agents/cross-session-judge.d.ts +7 -1
  17. package/dist/agents/cross-session-judge.js +1 -0
  18. package/dist/agents/cumulative-stats.d.ts +36 -2
  19. package/dist/agents/cumulative-stats.js +44 -9
  20. package/dist/agents/delegation-registry-seat.js +2 -3
  21. package/dist/agents/inherited-tool-pool.d.ts +9 -4
  22. package/dist/agents/inherited-tool-pool.js +7 -1
  23. package/dist/agents/leg-label.d.ts +28 -0
  24. package/dist/agents/leg-label.js +9 -0
  25. package/dist/agents/list-agents-tool.d.ts +1 -1
  26. package/dist/agents/list-agents-tool.js +4 -4
  27. package/dist/agents/org-delivery-gate.d.ts +129 -23
  28. package/dist/agents/org-delivery-gate.js +41 -20
  29. package/dist/agents/peer-held-queue.d.ts +15 -10
  30. package/dist/agents/peer-held-queue.js +47 -19
  31. package/dist/agents/peer-notice-route.js +2 -2
  32. package/dist/agents/peer-notices.d.ts +13 -2
  33. package/dist/agents/peer-notices.js +12 -2
  34. package/dist/agents/peer-session-drain.d.ts +65 -15
  35. package/dist/agents/peer-session-drain.js +198 -41
  36. package/dist/agents/read-inbox-tool.d.ts +3 -2
  37. package/dist/agents/read-inbox-tool.js +7 -5
  38. package/dist/agents/repair-loop.js +20 -16
  39. package/dist/agents/retain-ledger.d.ts +1 -1
  40. package/dist/agents/retain-ledger.js +2 -4
  41. package/dist/agents/root-session-lane.d.ts +27 -0
  42. package/dist/agents/root-session-lane.js +57 -0
  43. package/dist/agents/roster-store.js +1 -2
  44. package/dist/agents/send-message-tool.js +6 -4
  45. package/dist/agents/subagent.d.ts +20 -4
  46. package/dist/agents/subagent.js +218 -183
  47. package/dist/agents/tool-filter.d.ts +3 -10
  48. package/dist/agents/tool-filter.js +0 -13
  49. package/dist/agents/verifier-independence.d.ts +31 -0
  50. package/dist/agents/verifier-independence.js +23 -0
  51. package/dist/agents/verify.d.ts +23 -11
  52. package/dist/agents/verify.js +28 -12
  53. package/dist/agents/yield-adoption.d.ts +24 -0
  54. package/dist/agents/yield-adoption.js +84 -0
  55. package/dist/bench/metrics.d.ts +2 -2
  56. package/dist/brain/anthropic.d.ts +4 -2
  57. package/dist/brain/anthropic.js +49 -35
  58. package/dist/brain/brain-faces.d.ts +11 -0
  59. package/dist/brain/brain-faces.js +6 -0
  60. package/dist/brain/cache-retention.d.ts +2 -0
  61. package/dist/brain/cache-retention.js +9 -0
  62. package/dist/brain/circuit-breaker.js +51 -26
  63. package/dist/brain/errors.d.ts +15 -1
  64. package/dist/brain/errors.js +8 -0
  65. package/dist/brain/failover.d.ts +6 -0
  66. package/dist/brain/failover.js +52 -37
  67. package/dist/brain/media-degrade.d.ts +5 -0
  68. package/dist/brain/media-degrade.js +4 -0
  69. package/dist/brain/model-capability.d.ts +2 -1
  70. package/dist/brain/model-lane.d.ts +169 -0
  71. package/dist/brain/model-lane.js +505 -0
  72. package/dist/brain/open-responses.js +19 -22
  73. package/dist/brain/openai.js +23 -22
  74. package/dist/brain/provider-message.d.ts +9 -0
  75. package/dist/brain/provider-message.js +18 -0
  76. package/dist/brain/reasoning-request.d.ts +9 -7
  77. package/dist/brain/reasoning-request.js +9 -10
  78. package/dist/brain/reasoning.d.ts +47 -13
  79. package/dist/brain/reasoning.js +20 -10
  80. package/dist/brain/route-adjudicator.d.ts +8 -2
  81. package/dist/brain/route-adjudicator.js +35 -1
  82. package/dist/brain/route-conformance.js +17 -0
  83. package/dist/brain/routing.d.ts +2 -0
  84. package/dist/brain/routing.js +19 -8
  85. package/dist/brain/status-sink.d.ts +5 -4
  86. package/dist/brain/status-sink.js +2 -2
  87. package/dist/brain/stream-engine.js +8 -2
  88. package/dist/brain/stream-shared.d.ts +12 -0
  89. package/dist/brain/stream-shared.js +18 -0
  90. package/dist/brain/timeout.d.ts +28 -0
  91. package/dist/brain/timeout.js +13 -4
  92. package/dist/brain/tool-schema-projection.d.ts +2 -0
  93. package/dist/brain/tool-schema-projection.js +108 -0
  94. package/dist/brain/usage-reading.d.ts +49 -0
  95. package/dist/brain/usage-reading.js +44 -0
  96. package/dist/brain/usage-reasoning.d.ts +38 -0
  97. package/dist/brain/usage-reasoning.js +9 -0
  98. package/dist/config/catalog.d.ts +3 -0
  99. package/dist/config/catalog.js +18 -9
  100. package/dist/core/a2a.d.ts +22 -4
  101. package/dist/core/a2a.js +191 -50
  102. package/dist/core/agent-definition.d.ts +3 -1
  103. package/dist/core/agent-state.d.ts +29 -16
  104. package/dist/core/agent-state.js +36 -9
  105. package/dist/core/allow-entry.d.ts +12 -3
  106. package/dist/core/allow-entry.js +10 -3
  107. package/dist/core/approval-display.d.ts +18 -0
  108. package/dist/core/approval-display.js +26 -0
  109. package/dist/core/approval-object.js +2 -2
  110. package/dist/core/approval-route.d.ts +16 -0
  111. package/dist/core/approval-route.js +5 -0
  112. package/dist/core/approval-words.d.ts +43 -0
  113. package/dist/core/approval-words.js +37 -0
  114. package/dist/core/ask-origin.d.ts +37 -10
  115. package/dist/core/ask-origin.js +19 -7
  116. package/dist/core/ask-question.d.ts +36 -8
  117. package/dist/core/ask-question.js +24 -9
  118. package/dist/core/ask-unresolvable-notice.d.ts +3 -2
  119. package/dist/core/ask-unresolvable-notice.js +3 -2
  120. package/dist/core/attachment-source.d.ts +50 -0
  121. package/dist/core/attachment-source.js +46 -0
  122. package/dist/core/auto-compaction.d.ts +151 -40
  123. package/dist/core/auto-compaction.js +115 -50
  124. package/dist/core/auto-mode.d.ts +5 -0
  125. package/dist/core/auto-mode.js +11 -4
  126. package/dist/core/background-agent-store.d.ts +151 -23
  127. package/dist/core/background-agent-store.js +201 -61
  128. package/dist/core/background-shell.d.ts +4 -1
  129. package/dist/core/background-shell.js +1 -0
  130. package/dist/core/cache-break-detector.d.ts +49 -25
  131. package/dist/core/cache-break-detector.js +99 -44
  132. package/dist/core/caller-text.d.ts +28 -0
  133. package/dist/core/caller-text.js +12 -0
  134. package/dist/core/canonical-json.d.ts +5 -0
  135. package/dist/core/canonical-json.js +7 -0
  136. package/dist/core/checkpoint-features.d.ts +80 -9
  137. package/dist/core/checkpoint-features.js +1 -1
  138. package/dist/core/checkpoint-generation.d.ts +8 -1
  139. package/dist/core/checkpoint-generation.js +3 -0
  140. package/dist/core/checkpoint-queries.d.ts +47 -14
  141. package/dist/core/checkpoint-queries.js +63 -30
  142. package/dist/core/checkpoint-requirements.d.ts +36 -3
  143. package/dist/core/checkpoint-requirements.js +11 -1
  144. package/dist/core/checkpoint-row-verdict.d.ts +0 -2
  145. package/dist/core/checkpoint-row-verdict.js +5 -8
  146. package/dist/core/checkpoint-store.d.ts +166 -41
  147. package/dist/core/checkpoint-store.js +96 -15
  148. package/dist/core/child-clamp-seats.d.ts +10 -2
  149. package/dist/core/child-clamp-seats.js +2 -2
  150. package/dist/core/classifier-unavailable-arm.d.ts +11 -9
  151. package/dist/core/classifier-unavailable-arm.js +4 -2
  152. package/dist/core/command-sandbox-dispatch.d.ts +13 -0
  153. package/dist/core/command-sandbox-dispatch.js +8 -0
  154. package/dist/core/command-sandbox.d.ts +231 -0
  155. package/dist/core/command-sandbox.js +344 -0
  156. package/dist/core/completion-id.d.ts +21 -0
  157. package/dist/core/completion-id.js +14 -0
  158. package/dist/core/config-refusal-codes.d.ts +22 -0
  159. package/dist/core/config-refusal-codes.js +196 -0
  160. package/dist/core/context-edit.d.ts +26 -0
  161. package/dist/core/context-edit.js +4 -2
  162. package/dist/core/context-guard.d.ts +80 -7
  163. package/dist/core/context-guard.js +126 -25
  164. package/dist/core/context-settings.d.ts +32 -0
  165. package/dist/core/context-settings.js +41 -3
  166. package/dist/core/contract-faces.d.ts +22 -0
  167. package/dist/core/contract-faces.js +1 -0
  168. package/dist/core/credential-echo.d.ts +2 -2
  169. package/dist/core/credential-echo.js +2 -2
  170. package/dist/core/cross-boundary-taint.d.ts +10 -8
  171. package/dist/core/decision-receipt.d.ts +3 -2
  172. package/dist/core/decision-receipt.js +1 -1
  173. package/dist/core/definition-entry-grammar.d.ts +42 -0
  174. package/dist/core/definition-entry-grammar.js +15 -0
  175. package/dist/core/engine-attestation.d.ts +19 -4
  176. package/dist/core/engine-attestation.js +4 -0
  177. package/dist/core/engine-capabilities.d.ts +8 -1
  178. package/dist/core/engine-capabilities.js +1 -1
  179. package/dist/core/engine-contracts/open-face-contract.d.ts +39 -0
  180. package/dist/core/engine-contracts/open-face-contract.js +57 -0
  181. package/dist/core/engine-notice.d.ts +164 -33
  182. package/dist/core/exclusive-temp.d.ts +25 -0
  183. package/dist/core/exclusive-temp.js +19 -0
  184. package/dist/core/existing-target.d.ts +112 -0
  185. package/dist/core/existing-target.js +88 -0
  186. package/dist/core/file-history-store.d.ts +14 -6
  187. package/dist/core/gate-lanes.js +8 -3
  188. package/dist/core/gate-outcome.d.ts +2 -1
  189. package/dist/core/git-worktree-env.d.ts +92 -1
  190. package/dist/core/git-worktree-env.js +87 -6
  191. package/dist/core/governance-codes.d.ts +49 -8
  192. package/dist/core/governance-codes.js +59 -8
  193. package/dist/core/hands-band.d.ts +10 -6
  194. package/dist/core/hooks.d.ts +60 -6
  195. package/dist/core/hooks.js +10 -2
  196. package/dist/core/host-floor.d.ts +24 -8
  197. package/dist/core/host-floor.js +45 -16
  198. package/dist/core/human-input-projection.d.ts +7 -0
  199. package/dist/core/human-input-projection.js +11 -3
  200. package/dist/core/image-admission.d.ts +16 -4
  201. package/dist/core/image-admission.js +29 -17
  202. package/dist/core/input-author.d.ts +43 -1
  203. package/dist/core/input-author.js +19 -0
  204. package/dist/core/isolation-scope.d.ts +41 -0
  205. package/dist/core/isolation-scope.js +10 -0
  206. package/dist/core/json-schema-seats.d.ts +11 -0
  207. package/dist/core/json-schema-seats.js +5 -0
  208. package/dist/core/leg-identity.d.ts +53 -5
  209. package/dist/core/leg-identity.js +32 -1
  210. package/dist/core/locked-config.d.ts +33 -38
  211. package/dist/core/locked-config.js +21 -3
  212. package/dist/core/lsp.js +2 -1
  213. package/dist/core/mailbox-store.d.ts +111 -18
  214. package/dist/core/mailbox-store.js +101 -13
  215. package/dist/core/mcp-call-meta.js +1 -1
  216. package/dist/core/mcp-connection-pool.d.ts +8 -2
  217. package/dist/core/mcp-connection-pool.js +3 -1
  218. package/dist/core/mcp-failure.d.ts +6 -1
  219. package/dist/core/mcp-failure.js +10 -0
  220. package/dist/core/mcp-host-read.d.ts +293 -0
  221. package/dist/core/mcp-host-read.js +428 -0
  222. package/dist/core/mcp-server-link.d.ts +28 -6
  223. package/dist/core/mcp-server-link.js +35 -7
  224. package/dist/core/mcp-server-spec.d.ts +22 -29
  225. package/dist/core/mcp-server-spec.js +7 -14
  226. package/dist/core/mcp-server-unavailable-notice.d.ts +32 -0
  227. package/dist/core/mcp-server-unavailable-notice.js +15 -0
  228. package/dist/core/mcp-session-end.d.ts +5 -2
  229. package/dist/core/mcp-session-end.js +7 -2
  230. package/dist/core/mcp-tool-meta.d.ts +6 -0
  231. package/dist/core/mcp-tool-meta.js +1 -0
  232. package/dist/core/mcp.d.ts +54 -19
  233. package/dist/core/mcp.js +194 -241
  234. package/dist/core/memory-engine/committed-shadow-read.d.ts +16 -0
  235. package/dist/core/memory-engine/committed-shadow-read.js +21 -0
  236. package/dist/core/memory-engine/consolidation-driver.js +2 -1
  237. package/dist/core/memory-engine/consolidation.d.ts +3 -3
  238. package/dist/core/memory-engine/control-objects.d.ts +4 -3
  239. package/dist/core/memory-engine/control-objects.js +6 -4
  240. package/dist/core/memory-engine/delegation-settlement.d.ts +127 -25
  241. package/dist/core/memory-engine/delegation-settlement.js +145 -18
  242. package/dist/core/memory-engine/distiller.d.ts +2 -1
  243. package/dist/core/memory-engine/distiller.js +10 -5
  244. package/dist/core/memory-engine/dual-root.js +2 -2
  245. package/dist/core/memory-engine/engine.d.ts +127 -33
  246. package/dist/core/memory-engine/engine.js +774 -323
  247. package/dist/core/memory-engine/entry-scan.d.ts +3 -0
  248. package/dist/core/memory-engine/entry-scan.js +8 -0
  249. package/dist/core/memory-engine/export-bundle.d.ts +4 -0
  250. package/dist/core/memory-engine/export-bundle.js +2 -0
  251. package/dist/core/memory-engine/file-backend.d.ts +62 -17
  252. package/dist/core/memory-engine/file-backend.js +155 -99
  253. package/dist/core/memory-engine/index.d.ts +1 -1
  254. package/dist/core/memory-engine/index.js +1 -1
  255. package/dist/core/memory-engine/layer-observations.d.ts +7 -1
  256. package/dist/core/memory-engine/layer-observations.js +6 -0
  257. package/dist/core/memory-engine/layout.d.ts +88 -26
  258. package/dist/core/memory-engine/layout.js +105 -29
  259. package/dist/core/memory-engine/memory-deployment.js +4 -4
  260. package/dist/core/memory-engine/mount-failed-notice.d.ts +24 -0
  261. package/dist/core/memory-engine/mount-failed-notice.js +22 -0
  262. package/dist/core/memory-engine/origin-clearance.d.ts +15 -1
  263. package/dist/core/memory-engine/origin-clearance.js +30 -10
  264. package/dist/core/memory-engine/scan.js +1 -1
  265. package/dist/core/memory-engine/scope-contract.js +4 -3
  266. package/dist/core/memory-engine/session-write-home.js +13 -1
  267. package/dist/core/memory-engine/sync-client.d.ts +1 -1
  268. package/dist/core/memory-engine/sync-client.js +3 -1
  269. package/dist/core/memory-engine/tools.d.ts +5 -4
  270. package/dist/core/memory-engine/tools.js +1 -1
  271. package/dist/core/memory-engine/types.d.ts +18 -1
  272. package/dist/core/memory-engine/types.js +1 -0
  273. package/dist/core/memory.d.ts +1 -1
  274. package/dist/core/memory.js +2 -6
  275. package/dist/core/mode-policy.d.ts +8 -1
  276. package/dist/core/mode-policy.js +6 -2
  277. package/dist/core/model-fallbacks.d.ts +105 -0
  278. package/dist/core/model-fallbacks.js +79 -0
  279. package/dist/core/model-receipt.d.ts +15 -3
  280. package/dist/core/model-receipt.js +22 -1
  281. package/dist/core/model-seat.d.ts +1 -1
  282. package/dist/core/mods/classic-events.d.ts +5 -1
  283. package/dist/core/mods/dollar.d.ts +47 -2
  284. package/dist/core/mods/dollar.js +28 -5
  285. package/dist/core/mods/kernel/budget.d.ts +6 -0
  286. package/dist/core/mods/kernel/budget.js +6 -0
  287. package/dist/core/mods/kernel/dispatch.d.ts +23 -2
  288. package/dist/core/mods/kernel/dispatch.js +104 -15
  289. package/dist/core/mods/kernel/events.d.ts +18 -1
  290. package/dist/core/mods/kernel/events.js +7 -6
  291. package/dist/core/mods/kernel/index.d.ts +2 -2
  292. package/dist/core/mods/kernel/index.js +1 -1
  293. package/dist/core/mods/kernel/receive.d.ts +2 -1
  294. package/dist/core/mods/lifecycle-stations.d.ts +13 -4
  295. package/dist/core/mods/lifecycle-stations.js +8 -3
  296. package/dist/core/mods/message-display.d.ts +81 -0
  297. package/dist/core/mods/message-display.js +369 -0
  298. package/dist/core/mods/prompt-submit.d.ts +1 -1
  299. package/dist/core/mods/prompt-submit.js +5 -2
  300. package/dist/core/mods/session-append.d.ts +2 -2
  301. package/dist/core/mods/session-append.js +2 -1
  302. package/dist/core/mods/session-compact.js +2 -2
  303. package/dist/core/mods/stations.d.ts +48 -18
  304. package/dist/core/mods/stations.js +100 -19
  305. package/dist/core/mods/stop-answers.d.ts +23 -0
  306. package/dist/core/mods/stop-answers.js +20 -0
  307. package/dist/core/mounted-mcp.d.ts +48 -8
  308. package/dist/core/mounted-mcp.js +82 -16
  309. package/dist/core/namespaced-rule-name.js +2 -1
  310. package/dist/core/own-property-receipt.js +3 -5
  311. package/dist/core/parent-spec-seat.d.ts +20 -1
  312. package/dist/core/parent-spec-seat.js +13 -3
  313. package/dist/core/park-selfcheck.js +1 -0
  314. package/dist/core/path-identity.js +2 -1
  315. package/dist/core/peer-seat.d.ts +21 -7
  316. package/dist/core/peer-seat.js +25 -16
  317. package/dist/core/permission-rule-consent.js +15 -5
  318. package/dist/core/permission-rule-model.d.ts +4 -2
  319. package/dist/core/permission-rule-model.js +43 -23
  320. package/dist/core/permission-rule-store.d.ts +31 -16
  321. package/dist/core/permission-rule-store.js +27 -18
  322. package/dist/core/present-plan-tool.d.ts +6 -1
  323. package/dist/core/present-plan-tool.js +11 -3
  324. package/dist/core/pricing.d.ts +8 -6
  325. package/dist/core/pricing.js +1 -1
  326. package/dist/core/principal-name.d.ts +13 -0
  327. package/dist/core/principal-name.js +9 -2
  328. package/dist/core/process-identity.d.ts +140 -0
  329. package/dist/core/process-identity.js +215 -0
  330. package/dist/core/protocol-http-auth.d.ts +28 -6
  331. package/dist/core/protocol-http-auth.js +22 -5
  332. package/dist/core/protocol-naming.d.ts +7 -0
  333. package/dist/core/protocol-naming.js +12 -2
  334. package/dist/core/protocol-revocation.d.ts +72 -0
  335. package/dist/core/protocol-revocation.js +98 -0
  336. package/dist/core/protocol-table.d.ts +4 -4
  337. package/dist/core/protocol-table.js +3 -2
  338. package/dist/core/push-queue.d.ts +35 -2
  339. package/dist/core/push-queue.js +60 -4
  340. package/dist/core/read-only-shell.d.ts +19 -0
  341. package/dist/core/read-only-shell.js +38 -11
  342. package/dist/core/real-approval.d.ts +26 -0
  343. package/dist/core/real-approval.js +15 -0
  344. package/dist/core/redaction-marks.d.ts +6 -2
  345. package/dist/core/redaction-marks.js +3 -0
  346. package/dist/core/reminder-mint.d.ts +6 -0
  347. package/dist/core/reminder-mint.js +9 -8
  348. package/dist/core/remote-env.d.ts +31 -15
  349. package/dist/core/remote-env.js +29 -0
  350. package/dist/core/request-copy-projection.d.ts +51 -0
  351. package/dist/core/request-copy-projection.js +410 -0
  352. package/dist/core/resume-config-judge.d.ts +69 -0
  353. package/dist/core/resume-config-judge.js +78 -0
  354. package/dist/core/resume-startup-cause.d.ts +14 -4
  355. package/dist/core/resume-startup-cause.js +12 -2
  356. package/dist/core/retention-policy.js +2 -1
  357. package/dist/core/retention.d.ts +119 -24
  358. package/dist/core/retention.js +60 -16
  359. package/dist/core/retired-keys.d.ts +0 -10
  360. package/dist/core/retired-keys.js +2 -3
  361. package/dist/core/roles.d.ts +24 -25
  362. package/dist/core/roles.js +148 -21
  363. package/dist/core/row-shape.d.ts +149 -0
  364. package/dist/core/row-shape.js +184 -0
  365. package/dist/core/runner/advertised-writable-dirs.js +10 -9
  366. package/dist/core/runner/advisor-instructions.d.ts +11 -27
  367. package/dist/core/runner/advisor-instructions.js +18 -20
  368. package/dist/core/runner/advisor-tool.js +1 -0
  369. package/dist/core/runner/announce-once-ledger.js +4 -1
  370. package/dist/core/runner/approval-feedback.d.ts +17 -8
  371. package/dist/core/runner/approval-feedback.js +18 -13
  372. package/dist/core/runner/approver-defect-announcer.d.ts +17 -0
  373. package/dist/core/runner/approver-defect-announcer.js +22 -0
  374. package/dist/core/runner/assemble-result.d.ts +29 -14
  375. package/dist/core/runner/assemble-result.js +16 -25
  376. package/dist/core/runner/cache-hit-account.d.ts +77 -0
  377. package/dist/core/runner/cache-hit-account.js +46 -0
  378. package/dist/core/runner/call-hook-stations.d.ts +3 -2
  379. package/dist/core/runner/call-hook-stations.js +5 -4
  380. package/dist/core/runner/changed-files-scan.d.ts +43 -0
  381. package/dist/core/runner/changed-files-scan.js +34 -0
  382. package/dist/core/runner/checkpoint-scope.d.ts +33 -9
  383. package/dist/core/runner/checkpoint-scope.js +27 -1
  384. package/dist/core/runner/classifier-ladder.d.ts +2 -2
  385. package/dist/core/runner/classifier-ladder.js +18 -9
  386. package/dist/core/runner/clock-and-limits.d.ts +15 -4
  387. package/dist/core/runner/clock-and-limits.js +19 -1
  388. package/dist/core/runner/compact-session.js +84 -14
  389. package/dist/core/runner/compaction-call-options.d.ts +2 -29
  390. package/dist/core/runner/compaction-call-options.js +2 -9
  391. package/dist/core/runner/compaction-restate.d.ts +18 -2
  392. package/dist/core/runner/compaction-restate.js +36 -2
  393. package/dist/core/runner/construction-doors.js +8 -0
  394. package/dist/core/runner/context-room.d.ts +55 -0
  395. package/dist/core/runner/context-room.js +71 -0
  396. package/dist/core/runner/contracts.d.ts +313 -205
  397. package/dist/core/runner/conversation-segment.d.ts +49 -14
  398. package/dist/core/runner/conversation-segment.js +92 -19
  399. package/dist/core/runner/cross-boundary-lane.d.ts +4 -0
  400. package/dist/core/runner/cross-boundary-lane.js +9 -6
  401. package/dist/core/runner/decide-continuation.js +1 -1
  402. package/dist/core/runner/deferred-ask.d.ts +62 -0
  403. package/dist/core/runner/deferred-ask.js +44 -0
  404. package/dist/core/runner/delegation-owner.d.ts +19 -0
  405. package/dist/core/runner/delegation-owner.js +27 -1
  406. package/dist/core/runner/denial-limit-arms.d.ts +10 -6
  407. package/dist/core/runner/denial-limit-arms.js +13 -7
  408. package/dist/core/runner/env-capability-census.d.ts +1 -1
  409. package/dist/core/runner/file-history-request.js +2 -1
  410. package/dist/core/runner/file-history-restore.d.ts +16 -2
  411. package/dist/core/runner/file-history-restore.js +9 -1
  412. package/dist/core/runner/gate-exit.d.ts +18 -5
  413. package/dist/core/runner/gate-exit.js +26 -15
  414. package/dist/core/runner/git-status-frame.d.ts +26 -8
  415. package/dist/core/runner/git-status-frame.js +14 -9
  416. package/dist/core/runner/halt-attribution.d.ts +29 -12
  417. package/dist/core/runner/halt-attribution.js +38 -11
  418. package/dist/core/runner/image.js +3 -2
  419. package/dist/core/runner/initial-run-state.d.ts +1 -1
  420. package/dist/core/runner/initial-run-state.js +4 -4
  421. package/dist/core/runner/language-frame.d.ts +66 -0
  422. package/dist/core/runner/language-frame.js +76 -0
  423. package/dist/core/runner/leg-frame.d.ts +81 -0
  424. package/dist/core/runner/leg-frame.js +68 -0
  425. package/dist/core/runner/main-call-account.d.ts +34 -0
  426. package/dist/core/runner/main-call-account.js +50 -0
  427. package/dist/core/runner/mcp-redial.d.ts +9 -7
  428. package/dist/core/runner/mcp-redial.js +20 -21
  429. package/dist/core/runner/memory-consolidation-driver.d.ts +2 -0
  430. package/dist/core/runner/memory-consolidation-driver.js +5 -3
  431. package/dist/core/runner/messages-omitted-seat.d.ts +2 -0
  432. package/dist/core/runner/messages-omitted-seat.js +21 -0
  433. package/dist/core/runner/model-fallback-seat.d.ts +23 -0
  434. package/dist/core/runner/model-fallback-seat.js +64 -0
  435. package/dist/core/runner/model-lane-seat.d.ts +12 -0
  436. package/dist/core/runner/model-lane-seat.js +35 -0
  437. package/dist/core/runner/nested-memory-content.d.ts +33 -0
  438. package/dist/core/runner/nested-memory-content.js +171 -0
  439. package/dist/core/runner/nested-memory-lane.d.ts +181 -0
  440. package/dist/core/runner/nested-memory-lane.js +673 -0
  441. package/dist/core/runner/park-commit.d.ts +7 -0
  442. package/dist/core/runner/park-commit.js +3 -0
  443. package/dist/core/runner/prepare-advisor.d.ts +7 -9
  444. package/dist/core/runner/prepare-advisor.js +11 -5
  445. package/dist/core/runner/prepare-artifact.d.ts +1 -1
  446. package/dist/core/runner/prepare-artifact.js +8 -3
  447. package/dist/core/runner/prepare-ask-lane.d.ts +21 -3
  448. package/dist/core/runner/prepare-ask-lane.js +32 -28
  449. package/dist/core/runner/prepare-boundary-parks.d.ts +2 -2
  450. package/dist/core/runner/prepare-boundary-parks.js +21 -17
  451. package/dist/core/runner/prepare-caps-and-workflow.d.ts +10 -2
  452. package/dist/core/runner/prepare-caps-and-workflow.js +24 -18
  453. package/dist/core/runner/prepare-config-doors.d.ts +51 -5
  454. package/dist/core/runner/prepare-config-doors.js +73 -73
  455. package/dist/core/runner/prepare-context-lane.d.ts +68 -3
  456. package/dist/core/runner/prepare-context-lane.js +137 -27
  457. package/dist/core/runner/prepare-defer-classify.d.ts +0 -4
  458. package/dist/core/runner/prepare-defer-classify.js +9 -13
  459. package/dist/core/runner/prepare-delegation-surface.d.ts +8 -8
  460. package/dist/core/runner/prepare-delegation-surface.js +72 -64
  461. package/dist/core/runner/prepare-execution-env.js +1 -9
  462. package/dist/core/runner/prepare-file-history.d.ts +3 -2
  463. package/dist/core/runner/prepare-file-history.js +11 -4
  464. package/dist/core/runner/prepare-gate-stations.d.ts +21 -11
  465. package/dist/core/runner/prepare-gate-stations.js +13 -13
  466. package/dist/core/runner/prepare-hands-readface.d.ts +23 -6
  467. package/dist/core/runner/prepare-hands-readface.js +18 -12
  468. package/dist/core/runner/prepare-inherited-gate.d.ts +12 -5
  469. package/dist/core/runner/prepare-inherited-gate.js +14 -10
  470. package/dist/core/runner/prepare-lsp.js +2 -1
  471. package/dist/core/runner/prepare-memory-engine-session.js +30 -10
  472. package/dist/core/runner/prepare-memory.d.ts +4 -0
  473. package/dist/core/runner/prepare-memory.js +38 -16
  474. package/dist/core/runner/prepare-offload-wrappers.d.ts +3 -16
  475. package/dist/core/runner/prepare-offload-wrappers.js +6 -5
  476. package/dist/core/runner/prepare-park-ask.d.ts +11 -3
  477. package/dist/core/runner/prepare-park-ask.js +23 -19
  478. package/dist/core/runner/prepare-policy-chain.d.ts +17 -3
  479. package/dist/core/runner/prepare-policy-chain.js +144 -120
  480. package/dist/core/runner/prepare-project-context.d.ts +15 -53
  481. package/dist/core/runner/prepare-project-context.js +20 -83
  482. package/dist/core/runner/prepare-prompt-assembly.d.ts +7 -1
  483. package/dist/core/runner/prepare-prompt-assembly.js +9 -7
  484. package/dist/core/runner/prepare-prompt-inputs.d.ts +9 -3
  485. package/dist/core/runner/prepare-prompt-inputs.js +5 -3
  486. package/dist/core/runner/prepare-protocol-tools.d.ts +9 -4
  487. package/dist/core/runner/prepare-protocol-tools.js +46 -27
  488. package/dist/core/runner/prepare-question-face.d.ts +6 -5
  489. package/dist/core/runner/prepare-question-face.js +7 -6
  490. package/dist/core/runner/prepare-suspend-saga.d.ts +3 -0
  491. package/dist/core/runner/prepare-suspend-saga.js +1 -1
  492. package/dist/core/runner/prepare-task.d.ts +3 -3
  493. package/dist/core/runner/prepare-task.js +113 -61
  494. package/dist/core/runner/prepare-tool-disclosure-mount.js +6 -5
  495. package/dist/core/runner/prepare-turn-wiring.d.ts +33 -7
  496. package/dist/core/runner/prepare-turn-wiring.js +53 -17
  497. package/dist/core/runner/prepare-wiring-manifest.d.ts +42 -5
  498. package/dist/core/runner/prepare-wiring-manifest.js +81 -42
  499. package/dist/core/runner/prepare-workspace-restore.js +3 -2
  500. package/dist/core/runner/read-root-grant.js +2 -1
  501. package/dist/core/runner/reply-pricing.d.ts +31 -18
  502. package/dist/core/runner/reply-pricing.js +10 -15
  503. package/dist/core/runner/resume-admission.js +10 -15
  504. package/dist/core/runner/resume-apply.js +20 -9
  505. package/dist/core/runner/resume-checkpoint-screen.js +2 -4
  506. package/dist/core/runner/resume-internals-and-config.d.ts +12 -9
  507. package/dist/core/runner/resume-internals-and-config.js +37 -9
  508. package/dist/core/runner/resume-preflight.js +3 -3
  509. package/dist/core/runner/retired-runner-deps.js +3 -0
  510. package/dist/core/runner/rewind-files.js +6 -6
  511. package/dist/core/runner/run-attachment-seats.d.ts +1 -3
  512. package/dist/core/runner/run-attachment-seats.js +1 -6
  513. package/dist/core/runner/run-brain-sinks.d.ts +4 -7
  514. package/dist/core/runner/run-brain-sinks.js +7 -10
  515. package/dist/core/runner/run-clock-and-content.d.ts +8 -5
  516. package/dist/core/runner/run-clock-and-content.js +18 -3
  517. package/dist/core/runner/run-compaction-machinery.d.ts +8 -4
  518. package/dist/core/runner/run-compaction-machinery.js +4 -19
  519. package/dist/core/runner/run-git-lane.d.ts +8 -3
  520. package/dist/core/runner/run-git-lane.js +5 -3
  521. package/dist/core/runner/run-harness-handlers.d.ts +4 -1
  522. package/dist/core/runner/run-harness-handlers.js +70 -45
  523. package/dist/core/runner/run-identity-wiring.d.ts +6 -0
  524. package/dist/core/runner/run-identity-wiring.js +17 -8
  525. package/dist/core/runner/run-leg.d.ts +5 -2
  526. package/dist/core/runner/run-leg.js +156 -71
  527. package/dist/core/runner/run-notification-lane.d.ts +1 -1
  528. package/dist/core/runner/run-notification-lane.js +22 -10
  529. package/dist/core/runner/run-recovery-lanes.js +8 -6
  530. package/dist/core/runner/run-settle-and-teardown.d.ts +4 -0
  531. package/dist/core/runner/run-settle-and-teardown.js +77 -26
  532. package/dist/core/runner/run-stop-and-final-verify.js +46 -12
  533. package/dist/core/runner/run-telemetry-and-budget-seats.js +19 -28
  534. package/dist/core/runner/run-terminal-adoption.d.ts +2 -2
  535. package/dist/core/runner/run-terminal-adoption.js +14 -9
  536. package/dist/core/runner/run-tool-mount-facts.js +5 -9
  537. package/dist/core/runner/run-turn-boundary.d.ts +3 -2
  538. package/dist/core/runner/run-turn-boundary.js +112 -106
  539. package/dist/core/runner/runtask.d.ts +28 -8
  540. package/dist/core/runner/runtask.js +132 -41
  541. package/dist/core/runner/session-file-state-replay.d.ts +5 -3
  542. package/dist/core/runner/session-file-state-replay.js +10 -3
  543. package/dist/core/runner/session-rule-policy.d.ts +3 -3
  544. package/dist/core/runner/session-verb-doors.d.ts +18 -3
  545. package/dist/core/runner/session-verb-doors.js +38 -6
  546. package/dist/core/runner/shell-env-withheld.d.ts +8 -5
  547. package/dist/core/runner/shell-env-withheld.js +4 -4
  548. package/dist/core/runner/side-call-account.d.ts +12 -8
  549. package/dist/core/runner/side-call-account.js +24 -15
  550. package/dist/core/runner/stream-halt-verbs.js +1 -0
  551. package/dist/core/runner/stream-mode-verb.js +2 -1
  552. package/dist/core/runner/stream-settle-backstop.js +4 -1
  553. package/dist/core/runner/stream-steer-verb.js +35 -19
  554. package/dist/core/runner/sub-agent-deny-lists.d.ts +47 -11
  555. package/dist/core/runner/sub-agent-deny-lists.js +140 -39
  556. package/dist/core/runner/teardown-bounded.d.ts +6 -0
  557. package/dist/core/runner/teardown-bounded.js +12 -7
  558. package/dist/core/runner/terminal-account.d.ts +2 -0
  559. package/dist/core/runner/terminal-account.js +6 -1
  560. package/dist/core/runner/tool-disclosure.js +2 -1
  561. package/dist/core/runner/tool-end-body.js +3 -1
  562. package/dist/core/runner/tool-face-overlay.d.ts +1 -1
  563. package/dist/core/runner/tool-face-overlay.js +1 -1
  564. package/dist/core/runner/tool-occurrence.d.ts +34 -9
  565. package/dist/core/runner/tool-occurrence.js +32 -21
  566. package/dist/core/runner/tool-progress-lane.d.ts +20 -5
  567. package/dist/core/runner/tool-progress-lane.js +27 -5
  568. package/dist/core/runner/tool-result-media-seat.d.ts +15 -4
  569. package/dist/core/runner/tool-result-media-seat.js +17 -1
  570. package/dist/core/runner/tool-table-view.js +1 -1
  571. package/dist/core/runner/turn-attachments.d.ts +44 -71
  572. package/dist/core/runner/turn-attachments.js +52 -104
  573. package/dist/core/runner/usage-accounting.d.ts +3 -2
  574. package/dist/core/runner/usage-accounting.js +3 -2
  575. package/dist/core/runner/void-verifier-pause.js +1 -1
  576. package/dist/core/runner-deps.d.ts +42 -158
  577. package/dist/core/runtime-caps.d.ts +16 -4
  578. package/dist/core/secret-env.d.ts +20 -3
  579. package/dist/core/secret-env.js +46 -23
  580. package/dist/core/sensitive-path-policy.d.ts +8 -0
  581. package/dist/core/sensitive-path-policy.js +10 -2
  582. package/dist/core/session-checkout.d.ts +32 -27
  583. package/dist/core/session-checkout.js +109 -61
  584. package/dist/core/session-log-transfer.js +2 -1
  585. package/dist/core/session-policy-store.d.ts +24 -11
  586. package/dist/core/session-policy-store.js +11 -2
  587. package/dist/core/session-store.d.ts +16 -2
  588. package/dist/core/session-store.js +43 -17
  589. package/dist/core/session.d.ts +31 -3
  590. package/dist/core/session.js +33 -2
  591. package/dist/core/shell-run-candidates.d.ts +20 -8
  592. package/dist/core/shell-run-candidates.js +44 -21
  593. package/dist/core/side-query.d.ts +17 -5
  594. package/dist/core/side-query.js +17 -14
  595. package/dist/core/skill-grant.js +2 -3
  596. package/dist/core/skills-directory.js +3 -66
  597. package/dist/core/snapshot-frame-seat.d.ts +8 -0
  598. package/dist/core/snapshot-frame-seat.js +24 -0
  599. package/dist/core/steer-replay.d.ts +19 -3
  600. package/dist/core/steer-replay.js +8 -1
  601. package/dist/core/store-contracts/background-agent-store-contract.d.ts +17 -2
  602. package/dist/core/store-contracts/background-agent-store-contract.js +131 -2
  603. package/dist/core/store-contracts/checkpoint-store-contract.js +63 -1
  604. package/dist/core/store-contracts/mailbox-store-contract.d.ts +15 -2
  605. package/dist/core/store-contracts/mailbox-store-contract.js +213 -3
  606. package/dist/core/store-contracts/permission-rule-write-contract.js +24 -0
  607. package/dist/core/store-contracts/session-deletion-cascade-contract.d.ts +15 -0
  608. package/dist/core/store-contracts/session-deletion-cascade-contract.js +288 -0
  609. package/dist/core/store-contracts/session-policy-store-contract.js +57 -36
  610. package/dist/core/store-contracts/session-repo-contract.js +130 -5
  611. package/dist/core/store-contracts/session-store-contract.d.ts +1 -1
  612. package/dist/core/store-contracts/session-store-contract.js +17 -0
  613. package/dist/core/store-contracts/task-list-store-contract.d.ts +32 -0
  614. package/dist/core/store-contracts/task-list-store-contract.js +240 -0
  615. package/dist/core/store-contracts/tool-result-store-contract.d.ts +1 -1
  616. package/dist/core/store-contracts/tool-result-store-contract.js +41 -0
  617. package/dist/core/stub-env.d.ts +2 -2
  618. package/dist/core/stub-env.js +1 -0
  619. package/dist/core/synthetic-read-verdict.d.ts +38 -28
  620. package/dist/core/synthetic-read-verdict.js +19 -28
  621. package/dist/core/task-event.d.ts +171 -19
  622. package/dist/core/task-intake.d.ts +26 -0
  623. package/dist/core/task-intake.js +31 -0
  624. package/dist/core/task-limits.d.ts +8 -6
  625. package/dist/core/task-notification.d.ts +88 -8
  626. package/dist/core/task-notification.js +45 -5
  627. package/dist/core/task-registry-agent.d.ts +24 -7
  628. package/dist/core/task-registry-agent.js +51 -28
  629. package/dist/core/task-registry-monitor.js +16 -14
  630. package/dist/core/task-registry-shared.d.ts +177 -35
  631. package/dist/core/task-registry-shared.js +44 -17
  632. package/dist/core/task-registry-workflow.js +8 -5
  633. package/dist/core/task-registry-yield.d.ts +32 -0
  634. package/dist/core/task-registry-yield.js +85 -0
  635. package/dist/core/task-registry.d.ts +88 -10
  636. package/dist/core/task-registry.js +124 -33
  637. package/dist/core/task-result.d.ts +126 -31
  638. package/dist/core/task-spec-members.d.ts +140 -1
  639. package/dist/core/task-spec-members.js +23 -8
  640. package/dist/core/task-spec.d.ts +181 -51
  641. package/dist/core/task-spec.js +1 -1
  642. package/dist/core/task-stream.d.ts +12 -2
  643. package/dist/core/terminal-cause.d.ts +12 -4
  644. package/dist/core/thrown-value.d.ts +49 -7
  645. package/dist/core/thrown-value.js +38 -2
  646. package/dist/core/tool-catalog-entries.js +13 -3
  647. package/dist/core/tool-data-door.d.ts +7 -0
  648. package/dist/core/tool-data-door.js +13 -0
  649. package/dist/core/tool-face-lists.d.ts +25 -0
  650. package/dist/core/tool-face-lists.js +38 -0
  651. package/dist/core/tool-face-reader.d.ts +0 -10
  652. package/dist/core/tool-face-reader.js +5 -3
  653. package/dist/core/tool-list-grammar.d.ts +103 -0
  654. package/dist/core/tool-list-grammar.js +130 -0
  655. package/dist/core/tool-mount-facts.d.ts +47 -0
  656. package/dist/core/tool-mount-facts.js +50 -0
  657. package/dist/core/tool-mount-plan.d.ts +196 -0
  658. package/dist/core/tool-mount-plan.js +404 -0
  659. package/dist/core/tool-mount-static.d.ts +12 -0
  660. package/dist/core/tool-mount-static.js +174 -0
  661. package/dist/core/tool-name-aliases.d.ts +60 -2
  662. package/dist/core/tool-name-aliases.js +22 -2
  663. package/dist/core/tool-name-list.d.ts +3 -0
  664. package/dist/core/tool-name-readings.d.ts +4 -0
  665. package/dist/core/tool-name-readings.js +1 -0
  666. package/dist/core/tool-policy.d.ts +246 -51
  667. package/dist/core/tool-policy.js +165 -71
  668. package/dist/core/tool-registry.d.ts +4 -11
  669. package/dist/core/tool-registry.js +0 -3
  670. package/dist/core/tool-result-bytes.d.ts +94 -0
  671. package/dist/core/tool-result-bytes.js +34 -0
  672. package/dist/core/tool-result-store.d.ts +97 -13
  673. package/dist/core/tool-result-store.js +52 -4
  674. package/dist/core/tool-roster.d.ts +71 -10
  675. package/dist/core/tool-roster.js +71 -21
  676. package/dist/core/tool-search-setting.d.ts +7 -9
  677. package/dist/core/tool-search-setting.js +23 -7
  678. package/dist/core/tool-spec.d.ts +32 -2
  679. package/dist/core/tools.js +6 -20
  680. package/dist/core/trace.d.ts +63 -11
  681. package/dist/core/trace.js +19 -0
  682. package/dist/core/types.d.ts +8 -6
  683. package/dist/core/types.js +3 -1
  684. package/dist/core/unmatched-tool-names.d.ts +37 -0
  685. package/dist/core/unmatched-tool-names.js +18 -0
  686. package/dist/core/untrusted-egress.d.ts +16 -5
  687. package/dist/core/untrusted-egress.js +202 -32
  688. package/dist/core/untrusted-text.d.ts +29 -8
  689. package/dist/core/untrusted-text.js +6 -3
  690. package/dist/core/user-attachment.d.ts +129 -35
  691. package/dist/core/user-attachment.js +124 -57
  692. package/dist/core/user-row-origin.d.ts +63 -0
  693. package/dist/core/user-row-origin.js +61 -0
  694. package/dist/core/wiring-manifest.d.ts +161 -39
  695. package/dist/core/wiring-manifest.js +42 -6
  696. package/dist/core/workflow-run-store-contract.d.ts +11 -1
  697. package/dist/core/workflow-run-store-contract.js +60 -7
  698. package/dist/core/workflow-run-store.d.ts +61 -12
  699. package/dist/core/workflow-run-store.js +100 -15
  700. package/dist/core/workspace-snapshot.d.ts +10 -14
  701. package/dist/core/workspace-snapshot.js +3 -22
  702. package/dist/core/write-protect.d.ts +3 -5
  703. package/dist/core/write-protect.js +2 -4
  704. package/dist/engine/compaction/compaction.d.ts +3 -0
  705. package/dist/engine/compaction/compaction.js +4 -3
  706. package/dist/engine/execution-env/node-execution-env.d.ts +15 -4
  707. package/dist/engine/execution-env/node-execution-env.js +80 -27
  708. package/dist/engine/harness/agent-harness.d.ts +143 -27
  709. package/dist/engine/harness/agent-harness.js +162 -74
  710. package/dist/engine/harness/types.d.ts +84 -13
  711. package/dist/engine/harness/types.js +21 -1
  712. package/dist/engine/llm/tool-turns.d.ts +4 -0
  713. package/dist/engine/llm/tool-turns.js +7 -2
  714. package/dist/engine/llm/types.d.ts +111 -24
  715. package/dist/engine/llm/types.js +69 -5
  716. package/dist/engine/llm/validation.js +2 -1
  717. package/dist/engine/loop/agent-loop.d.ts +39 -6
  718. package/dist/engine/loop/agent-loop.js +172 -82
  719. package/dist/engine/loop/types.d.ts +43 -4
  720. package/dist/engine/lsp/node-lsp-manager.d.ts +5 -3
  721. package/dist/engine/lsp/node-lsp-manager.js +14 -10
  722. package/dist/engine/session/import-validate.js +9 -0
  723. package/dist/engine/session/memory-repo.d.ts +8 -1
  724. package/dist/engine/session/memory-repo.js +20 -12
  725. package/dist/engine/session/repo-utils.d.ts +10 -0
  726. package/dist/engine/session/repo-utils.js +11 -5
  727. package/dist/engine/session/row-cells.d.ts +32 -0
  728. package/dist/engine/session/row-cells.js +25 -0
  729. package/dist/index.d.ts +64 -34
  730. package/dist/index.js +45 -21
  731. package/dist/internal/harness.d.ts +8 -6
  732. package/dist/internal/harness.js +6 -4
  733. package/dist/internal/llm.d.ts +2 -2
  734. package/dist/internal/llm.js +1 -1
  735. package/dist/orchestration/governance-baseline-validity.d.ts +7 -0
  736. package/dist/orchestration/governance-baseline-validity.js +33 -9
  737. package/dist/orchestration/run-workflow-tool.d.ts +2 -0
  738. package/dist/orchestration/run-workflow-tool.js +25 -12
  739. package/dist/orchestration/workflow-governance.d.ts +19 -4
  740. package/dist/orchestration/workflow-governance.js +30 -9
  741. package/dist/orchestration/workflow-primitives.d.ts +4 -1
  742. package/dist/orchestration/workflow-primitives.js +2 -2
  743. package/dist/orchestration/workflow-script-runner.d.ts +1 -1
  744. package/dist/orchestration/workflow-size-guideline.d.ts +1 -1
  745. package/dist/orchestration/workflow-types.d.ts +21 -12
  746. package/dist/orchestration/workflow-types.js +15 -4
  747. package/dist/orchestration/workflow.d.ts +37 -7
  748. package/dist/orchestration/workflow.js +81 -35
  749. package/dist/prompt-assembly/artifact-store.js +6 -9
  750. package/dist/prompt-assembly/assemble.d.ts +4 -10
  751. package/dist/prompt-assembly/assemble.js +1 -3
  752. package/dist/prompt-assembly/catalog/constitution.d.ts +0 -20
  753. package/dist/prompt-assembly/catalog/constitution.js +2 -0
  754. package/dist/prompt-assembly/catalog/core-behavior.js +5 -3
  755. package/dist/prompt-assembly/catalog/engine.d.ts +108 -0
  756. package/dist/prompt-assembly/catalog/engine.js +19 -0
  757. package/dist/prompt-assembly/catalog/environment.d.ts +276 -0
  758. package/dist/prompt-assembly/catalog/environment.js +61 -0
  759. package/dist/prompt-assembly/catalog/index.d.ts +9 -2
  760. package/dist/prompt-assembly/catalog/index.js +73 -2
  761. package/dist/prompt-assembly/catalog/locales/index.d.ts +16 -0
  762. package/dist/prompt-assembly/catalog/locales/index.js +22 -0
  763. package/dist/prompt-assembly/catalog/locales/zh-Hans/constitution.d.ts +7 -0
  764. package/dist/prompt-assembly/catalog/locales/zh-Hans/constitution.js +124 -0
  765. package/dist/prompt-assembly/catalog/locales/zh-Hans/core-behavior.d.ts +6 -0
  766. package/dist/prompt-assembly/catalog/locales/zh-Hans/core-behavior.js +120 -0
  767. package/dist/prompt-assembly/catalog/locales/zh-Hans/cowork.d.ts +8 -0
  768. package/dist/prompt-assembly/catalog/locales/zh-Hans/cowork.js +442 -0
  769. package/dist/prompt-assembly/catalog/locales/zh-Hans/engine.d.ts +7 -0
  770. package/dist/prompt-assembly/catalog/locales/zh-Hans/engine.js +15 -0
  771. package/dist/prompt-assembly/catalog/locales/zh-Hans/environment.d.ts +7 -0
  772. package/dist/prompt-assembly/catalog/locales/zh-Hans/environment.js +50 -0
  773. package/dist/prompt-assembly/catalog/locales/zh-Hans/modes.d.ts +7 -0
  774. package/dist/prompt-assembly/catalog/locales/zh-Hans/modes.js +163 -0
  775. package/dist/prompt-assembly/catalog/locales/zh-Hans/role.d.ts +7 -0
  776. package/dist/prompt-assembly/catalog/locales/zh-Hans/role.js +148 -0
  777. package/dist/prompt-assembly/catalog/locales/zh-Hans/team.d.ts +6 -0
  778. package/dist/prompt-assembly/catalog/locales/zh-Hans/team.js +246 -0
  779. package/dist/prompt-assembly/catalog/role.js +3 -6
  780. package/dist/prompt-assembly/catalog/schema.d.ts +23 -1
  781. package/dist/prompt-assembly/catalog/schema.js +2 -0
  782. package/dist/prompt-assembly/composer.d.ts +6 -11
  783. package/dist/prompt-assembly/composer.js +7 -7
  784. package/dist/prompt-assembly/engine-text.d.ts +9 -0
  785. package/dist/prompt-assembly/engine-text.js +33 -0
  786. package/dist/prompt-assembly/event-registry.js +3 -3
  787. package/dist/prompt-assembly/explain.d.ts +1 -0
  788. package/dist/prompt-assembly/explain.js +1 -1
  789. package/dist/prompt-assembly/locale-review.d.ts +13 -0
  790. package/dist/prompt-assembly/locale-review.js +19 -0
  791. package/dist/prompt-assembly/overlay.d.ts +7 -3
  792. package/dist/prompt-assembly/overlay.js +27 -5
  793. package/dist/prompt-assembly/renderers.d.ts +4 -4
  794. package/dist/prompt-assembly/renderers.js +26 -17
  795. package/dist/prompt-assembly/role-base.d.ts +1 -1
  796. package/dist/prompt-assembly/select.d.ts +26 -5
  797. package/dist/prompt-assembly/select.js +25 -2
  798. package/dist/prompt-assembly/slots.d.ts +19 -0
  799. package/dist/prompt-assembly/slots.js +16 -0
  800. package/dist/prompt-assembly/sugar.d.ts +4 -7
  801. package/dist/prompt-assembly/sugar.js +1 -2
  802. package/dist/prompt-assembly/tool-catalog.d.ts +5 -1
  803. package/dist/prompt-assembly/tool-catalog.js +5 -1
  804. package/dist/prompt-assembly/turn-snapshot.d.ts +38 -10
  805. package/dist/prompt-assembly/turn-snapshot.js +43 -13
  806. package/dist/prompt-assembly/types.d.ts +3 -0
  807. package/dist/prompts/cowork.d.ts +6 -25
  808. package/dist/prompts/cowork.js +10 -12
  809. package/dist/prompts/default.d.ts +10 -32
  810. package/dist/prompts/default.js +37 -63
  811. package/dist/shell/lex.d.ts +39 -13
  812. package/dist/shell/lex.js +70 -30
  813. package/dist/stores/file/background-agent-store.d.ts +5 -0
  814. package/dist/stores/file/background-agent-store.js +35 -61
  815. package/dist/stores/file/checkpoint-store.d.ts +5 -3
  816. package/dist/stores/file/checkpoint-store.js +8 -10
  817. package/dist/stores/file/fs-atomic.d.ts +27 -70
  818. package/dist/stores/file/fs-atomic.js +52 -148
  819. package/dist/stores/file/index.d.ts +12 -0
  820. package/dist/stores/file/index.js +27 -2
  821. package/dist/stores/file/mailbox-store.d.ts +10 -1
  822. package/dist/stores/file/mailbox-store.js +40 -12
  823. package/dist/stores/file/permission-rule-adopt.js +5 -2
  824. package/dist/stores/file/permission-rule-store.d.ts +81 -20
  825. package/dist/stores/file/permission-rule-store.js +126 -33
  826. package/dist/stores/file/session-policy-store.d.ts +2 -2
  827. package/dist/stores/file/session-store.d.ts +21 -2
  828. package/dist/stores/file/session-store.js +27 -14
  829. package/dist/stores/file/task-list-store.js +23 -25
  830. package/dist/stores/file/tool-result-store.d.ts +45 -7
  831. package/dist/stores/file/tool-result-store.js +99 -36
  832. package/dist/stores/file/workflow-run-store.d.ts +1 -0
  833. package/dist/stores/file/workflow-run-store.js +14 -11
  834. package/dist/tools/artifact/artifact-tool.js +2 -0
  835. package/dist/tools/artifact/local-stub.js +6 -6
  836. package/dist/tools/fs/bash-program-position.d.ts +1 -2
  837. package/dist/tools/fs/bash-readonly-classifier.d.ts +35 -0
  838. package/dist/tools/fs/bash-readonly-classifier.js +50 -12
  839. package/dist/tools/fs/env-error-detail.d.ts +1 -0
  840. package/dist/tools/fs/env-error-detail.js +7 -0
  841. package/dist/tools/fs/fs-bash.d.ts +24 -6
  842. package/dist/tools/fs/fs-bash.js +73 -25
  843. package/dist/tools/fs/fs-pdf.js +6 -4
  844. package/dist/tools/fs/fs-read.d.ts +76 -31
  845. package/dist/tools/fs/fs-read.js +159 -79
  846. package/dist/tools/fs/fs-search-tools.d.ts +1 -1
  847. package/dist/tools/fs/fs-search-tools.js +3 -1
  848. package/dist/tools/fs/fs-shared.d.ts +59 -63
  849. package/dist/tools/fs/fs-shared.js +31 -18
  850. package/dist/tools/fs/fs-write.d.ts +13 -0
  851. package/dist/tools/fs/fs-write.js +69 -13
  852. package/dist/tools/fs/index.d.ts +19 -1
  853. package/dist/tools/fs/index.js +10 -2
  854. package/dist/tools/fs/pdf.js +10 -9
  855. package/dist/tools/fs/read-deny.js +4 -10
  856. package/dist/tools/fs/read-floor.d.ts +5 -4
  857. package/dist/tools/fs/removal-targets.d.ts +11 -5
  858. package/dist/tools/fs/removal-targets.js +62 -32
  859. package/dist/tools/fs/safety.d.ts +26 -19
  860. package/dist/tools/fs/safety.js +13 -8
  861. package/dist/tools/fs/search.d.ts +1 -1
  862. package/dist/tools/fs/shell-read-argv.js +1 -0
  863. package/dist/tools/fs/shell-read-bindings.d.ts +128 -26
  864. package/dist/tools/fs/shell-read-bindings.js +667 -139
  865. package/dist/tools/fs/shell-read-check.js +1 -1
  866. package/dist/tools/fs/shell-read-judge.d.ts +4 -1
  867. package/dist/tools/fs/shell-read-judge.js +5 -1
  868. package/dist/tools/fs/shell-read-plan.d.ts +4 -0
  869. package/dist/tools/fs/shell-read-plan.js +21 -19
  870. package/dist/tools/fs/shell-read-sourced.d.ts +4 -3
  871. package/dist/tools/fs/shell-read-sourced.js +18 -1
  872. package/dist/tools/fs/shell-read-start.d.ts +6 -6
  873. package/dist/tools/fs/shell-read-start.js +1 -6
  874. package/dist/tools/fs/shell-read-word.d.ts +4 -2
  875. package/dist/tools/fs/shell-read-word.js +7 -6
  876. package/dist/tools/fs/shell-read-workdir.d.ts +1 -1
  877. package/dist/tools/fs/shell-reentry-text.d.ts +24 -9
  878. package/dist/tools/fs/shell-reentry-text.js +50 -20
  879. package/dist/tools/monitor.d.ts +4 -0
  880. package/dist/tools/monitor.js +14 -4
  881. package/dist/tools/scheduler-tools.d.ts +5 -2
  882. package/dist/tools/scheduler-tools.js +8 -6
  883. package/dist/tools/task-list.d.ts +49 -20
  884. package/dist/tools/task-list.js +115 -35
  885. package/dist/tools/web.d.ts +13 -3
  886. package/dist/tools/web.js +17 -6
  887. package/dist/tools/worktree.d.ts +3 -2
  888. package/dist/tools/worktree.js +24 -25
  889. package/package.json +10 -3
  890. package/test/export-surface.snapshot.json +340 -32
  891. package/wire-changes/core-stores-sql@7.67.0.json +39 -0
  892. package/wire-changes/core-stores-sql@7.67.1.json +39 -0
  893. package/wire-changes/core@7.67.0.json +12578 -0
  894. package/wire-changes/core@7.67.1.json +406 -0
  895. package/wire-changes/mods-kernel@7.67.0.json +167 -0
  896. package/wire-changes/mods-kernel@7.67.1.json +39 -0
  897. package/wire-changes/primitives@7.67.0.json +325 -0
  898. package/wire-changes/primitives@7.67.1.json +39 -0
  899. package/wire-changes/wiki-gate@7.67.0.json +1636 -0
  900. package/wire-changes/wiki-gate@7.67.1.json +39 -0
  901. package/dist/brain/degrading.d.ts +0 -93
  902. package/dist/brain/degrading.js +0 -189
  903. package/dist/core/tool-conformance.d.ts +0 -20
  904. package/dist/core/tool-conformance.js +0 -37
@@ -1,6 +1,10 @@
1
1
  import type { SubagentEditedFile, SubagentStep } from "../agents/subagent-steps.js";
2
2
  import type { SubagentTranscriptTier } from "./wiring-manifest.js";
3
3
  import type { ExtensionRequester } from "./task-event.js";
4
+ import { type DamagedRowVerdict, type RowContext } from "./row-shape.js";
5
+ /** A background agent row's lifecycle words (closed; the stored row's `status` is read against it). */
6
+ export declare const BACKGROUND_AGENT_STATUSES: readonly ["running", "parked", "completed", "failed", "killed"];
7
+ export type BackgroundAgentStatus = (typeof BACKGROUND_AGENT_STATUSES)[number];
4
8
  /** Terminal/live usage rollup persisted on the row (mirror of the task_notification/BCE fields). */
5
9
  export interface BackgroundAgentUsage {
6
10
  totalTokens?: number;
@@ -45,6 +49,11 @@ export interface BackgroundAgentRecord {
45
49
  * spawning tree held no occupant for its root, or a row an earlier release wrote: the revived tree's root occupant is
46
50
  * then unknown. A store returns it as written, absent as absent. */
47
51
  rootSessionIncarnation?: string;
52
+ /** The scope {@link rootSessionId}'s durable box mounts in (the registry scope of the tree's root leg) — the third member of the
53
+ * root anchor's address, written beside it with the occupant. A drive of this row on a runner where no leg of the root runs
54
+ * writes the completion into that box. ABSENT = a row an earlier release wrote: the root's box is not judged, and such a drive's
55
+ * completion keeps the mount's sink. A store returns it as written, absent as absent. */
56
+ rootSessionScope?: string;
48
57
  parentTaskId?: string;
49
58
  /** The agent's name — the spawner's explicit one, or the one the engine derives from `handle`
50
59
  * (`engineAgentName`) when the spawn named none. Written by the registration that creates the row, so
@@ -90,23 +99,26 @@ export interface BackgroundAgentRecord {
90
99
  spawnedAt: number;
91
100
  updatedAt: number;
92
101
  settledAt?: number;
93
- /** design/153 §7.1: `"parked"` = durably suspended on a pending approval checkpoint (neither live
94
- * nor terminal) — reap-exempt like `running`; cleared to a real state by resume claim, TaskStop
102
+ /** design/153 §7.1: `"parked"` = durably suspended on a pending checkpoint (neither live nor terminal; what it
103
+ * waits on is the checkpoint's gate — a person's approval, or a resource limit such as a scheduler's yield, which
104
+ * its owner's next leg continues) — reap-exempt like `running`; cleared to a real state by resume claim, TaskStop
95
105
  * (checkpoint arbitration first), or the reconciliation sweep (checkpoint expired/missing). */
96
- status: "running" | "parked" | "completed" | "failed" | "killed";
106
+ status: BackgroundAgentStatus;
97
107
  /** Open enum (task-registry `StopSource` mirror). */
98
108
  stoppedBy?: string;
99
109
  /** The cross-channel completion correlation id
100
110
  * (task-registry `SemaTaskHandle.completionId` mirror). Written alongside `status`/`settledAt` at
101
- * the same durable terminal write that lands them, so a cross-restart fallback read (a host poll
102
- * after the writing process is gone) REPLAYS this exact value — there is no second mint point here,
103
- * this field only ever receives what the in-memory handle already minted before the write. */
111
+ * the same durable terminal write that lands them, so a cross-restart read — a host poll or a listing
112
+ * ({@link BackgroundAgentRowSummary.completionId}) after the writing process is gone — REPLAYS this exact value.
113
+ * A terminal write that has a live handle copies what the handle already minted; a store-side terminal write
114
+ * with no live handle (the store-only reconciliation, the stale-running reap) mints it through the same
115
+ * fill-once `mintCompletionId` — one minter either way. */
104
116
  completionId?: string;
105
117
  /** design/144 §1.1 dedup-key continuity (LOW-15): revival cycles re-mint seq FROM the stored value,
106
118
  * so `task_id:status:seq` keys never collide across restarts. */
107
119
  seq?: number;
108
120
  /**
109
- * design/153 §7.1 — the durable-approval checkpoint token this row is parked ON (`status:"parked"`
121
+ * design/153 §7.1 — the checkpoint token this row is parked ON (any gate; `status:"parked"`
110
122
  * only; park mint writes it, resume claim / terminal settle clears it). The checkpoint token CAS is
111
123
  * the MASTER arbitration domain (r4 F-05): every parked-row CAS also verifies THIS binding, and the
112
124
  * row never adjudicates a park outcome on its own. A row CAS that loses after the checkpoint was
@@ -210,10 +222,27 @@ export declare function clearRevivedRowTerminalPayload(record: BackgroundAgentRe
210
222
  */
211
223
  export declare const declaresTranscriptDurability: (tier: SubagentTranscriptTier) => boolean;
212
224
  export declare function announceTranscriptIntegrityGapOnce(handle: string, scope: string | undefined, sink: ((handle: string, scope: string | undefined) => void) | undefined, tier: SubagentTranscriptTier): void;
213
- /** Content-free projection for list reads (design/151 HIGH-1: `summary`/`finalOutput`/`recentSteps`
214
- * and friends NEVER ride a list — content is get-by-handle only, behind the full predicate). */
215
- export interface BackgroundAgentRowSummary {
225
+ /**
226
+ * Content-free projection for list reads (design/151 HIGH-1: `summary`/`finalOutput`/`recentSteps` and friends NEVER ride a list
227
+ * — content is get-by-handle only, behind the full predicate). A UNION: a row that reads ({@link BACKGROUND_AGENT_ROW_SHAPE}) is
228
+ * listed as {@link ReadableBackgroundAgentRowSummary}; one that does not is still one row of the listing —
229
+ * {@link DamagedBackgroundAgentRowSummary}, its handle and its verdict. Only the damaged arm carries `rowVerdict`: narrow with
230
+ * `"rowVerdict" in summary` before reading a member.
231
+ */
232
+ export type BackgroundAgentRowSummary = ReadableBackgroundAgentRowSummary | DamagedBackgroundAgentRowSummary;
233
+ /** A listed row that does not read: its handle and its verdict (the family's code, the member that failed first, its form and
234
+ * the fixed engine sentence a `get` of it refuses with). No other member. */
235
+ export interface DamagedBackgroundAgentRowSummary {
236
+ readonly rowVerdict: DamagedRowVerdict;
237
+ readonly handle: string;
238
+ }
239
+ /** The summary of a row that reads. */
240
+ export interface ReadableBackgroundAgentRowSummary {
216
241
  handle: string;
242
+ /** The tenant partition the row lives in ({@link BackgroundAgentRecord.scope}). A per-row follow-up on a summary (`get` / `delete` /
243
+ * `updateIf`) addresses the row in this scope: {@link BackgroundAgentStore.listByRoot} answers across scopes, so its caller reads the
244
+ * scope off each row instead of supplying one. */
245
+ scope: string;
217
246
  owner: string;
218
247
  sessionScoped: boolean;
219
248
  sessionId?: string;
@@ -227,12 +256,41 @@ export interface BackgroundAgentRowSummary {
227
256
  updatedAt: number;
228
257
  settledAt?: number;
229
258
  usage?: BackgroundAgentUsage;
259
+ /** The row's completion identity ({@link BackgroundAgentRecord.completionId}), verbatim — the value the live completion
260
+ * frame, the inbox / replay record and the host poll carry for the same completion, so a host that listed the row
261
+ * after a restart recognizes the completion it already met on another channel. An identity, not content (it may ride
262
+ * a list). Present iff the record carries one — a settled row; absent on a `running` / `parked` row and on a revived
263
+ * row until its new cycle settles. */
264
+ completionId?: string;
230
265
  }
231
266
  /** Typed store error so callers branch on `code` (mirrors `WorkflowRunStoreError`). */
232
267
  export declare class BackgroundAgentStoreError extends Error {
233
- readonly code: "agent_record.already_exists";
234
- constructor(code: "agent_record.already_exists", message: string);
268
+ readonly code: "agent_record.already_exists" | typeof BACKGROUND_AGENT_ROW_MALFORMED_CODE;
269
+ constructor(code: "agent_record.already_exists" | typeof BACKGROUND_AGENT_ROW_MALFORMED_CODE, message: string);
235
270
  }
271
+ /** The refusal code of a row whose stored body (or a write's candidate) does not read as {@link BACKGROUND_AGENT_ROW_SHAPE}. */
272
+ export declare const BACKGROUND_AGENT_ROW_MALFORMED_CODE = "agent_record.row_malformed";
273
+ /**
274
+ * THE BACKGROUND AGENT ROW'S MEMBER-SHAPE TABLE (`rowShapeReader`, row-shape.ts). `rowKey` is the file ledger's row predicate (a
275
+ * string handle and scope: the row's key). `members` is what the readers reach for: the owner and the session anchors (the access
276
+ * predicate and the session listing read them), the status word, the stamps, the revision and the writer's generation (the CAS
277
+ * compares them and bumps them — a stored revision that is no count is refused, never incremented), the claim and park bindings,
278
+ * the display members, and `name` — whose ABSENCE reads as the name the engine derives from the handle (`engineAgentName`; a row
279
+ * without a name whose handle derives none does not read). `requestedBy` is read by its own reader (a value it does not read is
280
+ * no requester). The write gate also holds a candidate to a non-empty scope (a row without one is world-readable through the
281
+ * access fallback). Exit `list-damaged`: a listing answers such a row by its handle, a `get` and every CAS refuse it in
282
+ * {@link BACKGROUND_AGENT_ROW_MALFORMED_CODE}, and deletion by its handle goes on.
283
+ */
284
+ export declare const BACKGROUND_AGENT_ROW_SHAPE: import("./row-shape.js").RowShapeReader<BackgroundAgentRecord>;
285
+ /**
286
+ * A stored row as every reader reads it — the row (an absent `name` read as the engine's name for its handle), or the refusal
287
+ * ({@link BACKGROUND_AGENT_ROW_MALFORMED_CODE}) of one that does not read, told to `disclose` first. A backend's `get` and every
288
+ * CAS's read of the live row go through this; a SQL twin passes its authoritative columns (`handle`, `scope`, `rev`).
289
+ */
290
+ export declare function readStoredBackgroundAgent(raw: unknown, ctx: RowContext, disclose?: (sentence: string) => void): BackgroundAgentRecord;
291
+ /** A write's candidate — its handle, scope and revision already placed by the backend's rule — held to
292
+ * {@link BACKGROUND_AGENT_ROW_SHAPE} and its write-only invariants: the row to store, or the refusal before anything is written. */
293
+ export declare function admitBackgroundAgent(candidate: BackgroundAgentRecord, ctx: RowContext): BackgroundAgentRecord;
236
294
  /**
237
295
  * design/151 §3.1c — the fallback access predicate (S-1 定谳 class). Mirrors the live registry's
238
296
  * `canAccess` axes with ONE remaining durable-only addition: a task-scoped row is readable by its
@@ -364,6 +422,17 @@ export interface BackgroundAgentStore {
364
422
  status?: BackgroundAgentRecord["status"];
365
423
  limit?: number;
366
424
  }): Promise<BackgroundAgentRowSummary[]>;
425
+ /** Every row of ONE delegation tree: a row qualifies when its tree root ({@link delegationRootOf}) equals `rootSessionId` — in
426
+ * EVERY scope, each summary carrying the scope its row lives in, so a follow-up on a row addresses it there (the session-deletion
427
+ * enumeration's face: a host session's children are found by the session, never by a scope the caller would have to guess).
428
+ * Content-free, newest-first; `opts` as {@link listBySession}. Deployment-op context, not a model-serving face — it crosses the
429
+ * tenant boundary by design, so a deployment that hands a row to a caller applies {@link canAccessAgentRecord} first. A row whose
430
+ * root is another session is not listed, even when its parent is `rootSessionId` (a grandchild of an intermediate session belongs
431
+ * to its own root's tree). `rootSessionId` is judged by {@link assertDelegationRoot} before any row is read. */
432
+ listByRoot(rootSessionId: string, opts?: {
433
+ status?: BackgroundAgentRecord["status"];
434
+ limit?: number;
435
+ }): Promise<BackgroundAgentRowSummary[]>;
367
436
  /** row-precise removal (the joint-reap deletion arm). Returns false on a miss.
368
437
  * `expect.rev` makes it CONDITIONAL — a live writer's concurrent revival (heartbeat
369
438
  * adopt bumps rev) must beat the reaper's stale snapshot, so the joint reap always deletes with
@@ -421,11 +490,39 @@ export declare function reconcileParkedAgents(stores: {
421
490
  rolledBack: number;
422
491
  }>;
423
492
  /**
424
- * REF-A3 — the query shape both `listBySession` (with {@link sessionId}) and `listByScope` (without it)
425
- * are expressed in. Named rather than inline because it crosses a module boundary (the file backend
426
- * imports it), and every field's ABSENCE is a defined "no filter" state rather than a missing value.
493
+ * The root of the delegation tree a row belongs to — the ONE reading of it, for a durable row and a live registry handle alike: the
494
+ * row's recorded `rootSessionId`; a row written before that column existed answers with its `parentSessionId` (a depth-1 row's parent
495
+ * IS its root); a session-scoped row with neither answers with its `owner` (a session-scoped registration's owner is the session id).
496
+ * `undefined` when none of the three is there — such a row is in no tree. Read by {@link BackgroundAgentStore.listByRoot} (through
497
+ * {@link queryBackgroundAgents}), by the registry's live tree selection, and by a revival keying its entry pool off the claimed row.
498
+ */
499
+ export declare function delegationRootOf(row: {
500
+ readonly rootSessionId?: string;
501
+ readonly parentSessionId?: string;
502
+ readonly sessionScoped?: boolean;
503
+ readonly owner?: string;
504
+ }): string | undefined;
505
+ /**
506
+ * THE judge of the root a tree query names ({@link BackgroundAgentStore.listByRoot}, `TaskRegistry.activeDelegationHandlesByRoot`), run
507
+ * before any row is read, in every backend: a non-empty string of at most {@link DELEGATION_ROOT_MAX_CHARS} UTF-16 units with no
508
+ * control character. Anything else is refused with `config.invalid_argument` — an empty or non-string root would answer "no rows" for
509
+ * a question that was never asked, and a deletion that enumerates a session's children by it would then delete none of them.
510
+ */
511
+ export declare function assertDelegationRoot(rootSessionId: unknown): asserts rootSessionId is string;
512
+ /** What {@link queryBackgroundAgents} keeps besides the partition: one status, and the newest N after the sort. */
513
+ interface BackgroundAgentQueryCut {
514
+ /** Keep only this status. ABSENT ⇒ every status. */
515
+ status?: BackgroundAgentRecord["status"];
516
+ /** Keep the newest N, applied AFTER the sort. ABSENT ⇒ no cap. */
517
+ limit?: number;
518
+ }
519
+ /**
520
+ * REF-A3 — the query shape `listBySession` (scope + {@link sessionId}), `listByScope` (scope alone) and `listByRoot` (`root` alone) are
521
+ * expressed in. Named rather than inline because it crosses a module boundary (the file backend imports it), and every field's
522
+ * ABSENCE is a defined "no filter" state rather than a missing value. Exactly one partition: a tenant (`scope`), or one delegation
523
+ * tree across tenants (`root`).
427
524
  */
428
- export interface BackgroundAgentQuery {
525
+ export type BackgroundAgentQuery = (BackgroundAgentQueryCut & {
429
526
  /** Tenant partition key, always in the WHERE — a row in another scope is never visible. */
430
527
  scope: string;
431
528
  /**
@@ -434,14 +531,17 @@ export interface BackgroundAgentQuery {
434
531
  * delegation tree under one host session) equals this. ABSENT ⇒ scope-wide enumeration.
435
532
  */
436
533
  sessionId?: string;
437
- /** Keep only this status. ABSENT ⇒ every status. */
438
- status?: BackgroundAgentRecord["status"];
439
- /** Keep the newest N, applied AFTER the sort. ABSENT ⇒ no cap. */
440
- limit?: number;
441
- }
534
+ root?: never;
535
+ }) | (BackgroundAgentQueryCut & {
536
+ /** One delegation tree in every scope: a row qualifies when {@link delegationRootOf} equals this (judged by
537
+ * {@link assertDelegationRoot} before any row is read). */
538
+ root: string;
539
+ scope?: never;
540
+ sessionId?: never;
541
+ });
442
542
  /**
443
543
  * REF-A3 — THE query projection for {@link BackgroundAgentStore.listBySession} /
444
- * {@link BackgroundAgentStore.listByScope}: filter → sort newest-first by `spawnedAt` → truncate →
544
+ * {@link BackgroundAgentStore.listByScope} / {@link BackgroundAgentStore.listByRoot}: filter → sort newest-first by `spawnedAt` → truncate →
445
545
  * content-free summary (HIGH-1). Pure (no store state, no I/O): it takes any row iterable, so the
446
546
  * in-memory backend passes its `Map` values and the file backend passes the shared ledger's. The two
447
547
  * backends held byte-identical hand copies of this before — the same one-of-two-implementations drift
@@ -454,7 +554,30 @@ export interface BackgroundAgentQuery {
454
554
  * {@link canAccessAgentRecord} first (the {@link BackgroundAgentStore} interface notes state the same
455
555
  * obligation for raw rows: a store never widens visibility, and raw rows are not a serving face).
456
556
  */
457
- export declare function queryBackgroundAgents(rows: Iterable<BackgroundAgentRecord>, query: BackgroundAgentQuery): BackgroundAgentRowSummary[];
557
+ export declare function queryBackgroundAgents(rows: Iterable<BackgroundAgentRecord>, query: BackgroundAgentQuery, disclose?: (sentence: string) => void): BackgroundAgentRowSummary[];
558
+ /** One stored row as a listing answers it: its content-free summary, or — a row that does not read — its handle and verdict
559
+ * (told to `disclose`). A SQL twin projects each row it lists through this, its authoritative columns in `ctx`. */
560
+ export declare function summarizeStoredBackgroundAgent(raw: unknown, ctx: RowContext, disclose?: (sentence: string) => void): BackgroundAgentRowSummary;
561
+ /**
562
+ * THE CAS guard of {@link BackgroundAgentStore.update} / {@link BackgroundAgentStore.updateIf}, shared by every backend: the row must
563
+ * exist under this scope; the live row is READ before its revision is compared (a row that does not read is refused, told to
564
+ * `disclose` — its revision is never compared or bumped); the revision and the field guards must match; the candidate, its handle,
565
+ * scope and revision placed by the key, is held to the write gate. Returns the row to persist, `null` when the CAS lost; PURE.
566
+ */
567
+ export declare function nextBackgroundAgentOnUpdate(live: BackgroundAgentRecord | undefined, key: string, handle: string, scope: string, record: BackgroundAgentRecord, expect: BackgroundAgentUpdateIfExpect, disclose?: (sentence: string) => void): BackgroundAgentRecord | null;
568
+ /** The row a stale-running sweep flips to `failed`, or `undefined` when it does not flip: not a running row of the scope, not
569
+ * stale, or a row that does not read (told to `disclose`, and left as stored). Every backend's one reading of arm 1. */
570
+ export declare function staleRunningFlip(live: BackgroundAgentRecord | undefined, key: string, scope: string, now: number, staleMs: number, disclose?: (sentence: string) => void): BackgroundAgentRecord | undefined;
571
+ /** A terminal-retention candidate: a terminal row of the scope whose stamps read — its key, spawn time and settle (else spawn) time. */
572
+ export interface BackgroundAgentReapCandidate {
573
+ readonly key: string;
574
+ readonly spawnedAt: number;
575
+ readonly age: number;
576
+ }
577
+ /** The rows a terminal-retention sweep may consider, newest first by `spawnedAt` — every backend's one reading of arm 2: a terminal
578
+ * status word (`running` and `parked` are exempt), a finite `spawnedAt`, a `settledAt` absent or finite. A row whose status or
579
+ * stamps do not read is never reaped by age or count (told to `disclose`). */
580
+ export declare function backgroundAgentReapCandidates(rows: Iterable<readonly [string, BackgroundAgentRecord]>, scope: string, disclose?: (sentence: string) => void): BackgroundAgentReapCandidate[];
458
581
  /**
459
582
  * In-process reference implementation. NOT default-mounted (divergence ② above) — single-instance
460
583
  * deployments and tests wire it explicitly; it does not survive a restart, so with THIS store the
@@ -479,9 +602,14 @@ export declare class InMemoryBackgroundAgentStore implements BackgroundAgentStor
479
602
  status?: BackgroundAgentRecord["status"];
480
603
  limit?: number;
481
604
  }): Promise<BackgroundAgentRowSummary[]>;
605
+ listByRoot(rootSessionId: string, opts?: {
606
+ status?: BackgroundAgentRecord["status"];
607
+ limit?: number;
608
+ }): Promise<BackgroundAgentRowSummary[]>;
482
609
  delete(handle: string, scope: string, expect?: {
483
610
  rev: number;
484
611
  }): Promise<boolean>;
485
612
  listScopes(): Promise<string[]>;
486
613
  reap(scope: string, now: number, opts?: BackgroundAgentReapOptions): Promise<number>;
487
614
  }
615
+ export {};
@@ -1,6 +1,10 @@
1
- import { uuidv7 } from "../internal/harness.js";
1
+ import { mintCompletionId } from "./completion-id.js";
2
2
  import { receiveRetentionPolicy } from "./retention-policy.js";
3
3
  import { readExtensionRequester } from "./extension-requester.js";
4
+ import { engineAgentName } from "./task-registry-shared.js";
5
+ import { absentReads, isBoolean, isCount, isFiniteNumber, isRecord, isRowCorrupt, isString, isWord, optional, pair, required, rowShapeReader, takesExit, via, } from "./row-shape.js";
6
+ export const BACKGROUND_AGENT_STATUSES = Object.freeze(["running", "parked", "completed", "failed", "killed"]);
7
+ import { receiptRefusal } from "./own-property-receipt.js";
4
8
  export const REVIVED_ROW_CLEARED_FIELDS = Object.freeze([
5
9
  "settledAt",
6
10
  "stoppedBy",
@@ -45,6 +49,63 @@ export class BackgroundAgentStoreError extends Error {
45
49
  this.name = "BackgroundAgentStoreError";
46
50
  }
47
51
  }
52
+ export const BACKGROUND_AGENT_ROW_MALFORMED_CODE = "agent_record.row_malformed";
53
+ const isNonEmptyString = (v) => (typeof v === "string" && v !== "" ? undefined : "is not a non-empty string");
54
+ export const BACKGROUND_AGENT_ROW_SHAPE = rowShapeReader({
55
+ family: "background-agent",
56
+ code: BACKGROUND_AGENT_ROW_MALFORMED_CODE,
57
+ sentence: "This background agent's stored row does not read the way this engine reads an agent row — an earlier engine release wrote it before a member it now reads existed, or it was changed in storage. It stays as stored: it is listed as unreadable, not revived, settled or reconciled here, and it can be deleted by its handle.",
58
+ exit: "list-damaged",
59
+ segments: [
60
+ { name: "rowKey", entries: [required("handle", isString), required("scope", isString)] },
61
+ {
62
+ name: "members",
63
+ entries: [
64
+ required("owner", isString),
65
+ required("sessionScoped", isBoolean),
66
+ required("status", isWord(BACKGROUND_AGENT_STATUSES)),
67
+ required("spawnedAt", isFiniteNumber),
68
+ required("updatedAt", isFiniteNumber),
69
+ optional("settledAt", isFiniteNumber),
70
+ optional("rev", isCount),
71
+ optional("writerId", isString),
72
+ optional("writerEpoch", isCount),
73
+ optional("parkClaimId", isString),
74
+ optional("parkedCheckpointToken", isString),
75
+ optional("parkedAt", isFiniteNumber),
76
+ optional("sessionId", isString),
77
+ optional("parentSessionId", isString),
78
+ optional("rootSessionId", isString),
79
+ optional("agentType", isString),
80
+ absentReads("name", (row) => engineAgentName(String(row.handle)), isNonEmptyString),
81
+ via("requestedBy", readExtensionRequester),
82
+ optional("usage", isRecord),
83
+ optional("completionId", isString),
84
+ ],
85
+ },
86
+ ],
87
+ admitOnly: [pair("scope", (row) => (row.scope === "" ? "its scope is empty — refusing a row without a scope (world-readable through the fallback)" : undefined))],
88
+ });
89
+ function backgroundAgentRefusal(corrupt) {
90
+ return new BackgroundAgentStoreError(BACKGROUND_AGENT_ROW_MALFORMED_CODE, BACKGROUND_AGENT_ROW_SHAPE.refusalText(corrupt));
91
+ }
92
+ function agentRowName(raw) {
93
+ const handle = typeof raw === "object" && raw !== null ? Reflect.get(raw, "handle") : undefined;
94
+ return `background agent ${typeof handle === "string" ? JSON.stringify(handle) : "(unreadable handle)"}`;
95
+ }
96
+ export function readStoredBackgroundAgent(raw, ctx, disclose) {
97
+ const answer = BACKGROUND_AGENT_ROW_SHAPE.read(raw, ctx);
98
+ if (!isRowCorrupt(answer))
99
+ return answer.row;
100
+ disclose?.(`${agentRowName(raw)}: ${answer.why} — refused in ${BACKGROUND_AGENT_ROW_MALFORMED_CODE}`);
101
+ throw backgroundAgentRefusal(answer);
102
+ }
103
+ export function admitBackgroundAgent(candidate, ctx) {
104
+ const answer = BACKGROUND_AGENT_ROW_SHAPE.admit(candidate, ctx);
105
+ if (isRowCorrupt(answer))
106
+ throw backgroundAgentRefusal(answer);
107
+ return answer.row;
108
+ }
48
109
  export function canAccessAgentRecord(record, access) {
49
110
  if (access.scope === undefined || record.scope !== access.scope)
50
111
  return false;
@@ -75,7 +136,7 @@ export async function reconcileParkedAgents(stores, scope, now, opts) {
75
136
  next.stoppedBy = "system";
76
137
  next.settledAt = now;
77
138
  next.updatedAt = now;
78
- next.completionId ??= uuidv7();
139
+ mintCompletionId(next);
79
140
  delete next.parkedCheckpointToken;
80
141
  delete next.parkClaimId;
81
142
  delete next.parkedAt;
@@ -93,6 +154,8 @@ export async function reconcileParkedAgents(stores, scope, now, opts) {
93
154
  }
94
155
  };
95
156
  for (const summary of await stores.agentStore.listByScope(scope, { status: "parked" })) {
157
+ if ("rowVerdict" in summary)
158
+ continue;
96
159
  const row = await stores.agentStore.get(summary.handle, scope);
97
160
  if (!row || row.status !== "parked")
98
161
  continue;
@@ -115,7 +178,7 @@ export async function reconcileParkedAgents(stores, scope, now, opts) {
115
178
  const staleClaims = [];
116
179
  for (const status of ["parked", "running"]) {
117
180
  for (const summary of await stores.agentStore.listByScope(scope, { status })) {
118
- if (now - summary.updatedAt <= staleMs)
181
+ if ("rowVerdict" in summary || now - summary.updatedAt <= staleMs)
119
182
  continue;
120
183
  const row = await stores.agentStore.get(summary.handle, scope);
121
184
  if (!row || row.status !== status)
@@ -182,6 +245,7 @@ function toSummary(r) {
182
245
  const requestedBy = readExtensionRequester(r.requestedBy);
183
246
  return {
184
247
  handle: r.handle,
248
+ scope: r.scope,
185
249
  owner: r.owner,
186
250
  sessionScoped: r.sessionScoped,
187
251
  ...(r.sessionId !== undefined ? { sessionId: r.sessionId } : {}),
@@ -195,24 +259,123 @@ function toSummary(r) {
195
259
  updatedAt: r.updatedAt,
196
260
  ...(r.settledAt !== undefined ? { settledAt: r.settledAt } : {}),
197
261
  ...(r.usage !== undefined ? { usage: structuredClone(r.usage) } : {}),
262
+ ...(r.completionId !== undefined ? { completionId: r.completionId } : {}),
198
263
  };
199
264
  }
200
- export function queryBackgroundAgents(rows, query) {
201
- const out = [];
202
- for (const r of rows) {
265
+ export function delegationRootOf(row) {
266
+ return row.rootSessionId ?? row.parentSessionId ?? (row.sessionScoped ? row.owner : undefined);
267
+ }
268
+ const DELEGATION_ROOT_MAX_CHARS = 256;
269
+ const CONTROL_CHARACTER = /\p{Cc}/u;
270
+ export function assertDelegationRoot(rootSessionId) {
271
+ if (typeof rootSessionId !== "string" ||
272
+ rootSessionId === "" ||
273
+ rootSessionId.length > DELEGATION_ROOT_MAX_CHARS ||
274
+ CONTROL_CHARACTER.test(rootSessionId)) {
275
+ throw receiptRefusal(`a delegation tree root must be a non-empty string of at most ${DELEGATION_ROOT_MAX_CHARS} characters with no control character, got ${typeof rootSessionId === "string" ? `a string of ${rootSessionId.length} characters` : typeof rootSessionId}`);
276
+ }
277
+ }
278
+ export function queryBackgroundAgents(rows, query, disclose) {
279
+ let root;
280
+ if ("root" in query) {
281
+ const named = query.root;
282
+ assertDelegationRoot(named);
283
+ root = named;
284
+ }
285
+ const inPartition = (r) => {
286
+ if (root !== undefined)
287
+ return delegationRootOf(r) === root;
203
288
  if (r.scope !== query.scope)
289
+ return false;
290
+ if (query.sessionId === undefined)
291
+ return true;
292
+ const scoped = r.sessionScoped;
293
+ const anchor = scoped === true ? r.owner : scoped === false ? r.parentSessionId : undefined;
294
+ return anchor === query.sessionId || r.rootSessionId === query.sessionId;
295
+ };
296
+ const hits = [];
297
+ for (const r of rows) {
298
+ if (!inPartition(r))
204
299
  continue;
205
- if (query.sessionId !== undefined) {
206
- const anchor = r.sessionScoped ? r.owner : r.parentSessionId;
207
- if (anchor !== query.sessionId && r.rootSessionId !== query.sessionId)
208
- continue;
209
- }
210
300
  if (query.status !== undefined && r.status !== query.status)
211
301
  continue;
212
- out.push(toSummary(r));
302
+ hits.push(r);
213
303
  }
214
- out.sort((a, b) => b.spawnedAt - a.spawnedAt);
215
- return query.limit !== undefined ? out.slice(0, Math.max(0, query.limit)) : out;
304
+ hits.sort((a, b) => {
305
+ const [ka, kb] = [orderKey(a.spawnedAt), orderKey(b.spawnedAt)];
306
+ return ka === kb ? 0 : ka < kb ? 1 : -1;
307
+ });
308
+ const page = query.limit !== undefined ? hits.slice(0, Math.max(0, query.limit)) : hits;
309
+ return page.map((r) => summarizeStoredBackgroundAgent(r, { key: `${String(r.scope)}\u0000${String(r.handle)}` }, disclose));
310
+ }
311
+ function orderKey(value) {
312
+ return typeof value === "number" && Number.isFinite(value) ? value : -Infinity;
313
+ }
314
+ export function summarizeStoredBackgroundAgent(raw, ctx, disclose) {
315
+ const answer = BACKGROUND_AGENT_ROW_SHAPE.read(raw, ctx);
316
+ if (!isRowCorrupt(answer))
317
+ return toSummary(answer.row);
318
+ takesExit(answer, "list-damaged", "background agent listing");
319
+ disclose?.(`${agentRowName(raw)}: ${answer.why} — listed as unreadable`);
320
+ const handle = ctx.authoritative?.handle ?? (typeof raw === "object" && raw !== null ? Reflect.get(raw, "handle") : undefined);
321
+ return { rowVerdict: BACKGROUND_AGENT_ROW_SHAPE.damagedVerdict(answer), handle: typeof handle === "string" ? handle : "" };
322
+ }
323
+ export function nextBackgroundAgentOnUpdate(live, key, handle, scope, record, expect, disclose) {
324
+ if (!live || live.scope !== scope)
325
+ return null;
326
+ const row = readStoredBackgroundAgent(live, { key }, disclose);
327
+ if (row.rev !== expect.rev)
328
+ return null;
329
+ if (expect.status !== undefined && row.status !== expect.status)
330
+ return null;
331
+ if (expect.parkedCheckpointToken !== undefined && (expect.parkedCheckpointToken === null ? row.parkedCheckpointToken !== undefined : row.parkedCheckpointToken !== expect.parkedCheckpointToken))
332
+ return null;
333
+ if (expect.parkClaimId !== undefined && (expect.parkClaimId === null ? row.parkClaimId !== undefined : row.parkClaimId !== expect.parkClaimId))
334
+ return null;
335
+ const stored = structuredClone(record);
336
+ stored.handle = handle;
337
+ stored.scope = scope;
338
+ stored.rev = row.rev + 1;
339
+ return admitBackgroundAgent(stored, { key });
340
+ }
341
+ export function staleRunningFlip(live, key, scope, now, staleMs, disclose) {
342
+ if (!live || live.scope !== scope || live.status !== "running")
343
+ return undefined;
344
+ const answer = BACKGROUND_AGENT_ROW_SHAPE.read(live, { key });
345
+ if (isRowCorrupt(answer)) {
346
+ disclose?.(`${agentRowName(live)}: ${answer.why} — the stale-running sweep leaves it as stored`);
347
+ return undefined;
348
+ }
349
+ const row = answer.row;
350
+ if (now - row.updatedAt <= staleMs)
351
+ return undefined;
352
+ const next = structuredClone(row);
353
+ next.status = "failed";
354
+ next.stoppedBy = "system";
355
+ next.summary = next.summary ?? STALE_RUNNING_REAP_ATTRIBUTION;
356
+ next.error = next.error ?? STALE_RUNNING_REAP_ATTRIBUTION;
357
+ next.settledAt = now;
358
+ next.updatedAt = now;
359
+ mintCompletionId(next);
360
+ next.rev = row.rev + 1;
361
+ return next;
362
+ }
363
+ export function backgroundAgentReapCandidates(rows, scope, disclose) {
364
+ const out = [];
365
+ for (const [key, r] of rows) {
366
+ if (r.scope !== scope || r.status === "running" || r.status === "parked")
367
+ continue;
368
+ const spawnedAt = r.spawnedAt;
369
+ const settledAt = r.settledAt;
370
+ const terminal = r.status === "completed" || r.status === "failed" || r.status === "killed";
371
+ const stamped = typeof spawnedAt === "number" && Number.isFinite(spawnedAt) && (settledAt === undefined || (typeof settledAt === "number" && Number.isFinite(settledAt)));
372
+ if (!terminal || !stamped) {
373
+ disclose?.(`${agentRowName(r)}: its status or stamps do not read — the retention sweep leaves it in place`);
374
+ continue;
375
+ }
376
+ out.push({ key, spawnedAt: r.spawnedAt, age: r.settledAt ?? r.spawnedAt });
377
+ }
378
+ return out.sort((a, b) => (a.spawnedAt === b.spawnedAt ? 0 : a.spawnedAt < b.spawnedAt ? 1 : -1));
216
379
  }
217
380
  export class InMemoryBackgroundAgentStore {
218
381
  rows = new Map();
@@ -220,45 +383,30 @@ export class InMemoryBackgroundAgentStore {
220
383
  return `${scope}\u0000${handle}`;
221
384
  }
222
385
  async put(record) {
223
- if (record.scope === undefined || record.scope === "") {
224
- throw new Error("BackgroundAgentStore.put: refusing a row without a scope (world-readable through the fallback)");
225
- }
386
+ const stored = structuredClone(record);
387
+ stored.rev = record.rev ?? 0;
226
388
  const k = this.key(record.handle, record.scope);
389
+ const admitted = admitBackgroundAgent(stored, { key: k });
227
390
  if (this.rows.has(k)) {
228
391
  throw new BackgroundAgentStoreError("agent_record.already_exists", "agent record already exists");
229
392
  }
230
- const stored = structuredClone(record);
231
- stored.rev = record.rev ?? 0;
232
- this.rows.set(k, stored);
393
+ this.rows.set(k, admitted);
233
394
  }
234
395
  async get(handle, scope) {
235
- const row = this.rows.get(this.key(handle, scope));
236
- return row ? structuredClone(row) : null;
396
+ const k = this.key(handle, scope);
397
+ const row = this.rows.get(k);
398
+ return row ? structuredClone(readStoredBackgroundAgent(row, { key: k })) : null;
237
399
  }
238
400
  async update(handle, scope, record, expect) {
239
- const k = this.key(handle, scope);
240
- const live = this.rows.get(k);
241
- if (!live || live.scope !== scope || live.rev !== expect.rev)
242
- return false;
243
- const stored = structuredClone(record);
244
- stored.handle = handle;
245
- stored.scope = scope;
246
- stored.rev = live.rev + 1;
247
- this.rows.set(k, stored);
248
- return true;
401
+ return this.updateIf(handle, scope, record, { rev: expect.rev });
249
402
  }
250
403
  async updateIf(handle, scope, record, expect) {
251
404
  const k = this.key(handle, scope);
252
- const live = this.rows.get(k);
253
- if (!live || live.scope !== scope || live.rev !== expect.rev)
254
- return false;
255
- if (expect.status !== undefined && live.status !== expect.status)
405
+ const next = nextBackgroundAgentOnUpdate(this.rows.get(k), k, handle, scope, record, expect);
406
+ if (next === null)
256
407
  return false;
257
- if (expect.parkedCheckpointToken !== undefined && (expect.parkedCheckpointToken === null ? live.parkedCheckpointToken !== undefined : live.parkedCheckpointToken !== expect.parkedCheckpointToken))
258
- return false;
259
- if (expect.parkClaimId !== undefined && (expect.parkClaimId === null ? live.parkClaimId !== undefined : live.parkClaimId !== expect.parkClaimId))
260
- return false;
261
- return this.update(handle, scope, record, { rev: expect.rev });
408
+ this.rows.set(k, next);
409
+ return true;
262
410
  }
263
411
  async listBySession(scope, sessionId, opts) {
264
412
  return queryBackgroundAgents(this.rows.values(), { scope, sessionId, status: opts?.status, limit: opts?.limit });
@@ -266,6 +414,9 @@ export class InMemoryBackgroundAgentStore {
266
414
  async listByScope(scope, opts) {
267
415
  return queryBackgroundAgents(this.rows.values(), { scope, status: opts?.status, limit: opts?.limit });
268
416
  }
417
+ async listByRoot(rootSessionId, opts) {
418
+ return queryBackgroundAgents(this.rows.values(), { root: rootSessionId, status: opts?.status, limit: opts?.limit });
419
+ }
269
420
  async delete(handle, scope, expect) {
270
421
  const k = this.key(handle, scope);
271
422
  const live = this.rows.get(k);
@@ -284,36 +435,25 @@ export class InMemoryBackgroundAgentStore {
284
435
  return 0;
285
436
  const flippedKeys = new Set();
286
437
  if (policy.staleRunningMaxAgeMs !== undefined) {
287
- for (const [k, r] of this.rows) {
288
- if (r.scope !== scope || r.status !== "running")
289
- continue;
290
- if (now - r.updatedAt <= policy.staleRunningMaxAgeMs)
438
+ for (const [k, r] of [...this.rows]) {
439
+ const flipped = staleRunningFlip(r, k, scope, now, policy.staleRunningMaxAgeMs);
440
+ if (flipped === undefined)
291
441
  continue;
292
- const flipped = structuredClone(r);
293
- flipped.status = "failed";
294
- flipped.stoppedBy = "system";
295
- flipped.summary = flipped.summary ?? STALE_RUNNING_REAP_ATTRIBUTION;
296
- flipped.error = flipped.error ?? STALE_RUNNING_REAP_ATTRIBUTION;
297
- flipped.settledAt = now;
298
- flipped.updatedAt = now;
299
- flipped.rev = r.rev + 1;
300
442
  this.rows.set(k, flipped);
301
443
  flippedKeys.add(k);
302
444
  }
303
445
  }
304
- const terminal = [...this.rows.entries()]
305
- .filter(([, r]) => r.scope === scope && r.status !== "running" && r.status !== "parked")
306
- .sort(([, a], [, b]) => b.spawnedAt - a.spawnedAt);
446
+ const terminal = backgroundAgentReapCandidates(this.rows.entries(), scope);
307
447
  const doomed = new Set();
308
448
  if (policy.maxAgeMs !== undefined) {
309
- for (const [k, r] of terminal) {
310
- if ((r.settledAt ?? r.spawnedAt) < now - policy.maxAgeMs)
311
- doomed.add(k);
449
+ for (const r of terminal) {
450
+ if (r.age < now - policy.maxAgeMs)
451
+ doomed.add(r.key);
312
452
  }
313
453
  }
314
454
  if (policy.keep !== undefined) {
315
- for (const [k] of terminal.slice(Math.max(0, policy.keep)))
316
- doomed.add(k);
455
+ for (const r of terminal.slice(Math.max(0, policy.keep)))
456
+ doomed.add(r.key);
317
457
  }
318
458
  for (const k of doomed)
319
459
  this.rows.delete(k);
@@ -13,6 +13,7 @@
13
13
  * - **按-id-可重读**:实现 MUST 保证按 shellId 跨多次独立调用可重复读取累积/增量输出(execStream 的 consume-once 不满足)。
14
14
  */
15
15
  import type { ExecutionEnv, ExecutionEnvExecOptions, Result } from "../internal/harness-types.js";
16
+ import type { ConfinementRefusal } from "./command-sandbox.js";
16
17
  /**
17
18
  * 一个 long-running / detached 进程的句柄。**env-local、非 durable、对调用方不透明** —— adapter 内部把它映射到真实进程/
18
19
  * provider job,**绝不**把可猜的 raw provider job id 暴露成 shellId(否则跨租户可枚举,design/103 §3.8 越界红线)。
@@ -26,11 +27,13 @@ export type BackgroundShellStatus = "running" | "exited" | "killed" | "failed";
26
27
  * 类型化错误码(对齐 `RemoteExecutionErrorCode` 风格)。`timeout`/`io` 覆盖 TOB 下的有界 liveness/传输失败 —— 接口规定
27
28
  * 方法 MUST NOT throw(返回 {@link Result}),所以挂掉的 provider RPC 必须有码可表达、而非违约抛异常。
28
29
  */
29
- export type BackgroundShellErrorCode = "unsupported" | "not_found" | "spawn_failed" | "limit_exceeded" | "timeout" | "io";
30
+ export type BackgroundShellErrorCode = "unsupported" | "not_found" | "spawn_failed" | "sandbox_unavailable" | "limit_exceeded" | "timeout" | "io";
30
31
  /** 后台 shell 操作的类型化错误。`code` 给程序分类,`message` 给模型自纠(design/103 错误文案纪律)。 */
31
32
  export declare class BackgroundShellError extends Error {
32
33
  readonly code: BackgroundShellErrorCode;
33
34
  readonly cause?: unknown | undefined;
35
+ /** `sandbox_unavailable` only — which way the start was refused, as `ExecutionError.refusedBy` reads it. */
36
+ refusedBy?: ConfinementRefusal;
34
37
  constructor(code: BackgroundShellErrorCode, message: string, cause?: unknown | undefined);
35
38
  }
36
39
  /**