@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
@@ -5,6 +5,8 @@ import { type RoleBaseDeclaration } from "../prompt-assembly/role-base.js";
5
5
  import { type ModelRef, type ModelRole, type ModelRoles, type RoleSpec } from "./types.js";
6
6
  export type { ModelRole, RoleSpec, ModelRoles } from "./types.js";
7
7
  export { MODEL_ROLES } from "./types.js";
8
+ /** A word in a refusal sentence, bounded and quoted; any other kind of value by its kind (rendering it could itself throw). */
9
+ export declare function bindingShown(value: unknown): string;
8
10
  /**
9
11
  * Resolve a ModelRef against the catalog (a Model object passes through). A word the catalog does not hold, and a value that is no model
10
12
  * reference, are refused by `config.unknown_role` with `detail { field: seat, reason }` — `seat` names where the caller wrote the word
@@ -118,6 +120,34 @@ export declare function roleSpecNamesModel(spec: RoleSpec | undefined): boolean;
118
120
  * maps, so an entry no task of this leg selects still refuses loudly.
119
121
  */
120
122
  export declare function screenRoleMap(roles: ModelRoles | undefined, field: "RunnerDeps.roles" | "TaskSpec.roles"): void;
123
+ /** A role seat whose word the catalog does not hold: the role, the seat as the refusal names it, the word written there. */
124
+ export interface UnheldRoleSeat {
125
+ role: ModelRole;
126
+ seat: string;
127
+ word: string;
128
+ }
129
+ /**
130
+ * The ONE test of "this seat names a word the deployment's catalog does not declare": the word a role entry writes — the string
131
+ * itself, or the `model` member of a config record — when it is a string and no key of the catalog answers it. A Model object, a
132
+ * `select`, a preset-only record and an absent seat name no word. Total: it reads, never judges the shape (a value that is no binding
133
+ * is the screen's refusal, `screenRoleMap`).
134
+ */
135
+ export declare function unheldSeatWord(spec: unknown, models: Record<string, Model> | undefined): string | undefined;
136
+ /** Every role seat of the merged maps (deployment and task) that names a word the catalog does not hold, in vocabulary order — the facts
137
+ * {@link seatRead} stands in for. `default` is never listed (it refuses) and neither is `classifier` unless asked (it says it itself). */
138
+ export declare function unheldRoleSeats(spec: {
139
+ roles?: ModelRoles;
140
+ }, deps: {
141
+ models?: Record<string, Model>;
142
+ roles?: ModelRoles;
143
+ }, only?: readonly ModelRole[]): UnheldRoleSeat[];
144
+ /** The refusal of an unheld seat — the seat's own `config.unknown_role` / `unknown_model_ref`, for the place where a chain ends with no model. */
145
+ export declare function unheldSeatRefusal(u: UnheldRoleSeat): Error;
146
+ /** The refusal for a chain of roles that supplied no model while one of its seats was written but not held — that seat's own
147
+ * `config.unknown_role`; `undefined` when no seat of the chain is unheld (the caller's own "no seat" refusal stands). */
148
+ export declare function unheldChainRefusal(chain: readonly ModelRole[], models: Record<string, Model> | undefined, roles: ModelRoles | undefined): Error | undefined;
149
+ /** The roles a role falls back to when its seat supplies nothing, nearest first (what {@link unheldRoleSeats} says it stands in for). */
150
+ export declare function roleFallbackChain(role: ModelRole): readonly ModelRole[];
121
151
  export interface ResolvedRole {
122
152
  model: Model;
123
153
  /**
@@ -156,7 +186,8 @@ export declare function presetRoleBaseOf(spec: {
156
186
  /**
157
187
  * Resolve the model (and default thinking) for a task. Explicit `spec.model` wins; otherwise walk the
158
188
  * `modelRole`'s fallback chain over the merged roles (task overrides runner) and use the first role
159
- * that supplies a model. Throws a helpful error if nothing resolves.
189
+ * that supplies a model. A seat on that chain whose word the catalog does not hold supplies none ({@link seatRead}); when the whole
190
+ * chain supplies none, the first such seat's own refusal is the answer. Throws a helpful error if nothing resolves.
160
191
  *
161
192
  * @contract roles.side_channels_deployment_only — an engine SIDE CHANNEL (the auto-mode classifier,
162
193
  * the compaction/summarize lane, memory consolidation, next-prompt suggestion) resolves here with a
@@ -179,7 +210,8 @@ export declare function resolveTaskModel(spec: {
179
210
  /**
180
211
  * Resolve a role's model **only if that exact role key is configured** (no fallback chain). Used for
181
212
  * the `summarize` compaction model: override only when a summarize-specific model is set, otherwise
182
- * let the caller fall back to the main model (unchanged behavior).
213
+ * let the caller fall back to the main model (unchanged behavior). A seat naming a word the catalog does not hold is "not set" here,
214
+ * as in the walk ({@link seatRead}); a caller that needs a model asks {@link unheldRoleSeats} for the refusal when it gets none.
183
215
  */
184
216
  export declare function roleModelIfSet(role: ModelRole, spec: {
185
217
  roles?: ModelRoles;
@@ -32,7 +32,7 @@ function isModelShaped(s) {
32
32
  function isBindingObject(value) {
33
33
  return (typeof value === "object" && value !== null) || typeof value === "function";
34
34
  }
35
- function bindingShown(value) {
35
+ export function bindingShown(value) {
36
36
  if (typeof value === "string")
37
37
  return JSON.stringify(value.length > 80 ? `${value.slice(0, 80)}…` : value);
38
38
  return value === null ? "null" : isList(value) ? "a list" : `a ${typeof value}`;
@@ -296,6 +296,40 @@ function partsModel(parts, models, seat = "a role seat") {
296
296
  }
297
297
  return undefined;
298
298
  }
299
+ export function unheldSeatWord(spec, models) {
300
+ const named = typeof spec === "string" ? spec : isBindingObject(spec) && !("id" in spec && "api" in spec) ? spec.model : undefined;
301
+ return typeof named === "string" && catalogModel(named, models) === undefined ? named : undefined;
302
+ }
303
+ const STRICT_SEATS = new Set(["default", "classifier"]);
304
+ function seatRead(parts, models, seat, role) {
305
+ const word = STRICT_SEATS.has(role) ? undefined : unheldSeatWord(parts.model, models);
306
+ if (word === undefined)
307
+ return { parts, model: partsModel(parts, models, seat), unheld: undefined };
308
+ const unset = { ...parts, model: undefined };
309
+ return { parts: unset, model: partsModel(unset, models, seat), unheld: { role, seat, word } };
310
+ }
311
+ export function unheldRoleSeats(spec, deps, only) {
312
+ const merged = mergeRoles(deps.roles, spec.roles);
313
+ const out = [];
314
+ for (const role of only ?? MODEL_ROLES) {
315
+ if (only === undefined && STRICT_SEATS.has(role))
316
+ continue;
317
+ const word = unheldSeatWord(merged[role], deps.models);
318
+ if (word !== undefined)
319
+ out.push({ role, seat: `roles.${role}`, word });
320
+ }
321
+ return out;
322
+ }
323
+ export function unheldSeatRefusal(u) {
324
+ return unknownModelRefRefusal(u.word, u.seat);
325
+ }
326
+ export function unheldChainRefusal(chain, models, roles) {
327
+ const first = unheldRoleSeats({}, { models, roles }, chain)[0];
328
+ return first !== undefined ? unheldSeatRefusal(first) : undefined;
329
+ }
330
+ export function roleFallbackChain(role) {
331
+ return FALLBACK[role];
332
+ }
299
333
  function chainHead(spec, deps) {
300
334
  const start = spec.modelRole === undefined ? "default" : spec.modelRole;
301
335
  assertKnownRole(start, "modelRole");
@@ -318,20 +352,25 @@ export function resolveTaskModel(spec, deps) {
318
352
  };
319
353
  }
320
354
  const { promptRole: startPromptRole, systemPrompt: startSystemPrompt } = startParts;
355
+ let firstUnheld;
321
356
  for (const role of [start, ...FALLBACK[start]]) {
322
- const parts = specParts(merged[role], `roles.${role}`);
323
- const fromParts = partsModel(parts, deps.models, `roles.${role}`);
357
+ const read = seatRead(specParts(merged[role], `roles.${role}`), deps.models, `roles.${role}`, role);
358
+ const parts = read.parts;
359
+ firstUnheld ??= read.unheld;
360
+ const fromParts = read.model;
324
361
  const model = fromParts ?? roleTierModel(role, deps.models);
325
362
  if (model) {
326
363
  const modelRef = fromParts !== undefined ? (parts.model ?? model) : (ROLE_TIER_DEFAULTS[role] ?? model);
327
364
  return { model, modelRef, thinking: spec.thinking ?? parts.thinking, promptRole: startPromptRole, systemPrompt: startSystemPrompt };
328
365
  }
329
366
  }
367
+ if (firstUnheld !== undefined)
368
+ throw unheldSeatRefusal(firstUnheld);
330
369
  throw new Error(`No model for role "${start}": set TaskSpec.model, or configure RunnerDeps.roles / TaskSpec.roles["${start}"] (or a "default" role). A "select" RoleSpec also fails here if no catalog model matches.`);
331
370
  }
332
371
  export function roleModelIfSet(role, spec, deps) {
333
372
  const merged = mergeRoles(deps.roles, spec.roles);
334
373
  const seat = `roles.${role}`;
335
374
  const parts = specParts(merged[role], seat);
336
- return partsModel(parts, deps.models, seat) ?? roleTierModel(role, deps.models);
375
+ return seatRead(parts, deps.models, seat, role).model ?? roleTierModel(role, deps.models);
337
376
  }
@@ -0,0 +1,40 @@
1
+ export declare const RUN_ORIGINS: readonly ["scheduled"];
2
+ export type RunOrigin = (typeof RUN_ORIGINS)[number];
3
+ /** Membership test for {@link RunOrigin}: the one a host checks the word it is about to stamp against. */
4
+ export declare function isRunOrigin(v: unknown): v is RunOrigin;
5
+ /** The checkpoint row's recorded word: absent or a member passes; anything else is a row this engine cannot resume under
6
+ * (`config.run_origin_invalid`). A resume's screen asks it after the row's reader requirements were judged, so a row a newer
7
+ * engine wrote is refused as newer first. */
8
+ export declare function screenRecordedRunOrigin(recorded: unknown): RunOrigin | undefined;
9
+ /**
10
+ * THE door of the declared word, and the leg's one reading of it. `declared` is the leg's config's word — the task spec's on a
11
+ * fresh leg, where it is the objective's; `row` is present on a resumed leg only and carries the word its checkpoint recorded
12
+ * and, when the resume hands over inputs to open the leg with (a wake), the newest one's word as `opening.word`
13
+ * ({@link wakeOpening}). On a fresh leg absent passes as absent, a member passes, and anything else present is refused loudly
14
+ * (`config.run_origin_invalid`), never folded to "the host said nothing" (that silence is exactly the invisibility the word
15
+ * exists to end).
16
+ *
17
+ * A resume config carries NO word, any value refused: a resume hands the engine no objective, so the field would have nothing
18
+ * to describe — the resumed leg's word is its opening input's when a wake opened it (absent included: a message that says
19
+ * nothing is not the row's word), the row's otherwise. Prepare's config doors and a resume's screen before the claim call this
20
+ * one function, so a resume prepare would refuse is refused while the row is pending.
21
+ */
22
+ export declare function runOriginOfLeg(declared: unknown, row?: {
23
+ readonly recorded: RunOrigin | undefined;
24
+ readonly opening?: {
25
+ readonly word: unknown;
26
+ };
27
+ }): RunOrigin | undefined;
28
+ /**
29
+ * The input that opens a woken leg: the NEWEST the wake hands over — its message, else the parked entry it delivers last
30
+ * (`parked` in `seq` order) — so a message-bearing wake and its atomic equivalent (`setPendingSteer` then a message-less wake)
31
+ * give the leg the same word. `undefined` when it hands over nothing. A decision on a parked leg opens nothing: what it
32
+ * delivers rides along with the answer, and the leg continues the row's word.
33
+ */
34
+ export declare function wakeOpening(parked: ReadonlyArray<{
35
+ readonly runOrigin?: unknown;
36
+ }>, message: {
37
+ readonly runOrigin?: unknown;
38
+ } | undefined): {
39
+ readonly word: unknown;
40
+ } | undefined;
@@ -0,0 +1,37 @@
1
+ import { describeRejectedValue } from "./tool-search-setting.js";
2
+ export const RUN_ORIGINS = Object.freeze(["scheduled"]);
3
+ const RUN_ORIGIN_SET = new Set(RUN_ORIGINS);
4
+ export function isRunOrigin(v) {
5
+ return RUN_ORIGIN_SET.has(v);
6
+ }
7
+ const WORDS = RUN_ORIGINS.map((w) => JSON.stringify(w)).join(" | ");
8
+ function refusal(message) {
9
+ const e = new Error(message);
10
+ e.code = "config.run_origin_invalid";
11
+ return e;
12
+ }
13
+ export function screenRecordedRunOrigin(recorded) {
14
+ if (recorded === undefined || isRunOrigin(recorded))
15
+ return recorded;
16
+ throw refusal(`the checkpoint row's runOrigin is ${describeRejectedValue(recorded)}, not a run origin this engine knows (${WORDS}) — the row cannot be resumed under a word nobody can read`);
17
+ }
18
+ export function runOriginOfLeg(declared, row) {
19
+ if (row !== undefined && declared !== undefined) {
20
+ throw refusal(`a resume config declares runOrigin ${describeRejectedValue(declared)} — a resume carries no run origin in its config: omit the field. ` +
21
+ `The resumed leg reads the word of the input that opens it — a wake states it on its message (message.runOrigin) — or else the parked row's (CheckpointSummary.runOrigin)`);
22
+ }
23
+ if (declared !== undefined && !isRunOrigin(declared)) {
24
+ throw refusal(`runOrigin ${describeRejectedValue(declared)} is not a run origin (${WORDS}) — omit it when the task was not started by the deployment's scheduler; an unreadable declaration is refused, never read as "not stated".`);
25
+ }
26
+ if (row === undefined)
27
+ return declared;
28
+ const opening = row.opening === undefined ? undefined : { word: row.opening.word };
29
+ if (opening !== undefined && opening.word !== undefined && !isRunOrigin(opening.word)) {
30
+ throw refusal(`the input that opens this leg declares runOrigin ${describeRejectedValue(opening.word)}, not a run origin (${WORDS}) — an unreadable declaration is refused, never read as "not stated".`);
31
+ }
32
+ return opening !== undefined ? opening.word : row.recorded;
33
+ }
34
+ export function wakeOpening(parked, message) {
35
+ const newest = message ?? parked[parked.length - 1];
36
+ return newest === undefined ? undefined : { word: newest.runOrigin };
37
+ }
@@ -1,46 +1,37 @@
1
- /**
2
- * The advertised-writable-directory seat — ONE rule for every directory the prompt tells the model
3
- * it may write with the file tools:
4
- *
5
- * a directory the prompt advertises as writable is a directory the root fence ADMITS; the same
6
- * admission decides the hole and the teaching, so a directory the fence cannot admit is neither
7
- * opened nor taught, and the skip is announced.
8
- *
9
- * Two advertisers share it: the deployment's scratchpad (`TaskSpec.envFacts.scratchpadDir`, spoken
10
- * by the `# Environment` block) and the memory engine's write root (spoken by the `# Memory`
11
- * instruction, "write to it directly with the Write tool"). Before this seat each advertiser judged
12
- * on its own: the scratchpad opened its hole in the hands phase, the memory instruction checked only
13
- * that a `Write` tool was mounted — and the fence refused the very path the instruction named
14
- * (`path_not_in_root`), a contradictory gate that taught the model to route around the tools.
15
- *
16
- * Admission = fail-closed canonicalization through the SAME ExecutionEnv the fence judges with (a
17
- * raw or dangling entry is never admitted — the ancestor-canonicalize fallback would let a symlinked
18
- * prefix carry writes outside every root). An advertiser that OWNS its directory's creation may ask
19
- * for materialization on a DEFINITIVE `not_found` (the exclusive-create marker, so a concurrently
20
- * planted path is never written through); an advertiser whose directory is created elsewhere passes
21
- * no marker and an absent directory narrows.
22
- *
23
- * A directory the fence already holds is never admitted as a HOLE in it: a candidate that resolves onto
24
- * a root — or above one — would turn that whole root into the advertised, write-gate-exempt domain, so
25
- * an ordinary source write inside the workspace would stop asking. One predicate
26
- * ({@link swallowedFenceRoot}) states that, and the write gate's configured domains apply the same one.
27
- *
28
- * Reverse check (the seat's own invariant): nothing enters `roots` except through `admit`, and every
29
- * caller of `admit` is an advertiser deciding its advertisement off the returned verdict — so no
30
- * directory reaches the ROOTS FENCE through this seat without the prompt advertising it, and none
31
- * the prompt advertises is refused by that fence.
32
- *
33
- * The invariant is about this seat, not about the whole write surface: under an open write face
34
- * ({@link import("../../tools/fs/containment-face.js").ContainmentFace}) the roots fence judges
35
- * nothing, so what the prompt advertises is a floor rather than the whole list — the `# Environment`
36
- * block says so in its own line, and the advertisement stays true (these directories ARE writable).
37
- */
38
1
  import type { ExecutionEnv } from "../../internal/harness.js";
2
+ /** The code a declared session plan file that cannot be held as stated refuses the run with (`TaskSpec.planFile`). */
3
+ export declare const PLAN_FILE_INVALID_CODE = "config.plan_file_invalid";
4
+ /** The coded refusal for `TaskSpec.planFile`: the value as given and why it cannot be the session's plan file. */
5
+ export declare function planFileInvalid(value: unknown, why: string): Error & {
6
+ code: string;
7
+ detail: {
8
+ planFile: unknown;
9
+ reason: string;
10
+ };
11
+ };
12
+ /** The declared plan file's SHAPE (no I/O): a non-empty absolute string in lexical normal form, else the coded refusal. */
13
+ export declare function checkedPlanFileShape(value: unknown): string | undefined;
14
+ /** How long a plan file's path may be: the longest path a platform spells (Linux PATH_MAX) — it is told to the model whole. */
15
+ export declare const PLAN_PATH_MAX = 4096;
16
+ /** How the plan file is told to the model (the plan-exit tool, the planning frames, the post-compaction reference): whole
17
+ * and verbatim — {@link checkedPlanFileShape} refuses a declared path this would re-spell, so for an admitted file this is
18
+ * the path itself; the defusing stays as the trusted line's guard. The ONE renderer: every teller reads its answer. */
19
+ export declare function planFileShown(path: string): string;
20
+ /** The most of a plan file the plan's readers take (1 MiB): a file past it is refused, never truncated into a plan. */
21
+ export declare const PLAN_FILE_MAX_BYTES: number;
22
+ /** What the session plan file holds: its text (`undefined` = not written yet — absent, or blank), or why it could not be read. */
23
+ export type PlanFileReading = {
24
+ readonly ok: true;
25
+ readonly text: string | undefined;
26
+ } | {
27
+ readonly ok: false;
28
+ readonly reason: string;
29
+ };
39
30
  export interface AdvertisedWritableDir {
40
31
  /** The directory as the advertisement spells it. */
41
32
  path: string;
42
33
  /** Who advertises it — names the skip line and the trace. */
43
- advertiser: "scratchpad" | "memory";
34
+ advertiser: "scratchpad" | "memory" | "plan";
44
35
  /**
45
36
  * How the directory comes to exist when the env reports it absent. The advertiser that owns the
46
37
  * directory's creation supplies the marker file name for the atomic exclusive-create
@@ -122,6 +113,34 @@ export declare class AdvertisedWritableDirs {
122
113
  /** The admitted roots, CANONICAL, in admission order, deduplicated. The hands phase folds this list into the
123
114
  * write-capable containment allowlist before the toolkit compiles; it is not a live view after that. */
124
115
  get roots(): readonly string[];
116
+ /** The session plan file as admitted — its declared spelling and its frozen canonical key (the key is also on
117
+ * {@link roots}) — or `undefined` when none was declared. The write-protection judge reads it to exempt exactly
118
+ * this file; nothing else holds a copy. */
119
+ get planFile(): {
120
+ readonly spelled: string;
121
+ readonly key: string;
122
+ } | undefined;
123
+ private admittedPlanFile;
124
+ /**
125
+ * Admit the session plan file (`TaskSpec.planFile`, already shape-checked by {@link checkedPlanFileShape}): a FILE, so
126
+ * its key is the CANONICAL PARENT joined with the declared name — frozen here like every key this seat holds, never
127
+ * re-resolved — and the leaf is looked at without following links. The file need not exist yet (the model creates it),
128
+ * and it is never materialized: its directory is the host's to create.
129
+ *
130
+ * Refusing, not skipping: the leaf is a symbolic link (admitting where it points would let the declaration exempt any
131
+ * file the link names), a directory or another non-file kind; the parent does not resolve, or resolves to something
132
+ * other than a directory; or the key would hold a root the fence already holds (the seat's one containment rule).
133
+ * Each throws {@link planFileInvalid} — the plan file decides what the plan-exit tool reads, so a declared file the
134
+ * fence narrowed away would teach a tool over a file nobody can write.
135
+ */
136
+ admitPlanFile(spelled: string): Promise<string>;
137
+ /**
138
+ * What the admitted session plan file holds right now — the ONE reader of the plan's contents (the plan-exit tool and the
139
+ * post-compaction reference both read here), through the environment the fence judges with, at the key admitted (frozen,
140
+ * never re-resolved), the leaf looked at without following a link: a file later replaced by a link, a directory or
141
+ * another kind is refused with the reason, never read through.
142
+ */
143
+ readPlanFile(signal?: AbortSignal): Promise<PlanFileReading>;
125
144
  /** What became of an advertiser's directory: admitted, skipped (announced), or never asked (the advertiser
126
145
  * had nothing to advertise, or decided not to). The prompt side reads this to withhold an advertisement. */
127
146
  verdictOf(advertiser: AdvertisedWritableDir["advertiser"]): "admitted" | "skipped" | "not-asked";
@@ -1,4 +1,43 @@
1
+ import { posix, win32 } from "node:path";
1
2
  import { isWithin } from "./session-rule-policy.js";
3
+ import { isWinFormPath, normalizeAbsPathLexically } from "../../tools/fs/safety.js";
4
+ import { validatePath } from "../effective-path-target.js";
5
+ import { inlineUntrusted } from "../untrusted-text.js";
6
+ export const PLAN_FILE_INVALID_CODE = "config.plan_file_invalid";
7
+ export function planFileInvalid(value, why) {
8
+ let shown;
9
+ try {
10
+ shown = JSON.stringify(value) ?? String(value);
11
+ }
12
+ catch {
13
+ shown = typeof value;
14
+ }
15
+ const e = new Error(`TaskSpec.planFile ${shown} ${why} — the plan file must be the absolute path, in lexical normal form, of a regular file (or of a file not yet written) whose directory exists, on a leg whose file tools can write; ` +
16
+ `a plan file the gates cannot hold as declared would teach the model a file nobody can write, so the run is refused rather than started without it.`);
17
+ e.code = PLAN_FILE_INVALID_CODE;
18
+ e.detail = { planFile: value, reason: why };
19
+ return e;
20
+ }
21
+ export function checkedPlanFileShape(value) {
22
+ if (value === undefined)
23
+ return undefined;
24
+ if (typeof value !== "string")
25
+ throw planFileInvalid(value, `is a ${value === null ? "null" : typeof value}, not a string`);
26
+ if (value.length === 0)
27
+ throw planFileInvalid(value, "is an empty string");
28
+ if (validatePath(value, { intent: "validate-coordinate" }) === undefined)
29
+ throw planFileInvalid(value, "is not an absolute path");
30
+ if (normalizeAbsPathLexically(value) !== value)
31
+ throw planFileInvalid(value, `is not in lexical normal form (it reads as ${normalizeAbsPathLexically(value)})`);
32
+ if (inlineUntrusted(value, PLAN_PATH_MAX) !== value)
33
+ throw planFileInvalid(value, `cannot be told to the model verbatim (a control character, a run of whitespace, an envelope marker, or more than ${PLAN_PATH_MAX} characters)`);
34
+ return value;
35
+ }
36
+ export const PLAN_PATH_MAX = 4096;
37
+ export function planFileShown(path) {
38
+ return inlineUntrusted(path, PLAN_PATH_MAX);
39
+ }
40
+ export const PLAN_FILE_MAX_BYTES = 1024 * 1024;
2
41
  export function swallowedFenceRoot(domainCanonical, fenceRootsCanonical) {
3
42
  for (const root of fenceRootsCanonical) {
4
43
  if (root && isWithin(domainCanonical, root))
@@ -51,6 +90,93 @@ export class AdvertisedWritableDirs {
51
90
  get roots() {
52
91
  return this.admitted;
53
92
  }
93
+ get planFile() {
94
+ return this.admittedPlanFile;
95
+ }
96
+ admittedPlanFile;
97
+ async admitPlanFile(spelled) {
98
+ const win = isWinFormPath(spelled);
99
+ const pathOps = win ? win32 : posix;
100
+ const parent = pathOps.dirname(spelled);
101
+ const name = pathOps.basename(spelled);
102
+ if (!name || parent === spelled)
103
+ throw planFileInvalid(spelled, "names no file below a directory");
104
+ const leaf = await this.env.fileInfo(spelled);
105
+ if (leaf.ok && leaf.value.kind !== "file")
106
+ throw planFileInvalid(spelled, leaf.value.kind === "symlink" ? "is a symbolic link (the plan file must be the file itself, not a link to one)" : `is a ${leaf.value.kind}, not a file`);
107
+ if (!leaf.ok && leaf.error.code !== "not_found")
108
+ throw planFileInvalid(spelled, `could not be examined (${leaf.error.code}: ${leaf.error.message})`);
109
+ const parentCanonical = await this.env.canonicalPath(parent);
110
+ if (!parentCanonical.ok)
111
+ throw planFileInvalid(spelled, `has a directory that does not resolve (${parentCanonical.error.code}: ${parentCanonical.error.message}) — the host creates the plan file's directory before the run`);
112
+ const parentInfo = await this.env.fileInfo(parentCanonical.value);
113
+ if (!parentInfo.ok || parentInfo.value.kind !== "directory")
114
+ throw planFileInvalid(spelled, `has a parent ${parentCanonical.value} that is not a directory`);
115
+ const own = leaf.ok ? await this.env.canonicalPath(spelled) : undefined;
116
+ if (own !== undefined && !own.ok)
117
+ throw planFileInvalid(spelled, `could not be resolved (${own.error.code}: ${own.error.message})`);
118
+ const joined = own?.ok === true ? own : await this.env.joinPath([parentCanonical.value, name]);
119
+ if (!joined.ok)
120
+ throw planFileInvalid(spelled, `could not be joined below its directory (${joined.error.code}: ${joined.error.message})`);
121
+ const key = joined.value;
122
+ await this.resolveDeclaredRoots();
123
+ const swallowed = swallowedFenceRoot(key, [...this.fenceRoots, ...this.admitted]);
124
+ if (swallowed !== undefined && swallowed !== key)
125
+ throw planFileInvalid(spelled, `resolves to ${key}, which holds the root ${swallowed}`);
126
+ if (!this.admitted.includes(key))
127
+ this.admitted.push(key);
128
+ this.admittedPlanFile = Object.freeze({ spelled, key });
129
+ this.verdicts.set("plan", "admitted");
130
+ return key;
131
+ }
132
+ async readPlanFile(signal) {
133
+ const planFile = this.admittedPlanFile;
134
+ if (planFile === undefined)
135
+ return { ok: false, reason: "this run admitted no plan file" };
136
+ const canonical = await this.env.canonicalPath(planFile.key, signal);
137
+ if (!canonical.ok)
138
+ return canonical.error.code === "not_found" ? { ok: true, text: undefined } : { ok: false, reason: `${canonical.error.code}: ${canonical.error.message}` };
139
+ if (canonical.value !== planFile.key)
140
+ return { ok: false, reason: `it now resolves to ${canonical.value} (a link replaced it or one of its directories), which is not read through` };
141
+ let bytes;
142
+ if (this.env.openBound !== undefined) {
143
+ const held = await this.env.openBound(planFile.key, signal);
144
+ if (!held.ok)
145
+ return held.error.code === "not_found" ? { ok: true, text: undefined } : { ok: false, reason: `${held.error.code}: ${held.error.message}` };
146
+ try {
147
+ if (held.value.kind !== "file")
148
+ return { ok: false, reason: `it is now a ${held.value.kind}` };
149
+ const read = await held.value.readBytes(PLAN_FILE_MAX_BYTES, signal);
150
+ if (!read.ok)
151
+ return { ok: false, reason: `${read.error.code}: ${read.error.message}` };
152
+ bytes = read.value;
153
+ }
154
+ finally {
155
+ await held.value.close();
156
+ }
157
+ }
158
+ else {
159
+ const leaf = await this.env.fileInfo(planFile.key, signal);
160
+ if (!leaf.ok)
161
+ return leaf.error.code === "not_found" ? { ok: true, text: undefined } : { ok: false, reason: `${leaf.error.code}: ${leaf.error.message}` };
162
+ if (leaf.value.kind !== "file")
163
+ return { ok: false, reason: leaf.value.kind === "symlink" ? "it is now a symbolic link, which is not read through" : `it is now a ${leaf.value.kind}` };
164
+ if (leaf.value.size > PLAN_FILE_MAX_BYTES)
165
+ return { ok: false, reason: `it is ${leaf.value.size} bytes, over the ${PLAN_FILE_MAX_BYTES} a plan is read up to` };
166
+ const read = await this.env.readBinaryFile(planFile.key, signal);
167
+ if (!read.ok)
168
+ return read.error.code === "not_found" ? { ok: true, text: undefined } : { ok: false, reason: `${read.error.code}: ${read.error.message}` };
169
+ const after = await this.env.canonicalPath(planFile.key, signal);
170
+ const afterLeaf = await this.env.fileInfo(planFile.key, signal);
171
+ if (!after.ok || after.value !== planFile.key || !afterLeaf.ok || afterLeaf.value.kind !== "file")
172
+ return { ok: false, reason: "it changed while it was read (a link or another object replaced it), so it is not read through" };
173
+ if (read.value.length > PLAN_FILE_MAX_BYTES)
174
+ return { ok: false, reason: `it is ${read.value.length} bytes, over the ${PLAN_FILE_MAX_BYTES} a plan is read up to` };
175
+ bytes = read.value;
176
+ }
177
+ const text = new TextDecoder("utf-8").decode(bytes);
178
+ return { ok: true, text: text.trim() === "" ? undefined : text };
179
+ }
54
180
  verdictOf(advertiser) {
55
181
  return this.verdicts.get(advertiser) ?? "not-asked";
56
182
  }
@@ -1,6 +1,7 @@
1
- import type { AnnouncedListingSnapshot, AnnouncedListingSnapshotInput, AnnouncedMcpFailure } from "../../internal/harness.js";
1
+ import type { AnnouncedListingSnapshot, AnnouncedListingSnapshotInput } from "../../internal/harness.js";
2
2
  import type { AnnounceOnceSink } from "./contracts.js";
3
3
  import type { McpDroppedTool, McpServerStatus } from "../mcp.js";
4
+ import type { McpUnavailableEntry } from "../mcp-failure.js";
4
5
  import type { RunnerDeps } from "../types.js";
5
6
  /** Upper bound on the advisory-digest arm kept in the record (oldest dropped past it). A digest is
6
7
  * 64 hex chars; a session accumulates a handful of distinct advisories, never hundreds — the bound
@@ -75,13 +76,13 @@ export declare function flushOwedAnnouncedSnapshot(prepared: {
75
76
  */
76
77
  export declare function settleMcpUnavailable(prepared: {
77
78
  readonly mcpUnavailable?: {
78
- pending: AnnouncedMcpFailure[];
79
+ pending: McpUnavailableEntry[];
79
80
  };
80
81
  readonly announcedListingsRef: AnnouncedListingSnapshotInput;
81
82
  readonly frameReceipts: {
82
83
  listingSnapshotOwed: boolean;
83
84
  };
84
- }, delivered: ReadonlyArray<AnnouncedMcpFailure>): void;
85
+ }, delivered: ReadonlyArray<McpUnavailableEntry>): void;
85
86
  /** The run-local ledger — see the module header for the two commit disciplines it serves. */
86
87
  export interface AnnounceOnceLedger {
87
88
  /** The nearest announced snapshot on the branch as read at prepare (undefined = pre-entry
@@ -109,7 +110,7 @@ export interface AnnounceOnceLedger {
109
110
  * bounded at intake, the reminder's own bounds) MINUS the pairs already announced on this branch.
110
111
  * As a side effect the record's `mcpFailed` arm is pruned to the pairs that are STILL failing —
111
112
  * a recovered server leaves the record silently. Call once per prepare. */
112
- mcpFailuresToAnnounce(statuses: ReadonlyArray<McpServerStatus>): AnnouncedMcpFailure[];
113
+ mcpFailuresToAnnounce(statuses: ReadonlyArray<McpServerStatus>): McpUnavailableEntry[];
113
114
  /** Remove, IN PLACE, the dropped-tool entries whose model-facing digest is already recorded (the
114
115
  * frame was delivered on an earlier run of this session). The operator line about each entry is a
115
116
  * separate digest — run that loop BEFORE pruning so both faces are judged on the full list. */
@@ -36,6 +36,7 @@ export function withAnnounceDigests(existing, add) {
36
36
  }
37
37
  return out.length > ANNOUNCE_ONCE_MAX_DIGESTS ? out.slice(out.length - ANNOUNCE_ONCE_MAX_DIGESTS) : out;
38
38
  }
39
+ const toldAuthorization = (a) => `needs authorization (${a.reason}, ${createHash("sha256").update(JSON.stringify([a.reason, a.authorizeUrl ?? ""])).digest("hex").slice(0, 16)})`;
39
40
  function sameFailure(a, b) {
40
41
  return a.name === b.name && a.error === b.error;
41
42
  }
@@ -49,7 +50,8 @@ export async function flushOwedAnnouncedSnapshot(prepared) {
49
50
  }
50
51
  export function settleMcpUnavailable(prepared, delivered) {
51
52
  prepared.mcpUnavailable?.pending.splice(0, delivered.length);
52
- prepared.announcedListingsRef.mcpFailed = [...(prepared.announcedListingsRef.mcpFailed ?? []), ...delivered];
53
+ const told = delivered.map(({ name, error }) => ({ name, ...(error !== undefined ? { error } : {}) }));
54
+ prepared.announcedListingsRef.mcpFailed = [...(prepared.announcedListingsRef.mcpFailed ?? []), ...told];
53
55
  prepared.frameReceipts.listingSnapshotOwed = true;
54
56
  }
55
57
  export async function loadAnnounceOnceLedger(session, checkpointMirror, onError) {
@@ -94,7 +96,7 @@ export async function loadAnnounceOnceLedger(session, checkpointMirror, onError)
94
96
  mcpFailuresToAnnounce: (statuses) => {
95
97
  const current = statuses
96
98
  .filter((s) => s.status === "failed")
97
- .map((s) => ({ name: inlineUntrusted(s.name, 160), ...(s.error !== undefined ? { error: inlineUntrusted(s.error, 240) } : {}) }));
99
+ .map((s) => ({ name: inlineUntrusted(s.name, 160), ...(s.authorization !== undefined ? { error: toldAuthorization(s.authorization), authorization: { ...s.authorization } } : s.error !== undefined ? { error: inlineUntrusted(s.error, 240) } : {}) }));
98
100
  const carried = mcpFailed.filter((r) => current.some((c) => sameFailure(c, r)));
99
101
  if (carried.length !== mcpFailed.length)
100
102
  dirty = true;
@@ -109,10 +109,10 @@ export function createApprovedCallScreen(input) {
109
109
  const subject = `this call to "${toolName}"`;
110
110
  const screened = await screening.screen(args, subject);
111
111
  if (screened.kind === "refused")
112
- return { refused: screened.reason };
112
+ return { refused: screened.reason, ...(screened.extension !== undefined ? { extension: screened.extension } : {}) };
113
113
  const r = screened.answer;
114
114
  if (r?.action === "deny")
115
- return { refused: screening.deniedReason(r) };
115
+ return { refused: screening.deniedReason(r), ...(screened.answeredBy !== undefined ? { extension: screened.answeredBy } : {}) };
116
116
  if (r !== undefined && policyCannotAnswer(r, decidedBy))
117
117
  return { refused: `a PreToolUse hook requires a person's approval for ${subject}, and this approval was the deployment's policy — not executed` };
118
118
  const context = r?.additionalContext;
@@ -3,10 +3,10 @@ import { type PostureFacts } from "../auto-mode-directive.js";
3
3
  import type { Prepared } from "./contracts.js";
4
4
  /**
5
5
  * The facts the posture composition reads, as the leg IS now: the live effective mode and ask answer, the plan-exit
6
- * tool's presence on the minted roster, and the minted delegation identity. The one place a leg's facts are assembled —
6
+ * tool's presence on the minted roster, the minted delegation identity, and the session plan file the run admitted. The one place a leg's facts are assembled —
7
7
  * the leg's first turn, a resumed continuation, a continuing boundary and a landed compaction all ask through it.
8
8
  */
9
- export declare function postureFactsOf(prepared: Pick<Prepared, "approvalPosture" | "toolRoster" | "hookIdentity">): PostureFacts;
9
+ export declare function postureFactsOf(prepared: Pick<Prepared, "approvalPosture" | "toolRoster" | "hookIdentity" | "advertisedWritableDirs">): PostureFacts;
10
10
  /**
11
11
  * The posture question, asked of the ACTIVE context: the frames the leg's mode facts owe now (exits of retired
12
12
  * families, the owed frame or its cadence's restatement — `composePostureFrames`), minted as one carrier text —
@@ -18,7 +18,7 @@ export declare function postureFactsOf(prepared: Pick<Prepared, "approvalPosture
18
18
  * function's own carriers and a landed compaction (which asks with `"always"`). A context that cannot be read
19
19
  * answers "nothing standing": the owed frame is restated rather than withheld.
20
20
  */
21
- export declare function owedPostureText(prepared: Pick<Prepared, "approvalPosture" | "toolRoster" | "hookIdentity" | "session" | "reminderMark" | "postureFrameRef">, ask: "always" | "on_change"): Promise<string | undefined>;
21
+ export declare function owedPostureText(prepared: Pick<Prepared, "approvalPosture" | "toolRoster" | "hookIdentity" | "advertisedWritableDirs" | "session" | "reminderMark" | "postureFrameRef">, ask: "always" | "on_change"): Promise<string | undefined>;
22
22
  /** The posture's COMPACTION arm: after a landed compaction the runner asks the posture question of the compacted
23
23
  * context and appends what it owes as one engine-minted message, before any reader of the new baseline (the next
24
24
  * model request included). A leg that owes no posture registers nothing: a compaction only REMOVES frames, and a
@@ -35,7 +35,7 @@ export declare function postureRestateOption(prepared: Prepared): Pick<MaybeComp
35
35
  * of every engine frame written at a boundary, the git frame's re-assert and the compaction itself: the run continues
36
36
  * and the failure is reported, `onError` phase `degraded`). Never throws.
37
37
  */
38
- export declare function appendOwedPosture(prepared: Pick<Prepared, "approvalPosture" | "toolRoster" | "hookIdentity" | "session" | "reminderMark" | "postureFrameRef" | "batchHaltRef" | "frameReceipts">, ask: "always" | "on_change"): Promise<void>;
38
+ export declare function appendOwedPosture(prepared: Pick<Prepared, "approvalPosture" | "toolRoster" | "hookIdentity" | "advertisedWritableDirs" | "session" | "reminderMark" | "postureFrameRef" | "batchHaltRef" | "frameReceipts">, ask: "always" | "on_change"): Promise<void>;
39
39
  /** The declared output style's frame as one engine-marked reminder — the one spelling every site that states it directly
40
40
  * (a resumed leg's continuation, a boundary a queued input continues) mints. */
41
41
  export declare function mintOutputStyleReminder(prepared: Pick<Prepared, "outputStyleFrame" | "reminderMark">): string | undefined;
@@ -49,6 +49,15 @@ export declare function frameCarried(ledger: Prepared["frameReceipts"], source:
49
49
  * carries it ({@link frameCarried}). Both frames keep the posture's halt rule. The guarantee is read synchronously, at
50
50
  * the call, before any await — a boundary with nothing queued returns the posture's own promise.
51
51
  */
52
- export declare function appendBoundaryFrames(prepared: Pick<Prepared, "approvalPosture" | "toolRoster" | "hookIdentity" | "session" | "reminderMark" | "postureFrameRef" | "batchHaltRef" | "outputStyleFrame" | "harness" | "frameReceipts">, turnOwesRequest: boolean): Promise<void>;
52
+ export declare function appendBoundaryFrames(prepared: Pick<Prepared, "approvalPosture" | "toolRoster" | "hookIdentity" | "advertisedWritableDirs" | "session" | "reminderMark" | "postureFrameRef" | "batchHaltRef" | "outputStyleFrame" | "harness" | "frameReceipts">, turnOwesRequest: boolean): Promise<void>;
53
+ /**
54
+ * The session plan file's post-compaction reference (the reference's `plan_file_reference`, CC 2.1.309 `Tmr` (cli309.js:265943)): a compaction
55
+ * summarizes away the turns that wrote the plan, so a leg whose run admitted a plan file that holds a plan is told where
56
+ * it is and what it says, in any mode — the reference's own sentences, the plan fenced as the untrusted model text it is.
57
+ * Read through the seat's one reader; an absent or blank file says nothing (there is no plan to refer to), and an
58
+ * unreadable one is not guessed at. One engine-minted message, appended like the posture's; a failed append is reported
59
+ * and never fails the landed compaction.
60
+ */
61
+ export declare function planFileRestateOption(prepared: Prepared): Pick<MaybeCompactOptions, "planFileRestate">;
53
62
  /** Every post-compaction restatement the turn boundary registers, at one spread site. */
54
- export declare function compactionRestateOptions(prepared: Prepared): Pick<MaybeCompactOptions, "gitRestate" | "postureRestate" | "advisorRestate">;
63
+ export declare function compactionRestateOptions(prepared: Prepared): Pick<MaybeCompactOptions, "gitRestate" | "postureRestate" | "planFileRestate" | "advisorRestate">;