@sema-agent/core 7.58.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 (519) hide show
  1. package/CHANGELOG.md +1340 -0
  2. package/README.md +6 -4
  3. package/dist/agents/agent-definition.d.ts +7 -0
  4. package/dist/agents/agent-definition.js +12 -0
  5. package/dist/agents/agent-transcript-tool.d.ts +2 -1
  6. package/dist/agents/agent-transcript-tool.js +3 -1
  7. package/dist/agents/cc-peer-directory.js +8 -8
  8. package/dist/agents/child-model-seat.d.ts +4 -2
  9. package/dist/agents/child-model-seat.js +9 -4
  10. package/dist/agents/cumulative-stats.js +0 -1
  11. package/dist/agents/inherited-tool-pool.d.ts +26 -1
  12. package/dist/agents/inherited-tool-pool.js +22 -0
  13. package/dist/agents/peer-directory.d.ts +9 -0
  14. package/dist/agents/peer-directory.js +6 -2
  15. package/dist/agents/retain-ledger.d.ts +11 -1
  16. package/dist/agents/retain-ledger.js +13 -2
  17. package/dist/agents/roster-store.d.ts +1 -1
  18. package/dist/agents/roster-store.js +3 -1
  19. package/dist/agents/send-message-tool.d.ts +8 -19
  20. package/dist/agents/send-message-tool.js +32 -50
  21. package/dist/agents/subagent.d.ts +51 -17
  22. package/dist/agents/subagent.js +150 -112
  23. package/dist/agents/tool-filter.d.ts +1 -3
  24. package/dist/agents/tool-filter.js +4 -12
  25. package/dist/bench/metrics.d.ts +3 -5
  26. package/dist/bench/metrics.js +0 -1
  27. package/dist/brain/anthropic.js +161 -45
  28. package/dist/brain/degrading.js +3 -1
  29. package/dist/brain/errors.d.ts +9 -3
  30. package/dist/brain/errors.js +7 -1
  31. package/dist/brain/failover.js +2 -1
  32. package/dist/brain/open-responses.js +3 -3
  33. package/dist/brain/openai.js +103 -53
  34. package/dist/brain/provider-dialect.d.ts +11 -0
  35. package/dist/brain/provider-dialect.js +5 -2
  36. package/dist/brain/reasoning-request.js +5 -4
  37. package/dist/brain/reasoning.d.ts +19 -0
  38. package/dist/brain/reasoning.js +17 -2
  39. package/dist/brain/request-route.d.ts +4 -1
  40. package/dist/brain/request-route.js +4 -1
  41. package/dist/brain/route-adjudicator.d.ts +84 -18
  42. package/dist/brain/route-adjudicator.js +90 -22
  43. package/dist/brain/route-conformance.js +1 -1
  44. package/dist/brain/status-sink.d.ts +7 -1
  45. package/dist/brain/status-sink.js +6 -0
  46. package/dist/brain/stream-engine.js +84 -49
  47. package/dist/brain/stream-shared.d.ts +30 -0
  48. package/dist/brain/stream-shared.js +34 -1
  49. package/dist/brain/timeout.d.ts +65 -6
  50. package/dist/brain/timeout.js +111 -11
  51. package/dist/core/a2a.d.ts +15 -5
  52. package/dist/core/a2a.js +34 -19
  53. package/dist/core/account-row.d.ts +61 -0
  54. package/dist/core/account-row.js +51 -0
  55. package/dist/core/advisor-verdict.d.ts +2 -1
  56. package/dist/core/advisor-verdict.js +1 -1
  57. package/dist/core/agent-definition.d.ts +20 -0
  58. package/dist/core/allow-entry.d.ts +20 -6
  59. package/dist/core/allow-entry.js +17 -7
  60. package/dist/core/approval-object.d.ts +29 -15
  61. package/dist/core/approval-object.js +47 -19
  62. package/dist/core/artifact-host.d.ts +0 -2
  63. package/dist/core/artifact-host.js +0 -1
  64. package/dist/core/auto-compaction.js +1 -1
  65. package/dist/core/auto-mode-defaults.d.ts +8 -0
  66. package/dist/core/auto-mode-defaults.js +1 -0
  67. package/dist/core/auto-mode-rebuild.d.ts +2 -1
  68. package/dist/core/auto-mode.d.ts +39 -4
  69. package/dist/core/auto-mode.js +63 -12
  70. package/dist/core/background-agent-store.d.ts +26 -4
  71. package/dist/core/background-agent-store.js +3 -2
  72. package/dist/core/background-shell.d.ts +12 -1
  73. package/dist/core/background-shell.js +12 -0
  74. package/dist/core/checkpoint-requirements.d.ts +13 -1
  75. package/dist/core/checkpoint-requirements.js +3 -1
  76. package/dist/core/checkpoint-store.d.ts +66 -25
  77. package/dist/core/checkpoint-store.js +22 -9
  78. package/dist/core/child-clamp-seats.d.ts +29 -0
  79. package/dist/core/child-clamp-seats.js +56 -1
  80. package/dist/core/compliance.d.ts +3 -3
  81. package/dist/core/compliance.js +1 -1
  82. package/dist/core/credential-echo.d.ts +52 -0
  83. package/dist/core/credential-echo.js +65 -0
  84. package/dist/core/credential-vocabulary.d.ts +13 -3
  85. package/dist/core/credential-vocabulary.js +12 -4
  86. package/dist/core/cross-boundary-taint.d.ts +4 -5
  87. package/dist/core/effective-path-target.d.ts +8 -2
  88. package/dist/core/effective-path-target.js +8 -3
  89. package/dist/core/engine-notice.d.ts +156 -23
  90. package/dist/core/engine-notice.js +19 -5
  91. package/dist/core/frame-settlement.d.ts +5 -0
  92. package/dist/core/frame-settlement.js +4 -0
  93. package/dist/core/gate-fold.js +8 -6
  94. package/dist/core/gate-lanes.js +47 -12
  95. package/dist/core/gate-outcome.d.ts +32 -3
  96. package/dist/core/gate-outcome.js +19 -1
  97. package/dist/core/governance-codes.d.ts +17 -1
  98. package/dist/core/governance-codes.js +25 -0
  99. package/dist/core/hands-band-screen.js +0 -1
  100. package/dist/core/hands-band.d.ts +0 -3
  101. package/dist/core/hooks.d.ts +70 -59
  102. package/dist/core/hooks.js +125 -80
  103. package/dist/core/image-admission.d.ts +106 -52
  104. package/dist/core/image-admission.js +184 -56
  105. package/dist/core/image-downsample.d.ts +36 -69
  106. package/dist/core/image-downsample.js +111 -73
  107. package/dist/core/integer-option.d.ts +21 -0
  108. package/dist/core/integer-option.js +13 -0
  109. package/dist/core/locked-config.d.ts +59 -5
  110. package/dist/core/locked-config.js +82 -50
  111. package/dist/core/mailbox-store.d.ts +45 -1
  112. package/dist/core/mailbox-store.js +53 -9
  113. package/dist/core/mcp-call-meta.d.ts +2 -2
  114. package/dist/core/mcp-call-meta.js +9 -10
  115. package/dist/core/mcp-failure.d.ts +122 -20
  116. package/dist/core/mcp-failure.js +73 -5
  117. package/dist/core/mcp-host-seat.d.ts +92 -0
  118. package/dist/core/mcp-host-seat.js +131 -0
  119. package/dist/core/mcp-probe.d.ts +7 -2
  120. package/dist/core/mcp-probe.js +7 -2
  121. package/dist/core/mcp-server-link.d.ts +22 -1
  122. package/dist/core/mcp-server-link.js +25 -1
  123. package/dist/core/mcp-server-spec.d.ts +38 -9
  124. package/dist/core/mcp-server-spec.js +55 -21
  125. package/dist/core/mcp.d.ts +27 -12
  126. package/dist/core/mcp.js +105 -76
  127. package/dist/core/memory-admission.d.ts +23 -6
  128. package/dist/core/memory-admission.js +19 -9
  129. package/dist/core/memory-engine/consolidation-driver.d.ts +2 -4
  130. package/dist/core/memory-engine/consolidation-driver.js +3 -3
  131. package/dist/core/memory-engine/consolidation.d.ts +4 -0
  132. package/dist/core/memory-engine/consolidation.js +1 -0
  133. package/dist/core/memory-engine/content-origin.d.ts +13 -0
  134. package/dist/core/memory-engine/content-origin.js +21 -3
  135. package/dist/core/memory-engine/delegation-settlement.js +5 -12
  136. package/dist/core/memory-engine/distiller.js +2 -2
  137. package/dist/core/memory-engine/dual-root.d.ts +50 -1
  138. package/dist/core/memory-engine/dual-root.js +44 -1
  139. package/dist/core/memory-engine/engine.d.ts +67 -14
  140. package/dist/core/memory-engine/engine.js +384 -212
  141. package/dist/core/memory-engine/export-bundle.d.ts +23 -0
  142. package/dist/core/memory-engine/export-bundle.js +23 -4
  143. package/dist/core/memory-engine/file-backend.d.ts +128 -55
  144. package/dist/core/memory-engine/file-backend.js +290 -117
  145. package/dist/core/memory-engine/index.d.ts +3 -2
  146. package/dist/core/memory-engine/index.js +2 -1
  147. package/dist/core/memory-engine/layout.d.ts +59 -11
  148. package/dist/core/memory-engine/layout.js +190 -40
  149. package/dist/core/memory-engine/memory-backend-contract.d.ts +1 -1
  150. package/dist/core/memory-engine/memory-backend-contract.js +39 -2
  151. package/dist/core/memory-engine/scope-contract.d.ts +13 -3
  152. package/dist/core/memory-engine/scope-contract.js +2 -2
  153. package/dist/core/memory-engine/sync-client.d.ts +51 -9
  154. package/dist/core/memory-engine/sync-client.js +107 -13
  155. package/dist/core/memory-engine/sync-report.d.ts +103 -0
  156. package/dist/core/memory-engine/sync-report.js +119 -0
  157. package/dist/core/memory-engine/sync.d.ts +8 -1
  158. package/dist/core/memory-engine/types.d.ts +6 -0
  159. package/dist/core/mode-policy.d.ts +9 -1
  160. package/dist/core/mode-policy.js +11 -1
  161. package/dist/core/model-receipt.d.ts +39 -0
  162. package/dist/core/model-receipt.js +139 -0
  163. package/dist/core/mods/agent-stations.d.ts +65 -0
  164. package/dist/core/mods/agent-stations.js +105 -0
  165. package/dist/core/mods/classic-events.d.ts +5 -1
  166. package/dist/core/mods/kernel/dispatch.d.ts +5 -1
  167. package/dist/core/mods/kernel/dispatch.js +6 -5
  168. package/dist/core/mods/kernel/events.d.ts +11 -4
  169. package/dist/core/mods/kernel/events.js +11 -7
  170. package/dist/core/mods/kernel/receive.d.ts +5 -0
  171. package/dist/core/mods/kernel/receive.js +10 -0
  172. package/dist/core/mods/kernel/registration.d.ts +4 -0
  173. package/dist/core/mods/kernel/registration.js +3 -0
  174. package/dist/core/mods/lifecycle-stations.d.ts +41 -0
  175. package/dist/core/mods/lifecycle-stations.js +35 -0
  176. package/dist/core/mods/stations.d.ts +73 -60
  177. package/dist/core/mods/stations.js +64 -40
  178. package/dist/core/mods/tool-call.d.ts +10 -4
  179. package/dist/core/mods/tool-call.js +28 -12
  180. package/dist/core/mounted-mcp.d.ts +5 -0
  181. package/dist/core/mounted-mcp.js +2 -2
  182. package/dist/core/namespaced-rule-name.d.ts +7 -1
  183. package/dist/core/namespaced-rule-name.js +13 -2
  184. package/dist/core/oracle-isolation.js +1 -1
  185. package/dist/core/own-property-receipt.d.ts +3 -0
  186. package/dist/core/own-property-receipt.js +3 -0
  187. package/dist/core/parent-spec-seat.d.ts +8 -3
  188. package/dist/core/parent-spec-seat.js +2 -0
  189. package/dist/core/park-selfcheck.js +14 -8
  190. package/dist/core/peer-seat.d.ts +133 -16
  191. package/dist/core/peer-seat.js +319 -42
  192. package/dist/core/permission-rule-consent.d.ts +0 -21
  193. package/dist/core/permission-rule-consent.js +11 -6
  194. package/dist/core/permission-rule-model.d.ts +20 -2
  195. package/dist/core/permission-rule-model.js +8 -7
  196. package/dist/core/present-plan-tool.d.ts +11 -3
  197. package/dist/core/present-plan-tool.js +2 -2
  198. package/dist/core/protocol-http-auth.d.ts +14 -2
  199. package/dist/core/protocol-http-auth.js +16 -7
  200. package/dist/core/read-face-seats.d.ts +7 -5
  201. package/dist/core/read-face-seats.js +4 -1
  202. package/dist/core/redaction-marks.d.ts +4 -3
  203. package/dist/core/redaction-marks.js +2 -2
  204. package/dist/core/remote-env.d.ts +146 -98
  205. package/dist/core/remote-env.js +113 -14
  206. package/dist/core/resume-startup-cause.js +1 -0
  207. package/dist/core/retention.js +37 -12
  208. package/dist/core/retired-keys.d.ts +6 -1
  209. package/dist/core/retired-keys.js +4 -1
  210. package/dist/core/rewrite-rejudge.d.ts +13 -5
  211. package/dist/core/rewrite-rejudge.js +9 -5
  212. package/dist/core/roles.d.ts +69 -3
  213. package/dist/core/roles.js +167 -80
  214. package/dist/core/rule-owner.d.ts +3 -0
  215. package/dist/core/runner/announce-once-ledger.d.ts +5 -4
  216. package/dist/core/runner/announce-once-ledger.js +4 -2
  217. package/dist/core/runner/assemble-result.d.ts +0 -5
  218. package/dist/core/runner/assemble-result.js +0 -1
  219. package/dist/core/runner/call-hook-stations.d.ts +17 -10
  220. package/dist/core/runner/call-hook-stations.js +23 -12
  221. package/dist/core/runner/child-tree.d.ts +7 -8
  222. package/dist/core/runner/child-tree.js +6 -6
  223. package/dist/core/runner/classifier-ladder.d.ts +10 -2
  224. package/dist/core/runner/classifier-ladder.js +39 -8
  225. package/dist/core/runner/construction-doors.js +5 -0
  226. package/dist/core/runner/contracts.d.ts +82 -57
  227. package/dist/core/runner/credential-origin-seat.js +4 -3
  228. package/dist/core/runner/cross-boundary-lane.d.ts +3 -5
  229. package/dist/core/runner/cross-boundary-lane.js +11 -2
  230. package/dist/core/runner/cwd-alignment-probe.d.ts +20 -0
  231. package/dist/core/runner/cwd-alignment-probe.js +21 -0
  232. package/dist/core/runner/decide-continuation.d.ts +2 -2
  233. package/dist/core/runner/env-capability-census.d.ts +15 -20
  234. package/dist/core/runner/env-capability-census.js +25 -34
  235. package/dist/core/runner/file-history-request.d.ts +2 -2
  236. package/dist/core/runner/file-history-request.js +0 -8
  237. package/dist/core/runner/gate-exit.d.ts +87 -11
  238. package/dist/core/runner/gate-exit.js +30 -8
  239. package/dist/core/runner/git-status-frame.d.ts +5 -2
  240. package/dist/core/runner/git-status-frame.js +3 -4
  241. package/dist/core/runner/image-removed-seat.d.ts +12 -0
  242. package/dist/core/runner/image-removed-seat.js +19 -0
  243. package/dist/core/runner/image.d.ts +7 -2
  244. package/dist/core/runner/image.js +14 -8
  245. package/dist/core/runner/inline-image.d.ts +10 -8
  246. package/dist/core/runner/inline-image.js +11 -9
  247. package/dist/core/runner/memory-consolidation-driver.js +5 -5
  248. package/dist/core/runner/park-commit.d.ts +1 -1
  249. package/dist/core/runner/park-commit.js +3 -0
  250. package/dist/core/runner/permission-rule-lanes.js +1 -1
  251. package/dist/core/runner/prepare-ask-lane.d.ts +1 -1
  252. package/dist/core/runner/prepare-ask-lane.js +2 -1
  253. package/dist/core/runner/prepare-boundary-parks.d.ts +2 -2
  254. package/dist/core/runner/prepare-boundary-parks.js +5 -5
  255. package/dist/core/runner/prepare-caps-and-workflow.d.ts +7 -5
  256. package/dist/core/runner/prepare-caps-and-workflow.js +6 -3
  257. package/dist/core/runner/prepare-config-doors.d.ts +6 -1
  258. package/dist/core/runner/prepare-config-doors.js +16 -9
  259. package/dist/core/runner/prepare-context-lane.js +2 -0
  260. package/dist/core/runner/prepare-delegation-surface.d.ts +9 -3
  261. package/dist/core/runner/prepare-delegation-surface.js +5 -4
  262. package/dist/core/runner/prepare-file-history.d.ts +10 -12
  263. package/dist/core/runner/prepare-file-history.js +3 -12
  264. package/dist/core/runner/prepare-gate-stations.d.ts +4 -3
  265. package/dist/core/runner/prepare-gate-stations.js +4 -3
  266. package/dist/core/runner/prepare-hands-readface.d.ts +7 -1
  267. package/dist/core/runner/prepare-hands-readface.js +19 -6
  268. package/dist/core/runner/prepare-inherited-gate.d.ts +6 -7
  269. package/dist/core/runner/prepare-inherited-gate.js +22 -31
  270. package/dist/core/runner/prepare-memory-engine-session.js +1 -1
  271. package/dist/core/runner/prepare-memory.d.ts +2 -2
  272. package/dist/core/runner/prepare-memory.js +12 -19
  273. package/dist/core/runner/prepare-park-ask.d.ts +4 -6
  274. package/dist/core/runner/prepare-park-ask.js +5 -9
  275. package/dist/core/runner/prepare-policy-chain.d.ts +8 -7
  276. package/dist/core/runner/prepare-policy-chain.js +136 -121
  277. package/dist/core/runner/prepare-project-context.d.ts +2 -2
  278. package/dist/core/runner/prepare-project-context.js +10 -7
  279. package/dist/core/runner/prepare-prompt-inputs.d.ts +5 -2
  280. package/dist/core/runner/prepare-prompt-inputs.js +10 -20
  281. package/dist/core/runner/prepare-protocol-tools.d.ts +5 -3
  282. package/dist/core/runner/prepare-protocol-tools.js +17 -2
  283. package/dist/core/runner/prepare-run-refs.d.ts +2 -3
  284. package/dist/core/runner/prepare-run-refs.js +4 -1
  285. package/dist/core/runner/prepare-suspend-saga.d.ts +0 -2
  286. package/dist/core/runner/prepare-suspend-saga.js +5 -7
  287. package/dist/core/runner/prepare-task.js +44 -28
  288. package/dist/core/runner/prepare-turn-wiring.d.ts +2 -0
  289. package/dist/core/runner/prepare-turn-wiring.js +7 -2
  290. package/dist/core/runner/prepare-wiring-manifest.d.ts +5 -4
  291. package/dist/core/runner/prepare-wiring-manifest.js +34 -19
  292. package/dist/core/runner/prepare-workspace-restore.js +3 -3
  293. package/dist/core/runner/reply-pricing.d.ts +30 -0
  294. package/dist/core/runner/reply-pricing.js +19 -0
  295. package/dist/core/runner/resume-admission.js +4 -2
  296. package/dist/core/runner/resume-apply.js +6 -1
  297. package/dist/core/runner/resume-checkpoint-screen.js +4 -4
  298. package/dist/core/runner/resume-policy-outcome.js +5 -5
  299. package/dist/core/runner/retired-runner-deps.js +4 -1
  300. package/dist/core/runner/role-seat-defaulted.d.ts +44 -0
  301. package/dist/core/runner/role-seat-defaulted.js +40 -0
  302. package/dist/core/runner/run-attachment-seats.js +3 -3
  303. package/dist/core/runner/run-brain-sinks.js +3 -0
  304. package/dist/core/runner/run-git-lane.d.ts +3 -1
  305. package/dist/core/runner/run-git-lane.js +1 -1
  306. package/dist/core/runner/run-harness-handlers.d.ts +3 -1
  307. package/dist/core/runner/run-harness-handlers.js +3 -1
  308. package/dist/core/runner/run-identity-wiring.d.ts +2 -5
  309. package/dist/core/runner/run-identity-wiring.js +6 -5
  310. package/dist/core/runner/run-leg.d.ts +2 -0
  311. package/dist/core/runner/run-leg.js +63 -56
  312. package/dist/core/runner/run-notification-lane.d.ts +3 -1
  313. package/dist/core/runner/run-notification-lane.js +16 -10
  314. package/dist/core/runner/run-settle-and-teardown.js +5 -1
  315. package/dist/core/runner/run-stop-and-final-verify.d.ts +4 -0
  316. package/dist/core/runner/run-stop-and-final-verify.js +14 -6
  317. package/dist/core/runner/run-terminal-adoption.d.ts +2 -5
  318. package/dist/core/runner/run-terminal-adoption.js +9 -3
  319. package/dist/core/runner/run-turn-boundary.js +89 -77
  320. package/dist/core/runner/runtask.d.ts +8 -5
  321. package/dist/core/runner/runtask.js +21 -13
  322. package/dist/core/runner/side-call-account.d.ts +1 -1
  323. package/dist/core/runner/side-call-account.js +3 -18
  324. package/dist/core/runner/skills-seat.js +2 -2
  325. package/dist/core/runner/sub-agent-deny-lists.d.ts +24 -0
  326. package/dist/core/runner/sub-agent-deny-lists.js +20 -7
  327. package/dist/core/runner/synthetic-tools.js +2 -2
  328. package/dist/core/runner/tool-disclosure.js +0 -2
  329. package/dist/core/runner/tool-end-body.js +2 -2
  330. package/dist/core/runner/tool-face-overlay.d.ts +1 -1
  331. package/dist/core/runner/tool-face-overlay.js +26 -19
  332. package/dist/core/runner/tool-occurrence.d.ts +1 -1
  333. package/dist/core/runner/tool-occurrence.js +2 -2
  334. package/dist/core/runner/tool-result-media-seat.d.ts +9 -1
  335. package/dist/core/runner/tool-result-media-seat.js +17 -1
  336. package/dist/core/runner/turn-attachments.d.ts +29 -27
  337. package/dist/core/runner/turn-attachments.js +27 -42
  338. package/dist/core/runner-deps.d.ts +32 -19
  339. package/dist/core/secret-env.d.ts +35 -4
  340. package/dist/core/secret-env.js +65 -3
  341. package/dist/core/sensitive-path-policy.js +3 -3
  342. package/dist/core/session-policy-store.d.ts +12 -3
  343. package/dist/core/session-policy-store.js +29 -10
  344. package/dist/core/session-store.d.ts +5 -7
  345. package/dist/core/session-store.js +50 -11
  346. package/dist/core/side-query.d.ts +11 -1
  347. package/dist/core/side-query.js +9 -0
  348. package/dist/core/skill-grant-binding.d.ts +31 -2
  349. package/dist/core/skill-grant-binding.js +31 -1
  350. package/dist/core/skill-grant.d.ts +17 -5
  351. package/dist/core/skill-grant.js +24 -6
  352. package/dist/core/store-contracts/background-agent-store-contract.js +27 -0
  353. package/dist/core/store-contracts/checkpoint-store-contract.js +3 -2
  354. package/dist/core/store-contracts/mailbox-store-contract.js +31 -1
  355. package/dist/core/store-contracts/tool-result-store-contract.d.ts +1 -1
  356. package/dist/core/store-contracts/tool-result-store-contract.js +37 -0
  357. package/dist/core/stub-env.d.ts +5 -5
  358. package/dist/core/stub-env.js +11 -1
  359. package/dist/core/swappable-deps.d.ts +17 -43
  360. package/dist/core/swappable-deps.js +15 -5
  361. package/dist/core/synthetic-read-verdict.d.ts +1 -1
  362. package/dist/core/synthetic-read-verdict.js +2 -1
  363. package/dist/core/task-event.d.ts +50 -10
  364. package/dist/core/task-notification.d.ts +88 -5
  365. package/dist/core/task-notification.js +146 -17
  366. package/dist/core/task-registry-agent.d.ts +18 -12
  367. package/dist/core/task-registry-agent.js +19 -6
  368. package/dist/core/task-registry-monitor.d.ts +7 -0
  369. package/dist/core/task-registry-monitor.js +28 -1
  370. package/dist/core/task-registry-shared.d.ts +43 -3
  371. package/dist/core/task-registry-shared.js +21 -7
  372. package/dist/core/task-registry-workflow.js +1 -1
  373. package/dist/core/task-registry.d.ts +50 -35
  374. package/dist/core/task-registry.js +64 -23
  375. package/dist/core/task-result.d.ts +3 -12
  376. package/dist/core/task-spec.d.ts +15 -7
  377. package/dist/core/task-stream.d.ts +1 -1
  378. package/dist/core/terminal-cause.d.ts +10 -0
  379. package/dist/core/tool-catalog-entries.js +1 -1
  380. package/dist/core/tool-check-reading.d.ts +1 -0
  381. package/dist/core/tool-check-reading.js +3 -3
  382. package/dist/core/tool-face-reader.d.ts +7 -6
  383. package/dist/core/tool-face-reader.js +4 -3
  384. package/dist/core/tool-name-aliases.d.ts +19 -0
  385. package/dist/core/tool-name-aliases.js +54 -2
  386. package/dist/core/tool-policy.d.ts +21 -4
  387. package/dist/core/tool-policy.js +1 -1
  388. package/dist/core/tool-registry.d.ts +5 -5
  389. package/dist/core/tool-registry.js +2 -2
  390. package/dist/core/tool-result-store.d.ts +88 -5
  391. package/dist/core/tool-result-store.js +51 -12
  392. package/dist/core/tool-roster.d.ts +112 -5
  393. package/dist/core/tool-roster.js +42 -1
  394. package/dist/core/tool-spec.d.ts +23 -5
  395. package/dist/core/trace.d.ts +0 -1
  396. package/dist/core/types.d.ts +5 -5
  397. package/dist/core/types.js +2 -2
  398. package/dist/core/untrusted-text.js +1 -1
  399. package/dist/core/user-attachment.d.ts +10 -5
  400. package/dist/core/user-attachment.js +15 -7
  401. package/dist/core/wiring-manifest.d.ts +6 -3
  402. package/dist/engine/compaction/compaction.js +29 -3
  403. package/dist/engine/execution-env/node-execution-env.d.ts +11 -5
  404. package/dist/engine/execution-env/node-execution-env.js +21 -13
  405. package/dist/engine/harness/agent-harness.d.ts +26 -3
  406. package/dist/engine/harness/agent-harness.js +49 -16
  407. package/dist/engine/harness/messages.d.ts +3 -1
  408. package/dist/engine/harness/messages.js +3 -2
  409. package/dist/engine/harness/types.d.ts +119 -28
  410. package/dist/engine/llm/rejected-images.d.ts +46 -0
  411. package/dist/engine/llm/rejected-images.js +54 -0
  412. package/dist/engine/llm/tool-turns.d.ts +2 -1
  413. package/dist/engine/llm/types.d.ts +18 -7
  414. package/dist/engine/loop/agent-loop.d.ts +20 -12
  415. package/dist/engine/loop/agent-loop.js +205 -36
  416. package/dist/engine/loop/types.d.ts +12 -3
  417. package/dist/engine/lsp/node-lsp-manager.d.ts +3 -3
  418. package/dist/engine/lsp/node-lsp-manager.js +32 -13
  419. package/dist/engine/session/path-to-root.d.ts +38 -0
  420. package/dist/engine/session/path-to-root.js +39 -0
  421. package/dist/engine/session/storage-base.js +4 -21
  422. package/dist/index.d.ts +35 -21
  423. package/dist/index.js +26 -17
  424. package/dist/internal/harness-types.d.ts +1 -1
  425. package/dist/internal/harness.d.ts +1 -0
  426. package/dist/internal/llm.d.ts +1 -0
  427. package/dist/orchestration/run-workflow-tool.d.ts +9 -3
  428. package/dist/orchestration/run-workflow-tool.js +59 -29
  429. package/dist/orchestration/workflow-governance.d.ts +1 -1
  430. package/dist/orchestration/workflow-governance.js +2 -1
  431. package/dist/orchestration/workflow-observe.d.ts +17 -1
  432. package/dist/orchestration/workflow-observe.js +20 -0
  433. package/dist/orchestration/workflow-types.d.ts +32 -7
  434. package/dist/orchestration/workflow.d.ts +4 -0
  435. package/dist/orchestration/workflow.js +762 -491
  436. package/dist/prompts/default.d.ts +1 -10
  437. package/dist/prompts/default.js +0 -2
  438. package/dist/shell/counting-pass.d.ts +50 -0
  439. package/dist/shell/counting-pass.js +502 -0
  440. package/dist/shell/lex.d.ts +4 -2
  441. package/dist/shell/lex.js +93 -34
  442. package/dist/shell/shell-words.d.ts +1 -1
  443. package/dist/shell/shell-words.js +7 -6
  444. package/dist/stores/file/background-agent-store.d.ts +1 -1
  445. package/dist/stores/file/background-agent-store.js +3 -1
  446. package/dist/stores/file/checkpoint-store.d.ts +127 -2
  447. package/dist/stores/file/checkpoint-store.js +19 -14
  448. package/dist/stores/file/file-history-store.d.ts +1 -1
  449. package/dist/stores/file/file-history-store.js +3 -1
  450. package/dist/stores/file/index.d.ts +4 -3
  451. package/dist/stores/file/index.js +17 -8
  452. package/dist/stores/file/mailbox-store.d.ts +1 -1
  453. package/dist/stores/file/mailbox-store.js +9 -11
  454. package/dist/stores/file/memory-store.d.ts +1 -1
  455. package/dist/stores/file/memory-store.js +3 -1
  456. package/dist/stores/file/session-policy-store.d.ts +1 -1
  457. package/dist/stores/file/session-policy-store.js +3 -1
  458. package/dist/stores/file/session-store.d.ts +1 -1
  459. package/dist/stores/file/session-store.js +3 -1
  460. package/dist/stores/file/shared-ledger.d.ts +26 -0
  461. package/dist/stores/file/shared-ledger.js +38 -9
  462. package/dist/stores/file/tool-result-store.d.ts +20 -2
  463. package/dist/stores/file/tool-result-store.js +74 -6
  464. package/dist/stores/file/usage-window-store.d.ts +1 -1
  465. package/dist/stores/file/usage-window-store.js +3 -1
  466. package/dist/stores/file/workflow-journal-store.d.ts +1 -11
  467. package/dist/stores/file/workflow-journal-store.js +3 -2
  468. package/dist/tools/fs/containment-face.d.ts +5 -0
  469. package/dist/tools/fs/encoding.d.ts +13 -4
  470. package/dist/tools/fs/encoding.js +17 -2
  471. package/dist/tools/fs/fs-bash-background-text.d.ts +7 -0
  472. package/dist/tools/fs/fs-bash-background-text.js +1 -0
  473. package/dist/tools/fs/fs-bash.d.ts +14 -4
  474. package/dist/tools/fs/fs-bash.js +29 -35
  475. package/dist/tools/fs/fs-pdf.d.ts +2 -2
  476. package/dist/tools/fs/fs-pdf.js +26 -21
  477. package/dist/tools/fs/fs-read.d.ts +5 -4
  478. package/dist/tools/fs/fs-read.js +35 -18
  479. package/dist/tools/fs/fs-search-tools.js +4 -1
  480. package/dist/tools/fs/fs-shared.d.ts +11 -13
  481. package/dist/tools/fs/fs-shared.js +11 -7
  482. package/dist/tools/fs/fs-write.js +5 -5
  483. package/dist/tools/fs/index.d.ts +14 -8
  484. package/dist/tools/fs/index.js +13 -5
  485. package/dist/tools/fs/program-read-model.d.ts +13 -0
  486. package/dist/tools/fs/program-read-model.js +15 -0
  487. package/dist/tools/fs/program-read-model.rows.js +1 -1
  488. package/dist/tools/fs/read-deny.d.ts +13 -10
  489. package/dist/tools/fs/read-deny.js +25 -5
  490. package/dist/tools/fs/read-floor.d.ts +62 -0
  491. package/dist/tools/fs/read-floor.js +58 -0
  492. package/dist/tools/fs/removal-targets.d.ts +9 -4
  493. package/dist/tools/fs/removal-targets.js +17 -9
  494. package/dist/tools/fs/search.d.ts +3 -3
  495. package/dist/tools/fs/search.js +4 -4
  496. package/dist/tools/fs/shell-read-check.d.ts +1 -1
  497. package/dist/tools/fs/shell-read-check.js +2 -1
  498. package/dist/tools/fs/shell-read-judge.d.ts +16 -8
  499. package/dist/tools/fs/shell-read-judge.js +10 -6
  500. package/dist/tools/fs/shell-read-plan.d.ts +6 -1
  501. package/dist/tools/fs/shell-read-plan.js +22 -15
  502. package/dist/tools/fs/shell-read-start.js +1 -0
  503. package/dist/tools/fs/shell-reentry-text.d.ts +15 -1
  504. package/dist/tools/fs/shell-reentry-text.js +25 -3
  505. package/dist/tools/monitor.d.ts +9 -4
  506. package/dist/tools/monitor.js +17 -8
  507. package/dist/tools/scheduler-tools.js +42 -4
  508. package/dist/tools/web.d.ts +0 -10
  509. package/dist/tools/web.js +1 -4
  510. package/package.json +5 -2
  511. package/test/export-surface.snapshot.json +161 -21
  512. package/wire-changes/core-stores-sql@7.59.0.json +29 -0
  513. package/wire-changes/core-stores-sql@7.60.0.json +30 -0
  514. package/wire-changes/core@7.59.0.json +2459 -0
  515. package/wire-changes/core@7.60.0.json +3274 -0
  516. package/wire-changes/mods-kernel@7.59.0.json +29 -0
  517. package/wire-changes/mods-kernel@7.60.0.json +62 -0
  518. package/wire-changes/primitives@7.59.0.json +29 -0
  519. package/wire-changes/primitives@7.60.0.json +30 -0
@@ -14,14 +14,14 @@ import type { OnElicit } from "./mcp-server-spec.js";
14
14
  import type { Brain, ModelRef, ModelRoles } from "./model-seat.js";
15
15
  import type { RuntimeCaps, WorkflowGovernanceBaseline } from "./runtime-caps.js";
16
16
  /**
17
- * parity-204 — structured `RunnerDeps.loadProjectMemory` return (backward-compatible, RL-1336-project-memory-bare: a bare
18
- * `string | null` keeps its exact historical meaning). Adds the `seededFromContext`
17
+ * parity-204 — the `RunnerDeps.loadProjectMemory` return: the one form a loader answers in (a loader with nothing to
18
+ * inject answers `{ content: null }`; a bare `string | null` is not read). Carries the `seededFromContext`
19
19
  * seam (cc204-bundle @17917159: CC preloads readFileState for CLAUDE.md/nested-memory files it
20
20
  * placed in context, and a DEFAULT whole-file Read of an unchanged seeded file answers with the
21
21
  * already-in-context reminder instead of re-transmitting the body — token economy, GA in 204).
22
22
  */
23
23
  export interface ProjectMemoryLoad {
24
- /** The project-context text to inject — same semantics as returning a bare string (null/blank ⇒ no injection). */
24
+ /** The project-context text to inject (null/blank ⇒ no injection). */
25
25
  content: string | null;
26
26
  /**
27
27
  * Files whose FULL, disk-verbatim text the deployment has placed in the model's context (e.g. the
@@ -223,6 +223,17 @@ export interface RunnerDeps {
223
223
  * ignored). Same deployment-only seat, clamp argument and checkpoint posture as the tiers key.
224
224
  */
225
225
  readDenyBuiltinExclude?: readonly string[];
226
+ /**
227
+ * #2936 — whether the deployment REQUIRES the byte floor kept: `true` ⇒ a run whose read-deny table holds a row, on an
228
+ * execution environment that does not declare it keeps the floor (`capabilities.keepsReadFloor`), is refused at prepare
229
+ * (`config.read_deny_floor_unkept`) before any command starts. Absent or `false` = not required — the documented
230
+ * reading, not a silent default: such a run is then announced once to the operator under the same code, because a
231
+ * recursive read under a root reads the files below it there, deny rows included. A present non-boolean value refuses
232
+ * (`config.read_face_seat`). The read-deny family's deployment seat (hot-swappable with it, `config.read_deny_swapped`);
233
+ * DEPLOYMENT seat ONLY, like the tier switch: a task can add deny rows, never change the deployment's gate. Mirrored on
234
+ * `HandsToolkitOptions.readDenyFloorRequired` for a library-direct band that compiles its own table.
235
+ */
236
+ readDenyFloorRequired?: boolean;
226
237
  /**
227
238
  * Where the host keeps the agent's configuration directory when it is not `<home>/.sema` — an ABSOLUTE path of an
228
239
  * existing directory, resolved by the host (the engine reads no environment variable for it). The rows of the
@@ -347,8 +358,8 @@ export interface RunnerDeps {
347
358
  * (single-process/single-host deployments: byte-identical behavior). A deployment whose control
348
359
  * plane does not survive into resume replicas (the stateless multi-replica server form) supplies
349
360
  * a durable store here; see {@link import("./memory-engine/layout.js").SessionCaptureRecordStore}
350
- * for the per-leg fail-closed contract. Also the §2.1b capability signal: on a REMOTE-execution
351
- * deployment with no store supplied here, a `capture:"off"` declaration is refused
361
+ * for the per-leg fail-closed contract. Also the §2.1b capability signal: where the execution env's paths are not
362
+ * the host's (`pathsAreHostLocal`) and no store is supplied here, a `capture:"off"` declaration is refused
352
363
  * (`config.memory_capture_unsupported`) rather than accepted onto a carrier that the next resume
353
364
  * cannot see — a false privacy promise is worse than a loud one.
354
365
  */
@@ -660,7 +671,7 @@ export interface RunnerDeps {
660
671
  runtimeCapsResolver?: (principal: string | undefined) => RuntimeCaps | undefined | Promise<RuntimeCaps | undefined>;
661
672
  /**
662
673
  * Administrator lock layer (ruled 2026-08-05) — the deployment's config-time declaration of which
663
- * lockable keys are locked (closed registry: `mcp` / `toolPolicy` / `compliancePosture` /
674
+ * lockable keys are locked (closed registry: `mcp` / `a2a` / `toolPolicy` / `compliancePosture` /
664
675
  * `retentionPolicy`; see {@link import("./locked-config.js").LOCKED_KEY_REGISTRY}). A task spec
665
676
  * carrying a value for a locked key is refused wholesale at the prepare door
666
677
  * (`config.locked_key`); an unknown key in this declaration is itself refused
@@ -783,6 +794,8 @@ export interface RunnerDeps {
783
794
  * (`config.auto_mode_classifier_fallback_invalid`) — never clamped, never read as the default.
784
795
  */
785
796
  classifierFallback?: import("./auto-mode.js").AutoModeClassifierFallback;
797
+ /** Consecutive classifications ending on the classifier SEAT's rate limit (an HTTP 429 after the brain's own backoff) before the seat is not asked again this run — the walk starts on the model behind it, `classifier.seat_rate_limited` says so once; default 3 (`AUTO_MODE_RATE_LIMIT_BREAK_AFTER_DEFAULT`); any other outcome zeroes the count; inert under `classifierFallback: "none"`; a value that is not a whole number of at least 1 is REFUSED at every leg's prepare (`config.auto_mode_rate_limit_break_invalid`), never clamped; no OFF. See the header of `auto-mode.ts`. */
798
+ rateLimitBreakAfter?: number;
786
799
  /**
787
800
  * The classifier DENIAL LIMIT: a run whose classifier keeps blocking falls
788
801
  * back to a PERSON instead of being denied without end. Per run: a `block` first increments the
@@ -1136,16 +1149,18 @@ export interface RunnerDeps {
1136
1149
  * unserializable (durable resume) and reading files for an UNTRUSTED caller would be a confused-deputy hole
1137
1150
  * (design/44 §7 Q4). DECOUPLED from `memoryStore` — injects even with NO long-term memory configured (H5).
1138
1151
  *
1139
- * `undefined` (default) ⇒ the whole path is skipped = byte-identical to today (full parity, H3). Returning
1140
- * `null`/blank ⇒ no injection (also byte-identical). The content is fenced/sanitized like every other memory
1152
+ * `undefined` (default) ⇒ the whole path is skipped = byte-identical to today (full parity, H3). The loader answers a
1153
+ * {@link ProjectMemoryLoad}; `{ content: null }` (or blank content) ⇒ no injection (also byte-identical). Any other
1154
+ * answer (a bare string, `null`, a non-object) is not read: it is disclosed on `onError` (phase `config`) and the leg runs
1155
+ * with no project layer, as when the loader throws. The content is fenced/sanitized like every other memory
1141
1156
  * layer (repo-controlled CLAUDE.md is UNTRUSTED data, not an instruction — H2). The ctx lets a profile tailor
1142
- * or suppress: `handsEnabled:false` = a hands-less chat with no real project (return null); `isSubagent` =
1157
+ * or suppress: `handsEnabled:false` = a hands-less chat with no real project (answer `{ content: null }`); `isSubagent` =
1143
1158
  * a delegated child (a profile may trim CLAUDE.md for a cheap "grep this" subagent — H7).
1144
1159
  */
1145
1160
  loadProjectMemory?: (ctx: {
1146
1161
  /** The task's working directory (= the execution env's cwd; a worktree task = its worktree root). */
1147
1162
  cwd: string;
1148
- /** False ⇒ a hands-less chat (no real filesystem/project) — a profile typically returns null. */
1163
+ /** False ⇒ a hands-less chat (no real filesystem/project) — a profile typically answers `{ content: null }`. */
1149
1164
  handsEnabled: boolean;
1150
1165
  /** True ⇒ a delegated subagent run (a profile may trim/suppress project content to control cost). */
1151
1166
  isSubagent: boolean;
@@ -1174,12 +1189,10 @@ export interface RunnerDeps {
1174
1189
  * docs/REVIEW-BACKLOG.md): a compaction followed by a mid-run user-role
1175
1190
  * injection (steer) before the next prepare reads as `"resume"` — the freshness
1176
1191
  * gap is covered by the C-4 `instructions_change` lane, not by this signal.
1177
- * - `"post-clear"` — RESERVED: core has no session-clear primitive today (a CC `/clear` maps to a
1178
- * NEW session ⇒ `"fresh"`; rewinding past the root is rejected), so core never
1179
- * emits this value — it exists so the seam's enum is stable when a clear verb lands.
1192
+ * A session clear starts a NEW session, which reads `"fresh"` (rewinding past the root is rejected).
1180
1193
  */
1181
- phase?: "fresh" | "resume" | "post-compact" | "post-clear";
1182
- }) => Promise<string | null | ProjectMemoryLoad> | string | null | ProjectMemoryLoad;
1194
+ phase?: "fresh" | "resume" | "post-compact";
1195
+ }) => Promise<ProjectMemoryLoad> | ProjectMemoryLoad;
1183
1196
  /**
1184
1197
  * design-A C-4 ([A2]) — the mid-session instruction-file change PROBE (the server half of the
1185
1198
  * `instructions_change` attachment lane). At eligible turn boundaries (continuation-gated like
@@ -1212,11 +1225,11 @@ export interface RunnerDeps {
1212
1225
  */
1213
1226
  onElicit?: OnElicit;
1214
1227
  /**
1215
- * design/116 CONFIRM-1 (加 seam 保体验): resize an over-limit MCP image so the model still SEES a
1216
- * degraded image instead of a spill-to-disk note. Absent ⇒ core auto-detects `sharp` (dynamic import;
1217
- * turnkey deployments with sharp installed get the CC experience with zero config) and otherwise spills.
1228
+ * The ONE image processor seat: every image a run hands the model (Read, PDF pages, Bash data URIs, MCP and any tool's results,
1229
+ * `TaskSpec.images`, attachments) passes the one admission with it (frame ladder, then toward `IMAGE_ADMISSION.soft.targetBytes`).
1230
+ * `false` = none (images go on as they are within the hard limits; the run says so once past the soft target); absent ⇒ detect sharp.
1218
1231
  */
1219
- mcpImageResizer?: import("./mcp.js").McpImageResizer;
1232
+ imageProcessor?: import("./image-downsample.js").ImageDownsampler | false;
1220
1233
  /** Default tool-call gate for all tasks (a task's own `toolPolicy` overrides this). */
1221
1234
  toolPolicy?: import("./tool-policy.js").ToolPolicy;
1222
1235
  /**
@@ -61,6 +61,16 @@ export interface WithheldEnvDeclaration {
61
61
  * a flag or placeholder word, one character repeated, or fewer than eight characters. */
62
62
  readonly values: readonly string[];
63
63
  }
64
+ /**
65
+ * THE one reading of an empty credential: a string with nothing but white space in it, the empty string included, is no
66
+ * credential, whoever hands it and wherever it is handed. Every face that asks "was a credential handed at all" reads
67
+ * this one: the withheld table's entry rule ({@link notACredentialReason}, its first answer), the engine's credential
68
+ * intake ({@link holdOwnCredentialValues}: a blank value is not taken in and not said), the route law
69
+ * (`route-adjudicator.ts`: a blank `apiKey` or a blank credential header is the keyless door — its source keeps its
70
+ * rank, so no other source's credential rides in its place, and nothing of it goes out or is bound) and the memory
71
+ * distiller's chat seat (a blank key is no key). White space is what `String.prototype.trim` removes.
72
+ */
73
+ export declare function isBlankCredential(value: string): boolean;
64
74
  /** {@link notACredentialReason}'s answer as a yes: the same guess for the second place that pays for withholding a string — every
65
75
  * occurrence of a request's key taken out of a remote's words (`remoteWords`): a key that names no secret (`EMPTY`, a local gateway's
66
76
  * one-letter key) is left in the words, as it is left to every child. */
@@ -97,14 +107,17 @@ export declare function namesASecret(value: string): boolean;
97
107
  export declare function declareWithheldEnv(table: WithheldEnvDeclaration): void;
98
108
  /**
99
109
  * The engine takes credential values in — each where the engine receives it: a first-party brain's construction
100
- * credential (`brainConfigSnapshot`), a model entry's own credential headers (`resolveRouteCredential`), a protocol
101
- * peer's credential headers (`resolveProtocolHttpHeaders`), the memory distiller's chat seat key (`openAiCompatChatSeat`,
110
+ * credential (`brainConfigSnapshot`), a model entry's own credential headers (`resolveRouteCredential`), the credential
111
+ * headers and variables a protocol peer's seat answers (`PeerCarrier`, before the answer is judged — a refused answer's
112
+ * values are taken in too), the memory distiller's chat seat key (`openAiCompatChatSeat`,
102
113
  * and `RunnerDeps.memoryConsolidationDriver.chat` at `new Runner`, before that seat is built). From then on, for the
103
114
  * life of the process, no child spawned on this host inherits an entry whose value equals one: the same table, the same
104
115
  * subtraction, finding and disclosure as a declared value ({@link declareWithheldEnv}). A credential the engine is handed
105
116
  * per request (a per-model auth hook's answer) is not taken in: the host that resolves it owns it and declares it.
106
- * An absent or empty value adds nothing. A value that is no credential ({@link notACredentialReason}: white space, a
107
- * flag or placeholder word, one character repeated, fewer than {@link CREDENTIAL_MIN_CHARS} characters — the key a local
117
+ * An absent or blank value ({@link isBlankCredential}) adds nothing and is not said: it is no credential, and no request
118
+ * carries it (the route law reads a blank key as the keyless door). A value that is no credential otherwise
119
+ * ({@link notACredentialReason}: a flag or placeholder word, one character repeated, fewer than
120
+ * {@link CREDENTIAL_MIN_CHARS} characters — the key a local
108
121
  * gateway is told to be handed) is not taken in: its holder uses it as given (it is no bad value), and the variables
109
122
  * that hold the same string stay with every child. Said once per process per value, never the value, as the notice
110
123
  * `config.credential_not_withheld` through the engine's one notice throat ({@link deliverEngineNotice}): to `onNotice`
@@ -161,6 +174,24 @@ export declare function __resetWithheldEnv(): void;
161
174
  * ask first, so a host that declared before building them hears it at start-up.
162
175
  */
163
176
  export declare function inheritedHostEnv(policy: InheritEnvPolicy | undefined, findings?: SecretEnvFinding[]): NodeJS.ProcessEnv;
177
+ /** What a child spawned on this host starts with ({@link hostChildEnv}), and the inherited entries it does not receive:
178
+ * the inheritance's findings less every name the composed environment sets (a grant's entry is the host's, never a loss). */
179
+ export interface HostChildEnv {
180
+ readonly env: NodeJS.ProcessEnv;
181
+ readonly withheld: readonly SecretEnvFinding[];
182
+ }
183
+ /** Why {@link hostChildEnv} would refuse these inputs, or `undefined` — the same judgment; it never throws. */
184
+ export declare function hostChildEnvProblem(policy: unknown, ...grants: readonly unknown[]): string | undefined;
185
+ /**
186
+ * THE environment a child spawned ON THIS HOST starts with: {@link inheritedHostEnv}'s reading of `policy`, then each
187
+ * grant in order (a later grant's value wins, names compared as the platform compares them; an `undefined` value
188
+ * unsets). The tool shell's children and a command hook's children are composed here alike: a hook starts from the
189
+ * run's shell policy and settings-env grant, with the hook's own variables as the last grant. An own credential is never
190
+ * inherited; a grant is the host's explicit act and is not read against the declaration. A grant that is not an object
191
+ * or throws while read, a name that is empty or holds `=`, NUL or an unpaired surrogate, and a value that is not a
192
+ * string or holds NUL or an unpaired surrogate throw, as a refused policy does ({@link hostChildEnvProblem}).
193
+ */
194
+ export declare function hostChildEnv(policy: InheritEnvPolicy | undefined, ...grants: readonly (Readonly<NodeJS.ProcessEnv> | undefined)[]): HostChildEnv;
164
195
  /** Why `value` is not an {@link InheritEnvPolicy} this deployment can read (absent counts as one — the scrub), or
165
196
  * `undefined` when it is: a malformed policy, or an allow list naming one of the declared own credentials
166
197
  * ({@link declareWithheldEnv}, compared as it says). */
@@ -197,10 +197,13 @@ function runtimeSuppliedHolderOf(value) {
197
197
  }
198
198
  const PLACEHOLDER_KEY_WORDS = new Set([...FLAG_WORDS, "undefined", "placeholder", "lm-studio", "not-needed", "sk-no-key-required"]);
199
199
  const ONE_REPEATED_CHARACTER_RE = /^(\S)\1{2,}$/u;
200
+ export function isBlankCredential(value) {
201
+ return value.trim() === "";
202
+ }
200
203
  function notACredentialReason(value) {
201
- const text = value.trim();
202
- if (text === "")
204
+ if (isBlankCredential(value))
203
205
  return "white space only, which every blank variable equals";
206
+ const text = value.trim();
204
207
  if (text.length < CREDENTIAL_MIN_CHARS)
205
208
  return `a string of fewer than ${CREDENTIAL_MIN_CHARS} characters, which names no secret`;
206
209
  if (PLACEHOLDER_KEY_WORDS.has(text.toLowerCase()))
@@ -267,7 +270,7 @@ export function declareWithheldEnv(table) {
267
270
  Reflect.set(globalThis, WITHHELD_ENV, { names: names, declared, held: withheldEnvOf().held });
268
271
  }
269
272
  export function holdOwnCredentialValues(values, onNotice) {
270
- const given = [...values].filter((v) => typeof v === "string" && v.length > 0);
273
+ const given = [...values].filter((v) => typeof v === "string" && !isBlankCredential(v));
271
274
  const taken = given.filter((v) => {
272
275
  const why = notACredentialReason(v);
273
276
  if (why !== undefined)
@@ -364,6 +367,65 @@ export function inheritedHostEnv(policy, findings) {
364
367
  throw new Error(problem);
365
368
  return withholdOwnCredentials(policyArm(policy, findings), findings);
366
369
  }
370
+ const unkeptCharacter = (text) => (text.includes("\0") ? "a NUL" : UNPAIRED_SURROGATE_RE.test(text) ? "an unpaired surrogate" : undefined);
371
+ function readGrant(grant, n) {
372
+ try {
373
+ if (typeof grant !== "object" || grant === null || Array.isArray(grant))
374
+ return `env grant ${n} must be an object of variable names to strings (got ${kindOf(grant)})`;
375
+ const entries = Object.entries(grant);
376
+ for (const [name, value] of entries) {
377
+ const unkept = name.includes("=") ? "\"=\"" : unkeptCharacter(name);
378
+ const badName = name === "" ? "an empty string" : unkept && `one holding ${unkept}`;
379
+ if (badName)
380
+ return `env grant ${n} holds a key that is not a variable name (${badName})`;
381
+ if (value !== undefined && typeof value !== "string")
382
+ return `env grant ${n}: ${name} must be a string (got ${kindOf(value)})`;
383
+ const badValue = value === undefined ? undefined : unkeptCharacter(value);
384
+ if (badValue !== undefined)
385
+ return `env grant ${n}: the value of ${name} holds ${badValue}`;
386
+ }
387
+ return entries;
388
+ }
389
+ catch {
390
+ return `env grant ${n} threw while it was read — refused`;
391
+ }
392
+ }
393
+ function composeHostChildEnv(policy, grants) {
394
+ let problem;
395
+ try {
396
+ problem = inheritEnvPolicyProblem(policy);
397
+ }
398
+ catch {
399
+ problem = "inheritEnv threw while it was read — refused";
400
+ }
401
+ if (problem !== undefined)
402
+ return problem;
403
+ const findings = [];
404
+ const entries = new Map();
405
+ for (const entry of Object.entries(inheritedHostEnv(policy, findings)))
406
+ entries.set(envNameKey(entry[0]), entry);
407
+ for (let i = 0; i < grants.length; i++) {
408
+ if (grants[i] === undefined)
409
+ continue;
410
+ const read = readGrant(grants[i], i + 1);
411
+ if (typeof read === "string")
412
+ return read;
413
+ for (const [name, value] of read)
414
+ entries.set(envNameKey(name), [entries.get(envNameKey(name))?.[0] ?? name, value]);
415
+ }
416
+ const env = Object.fromEntries(entries.values());
417
+ return { env, withheld: findings.filter((f) => entries.get(envNameKey(f.key))?.[1] === undefined) };
418
+ }
419
+ export function hostChildEnvProblem(policy, ...grants) {
420
+ const composed = composeHostChildEnv(policy, grants);
421
+ return typeof composed === "string" ? composed : undefined;
422
+ }
423
+ export function hostChildEnv(policy, ...grants) {
424
+ const composed = composeHostChildEnv(policy, grants);
425
+ if (typeof composed === "string")
426
+ throw new Error(composed);
427
+ return composed;
428
+ }
367
429
  function policyArm(policy, findings) {
368
430
  if (policy === "all")
369
431
  return { ...process.env };
@@ -2,7 +2,7 @@ import { homedir } from "node:os";
2
2
  import { isAbsolute, join, resolve } from "node:path";
3
3
  import { anchorSpelling, canonicalizeTarget, expandHomeTilde, isAbsoluteForFamily, isWinFormPath, pathFamilyOf, writeTargetPath } from "../tools/fs/safety.js";
4
4
  import { spelledExemptionOf } from "./write-protect.js";
5
- import { compileSegmentPattern, READ_FACE_BUILTIN_DENY_TABLE, readDenyPatternRun, segmentGuardRow } from "../tools/fs/read-deny.js";
5
+ import { compileSegmentPattern, READ_FACE_BUILTIN_DENY_TABLE, readDenyPatternRun, SEGMENT_FOLDS, segmentGuardRow } from "../tools/fs/read-deny.js";
6
6
  import { guardHitReachClause, guardHitVia, judgePathRows } from "./path-guard-rows.js";
7
7
  import { agentConfigDirSegments, agentConfigDirTail, checkedAgentConfigDir } from "./agent-config-dir.js";
8
8
  import { isProtectedWrite, protectivePathTargetOf } from "./tool-registry.js";
@@ -132,8 +132,8 @@ export function createSensitivePathPolicy(opts) {
132
132
  if (configRoot === undefined || configRows.length === 0)
133
133
  return [];
134
134
  const fold = CASE_INSENSITIVE_FS ? "ascii" : "none";
135
- const lower = (segs) => (CASE_INSENSITIVE_FS ? segs.map((seg) => seg.replace(/[A-Z]/g, (c) => c.toLowerCase())) : segs);
136
- const anchors = [configRoot, ...(env === undefined ? [] : await canonicalDataRootKeys(env, [configRoot], signal))].map((root) => lower(agentConfigDirSegments(root)));
135
+ const folded = (segs) => segs.map((seg) => SEGMENT_FOLDS[fold](seg));
136
+ const anchors = [configRoot, ...(env === undefined ? [] : await canonicalDataRootKeys(env, [configRoot], signal))].map((root) => folded(agentConfigDirSegments(root)));
137
137
  return configRows.map(({ raw, tail }) => ({ ...(compileSegmentPattern(tail, fold) ?? { raw, segments: [], fold }), raw, anchors, rootedOnly: true }));
138
138
  };
139
139
  const rowsOf = async (env, signal) => [...guardRows, ...(await configTwins(env, signal)).map(rowOf)];
@@ -81,7 +81,14 @@ export type SessionRuleEntryField = {
81
81
  * persisted grammar read every bare name as no rule. A session's entries mean what they meant (the entry reader already read a bare
82
82
  * name as the whole tool), so no earlier entry reads differently; the stamp moves for the persisted store's buckets and the sync
83
83
  * wire's states, so an engine of grammar 5 given a bucket written in grammar 6 refuses it whole rather than drop a whole-tool deny
84
- * as damage. No persisted row of an earlier stamp can hold a bare name (every entrance refused one), so none is read anew.
84
+ * as damage. No persisted row of an earlier stamp can hold a bare name (every entrance refused one), so none is read anew;
85
+ * - 7, an exact MCP tool name with `__` in its body (`mcp__a__b`, no `*`) in `toolDeny` reads every MCP server spelling it can
86
+ * stand for (`peerReadingsOf`: tool `b` of server `a` AND every tool of server `a__b`), where grammar 6 read the one exact tool.
87
+ * A session row an earlier grammar wrote reads such an entry as the one exact tool, announced (the revision table); an engine of
88
+ * grammar 6 given a row written in grammar 7 refuses it rather than read the deny as the narrower exact tool. The persisted store
89
+ * and the rule-sync wire stamp 7 as well, so a grammar-6 engine refuses their buckets and states too — but this revision does not
90
+ * pay the persisted store the reading of its earlier stamps owed below: a stored whole-tool deny / ask of such a name in a
91
+ * bucket of stamp 6 reads in this grammar, the wider way (#3085).
85
92
  * A row an earlier grammar wrote keeps the meaning that grammar gave its entries, and an entry that grammar could not read takes
86
93
  * this one's ({@link earlierGrammarReads}, over the revisions above as one table); an entry this grammar reads as no rule reads as
87
94
  * `earlier_grammar` ({@link compileSessionRuleBucket}).
@@ -94,7 +101,7 @@ export type SessionRuleEntryField = {
94
101
  * what an existing persisted rule text means owes that store a reading of its earlier stamps, as {@link earlierGrammarReads}
95
102
  * is for entries. Every stamp is judged by {@link readRuleGrammarStamp}.
96
103
  */
97
- export declare const SESSION_RULES_GRAMMAR = 6;
104
+ export declare const SESSION_RULES_GRAMMAR = 7;
98
105
  /** {@link SessionPermissionRules} plus the monotonic `rev` the store stamps (the OCC key). */
99
106
  export interface StoredSessionRules extends SessionPermissionRules {
100
107
  rev: number;
@@ -370,7 +377,9 @@ export declare function judgeSessionRulesWrite(prior: StoredSessionRules | null,
370
377
  * nothing is in no effect, so writing it in this engine's grammar widens). Both sides are read through
371
378
  * {@link readSessionRulesShape} first: a side it cannot read (a key that is no bucket — a retired one included) throws
372
379
  * `invalid_shape` rather than compare without it. `mountedToolNames` = the store's declaration
373
- * ({@link SessionPolicyStoreOptions.mountedToolNames}; empty when it has none) — the write judge's too.
380
+ * ({@link SessionPolicyStoreOptions.mountedToolNames}; empty when it has none), read with the engine's catalog as the one
381
+ * {@link storeRoster} the write judge reads: a case twin of an engine tool (`BASH`) is no entry on either side, so its owner can
382
+ * take a stored one out (and adding one widens nothing).
374
383
  */
375
384
  export declare function loosenReasons(priorValue: SessionPermissionRules, nextValue: SessionPermissionRules, mountedToolNames?: ReadonlySet<string>): string[];
376
385
  /**
@@ -7,12 +7,13 @@ import { valueTypeLabel } from "./tool-name-list.js";
7
7
  import { NAME_RULE_FACES, noticeRuleText } from "./permission-rule-model.js";
8
8
  import { parsePermissionRule, ruleSpellingOf } from "./permission-rule-syntax.js";
9
9
  import { splitNamespacedName } from "./tool-name-aliases.js";
10
+ import { namesASetOfTools } from "./namespaced-rule-name.js";
10
11
  const SESSION_RULE_BUCKETS = { toolAllow: "allow", toolDeny: "deny", allowDirs: "dirs" };
11
12
  const BUCKETS = Object.keys(SESSION_RULE_BUCKETS);
12
13
  const ENTRY_FIELDS = BUCKETS.filter((f) => SESSION_RULE_BUCKETS[f] !== "dirs");
13
14
  const STORE_STAMPS = new Set(["rev", "gen", "grammar"]);
14
15
  const OPERATOR_PART = "operatorRules";
15
- export const SESSION_RULES_GRAMMAR = 6;
16
+ export const SESSION_RULES_GRAMMAR = 7;
16
17
  export class SessionPolicyError extends Error {
17
18
  code;
18
19
  detail;
@@ -216,6 +217,20 @@ const GRAMMAR_REVISIONS = [
216
217
  return { ...answer, was: `the exact tool name ${JSON.stringify(pattern)}, so it refused only a tool of that name`, keep: { kind: "row", compiled: { kind: "tool", name: pattern } } };
217
218
  },
218
219
  },
220
+ {
221
+ grammar: 7,
222
+ answer: ({ direction, reading }) => {
223
+ if (direction !== "deny" || reading.kind !== "row" || reading.compiled.kind !== "covering" || namesASetOfTools(reading.compiled.pattern, "deny"))
224
+ return undefined;
225
+ const { pattern } = reading.compiled;
226
+ return {
227
+ was: `the exact tool name ${JSON.stringify(pattern)}, so it refused only a tool of that name`,
228
+ now: "every MCP server spelling the name can stand for — that tool, and every tool of a server whose own name carries the `__`",
229
+ keep: { kind: "row", compiled: { kind: "tool", name: pattern } },
230
+ reader: "grammar_revised",
231
+ };
232
+ },
233
+ },
219
234
  ];
220
235
  function earlierGrammarReads(row, direction, entry, reading, list) {
221
236
  if (row >= SESSION_RULES_GRAMMAR)
@@ -392,11 +407,14 @@ export function earlierGrammarAnnouncer(sink) {
392
407
  }
393
408
  };
394
409
  }
395
- function effectiveEntries(rules, field, mountedToolNames) {
396
- return compileSessionRuleBucket(rules, field, mountedToolNames).rows.map((r) => r.entry);
410
+ function storeRoster(declared) {
411
+ return rootFacingToolNames(declared);
412
+ }
413
+ function effectiveEntries(rules, field, roster) {
414
+ return compileSessionRuleBucket(rules, field, roster).rows.map((r) => r.entry);
397
415
  }
398
416
  function assertEntriesRead(rules, mountedToolNames) {
399
- const known = rootFacingToolNames(mountedToolNames);
417
+ const known = storeRoster(mountedToolNames);
400
418
  for (const field of ENTRY_FIELDS) {
401
419
  for (const { entry, reading: read, reader } of bucketReadings(rules, field, known)) {
402
420
  if (read.kind === "row")
@@ -467,23 +485,24 @@ export function loosenReasons(priorValue, nextValue, mountedToolNames = NO_DECLA
467
485
  };
468
486
  const prior = shapeOf("prior", priorValue);
469
487
  const next = shapeOf("next", nextValue);
470
- if (unreadableDenyEntries(next, mountedToolNames).length > 0)
488
+ const roster = storeRoster(mountedToolNames);
489
+ if (unreadableDenyEntries(next, roster).length > 0)
471
490
  return [];
472
- const unreadPrior = unreadableDenyEntries(prior, mountedToolNames);
491
+ const unreadPrior = unreadableDenyEntries(prior, roster);
473
492
  if (unreadPrior.length > 0) {
474
493
  return [`the prior rules refuse every call — their toolDeny holds ${shownEntries(unreadPrior.map((i) => i.entry), (entry) => inertEntryPhrase({ entry, reason: "grammar" }))}, which no grammar reads`];
475
494
  }
476
495
  const reasons = [];
477
- const keptDeny = new Set(effectiveEntries(next, "toolDeny", mountedToolNames));
478
- for (const x of effectiveEntries(prior, "toolDeny", mountedToolNames))
496
+ const keptDeny = new Set(effectiveEntries(next, "toolDeny", roster));
497
+ for (const x of effectiveEntries(prior, "toolDeny", roster))
479
498
  if (!keptDeny.has(x))
480
499
  reasons.push(`removed toolDeny ${renderListEntry(x)}`);
481
500
  if (prior.toolAllow !== undefined) {
482
501
  if (next.toolAllow === undefined)
483
502
  reasons.push("removed toolAllow allowlist (all allowed)");
484
503
  else {
485
- const had = new Set(effectiveEntries(prior, "toolAllow", mountedToolNames));
486
- for (const x of effectiveEntries(next, "toolAllow", mountedToolNames))
504
+ const had = new Set(effectiveEntries(prior, "toolAllow", roster));
505
+ for (const x of effectiveEntries(next, "toolAllow", roster))
487
506
  if (!had.has(x))
488
507
  reasons.push(`widened toolAllow with ${renderListEntry(x)}`);
489
508
  }
@@ -1,4 +1,4 @@
1
- import { type Session, type SessionHead, type SessionPlacementRecord, type SessionRepo } from "../internal/harness.js";
1
+ import { type ForkPoint, type Session, type SessionHead, type SessionPlacementRecord, type SessionRepo } from "../internal/harness.js";
2
2
  import { type AcquiredSession, type PlacedSessionRow, type SessionListQuery, type SessionLogTransfer, type SessionPlacement, type SessionStore, type SessionStoreHooks, type SessionStoreSummary } from "./session.js";
3
3
  import type { StoreDurability } from "./checkpoint-store.js";
4
4
  import { type RetentionDeclaration } from "./retention.js";
@@ -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;
@@ -339,7 +340,4 @@ export declare class TtlSessionStore implements SessionStore {
339
340
  * and owner it mints. Forking the whole log instead copies the in-flight turn. The walk is one of the parent-chain walks, so it takes the
340
341
  * shared guard: a leaf on a loop of tool-result messages is refused `invalid_session` (the sentence of `getPathToRoot`) instead of followed.
341
342
  */
342
- export declare function settledForkOptions(source: Session): Promise<{
343
- entryId?: string;
344
- position?: "at";
345
- }>;
343
+ export declare function settledForkOptions(source: Session): Promise<ForkPoint>;
@@ -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;
@@ -1,5 +1,6 @@
1
1
  import type { AssistantMessage, StopReason, Tool, ToolResultMessage, Usage, UserMessage } from "../internal/llm.js";
2
- import type { Brain, Model, ModelRef, ModelRole, ModelRoles, TaskSpec, ThinkingLevel } from "./types.js";
2
+ import type { Brain, Model, ModelRef, ModelRole, ModelRoles, RunnerDeps, TaskSpec, ThinkingLevel } from "./types.js";
3
+ import type { AccountRow } from "./account-row.js";
3
4
  import { type DegradationInfo } from "../brain/degrading.js";
4
5
  import { type BrainErrorCode } from "../brain/errors.js";
5
6
  /** A tool DEFINITION exposed to the model in a side query (never executed by the engine). */
@@ -113,6 +114,13 @@ export interface SideQueryResult {
113
114
  * figures, untouched. `usageMissing` ⇒ the numbers are UNKNOWN shells, not zeros. */
114
115
  usage: Usage;
115
116
  usageMissing?: true;
117
+ /** This query's line in the session's account: `origin: "side_query"`, priced by the engine from the deployment's price table
118
+ * (the arithmetic a run's own model calls use; `usage.cost` above stays the provider's own figure), the model that ANSWERED
119
+ * being the one priced. A host that keeps the account keeps this line beside its run lines and reads them back through
120
+ * `foldAccount`. `costMicroUsd` is absent when that model has no price table (unknown, not free); a reply that reported
121
+ * no usage yields `tokens: 0` with `usageMissing`. A malformed price table prices at its arithmetic, as it does for a run
122
+ * whose deployment governs no money. */
123
+ account: AccountRow;
116
124
  stopReason: StopReason;
117
125
  /** Present on `stopReason:"error"|"aborted"` — the query did not produce a usable reply. The verb
118
126
  * RETURNS the honest failure instead of throwing: utility callers uniformly need "no answer +
@@ -133,5 +141,7 @@ export interface SideQueryDeps {
133
141
  brain: Brain;
134
142
  models?: Record<string, Model>;
135
143
  roles?: ModelRoles;
144
+ /** The deployment's price table (`RunnerDeps.pricing`) the result's `account` line is priced from; absent ⇒ the model's own `cost`, else unpriced. */
145
+ pricing?: RunnerDeps["pricing"];
136
146
  }
137
147
  export declare function runSideQuery(spec: SideQuerySpec, deps: SideQueryDeps): Promise<SideQueryResult>;
@@ -6,6 +6,7 @@ import { effectiveTraitsOf, readModelPromptTraits, selectorsOf } from "../prompt
6
6
  import { readDegradation } from "../brain/degrading.js";
7
7
  import { extractErrorCode } from "../brain/errors.js";
8
8
  import { cacheFamilyOf, uncachedInputTokensOf } from "./runner/usage-accounting.js";
9
+ import { priceReply } from "./runner/reply-pricing.js";
9
10
  import { providerReportedModel } from "./message-utils.js";
10
11
  import { providerToolCallId } from "../brain/tool-call-id.js";
11
12
  function normalizeSideQueryUsage(model, u) {
@@ -82,6 +83,13 @@ export async function runSideQuery(spec, deps) {
82
83
  const servedModel = typeof msg.model === "string" && msg.model.length > 0 ? msg.model : resolved.model.id;
83
84
  const reportedModel = providerReportedModel(msg);
84
85
  const errorCode = extractErrorCode(msg.errorMessage);
86
+ const priced = priceReply(msg.usage, { model: resolved.model, ...(degraded !== undefined && degraded.to !== resolved.model.id ? { servedBy: degraded.to } : {}) }, { pricing: deps.pricing, catalog: deps.models });
87
+ const account = {
88
+ origin: "side_query",
89
+ tokens: msg.usage.totalTokens || 0,
90
+ ...(priced.priced ? { costMicroUsd: priced.costMicroUsd } : {}),
91
+ ...(msg.usageMissing === true ? { usageMissing: true } : {}),
92
+ };
85
93
  return {
86
94
  text,
87
95
  toolCalls,
@@ -91,6 +99,7 @@ export async function runSideQuery(spec, deps) {
91
99
  ...(reportedModel !== undefined ? { responseModel: reportedModel } : {}),
92
100
  usage: normalizeSideQueryUsage(resolved.model, msg.usage),
93
101
  ...(msg.usageMissing === true ? { usageMissing: true } : {}),
102
+ account,
94
103
  stopReason: msg.stopReason,
95
104
  ...(msg.errorMessage !== undefined ? { errorMessage: msg.errorMessage } : {}),
96
105
  ...(msg.stopReason === "error" && errorCode !== undefined ? { errorCode } : {}),