@sema-agent/core 7.59.0 → 7.60.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (360) hide show
  1. package/CHANGELOG.md +564 -0
  2. package/dist/agents/agent-definition.d.ts +7 -0
  3. package/dist/agents/agent-definition.js +12 -0
  4. package/dist/agents/agent-transcript-tool.d.ts +2 -1
  5. package/dist/agents/agent-transcript-tool.js +3 -1
  6. package/dist/agents/child-model-seat.js +6 -3
  7. package/dist/agents/cumulative-stats.js +0 -1
  8. package/dist/agents/inherited-tool-pool.d.ts +26 -1
  9. package/dist/agents/inherited-tool-pool.js +22 -0
  10. package/dist/agents/retain-ledger.d.ts +11 -1
  11. package/dist/agents/retain-ledger.js +13 -2
  12. package/dist/agents/roster-store.d.ts +1 -1
  13. package/dist/agents/roster-store.js +3 -1
  14. package/dist/agents/send-message-tool.d.ts +8 -19
  15. package/dist/agents/send-message-tool.js +11 -38
  16. package/dist/agents/subagent.d.ts +51 -17
  17. package/dist/agents/subagent.js +117 -78
  18. package/dist/agents/tool-filter.d.ts +1 -3
  19. package/dist/agents/tool-filter.js +4 -12
  20. package/dist/bench/metrics.d.ts +3 -5
  21. package/dist/bench/metrics.js +0 -1
  22. package/dist/brain/degrading.js +3 -1
  23. package/dist/brain/route-adjudicator.js +3 -1
  24. package/dist/brain/status-sink.d.ts +7 -1
  25. package/dist/brain/status-sink.js +6 -0
  26. package/dist/brain/timeout.d.ts +3 -1
  27. package/dist/brain/timeout.js +18 -5
  28. package/dist/core/a2a.d.ts +15 -5
  29. package/dist/core/a2a.js +34 -19
  30. package/dist/core/agent-definition.d.ts +20 -0
  31. package/dist/core/allow-entry.d.ts +2 -0
  32. package/dist/core/allow-entry.js +3 -1
  33. package/dist/core/artifact-host.d.ts +0 -2
  34. package/dist/core/artifact-host.js +0 -1
  35. package/dist/core/auto-mode-defaults.d.ts +8 -0
  36. package/dist/core/auto-mode-defaults.js +1 -0
  37. package/dist/core/auto-mode-rebuild.d.ts +2 -1
  38. package/dist/core/auto-mode.d.ts +39 -4
  39. package/dist/core/auto-mode.js +63 -12
  40. package/dist/core/background-agent-store.d.ts +10 -1
  41. package/dist/core/background-agent-store.js +3 -2
  42. package/dist/core/background-shell.d.ts +12 -1
  43. package/dist/core/background-shell.js +12 -0
  44. package/dist/core/checkpoint-store.d.ts +8 -13
  45. package/dist/core/checkpoint-store.js +4 -3
  46. package/dist/core/compliance.d.ts +1 -1
  47. package/dist/core/credential-echo.d.ts +52 -0
  48. package/dist/core/credential-echo.js +65 -0
  49. package/dist/core/credential-vocabulary.d.ts +13 -3
  50. package/dist/core/credential-vocabulary.js +12 -4
  51. package/dist/core/cross-boundary-taint.d.ts +4 -5
  52. package/dist/core/engine-notice.d.ts +58 -15
  53. package/dist/core/frame-settlement.d.ts +5 -0
  54. package/dist/core/frame-settlement.js +4 -0
  55. package/dist/core/gate-fold.js +7 -5
  56. package/dist/core/gate-lanes.js +39 -8
  57. package/dist/core/governance-codes.d.ts +9 -1
  58. package/dist/core/governance-codes.js +12 -0
  59. package/dist/core/hands-band-screen.js +0 -1
  60. package/dist/core/hands-band.d.ts +0 -3
  61. package/dist/core/hooks.d.ts +39 -56
  62. package/dist/core/hooks.js +123 -77
  63. package/dist/core/image-admission.d.ts +104 -51
  64. package/dist/core/image-admission.js +170 -46
  65. package/dist/core/image-downsample.d.ts +36 -69
  66. package/dist/core/image-downsample.js +111 -73
  67. package/dist/core/integer-option.d.ts +21 -0
  68. package/dist/core/integer-option.js +13 -0
  69. package/dist/core/locked-config.d.ts +54 -3
  70. package/dist/core/locked-config.js +81 -50
  71. package/dist/core/mcp-call-meta.d.ts +2 -2
  72. package/dist/core/mcp-call-meta.js +9 -10
  73. package/dist/core/mcp-failure.d.ts +9 -3
  74. package/dist/core/mcp-failure.js +10 -0
  75. package/dist/core/mcp-host-seat.d.ts +92 -0
  76. package/dist/core/mcp-host-seat.js +131 -0
  77. package/dist/core/mcp-probe.d.ts +7 -2
  78. package/dist/core/mcp-probe.js +7 -2
  79. package/dist/core/mcp-server-spec.d.ts +38 -9
  80. package/dist/core/mcp-server-spec.js +55 -21
  81. package/dist/core/mcp.d.ts +17 -6
  82. package/dist/core/mcp.js +67 -55
  83. package/dist/core/memory-admission.d.ts +23 -6
  84. package/dist/core/memory-admission.js +19 -9
  85. package/dist/core/memory-engine/content-origin.d.ts +13 -0
  86. package/dist/core/memory-engine/content-origin.js +21 -3
  87. package/dist/core/memory-engine/index.d.ts +2 -1
  88. package/dist/core/memory-engine/index.js +2 -1
  89. package/dist/core/memory-engine/scope-contract.d.ts +13 -3
  90. package/dist/core/memory-engine/scope-contract.js +2 -2
  91. package/dist/core/memory-engine/sync-client.d.ts +45 -11
  92. package/dist/core/memory-engine/sync-client.js +82 -11
  93. package/dist/core/memory-engine/sync-report.d.ts +103 -0
  94. package/dist/core/memory-engine/sync-report.js +119 -0
  95. package/dist/core/memory-engine/sync.d.ts +4 -2
  96. package/dist/core/mode-policy.d.ts +9 -1
  97. package/dist/core/mode-policy.js +11 -1
  98. package/dist/core/model-receipt.d.ts +39 -0
  99. package/dist/core/model-receipt.js +139 -0
  100. package/dist/core/mods/agent-stations.d.ts +65 -0
  101. package/dist/core/mods/agent-stations.js +105 -0
  102. package/dist/core/mods/kernel/dispatch.d.ts +5 -1
  103. package/dist/core/mods/kernel/dispatch.js +4 -4
  104. package/dist/core/mods/kernel/events.d.ts +10 -4
  105. package/dist/core/mods/kernel/events.js +10 -6
  106. package/dist/core/mods/kernel/receive.d.ts +5 -0
  107. package/dist/core/mods/kernel/receive.js +10 -0
  108. package/dist/core/mods/lifecycle-stations.d.ts +41 -0
  109. package/dist/core/mods/lifecycle-stations.js +35 -0
  110. package/dist/core/mods/stations.d.ts +51 -59
  111. package/dist/core/mods/stations.js +32 -42
  112. package/dist/core/mods/tool-call.d.ts +10 -4
  113. package/dist/core/mods/tool-call.js +28 -12
  114. package/dist/core/mounted-mcp.d.ts +5 -0
  115. package/dist/core/mounted-mcp.js +2 -2
  116. package/dist/core/namespaced-rule-name.d.ts +7 -1
  117. package/dist/core/namespaced-rule-name.js +13 -2
  118. package/dist/core/oracle-isolation.js +1 -1
  119. package/dist/core/own-property-receipt.d.ts +3 -0
  120. package/dist/core/own-property-receipt.js +3 -0
  121. package/dist/core/park-selfcheck.js +8 -8
  122. package/dist/core/peer-seat.d.ts +63 -8
  123. package/dist/core/peer-seat.js +179 -34
  124. package/dist/core/permission-rule-consent.d.ts +0 -21
  125. package/dist/core/permission-rule-consent.js +1 -2
  126. package/dist/core/permission-rule-model.d.ts +4 -2
  127. package/dist/core/permission-rule-model.js +7 -6
  128. package/dist/core/protocol-http-auth.d.ts +14 -2
  129. package/dist/core/protocol-http-auth.js +16 -7
  130. package/dist/core/read-face-seats.d.ts +7 -5
  131. package/dist/core/read-face-seats.js +4 -1
  132. package/dist/core/redaction-marks.d.ts +4 -3
  133. package/dist/core/redaction-marks.js +2 -2
  134. package/dist/core/remote-env.d.ts +146 -98
  135. package/dist/core/remote-env.js +113 -14
  136. package/dist/core/retention.js +37 -12
  137. package/dist/core/retired-keys.d.ts +6 -1
  138. package/dist/core/retired-keys.js +4 -1
  139. package/dist/core/rewrite-rejudge.d.ts +12 -5
  140. package/dist/core/rewrite-rejudge.js +9 -5
  141. package/dist/core/roles.d.ts +37 -3
  142. package/dist/core/roles.js +126 -78
  143. package/dist/core/rule-owner.d.ts +3 -0
  144. package/dist/core/runner/assemble-result.d.ts +0 -5
  145. package/dist/core/runner/assemble-result.js +0 -1
  146. package/dist/core/runner/call-hook-stations.d.ts +17 -10
  147. package/dist/core/runner/call-hook-stations.js +21 -10
  148. package/dist/core/runner/child-tree.d.ts +7 -8
  149. package/dist/core/runner/child-tree.js +6 -6
  150. package/dist/core/runner/classifier-ladder.d.ts +10 -2
  151. package/dist/core/runner/classifier-ladder.js +39 -8
  152. package/dist/core/runner/construction-doors.js +5 -0
  153. package/dist/core/runner/contracts.d.ts +62 -41
  154. package/dist/core/runner/cross-boundary-lane.d.ts +3 -5
  155. package/dist/core/runner/cross-boundary-lane.js +11 -2
  156. package/dist/core/runner/env-capability-census.d.ts +15 -20
  157. package/dist/core/runner/env-capability-census.js +25 -34
  158. package/dist/core/runner/file-history-request.d.ts +2 -2
  159. package/dist/core/runner/file-history-request.js +0 -8
  160. package/dist/core/runner/gate-exit.d.ts +75 -7
  161. package/dist/core/runner/gate-exit.js +20 -1
  162. package/dist/core/runner/git-status-frame.d.ts +5 -2
  163. package/dist/core/runner/git-status-frame.js +3 -4
  164. package/dist/core/runner/image.d.ts +7 -2
  165. package/dist/core/runner/image.js +14 -8
  166. package/dist/core/runner/inline-image.d.ts +10 -8
  167. package/dist/core/runner/inline-image.js +11 -9
  168. package/dist/core/runner/memory-consolidation-driver.js +4 -4
  169. package/dist/core/runner/permission-rule-lanes.js +1 -1
  170. package/dist/core/runner/prepare-boundary-parks.d.ts +2 -2
  171. package/dist/core/runner/prepare-boundary-parks.js +3 -3
  172. package/dist/core/runner/prepare-caps-and-workflow.d.ts +4 -0
  173. package/dist/core/runner/prepare-caps-and-workflow.js +4 -3
  174. package/dist/core/runner/prepare-config-doors.d.ts +6 -1
  175. package/dist/core/runner/prepare-config-doors.js +14 -9
  176. package/dist/core/runner/prepare-delegation-surface.d.ts +5 -3
  177. package/dist/core/runner/prepare-delegation-surface.js +4 -4
  178. package/dist/core/runner/prepare-file-history.d.ts +10 -12
  179. package/dist/core/runner/prepare-file-history.js +3 -12
  180. package/dist/core/runner/prepare-gate-stations.d.ts +4 -3
  181. package/dist/core/runner/prepare-gate-stations.js +4 -3
  182. package/dist/core/runner/prepare-hands-readface.d.ts +3 -1
  183. package/dist/core/runner/prepare-hands-readface.js +15 -7
  184. package/dist/core/runner/prepare-inherited-gate.d.ts +5 -4
  185. package/dist/core/runner/prepare-inherited-gate.js +9 -5
  186. package/dist/core/runner/prepare-memory-engine-session.js +1 -1
  187. package/dist/core/runner/prepare-memory.d.ts +2 -2
  188. package/dist/core/runner/prepare-memory.js +2 -2
  189. package/dist/core/runner/prepare-park-ask.d.ts +3 -5
  190. package/dist/core/runner/prepare-park-ask.js +3 -8
  191. package/dist/core/runner/prepare-policy-chain.d.ts +5 -4
  192. package/dist/core/runner/prepare-policy-chain.js +120 -108
  193. package/dist/core/runner/prepare-project-context.js +8 -5
  194. package/dist/core/runner/prepare-prompt-inputs.d.ts +4 -1
  195. package/dist/core/runner/prepare-prompt-inputs.js +3 -2
  196. package/dist/core/runner/prepare-protocol-tools.d.ts +5 -3
  197. package/dist/core/runner/prepare-protocol-tools.js +9 -2
  198. package/dist/core/runner/prepare-suspend-saga.d.ts +0 -2
  199. package/dist/core/runner/prepare-suspend-saga.js +5 -7
  200. package/dist/core/runner/prepare-task.js +41 -27
  201. package/dist/core/runner/prepare-turn-wiring.d.ts +2 -0
  202. package/dist/core/runner/prepare-turn-wiring.js +7 -2
  203. package/dist/core/runner/prepare-wiring-manifest.d.ts +4 -3
  204. package/dist/core/runner/prepare-wiring-manifest.js +32 -18
  205. package/dist/core/runner/prepare-workspace-restore.js +3 -3
  206. package/dist/core/runner/resume-checkpoint-screen.js +4 -4
  207. package/dist/core/runner/retired-runner-deps.js +4 -1
  208. package/dist/core/runner/run-attachment-seats.js +3 -3
  209. package/dist/core/runner/run-brain-sinks.js +1 -0
  210. package/dist/core/runner/run-git-lane.d.ts +3 -1
  211. package/dist/core/runner/run-git-lane.js +1 -1
  212. package/dist/core/runner/run-harness-handlers.d.ts +3 -1
  213. package/dist/core/runner/run-harness-handlers.js +3 -1
  214. package/dist/core/runner/run-identity-wiring.js +1 -1
  215. package/dist/core/runner/run-leg.js +26 -28
  216. package/dist/core/runner/run-notification-lane.d.ts +3 -1
  217. package/dist/core/runner/run-notification-lane.js +16 -10
  218. package/dist/core/runner/run-settle-and-teardown.js +5 -1
  219. package/dist/core/runner/run-stop-and-final-verify.d.ts +4 -0
  220. package/dist/core/runner/run-stop-and-final-verify.js +12 -4
  221. package/dist/core/runner/run-turn-boundary.js +12 -7
  222. package/dist/core/runner/runtask.d.ts +7 -4
  223. package/dist/core/runner/runtask.js +19 -11
  224. package/dist/core/runner/skills-seat.js +2 -2
  225. package/dist/core/runner/sub-agent-deny-lists.js +10 -7
  226. package/dist/core/runner/synthetic-tools.js +2 -2
  227. package/dist/core/runner/tool-disclosure.js +0 -2
  228. package/dist/core/runner/tool-face-overlay.d.ts +1 -1
  229. package/dist/core/runner/tool-face-overlay.js +26 -19
  230. package/dist/core/runner/tool-result-media-seat.d.ts +9 -1
  231. package/dist/core/runner/tool-result-media-seat.js +17 -1
  232. package/dist/core/runner/turn-attachments.d.ts +3 -5
  233. package/dist/core/runner/turn-attachments.js +3 -16
  234. package/dist/core/runner-deps.d.ts +31 -18
  235. package/dist/core/secret-env.d.ts +3 -2
  236. package/dist/core/session-policy-store.d.ts +9 -2
  237. package/dist/core/session-policy-store.js +16 -1
  238. package/dist/core/session-store.d.ts +3 -2
  239. package/dist/core/session-store.js +50 -11
  240. package/dist/core/skill-grant.d.ts +9 -0
  241. package/dist/core/skill-grant.js +18 -0
  242. package/dist/core/store-contracts/tool-result-store-contract.d.ts +1 -1
  243. package/dist/core/store-contracts/tool-result-store-contract.js +37 -0
  244. package/dist/core/stub-env.d.ts +5 -5
  245. package/dist/core/stub-env.js +11 -1
  246. package/dist/core/swappable-deps.d.ts +17 -43
  247. package/dist/core/swappable-deps.js +15 -5
  248. package/dist/core/synthetic-read-verdict.d.ts +1 -1
  249. package/dist/core/task-event.d.ts +18 -2
  250. package/dist/core/task-notification.d.ts +88 -5
  251. package/dist/core/task-notification.js +130 -7
  252. package/dist/core/task-registry-agent.d.ts +18 -12
  253. package/dist/core/task-registry-agent.js +18 -6
  254. package/dist/core/task-registry-monitor.d.ts +7 -0
  255. package/dist/core/task-registry-monitor.js +28 -1
  256. package/dist/core/task-registry-shared.d.ts +38 -3
  257. package/dist/core/task-registry-shared.js +21 -7
  258. package/dist/core/task-registry-workflow.js +1 -1
  259. package/dist/core/task-registry.d.ts +50 -35
  260. package/dist/core/task-registry.js +64 -23
  261. package/dist/core/task-result.d.ts +3 -12
  262. package/dist/core/task-spec.d.ts +3 -6
  263. package/dist/core/task-stream.d.ts +1 -1
  264. package/dist/core/tool-catalog-entries.js +1 -1
  265. package/dist/core/tool-face-reader.d.ts +7 -6
  266. package/dist/core/tool-face-reader.js +4 -3
  267. package/dist/core/tool-name-aliases.d.ts +19 -0
  268. package/dist/core/tool-name-aliases.js +54 -2
  269. package/dist/core/tool-policy.d.ts +5 -4
  270. package/dist/core/tool-policy.js +1 -1
  271. package/dist/core/tool-registry.d.ts +5 -5
  272. package/dist/core/tool-registry.js +2 -2
  273. package/dist/core/tool-result-store.d.ts +88 -5
  274. package/dist/core/tool-result-store.js +51 -12
  275. package/dist/core/tool-spec.d.ts +20 -4
  276. package/dist/core/trace.d.ts +0 -1
  277. package/dist/core/types.d.ts +3 -3
  278. package/dist/core/types.js +1 -1
  279. package/dist/core/untrusted-text.js +1 -1
  280. package/dist/core/user-attachment.d.ts +10 -5
  281. package/dist/core/user-attachment.js +14 -6
  282. package/dist/engine/execution-env/node-execution-env.d.ts +7 -2
  283. package/dist/engine/execution-env/node-execution-env.js +12 -1
  284. package/dist/engine/harness/agent-harness.d.ts +1 -1
  285. package/dist/engine/harness/agent-harness.js +8 -4
  286. package/dist/engine/harness/types.d.ts +112 -29
  287. package/dist/engine/loop/agent-loop.d.ts +12 -12
  288. package/dist/engine/loop/agent-loop.js +153 -21
  289. package/dist/engine/loop/types.d.ts +9 -2
  290. package/dist/engine/lsp/node-lsp-manager.d.ts +3 -3
  291. package/dist/engine/lsp/node-lsp-manager.js +32 -13
  292. package/dist/index.d.ts +22 -14
  293. package/dist/index.js +15 -10
  294. package/dist/internal/harness-types.d.ts +1 -1
  295. package/dist/orchestration/run-workflow-tool.d.ts +9 -3
  296. package/dist/orchestration/run-workflow-tool.js +59 -29
  297. package/dist/orchestration/workflow-governance.d.ts +1 -1
  298. package/dist/orchestration/workflow-governance.js +2 -1
  299. package/dist/orchestration/workflow.d.ts +4 -0
  300. package/dist/orchestration/workflow.js +25 -4
  301. package/dist/prompts/default.d.ts +1 -10
  302. package/dist/prompts/default.js +0 -2
  303. package/dist/stores/file/background-agent-store.d.ts +1 -1
  304. package/dist/stores/file/background-agent-store.js +3 -1
  305. package/dist/stores/file/checkpoint-store.d.ts +127 -2
  306. package/dist/stores/file/checkpoint-store.js +19 -14
  307. package/dist/stores/file/file-history-store.d.ts +1 -1
  308. package/dist/stores/file/file-history-store.js +3 -1
  309. package/dist/stores/file/index.d.ts +4 -3
  310. package/dist/stores/file/index.js +17 -8
  311. package/dist/stores/file/mailbox-store.d.ts +1 -1
  312. package/dist/stores/file/mailbox-store.js +3 -1
  313. package/dist/stores/file/memory-store.d.ts +1 -1
  314. package/dist/stores/file/memory-store.js +3 -1
  315. package/dist/stores/file/session-policy-store.d.ts +1 -1
  316. package/dist/stores/file/session-policy-store.js +3 -1
  317. package/dist/stores/file/session-store.d.ts +1 -1
  318. package/dist/stores/file/session-store.js +3 -1
  319. package/dist/stores/file/shared-ledger.d.ts +26 -0
  320. package/dist/stores/file/shared-ledger.js +38 -9
  321. package/dist/stores/file/tool-result-store.d.ts +20 -2
  322. package/dist/stores/file/tool-result-store.js +74 -6
  323. package/dist/stores/file/usage-window-store.d.ts +1 -1
  324. package/dist/stores/file/usage-window-store.js +3 -1
  325. package/dist/stores/file/workflow-journal-store.d.ts +1 -11
  326. package/dist/stores/file/workflow-journal-store.js +3 -2
  327. package/dist/tools/fs/containment-face.d.ts +5 -0
  328. package/dist/tools/fs/encoding.d.ts +13 -4
  329. package/dist/tools/fs/encoding.js +17 -2
  330. package/dist/tools/fs/fs-bash-background-text.d.ts +7 -0
  331. package/dist/tools/fs/fs-bash-background-text.js +1 -0
  332. package/dist/tools/fs/fs-bash.d.ts +8 -4
  333. package/dist/tools/fs/fs-bash.js +26 -35
  334. package/dist/tools/fs/fs-pdf.d.ts +2 -2
  335. package/dist/tools/fs/fs-pdf.js +26 -21
  336. package/dist/tools/fs/fs-read.d.ts +5 -4
  337. package/dist/tools/fs/fs-read.js +35 -18
  338. package/dist/tools/fs/fs-search-tools.js +4 -1
  339. package/dist/tools/fs/fs-shared.d.ts +11 -13
  340. package/dist/tools/fs/fs-shared.js +11 -7
  341. package/dist/tools/fs/fs-write.js +5 -5
  342. package/dist/tools/fs/index.d.ts +14 -8
  343. package/dist/tools/fs/index.js +8 -4
  344. package/dist/tools/fs/read-floor.d.ts +44 -1
  345. package/dist/tools/fs/read-floor.js +35 -0
  346. package/dist/tools/fs/removal-targets.d.ts +9 -4
  347. package/dist/tools/fs/removal-targets.js +17 -9
  348. package/dist/tools/fs/search.d.ts +3 -3
  349. package/dist/tools/fs/search.js +4 -4
  350. package/dist/tools/monitor.d.ts +5 -4
  351. package/dist/tools/monitor.js +15 -8
  352. package/dist/tools/scheduler-tools.js +42 -4
  353. package/dist/tools/web.d.ts +0 -10
  354. package/dist/tools/web.js +1 -4
  355. package/package.json +4 -2
  356. package/test/export-surface.snapshot.json +75 -21
  357. package/wire-changes/core-stores-sql@7.60.0.json +30 -0
  358. package/wire-changes/core@7.60.0.json +3274 -0
  359. package/wire-changes/mods-kernel@7.60.0.json +62 -0
  360. package/wire-changes/primitives@7.60.0.json +30 -0
@@ -9,7 +9,8 @@ export type EvictPolicy = "delete" | "forget";
9
9
  export interface TtlSessionStoreOptions {
10
10
  /** Idle TTL before a cached session is evicted. Default 7 days. */
11
11
  defaultTtlDays?: number;
12
- /** Optional background sweep interval (ms). Off by default (sweeps opportunistically on acquire). */
12
+ /** Optional background sweep interval: a whole number of milliseconds from 1 to 2147483647 (the longest a timer takes; any other
13
+ * value is refused, `config.invalid_argument`). Omit it for no background sweep (sweeps opportunistically on acquire). */
13
14
  sweepIntervalMs?: number;
14
15
  /**
15
16
  * Backing session repo. Default `InMemorySessionRepo` (process-only, lost on restart). Supply a
@@ -171,7 +172,7 @@ export declare class TtlSessionStore implements SessionStore {
171
172
  private defaultTtlMs;
172
173
  private evictPolicy;
173
174
  private sweepTimer?;
174
- constructor(opts?: TtlSessionStoreOptions);
175
+ constructor(options?: TtlSessionStoreOptions);
175
176
  /** Get an existing session by id (resuming from the repo if needed), or create one. */
176
177
  acquire(sessionId?: string, opts?: {
177
178
  requireExisting?: boolean;
@@ -3,7 +3,10 @@ import { isSessionConflict, readSessionListQuery } from "./session.js";
3
3
  import { readRetentionDeclaration } from "./retention.js";
4
4
  import { readMember } from "./thrown-value.js";
5
5
  import { principalNameFault, principalNameOf } from "./principal-name.js";
6
- import { receiptRefusal, receiveOwnProperties } from "./own-property-receipt.js";
6
+ import { DECLARATION_RECEIPT_MODE, receiptRefusal, receiveOptions, receiveOwnProperties } from "./own-property-receipt.js";
7
+ import { describeFault, receive } from "./mods/kernel/receive.js";
8
+ import { describeRejectedValue } from "./tool-search-setting.js";
9
+ import { readIntegerOption, TIMER_DELAY_MS } from "./integer-option.js";
7
10
  import { repoLogTransfer } from "./session-log-transfer.js";
8
11
  const DAY_MS = 24 * 60 * 60 * 1000;
9
12
  import { SESSION_DEFAULT_TTL_DAYS } from "../config/defaults.js";
@@ -43,16 +46,18 @@ export class TtlSessionStore {
43
46
  defaultTtlMs;
44
47
  evictPolicy;
45
48
  sweepTimer;
46
- constructor(opts = {}) {
49
+ constructor(options) {
50
+ const opts = receiveOptions(options, "TtlSessionStore");
47
51
  this.retention = readRetentionDeclaration("TtlSessionStoreOptions.retention", opts.retention);
48
- this.repo = opts.repo ?? new InMemorySessionRepo();
49
- const durability = opts.durability ?? (opts.repo === undefined ? "process-local" : undefined);
52
+ const givenRepo = opts.repo;
53
+ this.repo = givenRepo ?? new InMemorySessionRepo();
54
+ const durability = opts.durability !== undefined ? durabilityWord("TtlSessionStoreOptions.durability", opts.durability) : givenRepo === undefined ? "process-local" : undefined;
50
55
  if (durability !== undefined)
51
56
  this.durability = durability;
52
- this.defaultTtlMs = (opts.defaultTtlDays ?? SESSION_DEFAULT_TTL_DAYS) * DAY_MS;
53
- this.evictPolicy = opts.evict ?? (opts.repo ? "forget" : "delete");
57
+ this.defaultTtlMs = ttlDays(opts.defaultTtlDays) * DAY_MS;
58
+ this.evictPolicy = opts.evict !== undefined ? evictWord(opts.evict) : givenRepo ? "forget" : "delete";
54
59
  if (opts.placements !== undefined)
55
- this.placements = opts.placements;
60
+ this.placements = placementsDeclaration(opts.placements);
56
61
  const repoListPlaced = this.repo.listPlaced;
57
62
  if (typeof repoListPlaced === "function") {
58
63
  this.listPlaced = (kind, o) => repoListPlaced.call(this.repo, kind, o);
@@ -78,11 +83,13 @@ export class TtlSessionStore {
78
83
  });
79
84
  }
80
85
  }
81
- const beforeRowDelete = readStoreHooks(opts.hooks);
86
+ const hooks = opts.hooks;
87
+ const beforeRowDelete = readStoreHooks(hooks);
82
88
  if (beforeRowDelete !== undefined)
83
- this.beforeRowDelete = (sessionId) => Reflect.apply(beforeRowDelete, opts.hooks, [sessionId]);
84
- if (opts.sweepIntervalMs !== undefined && opts.sweepIntervalMs > 0) {
85
- this.sweepTimer = setInterval(() => this.sweep(), opts.sweepIntervalMs);
89
+ this.beforeRowDelete = (sessionId) => Reflect.apply(beforeRowDelete, hooks, [sessionId]);
90
+ const sweepIntervalMs = readIntegerOption("TtlSessionStoreOptions.sweepIntervalMs", opts.sweepIntervalMs, TIMER_DELAY_MS, "milliseconds", "no background sweep");
91
+ if (sweepIntervalMs !== undefined) {
92
+ this.sweepTimer = setInterval(() => this.sweep(), sweepIntervalMs);
86
93
  this.sweepTimer.unref?.();
87
94
  }
88
95
  }
@@ -491,6 +498,38 @@ function newestFirst(a, b) {
491
498
  return b.lastActiveAt - a.lastActiveAt;
492
499
  return a.sessionId < b.sessionId ? 1 : a.sessionId > b.sessionId ? -1 : 0;
493
500
  }
501
+ function durabilityWord(name, value) {
502
+ if (value === "durable" || value === "process-local")
503
+ return value;
504
+ throw receiptRefusal(`${name} must be "durable" or "process-local" when given (got ${describeRejectedValue(value)})`);
505
+ }
506
+ function ttlDays(value) {
507
+ if (value === undefined)
508
+ return SESSION_DEFAULT_TTL_DAYS;
509
+ if (typeof value === "number" && Number.isFinite(value) && value >= 0)
510
+ return value;
511
+ throw receiptRefusal(`TtlSessionStoreOptions.defaultTtlDays must be a finite non-negative number of days when given (got ${describeRejectedValue(value)})`);
512
+ }
513
+ function evictWord(value) {
514
+ if (value === "delete" || value === "forget")
515
+ return value;
516
+ throw receiptRefusal(`TtlSessionStoreOptions.evict must be "delete" or "forget" when given (got ${describeRejectedValue(value)})`);
517
+ }
518
+ function placementsDeclaration(value) {
519
+ const got = receive(value, DECLARATION_RECEIPT_MODE);
520
+ if (!got.ok)
521
+ throw receiptRefusal(`TtlSessionStoreOptions.placements could not be read as plain data — ${describeFault(got.fault)}`);
522
+ const held = got.value;
523
+ if (typeof held !== "object" || held === null || Array.isArray(held))
524
+ throw receiptRefusal(`TtlSessionStoreOptions.placements must be a record when given (got ${describeRejectedValue(held)})`);
525
+ const subagent = held.subagent;
526
+ if (subagent !== undefined) {
527
+ if (typeof subagent !== "object" || subagent === null || Array.isArray(subagent))
528
+ throw receiptRefusal(`TtlSessionStoreOptions.placements.subagent must be a record when given (got ${describeRejectedValue(subagent)})`);
529
+ durabilityWord("TtlSessionStoreOptions.placements.subagent.durability", subagent.durability);
530
+ }
531
+ return held;
532
+ }
494
533
  function readStoreHooks(hooks) {
495
534
  if (hooks === undefined)
496
535
  return undefined;
@@ -46,6 +46,15 @@ export interface SkillGrantSource {
46
46
  * the person's invoked names are read through it ({@link seedSkillGrants}).
47
47
  */
48
48
  export declare function skillNamedBy<T extends Pick<SkillGrantSource, "name">>(args: unknown, skills: readonly T[]): T | undefined;
49
+ /**
50
+ * The listed name a missed `Skill` call most likely meant, for the refusal to say — never to act on ({@link skillNamedBy} stays
51
+ * the ONE resolution: nothing activates, binds or digests under a name the table does not spell exactly). The nearest listed
52
+ * name within two edits ({@link closestName}); failing that, the asked name with the foreign namespace prefix taken off when
53
+ * that bare name is listed. Undefined: nothing near, no `skill` member that is a string, or an empty one.
54
+ */
55
+ export declare function skillNameSuggestion<T extends Pick<SkillGrantSource, "name">>(args: unknown, skills: readonly T[]): string | undefined;
56
+ /** The sentence the refusal of a missed `Skill` call adds for {@link skillNameSuggestion} (leading space included), or `""` when there is nothing to suggest. */
57
+ export declare function skillNameHint<T extends Pick<SkillGrantSource, "name">>(args: unknown, skills: readonly T[]): string;
49
58
  /** The digest of what a Skill card disclosed — `Execute skill: <name>` and the lists approving it releases ({@link skillGrantBinding}). The read point a parked Skill approval binds to (stored beside the row's input binding, compared before the resumed activation). */
50
59
  export declare function skillGrantDigest(skill: Pick<SkillGrantSource, "name" | "allowedTools" | "disallowedTools"> | undefined): string;
51
60
  /**
@@ -5,6 +5,7 @@ import { inlineUntrusted } from "./untrusted-text.js";
5
5
  import { boundInputHashOf } from "./canonical-json.js";
6
6
  import { NOT_BINDABLE } from "./skill-grant-binding.js";
7
7
  import { readToolNameList } from "./tool-name-list.js";
8
+ import { closestName } from "./task-registry-shared.js";
8
9
  import { allowingRows, strippedInAuto, compileAllowList, readRuleEntry, inertEntryPhrase, judgeAllowEntries, nonListValueLabel, renderListEntry, spelledListEntry } from "./allow-entry.js";
9
10
  export const SKILL_GRANT_ORIGINS = Object.freeze(["model", "user", "inherited"]);
10
11
  const FROZEN_SKILL_GRANT_ORIGINS = new Set(["model", "inherited"]);
@@ -12,6 +13,23 @@ export function skillNamedBy(args, skills) {
12
13
  const named = args?.skill;
13
14
  return typeof named === "string" ? skills.find((s) => s.name === named) : undefined;
14
15
  }
16
+ const FOREIGN_SKILL_NAMESPACE = "anthropic-skills:";
17
+ export function skillNameSuggestion(args, skills) {
18
+ const named = args?.skill;
19
+ if (typeof named !== "string" || named.trim() === "")
20
+ return undefined;
21
+ const nearest = closestName(named, skills.map((s) => s.name));
22
+ if (nearest !== undefined)
23
+ return nearest;
24
+ if (!named.startsWith(FOREIGN_SKILL_NAMESPACE))
25
+ return undefined;
26
+ const bare = named.slice(FOREIGN_SKILL_NAMESPACE.length);
27
+ return skills.some((s) => s.name === bare) ? bare : undefined;
28
+ }
29
+ export function skillNameHint(args, skills) {
30
+ const suggestion = skillNameSuggestion(args, skills);
31
+ return suggestion === undefined ? "" : ` Did you mean ${suggestion}? Invoke it by that full name.`;
32
+ }
15
33
  function readsAsNothingLabel(inert) {
16
34
  return `<reads as nothing (${inert.reason}): ${spelledListEntry(inert.entry)}>`;
17
35
  }
@@ -20,6 +20,6 @@ import { type ContractAssertionRunner } from "./contract-harness.js";
20
20
  * exactly the divergence the two legs above exist to prevent.
21
21
  */
22
22
  export declare function toolResultStoreContract(make: () => ToolResultStore, runAssertion?: ContractAssertionRunner, onOptionalMember?: (report: {
23
- member: "deleteBySession";
23
+ member: "deleteBySession" | "listBySession";
24
24
  status: "verified" | "absent";
25
25
  }) => void): Promise<void>;
@@ -80,5 +80,42 @@ export async function toolResultStoreContract(make, runAssertion, onOptionalMemb
80
80
  assert.equal((await store.get("tr_sweep~other")).content, "OTHER-bytes");
81
81
  onOptionalMember?.({ member: "deleteBySession", status: "verified" });
82
82
  });
83
+ run("listBySession (optional): the sweep's selection, read-only; absence is REPORTED, not silently green", async () => {
84
+ const probe = make();
85
+ if (probe.listBySession === undefined) {
86
+ onOptionalMember?.({ member: "listBySession", status: "absent" });
87
+ return;
88
+ }
89
+ assert.equal(typeof probe.listBySession, "function", `listBySession is present but not callable (got ${typeof probe.listBySession}) — a garbage member is a DEFECT, not an optional-member absence`);
90
+ const store = make();
91
+ const list = async (sessionId) => Promise.resolve(store.listBySession(sessionId));
92
+ const refsOf = (l) => l.entries.map((e) => e.ref).sort();
93
+ await store.put("tr_list~a", "A-bytes", { sessionId: "sess-L", taskId: "t1" });
94
+ await store.put("tr_list~b", "B-bytes", { sessionId: "sess-L" });
95
+ await store.put("tr_list~other", "OTHER-bytes", { sessionId: "sess-M" });
96
+ await store.put("tr_list~unowned", "UNOWNED-bytes");
97
+ const first = await list("sess-L");
98
+ assert.deepEqual(refsOf(first), ["tr_list~a", "tr_list~b"], "the session's rows, and only those, are listed");
99
+ const byRef = new Map(first.entries.map((e) => [e.ref, e.provenance]));
100
+ assert.deepEqual(byRef.get("tr_list~a"), { sessionId: "sess-L", taskId: "t1" }, "the recorded owner rides the entry, taskId included");
101
+ assert.deepEqual(byRef.get("tr_list~b"), { sessionId: "sess-L" }, "a session-only owner carries no taskId");
102
+ assert.equal(first.unaddressable, 0, "every row here was written by this store: none is unaddressable (the count is for rows written before the ref was recorded, never a second kind)");
103
+ assert.equal((await store.get("tr_list~a")).content, "A-bytes");
104
+ assert.deepEqual(await store.ownerOf("tr_list~a"), byRef.get("tr_list~a"), "the listed owner is the one ownerOf answers");
105
+ assert.equal(refsOf(first).includes("tr_list~other"), false, "another session's row is not listed");
106
+ assert.equal(refsOf(first).includes("tr_list~unowned"), false, "an unowned row is never listed");
107
+ assert.equal(first.unattributable >= 1, true, "an unowned row is counted unattributable");
108
+ const none = await list("sess-nobody");
109
+ assert.deepEqual(none.entries, [], "a session with no entries lists none");
110
+ assert.deepEqual(refsOf(await list("sess-L")), refsOf(first), "listing deletes and changes nothing");
111
+ assert.equal((await store.get("tr_list~b")).content, "B-bytes", "a listing leaves the bytes where they were");
112
+ if (store.deleteBySession !== undefined) {
113
+ const swept = await Promise.resolve(store.deleteBySession("sess-L"));
114
+ assert.equal(swept.deleted, first.entries.length + first.unaddressable, "the sweep deletes exactly the listed rows and the ones the listing counted but could not name");
115
+ assert.deepEqual((await list("sess-L")).entries, [], "a swept session lists nothing");
116
+ assert.equal((await store.get("tr_list~other")).content, "OTHER-bytes", "another session's row survives the sweep");
117
+ }
118
+ onOptionalMember?.({ member: "listBySession", status: "verified" });
119
+ });
83
120
  await settle();
84
121
  }
@@ -1,4 +1,4 @@
1
- import { type ExecResult, type ExecutionEnv, ExecutionError, FileError, type FileInfo, type Result } from "../internal/harness.js";
1
+ import { type ExecResult, type ExecutionEnv, type ExecutionEnvCapabilities, ExecutionError, FileError, type FileInfo, type Result } from "../internal/harness.js";
2
2
  /**
3
3
  * A no-op ExecutionEnv for tool/MCP-only deployments (no shell, no filesystem).
4
4
  *
@@ -8,10 +8,10 @@ import { type ExecResult, type ExecutionEnv, ExecutionError, FileError, type Fil
8
8
  */
9
9
  export declare class StubExecutionEnv implements ExecutionEnv {
10
10
  cwd: string;
11
- /** design/380 O9a — declared on the class so the prepare fold can read the optional interface
12
- * member off a `ExecutionEnv | StubExecutionEnv` union; the no-I/O stub produces no target
13
- * content, so it never declares (always `undefined` — the trusted-side default). */
14
- readonly externalContentTarget?: boolean;
11
+ /** `ExecutionEnv.capabilities`: no target at all (`io: false`) — every operation refuses, so it produces no outside
12
+ * content, names no path that is not the engine host's, and keeps the byte floor by refusing every start
13
+ * (`keepsReadFloor: true`). A subclass that overrides operations with real I/O states its own block. */
14
+ readonly capabilities: ExecutionEnvCapabilities;
15
15
  /** `ExecutionEnv.cdPath`: the stub runs no shell, so no shell receives a `CDPATH`. */
16
16
  readonly cdPath: readonly string[];
17
17
  /** `ExecutionEnv.withheldEnv`: no shell child, so nothing is withheld from one. */
@@ -1,7 +1,17 @@
1
1
  import { ExecutionError, FileError, err, } from "../internal/harness.js";
2
+ const STUB_ENV_CAPABILITIES = Object.freeze({
3
+ isolation: false,
4
+ suspendable: false,
5
+ sharesProcessTable: true,
6
+ canonicalPathAuthoritative: false,
7
+ hostLocalPaths: true,
8
+ externalContentTarget: false,
9
+ io: false,
10
+ keepsReadFloor: true,
11
+ });
2
12
  export class StubExecutionEnv {
3
13
  cwd;
4
- externalContentTarget;
14
+ capabilities = STUB_ENV_CAPABILITIES;
5
15
  cdPath = [];
6
16
  withheldEnv = [];
7
17
  constructor(cwd = "/") {
@@ -1,41 +1,3 @@
1
- /**
2
- * The deployment seats a Runner may HOT-SWAP after construction — the vocabulary behind the ONE door,
3
- * `Runner.swapDeps` (runtask.ts).
4
- *
5
- * WHY ONE DOOR. Each hot-swappable seat used to be a verb of its own (`swapModels` was the first), and a
6
- * verb per seat restates the same three laws every time — validate the candidate BEFORE anything is
7
- * written, write the deps object ONCE (a swap is atomic: a refused candidate leaves the current deps
8
- * byte-identical), announce the change under a notice code — while the question "which seats may be
9
- * swapped at all" was answered by the list of verbs, i.e. by nothing a compiler could see. With one door
10
- * the laws are stated once, the swappable set is THIS closed list, and every seat carries its rows in
11
- * the tables beside it: the compiler refuses a member without its rows ({@link AssertAllKeysHandled}),
12
- * the door refuses a key outside the set at run time (never a silent ignore — a hot-config driver
13
- * handing `{ brain }` must learn that the brain is not a swappable seat, not watch nothing happen).
14
- *
15
- * WHAT A SWAP MEANS — the natural snapshot, one sentence for every ROUTING seat: a running task reads the
16
- * deps object it was handed at its prepare and holds that reference; a swap replaces the Runner's object, so
17
- * every LATER prepare reads the new seat and every in-flight leg keeps the value it prepared under.
18
- * Nothing is re-routed, re-priced or re-fenced mid-run; the divergence window is exactly the in-flight
19
- * legs' lifetime, by design (the `swapModels` precedent).
20
- *
21
- * …WITH ONE SEAT OUTSIDE IT, and the boundary is the point rather than the exception: `contextSettings` is
22
- * read LIVE by in-flight legs. The snapshot law protects the routing CARD — a request already in flight must
23
- * reach the endpoint it was priced, credentialed and fenced for, and re-reading any of that mid-run buys
24
- * nothing and breaks the request. A leg's usable WINDOW is not on that card: it is a setting about how much
25
- * conversation may accumulate before the leg summarizes, the reference implementation keeps it off the model
26
- * object for exactly this reason and re-reads it on every request (clamped to the model's physical window),
27
- * and an operator who lowers it is asking the legs running RIGHT NOW to compact sooner — which is the whole
28
- * request. So the window declarations live on their own seat (`context-settings.ts`), keyed by catalog word,
29
- * and the legs read them at every boundary, every recovery pass, the end-of-task summary and every request
30
- * build. Routing stays snapshotted; geometry follows the operator. The two are not the same question, and
31
- * one law over both could only be wrong about one of them.
32
- *
33
- * KEY PRESENCE IS THE INSTRUCTION: a key present on the candidate is REPLACED (an explicit `undefined`
34
- * CLEARS an optional seat back to its engine default — `readFace: undefined` ⇒ the deployment declares
35
- * no read face, `tiers: undefined` ⇒ no tier bindings); a key absent is KEPT. `Object.hasOwn`, never
36
- * truthiness, so the two spellings cannot be confused. An EMPTY candidate is refused: a swap that names
37
- * no seat is a caller defect, not a no-op.
38
- */
39
1
  import type { AssertAllKeysHandled } from "./ask-origin.js";
40
2
  import type { RunnerDeps } from "./runner-deps.js";
41
3
  import { type ReadDenyDeploymentSeat } from "./read-face-seats.js";
@@ -60,12 +22,13 @@ import { type ReadDenyDeploymentSeat } from "./read-face-seats.js";
60
22
  * - `contextSettings` — the per-model context-window overlay ({@link RunnerDeps.contextSettings}); screened
61
23
  * by the same value gate construction applies (`assertContextSettingsValue`). THE ONE SEAT
62
24
  * IN-FLIGHT LEGS RE-READ — see the header: it carries geometry, not route.
63
- * - `readDenyPatterns` / `readDenyBuiltinTiers` / `readDenyBuiltinExclude` — the deployment's read-deny
64
- * declaration (additions, built-in tier selection, built-in row removal); screened by the
65
- * gates a prepare applies ({@link screenReadDenySeat}). A resumed leg compiles against the
66
- * seats in force at its prepare (the checkpoint keeps additions only, stricter-wins).
25
+ * - `readDenyPatterns` / `readDenyBuiltinTiers` / `readDenyBuiltinExclude` / `readDenyFloorRequired` — the
26
+ * deployment's read-deny declaration (additions, built-in tier selection, built-in row removal,
27
+ * whether the byte floor must be kept); screened by the gates a prepare applies
28
+ * ({@link screenReadDenySeat}). A resumed leg compiles against the seats in force at its prepare
29
+ * (the checkpoint keeps additions only, stricter-wins).
67
30
  */
68
- export declare const SWAPPABLE_DEP_SEATS: readonly ["models", "tiers", "readFace", "writeFace", "contextSettings", "readDenyPatterns", "readDenyBuiltinTiers", "readDenyBuiltinExclude"];
31
+ export declare const SWAPPABLE_DEP_SEATS: readonly ["models", "tiers", "readFace", "writeFace", "contextSettings", "readDenyPatterns", "readDenyBuiltinTiers", "readDenyBuiltinExclude", "readDenyFloorRequired"];
69
32
  export type SwappableDepSeat = (typeof SWAPPABLE_DEP_SEATS)[number];
70
33
  /** The candidate a swap takes: the swappable seats of {@link RunnerDeps}, each optional (presence = instruction). */
71
34
  export type SwappableDeps = Pick<RunnerDeps, SwappableDepSeat>;
@@ -85,6 +48,7 @@ export declare const SWAP_SEAT_NOTICE: {
85
48
  readonly readDenyPatterns: "config.read_deny_swapped";
86
49
  readonly readDenyBuiltinTiers: "config.read_deny_swapped";
87
50
  readonly readDenyBuiltinExclude: "config.read_deny_swapped";
51
+ readonly readDenyFloorRequired: "config.read_deny_swapped";
88
52
  };
89
53
  /** The fence over the notice table: `never` while every seat has a row. */
90
54
  export type SwapNoticeTableCoversEverySeat = AssertAllKeysHandled<Exclude<SwappableDepSeat, keyof typeof SWAP_SEAT_NOTICE>>;
@@ -114,6 +78,16 @@ export interface ScreenedSwappableDeps {
114
78
  * `assertContainmentFaceValue`), so a value the door admits is a value every later prepare admits.
115
79
  */
116
80
  export declare function screenSwappableDeps(next: unknown): ScreenedSwappableDeps;
81
+ /**
82
+ * The identity of a model-catalog generation as the swap announces it: a digest of the catalog's KEY MATERIAL — the model names the
83
+ * candidate declares and the tier bindings over them (each tier word, and the catalog word it binds; a binding that is a `Model` object
84
+ * has no word, so it stands as `null`) — never the catalog's content. Names and tier words are sorted, so the digest does not depend on
85
+ * the order a driver spelled them in; it depends on nothing but those two tables, so every Runner a driver swaps to the SAME model names
86
+ * under the SAME tier bindings announces the SAME generation (each notice still mints its own `occurrenceId`), and a swap that ends on
87
+ * another model name or another tier binding announces another. Two generations with equal key material read as one; the digest names what a consumer can tell apart
88
+ * from the line, which is the keys — the line is an operator breadcrumb, not a content fingerprint.
89
+ */
90
+ export declare function catalogGenerationOf(models: Readonly<Record<string, unknown>>, tiers: Readonly<Record<string, unknown>> | undefined): string;
117
91
  /**
118
92
  * Announce a swap of the deployment's read-deny declaration, after the write: ONE `config.read_deny_swapped`
119
93
  * line however many of its three seats the swap named (the line's contract lives at the notice catalog,
@@ -1,9 +1,11 @@
1
+ import { createHash } from "node:crypto";
1
2
  import { assertContainmentFaceValue } from "../tools/fs/containment-face.js";
2
3
  import { assertContextSettingsValue } from "./context-settings.js";
3
4
  import { READ_DENY_DEPLOYMENT_SEATS, screenReadDenySeat } from "./read-face-seats.js";
4
5
  import { deliverEngineNotice } from "./engine-notice.js";
5
6
  import { uuidv7 } from "../internal/harness.js";
6
- export const SWAPPABLE_DEP_SEATS = Object.freeze(["models", "tiers", "readFace", "writeFace", "contextSettings", "readDenyPatterns", "readDenyBuiltinTiers", "readDenyBuiltinExclude"]);
7
+ import { receiveOwnProperties } from "./own-property-receipt.js";
8
+ export const SWAPPABLE_DEP_SEATS = Object.freeze(["models", "tiers", "readFace", "writeFace", "contextSettings", "readDenyPatterns", "readDenyBuiltinTiers", "readDenyBuiltinExclude", "readDenyFloorRequired"]);
7
9
  const SWAPPABLE_DEP_SEAT_SET = new Set(SWAPPABLE_DEP_SEATS);
8
10
  export function isSwappableDepSeat(k) {
9
11
  return SWAPPABLE_DEP_SEAT_SET.has(k);
@@ -17,6 +19,7 @@ export const SWAP_SEAT_NOTICE = {
17
19
  readDenyPatterns: "config.read_deny_swapped",
18
20
  readDenyBuiltinTiers: "config.read_deny_swapped",
19
21
  readDenyBuiltinExclude: "config.read_deny_swapped",
22
+ readDenyFloorRequired: "config.read_deny_swapped",
20
23
  };
21
24
  export function screenSwappableDeps(next) {
22
25
  if (next === null || typeof next !== "object" || Array.isArray(next)) {
@@ -40,7 +43,7 @@ export function screenSwappableDeps(next) {
40
43
  if (v === null || typeof v !== "object" || Array.isArray(v)) {
41
44
  throw new Error(`swapDeps: models must be a plain Record<string, Model> (got ${v === null ? "null" : Array.isArray(v) ? "array" : typeof v}) — the current generation stays in force`);
42
45
  }
43
- candidate.models = { ...v };
46
+ candidate.models = receiveOwnProperties(v, { subject: "swapDeps.models", unit: "entry", moment: "at swapDeps" });
44
47
  break;
45
48
  case "tiers":
46
49
  if (!present.includes("models")) {
@@ -49,7 +52,7 @@ export function screenSwappableDeps(next) {
49
52
  if (v !== undefined && (v === null || typeof v !== "object" || Array.isArray(v))) {
50
53
  throw new Error(`swapDeps: tiers must be a plain Record<string, ModelRef> or undefined (got ${v === null ? "null" : Array.isArray(v) ? "array" : typeof v}) — the current generation stays in force`);
51
54
  }
52
- candidate.tiers = v === undefined ? undefined : { ...v };
55
+ candidate.tiers = v === undefined ? undefined : receiveOwnProperties(v, { subject: "swapDeps.tiers", unit: "binding", moment: "at swapDeps" });
53
56
  break;
54
57
  case "readFace":
55
58
  candidate.readFace = assertContainmentFaceValue(v, "read", "deps");
@@ -63,6 +66,7 @@ export function screenSwappableDeps(next) {
63
66
  case "readDenyPatterns":
64
67
  case "readDenyBuiltinTiers":
65
68
  case "readDenyBuiltinExclude":
69
+ case "readDenyFloorRequired":
66
70
  candidate[seat] = screenReadDenySeat(seat, v);
67
71
  break;
68
72
  default: {
@@ -73,6 +77,11 @@ export function screenSwappableDeps(next) {
73
77
  }
74
78
  return { seats: present, candidate: candidate };
75
79
  }
80
+ export function catalogGenerationOf(models, tiers) {
81
+ const names = Object.keys(models).sort();
82
+ const bindings = tiers === undefined ? [] : Object.keys(tiers).sort().map((tier) => [tier, typeof tiers[tier] === "string" ? tiers[tier] : null]);
83
+ return `cgv1:${createHash("sha256").update(JSON.stringify([names, bindings])).digest("hex")}`;
84
+ }
76
85
  export function announceReadDenySwap(onNotice, seats, inForce) {
77
86
  const named = READ_DENY_DEPLOYMENT_SEATS.filter((s) => seats.includes(s));
78
87
  if (named.length === 0)
@@ -80,9 +89,10 @@ export function announceReadDenySwap(onNotice, seats, inForce) {
80
89
  const patterns = inForce.readDenyPatterns?.length ?? null;
81
90
  const tiers = inForce.readDenyBuiltinTiers !== undefined ? [...inForce.readDenyBuiltinTiers] : null;
82
91
  const exclude = inForce.readDenyBuiltinExclude?.length ?? null;
92
+ const floorRequired = inForce.readDenyFloorRequired ?? null;
83
93
  deliverEngineNotice(onNotice, {
84
94
  code: "config.read_deny_swapped",
85
- message: `deployment read-deny declaration swapped (${named.join(", ")}): ${patterns ?? "no"} addition(s), built-in tiers ${tiers === null ? "(default)" : `[${tiers.join(", ")}]`}, ${exclude ?? "no"} built-in row removal(s); in-flight legs keep the deny face they prepared under, new legs compile against the new declaration`,
86
- detail: { seats: named, patterns, tiers, exclude, occurrenceId: uuidv7() },
95
+ message: `deployment read-deny declaration swapped (${named.join(", ")}): ${patterns ?? "no"} addition(s), built-in tiers ${tiers === null ? "(default)" : `[${tiers.join(", ")}]`}, ${exclude ?? "no"} built-in row removal(s), byte floor ${floorRequired === true ? "required" : "not required"}; in-flight legs keep the deny face they prepared under, new legs compile against the new declaration`,
96
+ detail: { seats: named, patterns, tiers, exclude, floorRequired, occurrenceId: uuidv7() },
87
97
  });
88
98
  }
@@ -57,7 +57,7 @@
57
57
  * waiting for that layer (the layer answered, or its share of the judgment's budget is spent) or when the run's signal ends.
58
58
  * An abort means only that: the task ended, or the judge no longer waits — never "there is no approver". Every engine
59
59
  * policy factory reads the statement before reaching a seat (the approval factory answers a deny attested `no_approver`,
60
- * read here as `approval_seat`; the inherited PreToolUse constraint does the same before invoking its hook), and the
60
+ * read here as `approval_seat`; an inherited screening installation is no policy layer here, as a leg's own PreToolUse is not), and the
61
61
  * engine's own guards composed into a deployment's policy judge the probe as they judge a call — a lookup bounded by a
62
62
  * live deadline answers. A deny that carries no engine settlement is a rule's deny and stands. RESIDUALS (stated, not
63
63
  * closed): a deployment closure that ignores the statement and reaches an approver IS asked — the judge waits for it at
@@ -113,6 +113,12 @@ export type BrainStatusPhase = "rate_limited" | "retrying" | "reconnecting" | "c
113
113
  * lowered output cap after the provider reported the context limit exceeded (no backoff).
114
114
  */
115
115
  export type BrainRetryErrClass = "connect_refused" | "transport" | "stall" | "rate_limit" | "server" | "http" | "output_cap";
116
+ /**
117
+ * WHOSE model call a liveness frame is about, when it is not the run's own turn — the closed set behind
118
+ * {@link BrainStatus.seat}. `classifier` = a call made for the auto-mode classifier lane (the classifier seat's model, or the
119
+ * main model standing in behind it): a side call beside the person's turn, never the turn itself.
120
+ */
121
+ export type BrainStatusSeat = "classifier";
116
122
  /** design/99 §E3/§E10 — the payload of a {@link TaskEvent} `status` event (and the brain→runner signal). */
117
123
  export interface BrainStatus {
118
124
  phase: BrainStatusPhase;
@@ -235,6 +241,15 @@ export interface BrainStatus {
235
241
  /** Which evidence {@link providerCondition} rests on (`unified_header` / `provider_code` / `status`). Present
236
242
  * exactly when it is. */
237
243
  providerConditionSource?: ProviderConditionSource;
244
+ /**
245
+ * WHOSE model call this frame is about ({@link BrainStatusSeat}), on every phase — a 429 backoff, a reconnect, a
246
+ * `circuit_open` fast-fail or a first-token wait all describe ONE call, and the person watching needs to know it is not their
247
+ * turn's. PRESENCE: `"classifier"` exactly on a frame about a call made for the auto-mode classifier lane
248
+ * (whichever rung's model it was asked on: the classifier seat's, or the main model standing in behind it). ABSENT =
249
+ * the run's own turn: the engine does not state a seat for the person's own model, so a consumer reads absence as "the
250
+ * main loop" — never as "unknown". Additive and optional: a consumer that never reads it renders every frame as before.
251
+ */
252
+ seat?: BrainStatusSeat;
238
253
  }
239
254
  /**
240
255
  * design/97 CORE-8 (③): one lightweight TOOL-ACTIVITY beat surfaced from a running task, for a per-agent live
@@ -1263,8 +1278,9 @@ export type TaskEvent = ({
1263
1278
  id: string;
1264
1279
  source: "marker" | "declared";
1265
1280
  };
1266
- /** True ⇔ the paths name locations inside a remote / non-host execution env, not host paths (the reading
1267
- * `ResolvedWorkspace.remote` carries). */
1281
+ /** True ⇔ the leg's execution env does not declare its paths the host's (`capabilities.hostLocalPaths`), so the
1282
+ * paths name locations inside that env, not host paths — whatever interface drives it: a host lane driven
1283
+ * through the remote seam reads `false` (the reading `ResolvedWorkspace.remote` carries). */
1268
1284
  remote: boolean;
1269
1285
  } & TaskEventIdentity) | ({
1270
1286
  /**
@@ -518,9 +518,14 @@ export declare function terminalFrameFacets(facts: {
518
518
  /**
519
519
  * A delegated child's report as its completion frame carries it — the one value the parent's notification and the fleet
520
520
  * terminal projected from that frame both read: redacted BEFORE the cut, with the pass the task row's copy uses (a token
521
- * across the cut is never half-shown), then cut with an honest total. Absent in ⇒ absent out.
521
+ * across the cut is never half-shown), then cut with an honest total. A report longer than the frame carries is the task's
522
+ * result artifact: `persist` stores the whole redacted report and the cut line names what it answered — awaited first, so
523
+ * the frame never names a ref whose write has not landed. `ref` = the stored ref, for the task row. Absent in ⇒ absent out.
522
524
  */
523
- export declare function notifyResultField(result: string | undefined): string | undefined;
525
+ export declare function completionResultField(result: string | undefined, persist: (report: string) => Promise<import("./tool-result-store.js").TaskArtifact>): Promise<{
526
+ readonly text: string;
527
+ readonly ref?: string;
528
+ } | undefined>;
524
529
  /** The codec version this engine writes into an `engine_frame` record and the highest it reads. */
525
530
  export declare const ENGINE_FRAME_CODEC_VERSION = 1;
526
531
  /** The engine's own lanes — the only frames the durable park may encode (an `external` event never is). */
@@ -580,6 +585,63 @@ export declare function isDelegatedAgentTerminal(n: Pick<TaskNotificationPayload
580
585
  * lane-blind, the trust cut is the marking site's.
581
586
  */
582
587
  export declare function isTerminalTaskNotification(n: Pick<TaskNotificationPayload, "status">): boolean;
588
+ /**
589
+ * THE completion-sink resolution every background producer reads — a background command, a Monitor watch, a background
590
+ * agent, a workflow run: the run lane the call carries (`ToolExecuteContext.onTaskNotification`) when there is one, else
591
+ * the mount's own sink. One value per launch: the producer judges "will a completion reach the model" by it, delivers
592
+ * through it, and owes its terminal frame to it ({@link oweTerminalDelivery}) — never one sink for the judgment and
593
+ * another for the delivery.
594
+ */
595
+ export declare function resolveCompletionSink<C, M>(callSink: C | undefined, mountSink: M | undefined): C | M | undefined;
596
+ /**
597
+ * The terminal frames a run's notification lane is still OWED — the one book a one-shot submission's ending waits on.
598
+ * A loop-type background task (a background agent, a continued agent, a workflow run) whose completion sink is a run's
599
+ * lane is entered when it is admitted ({@link oweTerminalDelivery}, on the sink it will deliver through); its terminal
600
+ * frame reaching that sink discharges it — whatever the lane then does with the frame (queues it for this run, or parks
601
+ * it for the session's next run): either way nothing more for that cycle will arrive on this lane. A debt is per CYCLE:
602
+ * an agent continued while its previous cycle's frame is still on its way owes two frames, and one frame — counted once,
603
+ * by its identity (`taskNotificationDedupKey`) — settles one. A debt is booked under the task's lane key
604
+ * ({@link taskNotificationLaneKey}, the pending store's own bucket key): admission, discharge and release all name the
605
+ * task by the frame it delivers, so a frame of another lane carrying the same `task_id` settles nothing here. A background
606
+ * command or a Monitor watch never enters: its lifetime is its process's (it may never end), and a one-shot ending treats
607
+ * it by the run's teardown rules without waiting. A sink no lane bound (a host's own) owes nothing.
608
+ */
609
+ export declare class DeliveryObligations {
610
+ /** lane key → admitted cycles whose terminal frame has not reached the sink. */
611
+ private readonly owed;
612
+ /** The terminal frames already counted (their dedup keys): a repeat of one settles nothing more. */
613
+ private readonly counted;
614
+ private readonly wakers;
615
+ /** When the waiting stops whatever is still owed (monotonic) — set by the first wait, never moved. */
616
+ private waitDeadline;
617
+ owe(task: Pick<TaskNotificationPayload, "task_id" | "task_type">): void;
618
+ discharge(frame: TaskNotificationPayload): void;
619
+ /** A cycle whose terminal frame was voided before it reached the sink (a continuation dropped its deferred frame) owes
620
+ * nothing more: one debt is released, the same way its frame would have released it. */
621
+ retire(task: Pick<TaskNotificationPayload, "task_id" | "task_type">): void;
622
+ private release;
623
+ /** Wake a wait to re-check its condition (a discharge, or input the run can now drain). */
624
+ wake(): void;
625
+ /** The lane keys still owed (an internal lane's is its task id), in admission order. */
626
+ get pending(): readonly string[];
627
+ /** Resolves at the next wake, when `signal` aborts, or after `withinMs` — at once when nothing is owed, it has already
628
+ * aborted, or no time is left. */
629
+ nextDischarge(signal: AbortSignal, withinMs: number): Promise<void>;
630
+ /**
631
+ * Wait out the debt the way a one-shot ending does: wake by wake, while something is owed, `keepWaiting()` holds (no
632
+ * input is queued for the run yet, the run is not ending) and `signal` has not aborted — and never past the reference's
633
+ * print-mode ceiling, counted from this book's first wait: `mFt` (cli309.js:260064), the default of
634
+ * `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` (cli309.js:263180), taken as a constant. `onInput` subscribes a wake to every
635
+ * input that reaches the run's queues meanwhile (a steer, a child's message, any engine note) — the wait re-checks.
636
+ */
637
+ waitOut(signal: AbortSignal, keepWaiting: () => boolean, onInput: (wake: () => void) => () => void): Promise<void>;
638
+ }
639
+ export declare function bindDeliveryObligations(sink: object, book: DeliveryObligations): void;
640
+ /** An admitted loop-type task owes `sink` its terminal frame — named by that frame's `task_id` and `task_type` (a no-op
641
+ * for a sink no run lane bound, or none). */
642
+ export declare function oweTerminalDelivery(sink: unknown, task: Pick<TaskNotificationPayload, "task_id" | "task_type">): void;
643
+ /** A cycle whose terminal frame will never reach `sink` (it was voided) releases its debt there (no-op for an unbound sink). */
644
+ export declare function retireTerminalDelivery(sink: unknown, task: Pick<TaskNotificationPayload, "task_id" | "task_type">): void;
583
645
  export interface DrainedPendingNotifications {
584
646
  /** Payloads still held when the session's next run drained. design/373 §3.5: batch order is
585
647
  * PRIORITY-MAJOR (now < next < later; a record with no carried priority ranks AS later —
@@ -819,7 +881,7 @@ export declare function sessionBoxRecordOf(payload: TaskNotificationPayload & {
819
881
  * carrier shapes, chosen per survivor:
820
882
  * · a CLASSIC survivor (renders through the `<task-notification>` shell) is annotated IN PLACE — the
821
883
  * first surviving payload of a task that lost events gets a `[task_id]`-prefixed disclosure line
822
- * prepended to its summary (backgroundTasks 同规: the id keeps the loss addressable via TaskOutput);
884
+ * prepended to its summary (backgroundTasks 同规: the id keeps the loss addressable);
823
885
  * · an AGENT-MESSAGE survivor (design/385 §1.4 d1; renders as the `<agent-message>` carrier, its
824
886
  * `summary` wire-only) is left byte-unchanged, and the disclosure rides as a SEPARATE engine-authored
825
887
  * `event` payload inserted immediately AHEAD of it (engine speech never goes inside a peer frame;
@@ -829,9 +891,30 @@ export declare function sessionBoxRecordOf(payload: TaskNotificationPayload & {
829
891
  * whole-session line below) — consume it by iteration, never by index-pairing against `items`. The
830
892
  * zero-disclosure path returns `drained.items` itself (identity, no allocation). A task whose EVERY
831
893
  * pending item was evicted still gets one honest synthetic `event` payload saying so — a fully silent
832
- * loss is never allowed.
894
+ * loss is never allowed. `readHandleOf` = the leg's reading of a task's read handle (`Prepared.taskReadHandleOf`): that
895
+ * synthetic line names where the task's output or result is read, or that its row is no longer readable from this run.
896
+ * `tasks` = the leg's background-task table, finished rows included (`Prepared.listBackgroundTasks({ settled: true })`):
897
+ * a whole-session loss names no task, so its line carries that table instead — every task the run can still reach, live
898
+ * or finished, and where each is read — or says the run has none. A caller with neither reading claims nothing.
899
+ */
900
+ export declare function discloseDroppedPending(drained: DrainedPendingNotifications, readHandleOf?: (taskId: string) => string | undefined, tasks?: () => ReadonlyArray<BackgroundTaskTableRow>): TaskNotificationPayload[];
901
+ /** One task as the background-task table lists it: its id (TaskStop addresses it), its description, its status, and its read
902
+ * handle (`TaskRegistry.readHandleOf`) — where its output or result is read; absent = nothing to read yet. */
903
+ export interface BackgroundTaskTableRow {
904
+ id: string;
905
+ description?: string;
906
+ status: string;
907
+ read?: string;
908
+ }
909
+ /**
910
+ * THE background-task table body — every model-facing list of a run's background tasks renders through it (the
911
+ * post-compaction announce, a whole-session loss line). The per-task status phrase is the reference's attachment-renderer
912
+ * wording (cli309.js:296735) "completed in background" — completed → "completed in background" · killed → "stopped" ·
913
+ * running → "still running in background" · anything else → the raw status (CC's own fallback arm); the line mirrors CC's
914
+ * `Task "${description}" ${phrase}` with the sema task_id prefixed and the row's read handle after it. A capped list says
915
+ * how many it left out, so a short count is never passed off as the whole.
833
916
  */
834
- export declare function discloseDroppedPending(drained: DrainedPendingNotifications): TaskNotificationPayload[];
917
+ export declare function renderBackgroundTaskTable(tasks: ReadonlyArray<BackgroundTaskTableRow>): string;
835
918
  export declare class SystemInjectionQueue<TPayload = TaskNotificationPayload> {
836
919
  private readonly queues;
837
920
  private readonly dedup;