@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,3 +1,4 @@
1
+ import { egressThrownText } from "./untrusted-egress.js";
1
2
  export const REOPEN_REASONS = Object.freeze(["env_failed", "tool_unavailable", "constraint_rejected", "config_refused"]);
2
3
  export const RESUME_STARTUP_CAUSES = Object.freeze(["environment", "session_gone", "transcript_corrupt", "tool_unavailable", "configuration", "decision_rejected"]);
3
4
  const CAUSE_OF_CODE = new Map([
@@ -44,7 +45,25 @@ const REOPEN_REASON_OF_CAUSE = {
44
45
  export function reopenReasonOf(cause) {
45
46
  return cause === undefined ? "env_failed" : REOPEN_REASON_OF_CAUSE[cause];
46
47
  }
47
- export function reopenedUnstartedSentence(reason) {
48
+ export async function compensateUnstarted(reopen, reason) {
49
+ try {
50
+ return (await reopen(reason)) === "reopened" ? { kind: "reopened", reason } : { kind: "declined" };
51
+ }
52
+ catch (thrown) {
53
+ return { kind: "unknown", thrown };
54
+ }
55
+ }
56
+ export function unstartedRowSentence(row) {
57
+ switch (row.kind) {
58
+ case "reopened":
59
+ return reopenedUnstartedSentence(row.reason);
60
+ case "declined":
61
+ return "the approved action never started, and the store DECLINED to reopen the checkpoint — it is no longer the resolved row this leg claimed (missing, expired, its decided action already disposed, or pending again): read the row before deciding; if it is resolved or gone, a retry needs a fresh approval";
62
+ case "unknown":
63
+ return `the approved action never started, and reopening the checkpoint FAILED IN FLIGHT (${egressThrownText("same-principal", row.thrown)}) — its state UNKNOWN, unprovable from here: re-read it before deciding; do NOT issue a fresh approval on the assumption the old one is dead`;
64
+ }
65
+ }
66
+ function reopenedUnstartedSentence(reason) {
48
67
  switch (reason) {
49
68
  case "env_failed":
50
69
  return "the approved action never started, so the checkpoint was REOPENED (pending): the same approval can be resumed again, do not ask for a fresh one";
@@ -1,12 +1,21 @@
1
- /** A store's retention capability declaration. Absent ⇒ read fail-closed as `"none"`. */
1
+ /** A store's retention declaration: `"managed"` = this store's rows are deleted on schedule by the
2
+ * deployment; `"none"` = nothing deletes them on schedule. Absent ⇒ read fail-closed as `"none"`. */
2
3
  export type RetentionDeclaration = "managed" | "none";
3
4
  /** The declaration face a storage implementation carries (structural — every store interface's
4
- * optional `retention` field conforms). `"managed"` is a PROMISE to honor
5
- * {@link ManagedRetentionCapability}; `"none"` is the honest default for stores that cannot delete
6
- * on schedule (all bundled in-memory/TTL stores declare it). */
5
+ * optional `retention` field conforms). The word is the deployment's statement about this store's
6
+ * rows (see {@link RetentionDeclaration}), given by the party that runs the sweep when it constructs
7
+ * the store: the bundled stores take it as their `retention` option and default to `"none"`. */
7
8
  export interface RetentionDeclaring {
8
9
  readonly retention?: RetentionDeclaration;
9
10
  }
11
+ /**
12
+ * The one reader of a retention declaration word — the startup validation's and every bundled store's
13
+ * constructor option's. `undefined` reads as `"none"`; anything but the two words is refused
14
+ * (`config.retention_capability`), so a typo'd declaration never silently means anything.
15
+ *
16
+ * @param name the deployment-facing name of where the word was read (a store seat, an option).
17
+ */
18
+ export declare function readRetentionDeclaration(name: string, value: unknown): RetentionDeclaration;
10
19
  /**
11
20
  * The deployment's managed-retention policy ({@link import("./types.js").RunnerDeps.retentionPolicy}).
12
21
  * Core consumes it ONLY for the startup capability validation (and exposes it to the deployment's
@@ -19,9 +28,10 @@ export interface RetentionPolicy {
19
28
  maxAgeDays: number;
20
29
  }
21
30
  /**
22
- * What a `retention: "managed"` store PROMISES (contract TYPE — core ships no implementation; the
23
- * server half consumes this. Reference implementation of the cascade: the server's session-purge
24
- * order contract). Every method is expected to be:
31
+ * The executor that deletes the rows of the stores declaring `retention: "managed"` — a backend's
32
+ * `retention` member (contract TYPE — core ships no implementation; the server half consumes this.
33
+ * Reference implementation of the cascade: the server's session-purge order contract). A deployment
34
+ * that declares a store managed runs one over that store's rows. Every method is expected to be:
25
35
  * - **tenant-domain scoped**: work is enumerated and executed per retention domain (tenant/scope),
26
36
  * never as one global sweep;
27
37
  * - **idempotent**: a retried invocation after a crash re-converges (already-deleted rows are
@@ -84,14 +94,8 @@ export interface RetentionReceipt {
84
94
  /** Tombstones written for the deleted rows. */
85
95
  tombstones: number;
86
96
  }
87
- /**
88
- * Startup validation (and per-prepare backstop): with the retention policy LOCKED and configured,
89
- * every wired store must declare `retention: "managed"` — a locked policy over a store that cannot
90
- * delete is refused (`config.retention_capability`), never silently accepted. Also fail-loud
91
- * validates the policy value itself (`config.retention_policy`). Exported for deployments to call at
92
- * their own startup; the prepare preflight re-runs it on every leg regardless.
93
- */
94
- export declare function assertRetentionCapability(input: {
97
+ /** The stores whose words are judged, and the policy that judges them. */
98
+ interface RetentionWords {
95
99
  policy: RetentionPolicy | undefined;
96
100
  /** Whether locked-config locks the `retentionPolicy` key (locked-config.ts `LockedKey`). */
97
101
  locked: boolean;
@@ -102,4 +106,26 @@ export declare function assertRetentionCapability(input: {
102
106
  name: string;
103
107
  store: object | undefined;
104
108
  }>;
109
+ }
110
+ /**
111
+ * The declaration half of the check — all a caller that holds no executor can judge: the policy value, every
112
+ * wired store's word, and, with the retention policy LOCKED and configured, every store declaring
113
+ * `retention: "managed"` — a locked policy over a store that cannot delete is refused
114
+ * (`config.retention_capability`), never silently accepted. The task-prepare preflight runs it on every leg;
115
+ * a deployment's own startup calls {@link assertRetentionCapability}, which runs it too.
116
+ */
117
+ export declare function assertRetentionWords(input: RetentionWords): void;
118
+ /**
119
+ * Startup validation, the deployment's call: the declaration half ({@link assertRetentionWords}) and the
120
+ * declaration held to the executor the deployment runs. `executor` is required — the
121
+ * {@link ManagedRetentionCapability} the deployment runs over these stores' rows (a backend's `retention` member),
122
+ * or `null` when it runs none; `undefined` is refused (`config.retention_capability`), so a backend's absent
123
+ * member is never read as "judge the words alone". Locked or not, a store saying `"managed"` (its rows are deleted
124
+ * on schedule) beside `executor: null` is refused, and so is an executor that is not one. A `"none"` store beside
125
+ * an executor is not refused — a deployment may hold the executor and not run it on a store, and a locked policy
126
+ * refuses that store by its word.
127
+ */
128
+ export declare function assertRetentionCapability(input: RetentionWords & {
129
+ executor: ManagedRetentionCapability | null;
105
130
  }): void;
131
+ export {};
@@ -1,4 +1,12 @@
1
1
  import { describeRejectedValue } from "./tool-search-setting.js";
2
+ import { thrownText } from "./thrown-value.js";
3
+ export function readRetentionDeclaration(name, value) {
4
+ if (value === undefined || value === "none")
5
+ return "none";
6
+ if (value === "managed")
7
+ return "managed";
8
+ throw codedError("config.retention_capability", `store "${name}" declares an unparseable retention value ${describeRejectedValue(value)} — expected "managed" or "none".`);
9
+ }
2
10
  export const RETENTION_CASCADE_DOMAINS = Object.freeze(["checkpoints", "session-trees", "orphan-tool-results"]);
3
11
  export const RETENTION_CASCADE_EXEMPT = Object.freeze(["session-pollution", "session-capture-optout", "lineage.json"]);
4
12
  function codedError(code, message) {
@@ -6,8 +14,30 @@ function codedError(code, message) {
6
14
  e.code = code;
7
15
  return e;
8
16
  }
9
- export function assertRetentionCapability(input) {
10
- const { policy, locked, stores } = input;
17
+ const RETENTION_EXECUTOR_MEMBERS = Object.keys({
18
+ listRetentionDomains: true,
19
+ expireCheckpoints: true,
20
+ deleteExpiredSessions: true,
21
+ deleteOrphanToolResults: true,
22
+ });
23
+ function assertRetentionExecutor(executor) {
24
+ if ((typeof executor !== "object" && typeof executor !== "function") || executor === null) {
25
+ throw codedError("config.retention_capability", `the retention executor must be an object implementing ManagedRetentionCapability, or null when the deployment runs none (got ${describeRejectedValue(executor)}).`);
26
+ }
27
+ for (const member of RETENTION_EXECUTOR_MEMBERS) {
28
+ let value;
29
+ try {
30
+ value = executor[member];
31
+ }
32
+ catch (cause) {
33
+ throw codedError("config.retention_capability", `the retention executor's ${member} could not be read (${thrownText(cause)}) — it is not a ManagedRetentionCapability.`);
34
+ }
35
+ if (typeof value !== "function") {
36
+ throw codedError("config.retention_capability", `the retention executor's ${member} is ${describeRejectedValue(value)}, not a function — it is not a ManagedRetentionCapability.`);
37
+ }
38
+ }
39
+ }
40
+ function readRetentionWords({ policy, stores }) {
11
41
  const declared = policy;
12
42
  if (declared !== undefined && (typeof declared !== "object" || declared === null || Array.isArray(declared))) {
13
43
  throw codedError("config.retention_policy", `retentionPolicy must be an object carrying maxAgeDays (got ${declared === null ? "null" : Array.isArray(declared) ? "an array" : typeof declared}).`);
@@ -15,17 +45,34 @@ export function assertRetentionCapability(input) {
15
45
  if (policy !== undefined && (!Number.isFinite(policy.maxAgeDays) || policy.maxAgeDays < 0)) {
16
46
  throw codedError("config.retention_policy", `retentionPolicy.maxAgeDays must be a finite non-negative number of days (got ${describeRejectedValue(policy.maxAgeDays)}).`);
17
47
  }
18
- const declaredRetention = (name, store) => {
19
- const r = store.retention;
20
- if (r === undefined || r === "none")
21
- return "none";
22
- if (r === "managed")
23
- return "managed";
24
- throw codedError("config.retention_capability", `store "${name}" declares an unparseable retention value ${JSON.stringify(r)} — expected "managed" or "none".`);
25
- };
26
- const declarations = stores
48
+ return stores
27
49
  .filter((s) => s.store !== undefined && s.store !== null)
28
- .map(({ name, store }) => ({ name, retention: declaredRetention(name, store) }));
50
+ .map(({ name, store }) => ({ name, retention: readRetentionDeclaration(name, store.retention) }));
51
+ }
52
+ export function assertRetentionWords(input) {
53
+ const { policy, locked, stores } = input;
54
+ const words = { policy, locked, stores };
55
+ refuseLockedOverNone(words, readRetentionWords(words));
56
+ }
57
+ export function assertRetentionCapability(input) {
58
+ const { policy, locked, stores, executor } = input;
59
+ const words = { policy, locked, stores };
60
+ if (executor === undefined) {
61
+ throw codedError("config.retention_capability", `executor is required — the managed-retention executor the deployment runs over these stores' rows (a backend's \`retention\` member), or null when it runs none (got undefined).`);
62
+ }
63
+ const declarations = readRetentionWords(words);
64
+ if (executor !== null)
65
+ assertRetentionExecutor(executor);
66
+ else {
67
+ const unexecuted = declarations.filter(({ retention }) => retention === "managed");
68
+ if (unexecuted.length > 0) {
69
+ throw codedError("config.retention_capability", `${unexecuted.map((s) => s.name).join(", ")} declare${unexecuted.length === 1 ? "s" : ""} retention "managed" — rows deleted on schedule by the deployment — ` +
70
+ `but the deployment runs no retention executor: nothing would delete them. Declare those stores "none", or wire the executor that deletes their rows.`);
71
+ }
72
+ }
73
+ refuseLockedOverNone(words, declarations);
74
+ }
75
+ function refuseLockedOverNone({ policy, locked }, declarations) {
29
76
  if (!locked || policy === undefined)
30
77
  return;
31
78
  const incapable = declarations.filter(({ retention }) => retention !== "managed");
@@ -1,6 +1,43 @@
1
1
  import type { PreToolUseResult } from "./hooks.js";
2
2
  import type { PermissionResult } from "./tool-policy.js";
3
3
  import type { PreToolUseScreening } from "./runner/gate-exit.js";
4
+ import type { RewriteAuthor, ToolInputRewrite } from "./task-event.js";
5
+ /** One gate pass's account of its rewrites: the bytes it took at its entry, and one author per adoption that changed the bytes
6
+ * in hand (written only through {@link noteRewrite}). */
7
+ export interface RewriteAccount {
8
+ readonly entry: unknown;
9
+ readonly by: RewriteAuthor[];
10
+ }
11
+ /** An adoption of `to` in place of `from`, by `authors`: they are named when the two read as other bytes. */
12
+ export declare function noteRewrite(account: RewriteAccount, req: {
13
+ readonly face?: object | undefined;
14
+ }, from: unknown, to: unknown, authors: readonly RewriteAuthor[]): void;
15
+ /** The restriction chain's and the approver's word in an account (one author each, frozen once). */
16
+ export declare const POLICY_AUTHOR: readonly RewriteAuthor[];
17
+ export declare const APPROVER_AUTHOR: readonly RewriteAuthor[];
18
+ /** The extensions that authored a screening's rewrite, as authors. */
19
+ export declare const extensionAuthors: (names: readonly string[]) => readonly RewriteAuthor[];
20
+ /** The call's record at the allow exit: when `ran` (the bytes the gate lets go) is not the bytes it took, `snapshot` (their frozen
21
+ * plain-data projection, the exit's `finalInput`) with the authors the account holds. Bytes that moved with no author named is an
22
+ * engine defect (an adoption that did not name itself). */
23
+ export declare function rewriteRecordOf(account: RewriteAccount, req: {
24
+ readonly face?: object | undefined;
25
+ readonly toolName: string;
26
+ }, ran: unknown, snapshot: unknown): ToolInputRewrite | undefined;
27
+ /** The authors of each `classic.PreToolUse` answer one dispatch received, read by the answer's identity as the station receives
28
+ * it: a handler is an author when its answer's `updatedInput` reads as other bytes ({@link sameBytes}, under `req`'s reading) than
29
+ * what its `next()` returned (the event's `input` when that carried none, or when it never called `next`); otherwise its answer
30
+ * carries the authors of what came up. `record` is the station's answer check (it refuses nothing); `of` reads the chain's answer. */
31
+ export declare function screeningAuthorship(req: {
32
+ readonly face?: object | undefined;
33
+ }): {
34
+ readonly record: (answer: unknown, e: {
35
+ readonly input?: unknown;
36
+ }, by: {
37
+ readonly plugin: string;
38
+ }, below: readonly unknown[]) => undefined;
39
+ readonly of: (answer: unknown) => readonly string[];
40
+ };
4
41
  /** What a judge did with the bytes it was handed: kept them (`as_is`), or handed back another form. */
5
42
  export type RejudgeReading = {
6
43
  readonly kind: "as_is";
@@ -1,5 +1,45 @@
1
1
  import { canonicalize } from "./canonical-json.js";
2
2
  import { argsAsTheToolReads } from "./effective-path-target.js";
3
+ export function noteRewrite(account, req, from, to, authors) {
4
+ if (!sameBytes(req, from, to))
5
+ account.by.push(...authors);
6
+ }
7
+ export const POLICY_AUTHOR = Object.freeze([Object.freeze({ kind: "policy" })]);
8
+ export const APPROVER_AUTHOR = Object.freeze([Object.freeze({ kind: "approver" })]);
9
+ export const extensionAuthors = (names) => names.map((name) => Object.freeze({ kind: "extension", name }));
10
+ export function rewriteRecordOf(account, req, ran, snapshot) {
11
+ if (sameBytes(req, account.entry, ran))
12
+ return undefined;
13
+ if (account.by.length === 0)
14
+ throw new Error(`the arguments of "${req.toolName}" the gate lets go are not the ones it took, and no adoption named who replaced them — an engine defect`);
15
+ return Object.freeze({ by: Object.freeze([...account.by]), input: snapshot });
16
+ }
17
+ export function screeningAuthorship(req) {
18
+ const authors = new WeakMap();
19
+ const rewriteOf = (a) => Reflect.get(a, "updatedInput");
20
+ const same = (x, y) => { try {
21
+ return sameBytes(req, x, y);
22
+ }
23
+ catch {
24
+ return false;
25
+ } };
26
+ return {
27
+ record: (answer, e, by, below) => {
28
+ if (typeof answer !== "object" || answer === null || authors.has(answer))
29
+ return undefined;
30
+ let lower;
31
+ for (const b of below)
32
+ if (typeof b === "object" && b !== null)
33
+ lower = b;
34
+ const lowerAuthors = lower !== undefined ? (authors.get(lower) ?? []) : [];
35
+ const lowerBytes = lower !== undefined && rewriteOf(lower) !== undefined ? rewriteOf(lower) : e.input;
36
+ const mine = rewriteOf(answer);
37
+ authors.set(answer, mine === undefined ? [] : same(lowerBytes, mine) ? lowerAuthors : [...lowerAuthors, by.plugin]);
38
+ return undefined;
39
+ },
40
+ of: (answer) => (typeof answer === "object" && answer !== null ? (authors.get(answer) ?? []) : []),
41
+ };
42
+ }
3
43
  export function sameBytes(req, a, b) {
4
44
  return a === b || canonicalize(argsAsTheToolReads(req, a)) === canonicalize(argsAsTheToolReads(req, b));
5
45
  }
@@ -1,6 +1,7 @@
1
1
  import { selectModel } from "./select-model.js";
2
2
  import { namesRoleBase } from "../prompt-assembly/role-base.js";
3
3
  import { readPromptRole } from "../prompt-assembly/select.js";
4
+ import { readMember } from "./thrown-value.js";
4
5
  import { MODEL_ROLES } from "./types.js";
5
6
  export { MODEL_ROLES } from "./types.js";
6
7
  function catalogModel(ref, models) {
@@ -13,13 +14,36 @@ function modelBindingRefusal(field, reason, message) {
13
14
  e.detail = { field, reason };
14
15
  return e;
15
16
  }
17
+ const ROLE_RECORD_KEYS = new Set(["model", "select", "thinking", "promptRole", "systemPrompt"]);
18
+ function isModelShaped(s) {
19
+ try {
20
+ if (typeof s === "function" || isList(s)) {
21
+ Reflect.ownKeys(s);
22
+ return false;
23
+ }
24
+ if (Reflect.ownKeys(s).some((k) => typeof k !== "string" || !ROLE_RECORD_KEYS.has(k)))
25
+ return true;
26
+ return readMember(s, "id") !== undefined || readMember(s, "api") !== undefined;
27
+ }
28
+ catch {
29
+ return true;
30
+ }
31
+ }
16
32
  function isBindingObject(value) {
17
33
  return (typeof value === "object" && value !== null) || typeof value === "function";
18
34
  }
19
35
  function bindingShown(value) {
20
36
  if (typeof value === "string")
21
37
  return JSON.stringify(value.length > 80 ? `${value.slice(0, 80)}…` : value);
22
- return value === null ? "null" : Array.isArray(value) ? "a list" : `a ${typeof value}`;
38
+ return value === null ? "null" : isList(value) ? "a list" : `a ${typeof value}`;
39
+ }
40
+ function isList(value) {
41
+ try {
42
+ return Array.isArray(value);
43
+ }
44
+ catch {
45
+ return false;
46
+ }
23
47
  }
24
48
  function unknownModelRefRefusal(ref, seat) {
25
49
  return modelBindingRefusal(seat, "unknown_model_ref", `Unknown model ref ${bindingShown(ref)} in ${seat}. Provide it in RunnerDeps.models or pass a Model object.`);
@@ -30,6 +54,7 @@ function modelOfBinding(value, models, seat, binds) {
30
54
  const held = catalogModel(value, models);
31
55
  if (held === undefined)
32
56
  throw unknownModelRefRefusal(value, seat);
57
+ assertModelObject(held, seat, `${bindingShown(value)} (a catalog entry)`);
33
58
  return held;
34
59
  }
35
60
  return value;
@@ -37,9 +62,19 @@ function modelOfBinding(value, models, seat, binds) {
37
62
  function assertModelBindingShape(value, seat, binds) {
38
63
  if (typeof value === "string")
39
64
  return;
40
- if (typeof value !== "object" || value === null || Array.isArray(value)) {
65
+ if (typeof value !== "object" || value === null || isList(value)) {
41
66
  throw modelBindingRefusal(seat, "not_a_model_ref", `${seat} is ${bindingShown(value)}, not a model reference — ${binds}.`);
42
67
  }
68
+ assertModelObject(value, seat, "a Model object", binds === ROLE_BINDS ? " At a role seat an object with a key beyond model / select / thinking / promptRole / systemPrompt is read as a Model, not as a role record." : "");
69
+ }
70
+ function assertModelObject(value, seat, what, note = "") {
71
+ const id = readMember(value, "id");
72
+ const api = readMember(value, "api");
73
+ const [member, got] = typeof id !== "string" || id === "" ? ["id", id] : typeof api !== "string" ? ["api", api] : [undefined, undefined];
74
+ if (member === undefined)
75
+ return;
76
+ const shown = got === undefined ? "absent" : bindingShown(got);
77
+ throw modelBindingRefusal(seat, "not_a_model_ref", `${seat} is ${what} whose \`${member}\` is ${shown} — a Model carries a non-empty string \`id\` and a string \`api\`.${note}`);
43
78
  }
44
79
  const ROLE_BINDS = "a role binds a catalog model name or a Model object";
45
80
  const roleModelSeat = (named, seat) => (typeof named === "string" ? seat : `${seat}.model`);
@@ -158,7 +193,10 @@ function roleTierModel(role, models) {
158
193
  if (!models || !models[TIERS_ACTIVE])
159
194
  return undefined;
160
195
  const tier = ROLE_TIER_DEFAULTS[role];
161
- return tier !== undefined ? models[tier] : undefined;
196
+ const m = tier !== undefined ? models[tier] : undefined;
197
+ if (m)
198
+ assertModelObject(m, `tiers.${String(tier)}`, "the catalog entry the tier word names");
199
+ return m;
162
200
  }
163
201
  const FALLBACK = {
164
202
  default: [],
@@ -178,7 +216,7 @@ function specParts(s, seat = "a role seat") {
178
216
  if (!isBindingObject(s)) {
179
217
  throw modelBindingRefusal(seat, "not_a_model_ref", `${seat} is ${bindingShown(s)}, not a model reference — a role binds a catalog model name, a Model object or a { model, select, thinking, systemPrompt } record.`);
180
218
  }
181
- if ("id" in s && "api" in s) {
219
+ if (isModelShaped(s)) {
182
220
  return { model: s };
183
221
  }
184
222
  const cfg = s;
@@ -192,7 +230,7 @@ function toConfig(s) {
192
230
  if (s === undefined) {
193
231
  return undefined;
194
232
  }
195
- if (typeof s === "string" || ("id" in s && "api" in s)) {
233
+ if (typeof s === "string" || isModelShaped(s)) {
196
234
  return { model: s };
197
235
  }
198
236
  return s;
@@ -248,8 +286,13 @@ function partsModel(parts, models, seat = "a role seat") {
248
286
  if (needs != null && !Array.isArray(needs)) {
249
287
  throw modelBindingRefusal(`${seat}.select`, "not_a_model_ref", `${seat}.select.needs is ${bindingShown(needs)}, not a list of capabilities (vision / reasoning).`);
250
288
  }
251
- const held = models != null && typeof models === "object" ? Object.values(models).filter(Boolean) : [];
252
- return selectModel(held, parts.select);
289
+ const held = models != null && typeof models === "object" ? Object.entries(models).filter(([, m]) => Boolean(m)) : [];
290
+ for (const [key, m] of held)
291
+ assertModelObject(m, `${seat}.select`, `the catalog entry ${bindingShown(key)} the criteria read`);
292
+ const picked = selectModel(held.map(([, m]) => m), parts.select);
293
+ if (picked !== undefined)
294
+ assertModelObject(picked, `${seat}.select`, "the catalog entry the criteria pick");
295
+ return picked;
253
296
  }
254
297
  return undefined;
255
298
  }
@@ -0,0 +1,40 @@
1
+ export declare const RUN_ORIGINS: readonly ["scheduled"];
2
+ export type RunOrigin = (typeof RUN_ORIGINS)[number];
3
+ /** Membership test for {@link RunOrigin}: the one a host checks the word it is about to stamp against. */
4
+ export declare function isRunOrigin(v: unknown): v is RunOrigin;
5
+ /** The checkpoint row's recorded word: absent or a member passes; anything else is a row this engine cannot resume under
6
+ * (`config.run_origin_invalid`). A resume's screen asks it after the row's reader requirements were judged, so a row a newer
7
+ * engine wrote is refused as newer first. */
8
+ export declare function screenRecordedRunOrigin(recorded: unknown): RunOrigin | undefined;
9
+ /**
10
+ * THE door of the declared word, and the leg's one reading of it. `declared` is the leg's config's word — the task spec's on a
11
+ * fresh leg, where it is the objective's; `row` is present on a resumed leg only and carries the word its checkpoint recorded
12
+ * and, when the resume hands over inputs to open the leg with (a wake), the newest one's word as `opening.word`
13
+ * ({@link wakeOpening}). On a fresh leg absent passes as absent, a member passes, and anything else present is refused loudly
14
+ * (`config.run_origin_invalid`), never folded to "the host said nothing" (that silence is exactly the invisibility the word
15
+ * exists to end).
16
+ *
17
+ * A resume config carries NO word, any value refused: a resume hands the engine no objective, so the field would have nothing
18
+ * to describe — the resumed leg's word is its opening input's when a wake opened it (absent included: a message that says
19
+ * nothing is not the row's word), the row's otherwise. Prepare's config doors and a resume's screen before the claim call this
20
+ * one function, so a resume prepare would refuse is refused while the row is pending.
21
+ */
22
+ export declare function runOriginOfLeg(declared: unknown, row?: {
23
+ readonly recorded: RunOrigin | undefined;
24
+ readonly opening?: {
25
+ readonly word: unknown;
26
+ };
27
+ }): RunOrigin | undefined;
28
+ /**
29
+ * The input that opens a woken leg: the NEWEST the wake hands over — its message, else the parked entry it delivers last
30
+ * (`parked` in `seq` order) — so a message-bearing wake and its atomic equivalent (`setPendingSteer` then a message-less wake)
31
+ * give the leg the same word. `undefined` when it hands over nothing. A decision on a parked leg opens nothing: what it
32
+ * delivers rides along with the answer, and the leg continues the row's word.
33
+ */
34
+ export declare function wakeOpening(parked: ReadonlyArray<{
35
+ readonly runOrigin?: unknown;
36
+ }>, message: {
37
+ readonly runOrigin?: unknown;
38
+ } | undefined): {
39
+ readonly word: unknown;
40
+ } | undefined;
@@ -0,0 +1,37 @@
1
+ import { describeRejectedValue } from "./tool-search-setting.js";
2
+ export const RUN_ORIGINS = Object.freeze(["scheduled"]);
3
+ const RUN_ORIGIN_SET = new Set(RUN_ORIGINS);
4
+ export function isRunOrigin(v) {
5
+ return RUN_ORIGIN_SET.has(v);
6
+ }
7
+ const WORDS = RUN_ORIGINS.map((w) => JSON.stringify(w)).join(" | ");
8
+ function refusal(message) {
9
+ const e = new Error(message);
10
+ e.code = "config.run_origin_invalid";
11
+ return e;
12
+ }
13
+ export function screenRecordedRunOrigin(recorded) {
14
+ if (recorded === undefined || isRunOrigin(recorded))
15
+ return recorded;
16
+ throw refusal(`the checkpoint row's runOrigin is ${describeRejectedValue(recorded)}, not a run origin this engine knows (${WORDS}) — the row cannot be resumed under a word nobody can read`);
17
+ }
18
+ export function runOriginOfLeg(declared, row) {
19
+ if (row !== undefined && declared !== undefined) {
20
+ throw refusal(`a resume config declares runOrigin ${describeRejectedValue(declared)} — a resume carries no run origin in its config: omit the field. ` +
21
+ `The resumed leg reads the word of the input that opens it — a wake states it on its message (message.runOrigin) — or else the parked row's (CheckpointSummary.runOrigin)`);
22
+ }
23
+ if (declared !== undefined && !isRunOrigin(declared)) {
24
+ throw refusal(`runOrigin ${describeRejectedValue(declared)} is not a run origin (${WORDS}) — omit it when the task was not started by the deployment's scheduler; an unreadable declaration is refused, never read as "not stated".`);
25
+ }
26
+ if (row === undefined)
27
+ return declared;
28
+ const opening = row.opening === undefined ? undefined : { word: row.opening.word };
29
+ if (opening !== undefined && opening.word !== undefined && !isRunOrigin(opening.word)) {
30
+ throw refusal(`the input that opens this leg declares runOrigin ${describeRejectedValue(opening.word)}, not a run origin (${WORDS}) — an unreadable declaration is refused, never read as "not stated".`);
31
+ }
32
+ return opening !== undefined ? opening.word : row.recorded;
33
+ }
34
+ export function wakeOpening(parked, message) {
35
+ const newest = message ?? parked[parked.length - 1];
36
+ return newest === undefined ? undefined : { word: newest.runOrigin };
37
+ }
@@ -1,46 +1,37 @@
1
- /**
2
- * The advertised-writable-directory seat — ONE rule for every directory the prompt tells the model
3
- * it may write with the file tools:
4
- *
5
- * a directory the prompt advertises as writable is a directory the root fence ADMITS; the same
6
- * admission decides the hole and the teaching, so a directory the fence cannot admit is neither
7
- * opened nor taught, and the skip is announced.
8
- *
9
- * Two advertisers share it: the deployment's scratchpad (`TaskSpec.envFacts.scratchpadDir`, spoken
10
- * by the `# Environment` block) and the memory engine's write root (spoken by the `# Memory`
11
- * instruction, "write to it directly with the Write tool"). Before this seat each advertiser judged
12
- * on its own: the scratchpad opened its hole in the hands phase, the memory instruction checked only
13
- * that a `Write` tool was mounted — and the fence refused the very path the instruction named
14
- * (`path_not_in_root`), a contradictory gate that taught the model to route around the tools.
15
- *
16
- * Admission = fail-closed canonicalization through the SAME ExecutionEnv the fence judges with (a
17
- * raw or dangling entry is never admitted — the ancestor-canonicalize fallback would let a symlinked
18
- * prefix carry writes outside every root). An advertiser that OWNS its directory's creation may ask
19
- * for materialization on a DEFINITIVE `not_found` (the exclusive-create marker, so a concurrently
20
- * planted path is never written through); an advertiser whose directory is created elsewhere passes
21
- * no marker and an absent directory narrows.
22
- *
23
- * A directory the fence already holds is never admitted as a HOLE in it: a candidate that resolves onto
24
- * a root — or above one — would turn that whole root into the advertised, write-gate-exempt domain, so
25
- * an ordinary source write inside the workspace would stop asking. One predicate
26
- * ({@link swallowedFenceRoot}) states that, and the write gate's configured domains apply the same one.
27
- *
28
- * Reverse check (the seat's own invariant): nothing enters `roots` except through `admit`, and every
29
- * caller of `admit` is an advertiser deciding its advertisement off the returned verdict — so no
30
- * directory reaches the ROOTS FENCE through this seat without the prompt advertising it, and none
31
- * the prompt advertises is refused by that fence.
32
- *
33
- * The invariant is about this seat, not about the whole write surface: under an open write face
34
- * ({@link import("../../tools/fs/containment-face.js").ContainmentFace}) the roots fence judges
35
- * nothing, so what the prompt advertises is a floor rather than the whole list — the `# Environment`
36
- * block says so in its own line, and the advertisement stays true (these directories ARE writable).
37
- */
38
1
  import type { ExecutionEnv } from "../../internal/harness.js";
2
+ /** The code a declared session plan file that cannot be held as stated refuses the run with (`TaskSpec.planFile`). */
3
+ export declare const PLAN_FILE_INVALID_CODE = "config.plan_file_invalid";
4
+ /** The coded refusal for `TaskSpec.planFile`: the value as given and why it cannot be the session's plan file. */
5
+ export declare function planFileInvalid(value: unknown, why: string): Error & {
6
+ code: string;
7
+ detail: {
8
+ planFile: unknown;
9
+ reason: string;
10
+ };
11
+ };
12
+ /** The declared plan file's SHAPE (no I/O): a non-empty absolute string in lexical normal form, else the coded refusal. */
13
+ export declare function checkedPlanFileShape(value: unknown): string | undefined;
14
+ /** How long a plan file's path may be: the longest path a platform spells (Linux PATH_MAX) — it is told to the model whole. */
15
+ export declare const PLAN_PATH_MAX = 4096;
16
+ /** How the plan file is told to the model (the plan-exit tool, the planning frames, the post-compaction reference): whole
17
+ * and verbatim — {@link checkedPlanFileShape} refuses a declared path this would re-spell, so for an admitted file this is
18
+ * the path itself; the defusing stays as the trusted line's guard. The ONE renderer: every teller reads its answer. */
19
+ export declare function planFileShown(path: string): string;
20
+ /** The most of a plan file the plan's readers take (1 MiB): a file past it is refused, never truncated into a plan. */
21
+ export declare const PLAN_FILE_MAX_BYTES: number;
22
+ /** What the session plan file holds: its text (`undefined` = not written yet — absent, or blank), or why it could not be read. */
23
+ export type PlanFileReading = {
24
+ readonly ok: true;
25
+ readonly text: string | undefined;
26
+ } | {
27
+ readonly ok: false;
28
+ readonly reason: string;
29
+ };
39
30
  export interface AdvertisedWritableDir {
40
31
  /** The directory as the advertisement spells it. */
41
32
  path: string;
42
33
  /** Who advertises it — names the skip line and the trace. */
43
- advertiser: "scratchpad" | "memory";
34
+ advertiser: "scratchpad" | "memory" | "plan";
44
35
  /**
45
36
  * How the directory comes to exist when the env reports it absent. The advertiser that owns the
46
37
  * directory's creation supplies the marker file name for the atomic exclusive-create
@@ -122,6 +113,34 @@ export declare class AdvertisedWritableDirs {
122
113
  /** The admitted roots, CANONICAL, in admission order, deduplicated. The hands phase folds this list into the
123
114
  * write-capable containment allowlist before the toolkit compiles; it is not a live view after that. */
124
115
  get roots(): readonly string[];
116
+ /** The session plan file as admitted — its declared spelling and its frozen canonical key (the key is also on
117
+ * {@link roots}) — or `undefined` when none was declared. The write-protection judge reads it to exempt exactly
118
+ * this file; nothing else holds a copy. */
119
+ get planFile(): {
120
+ readonly spelled: string;
121
+ readonly key: string;
122
+ } | undefined;
123
+ private admittedPlanFile;
124
+ /**
125
+ * Admit the session plan file (`TaskSpec.planFile`, already shape-checked by {@link checkedPlanFileShape}): a FILE, so
126
+ * its key is the CANONICAL PARENT joined with the declared name — frozen here like every key this seat holds, never
127
+ * re-resolved — and the leaf is looked at without following links. The file need not exist yet (the model creates it),
128
+ * and it is never materialized: its directory is the host's to create.
129
+ *
130
+ * Refusing, not skipping: the leaf is a symbolic link (admitting where it points would let the declaration exempt any
131
+ * file the link names), a directory or another non-file kind; the parent does not resolve, or resolves to something
132
+ * other than a directory; or the key would hold a root the fence already holds (the seat's one containment rule).
133
+ * Each throws {@link planFileInvalid} — the plan file decides what the plan-exit tool reads, so a declared file the
134
+ * fence narrowed away would teach a tool over a file nobody can write.
135
+ */
136
+ admitPlanFile(spelled: string): Promise<string>;
137
+ /**
138
+ * What the admitted session plan file holds right now — the ONE reader of the plan's contents (the plan-exit tool and the
139
+ * post-compaction reference both read here), through the environment the fence judges with, at the key admitted (frozen,
140
+ * never re-resolved), the leaf looked at without following a link: a file later replaced by a link, a directory or
141
+ * another kind is refused with the reason, never read through.
142
+ */
143
+ readPlanFile(signal?: AbortSignal): Promise<PlanFileReading>;
125
144
  /** What became of an advertiser's directory: admitted, skipped (announced), or never asked (the advertiser
126
145
  * had nothing to advertise, or decided not to). The prompt side reads this to withhold an advertisement. */
127
146
  verdictOf(advertiser: AdvertisedWritableDir["advertiser"]): "admitted" | "skipped" | "not-asked";