@sema-agent/core 7.57.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 (198) hide show
  1. package/CHANGELOG.md +385 -0
  2. package/dist/agents/subagent-steps.js +2 -4
  3. package/dist/brain/route-adjudicator.js +2 -1
  4. package/dist/core/a2a.d.ts +2 -1
  5. package/dist/core/a2a.js +23 -10
  6. package/dist/core/allow-entry.d.ts +2 -1
  7. package/dist/core/allow-entry.js +2 -1
  8. package/dist/core/ask-origin.d.ts +21 -2
  9. package/dist/core/ask-origin.js +5 -1
  10. package/dist/core/auto-compaction.d.ts +4 -0
  11. package/dist/core/auto-compaction.js +1 -1
  12. package/dist/core/auto-mode-directive.d.ts +29 -5
  13. package/dist/core/auto-mode-directive.js +38 -8
  14. package/dist/core/checkpoint-requirements.d.ts +7 -1
  15. package/dist/core/checkpoint-requirements.js +2 -0
  16. package/dist/core/checkpoint-store.d.ts +27 -11
  17. package/dist/core/checkpoint-store.js +13 -3
  18. package/dist/core/engine-notice.d.ts +1 -1
  19. package/dist/core/fs-write-gate-policy.d.ts +4 -2
  20. package/dist/core/fs-write-gate-policy.js +7 -3
  21. package/dist/core/gate-fold.js +6 -3
  22. package/dist/core/gate-lanes.js +11 -2
  23. package/dist/core/git-worktree-env.d.ts +53 -11
  24. package/dist/core/git-worktree-env.js +96 -12
  25. package/dist/core/hooks.d.ts +4 -1
  26. package/dist/core/hooks.js +12 -5
  27. package/dist/core/human-input-projection.d.ts +1 -0
  28. package/dist/core/human-input-projection.js +3 -0
  29. package/dist/core/locked-config.d.ts +15 -1
  30. package/dist/core/locked-config.js +38 -2
  31. package/dist/core/mcp-call-meta.d.ts +66 -0
  32. package/dist/core/mcp-call-meta.js +103 -0
  33. package/dist/core/mcp-connection-pool.d.ts +3 -1
  34. package/dist/core/mcp-connection-pool.js +3 -1
  35. package/dist/core/mcp-failure.d.ts +7 -1
  36. package/dist/core/mcp-failure.js +10 -0
  37. package/dist/core/mcp-probe.d.ts +4 -0
  38. package/dist/core/mcp-probe.js +1 -1
  39. package/dist/core/mcp-server-link.d.ts +5 -2
  40. package/dist/core/mcp-server-spec.d.ts +46 -18
  41. package/dist/core/mcp-server-spec.js +1 -18
  42. package/dist/core/mcp.d.ts +6 -14
  43. package/dist/core/mcp.js +77 -37
  44. package/dist/core/memory-engine/scope-contract.d.ts +45 -4
  45. package/dist/core/memory-engine/scope-contract.js +80 -11
  46. package/dist/core/mode-policy.d.ts +8 -5
  47. package/dist/core/mode-policy.js +5 -4
  48. package/dist/core/mods/host.js +1 -1
  49. package/dist/core/mods/kernel/dispatch.d.ts +3 -0
  50. package/dist/core/mods/kernel/dispatch.js +10 -8
  51. package/dist/core/mods/kernel/events.d.ts +5 -1
  52. package/dist/core/mods/kernel/events.js +1 -1
  53. package/dist/core/mods/kernel/registration.d.ts +5 -1
  54. package/dist/core/mods/kernel/site-rules.d.ts +3 -0
  55. package/dist/core/mods/kernel/site-rules.js +10 -0
  56. package/dist/core/mods/package.d.ts +23 -0
  57. package/dist/core/mods/package.js +118 -0
  58. package/dist/core/mods/stations.d.ts +2 -2
  59. package/dist/core/mods/stations.js +1 -1
  60. package/dist/core/mods/tool-call.d.ts +5 -1
  61. package/dist/core/mods/tool-call.js +12 -3
  62. package/dist/core/path-guard-rows.d.ts +20 -0
  63. package/dist/core/path-guard-rows.js +11 -0
  64. package/dist/core/peer-seat.d.ts +186 -0
  65. package/dist/core/peer-seat.js +307 -0
  66. package/dist/core/present-plan-tool.d.ts +10 -1
  67. package/dist/core/present-plan-tool.js +46 -2
  68. package/dist/core/protocol-http-auth.d.ts +40 -29
  69. package/dist/core/protocol-http-auth.js +30 -32
  70. package/dist/core/redaction-marks.d.ts +16 -0
  71. package/dist/core/redaction-marks.js +16 -0
  72. package/dist/core/redaction-passes.js +8 -9
  73. package/dist/core/retention.d.ts +41 -15
  74. package/dist/core/retention.js +59 -12
  75. package/dist/core/rewrite-rejudge.d.ts +37 -0
  76. package/dist/core/rewrite-rejudge.js +40 -0
  77. package/dist/core/run-origin.d.ts +40 -0
  78. package/dist/core/run-origin.js +37 -0
  79. package/dist/core/runner/advertised-writable-dirs.d.ts +57 -38
  80. package/dist/core/runner/advertised-writable-dirs.js +126 -0
  81. package/dist/core/runner/compaction-restate.d.ts +15 -6
  82. package/dist/core/runner/compaction-restate.js +28 -2
  83. package/dist/core/runner/contracts.d.ts +13 -5
  84. package/dist/core/runner/gate-exit.d.ts +18 -4
  85. package/dist/core/runner/gate-exit.js +5 -1
  86. package/dist/core/runner/prepare-caps-and-workflow.d.ts +2 -0
  87. package/dist/core/runner/prepare-caps-and-workflow.js +1 -1
  88. package/dist/core/runner/prepare-config-doors.d.ts +8 -5
  89. package/dist/core/runner/prepare-config-doors.js +12 -10
  90. package/dist/core/runner/prepare-delegation-surface.d.ts +4 -0
  91. package/dist/core/runner/prepare-delegation-surface.js +15 -18
  92. package/dist/core/runner/prepare-gate-stations.js +1 -1
  93. package/dist/core/runner/prepare-hands-readface.d.ts +7 -3
  94. package/dist/core/runner/prepare-hands-readface.js +4 -1
  95. package/dist/core/runner/prepare-memory.d.ts +3 -0
  96. package/dist/core/runner/prepare-memory.js +19 -23
  97. package/dist/core/runner/prepare-policy-chain.d.ts +4 -4
  98. package/dist/core/runner/prepare-policy-chain.js +2 -2
  99. package/dist/core/runner/prepare-protocol-tools.d.ts +4 -2
  100. package/dist/core/runner/prepare-protocol-tools.js +3 -3
  101. package/dist/core/runner/prepare-suspend-saga.d.ts +2 -0
  102. package/dist/core/runner/prepare-suspend-saga.js +2 -1
  103. package/dist/core/runner/prepare-task.js +25 -12
  104. package/dist/core/runner/prepare-wiring-manifest.d.ts +1 -0
  105. package/dist/core/runner/prepare-wiring-manifest.js +2 -2
  106. package/dist/core/runner/prepare-workspace-restore.d.ts +3 -0
  107. package/dist/core/runner/prepare-workspace-restore.js +4 -4
  108. package/dist/core/runner/resume-admission.js +1 -1
  109. package/dist/core/runner/resume-checkpoint-screen.js +2 -0
  110. package/dist/core/runner/run-harness-handlers.d.ts +3 -4
  111. package/dist/core/runner/run-harness-handlers.js +1 -8
  112. package/dist/core/runner/run-identity-wiring.js +1 -0
  113. package/dist/core/runner/run-leg.js +5 -1
  114. package/dist/core/runner/run-notification-lane.js +3 -0
  115. package/dist/core/runner/terminal-account.js +3 -3
  116. package/dist/core/runner/tool-end-body.js +1 -0
  117. package/dist/core/runner/tool-occurrence.d.ts +4 -1
  118. package/dist/core/runner/tool-occurrence.js +2 -1
  119. package/dist/core/runner/write-protection-station.d.ts +8 -2
  120. package/dist/core/runner/write-protection-station.js +2 -0
  121. package/dist/core/runner-deps.d.ts +2 -2
  122. package/dist/core/sensitive-path-policy.js +6 -7
  123. package/dist/core/session-log-transfer.d.ts +24 -0
  124. package/dist/core/session-log-transfer.js +166 -0
  125. package/dist/core/session-store.d.ts +84 -19
  126. package/dist/core/session-store.js +162 -24
  127. package/dist/core/session.d.ts +92 -1
  128. package/dist/core/shell-read-silence.js +1 -0
  129. package/dist/core/steer-replay.d.ts +4 -2
  130. package/dist/core/steer-replay.js +2 -1
  131. package/dist/core/store-contracts/checkpoint-store-contract.js +17 -0
  132. package/dist/core/store-contracts/session-repo-contract.js +112 -5
  133. package/dist/core/store-contracts/session-store-contract.d.ts +4 -1
  134. package/dist/core/store-contracts/session-store-contract.js +236 -2
  135. package/dist/core/task-event.d.ts +68 -8
  136. package/dist/core/task-registry-shared.d.ts +2 -1
  137. package/dist/core/task-spec.d.ts +37 -0
  138. package/dist/core/task-stream.d.ts +2 -1
  139. package/dist/core/terminal-cause.d.ts +1 -1
  140. package/dist/core/tool-catalog-entries.js +1 -0
  141. package/dist/core/tool-result-store.d.ts +17 -10
  142. package/dist/core/tool-result-store.js +3 -1
  143. package/dist/core/types.d.ts +1 -1
  144. package/dist/core/untrusted-egress.d.ts +0 -2
  145. package/dist/core/untrusted-egress.js +10 -14
  146. package/dist/core/wiring-manifest.d.ts +12 -3
  147. package/dist/core/wiring-manifest.js +4 -3
  148. package/dist/core/workspace-snapshot.d.ts +44 -0
  149. package/dist/core/workspace-snapshot.js +34 -0
  150. package/dist/core/write-protect.d.ts +43 -3
  151. package/dist/core/write-protect.js +43 -16
  152. package/dist/engine/execution-env/node-execution-env.js +15 -11
  153. package/dist/engine/execution-env/symlink-chain.d.ts +7 -5
  154. package/dist/engine/harness/agent-harness.d.ts +5 -0
  155. package/dist/engine/harness/agent-harness.js +2 -0
  156. package/dist/engine/harness/types.d.ts +48 -7
  157. package/dist/engine/harness/types.js +5 -1
  158. package/dist/engine/llm/types.d.ts +12 -3
  159. package/dist/engine/llm/types.js +1 -1
  160. package/dist/engine/session/import-validate.js +3 -0
  161. package/dist/engine/session/memory-repo.d.ts +17 -9
  162. package/dist/engine/session/memory-repo.js +44 -34
  163. package/dist/engine/session/repo-utils.d.ts +22 -4
  164. package/dist/engine/session/repo-utils.js +49 -1
  165. package/dist/engine/session/storage-base.d.ts +10 -1
  166. package/dist/engine/session/storage-base.js +7 -1
  167. package/dist/index.d.ts +13 -6
  168. package/dist/index.js +10 -4
  169. package/dist/internal/harness-types.d.ts +1 -1
  170. package/dist/internal/harness.d.ts +2 -2
  171. package/dist/internal/harness.js +2 -2
  172. package/dist/stores/file/index.d.ts +4 -1
  173. package/dist/stores/file/index.js +4 -1
  174. package/dist/stores/file/session-store.d.ts +15 -8
  175. package/dist/stores/file/session-store.js +28 -13
  176. package/dist/tools/fs/fs-write.d.ts +6 -3
  177. package/dist/tools/fs/fs-write.js +8 -7
  178. package/dist/tools/fs/index.d.ts +3 -0
  179. package/dist/tools/fs/index.js +1 -1
  180. package/dist/tools/fs/safety.js +40 -8
  181. package/dist/tools/fs/search.js +6 -24
  182. package/dist/tools/fs/shell-read-check.d.ts +8 -1
  183. package/dist/tools/fs/shell-read-check.js +59 -15
  184. package/dist/tools/fs/shell-read-establish.js +2 -1
  185. package/dist/tools/fs/shell-read-identity.js +1 -1
  186. package/dist/tools/fs/shell-read-judge.d.ts +10 -1
  187. package/dist/tools/worktree.d.ts +42 -15
  188. package/dist/tools/worktree.js +60 -32
  189. package/package.json +4 -2
  190. package/test/export-surface.snapshot.json +63 -1
  191. package/wire-changes/core-stores-sql@7.58.0.json +29 -0
  192. package/wire-changes/core@7.58.0.json +2188 -0
  193. package/wire-changes/mods-kernel@7.58.0.json +81 -0
  194. package/wire-changes/primitives@7.58.0.json +29 -0
  195. package/dist/primitives/credential-ref.d.ts +0 -89
  196. package/dist/primitives/credential-ref.js +0 -125
  197. package/dist/primitives/index.d.ts +0 -2
  198. package/dist/primitives/index.js +0 -1
@@ -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
@@ -860,7 +860,8 @@ export declare function engineAgentName(handle: string): string;
860
860
  * also a spawn identity (the teammate key, `spawnName` on frames, a roster entry, the unnamed-child tool pool),
861
861
  * and a reader that hands a row's name back into a place that reads it as an identity — a revival's `name`
862
862
  * argument, a retained resume's row name — goes through here, so an agent nobody named stays unnamed in every
863
- * later cycle. A reader that only needs to ADDRESS the agent reads `name` as it is.
863
+ * later cycle. A reader that only needs to ADDRESS the agent reads `name` as it is. A serving layer's roster reads
864
+ * "chosen vs derived" back through here from the row's handle + name — it keeps no column of its own for it.
864
865
  */
865
866
  export declare function chosenAgentName(handle: string, name: string | undefined): string | undefined;
866
867
  /** Synthetic settle error the subagent reap path passes after a stop/parent teardown. It is NOT a
@@ -111,6 +111,22 @@ export interface TaskSpec {
111
111
  * honest one, because `hostAsserted` states whether the identity was ingress-derived.
112
112
  */
113
113
  actor?: ActorAssertion;
114
+ /**
115
+ * What started this task, when the host says so ({@link import("./run-origin.js").RunOrigin}): `"scheduled"` = the
116
+ * deployment's scheduler (cron, heartbeat, delayed wake-up, stored routine) fired an intent stored earlier — nobody submitted
117
+ * it just now. Absent = the host said nothing (never read as "a person sent it"). Attribution only, exactly like
118
+ * {@link actor}: no permission, approval, mode or scope decision reads it, and it never enters the model's context.
119
+ *
120
+ * It is the word of the objective, the input that opens the task's first leg: that leg's `wiring_manifest` reports it
121
+ * (`leg.runOrigin`), the objective's `human_input` frame and its message carry it, and a checkpoint the leg parks records it
122
+ * (`CheckpointSummary.runOrigin`). A resumed leg continues the row's word unless a wake opens it (with the newest input the
123
+ * wake hands over, which states its own); a resume config carries NO word — any value is refused, before the claim. A
124
+ * delegated child does not inherit it. A value outside the set is refused at the door (`config.run_origin_invalid`).
125
+ *
126
+ * 🔴 Trust contract: set it ONLY at the deployment's own scheduler fire path — never copy it from a request body, or any
127
+ * caller can mark its run as scheduled and the audit face reads the claim as the host's. The engine cannot verify it.
128
+ */
129
+ runOrigin?: import("./run-origin.js").RunOrigin;
114
130
  /**
115
131
  * design/173 §3/§8.3 — the caller's DECLARED interaction posture for this run. `"interactive"`
116
132
  * asserts a live human is reachable and makes prepare REFUSE the leg (fail-loud
@@ -178,6 +194,14 @@ export interface TaskSpec {
178
194
  userAttachments?: readonly UserAttachment[];
179
195
  /** Reuse an existing in-memory session for chat continuity; omit to start fresh. */
180
196
  sessionId?: string;
197
+ /**
198
+ * The project the host files this session under — a project UUID (the id a `.sema/project` marker carries; send it on
199
+ * every leg). The engine has ONE judge of a leg's project identity: when the leg's checkout carries a marker, the marker
200
+ * decides and this value must EQUAL it (else the leg is refused, `config.project_identity_mismatch`); in a checkout with
201
+ * no marker this value IS the identity. Not a UUID ⇒ `config.project_id_invalid`. The verdict rides
202
+ * `workspace_changed.project`; read it there rather than re-deriving it. Memory keys only by the marker.
203
+ */
204
+ projectId?: string;
181
205
  /**
182
206
  * design/114 Phase3 — with `sessionId` set, REQUIRE that session to already exist: if it is gone (e.g. a
183
207
  * non-durable store lost it across a restart, or a typo'd id), the run FAILS LOUD (`resume.session_not_found`)
@@ -972,6 +996,19 @@ export interface TaskSpec {
972
996
  * `requestReview` is a no-op). The tool is a thin composition over the general `requestReview` primitive.
973
997
  */
974
998
  enablePlanMode?: boolean;
999
+ /**
1000
+ * The absolute path of THIS session's plan file in the leg's execution environment (the reference's `<plans dir>/<slug>.md`).
1001
+ * Where the plan lives is one fact: declared, the plan is that file — admitted by the advertised-writable seat (its third
1002
+ * advertiser), so the file tools' root fence (write + read) and every mode's write gate admit it without a question, the
1003
+ * write-protection table does not demote it, `ExitPlanMode` takes no `plan` and reads it, and the planning frames name it;
1004
+ * absent, the plan is `ExitPlanMode`'s `plan` argument and no plan file exists (byte-identical to a run before this seat).
1005
+ * The fence and write gates admit the path and anything beneath it until #2746 (KL-1503-a); the table exempts exactly the
1006
+ * file; siblings, a link swapped in later and every deny row stay as they were. The host creates the file's directory
1007
+ * before the run. Refused with `config.plan_file_invalid` (the run never starts): not an absolute string in lexical normal
1008
+ * form that the model can be told verbatim; a link, directory or other non-file leaf; a parent that is not a directory;
1009
+ * hands absent or read-only; a key holding a fence root. Not inherited by a delegated child, a fork or a workflow step.
1010
+ */
1011
+ planFile?: string;
975
1012
  /**
976
1013
  * Interactive-tool mounting override (AskUserQuestion / ExitPlanMode /
977
1014
  * EnterPlanMode share one `isEnabled` gate — in non-interactive mode without an SDK permission-prompt
@@ -53,7 +53,8 @@ export interface TaskStream extends AsyncIterable<TaskEvent> {
53
53
  * evidence of a replay, and two callers colliding on one id must not silently lose the second
54
54
  * (the parked leg's `appendPendingSteer` judges and refuses it identically). The error carries
55
55
  * `detail.differs` — the facets that differ (closed `STEER_REPLAY_FACETS`: `text`, `trusted`,
56
- * `priority`, `actor`), compared on what the caller SENT, never on the framed bytes. With `text`
56
+ * `priority`, `actor`, `runOrigin` — this verb takes no run origin, so a repeat here never differs in it),
57
+ * compared on what the caller SENT, never on the framed bytes. With `text`
57
58
  * among them it is another instruction: re-issue it under a fresh id. Without, it is the accepted one
58
59
  * re-sent at another tier / trust / attribution, which acceptance does not change: a fresh id would
59
60
  * queue it twice, so replay it with its original values to confirm the receipt.
@@ -210,7 +210,7 @@ export type TerminalFailureDetail = {
210
210
  * The thrown error's own `detail`, as its throw site stated it — a snapshot of its JSON-plain members (strings,
211
211
  * finite numbers, booleans, null, and arrays / plain objects of those, bounded; a member of any other kind is left
212
212
  * out; bytes — an `ArrayBuffer` view, an index-keyed object — are never a record). A member under a credential
213
- * name (the env-credential judge's names: `password`, `apiKey`, `token` …) stands as `"[redacted]"`, unread; every
213
+ * name (the env-credential judge's names: `password`, `apiKey`, `token` …) stands as the redaction mark (`REDACTION_MARK`), unread; every
214
214
  * other string leaf passes the secret-tier redaction (credential shapes masked; a path is kept — it rides this
215
215
  * structured seat, never `message`); a member whose key is not JSON-safe (visible ASCII 1–128, nothing the
216
216
  * redaction would mask) is left out. Read off the same link of the error's `cause` chain whose `code` became
@@ -139,6 +139,7 @@ export const TOOL_CATALOG_ENTRIES = [
139
139
  { id: "advisor", name: "advisor", source: "builtin", definedIn: "src/core/runner/advisor-tool.ts", mountedBy: ["optional"], cards: ["advisor"], face: { family: "scaffold", boundaryLegs: [], effect: "read", contentOrigin: "local", contract: c("core.advisor@1"), offload: false, budgetExempt: true, ruleFace: { params: [] } } },
140
140
  { id: "ask-user-question", name: "AskUserQuestion", source: "builtin", definedIn: "src/core/ask-question.ts", mountedBy: ["optional"], cards: ["ask-question"], face: { family: "other", boundaryLegs: [], effect: "read", contract: c("core.ask_user_question@1"), renderHints: { approvalCard: "question" }, ruleFace: { params: [] } } },
141
141
  { id: "exit-plan-mode", name: "ExitPlanMode", source: "builtin", definedIn: "src/core/present-plan-tool.ts", mountedBy: ["optional"], cards: ["exit-plan-mode"], face: { family: "plan", boundaryLegs: [], effect: "read", contract: c("core.exit_plan_mode@1"), renderHints: { userFacingName: "", approvalCard: "plan" }, ruleFace: { params: ["plan"] } } },
142
+ { id: "exit-plan-mode-file", name: "ExitPlanMode", source: "builtin", definedIn: "src/core/present-plan-tool.ts", mountedBy: ["optional"], cards: ["exit-plan-mode"], face: { family: "plan", boundaryLegs: [], effect: "read", contract: c("core.exit_plan_mode_file@1"), renderHints: { userFacingName: "", approvalCard: "plan" }, ruleFace: { params: [] } } },
142
143
  { id: "enter-plan-mode", name: "EnterPlanMode", source: "builtin", definedIn: "src/core/present-plan-tool.ts", mountedBy: ["optional"], cards: ["enter-plan-mode"], face: { family: "plan", boundaryLegs: [], effect: "read", contract: c("core.enter_plan_mode@1"), ruleFace: { params: [] } } },
143
144
  { id: "refresh-mcp-tools", name: REFRESH_MCP_TOOLS_TOOL_NAME, source: "builtin", definedIn: "src/core/runner/prepare-protocol-tools.ts", mountedBy: ["optional"], cards: [], face: { family: "protocol", boundaryLegs: ["outside_read"], effect: "read", ruleFace: { params: ["server"] } } },
144
145
  { id: "memory-search", name: "memory_search", source: "builtin", definedIn: "src/core/memory-engine/tools.ts", mountedBy: ["memory"], cards: [], face: { family: "memory", boundaryLegs: [], effect: "read", contentOrigin: "local", contract: c("core.memory_search@1", "7"), offload: false, ruleFace: { params: ["query", "limit", "includeSuperseded", "includeShadowed"] } } },
@@ -1,4 +1,5 @@
1
1
  import type { AgentTool } from "../internal/harness-types.js";
2
+ import { type RetentionDeclaration } from "./retention.js";
2
3
  /**
3
4
  * Pluggable backing store for **offloaded large tool results** (design/30). When a tool returns more
4
5
  * text than the threshold, the full content is moved here and the conversation keeps only a preview +
@@ -12,13 +13,14 @@ import type { AgentTool } from "../internal/harness-types.js";
12
13
  */
13
14
  export interface ToolResultStore {
14
15
  /**
15
- * Managed-retention declaration (ruled 2026-08-05, retention.ts): `"managed"` promises the
16
- * `ManagedRetentionCapability` contract (scheduled, tenant-scoped, audited deletion); `"none"` (or
17
- * ABSENT — read fail-closed as `"none"`) states the store cannot delete on schedule. A deployment
18
- * with a LOCKED retention policy refuses to start over a `"none"` store. Declaration, never
19
- * duck-typing.
16
+ * Managed-retention declaration (retention.ts): `"managed"` says this store's rows are deleted on
17
+ * schedule by the deployment (a `ManagedRetentionCapability` executor — scheduled, tenant-scoped,
18
+ * audited deletion — runs over them); `"none"` (or ABSENT — read fail-closed as `"none"`) says
19
+ * nothing deletes them on schedule. The party that runs the sweep states it when it constructs the
20
+ * store. A deployment with a LOCKED retention policy refuses to start over a `"none"` store.
21
+ * Declaration, never duck-typing.
20
22
  */
21
- readonly retention?: import("./retention.js").RetentionDeclaration;
23
+ readonly retention?: RetentionDeclaration;
22
24
  /**
23
25
  * Persist full content under a stable `ref`. **Write-once and idempotent**: if `ref` already exists,
24
26
  * keep the existing content and do nothing (the aggregate budget re-runs every query with the same
@@ -110,8 +112,9 @@ export interface ToolResultStore {
110
112
  * callback (a checkable fact, not a failure). Present ⇒ the store can complete a session
111
113
  * deletion; absent ⇒ the deployment owns that gap.
112
114
  *
113
- * Implementing it does NOT make a store `retention: "managed"` — that declaration promises the whole
114
- * {@link import("./retention.js").ManagedRetentionCapability} (domain enumeration, tombstones,
115
+ * Implementing it does NOT make a store `retention: "managed"` — that declaration says the
116
+ * deployment deletes this store's rows on schedule through a whole
117
+ * {@link import("./retention.js").ManagedRetentionCapability} executor (domain enumeration, tombstones,
115
118
  * audit receipts, scheduled execution), of which this is one caller-driven erase.
116
119
  */
117
120
  deleteBySession?(sessionId: string): Promise<ToolResultDeletionReport> | ToolResultDeletionReport;
@@ -318,14 +321,18 @@ export interface ToolResultSlice {
318
321
  * store (e.g. FileToolResultStore) via `RunnerDeps.toolResultStore`. */
319
322
  export declare class InMemoryToolResultStore implements ToolResultStore {
320
323
  private readonly opts?;
321
- /** put/get only — no scheduled deletion contract: honestly `"none"` (retention.ts). */
322
- readonly retention: "none";
324
+ /** Managed-retention declaration (retention.ts): whether this store's rows are deleted on schedule by the deployment — given by
325
+ * the party that runs the sweep (the `retention` option), `"none"` when none is given; the store itself is put/get only. */
326
+ readonly retention: RetentionDeclaration;
323
327
  /** The entry is content AND owner as ONE value — the write-once election that decides the
324
328
  * content decides the owner in the same step (no window where an entry exists ownerless). */
325
329
  private readonly map;
326
330
  private totalChars;
331
+ /** @param opts.retention the store's managed-retention declaration, default `"none"`; a word other than the two is refused
332
+ * (`config.retention_capability`). */
327
333
  constructor(opts?: {
328
334
  maxTotalChars?: number;
335
+ retention?: RetentionDeclaration;
329
336
  } | undefined);
330
337
  put(ref: string, content: string, provenance?: ToolResultProvenance): void;
331
338
  /** The owner recorded at the winning write; `undefined` for unknown AND for unowned entries,
@@ -6,6 +6,7 @@ import { deliverEngineNotice } from "./types.js";
6
6
  import { TOOL_SEARCH_NAME } from "./runner/tool-disclosure.js";
7
7
  import { mountRuleFace, toolFace } from "./tool-catalog-entries.js";
8
8
  import { thrownText } from "./thrown-value.js";
9
+ import { readRetentionDeclaration } from "./retention.js";
9
10
  import { carryNotStartedReceipt } from "./delegation-not-started.js";
10
11
  export const TOOL_RESULT_REF_CONFLICT_CODE = "tool_result.ref_conflict";
11
12
  export class ToolResultRefConflictError extends Error {
@@ -67,11 +68,12 @@ function digestOfString(s) {
67
68
  }
68
69
  export class InMemoryToolResultStore {
69
70
  opts;
70
- retention = "none";
71
+ retention;
71
72
  map = new Map();
72
73
  totalChars = 0;
73
74
  constructor(opts) {
74
75
  this.opts = opts;
76
+ this.retention = readRetentionDeclaration("InMemoryToolResultStore.retention", opts?.retention);
75
77
  const cap = opts?.maxTotalChars;
76
78
  if (cap !== undefined && Number.isNaN(cap)) {
77
79
  throw new Error("InMemoryToolResultStore: maxTotalChars must be a number (got NaN) — omit it for an unbounded store");
@@ -23,7 +23,7 @@ export { DECLARATION_PATH_RULES, NO_DECLARATION_PATH_RULES, dataKind, declaratio
23
23
  export type { TaskLimits } from "./task-limits.js";
24
24
  export type { TaskStatus, RemoteEnvFailureNote, EffectiveMemoryScopes, TaskResult, HumanReviewGateRow } from "./task-result.js";
25
25
  export type { TerminalCause, PausedCause } from "./terminal-cause.js";
26
- export type { TaskEventIdentity, BrainStatusPhase, BrainRetryErrClass, BrainStatus, ToolActivity, HumanInputSource, HumanInputDelivery, DelegationTaskType, TaskEvent, HumanInputEvent, HumanInputAttachment, CompactOutcome, ExtensionRequester } from "./task-event.js";
26
+ export type { TaskEventIdentity, BrainStatusPhase, BrainRetryErrClass, BrainStatus, ToolActivity, HumanInputSource, HumanInputDelivery, DelegationTaskType, TaskEvent, HumanInputEvent, HumanInputAttachment, CompactOutcome, ExtensionRequester, RewriteAuthor, ToolInputRewrite } from "./task-event.js";
27
27
  export type { TaskStream } from "./task-stream.js";
28
28
  export type { WorkflowGovernanceBaseline, RuntimeCaps, AutoModeDenySource } from "./runtime-caps.js";
29
29
  export { AUTO_MODE_DENY_SOURCES, isAutoModeDenySource } from "./runtime-caps.js";
@@ -78,8 +78,6 @@ export declare function egressValue<T extends EgressTier, V>(tier: T, value: V):
78
78
  * Every pass it runs is a fixed point, so an account value minted twice reads the same.
79
79
  */
80
80
  export declare function egressAccount<T extends EgressTier, V>(tier: T, value: V): V;
81
- /** Where the markers sit in `s`, as [start, end) spans, leftmost first. */
82
- export declare function redactionMarkerSpans(s: string): Array<[number, number]>;
83
81
  /** The `same-principal` tier's pass + size-bound (NO injection fence): workflow outputs/results/errors riding back to
84
82
  * the launching model/script, run rows behind scope-gated observe. Paths/URLs survive (the assertion pattern depends on
85
83
  * them); secrets never do. */