@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
@@ -14,4 +14,4 @@ export type { SessionWriteOptions, CompactionEntry } from "../engine/harness/typ
14
14
  export type { ActiveWorktreeSession, WorkspaceState } from "../engine/harness/types.js";
15
15
  export type { GitAnnouncementKind, GitAnnouncementState } from "../engine/harness/types.js";
16
16
  export type { SessionForkOptions } from "../engine/harness/types.js";
17
- export type { SessionPlacementRecord, SessionCreateOptions, SessionHead, SessionRow } from "../engine/harness/types.js";
17
+ export type { SessionPlacementRecord, SessionCreateOptions, SessionHead, SessionRow, SessionRowExpectation, SessionRowRead, SessionLogMark } from "../engine/harness/types.js";
@@ -11,15 +11,15 @@
11
11
  */
12
12
  export * from "./harness-types.js";
13
13
  export { AgentHarness } from "../engine/harness/agent-harness.js";
14
- export type { HaltConsumption, PromptDeliveredCallback, SeatCutSource, StopRequestSource, TrailingToolBatchOptions } from "../engine/harness/agent-harness.js";
14
+ export type { HaltConsumption, PromptCommittedCallback, SeatCutSource, StopRequestSource, TrailingToolBatchOptions } from "../engine/harness/agent-harness.js";
15
15
  export { CompactionError, ExecutionError, FileError, isTimeCutCode, ok, err } from "../engine/harness/types.js";
16
16
  export { DEFAULT_CHARS_PER_TOKEN, DEFAULT_CLAMP_TOLERANCE, DEFAULT_COMPACTION_SETTINGS, compact, computeFileLists, dryRunSummarizationClamp, estimateContextTokens, estimateTokens, prepareCompaction, shouldCompact, summaryOutputBudgetTokens, } from "../engine/compaction/compaction.js";
17
17
  export { SKILL_RETENTION_PER_SKILL_MAX_CHARS, SKILL_RETENTION_TOTAL_MAX_CHARS, SKILL_RETENTION_TRUNCATION_MARKER, formatFileOperations, formatPersistedOutputRefs, readCompactionActiveTools, readRetainedInvokedSkills, renderInvokedSkillsRetention, } from "../engine/compaction/utils.js";
18
18
  export { NodeExecutionEnv } from "../engine/execution-env/node-execution-env.js";
19
19
  export { StoredSession, buildSessionContext } from "../engine/session/session.js";
20
- export { assertForkTarget, compareOccupants, forkRowCells, frozenRow, getEntriesToFork, importRowCells, incarnationCell, ownerCell, readIncarnationCell, readOwnerCell } from "../engine/session/repo-utils.js";
20
+ export { assertForkTarget, compareOccupants, forkRowCells, frozenRow, getEntriesToFork, importRowCells, incarnationCell, ownerCell, readIncarnationCell, readOwnerCell, rowExpectationMissed, sessionRowMatches } from "../engine/session/repo-utils.js";
21
21
  export { validateEntriesForImport, StreamingImportValidator } from "../engine/session/import-validate.js";
22
- export { BaseSessionStorage, leafIdAfterEntry } from "../engine/session/storage-base.js";
22
+ export { BaseSessionStorage, leafIdAfterEntry, resolveLeafId, sessionLogMarkOf } from "../engine/session/storage-base.js";
23
23
  export { InMemorySessionStorage } from "../engine/session/memory-storage.js";
24
24
  export { InMemorySessionRepo } from "../engine/session/memory-repo.js";
25
25
  export { uuidv7 } from "../engine/session/uuid.js";
@@ -30,3 +30,4 @@ export type { AnnouncedAdvisorState, AnnouncedListingSnapshot, AnnouncedListingS
30
30
  export { normalizeGitAnnouncement } from "../engine/harness/types.js";
31
31
  export { gitFrameContextVisible } from "../engine/session/session.js";
32
32
  export { isSyntheticApiErrorMessage } from "../engine/harness/types.js";
33
+ export { convertToLlm } from "../engine/harness/messages.js";
@@ -5,9 +5,9 @@ export { DEFAULT_CHARS_PER_TOKEN, DEFAULT_CLAMP_TOLERANCE, DEFAULT_COMPACTION_SE
5
5
  export { SKILL_RETENTION_PER_SKILL_MAX_CHARS, SKILL_RETENTION_TOTAL_MAX_CHARS, SKILL_RETENTION_TRUNCATION_MARKER, formatFileOperations, formatPersistedOutputRefs, readCompactionActiveTools, readRetainedInvokedSkills, renderInvokedSkillsRetention, } from "../engine/compaction/utils.js";
6
6
  export { NodeExecutionEnv } from "../engine/execution-env/node-execution-env.js";
7
7
  export { StoredSession, buildSessionContext } from "../engine/session/session.js";
8
- export { assertForkTarget, compareOccupants, forkRowCells, frozenRow, getEntriesToFork, importRowCells, incarnationCell, ownerCell, readIncarnationCell, readOwnerCell } from "../engine/session/repo-utils.js";
8
+ export { assertForkTarget, compareOccupants, forkRowCells, frozenRow, getEntriesToFork, importRowCells, incarnationCell, ownerCell, readIncarnationCell, readOwnerCell, rowExpectationMissed, sessionRowMatches } from "../engine/session/repo-utils.js";
9
9
  export { validateEntriesForImport, StreamingImportValidator } from "../engine/session/import-validate.js";
10
- export { BaseSessionStorage, leafIdAfterEntry } from "../engine/session/storage-base.js";
10
+ export { BaseSessionStorage, leafIdAfterEntry, resolveLeafId, sessionLogMarkOf } from "../engine/session/storage-base.js";
11
11
  export { InMemorySessionStorage } from "../engine/session/memory-storage.js";
12
12
  export { InMemorySessionRepo } from "../engine/session/memory-repo.js";
13
13
  export { uuidv7 } from "../engine/session/uuid.js";
@@ -17,3 +17,4 @@ export { SessionError } from "../engine/harness/types.js";
17
17
  export { normalizeGitAnnouncement } from "../engine/harness/types.js";
18
18
  export { gitFrameContextVisible } from "../engine/session/session.js";
19
19
  export { isSyntheticApiErrorMessage } from "../engine/harness/types.js";
20
+ export { convertToLlm } from "../engine/harness/messages.js";
@@ -35,10 +35,6 @@ export declare class FileCheckpointStore implements CheckpointStore {
35
35
  * same JSON reading as the ledger line); the declaration is what makes the loss visible to the mint BEFORE the
36
36
  * row is filed. */
37
37
  readonly fidelity: "json";
38
- /** F-012 L2: `reopen` here is a real resolved→pending CAS journaled to the ledger — declared, not sniffed. */
39
- readonly redecision: {
40
- readonly reopen: true;
41
- };
42
38
  /** The execution-outcome record verb below is the contract's CAS (journaled), and `reopen` honours the record. */
43
39
  readonly execution: {
44
40
  readonly outcome: true;
@@ -88,7 +88,6 @@ const checkpointLedgers = new SharedLedgerTable({
88
88
  export class FileCheckpointStore {
89
89
  durability = "durable";
90
90
  fidelity = "json";
91
- redecision = { reopen: true };
92
91
  execution = { outcome: true };
93
92
  holderIsCurrent;
94
93
  fsyncEnabled;
@@ -1147,6 +1147,14 @@ export class FileFileHistoryStore {
1147
1147
  const shaped = validateFileHistoryExport(data);
1148
1148
  if (!shaped.ok)
1149
1149
  return shaped;
1150
+ for (const b of data.boundaries) {
1151
+ try {
1152
+ historyPathComponent(b.entryId);
1153
+ }
1154
+ catch (err) {
1155
+ return { ok: false, error: { code: "unsupported_format", message: `importHistory refused a boundary entry id this backend cannot hold as a record name: ${thrownText(err)} — nothing was fetched or published` } };
1156
+ }
1157
+ }
1150
1158
  const target = await this.importTargetOf(scope, data, "before");
1151
1159
  if (typeof target === "object")
1152
1160
  return target;
@@ -1164,7 +1172,7 @@ export class FileFileHistoryStore {
1164
1172
  return await this.runImport(scope, data, srcGetBlob, importJournal, identicalRepublish);
1165
1173
  }
1166
1174
  catch (err) {
1167
- return { ok: false, error: { code: "unsupported_format", message: `importHistory failed: ${thrownText(err)}`, ...caughtFault(err) } };
1175
+ return { ok: false, error: { code: "adopt_failed", message: `importHistory failed: ${thrownText(err)}`, ...caughtFault(err) } };
1168
1176
  }
1169
1177
  }
1170
1178
  async runImport(scope, data, srcGetBlob, importJournal, identicalRepublish) {
@@ -1191,12 +1199,12 @@ export class FileFileHistoryStore {
1191
1199
  bytes = await srcGetBlob(v.blobHash);
1192
1200
  }
1193
1201
  catch (err) {
1194
- return { ok: false, error: { code: "unsupported_format", message: `source blob ${v.blobHash} fetch failed: ${thrownText(err)}`, ...caughtFault(err) } };
1202
+ return { ok: false, error: { code: "adopt_failed", message: `source blob ${v.blobHash} fetch failed: ${thrownText(err)}`, ...caughtFault(err) } };
1195
1203
  }
1196
1204
  if (bytes === undefined)
1197
1205
  return { ok: false, error: { code: "adopt_failed", message: `source blob ${v.blobHash} is missing — the envelope's graph cannot be completed, so nothing is published` } };
1198
1206
  if (createHash("sha256").update(bytes).digest("hex") !== v.blobHash) {
1199
- return { ok: false, error: { code: "unsupported_format", message: `source blob ${v.blobHash} fails content-address integrity — refused, nothing published` } };
1207
+ return { ok: false, error: { code: "adopt_failed", message: `source blob ${v.blobHash} fails content-address integrity — refused, nothing published` } };
1200
1208
  }
1201
1209
  this.putBlob(v.blobHash, bytes);
1202
1210
  }
@@ -1250,7 +1258,7 @@ export class FileFileHistoryStore {
1250
1258
  return { ok: true };
1251
1259
  }
1252
1260
  catch (err) {
1253
- return { ok: false, error: { code: "unsupported_format", message: `importHistory failed: ${thrownText(err)}`, ...caughtFault(err) } };
1261
+ return { ok: false, error: { code: "adopt_failed", message: `importHistory failed: ${thrownText(err)}`, ...caughtFault(err) } };
1254
1262
  }
1255
1263
  finally {
1256
1264
  safeRm(importJournal);
@@ -2,7 +2,7 @@ import { type MemoryStore, type UtilityGate } from "../../core/memory.js";
2
2
  import type { CheckpointStore } from "../../core/checkpoint-store.js";
3
3
  import type { ToolResultStore } from "../../core/tool-result-store.js";
4
4
  import { type EvictPolicy } from "../../core/session-store.js";
5
- import type { SessionStore } from "../../core/session.js";
5
+ import type { SessionStore, SessionStoreHooks } from "../../core/session.js";
6
6
  import { type FileCheckpointStoreOptions } from "./checkpoint-store.js";
7
7
  import { type FileSessionPolicyStoreOptions } from "./session-policy-store.js";
8
8
  import { type FileFileHistoryStoreOptions } from "./file-history-store.js";
@@ -107,6 +107,9 @@ export interface FileStorageBackendOptions {
107
107
  * `principal` when the read was keyed by one. One sink for one failure grammar — a host does not register three.
108
108
  */
109
109
  onCorruptRead?: (info: FileStorageCorruptReadInfo) => void;
110
+ /** The deployment's hooks on the session store's row deletions ({@link SessionStoreHooks}) — the File lane has no foreign keys, so a
111
+ * deployment's own records keyed by session id are cleaned here, before each row the session store deletes. */
112
+ sessions?: SessionStoreHooks;
110
113
  }
111
114
  /**
112
115
  * The payload of {@link FileStorageBackendOptions.onCorruptRead} — the widest shape any store this
@@ -51,6 +51,9 @@ export class FileStorageBackend {
51
51
  fileSessions;
52
52
  fileWorkflowJournal;
53
53
  constructor(opts = {}) {
54
+ if ("retention" in opts) {
55
+ throw Object.assign(new Error(`FileStorageBackend runs no retention executor, so its options take no \`retention\` word: its stores declare "none".`), { code: "config.retention_capability" });
56
+ }
54
57
  this.root = resolveDataRoot(opts.root);
55
58
  assertAdoptionBootGate(this.root, "FileStorageBackend");
56
59
  this.lock = new BootLock(join(this.root, "LOCK"));
@@ -60,7 +63,7 @@ export class FileStorageBackend {
60
63
  const corruptRead = opts.onCorruptRead !== undefined ? { onCorruptRead: opts.onCorruptRead } : undefined;
61
64
  const repo = new FileSessionRepo(this.root, corruptRead);
62
65
  this.fileSessions = repo;
63
- this.ttl = new TtlSessionStore({ repo, evict: opts.evict ?? "forget", durability: "durable", placements: { subagent: { durability: "durable" } } });
66
+ this.ttl = new TtlSessionStore({ repo, evict: opts.evict ?? "forget", durability: "durable", placements: { subagent: { durability: "durable" } }, ...(opts.sessions !== undefined ? { hooks: opts.sessions } : {}) });
64
67
  this.sessionStore = this.ttl;
65
68
  const sessionHeadOf = this.ttl.headOf;
66
69
  this.fileCheckpoints = new FileCheckpointStore(this.root, { ...opts.checkpoint, ...corruptRead, ...(sessionHeadOf !== undefined ? { sessionHeadOf } : {}) });
@@ -1,4 +1,4 @@
1
- import { type MailboxAckResult, type MailboxAppendMessage, type MailboxLease, type MailboxStore } from "../../core/mailbox-store.js";
1
+ import { type MailboxAckResult, type MailboxAppendMessage, type MailboxLease, type MailboxDecisionOutcome, type MailboxDecision, type MailboxStore } from "../../core/mailbox-store.js";
2
2
  import { type CorruptReadInfo } from "./corrupt-read-sink.js";
3
3
  /** The waiter's refusal when a box lock stays held by a LIVE process past `lockWaitMs`. Carried as
4
4
  * `.code` on a plain Error (consumers branch on the string); the message names the lock and the holder. */
@@ -113,6 +113,7 @@ export declare class FileMailboxStore implements MailboxStore {
113
113
  append(scope: string, handle: string, msg: MailboxAppendMessage): Promise<number>;
114
114
  claimLease(scope: string, handle: string, owner: string, ttlMs: number, now?: number): Promise<MailboxLease | null>;
115
115
  ack(scope: string, handle: string, owner: string, upToSeq: number): Promise<MailboxAckResult>;
116
+ moveDecision(scope: string, handle: string, seq: number, expect: MailboxDecision | undefined, next: MailboxDecision): Promise<MailboxDecisionOutcome>;
116
117
  releaseLease(scope: string, handle: string, owner: string): Promise<void>;
117
118
  peekCount(scope: string, handle: string): Promise<number>;
118
119
  drop(scope: string, handle: string): Promise<void>;
@@ -2,7 +2,7 @@ import { join, resolve, sep } from "node:path";
2
2
  import { createHash, randomBytes } from "node:crypto";
3
3
  import { assertRetentionPolicy } from "../../core/retention-policy.js";
4
4
  import { existsSync, linkSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
5
- import { detachMailboxMessage, newestSentAt, readMailboxPeerMeta, } from "../../core/mailbox-store.js";
5
+ import { assertMailboxDecisionMove, detachMailboxMessage, newestSentAt, readStoredMailboxDecision, readMailboxPeerMeta, } from "../../core/mailbox-store.js";
6
6
  import { AppendLog, atomicWriteFile, canonicalStoreKey, ensureDir, readJsonlRecords, sanitizeScope, sanitizePathComponent } from "./fs-atomic.js";
7
7
  import { guardCorruptSink } from "./corrupt-read-sink.js";
8
8
  import { physicalPathOf } from "../../core/physical-path.js";
@@ -478,6 +478,19 @@ export class FileMailboxStore {
478
478
  return { acked: true };
479
479
  });
480
480
  }
481
+ async moveDecision(scope, handle, seq, expect, next) {
482
+ assertMailboxDecisionMove(seq, expect, next);
483
+ return this.withBox(this.lockKey(scope, handle), this.boxPath(scope, handle), () => {
484
+ const b = this.load(scope, handle);
485
+ const m = b.messages.find((x) => x.seq === seq);
486
+ if (m === undefined)
487
+ return { ok: false, current: "gone" };
488
+ if (m.decision !== expect)
489
+ return { ok: false, current: m.decision ?? "unset" };
490
+ this.commit(b, this.boxPath(scope, handle), { t: "decision", seq, state: next });
491
+ return { ok: true };
492
+ });
493
+ }
481
494
  async releaseLease(scope, handle, owner) {
482
495
  return this.withBox(this.lockKey(scope, handle), this.boxPath(scope, handle), () => {
483
496
  const b = this.load(scope, handle);
@@ -592,12 +605,19 @@ const MAILBOX_EVENT_JUDGE = {
592
605
  return typeof ev.owner === "string" && num(ev.maxSeq) && num(ev.expiresAt);
593
606
  if (ev.t === "ack")
594
607
  return num(ev.upToSeq);
608
+ if (ev.t === "decision")
609
+ return num(r.seq) && typeof r.state === "string";
595
610
  return ev.t === "release" && typeof ev.owner === "string";
596
611
  },
597
612
  what: "a mailbox record is not one of this box's events — an unknown tag, or a known tag whose payload is missing",
598
613
  };
599
614
  function applyEvent(b, ev) {
600
615
  if (ev.t === "append") {
616
+ const decision = readStoredMailboxDecision(ev.m.decision);
617
+ if (decision === undefined)
618
+ delete ev.m.decision;
619
+ else
620
+ ev.m.decision = decision;
601
621
  b.messages.push(ev.m);
602
622
  if (ev.m.seq >= b.nextSeq)
603
623
  b.nextSeq = ev.m.seq + 1;
@@ -613,6 +633,11 @@ function applyEvent(b, ev) {
613
633
  if (b.lease !== undefined && b.lease.maxSeq <= ev.upToSeq)
614
634
  b.lease = undefined;
615
635
  }
636
+ else if (ev.t === "decision") {
637
+ const m = b.messages.find((x) => x.seq === ev.seq);
638
+ if (m !== undefined)
639
+ m.decision = readStoredMailboxDecision(ev.state) ?? "held";
640
+ }
616
641
  else if (b.lease?.owner === ev.owner) {
617
642
  b.lease = undefined;
618
643
  }
@@ -1,4 +1,4 @@
1
- import type { Session, SessionCreateOptions, SessionForkOptions, SessionHead, SessionMetadata, SessionPlacementRecord, SessionRepo, SessionRow, SessionTreeEntry } from "../../internal/harness.js";
1
+ import type { Session, SessionCreateOptions, SessionForkOptions, SessionHead, SessionMetadata, SessionPlacementRecord, SessionRepo, SessionRow, SessionRowExpectation, SessionRowRead, SessionTreeEntry } from "../../internal/harness.js";
2
2
  import type { PlacedSessionRow } from "../../core/session.js";
3
3
  import { type CorruptReadInfo } from "./corrupt-read-sink.js";
4
4
  export interface FileSessionRepoOptions {
@@ -60,6 +60,13 @@ export declare class FileSessionRepo implements SessionRepo {
60
60
  * head does not see. A leaf entry naming an id the log does not hold is not checked here (a replay refuses that log on open).
61
61
  */
62
62
  headOf(sessionId: string): Promise<SessionHead | undefined>;
63
+ /** {@link headOf}'s one read, synchronously — what a conditional delete judges its expectation against in the step that removes the row. */
64
+ private headNow;
65
+ /** The row in one read of its file (one inode): the header's cells, the head they and the replayed log give, and the log. */
66
+ readRow(sessionId: string): Promise<SessionRowRead | undefined>;
67
+ /** {@link readRow}'s one read, synchronously — what a conditional import judges its expectation against in the step that writes. A
68
+ * file whose header cannot be read rejects (`corrupt_session`): it is a row whose cells nobody can name. */
69
+ private rowNow;
63
70
  /**
64
71
  * The row's {@link SessionRow} — its header cells and the newest write it holds, the log's modification time (every write to a row
65
72
  * is an append to its log; the placed listing's age reads the same time) — in one read of the header, never a replay of the log.
@@ -111,24 +118,24 @@ export declare class FileSessionRepo implements SessionRepo {
111
118
  olderThanMs?: number;
112
119
  scope?: string;
113
120
  }): Promise<PlacedSessionRow[]>;
114
- /** The row as it stands before a file-replacing write: `undefined` ⇔ there is no row (no file); a row
115
- * whose header cannot be read rejects (it exists, and nobody can name its cells). */
116
- private priorHeader;
117
121
  /** Cheap placement probe for one id (the TtlSessionStore's cold-cache release consults it so the
118
122
  * placed real-deletion obligation holds after a restart). `undefined` = missing file OR unplaced; a row that cannot be read rejects. */
119
123
  placementOf(sessionId: string): Promise<SessionPlacementRecord | undefined>;
120
- delete(metadata: SessionMetadata): Promise<void>;
124
+ delete(metadata: SessionMetadata, expect?: SessionRowExpectation): Promise<void>;
121
125
  fork(sourceMetadata: SessionMetadata, options?: SessionForkOptions & SessionCreateOptions): Promise<Session>;
122
126
  /** 2c session-sync (the FILE half): the FULL oldest-first log for export. The file backend
123
127
  * has NO F3 floor — `read` returns EVERY persisted entry (`id`/`parentId` verbatim) — so this is the complete
124
128
  * log, BYPASSing any bounded tail (matches `InMemorySessionRepo.exportEntries`). Missing file → not_found. */
125
129
  exportEntries(sessionId: string): Promise<SessionTreeEntry[]>;
126
130
  /** 2c session-sync: import a verbatim log into `sessionId`. The single fail-closed invariant gate runs
127
- * FIRST ({@link validateEntriesForImport}); a new row's header records `owner`, an existing row's is laid down again whole. Writes the WHOLE file
131
+ * FIRST ({@link validateEntriesForImport}); a new row's header records `owner`, an existing row's is laid down again whole and must already
132
+ * be `owner`'s (`importRowCells`), and the row must be the one `options.expect` names (`sessionRowMatches`) — the row read, both
133
+ * judgements and the write with no await between; the head answered is the one the write lays down. Writes the WHOLE file
128
134
  * (meta + entries) atomically via tmp→fsync→rename — the rename is the commit point, so a crash leaves either nothing or an
129
- * orphan temp, never a partially-imported session (mirrors `fork`). An existing session is REPLACED (the
135
+ * orphan temp, never a partially-imported session (mirrors `fork`). The importer's existing session is REPLACED (the
130
136
  * orchestrator's importSession owns the already-exists policy, same as InMemory's overwrite). */
131
137
  importEntries(sessionId: string, owner: string | undefined, entries: SessionTreeEntry[], options?: {
132
138
  preserveActorAssertions?: boolean;
133
- }): Promise<void>;
139
+ expect?: SessionRowExpectation;
140
+ }): Promise<SessionHead>;
134
141
  }
@@ -1,6 +1,6 @@
1
1
  import { closeSync, existsSync, fstatSync, openSync, readdirSync, rmSync, utimesSync } from "node:fs";
2
2
  import { join } from "node:path";
3
- import { BaseSessionStorage, StoredSession, SessionError, assertForkTarget, compareOccupants, forkRowCells, frozenRow, getEntriesToFork, importRowCells, incarnationCell, leafIdAfterEntry, ownerCell, readIncarnationCell, readOwnerCell, uuidv7, validateEntriesForImport, } from "../../internal/harness.js";
3
+ import { BaseSessionStorage, StoredSession, SessionError, assertForkTarget, compareOccupants, forkRowCells, frozenRow, getEntriesToFork, importRowCells, incarnationCell, leafIdAfterEntry, ownerCell, readIncarnationCell, readOwnerCell, resolveLeafId, rowExpectationMissed, sessionLogMarkOf, sessionRowMatches, uuidv7, validateEntriesForImport, } from "../../internal/harness.js";
4
4
  import { canonicalStoreKey, AppendLog, atomicWriteFile, ensureDir, firstJsonlRecord, lastJsonlRecord, readJsonlRecords, sanitizePathComponent, writeThenLink } from "./fs-atomic.js";
5
5
  import { guardCorruptSink } from "./corrupt-read-sink.js";
6
6
  import { assertAdoptionBootGate } from "./adoption/marker.js";
@@ -125,11 +125,30 @@ export class FileSessionRepo {
125
125
  };
126
126
  }
127
127
  async headOf(sessionId) {
128
+ return this.headNow(sessionId);
129
+ }
130
+ headNow(sessionId) {
128
131
  return this.atRow(sessionId, (fd, size, meta) => {
129
132
  const last = lastJsonlRecord(fd, size, (r) => r.kind === "entry", SESSION_LINE_JUDGE);
130
133
  return { owner: meta.owner ?? null, incarnation: meta.incarnation, leafId: last === undefined ? null : leafIdAfterEntry(last.entry) };
131
134
  });
132
135
  }
136
+ async readRow(sessionId) {
137
+ return this.rowNow(sessionId);
138
+ }
139
+ rowNow(sessionId) {
140
+ let read;
141
+ try {
142
+ read = this.read(sessionId);
143
+ }
144
+ catch (err) {
145
+ if (err instanceof SessionError && err.code === "not_found")
146
+ return undefined;
147
+ throw err;
148
+ }
149
+ const { meta, entries } = read;
150
+ return { metadata: meta, head: { owner: meta.owner ?? null, incarnation: meta.incarnation, leafId: resolveLeafId(entries) }, entries };
151
+ }
133
152
  rowOf(sessionId) {
134
153
  return this.atRow(sessionId, (_fd, _size, meta, mtimeMs) => ({ ...meta, lastActiveAt: Math.trunc(mtimeMs) }));
135
154
  }
@@ -270,16 +289,6 @@ export class FileSessionRepo {
270
289
  }
271
290
  return out;
272
291
  }
273
- priorHeader(id) {
274
- try {
275
- return this.read(id).meta;
276
- }
277
- catch (err) {
278
- if (err instanceof SessionError && err.code === "not_found")
279
- return undefined;
280
- throw err;
281
- }
282
- }
283
292
  async placementOf(sessionId) {
284
293
  try {
285
294
  return this.read(sessionId).meta.placement;
@@ -290,7 +299,9 @@ export class FileSessionRepo {
290
299
  throw err;
291
300
  }
292
301
  }
293
- async delete(metadata) {
302
+ async delete(metadata, expect) {
303
+ if (expect !== undefined && !sessionRowMatches(expect, this.headNow(metadata.id), () => sessionLogMarkOf(this.read(metadata.id).entries)))
304
+ throw rowExpectationMissed(metadata.id, "delete");
294
305
  evictSharedSessionStorage(canonicalStoreKey(this.pathFor(metadata.id)));
295
306
  try {
296
307
  rmSync(this.pathFor(metadata.id), { force: true });
@@ -320,12 +331,16 @@ export class FileSessionRepo {
320
331
  }
321
332
  async importEntries(sessionId, owner, entries, options) {
322
333
  const validated = validateEntriesForImport(entries, options);
323
- const meta = importRowCells(sessionId, owner, this.priorHeader(sessionId), new Date().toISOString());
334
+ const prior = this.rowNow(sessionId);
335
+ if (!sessionRowMatches(options?.expect, prior?.metadata, () => sessionLogMarkOf(prior.entries)))
336
+ throw rowExpectationMissed(sessionId, "import");
337
+ const meta = importRowCells(sessionId, owner, prior?.metadata, new Date().toISOString());
324
338
  evictSharedSessionStorage(canonicalStoreKey(this.pathFor(sessionId)));
325
339
  const lines = [JSON.stringify({ kind: "meta", ...meta })];
326
340
  for (const entry of validated) {
327
341
  lines.push(JSON.stringify({ kind: "entry", entry }));
328
342
  }
329
343
  atomicWriteFile(this.tmpDir, this.pathFor(sessionId), `${lines.join("\n")}\n`);
344
+ return { owner: meta.owner ?? null, incarnation: meta.incarnation, leafId: resolveLeafId(validated) };
330
345
  }
331
346
  }
@@ -2,15 +2,15 @@ import { type LexedCommand, type LexedSegment, type LexedWord, type ShellLex, ty
2
2
  import { type ProgramRow } from "./program-read-model.js";
3
3
  /**
4
4
  * Bare command names `bash_readonly` permits out of the box, ALSO the default reversible set for the
5
- * The {@link import("./fs-bash.js").bashReversibilityProbe} classifier. **Coarse first filter, NOT a security
6
- * boundary**: {@link coarseReadonlyCheck} matches only the command NAME, so a listed command with a
7
- * writing flag (e.g. `find -delete`, `sort -o`, `tee`) would still write. Such commands are therefore
8
- * kept OFF this default — the list is curated to commands with NO write/mutation mode under ANY args, so
9
- * the `effect:"read"` declaration (relied on by wake/resume reconcile + the verifier read-only boundary)
10
- * AND the classifier's "reversible" promise both stay truthful. The deployment's tool-policy gate is the
11
- * authoritative control (council blocker #1); anything that can mutate state or run arbitrary
12
- * code belongs on the full `bash` (effect:write, gated), not here. A deployment may widen this list,
13
- * accepting that responsibility.
5
+ * {@link import("./fs-bash.js").bashReversibilityProbe} classifier. On the read-only face and in the transcript gate the
6
+ * list only NARROWS the read-only reader ({@link import("../../core/read-only-shell.js").readOnlyShellVerdict}'s
7
+ * `readers`): a listed program runs there only in a call the reader reads as read-only, so a deployment that widens the
8
+ * list with `sort` still has `sort -o out f` refused. The reversibility classifier reads the list as its allowlist: a
9
+ * listed program with a program-model row has its writing options refused by the row; one without a row is admitted
10
+ * by its name. The default is curated to commands with NO write/mutation mode under ANY args, so the `effect:"read"`
11
+ * declaration (relied on by wake/resume reconcile + the verifier read-only boundary) AND the classifier's
12
+ * "reversible" promise both stay truthful. The deployment's tool-policy gate is the authoritative control;
13
+ * anything that can mutate state or run arbitrary code belongs on the full `bash` (effect:write, gated), not here.
14
14
  *
15
15
  * Deliberately ABSENT: `date` (`-s`/`--set` → CLOCK_SETTIME), `hostname` (`<name>` → kernel
16
16
  * hostname), and `file` (`-C -m` → compiles/writes a magic file) were REMOVED — each is read-only by NAME
@@ -112,7 +112,7 @@ export interface LeadingCommandNameOptions {
112
112
  pathPrefixedNameIsText?: boolean;
113
113
  }
114
114
  /**
115
- * The SINGLE fail-closed simple-command parser shared by `bash_readonly` ({@link coarseReadonlyCheck}), the
115
+ * The SINGLE fail-closed simple-command parser shared by `bash_readonly`'s single-command admission, the
116
116
  * `bash` reversibility classifier ({@link import("./fs-bash.js").bashReversibilityProbe}), and the coarse command-name policy
117
117
  * ({@link import("../../core/tool-policy.js").createCoarseCommandNamePolicy}). It extracts the leading
118
118
  * `argv[0]` command NAME of a SINGLE simple command, rejecting anything that could chain past or escape an
@@ -131,13 +131,9 @@ export declare function parseLeadingCommandName(command: string, options?: Leadi
131
131
  } | {
132
132
  reject: string;
133
133
  };
134
- /** Coarse pre-execution check for `bash_readonly`: the command must be a single bare allowlisted command
135
- * with no shell operators. It validates the NAME only (+ blocks operators/path-prefix/env-assignment); it
136
- * does NOT inspect arguments for write flags — keeping the allowlist free of write-capable commands and
137
- * the policy gate are what make `effect:"read"` truthful. Returns a reason when rejected, else undefined.
138
- * This `effect:"read"` DECLARATION face deliberately stays strict-single-command; only the
139
- * classify face ({@link classifyCompoundReadonly} via {@link import("./fs-bash.js").bashReversibilityProbe}) segments compounds. */
140
- export declare function coarseReadonlyCheck(command: string, allow: ReadonlySet<string>, options?: LeadingCommandNameOptions): string | undefined;
134
+ /** The one sentence for a program a face's list of programs does not name — the compound classifier's list check and
135
+ * the read-only reader's `readers` narrowing both mint it here. */
136
+ export declare function unlistedReaderSentence(program: string): string;
141
137
  /**
142
138
  * Does this text carry a bare redirection operator — the ONE metacharacter family
143
139
  * {@link splitShellCompoundSegments} can be asked to tolerate at its whole-string gate
@@ -226,7 +222,7 @@ export declare function splitShellCompoundSegments(source: string, options?: {
226
222
  /**
227
223
  * Compound read-only classification for the `bash` full-shell face (the shape tier).
228
224
  * Splits a command on the connector set `;` `&&` `||` `|` and passes every segment through
229
- * {@link coarseReadonlyCheck} (the single {@link parseLeadingCommandName} parser + bare-name allowlist).
225
+ * the single {@link parseLeadingCommandName} parser and the bare-name allowlist.
230
226
  * All segments green ⇒ read-only. Returns a reason when rejected, else undefined.
231
227
  *
232
228
  * G2 — the split CARRIES QUOTE STATE (the one lexer): a connector character inside a quoted region is
@@ -548,7 +544,7 @@ export declare const POLL_LOOP_MAX_SLEEP_SECONDS = 600;
548
544
  * -f`, unbounded devices all reject), and `sleep` must be a literal ≤
549
545
  * {@link POLL_LOOP_MAX_SLEEP_SECONDS}. Bounded beats × terminating body ⇒ the loop halts.
550
546
  * G2 NO WRITE OR EGRESS CHANNEL. Every non-`sleep` body segment must pass the SAME
551
- * {@link coarseReadonlyCheck} parser + allowlist as the plain face (one parser, no drift);
547
+ * {@link parseLeadingCommandName} parser + allowlist the compound classifier reads (one parser, no drift);
552
548
  * `sleep` touches neither filesystem nor network. No redirection (`>` `<`), no `$`/backtick
553
549
  * substitution, no subshell exists anywhere: the body bans them wholesale
554
550
  * ({@link POLL_BODY_HARD_REJECT}), and the head's single `$(seq <int> <int>)` exemption is an
@@ -71,13 +71,8 @@ export function parseLeadingCommandName(command, options) {
71
71
  return { reject: "the command name must be a bare token (no quotes, braces, globs, or ~)" };
72
72
  return { name: first };
73
73
  }
74
- export function coarseReadonlyCheck(command, allow, options) {
75
- const parsed = parseLeadingCommandName(command, options);
76
- if ("reject" in parsed)
77
- return parsed.reject;
78
- if (!allow.has(parsed.name))
79
- return `command "${parsed.name}" is not in the read-only allowlist`;
80
- return undefined;
74
+ export function unlistedReaderSentence(program) {
75
+ return `command "${program}" is not in the read-only allowlist`;
81
76
  }
82
77
  const SHELL_SEGMENT_QUOTE_BLIND_REJECT = /[<>()`\n\r\\]/;
83
78
  const SHELL_EXPANSION_CHARS = /[$]/;
@@ -761,7 +756,7 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary) {
761
756
  return { reason: "`coproc` backgrounds a command — a backgrounded process outlives the command" };
762
757
  if (isBareControlWord(words, from, BLOCK_WORD_NAMES)) {
763
758
  unlistedSegments.add(si);
764
- nameRefusal ??= `command "${written}" is not in the read-only allowlist`;
759
+ nameRefusal ??= unlistedReaderSentence(written);
765
760
  continue;
766
761
  }
767
762
  const program = pos.program;
@@ -783,10 +778,10 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary) {
783
778
  if (pathPrefixed || from > 0)
784
779
  reheaded.set(si, { from, head: name });
785
780
  if (from > 0)
786
- nameRefusal ??= `command "${folded[0]}" is not in the read-only allowlist`;
781
+ nameRefusal ??= unlistedReaderSentence(folded[0]);
787
782
  continue;
788
783
  }
789
- nameRefusal ??= `command "${parsed.name}" is not in the read-only allowlist`;
784
+ nameRefusal ??= unlistedReaderSentence(parsed.name);
790
785
  if (runsShellText(name))
791
786
  return { reason: unjudgedProgramTextRefusal(parsed.name, "runs its argument as shell text") };
792
787
  if (pos.launchers.length > 0) {
@@ -16,7 +16,8 @@ import { boundaryIsTheSandbox, hasDestroy, isIsolated } from "../../core/remote-
16
16
  import { ghRateLimitHint } from "./gh-rate-limit.js";
17
17
  import { backgroundLifetimeNote } from "./fs-bash-background-text.js";
18
18
  import { resolveBashTimeoutCaps, bashTimeoutCapsSec, bashTimeoutArgRefusal, bashTimeoutParamDescription, envErrorDetail, bashMaxOutputChars, clipShellOutput, writeShellOverflowFile, shellRecoveryHint, CWD_SENTINEL, stripCwdSentinel, } from "./fs-shared.js";
19
- import { bashClassifyDefaultAllow, BASH_READONLY_DEFAULT_ALLOW, coarseReadonlyCheck, classifyBoundedReadonlyPollLoopDetailed, classifyCompoundReadonlyDetailed } from "./bash-readonly-classifier.js";
19
+ import { bashClassifyDefaultAllow, BASH_READONLY_DEFAULT_ALLOW, classifyBoundedReadonlyPollLoopDetailed, classifyCompoundReadonlyDetailed, parseLeadingCommandName } from "./bash-readonly-classifier.js";
20
+ import { readOnlyShellVerdict } from "../../core/read-only-shell.js";
20
21
  import { mountRuleFace, toolFace } from "../../core/tool-catalog-entries.js";
21
22
  import { argvOf, compoundValueHidesRun, expansionHidesRun, expansionsInHeredocBody, lexShell } from "../../shell/lex.js";
22
23
  import { arithmeticAssignedNames } from "./shell-read-bindings.js";
@@ -26,6 +27,12 @@ function shellCommandOf(args) {
26
27
  const command = args?.command;
27
28
  return typeof command === "string" ? command : undefined;
28
29
  }
30
+ const CONCURRENT_READERS = new Set(BASH_READONLY_DEFAULT_ALLOW);
31
+ function readOnlyFaceRefusal(command, allow) {
32
+ const parsed = parseLeadingCommandName(command);
33
+ const verdict = "reject" in parsed ? { readOnly: false, reason: parsed.reject } : readOnlyShellVerdict(command, { readers: allow });
34
+ return verdict.readOnly ? undefined : verdict.reason;
35
+ }
29
36
  function isBackgroundShellCall(args) {
30
37
  return args?.run_in_background === true;
31
38
  }
@@ -578,7 +585,7 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
578
585
  const command = shellCommandOf(args);
579
586
  if (command === undefined || isBackgroundShellCall(args))
580
587
  return false;
581
- return coarseReadonlyCheck(command, new Set(BASH_READONLY_DEFAULT_ALLOW)) === undefined;
588
+ return readOnlyShellVerdict(command, { readers: CONCURRENT_READERS }).readOnly;
582
589
  },
583
590
  execute: async (args, ctx) => {
584
591
  const { command, timeout, run_in_background, description } = args;
@@ -797,7 +804,7 @@ export function createBashReadonlyTool(env, rootCanonical, allow, opts) {
797
804
  const timeoutRefusal = bashTimeoutArgRefusal(timeout, timeoutCaps);
798
805
  if (timeoutRefusal !== undefined)
799
806
  return errorResult(timeoutRefusal, { type: "bash_invalid_timeout", code: "bash_invalid_timeout" });
800
- const reason = coarseReadonlyCheck(command, allow);
807
+ const reason = readOnlyFaceRefusal(command, allow);
801
808
  if (reason)
802
809
  return errorResult(`Error (Bash): ${reason}`);
803
810
  const refused = await opts?.shellReadAdmission?.("Bash", ctx.toolCallId, command, ctx.signal);
@@ -14,8 +14,11 @@ import { type CwdRef } from "./fs-shared.js";
14
14
  * Absent hook ⇒ byte-identical behavior.
15
15
  */
16
16
  export type { BeforeWriteRequest, BeforeWriteResult, BeforeWriteHook, TrackEditRequest, TrackEditResult, TrackFileEditHook } from "../../core/types.js";
17
- export declare function createEditFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook, onEdited?: FileEditedHook, writeFace?: () => ContainmentFace, writeDeny?: WriteDenyMatcher): AgentTool;
18
- export declare function createWriteFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook, onEdited?: FileEditedHook, writeFace?: () => ContainmentFace, writeDeny?: WriteDenyMatcher): AgentTool;
17
+ /** A write tool's primary containment root: fixed, or a getter over the leg's live write location (read once per call, so an
18
+ * EnterWorktree switch moves where the next write may land). Canonical in both forms. */
19
+ export type WriteRootSeat = string | (() => string);
20
+ export declare function createEditFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: WriteRootSeat, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook, onEdited?: FileEditedHook, writeFace?: () => ContainmentFace, writeDeny?: WriteDenyMatcher): AgentTool;
21
+ export declare function createWriteFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: WriteRootSeat, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook, onEdited?: FileEditedHook, writeFace?: () => ContainmentFace, writeDeny?: WriteDenyMatcher): AgentTool;
19
22
  /**
20
23
  * design v1.163 — NotebookEdit: replace/insert/delete a single cell in a .ipynb. CC-parity tool over the SAME hand-band
21
24
  * safety skeleton as Edit/Write (resolveKey containment → requireRead read-before-edit → checkStale content-hash
@@ -23,4 +26,4 @@ export declare function createWriteFileTool(env: ExecutionEnv, state: ReadFileSt
23
26
  * .ipynb as the cell projection but records read state (hash/totalLines) in the RAW notebook-text
24
27
  * coordinate — that raw-coordinate read record is what this tool's freshness check depends on.
25
28
  */
26
- export declare function createNotebookEditTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook, onEdited?: FileEditedHook, writeFace?: () => ContainmentFace, writeDeny?: WriteDenyMatcher): AgentTool;
29
+ export declare function createNotebookEditTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: WriteRootSeat, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook, onEdited?: FileEditedHook, writeFace?: () => ContainmentFace, writeDeny?: WriteDenyMatcher): AgentTool;