@sema-agent/core 7.56.0 → 7.58.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 (319) hide show
  1. package/CHANGELOG.md +926 -0
  2. package/LICENSE +1 -1
  3. package/dist/agents/org-delivery-gate.js +3 -4
  4. package/dist/agents/peer-held-queue.d.ts +69 -49
  5. package/dist/agents/peer-held-queue.js +255 -106
  6. package/dist/agents/peer-session-drain.js +63 -43
  7. package/dist/agents/send-message-tool.js +3 -2
  8. package/dist/agents/subagent-steps.js +2 -4
  9. package/dist/agents/subagent.js +8 -8
  10. package/dist/brain/anthropic.js +16 -8
  11. package/dist/brain/open-responses.js +10 -8
  12. package/dist/brain/openai.js +11 -9
  13. package/dist/brain/provider-dialect.d.ts +3 -2
  14. package/dist/brain/provider-dialect.js +2 -2
  15. package/dist/brain/request-params.d.ts +6 -0
  16. package/dist/brain/request-params.js +14 -1
  17. package/dist/brain/route-adjudicator.js +2 -1
  18. package/dist/brain/stream-engine.d.ts +9 -0
  19. package/dist/brain/stream-engine.js +24 -10
  20. package/dist/brain/stream-shared.d.ts +5 -4
  21. package/dist/brain/stream-shared.js +4 -4
  22. package/dist/core/a2a.d.ts +2 -1
  23. package/dist/core/a2a.js +23 -10
  24. package/dist/core/allow-entry.d.ts +5 -11
  25. package/dist/core/allow-entry.js +19 -26
  26. package/dist/core/approval-object.d.ts +21 -5
  27. package/dist/core/approval-object.js +44 -17
  28. package/dist/core/ask-origin.d.ts +23 -4
  29. package/dist/core/ask-origin.js +5 -1
  30. package/dist/core/auto-compaction.d.ts +75 -6
  31. package/dist/core/auto-compaction.js +43 -27
  32. package/dist/core/auto-mode-directive.d.ts +29 -5
  33. package/dist/core/auto-mode-directive.js +38 -8
  34. package/dist/core/background-agent-store.d.ts +6 -2
  35. package/dist/core/background-agent-store.js +1 -1
  36. package/dist/core/checkpoint-requirements.d.ts +13 -1
  37. package/dist/core/checkpoint-requirements.js +4 -0
  38. package/dist/core/checkpoint-store.d.ts +44 -40
  39. package/dist/core/checkpoint-store.js +32 -14
  40. package/dist/core/cross-boundary-taint.js +4 -2
  41. package/dist/core/engine-notice.d.ts +4 -3
  42. package/dist/core/engine-notice.js +6 -0
  43. package/dist/core/file-history-store.d.ts +14 -8
  44. package/dist/core/file-history-store.js +14 -4
  45. package/dist/core/fs-write-gate-policy.d.ts +4 -2
  46. package/dist/core/fs-write-gate-policy.js +7 -3
  47. package/dist/core/gate-fold.js +6 -3
  48. package/dist/core/gate-lanes.js +13 -5
  49. package/dist/core/git-worktree-env.d.ts +53 -11
  50. package/dist/core/git-worktree-env.js +96 -12
  51. package/dist/core/hooks.d.ts +6 -3
  52. package/dist/core/hooks.js +12 -5
  53. package/dist/core/human-input-projection.d.ts +1 -0
  54. package/dist/core/human-input-projection.js +3 -0
  55. package/dist/core/locked-config.d.ts +15 -1
  56. package/dist/core/locked-config.js +38 -2
  57. package/dist/core/mailbox-store.d.ts +62 -1
  58. package/dist/core/mailbox-store.js +59 -0
  59. package/dist/core/mcp-call-meta.d.ts +66 -0
  60. package/dist/core/mcp-call-meta.js +103 -0
  61. package/dist/core/mcp-connection-pool.d.ts +3 -1
  62. package/dist/core/mcp-connection-pool.js +3 -1
  63. package/dist/core/mcp-failure.d.ts +7 -1
  64. package/dist/core/mcp-failure.js +10 -0
  65. package/dist/core/mcp-name-judge.d.ts +46 -0
  66. package/dist/core/mcp-name-judge.js +61 -0
  67. package/dist/core/mcp-probe.d.ts +5 -1
  68. package/dist/core/mcp-probe.js +3 -6
  69. package/dist/core/mcp-server-link.d.ts +5 -2
  70. package/dist/core/mcp-server-spec.d.ts +46 -18
  71. package/dist/core/mcp-server-spec.js +1 -18
  72. package/dist/core/mcp.d.ts +6 -14
  73. package/dist/core/mcp.js +85 -65
  74. package/dist/core/memory-engine/consolidation-driver.js +4 -3
  75. package/dist/core/memory-engine/distiller.js +26 -17
  76. package/dist/core/memory-engine/layout.js +5 -2
  77. package/dist/core/memory-engine/scope-contract.d.ts +45 -4
  78. package/dist/core/memory-engine/scope-contract.js +80 -11
  79. package/dist/core/mode-policy.d.ts +8 -5
  80. package/dist/core/mode-policy.js +5 -4
  81. package/dist/core/mods/host.js +1 -1
  82. package/dist/core/mods/kernel/dispatch.d.ts +3 -0
  83. package/dist/core/mods/kernel/dispatch.js +10 -8
  84. package/dist/core/mods/kernel/events.d.ts +5 -1
  85. package/dist/core/mods/kernel/events.js +1 -1
  86. package/dist/core/mods/kernel/registration.d.ts +5 -1
  87. package/dist/core/mods/kernel/site-rules.d.ts +3 -0
  88. package/dist/core/mods/kernel/site-rules.js +10 -0
  89. package/dist/core/mods/package.d.ts +23 -0
  90. package/dist/core/mods/package.js +118 -0
  91. package/dist/core/mods/stations.d.ts +2 -2
  92. package/dist/core/mods/stations.js +1 -1
  93. package/dist/core/mods/tool-call.d.ts +5 -1
  94. package/dist/core/mods/tool-call.js +12 -3
  95. package/dist/core/park-selfcheck.js +2 -0
  96. package/dist/core/path-guard-rows.d.ts +20 -0
  97. package/dist/core/path-guard-rows.js +11 -0
  98. package/dist/core/peer-seat.d.ts +186 -0
  99. package/dist/core/peer-seat.js +307 -0
  100. package/dist/core/permission-rule-consent.d.ts +5 -3
  101. package/dist/core/permission-rule-consent.js +20 -15
  102. package/dist/core/permission-rule-model.d.ts +43 -2
  103. package/dist/core/permission-rule-model.js +52 -8
  104. package/dist/core/permission-rule-org.js +1 -1
  105. package/dist/core/present-plan-tool.d.ts +10 -1
  106. package/dist/core/present-plan-tool.js +46 -2
  107. package/dist/core/protocol-http-auth.d.ts +56 -31
  108. package/dist/core/protocol-http-auth.js +71 -42
  109. package/dist/core/protocol-naming.d.ts +20 -0
  110. package/dist/core/protocol-naming.js +20 -3
  111. package/dist/core/read-only-shell.d.ts +20 -5
  112. package/dist/core/read-only-shell.js +29 -14
  113. package/dist/core/redaction-marks.d.ts +16 -0
  114. package/dist/core/redaction-marks.js +16 -0
  115. package/dist/core/redaction-passes.js +8 -9
  116. package/dist/core/remote-env.d.ts +37 -1
  117. package/dist/core/remote-env.js +11 -0
  118. package/dist/core/resume-startup-cause.d.ts +24 -2
  119. package/dist/core/resume-startup-cause.js +20 -1
  120. package/dist/core/retention.d.ts +41 -15
  121. package/dist/core/retention.js +59 -12
  122. package/dist/core/rewrite-rejudge.d.ts +37 -0
  123. package/dist/core/rewrite-rejudge.js +40 -0
  124. package/dist/core/roles.js +50 -7
  125. package/dist/core/run-origin.d.ts +40 -0
  126. package/dist/core/run-origin.js +37 -0
  127. package/dist/core/runner/advertised-writable-dirs.d.ts +57 -38
  128. package/dist/core/runner/advertised-writable-dirs.js +126 -0
  129. package/dist/core/runner/compact-session.d.ts +10 -0
  130. package/dist/core/runner/compact-session.js +202 -0
  131. package/dist/core/runner/compaction-call-options.d.ts +2 -2
  132. package/dist/core/runner/compaction-restate.d.ts +15 -6
  133. package/dist/core/runner/compaction-restate.js +28 -2
  134. package/dist/core/runner/compaction-seams.d.ts +21 -1
  135. package/dist/core/runner/compaction-seams.js +11 -8
  136. package/dist/core/runner/contracts.d.ts +36 -21
  137. package/dist/core/runner/derived-route-fallback.d.ts +13 -0
  138. package/dist/core/runner/derived-route-fallback.js +6 -0
  139. package/dist/core/runner/env-capability-census.d.ts +3 -2
  140. package/dist/core/runner/env-capability-census.js +9 -3
  141. package/dist/core/runner/gate-exit.d.ts +18 -4
  142. package/dist/core/runner/gate-exit.js +5 -1
  143. package/dist/core/runner/permission-rule-lanes.d.ts +7 -7
  144. package/dist/core/runner/permission-rule-lanes.js +17 -11
  145. package/dist/core/runner/prepare-acquire-reconcile.d.ts +3 -0
  146. package/dist/core/runner/prepare-acquire-reconcile.js +2 -1
  147. package/dist/core/runner/prepare-caps-and-workflow.d.ts +2 -0
  148. package/dist/core/runner/prepare-caps-and-workflow.js +1 -1
  149. package/dist/core/runner/prepare-config-doors.d.ts +14 -5
  150. package/dist/core/runner/prepare-config-doors.js +16 -13
  151. package/dist/core/runner/prepare-delegation-surface.d.ts +4 -0
  152. package/dist/core/runner/prepare-delegation-surface.js +15 -18
  153. package/dist/core/runner/prepare-gate-stations.js +1 -1
  154. package/dist/core/runner/prepare-hands-readface.d.ts +10 -4
  155. package/dist/core/runner/prepare-hands-readface.js +6 -1
  156. package/dist/core/runner/prepare-memory.d.ts +3 -0
  157. package/dist/core/runner/prepare-memory.js +19 -23
  158. package/dist/core/runner/prepare-park-ask.d.ts +2 -0
  159. package/dist/core/runner/prepare-park-ask.js +2 -2
  160. package/dist/core/runner/prepare-policy-chain.d.ts +4 -4
  161. package/dist/core/runner/prepare-policy-chain.js +4 -6
  162. package/dist/core/runner/prepare-protocol-tools.d.ts +4 -2
  163. package/dist/core/runner/prepare-protocol-tools.js +3 -3
  164. package/dist/core/runner/prepare-suspend-saga.d.ts +2 -0
  165. package/dist/core/runner/prepare-suspend-saga.js +2 -1
  166. package/dist/core/runner/prepare-task.d.ts +4 -1
  167. package/dist/core/runner/prepare-task.js +46 -37
  168. package/dist/core/runner/prepare-tool-disclosure-mount.d.ts +13 -0
  169. package/dist/core/runner/prepare-tool-disclosure-mount.js +13 -7
  170. package/dist/core/runner/prepare-wiring-manifest.d.ts +1 -0
  171. package/dist/core/runner/prepare-wiring-manifest.js +2 -2
  172. package/dist/core/runner/prepare-workspace-restore.d.ts +3 -0
  173. package/dist/core/runner/prepare-workspace-restore.js +4 -4
  174. package/dist/core/runner/resume-admission.js +1 -1
  175. package/dist/core/runner/resume-checkpoint-screen.js +2 -0
  176. package/dist/core/runner/rewind-files.d.ts +2 -5
  177. package/dist/core/runner/rewind-files.js +9 -51
  178. package/dist/core/runner/run-harness-handlers.d.ts +3 -4
  179. package/dist/core/runner/run-harness-handlers.js +1 -8
  180. package/dist/core/runner/run-identity-wiring.js +1 -0
  181. package/dist/core/runner/run-leg.js +15 -22
  182. package/dist/core/runner/run-notification-lane.d.ts +2 -0
  183. package/dist/core/runner/run-notification-lane.js +5 -2
  184. package/dist/core/runner/run-recovery-lanes.js +3 -4
  185. package/dist/core/runner/run-settle-and-teardown.js +5 -11
  186. package/dist/core/runner/run-terminal-adoption.js +3 -4
  187. package/dist/core/runner/run-turn-boundary.js +3 -5
  188. package/dist/core/runner/runtask.d.ts +8 -1
  189. package/dist/core/runner/runtask.js +28 -34
  190. package/dist/core/runner/send-message-continuation.js +1 -1
  191. package/dist/core/runner/session-verb-doors.d.ts +28 -0
  192. package/dist/core/runner/session-verb-doors.js +48 -0
  193. package/dist/core/runner/session-write-ledger.d.ts +30 -0
  194. package/dist/core/runner/session-write-ledger.js +101 -0
  195. package/dist/core/runner/stream-settle-backstop.js +11 -14
  196. package/dist/core/runner/sub-agent-deny-lists.d.ts +25 -3
  197. package/dist/core/runner/sub-agent-deny-lists.js +21 -10
  198. package/dist/core/runner/teardown-bounded.d.ts +1 -0
  199. package/dist/core/runner/teardown-bounded.js +1 -0
  200. package/dist/core/runner/terminal-account.js +3 -3
  201. package/dist/core/runner/tool-end-body.js +1 -0
  202. package/dist/core/runner/tool-occurrence.d.ts +4 -1
  203. package/dist/core/runner/tool-occurrence.js +2 -1
  204. package/dist/core/runner/write-protection-station.d.ts +8 -2
  205. package/dist/core/runner/write-protection-station.js +2 -0
  206. package/dist/core/runner-deps.d.ts +4 -4
  207. package/dist/core/secret-env.d.ts +4 -0
  208. package/dist/core/secret-env.js +3 -0
  209. package/dist/core/sensitive-path-policy.js +6 -7
  210. package/dist/core/session-log-transfer.d.ts +24 -0
  211. package/dist/core/session-log-transfer.js +166 -0
  212. package/dist/core/session-policy-store.d.ts +7 -2
  213. package/dist/core/session-policy-store.js +1 -1
  214. package/dist/core/session-store.d.ts +84 -19
  215. package/dist/core/session-store.js +162 -24
  216. package/dist/core/session.d.ts +92 -1
  217. package/dist/core/shell-read-silence.js +1 -0
  218. package/dist/core/shell-wrapper-projection.d.ts +1 -1
  219. package/dist/core/steer-replay.d.ts +4 -2
  220. package/dist/core/steer-replay.js +2 -1
  221. package/dist/core/store-contracts/background-agent-store-contract.js +1 -0
  222. package/dist/core/store-contracts/checkpoint-store-contract.js +19 -1
  223. package/dist/core/store-contracts/file-history-store-contract.js +9 -0
  224. package/dist/core/store-contracts/mailbox-store-contract.js +49 -1
  225. package/dist/core/store-contracts/session-repo-contract.js +112 -5
  226. package/dist/core/store-contracts/session-store-contract.d.ts +4 -1
  227. package/dist/core/store-contracts/session-store-contract.js +236 -2
  228. package/dist/core/task-event.d.ts +68 -8
  229. package/dist/core/task-registry-agent.d.ts +8 -4
  230. package/dist/core/task-registry-agent.js +14 -8
  231. package/dist/core/task-registry-shared.d.ts +36 -6
  232. package/dist/core/task-registry-shared.js +11 -0
  233. package/dist/core/task-registry.d.ts +1 -1
  234. package/dist/core/task-registry.js +1 -1
  235. package/dist/core/task-spec.d.ts +37 -0
  236. package/dist/core/task-stream.d.ts +2 -1
  237. package/dist/core/terminal-cause.d.ts +1 -1
  238. package/dist/core/tool-catalog-entries.d.ts +6 -0
  239. package/dist/core/tool-catalog-entries.js +2 -0
  240. package/dist/core/tool-name-aliases.d.ts +32 -2
  241. package/dist/core/tool-name-aliases.js +23 -0
  242. package/dist/core/tool-name-readings.d.ts +4 -0
  243. package/dist/core/tool-name-readings.js +1 -0
  244. package/dist/core/tool-policy.d.ts +10 -6
  245. package/dist/core/tool-policy.js +4 -7
  246. package/dist/core/tool-result-store.d.ts +17 -10
  247. package/dist/core/tool-result-store.js +3 -1
  248. package/dist/core/trace.d.ts +4 -1
  249. package/dist/core/trace.js +2 -1
  250. package/dist/core/types.d.ts +1 -1
  251. package/dist/core/untrusted-egress.d.ts +18 -0
  252. package/dist/core/untrusted-egress.js +82 -12
  253. package/dist/core/wiring-manifest.d.ts +12 -3
  254. package/dist/core/wiring-manifest.js +4 -3
  255. package/dist/core/workspace-snapshot.d.ts +44 -0
  256. package/dist/core/workspace-snapshot.js +34 -0
  257. package/dist/core/write-protect.d.ts +43 -3
  258. package/dist/core/write-protect.js +43 -16
  259. package/dist/engine/execution-env/node-execution-env.js +15 -11
  260. package/dist/engine/execution-env/symlink-chain.d.ts +7 -5
  261. package/dist/engine/harness/agent-harness.d.ts +12 -5
  262. package/dist/engine/harness/agent-harness.js +13 -2
  263. package/dist/engine/harness/types.d.ts +48 -7
  264. package/dist/engine/harness/types.js +5 -1
  265. package/dist/engine/llm/types.d.ts +12 -3
  266. package/dist/engine/llm/types.js +1 -1
  267. package/dist/engine/loop/agent-loop.d.ts +1 -4
  268. package/dist/engine/loop/agent-loop.js +26 -4
  269. package/dist/engine/session/import-validate.js +3 -0
  270. package/dist/engine/session/memory-repo.d.ts +17 -9
  271. package/dist/engine/session/memory-repo.js +44 -34
  272. package/dist/engine/session/repo-utils.d.ts +22 -4
  273. package/dist/engine/session/repo-utils.js +49 -1
  274. package/dist/engine/session/storage-base.d.ts +10 -1
  275. package/dist/engine/session/storage-base.js +7 -1
  276. package/dist/index.d.ts +23 -11
  277. package/dist/index.js +15 -6
  278. package/dist/internal/harness-types.d.ts +1 -1
  279. package/dist/internal/harness.d.ts +4 -3
  280. package/dist/internal/harness.js +3 -2
  281. package/dist/stores/file/checkpoint-store.d.ts +0 -4
  282. package/dist/stores/file/checkpoint-store.js +0 -1
  283. package/dist/stores/file/file-history-store.js +12 -4
  284. package/dist/stores/file/index.d.ts +4 -1
  285. package/dist/stores/file/index.js +4 -1
  286. package/dist/stores/file/mailbox-store.d.ts +2 -1
  287. package/dist/stores/file/mailbox-store.js +26 -1
  288. package/dist/stores/file/session-store.d.ts +15 -8
  289. package/dist/stores/file/session-store.js +28 -13
  290. package/dist/tools/fs/bash-readonly-classifier.d.ts +15 -19
  291. package/dist/tools/fs/bash-readonly-classifier.js +5 -10
  292. package/dist/tools/fs/fs-bash.js +10 -3
  293. package/dist/tools/fs/fs-write.d.ts +6 -3
  294. package/dist/tools/fs/fs-write.js +8 -7
  295. package/dist/tools/fs/index.d.ts +3 -0
  296. package/dist/tools/fs/index.js +1 -1
  297. package/dist/tools/fs/pattern-kill-guard.d.ts +3 -2
  298. package/dist/tools/fs/pattern-kill-guard.js +68 -36
  299. package/dist/tools/fs/safety.js +40 -8
  300. package/dist/tools/fs/search.js +6 -24
  301. package/dist/tools/fs/shell-read-check.d.ts +18 -1
  302. package/dist/tools/fs/shell-read-check.js +66 -16
  303. package/dist/tools/fs/shell-read-establish.js +2 -1
  304. package/dist/tools/fs/shell-read-identity.d.ts +12 -9
  305. package/dist/tools/fs/shell-read-identity.js +10 -5
  306. package/dist/tools/fs/shell-read-judge.d.ts +10 -1
  307. package/dist/tools/web.js +9 -7
  308. package/dist/tools/worktree.d.ts +42 -15
  309. package/dist/tools/worktree.js +60 -32
  310. package/package.json +4 -2
  311. package/test/export-surface.snapshot.json +141 -3
  312. package/wire-changes/core-stores-sql@7.57.0.json +29 -0
  313. package/wire-changes/core-stores-sql@7.58.0.json +29 -0
  314. package/wire-changes/core@7.57.0.json +1487 -0
  315. package/wire-changes/core@7.58.0.json +2188 -0
  316. package/wire-changes/mods-kernel@7.57.0.json +29 -0
  317. package/wire-changes/mods-kernel@7.58.0.json +81 -0
  318. package/wire-changes/primitives@7.57.0.json +245 -0
  319. package/wire-changes/primitives@7.58.0.json +29 -0
@@ -1,7 +1,8 @@
1
1
  import { requireWriteGate } from "./consolidation-write-gate.js";
2
2
  import { readMember, thrownText } from "../thrown-value.js";
3
3
  import { assertServableRequestRoot, joinRequestUrl } from "../../brain/route-adjudicator.js";
4
- import { holdOwnCredentialValues } from "../secret-env.js";
4
+ import { holdOwnCredentialValues, namesASecret } from "../secret-env.js";
5
+ import { remoteWords } from "../protocol-http-auth.js";
5
6
  export const DISTILLER_DEFAULT_MAX_INPUTS_PER_PRODUCT = 32;
6
7
  const SIZE_CLAUSE = {
7
8
  "dl-2": "- the index should be as small as it can be made without losing either of the above.",
@@ -171,29 +172,37 @@ export function openAiCompatChatSeat(seat) {
171
172
  catch (e) {
172
173
  throw distillerConfigRefusal(thrownText(e), e);
173
174
  }
175
+ const declared = namesASecret(apiKey) ? [apiKey] : [];
174
176
  return async (req) => {
175
- const res = await fetch(joinRequestUrl(requestRoot, "/chat/completions"), {
176
- method: "POST",
177
- headers: { "content-type": "application/json", authorization: `Bearer ${apiKey}` },
178
- body: JSON.stringify({
179
- model: seat.model,
180
- messages: [
181
- { role: "system", content: req.system },
182
- { role: "user", content: req.user },
183
- ],
184
- temperature: req.temperature,
185
- max_tokens: req.maxTokens,
186
- }),
187
- });
188
- const text = await res.text();
177
+ let res;
178
+ let text;
179
+ try {
180
+ res = await fetch(joinRequestUrl(requestRoot, "/chat/completions"), {
181
+ method: "POST",
182
+ headers: { "content-type": "application/json", authorization: `Bearer ${apiKey}` },
183
+ body: JSON.stringify({
184
+ model: seat.model,
185
+ messages: [
186
+ { role: "system", content: req.system },
187
+ { role: "user", content: req.user },
188
+ ],
189
+ temperature: req.temperature,
190
+ max_tokens: req.maxTokens,
191
+ }),
192
+ });
193
+ text = await res.text();
194
+ }
195
+ catch (e) {
196
+ throw new Error(`model call failed: ${remoteWords(thrownText(e), declared)}`);
197
+ }
189
198
  if (!res.ok)
190
- throw new Error(`model call failed ${res.status}: ${text.slice(0, 400)}`);
199
+ throw new Error(`model call failed ${res.status}: ${remoteWords(text, declared).slice(0, 400)}`);
191
200
  let body;
192
201
  try {
193
202
  body = JSON.parse(text);
194
203
  }
195
204
  catch {
196
- throw new Error(`model returned non-JSON envelope: ${text.slice(0, 400)}`);
205
+ throw new Error(`model returned non-JSON envelope: ${remoteWords(text, declared).slice(0, 400)}`);
197
206
  }
198
207
  return {
199
208
  content: body.choices?.[0]?.message?.content ?? "",
@@ -6,6 +6,7 @@ import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
6
6
  import { MEMORY_ORIGIN_CAUSES } from "./types.js";
7
7
  import { physicalPathOf, physicalPathOfExisting, priorCallerCasedPathOf } from "../physical-path.js";
8
8
  import { thrownLabel, thrownText } from "../thrown-value.js";
9
+ import { egressText } from "../untrusted-egress.js";
9
10
  const SCOPES_FILE = "scopes.json";
10
11
  export const CURSORS_FILE = "cursors.json";
11
12
  export const CONTROL_PLANE_DIR = ".engine";
@@ -1467,6 +1468,7 @@ function readSidecarJson(controlDir, fileName) {
1467
1468
  }
1468
1469
  return undefined;
1469
1470
  }
1471
+ const mintedItems = (items) => items.map((item) => egressText("same-principal", item));
1470
1472
  function coerceAnnouncements(raw) {
1471
1473
  const rec = { folded: 0, queue: [] };
1472
1474
  if (!raw || typeof raw !== "object" || Array.isArray(raw))
@@ -1488,7 +1490,7 @@ function coerceAnnouncements(raw) {
1488
1490
  at: a.at,
1489
1491
  ...(typeof a.sessionId === "string" ? { sessionId: a.sessionId } : {}),
1490
1492
  ...(typeof a.reportId === "string" ? { reportId: a.reportId } : {}),
1491
- items: a.items,
1493
+ items: mintedItems(a.items),
1492
1494
  });
1493
1495
  }
1494
1496
  }
@@ -1496,7 +1498,8 @@ function coerceAnnouncements(raw) {
1496
1498
  return rec;
1497
1499
  }
1498
1500
  export function enqueueMemoryAnnouncement(controlDir, ann, opts) {
1499
- const family = opts?.supersedesPrefix;
1501
+ ann = { ...ann, items: mintedItems(ann.items) };
1502
+ const family = opts?.supersedesPrefix === undefined ? undefined : egressText("same-principal", opts.supersedesPrefix);
1500
1503
  if (ann.items.length === 0 && family === undefined)
1501
1504
  return;
1502
1505
  lockedJournaledUpdate(controlDir, ANNOUNCEMENTS_FILE, (current) => {
@@ -1,3 +1,4 @@
1
+ import type { ExecutionEnv } from "../../internal/harness-types.js";
1
2
  /** Per-segment cap, measured AFTER encoding. A conservative portability policy adopted as contract
2
3
  * (research (d) recommendation — NOT a verified third-party hard limit; uuidv7 = 36 chars fits). */
3
4
  export declare const SCOPE_SEGMENT_MAX_ENCODED = 64;
@@ -96,6 +97,17 @@ export declare function formatProjectMarker(projectId: string): string;
96
97
  export declare function parseProjectMarker(body: string): {
97
98
  projectId: string;
98
99
  } | null;
100
+ /** What the marker walk reads through: the filesystem the task root names — the leg's execution env (any `ExecutionEnv`
101
+ * satisfies it), or the host's ({@link hostProjectMarkerFs}) for a leg that has none. */
102
+ export type ProjectMarkerFs = Pick<ExecutionEnv, "exists" | "readTextFile">;
103
+ /** The host filesystem as a {@link ProjectMarkerFs} — what a leg whose env does no I/O reads its task root through (its
104
+ * root is a host path: the deployment's `rootPath`). `exists` answers `false` only for a path that is not there; any
105
+ * other failure is an error, never an absence. Read synchronously, as the memory phase always read the marker: a leg
106
+ * with no I/O of its own gains no event-loop turn from its project read (its scheduling against sibling legs stays). */
107
+ export declare const hostProjectMarkerFs: ProjectMarkerFs;
108
+ /** The filesystem a leg's task root names: its execution env, or the host's when the env is the no-I/O placeholder (a leg
109
+ * with no env, or one handed none — the hands band's own "is there a filesystem" reading). */
110
+ export declare function projectMarkerFsOf(env: ExecutionEnv): ProjectMarkerFs;
99
111
  /**
100
112
  * design/142 §1.1 — resolve a project's identity. READS ONLY THE MARKER (复审 F2: never derives an
101
113
  * identity from a git remote; remote-URL normalization is a scaffold-side minting heuristic, not an
@@ -104,10 +116,39 @@ export declare function parseProjectMarker(body: string): {
104
116
  * repo root is fail-loud (`config.memory_project_marker_nested`) — monorepo sub-project identity
105
117
  * is a future need-signal, not a silent second identity;
106
118
  * - outside git, the given rootDir IS the project root (path-form local projects).
107
- * Returns null when no marker exists (callers fall through the resolution ladder: explicit
108
- * declaration → path fallback with a warning).
119
+ * Read through `fs` — the filesystem `rootDir` names (a remote env's marker lives in that env). A lookup
120
+ * the filesystem could not answer, or a marker it could not read, is `config.memory_project_marker` (never "no marker").
121
+ * Returns null when no marker exists. The leg's verdict over this read is {@link resolveSessionProject}.
109
122
  */
110
- export declare function resolveProjectId(rootDir: string): {
123
+ export declare function resolveProjectId(fs: ProjectMarkerFs, rootDir: string): Promise<{
111
124
  projectId: string;
112
125
  markerDir: string;
113
- } | null;
126
+ } | null>;
127
+ /** A leg's project identity. `marker` = the checkout's `.sema/project` (a declaration, when present,
128
+ * equals it); `declared` = `TaskSpec.projectId` in a checkout that carries no marker. */
129
+ export interface SessionProject {
130
+ readonly id: string;
131
+ readonly source: "marker" | "declared";
132
+ }
133
+ /** The ONE verdict every reader of a leg's project identity reads (the `workspace_changed` frame, memory v2). */
134
+ export interface SessionProjectVerdict {
135
+ /** The root the verdict was decided on (the leg's task root): a reader keeping facts about ANOTHER root (memory's
136
+ * per-partition marker hint) reads the verdict as a fact about this root only. */
137
+ readonly root: string;
138
+ /** ABSENT = no marker and no declaration, or the marker could not be read ({@link markerFault} says why). */
139
+ readonly project?: SessionProject;
140
+ /** Why the marker could not be read (nested / corrupt / unreadable), on a leg that declared no project — reported by
141
+ * the caller, NOT thrown here: only a reader that consumes project identity refuses with it (memory v2 `proj:` /
142
+ * `userproj:` keys). A leg that DECLARED a project consumes it, so there the fault is thrown. */
143
+ readonly markerFault?: Error & {
144
+ code: string;
145
+ };
146
+ }
147
+ /**
148
+ * The leg's ONE project-identity judge, called once per leg on the task root. The marker decides when the
149
+ * checkout carries one; `declared` (`TaskSpec.projectId`) is the identity only where it does not. Refuses the leg when
150
+ * `declared` is not a UUID (`config.project_id_invalid`), when it names a different project than the marker
151
+ * (`config.project_identity_mismatch` — never file the session under the wrong project), and when the marker cannot be
152
+ * read while a declaration needs checking against it (the marker's own code).
153
+ */
154
+ export declare function resolveSessionProject(fs: ProjectMarkerFs, taskRoot: string, declared: string | undefined): Promise<SessionProjectVerdict>;
@@ -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
+ }
@@ -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;
@@ -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));
@@ -21,8 +21,12 @@
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.
24
28
  */
25
- export declare const KERNEL_CONTRACT_VERSION = 3;
29
+ export declare const KERNEL_CONTRACT_VERSION = 4;
26
30
  /** The five tiers in run order (CC names). `builtin` and `core` are the engine's own. */
27
31
  export declare const MOD_TIERS: readonly ["prepend", "user", "append", "builtin", "core"];
28
32
  export type ModTier = (typeof MOD_TIERS)[number];
@@ -1,4 +1,4 @@
1
- export const KERNEL_CONTRACT_VERSION = 3;
1
+ export const KERNEL_CONTRACT_VERSION = 4;
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"]);
@@ -118,11 +118,14 @@ export interface ModRegistration<D extends ModDollarBase = ModDollarBase> {
118
118
  readonly options?: unknown;
119
119
  register(on: On<D>, options: unknown): void;
120
120
  }
121
- /** One admission result: mounted (with the patterns it actually hung) or refused (by whom, why). */
121
+ /** One admission result: mounted (with the patterns it actually hung, and among them the ones on which every handler it
122
+ * hung watches) or refused (by whom, why). `provenance` is the registration's own label, carried as the host gave it on
123
+ * either arm — absent when the host gave none. */
122
124
  export type ModAdmissionRecord = {
123
125
  readonly name: string;
124
126
  readonly seat: ModSeat;
125
127
  readonly tier: ModTier;
128
+ readonly provenance?: string;
126
129
  readonly events: readonly string[];
127
130
  readonly observe?: readonly string[];
128
131
  /** Judges skipped while this registration was judged (their failure or site violation), as the dispatch listed them. */
@@ -131,6 +134,7 @@ export type ModAdmissionRecord = {
131
134
  readonly name: string;
132
135
  readonly seat: ModSeat;
133
136
  readonly tier: ModTier;
137
+ readonly provenance?: string;
134
138
  readonly refusedBy: string;
135
139
  readonly reason: string;
136
140
  };
@@ -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
+ }