@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,5 +1,8 @@
1
- import { existsSync, readFileSync } from "node:fs";
1
+ import { lstatSync, readFileSync } from "node:fs";
2
2
  import { dirname, join, resolve } from "node:path";
3
+ import { err, FileError, ok } from "../../internal/harness.js";
4
+ import { StubExecutionEnv } from "../stub-env.js";
5
+ import { thrownText } from "../thrown-value.js";
3
6
  import { canonicalize } from "./layout.js";
4
7
  function pathSegmentsDualFamily(p) {
5
8
  return p.split(/[\\/]/).filter(Boolean);
@@ -178,10 +181,54 @@ export function parseProjectMarker(body) {
178
181
  return null;
179
182
  return { projectId };
180
183
  }
181
- function gitRootOf(dir) {
184
+ export const hostProjectMarkerFs = {
185
+ exists(path) {
186
+ try {
187
+ return Promise.resolve(ok(lstatSync(path, { throwIfNoEntry: false }) !== undefined));
188
+ }
189
+ catch (e) {
190
+ const code = e.code;
191
+ return Promise.resolve(code === "ENOTDIR" ? ok(false) : err(new FileError("unknown", `could not stat ${path}: ${thrownText(e)}`, path)));
192
+ }
193
+ },
194
+ readTextFile(path) {
195
+ try {
196
+ return Promise.resolve(ok(readFileSync(path, "utf8")));
197
+ }
198
+ catch (e) {
199
+ return Promise.resolve(err(new FileError("unknown", `could not read ${path}: ${thrownText(e)}`, path)));
200
+ }
201
+ },
202
+ };
203
+ export function projectMarkerFsOf(env) {
204
+ return env instanceof StubExecutionEnv ? hostProjectMarkerFs : env;
205
+ }
206
+ function identityError(code, message) {
207
+ const e = new Error(message);
208
+ e.code = code;
209
+ return e;
210
+ }
211
+ async function readOrFault(path, read) {
212
+ let r;
213
+ try {
214
+ r = await read();
215
+ }
216
+ catch (e) {
217
+ r = { ok: false, error: { message: thrownText(e) } };
218
+ }
219
+ if (!r.ok)
220
+ throw identityError("config.memory_project_marker", `project marker lookup could not read ${path}: ${r.error.message}`);
221
+ return r.value;
222
+ }
223
+ const existsOrFault = (fs, path) => readOrFault(path, () => fs.exists(path));
224
+ function isMarkerFault(e) {
225
+ const code = e instanceof Error ? e.code : undefined;
226
+ return code === "config.memory_project_marker" || code === "config.memory_project_marker_nested";
227
+ }
228
+ async function gitRootOf(fs, dir) {
182
229
  let cur = resolve(dir);
183
230
  for (;;) {
184
- if (existsSync(join(cur, ".git")))
231
+ if (await existsOrFault(fs, join(cur, ".git")))
185
232
  return cur;
186
233
  const parent = dirname(cur);
187
234
  if (parent === cur)
@@ -189,18 +236,16 @@ function gitRootOf(dir) {
189
236
  cur = parent;
190
237
  }
191
238
  }
192
- export function resolveProjectId(rootDir) {
239
+ export async function resolveProjectId(fs, rootDir) {
193
240
  const dir = resolve(rootDir);
194
- const gitRoot = gitRootOf(dir);
241
+ const gitRoot = await gitRootOf(fs, dir);
195
242
  const projectRoot = gitRoot ?? dir;
196
243
  if (gitRoot !== undefined) {
197
244
  let cur = dir;
198
245
  while (cur !== gitRoot) {
199
- if (existsSync(join(cur, PROJECT_MARKER_PATH))) {
200
- const e = new Error(`nested project marker: ${join(cur, PROJECT_MARKER_PATH)} sits below the repo root (${gitRoot}) — ` +
246
+ if (await existsOrFault(fs, join(cur, PROJECT_MARKER_PATH))) {
247
+ throw identityError("config.memory_project_marker_nested", `nested project marker: ${join(cur, PROJECT_MARKER_PATH)} sits below the repo root (${gitRoot}) — ` +
201
248
  `v1 supports ONE marker at the repo root (design/142 §1.1); remove the nested marker or split the repo.`);
202
- e.code = "config.memory_project_marker_nested";
203
- throw e;
204
249
  }
205
250
  const parent = dirname(cur);
206
251
  if (parent === cur)
@@ -209,10 +254,34 @@ export function resolveProjectId(rootDir) {
209
254
  }
210
255
  }
211
256
  const markerFile = join(projectRoot, PROJECT_MARKER_PATH);
212
- if (!existsSync(markerFile))
257
+ if (!(await existsOrFault(fs, markerFile)))
213
258
  return null;
214
- const parsed = parseProjectMarker(readFileSync(markerFile, "utf8"));
259
+ const parsed = parseProjectMarker(await readOrFault(markerFile, () => fs.readTextFile(markerFile)));
215
260
  if (!parsed)
216
261
  return null;
217
262
  return { projectId: parsed.projectId, markerDir: projectRoot };
218
263
  }
264
+ export async function resolveSessionProject(fs, taskRoot, declared) {
265
+ if (declared !== undefined && (typeof declared !== "string" || !UUID_RE.test(declared))) {
266
+ const shown = typeof declared === "string" ? JSON.stringify(declared.slice(0, 64)) : typeof declared;
267
+ throw identityError("config.project_id_invalid", `TaskSpec.projectId must be a project UUID (the id a \`.sema/project\` marker carries), got ${shown}; the leg is refused rather than filed under no project.`);
268
+ }
269
+ const declaredId = declared?.toLowerCase();
270
+ let marker;
271
+ try {
272
+ marker = await resolveProjectId(fs, taskRoot);
273
+ }
274
+ catch (e) {
275
+ if (!isMarkerFault(e) || declaredId !== undefined)
276
+ throw e;
277
+ return { root: taskRoot, markerFault: e };
278
+ }
279
+ if (marker !== null) {
280
+ if (declaredId !== undefined && declaredId !== marker.projectId) {
281
+ throw identityError("config.project_identity_mismatch", `TaskSpec.projectId declares ${declaredId}, but this checkout's project marker ${join(marker.markerDir, PROJECT_MARKER_PATH)} carries ${marker.projectId} — ` +
282
+ `the leg is refused rather than filed under the wrong project. Declare the marker's id, or correct the marker.`);
283
+ }
284
+ return { root: taskRoot, project: { id: marker.projectId, source: "marker" } };
285
+ }
286
+ return declaredId !== undefined ? { root: taskRoot, project: { id: declaredId, source: "declared" } } : { root: taskRoot };
287
+ }
@@ -1,5 +1,11 @@
1
1
  import { type MemorySyncCursor } from "./sync.js";
2
2
  import { type MemoryBackend, type MemoryEntry, type PatchReport } from "./types.js";
3
+ /**
4
+ * The identity a sync cursor is bound to — the one mint of {@link MemorySyncCursor.store}: the physical root of
5
+ * the local File store (the path its root anchor records). A store without a directory has no root to bind a
6
+ * baseline to and is refused as a sync plane (`config.memory_sync_store`).
7
+ */
8
+ export declare function memorySyncStoreOf(backend: MemoryBackend): string;
3
9
  /** The injected HTTP seam — core never bundles a fetch. The deployment maps `path` (e.g.
4
10
  * `/v1/memory/sync/user%3Aalice`) onto its server base URL, attaches auth, and returns the
5
11
  * DECODED JSON body of a 2xx response; any non-2xx / network failure should THROW (the round then
@@ -81,7 +87,9 @@ export interface SyncMemoryScopeOptions {
81
87
  scope: string;
82
88
  /** The injected HTTP seam. */
83
89
  transport: MemorySyncTransport;
84
- /** The persisted cursor from the last completed round with this peer; absent = first round. */
90
+ /** The persisted cursor from the last completed round with this peer; absent = first round. A cursor
91
+ * for another scope, peer or local store — or one with no store binding — is refused
92
+ * (`config.memory_sync_cursor_mismatch`) before any I/O; sync with no cursor instead. */
85
93
  cursor?: MemorySyncCursor;
86
94
  /** Peer name for the cursor partition (defaults to the cursor's peer, else "central"). */
87
95
  peer?: string;
@@ -4,6 +4,32 @@ import { scanMemoryFileName, scanMemoryWrite } from "./scan.js";
4
4
  import { MAX_MEMORY_BYTES } from "../memory.js";
5
5
  import { reconcileMemoryEntries } from "./sync.js";
6
6
  import { MEMORY_ORIGIN_CAUSES } from "./types.js";
7
+ import { directoryPinOf } from "./dual-root.js";
8
+ import { landingPathOf } from "./layout.js";
9
+ function syncRefusal(code, message) {
10
+ const e = new Error(message);
11
+ e.code = code;
12
+ return e;
13
+ }
14
+ export function memorySyncStoreOf(backend) {
15
+ return syncStoreOf(backend).identity;
16
+ }
17
+ function syncStoreOf(backend) {
18
+ const pin = directoryPinOf(backend);
19
+ if (pin === undefined)
20
+ throw syncRefusal("config.memory_sync_store", "memory sync: the local store has no directory — a sync baseline is bound to a File store's root, and this store has none");
21
+ const root = landingPathOf(pin);
22
+ return { root, identity: `file:${root}` };
23
+ }
24
+ function refuseForeignCursor(cursor, scope, peer, store) {
25
+ const axis = [["scope", cursor.scope, scope], ["peer", cursor.peer, peer], ["store", cursor.store, store]];
26
+ for (const [name, got, want] of axis) {
27
+ if (got === want)
28
+ continue;
29
+ const found = got === undefined ? `has no ${name} binding` : `is for ${name} ${JSON.stringify(typeof got === "string" ? got : typeof got)}`;
30
+ throw syncRefusal("config.memory_sync_cursor_mismatch", `memory sync: cursor ${found}; this round's ${name} is ${JSON.stringify(want)} — a baseline taken elsewhere would misjudge every entry; run this round from no cursor`);
31
+ }
32
+ }
7
33
  function memorySyncPath(scope) {
8
34
  return `/v1/memory/sync/${encodeURIComponent(scope)}`;
9
35
  }
@@ -207,12 +233,9 @@ export async function syncMemoryScope(opts) {
207
233
  throw new Error("memory sync: scope must be a non-empty string");
208
234
  const peer = opts.peer ?? cursor?.peer ?? "central";
209
235
  const now = opts.now ?? Date.now;
210
- if (cursor !== undefined && cursor.scope !== scope) {
211
- throw new Error(`memory sync: cursor is for scope ${JSON.stringify(cursor.scope)}, not ${JSON.stringify(scope)}`);
212
- }
213
- if (cursor !== undefined && cursor.peer !== peer) {
214
- throw new Error(`memory sync: cursor is for peer ${JSON.stringify(cursor.peer)}, not ${JSON.stringify(peer)}`);
215
- }
236
+ const { root: storeRoot, identity: store } = syncStoreOf(backend);
237
+ if (cursor !== undefined)
238
+ refuseForeignCursor(cursor, scope, peer, store);
216
239
  for (const [name, v] of [["maxPushEntries", opts.maxPushEntries], ["maxPullEntries", opts.maxPullEntries], ["maxEntryBytes", opts.maxEntryBytes]]) {
217
240
  if (v !== undefined && (!Number.isSafeInteger(v) || v < 1)) {
218
241
  throw new Error(`memory sync: ${name} must be a positive integer (>= 1) when set, got ${String(v)}`);
@@ -341,7 +364,7 @@ export async function syncMemoryScope(opts) {
341
364
  }),
342
365
  ...deletePatches,
343
366
  ];
344
- const report = patches.length > 0 ? await backend.applyPatches(patches) : { applied: [], conflicts: [] };
367
+ const report = patches.length > 0 ? await backend.applyPatches(patches, { anchoredRoot: storeRoot }) : { applied: [], conflicts: [] };
345
368
  for (const c of report.conflicts) {
346
369
  conflicts.push({
347
370
  side: "local",
@@ -388,7 +411,7 @@ export async function syncMemoryScope(opts) {
388
411
  nextBaseRevs[op.id] = landedRev;
389
412
  }
390
413
  }
391
- nextCursor = { scope, peer, baseRevs: nextBaseRevs, updatedAtMs: now() };
414
+ nextCursor = { scope, peer, store, baseRevs: nextBaseRevs, updatedAtMs: now() };
392
415
  }
393
416
  return {
394
417
  ok: cursorAdvanced && conflicts.length === 0,
@@ -10,6 +10,11 @@ export interface MemorySyncCursor {
10
10
  scope: string;
11
11
  /** The PEER this cursor tracks (e.g. "central", a repo remote name) — one cursor per peer. */
12
12
  peer: string;
13
+ /** The LOCAL store the baseline was taken against (minted by `memorySyncStoreOf`, sync-client.ts).
14
+ * A sync over any other store refuses the cursor: the baseline describes another store's
15
+ * entries, and an id it holds that this store lacks would be pushed as a delete. Persist it
16
+ * verbatim with the rest of the cursor. */
17
+ store: string;
13
18
  /** id → rev at the last completed sync round with this peer. */
14
19
  baseRevs: Record<string, string>;
15
20
  /** Caller-injected clock (never Date.now inside the engine — clock-injection precedent). */
@@ -586,6 +586,12 @@ export interface MemoryAnnouncement {
586
586
  * degradation, applied-patch summary); `external` = out-of-session changes the backend's read-side
587
587
  * detected (disk rev ≠ ledger: adopted external edits + inbound-gate rejects). */
588
588
  kind: "gate" | "external";
589
+ /** The one scope this notice reports on — the queue it is filed under, and therefore who reads it:
590
+ * only a session that mounts this scope drains it. Required: a notice that cannot name one scope
591
+ * (a count over several scopes, a fact of the whole control plane, a session-level event with no
592
+ * scope in hand) is not a model-face notice at all — the engine sends it to the host's incident
593
+ * sink instead, so no session reads a name or a count of a scope it does not mount. */
594
+ scope: string;
589
595
  /** ms epoch at enqueue. */
590
596
  at: number;
591
597
  /** Optional producing-session id (repo-level event stream — Q-G: no worktree attribution in S2). */
@@ -61,14 +61,17 @@ export declare function modePolicyOf(mode: PermissionMode): ModePolicy;
61
61
  */
62
62
  export declare function modeAcceptsFileCommand(mode: PermissionMode, toolName: string, args: unknown): boolean;
63
63
  /** What the mode gate policy resolves paths against. `acceptDirs` = the leg's WRITE ROOTS (the task root plus every additional
64
- * working directory), the set `acceptEdits` allows writes inside — absent ⇒ the root alone; `exemptDirs` = the task's scratchpad,
65
- * never asked about; `roster` = the leg's live tool roster (who defined the called tool and its effect) and `readOnlyDeclared` =
66
- * whether the mounted tool of that name declares itself read-only, both read per call by {@link planRefusesWrite}. */
64
+ * working directory), the set `acceptEdits` allows writes inside — absent ⇒ the root alone; `roster` = the leg's live tool roster
65
+ * (who defined the called tool and its effect) and `readOnlyDeclared` = whether the mounted tool of that name declares itself
66
+ * read-only, both read per call by {@link planRefusesWrite}. What the gate never asks about is not a seat here: it is the run's
67
+ * advertised writable seat (scratchpad, memory root, session plan file), stamped on every request as
68
+ * `advertisedWritableRoots` — the fence's own admission, so the gate holds no second copy of it. */
67
69
  export interface ModeGateSeats {
68
70
  env: ExecutionEnv;
69
71
  rootPath: string;
70
- acceptDirs?: readonly string[];
71
- exemptDirs?: readonly string[];
72
+ /** A getter is read per call: the leg's live write roots (canonical identities), which move with its write location (an
73
+ * EnterWorktree switch). */
74
+ acceptDirs?: readonly string[] | (() => readonly string[]);
72
75
  roster?: {
73
76
  readonly current: ToolRoster | undefined;
74
77
  };
@@ -66,10 +66,11 @@ export function planRefusesWrite(req, roster, readOnlyDeclared) {
66
66
  }
67
67
  const planAsk = (message) => ({ action: "ask", message, decisionReason: "mode" });
68
68
  export function createModeGatePolicy(modeRef, seats) {
69
- const exemptDirs = seats.exemptDirs !== undefined && seats.exemptDirs.length > 0 ? { exemptDirs: seats.exemptDirs } : {};
70
- const askGate = createFsWriteGatePolicy({ env: seats.env, rootPath: seats.rootPath, ...exemptDirs, defaultWrite: "ask" });
71
- const acceptRootGate = createFsWriteGatePolicy({ env: seats.env, rootPath: seats.rootPath, acceptDirs: seats.acceptDirs !== undefined && seats.acceptDirs.length > 0 ? [...seats.acceptDirs] : [seats.rootPath], ...exemptDirs, defaultWrite: "ask" });
72
- const planGate = createFsWriteGatePolicy({ env: seats.env, rootPath: seats.rootPath, ...exemptDirs, defaultWrite: "ask", defaultAsk: (path, note) => planAsk(`Cannot write to ${path} while in plan mode.${note ?? ""}`) });
69
+ const askGate = createFsWriteGatePolicy({ env: seats.env, rootPath: seats.rootPath, defaultWrite: "ask" });
70
+ const acceptSeat = seats.acceptDirs;
71
+ const acceptDirs = typeof acceptSeat === "function" ? acceptSeat : acceptSeat !== undefined && acceptSeat.length > 0 ? [...acceptSeat] : [seats.rootPath];
72
+ const acceptRootGate = createFsWriteGatePolicy({ env: seats.env, rootPath: seats.rootPath, acceptDirs, defaultWrite: "ask" });
73
+ const planGate = createFsWriteGatePolicy({ env: seats.env, rootPath: seats.rootPath, defaultWrite: "ask", defaultAsk: (path, note) => planAsk(`Cannot write to ${path} while in plan mode.${note ?? ""}`) });
73
74
  return {
74
75
  async check(req, signal) {
75
76
  const gate = modePolicyOf(modeRef.current).writeGate;
@@ -4,7 +4,7 @@
4
4
  * registration form types a handler by it. Its keys are the event table's `classic.*` rows that carry a station — the key
5
5
  * set is held to that table.
6
6
  */
7
- import type { PermissionDeniedPayload, PostCompactEvent, PostToolBatchEvent, PostToolBatchResult, PostToolUseEvent, PostToolUseFailureEvent, PostToolUseFailureResult, PostToolUseResult, PreCompactEvent, PreCompactResult, PreToolUseEvent, PreToolUseResult, StopEvent, StopFailureEvent, StopHookResult, UserPromptSubmitEvent, UserPromptSubmitResult } from "../hooks.js";
7
+ import type { PermissionDeniedPayload, PostCompactEvent, PostToolBatchEvent, PostToolBatchResult, PostToolUseEvent, PostToolUseFailureEvent, PostToolUseFailureResult, PostToolUseResult, PreCompactEvent, PreCompactResult, PreToolUseEvent, PreToolUseResult, StopEvent, StopFailureEvent, StopHookResult, SubagentStartEvent, SubagentStartResult, UserPromptSubmitEvent, UserPromptSubmitResult } from "../hooks.js";
8
8
  import type { MappedOn, ModRegistration } from "./kernel/index.js";
9
9
  import type { EngineDollar } from "./dollar.js";
10
10
  /** The answer of an event whose station reads none (an observation event): a chain handler passes `next(e)`'s on. */
@@ -31,6 +31,10 @@ export type ClassicEventMap = {
31
31
  readonly e: UserPromptSubmitEvent;
32
32
  readonly answer: UserPromptSubmitResult;
33
33
  };
34
+ readonly "classic.SubagentStart": {
35
+ readonly e: SubagentStartEvent;
36
+ readonly answer: SubagentStartResult;
37
+ };
34
38
  readonly "classic.Stop": {
35
39
  readonly e: StopEvent;
36
40
  readonly answer: StopHookResult;
@@ -16,6 +16,6 @@ export function registrationRefusedNotice(record, sessionId) {
16
16
  return {
17
17
  code: REGISTRATION_REFUSED,
18
18
  message: `extension "${record.name}" (${record.seat} seat) was not mounted: ${record.refusedBy} refused it — ${record.reason}`,
19
- detail: { name: record.name, seat: record.seat, tier: record.tier, refusedBy: record.refusedBy, reason: record.reason, sessionId },
19
+ detail: { name: record.name, seat: record.seat, tier: record.tier, ...(record.provenance !== undefined ? { provenance: record.provenance } : {}), refusedBy: record.refusedBy, reason: record.reason, sessionId },
20
20
  };
21
21
  }
@@ -68,6 +68,9 @@ export interface ModDispatchOptions {
68
68
  readonly origin?: ModOrigin;
69
69
  /** The raiser's reading of an answer; an answer it refuses is a violation of the site. */
70
70
  readonly checkAnswer?: ModAnswerCheck;
71
+ /** The raiser's reading of what a handler hands on (a payload other than the dispatch's own `e`, received, its pinned keys
72
+ * judged); a payload it refuses is a violation of the site — the other direction of {@link checkAnswer}. */
73
+ readonly checkHandOn?: (payload: ModEventPayload) => string | undefined;
71
74
  /** The station's ranking of its answers — named by every dispatch of an event whose failure column refuses (one that
72
75
  * names none is not run), and read by the seat-trust law. */
73
76
  readonly ranks?: ModAnswerRanks;
@@ -1,7 +1,7 @@
1
1
  import { CATCH_BUDGET_MS, createSelfBudget, POST_ABORT_GRACE_MS, RUNAWAY_AFTER_MS, unrefTimer, watchRunaway } from "./budget.js";
2
2
  import { expandOnSide, failureRefuses, isModEventName, MOD_SEATS, nextToRefusal, stationOn } from "./events.js";
3
3
  import { ENGINE_ORIGIN, modsInvalid, screenModSeats, } from "./registration.js";
4
- import { answerUpward, answerViolation, detachedCopy, engineObjectsOnce, handedOn, matcherMatches, matcherViolation, methodAnswerViolation, NEXT_IN_FLIGHT, receiveAnswer, receiveEvent, receivePayload, sealedObjects, } from "./site-rules.js";
4
+ import { answerUpward, answerViolation, detachedCopy, engineObjectsOnce, handedOn, handOnViolation, matcherMatches, matcherViolation, methodAnswerViolation, NEXT_IN_FLIGHT, receiveAnswer, receiveEvent, receivePayload, sealedObjects, } from "./site-rules.js";
5
5
  const TIER_RANK = { prepend: 0, user: 1, append: 2, builtin: 3, core: 4 };
6
6
  const bypassed = (floors, tier) => floors.some((f) => TIER_RANK[f.from] < TIER_RANK[tier] && TIER_RANK[tier] < TIER_RANK[f.to]);
7
7
  export async function admitMods(input) {
@@ -31,23 +31,22 @@ export async function admitMods(input) {
31
31
  });
32
32
  if (outcome.kind === "aborted")
33
33
  throw input.signal?.reason ?? new Error("admission aborted");
34
+ const whose = { name: cand.name, seat: cand.seat, tier: cand.tier, ...(cand.provenance !== undefined ? { provenance: cand.provenance } : {}) };
34
35
  if (outcome.kind === "failed") {
35
- records.push(Object.freeze({ name: cand.name, seat: cand.seat, tier: cand.tier, refusedBy: outcome.registration, reason: `${outcome.registration} failed: ${outcome.reason}` }));
36
+ records.push(Object.freeze({ ...whose, refusedBy: outcome.registration, reason: `${outcome.registration} failed: ${outcome.reason}` }));
36
37
  continue;
37
38
  }
38
39
  const refused = refusalOf(outcome.answer);
39
40
  if (refused !== undefined) {
40
- records.push(Object.freeze({ name: cand.name, seat: cand.seat, tier: cand.tier, refusedBy: outcome.answeredBy ?? "engine", reason: refused }));
41
+ records.push(Object.freeze({ ...whose, refusedBy: outcome.answeredBy ?? "engine", reason: refused }));
41
42
  continue;
42
43
  }
43
44
  const own = mountOne(cand, input.side, describe);
44
45
  mounted.push(...own);
45
46
  const events = unique(own.map((h) => h.pattern));
46
- const observe = unique(own.filter((h) => h.observe).map((h) => h.pattern));
47
+ const observe = Object.freeze(events.filter((p) => own.every((h) => h.pattern !== p || h.observe)));
47
48
  records.push(Object.freeze({
48
- name: cand.name,
49
- seat: cand.seat,
50
- tier: cand.tier,
49
+ ...whose,
51
50
  events,
52
51
  ...(observe.length > 0 ? { observe } : {}),
53
52
  ...(outcome.skipped.length > 0 ? { skipped: outcome.skipped } : {}),
@@ -376,7 +375,10 @@ function createBus(side, mounted, bottoms, entries, report, records, describe, i
376
375
  if (passed === e0)
377
376
  return { snap: e0 };
378
377
  const handed = handedOn(st.pinned, e0, passed, engines(), isProxy);
379
- return "violation" in handed ? handed : { snap: handed.payload };
378
+ if ("violation" in handed)
379
+ return handed;
380
+ const why = handOnViolation(handed.payload, options.checkHandOn);
381
+ return why !== undefined ? { violation: why } : { snap: handed.payload };
380
382
  };
381
383
  const trustFloors = new Map();
382
384
  const NO_FLOOR = Object.freeze(MOD_SEATS.map(() => 0));
@@ -582,7 +584,8 @@ function createBus(side, mounted, bottoms, entries, report, records, describe, i
582
584
  if (caught !== undefined && "answer" in caught) {
583
585
  if (failure.cause !== "violation" && failure.cause !== "reentry")
584
586
  report(new Error(`${name}: ${event}: ${failure.reason}; its .catch answered`));
585
- producers.set(caught.answer, name);
587
+ if (!(typeof caught.answer === "object" && caught.answer !== null && producers.has(caught.answer)))
588
+ producers.set(caught.answer, name);
586
589
  traceOf(sink, i, name, h.reg.tier, "caught", ms);
587
590
  return caught.answer;
588
591
  }
@@ -21,8 +21,13 @@
21
21
  * reaches the host's entry, the dispatch records whether its bottom started, a re-entered guard with no `.catch`
22
22
  * refuses, the one side lock over `uses` and `on`, answers received as data, the seat-trust law, `prompt.mention`
23
23
  * on the engine's side, and `tool.call` with the `refuse_until_run` failure answer, callable.
24
+ * 4: a station may judge what a handler hands on (the dispatch's `checkHandOn`: its sentence is the handler's violation, as a
25
+ * changed pinned key is), `tool.call` takes one member more than its own — `requestMeta`, a record of strings, judged there —
26
+ * and an admission record carries the registration's `provenance` as the host gave it and lists in `observe` only the patterns
27
+ * on which every handler it hung watches.
28
+ * 5: `classic.SubagentStart` has a station (a delegated leg's opening event).
24
29
  */
25
- export declare const KERNEL_CONTRACT_VERSION = 3;
30
+ export declare const KERNEL_CONTRACT_VERSION = 5;
26
31
  /** The five tiers in run order (CC names). `builtin` and `core` are the engine's own. */
27
32
  export declare const MOD_TIERS: readonly ["prepend", "user", "append", "builtin", "core"];
28
33
  export type ModTier = (typeof MOD_TIERS)[number];
@@ -1,4 +1,4 @@
1
- export const KERNEL_CONTRACT_VERSION = 3;
1
+ export const KERNEL_CONTRACT_VERSION = 5;
2
2
  export const MOD_TIERS = Object.freeze(["prepend", "user", "append", "builtin", "core"]);
3
3
  export const MOD_SEATS = Object.freeze(["deployment", "task"]);
4
4
  export const MOD_EVENT_SIDES = Object.freeze(["engine", "surface", "both"]);
@@ -55,7 +55,7 @@ export const MOD_EVENT_TABLE = Object.freeze({
55
55
  "classic.SessionEnd": engine(),
56
56
  "classic.Stop": engine(station("skip", "immediate")),
57
57
  "classic.StopFailure": engine(station("skip", "grace")),
58
- "classic.SubagentStart": engine(),
58
+ "classic.SubagentStart": engine(station("skip", "immediate", ["agentId", "agentType"])),
59
59
  "classic.SubagentStop": engine(station("skip", "immediate")),
60
60
  "classic.PreCompact": engine(station("skip", "grace")),
61
61
  "classic.PostCompact": engine(station("skip", "grace")),
@@ -23,6 +23,10 @@ export interface ModOrigin {
23
23
  }
24
24
  /** The engine's own origin; its `plugin` word is reserved (no registration may take it). */
25
25
  export declare const ENGINE_ORIGIN: ModOrigin;
26
+ /** The extension a refusal names: the registration's own name — never the engine's origin word (a raise the engine could not run
27
+ * names no extension), never an absent one. The one reading of "who refused" for every station that refuses a call at the hook
28
+ * layer (`GateDisposition.extension`). Module-level: not part of the kernel's entry. */
29
+ export declare function namedRegistration(registration: string | undefined): string | undefined;
26
30
  /** The facts `$.plugin` carries. */
27
31
  export interface ModPluginFacts {
28
32
  readonly name: string;
@@ -118,11 +122,14 @@ export interface ModRegistration<D extends ModDollarBase = ModDollarBase> {
118
122
  readonly options?: unknown;
119
123
  register(on: On<D>, options: unknown): void;
120
124
  }
121
- /** One admission result: mounted (with the patterns it actually hung) or refused (by whom, why). */
125
+ /** One admission result: mounted (with the patterns it actually hung, and among them the ones on which every handler it
126
+ * hung watches) or refused (by whom, why). `provenance` is the registration's own label, carried as the host gave it on
127
+ * either arm — absent when the host gave none. */
122
128
  export type ModAdmissionRecord = {
123
129
  readonly name: string;
124
130
  readonly seat: ModSeat;
125
131
  readonly tier: ModTier;
132
+ readonly provenance?: string;
126
133
  readonly events: readonly string[];
127
134
  readonly observe?: readonly string[];
128
135
  /** Judges skipped while this registration was judged (their failure or site violation), as the dispatch listed them. */
@@ -131,6 +138,7 @@ export type ModAdmissionRecord = {
131
138
  readonly name: string;
132
139
  readonly seat: ModSeat;
133
140
  readonly tier: ModTier;
141
+ readonly provenance?: string;
134
142
  readonly refusedBy: string;
135
143
  readonly reason: string;
136
144
  };
@@ -3,6 +3,9 @@ import { resolveModBudgetMs } from "./budget.js";
3
3
  export const MODS_INVALID_CODE = "config.mods_invalid";
4
4
  export const MODS_REGISTRATION_REFUSED_CODE = "mods.registration_refused";
5
5
  export const ENGINE_ORIGIN = Object.freeze({ plugin: "engine", tier: "core" });
6
+ export function namedRegistration(registration) {
7
+ return registration === undefined || registration === ENGINE_ORIGIN.plugin ? undefined : registration;
8
+ }
6
9
  export const MOD_TRACE_OUTCOMES = Object.freeze(["returned", "passed", "rejected", "caught", "expired", "kept", "skipped", "bypassed"]);
7
10
  export function modsInvalid(message) {
8
11
  return Object.assign(new Error(message), { code: MODS_INVALID_CODE });
@@ -109,6 +109,9 @@ export declare function pinnedHandOn(pinned: readonly string[], held: ModEventPa
109
109
  };
110
110
  /** Why a handler's answer breaks the site, or undefined. No answer at all is never an answer. */
111
111
  export declare function answerViolation(answer: unknown, check: ModAnswerCheck | undefined, e: ModEventPayload, by: ModAnswerer, below: readonly unknown[], run: ModDispatchRun): string | undefined;
112
+ /** A station's reading of what a handler hands on: its sentence, or undefined (no check, or the payload passes). A check that
113
+ * throws is a sentence too — the station could not read the payload, so it is not handed on. */
114
+ export declare function handOnViolation(payload: ModEventPayload, check: ((payload: ModEventPayload) => string | undefined) | undefined): string | undefined;
112
115
  /**
113
116
  * A `$` method's answer form: `{ value }` (the call's result) or `{ deny }` (the call throws). A `{ deny }` given after
114
117
  * the handler's `next` was answered with something that is not a deny — or while that `next` is still running — breaks
@@ -203,6 +203,16 @@ export function answerViolation(answer, check, e, by, below, run) {
203
203
  return "returned an answer the station cannot read";
204
204
  }
205
205
  }
206
+ export function handOnViolation(payload, check) {
207
+ if (check === undefined)
208
+ return undefined;
209
+ try {
210
+ return check(payload);
211
+ }
212
+ catch {
213
+ return "handed on an event the station cannot read";
214
+ }
215
+ }
206
216
  const denyOf = (a) => (typeof a === "object" && a !== null && Object.prototype.hasOwnProperty.call(a, "deny") ? Reflect.get(a, "deny") : undefined);
207
217
  export function methodAnswerViolation(answer, _e, _by, below = []) {
208
218
  if (!isPlainRecord(answer))
@@ -0,0 +1,23 @@
1
+ import { type ModRegistrationTier } from "./kernel/index.js";
2
+ import type { EngineModRegistration } from "./classic-events.js";
3
+ /** The host's facts about a package it loads: never read from the package itself. */
4
+ export interface ModPackageHost {
5
+ /** The tier the host seats it in (a deployment seat requires one; the task seat takes `user` or none). */
6
+ readonly tier?: ModRegistrationTier;
7
+ /** The host's provenance label, handed to admission and carried on the admission record as given. */
8
+ readonly provenance?: string;
9
+ /** The values handed to the package's `register(on, options)`. */
10
+ readonly options?: unknown;
11
+ }
12
+ /** A package read into a registration, with the identity of the bytes it was read from. */
13
+ export interface ModPackageRegistration extends EngineModRegistration {
14
+ /**
15
+ * The sha256 (lowercase hex) of the three files this reader read, in this order — `plugin.json`, `hooks.json`, the
16
+ * hooks module — taken as the newline-joined sha256 of each file's bytes. One changed byte in any of the three changes
17
+ * it. The module is imported from those bytes, so this names the module that runs; what its code loads beyond them (an
18
+ * absolute URL, a file it reads) is not among them.
19
+ */
20
+ readonly digest: string;
21
+ }
22
+ /** Read the package at `dir` into a registration the host seats in `RunnerDeps.mods` or `TaskSpec.mods`. */
23
+ export declare function loadModPackage(dir: string, host?: ModPackageHost): Promise<ModPackageRegistration>;
@@ -0,0 +1,118 @@
1
+ import { createHash } from "node:crypto";
2
+ import { constants } from "node:fs";
3
+ import { open, stat } from "node:fs/promises";
4
+ import { extname, isAbsolute, join, relative, resolve, sep } from "node:path";
5
+ import { KERNEL_CONTRACT_VERSION } from "./kernel/index.js";
6
+ import { modsInvalid } from "./kernel/registration.js";
7
+ import { physicalPathOfAsync } from "../physical-path.js";
8
+ import { describeThrown } from "../tool-policy.js";
9
+ import { extensionWords } from "../untrusted-egress.js";
10
+ const PLUGIN_FILE = join(".claude-plugin", "plugin.json");
11
+ const HOOKS_FILE = join("hooks", "hooks.json");
12
+ const PLUGIN_KEYS = ["name", "version", "description", "author"];
13
+ const HOOKS_KEYS = ["modules", "contract", "uses", "description"];
14
+ const MODULE_EXTENSION = ".mjs";
15
+ const MODULE_URL_HEAD = "data:text/javascript;base64,";
16
+ const MODULE_URL_TEXT = /data:text\/javascript;base64,[A-Za-z0-9+/=]*/g;
17
+ export async function loadModPackage(dir, host = {}) {
18
+ const root = await realRoot(dir);
19
+ const refuse = (file, why) => modsInvalid(`mod package ${root}: ${file}: ${why}`);
20
+ const pluginFile = await packageFile(root, PLUGIN_FILE, refuse);
21
+ const plugin = jsonRecord(pluginFile.bytes, PLUGIN_FILE, PLUGIN_KEYS, refuse);
22
+ const hooksFile = await packageFile(root, HOOKS_FILE, refuse);
23
+ const hooks = jsonRecord(hooksFile.bytes, HOOKS_FILE, HOOKS_KEYS, refuse);
24
+ const contract = hooks["contract"];
25
+ if (contract !== KERNEL_CONTRACT_VERSION) {
26
+ throw refuse(HOOKS_FILE, `contract is ${kind(contract)}; this engine's mods kernel is contract ${KERNEL_CONTRACT_VERSION}, and a package loads only under the contract it was written against`);
27
+ }
28
+ const modules = hooks["modules"];
29
+ if (!Array.isArray(modules) || modules.length !== 1 || typeof modules[0] !== "string")
30
+ throw refuse(HOOKS_FILE, `modules is ${kind(modules)}; it lists exactly one path, relative to hooks.json`);
31
+ const given = modules[0];
32
+ const shown = extensionWords(given, 120);
33
+ if (given === "" || isAbsolute(given))
34
+ throw refuse(HOOKS_FILE, `modules names "${shown}"; the path is relative to hooks.json`);
35
+ if (extname(given) !== MODULE_EXTENSION)
36
+ throw refuse(HOOKS_FILE, `modules names "${shown}"; a hooks module is an ES module named ${MODULE_EXTENSION}`);
37
+ const moduleFile = await packageFile(root, join("hooks", given), (_file, why) => refuse(HOOKS_FILE, `modules names "${shown}": ${why}`));
38
+ const digest = sha256([pluginFile.bytes, hooksFile.bytes, moduleFile.bytes].map(sha256).join("\n"));
39
+ let ns;
40
+ try {
41
+ ns = await import(`${MODULE_URL_HEAD}${moduleFile.bytes.toString("base64")}`);
42
+ }
43
+ catch (err) {
44
+ const said = describeThrown(err).replace(MODULE_URL_TEXT, moduleFile.inside);
45
+ throw refuse(moduleFile.inside, `could not be imported (${said}); a hooks module is imported from its own bytes, so it is one self-contained file: a relative or package import has nothing to resolve from`);
46
+ }
47
+ return Object.freeze({
48
+ name: plugin["name"],
49
+ uses: hooks["uses"],
50
+ ...(host.tier !== undefined ? { tier: host.tier } : {}),
51
+ ...(host.provenance !== undefined ? { provenance: host.provenance } : {}),
52
+ ...(host.options !== undefined ? { options: host.options } : {}),
53
+ register: (typeof ns === "object" && ns !== null ? Reflect.get(ns, "register") : undefined),
54
+ digest,
55
+ });
56
+ }
57
+ async function realRoot(dir) {
58
+ try {
59
+ const root = await physicalPathOfAsync(resolve(dir));
60
+ if ((await stat(root)).isDirectory())
61
+ return root;
62
+ }
63
+ catch {
64
+ }
65
+ throw modsInvalid(`mod package ${dir}: not a directory`);
66
+ }
67
+ async function packageFile(root, file, refuse) {
68
+ let real;
69
+ try {
70
+ real = await physicalPathOfAsync(resolve(root, file));
71
+ }
72
+ catch {
73
+ throw refuse(file, "is not in the package; a mod package carries it");
74
+ }
75
+ const inside = relative(root, real);
76
+ if (inside === "" || inside === ".." || inside.startsWith(`..${sep}`) || isAbsolute(inside))
77
+ throw refuse(file, "resolves outside the package");
78
+ let handle;
79
+ try {
80
+ handle = await open(real, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
81
+ if (!(await handle.stat()).isFile())
82
+ throw new Error("not a regular file");
83
+ return { inside, bytes: await handle.readFile() };
84
+ }
85
+ catch (err) {
86
+ throw refuse(file, `could not be read as a regular file of the package (${describeThrown(err)})`);
87
+ }
88
+ finally {
89
+ await handle?.close();
90
+ }
91
+ }
92
+ function jsonRecord(bytes, file, keys, refuse) {
93
+ let parsed;
94
+ try {
95
+ parsed = JSON.parse(bytes.toString("utf8"));
96
+ }
97
+ catch {
98
+ throw refuse(file, "is not JSON");
99
+ }
100
+ if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
101
+ throw refuse(file, `is ${kind(parsed)}; it is a JSON object`);
102
+ const extra = Object.keys(parsed).find((k) => !keys.includes(k));
103
+ if (extra !== undefined)
104
+ throw refuse(file, `carries "${extensionWords(extra, 60)}", which a mod package does not state here (it takes ${keys.join(", ")})`);
105
+ return parsed;
106
+ }
107
+ function sha256(data) {
108
+ return createHash("sha256").update(data).digest("hex");
109
+ }
110
+ function kind(v) {
111
+ if (v === undefined)
112
+ return "absent";
113
+ if (v === null)
114
+ return "null";
115
+ if (Array.isArray(v))
116
+ return `a list of ${v.length}`;
117
+ return typeof v === "number" || typeof v === "boolean" ? String(v) : `a ${typeof v}`;
118
+ }