@sema-agent/core 7.57.0 → 7.59.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 (399) hide show
  1. package/CHANGELOG.md +1161 -0
  2. package/README.md +6 -4
  3. package/dist/agents/cc-peer-directory.js +8 -8
  4. package/dist/agents/child-model-seat.d.ts +4 -2
  5. package/dist/agents/child-model-seat.js +5 -3
  6. package/dist/agents/peer-directory.d.ts +9 -0
  7. package/dist/agents/peer-directory.js +6 -2
  8. package/dist/agents/send-message-tool.js +21 -12
  9. package/dist/agents/subagent-steps.js +2 -4
  10. package/dist/agents/subagent.js +33 -34
  11. package/dist/brain/anthropic.js +161 -45
  12. package/dist/brain/errors.d.ts +9 -3
  13. package/dist/brain/errors.js +7 -1
  14. package/dist/brain/failover.js +2 -1
  15. package/dist/brain/open-responses.js +3 -3
  16. package/dist/brain/openai.js +103 -53
  17. package/dist/brain/provider-dialect.d.ts +11 -0
  18. package/dist/brain/provider-dialect.js +5 -2
  19. package/dist/brain/reasoning-request.js +5 -4
  20. package/dist/brain/reasoning.d.ts +19 -0
  21. package/dist/brain/reasoning.js +17 -2
  22. package/dist/brain/request-route.d.ts +4 -1
  23. package/dist/brain/request-route.js +4 -1
  24. package/dist/brain/route-adjudicator.d.ts +84 -18
  25. package/dist/brain/route-adjudicator.js +89 -22
  26. package/dist/brain/route-conformance.js +1 -1
  27. package/dist/brain/stream-engine.js +84 -49
  28. package/dist/brain/stream-shared.d.ts +30 -0
  29. package/dist/brain/stream-shared.js +34 -1
  30. package/dist/brain/timeout.d.ts +62 -5
  31. package/dist/brain/timeout.js +93 -6
  32. package/dist/core/a2a.d.ts +2 -1
  33. package/dist/core/a2a.js +23 -10
  34. package/dist/core/account-row.d.ts +61 -0
  35. package/dist/core/account-row.js +51 -0
  36. package/dist/core/advisor-verdict.d.ts +2 -1
  37. package/dist/core/advisor-verdict.js +1 -1
  38. package/dist/core/allow-entry.d.ts +20 -7
  39. package/dist/core/allow-entry.js +18 -9
  40. package/dist/core/approval-object.d.ts +29 -15
  41. package/dist/core/approval-object.js +47 -19
  42. package/dist/core/ask-origin.d.ts +21 -2
  43. package/dist/core/ask-origin.js +5 -1
  44. package/dist/core/auto-compaction.d.ts +4 -0
  45. package/dist/core/auto-compaction.js +2 -2
  46. package/dist/core/auto-mode-directive.d.ts +29 -5
  47. package/dist/core/auto-mode-directive.js +38 -8
  48. package/dist/core/background-agent-store.d.ts +16 -3
  49. package/dist/core/checkpoint-requirements.d.ts +19 -1
  50. package/dist/core/checkpoint-requirements.js +5 -1
  51. package/dist/core/checkpoint-store.d.ts +85 -23
  52. package/dist/core/checkpoint-store.js +31 -9
  53. package/dist/core/child-clamp-seats.d.ts +29 -0
  54. package/dist/core/child-clamp-seats.js +56 -1
  55. package/dist/core/compliance.d.ts +2 -2
  56. package/dist/core/compliance.js +1 -1
  57. package/dist/core/effective-path-target.d.ts +8 -2
  58. package/dist/core/effective-path-target.js +8 -3
  59. package/dist/core/engine-notice.d.ts +99 -9
  60. package/dist/core/engine-notice.js +19 -5
  61. package/dist/core/fs-write-gate-policy.d.ts +4 -2
  62. package/dist/core/fs-write-gate-policy.js +7 -3
  63. package/dist/core/gate-fold.js +7 -4
  64. package/dist/core/gate-lanes.js +19 -6
  65. package/dist/core/gate-outcome.d.ts +32 -3
  66. package/dist/core/gate-outcome.js +19 -1
  67. package/dist/core/git-worktree-env.d.ts +53 -11
  68. package/dist/core/git-worktree-env.js +96 -12
  69. package/dist/core/governance-codes.d.ts +9 -1
  70. package/dist/core/governance-codes.js +13 -0
  71. package/dist/core/hooks.d.ts +35 -4
  72. package/dist/core/hooks.js +17 -11
  73. package/dist/core/human-input-projection.d.ts +1 -0
  74. package/dist/core/human-input-projection.js +3 -0
  75. package/dist/core/image-admission.d.ts +6 -5
  76. package/dist/core/image-admission.js +18 -14
  77. package/dist/core/locked-config.d.ts +20 -3
  78. package/dist/core/locked-config.js +40 -3
  79. package/dist/core/mailbox-store.d.ts +45 -1
  80. package/dist/core/mailbox-store.js +53 -9
  81. package/dist/core/mcp-call-meta.d.ts +66 -0
  82. package/dist/core/mcp-call-meta.js +103 -0
  83. package/dist/core/mcp-connection-pool.d.ts +3 -1
  84. package/dist/core/mcp-connection-pool.js +3 -1
  85. package/dist/core/mcp-failure.d.ts +117 -15
  86. package/dist/core/mcp-failure.js +71 -3
  87. package/dist/core/mcp-probe.d.ts +4 -0
  88. package/dist/core/mcp-probe.js +1 -1
  89. package/dist/core/mcp-server-link.d.ts +27 -3
  90. package/dist/core/mcp-server-link.js +25 -1
  91. package/dist/core/mcp-server-spec.d.ts +46 -18
  92. package/dist/core/mcp-server-spec.js +1 -18
  93. package/dist/core/mcp.d.ts +16 -20
  94. package/dist/core/mcp.js +112 -55
  95. package/dist/core/memory-engine/consolidation-driver.d.ts +2 -4
  96. package/dist/core/memory-engine/consolidation-driver.js +3 -3
  97. package/dist/core/memory-engine/consolidation.d.ts +4 -0
  98. package/dist/core/memory-engine/consolidation.js +1 -0
  99. package/dist/core/memory-engine/delegation-settlement.js +5 -12
  100. package/dist/core/memory-engine/distiller.js +2 -2
  101. package/dist/core/memory-engine/dual-root.d.ts +50 -1
  102. package/dist/core/memory-engine/dual-root.js +44 -1
  103. package/dist/core/memory-engine/engine.d.ts +67 -14
  104. package/dist/core/memory-engine/engine.js +384 -212
  105. package/dist/core/memory-engine/export-bundle.d.ts +23 -0
  106. package/dist/core/memory-engine/export-bundle.js +23 -4
  107. package/dist/core/memory-engine/file-backend.d.ts +128 -55
  108. package/dist/core/memory-engine/file-backend.js +290 -117
  109. package/dist/core/memory-engine/index.d.ts +1 -1
  110. package/dist/core/memory-engine/layout.d.ts +59 -11
  111. package/dist/core/memory-engine/layout.js +190 -40
  112. package/dist/core/memory-engine/memory-backend-contract.d.ts +1 -1
  113. package/dist/core/memory-engine/memory-backend-contract.js +39 -2
  114. package/dist/core/memory-engine/scope-contract.d.ts +45 -4
  115. package/dist/core/memory-engine/scope-contract.js +80 -11
  116. package/dist/core/memory-engine/sync-client.d.ts +9 -1
  117. package/dist/core/memory-engine/sync-client.js +31 -8
  118. package/dist/core/memory-engine/sync.d.ts +5 -0
  119. package/dist/core/memory-engine/types.d.ts +6 -0
  120. package/dist/core/mode-policy.d.ts +8 -5
  121. package/dist/core/mode-policy.js +5 -4
  122. package/dist/core/mods/classic-events.d.ts +5 -1
  123. package/dist/core/mods/host.js +1 -1
  124. package/dist/core/mods/kernel/dispatch.d.ts +3 -0
  125. package/dist/core/mods/kernel/dispatch.js +12 -9
  126. package/dist/core/mods/kernel/events.d.ts +6 -1
  127. package/dist/core/mods/kernel/events.js +2 -2
  128. package/dist/core/mods/kernel/registration.d.ts +9 -1
  129. package/dist/core/mods/kernel/registration.js +3 -0
  130. package/dist/core/mods/kernel/site-rules.d.ts +3 -0
  131. package/dist/core/mods/kernel/site-rules.js +10 -0
  132. package/dist/core/mods/package.d.ts +23 -0
  133. package/dist/core/mods/package.js +118 -0
  134. package/dist/core/mods/stations.d.ts +33 -12
  135. package/dist/core/mods/stations.js +45 -11
  136. package/dist/core/mods/tool-call.d.ts +5 -1
  137. package/dist/core/mods/tool-call.js +13 -4
  138. package/dist/core/parent-spec-seat.d.ts +8 -3
  139. package/dist/core/parent-spec-seat.js +2 -0
  140. package/dist/core/park-selfcheck.js +6 -0
  141. package/dist/core/path-guard-rows.d.ts +20 -0
  142. package/dist/core/path-guard-rows.js +11 -0
  143. package/dist/core/peer-seat.d.ts +248 -0
  144. package/dist/core/peer-seat.js +439 -0
  145. package/dist/core/permission-rule-consent.js +10 -4
  146. package/dist/core/permission-rule-model.d.ts +16 -0
  147. package/dist/core/permission-rule-model.js +1 -1
  148. package/dist/core/present-plan-tool.d.ts +20 -3
  149. package/dist/core/present-plan-tool.js +48 -4
  150. package/dist/core/protocol-http-auth.d.ts +40 -29
  151. package/dist/core/protocol-http-auth.js +30 -32
  152. package/dist/core/redaction-marks.d.ts +16 -0
  153. package/dist/core/redaction-marks.js +16 -0
  154. package/dist/core/redaction-passes.js +8 -9
  155. package/dist/core/resume-startup-cause.js +1 -0
  156. package/dist/core/retention.d.ts +41 -15
  157. package/dist/core/retention.js +59 -12
  158. package/dist/core/rewrite-rejudge.d.ts +38 -0
  159. package/dist/core/rewrite-rejudge.js +42 -2
  160. package/dist/core/roles.d.ts +34 -2
  161. package/dist/core/roles.js +43 -4
  162. package/dist/core/run-origin.d.ts +40 -0
  163. package/dist/core/run-origin.js +37 -0
  164. package/dist/core/runner/advertised-writable-dirs.d.ts +57 -38
  165. package/dist/core/runner/advertised-writable-dirs.js +126 -0
  166. package/dist/core/runner/announce-once-ledger.d.ts +5 -4
  167. package/dist/core/runner/announce-once-ledger.js +4 -2
  168. package/dist/core/runner/call-hook-stations.js +2 -2
  169. package/dist/core/runner/compaction-restate.d.ts +15 -6
  170. package/dist/core/runner/compaction-restate.js +28 -2
  171. package/dist/core/runner/contracts.d.ts +33 -21
  172. package/dist/core/runner/credential-origin-seat.js +4 -3
  173. package/dist/core/runner/cwd-alignment-probe.d.ts +20 -0
  174. package/dist/core/runner/cwd-alignment-probe.js +21 -0
  175. package/dist/core/runner/decide-continuation.d.ts +2 -2
  176. package/dist/core/runner/gate-exit.d.ts +30 -8
  177. package/dist/core/runner/gate-exit.js +15 -8
  178. package/dist/core/runner/image-removed-seat.d.ts +12 -0
  179. package/dist/core/runner/image-removed-seat.js +19 -0
  180. package/dist/core/runner/inline-image.js +1 -1
  181. package/dist/core/runner/memory-consolidation-driver.js +3 -3
  182. package/dist/core/runner/park-commit.d.ts +1 -1
  183. package/dist/core/runner/park-commit.js +3 -0
  184. package/dist/core/runner/prepare-ask-lane.d.ts +1 -1
  185. package/dist/core/runner/prepare-ask-lane.js +2 -1
  186. package/dist/core/runner/prepare-boundary-parks.js +2 -2
  187. package/dist/core/runner/prepare-caps-and-workflow.d.ts +5 -5
  188. package/dist/core/runner/prepare-caps-and-workflow.js +3 -1
  189. package/dist/core/runner/prepare-config-doors.d.ts +8 -5
  190. package/dist/core/runner/prepare-config-doors.js +14 -10
  191. package/dist/core/runner/prepare-context-lane.js +2 -0
  192. package/dist/core/runner/prepare-delegation-surface.d.ts +8 -0
  193. package/dist/core/runner/prepare-delegation-surface.js +16 -18
  194. package/dist/core/runner/prepare-gate-stations.js +1 -1
  195. package/dist/core/runner/prepare-hands-readface.d.ts +11 -3
  196. package/dist/core/runner/prepare-hands-readface.js +9 -1
  197. package/dist/core/runner/prepare-inherited-gate.d.ts +1 -3
  198. package/dist/core/runner/prepare-inherited-gate.js +14 -27
  199. package/dist/core/runner/prepare-memory.d.ts +3 -0
  200. package/dist/core/runner/prepare-memory.js +26 -37
  201. package/dist/core/runner/prepare-park-ask.d.ts +1 -1
  202. package/dist/core/runner/prepare-park-ask.js +2 -1
  203. package/dist/core/runner/prepare-policy-chain.d.ts +7 -7
  204. package/dist/core/runner/prepare-policy-chain.js +18 -15
  205. package/dist/core/runner/prepare-project-context.d.ts +2 -2
  206. package/dist/core/runner/prepare-project-context.js +2 -2
  207. package/dist/core/runner/prepare-prompt-inputs.d.ts +1 -1
  208. package/dist/core/runner/prepare-prompt-inputs.js +8 -19
  209. package/dist/core/runner/prepare-protocol-tools.d.ts +4 -2
  210. package/dist/core/runner/prepare-protocol-tools.js +11 -3
  211. package/dist/core/runner/prepare-run-refs.d.ts +2 -3
  212. package/dist/core/runner/prepare-run-refs.js +4 -1
  213. package/dist/core/runner/prepare-suspend-saga.d.ts +2 -0
  214. package/dist/core/runner/prepare-suspend-saga.js +2 -1
  215. package/dist/core/runner/prepare-task.js +28 -13
  216. package/dist/core/runner/prepare-wiring-manifest.d.ts +2 -1
  217. package/dist/core/runner/prepare-wiring-manifest.js +4 -3
  218. package/dist/core/runner/prepare-workspace-restore.d.ts +3 -0
  219. package/dist/core/runner/prepare-workspace-restore.js +4 -4
  220. package/dist/core/runner/reply-pricing.d.ts +30 -0
  221. package/dist/core/runner/reply-pricing.js +19 -0
  222. package/dist/core/runner/resume-admission.js +5 -3
  223. package/dist/core/runner/resume-apply.js +6 -1
  224. package/dist/core/runner/resume-checkpoint-screen.js +2 -0
  225. package/dist/core/runner/resume-policy-outcome.js +5 -5
  226. package/dist/core/runner/role-seat-defaulted.d.ts +44 -0
  227. package/dist/core/runner/role-seat-defaulted.js +40 -0
  228. package/dist/core/runner/run-brain-sinks.js +2 -0
  229. package/dist/core/runner/run-harness-handlers.d.ts +3 -4
  230. package/dist/core/runner/run-harness-handlers.js +1 -8
  231. package/dist/core/runner/run-identity-wiring.d.ts +2 -5
  232. package/dist/core/runner/run-identity-wiring.js +6 -4
  233. package/dist/core/runner/run-leg.d.ts +2 -0
  234. package/dist/core/runner/run-leg.js +42 -29
  235. package/dist/core/runner/run-notification-lane.js +3 -0
  236. package/dist/core/runner/run-stop-and-final-verify.js +2 -2
  237. package/dist/core/runner/run-terminal-adoption.d.ts +2 -5
  238. package/dist/core/runner/run-terminal-adoption.js +9 -3
  239. package/dist/core/runner/run-turn-boundary.js +77 -70
  240. package/dist/core/runner/runtask.d.ts +1 -1
  241. package/dist/core/runner/runtask.js +2 -2
  242. package/dist/core/runner/side-call-account.d.ts +1 -1
  243. package/dist/core/runner/side-call-account.js +3 -18
  244. package/dist/core/runner/sub-agent-deny-lists.d.ts +24 -0
  245. package/dist/core/runner/sub-agent-deny-lists.js +10 -0
  246. package/dist/core/runner/terminal-account.js +3 -3
  247. package/dist/core/runner/tool-end-body.js +2 -1
  248. package/dist/core/runner/tool-occurrence.d.ts +5 -2
  249. package/dist/core/runner/tool-occurrence.js +4 -3
  250. package/dist/core/runner/turn-attachments.d.ts +26 -22
  251. package/dist/core/runner/turn-attachments.js +24 -26
  252. package/dist/core/runner/write-protection-station.d.ts +8 -2
  253. package/dist/core/runner/write-protection-station.js +2 -0
  254. package/dist/core/runner-deps.d.ts +3 -3
  255. package/dist/core/secret-env.d.ts +32 -2
  256. package/dist/core/secret-env.js +65 -3
  257. package/dist/core/sensitive-path-policy.js +9 -10
  258. package/dist/core/session-log-transfer.d.ts +24 -0
  259. package/dist/core/session-log-transfer.js +166 -0
  260. package/dist/core/session-policy-store.d.ts +3 -1
  261. package/dist/core/session-policy-store.js +13 -9
  262. package/dist/core/session-store.d.ts +86 -24
  263. package/dist/core/session-store.js +162 -24
  264. package/dist/core/session.d.ts +92 -1
  265. package/dist/core/shell-read-silence.js +1 -0
  266. package/dist/core/side-query.d.ts +11 -1
  267. package/dist/core/side-query.js +9 -0
  268. package/dist/core/skill-grant-binding.d.ts +31 -2
  269. package/dist/core/skill-grant-binding.js +31 -1
  270. package/dist/core/skill-grant.d.ts +8 -5
  271. package/dist/core/skill-grant.js +6 -6
  272. package/dist/core/steer-replay.d.ts +4 -2
  273. package/dist/core/steer-replay.js +2 -1
  274. package/dist/core/store-contracts/background-agent-store-contract.js +27 -0
  275. package/dist/core/store-contracts/checkpoint-store-contract.js +20 -2
  276. package/dist/core/store-contracts/mailbox-store-contract.js +31 -1
  277. package/dist/core/store-contracts/session-repo-contract.js +112 -5
  278. package/dist/core/store-contracts/session-store-contract.d.ts +4 -1
  279. package/dist/core/store-contracts/session-store-contract.js +236 -2
  280. package/dist/core/synthetic-read-verdict.js +2 -1
  281. package/dist/core/task-event.d.ts +92 -8
  282. package/dist/core/task-notification.js +16 -10
  283. package/dist/core/task-registry-agent.js +1 -0
  284. package/dist/core/task-registry-shared.d.ts +7 -1
  285. package/dist/core/task-spec.d.ts +49 -1
  286. package/dist/core/task-stream.d.ts +2 -1
  287. package/dist/core/terminal-cause.d.ts +11 -1
  288. package/dist/core/tool-catalog-entries.js +1 -0
  289. package/dist/core/tool-check-reading.d.ts +1 -0
  290. package/dist/core/tool-check-reading.js +3 -3
  291. package/dist/core/tool-policy.d.ts +16 -0
  292. package/dist/core/tool-result-store.d.ts +17 -10
  293. package/dist/core/tool-result-store.js +3 -1
  294. package/dist/core/tool-roster.d.ts +112 -5
  295. package/dist/core/tool-roster.js +42 -1
  296. package/dist/core/tool-spec.d.ts +3 -1
  297. package/dist/core/types.d.ts +3 -3
  298. package/dist/core/types.js +1 -1
  299. package/dist/core/untrusted-egress.d.ts +0 -2
  300. package/dist/core/untrusted-egress.js +10 -14
  301. package/dist/core/user-attachment.js +1 -1
  302. package/dist/core/wiring-manifest.d.ts +18 -6
  303. package/dist/core/wiring-manifest.js +4 -3
  304. package/dist/core/workspace-snapshot.d.ts +44 -0
  305. package/dist/core/workspace-snapshot.js +34 -0
  306. package/dist/core/write-protect.d.ts +43 -3
  307. package/dist/core/write-protect.js +43 -16
  308. package/dist/engine/compaction/compaction.js +29 -3
  309. package/dist/engine/execution-env/node-execution-env.d.ts +4 -3
  310. package/dist/engine/execution-env/node-execution-env.js +24 -23
  311. package/dist/engine/execution-env/symlink-chain.d.ts +7 -5
  312. package/dist/engine/harness/agent-harness.d.ts +30 -2
  313. package/dist/engine/harness/agent-harness.js +43 -12
  314. package/dist/engine/harness/messages.d.ts +3 -1
  315. package/dist/engine/harness/messages.js +3 -2
  316. package/dist/engine/harness/types.d.ts +56 -7
  317. package/dist/engine/harness/types.js +5 -1
  318. package/dist/engine/llm/rejected-images.d.ts +46 -0
  319. package/dist/engine/llm/rejected-images.js +54 -0
  320. package/dist/engine/llm/tool-turns.d.ts +2 -1
  321. package/dist/engine/llm/types.d.ts +30 -10
  322. package/dist/engine/llm/types.js +1 -1
  323. package/dist/engine/loop/agent-loop.d.ts +8 -0
  324. package/dist/engine/loop/agent-loop.js +52 -15
  325. package/dist/engine/loop/types.d.ts +3 -1
  326. package/dist/engine/session/import-validate.js +3 -0
  327. package/dist/engine/session/memory-repo.d.ts +17 -9
  328. package/dist/engine/session/memory-repo.js +44 -34
  329. package/dist/engine/session/path-to-root.d.ts +38 -0
  330. package/dist/engine/session/path-to-root.js +39 -0
  331. package/dist/engine/session/repo-utils.d.ts +22 -4
  332. package/dist/engine/session/repo-utils.js +49 -1
  333. package/dist/engine/session/storage-base.d.ts +10 -1
  334. package/dist/engine/session/storage-base.js +11 -22
  335. package/dist/index.d.ts +29 -16
  336. package/dist/index.js +21 -11
  337. package/dist/internal/harness-types.d.ts +2 -2
  338. package/dist/internal/harness.d.ts +3 -2
  339. package/dist/internal/harness.js +2 -2
  340. package/dist/internal/llm.d.ts +1 -0
  341. package/dist/orchestration/workflow-observe.d.ts +17 -1
  342. package/dist/orchestration/workflow-observe.js +20 -0
  343. package/dist/orchestration/workflow-types.d.ts +32 -7
  344. package/dist/orchestration/workflow.js +739 -489
  345. package/dist/shell/counting-pass.d.ts +50 -0
  346. package/dist/shell/counting-pass.js +502 -0
  347. package/dist/shell/lex.d.ts +4 -2
  348. package/dist/shell/lex.js +93 -34
  349. package/dist/shell/shell-words.d.ts +1 -1
  350. package/dist/shell/shell-words.js +7 -6
  351. package/dist/stores/file/index.d.ts +4 -1
  352. package/dist/stores/file/index.js +4 -1
  353. package/dist/stores/file/mailbox-store.js +6 -10
  354. package/dist/stores/file/session-store.d.ts +15 -8
  355. package/dist/stores/file/session-store.js +28 -13
  356. package/dist/tools/fs/fs-bash.d.ts +6 -0
  357. package/dist/tools/fs/fs-bash.js +6 -3
  358. package/dist/tools/fs/fs-write.d.ts +6 -3
  359. package/dist/tools/fs/fs-write.js +8 -7
  360. package/dist/tools/fs/index.d.ts +3 -0
  361. package/dist/tools/fs/index.js +7 -3
  362. package/dist/tools/fs/program-read-model.d.ts +13 -0
  363. package/dist/tools/fs/program-read-model.js +15 -0
  364. package/dist/tools/fs/program-read-model.rows.js +1 -1
  365. package/dist/tools/fs/read-deny.d.ts +13 -10
  366. package/dist/tools/fs/read-deny.js +25 -5
  367. package/dist/tools/fs/read-floor.d.ts +19 -0
  368. package/dist/tools/fs/read-floor.js +23 -0
  369. package/dist/tools/fs/safety.js +40 -8
  370. package/dist/tools/fs/search.js +6 -24
  371. package/dist/tools/fs/shell-read-check.d.ts +9 -2
  372. package/dist/tools/fs/shell-read-check.js +61 -16
  373. package/dist/tools/fs/shell-read-establish.js +2 -1
  374. package/dist/tools/fs/shell-read-identity.js +1 -1
  375. package/dist/tools/fs/shell-read-judge.d.ts +26 -9
  376. package/dist/tools/fs/shell-read-judge.js +10 -6
  377. package/dist/tools/fs/shell-read-plan.d.ts +6 -1
  378. package/dist/tools/fs/shell-read-plan.js +22 -15
  379. package/dist/tools/fs/shell-read-start.js +1 -0
  380. package/dist/tools/fs/shell-reentry-text.d.ts +15 -1
  381. package/dist/tools/fs/shell-reentry-text.js +25 -3
  382. package/dist/tools/monitor.d.ts +4 -0
  383. package/dist/tools/monitor.js +2 -0
  384. package/dist/tools/worktree.d.ts +42 -15
  385. package/dist/tools/worktree.js +60 -32
  386. package/package.json +5 -2
  387. package/test/export-surface.snapshot.json +149 -1
  388. package/wire-changes/core-stores-sql@7.58.0.json +29 -0
  389. package/wire-changes/core-stores-sql@7.59.0.json +29 -0
  390. package/wire-changes/core@7.58.0.json +2188 -0
  391. package/wire-changes/core@7.59.0.json +2459 -0
  392. package/wire-changes/mods-kernel@7.58.0.json +81 -0
  393. package/wire-changes/mods-kernel@7.59.0.json +29 -0
  394. package/wire-changes/primitives@7.58.0.json +29 -0
  395. package/wire-changes/primitives@7.59.0.json +29 -0
  396. package/dist/primitives/credential-ref.d.ts +0 -89
  397. package/dist/primitives/credential-ref.js +0 -125
  398. package/dist/primitives/index.d.ts +0 -2
  399. package/dist/primitives/index.js +0 -1
@@ -1,49 +1,59 @@
1
1
  /**
2
- * The HTTP credentials a protocol declaration carries — its static `headers` and the per-task principal
3
- * header (`principalHeader`) — and the one rule they obey, for MCP and A2A alike: they travel only to the
4
- * endpoints the declaration names, and every header name has exactly one owner, compared the way HTTP
5
- * compares names (case-insensitively). The principal header's owner is the engine: it sends the task's
6
- * principal under that name, or nothing under it when the task has none. A static header the credential vocabulary
7
- * reads as a credential is one the engine holds from the moment it resolves it: no child spawned on this host inherits
8
- * a variable whose value equals it (`holdOwnCredentialValues`, src/core/secret-env.ts).
2
+ * The HTTP headers one send to a protocol peer carries — the pieces the deployment's peer seat answered for it
3
+ * (src/core/peer-seat.ts) and the per-task principal header the declaration names (`principalHeader`) — and the one
4
+ * rule they obey, for MCP and A2A alike: they travel only to the endpoints the declaration names, and every header name
5
+ * has exactly one owner, compared the way HTTP compares names (case-insensitively). The principal header's owner is the
6
+ * engine: it sends the task's principal under that name, or nothing under it when the task has none. A name a protocol's
7
+ * transport writes itself (an MCP request's session, protocol version, content type, accept and resume headers) is the
8
+ * protocol's: neither a seat's answer nor the principal header owns it. The hosted-connector assertion header
9
+ * ({@link MCP_ASSERTION_HEADER}) is the seat's to answer and never the principal header's name. A header the credential
10
+ * vocabulary reads as a credential is one the engine holds from the moment it resolves it: no child spawned on this host
11
+ * inherits a variable whose value equals it (`holdOwnCredentialValues`, src/core/secret-env.ts).
9
12
  *
10
- * A declaration that breaks the rule is that peer's defect: the resolver throws inside the peer's own dial,
11
- * so the peer is skipped with a coded warning and its siblings still mount. The MCP transport binds its
12
- * endpoint by dialing only the declared URL with redirects not followed (`declaredEndpointFetch`); the A2A
13
- * peer, whose card may name another endpoint, is bound by {@link assertEndpointBound} and by its follow law (a request carrying
14
- * declared headers follows no redirect, {@link carriesDeclaredHeaders}).
13
+ * A principal header that breaks the rule is that peer's defect: the resolver throws inside the peer's own dial, so the
14
+ * peer is skipped with a coded warning and its siblings still mount; an answer that breaks it is the seat's, and that send
15
+ * is not made. The MCP transport binds its endpoint by dialing only the declared URL with redirects not followed (the seat's
16
+ * fetch, `peerFetch`); the A2A peer, whose card may name another endpoint, is bound at each send that carries pieces by
17
+ * {@link assertEndpointBound} and by its follow law (a request carrying them follows no redirect, {@link carriesDeclaredHeaders}).
15
18
  */
16
19
  import type { ProtocolId } from "./protocol-table.js";
17
20
  import { type Egress } from "./untrusted-egress.js";
18
- /** The per-peer HTTP auth declaration every protocol spec carries in the same two fields. */
21
+ /**
22
+ * The HTTP header NAME a hosted connector reads the principal assertion from: the engine's one definition of that name, exported from
23
+ * the package root so a deployment, a host and a connector each read it here instead of spelling it again. The name only — the
24
+ * value (the assertion itself) is not minted or held by this constant: the deployment's peer seat answers it under this name, per
25
+ * send. It is never the principal header's name (in any letter case): a declaration naming it so is refused at its dial with
26
+ * `config.protocol_header_collision`.
27
+ */
28
+ export declare const MCP_ASSERTION_HEADER = "connector-assertion";
29
+ /** The headers one send carries: the seat's answered `headers` and the declaration's `principalHeader` name. */
19
30
  export interface ProtocolHttpAuth {
20
31
  headers?: Record<string, string>;
21
32
  principalHeader?: string;
22
33
  }
23
- /** The first header name (any case) the declaration gives two owners, with both spellings. */
24
- export declare function headerOwnershipCollision(t: ProtocolHttpAuth): {
34
+ /**
35
+ * The first header name (any case) one send to a `protocol` peer would give two owners, with both spellings: two spellings among the
36
+ * answered `headers`, an answered header under the principal header's name, a name the protocol's transport writes itself (`first` is
37
+ * then the protocol's spelling, `engineOwned` true), or a principal header named as the engine's {@link MCP_ASSERTION_HEADER}
38
+ * (`first` the engine's spelling, `engineOwned` true). The assertion header among the answered headers is the seat's to send.
39
+ */
40
+ export declare function headerOwnershipCollision(t: ProtocolHttpAuth, protocol: ProtocolId): {
25
41
  readonly first: string;
26
42
  readonly second: string;
43
+ readonly engineOwned: boolean;
27
44
  } | undefined;
28
45
  /**
29
- * Resolve the HTTP request headers for one remote peer of `protocol`: the static headers, plus the
46
+ * Resolve the HTTP request headers of one send to a peer of `protocol`: the seat's answered headers, plus the
30
47
  * principal under `principalHeader` when both are present. Throws `config.protocol_header_collision` when
31
- * one header name has two owners (two static spellings, or a static entry under the principal header's
32
- * name — which would otherwise be sent merged beside the principal, or alone when the task has none), and
33
- * on a principal carrying CR/LF. Callers invoke it INSIDE their per-peer boundary.
48
+ * one header name would have two owners ({@link headerOwnershipCollision}: two spellings of one answered name, an
49
+ * answered header under the principal header's name — which would otherwise be sent merged beside the principal, or
50
+ * alone when the task has none — a name the protocol's transport writes, or a principal header named as the engine's
51
+ * {@link MCP_ASSERTION_HEADER}), and on a principal carrying CR/LF. Callers invoke it INSIDE their per-peer boundary.
34
52
  */
35
53
  export declare function resolveProtocolHttpHeaders(protocol: ProtocolId, t: ProtocolHttpAuth, principal?: string): Readonly<Record<string, string>> | undefined;
36
54
  /** The engine's default request headers under the declared ones: a declared name, in any case, owns that header
37
55
  * (the default of the same name is not sent beside it). */
38
56
  export declare function underDeclaredHeaders(defaults: Readonly<Record<string, string>>, declared: Record<string, string> | undefined): Record<string, string>;
39
- /**
40
- * Every header VALUE one HTTP peer's requests carry, whatever the header's NAME: each string value of the declaration's static
41
- * `headers` and the principal the engine sends under `principalHeader`, as declared. The transport knows these; the credential vocabulary
42
- * can only guess by name. How an endpoint can print one back — edges dropped, its credentials part, percent-encoded — is derived from
43
- * each value by {@link requestEchoSpellings}, once, and nowhere else.
44
- * Total: a declaration whose members cannot be read yields what could be read, because it is called on a failure path.
45
- */
46
- export declare function declaredHeaderValues(transport: unknown, principal?: string): readonly string[];
47
57
  /**
48
58
  * A peer's error text with what the peer was SENT taken out of it. Both kinds of removal are found on the ORIGINAL text (so no marker is
49
59
  * rescanned and no replacement can disturb what another one reads) and the ranges they take are merged, one marker per merged range: every
@@ -75,7 +85,8 @@ export declare function remoteWords(text: string, declared: readonly string[]):
75
85
  * next hop is not a declared endpoint; A2A's follow law reads this). */
76
86
  export declare function carriesDeclaredHeaders(headers: Record<string, string> | undefined): boolean;
77
87
  /**
78
- * Refuse an endpoint a peer advertised (an A2A card's interface URL) when it lies outside every origin the
79
- * declaration names and the peer's requests carry declared headers: `config.protocol_endpoint_unbound`.
88
+ * Refuse a send to `endpoint` (an A2A card's interface URL, judged at every send) when it lies outside every origin the
89
+ * declaration names and the send carries pieces the peer seat answered: `config.protocol_endpoint_unbound`. A send that
90
+ * carries none goes where the card says.
80
91
  */
81
92
  export declare function assertEndpointBound(protocol: ProtocolId, peer: string, endpoint: string, declared: readonly string[], headers: Record<string, string> | undefined): void;
@@ -1,25 +1,42 @@
1
1
  import { authSchemeCredentials, credentialHeaderValues, holdOwnCredentialValues } from "./secret-env.js";
2
- import { readMember } from "./thrown-value.js";
3
- import { egressText, redactionMarkerSpans } from "./untrusted-egress.js";
2
+ import { egressText } from "./untrusted-egress.js";
3
+ import { REDACTION_MARK, redactionMarkerSpans } from "./redaction-marks.js";
4
4
  import { inlineUntrusted } from "./untrusted-text.js";
5
- export function headerOwnershipCollision(t) {
5
+ export const MCP_ASSERTION_HEADER = "connector-assertion";
6
+ const PROTOCOL_OWNED_HEADERS = Object.freeze({
7
+ mcp: Object.freeze(["mcp-session-id", "mcp-protocol-version", "content-type", "accept", "last-event-id"]),
8
+ a2a: Object.freeze([]),
9
+ });
10
+ const ENGINE_OWNED_HEADERS = new Map([[MCP_ASSERTION_HEADER.toLowerCase(), MCP_ASSERTION_HEADER]]);
11
+ export function headerOwnershipCollision(t, protocol) {
6
12
  const owners = new Map();
7
- for (const name of [...Object.keys(t.headers ?? {}), ...(t.principalHeader ? [t.principalHeader] : [])]) {
8
- const prior = owners.get(name.toLowerCase());
13
+ const protocolOwned = PROTOCOL_OWNED_HEADERS[protocol];
14
+ const principalHeader = t.principalHeader ? [t.principalHeader] : [];
15
+ for (const name of [...Object.keys(t.headers ?? {}), ...principalHeader]) {
16
+ const folded = name.toLowerCase();
17
+ if (protocolOwned.includes(folded))
18
+ return { first: folded, second: name, engineOwned: true };
19
+ const engine = ENGINE_OWNED_HEADERS.get(folded);
20
+ if (engine !== undefined && principalHeader[0] === name)
21
+ return { first: engine, second: name, engineOwned: true };
22
+ const prior = owners.get(folded);
9
23
  if (prior !== undefined)
10
- return { first: prior, second: name };
11
- owners.set(name.toLowerCase(), name);
24
+ return { first: prior, second: name, engineOwned: false };
25
+ owners.set(folded, name);
12
26
  }
13
27
  return undefined;
14
28
  }
15
29
  export function resolveProtocolHttpHeaders(protocol, t, principal) {
16
30
  const principalHeader = t.principalHeader;
17
- const declared = t.headers;
18
- const own = { ...(declared !== undefined ? { headers: { ...declared } } : {}), ...(principalHeader !== undefined ? { principalHeader } : {}) };
31
+ const answered = t.headers;
32
+ const own = { ...(answered !== undefined ? { headers: { ...answered } } : {}), ...(principalHeader !== undefined ? { principalHeader } : {}) };
19
33
  holdOwnCredentialValues(credentialHeaderValues(own.headers));
20
- const collision = headerOwnershipCollision(own);
34
+ const collision = headerOwnershipCollision(own, protocol);
21
35
  if (collision !== undefined) {
22
- throw Object.assign(new Error(`${protocol}: the declaration names the header "${inlineUntrusted(collision.first, 80)}" twice ("${inlineUntrusted(collision.second, 80)}" — header names are case-insensitive); ${principalHeader !== undefined && collision.second === principalHeader ? "the principal header is the engine's to send, so remove the static entry" : "keep one spelling"} — this peer is not dialed`), { code: "config.protocol_header_collision" });
36
+ const problem = collision.engineOwned
37
+ ? `the header "${inlineUntrusted(collision.second, 80)}" is the ${PROTOCOL_OWNED_HEADERS[protocol].includes(collision.first) ? "protocol's own" : "engine's"} ${collision.first} header (header names are case-insensitive) and not ${principalHeader !== undefined && collision.second === principalHeader ? "the principal header's name" : "a header an answer may set"} — remove it`
38
+ : `the header "${inlineUntrusted(collision.first, 80)}" is named twice ("${inlineUntrusted(collision.second, 80)}" — header names are case-insensitive); ${principalHeader !== undefined && collision.second === principalHeader ? "the principal header is the engine's to send, so the answer may not set it" : "keep one spelling"}`;
39
+ throw Object.assign(new Error(`${protocol}: ${problem} — this peer is not dialed`), { code: "config.protocol_header_collision" });
23
40
  }
24
41
  if (principalHeader && principal !== undefined) {
25
42
  if (/[\r\n]/.test(principal))
@@ -33,24 +50,6 @@ export function underDeclaredHeaders(defaults, declared) {
33
50
  return { ...Object.fromEntries(Object.entries(defaults).filter(([k]) => !owned.has(k.toLowerCase()))), ...declared };
34
51
  }
35
52
  const httpTrimmed = (value) => value.replace(/^[\t\n\r ]+|[\t\n\r ]+$/g, "");
36
- export function declaredHeaderValues(transport, principal) {
37
- const out = new Set();
38
- try {
39
- const headers = readMember(transport, "headers");
40
- if (typeof headers === "object" && headers !== null) {
41
- for (const value of Object.values(headers))
42
- if (typeof value === "string")
43
- out.add(value);
44
- }
45
- }
46
- catch {
47
- }
48
- const principalHeader = readMember(transport, "principalHeader");
49
- if (typeof principalHeader === "string" && principalHeader !== "" && principal !== undefined)
50
- out.add(principal);
51
- out.delete("");
52
- return [...out];
53
- }
54
53
  function percentEncoded(value) {
55
54
  try {
56
55
  return encodeURIComponent(value);
@@ -73,7 +72,6 @@ function requestEchoSpellings(value) {
73
72
  }
74
73
  return [...spellings];
75
74
  }
76
- const ECHO_MARKER = "[redacted]";
77
75
  const COOKIE_START = String.raw `(?<![\w-])(?<cookie>(?:[Ss][Ee][Tt]-)?[Cc][Oo][Oo][Kk][Ii][Ee])(?<quote>["']?)[ \t]*:`;
78
76
  function stringEnd(text, at) {
79
77
  for (let i = at + 1; i < text.length; i++) {
@@ -118,7 +116,7 @@ export function scrubRequestEcho(text, declared) {
118
116
  kept = Math.max(kept, end);
119
117
  continue;
120
118
  }
121
- out += text.slice(kept, start) + ECHO_MARKER;
119
+ out += text.slice(kept, start) + REDACTION_MARK;
122
120
  kept = end;
123
121
  }
124
122
  return out + text.slice(kept);
@@ -207,5 +205,5 @@ export function assertEndpointBound(protocol, peer, endpoint, declared, headers)
207
205
  const at = new URL(endpoint).origin;
208
206
  if (origins.includes(at))
209
207
  return;
210
- throw Object.assign(new Error(`${protocol}: peer "${inlineUntrusted(peer, 80)}" advertises the endpoint origin ${inlineUntrusted(at, 120)}, outside the origins its declaration names (${origins.map((o) => inlineUntrusted(o, 120)).join(", ")}); the declared headers travel only to those — declare that origin as the peer's url (and the card's location as cardUrl) or drop the headers`), { code: "config.protocol_endpoint_unbound" });
208
+ throw Object.assign(new Error(`${protocol}: peer "${inlineUntrusted(peer, 80)}" advertises the endpoint origin ${inlineUntrusted(at, 120)}, outside the origins its declaration names (${origins.map((o) => inlineUntrusted(o, 120)).join(", ")}); the headers the peer seat answers travel only to those — declare that origin as the peer's url (and the card's location as cardUrl) or have the seat answer none for it`), { code: "config.protocol_endpoint_unbound" });
211
209
  }
@@ -0,0 +1,16 @@
1
+ /** The marks, by what they stand for. `whole` is the bare mark (a span removed whole — a credential value, a floor, a
2
+ * depth cut); the others name the shape that was withheld: `credentials` a URL's userinfo, `url` a whole URL, `path` an
3
+ * absolute filesystem path. A mark the engine writes is exactly one of these four. */
4
+ export declare const REDACTION_MARKS: {
5
+ readonly whole: "[redacted]";
6
+ readonly credentials: "[redacted-credentials]";
7
+ readonly url: "[redacted-url]";
8
+ readonly path: "[redacted-path]";
9
+ };
10
+ /** The bare mark — what a host compares against to tell that the engine withheld a value. */
11
+ export declare const REDACTION_MARK: "[redacted]";
12
+ /** Where the marks sit in `s`, one [start, end) span at a time, leftmost first. Lazy: a reader that stops early (a display cut stops
13
+ * at its bound) pays for the marks it looked at, not for every mark an input of a million of them holds. */
14
+ export declare function eachRedactionMarkerSpan(s: string): Generator<[number, number], void, undefined>;
15
+ /** Where the marks sit in `s`, all of them, as [start, end) spans, leftmost first. */
16
+ export declare function redactionMarkerSpans(s: string): Array<[number, number]>;
@@ -0,0 +1,16 @@
1
+ export const REDACTION_MARKS = {
2
+ whole: "[redacted]",
3
+ credentials: "[redacted-credentials]",
4
+ url: "[redacted-url]",
5
+ path: "[redacted-path]",
6
+ };
7
+ export const REDACTION_MARK = REDACTION_MARKS.whole;
8
+ const escapeLiteral = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
9
+ const REDACTION_MARKER_RE = new RegExp(Object.values(REDACTION_MARKS).map(escapeLiteral).join("|"), "g");
10
+ export function* eachRedactionMarkerSpan(s) {
11
+ for (const m of s.matchAll(REDACTION_MARKER_RE))
12
+ yield [m.index, m.index + m[0].length];
13
+ }
14
+ export function redactionMarkerSpans(s) {
15
+ return [...eachRedactionMarkerSpan(s)];
16
+ }
@@ -1,3 +1,4 @@
1
+ import { REDACTION_MARK, REDACTION_MARKS, redactionMarkerSpans } from "./redaction-marks.js";
1
2
  export function summarizeRedactions(findings) {
2
3
  if (findings.length === 0)
3
4
  return "no redactions";
@@ -34,10 +35,8 @@ function passZeroMapper(batches) {
34
35
  return p;
35
36
  };
36
37
  }
37
- const PREEXISTING_MARKER_RE = /\[redacted(?:-[a-z]+)?\]/g;
38
38
  const FORMAT_CHAR_RE = /\p{Cf}/u;
39
39
  const MAX_FORMAT_SLOT_SCANS = 64;
40
- const REDACTED_WHOLE = "[redacted]";
41
40
  function finding(pass, span, family) {
42
41
  const f = { kind: pass.kind, confidence: pass.confidence, span, marker: pass.marker, source: pass.source };
43
42
  if (family !== undefined)
@@ -96,7 +95,7 @@ function soloHits(input, passes) {
96
95
  if (rescans) {
97
96
  work -= m[0].length;
98
97
  if (work < 0) {
99
- hits.push({ start: at, end: input.length, marker: pass.marker === "" ? REDACTED_WHOLE : pass.marker, pass: i, family: familyAt(), matchStart: at, matchEnd: input.length });
98
+ hits.push({ start: at, end: input.length, marker: pass.marker === "" ? REDACTION_MARK : pass.marker, pass: i, family: familyAt(), matchStart: at, matchEnd: input.length });
100
99
  break;
101
100
  }
102
101
  re.lastIndex = at + 1;
@@ -168,7 +167,7 @@ function renderRemovals(input, removals) {
168
167
  if (r.marker !== "" && (widest === undefined || r.end - r.start > widest.end - widest.start))
169
168
  widest = r;
170
169
  }
171
- const marker = widest?.marker ?? REDACTED_WHOLE;
170
+ const marker = widest?.marker ?? REDACTION_MARK;
172
171
  out += input.slice(cursor, start) + marker;
173
172
  cursor = end;
174
173
  edits.push({ at: start, removedLen: end - start, insertedLen: marker.length, inserted: marker, family: widest?.family, head: 0, tail: 0, pass: widest?.pass ?? sorted[i - 1].pass });
@@ -248,7 +247,7 @@ function replacedSpans(batches) {
248
247
  }
249
248
  export function runRedactionPasses(input, passes, report) {
250
249
  if (report !== undefined && report.preexistingMarkers === undefined) {
251
- report.preexistingMarkers = input.match(PREEXISTING_MARKER_RE)?.length ?? 0;
250
+ report.preexistingMarkers = redactionMarkerSpans(input).length;
252
251
  }
253
252
  if (!FORMAT_CHAR_RE.test(input))
254
253
  return applyPasses(input, passes, report, (pos) => pos).out;
@@ -288,7 +287,7 @@ export function runRedactionPasses(input, passes, report) {
288
287
  const { batches } = applyPasses(view, passes, report, toOriginal, true);
289
288
  const viewSpans = replacedSpans(batches);
290
289
  if (viewSpans === undefined)
291
- return REDACTED_WHOLE;
290
+ return REDACTION_MARK;
292
291
  const spans = viewSpans.map((sp) => {
293
292
  const startIdx = offsetToCharIndex.get(sp.start) ?? viewChars.length;
294
293
  const endIdx = offsetToCharIndex.get(sp.end) ?? viewChars.length;
@@ -308,7 +307,7 @@ export function runRedactionPasses(input, passes, report) {
308
307
  if (formatAtSlot[k] !== "")
309
308
  cutOffsets.push(charStartOffsets[k]);
310
309
  if (cutOffsets.length > MAX_FORMAT_SLOT_SCANS)
311
- return REDACTED_WHOLE;
310
+ return REDACTION_MARK;
312
311
  const extra = [];
313
312
  const rawSpans = replacedSpans(applyPasses(input, passes, undefined, (pos) => pos, true).batches);
314
313
  if (rawSpans !== undefined)
@@ -363,8 +362,8 @@ export function runRedactionPasses(input, passes, report) {
363
362
  result += input.slice(cursor);
364
363
  return result;
365
364
  }
366
- const BRACKET_MARKER = { "url-credentials": "[redacted-credentials]" };
367
- const bracketMarker = (kind) => BRACKET_MARKER[kind] ?? "[redacted]";
365
+ const BRACKET_MARKER = { "url-credentials": REDACTION_MARKS.credentials };
366
+ const bracketMarker = (kind) => BRACKET_MARKER[kind] ?? REDACTION_MARK;
368
367
  const capturesLabel = (re) => new RegExp(`${re.source}|`).exec("").length > 1;
369
368
  export function egressPasses(groups, replacers = {}) {
370
369
  return groups.map((rows) => {
@@ -12,6 +12,7 @@ const CAUSE_OF_CODE = new Map([
12
12
  ["checkpoint.config_refused", "configuration"],
13
13
  ["resume.parent_constraint_missing", "configuration"],
14
14
  ["resume.parent_constraint_mismatch", "configuration"],
15
+ ["revive.policy_floor_unreadable", "configuration"],
15
16
  ["checkpoint.gate_mismatch", "decision_rejected"],
16
17
  ["checkpoint.invalid_outcome", "decision_rejected"],
17
18
  ["resume.constraint_rejected", "decision_rejected"],
@@ -1,12 +1,21 @@
1
- /** A store's retention capability declaration. Absent ⇒ read fail-closed as `"none"`. */
1
+ /** A store's retention declaration: `"managed"` = this store's rows are deleted on schedule by the
2
+ * deployment; `"none"` = nothing deletes them on schedule. Absent ⇒ read fail-closed as `"none"`. */
2
3
  export type RetentionDeclaration = "managed" | "none";
3
4
  /** The declaration face a storage implementation carries (structural — every store interface's
4
- * optional `retention` field conforms). `"managed"` is a PROMISE to honor
5
- * {@link ManagedRetentionCapability}; `"none"` is the honest default for stores that cannot delete
6
- * on schedule (all bundled in-memory/TTL stores declare it). */
5
+ * optional `retention` field conforms). The word is the deployment's statement about this store's
6
+ * rows (see {@link RetentionDeclaration}), given by the party that runs the sweep when it constructs
7
+ * the store: the bundled stores take it as their `retention` option and default to `"none"`. */
7
8
  export interface RetentionDeclaring {
8
9
  readonly retention?: RetentionDeclaration;
9
10
  }
11
+ /**
12
+ * The one reader of a retention declaration word — the startup validation's and every bundled store's
13
+ * constructor option's. `undefined` reads as `"none"`; anything but the two words is refused
14
+ * (`config.retention_capability`), so a typo'd declaration never silently means anything.
15
+ *
16
+ * @param name the deployment-facing name of where the word was read (a store seat, an option).
17
+ */
18
+ export declare function readRetentionDeclaration(name: string, value: unknown): RetentionDeclaration;
10
19
  /**
11
20
  * The deployment's managed-retention policy ({@link import("./types.js").RunnerDeps.retentionPolicy}).
12
21
  * Core consumes it ONLY for the startup capability validation (and exposes it to the deployment's
@@ -19,9 +28,10 @@ export interface RetentionPolicy {
19
28
  maxAgeDays: number;
20
29
  }
21
30
  /**
22
- * What a `retention: "managed"` store PROMISES (contract TYPE — core ships no implementation; the
23
- * server half consumes this. Reference implementation of the cascade: the server's session-purge
24
- * order contract). Every method is expected to be:
31
+ * The executor that deletes the rows of the stores declaring `retention: "managed"` — a backend's
32
+ * `retention` member (contract TYPE — core ships no implementation; the server half consumes this.
33
+ * Reference implementation of the cascade: the server's session-purge order contract). A deployment
34
+ * that declares a store managed runs one over that store's rows. Every method is expected to be:
25
35
  * - **tenant-domain scoped**: work is enumerated and executed per retention domain (tenant/scope),
26
36
  * never as one global sweep;
27
37
  * - **idempotent**: a retried invocation after a crash re-converges (already-deleted rows are
@@ -84,14 +94,8 @@ export interface RetentionReceipt {
84
94
  /** Tombstones written for the deleted rows. */
85
95
  tombstones: number;
86
96
  }
87
- /**
88
- * Startup validation (and per-prepare backstop): with the retention policy LOCKED and configured,
89
- * every wired store must declare `retention: "managed"` — a locked policy over a store that cannot
90
- * delete is refused (`config.retention_capability`), never silently accepted. Also fail-loud
91
- * validates the policy value itself (`config.retention_policy`). Exported for deployments to call at
92
- * their own startup; the prepare preflight re-runs it on every leg regardless.
93
- */
94
- export declare function assertRetentionCapability(input: {
97
+ /** The stores whose words are judged, and the policy that judges them. */
98
+ interface RetentionWords {
95
99
  policy: RetentionPolicy | undefined;
96
100
  /** Whether locked-config locks the `retentionPolicy` key (locked-config.ts `LockedKey`). */
97
101
  locked: boolean;
@@ -102,4 +106,26 @@ export declare function assertRetentionCapability(input: {
102
106
  name: string;
103
107
  store: object | undefined;
104
108
  }>;
109
+ }
110
+ /**
111
+ * The declaration half of the check — all a caller that holds no executor can judge: the policy value, every
112
+ * wired store's word, and, with the retention policy LOCKED and configured, every store declaring
113
+ * `retention: "managed"` — a locked policy over a store that cannot delete is refused
114
+ * (`config.retention_capability`), never silently accepted. The task-prepare preflight runs it on every leg;
115
+ * a deployment's own startup calls {@link assertRetentionCapability}, which runs it too.
116
+ */
117
+ export declare function assertRetentionWords(input: RetentionWords): void;
118
+ /**
119
+ * Startup validation, the deployment's call: the declaration half ({@link assertRetentionWords}) and the
120
+ * declaration held to the executor the deployment runs. `executor` is required — the
121
+ * {@link ManagedRetentionCapability} the deployment runs over these stores' rows (a backend's `retention` member),
122
+ * or `null` when it runs none; `undefined` is refused (`config.retention_capability`), so a backend's absent
123
+ * member is never read as "judge the words alone". Locked or not, a store saying `"managed"` (its rows are deleted
124
+ * on schedule) beside `executor: null` is refused, and so is an executor that is not one. A `"none"` store beside
125
+ * an executor is not refused — a deployment may hold the executor and not run it on a store, and a locked policy
126
+ * refuses that store by its word.
127
+ */
128
+ export declare function assertRetentionCapability(input: RetentionWords & {
129
+ executor: ManagedRetentionCapability | null;
105
130
  }): void;
131
+ export {};
@@ -1,4 +1,12 @@
1
1
  import { describeRejectedValue } from "./tool-search-setting.js";
2
+ import { thrownText } from "./thrown-value.js";
3
+ export function readRetentionDeclaration(name, value) {
4
+ if (value === undefined || value === "none")
5
+ return "none";
6
+ if (value === "managed")
7
+ return "managed";
8
+ throw codedError("config.retention_capability", `store "${name}" declares an unparseable retention value ${describeRejectedValue(value)} — expected "managed" or "none".`);
9
+ }
2
10
  export const RETENTION_CASCADE_DOMAINS = Object.freeze(["checkpoints", "session-trees", "orphan-tool-results"]);
3
11
  export const RETENTION_CASCADE_EXEMPT = Object.freeze(["session-pollution", "session-capture-optout", "lineage.json"]);
4
12
  function codedError(code, message) {
@@ -6,8 +14,30 @@ function codedError(code, message) {
6
14
  e.code = code;
7
15
  return e;
8
16
  }
9
- export function assertRetentionCapability(input) {
10
- const { policy, locked, stores } = input;
17
+ const RETENTION_EXECUTOR_MEMBERS = Object.keys({
18
+ listRetentionDomains: true,
19
+ expireCheckpoints: true,
20
+ deleteExpiredSessions: true,
21
+ deleteOrphanToolResults: true,
22
+ });
23
+ function assertRetentionExecutor(executor) {
24
+ if ((typeof executor !== "object" && typeof executor !== "function") || executor === null) {
25
+ throw codedError("config.retention_capability", `the retention executor must be an object implementing ManagedRetentionCapability, or null when the deployment runs none (got ${describeRejectedValue(executor)}).`);
26
+ }
27
+ for (const member of RETENTION_EXECUTOR_MEMBERS) {
28
+ let value;
29
+ try {
30
+ value = executor[member];
31
+ }
32
+ catch (cause) {
33
+ throw codedError("config.retention_capability", `the retention executor's ${member} could not be read (${thrownText(cause)}) — it is not a ManagedRetentionCapability.`);
34
+ }
35
+ if (typeof value !== "function") {
36
+ throw codedError("config.retention_capability", `the retention executor's ${member} is ${describeRejectedValue(value)}, not a function — it is not a ManagedRetentionCapability.`);
37
+ }
38
+ }
39
+ }
40
+ function readRetentionWords({ policy, stores }) {
11
41
  const declared = policy;
12
42
  if (declared !== undefined && (typeof declared !== "object" || declared === null || Array.isArray(declared))) {
13
43
  throw codedError("config.retention_policy", `retentionPolicy must be an object carrying maxAgeDays (got ${declared === null ? "null" : Array.isArray(declared) ? "an array" : typeof declared}).`);
@@ -15,17 +45,34 @@ export function assertRetentionCapability(input) {
15
45
  if (policy !== undefined && (!Number.isFinite(policy.maxAgeDays) || policy.maxAgeDays < 0)) {
16
46
  throw codedError("config.retention_policy", `retentionPolicy.maxAgeDays must be a finite non-negative number of days (got ${describeRejectedValue(policy.maxAgeDays)}).`);
17
47
  }
18
- const declaredRetention = (name, store) => {
19
- const r = store.retention;
20
- if (r === undefined || r === "none")
21
- return "none";
22
- if (r === "managed")
23
- return "managed";
24
- throw codedError("config.retention_capability", `store "${name}" declares an unparseable retention value ${JSON.stringify(r)} — expected "managed" or "none".`);
25
- };
26
- const declarations = stores
48
+ return stores
27
49
  .filter((s) => s.store !== undefined && s.store !== null)
28
- .map(({ name, store }) => ({ name, retention: declaredRetention(name, store) }));
50
+ .map(({ name, store }) => ({ name, retention: readRetentionDeclaration(name, store.retention) }));
51
+ }
52
+ export function assertRetentionWords(input) {
53
+ const { policy, locked, stores } = input;
54
+ const words = { policy, locked, stores };
55
+ refuseLockedOverNone(words, readRetentionWords(words));
56
+ }
57
+ export function assertRetentionCapability(input) {
58
+ const { policy, locked, stores, executor } = input;
59
+ const words = { policy, locked, stores };
60
+ if (executor === undefined) {
61
+ throw codedError("config.retention_capability", `executor is required — the managed-retention executor the deployment runs over these stores' rows (a backend's \`retention\` member), or null when it runs none (got undefined).`);
62
+ }
63
+ const declarations = readRetentionWords(words);
64
+ if (executor !== null)
65
+ assertRetentionExecutor(executor);
66
+ else {
67
+ const unexecuted = declarations.filter(({ retention }) => retention === "managed");
68
+ if (unexecuted.length > 0) {
69
+ throw codedError("config.retention_capability", `${unexecuted.map((s) => s.name).join(", ")} declare${unexecuted.length === 1 ? "s" : ""} retention "managed" — rows deleted on schedule by the deployment — ` +
70
+ `but the deployment runs no retention executor: nothing would delete them. Declare those stores "none", or wire the executor that deletes their rows.`);
71
+ }
72
+ }
73
+ refuseLockedOverNone(words, declarations);
74
+ }
75
+ function refuseLockedOverNone({ policy, locked }, declarations) {
29
76
  if (!locked || policy === undefined)
30
77
  return;
31
78
  const incapable = declarations.filter(({ retention }) => retention !== "managed");
@@ -1,6 +1,43 @@
1
1
  import type { PreToolUseResult } from "./hooks.js";
2
2
  import type { PermissionResult } from "./tool-policy.js";
3
3
  import type { PreToolUseScreening } from "./runner/gate-exit.js";
4
+ import type { RewriteAuthor, ToolInputRewrite } from "./task-event.js";
5
+ /** One gate pass's account of its rewrites: the bytes it took at its entry, and one author per adoption that changed the bytes
6
+ * in hand (written only through {@link noteRewrite}). */
7
+ export interface RewriteAccount {
8
+ readonly entry: unknown;
9
+ readonly by: RewriteAuthor[];
10
+ }
11
+ /** An adoption of `to` in place of `from`, by `authors`: they are named when the two read as other bytes. */
12
+ export declare function noteRewrite(account: RewriteAccount, req: {
13
+ readonly face?: object | undefined;
14
+ }, from: unknown, to: unknown, authors: readonly RewriteAuthor[]): void;
15
+ /** The restriction chain's and the approver's word in an account (one author each, frozen once). */
16
+ export declare const POLICY_AUTHOR: readonly RewriteAuthor[];
17
+ export declare const APPROVER_AUTHOR: readonly RewriteAuthor[];
18
+ /** The extensions that authored a screening's rewrite, as authors. */
19
+ export declare const extensionAuthors: (names: readonly string[]) => readonly RewriteAuthor[];
20
+ /** The call's record at the allow exit: when `ran` (the bytes the gate lets go) is not the bytes it took, `snapshot` (their frozen
21
+ * plain-data projection, the exit's `finalInput`) with the authors the account holds. Bytes that moved with no author named is an
22
+ * engine defect (an adoption that did not name itself). */
23
+ export declare function rewriteRecordOf(account: RewriteAccount, req: {
24
+ readonly face?: object | undefined;
25
+ readonly toolName: string;
26
+ }, ran: unknown, snapshot: unknown): ToolInputRewrite | undefined;
27
+ /** The authors of each `classic.PreToolUse` answer one dispatch received, read by the answer's identity as the station receives
28
+ * it: a handler is an author when its answer's `updatedInput` reads as other bytes ({@link sameBytes}, under `req`'s reading) than
29
+ * what its `next()` returned (the event's `input` when that carried none, or when it never called `next`); otherwise its answer
30
+ * carries the authors of what came up. `record` is the station's answer check (it refuses nothing); `of` reads the chain's answer. */
31
+ export declare function screeningAuthorship(req: {
32
+ readonly face?: object | undefined;
33
+ }): {
34
+ readonly record: (answer: unknown, e: {
35
+ readonly input?: unknown;
36
+ }, by: {
37
+ readonly plugin: string;
38
+ }, below: readonly unknown[]) => undefined;
39
+ readonly of: (answer: unknown) => readonly string[];
40
+ };
4
41
  /** What a judge did with the bytes it was handed: kept them (`as_is`), or handed back another form. */
5
42
  export type RejudgeReading = {
6
43
  readonly kind: "as_is";
@@ -30,6 +67,7 @@ export type ScreeningRejudge = {
30
67
  readonly kind: "refused";
31
68
  readonly reason: string;
32
69
  readonly by: "hook" | "engine";
70
+ readonly extension?: string;
33
71
  };
34
72
  /** The screening's second look at rewritten `bytes` (the gate's fold after a policy rewrite; the approved-edit pass). */
35
73
  export declare function screenRewrite(screening: PreToolUseScreening, req: {
@@ -1,5 +1,45 @@
1
1
  import { canonicalize } from "./canonical-json.js";
2
2
  import { argsAsTheToolReads } from "./effective-path-target.js";
3
+ export function noteRewrite(account, req, from, to, authors) {
4
+ if (!sameBytes(req, from, to))
5
+ account.by.push(...authors);
6
+ }
7
+ export const POLICY_AUTHOR = Object.freeze([Object.freeze({ kind: "policy" })]);
8
+ export const APPROVER_AUTHOR = Object.freeze([Object.freeze({ kind: "approver" })]);
9
+ export const extensionAuthors = (names) => names.map((name) => Object.freeze({ kind: "extension", name }));
10
+ export function rewriteRecordOf(account, req, ran, snapshot) {
11
+ if (sameBytes(req, account.entry, ran))
12
+ return undefined;
13
+ if (account.by.length === 0)
14
+ throw new Error(`the arguments of "${req.toolName}" the gate lets go are not the ones it took, and no adoption named who replaced them — an engine defect`);
15
+ return Object.freeze({ by: Object.freeze([...account.by]), input: snapshot });
16
+ }
17
+ export function screeningAuthorship(req) {
18
+ const authors = new WeakMap();
19
+ const rewriteOf = (a) => Reflect.get(a, "updatedInput");
20
+ const same = (x, y) => { try {
21
+ return sameBytes(req, x, y);
22
+ }
23
+ catch {
24
+ return false;
25
+ } };
26
+ return {
27
+ record: (answer, e, by, below) => {
28
+ if (typeof answer !== "object" || answer === null || authors.has(answer))
29
+ return undefined;
30
+ let lower;
31
+ for (const b of below)
32
+ if (typeof b === "object" && b !== null)
33
+ lower = b;
34
+ const lowerAuthors = lower !== undefined ? (authors.get(lower) ?? []) : [];
35
+ const lowerBytes = lower !== undefined && rewriteOf(lower) !== undefined ? rewriteOf(lower) : e.input;
36
+ const mine = rewriteOf(answer);
37
+ authors.set(answer, mine === undefined ? [] : same(lowerBytes, mine) ? lowerAuthors : [...lowerAuthors, by.plugin]);
38
+ return undefined;
39
+ },
40
+ of: (answer) => (typeof answer === "object" && answer !== null ? (authors.get(answer) ?? []) : []),
41
+ };
42
+ }
3
43
  export function sameBytes(req, a, b) {
4
44
  return a === b || canonicalize(argsAsTheToolReads(req, a)) === canonicalize(argsAsTheToolReads(req, b));
5
45
  }
@@ -10,10 +50,10 @@ export function readRejudge(req, given, answer) {
10
50
  export async function screenRewrite(screening, req, bytes, subject) {
11
51
  const screened = await screening.screen(bytes, subject);
12
52
  if (screened.kind === "refused")
13
- return { kind: "refused", reason: screened.reason, by: "engine" };
53
+ return { kind: "refused", reason: screened.reason, by: "engine", ...(screened.extension !== undefined ? { extension: screened.extension } : {}) };
14
54
  const r = screened.answer;
15
55
  if (r?.action === "deny")
16
- return { kind: "refused", reason: screening.deniedReason(r), by: "hook" };
56
+ return { kind: "refused", reason: screening.deniedReason(r), by: "hook", ...(screened.answeredBy !== undefined ? { extension: screened.answeredBy } : {}) };
17
57
  if (readRejudge(req, bytes, r).kind === "rewritten")
18
58
  return { kind: "refused", reason: rewriteChasedSentence(req.toolName), by: "engine" };
19
59
  if (r === undefined)