@sema-agent/core 7.61.0 → 7.63.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 (298) hide show
  1. package/CHANGELOG.md +840 -0
  2. package/dist/agents/cascade.d.ts +11 -3
  3. package/dist/agents/cascade.js +1 -1
  4. package/dist/agents/peer-held-queue.d.ts +27 -4
  5. package/dist/agents/peer-held-queue.js +81 -36
  6. package/dist/agents/peer-session-drain.js +13 -3
  7. package/dist/agents/subagent-transcript-placement.d.ts +23 -0
  8. package/dist/agents/subagent-transcript-placement.js +14 -0
  9. package/dist/agents/subagent.d.ts +6 -1
  10. package/dist/agents/subagent.js +143 -58
  11. package/dist/agents/suspend-guard.d.ts +38 -16
  12. package/dist/agents/suspend-guard.js +9 -4
  13. package/dist/agents/verify.js +4 -3
  14. package/dist/brain/route-adjudicator.js +9 -4
  15. package/dist/core/approval-object.js +1 -1
  16. package/dist/core/arg-summary.js +1 -1
  17. package/dist/core/ask-question.d.ts +2 -2
  18. package/dist/core/canonical-json.d.ts +23 -13
  19. package/dist/core/canonical-json.js +4 -4
  20. package/dist/core/checkpoint-features.d.ts +722 -0
  21. package/dist/core/checkpoint-features.js +98 -0
  22. package/dist/core/checkpoint-queries.d.ts +47 -4
  23. package/dist/core/checkpoint-queries.js +36 -16
  24. package/dist/core/checkpoint-requirements.d.ts +12 -5
  25. package/dist/core/checkpoint-requirements.js +11 -5
  26. package/dist/core/checkpoint-row-verdict.d.ts +110 -0
  27. package/dist/core/checkpoint-row-verdict.js +245 -0
  28. package/dist/core/checkpoint-store.d.ts +76 -753
  29. package/dist/core/checkpoint-store.js +83 -144
  30. package/dist/core/compliance.d.ts +6 -2
  31. package/dist/core/compliance.js +3 -3
  32. package/dist/core/engine-attestation.d.ts +1 -1
  33. package/dist/core/engine-notice.d.ts +38 -7
  34. package/dist/core/engine-notice.js +9 -2
  35. package/dist/core/gate-fold.js +2 -2
  36. package/dist/core/git-worktree-env.d.ts +62 -3
  37. package/dist/core/git-worktree-env.js +91 -30
  38. package/dist/core/governance-codes.d.ts +9 -3
  39. package/dist/core/governance-codes.js +16 -3
  40. package/dist/core/hooks.d.ts +13 -0
  41. package/dist/core/human-input-projection.d.ts +1 -0
  42. package/dist/core/human-input-projection.js +3 -0
  43. package/dist/core/image-admission.d.ts +1 -1
  44. package/dist/core/locked-config.d.ts +2 -2
  45. package/dist/core/mcp-host-seat.js +6 -1
  46. package/dist/core/memory-engine/consolidation-driver.d.ts +33 -18
  47. package/dist/core/memory-engine/consolidation-driver.js +99 -98
  48. package/dist/core/memory-engine/consolidation.d.ts +73 -10
  49. package/dist/core/memory-engine/consolidation.js +167 -11
  50. package/dist/core/memory-engine/data-plane.d.ts +8 -4
  51. package/dist/core/memory-engine/data-plane.js +11 -6
  52. package/dist/core/memory-engine/delegation-settlement.d.ts +37 -35
  53. package/dist/core/memory-engine/delegation-settlement.js +53 -59
  54. package/dist/core/memory-engine/dual-root.d.ts +12 -6
  55. package/dist/core/memory-engine/dual-root.js +9 -5
  56. package/dist/core/memory-engine/engine.d.ts +98 -35
  57. package/dist/core/memory-engine/engine.js +477 -380
  58. package/dist/core/memory-engine/entry-scan.d.ts +8 -0
  59. package/dist/core/memory-engine/entry-scan.js +3 -0
  60. package/dist/core/memory-engine/file-backend.d.ts +29 -3
  61. package/dist/core/memory-engine/file-backend.js +66 -35
  62. package/dist/core/memory-engine/index.d.ts +7 -7
  63. package/dist/core/memory-engine/index.js +6 -6
  64. package/dist/core/memory-engine/landing-admission.d.ts +5 -3
  65. package/dist/core/memory-engine/landing-admission.js +3 -3
  66. package/dist/core/memory-engine/layout.d.ts +121 -45
  67. package/dist/core/memory-engine/layout.js +252 -102
  68. package/dist/core/memory-engine/memory-backend-contract.d.ts +19 -1
  69. package/dist/core/memory-engine/memory-backend-contract.js +320 -0
  70. package/dist/core/memory-engine/memory-deployment.d.ts +31 -8
  71. package/dist/core/memory-engine/memory-deployment.js +26 -12
  72. package/dist/core/memory-engine/scope-contract.d.ts +52 -11
  73. package/dist/core/memory-engine/scope-contract.js +68 -19
  74. package/dist/core/memory-engine/session-write-home.d.ts +3 -1
  75. package/dist/core/memory-engine/session-write-home.js +1 -1
  76. package/dist/core/memory-engine/sync-client.d.ts +3 -1
  77. package/dist/core/memory-engine/sync-client.js +7 -0
  78. package/dist/core/memory-engine/sync-report.d.ts +3 -2
  79. package/dist/core/memory-engine/sync-report.js +6 -2
  80. package/dist/core/memory-engine/tools.d.ts +2 -2
  81. package/dist/core/memory-engine/tools.js +10 -10
  82. package/dist/core/memory-engine/types.d.ts +118 -19
  83. package/dist/core/memory-engine/types.js +1 -0
  84. package/dist/core/memory-vector.d.ts +1 -1
  85. package/dist/core/memory.d.ts +10 -10
  86. package/dist/core/memory.js +15 -6
  87. package/dist/core/mode-policy.js +1 -1
  88. package/dist/core/mods/classic-events.d.ts +9 -1
  89. package/dist/core/mods/dollar.d.ts +32 -1
  90. package/dist/core/mods/dollar.js +13 -1
  91. package/dist/core/mods/kernel/events.d.ts +11 -3
  92. package/dist/core/mods/kernel/events.js +13 -10
  93. package/dist/core/mods/lifecycle-stations.d.ts +36 -4
  94. package/dist/core/mods/lifecycle-stations.js +44 -9
  95. package/dist/core/mods/session-append.d.ts +4 -1
  96. package/dist/core/mods/session-append.js +7 -0
  97. package/dist/core/mods/session-receive.js +12 -15
  98. package/dist/core/mods/stations.d.ts +70 -6
  99. package/dist/core/mods/stations.js +144 -1
  100. package/dist/core/own-property-receipt.d.ts +7 -0
  101. package/dist/core/own-property-receipt.js +3 -0
  102. package/dist/core/park-selfcheck.js +2 -2
  103. package/dist/core/pause-registry.d.ts +2 -0
  104. package/dist/core/pause-registry.js +3 -0
  105. package/dist/core/permission-rule-consent.d.ts +10 -3
  106. package/dist/core/permission-rule-consent.js +37 -24
  107. package/dist/core/permission-rule-store.d.ts +35 -1
  108. package/dist/core/permission-rule-store.js +27 -8
  109. package/dist/core/read-only-shell.js +3 -2
  110. package/dist/core/read-root-candidate.js +1 -1
  111. package/dist/core/redaction-marks.d.ts +8 -0
  112. package/dist/core/redaction-marks.js +6 -0
  113. package/dist/core/remote-env.d.ts +12 -1
  114. package/dist/core/remote-env.js +3 -0
  115. package/dist/core/resume-startup-cause.d.ts +5 -4
  116. package/dist/core/runner/child-tree.d.ts +29 -3
  117. package/dist/core/runner/child-tree.js +39 -16
  118. package/dist/core/runner/compact-session.js +5 -2
  119. package/dist/core/runner/contracts.d.ts +36 -17
  120. package/dist/core/runner/delegation-owner.d.ts +43 -0
  121. package/dist/core/runner/delegation-owner.js +59 -0
  122. package/dist/core/runner/gate-exit.js +2 -2
  123. package/dist/core/runner/inherited-ask-grants.js +1 -1
  124. package/dist/core/runner/lineage-reroot-view.d.ts +56 -0
  125. package/dist/core/runner/lineage-reroot-view.js +108 -0
  126. package/dist/core/runner/memory-consolidation-driver.d.ts +6 -3
  127. package/dist/core/runner/memory-consolidation-driver.js +4 -4
  128. package/dist/core/runner/memory-consolidation-write-judge.d.ts +2 -1
  129. package/dist/core/runner/memory-consolidation-write-judge.js +3 -2
  130. package/dist/core/runner/permission-rule-lanes.d.ts +2 -1
  131. package/dist/core/runner/permission-rule-lanes.js +2 -2
  132. package/dist/core/runner/person-path-rows.d.ts +23 -3
  133. package/dist/core/runner/person-path-rows.js +31 -4
  134. package/dist/core/runner/placement-fence.d.ts +12 -0
  135. package/dist/core/runner/placement-fence.js +20 -6
  136. package/dist/core/runner/prepare-acquire-reconcile.d.ts +4 -1
  137. package/dist/core/runner/prepare-acquire-reconcile.js +7 -2
  138. package/dist/core/runner/prepare-ask-lane.js +2 -2
  139. package/dist/core/runner/prepare-caps-and-workflow.d.ts +5 -1
  140. package/dist/core/runner/prepare-caps-and-workflow.js +6 -3
  141. package/dist/core/runner/prepare-config-doors.d.ts +6 -6
  142. package/dist/core/runner/prepare-config-doors.js +3 -4
  143. package/dist/core/runner/prepare-execution-env.js +17 -6
  144. package/dist/core/runner/prepare-hands-readface.d.ts +3 -2
  145. package/dist/core/runner/prepare-hands-readface.js +32 -10
  146. package/dist/core/runner/prepare-inherited-gate.d.ts +12 -8
  147. package/dist/core/runner/prepare-inherited-gate.js +14 -6
  148. package/dist/core/runner/prepare-memory-engine-session.d.ts +2 -4
  149. package/dist/core/runner/prepare-memory-engine-session.js +4 -4
  150. package/dist/core/runner/prepare-memory.d.ts +3 -2
  151. package/dist/core/runner/prepare-memory.js +28 -20
  152. package/dist/core/runner/prepare-park-ask.js +4 -3
  153. package/dist/core/runner/prepare-task.js +22 -16
  154. package/dist/core/runner/prepare-workspace-restore.js +3 -6
  155. package/dist/core/runner/resume-admission.d.ts +3 -3
  156. package/dist/core/runner/resume-admission.js +6 -3
  157. package/dist/core/runner/resume-apply.d.ts +4 -0
  158. package/dist/core/runner/resume-apply.js +11 -4
  159. package/dist/core/runner/resume-checkpoint-screen.d.ts +9 -0
  160. package/dist/core/runner/resume-checkpoint-screen.js +4 -84
  161. package/dist/core/runner/run-git-lane.d.ts +2 -0
  162. package/dist/core/runner/run-git-lane.js +4 -1
  163. package/dist/core/runner/run-harness-handlers.d.ts +2 -0
  164. package/dist/core/runner/run-harness-handlers.js +3 -2
  165. package/dist/core/runner/run-leg.js +25 -8
  166. package/dist/core/runner/run-settle-and-teardown.js +6 -4
  167. package/dist/core/runner/run-stop-and-final-verify.js +2 -1
  168. package/dist/core/runner/run-turn-boundary.js +7 -4
  169. package/dist/core/runner/runtask.js +6 -6
  170. package/dist/core/runner/steering-preview.d.ts +9 -0
  171. package/dist/core/runner/steering-preview.js +5 -0
  172. package/dist/core/runner/stream-steer-verb.js +8 -0
  173. package/dist/core/runner/terminal-account.js +1 -1
  174. package/dist/core/runner/tool-face-overlay.js +2 -0
  175. package/dist/core/runner/turn-attachments.d.ts +5 -0
  176. package/dist/core/runner/turn-attachments.js +1 -1
  177. package/dist/core/runner-deps.d.ts +8 -4
  178. package/dist/core/secret-env.d.ts +9 -6
  179. package/dist/core/secret-env.js +41 -22
  180. package/dist/core/session-checkout.d.ts +108 -0
  181. package/dist/core/session-checkout.js +485 -0
  182. package/dist/core/session-store.d.ts +13 -5
  183. package/dist/core/session-store.js +28 -4
  184. package/dist/core/session.d.ts +29 -5
  185. package/dist/core/session.js +3 -0
  186. package/dist/core/store-contracts/checkpoint-store-contract.d.ts +6 -12
  187. package/dist/core/store-contracts/checkpoint-store-contract.js +73 -6
  188. package/dist/core/store-contracts/session-store-contract.js +61 -8
  189. package/dist/core/task-event.d.ts +28 -1
  190. package/dist/core/task-notification.d.ts +9 -1
  191. package/dist/core/task-notification.js +8 -1
  192. package/dist/core/task-registry-agent.d.ts +40 -8
  193. package/dist/core/task-registry-agent.js +57 -24
  194. package/dist/core/task-registry-shared.d.ts +33 -11
  195. package/dist/core/task-registry-workflow.js +4 -3
  196. package/dist/core/task-registry.d.ts +27 -10
  197. package/dist/core/task-registry.js +19 -13
  198. package/dist/core/task-result.d.ts +5 -5
  199. package/dist/core/task-spec-members.js +1 -1
  200. package/dist/core/task-spec.d.ts +21 -1
  201. package/dist/core/terminal-cause.d.ts +6 -6
  202. package/dist/core/tool-face.d.ts +6 -2
  203. package/dist/core/tool-face.js +1 -1
  204. package/dist/core/tool-policy.d.ts +16 -13
  205. package/dist/core/tool-policy.js +11 -10
  206. package/dist/core/tool-roster.d.ts +4 -4
  207. package/dist/core/tool-spec.d.ts +42 -19
  208. package/dist/core/types.d.ts +2 -2
  209. package/dist/core/types.js +1 -1
  210. package/dist/core/untrusted-egress.d.ts +15 -4
  211. package/dist/core/untrusted-egress.js +23 -22
  212. package/dist/core/workspace-snapshot.d.ts +3 -1
  213. package/dist/core/workspace-snapshot.js +1 -0
  214. package/dist/engine/execution-env/node-execution-env.d.ts +3 -0
  215. package/dist/engine/execution-env/node-execution-env.js +12 -5
  216. package/dist/engine/harness/types.d.ts +77 -1
  217. package/dist/engine/harness/types.js +108 -0
  218. package/dist/engine/session/import-validate.js +6 -1
  219. package/dist/engine/session/parent-chain-guard.d.ts +3 -3
  220. package/dist/engine/session/parent-chain-guard.js +1 -1
  221. package/dist/engine/session/path-to-root.d.ts +18 -3
  222. package/dist/engine/session/path-to-root.js +15 -1
  223. package/dist/engine/session/repo-utils.d.ts +12 -1
  224. package/dist/engine/session/repo-utils.js +41 -0
  225. package/dist/engine/session/session.d.ts +24 -1
  226. package/dist/engine/session/session.js +46 -2
  227. package/dist/engine/session/storage-base.d.ts +20 -0
  228. package/dist/engine/session/storage-base.js +28 -9
  229. package/dist/index.d.ts +16 -12
  230. package/dist/index.js +11 -8
  231. package/dist/internal/harness-types.d.ts +1 -1
  232. package/dist/internal/harness.d.ts +4 -3
  233. package/dist/internal/harness.js +3 -2
  234. package/dist/orchestration/run-workflow-tool.d.ts +7 -1
  235. package/dist/orchestration/run-workflow-tool.js +28 -11
  236. package/dist/orchestration/workflow-governance.d.ts +1 -1
  237. package/dist/orchestration/workflow.d.ts +6 -0
  238. package/dist/orchestration/workflow.js +5 -8
  239. package/dist/stores/file/checkpoint-store.d.ts +2 -0
  240. package/dist/stores/file/checkpoint-store.js +7 -6
  241. package/dist/stores/file/fs-atomic.d.ts +0 -22
  242. package/dist/stores/file/fs-atomic.js +0 -17
  243. package/dist/stores/file/index.d.ts +2 -9
  244. package/dist/stores/file/index.js +2 -4
  245. package/dist/stores/file/session-store.d.ts +13 -7
  246. package/dist/stores/file/session-store.js +42 -18
  247. package/dist/tools/fs/bash-program-position.d.ts +3 -2
  248. package/dist/tools/fs/bash-program-position.js +10 -10
  249. package/dist/tools/fs/program-read-model.d.ts +34 -10
  250. package/dist/tools/fs/program-read-model.js +37 -7
  251. package/dist/tools/fs/program-read-model.rows.js +13 -2
  252. package/dist/tools/fs/read-deny.d.ts +13 -1
  253. package/dist/tools/fs/read-deny.js +10 -2
  254. package/dist/tools/fs/removal-targets.js +5 -5
  255. package/dist/tools/fs/safety.d.ts +2 -0
  256. package/dist/tools/fs/safety.js +1 -1
  257. package/dist/tools/fs/shell-read-argv.d.ts +11 -2
  258. package/dist/tools/fs/shell-read-argv.js +45 -29
  259. package/dist/tools/fs/shell-read-bindings.d.ts +20 -2
  260. package/dist/tools/fs/shell-read-bindings.js +153 -69
  261. package/dist/tools/fs/shell-read-brace.d.ts +18 -0
  262. package/dist/tools/fs/shell-read-brace.js +79 -0
  263. package/dist/tools/fs/shell-read-check.js +29 -11
  264. package/dist/tools/fs/shell-read-establish.js +43 -22
  265. package/dist/tools/fs/shell-read-functions.js +2 -2
  266. package/dist/tools/fs/shell-read-judge.d.ts +11 -0
  267. package/dist/tools/fs/shell-read-judge.js +3 -3
  268. package/dist/tools/fs/shell-read-object-path.d.ts +59 -0
  269. package/dist/tools/fs/shell-read-object-path.js +119 -0
  270. package/dist/tools/fs/shell-read-plan.d.ts +18 -0
  271. package/dist/tools/fs/shell-read-plan.js +217 -104
  272. package/dist/tools/fs/shell-read-start.d.ts +76 -13
  273. package/dist/tools/fs/shell-read-start.js +97 -17
  274. package/dist/tools/fs/shell-read-word.d.ts +10 -0
  275. package/dist/tools/fs/shell-read-word.js +9 -5
  276. package/dist/tools/fs/shell-read-workdir.d.ts +54 -14
  277. package/dist/tools/fs/shell-read-workdir.js +103 -19
  278. package/dist/tools/fs/shell-read-write-targets.js +13 -8
  279. package/dist/tools/worktree.d.ts +3 -2
  280. package/dist/tools/worktree.js +7 -35
  281. package/package.json +3 -2
  282. package/test/export-surface.snapshot.json +93 -43
  283. package/wire-changes/core-stores-sql@7.62.0.json +30 -0
  284. package/wire-changes/core-stores-sql@7.63.0.json +30 -0
  285. package/wire-changes/core@7.62.0.json +2181 -0
  286. package/wire-changes/core@7.63.0.json +3523 -0
  287. package/wire-changes/mods-kernel@7.62.0.json +42 -0
  288. package/wire-changes/mods-kernel@7.63.0.json +30 -0
  289. package/wire-changes/primitives@7.62.0.json +30 -0
  290. package/wire-changes/primitives@7.63.0.json +445 -0
  291. package/dist/core/consolidate-scope.d.ts +0 -93
  292. package/dist/core/consolidate-scope.js +0 -98
  293. package/dist/core/credential-vocabulary.d.ts +0 -176
  294. package/dist/core/credential-vocabulary.js +0 -190
  295. package/dist/core/redaction-passes.d.ts +0 -82
  296. package/dist/core/redaction-passes.js +0 -377
  297. package/dist/core/runner/memory-consolidation.d.ts +0 -109
  298. package/dist/core/runner/memory-consolidation.js +0 -251
@@ -128,8 +128,11 @@ export interface CascadeAttempt {
128
128
  export interface CascadeRunResult extends TaskResult {
129
129
  /**
130
130
  * The cascade's conclusion, **distinct from the inherited `status`**: `"passed"` = some rung passed the
131
- * gate; `"exhausted"` = ladder/guards ran out with no rung passing (the last rung's result is returned,
132
- * and its `status` may still be "completed" — judge the cascade by `cascadeOutcome`, not `status`).
131
+ * gate; `"exhausted"` = the cascade ended with no rung passing (the last rung's result is returned, and its
132
+ * `status` may still be "completed" — judge the cascade by `cascadeOutcome`, not `status`). It ends that way
133
+ * when the ladder ran out, when a guard stopped it (escalation cap, cost ceiling, wall-clock budget, the
134
+ * caller's signal), when a rung durably parked (`failed.nestedPause` is on the terminal: {@link resumeCascade}
135
+ * continues it), or when a resumed rung's approved action never started (`failed.unstartedRow`).
133
136
  */
134
137
  cascadeOutcome: "passed" | "exhausted";
135
138
  /** F4: present when a finite `costCeilingMicroUsd` was configured but some rung's spend was unpriced —
@@ -216,11 +219,16 @@ internals?: RunInternals): Promise<CascadeRunResult>;
216
219
  /**
217
220
  * Continue a cascade from a rung's parked card, then climb the rest of the ladder: the resume entry beside {@link runCascade},
218
221
  * as {@link import("./verify.js").resumeWithVerification} is beside its fresh-run entry. A rung that durably parks ends the
219
- * ladder with `cascadeOutcome: "exhausted"` and the pause on `failed.nestedPause` — the host holds the token, and the card's
222
+ * ladder (`cascadeOutcome`, `failed.nestedPause`) — the host holds the token, and the card's
220
223
  * `CheckpointState.compositionLeg` says which rung parked and which host session it belongs to. Once the pause is decided,
221
224
  * the host calls this with the token, the outcome, the ORIGINAL task spec, the ladder config and that `compositionLeg` as the
222
225
  * card records it.
223
226
  *
227
+ * A run whose task spec named no session (`spec.sessionId`) and whose caller handed it no leg through `internals` mints no
228
+ * composition leg, so its card records none: the host supplies `parkedLeg` itself — `{ entry: "cascade", leg: <the parked rung:
229
+ * the result's `finalRung`>, hostSessionId: <a session of its own> }` — and that value is the card's first record. The
230
+ * terminal's sentence says so.
231
+ *
224
232
  * - **One door**: the parked rung is continued through `runner.resume(token, outcome, <rung config>, internals)` — the rung's
225
233
  * config is the one {@link runCascade} derives for that rung (the task spec with the rung's model and overrides), minus the
226
234
  * members a resume does not take (`objective`, `sessionId`, `userAttachments`, `runOrigin`); its internals carry
@@ -178,7 +178,7 @@ async function climbLadder(entryName, runner, spec, config, internals, opening)
178
178
  nestedCostMicro += s.nested.costMicroUsd ?? 0;
179
179
  }
180
180
  if (isDurablePause(result.terminal) || resumeNeverStarted(result)) {
181
- const mapped = mapNestedSuspend(result);
181
+ const mapped = mapNestedSuspend(result, { door: "resumeCascade", legFrom: rungInternals?.compositionLeg === undefined ? "caller" : "card" });
182
182
  attempts.push({ index: i, model: rung.model, passed: false, costMicroUsd: rungCost, status: attemptTerminal(result).status, errorCode: attemptTerminal(mapped).errorCode });
183
183
  return {
184
184
  ...mapped,
@@ -27,6 +27,10 @@ export interface PeerHeldEntry {
27
27
  * waiting for a lease-holding pass — a re-judgment that now refuses still wins); `delivered` (this
28
28
  * queue took the hand-over move and the injection is still owed; a policy that now refuses ends it as `dropped`). */
29
29
  decision: PeerCardDecision;
30
+ /** When this hold resolves to `expired` unless someone answers it first (ms epoch) — present exactly while
31
+ * its expiry timer is armed: a cause in `PEER_HELD_REVIEW_CAUSES`, a finite `dialogExpiry`, the card still
32
+ * `held`. A cause move re-arms or clears it; an approval, a hand-over, the deadline itself or the card leaving clears it. */
33
+ deadlineAt?: number;
30
34
  }
31
35
  /** How an entry left this queue. `retired` — the CARD left this process but no decision was taken: the
32
36
  * record stays held in its box for the next consumer (a queue-local event no receipt announced,
@@ -56,8 +60,10 @@ export interface PeerHeldQueueSink {
56
60
  * deliver never takes a move out of `delivered`. Absent ⇒
57
61
  * the presence of `inject` decides. */
58
62
  canInject?: (entry: PeerHeldEntry) => boolean;
59
- /** The receipt to the sender (the binding routes it into the sender's box). */
60
- receipt: (entry: PeerHeldEntry, state: PeerDeliveryReceiptState) => void;
63
+ /** The receipt to the sender (the binding routes it into the sender's box). Resolves once the receipt is in
64
+ * that box (or has no reader there); rejects when it could not be written. Only {@link PeerHeldQueue.shutdown}
65
+ * waits on it — every other path sends and goes on. */
66
+ receipt: (entry: PeerHeldEntry, state: PeerDeliveryReceiptState) => Promise<void>;
61
67
  /** Does a receipt about this entry reach a sender? A queue-local event (eviction, shutdown, a refused
62
68
  * release) is a decision about the record exactly when it does — the sender is told it is final. */
63
69
  tellsSender: (entry: PeerHeldEntry) => boolean;
@@ -101,7 +107,7 @@ export interface PeerHeldQueue {
101
107
  * At the cap, settles the oldest held card that tells its sender (it is then a decision); arms the
102
108
  * deadline for a hold cause a person could answer.
103
109
  */
104
- hold(entry: Omit<PeerHeldEntry, "heldAt" | "decision">, decision?: PeerCardDecision): Promise<PeerHoldOutcome>;
110
+ hold(entry: Omit<PeerHeldEntry, "heldAt" | "decision" | "deadlineAt">, decision?: PeerCardDecision): Promise<PeerHoldOutcome>;
105
111
  /** Re-judge every entry against current settings (CC `D`): deliverable ⇒ handed over (or kept with no
106
112
  * live run), refused ⇒ refused with a receipt, still held ⇒ re-announced only when the cause moved.
107
113
  * Every move goes through the decision seat. */
@@ -128,7 +134,8 @@ export interface PeerHeldQueue {
128
134
  list(): readonly PeerHeldEntry[];
129
135
  size(): number;
130
136
  /** CC `HBe` — a graceful shutdown settles everything still held as `expired` with receipts (where a
131
- * receipt reaches a sender; elsewhere the cards just leave this process). */
137
+ * receipt reaches a sender; elsewhere the cards just leave this process). Resolves once every receipt it
138
+ * sent has landed; rejects naming the seqs whose receipt did not (every card is settled either way). */
132
139
  shutdown(): Promise<void>;
133
140
  }
134
141
  export declare function createPeerHeldQueue(key: string, opts?: {
@@ -149,5 +156,21 @@ export declare function peerHeldQueueFor(scope: string, sessionId: string, opts?
149
156
  /** The held queue of a session if one exists in this process (a host review face reads through this
150
157
  * without creating state for sessions that never held anything); `box` as in {@link peerHeldQueueFor}. */
151
158
  export declare function peerHeldQueueIfAny(scope: string, sessionId: string, box?: string): PeerHeldQueue | undefined;
159
+ /** One held queue of this process as {@link listPeerHeldQueues} shows it. */
160
+ export interface PeerHeldQueueSnapshot {
161
+ readonly scope: string;
162
+ /** The session that opened the queue (the spelling it first used; the key folds case). */
163
+ readonly sessionId: string;
164
+ /** The box its cards come from: the session's own, or the principal inbox it also drains. */
165
+ readonly box: string;
166
+ readonly size: number;
167
+ /** The cards as {@link PeerHeldQueue.list} shows them, at the same moment as `size`. */
168
+ readonly entries: readonly PeerHeldEntry[];
169
+ }
170
+ /** Every held queue of this process's registry (opened through {@link peerHeldQueueFor}, as every drain opens its
171
+ * queues; a bare {@link createPeerHeldQueue} is not in it), as a read-only snapshot that opens none: a host approval face lists
172
+ * the held cards of all its sessions without keeping its own table of (session, box) coordinates. A row's
173
+ * (scope, sessionId, box) handed to {@link peerHeldQueueIfAny} reaches that queue for its settle face. */
174
+ export declare function listPeerHeldQueues(): readonly PeerHeldQueueSnapshot[];
152
175
  /** Test seam: drop every queue (timers cleared, NO receipts — the crash form). Never called by production code. */
153
176
  export declare function resetPeerHeldQueuesForTests(): void;
@@ -40,25 +40,37 @@ export function createPeerHeldQueue(key, opts = {}) {
40
40
  catch {
41
41
  }
42
42
  };
43
- const clearDeadline = (seq) => {
44
- const h = deadlines.get(seq);
43
+ const clearDeadline = (entry) => {
44
+ const h = deadlines.get(entry.seq);
45
45
  if (h !== undefined) {
46
46
  clock.clearTimeout(h);
47
- deadlines.delete(seq);
47
+ deadlines.delete(entry.seq);
48
48
  }
49
+ delete entry.deadlineAt;
49
50
  };
50
51
  const remove = (entry) => {
51
52
  const i = entries.indexOf(entry);
52
53
  if (i !== -1)
53
54
  entries.splice(i, 1);
54
- clearDeadline(entry.seq);
55
+ clearDeadline(entry);
56
+ };
57
+ const sendReceipt = (sink, entry, state) => {
58
+ let landed;
59
+ try {
60
+ landed = Promise.resolve(sink.receipt(entry, state));
61
+ }
62
+ catch (e) {
63
+ landed = Promise.reject(e);
64
+ }
65
+ landed.catch(() => undefined);
66
+ return landed;
55
67
  };
56
68
  const leave = (entry, settlement, reason, receipt) => {
57
69
  const sink = sinkOrThrow();
58
70
  remove(entry);
59
- if (receipt !== undefined)
60
- safe(() => sink.receipt(entry, receipt));
71
+ const landed = receipt !== undefined ? sendReceipt(sink, entry, receipt) : undefined;
61
72
  safe(() => sink.onSettled?.(entry, settlement, reason, entries.length));
73
+ return landed;
62
74
  };
63
75
  const move = async (entry, next) => {
64
76
  const sink = sinkOrThrow();
@@ -78,13 +90,17 @@ export function createPeerHeldQueue(key, opts = {}) {
78
90
  const adoptCurrent = (entry, current) => {
79
91
  if (!entries.includes(entry))
80
92
  return;
81
- if (current === "gone" || current === "unset")
82
- return leave(entry, "retired", "superseded", undefined);
83
- if (isMailboxDecisionFinal(current))
84
- return leave(entry, current, "decided_elsewhere", undefined);
93
+ if (current === "gone" || current === "unset") {
94
+ leave(entry, "retired", "superseded", undefined);
95
+ return;
96
+ }
97
+ if (isMailboxDecisionFinal(current)) {
98
+ leave(entry, current, "decided_elsewhere", undefined);
99
+ return;
100
+ }
85
101
  if (isMailboxDecisionDeliverable(current) && entry.decision !== current) {
86
102
  entry.decision = current;
87
- clearDeadline(entry.seq);
103
+ clearDeadline(entry);
88
104
  }
89
105
  };
90
106
  const settleLocal = async (entry, settlement, reason) => {
@@ -97,13 +113,16 @@ export function createPeerHeldQueue(key, opts = {}) {
97
113
  tells = false;
98
114
  }
99
115
  const from = settlement === "expired" ? "held" : "delivered";
100
- if (!tells || entry.decision !== from)
101
- return leave(entry, "retired", reason, undefined);
116
+ if (!tells || entry.decision !== from) {
117
+ leave(entry, "retired", reason, undefined);
118
+ return {};
119
+ }
102
120
  const r = await move(entry, settlement);
103
121
  if (r === "won")
104
- leave(entry, settlement, reason, settlement);
105
- else if (r === "fault")
122
+ return { landed: leave(entry, settlement, reason, settlement) };
123
+ if (r === "fault")
106
124
  leave(entry, "retired", reason, undefined);
125
+ return {};
107
126
  };
108
127
  const armDeadline = (entry) => {
109
128
  if (cfg === undefined || cfg.dialogExpiryMs === null || deadlines.has(entry.seq))
@@ -112,8 +131,9 @@ export function createPeerHeldQueue(key, opts = {}) {
112
131
  return;
113
132
  if (!PEER_HELD_REVIEW_CAUSES.includes(entry.cause))
114
133
  return;
134
+ entry.deadlineAt = clock.now() + cfg.dialogExpiryMs;
115
135
  const h = clock.setTimeout(() => {
116
- deadlines.delete(entry.seq);
136
+ clearDeadline(entry);
117
137
  void (async () => {
118
138
  if (!entries.includes(entry))
119
139
  return;
@@ -150,7 +170,7 @@ export function createPeerHeldQueue(key, opts = {}) {
150
170
  if (r === "fault")
151
171
  return "no_leg";
152
172
  entry.decision = "delivered";
153
- clearDeadline(entry.seq);
173
+ clearDeadline(entry);
154
174
  }
155
175
  try {
156
176
  if (sink.inject(entry) === "deferred")
@@ -191,7 +211,7 @@ export function createPeerHeldQueue(key, opts = {}) {
191
211
  if (verdict.verdict === "hold" && verdict.cause !== entry.cause) {
192
212
  entry.cause = verdict.cause;
193
213
  reannounce.push([entry, verdict.cause]);
194
- clearDeadline(entry.seq);
214
+ clearDeadline(entry);
195
215
  armDeadline(entry);
196
216
  }
197
217
  return "held";
@@ -253,7 +273,7 @@ export function createPeerHeldQueue(key, opts = {}) {
253
273
  cfg = next;
254
274
  for (const entry of entries) {
255
275
  if (next.dialogExpiryMs === null)
256
- clearDeadline(entry.seq);
276
+ clearDeadline(entry);
257
277
  else
258
278
  armDeadline(entry);
259
279
  }
@@ -266,8 +286,10 @@ export function createPeerHeldQueue(key, opts = {}) {
266
286
  cfg = { ...cfg, sink: rest };
267
287
  },
268
288
  configured: () => cfg !== undefined,
269
- async hold(input, known) {
289
+ async hold(held, known) {
270
290
  const sink = sinkOrThrow();
291
+ const { deadlineAt: _callerDeadline, ...input } = held;
292
+ void _callerDeadline;
271
293
  if (entries.some((e) => e.box === input.box && e.seq === input.seq))
272
294
  return "adopted";
273
295
  let state = known ?? "held";
@@ -294,7 +316,7 @@ export function createPeerHeldQueue(key, opts = {}) {
294
316
  return fresh ? "held" : "adopted";
295
317
  if (!(await makeRoom())) {
296
318
  if (fresh)
297
- safe(() => sink.receipt({ ...input, heldAt: clock.now(), decision: state }, "held"));
319
+ void sendReceipt(sink, { ...input, heldAt: clock.now(), decision: state }, "held");
298
320
  return "uncarded";
299
321
  }
300
322
  const entry = { ...input, heldAt: clock.now(), decision: state };
@@ -303,7 +325,7 @@ export function createPeerHeldQueue(key, opts = {}) {
303
325
  if (state === "held")
304
326
  safe(() => sink.onHeld?.(entry, entries.length, entry.cause, false));
305
327
  if (fresh)
306
- safe(() => sink.receipt(entry, "held"));
328
+ void sendReceipt(sink, entry, "held");
307
329
  return fresh ? "held" : "adopted";
308
330
  },
309
331
  rejudge,
@@ -322,12 +344,25 @@ export function createPeerHeldQueue(key, opts = {}) {
322
344
  deadlines.clear();
323
345
  return;
324
346
  }
347
+ const owed = [];
325
348
  for (const entry of [...entries]) {
326
349
  await onCard(entry.seq, async () => {
327
- if (entries.includes(entry))
328
- await settleLocal(entry, "expired", "shutdown");
350
+ if (!entries.includes(entry))
351
+ return;
352
+ const { landed } = await settleLocal(entry, "expired", "shutdown");
353
+ if (landed !== undefined)
354
+ owed.push({ seq: entry.seq, landed });
329
355
  });
330
356
  }
357
+ const outcomes = await Promise.allSettled(owed.map((o) => o.landed));
358
+ const unlanded = [];
359
+ outcomes.forEach((outcome, i) => {
360
+ if (outcome.status === "rejected")
361
+ unlanded.push({ seq: owed[i].seq, reason: outcome.reason });
362
+ });
363
+ if (unlanded.length > 0) {
364
+ throw new AggregateError(unlanded.map((u) => u.reason), `PeerHeldQueue.shutdown: every held card was settled, but the expired receipt of seq ${unlanded.map((u) => u.seq).join(", ")} did not reach its sender's box`);
365
+ }
331
366
  },
332
367
  };
333
368
  async function settleCard(seq, decision) {
@@ -371,7 +406,7 @@ export function createPeerHeldQueue(key, opts = {}) {
371
406
  if (r === "lost")
372
407
  return "decided_elsewhere";
373
408
  entry.decision = "approved";
374
- clearDeadline(entry.seq);
409
+ clearDeadline(entry);
375
410
  }
376
411
  if (verdict === undefined)
377
412
  return "released_pending";
@@ -386,25 +421,35 @@ export function createPeerHeldQueue(key, opts = {}) {
386
421
  });
387
422
  return queue;
388
423
  }
424
+ function peerHeldQueueSeat(scope, sessionId, box) {
425
+ const own = peerSessionBoxHandle(sessionId);
426
+ const at = box ?? own;
427
+ return { scope, sessionId, box: at, key: JSON.stringify(at === own ? [scope, own] : [scope, own, at]) };
428
+ }
389
429
  const heldQueues = new Map();
390
430
  export function peerHeldQueueKey(scope, sessionId, box) {
391
- const own = peerSessionBoxHandle(sessionId);
392
- return JSON.stringify(box === undefined || box === own ? [scope, own] : [scope, own, box]);
431
+ return peerHeldQueueSeat(scope, sessionId, box).key;
393
432
  }
394
433
  export function peerHeldQueueFor(scope, sessionId, opts = {}) {
395
- const key = peerHeldQueueKey(scope, sessionId, opts.box);
396
- let q = heldQueues.get(key);
397
- if (q === undefined) {
398
- q = createPeerHeldQueue(key, opts);
399
- heldQueues.set(key, q);
434
+ const seat = peerHeldQueueSeat(scope, sessionId, opts.box);
435
+ let row = heldQueues.get(seat.key);
436
+ if (row === undefined) {
437
+ row = { seat, queue: createPeerHeldQueue(seat.key, opts) };
438
+ heldQueues.set(seat.key, row);
400
439
  }
401
- return q;
440
+ return row.queue;
402
441
  }
403
442
  export function peerHeldQueueIfAny(scope, sessionId, box) {
404
- return heldQueues.get(peerHeldQueueKey(scope, sessionId, box));
443
+ return heldQueues.get(peerHeldQueueKey(scope, sessionId, box))?.queue;
444
+ }
445
+ export function listPeerHeldQueues() {
446
+ return [...heldQueues.values()].map(({ seat, queue }) => {
447
+ const entries = queue.list();
448
+ return { scope: seat.scope, sessionId: seat.sessionId, box: seat.box, size: entries.length, entries };
449
+ });
405
450
  }
406
451
  export function resetPeerHeldQueuesForTests() {
407
- for (const q of heldQueues.values())
408
- crashHandlers.get(q)?.();
452
+ for (const { queue } of heldQueues.values())
453
+ crashHandlers.get(queue)?.();
409
454
  heldQueues.clear();
410
455
  }
@@ -147,14 +147,24 @@ export function createPeerSessionDrain(opts) {
147
147
  _sema_provenance: { kind: "cross_session_notice", from: encodePeerAddress(storedSessionAddress(m.peerMeta?.fromSession) ?? (m.from ?? "unknown")), taskId: boxHandle, seq: m.seq, ...(m.peerMeta !== undefined ? { peerMeta: { ...m.peerMeta } } : {}) },
148
148
  });
149
149
  const receiptAddress = (lane, entry) => (lane.kind === "session" ? entry.peerMeta?.fromSession : undefined);
150
- const receipt = (lane) => (entry, state) => {
150
+ const receipt = (lane) => async (entry, state) => {
151
151
  const to = receiptAddress(lane, entry);
152
152
  if (to === undefined)
153
153
  return;
154
+ const faults = [];
155
+ const via = {
156
+ ...route(),
157
+ onError: (error, ctx) => {
158
+ faults.push(error);
159
+ opts.onError?.(error, ctx);
160
+ },
161
+ };
154
162
  if (state === "dropped")
155
- void routePeerDroppedReceipt(route(), to, entry.seq);
163
+ await routePeerDroppedReceipt(via, to, entry.seq);
156
164
  else
157
- void routePeerDeliveryReceipt(route(), to, state, entry.seq);
165
+ await routePeerDeliveryReceipt(via, to, state, entry.seq);
166
+ if (faults.length > 0)
167
+ throw faults[0];
158
168
  };
159
169
  const settleConsumed = (lane, seq, payload, by, reason) => {
160
170
  lane.ledger.set(seq, { kind: "terminal", why: "consumed" });
@@ -0,0 +1,23 @@
1
+ import { type SessionPlacement, type SessionStore } from "../core/session.js";
2
+ /**
3
+ * Whether a background child's transcript is placed. Gated on BOTH stores: the row store (the a* handle the tuple joins to) AND the
4
+ * declaration of the session store that creates the transcript (`declaresSubagentPlacement`, the deployment's opt-in) — for a fork
5
+ * that is the store the branch is created in, so the Runner's host fork applies the host store's declaration. Without the declaration gate, a hand-wired durable repo
6
+ * (TtlSessionStore over FileSessionRepo, no `placements`) would persist tuples it never opted into: list-excluded transcripts
7
+ * nothing can address, a release that really deletes under evict:"forget", and a manifest reporting tier "rows" while placed
8
+ * semantics are silently in force. Obligation enforcement below the store keys on the PERSISTED fact — this gate is what keeps
9
+ * that fact deployment-consistent. What it does NOT decide is whether the transcript reaches DISK: an unplaced child still lands
10
+ * in whatever store the child runner is backed by. Placement buys ADDRESSABILITY (the a* handle, cross-restart revival, joint
11
+ * reap), not persistence.
12
+ */
13
+ export declare function placesSubagentTranscripts(agentStore: unknown, sessions: Pick<SessionStore, "placements">): boolean;
14
+ /**
15
+ * The one tuple a background child's transcript session is created with, on both background lanes: a plain spawn's creating
16
+ * acquire and a fork's creating write. The spawner is the minter — it knows the a* handle, the row's scope and the tree it spawns
17
+ * in — so the parent is the spawning session and the root is that session's root (or itself). It names no owner: the plain lane
18
+ * adds the delegation tree's owner for its acquire's owner cell, a fork records it through the fork's own owner argument.
19
+ */
20
+ export declare function subagentTranscriptPlacement(spawner: {
21
+ readonly sessionId?: string;
22
+ readonly rootSessionId?: string;
23
+ }, scope: string | undefined, handle: string): Omit<SessionPlacement, "owner">;
@@ -0,0 +1,14 @@
1
+ import { declaresSubagentPlacement } from "../core/session.js";
2
+ export function placesSubagentTranscripts(agentStore, sessions) {
3
+ return agentStore !== undefined && declaresSubagentPlacement(sessions);
4
+ }
5
+ export function subagentTranscriptPlacement(spawner, scope, handle) {
6
+ const root = spawner.rootSessionId ?? spawner.sessionId;
7
+ return {
8
+ kind: "subagent",
9
+ ...(scope !== undefined ? { scope } : {}),
10
+ ...(spawner.sessionId !== undefined ? { parentSessionId: spawner.sessionId } : {}),
11
+ ...(root !== undefined ? { rootSessionId: root } : {}),
12
+ handle,
13
+ };
14
+ }
@@ -641,8 +641,13 @@ export interface SubagentToolOptions {
641
641
  * milliseconds of minting and the redemption window never exists. The hook must cover the
642
642
  * store the child session ACTUALLY lives in — copy the session tree into the durable store,
643
643
  * then re-verify, and only then resolve.
644
+ *
645
+ * `given.owner` is the child's delegation tree owner (the owner of its tree root's row as the root run read it; for a revived
646
+ * child, its own row's): a promotion that creates the durable row records exactly it — the hook derives no owner of its own.
644
647
  */
645
- ensureChildSessionDurable?: (sessionId: string) => Promise<void>;
648
+ ensureChildSessionDurable?: (sessionId: string, given: {
649
+ owner: string | null;
650
+ }) => Promise<void>;
646
651
  };
647
652
  /** Model the child runs on when neither the call nor the agent definition names one (the tool-level explicit seat).
648
653
  * Omitted too ⇒ the deployment's stated `roles.subagent` tier, else the parent run's effective model (`childModelSeat`). */