@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
@@ -0,0 +1,166 @@
1
+ import { SessionError, StreamingImportValidator, importRowCells, ownerCell, sessionLogMarkOf, uuidv7 } from "../internal/harness.js";
2
+ import { receiptRefusal, receiveOwnProperties } from "./own-property-receipt.js";
3
+ import { thrownText } from "./thrown-value.js";
4
+ const EXPORT_WORDS = { subject: "SessionLogExportOptions", unit: "member", moment: "at SessionLogTransfer.exportStream" };
5
+ const BEGIN_WORDS = { subject: "SessionLogTransfer.beginReplace options", unit: "member", moment: "at SessionLogTransfer.beginReplace" };
6
+ const COMMIT_WORDS = { subject: "SessionLogCommit", unit: "member", moment: "at SessionLogReplace.commit" };
7
+ async function logOrNull(seat, sessionId) {
8
+ return (await seat.readRow(sessionId))?.entries ?? null;
9
+ }
10
+ function committedHead(sessionId, answer) {
11
+ if (typeof answer === "object" && answer !== null) {
12
+ const { owner, incarnation, leafId } = answer;
13
+ if ((owner === null || typeof owner === "string") && (incarnation === undefined || typeof incarnation === "string") && (leafId === null || typeof leafId === "string"))
14
+ return { owner, incarnation, leafId };
15
+ }
16
+ throw new SessionError("storage", `the repo's importEntries wrote session ${sessionId}'s log but answered no head (got ${answer === null ? "null" : typeof answer}) — a repo behind SessionStore.logTransfer answers the head its write committed; read the row again`);
17
+ }
18
+ function readRecord(raw, words, names) {
19
+ if (typeof raw !== "object" || raw === null)
20
+ throw receiptRefusal(`${words.subject} must be an object, got ${raw === null ? "null" : typeof raw}`);
21
+ const got = receiveOwnProperties(raw, words);
22
+ for (const name of Object.keys(got))
23
+ if (!names.includes(name))
24
+ throw receiptRefusal(`${words.subject} carries "${name}" — not a member this face reads`);
25
+ return got;
26
+ }
27
+ function isIntegerFrom(value, floor) {
28
+ return typeof value === "number" && Number.isSafeInteger(value) && value >= floor;
29
+ }
30
+ function readExportOptions(raw) {
31
+ if (raw === undefined)
32
+ return { afterSeq: -1 };
33
+ const got = readRecord(raw, EXPORT_WORDS, ["afterSeq", "batchSize"]);
34
+ const afterSeq = got["afterSeq"];
35
+ if (afterSeq !== undefined && !isIntegerFrom(afterSeq, -1))
36
+ throw receiptRefusal("SessionLogExportOptions.afterSeq must be an integer ≥ -1 when present");
37
+ if (got["batchSize"] !== undefined && !isIntegerFrom(got["batchSize"], 1))
38
+ throw receiptRefusal("SessionLogExportOptions.batchSize must be an integer ≥ 1 when present");
39
+ return { afterSeq: isIntegerFrom(afterSeq, -1) ? afterSeq : -1 };
40
+ }
41
+ function readBeginOptions(raw) {
42
+ if (raw === undefined)
43
+ return {};
44
+ const preserveActorAssertions = readRecord(raw, BEGIN_WORDS, ["preserveActorAssertions"])["preserveActorAssertions"];
45
+ if (preserveActorAssertions === undefined)
46
+ return {};
47
+ if (typeof preserveActorAssertions !== "boolean")
48
+ throw receiptRefusal("beginReplace options.preserveActorAssertions must be a boolean when present");
49
+ return { preserveActorAssertions };
50
+ }
51
+ function readCommit(raw) {
52
+ const { owner, decide } = readRecord(raw, COMMIT_WORDS, ["owner", "decide"]);
53
+ if (owner === undefined)
54
+ throw receiptRefusal("SessionLogCommit.owner must be a principal name or null (anonymous), got undefined");
55
+ try {
56
+ ownerCell(owner);
57
+ }
58
+ catch (err) {
59
+ throw receiptRefusal(`SessionLogCommit.owner: ${thrownText(err)}`);
60
+ }
61
+ if (typeof decide !== "function")
62
+ throw receiptRefusal(`SessionLogCommit.decide must be a function, got ${typeof decide}`);
63
+ return { owner: owner, decide: decide };
64
+ }
65
+ function detachedCopy(entry) {
66
+ try {
67
+ return structuredClone(entry);
68
+ }
69
+ catch (err) {
70
+ throw new SessionError("invalid_session", `a staged entry is not plain data: ${thrownText(err)}`);
71
+ }
72
+ }
73
+ function pick(log, ids, side) {
74
+ const byId = new Map(log.map((e) => [e.id, e]));
75
+ return ids.map((id) => {
76
+ const entry = byId.get(id);
77
+ if (entry === undefined)
78
+ throw new SessionError("not_found", `the ${side} log holds no entry ${id}`);
79
+ return entry;
80
+ });
81
+ }
82
+ export function repoLogTransfer(seat) {
83
+ return {
84
+ async listEntryIds(sessionId) {
85
+ const log = await logOrNull(seat, sessionId);
86
+ return log === null ? null : log.map((e) => e.id);
87
+ },
88
+ async exportStream(sessionId, opts) {
89
+ const { afterSeq } = readExportOptions(opts);
90
+ const log = await logOrNull(seat, sessionId);
91
+ if (log === null)
92
+ return null;
93
+ const tail = log.slice(afterSeq + 1);
94
+ return (async function* () {
95
+ yield* tail;
96
+ })();
97
+ },
98
+ beginReplace(sessionId, opts) {
99
+ return stagedReplace(seat, sessionId, readBeginOptions(opts));
100
+ },
101
+ };
102
+ }
103
+ function stagedReplace(seat, sessionId, gate) {
104
+ const validator = new StreamingImportValidator(gate);
105
+ let staged = [];
106
+ let ended;
107
+ const refuseEnded = () => {
108
+ if (ended !== undefined)
109
+ throw new SessionError("invalid_session", `the staging of session ${sessionId} has ended (${ended}) — it takes nothing more`);
110
+ };
111
+ return {
112
+ stagingId: `${sessionId}#stg-${uuidv7()}`,
113
+ async append(entries) {
114
+ refuseEnded();
115
+ try {
116
+ if (!Array.isArray(entries))
117
+ throw receiptRefusal(`SessionLogReplace.append takes an array of entries, got ${entries === null ? "null" : typeof entries}`);
118
+ for (const entry of entries) {
119
+ const copy = detachedCopy(entry);
120
+ validator.step(copy);
121
+ staged.push(copy);
122
+ }
123
+ }
124
+ catch (err) {
125
+ ended = "a batch was refused";
126
+ staged = [];
127
+ throw err;
128
+ }
129
+ },
130
+ async commit(input) {
131
+ refuseEnded();
132
+ ended = "committed";
133
+ const entries = staged;
134
+ staged = [];
135
+ const { owner, decide } = readCommit(input);
136
+ validator.finish();
137
+ const stagedIds = entries.map((e) => e.id);
138
+ return seat.holding(sessionId, async () => {
139
+ const row = await seat.readRow(sessionId);
140
+ if (row !== undefined)
141
+ importRowCells(sessionId, owner, row.metadata, row.metadata.createdAt);
142
+ const current = row === undefined ? null : row.entries;
143
+ const view = {
144
+ current: current === null ? null : current.map((e) => e.id),
145
+ staged: stagedIds,
146
+ read: async (side, ids) => structuredClone(side === "current" ? pick(current ?? [], ids, "current") : pick(entries, ids, "staged")),
147
+ };
148
+ const verdict = await decide(view);
149
+ if (verdict !== "replace" && verdict !== "keep")
150
+ throw receiptRefusal(`SessionLogCommit.decide must answer "replace" or "keep", got ${typeof verdict === "string" ? `"${verdict}"` : typeof verdict}`);
151
+ if (verdict === "keep") {
152
+ if (row === undefined)
153
+ throw new SessionError("invalid_session", `decide answered "keep" for session ${sessionId}, which has no row — there is no log to keep`);
154
+ return { outcome: "kept", head: row.head };
155
+ }
156
+ const expect = row === undefined ? { row: null } : { row: row.head, log: sessionLogMarkOf(row.entries) };
157
+ const answer = await seat.importEntries(sessionId, owner ?? undefined, entries, { ...gate, expect });
158
+ return { outcome: "replaced", head: committedHead(sessionId, answer) };
159
+ });
160
+ },
161
+ async abort() {
162
+ ended ??= "aborted";
163
+ staged = [];
164
+ },
165
+ };
166
+ }
@@ -76,7 +76,12 @@ export type SessionRuleEntryField = {
76
76
  * name starting with `*` as no rule; in `toolAllow` it grants nothing by itself and the entries beside it keep their reading,
77
77
  * where grammars 1–4 voided a list holding it. An engine of grammar 4 given a row written in grammar 5 refuses it rather than
78
78
  * read a `*` deny as nothing. In the same revision a host pattern with an empty label (`WebFetch(domain:.evil.test)`) or a `*`
79
- * the URL parser folds (`*.`) is no rule, where grammar 4 read the exact host it spelled; an earlier row's such entry reads as no rule.
79
+ * the URL parser folds (`*.`) is no rule, where grammar 4 read the exact host it spelled; an earlier row's such entry reads as no rule;
80
+ * - 6, a persisted rule with no content (`SendUserFile`, `Bash`, `Bash(*)`) is the WHOLE-TOOL rule (`match: "tool"`), where grammar 5's
81
+ * persisted grammar read every bare name as no rule. A session's entries mean what they meant (the entry reader already read a bare
82
+ * name as the whole tool), so no earlier entry reads differently; the stamp moves for the persisted store's buckets and the sync
83
+ * wire's states, so an engine of grammar 5 given a bucket written in grammar 6 refuses it whole rather than drop a whole-tool deny
84
+ * as damage. No persisted row of an earlier stamp can hold a bare name (every entrance refused one), so none is read anew.
80
85
  * A row an earlier grammar wrote keeps the meaning that grammar gave its entries, and an entry that grammar could not read takes
81
86
  * this one's ({@link earlierGrammarReads}, over the revisions above as one table); an entry this grammar reads as no rule reads as
82
87
  * `earlier_grammar` ({@link compileSessionRuleBucket}).
@@ -89,7 +94,7 @@ export type SessionRuleEntryField = {
89
94
  * what an existing persisted rule text means owes that store a reading of its earlier stamps, as {@link earlierGrammarReads}
90
95
  * is for entries. Every stamp is judged by {@link readRuleGrammarStamp}.
91
96
  */
92
- export declare const SESSION_RULES_GRAMMAR = 5;
97
+ export declare const SESSION_RULES_GRAMMAR = 6;
93
98
  /** {@link SessionPermissionRules} plus the monotonic `rev` the store stamps (the OCC key). */
94
99
  export interface StoredSessionRules extends SessionPermissionRules {
95
100
  rev: number;
@@ -12,7 +12,7 @@ const BUCKETS = Object.keys(SESSION_RULE_BUCKETS);
12
12
  const ENTRY_FIELDS = BUCKETS.filter((f) => SESSION_RULE_BUCKETS[f] !== "dirs");
13
13
  const STORE_STAMPS = new Set(["rev", "gen", "grammar"]);
14
14
  const OPERATOR_PART = "operatorRules";
15
- export const SESSION_RULES_GRAMMAR = 5;
15
+ export const SESSION_RULES_GRAMMAR = 6;
16
16
  export class SessionPolicyError extends Error {
17
17
  code;
18
18
  detail;
@@ -1,6 +1,7 @@
1
1
  import { type Session, type SessionHead, type SessionPlacementRecord, type SessionRepo } from "../internal/harness.js";
2
- import { type AcquiredSession, type PlacedSessionRow, type SessionListQuery, type SessionPlacement, type SessionStore, type SessionStoreSummary } from "./session.js";
2
+ import { type AcquiredSession, type PlacedSessionRow, type SessionListQuery, type SessionLogTransfer, type SessionPlacement, type SessionStore, type SessionStoreHooks, type SessionStoreSummary } from "./session.js";
3
3
  import type { StoreDurability } from "./checkpoint-store.js";
4
+ import { type RetentionDeclaration } from "./retention.js";
4
5
  import { SESSION_DEFAULT_TTL_DAYS } from "../config/defaults.js";
5
6
  export { SESSION_DEFAULT_TTL_DAYS };
6
7
  /** What idle-eviction and `release` do to the underlying repo. */
@@ -51,6 +52,17 @@ export interface TtlSessionStoreOptions {
51
52
  durability: StoreDurability;
52
53
  };
53
54
  };
55
+ /**
56
+ * The store's managed-retention declaration ({@link RetentionDeclaration}): `"managed"` says this store's rows are deleted
57
+ * on schedule by the deployment. Same declaration rule as {@link durability}: this cache layer runs no sweep and cannot see
58
+ * one, so the party that runs the sweep over the repo's rows states it. Default `"none"`. A word other than the two is refused
59
+ * at construction (`config.retention_capability`).
60
+ */
61
+ retention?: RetentionDeclaration;
62
+ /** The deployment's hooks on this store's row deletions ({@link SessionStoreHooks}): `beforeSessionDelete` runs, awaited, before
63
+ * every row this store deletes — an owner's `delete`, a placed `release`, an `evict: "delete"` release or idle sweep. A hook that is
64
+ * not a function, or a member this store does not run, is refused at construction. */
65
+ hooks?: SessionStoreHooks;
54
66
  }
55
67
  /**
56
68
  * The one placement admission of a session store's `acquire` — every backend that declares the placement partition
@@ -97,12 +109,12 @@ export declare function admitSessionPlacement(sessionId: string, persisted: Sess
97
109
  * See `design/10-会话持久化与会话中心.md` for the durable-backend (TiDB) contract.
98
110
  */
99
111
  export declare class TtlSessionStore implements SessionStore {
100
- /** Managed-retention declaration (ruled 2026-08-05, retention.ts): with a custom repo the default
101
- * evict policy is `forget` — cache eviction only, the durable rows live on — and there is no
102
- * tenant-scoped scheduled-deletion contract on any arm. Honestly `"none"`: a deployment with a
103
- * LOCKED retention policy refuses to start over this store. (The `SessionStore` interface itself
104
- * is declaration-agnostic; the retention face is the structural `RetentionDeclaring` shape.) */
105
- readonly retention: "none";
112
+ /** Managed-retention declaration (retention.ts): whether this store's rows are deleted on schedule by the deployment — given
113
+ * by the party that runs the sweep ({@link TtlSessionStoreOptions.retention}), `"none"` when none is given. This layer deletes
114
+ * nothing on schedule itself: with a custom repo the default evict policy is `forget` (cache eviction only, the durable rows
115
+ * live on), so a locked retention policy refuses this store at the default. (The `SessionStore` interface
116
+ * itself is declaration-agnostic; the retention face is the structural `RetentionDeclaring` shape.) */
117
+ readonly retention: RetentionDeclaration;
106
118
  /** design/173 §2.3 — see {@link TtlSessionStoreOptions.durability} for the declaration rules. */
107
119
  readonly durability?: StoreDurability;
108
120
  /** Subagent transcript persistence — see {@link TtlSessionStoreOptions.placements}. */
@@ -124,6 +136,20 @@ export declare class TtlSessionStore implements SessionStore {
124
136
  /** The repo's head read as this store's own decisions read the row through it (the cache check, the existence check), held
125
137
  * privately so the store's reading of its rows is the repo's whatever a host does with the face. */
126
138
  private readonly repoHead?;
139
+ /** The storage half of a cross-backend move ({@link SessionStore.logTransfer}), over the repo's row read and its conditional import:
140
+ * present only when the repo has both and a head read. A staging lives in this process; a commit holds the id as a release does, and
141
+ * the import it ends with is conditional on the row the commit read. */
142
+ readonly logTransfer?: SessionLogTransfer;
143
+ /** The owner-guarded delete ({@link SessionStore.delete}): present only when the repo has a head read (the owner it guards on) and
144
+ * the row read (so its removal is conditional on the row it judged). */
145
+ readonly delete?: (sessionId: string, guard: {
146
+ owner: string | null;
147
+ }) => Promise<boolean>;
148
+ /** Whether the repo judges the expectation of the writes this store hands it (`SessionRepo.delete` / `importEntries` with `expect`):
149
+ * a repo with a head read and the row read ({@link SessionRepo.readRow}). Over any other repo a deletion is of the id it judged. */
150
+ private readonly judgesRows;
151
+ /** {@link TtlSessionStoreOptions.hooks}' deletion hook, read once at construction. */
152
+ private readonly beforeRowDelete?;
127
153
  private repo;
128
154
  private entries;
129
155
  /** In-flight acquisitions keyed by id, so concurrent acquire(sameId) share one session. */
@@ -138,6 +164,8 @@ export declare class TtlSessionStore implements SessionStore {
138
164
  * and then lose) an authority the delete is about to close, and the caller would hold a session whose first append answers
139
165
  * log_closed while the file still exists. The gate is per-id and bounded by the release's own settlement (both outcomes release it). */
140
166
  private releasing;
167
+ /** Resolutions of an id in flight (`openOrCreate`), each marked when a hold of the id starts while it reads the row. */
168
+ private readonly resolutions;
141
169
  /** Sessions pinned by a design/45 checkpoint — skipped by idle sweep until unpinned (B6/§5). */
142
170
  private pinned;
143
171
  private defaultTtlMs;
@@ -157,16 +185,24 @@ export declare class TtlSessionStore implements SessionStore {
157
185
  * view without positive proof is dropped and the id resolved from the row; over one with no head read (it mints no occupant token)
158
186
  * the cached view is the only evidence of the occupant, and it stands. */
159
187
  private viewStandsFor;
160
- /** Whether a cached view is still the occupant the row holds ({@link viewStandsFor}, over the row's head read in one read). Over a repo
161
- * with no head read there is no row to read: the judge's answer for no row there is "stands", given without reading the view. */
162
- private cachedViewStands;
188
+ /** Whether a cached view is still the occupant the row holds ({@link viewStandsFor}, over the row's head read in one read) and still
189
+ * the log it holds — the row's leaf is the view's: a log replaced under the same occupant (a cross-backend move's commit, through
190
+ * another instance or the repo) is another log, and its view is dropped and the id resolved from the row. Answers the head that read
191
+ * gave when the view stands — the row a deletion through the view expects (`SessionRepo.delete`'s expectation) — and `undefined` when
192
+ * it does not. Over a repo with no head read there is no row to read: the judge's answer for no row there is "stands" (`null`: no head
193
+ * to expect), given without reading the view. */
194
+ private standingRow;
163
195
  /** The placement admission ({@link admitSessionPlacement}) for this store, judged on every resolution path. The
164
196
  * partition declaration is a getter over this store's live field, so it is read where the admission judges the
165
197
  * mirror direction (after the request's own members, and only then) — never captured at construction. */
166
198
  private assertPlacementAdmission;
167
199
  /** Resume an existing session from the repo, or create it if the backend has no such id (unless
168
- * `requireExisting`, in which case a genuinely-missing id fails loud instead — design/114 Phase3). */
200
+ * `requireExisting`, in which case a genuinely-missing id fails loud instead — design/114 Phase3). A resolution that a hold of the id
201
+ * (a commit, a delete, a release) overtook while it read the row is withdrawn and made again after the hold: the view it read may be of
202
+ * a log the hold replaced, and it is never left published. */
169
203
  private openOrCreate;
204
+ /** One resolution of {@link openOrCreate}: open the row, or create it on a miss. */
205
+ private resolveRow;
170
206
  private createAndStore;
171
207
  /** Refresh the idle timer for a session, and record the activity on its row through the repo ({@link SessionRepo.touch}, where the repo
172
208
  * has it) — the time {@link list} orders by. A fault recording it rejects. */
@@ -208,17 +244,46 @@ export declare class TtlSessionStore implements SessionStore {
208
244
  /** Run a release that may delete the row while it holds the id: the gate is set before the first await, after any release already in
209
245
  * flight for the id, and `acquire` / `register` answer after it settles — no caller captures an authority the delete is about to tear
210
246
  * down (the repo closes the shared authority before its removal can fail), or writes the row mid-decision. */
247
+ /** Resolves once the hold of the id in flight when the caller arrived settles (either outcome). A hold queued behind it is the next
248
+ * resolution's concern: `openOrCreate` resolves again after any hold that overtakes it. */
249
+ private settledHolds;
211
250
  private holdingId;
212
251
  /** The deciding half of {@link release}, under its gate. A delete goes through the cached view only while the row still stands for it
213
- * (`cachedViewStands`); with no view, or a view of an occupant the row no longer holds (another writer deleted the row, or deleted and
214
- * created it again), the row decides — its placement read cold ({@link rowIsPlaced}) — and an unplaced row nobody here holds is left
215
- * as it is. Placement obligation 4: a placed row's release is a REAL deletion whatever the evict policy (the joint reap deletes the
216
- * agent row first and then calls this to end the transcript; a forget would strand it). A delete runs only on a read that answered
217
- * — the head read with the view still standing, or the row's own placement: a read that faults deletes nothing, and the release
218
- * rejects with it. A placed release that fails (a read or the delete) leaves the tombstone, so the retry reads the row again —
219
- * never a retained cache entry, which could serve a closed log; an unplaced view's release under `evict: "delete"` leaves nothing,
220
- * so its retry after a failed read resolves and deletes nothing. */
252
+ * (`standingRow`); with no view, or a view of an occupant the row no longer holds (another writer deleted the row, or deleted and
253
+ * created it again), the row decides — its head read first, then its placement read cold ({@link rowIsPlaced}) — and an unplaced row
254
+ * nobody here holds is left as it is. Placement obligation 4: a placed row's release is a REAL deletion whatever the evict policy (the
255
+ * joint reap deletes the agent row first and then calls this to end the transcript; a forget would strand it). A delete runs only on a
256
+ * read that answered — the head read with the view still standing, or the row's own placement: a read that faults deletes nothing, and
257
+ * the release rejects with it. A placed release that fails (a read or the delete) leaves the tombstone, so the retry reads the row
258
+ * again — never a retained cache entry, which could serve a closed log; an unplaced view's release under `evict: "delete"` leaves
259
+ * nothing, so its retry after a failed read resolves and deletes nothing. What the deletion expects of the row is what was judged:
260
+ * a placed transcript's deletion is owed to its occupant, so it expects the occupant only; an unplaced view's eviction judged its log
261
+ * idle, so it expects the view's occupant and the view's log as it stands after the hook ({@link idleViewExpectation}). A cold release
262
+ * expects the head it read before the placement (no row read ⇒ it expects no row, and so deletes none): the deletion lands only on
263
+ * that generation, and a row once replaced never comes back, so the placement read after it was of that same row. */
221
264
  private releaseRow;
265
+ /** What the deletion of a view judged idle (an `evict: "delete"` release or sweep) expects of the row, read after the hook: the occupant
266
+ * the view stood for and the view's log as it stands then — an append through the view itself while the hook ran is still the view's
267
+ * log; a write through anyone else is not, and the row is not deleted. Over a repo that does not judge rows, none (the id judged). */
268
+ private idleViewExpectation;
269
+ /** Every row deletion this store makes, after its caller judged the row: the deployment's {@link TtlSessionStoreOptions.hooks} deletion
270
+ * hook first, awaited — when it rejects the row is not deleted and the deletion rejects with it — then the repo's delete, conditional
271
+ * on the row the caller judged (`expect`, read after the hook and judged by the repo in the step that removes the row: the hook ran in
272
+ * another writer's time, which may have deleted the row, created another under the id, or written it). Answers whether it deleted: a
273
+ * missed expectation (`conflict`) deletes nothing and answers `false`. With no expectation (a repo that does not judge rows) the
274
+ * deletion is of the id judged. */
275
+ private deleteRow;
276
+ /**
277
+ * The owner-guarded delete ({@link SessionStore.delete}), holding the id as a release does: the row's head decides — no row, or an
278
+ * owner other than `guard.owner` (null-safe), deletes nothing — and a placed row is left to `release` (the joint reap). A deleted row
279
+ * leaves no cached view and no pin: the id answers nothing afterwards, and a later create under it is a new occupant.
280
+ */
281
+ private deleteOwned;
282
+ /** The row's metadata as the repo holds it, its placement included; `undefined` = no row. A read fault rejects. */
283
+ private rowMetadata;
284
+ /** The row's placement: the repo's placement probe where it has one, else the row's own metadata; `undefined` = no row or an unplaced
285
+ * one. A read fault rejects. */
286
+ private readPlacement;
222
287
  /** The repo's placement probe, where it has one. */
223
288
  private placementProbe;
224
289
  /** Whether an uncached id's row is worth reading for its placement: through the probe on a store that declares placements, and by