@sema-agent/core 7.66.0 → 7.67.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 (903) hide show
  1. package/CHANGELOG.md +3498 -0
  2. package/LICENSE +2 -1
  3. package/dist/agents/agent-definition.js +2 -1
  4. package/dist/agents/agent-transcript-tool.d.ts +1 -1
  5. package/dist/agents/agent-transcript-tool.js +4 -3
  6. package/dist/agents/builtin-agents.d.ts +10 -7
  7. package/dist/agents/builtin-agents.js +1 -0
  8. package/dist/agents/cascade.d.ts +24 -11
  9. package/dist/agents/cascade.js +21 -9
  10. package/dist/agents/child-failure.d.ts +30 -0
  11. package/dist/agents/child-failure.js +25 -1
  12. package/dist/agents/composition-placement.d.ts +6 -2
  13. package/dist/agents/composition-placement.js +7 -3
  14. package/dist/agents/cross-session-envelope.d.ts +10 -1
  15. package/dist/agents/cross-session-envelope.js +6 -2
  16. package/dist/agents/cross-session-judge.d.ts +7 -1
  17. package/dist/agents/cross-session-judge.js +1 -0
  18. package/dist/agents/cumulative-stats.d.ts +36 -2
  19. package/dist/agents/cumulative-stats.js +44 -9
  20. package/dist/agents/delegation-registry-seat.js +2 -3
  21. package/dist/agents/inherited-tool-pool.d.ts +9 -4
  22. package/dist/agents/inherited-tool-pool.js +7 -1
  23. package/dist/agents/leg-label.d.ts +28 -0
  24. package/dist/agents/leg-label.js +9 -0
  25. package/dist/agents/list-agents-tool.d.ts +1 -1
  26. package/dist/agents/list-agents-tool.js +4 -4
  27. package/dist/agents/org-delivery-gate.d.ts +129 -23
  28. package/dist/agents/org-delivery-gate.js +41 -20
  29. package/dist/agents/peer-held-queue.d.ts +15 -10
  30. package/dist/agents/peer-held-queue.js +47 -19
  31. package/dist/agents/peer-notice-route.js +2 -2
  32. package/dist/agents/peer-notices.d.ts +13 -2
  33. package/dist/agents/peer-notices.js +12 -2
  34. package/dist/agents/peer-session-drain.d.ts +65 -15
  35. package/dist/agents/peer-session-drain.js +198 -41
  36. package/dist/agents/read-inbox-tool.d.ts +3 -2
  37. package/dist/agents/read-inbox-tool.js +7 -5
  38. package/dist/agents/repair-loop.js +20 -16
  39. package/dist/agents/retain-ledger.d.ts +1 -1
  40. package/dist/agents/retain-ledger.js +2 -4
  41. package/dist/agents/root-session-lane.d.ts +27 -0
  42. package/dist/agents/root-session-lane.js +57 -0
  43. package/dist/agents/roster-store.js +1 -2
  44. package/dist/agents/send-message-tool.js +6 -4
  45. package/dist/agents/subagent.d.ts +20 -4
  46. package/dist/agents/subagent.js +218 -183
  47. package/dist/agents/tool-filter.d.ts +3 -10
  48. package/dist/agents/tool-filter.js +0 -13
  49. package/dist/agents/verifier-independence.d.ts +31 -0
  50. package/dist/agents/verifier-independence.js +23 -0
  51. package/dist/agents/verify.d.ts +23 -11
  52. package/dist/agents/verify.js +28 -12
  53. package/dist/agents/yield-adoption.d.ts +24 -0
  54. package/dist/agents/yield-adoption.js +84 -0
  55. package/dist/bench/metrics.d.ts +2 -2
  56. package/dist/brain/anthropic.d.ts +4 -2
  57. package/dist/brain/anthropic.js +49 -35
  58. package/dist/brain/brain-faces.d.ts +11 -0
  59. package/dist/brain/brain-faces.js +6 -0
  60. package/dist/brain/cache-retention.d.ts +2 -0
  61. package/dist/brain/cache-retention.js +9 -0
  62. package/dist/brain/circuit-breaker.js +51 -26
  63. package/dist/brain/errors.d.ts +15 -1
  64. package/dist/brain/errors.js +8 -0
  65. package/dist/brain/failover.d.ts +6 -0
  66. package/dist/brain/failover.js +52 -37
  67. package/dist/brain/media-degrade.d.ts +5 -0
  68. package/dist/brain/media-degrade.js +4 -0
  69. package/dist/brain/model-capability.d.ts +2 -1
  70. package/dist/brain/model-lane.d.ts +145 -0
  71. package/dist/brain/model-lane.js +444 -0
  72. package/dist/brain/open-responses.js +19 -22
  73. package/dist/brain/openai.js +23 -22
  74. package/dist/brain/provider-message.d.ts +9 -0
  75. package/dist/brain/provider-message.js +18 -0
  76. package/dist/brain/reasoning-request.d.ts +9 -7
  77. package/dist/brain/reasoning-request.js +9 -10
  78. package/dist/brain/reasoning.d.ts +47 -13
  79. package/dist/brain/reasoning.js +20 -10
  80. package/dist/brain/route-adjudicator.d.ts +8 -2
  81. package/dist/brain/route-adjudicator.js +35 -1
  82. package/dist/brain/route-conformance.js +17 -0
  83. package/dist/brain/routing.d.ts +2 -0
  84. package/dist/brain/routing.js +19 -8
  85. package/dist/brain/status-sink.d.ts +5 -4
  86. package/dist/brain/status-sink.js +2 -2
  87. package/dist/brain/stream-engine.js +8 -2
  88. package/dist/brain/stream-shared.d.ts +12 -0
  89. package/dist/brain/stream-shared.js +18 -0
  90. package/dist/brain/timeout.d.ts +28 -0
  91. package/dist/brain/timeout.js +13 -4
  92. package/dist/brain/tool-schema-projection.d.ts +2 -0
  93. package/dist/brain/tool-schema-projection.js +108 -0
  94. package/dist/brain/usage-reading.d.ts +49 -0
  95. package/dist/brain/usage-reading.js +44 -0
  96. package/dist/brain/usage-reasoning.d.ts +38 -0
  97. package/dist/brain/usage-reasoning.js +9 -0
  98. package/dist/config/catalog.d.ts +3 -0
  99. package/dist/config/catalog.js +18 -9
  100. package/dist/core/a2a.d.ts +22 -4
  101. package/dist/core/a2a.js +191 -50
  102. package/dist/core/agent-definition.d.ts +3 -1
  103. package/dist/core/agent-state.d.ts +29 -16
  104. package/dist/core/agent-state.js +36 -9
  105. package/dist/core/allow-entry.d.ts +12 -3
  106. package/dist/core/allow-entry.js +10 -3
  107. package/dist/core/approval-display.d.ts +18 -0
  108. package/dist/core/approval-display.js +26 -0
  109. package/dist/core/approval-object.js +2 -2
  110. package/dist/core/approval-route.d.ts +16 -0
  111. package/dist/core/approval-route.js +5 -0
  112. package/dist/core/approval-words.d.ts +43 -0
  113. package/dist/core/approval-words.js +37 -0
  114. package/dist/core/ask-origin.d.ts +37 -10
  115. package/dist/core/ask-origin.js +19 -7
  116. package/dist/core/ask-question.d.ts +36 -8
  117. package/dist/core/ask-question.js +24 -9
  118. package/dist/core/ask-unresolvable-notice.d.ts +3 -2
  119. package/dist/core/ask-unresolvable-notice.js +3 -2
  120. package/dist/core/attachment-source.d.ts +50 -0
  121. package/dist/core/attachment-source.js +46 -0
  122. package/dist/core/auto-compaction.d.ts +151 -40
  123. package/dist/core/auto-compaction.js +115 -50
  124. package/dist/core/auto-mode.d.ts +5 -0
  125. package/dist/core/auto-mode.js +11 -4
  126. package/dist/core/background-agent-store.d.ts +151 -23
  127. package/dist/core/background-agent-store.js +201 -61
  128. package/dist/core/background-shell.d.ts +4 -1
  129. package/dist/core/background-shell.js +1 -0
  130. package/dist/core/cache-break-detector.d.ts +49 -25
  131. package/dist/core/cache-break-detector.js +99 -44
  132. package/dist/core/caller-text.d.ts +28 -0
  133. package/dist/core/caller-text.js +12 -0
  134. package/dist/core/canonical-json.d.ts +5 -0
  135. package/dist/core/canonical-json.js +7 -0
  136. package/dist/core/checkpoint-features.d.ts +80 -9
  137. package/dist/core/checkpoint-features.js +1 -1
  138. package/dist/core/checkpoint-generation.d.ts +8 -1
  139. package/dist/core/checkpoint-generation.js +3 -0
  140. package/dist/core/checkpoint-queries.d.ts +47 -14
  141. package/dist/core/checkpoint-queries.js +63 -30
  142. package/dist/core/checkpoint-requirements.d.ts +36 -3
  143. package/dist/core/checkpoint-requirements.js +11 -1
  144. package/dist/core/checkpoint-row-verdict.d.ts +0 -2
  145. package/dist/core/checkpoint-row-verdict.js +5 -8
  146. package/dist/core/checkpoint-store.d.ts +166 -41
  147. package/dist/core/checkpoint-store.js +96 -15
  148. package/dist/core/child-clamp-seats.d.ts +10 -2
  149. package/dist/core/child-clamp-seats.js +2 -2
  150. package/dist/core/classifier-unavailable-arm.d.ts +11 -9
  151. package/dist/core/classifier-unavailable-arm.js +4 -2
  152. package/dist/core/command-sandbox-dispatch.d.ts +13 -0
  153. package/dist/core/command-sandbox-dispatch.js +8 -0
  154. package/dist/core/command-sandbox.d.ts +231 -0
  155. package/dist/core/command-sandbox.js +344 -0
  156. package/dist/core/completion-id.d.ts +21 -0
  157. package/dist/core/completion-id.js +14 -0
  158. package/dist/core/config-refusal-codes.d.ts +22 -0
  159. package/dist/core/config-refusal-codes.js +196 -0
  160. package/dist/core/context-edit.d.ts +26 -0
  161. package/dist/core/context-edit.js +4 -2
  162. package/dist/core/context-guard.d.ts +80 -7
  163. package/dist/core/context-guard.js +126 -25
  164. package/dist/core/context-settings.d.ts +32 -0
  165. package/dist/core/context-settings.js +41 -3
  166. package/dist/core/contract-faces.d.ts +22 -0
  167. package/dist/core/contract-faces.js +1 -0
  168. package/dist/core/credential-echo.d.ts +2 -2
  169. package/dist/core/credential-echo.js +2 -2
  170. package/dist/core/cross-boundary-taint.d.ts +10 -8
  171. package/dist/core/decision-receipt.d.ts +3 -2
  172. package/dist/core/decision-receipt.js +1 -1
  173. package/dist/core/definition-entry-grammar.d.ts +42 -0
  174. package/dist/core/definition-entry-grammar.js +15 -0
  175. package/dist/core/engine-attestation.d.ts +19 -4
  176. package/dist/core/engine-attestation.js +4 -0
  177. package/dist/core/engine-capabilities.d.ts +8 -1
  178. package/dist/core/engine-capabilities.js +1 -1
  179. package/dist/core/engine-contracts/open-face-contract.d.ts +39 -0
  180. package/dist/core/engine-contracts/open-face-contract.js +57 -0
  181. package/dist/core/engine-notice.d.ts +161 -33
  182. package/dist/core/exclusive-temp.d.ts +25 -0
  183. package/dist/core/exclusive-temp.js +19 -0
  184. package/dist/core/existing-target.d.ts +112 -0
  185. package/dist/core/existing-target.js +88 -0
  186. package/dist/core/file-history-store.d.ts +14 -6
  187. package/dist/core/gate-lanes.js +8 -3
  188. package/dist/core/gate-outcome.d.ts +2 -1
  189. package/dist/core/git-worktree-env.d.ts +92 -1
  190. package/dist/core/git-worktree-env.js +87 -6
  191. package/dist/core/governance-codes.d.ts +49 -8
  192. package/dist/core/governance-codes.js +59 -8
  193. package/dist/core/hands-band.d.ts +10 -6
  194. package/dist/core/hooks.d.ts +60 -6
  195. package/dist/core/hooks.js +10 -2
  196. package/dist/core/host-floor.d.ts +24 -8
  197. package/dist/core/host-floor.js +45 -16
  198. package/dist/core/human-input-projection.d.ts +7 -0
  199. package/dist/core/human-input-projection.js +11 -3
  200. package/dist/core/image-admission.d.ts +16 -4
  201. package/dist/core/image-admission.js +29 -17
  202. package/dist/core/input-author.d.ts +43 -1
  203. package/dist/core/input-author.js +19 -0
  204. package/dist/core/isolation-scope.d.ts +41 -0
  205. package/dist/core/isolation-scope.js +10 -0
  206. package/dist/core/json-schema-seats.d.ts +11 -0
  207. package/dist/core/json-schema-seats.js +5 -0
  208. package/dist/core/leg-identity.d.ts +53 -5
  209. package/dist/core/leg-identity.js +32 -1
  210. package/dist/core/locked-config.d.ts +33 -38
  211. package/dist/core/locked-config.js +21 -3
  212. package/dist/core/lsp.js +2 -1
  213. package/dist/core/mailbox-store.d.ts +111 -18
  214. package/dist/core/mailbox-store.js +101 -13
  215. package/dist/core/mcp-call-meta.js +1 -1
  216. package/dist/core/mcp-connection-pool.d.ts +8 -2
  217. package/dist/core/mcp-connection-pool.js +3 -1
  218. package/dist/core/mcp-failure.d.ts +6 -1
  219. package/dist/core/mcp-failure.js +10 -0
  220. package/dist/core/mcp-host-read.d.ts +293 -0
  221. package/dist/core/mcp-host-read.js +428 -0
  222. package/dist/core/mcp-server-link.d.ts +28 -6
  223. package/dist/core/mcp-server-link.js +35 -7
  224. package/dist/core/mcp-server-spec.d.ts +22 -29
  225. package/dist/core/mcp-server-spec.js +7 -14
  226. package/dist/core/mcp-server-unavailable-notice.d.ts +32 -0
  227. package/dist/core/mcp-server-unavailable-notice.js +15 -0
  228. package/dist/core/mcp-session-end.d.ts +5 -2
  229. package/dist/core/mcp-session-end.js +7 -2
  230. package/dist/core/mcp-tool-meta.d.ts +6 -0
  231. package/dist/core/mcp-tool-meta.js +1 -0
  232. package/dist/core/mcp.d.ts +54 -19
  233. package/dist/core/mcp.js +194 -241
  234. package/dist/core/memory-engine/committed-shadow-read.d.ts +16 -0
  235. package/dist/core/memory-engine/committed-shadow-read.js +21 -0
  236. package/dist/core/memory-engine/consolidation-driver.js +2 -1
  237. package/dist/core/memory-engine/consolidation.d.ts +3 -3
  238. package/dist/core/memory-engine/control-objects.d.ts +4 -3
  239. package/dist/core/memory-engine/control-objects.js +6 -4
  240. package/dist/core/memory-engine/delegation-settlement.d.ts +127 -25
  241. package/dist/core/memory-engine/delegation-settlement.js +145 -18
  242. package/dist/core/memory-engine/distiller.d.ts +2 -1
  243. package/dist/core/memory-engine/distiller.js +10 -5
  244. package/dist/core/memory-engine/dual-root.js +2 -2
  245. package/dist/core/memory-engine/engine.d.ts +127 -33
  246. package/dist/core/memory-engine/engine.js +774 -323
  247. package/dist/core/memory-engine/entry-scan.d.ts +3 -0
  248. package/dist/core/memory-engine/entry-scan.js +8 -0
  249. package/dist/core/memory-engine/export-bundle.d.ts +4 -0
  250. package/dist/core/memory-engine/export-bundle.js +2 -0
  251. package/dist/core/memory-engine/file-backend.d.ts +62 -17
  252. package/dist/core/memory-engine/file-backend.js +155 -99
  253. package/dist/core/memory-engine/index.d.ts +1 -1
  254. package/dist/core/memory-engine/index.js +1 -1
  255. package/dist/core/memory-engine/layer-observations.d.ts +7 -1
  256. package/dist/core/memory-engine/layer-observations.js +6 -0
  257. package/dist/core/memory-engine/layout.d.ts +88 -26
  258. package/dist/core/memory-engine/layout.js +105 -29
  259. package/dist/core/memory-engine/memory-deployment.js +4 -4
  260. package/dist/core/memory-engine/mount-failed-notice.d.ts +24 -0
  261. package/dist/core/memory-engine/mount-failed-notice.js +22 -0
  262. package/dist/core/memory-engine/origin-clearance.d.ts +15 -1
  263. package/dist/core/memory-engine/origin-clearance.js +30 -10
  264. package/dist/core/memory-engine/scan.js +1 -1
  265. package/dist/core/memory-engine/scope-contract.js +4 -3
  266. package/dist/core/memory-engine/session-write-home.js +13 -1
  267. package/dist/core/memory-engine/sync-client.d.ts +1 -1
  268. package/dist/core/memory-engine/sync-client.js +3 -1
  269. package/dist/core/memory-engine/tools.d.ts +5 -4
  270. package/dist/core/memory-engine/tools.js +1 -1
  271. package/dist/core/memory-engine/types.d.ts +18 -1
  272. package/dist/core/memory-engine/types.js +1 -0
  273. package/dist/core/memory.d.ts +1 -1
  274. package/dist/core/memory.js +2 -6
  275. package/dist/core/mode-policy.d.ts +8 -1
  276. package/dist/core/mode-policy.js +6 -2
  277. package/dist/core/model-fallbacks.d.ts +103 -0
  278. package/dist/core/model-fallbacks.js +79 -0
  279. package/dist/core/model-receipt.d.ts +15 -3
  280. package/dist/core/model-receipt.js +22 -1
  281. package/dist/core/model-seat.d.ts +1 -1
  282. package/dist/core/mods/classic-events.d.ts +5 -1
  283. package/dist/core/mods/dollar.d.ts +47 -2
  284. package/dist/core/mods/dollar.js +28 -5
  285. package/dist/core/mods/kernel/budget.d.ts +6 -0
  286. package/dist/core/mods/kernel/budget.js +6 -0
  287. package/dist/core/mods/kernel/dispatch.d.ts +23 -2
  288. package/dist/core/mods/kernel/dispatch.js +104 -15
  289. package/dist/core/mods/kernel/events.d.ts +18 -1
  290. package/dist/core/mods/kernel/events.js +7 -6
  291. package/dist/core/mods/kernel/index.d.ts +2 -2
  292. package/dist/core/mods/kernel/index.js +1 -1
  293. package/dist/core/mods/kernel/receive.d.ts +2 -1
  294. package/dist/core/mods/lifecycle-stations.d.ts +13 -4
  295. package/dist/core/mods/lifecycle-stations.js +8 -3
  296. package/dist/core/mods/message-display.d.ts +81 -0
  297. package/dist/core/mods/message-display.js +369 -0
  298. package/dist/core/mods/prompt-submit.d.ts +1 -1
  299. package/dist/core/mods/prompt-submit.js +5 -2
  300. package/dist/core/mods/session-append.d.ts +2 -2
  301. package/dist/core/mods/session-append.js +2 -1
  302. package/dist/core/mods/session-compact.js +2 -2
  303. package/dist/core/mods/stations.d.ts +48 -18
  304. package/dist/core/mods/stations.js +100 -19
  305. package/dist/core/mods/stop-answers.d.ts +23 -0
  306. package/dist/core/mods/stop-answers.js +20 -0
  307. package/dist/core/mounted-mcp.d.ts +48 -8
  308. package/dist/core/mounted-mcp.js +82 -16
  309. package/dist/core/namespaced-rule-name.js +2 -1
  310. package/dist/core/own-property-receipt.js +3 -5
  311. package/dist/core/parent-spec-seat.d.ts +20 -1
  312. package/dist/core/parent-spec-seat.js +13 -3
  313. package/dist/core/park-selfcheck.js +1 -0
  314. package/dist/core/path-identity.js +2 -1
  315. package/dist/core/peer-seat.d.ts +21 -7
  316. package/dist/core/peer-seat.js +25 -16
  317. package/dist/core/permission-rule-consent.js +15 -5
  318. package/dist/core/permission-rule-model.d.ts +4 -2
  319. package/dist/core/permission-rule-model.js +43 -23
  320. package/dist/core/permission-rule-store.d.ts +31 -16
  321. package/dist/core/permission-rule-store.js +27 -18
  322. package/dist/core/present-plan-tool.d.ts +6 -1
  323. package/dist/core/present-plan-tool.js +11 -3
  324. package/dist/core/pricing.d.ts +8 -6
  325. package/dist/core/pricing.js +1 -1
  326. package/dist/core/principal-name.d.ts +13 -0
  327. package/dist/core/principal-name.js +9 -2
  328. package/dist/core/process-identity.d.ts +140 -0
  329. package/dist/core/process-identity.js +215 -0
  330. package/dist/core/protocol-http-auth.d.ts +28 -6
  331. package/dist/core/protocol-http-auth.js +22 -5
  332. package/dist/core/protocol-naming.d.ts +7 -0
  333. package/dist/core/protocol-naming.js +12 -2
  334. package/dist/core/protocol-revocation.d.ts +72 -0
  335. package/dist/core/protocol-revocation.js +98 -0
  336. package/dist/core/protocol-table.d.ts +4 -4
  337. package/dist/core/protocol-table.js +3 -2
  338. package/dist/core/push-queue.d.ts +35 -2
  339. package/dist/core/push-queue.js +60 -4
  340. package/dist/core/read-only-shell.d.ts +19 -0
  341. package/dist/core/read-only-shell.js +38 -11
  342. package/dist/core/real-approval.d.ts +26 -0
  343. package/dist/core/real-approval.js +15 -0
  344. package/dist/core/redaction-marks.d.ts +6 -2
  345. package/dist/core/redaction-marks.js +3 -0
  346. package/dist/core/reminder-mint.d.ts +6 -0
  347. package/dist/core/reminder-mint.js +9 -8
  348. package/dist/core/remote-env.d.ts +31 -15
  349. package/dist/core/remote-env.js +29 -0
  350. package/dist/core/request-copy-projection.d.ts +51 -0
  351. package/dist/core/request-copy-projection.js +410 -0
  352. package/dist/core/resume-config-judge.d.ts +69 -0
  353. package/dist/core/resume-config-judge.js +78 -0
  354. package/dist/core/resume-startup-cause.d.ts +14 -4
  355. package/dist/core/resume-startup-cause.js +12 -2
  356. package/dist/core/retention-policy.js +2 -1
  357. package/dist/core/retention.d.ts +119 -24
  358. package/dist/core/retention.js +60 -16
  359. package/dist/core/retired-keys.d.ts +0 -10
  360. package/dist/core/retired-keys.js +2 -3
  361. package/dist/core/roles.d.ts +6 -0
  362. package/dist/core/roles.js +65 -4
  363. package/dist/core/row-shape.d.ts +149 -0
  364. package/dist/core/row-shape.js +184 -0
  365. package/dist/core/runner/advertised-writable-dirs.js +10 -9
  366. package/dist/core/runner/advisor-instructions.d.ts +11 -27
  367. package/dist/core/runner/advisor-instructions.js +18 -20
  368. package/dist/core/runner/advisor-tool.js +1 -0
  369. package/dist/core/runner/announce-once-ledger.js +4 -1
  370. package/dist/core/runner/approval-feedback.d.ts +17 -8
  371. package/dist/core/runner/approval-feedback.js +18 -13
  372. package/dist/core/runner/approver-defect-announcer.d.ts +17 -0
  373. package/dist/core/runner/approver-defect-announcer.js +22 -0
  374. package/dist/core/runner/assemble-result.d.ts +29 -14
  375. package/dist/core/runner/assemble-result.js +16 -25
  376. package/dist/core/runner/cache-hit-account.d.ts +77 -0
  377. package/dist/core/runner/cache-hit-account.js +46 -0
  378. package/dist/core/runner/call-hook-stations.d.ts +3 -2
  379. package/dist/core/runner/call-hook-stations.js +5 -4
  380. package/dist/core/runner/changed-files-scan.d.ts +43 -0
  381. package/dist/core/runner/changed-files-scan.js +34 -0
  382. package/dist/core/runner/checkpoint-scope.d.ts +33 -9
  383. package/dist/core/runner/checkpoint-scope.js +27 -1
  384. package/dist/core/runner/classifier-ladder.d.ts +2 -2
  385. package/dist/core/runner/classifier-ladder.js +18 -9
  386. package/dist/core/runner/clock-and-limits.d.ts +15 -4
  387. package/dist/core/runner/clock-and-limits.js +19 -1
  388. package/dist/core/runner/compact-session.js +84 -14
  389. package/dist/core/runner/compaction-call-options.d.ts +2 -29
  390. package/dist/core/runner/compaction-call-options.js +2 -9
  391. package/dist/core/runner/compaction-restate.d.ts +18 -2
  392. package/dist/core/runner/compaction-restate.js +36 -2
  393. package/dist/core/runner/construction-doors.js +8 -0
  394. package/dist/core/runner/context-room.d.ts +55 -0
  395. package/dist/core/runner/context-room.js +71 -0
  396. package/dist/core/runner/contracts.d.ts +313 -205
  397. package/dist/core/runner/conversation-segment.d.ts +49 -14
  398. package/dist/core/runner/conversation-segment.js +92 -19
  399. package/dist/core/runner/cross-boundary-lane.d.ts +4 -0
  400. package/dist/core/runner/cross-boundary-lane.js +9 -6
  401. package/dist/core/runner/decide-continuation.js +1 -1
  402. package/dist/core/runner/deferred-ask.d.ts +62 -0
  403. package/dist/core/runner/deferred-ask.js +44 -0
  404. package/dist/core/runner/delegation-owner.d.ts +19 -0
  405. package/dist/core/runner/delegation-owner.js +27 -1
  406. package/dist/core/runner/denial-limit-arms.d.ts +10 -6
  407. package/dist/core/runner/denial-limit-arms.js +13 -7
  408. package/dist/core/runner/env-capability-census.d.ts +1 -1
  409. package/dist/core/runner/file-history-request.js +2 -1
  410. package/dist/core/runner/file-history-restore.d.ts +16 -2
  411. package/dist/core/runner/file-history-restore.js +9 -1
  412. package/dist/core/runner/gate-exit.d.ts +18 -5
  413. package/dist/core/runner/gate-exit.js +26 -15
  414. package/dist/core/runner/git-status-frame.d.ts +26 -8
  415. package/dist/core/runner/git-status-frame.js +14 -9
  416. package/dist/core/runner/halt-attribution.d.ts +29 -12
  417. package/dist/core/runner/halt-attribution.js +38 -11
  418. package/dist/core/runner/image.js +3 -2
  419. package/dist/core/runner/initial-run-state.d.ts +1 -1
  420. package/dist/core/runner/initial-run-state.js +4 -4
  421. package/dist/core/runner/language-frame.d.ts +66 -0
  422. package/dist/core/runner/language-frame.js +76 -0
  423. package/dist/core/runner/leg-frame.d.ts +81 -0
  424. package/dist/core/runner/leg-frame.js +68 -0
  425. package/dist/core/runner/main-call-account.d.ts +34 -0
  426. package/dist/core/runner/main-call-account.js +50 -0
  427. package/dist/core/runner/mcp-redial.d.ts +9 -7
  428. package/dist/core/runner/mcp-redial.js +20 -21
  429. package/dist/core/runner/memory-consolidation-driver.d.ts +2 -0
  430. package/dist/core/runner/memory-consolidation-driver.js +5 -3
  431. package/dist/core/runner/messages-omitted-seat.d.ts +2 -0
  432. package/dist/core/runner/messages-omitted-seat.js +21 -0
  433. package/dist/core/runner/model-fallback-seat.d.ts +20 -0
  434. package/dist/core/runner/model-fallback-seat.js +43 -0
  435. package/dist/core/runner/model-lane-seat.d.ts +12 -0
  436. package/dist/core/runner/model-lane-seat.js +35 -0
  437. package/dist/core/runner/nested-memory-content.d.ts +33 -0
  438. package/dist/core/runner/nested-memory-content.js +171 -0
  439. package/dist/core/runner/nested-memory-lane.d.ts +181 -0
  440. package/dist/core/runner/nested-memory-lane.js +673 -0
  441. package/dist/core/runner/park-commit.d.ts +7 -0
  442. package/dist/core/runner/park-commit.js +3 -0
  443. package/dist/core/runner/prepare-advisor.d.ts +7 -9
  444. package/dist/core/runner/prepare-advisor.js +11 -5
  445. package/dist/core/runner/prepare-artifact.d.ts +1 -1
  446. package/dist/core/runner/prepare-artifact.js +8 -3
  447. package/dist/core/runner/prepare-ask-lane.d.ts +21 -3
  448. package/dist/core/runner/prepare-ask-lane.js +32 -28
  449. package/dist/core/runner/prepare-boundary-parks.d.ts +2 -2
  450. package/dist/core/runner/prepare-boundary-parks.js +21 -17
  451. package/dist/core/runner/prepare-caps-and-workflow.d.ts +10 -2
  452. package/dist/core/runner/prepare-caps-and-workflow.js +24 -18
  453. package/dist/core/runner/prepare-config-doors.d.ts +51 -5
  454. package/dist/core/runner/prepare-config-doors.js +73 -73
  455. package/dist/core/runner/prepare-context-lane.d.ts +68 -3
  456. package/dist/core/runner/prepare-context-lane.js +137 -27
  457. package/dist/core/runner/prepare-defer-classify.d.ts +0 -4
  458. package/dist/core/runner/prepare-defer-classify.js +9 -13
  459. package/dist/core/runner/prepare-delegation-surface.d.ts +8 -8
  460. package/dist/core/runner/prepare-delegation-surface.js +72 -64
  461. package/dist/core/runner/prepare-execution-env.js +1 -9
  462. package/dist/core/runner/prepare-file-history.d.ts +3 -2
  463. package/dist/core/runner/prepare-file-history.js +11 -4
  464. package/dist/core/runner/prepare-gate-stations.d.ts +21 -11
  465. package/dist/core/runner/prepare-gate-stations.js +13 -13
  466. package/dist/core/runner/prepare-hands-readface.d.ts +23 -6
  467. package/dist/core/runner/prepare-hands-readface.js +18 -12
  468. package/dist/core/runner/prepare-inherited-gate.d.ts +12 -5
  469. package/dist/core/runner/prepare-inherited-gate.js +14 -10
  470. package/dist/core/runner/prepare-lsp.js +2 -1
  471. package/dist/core/runner/prepare-memory-engine-session.js +30 -10
  472. package/dist/core/runner/prepare-memory.d.ts +4 -0
  473. package/dist/core/runner/prepare-memory.js +38 -16
  474. package/dist/core/runner/prepare-offload-wrappers.d.ts +3 -16
  475. package/dist/core/runner/prepare-offload-wrappers.js +6 -5
  476. package/dist/core/runner/prepare-park-ask.d.ts +13 -3
  477. package/dist/core/runner/prepare-park-ask.js +25 -19
  478. package/dist/core/runner/prepare-policy-chain.d.ts +17 -3
  479. package/dist/core/runner/prepare-policy-chain.js +144 -120
  480. package/dist/core/runner/prepare-project-context.d.ts +15 -53
  481. package/dist/core/runner/prepare-project-context.js +20 -83
  482. package/dist/core/runner/prepare-prompt-assembly.d.ts +7 -1
  483. package/dist/core/runner/prepare-prompt-assembly.js +9 -7
  484. package/dist/core/runner/prepare-prompt-inputs.d.ts +9 -3
  485. package/dist/core/runner/prepare-prompt-inputs.js +5 -3
  486. package/dist/core/runner/prepare-protocol-tools.d.ts +9 -4
  487. package/dist/core/runner/prepare-protocol-tools.js +46 -27
  488. package/dist/core/runner/prepare-question-face.d.ts +7 -6
  489. package/dist/core/runner/prepare-question-face.js +7 -6
  490. package/dist/core/runner/prepare-suspend-saga.d.ts +3 -0
  491. package/dist/core/runner/prepare-suspend-saga.js +1 -1
  492. package/dist/core/runner/prepare-task.d.ts +3 -3
  493. package/dist/core/runner/prepare-task.js +113 -61
  494. package/dist/core/runner/prepare-tool-disclosure-mount.js +6 -5
  495. package/dist/core/runner/prepare-turn-wiring.d.ts +33 -7
  496. package/dist/core/runner/prepare-turn-wiring.js +53 -17
  497. package/dist/core/runner/prepare-wiring-manifest.d.ts +42 -5
  498. package/dist/core/runner/prepare-wiring-manifest.js +81 -42
  499. package/dist/core/runner/prepare-workspace-restore.js +3 -2
  500. package/dist/core/runner/read-root-grant.js +2 -1
  501. package/dist/core/runner/reply-pricing.d.ts +31 -18
  502. package/dist/core/runner/reply-pricing.js +10 -15
  503. package/dist/core/runner/resume-admission.js +10 -15
  504. package/dist/core/runner/resume-apply.js +20 -9
  505. package/dist/core/runner/resume-checkpoint-screen.js +2 -4
  506. package/dist/core/runner/resume-internals-and-config.d.ts +12 -9
  507. package/dist/core/runner/resume-internals-and-config.js +37 -9
  508. package/dist/core/runner/resume-preflight.js +3 -3
  509. package/dist/core/runner/retired-runner-deps.js +3 -0
  510. package/dist/core/runner/rewind-files.js +6 -6
  511. package/dist/core/runner/run-attachment-seats.d.ts +1 -3
  512. package/dist/core/runner/run-attachment-seats.js +1 -6
  513. package/dist/core/runner/run-brain-sinks.d.ts +4 -7
  514. package/dist/core/runner/run-brain-sinks.js +7 -10
  515. package/dist/core/runner/run-clock-and-content.d.ts +8 -5
  516. package/dist/core/runner/run-clock-and-content.js +18 -3
  517. package/dist/core/runner/run-compaction-machinery.d.ts +8 -4
  518. package/dist/core/runner/run-compaction-machinery.js +4 -19
  519. package/dist/core/runner/run-git-lane.d.ts +8 -3
  520. package/dist/core/runner/run-git-lane.js +5 -3
  521. package/dist/core/runner/run-harness-handlers.d.ts +4 -1
  522. package/dist/core/runner/run-harness-handlers.js +70 -45
  523. package/dist/core/runner/run-identity-wiring.d.ts +6 -0
  524. package/dist/core/runner/run-identity-wiring.js +17 -8
  525. package/dist/core/runner/run-leg.d.ts +5 -2
  526. package/dist/core/runner/run-leg.js +156 -71
  527. package/dist/core/runner/run-notification-lane.d.ts +1 -1
  528. package/dist/core/runner/run-notification-lane.js +22 -10
  529. package/dist/core/runner/run-recovery-lanes.js +8 -6
  530. package/dist/core/runner/run-settle-and-teardown.d.ts +4 -0
  531. package/dist/core/runner/run-settle-and-teardown.js +77 -26
  532. package/dist/core/runner/run-stop-and-final-verify.js +46 -12
  533. package/dist/core/runner/run-telemetry-and-budget-seats.js +13 -28
  534. package/dist/core/runner/run-terminal-adoption.d.ts +2 -2
  535. package/dist/core/runner/run-terminal-adoption.js +14 -9
  536. package/dist/core/runner/run-tool-mount-facts.js +5 -9
  537. package/dist/core/runner/run-turn-boundary.d.ts +3 -2
  538. package/dist/core/runner/run-turn-boundary.js +112 -106
  539. package/dist/core/runner/runtask.d.ts +28 -8
  540. package/dist/core/runner/runtask.js +132 -41
  541. package/dist/core/runner/session-file-state-replay.d.ts +5 -3
  542. package/dist/core/runner/session-file-state-replay.js +10 -3
  543. package/dist/core/runner/session-rule-policy.d.ts +3 -3
  544. package/dist/core/runner/session-verb-doors.d.ts +18 -3
  545. package/dist/core/runner/session-verb-doors.js +38 -6
  546. package/dist/core/runner/shell-env-withheld.d.ts +8 -5
  547. package/dist/core/runner/shell-env-withheld.js +4 -4
  548. package/dist/core/runner/side-call-account.d.ts +12 -8
  549. package/dist/core/runner/side-call-account.js +24 -15
  550. package/dist/core/runner/stream-halt-verbs.js +1 -0
  551. package/dist/core/runner/stream-mode-verb.js +2 -1
  552. package/dist/core/runner/stream-settle-backstop.js +4 -1
  553. package/dist/core/runner/stream-steer-verb.js +35 -19
  554. package/dist/core/runner/sub-agent-deny-lists.d.ts +47 -11
  555. package/dist/core/runner/sub-agent-deny-lists.js +140 -39
  556. package/dist/core/runner/teardown-bounded.d.ts +6 -0
  557. package/dist/core/runner/teardown-bounded.js +12 -7
  558. package/dist/core/runner/terminal-account.d.ts +2 -0
  559. package/dist/core/runner/terminal-account.js +6 -1
  560. package/dist/core/runner/tool-disclosure.js +2 -1
  561. package/dist/core/runner/tool-end-body.js +3 -1
  562. package/dist/core/runner/tool-face-overlay.d.ts +1 -1
  563. package/dist/core/runner/tool-face-overlay.js +1 -1
  564. package/dist/core/runner/tool-occurrence.d.ts +34 -9
  565. package/dist/core/runner/tool-occurrence.js +32 -21
  566. package/dist/core/runner/tool-progress-lane.d.ts +20 -5
  567. package/dist/core/runner/tool-progress-lane.js +27 -5
  568. package/dist/core/runner/tool-result-media-seat.d.ts +15 -4
  569. package/dist/core/runner/tool-result-media-seat.js +17 -1
  570. package/dist/core/runner/tool-table-view.js +1 -1
  571. package/dist/core/runner/turn-attachments.d.ts +44 -71
  572. package/dist/core/runner/turn-attachments.js +52 -104
  573. package/dist/core/runner/usage-accounting.d.ts +3 -2
  574. package/dist/core/runner/usage-accounting.js +3 -2
  575. package/dist/core/runner/void-verifier-pause.js +1 -1
  576. package/dist/core/runner-deps.d.ts +42 -158
  577. package/dist/core/runtime-caps.d.ts +16 -4
  578. package/dist/core/secret-env.d.ts +20 -3
  579. package/dist/core/secret-env.js +46 -23
  580. package/dist/core/sensitive-path-policy.d.ts +8 -0
  581. package/dist/core/sensitive-path-policy.js +10 -2
  582. package/dist/core/session-checkout.d.ts +32 -27
  583. package/dist/core/session-checkout.js +109 -61
  584. package/dist/core/session-log-transfer.js +2 -1
  585. package/dist/core/session-policy-store.d.ts +24 -11
  586. package/dist/core/session-policy-store.js +11 -2
  587. package/dist/core/session-store.d.ts +16 -2
  588. package/dist/core/session-store.js +43 -17
  589. package/dist/core/session.d.ts +31 -3
  590. package/dist/core/session.js +33 -2
  591. package/dist/core/shell-run-candidates.d.ts +20 -8
  592. package/dist/core/shell-run-candidates.js +44 -21
  593. package/dist/core/side-query.d.ts +17 -5
  594. package/dist/core/side-query.js +17 -14
  595. package/dist/core/skill-grant.js +2 -3
  596. package/dist/core/skills-directory.js +3 -66
  597. package/dist/core/snapshot-frame-seat.d.ts +8 -0
  598. package/dist/core/snapshot-frame-seat.js +24 -0
  599. package/dist/core/steer-replay.d.ts +19 -3
  600. package/dist/core/steer-replay.js +8 -1
  601. package/dist/core/store-contracts/background-agent-store-contract.d.ts +17 -2
  602. package/dist/core/store-contracts/background-agent-store-contract.js +131 -2
  603. package/dist/core/store-contracts/checkpoint-store-contract.js +63 -1
  604. package/dist/core/store-contracts/mailbox-store-contract.d.ts +15 -2
  605. package/dist/core/store-contracts/mailbox-store-contract.js +213 -3
  606. package/dist/core/store-contracts/permission-rule-write-contract.js +24 -0
  607. package/dist/core/store-contracts/session-deletion-cascade-contract.d.ts +15 -0
  608. package/dist/core/store-contracts/session-deletion-cascade-contract.js +288 -0
  609. package/dist/core/store-contracts/session-policy-store-contract.js +57 -36
  610. package/dist/core/store-contracts/session-repo-contract.js +130 -5
  611. package/dist/core/store-contracts/session-store-contract.d.ts +1 -1
  612. package/dist/core/store-contracts/session-store-contract.js +17 -0
  613. package/dist/core/store-contracts/task-list-store-contract.d.ts +32 -0
  614. package/dist/core/store-contracts/task-list-store-contract.js +240 -0
  615. package/dist/core/store-contracts/tool-result-store-contract.d.ts +1 -1
  616. package/dist/core/store-contracts/tool-result-store-contract.js +41 -0
  617. package/dist/core/stub-env.d.ts +2 -2
  618. package/dist/core/stub-env.js +1 -0
  619. package/dist/core/synthetic-read-verdict.d.ts +38 -28
  620. package/dist/core/synthetic-read-verdict.js +19 -28
  621. package/dist/core/task-event.d.ts +171 -19
  622. package/dist/core/task-intake.d.ts +26 -0
  623. package/dist/core/task-intake.js +31 -0
  624. package/dist/core/task-limits.d.ts +8 -6
  625. package/dist/core/task-notification.d.ts +88 -8
  626. package/dist/core/task-notification.js +45 -5
  627. package/dist/core/task-registry-agent.d.ts +24 -7
  628. package/dist/core/task-registry-agent.js +51 -28
  629. package/dist/core/task-registry-monitor.js +16 -14
  630. package/dist/core/task-registry-shared.d.ts +177 -35
  631. package/dist/core/task-registry-shared.js +44 -17
  632. package/dist/core/task-registry-workflow.js +8 -5
  633. package/dist/core/task-registry-yield.d.ts +32 -0
  634. package/dist/core/task-registry-yield.js +85 -0
  635. package/dist/core/task-registry.d.ts +88 -10
  636. package/dist/core/task-registry.js +124 -33
  637. package/dist/core/task-result.d.ts +115 -31
  638. package/dist/core/task-spec-members.d.ts +140 -1
  639. package/dist/core/task-spec-members.js +23 -8
  640. package/dist/core/task-spec.d.ts +181 -51
  641. package/dist/core/task-spec.js +1 -1
  642. package/dist/core/task-stream.d.ts +12 -2
  643. package/dist/core/terminal-cause.d.ts +12 -4
  644. package/dist/core/thrown-value.d.ts +49 -7
  645. package/dist/core/thrown-value.js +38 -2
  646. package/dist/core/tool-catalog-entries.js +13 -3
  647. package/dist/core/tool-data-door.d.ts +7 -0
  648. package/dist/core/tool-data-door.js +13 -0
  649. package/dist/core/tool-face-lists.d.ts +25 -0
  650. package/dist/core/tool-face-lists.js +38 -0
  651. package/dist/core/tool-face-reader.d.ts +0 -10
  652. package/dist/core/tool-face-reader.js +5 -3
  653. package/dist/core/tool-list-grammar.d.ts +103 -0
  654. package/dist/core/tool-list-grammar.js +130 -0
  655. package/dist/core/tool-mount-facts.d.ts +47 -0
  656. package/dist/core/tool-mount-facts.js +50 -0
  657. package/dist/core/tool-mount-plan.d.ts +196 -0
  658. package/dist/core/tool-mount-plan.js +404 -0
  659. package/dist/core/tool-mount-static.d.ts +12 -0
  660. package/dist/core/tool-mount-static.js +174 -0
  661. package/dist/core/tool-name-aliases.d.ts +60 -2
  662. package/dist/core/tool-name-aliases.js +22 -2
  663. package/dist/core/tool-name-list.d.ts +3 -0
  664. package/dist/core/tool-name-readings.d.ts +4 -0
  665. package/dist/core/tool-name-readings.js +1 -0
  666. package/dist/core/tool-policy.d.ts +246 -51
  667. package/dist/core/tool-policy.js +165 -71
  668. package/dist/core/tool-registry.d.ts +4 -11
  669. package/dist/core/tool-registry.js +0 -3
  670. package/dist/core/tool-result-bytes.d.ts +94 -0
  671. package/dist/core/tool-result-bytes.js +34 -0
  672. package/dist/core/tool-result-store.d.ts +97 -13
  673. package/dist/core/tool-result-store.js +52 -4
  674. package/dist/core/tool-roster.d.ts +71 -10
  675. package/dist/core/tool-roster.js +71 -21
  676. package/dist/core/tool-search-setting.d.ts +7 -9
  677. package/dist/core/tool-search-setting.js +23 -7
  678. package/dist/core/tool-spec.d.ts +32 -2
  679. package/dist/core/tools.js +6 -20
  680. package/dist/core/trace.d.ts +63 -11
  681. package/dist/core/trace.js +19 -0
  682. package/dist/core/types.d.ts +8 -6
  683. package/dist/core/types.js +3 -1
  684. package/dist/core/unmatched-tool-names.d.ts +37 -0
  685. package/dist/core/unmatched-tool-names.js +18 -0
  686. package/dist/core/untrusted-egress.d.ts +16 -5
  687. package/dist/core/untrusted-egress.js +202 -32
  688. package/dist/core/untrusted-text.d.ts +29 -8
  689. package/dist/core/untrusted-text.js +6 -3
  690. package/dist/core/user-attachment.d.ts +129 -35
  691. package/dist/core/user-attachment.js +124 -57
  692. package/dist/core/user-row-origin.d.ts +63 -0
  693. package/dist/core/user-row-origin.js +61 -0
  694. package/dist/core/wiring-manifest.d.ts +161 -39
  695. package/dist/core/wiring-manifest.js +42 -6
  696. package/dist/core/workflow-run-store-contract.d.ts +11 -1
  697. package/dist/core/workflow-run-store-contract.js +60 -7
  698. package/dist/core/workflow-run-store.d.ts +61 -12
  699. package/dist/core/workflow-run-store.js +100 -15
  700. package/dist/core/workspace-snapshot.d.ts +10 -14
  701. package/dist/core/workspace-snapshot.js +3 -22
  702. package/dist/core/write-protect.d.ts +3 -5
  703. package/dist/core/write-protect.js +2 -4
  704. package/dist/engine/compaction/compaction.d.ts +3 -0
  705. package/dist/engine/compaction/compaction.js +4 -3
  706. package/dist/engine/execution-env/node-execution-env.d.ts +15 -4
  707. package/dist/engine/execution-env/node-execution-env.js +80 -27
  708. package/dist/engine/harness/agent-harness.d.ts +143 -27
  709. package/dist/engine/harness/agent-harness.js +162 -74
  710. package/dist/engine/harness/types.d.ts +84 -13
  711. package/dist/engine/harness/types.js +21 -1
  712. package/dist/engine/llm/tool-turns.d.ts +4 -0
  713. package/dist/engine/llm/tool-turns.js +7 -2
  714. package/dist/engine/llm/types.d.ts +111 -24
  715. package/dist/engine/llm/types.js +69 -5
  716. package/dist/engine/llm/validation.js +2 -1
  717. package/dist/engine/loop/agent-loop.d.ts +39 -6
  718. package/dist/engine/loop/agent-loop.js +172 -82
  719. package/dist/engine/loop/types.d.ts +43 -4
  720. package/dist/engine/lsp/node-lsp-manager.d.ts +5 -3
  721. package/dist/engine/lsp/node-lsp-manager.js +14 -10
  722. package/dist/engine/session/import-validate.js +9 -0
  723. package/dist/engine/session/memory-repo.d.ts +8 -1
  724. package/dist/engine/session/memory-repo.js +20 -12
  725. package/dist/engine/session/repo-utils.d.ts +10 -0
  726. package/dist/engine/session/repo-utils.js +11 -5
  727. package/dist/engine/session/row-cells.d.ts +32 -0
  728. package/dist/engine/session/row-cells.js +25 -0
  729. package/dist/index.d.ts +63 -34
  730. package/dist/index.js +44 -21
  731. package/dist/internal/harness.d.ts +8 -6
  732. package/dist/internal/harness.js +6 -4
  733. package/dist/internal/llm.d.ts +2 -2
  734. package/dist/internal/llm.js +1 -1
  735. package/dist/orchestration/governance-baseline-validity.d.ts +7 -0
  736. package/dist/orchestration/governance-baseline-validity.js +33 -9
  737. package/dist/orchestration/run-workflow-tool.d.ts +2 -0
  738. package/dist/orchestration/run-workflow-tool.js +25 -12
  739. package/dist/orchestration/workflow-governance.d.ts +19 -4
  740. package/dist/orchestration/workflow-governance.js +30 -9
  741. package/dist/orchestration/workflow-primitives.d.ts +4 -1
  742. package/dist/orchestration/workflow-primitives.js +2 -2
  743. package/dist/orchestration/workflow-script-runner.d.ts +1 -1
  744. package/dist/orchestration/workflow-size-guideline.d.ts +1 -1
  745. package/dist/orchestration/workflow-types.d.ts +21 -12
  746. package/dist/orchestration/workflow-types.js +15 -4
  747. package/dist/orchestration/workflow.d.ts +37 -7
  748. package/dist/orchestration/workflow.js +81 -35
  749. package/dist/prompt-assembly/artifact-store.js +6 -9
  750. package/dist/prompt-assembly/assemble.d.ts +4 -10
  751. package/dist/prompt-assembly/assemble.js +1 -3
  752. package/dist/prompt-assembly/catalog/constitution.d.ts +0 -20
  753. package/dist/prompt-assembly/catalog/constitution.js +2 -0
  754. package/dist/prompt-assembly/catalog/core-behavior.js +5 -3
  755. package/dist/prompt-assembly/catalog/engine.d.ts +108 -0
  756. package/dist/prompt-assembly/catalog/engine.js +19 -0
  757. package/dist/prompt-assembly/catalog/environment.d.ts +276 -0
  758. package/dist/prompt-assembly/catalog/environment.js +61 -0
  759. package/dist/prompt-assembly/catalog/index.d.ts +9 -2
  760. package/dist/prompt-assembly/catalog/index.js +73 -2
  761. package/dist/prompt-assembly/catalog/locales/index.d.ts +16 -0
  762. package/dist/prompt-assembly/catalog/locales/index.js +22 -0
  763. package/dist/prompt-assembly/catalog/locales/zh-Hans/constitution.d.ts +7 -0
  764. package/dist/prompt-assembly/catalog/locales/zh-Hans/constitution.js +124 -0
  765. package/dist/prompt-assembly/catalog/locales/zh-Hans/core-behavior.d.ts +6 -0
  766. package/dist/prompt-assembly/catalog/locales/zh-Hans/core-behavior.js +120 -0
  767. package/dist/prompt-assembly/catalog/locales/zh-Hans/cowork.d.ts +8 -0
  768. package/dist/prompt-assembly/catalog/locales/zh-Hans/cowork.js +442 -0
  769. package/dist/prompt-assembly/catalog/locales/zh-Hans/engine.d.ts +7 -0
  770. package/dist/prompt-assembly/catalog/locales/zh-Hans/engine.js +15 -0
  771. package/dist/prompt-assembly/catalog/locales/zh-Hans/environment.d.ts +7 -0
  772. package/dist/prompt-assembly/catalog/locales/zh-Hans/environment.js +50 -0
  773. package/dist/prompt-assembly/catalog/locales/zh-Hans/modes.d.ts +7 -0
  774. package/dist/prompt-assembly/catalog/locales/zh-Hans/modes.js +163 -0
  775. package/dist/prompt-assembly/catalog/locales/zh-Hans/role.d.ts +7 -0
  776. package/dist/prompt-assembly/catalog/locales/zh-Hans/role.js +148 -0
  777. package/dist/prompt-assembly/catalog/locales/zh-Hans/team.d.ts +6 -0
  778. package/dist/prompt-assembly/catalog/locales/zh-Hans/team.js +246 -0
  779. package/dist/prompt-assembly/catalog/role.js +3 -6
  780. package/dist/prompt-assembly/catalog/schema.d.ts +23 -1
  781. package/dist/prompt-assembly/catalog/schema.js +2 -0
  782. package/dist/prompt-assembly/composer.d.ts +6 -11
  783. package/dist/prompt-assembly/composer.js +7 -7
  784. package/dist/prompt-assembly/engine-text.d.ts +9 -0
  785. package/dist/prompt-assembly/engine-text.js +33 -0
  786. package/dist/prompt-assembly/event-registry.js +3 -3
  787. package/dist/prompt-assembly/explain.d.ts +1 -0
  788. package/dist/prompt-assembly/explain.js +1 -1
  789. package/dist/prompt-assembly/locale-review.d.ts +13 -0
  790. package/dist/prompt-assembly/locale-review.js +19 -0
  791. package/dist/prompt-assembly/overlay.d.ts +7 -3
  792. package/dist/prompt-assembly/overlay.js +27 -5
  793. package/dist/prompt-assembly/renderers.d.ts +4 -4
  794. package/dist/prompt-assembly/renderers.js +26 -17
  795. package/dist/prompt-assembly/role-base.d.ts +1 -1
  796. package/dist/prompt-assembly/select.d.ts +26 -5
  797. package/dist/prompt-assembly/select.js +25 -2
  798. package/dist/prompt-assembly/slots.d.ts +19 -0
  799. package/dist/prompt-assembly/slots.js +16 -0
  800. package/dist/prompt-assembly/sugar.d.ts +4 -7
  801. package/dist/prompt-assembly/sugar.js +1 -2
  802. package/dist/prompt-assembly/tool-catalog.d.ts +5 -1
  803. package/dist/prompt-assembly/tool-catalog.js +5 -1
  804. package/dist/prompt-assembly/turn-snapshot.d.ts +38 -10
  805. package/dist/prompt-assembly/turn-snapshot.js +43 -13
  806. package/dist/prompt-assembly/types.d.ts +3 -0
  807. package/dist/prompts/cowork.d.ts +6 -25
  808. package/dist/prompts/cowork.js +10 -12
  809. package/dist/prompts/default.d.ts +10 -32
  810. package/dist/prompts/default.js +37 -63
  811. package/dist/shell/lex.d.ts +39 -13
  812. package/dist/shell/lex.js +70 -30
  813. package/dist/stores/file/background-agent-store.d.ts +5 -0
  814. package/dist/stores/file/background-agent-store.js +35 -61
  815. package/dist/stores/file/checkpoint-store.d.ts +5 -3
  816. package/dist/stores/file/checkpoint-store.js +8 -10
  817. package/dist/stores/file/fs-atomic.d.ts +27 -70
  818. package/dist/stores/file/fs-atomic.js +52 -148
  819. package/dist/stores/file/index.d.ts +12 -0
  820. package/dist/stores/file/index.js +27 -2
  821. package/dist/stores/file/mailbox-store.d.ts +10 -1
  822. package/dist/stores/file/mailbox-store.js +40 -12
  823. package/dist/stores/file/permission-rule-adopt.js +5 -2
  824. package/dist/stores/file/permission-rule-store.d.ts +81 -20
  825. package/dist/stores/file/permission-rule-store.js +126 -33
  826. package/dist/stores/file/session-policy-store.d.ts +2 -2
  827. package/dist/stores/file/session-store.d.ts +21 -2
  828. package/dist/stores/file/session-store.js +27 -14
  829. package/dist/stores/file/task-list-store.js +23 -25
  830. package/dist/stores/file/tool-result-store.d.ts +45 -7
  831. package/dist/stores/file/tool-result-store.js +99 -36
  832. package/dist/stores/file/workflow-run-store.d.ts +1 -0
  833. package/dist/stores/file/workflow-run-store.js +14 -11
  834. package/dist/tools/artifact/artifact-tool.js +2 -0
  835. package/dist/tools/artifact/local-stub.js +6 -6
  836. package/dist/tools/fs/bash-program-position.d.ts +1 -2
  837. package/dist/tools/fs/bash-readonly-classifier.d.ts +35 -0
  838. package/dist/tools/fs/bash-readonly-classifier.js +50 -12
  839. package/dist/tools/fs/env-error-detail.d.ts +1 -0
  840. package/dist/tools/fs/env-error-detail.js +7 -0
  841. package/dist/tools/fs/fs-bash.d.ts +24 -6
  842. package/dist/tools/fs/fs-bash.js +73 -25
  843. package/dist/tools/fs/fs-pdf.js +6 -4
  844. package/dist/tools/fs/fs-read.d.ts +76 -31
  845. package/dist/tools/fs/fs-read.js +159 -79
  846. package/dist/tools/fs/fs-search-tools.d.ts +1 -1
  847. package/dist/tools/fs/fs-search-tools.js +3 -1
  848. package/dist/tools/fs/fs-shared.d.ts +59 -63
  849. package/dist/tools/fs/fs-shared.js +31 -18
  850. package/dist/tools/fs/fs-write.d.ts +13 -0
  851. package/dist/tools/fs/fs-write.js +69 -13
  852. package/dist/tools/fs/index.d.ts +19 -1
  853. package/dist/tools/fs/index.js +10 -2
  854. package/dist/tools/fs/pdf.js +10 -9
  855. package/dist/tools/fs/read-deny.js +4 -10
  856. package/dist/tools/fs/read-floor.d.ts +5 -4
  857. package/dist/tools/fs/removal-targets.d.ts +11 -5
  858. package/dist/tools/fs/removal-targets.js +62 -32
  859. package/dist/tools/fs/safety.d.ts +26 -19
  860. package/dist/tools/fs/safety.js +13 -8
  861. package/dist/tools/fs/search.d.ts +1 -1
  862. package/dist/tools/fs/shell-read-argv.js +1 -0
  863. package/dist/tools/fs/shell-read-bindings.d.ts +128 -26
  864. package/dist/tools/fs/shell-read-bindings.js +667 -139
  865. package/dist/tools/fs/shell-read-check.js +1 -1
  866. package/dist/tools/fs/shell-read-judge.d.ts +4 -1
  867. package/dist/tools/fs/shell-read-judge.js +5 -1
  868. package/dist/tools/fs/shell-read-plan.d.ts +4 -0
  869. package/dist/tools/fs/shell-read-plan.js +21 -19
  870. package/dist/tools/fs/shell-read-sourced.d.ts +4 -3
  871. package/dist/tools/fs/shell-read-sourced.js +18 -1
  872. package/dist/tools/fs/shell-read-start.d.ts +6 -6
  873. package/dist/tools/fs/shell-read-start.js +1 -6
  874. package/dist/tools/fs/shell-read-word.d.ts +4 -2
  875. package/dist/tools/fs/shell-read-word.js +7 -6
  876. package/dist/tools/fs/shell-read-workdir.d.ts +1 -1
  877. package/dist/tools/fs/shell-reentry-text.d.ts +24 -9
  878. package/dist/tools/fs/shell-reentry-text.js +50 -20
  879. package/dist/tools/monitor.d.ts +4 -0
  880. package/dist/tools/monitor.js +14 -4
  881. package/dist/tools/scheduler-tools.d.ts +5 -2
  882. package/dist/tools/scheduler-tools.js +8 -6
  883. package/dist/tools/task-list.d.ts +49 -20
  884. package/dist/tools/task-list.js +115 -35
  885. package/dist/tools/web.d.ts +13 -3
  886. package/dist/tools/web.js +17 -6
  887. package/dist/tools/worktree.d.ts +3 -2
  888. package/dist/tools/worktree.js +24 -25
  889. package/package.json +10 -3
  890. package/test/export-surface.snapshot.json +330 -32
  891. package/wire-changes/core-stores-sql@7.66.1.json +30 -0
  892. package/wire-changes/core-stores-sql@7.67.0.json +39 -0
  893. package/wire-changes/core@7.66.1.json +46 -0
  894. package/wire-changes/core@7.67.0.json +12578 -0
  895. package/wire-changes/mods-kernel@7.66.1.json +30 -0
  896. package/wire-changes/mods-kernel@7.67.0.json +167 -0
  897. package/wire-changes/primitives@7.66.1.json +30 -0
  898. package/wire-changes/primitives@7.67.0.json +325 -0
  899. package/wire-changes/wiki-gate@7.67.0.json +1636 -0
  900. package/dist/brain/degrading.d.ts +0 -93
  901. package/dist/brain/degrading.js +0 -189
  902. package/dist/core/tool-conformance.d.ts +0 -20
  903. package/dist/core/tool-conformance.js +0 -37
@@ -310,7 +310,7 @@ function shownEntries(entries, render) {
310
310
  const rest = entries.length > ADVISORY_ENTRIES_SHOWN ? ` and ${entries.length - ADVISORY_ENTRIES_SHOWN} more` : "";
311
311
  return `${entries.slice(0, ADVISORY_ENTRIES_SHOWN).map(render).join(", ")}${rest}`;
312
312
  }
313
- const REWRITE_THROUGH = `through this engine (an operator write of a new value without the stored row's rev; the write stamps grammar ${SESSION_RULES_GRAMMAR})`;
313
+ const REWRITE_THROUGH = `through this engine (an operator write of a new value without the stored row's rev, declaring grammar ${SESSION_RULES_GRAMMAR}; the write stamps it)`;
314
314
  export function earlierGrammarAdvisory(sessionId, entries, field, grammar) {
315
315
  const read = earlierGrammarReadings(entries, field, grammar);
316
316
  const noRule = read.filter((r) => r.reader === "no_rule").map((r) => r.entry);
@@ -430,7 +430,7 @@ function assertEntriesRead(rules, mountedToolNames) {
430
430
  : ` These rules are written in grammar ${rules.grammar} (a stored row from before the grammar stamp), in which this entry names no tool.` +
431
431
  (readsAsWildcard(entry)
432
432
  ? ` It is no allow rule in grammar ${SESSION_RULES_GRAMMAR} either (a write holding it is refused) — leave the entry out.`
433
- : ` To make it an allow rule, write the rules afresh — a value without the stored row's rev; the write stamps grammar ${SESSION_RULES_GRAMMAR} — or leave the entry out.`)
433
+ : ` To make it an allow rule, write the rules afresh — a value without the stored row's rev, declaring grammar ${SESSION_RULES_GRAMMAR}; the write stamps it — or leave the entry out.`)
434
434
  : why.verdict === "retired" || why.reason === "near_miss"
435
435
  ? ` If this deployment mounts its own tool under ${renderListEntry(entry)}, declare it in the store's mountedToolNames.`
436
436
  : why.currentName === undefined
@@ -447,10 +447,19 @@ function assertEntriesRead(rules, mountedToolNames) {
447
447
  }
448
448
  }
449
449
  }
450
+ function refuseUndeclaredGrammar(rules) {
451
+ if (typeof rules !== "object" || rules === null || Array.isArray(rules))
452
+ return;
453
+ if (rules.grammar !== undefined)
454
+ return;
455
+ throw new SessionPolicyError("grammar_required", `session rules carry no grammar stamp — a write declares the rule grammar its entries are written in (grammar: ${SESSION_RULES_GRAMMAR} is the grammar this engine reads; ` +
456
+ `a stored row handed back keeps its own stamp, and one stored before the stamp was written in grammar 0); nothing was written`);
457
+ }
450
458
  export function judgeSessionRulesWrite(prior, rules, opts, mountedToolNames = NO_DECLARED_TOOLS) {
451
459
  if (opts?.expectedRev !== undefined && (prior?.rev ?? 0) !== opts.expectedRev) {
452
460
  throw new SessionPolicyError("conflict", `session rules rev mismatch (expected ${opts.expectedRev}, have ${prior?.rev ?? 0})`);
453
461
  }
462
+ refuseUndeclaredGrammar(rules);
454
463
  const read = shapeOrRefuse(rules);
455
464
  const clean = canonicalRules(read);
456
465
  assertEntriesRead(read, mountedToolNames);
@@ -149,6 +149,9 @@ export declare class TtlSessionStore implements SessionStore {
149
149
  readonly delete?: (sessionId: string, guard: {
150
150
  owner: string | null;
151
151
  }) => Promise<boolean>;
152
+ /** The operator's removal of a row whose head cannot be read ({@link SessionStore.deleteUnreadable}): present only when the repo has a
153
+ * head read and its own unreadable-row removal ({@link SessionRepo.deleteUnreadable}), which re-reads the head in the step that removes. */
154
+ readonly deleteUnreadable?: (sessionId: string) => Promise<boolean>;
152
155
  /** Whether the repo judges the expectation of the writes this store hands it (`SessionRepo.delete` / `importEntries` with `expect`):
153
156
  * a repo with a head read and the row read ({@link SessionRepo.readRow}). Over any other repo a deletion is of the id it judged. */
154
157
  private readonly judgesRows;
@@ -249,8 +252,8 @@ export declare class TtlSessionStore implements SessionStore {
249
252
  }): Promise<string | null>;
250
253
  /** Drop a session from the live set. With a durable repo (`evict: "forget"`) the history is kept. A release that rejects leaves the
251
254
  * session where it was: the store keeps no view of it and retries nothing on its own, and a placed row is found again by the
252
- * partition-GC leg's `listPlaced` — except one whose header is damaged, which `listPlaced` skips and every release of it rejects
253
- * (`corrupt_session`), so only manual cleanup removes it. */
255
+ * partition-GC leg's `listPlaced`. A row whose header cannot be read is no release's: every release of it rejects
256
+ * (`corrupt_session`); it is removed by the operator's {@link deleteUnreadable}. */
254
257
  release(sessionId: string): Promise<void>;
255
258
  /** Run a release that may delete the row while it holds the id: the gate is set before the first await, after any release already in
256
259
  * flight for the id, and `acquire` / `register` answer after it settles — no caller captures an authority the delete is about to tear
@@ -284,6 +287,17 @@ export declare class TtlSessionStore implements SessionStore {
284
287
  * missed expectation (`conflict`) deletes nothing and answers `false`. With no expectation (a repo that does not judge rows) the
285
288
  * deletion is of the id judged. */
286
289
  private deleteRow;
290
+ /** The one order of every deletion this store makes: the deletion hook first, awaited — a rejection removes nothing and the deletion
291
+ * rejects with it — then `remove`, which judges the row again in the repo's own step and answers whether it removed it. */
292
+ private removeAfterHook;
293
+ /**
294
+ * The operator's removal of an unreadable row ({@link SessionStore.deleteUnreadable}), holding the id as every deletion here does: the
295
+ * head read first — only a row it reads as unreadable goes on (a readable row or no row answers `false` and the hook does not run;
296
+ * another fault rejects with it) — then the hook, then the repo's removal, which reads the head again in the step that removes the row
297
+ * (a row repaired or replaced while the hook ran is not removed: `false`). The placement is not read. A removed row leaves no cached
298
+ * view, no pin and no tombstone of a failed placed deletion.
299
+ */
300
+ private deleteUnreadableRow;
287
301
  /**
288
302
  * The owner-guarded delete ({@link SessionStore.delete}), holding the id as a release does: the row's head decides — no row, or an
289
303
  * owner other than `guard.owner` (null-safe), deletes nothing — and a placed row is left to `release` (the joint reap). A deleted row
@@ -1,5 +1,5 @@
1
- import { InMemorySessionRepo, ParentChainGuard, SessionError, findUnansweredToolBatch, compareOccupants, ownerCell, sessionLogMarkOf, uuidv7, } from "../internal/harness.js";
2
- import { isSessionConflict, readSessionListQuery } from "./session.js";
1
+ import { InMemorySessionRepo, ParentChainGuard, SessionError, findUnansweredToolBatch, compareOccupants, ownerCell, readSessionRepoRowCells, sessionLogMarkOf, uuidv7, } from "../internal/harness.js";
2
+ import { isSessionConflict, readSessionListQuery, readUnreadableDeleteId, rowUnreadableAt } from "./session.js";
3
3
  import { readRetentionDeclaration } from "./retention.js";
4
4
  import { readMember, thrownText } from "./thrown-value.js";
5
5
  import { principalNameFault, principalNameOf } from "./principal-name.js";
@@ -40,6 +40,7 @@ export class TtlSessionStore {
40
40
  repoHead;
41
41
  logTransfer;
42
42
  delete;
43
+ deleteUnreadable;
43
44
  judgesRows = false;
44
45
  beforeRowDelete;
45
46
  repo;
@@ -57,6 +58,9 @@ export class TtlSessionStore {
57
58
  this.retention = readRetentionDeclaration("TtlSessionStoreOptions.retention", opts.retention);
58
59
  const givenRepo = opts.repo;
59
60
  this.repo = givenRepo ?? new InMemorySessionRepo();
61
+ if (readSessionRepoRowCells("TtlSessionStoreOptions.repo", this.repo.rowCells) === "host") {
62
+ throw receiptRefusal(`TtlSessionStoreOptions.repo holds no occupant cells (rowCells "host") and this layer has no occupant source — a repo whose host holds the occupant is served by the host's own session store, which puts the occupant on the metadata its sessions answer and on its head read`);
63
+ }
60
64
  const durability = opts.durability !== undefined ? durabilityWord("TtlSessionStoreOptions.durability", opts.durability) : givenRepo === undefined ? "process-local" : undefined;
61
65
  if (durability !== undefined)
62
66
  this.durability = durability;
@@ -73,7 +77,11 @@ export class TtlSessionStore {
73
77
  const repoHead = (sessionId) => repoHeadOf.call(this.repo, sessionId);
74
78
  this.repoHead = repoHead;
75
79
  this.headOf = repoHead;
76
- const { readRow, importEntries } = this.repo;
80
+ const { readRow, importEntries, deleteUnreadable } = this.repo;
81
+ if (typeof deleteUnreadable === "function") {
82
+ const repoRemoval = (sessionId) => deleteUnreadable.call(this.repo, sessionId);
83
+ this.deleteUnreadable = (sessionId) => this.deleteUnreadableRow(sessionId, repoHead, repoRemoval);
84
+ }
77
85
  if (typeof readRow === "function") {
78
86
  this.judgesRows = true;
79
87
  this.delete = (sessionId, guard) => this.deleteOwned(sessionId, guard);
@@ -363,22 +371,40 @@ export class TtlSessionStore {
363
371
  return undefined;
364
372
  return async () => ({ row: standing, log: sessionLogMarkOf(await view.session.getStorage().getEntries()) });
365
373
  }
366
- async deleteRow(meta, expect) {
367
- if (this.beforeRowDelete !== undefined)
368
- await this.beforeRowDelete(meta.id);
369
- if (expect === undefined) {
370
- await this.repo.delete(meta);
374
+ deleteRow(meta, expect) {
375
+ return this.removeAfterHook(meta.id, async () => {
376
+ if (expect === undefined) {
377
+ await this.repo.delete(meta);
378
+ return true;
379
+ }
380
+ try {
381
+ await this.repo.delete(meta, await expect());
382
+ }
383
+ catch (err) {
384
+ if (isSessionConflict(err))
385
+ return false;
386
+ throw err;
387
+ }
371
388
  return true;
372
- }
373
- try {
374
- await this.repo.delete(meta, await expect());
375
- }
376
- catch (err) {
377
- if (isSessionConflict(err))
389
+ });
390
+ }
391
+ async removeAfterHook(sessionId, remove) {
392
+ if (this.beforeRowDelete !== undefined)
393
+ await this.beforeRowDelete(sessionId);
394
+ return remove();
395
+ }
396
+ async deleteUnreadableRow(sessionId, readHead, removal) {
397
+ const id = readUnreadableDeleteId("SessionStore.deleteUnreadable", sessionId);
398
+ return this.holdingId(id, async () => {
399
+ this.entries.delete(id);
400
+ if (!(await rowUnreadableAt(() => readHead(id))))
378
401
  return false;
379
- throw err;
380
- }
381
- return true;
402
+ if (!(await this.removeAfterHook(id, () => removal(id))))
403
+ return false;
404
+ this.pinned.delete(id);
405
+ this.pendingPlacedDeletes.delete(id);
406
+ return true;
407
+ });
382
408
  }
383
409
  async deleteOwned(sessionId, guard) {
384
410
  const want = readDeleteGuard(guard);
@@ -2,7 +2,7 @@ export { StoredSession } from "../internal/harness.js";
2
2
  export type { Session } from "../internal/harness.js";
3
3
  export { InMemorySessionRepo, InMemorySessionStorage, uuidv7, validateEntriesForImport, StreamingImportValidator, } from "../internal/harness.js";
4
4
  export { BaseSessionStorage, leafIdAfterEntry, } from "../internal/harness.js";
5
- export type { SessionStorage, SessionRepo, SessionRow, SessionMetadata, SessionTreeEntry, } from "../internal/harness.js";
5
+ export type { SessionStorage, SessionRepo, SessionRepoRowCells, SessionRow, SessionMetadata, SessionTreeEntry, } from "../internal/harness.js";
6
6
  export { SessionError } from "../internal/harness.js";
7
7
  export type { SessionWriteOptions } from "../internal/harness.js";
8
8
  import type { Session } from "../internal/harness.js";
@@ -14,6 +14,19 @@ export type { SessionHead, SessionLogMark, SessionRowExpectation, SessionRowRead
14
14
  * never a raise inside the classify-and-rethrow guard. The class test is KEPT: widening the verdict to
15
15
  * any value carrying the word would arm the CAS retry loop on a foreign error (KL-942b). */
16
16
  export declare function isSessionConflict(err: unknown): boolean;
17
+ /** True when `err` is a by-id head read's refusal of a row it cannot read (`corrupt_session`): the row stands, and no owner,
18
+ * occupant or placement can be named from it. That refusal is the only reading of "unreadable" — a head never carries a third owner
19
+ * value — and a `storage` fault (an I/O error) is never unreadable: it does not say whether the row stands. Same form as
20
+ * {@link isSessionConflict} (the class test, then one guarded read of `code`), and like it, it reads what a host's store threw. */
21
+ export declare function isRowUnreadable(err: unknown): boolean;
22
+ /** Is the row unreadable now, by ONE synchronous head read: refused {@link isRowUnreadable} ⇒ `true`; a head or no row ⇒ `false`; any
23
+ * other fault rethrown. What a repo's unreadable-row removal decides by, in the step that removes the row. */
24
+ export declare function rowUnreadableNow(readHead: () => unknown): boolean;
25
+ /** {@link rowUnreadableNow} over an awaited head read — what a store's operator entry reads before it runs the deletion hook. */
26
+ export declare function rowUnreadableAt(readHead: () => Promise<unknown>): Promise<boolean>;
27
+ /** The operator deletion entries' one reading of the id they are handed: a session id is a non-empty string, and anything else is refused
28
+ * (`config.invalid_argument`) before any row is read — a number or an empty string never names a row by coercion. */
29
+ export declare function readUnreadableDeleteId(face: string, sessionId: unknown): string;
17
30
  /**
18
31
  * Subagent transcript persistence — the ACQUIRE-form placement declaration a trusted spawner passes
19
32
  * when it creates a subagent's transcript session: the session is created INTO the store's subagent
@@ -357,7 +370,7 @@ export interface SessionStore<S extends SessionStoreSummary = SessionStoreSummar
357
370
  * whose row EXISTS it does nothing, whatever it carries — an owned row, an anonymous row, a row `acquire` created (which
358
371
  * records `null`), or a placed row (the owner its placing write recorded) stays as it is: a row's owner is recorded by the write that
359
372
  * creates it and `register` never changes it; there is no claiming of an existing row. A FIRST write whose `owner` is neither a principal
360
- * name (a string with a visible character, no control or separator character, and no format character but a joiner) nor `null` is refused loudly and leaves no row; a later call stays a silent no-op
373
+ * name (a string with a visible character, no control or separator character, no format character but a joiner, and at most 256 characters) nor `null` is refused loudly and leaves no row; a later call stays a silent no-op
361
374
  * whatever it carries. Deliberately makes NO
362
375
  * authorization decision — the caller re-reads {@link headOf} and judges there. The owner lives and dies with its row.
363
376
  */
@@ -377,7 +390,10 @@ export interface SessionStore<S extends SessionStoreSummary = SessionStoreSummar
377
390
  */
378
391
  readonly logTransfer?: SessionLogTransfer;
379
392
  /**
380
- * Delete a session at its owner's request — the row and its whole log. Only when the row's owner equals `guard.owner` (null-safe:
393
+ * Delete ONE session row and its log — the row primitive, and the last leg of the session-deletion cascade
394
+ * ({@link import("./retention.js").RETENTION_CASCADE}). It reads no reference and touches no other store: the session's checkpoints,
395
+ * offloaded tool results, session rules, file history and the rest outlive it until the cascade's executor removes them, so a host that
396
+ * offers "delete a session" runs the cascade, not this call alone. Only when the row's owner equals `guard.owner` (null-safe:
381
397
  * `null` deletes only an anonymous row); a placed row is not deleted here (its deletion is `release`'s, through the joint reap). `true`
382
398
  * = this call deleted the row; `false` = there was no row, the guard did not hold, or the row is placed — nothing was deleted, so a
383
399
  * repeat is harmless. The id answers nothing afterwards, and a later create under it is a new occupant. A store wired with
@@ -387,6 +403,18 @@ export interface SessionStore<S extends SessionStoreSummary = SessionStoreSummar
387
403
  delete?(sessionId: string, guard: {
388
404
  owner: string | null;
389
405
  }): Promise<boolean>;
406
+ /**
407
+ * Delete a session whose head cannot be read — a deployment operator's act, never an owner's request: a row that cannot be read names
408
+ * no owner, so no owner-guarded door (`delete`, `release`, an import) ever takes it. The row's head is read again in the step that
409
+ * removes it: a read refused {@link isRowUnreadable} ⇒ the row and its whole log are deleted, `true`; a readable row (owned or
410
+ * anonymous) or no row ⇒ nothing deleted, `false`; any other fault of that read (a `storage` fault, an errno) rejects with it and
411
+ * deletes nothing. The row's placement is not read: a placed row is deleted alike, and a child still writing into it has its next
412
+ * write refused `log_closed` — the deletion does not wait for children. A store wired with {@link SessionStoreHooks.beforeSessionDelete}
413
+ * runs it first, only for a row it read as unreadable, and deletes nothing when it rejects (the call rejects with it). An id that is not
414
+ * a non-empty string is refused (`config.invalid_argument`) before anything is read. Nothing automatic calls it (idle sweep, release,
415
+ * retention). **Optional**: absent = this store cannot remove an unreadable row (its repo cannot, or its rows cannot be unreadable).
416
+ */
417
+ deleteUnreadable?(sessionId: string): Promise<boolean>;
390
418
  /** Number of live/cached sessions (best-effort). */
391
419
  readonly size: number;
392
420
  /** Release resources (timers, connections). Best-effort; must not throw. */
@@ -5,10 +5,41 @@ export { SessionError } from "../internal/harness.js";
5
5
  import { SessionError } from "../internal/harness.js";
6
6
  import { readMember, thrownIs } from "./thrown-value.js";
7
7
  import { receiptRefusal, receiveOwnProperties } from "./own-property-receipt.js";
8
- import { principalNameFault, principalNameOf } from "./principal-name.js";
8
+ import { PRINCIPAL_NAME_SPELLING, principalNameFault, principalNameOf } from "./principal-name.js";
9
9
  export function isSessionConflict(err) {
10
10
  return thrownIs(err, SessionError) && readMember(err, "code") === "conflict";
11
11
  }
12
+ export function isRowUnreadable(err) {
13
+ return thrownIs(err, SessionError) && readMember(err, "code") === "corrupt_session";
14
+ }
15
+ function unreadableOrRethrow(err) {
16
+ if (isRowUnreadable(err))
17
+ return true;
18
+ throw err;
19
+ }
20
+ export function rowUnreadableNow(readHead) {
21
+ try {
22
+ readHead();
23
+ }
24
+ catch (err) {
25
+ return unreadableOrRethrow(err);
26
+ }
27
+ return false;
28
+ }
29
+ export async function rowUnreadableAt(readHead) {
30
+ try {
31
+ await readHead();
32
+ }
33
+ catch (err) {
34
+ return unreadableOrRethrow(err);
35
+ }
36
+ return false;
37
+ }
38
+ export function readUnreadableDeleteId(face, sessionId) {
39
+ if (typeof sessionId !== "string" || sessionId === "")
40
+ throw receiptRefusal(`${face}: the session id must be a non-empty string, got ${sessionId === "" ? "an empty string" : typeof sessionId}`);
41
+ return sessionId;
42
+ }
12
43
  export const SESSION_LIST_LIMITS = Object.freeze({ default: 50, max: 1000 });
13
44
  const LIST_QUERY_MEMBERS = ["owner", "includeUnowned", "after", "limit"];
14
45
  export function readSessionListQuery(raw, extensions = []) {
@@ -28,7 +59,7 @@ export function readSessionListQuery(raw, extensions = []) {
28
59
  const { owner: ownerGiven, includeUnowned, after, limit } = got;
29
60
  const owner = ownerGiven === undefined ? undefined : principalNameOf(ownerGiven);
30
61
  if (ownerGiven !== undefined && owner === undefined) {
31
- throw receiptRefusal(`SessionListQuery.owner must be a principal name (a string with a visible character, no control or separator character, and no format character but a joiner) when present, got ${principalNameFault(ownerGiven)}`);
62
+ throw receiptRefusal(`SessionListQuery.owner must be a principal name (${PRINCIPAL_NAME_SPELLING}) when present, got ${principalNameFault(ownerGiven)}`);
32
63
  }
33
64
  if (includeUnowned !== undefined && typeof includeUnowned !== "boolean")
34
65
  throw receiptRefusal(`SessionListQuery.includeUnowned must be a boolean when present, got ${typeof includeUnowned}`);
@@ -3,10 +3,12 @@
3
3
  * even be read?" — for the deny/ask direction of the permission-rule lane (`permission-rule-model.ts`
4
4
  * `programRunReachOf`) and the read-only allow member (`read-only-shell.ts`). It reads the ONE shell lexer's result
5
5
  * (`shell/lex.ts`) and adds only this reader's own domain: which pieces of a line are run candidates, the leading
6
- * keyword of a control structure, and the additive peel. A segment that carries a command/process substitution
7
- * anywhere (an argument, a redirection operand, an unquoted heredoc body) is one whose program runs are not fully
8
- * known — the reader answers `unreadable` for every rule such a segment does not otherwise reach, never silence; the
9
- * leading assignments and the wrapper programs of {@link SHELL_WRAPPER_TABLE} are peeled ADDITIVELY — a segment keeps
6
+ * keyword of a control structure, and the additive peel. The command line a command/process substitution runs — in an
7
+ * argument, a redirection operand, an unquoted heredoc body, an arithmetic text — is read by this same reader and carried
8
+ * on the segment ({@link ShellSegment.substituted}), down to {@link MAX_SUBSTITUTION_DEPTH} levels; a segment that may run
9
+ * a program no carried line shows (a substitution inside a parameter's operand, a name the arithmetic evaluator reads,
10
+ * a substitution past the depth) is one whose program runs are not fully known — the reader answers `unreadable` for
11
+ * every rule such a segment does not otherwise reach, never silence; the leading assignments and the wrapper programs of {@link SHELL_WRAPPER_TABLE} are peeled ADDITIVELY — a segment keeps
10
12
  * its spelled argv as one run candidate and gains one per peeled layer, so `sudo env X=1 nohup rm -r x` is a run of
11
13
  * `sudo …`, of `env …`, of `nohup …` and of `rm -r x`, and a deny on any of them reaches.
12
14
  *
@@ -55,10 +57,16 @@ export interface ShellSegment {
55
57
  readonly unreadable?: string;
56
58
  /** Present when the segment's program runs are NOT fully known although its candidates could be read:
57
59
  * a peel that stopped before the wrapped program could be named (its options carry an expansion, a
58
- * command string, an option of unknown arity), or a command/process substitution anywhere in the
59
- * segment (it runs a program the reader does not read). The candidates stand — a rule they reach is
60
- * reached — and every other rule reads `unreadable`. */
60
+ * command string, an option of unknown arity), or a run the segment may perform that no line in
61
+ * {@link substituted} shows (a substitution in a parameter's operand, a name the arithmetic evaluator
62
+ * reads, a substitution nested past {@link MAX_SUBSTITUTION_DEPTH}). The candidates stand — a rule they
63
+ * reach is reached — and every other rule reads `unreadable`. */
61
64
  readonly peelUnreadable?: string;
65
+ /** The command lines the segment's command and process substitutions run, each read by this same reader
66
+ * (`echo "$(rm -r x)"` carries the line `rm -r x`): a rule reaches the segment when it reaches a run of
67
+ * one of them. Present only when the segment carries at least one; a segment may then spell no run of its
68
+ * own (`[ -n "$(…)" ]`, `> "$(…)"`, a here-document body on an empty piece). */
69
+ readonly substituted?: readonly ShellCommandShape[];
62
70
  }
63
71
  /** A command line as the tightening reader sees it. */
64
72
  export interface ShellCommandShape {
@@ -82,8 +90,12 @@ export { SHELL_WRAPPER_TABLE, type ShellWrapperName } from "./shell-wrapper-tabl
82
90
  * same size. */
83
91
  export declare const MAX_SHELL_READ_CHARS = 10000;
84
92
  export declare function lexedWordOf(w: ShellWord): LexedWord | undefined;
93
+ /** Nesting levels of command substitution the reader reads (the outermost line is level 0); a substitution nested deeper
94
+ * is a run this reader does not read. Upstream's own reader stops at the same depth. */
95
+ export declare const MAX_SUBSTITUTION_DEPTH = 16;
85
96
  /** Read `source` as the tightening reader must: every program run the text could perform, or why it cannot be read. */
86
97
  export declare function readShellCommand(source: string): ShellCommandShape;
87
98
  /** Every program run of `shape` can be NAMED from the text: no segment is unreadable, no peel stopped,
88
- * and every run candidate's program word is literal. The offer/mint side's "judgeable" question. */
99
+ * every run candidate's program word is literal, and so is every run of every line a segment's substitutions
100
+ * run ({@link ShellSegment.substituted}). The offer/mint side's "judgeable" question. */
89
101
  export declare function isFullyReadable(shape: ShellCommandShape): boolean;
@@ -1,4 +1,4 @@
1
- import { arithmeticTextIsPlain, heredocBodyHidesRun, lexShell, namesRedirectDescriptor, PARSE_FAILURE_SENTENCE, wordHidesRun, } from "../shell/lex.js";
1
+ import { arithmeticTextIsPlain, arithmeticTextRunsOf, heredocRunsOf, lexShell, namesRedirectDescriptor, PARSE_FAILURE_SENTENCE, wordRunsOf, } from "../shell/lex.js";
2
2
  import { shellWordsOf } from "../shell/shell-words.js";
3
3
  import { isLauncherAssignmentOperand } from "../tools/fs/bash-program-position.js";
4
4
  import { extglobOpenerIn } from "../tools/fs/bash-readonly-classifier.js";
@@ -50,10 +50,15 @@ function wordOf(w) {
50
50
  }
51
51
  const literalIn = (w, set) => w !== undefined && w.expands === false && set.has(w.text);
52
52
  const bareAssignment = (w) => lexedWordOf(w)?.assignment?.bare === true;
53
- const hidesRun = wordHidesRun;
53
+ const runsOf = wordRunsOf;
54
+ const emptyPiece = () => ({ words: [], redirections: [], lines: [] });
55
+ export const MAX_SUBSTITUTION_DEPTH = 16;
54
56
  const CASE_ARM_UNREAD = "a `case` arm terminator outside a `case` this lane reads";
55
57
  const EXTGLOB_UNREAD = "an extended pattern (`?(…)` `*(…)` `+(…)` `@(…)` `!(…)`) is one this reader does not expand";
56
58
  export function readShellCommand(source) {
59
+ return readShellCommandAt(source, 0);
60
+ }
61
+ function readShellCommandAt(source, depth) {
57
62
  if (source.length > MAX_SHELL_READ_CHARS)
58
63
  return { segments: [{ argv: [], redirections: [], peeled: [], unreadable: `the command is longer than ${MAX_SHELL_READ_CHARS} characters — not read` }], connectors: [], grouped: false, backgrounded: false, strayRedirection: false };
59
64
  const lexed = lexShell(source);
@@ -64,12 +69,12 @@ export function readShellCommand(source) {
64
69
  let grouped = false;
65
70
  let backgrounded = false;
66
71
  let strayRedirection = false;
67
- let seg = { words: [], redirections: [] };
72
+ let seg = emptyPiece();
68
73
  let afterBoundary = true;
69
74
  let lastConnector;
70
75
  let arithmetic;
71
76
  const finishSegment = (connector) => {
72
- let built = buildSegment(seg);
77
+ let built = buildSegment(seg, depth);
73
78
  if (built === "keyworded")
74
79
  grouped = true;
75
80
  if ((built === "empty" || built === "keyworded") && seg.redirections.length > 0)
@@ -84,7 +89,7 @@ export function readShellCommand(source) {
84
89
  grouped = true;
85
90
  if (connector !== undefined && !continuation)
86
91
  lastConnector = connector;
87
- seg = { words: [], redirections: [] };
92
+ seg = emptyPiece();
88
93
  afterBoundary = false;
89
94
  return;
90
95
  }
@@ -94,17 +99,18 @@ export function readShellCommand(source) {
94
99
  segments.push(built);
95
100
  if (connector !== undefined)
96
101
  lastConnector = connector;
97
- seg = { words: [], redirections: [] };
102
+ seg = emptyPiece();
98
103
  afterBoundary = false;
99
104
  };
100
105
  const boundary = () => { finishSegment(undefined); grouped = true; afterBoundary = true; lastConnector = undefined; };
101
- const word = (w) => { if (hidesRun(w))
102
- seg.substitution = true; return wordOf(w); };
106
+ const carry = (r) => { if (r.hidden)
107
+ seg.hiddenRun = true; seg.lines.push(...r.lines); };
108
+ const word = (w) => { carry(runsOf(w)); return wordOf(w); };
103
109
  const readTokens = (s) => {
104
110
  const tokens = s.tokens;
105
111
  const shown = tokens.flatMap((t) => (t.kind === "word" ? t.expansions : t.kind === "redirect" ? t.target?.expansions ?? [] : [])).filter((p) => p.expansion?.kind === "command" || p.expansion?.kind === "process" || p.expansion?.kind === "arithmetic").length;
106
112
  if (s.substitutions.length > shown)
107
- seg.substitution = true;
113
+ seg.hiddenRun = true;
108
114
  let definitionClose = false;
109
115
  tokens.forEach((t, i) => {
110
116
  if (arithmetic !== undefined) {
@@ -115,10 +121,14 @@ export function readShellCommand(source) {
115
121
  return;
116
122
  }
117
123
  const w = t.kind === "word" ? t : t.kind === "redirect" ? t.target : undefined;
118
- if (w === undefined || hidesRun(w) || !arithmeticTextIsPlain(w.raw) || t.kind === "heredoc")
119
- seg.substitution = true;
124
+ if (w !== undefined) {
125
+ carry(runsOf(w));
126
+ carry(arithmeticTextRunsOf(w.raw));
127
+ }
128
+ if (w === undefined || !arithmeticTextIsPlain(w.raw) || t.kind === "heredoc")
129
+ seg.hiddenRun = true;
120
130
  if (t.kind === "redirect" && t.dup !== undefined && !arithmeticTextIsPlain(t.dup))
121
- seg.substitution = true;
131
+ seg.hiddenRun = true;
122
132
  return;
123
133
  }
124
134
  if (t.kind === "word") {
@@ -133,8 +143,8 @@ export function readShellCommand(source) {
133
143
  }
134
144
  if (t.kind === "heredoc") {
135
145
  seg.redirections.push({ op: "<<", target: { text: t.delimiter, raw: t.delimiter, expands: false } });
136
- if (!t.quoted && heredocBodyHidesRun(t.body))
137
- seg.substitution = true;
146
+ if (!t.quoted)
147
+ carry(heredocRunsOf(t.body));
138
148
  return;
139
149
  }
140
150
  const next = tokens[i + 1];
@@ -166,7 +176,7 @@ export function readShellCommand(source) {
166
176
  const connector = s.pipesStderr === true ? "|&" : s.connector;
167
177
  if (arithmetic !== undefined) {
168
178
  if (connector === ";")
169
- seg.substitution = true;
179
+ seg.hiddenRun = true;
170
180
  }
171
181
  else {
172
182
  if (connector === "&")
@@ -203,13 +213,26 @@ function caseArmEnd(read, k) {
203
213
  const SUBSTITUTION_UNREAD = "a command substitution runs a program this reader does not read";
204
214
  const MAX_WRAPPER_LAYERS = 8;
205
215
  export function isFullyReadable(shape) {
206
- return shape.segments.every((s) => s.unreadable === undefined && s.peelUnreadable === undefined && [s.argv, ...s.peeled].every((argv) => argv[0]?.expands === false));
216
+ return shape.segments.every((s) => s.unreadable === undefined && s.peelUnreadable === undefined && (s.argv.length === 0 || [s.argv, ...s.peeled].every((argv) => argv[0]?.expands === false)) && (s.substituted ?? []).every(isFullyReadable));
207
217
  }
208
218
  const operandsOf = (run) => run.map((w) => ({ text: w.text, raw: w.raw, assignment: lexedWordOf(w)?.assignment }));
209
- function buildSegment(seg) {
219
+ function substitutedOf(seg, depth) {
220
+ if (seg.lines.length === 0)
221
+ return [];
222
+ if (depth + 1 > MAX_SUBSTITUTION_DEPTH)
223
+ return undefined;
224
+ return [...new Set(seg.lines)].map((line) => readShellCommandAt(line, depth + 1));
225
+ }
226
+ function buildSegment(seg, depth) {
210
227
  if (seg.unreadable !== undefined)
211
228
  return { argv: seg.words, redirections: seg.redirections, peeled: [], unreadable: seg.unreadable };
212
- const carried = () => (seg.substitution === true ? { argv: [], redirections: seg.redirections, peeled: [], peelUnreadable: SUBSTITUTION_UNREAD } : keyworded ? "keyworded" : "empty");
229
+ const read = substitutedOf(seg, depth);
230
+ if (read === undefined)
231
+ seg.hiddenRun = true;
232
+ const substituted = read !== undefined && read.length > 0 ? { substituted: read } : {};
233
+ const carried = () => seg.hiddenRun === true ? { argv: [], redirections: seg.redirections, peeled: [], peelUnreadable: SUBSTITUTION_UNREAD, ...substituted }
234
+ : "substituted" in substituted ? { argv: [], redirections: seg.redirections, peeled: [], ...substituted }
235
+ : keyworded ? "keyworded" : "empty";
213
236
  let keyworded = false;
214
237
  let k0 = 0;
215
238
  while (k0 < seg.words.length && (literalIn(seg.words[k0], PREFIX_KEYWORDS) || literalIn(seg.words[k0], CLOSING_KEYWORDS))) {
@@ -221,7 +244,7 @@ function buildSegment(seg) {
221
244
  if (head === undefined)
222
245
  return carried();
223
246
  if (evaluatesOperand(operandsOf(words)))
224
- seg.substitution = true;
247
+ seg.hiddenRun = true;
225
248
  if (head.expands === false && (head.text === "[[" || head.text === "["))
226
249
  return carried();
227
250
  if (literalIn(head, OPAQUE_KEYWORDS))
@@ -263,9 +286,9 @@ function buildSegment(seg) {
263
286
  run = next;
264
287
  peeled.push(run);
265
288
  }
266
- if (seg.substitution === true || [argv, ...peeled].some((c) => c[0]?.expands === false && evaluatesOperand(operandsOf(c))))
289
+ if (seg.hiddenRun === true || [argv, ...peeled].some((c) => c[0]?.expands === false && evaluatesOperand(operandsOf(c))))
267
290
  peelUnreadable ??= SUBSTITUTION_UNREAD;
268
- return { argv, redirections: seg.redirections, peeled, ...(peelUnreadable !== undefined ? { peelUnreadable } : {}) };
291
+ return { argv, redirections: seg.redirections, peeled, ...(peelUnreadable !== undefined ? { peelUnreadable } : {}), ...substituted };
269
292
  }
270
293
  function unwrap(words) {
271
294
  const head = words[0];
@@ -1,7 +1,7 @@
1
1
  import type { AssistantMessage, StopReason, Tool, ToolResultMessage, Usage, UserMessage } from "../internal/llm.js";
2
2
  import type { Brain, Model, ModelRef, ModelRole, ModelRoles, RunnerDeps, TaskSpec, ThinkingLevel } from "./types.js";
3
3
  import type { AccountRow } from "./account-row.js";
4
- import { type DegradationInfo } from "../brain/degrading.js";
4
+ import type { DegradationInfo } from "../brain/model-lane.js";
5
5
  import { type BrainErrorCode } from "../brain/errors.js";
6
6
  /** A tool DEFINITION exposed to the model in a side query (never executed by the engine). */
7
7
  export interface SideQueryToolDef {
@@ -80,6 +80,11 @@ export interface SideQuerySpec {
80
80
  */
81
81
  getApiKeyAndHeaders?: TaskSpec["getApiKeyAndHeaders"];
82
82
  signal?: AbortSignal;
83
+ /** The query's rendering of the catalog — {@link TaskSpec.promptLocale}'s one door and words: absent ⇒ the catalog's own
84
+ * text, `"zh-Hans"` ⇒ a role base a preset names renders in it and the request carries it (`Context.promptLocale`) for
85
+ * the adapter's own texts; any other value is refused (`config.prompt_selector_invalid`). The advisor hands the main
86
+ * lane's request's locale on as recorded. */
87
+ promptLocale?: TaskSpec["promptLocale"];
83
88
  }
84
89
  export interface SideQueryResult {
85
90
  /** Concatenated assistant text (may be empty when the reply is tool-calls-only). */
@@ -97,9 +102,10 @@ export interface SideQueryResult {
97
102
  /** The RESOLVED pool model id the query was ROUTED to (the caller's ref resolved). See
98
103
  * `servedModel` for the engine-selected id the reply came back stamped with. */
99
104
  model: string;
100
- /** The ENGINE-SELECTED id the reply came back stamped with (a degrading deployment may fall back
101
- * mid-query — attribution follows the entry that ran, not the routing intent); equals `model` when
102
- * nothing degraded. Still THIS catalog's id: what the PROVIDER called it is `responseModel` below. */
105
+ /** The ENGINE-SELECTED id the reply came back stamped with (the model lane may walk the requested
106
+ * entry's `fallbacks` chain mid-query — attribution follows the entry that answered, not the routing
107
+ * intent); equals `model` when nothing was walked. Still THIS catalog's id: what the PROVIDER called it
108
+ * is `responseModel` below. */
103
109
  servedModel: string;
104
110
  /** Structured degradation marker when a fallback model served (from/to/reason/chain). */
105
111
  degraded?: DegradationInfo;
@@ -111,7 +117,8 @@ export interface SideQueryResult {
111
117
  * applies (`usage-accounting.ts`). The openai-completions family reports `input` INCLUDING the
112
118
  * cached subset; hand that through raw and a consumer summing `input + cacheRead` double-counts
113
119
  * every cache hit. `cacheRead`/`cacheWrite`/`output`/`totalTokens`/`cost` are the provider's own
114
- * figures, untouched. `usageMissing` ⇒ the numbers are UNKNOWN shells, not zeros. */
120
+ * figures, untouched — a cache member the provider did not report is ABSENT (unknown, not 0; the OpenAI-shaped wires
121
+ * never report `cacheWrite`). `usageMissing` ⇒ the numbers are UNKNOWN shells, not zeros. */
115
122
  usage: Usage;
116
123
  usageMissing?: true;
117
124
  /** This query's line in the session's account: `origin: "side_query"`, priced by the engine from the deployment's price table
@@ -138,7 +145,12 @@ export interface SideQueryResult {
138
145
  }
139
146
  /** Dependencies the Runner passes through (a strict subset of RunnerDeps — no session/tool machinery). */
140
147
  export interface SideQueryDeps {
148
+ /** The Brain the query is asked on, through the model lane (a catalog entry's `fallbacks` chain is walked here as on every lane). */
141
149
  brain: Brain;
150
+ /** The fallback policy the lane walks on (`RunnerDeps.modelFallback`); absent ⇒ the default gate. */
151
+ modelFallback?: RunnerDeps["modelFallback"];
152
+ /** The retention word the lane writes on the query's call (`RunnerDeps.cacheRetention`); absent ⇒ the call's own (none). */
153
+ cacheRetention?: RunnerDeps["cacheRetention"];
142
154
  models?: Record<string, Model>;
143
155
  roles?: ModelRoles;
144
156
  /** The deployment's price table (`RunnerDeps.pricing`) the result's `account` line is priced from; absent ⇒ the model's own `cost`, else unpriced. */