@sema-agent/core 7.56.0 → 7.58.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (319) hide show
  1. package/CHANGELOG.md +926 -0
  2. package/LICENSE +1 -1
  3. package/dist/agents/org-delivery-gate.js +3 -4
  4. package/dist/agents/peer-held-queue.d.ts +69 -49
  5. package/dist/agents/peer-held-queue.js +255 -106
  6. package/dist/agents/peer-session-drain.js +63 -43
  7. package/dist/agents/send-message-tool.js +3 -2
  8. package/dist/agents/subagent-steps.js +2 -4
  9. package/dist/agents/subagent.js +8 -8
  10. package/dist/brain/anthropic.js +16 -8
  11. package/dist/brain/open-responses.js +10 -8
  12. package/dist/brain/openai.js +11 -9
  13. package/dist/brain/provider-dialect.d.ts +3 -2
  14. package/dist/brain/provider-dialect.js +2 -2
  15. package/dist/brain/request-params.d.ts +6 -0
  16. package/dist/brain/request-params.js +14 -1
  17. package/dist/brain/route-adjudicator.js +2 -1
  18. package/dist/brain/stream-engine.d.ts +9 -0
  19. package/dist/brain/stream-engine.js +24 -10
  20. package/dist/brain/stream-shared.d.ts +5 -4
  21. package/dist/brain/stream-shared.js +4 -4
  22. package/dist/core/a2a.d.ts +2 -1
  23. package/dist/core/a2a.js +23 -10
  24. package/dist/core/allow-entry.d.ts +5 -11
  25. package/dist/core/allow-entry.js +19 -26
  26. package/dist/core/approval-object.d.ts +21 -5
  27. package/dist/core/approval-object.js +44 -17
  28. package/dist/core/ask-origin.d.ts +23 -4
  29. package/dist/core/ask-origin.js +5 -1
  30. package/dist/core/auto-compaction.d.ts +75 -6
  31. package/dist/core/auto-compaction.js +43 -27
  32. package/dist/core/auto-mode-directive.d.ts +29 -5
  33. package/dist/core/auto-mode-directive.js +38 -8
  34. package/dist/core/background-agent-store.d.ts +6 -2
  35. package/dist/core/background-agent-store.js +1 -1
  36. package/dist/core/checkpoint-requirements.d.ts +13 -1
  37. package/dist/core/checkpoint-requirements.js +4 -0
  38. package/dist/core/checkpoint-store.d.ts +44 -40
  39. package/dist/core/checkpoint-store.js +32 -14
  40. package/dist/core/cross-boundary-taint.js +4 -2
  41. package/dist/core/engine-notice.d.ts +4 -3
  42. package/dist/core/engine-notice.js +6 -0
  43. package/dist/core/file-history-store.d.ts +14 -8
  44. package/dist/core/file-history-store.js +14 -4
  45. package/dist/core/fs-write-gate-policy.d.ts +4 -2
  46. package/dist/core/fs-write-gate-policy.js +7 -3
  47. package/dist/core/gate-fold.js +6 -3
  48. package/dist/core/gate-lanes.js +13 -5
  49. package/dist/core/git-worktree-env.d.ts +53 -11
  50. package/dist/core/git-worktree-env.js +96 -12
  51. package/dist/core/hooks.d.ts +6 -3
  52. package/dist/core/hooks.js +12 -5
  53. package/dist/core/human-input-projection.d.ts +1 -0
  54. package/dist/core/human-input-projection.js +3 -0
  55. package/dist/core/locked-config.d.ts +15 -1
  56. package/dist/core/locked-config.js +38 -2
  57. package/dist/core/mailbox-store.d.ts +62 -1
  58. package/dist/core/mailbox-store.js +59 -0
  59. package/dist/core/mcp-call-meta.d.ts +66 -0
  60. package/dist/core/mcp-call-meta.js +103 -0
  61. package/dist/core/mcp-connection-pool.d.ts +3 -1
  62. package/dist/core/mcp-connection-pool.js +3 -1
  63. package/dist/core/mcp-failure.d.ts +7 -1
  64. package/dist/core/mcp-failure.js +10 -0
  65. package/dist/core/mcp-name-judge.d.ts +46 -0
  66. package/dist/core/mcp-name-judge.js +61 -0
  67. package/dist/core/mcp-probe.d.ts +5 -1
  68. package/dist/core/mcp-probe.js +3 -6
  69. package/dist/core/mcp-server-link.d.ts +5 -2
  70. package/dist/core/mcp-server-spec.d.ts +46 -18
  71. package/dist/core/mcp-server-spec.js +1 -18
  72. package/dist/core/mcp.d.ts +6 -14
  73. package/dist/core/mcp.js +85 -65
  74. package/dist/core/memory-engine/consolidation-driver.js +4 -3
  75. package/dist/core/memory-engine/distiller.js +26 -17
  76. package/dist/core/memory-engine/layout.js +5 -2
  77. package/dist/core/memory-engine/scope-contract.d.ts +45 -4
  78. package/dist/core/memory-engine/scope-contract.js +80 -11
  79. package/dist/core/mode-policy.d.ts +8 -5
  80. package/dist/core/mode-policy.js +5 -4
  81. package/dist/core/mods/host.js +1 -1
  82. package/dist/core/mods/kernel/dispatch.d.ts +3 -0
  83. package/dist/core/mods/kernel/dispatch.js +10 -8
  84. package/dist/core/mods/kernel/events.d.ts +5 -1
  85. package/dist/core/mods/kernel/events.js +1 -1
  86. package/dist/core/mods/kernel/registration.d.ts +5 -1
  87. package/dist/core/mods/kernel/site-rules.d.ts +3 -0
  88. package/dist/core/mods/kernel/site-rules.js +10 -0
  89. package/dist/core/mods/package.d.ts +23 -0
  90. package/dist/core/mods/package.js +118 -0
  91. package/dist/core/mods/stations.d.ts +2 -2
  92. package/dist/core/mods/stations.js +1 -1
  93. package/dist/core/mods/tool-call.d.ts +5 -1
  94. package/dist/core/mods/tool-call.js +12 -3
  95. package/dist/core/park-selfcheck.js +2 -0
  96. package/dist/core/path-guard-rows.d.ts +20 -0
  97. package/dist/core/path-guard-rows.js +11 -0
  98. package/dist/core/peer-seat.d.ts +186 -0
  99. package/dist/core/peer-seat.js +307 -0
  100. package/dist/core/permission-rule-consent.d.ts +5 -3
  101. package/dist/core/permission-rule-consent.js +20 -15
  102. package/dist/core/permission-rule-model.d.ts +43 -2
  103. package/dist/core/permission-rule-model.js +52 -8
  104. package/dist/core/permission-rule-org.js +1 -1
  105. package/dist/core/present-plan-tool.d.ts +10 -1
  106. package/dist/core/present-plan-tool.js +46 -2
  107. package/dist/core/protocol-http-auth.d.ts +56 -31
  108. package/dist/core/protocol-http-auth.js +71 -42
  109. package/dist/core/protocol-naming.d.ts +20 -0
  110. package/dist/core/protocol-naming.js +20 -3
  111. package/dist/core/read-only-shell.d.ts +20 -5
  112. package/dist/core/read-only-shell.js +29 -14
  113. package/dist/core/redaction-marks.d.ts +16 -0
  114. package/dist/core/redaction-marks.js +16 -0
  115. package/dist/core/redaction-passes.js +8 -9
  116. package/dist/core/remote-env.d.ts +37 -1
  117. package/dist/core/remote-env.js +11 -0
  118. package/dist/core/resume-startup-cause.d.ts +24 -2
  119. package/dist/core/resume-startup-cause.js +20 -1
  120. package/dist/core/retention.d.ts +41 -15
  121. package/dist/core/retention.js +59 -12
  122. package/dist/core/rewrite-rejudge.d.ts +37 -0
  123. package/dist/core/rewrite-rejudge.js +40 -0
  124. package/dist/core/roles.js +50 -7
  125. package/dist/core/run-origin.d.ts +40 -0
  126. package/dist/core/run-origin.js +37 -0
  127. package/dist/core/runner/advertised-writable-dirs.d.ts +57 -38
  128. package/dist/core/runner/advertised-writable-dirs.js +126 -0
  129. package/dist/core/runner/compact-session.d.ts +10 -0
  130. package/dist/core/runner/compact-session.js +202 -0
  131. package/dist/core/runner/compaction-call-options.d.ts +2 -2
  132. package/dist/core/runner/compaction-restate.d.ts +15 -6
  133. package/dist/core/runner/compaction-restate.js +28 -2
  134. package/dist/core/runner/compaction-seams.d.ts +21 -1
  135. package/dist/core/runner/compaction-seams.js +11 -8
  136. package/dist/core/runner/contracts.d.ts +36 -21
  137. package/dist/core/runner/derived-route-fallback.d.ts +13 -0
  138. package/dist/core/runner/derived-route-fallback.js +6 -0
  139. package/dist/core/runner/env-capability-census.d.ts +3 -2
  140. package/dist/core/runner/env-capability-census.js +9 -3
  141. package/dist/core/runner/gate-exit.d.ts +18 -4
  142. package/dist/core/runner/gate-exit.js +5 -1
  143. package/dist/core/runner/permission-rule-lanes.d.ts +7 -7
  144. package/dist/core/runner/permission-rule-lanes.js +17 -11
  145. package/dist/core/runner/prepare-acquire-reconcile.d.ts +3 -0
  146. package/dist/core/runner/prepare-acquire-reconcile.js +2 -1
  147. package/dist/core/runner/prepare-caps-and-workflow.d.ts +2 -0
  148. package/dist/core/runner/prepare-caps-and-workflow.js +1 -1
  149. package/dist/core/runner/prepare-config-doors.d.ts +14 -5
  150. package/dist/core/runner/prepare-config-doors.js +16 -13
  151. package/dist/core/runner/prepare-delegation-surface.d.ts +4 -0
  152. package/dist/core/runner/prepare-delegation-surface.js +15 -18
  153. package/dist/core/runner/prepare-gate-stations.js +1 -1
  154. package/dist/core/runner/prepare-hands-readface.d.ts +10 -4
  155. package/dist/core/runner/prepare-hands-readface.js +6 -1
  156. package/dist/core/runner/prepare-memory.d.ts +3 -0
  157. package/dist/core/runner/prepare-memory.js +19 -23
  158. package/dist/core/runner/prepare-park-ask.d.ts +2 -0
  159. package/dist/core/runner/prepare-park-ask.js +2 -2
  160. package/dist/core/runner/prepare-policy-chain.d.ts +4 -4
  161. package/dist/core/runner/prepare-policy-chain.js +4 -6
  162. package/dist/core/runner/prepare-protocol-tools.d.ts +4 -2
  163. package/dist/core/runner/prepare-protocol-tools.js +3 -3
  164. package/dist/core/runner/prepare-suspend-saga.d.ts +2 -0
  165. package/dist/core/runner/prepare-suspend-saga.js +2 -1
  166. package/dist/core/runner/prepare-task.d.ts +4 -1
  167. package/dist/core/runner/prepare-task.js +46 -37
  168. package/dist/core/runner/prepare-tool-disclosure-mount.d.ts +13 -0
  169. package/dist/core/runner/prepare-tool-disclosure-mount.js +13 -7
  170. package/dist/core/runner/prepare-wiring-manifest.d.ts +1 -0
  171. package/dist/core/runner/prepare-wiring-manifest.js +2 -2
  172. package/dist/core/runner/prepare-workspace-restore.d.ts +3 -0
  173. package/dist/core/runner/prepare-workspace-restore.js +4 -4
  174. package/dist/core/runner/resume-admission.js +1 -1
  175. package/dist/core/runner/resume-checkpoint-screen.js +2 -0
  176. package/dist/core/runner/rewind-files.d.ts +2 -5
  177. package/dist/core/runner/rewind-files.js +9 -51
  178. package/dist/core/runner/run-harness-handlers.d.ts +3 -4
  179. package/dist/core/runner/run-harness-handlers.js +1 -8
  180. package/dist/core/runner/run-identity-wiring.js +1 -0
  181. package/dist/core/runner/run-leg.js +15 -22
  182. package/dist/core/runner/run-notification-lane.d.ts +2 -0
  183. package/dist/core/runner/run-notification-lane.js +5 -2
  184. package/dist/core/runner/run-recovery-lanes.js +3 -4
  185. package/dist/core/runner/run-settle-and-teardown.js +5 -11
  186. package/dist/core/runner/run-terminal-adoption.js +3 -4
  187. package/dist/core/runner/run-turn-boundary.js +3 -5
  188. package/dist/core/runner/runtask.d.ts +8 -1
  189. package/dist/core/runner/runtask.js +28 -34
  190. package/dist/core/runner/send-message-continuation.js +1 -1
  191. package/dist/core/runner/session-verb-doors.d.ts +28 -0
  192. package/dist/core/runner/session-verb-doors.js +48 -0
  193. package/dist/core/runner/session-write-ledger.d.ts +30 -0
  194. package/dist/core/runner/session-write-ledger.js +101 -0
  195. package/dist/core/runner/stream-settle-backstop.js +11 -14
  196. package/dist/core/runner/sub-agent-deny-lists.d.ts +25 -3
  197. package/dist/core/runner/sub-agent-deny-lists.js +21 -10
  198. package/dist/core/runner/teardown-bounded.d.ts +1 -0
  199. package/dist/core/runner/teardown-bounded.js +1 -0
  200. package/dist/core/runner/terminal-account.js +3 -3
  201. package/dist/core/runner/tool-end-body.js +1 -0
  202. package/dist/core/runner/tool-occurrence.d.ts +4 -1
  203. package/dist/core/runner/tool-occurrence.js +2 -1
  204. package/dist/core/runner/write-protection-station.d.ts +8 -2
  205. package/dist/core/runner/write-protection-station.js +2 -0
  206. package/dist/core/runner-deps.d.ts +4 -4
  207. package/dist/core/secret-env.d.ts +4 -0
  208. package/dist/core/secret-env.js +3 -0
  209. package/dist/core/sensitive-path-policy.js +6 -7
  210. package/dist/core/session-log-transfer.d.ts +24 -0
  211. package/dist/core/session-log-transfer.js +166 -0
  212. package/dist/core/session-policy-store.d.ts +7 -2
  213. package/dist/core/session-policy-store.js +1 -1
  214. package/dist/core/session-store.d.ts +84 -19
  215. package/dist/core/session-store.js +162 -24
  216. package/dist/core/session.d.ts +92 -1
  217. package/dist/core/shell-read-silence.js +1 -0
  218. package/dist/core/shell-wrapper-projection.d.ts +1 -1
  219. package/dist/core/steer-replay.d.ts +4 -2
  220. package/dist/core/steer-replay.js +2 -1
  221. package/dist/core/store-contracts/background-agent-store-contract.js +1 -0
  222. package/dist/core/store-contracts/checkpoint-store-contract.js +19 -1
  223. package/dist/core/store-contracts/file-history-store-contract.js +9 -0
  224. package/dist/core/store-contracts/mailbox-store-contract.js +49 -1
  225. package/dist/core/store-contracts/session-repo-contract.js +112 -5
  226. package/dist/core/store-contracts/session-store-contract.d.ts +4 -1
  227. package/dist/core/store-contracts/session-store-contract.js +236 -2
  228. package/dist/core/task-event.d.ts +68 -8
  229. package/dist/core/task-registry-agent.d.ts +8 -4
  230. package/dist/core/task-registry-agent.js +14 -8
  231. package/dist/core/task-registry-shared.d.ts +36 -6
  232. package/dist/core/task-registry-shared.js +11 -0
  233. package/dist/core/task-registry.d.ts +1 -1
  234. package/dist/core/task-registry.js +1 -1
  235. package/dist/core/task-spec.d.ts +37 -0
  236. package/dist/core/task-stream.d.ts +2 -1
  237. package/dist/core/terminal-cause.d.ts +1 -1
  238. package/dist/core/tool-catalog-entries.d.ts +6 -0
  239. package/dist/core/tool-catalog-entries.js +2 -0
  240. package/dist/core/tool-name-aliases.d.ts +32 -2
  241. package/dist/core/tool-name-aliases.js +23 -0
  242. package/dist/core/tool-name-readings.d.ts +4 -0
  243. package/dist/core/tool-name-readings.js +1 -0
  244. package/dist/core/tool-policy.d.ts +10 -6
  245. package/dist/core/tool-policy.js +4 -7
  246. package/dist/core/tool-result-store.d.ts +17 -10
  247. package/dist/core/tool-result-store.js +3 -1
  248. package/dist/core/trace.d.ts +4 -1
  249. package/dist/core/trace.js +2 -1
  250. package/dist/core/types.d.ts +1 -1
  251. package/dist/core/untrusted-egress.d.ts +18 -0
  252. package/dist/core/untrusted-egress.js +82 -12
  253. package/dist/core/wiring-manifest.d.ts +12 -3
  254. package/dist/core/wiring-manifest.js +4 -3
  255. package/dist/core/workspace-snapshot.d.ts +44 -0
  256. package/dist/core/workspace-snapshot.js +34 -0
  257. package/dist/core/write-protect.d.ts +43 -3
  258. package/dist/core/write-protect.js +43 -16
  259. package/dist/engine/execution-env/node-execution-env.js +15 -11
  260. package/dist/engine/execution-env/symlink-chain.d.ts +7 -5
  261. package/dist/engine/harness/agent-harness.d.ts +12 -5
  262. package/dist/engine/harness/agent-harness.js +13 -2
  263. package/dist/engine/harness/types.d.ts +48 -7
  264. package/dist/engine/harness/types.js +5 -1
  265. package/dist/engine/llm/types.d.ts +12 -3
  266. package/dist/engine/llm/types.js +1 -1
  267. package/dist/engine/loop/agent-loop.d.ts +1 -4
  268. package/dist/engine/loop/agent-loop.js +26 -4
  269. package/dist/engine/session/import-validate.js +3 -0
  270. package/dist/engine/session/memory-repo.d.ts +17 -9
  271. package/dist/engine/session/memory-repo.js +44 -34
  272. package/dist/engine/session/repo-utils.d.ts +22 -4
  273. package/dist/engine/session/repo-utils.js +49 -1
  274. package/dist/engine/session/storage-base.d.ts +10 -1
  275. package/dist/engine/session/storage-base.js +7 -1
  276. package/dist/index.d.ts +23 -11
  277. package/dist/index.js +15 -6
  278. package/dist/internal/harness-types.d.ts +1 -1
  279. package/dist/internal/harness.d.ts +4 -3
  280. package/dist/internal/harness.js +3 -2
  281. package/dist/stores/file/checkpoint-store.d.ts +0 -4
  282. package/dist/stores/file/checkpoint-store.js +0 -1
  283. package/dist/stores/file/file-history-store.js +12 -4
  284. package/dist/stores/file/index.d.ts +4 -1
  285. package/dist/stores/file/index.js +4 -1
  286. package/dist/stores/file/mailbox-store.d.ts +2 -1
  287. package/dist/stores/file/mailbox-store.js +26 -1
  288. package/dist/stores/file/session-store.d.ts +15 -8
  289. package/dist/stores/file/session-store.js +28 -13
  290. package/dist/tools/fs/bash-readonly-classifier.d.ts +15 -19
  291. package/dist/tools/fs/bash-readonly-classifier.js +5 -10
  292. package/dist/tools/fs/fs-bash.js +10 -3
  293. package/dist/tools/fs/fs-write.d.ts +6 -3
  294. package/dist/tools/fs/fs-write.js +8 -7
  295. package/dist/tools/fs/index.d.ts +3 -0
  296. package/dist/tools/fs/index.js +1 -1
  297. package/dist/tools/fs/pattern-kill-guard.d.ts +3 -2
  298. package/dist/tools/fs/pattern-kill-guard.js +68 -36
  299. package/dist/tools/fs/safety.js +40 -8
  300. package/dist/tools/fs/search.js +6 -24
  301. package/dist/tools/fs/shell-read-check.d.ts +18 -1
  302. package/dist/tools/fs/shell-read-check.js +66 -16
  303. package/dist/tools/fs/shell-read-establish.js +2 -1
  304. package/dist/tools/fs/shell-read-identity.d.ts +12 -9
  305. package/dist/tools/fs/shell-read-identity.js +10 -5
  306. package/dist/tools/fs/shell-read-judge.d.ts +10 -1
  307. package/dist/tools/web.js +9 -7
  308. package/dist/tools/worktree.d.ts +42 -15
  309. package/dist/tools/worktree.js +60 -32
  310. package/package.json +4 -2
  311. package/test/export-surface.snapshot.json +141 -3
  312. package/wire-changes/core-stores-sql@7.57.0.json +29 -0
  313. package/wire-changes/core-stores-sql@7.58.0.json +29 -0
  314. package/wire-changes/core@7.57.0.json +1487 -0
  315. package/wire-changes/core@7.58.0.json +2188 -0
  316. package/wire-changes/mods-kernel@7.57.0.json +29 -0
  317. package/wire-changes/mods-kernel@7.58.0.json +81 -0
  318. package/wire-changes/primitives@7.57.0.json +245 -0
  319. package/wire-changes/primitives@7.58.0.json +29 -0
@@ -1,4 +1,5 @@
1
1
  import { strict as assert } from "node:assert";
2
+ import { sessionLogMarkOf } from "../../internal/harness.js";
2
3
  import { TtlSessionStore } from "../session-store.js";
3
4
  import { beginContract } from "./contract-harness.js";
4
5
  const SESSION_ENTRY = (id, parentId) => ({
@@ -142,7 +143,7 @@ export async function sessionRepoContract(make, runAssertion) {
142
143
  assert.equal((await again.getMetadata()).incarnation, token, "and the same occupant");
143
144
  assert.equal((await (await repo.open({ id: A, createdAt: "" })).getMetadata()).owner, "kit-x");
144
145
  });
145
- run("fork records the owner its options name in the fork row, else (absent or null) the source row's; importEntries onto an existing row keeps its metadata whole, onto an absent id records the importer", async () => {
146
+ run("fork records the owner its options name in the fork row, else (absent or null) the source row's; importEntries onto an existing row keeps its metadata whole and lands only when the row is the importer's (another owner's, or an owned row by an anonymous import, is refused conflict with nothing written), onto an absent id records the importer", async () => {
146
147
  const repo = make();
147
148
  const src = await repo.create({ id: A, owner: "kit-alice" });
148
149
  await src.getStorage().appendEntry(SESSION_ENTRY("e1", null));
@@ -155,15 +156,28 @@ export async function sessionRepoContract(make, runAssertion) {
155
156
  if (repo.importEntries === undefined)
156
157
  return;
157
158
  const token = (await src.getMetadata()).incarnation;
158
- await repo.importEntries(A, "kit-carol", [SESSION_ENTRY("e1", null)]);
159
+ const logOf = async (id) => (await (await repo.open({ id, createdAt: "" })).getStorage().getEntries()).map((e) => e.id);
160
+ const refusedAsConflict = async (owner, what) => {
161
+ let code;
162
+ try {
163
+ await repo.importEntries(A, owner, [SESSION_ENTRY("x1", null)]);
164
+ }
165
+ catch (err) {
166
+ code = err?.code;
167
+ }
168
+ assert.equal(code, "conflict", `${what}: an import lands only on the importer's row`);
169
+ assert.deepEqual(await logOf(A), ["e1"], `${what}: a refused import writes nothing`);
170
+ };
171
+ await refusedAsConflict("kit-carol", "an import by another principal");
172
+ await refusedAsConflict(undefined, "an import with no principal onto an owned row");
173
+ await repo.importEntries(A, "kit-alice", [SESSION_ENTRY("n1", null)]);
159
174
  const imported = await (await repo.open({ id: A, createdAt: "" })).getMetadata();
175
+ assert.deepEqual(await logOf(A), ["n1"], "the owner's import replaces the log");
160
176
  assert.equal(imported.owner, "kit-alice", "the owner is recorded only by the write that creates the row: an import never re-stamps it");
161
177
  assert.equal(imported.incarnation, token, "the log is replaced, not the occupant");
162
- await repo.importEntries(A, undefined, []);
163
- assert.equal((await (await repo.open({ id: A, createdAt: "" })).getMetadata()).owner, "kit-alice", "an import with no principal never makes an owned row anonymous");
164
178
  const cells = (m) => [m.createdAt, m.forkedFrom, m.forkedFromIncarnation, m.incarnation, m.owner, JSON.stringify(m.placement)];
165
179
  const forkRow = await (await repo.open({ id: B, createdAt: "" })).getMetadata();
166
- await repo.importEntries(B, "kit-carol", [SESSION_ENTRY("e1", null)]);
180
+ await repo.importEntries(B, "kit-bob", [SESSION_ENTRY("e1", null)]);
167
181
  assert.deepEqual(cells(await (await repo.open({ id: B, createdAt: "" })).getMetadata()), cells(forkRow), "the log is replaced, never the row: a fork row keeps its creation time and its lineage");
168
182
  const E = "0198fa00-0000-7000-8000-00000000000e";
169
183
  await repo.importEntries(E, "kit-carol", [SESSION_ENTRY("e1", null)]);
@@ -218,6 +232,99 @@ export async function sessionRepoContract(make, runAssertion) {
218
232
  store.dispose();
219
233
  }
220
234
  });
235
+ const conflictOf = async (write) => {
236
+ try {
237
+ await write();
238
+ }
239
+ catch (err) {
240
+ return err?.code;
241
+ }
242
+ return "resolved";
243
+ };
244
+ const logIds = async (repo, id) => {
245
+ try {
246
+ return (await (await repo.open({ id, createdAt: "" })).getStorage().getEntries()).map((e) => e.id);
247
+ }
248
+ catch {
249
+ return undefined;
250
+ }
251
+ };
252
+ run("importEntries answers the head its write committed — the same head a head read answers right after it", async () => {
253
+ const repo = make();
254
+ if (repo.importEntries === undefined || repo.headOf === undefined)
255
+ return;
256
+ const fresh = await repo.importEntries(A, "kit-alice", [SESSION_ENTRY("e1", null), SESSION_ENTRY("e2", "e1")]);
257
+ assert.deepEqual(fresh, await repo.headOf(A), "an import onto an absent id answers the new row's head");
258
+ assert.equal(fresh.leafId, "e2");
259
+ const again = await repo.importEntries(A, "kit-alice", [SESSION_ENTRY("n1", null)]);
260
+ assert.deepEqual(again, await repo.headOf(A), "an import onto the importer's row answers that row's head after the write");
261
+ assert.equal(again.incarnation, fresh.incarnation, "the same occupant");
262
+ });
263
+ run("readRow (where the repo answers it): no row ⇒ undefined; a row ⇒ its metadata, its whole log oldest-first and the head a head read answers, of one row", async () => {
264
+ const repo = make();
265
+ if (repo.readRow === undefined)
266
+ return;
267
+ assert.equal(await repo.readRow(A), undefined);
268
+ const sess = await repo.create({ id: A, owner: "kit-alice" });
269
+ await sess.getStorage().appendEntry(SESSION_ENTRY("e1", null));
270
+ await sess.getStorage().appendEntry(SESSION_ENTRY("e2", "e1"));
271
+ const row = await repo.readRow(A);
272
+ assert.ok(row !== undefined);
273
+ assert.equal(row.metadata.owner, "kit-alice");
274
+ assert.deepEqual(row.entries.map((e) => e.id), ["e1", "e2"]);
275
+ if (repo.headOf !== undefined)
276
+ assert.deepEqual(row.head, await repo.headOf(A), "the head of the row read is the head read's");
277
+ if (repo.exportEntries !== undefined)
278
+ assert.deepEqual(row.entries, await repo.exportEntries(A), "the log of the row read is the export's");
279
+ });
280
+ run("a conditional import lands only on the row it expects: the row and log as read ⇒ written; after an append, a delete, a delete and create again, or with no row expected while one stands ⇒ conflict, nothing written", async () => {
281
+ const repo = make();
282
+ if (repo.readRow === undefined || repo.importEntries === undefined)
283
+ return;
284
+ const sess = await repo.create({ id: A, owner: "kit-alice" });
285
+ await sess.getStorage().appendEntry(SESSION_ENTRY("e1", null));
286
+ const read = (await repo.readRow(A));
287
+ const asRead = { row: read.head, log: sessionLogMarkOf(read.entries) };
288
+ await sess.getStorage().appendEntry(SESSION_ENTRY("e2", "e1"));
289
+ assert.equal(await conflictOf(() => repo.importEntries(A, "kit-alice", [SESSION_ENTRY("x1", null)], { expect: asRead })), "conflict", "an append since the read: the log is not the one read");
290
+ assert.deepEqual(await logIds(repo, A), ["e1", "e2"], "the refused import wrote nothing");
291
+ assert.equal(await conflictOf(() => repo.importEntries(A, "kit-alice", [SESSION_ENTRY("x1", null)], { expect: { row: null } })), "conflict", "no row expected, a row stands");
292
+ const now = (await repo.readRow(A));
293
+ await repo.importEntries(A, "kit-alice", [SESSION_ENTRY("n1", null)], { expect: { row: now.head, log: sessionLogMarkOf(now.entries) } });
294
+ assert.deepEqual(await logIds(repo, A), ["n1"], "the row and log as read: written");
295
+ const before = (await repo.readRow(A));
296
+ await repo.delete({ id: A, createdAt: "" });
297
+ assert.equal(await conflictOf(() => repo.importEntries(A, "kit-alice", [SESSION_ENTRY("x1", null)], { expect: { row: before.head } })), "conflict", "the row was deleted since the read");
298
+ assert.equal(await logIds(repo, A), undefined, "and no row was created");
299
+ await repo.create({ id: A, owner: "kit-alice" });
300
+ assert.equal(await conflictOf(() => repo.importEntries(A, "kit-alice", [SESSION_ENTRY("x1", null)], { expect: { row: before.head } })), "conflict", "the row was created again: another occupant, same owner");
301
+ assert.deepEqual(await logIds(repo, A), [], "the new row's log is untouched");
302
+ const noShape = { row: before.head, log: "a mark of no shape" };
303
+ await assert.rejects(() => repo.importEntries(A, "kit-alice", [SESSION_ENTRY("x1", null)], { expect: noShape }), TypeError, "an expectation of no shape is refused, never read as none");
304
+ assert.deepEqual(await logIds(repo, A), [], "and wrote nothing");
305
+ });
306
+ run("a conditional delete removes only the row it expects: another occupant or no row ⇒ conflict, nothing removed; an occupant-only expectation survives an append, an expectation binding the log does not", async () => {
307
+ const repo = make();
308
+ if (repo.readRow === undefined)
309
+ return;
310
+ const sess = await repo.create({ id: A, owner: "kit-alice" });
311
+ await sess.getStorage().appendEntry(SESSION_ENTRY("e1", null));
312
+ const read = (await repo.readRow(A));
313
+ await sess.getStorage().appendEntry(SESSION_ENTRY("e2", "e1"));
314
+ assert.equal(await conflictOf(() => repo.delete({ id: A, createdAt: "" }, { row: read.head, log: sessionLogMarkOf(read.entries) })), "conflict", "the log bound and appended to since: not deleted");
315
+ assert.deepEqual(await logIds(repo, A), ["e1", "e2"]);
316
+ await repo.delete({ id: A, createdAt: "" });
317
+ await repo.create({ id: A, owner: "kit-alice" });
318
+ assert.equal(await conflictOf(() => repo.delete({ id: A, createdAt: "" }, { row: read.head })), "conflict", "another occupant under the id: not deleted");
319
+ assert.deepEqual(await logIds(repo, A), [], "the new occupant stands");
320
+ const current = (await repo.readRow(A));
321
+ await (await repo.open({ id: A, createdAt: "" })).getStorage().appendEntry(SESSION_ENTRY("f1", null));
322
+ await repo.delete({ id: A, createdAt: "" }, { row: current.head });
323
+ assert.equal(await logIds(repo, A), undefined, "the occupant expected, appended to since: deleted (an append does not make it another row)");
324
+ assert.equal(await conflictOf(() => repo.delete({ id: A, createdAt: "" }, { row: current.head })), "conflict", "no row: an occupant expected is not there");
325
+ const noShape = { row: undefined };
326
+ await assert.rejects(() => repo.delete({ id: A, createdAt: "" }, noShape), TypeError, "an expectation of no shape is refused, never read as none");
327
+ });
221
328
  run("the store over a repo answers headOf exactly when the repo does: present ⇒ the repo's own answer; absent ⇒ no headOf on the store, which still works", async () => {
222
329
  const repo = make();
223
330
  const store = new TtlSessionStore({ repo });
@@ -20,6 +20,9 @@ import { type ContractAssertionRunner } from "./contract-harness.js";
20
20
  *
21
21
  * Semantics since @sema-agent/core 7.56.0: the list reads the store's rows (a reopened store lists them), pages by the
22
22
  * `(lastActiveAt, sessionId)` keyset, filters by the row's owner, and refuses a bad query through `readSessionListQuery`.
23
+ * Since 7.57.0: the write faces — `logTransfer` (one write law: a commit lands only on the committer's row, keeps an existing row's
24
+ * occupant, refuses a placed row, passes every entry through the import gate, writes nothing on any refusal) and the owner-guarded
25
+ * `delete` — and a cached view is served only while it holds the row's leaf as well as its occupant.
23
26
  */
24
27
  export interface SessionStoreContractHooks {
25
28
  /** Delete `sessionId`'s session ROW through the backend's own deletion path (history and all), so that a later
@@ -38,7 +41,7 @@ export interface SessionStoreContractHooks {
38
41
  /** Optional faces (plus the replica hook, and `requireExisting` — absent = the store rejects the option, its other
39
42
  * legal mode) a run verified or found absent; reported per judging case, after its assertions held. */
40
43
  onOptionalMember?: (report: {
41
- member: "requireExisting" | "forget" | "fork" | "list" | "noteTaskRun" | "listPlaced" | "placements" | "headOf" | "ownership" | "replica";
44
+ member: "requireExisting" | "forget" | "fork" | "list" | "noteTaskRun" | "listPlaced" | "placements" | "headOf" | "ownership" | "replica" | "logTransfer" | "delete";
42
45
  status: "verified" | "absent";
43
46
  }) => void;
44
47
  }
@@ -1,6 +1,6 @@
1
1
  import { strict as assert } from "node:assert";
2
- import { uuidv7 } from "../../internal/harness.js";
3
- import { SESSION_LIST_LIMITS, hasSessionFork, isSessionConflict } from "../session.js";
2
+ import { SessionError, uuidv7 } from "../../internal/harness.js";
3
+ import { SESSION_LIST_LIMITS, hasSessionFork, isSessionConflict, } from "../session.js";
4
4
  import { readMember } from "../thrown-value.js";
5
5
  import { receiptRefusal, receiveOwnProperties } from "../own-property-receipt.js";
6
6
  import { beginContract } from "./contract-harness.js";
@@ -181,6 +181,8 @@ async function runSessionStoreContract(make, hooks) {
181
181
  headOf: hasHead,
182
182
  ownership: hasOwnership,
183
183
  replica: () => hooks.replica !== undefined,
184
+ logTransfer: (s) => hasHead(s) && typeof s.logTransfer === "object" && s.logTransfer !== null,
185
+ delete: (s) => hasHead(s) && typeof s.delete === "function",
184
186
  };
185
187
  const faceRun = (name, needs, fn) => run(name, async (store, open) => {
186
188
  const missing = [];
@@ -989,5 +991,237 @@ async function runSessionStoreContract(make, hooks) {
989
991
  assert.notEqual(await tokenOf(store, forkedId, "fork"), source, "a fork copies the history, never the occupant");
990
992
  assert.equal(await tokenOf(store, src, "fork source after"), source, "forking does not touch the source's occupant");
991
993
  });
994
+ run("[transfer] the read half answers the whole log oldest-first, resumes after a position, and says null for an id with no row; a bad read option is refused", async (store) => {
995
+ if (!(await FACE_PRESENT.logTransfer(store)))
996
+ return report("logTransfer", "absent");
997
+ const t = store.logTransfer;
998
+ const id = freshId();
999
+ const session = (await store.acquire(id)).session;
1000
+ for (const e of [userEntry("e1", null), assistantEntry("e2", "e1"), userEntry("e3", "e2")])
1001
+ await append(session, e);
1002
+ assert.deepEqual(await t.listEntryIds(id), ["e1", "e2", "e3"]);
1003
+ assert.deepEqual(await streamIds(t, id), ["e1", "e2", "e3"]);
1004
+ assert.deepEqual(await streamIds(t, id, { afterSeq: 0, batchSize: 1 }), ["e2", "e3"], "afterSeq resumes after that position, whatever the page");
1005
+ assert.deepEqual(await streamIds(t, id, { afterSeq: -1 }), ["e1", "e2", "e3"]);
1006
+ const absent = freshId();
1007
+ assert.equal(await t.listEntryIds(absent), null, "no row ⇒ null, never an empty log");
1008
+ assert.equal(await t.exportStream(absent), null);
1009
+ for (const bad of [{ afterSeq: -2 }, { afterSeq: 1.5 }, { batchSize: 0 }, { afterSeq: "0" }, { cursor: 1 }]) {
1010
+ await rejectsWithCode(() => Reflect.apply(t.exportStream, t, [id, bad]), "config.invalid_argument", `exportStream(${JSON.stringify(bad)})`);
1011
+ }
1012
+ report("logTransfer", "verified");
1013
+ });
1014
+ faceRun("[transfer] a commit onto the committer's own row replaces the log and keeps the row: the occupant and owner stay, and the new log is what this store and a reopened one serve", ["logTransfer", "ownership"], async (store, open) => {
1015
+ const id = freshId();
1016
+ await store.register(id, "kit-alice");
1017
+ const held = (await store.acquire(id)).session;
1018
+ await append(held, userEntry("old1", null));
1019
+ const before = await tokenOf(store, id, "before the commit");
1020
+ const done = await commitLog(store, id, { owner: "kit-alice" }, [userEntry("n1", null), assistantEntry("n2", "n1")]);
1021
+ assert.equal(done.outcome, "replaced");
1022
+ assert.deepEqual({ owner: done.head.owner, incarnation: done.head.incarnation, leafId: done.head.leafId }, { owner: "kit-alice", incarnation: before, leafId: "n2" }, "the head the commit answers is the row it left");
1023
+ assert.deepEqual(await headOf(store, id), done.head);
1024
+ assert.deepEqual(await entryIds((await store.acquire(id)).session), ["n1", "n2"], "a cached view of the replaced log is not served again");
1025
+ const second = await open(hooks.reopen(store));
1026
+ assert.deepEqual(await entryIds(await readBack(second, id)), ["n1", "n2"]);
1027
+ assert.equal(await tokenOf(second, id, "after a restart"), before, "the occupant is the row's: a commit onto an existing row keeps it");
1028
+ });
1029
+ faceRun("[transfer] a commit onto an id with no row creates it: the committer is its owner (null = anonymous) and it is a new occupant", ["logTransfer", "headOf"], async (store) => {
1030
+ const [owned, anonymous] = [freshId(), freshId()];
1031
+ const a = await commitLog(store, owned, { owner: "kit-alice" }, [userEntry("e1", null)]);
1032
+ assert.equal(a.outcome, "replaced");
1033
+ assert.equal(a.head.owner, "kit-alice");
1034
+ const token = await tokenOf(store, owned, "a row a commit created");
1035
+ assert.equal(a.head.incarnation, token);
1036
+ const b = await commitLog(store, anonymous, { owner: null }, [userEntry("e1", null)]);
1037
+ assert.equal(b.head.owner, null);
1038
+ assert.notEqual(await tokenOf(store, anonymous, "a second created row"), token, "two rows are two occupants");
1039
+ });
1040
+ faceRun("[transfer] a commit lands only on the committer's row: another owner's, an anonymous row by a principal, an owned row by an anonymous commit — each refused conflict, decide never asked, nothing written", ["logTransfer", "ownership"], async (store) => {
1041
+ const owned = freshId();
1042
+ await store.register(owned, "kit-alice");
1043
+ await append((await store.acquire(owned)).session, userEntry("a1", null));
1044
+ const anonymous = freshId();
1045
+ await append((await store.acquire(anonymous)).session, userEntry("z1", null));
1046
+ for (const [id, owner, keep] of [[owned, "kit-bob", "a1"], [owned, null, "a1"], [anonymous, "kit-bob", "z1"]]) {
1047
+ for (const verdict of ["replace", "keep"]) {
1048
+ let asked = false;
1049
+ await rejectsWithConflict(() => commitLog(store, id, { owner, decide: () => {
1050
+ asked = true;
1051
+ return verdict;
1052
+ } }, [userEntry("x1", null)]), `a ${verdict} commit by ${String(owner)} onto another's row`);
1053
+ assert.equal(asked, false, "the relation is not judged for a row the committer may not write");
1054
+ assert.deepEqual(await store.logTransfer.listEntryIds(id), [keep], "a refused commit writes nothing");
1055
+ }
1056
+ }
1057
+ assert.equal(await ownerOf(store, owned, "the owned row"), "kit-alice");
1058
+ assert.equal(await ownerOf(store, anonymous, "the anonymous row"), null);
1059
+ });
1060
+ faceRun("[transfer] a row another writer creates while a staging is open: the commit is refused conflict and that row stands — and a row of the committer's own that appears is shown to decide", ["logTransfer", "ownership"], async (store) => {
1061
+ const id = freshId();
1062
+ const staging = store.logTransfer.beginReplace(id);
1063
+ await staging.append([userEntry("x1", null)]);
1064
+ await store.register(id, "kit-bob");
1065
+ await rejectsWithConflict(() => staging.commit({ owner: "kit-alice", decide: () => "replace" }), "a commit onto a row another principal created after the staging opened");
1066
+ assert.equal(await ownerOf(store, id, "the other writer's row"), "kit-bob", "the commit took nobody's row");
1067
+ assert.deepEqual(await store.logTransfer.listEntryIds(id), []);
1068
+ const mine = freshId();
1069
+ const staged = store.logTransfer.beginReplace(mine);
1070
+ await staged.append([userEntry("x1", null)]);
1071
+ await store.register(mine, "kit-alice");
1072
+ let seen;
1073
+ await rejectsWithCode(() => staged.commit({ owner: "kit-alice", decide: (v) => { seen = v.current; throw new SessionError("conflict", "the committer expected no row"); } }), "conflict", "a committer refusing a row it did not expect");
1074
+ assert.deepEqual(seen, [], "decide sees the row as it stands now — present, with its (empty) log, not the absence the staging began on");
1075
+ assert.deepEqual(await store.logTransfer.listEntryIds(mine), []);
1076
+ });
1077
+ faceRun("[transfer] a placed row's log is not replaced: the commit is refused placement_refused and the transcript stays", ["logTransfer", "placements"], async (store) => {
1078
+ const id = freshId();
1079
+ await append((await store.acquire(id, { placement: placementFor() })).session, userEntry("p1", null));
1080
+ await rejectsWithCode(() => commitLog(store, id, { owner: null }, [userEntry("x1", null)]), "placement_refused", "a commit onto a placed row");
1081
+ assert.deepEqual(await store.logTransfer.listEntryIds(id), ["p1"]);
1082
+ });
1083
+ faceRun("[transfer] every staged entry passes the import gate: a refused batch ends the staging, a staged log that does not close is refused at the commit, and either way nothing is written", ["logTransfer", "headOf"], async (store) => {
1084
+ const id = freshId();
1085
+ const broken = store.logTransfer.beginReplace(id);
1086
+ await rejectsWithCode(() => broken.append([userEntry("e2", "missing-parent")]), "invalid_session", "a batch whose entry's parent never appears");
1087
+ await rejectsWithCode(() => broken.append([userEntry("e1", null)]), "invalid_session", "a staging after a refused batch");
1088
+ await rejectsWithCode(() => broken.commit({ owner: null, decide: () => "replace" }), "invalid_session", "a commit of a refused staging");
1089
+ const tworoots = store.logTransfer.beginReplace(id);
1090
+ let early;
1091
+ try {
1092
+ await tworoots.append([userEntry("r1", null), userEntry("r2", null)]);
1093
+ }
1094
+ catch (err) {
1095
+ early = err;
1096
+ }
1097
+ if (early !== undefined)
1098
+ assert.equal(readMember(early, "code"), "invalid_session", "a two-root batch refused at append is refused invalid_session");
1099
+ await rejectsWithCode(() => tworoots.commit({ owner: null, decide: () => "replace" }), "invalid_session", "a staged log with two roots");
1100
+ assert.equal(await headOf(store, id), undefined, "no row was created");
1101
+ });
1102
+ faceRun("[transfer] before its commit a staging is invisible; decide reads both sides, and its throw writes nothing; an abort writes nothing and ends the staging; a decide answer outside the two is refused", ["logTransfer", "ownership"], async (store) => {
1103
+ const id = freshId();
1104
+ await store.register(id, "kit-alice");
1105
+ await append((await store.acquire(id)).session, userEntry("old1", null));
1106
+ const staging = store.logTransfer.beginReplace(id);
1107
+ await staging.append([userEntry("n1", null)]);
1108
+ await staging.append([assistantEntry("n2", "n1")]);
1109
+ assert.deepEqual(await store.logTransfer.listEntryIds(id), ["old1"], "nothing staged is read before the commit");
1110
+ assert.deepEqual(await entryIds((await store.acquire(id)).session), ["old1"]);
1111
+ const boom = new Error("the committer's own refusal");
1112
+ let reads = [];
1113
+ const thrown = await thrownBy(() => staging.commit({
1114
+ owner: "kit-alice",
1115
+ decide: async (v) => {
1116
+ assert.deepEqual(v.current, ["old1"]);
1117
+ assert.deepEqual(v.staged, ["n1", "n2"]);
1118
+ const current = await v.read("current", ["old1"]);
1119
+ reads = [...current, ...(await v.read("staged", ["n2", "n1"]))].map((e) => e.id);
1120
+ firstTextBlock(current[0]).text = "written by decide";
1121
+ throw boom;
1122
+ },
1123
+ }), "a commit whose decide throws");
1124
+ assert.equal(thrown, boom, "the commit rejects with decide's own throw");
1125
+ assert.deepEqual(reads, ["old1", "n2", "n1"], "read answers the entries asked for, in the order asked");
1126
+ assert.deepEqual(await store.logTransfer.listEntryIds(id), ["old1"]);
1127
+ const kept = (await (await store.acquire(id)).session.getStorage().getEntries())[0];
1128
+ assert.equal(firstTextBlock(kept).text, "t-old1", "an entry decide read is a copy: writing to it changes no log");
1129
+ await rejectsWithCode(() => staging.commit({ owner: "kit-alice", decide: () => "replace" }), "invalid_session", "a second commit of one staging");
1130
+ const aborted = store.logTransfer.beginReplace(id);
1131
+ await aborted.append([userEntry("n1", null)]);
1132
+ await aborted.abort();
1133
+ await aborted.abort();
1134
+ await rejectsWithCode(() => aborted.commit({ owner: "kit-alice", decide: () => "replace" }), "invalid_session", "a commit after an abort");
1135
+ const odd = store.logTransfer.beginReplace(id);
1136
+ await odd.append([userEntry("n1", null)]);
1137
+ await rejectsWithCode(() => Reflect.apply(odd.commit, odd, [{ owner: "kit-alice", decide: () => "restamp" }]), "config.invalid_argument", "a decide answer outside replace / keep");
1138
+ assert.deepEqual(await store.logTransfer.listEntryIds(id), ["old1"], "nothing was written by any of them");
1139
+ });
1140
+ faceRun("[transfer] decide answering keep leaves the log as it is and answers the row's head; keep for an id with no row is refused and creates nothing", ["logTransfer", "ownership"], async (store) => {
1141
+ const id = freshId();
1142
+ await store.register(id, "kit-alice");
1143
+ await append((await store.acquire(id)).session, userEntry("e1", null));
1144
+ const done = await commitLog(store, id, { owner: "kit-alice", decide: () => "keep" }, [userEntry("e1", null)]);
1145
+ assert.equal(done.outcome, "kept");
1146
+ assert.deepEqual(done.head, await headOf(store, id));
1147
+ assert.equal(done.head.leafId, "e1");
1148
+ const absent = freshId();
1149
+ await rejectsWithCode(() => commitLog(store, absent, { owner: null, decide: () => "keep" }, [userEntry("e1", null)]), "invalid_session", "keep for an id with no row");
1150
+ assert.equal(await headOf(store, absent), undefined);
1151
+ });
1152
+ faceRun("[transfer] a commit through another instance: this instance's cached view of the replaced log is not served again", ["logTransfer", "ownership", "replica"], async (store, open) => {
1153
+ const id = freshId();
1154
+ const other = await open(hooks.replica(store));
1155
+ await store.register(id, "kit-alice");
1156
+ await append((await store.acquire(id)).session, userEntry("old1", null));
1157
+ await commitLog(other, id, { owner: "kit-alice" }, [userEntry("n1", null), assistantEntry("n2", "n1")]);
1158
+ assert.deepEqual(await entryIds((await store.acquire(id)).session), ["n1", "n2"], "the occupant is the same, the log is not — a view of the old log is a view of a log the row no longer holds");
1159
+ });
1160
+ faceRun("[transfer] a write through another instance while decide weighs the destination (an append to it): the commit is refused conflict, nothing written, and that write stands", ["logTransfer", "ownership", "replica"], async (store, open) => {
1161
+ const id = freshId();
1162
+ const other = await open(hooks.replica(store));
1163
+ await store.register(id, "kit-alice");
1164
+ await append((await store.acquire(id)).session, userEntry("e1", null));
1165
+ const staging = store.logTransfer.beginReplace(id);
1166
+ await staging.append([userEntry("n1", null)]);
1167
+ const decide = async () => {
1168
+ await append((await other.acquire(id)).session, assistantEntry("e2", "e1"));
1169
+ return "replace";
1170
+ };
1171
+ await rejectsWithConflict(() => staging.commit({ owner: "kit-alice", decide }), "a commit whose destination another instance wrote while decide weighed it");
1172
+ assert.deepEqual(await store.logTransfer.listEntryIds(id), ["e1", "e2"], "the other instance's write stands, and nothing of the staged log was written");
1173
+ });
1174
+ faceRun("[delete] only the owner's delete deletes: another owner's or an anonymous guard on an owned row, and an owner's guard on an anonymous row, answer false and leave the row; the right guard answers true, the id is gone, a repeat answers false, and a later create is a new occupant", ["delete", "ownership"], async (store) => {
1175
+ const id = freshId();
1176
+ await store.register(id, "kit-alice");
1177
+ await append((await store.acquire(id)).session, userEntry("e1", null));
1178
+ const before = await tokenOf(store, id, "the owned row");
1179
+ assert.equal(await store.delete(id, { owner: "kit-bob" }), false);
1180
+ assert.equal(await store.delete(id, { owner: null }), false, "null is no wildcard: it deletes only an anonymous row");
1181
+ assert.equal(await ownerOf(store, id, "after two refused deletes"), "kit-alice");
1182
+ assert.equal(await store.delete(id, { owner: "kit-alice" }), true);
1183
+ assert.equal(await headOf(store, id), undefined, "a deleted row answers nothing");
1184
+ assert.equal(await store.delete(id, { owner: "kit-alice" }), false, "a repeat is harmless");
1185
+ assert.deepEqual(await entryIds((await store.acquire(id)).session), [], "the deleted log is not served under the id again");
1186
+ assert.notEqual(await tokenOf(store, id, "the id created again"), before, "a later create under the id is a new occupant");
1187
+ const anonymous = freshId();
1188
+ await append((await store.acquire(anonymous)).session, userEntry("z1", null));
1189
+ assert.equal(await store.delete(anonymous, { owner: "kit-alice" }), false);
1190
+ assert.equal(await store.delete(anonymous, { owner: null }), true);
1191
+ assert.equal(await store.delete(freshId(), { owner: null }), false, "no row ⇒ false");
1192
+ });
1193
+ faceRun("[delete] a guard that names no owner is refused before anything is deleted: an absent owner, a blank one, a non-object guard", ["delete", "ownership"], async (store) => {
1194
+ const id = freshId();
1195
+ await store.register(id, "kit-alice");
1196
+ for (const guard of [{}, { owner: undefined }, { owner: "" }, { owner: " " }, { owner: 7 }, null, "kit-alice"]) {
1197
+ await thrownBy(() => Reflect.apply(store.delete, store, [id, guard]), `delete with guard ${JSON.stringify(guard)}`);
1198
+ }
1199
+ assert.equal(await ownerOf(store, id, "after the refused deletes"), "kit-alice");
1200
+ });
1201
+ faceRun("[delete] a placed row is not deleted here: its deletion is release's", ["delete", "placements"], async (store) => {
1202
+ const id = freshId();
1203
+ await append((await store.acquire(id, { placement: placementFor() })).session, userEntry("p1", null));
1204
+ assert.equal(await store.delete(id, { owner: null }), false);
1205
+ assert.ok((await headOf(store, id)) !== undefined, "the placed row stands");
1206
+ });
992
1207
  await settle();
993
1208
  }
1209
+ function firstTextBlock(entry) {
1210
+ const content = entry.type === "message" ? entry.message.content : undefined;
1211
+ const block = Array.isArray(content) ? content[0] : undefined;
1212
+ assert.ok(block !== undefined && typeof block.text === "string", "a kit user entry carries one text block");
1213
+ return block;
1214
+ }
1215
+ async function streamIds(t, sessionId, opts) {
1216
+ const stream = await t.exportStream(sessionId, opts);
1217
+ assert.ok(stream !== null, "the row exists, so exportStream must answer a stream");
1218
+ const ids = [];
1219
+ for await (const e of stream)
1220
+ ids.push(e.id);
1221
+ return ids;
1222
+ }
1223
+ async function commitLog(store, sessionId, commit, entries) {
1224
+ const staging = store.logTransfer.beginReplace(sessionId);
1225
+ await staging.append(entries);
1226
+ return staging.commit({ owner: commit.owner, decide: commit.decide ?? (() => "replace") });
1227
+ }
@@ -278,6 +278,27 @@ export interface ExtensionRequester {
278
278
  readonly kind: "extension";
279
279
  readonly name: string;
280
280
  }
281
+ /**
282
+ * Who replaced the arguments the gate let a tool call go with, one entry per replacement: an extension of this leg by its
283
+ * registration name (its `classic.PreToolUse` answer's `updatedInput`); the leg's restriction chain (`policy` — the bytes came
284
+ * back in the chain's answer, whoever inside it wrote them: the deployment's `ToolPolicy`, a constraint the leg inherited (an
285
+ * ancestor leg's screening among them), an approver a layer consults itself — the layer word a refusal of that chain carries); or
286
+ * the approver of the call's ask, who answered with other arguments (`approver` — whether a person or the host's own approver is
287
+ * the frame's `gate.settlement.who`).
288
+ */
289
+ export type RewriteAuthor = ExtensionRequester | {
290
+ readonly kind: "policy";
291
+ } | {
292
+ readonly kind: "approver";
293
+ };
294
+ /** The arguments the gate let a call go with when they are not the ones it took ({@link RewriteAuthor} names who replaced them). */
295
+ export interface ToolInputRewrite {
296
+ /** One entry per replacement that changed the arguments, in the order they were made (a judge that changed them twice is named twice). */
297
+ readonly by: readonly RewriteAuthor[];
298
+ /** The arguments the gate let the call go with, as the gate's frozen plain-data projection of them (the `finalInput` it records:
299
+ * a member that is not plain data — a bigint, a cycle's closing member — reads as a `[not recorded: …]` marker). */
300
+ readonly input: unknown;
301
+ }
281
302
  /** Streaming events surfaced from a running task (for live UIs). */
282
303
  export type TaskEvent = ({
283
304
  type: "text_delta";
@@ -589,6 +610,19 @@ export type TaskEvent = ({
589
610
  * whose body ran or that no extension answered.
590
611
  */
591
612
  answeredBy?: string;
613
+ /**
614
+ * @contract tool_end.rewrite — the gate let the call go with arguments other than the ones it took: `input` is what it
615
+ * let the call go with, `by` who replaced them. Whether the body then ran is the frame's other members' to say (`isError`
616
+ * with `errorCode`, as for a tool's refusal of those arguments) — this member is never evidence that it did. Present
617
+ * exactly when the gate's allow exit let the call go, the frame carries no {@link notExecuted}, and the arguments it let
618
+ * the call go with differ from those it took at its entry (both as the tool reads them — the loop's argument preparation
619
+ * and schema coercion are no rewrite, so the comparison is never against `tool_start.args`, which stays the model's
620
+ * own). Absent on a call refused before it was let go, on a parked or answered-in-place call, and on one whose arguments
621
+ * were replaced and then set back; a refusal recorded after the call was let go (the shell read admission inside the
622
+ * execution) leaves it beside the `denied` record — the call was let go with them. On the frame only: the persisted
623
+ * `toolResult` row does not repeat it. A resumed leg's frames do not carry it.
624
+ */
625
+ rewrite?: ToolInputRewrite;
592
626
  /** The same member as the paired `tool_start`'s: an extension's own call, and who asked for it. */
593
627
  requestedBy?: ExtensionRequester;
594
628
  /**
@@ -968,6 +1002,10 @@ export type TaskEvent = ({
968
1002
  * the engine read for it and will send (`outcome`) — an admission result, not a delivery. Each attachment is
969
1003
  * delivered as its own message after the objective; its `message_committed` is the delivery. */
970
1004
  attachments?: readonly HumanInputAttachment[];
1005
+ /** What brought THIS input, when its host said so on its carrier (`"scheduled"`: the deployment's scheduler handed it —
1006
+ * render it as the scheduler's, not as someone typing): the objective's `TaskSpec.runOrigin`, a parked or waking
1007
+ * message's `runOrigin`. Absent ⇒ the host said nothing (never "a person sent it"). Attribution only. */
1008
+ runOrigin?: import("./run-origin.js").RunOrigin;
971
1009
  } & TaskEventIdentity) | ({
972
1010
  /**
973
1011
  * design/99 §E3/§E10 — a live BRAIN-LAYER status the brain would otherwise absorb
@@ -1171,17 +1209,39 @@ export type TaskEvent = ({
1171
1209
  status: "running" | "completed" | "failed";
1172
1210
  } & TaskEventIdentity) | ({
1173
1211
  /**
1174
- * design/99 §E13 — the task's tracked working directory CHANGED mid-run (a `bash`
1175
- * `cd` moved it). Emitted live after the tool that moved it, carrying the new logical cwd, so a shell UI
1176
- * can update its prompt/path display. The tracked cwd is the RAW logical path (a `cd` through a symlink
1177
- * reports the raw path navigated, not the resolved target). Only fires when a real shell is mounted
1178
- * (absent under `handsReadOnly` / no-exec). The initial cwd is NOT announced (it is the known root); only
1179
- * subsequent changes are. A live observability signal — not persisted, and the tracked cwd RESETS to the
1180
- * root across a suspend/resume (the per-leg execution cwd is not durable today — a pre-existing limitation
1181
- * tracked with the E18/E19 execution-state durability work); within a leg, every `cd` move is reported.
1212
+ * WHERE THIS LEG STANDS, one WHOLE snapshot (minted only by `workspaceSnapshotOf`). EVERY prepared
1213
+ * leg — fresh, resumed, continued, child; a read-only leg and a leg with no shell included — sends ONE leg-start frame
1214
+ * after `wiring_manifest` and the leg-start `tool_disclosure` census (when the leg has one), before its first model or
1215
+ * tool interaction, then one more each time the snapshot CHANGES (a `bash` `cd`, EnterWorktree /
1216
+ * ExitWorktree; observed after the tool that moved it, a resumed leg's approved call included). A frame equal to the
1217
+ * last one this leg sent is never sent. Replace your copy with each frame (last frame wins): the leg-start frame is
1218
+ * a snapshot, not a report that something moved — a consumer already holding the same values renders nothing for it.
1219
+ * A host keeping a session row keeps the LAST frame; nothing else needs re-deriving (the next leg re-sends its own).
1182
1220
  */
1183
1221
  type: "workspace_changed";
1222
+ /** The tracked logical cwd — the RAW path the shell navigated (a `cd` through a symlink reports the path walked,
1223
+ * not its target). A resumed or continuing leg starts where it restored to; a leg with no shell reports `root`. */
1184
1224
  cwd: string;
1225
+ /** This leg's task root as the leg's root receiving point settled it — the spelling its file fences and path rules are
1226
+ * anchored at, and where `cwd` starts. */
1227
+ root: string;
1228
+ /** The model's EnterWorktree switch active on this leg (`byPath`: entered via `path`, not created by this session);
1229
+ * ABSENT = no switch is active on this leg. */
1230
+ entered?: {
1231
+ dir: string;
1232
+ byPath?: true;
1233
+ };
1234
+ /** This leg's project identity, decided ONCE at leg start and fixed for the leg: `marker` = the checkout's
1235
+ * `.sema/project` (a `TaskSpec.projectId`, when given, equals it); `declared` = `TaskSpec.projectId` in a checkout
1236
+ * that carries no marker. ABSENT = no marker and no declaration, or the marker could not be read (the deployment's
1237
+ * `onError` was told which file and why). */
1238
+ project?: {
1239
+ id: string;
1240
+ source: "marker" | "declared";
1241
+ };
1242
+ /** True ⇔ the paths name locations inside a remote / non-host execution env, not host paths (the reading
1243
+ * `ResolvedWorkspace.remote` carries). */
1244
+ remote: boolean;
1185
1245
  } & TaskEventIdentity) | ({
1186
1246
  /**
1187
1247
  * design/173 §2.4/§8.1 — this leg's EFFECTIVE wiring manifest: the machine-readable
@@ -443,19 +443,23 @@ export declare function deliverToRunningAgentLane(core: DurableAgentCore, id: st
443
443
  * counterpart rows here). This variant is the SENDMESSAGE footer's source and lists EVERY running
444
444
  * agent, named or not: SendMessage addresses by name AND by id, so dropping named rows here (the way
445
445
  * {@link runningAgentFooterLane} does for the task faces, per CC `rxo`'s `!n.has(i.id)`) would hide the
446
- * very rows a retry needs. The task faces' split lives in `runningAgentFooterLane` (RB-332). */
446
+ * very rows a retry needs. The label is the name someone chose, else the description: the name an agent
447
+ * carries only because it must carry one ({@link chosenAgentName}) says nothing about what it does.
448
+ * The task faces' split lives in `runningAgentFooterLane` (RB-332). */
447
449
  export declare function runningBackgroundAgentLabelsLane(core: DurableAgentCore, access: TaskAccess): string[];
448
450
  /**
449
451
  * The not-found FOOTER's two rows, split the way the reference assembles them:
450
452
  * - `named` = CC `uG_` (220:467941-467953): the agentNameRegistry's KEYS whose task is a running local
451
453
  * agent, listed as BARE NAMES — the string a retry should pass verbatim. sema's counterpart
452
- * of "has a registry entry" is the handle carrying an explicit `name` (spawn-time label),
453
- * the same field TaskStop's name leg and SendMessage address by.
454
+ * of "has a registry entry" is the handle carrying a CHOSEN name (the spawn-time label; the
455
+ * name an agent carries only because every agent has one is not a registry entry —
456
+ * {@link chosenAgentName}).
454
457
  * - `background` = CC `rxo` (220:467937-467951): the remaining running background agents as `id (label)`
455
458
  * rows. CC filters `!n.has(i.id)` — a NAMED agent is deliberately NOT repeated here, because
456
459
  * its addressable form is the name, not the id. The pre-RB-332 sema code merged both legs
457
460
  * into one list and justified it with "named has no counterpart", a claim [c209-D] retired
458
- * when the explicit `name` field landed.
461
+ * when the explicit `name` field landed. The id stays in these rows because TaskOutput
462
+ * resolves exact ids only: an agent nobody named is the one a retry can reach by its id alone.
459
463
  * CC's `YEd` "Running teammates:" leg has no sema counterpart (no teammate registry on this face) and is
460
464
  * honestly absent rather than faked.
461
465
  */