@sema-agent/core 7.61.0 → 7.63.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 (298) hide show
  1. package/CHANGELOG.md +840 -0
  2. package/dist/agents/cascade.d.ts +11 -3
  3. package/dist/agents/cascade.js +1 -1
  4. package/dist/agents/peer-held-queue.d.ts +27 -4
  5. package/dist/agents/peer-held-queue.js +81 -36
  6. package/dist/agents/peer-session-drain.js +13 -3
  7. package/dist/agents/subagent-transcript-placement.d.ts +23 -0
  8. package/dist/agents/subagent-transcript-placement.js +14 -0
  9. package/dist/agents/subagent.d.ts +6 -1
  10. package/dist/agents/subagent.js +143 -58
  11. package/dist/agents/suspend-guard.d.ts +38 -16
  12. package/dist/agents/suspend-guard.js +9 -4
  13. package/dist/agents/verify.js +4 -3
  14. package/dist/brain/route-adjudicator.js +9 -4
  15. package/dist/core/approval-object.js +1 -1
  16. package/dist/core/arg-summary.js +1 -1
  17. package/dist/core/ask-question.d.ts +2 -2
  18. package/dist/core/canonical-json.d.ts +23 -13
  19. package/dist/core/canonical-json.js +4 -4
  20. package/dist/core/checkpoint-features.d.ts +722 -0
  21. package/dist/core/checkpoint-features.js +98 -0
  22. package/dist/core/checkpoint-queries.d.ts +47 -4
  23. package/dist/core/checkpoint-queries.js +36 -16
  24. package/dist/core/checkpoint-requirements.d.ts +12 -5
  25. package/dist/core/checkpoint-requirements.js +11 -5
  26. package/dist/core/checkpoint-row-verdict.d.ts +110 -0
  27. package/dist/core/checkpoint-row-verdict.js +245 -0
  28. package/dist/core/checkpoint-store.d.ts +76 -753
  29. package/dist/core/checkpoint-store.js +83 -144
  30. package/dist/core/compliance.d.ts +6 -2
  31. package/dist/core/compliance.js +3 -3
  32. package/dist/core/engine-attestation.d.ts +1 -1
  33. package/dist/core/engine-notice.d.ts +38 -7
  34. package/dist/core/engine-notice.js +9 -2
  35. package/dist/core/gate-fold.js +2 -2
  36. package/dist/core/git-worktree-env.d.ts +62 -3
  37. package/dist/core/git-worktree-env.js +91 -30
  38. package/dist/core/governance-codes.d.ts +9 -3
  39. package/dist/core/governance-codes.js +16 -3
  40. package/dist/core/hooks.d.ts +13 -0
  41. package/dist/core/human-input-projection.d.ts +1 -0
  42. package/dist/core/human-input-projection.js +3 -0
  43. package/dist/core/image-admission.d.ts +1 -1
  44. package/dist/core/locked-config.d.ts +2 -2
  45. package/dist/core/mcp-host-seat.js +6 -1
  46. package/dist/core/memory-engine/consolidation-driver.d.ts +33 -18
  47. package/dist/core/memory-engine/consolidation-driver.js +99 -98
  48. package/dist/core/memory-engine/consolidation.d.ts +73 -10
  49. package/dist/core/memory-engine/consolidation.js +167 -11
  50. package/dist/core/memory-engine/data-plane.d.ts +8 -4
  51. package/dist/core/memory-engine/data-plane.js +11 -6
  52. package/dist/core/memory-engine/delegation-settlement.d.ts +37 -35
  53. package/dist/core/memory-engine/delegation-settlement.js +53 -59
  54. package/dist/core/memory-engine/dual-root.d.ts +12 -6
  55. package/dist/core/memory-engine/dual-root.js +9 -5
  56. package/dist/core/memory-engine/engine.d.ts +98 -35
  57. package/dist/core/memory-engine/engine.js +477 -380
  58. package/dist/core/memory-engine/entry-scan.d.ts +8 -0
  59. package/dist/core/memory-engine/entry-scan.js +3 -0
  60. package/dist/core/memory-engine/file-backend.d.ts +29 -3
  61. package/dist/core/memory-engine/file-backend.js +66 -35
  62. package/dist/core/memory-engine/index.d.ts +7 -7
  63. package/dist/core/memory-engine/index.js +6 -6
  64. package/dist/core/memory-engine/landing-admission.d.ts +5 -3
  65. package/dist/core/memory-engine/landing-admission.js +3 -3
  66. package/dist/core/memory-engine/layout.d.ts +121 -45
  67. package/dist/core/memory-engine/layout.js +252 -102
  68. package/dist/core/memory-engine/memory-backend-contract.d.ts +19 -1
  69. package/dist/core/memory-engine/memory-backend-contract.js +320 -0
  70. package/dist/core/memory-engine/memory-deployment.d.ts +31 -8
  71. package/dist/core/memory-engine/memory-deployment.js +26 -12
  72. package/dist/core/memory-engine/scope-contract.d.ts +52 -11
  73. package/dist/core/memory-engine/scope-contract.js +68 -19
  74. package/dist/core/memory-engine/session-write-home.d.ts +3 -1
  75. package/dist/core/memory-engine/session-write-home.js +1 -1
  76. package/dist/core/memory-engine/sync-client.d.ts +3 -1
  77. package/dist/core/memory-engine/sync-client.js +7 -0
  78. package/dist/core/memory-engine/sync-report.d.ts +3 -2
  79. package/dist/core/memory-engine/sync-report.js +6 -2
  80. package/dist/core/memory-engine/tools.d.ts +2 -2
  81. package/dist/core/memory-engine/tools.js +10 -10
  82. package/dist/core/memory-engine/types.d.ts +118 -19
  83. package/dist/core/memory-engine/types.js +1 -0
  84. package/dist/core/memory-vector.d.ts +1 -1
  85. package/dist/core/memory.d.ts +10 -10
  86. package/dist/core/memory.js +15 -6
  87. package/dist/core/mode-policy.js +1 -1
  88. package/dist/core/mods/classic-events.d.ts +9 -1
  89. package/dist/core/mods/dollar.d.ts +32 -1
  90. package/dist/core/mods/dollar.js +13 -1
  91. package/dist/core/mods/kernel/events.d.ts +11 -3
  92. package/dist/core/mods/kernel/events.js +13 -10
  93. package/dist/core/mods/lifecycle-stations.d.ts +36 -4
  94. package/dist/core/mods/lifecycle-stations.js +44 -9
  95. package/dist/core/mods/session-append.d.ts +4 -1
  96. package/dist/core/mods/session-append.js +7 -0
  97. package/dist/core/mods/session-receive.js +12 -15
  98. package/dist/core/mods/stations.d.ts +70 -6
  99. package/dist/core/mods/stations.js +144 -1
  100. package/dist/core/own-property-receipt.d.ts +7 -0
  101. package/dist/core/own-property-receipt.js +3 -0
  102. package/dist/core/park-selfcheck.js +2 -2
  103. package/dist/core/pause-registry.d.ts +2 -0
  104. package/dist/core/pause-registry.js +3 -0
  105. package/dist/core/permission-rule-consent.d.ts +10 -3
  106. package/dist/core/permission-rule-consent.js +37 -24
  107. package/dist/core/permission-rule-store.d.ts +35 -1
  108. package/dist/core/permission-rule-store.js +27 -8
  109. package/dist/core/read-only-shell.js +3 -2
  110. package/dist/core/read-root-candidate.js +1 -1
  111. package/dist/core/redaction-marks.d.ts +8 -0
  112. package/dist/core/redaction-marks.js +6 -0
  113. package/dist/core/remote-env.d.ts +12 -1
  114. package/dist/core/remote-env.js +3 -0
  115. package/dist/core/resume-startup-cause.d.ts +5 -4
  116. package/dist/core/runner/child-tree.d.ts +29 -3
  117. package/dist/core/runner/child-tree.js +39 -16
  118. package/dist/core/runner/compact-session.js +5 -2
  119. package/dist/core/runner/contracts.d.ts +36 -17
  120. package/dist/core/runner/delegation-owner.d.ts +43 -0
  121. package/dist/core/runner/delegation-owner.js +59 -0
  122. package/dist/core/runner/gate-exit.js +2 -2
  123. package/dist/core/runner/inherited-ask-grants.js +1 -1
  124. package/dist/core/runner/lineage-reroot-view.d.ts +56 -0
  125. package/dist/core/runner/lineage-reroot-view.js +108 -0
  126. package/dist/core/runner/memory-consolidation-driver.d.ts +6 -3
  127. package/dist/core/runner/memory-consolidation-driver.js +4 -4
  128. package/dist/core/runner/memory-consolidation-write-judge.d.ts +2 -1
  129. package/dist/core/runner/memory-consolidation-write-judge.js +3 -2
  130. package/dist/core/runner/permission-rule-lanes.d.ts +2 -1
  131. package/dist/core/runner/permission-rule-lanes.js +2 -2
  132. package/dist/core/runner/person-path-rows.d.ts +23 -3
  133. package/dist/core/runner/person-path-rows.js +31 -4
  134. package/dist/core/runner/placement-fence.d.ts +12 -0
  135. package/dist/core/runner/placement-fence.js +20 -6
  136. package/dist/core/runner/prepare-acquire-reconcile.d.ts +4 -1
  137. package/dist/core/runner/prepare-acquire-reconcile.js +7 -2
  138. package/dist/core/runner/prepare-ask-lane.js +2 -2
  139. package/dist/core/runner/prepare-caps-and-workflow.d.ts +5 -1
  140. package/dist/core/runner/prepare-caps-and-workflow.js +6 -3
  141. package/dist/core/runner/prepare-config-doors.d.ts +6 -6
  142. package/dist/core/runner/prepare-config-doors.js +3 -4
  143. package/dist/core/runner/prepare-execution-env.js +17 -6
  144. package/dist/core/runner/prepare-hands-readface.d.ts +3 -2
  145. package/dist/core/runner/prepare-hands-readface.js +32 -10
  146. package/dist/core/runner/prepare-inherited-gate.d.ts +12 -8
  147. package/dist/core/runner/prepare-inherited-gate.js +14 -6
  148. package/dist/core/runner/prepare-memory-engine-session.d.ts +2 -4
  149. package/dist/core/runner/prepare-memory-engine-session.js +4 -4
  150. package/dist/core/runner/prepare-memory.d.ts +3 -2
  151. package/dist/core/runner/prepare-memory.js +28 -20
  152. package/dist/core/runner/prepare-park-ask.js +4 -3
  153. package/dist/core/runner/prepare-task.js +22 -16
  154. package/dist/core/runner/prepare-workspace-restore.js +3 -6
  155. package/dist/core/runner/resume-admission.d.ts +3 -3
  156. package/dist/core/runner/resume-admission.js +6 -3
  157. package/dist/core/runner/resume-apply.d.ts +4 -0
  158. package/dist/core/runner/resume-apply.js +11 -4
  159. package/dist/core/runner/resume-checkpoint-screen.d.ts +9 -0
  160. package/dist/core/runner/resume-checkpoint-screen.js +4 -84
  161. package/dist/core/runner/run-git-lane.d.ts +2 -0
  162. package/dist/core/runner/run-git-lane.js +4 -1
  163. package/dist/core/runner/run-harness-handlers.d.ts +2 -0
  164. package/dist/core/runner/run-harness-handlers.js +3 -2
  165. package/dist/core/runner/run-leg.js +25 -8
  166. package/dist/core/runner/run-settle-and-teardown.js +6 -4
  167. package/dist/core/runner/run-stop-and-final-verify.js +2 -1
  168. package/dist/core/runner/run-turn-boundary.js +7 -4
  169. package/dist/core/runner/runtask.js +6 -6
  170. package/dist/core/runner/steering-preview.d.ts +9 -0
  171. package/dist/core/runner/steering-preview.js +5 -0
  172. package/dist/core/runner/stream-steer-verb.js +8 -0
  173. package/dist/core/runner/terminal-account.js +1 -1
  174. package/dist/core/runner/tool-face-overlay.js +2 -0
  175. package/dist/core/runner/turn-attachments.d.ts +5 -0
  176. package/dist/core/runner/turn-attachments.js +1 -1
  177. package/dist/core/runner-deps.d.ts +8 -4
  178. package/dist/core/secret-env.d.ts +9 -6
  179. package/dist/core/secret-env.js +41 -22
  180. package/dist/core/session-checkout.d.ts +108 -0
  181. package/dist/core/session-checkout.js +485 -0
  182. package/dist/core/session-store.d.ts +13 -5
  183. package/dist/core/session-store.js +28 -4
  184. package/dist/core/session.d.ts +29 -5
  185. package/dist/core/session.js +3 -0
  186. package/dist/core/store-contracts/checkpoint-store-contract.d.ts +6 -12
  187. package/dist/core/store-contracts/checkpoint-store-contract.js +73 -6
  188. package/dist/core/store-contracts/session-store-contract.js +61 -8
  189. package/dist/core/task-event.d.ts +28 -1
  190. package/dist/core/task-notification.d.ts +9 -1
  191. package/dist/core/task-notification.js +8 -1
  192. package/dist/core/task-registry-agent.d.ts +40 -8
  193. package/dist/core/task-registry-agent.js +57 -24
  194. package/dist/core/task-registry-shared.d.ts +33 -11
  195. package/dist/core/task-registry-workflow.js +4 -3
  196. package/dist/core/task-registry.d.ts +27 -10
  197. package/dist/core/task-registry.js +19 -13
  198. package/dist/core/task-result.d.ts +5 -5
  199. package/dist/core/task-spec-members.js +1 -1
  200. package/dist/core/task-spec.d.ts +21 -1
  201. package/dist/core/terminal-cause.d.ts +6 -6
  202. package/dist/core/tool-face.d.ts +6 -2
  203. package/dist/core/tool-face.js +1 -1
  204. package/dist/core/tool-policy.d.ts +16 -13
  205. package/dist/core/tool-policy.js +11 -10
  206. package/dist/core/tool-roster.d.ts +4 -4
  207. package/dist/core/tool-spec.d.ts +42 -19
  208. package/dist/core/types.d.ts +2 -2
  209. package/dist/core/types.js +1 -1
  210. package/dist/core/untrusted-egress.d.ts +15 -4
  211. package/dist/core/untrusted-egress.js +23 -22
  212. package/dist/core/workspace-snapshot.d.ts +3 -1
  213. package/dist/core/workspace-snapshot.js +1 -0
  214. package/dist/engine/execution-env/node-execution-env.d.ts +3 -0
  215. package/dist/engine/execution-env/node-execution-env.js +12 -5
  216. package/dist/engine/harness/types.d.ts +77 -1
  217. package/dist/engine/harness/types.js +108 -0
  218. package/dist/engine/session/import-validate.js +6 -1
  219. package/dist/engine/session/parent-chain-guard.d.ts +3 -3
  220. package/dist/engine/session/parent-chain-guard.js +1 -1
  221. package/dist/engine/session/path-to-root.d.ts +18 -3
  222. package/dist/engine/session/path-to-root.js +15 -1
  223. package/dist/engine/session/repo-utils.d.ts +12 -1
  224. package/dist/engine/session/repo-utils.js +41 -0
  225. package/dist/engine/session/session.d.ts +24 -1
  226. package/dist/engine/session/session.js +46 -2
  227. package/dist/engine/session/storage-base.d.ts +20 -0
  228. package/dist/engine/session/storage-base.js +28 -9
  229. package/dist/index.d.ts +16 -12
  230. package/dist/index.js +11 -8
  231. package/dist/internal/harness-types.d.ts +1 -1
  232. package/dist/internal/harness.d.ts +4 -3
  233. package/dist/internal/harness.js +3 -2
  234. package/dist/orchestration/run-workflow-tool.d.ts +7 -1
  235. package/dist/orchestration/run-workflow-tool.js +28 -11
  236. package/dist/orchestration/workflow-governance.d.ts +1 -1
  237. package/dist/orchestration/workflow.d.ts +6 -0
  238. package/dist/orchestration/workflow.js +5 -8
  239. package/dist/stores/file/checkpoint-store.d.ts +2 -0
  240. package/dist/stores/file/checkpoint-store.js +7 -6
  241. package/dist/stores/file/fs-atomic.d.ts +0 -22
  242. package/dist/stores/file/fs-atomic.js +0 -17
  243. package/dist/stores/file/index.d.ts +2 -9
  244. package/dist/stores/file/index.js +2 -4
  245. package/dist/stores/file/session-store.d.ts +13 -7
  246. package/dist/stores/file/session-store.js +42 -18
  247. package/dist/tools/fs/bash-program-position.d.ts +3 -2
  248. package/dist/tools/fs/bash-program-position.js +10 -10
  249. package/dist/tools/fs/program-read-model.d.ts +34 -10
  250. package/dist/tools/fs/program-read-model.js +37 -7
  251. package/dist/tools/fs/program-read-model.rows.js +13 -2
  252. package/dist/tools/fs/read-deny.d.ts +13 -1
  253. package/dist/tools/fs/read-deny.js +10 -2
  254. package/dist/tools/fs/removal-targets.js +5 -5
  255. package/dist/tools/fs/safety.d.ts +2 -0
  256. package/dist/tools/fs/safety.js +1 -1
  257. package/dist/tools/fs/shell-read-argv.d.ts +11 -2
  258. package/dist/tools/fs/shell-read-argv.js +45 -29
  259. package/dist/tools/fs/shell-read-bindings.d.ts +20 -2
  260. package/dist/tools/fs/shell-read-bindings.js +153 -69
  261. package/dist/tools/fs/shell-read-brace.d.ts +18 -0
  262. package/dist/tools/fs/shell-read-brace.js +79 -0
  263. package/dist/tools/fs/shell-read-check.js +29 -11
  264. package/dist/tools/fs/shell-read-establish.js +43 -22
  265. package/dist/tools/fs/shell-read-functions.js +2 -2
  266. package/dist/tools/fs/shell-read-judge.d.ts +11 -0
  267. package/dist/tools/fs/shell-read-judge.js +3 -3
  268. package/dist/tools/fs/shell-read-object-path.d.ts +59 -0
  269. package/dist/tools/fs/shell-read-object-path.js +119 -0
  270. package/dist/tools/fs/shell-read-plan.d.ts +18 -0
  271. package/dist/tools/fs/shell-read-plan.js +217 -104
  272. package/dist/tools/fs/shell-read-start.d.ts +76 -13
  273. package/dist/tools/fs/shell-read-start.js +97 -17
  274. package/dist/tools/fs/shell-read-word.d.ts +10 -0
  275. package/dist/tools/fs/shell-read-word.js +9 -5
  276. package/dist/tools/fs/shell-read-workdir.d.ts +54 -14
  277. package/dist/tools/fs/shell-read-workdir.js +103 -19
  278. package/dist/tools/fs/shell-read-write-targets.js +13 -8
  279. package/dist/tools/worktree.d.ts +3 -2
  280. package/dist/tools/worktree.js +7 -35
  281. package/package.json +3 -2
  282. package/test/export-surface.snapshot.json +93 -43
  283. package/wire-changes/core-stores-sql@7.62.0.json +30 -0
  284. package/wire-changes/core-stores-sql@7.63.0.json +30 -0
  285. package/wire-changes/core@7.62.0.json +2181 -0
  286. package/wire-changes/core@7.63.0.json +3523 -0
  287. package/wire-changes/mods-kernel@7.62.0.json +42 -0
  288. package/wire-changes/mods-kernel@7.63.0.json +30 -0
  289. package/wire-changes/primitives@7.62.0.json +30 -0
  290. package/wire-changes/primitives@7.63.0.json +445 -0
  291. package/dist/core/consolidate-scope.d.ts +0 -93
  292. package/dist/core/consolidate-scope.js +0 -98
  293. package/dist/core/credential-vocabulary.d.ts +0 -176
  294. package/dist/core/credential-vocabulary.js +0 -190
  295. package/dist/core/redaction-passes.d.ts +0 -82
  296. package/dist/core/redaction-passes.js +0 -377
  297. package/dist/core/runner/memory-consolidation.d.ts +0 -109
  298. package/dist/core/runner/memory-consolidation.js +0 -251
@@ -210,7 +210,7 @@ export function collectDueAttachments(state, inp) {
210
210
  }
211
211
  if (inp.config.backgroundTasks && state.postCompactPending) {
212
212
  if (inp.backgroundTasks !== undefined && inp.backgroundTasks.length > 0) {
213
- (out ??= []).push({ source: "background_tasks", body: renderBackgroundTasks(inp.backgroundTasks), commit: () => void (state.postCompactPending = false) });
213
+ (out ??= []).push({ source: "background_tasks", body: renderBackgroundTasks(inp.backgroundTasks), echoBound: ATTACHMENT_BYTE_CAP, commit: () => void (state.postCompactPending = false) });
214
214
  }
215
215
  else {
216
216
  state.postCompactPending = false;
@@ -377,7 +377,9 @@ export interface RunnerDeps {
377
377
  * stays host-owned (the four verbs are engine host API; nothing in a task can trigger a run).
378
378
  * `provenance: "off"` beside this refuses loudly at prepare
379
379
  * (`config.memory_consolidation_provenance_off` — the fold law must be able to mint);
380
- * `multiNode: true` without a lease refuses (`config.memory_consolidation_lease_required`);
380
+ * `multiNode: true` without a lease refuses (`config.memory_consolidation_lease_required`), and over a backend whose
381
+ * consolidation state is replica-local (`memoryGovernanceDurability`) it refuses
382
+ * (`config.memory_consolidation_replica_local`);
381
383
  * every other bad value refuses under `config.memory_consolidation` (#123). DEPLOYMENT seat
382
384
  * ONLY (no TaskSpec twin, not in the governed workflow whitelist), same law as
383
385
  * {@link memoryProvenance}.
@@ -703,8 +705,10 @@ export interface RunnerDeps {
703
705
  * resolver fault rather than an adjudicated posture). `undefined` (no resolver / no posture for
704
706
  * the principal) = no compliance restriction from the deployment — existing deployments are untouched. The run's deny
705
707
  * set is this posture's UNION the request's own denies ({@link TaskSpec.complianceAdditionalDenies}, add-only).
708
+ * One seat is asked a second question: the automatic consolidation run a settled leg fires asks it for the posture of the
709
+ * consolidated scope's OWNER (`memory_consolidation`, read by the consolidation verb at its start, not frozen at prepare).
706
710
  */
707
- compliancePostureResolver?: (principal: string | undefined) => import("./compliance.js").CompliancePosture | undefined | Promise<import("./compliance.js").CompliancePosture | undefined>;
711
+ compliancePostureResolver?: import("./compliance.js").CompliancePostureSeat;
708
712
  /**
709
713
  * Org-memory tenant admission (ruled 2026-08-05) — the fail-closed adjudicator for REQUEST-origin
710
714
  * `org:` memory scopes (`TaskSpec.memory` / a subagent's `AgentDefinition.memory`, under the v2
@@ -1372,8 +1376,8 @@ export interface RunnerDeps {
1372
1376
  * errors and do not affect the run, which the engine otherwise prints via `console.warn` (e.g. a
1373
1377
  * configured timeout/env value discarded in favor of another). When wired, a notice goes HERE
1374
1378
  * INSTEAD of `console.warn` (structured replaces the console line — a host forwarding notices to
1375
- * its own surface must not show every fact twice); when absent, the historic `console.warn` line
1376
- * is printed verbatim, so an unwired build keeps its exact loudness. Swallow-guarded at every
1379
+ * its own surface must not show every fact twice); when absent, the default seat the host installed
1380
+ * (`setDefaultEngineNoticeSeat`) takes it, else the historic `console.warn` line is printed verbatim. Swallow-guarded at every
1377
1381
  * emission point (`onError`/`tracer` posture): neither a throwing sink nor an async sink's
1378
1382
  * rejected promise ever affects the run. A PRESENT NON-function value (an untyped host wiring
1379
1383
  * null/junk) is a bad deployment value, not a wired sink: every notice then falls back to the
@@ -19,7 +19,7 @@
19
19
  * as written, three ways stricter: plural `TOKENS` is a credential word unless a count word touches it, the GitHub
20
20
  * token names are not held back from the name shape, and the name shape always runs.
21
21
  */
22
- import { type RedactionConfidence, type RedactionSource } from "./credential-vocabulary.js";
22
+ import { type RedactionConfidence, type RedactionSource } from "@sema-agent/primitives";
23
23
  import { type EngineNotice } from "./engine-notice.js";
24
24
  /** Does a value carry a credential? A URL userinfo (after every `scheme://`, and a leading `//`) with a password or a
25
25
  * token-like user; a scheme-less `user:password@host`; a credential assignment; a webhook URL; a Sonar login; a
@@ -97,7 +97,8 @@ export declare function namesASecret(value: string): boolean;
97
97
  * word, one character repeated, fewer than {@link CREDENTIAL_MIN_CHARS} characters — withholding it would take a setting
98
98
  * such as `CI=true` from every child) or that is, in this process's environment now, the value of such a variable —
99
99
  * throws and leaves the declaration as it was. A value listed twice is the one value (the declaration is a set). No
100
- * refusal sentence repeats a value.
100
+ * refusal sentence repeats a value. A value refused as no credential is the one value the refusal names: the host was
101
+ * told of it there, so the engine's intake ({@link holdOwnCredentialValues}) does not say it again.
101
102
  *
102
103
  * Two Windows readings, measured on a real machine: a withheld name that the child's own shell or runtime re-creates
103
104
  * with a DEFAULT of its own (`ComSpec`, `PATHEXT`, `HOME`, `CommonProgramFiles`, …) shows up in the child's table with
@@ -121,9 +122,11 @@ export declare function declareWithheldEnv(table: WithheldEnvDeclaration): void;
121
122
  * gateway is told to be handed) is not taken in: its holder uses it as given (it is no bad value), and the variables
122
123
  * that hold the same string stay with every child. Said once per process per value, never the value, as the notice
123
124
  * `config.credential_not_withheld` through the engine's one notice throat ({@link deliverEngineNotice}): to `onNotice`
124
- * when the intake has the structured seat in hand (the `RunnerDeps` receipt at `new Runner`), else as that notice's
125
- * line on `console.warn` (the throat's own arm for an absent seat — a brain's construction, a request's route reading,
126
- * a peer's dial, a directly built distiller seat). A value that is, in this process's
125
+ * when the intake has the structured seat in hand (the `RunnerDeps` receipt at `new Runner`), else to the process's
126
+ * default seat ({@link import("./engine-notice.js").setDefaultEngineNoticeSeat}) when a host installed one, else as that
127
+ * notice's line on `console.warn` (the throat's own arm for an absent seat — a brain's construction, a request's route
128
+ * reading, a peer's dial, a directly built distiller seat). A value the host's declaration refused as no credential
129
+ * ({@link declareWithheldEnv}) was told in that refusal and is on the same account: not said again. A value that is, in this process's
127
130
  * environment now, the value of a variable every child is handed whatever the spawn passes cannot be withheld: the intake
128
131
  * throws (`config.invalid_argument`, the variable named, never the value) and takes nothing in — the brain is not built,
129
132
  * the peer is not dialed.
@@ -209,7 +212,7 @@ export declare function withheldEnvNames(findings: readonly SecretEnvFinding[]):
209
212
  /**
210
213
  * The ONE disclosure point for a scrub's withheld keys. Routed through {@link deliverEngineNotice} — the
211
214
  * engine's one notice throat — so a wired `onNotice` seat REPLACES the console line exactly as every
212
- * other `EngineNotice` does, and an absent seat prints the same words `console.warn` always printed here.
215
+ * other `EngineNotice` does, and an absent seat (no default seat installed) prints the same words `console.warn` always printed here.
213
216
  * `detail` is {@link withheldEnvNames}: `names` every withheld key, `ownCredentials` (present only when one was
214
217
  * withheld) the subset that is the engine's own credentials. Once per PROCESS, never per call or per site; an
215
218
  * EMPTY findings array is a no-op.
@@ -1,6 +1,6 @@
1
1
  import { createHash } from "node:crypto";
2
2
  import { types } from "node:util";
3
- import { CREDENTIAL_MIN_CHARS, CREDENTIAL_VOCABULARY, envNameView, isSensitiveHeaderName, splitCamelCase } from "./credential-vocabulary.js";
3
+ import { CREDENTIAL_MIN_CHARS, envNameView, isSensitiveHeaderName, splitCamelCase } from "@sema-agent/primitives";
4
4
  import { DEFAULT_INHERITED_ENV_VARS } from "@modelcontextprotocol/client/stdio";
5
5
  import { deliverEngineNotice } from "./engine-notice.js";
6
6
  import { optionKeys, receiveMembers } from "./own-property-receipt.js";
@@ -9,9 +9,9 @@ const PROXY_ENV_RE = /^(?:(?:https?|ftp|all|no)_proxy|npm_config_(?:https?_)?pro
9
9
  function isExemptEnvName(name) {
10
10
  return GIT_CONFIG_ENV_RE.test(name) || PROXY_ENV_RE.test(name);
11
11
  }
12
- const ENV_NAMES = envNameView(CREDENTIAL_VOCABULARY);
12
+ const ENV_NAMES = envNameView();
13
13
  const OTEL_ENV_RE = /^(?:INPUT_)?OTEL_/i;
14
- const SEMA_NAMESPACE_SECRET_RE = new RegExp(`^SEMA_(?:.*_)?${ENV_NAMES.segmentWord}(?:_|$)`, "is");
14
+ const SEMA_NAMESPACE_SECRET_RE = ENV_NAMES.anySegmentUnder("SEMA_");
15
15
  const BUNDLER_SETTINGS = ["BUILD", "LOCAL", "MIRROR", "PATH", "WITH", "WITHOUT", "CACHE", "DISABLE", "IGNORE", "ONLY"];
16
16
  const BUNDLER_HOST = "(?:[A-Za-z0-9]+(?:___[A-Za-z0-9]+)*__)+[A-Za-z]{2,}";
17
17
  const BUNDLER_CREDENTIAL_RE = new RegExp(`^(?:INPUT_)?BUNDLE_(?!(?:${BUNDLER_SETTINGS.join("|")})__(?!${BUNDLER_HOST}$))\\w*__`, "i");
@@ -210,27 +210,30 @@ function notACredentialReason(value) {
210
210
  return `a string of fewer than ${CREDENTIAL_MIN_CHARS} characters, which names no secret`;
211
211
  if (PLACEHOLDER_KEY_WORDS.has(text.toLowerCase()))
212
212
  return "a flag or placeholder word, which names no secret";
213
- if (ONE_REPEATED_CHARACTER_RE.test(text.replace(CREDENTIAL_VOCABULARY.tokenPrefix, "")))
213
+ if (ONE_REPEATED_CHARACTER_RE.test(text.replace(ENV_NAMES.tokenPrefix, "")))
214
214
  return "one character repeated, which names no secret";
215
215
  return undefined;
216
216
  }
217
217
  export function namesASecret(value) {
218
218
  return notACredentialReason(value) === undefined;
219
219
  }
220
- function credentialValueProblem(v) {
220
+ function notVariableValueReason(v) {
221
221
  if (typeof v !== "string")
222
222
  return kindOf(v);
223
223
  if (v === "")
224
224
  return "an empty string, which every variable set to nothing equals";
225
225
  if (v.includes("\0") || UNPAIRED_SURROGATE_RE.test(v))
226
226
  return `a value holding ${v.includes("\0") ? "a NUL" : "an unpaired surrogate"}, which no variable can hold`;
227
- return notACredentialReason(v);
227
+ return undefined;
228
228
  }
229
- function credentialValueListProblem(value) {
230
- for (const [i, v] of value.entries()) {
229
+ function credentialValueProblem(v) {
230
+ return notVariableValueReason(v) ?? notACredentialReason(v);
231
+ }
232
+ function firstRefusedValue(value) {
233
+ for (const [index, v] of value.entries()) {
231
234
  const why = credentialValueProblem(v);
232
235
  if (why !== undefined)
233
- return `values[${i}] is not a credential value (got ${why})`;
236
+ return { index, why };
234
237
  }
235
238
  return undefined;
236
239
  }
@@ -255,9 +258,13 @@ export function declareWithheldEnv(table) {
255
258
  if (!Array.isArray(givenValues))
256
259
  throw new Error(`declareWithheldEnv: values must be an array of credential values (got ${kindOf(givenValues)})`);
257
260
  const values = listCopy("values", givenValues);
258
- const valueProblem = credentialValueListProblem(values);
259
- if (valueProblem !== undefined)
260
- throw new Error(`declareWithheldEnv: ${valueProblem}`);
261
+ const refused = firstRefusedValue(values);
262
+ if (refused !== undefined) {
263
+ const told = values[refused.index];
264
+ if (typeof told === "string" && notVariableValueReason(told) === undefined && !isBlankCredential(told))
265
+ noteIntakeSaid(told);
266
+ throw new Error(`declareWithheldEnv: values[${refused.index}] is not a credential value (got ${refused.why})`);
267
+ }
261
268
  for (const [i, v] of values.entries()) {
262
269
  const holder = runtimeSuppliedHolderOf(v);
263
270
  if (holder !== undefined)
@@ -270,20 +277,27 @@ export function declareWithheldEnv(table) {
270
277
  }
271
278
  export function holdOwnCredentialValues(values, onNotice) {
272
279
  const given = [...values].filter((v) => typeof v === "string" && !isBlankCredential(v));
280
+ const notTaken = new Map();
273
281
  const taken = given.filter((v) => {
274
282
  const why = notACredentialReason(v);
275
283
  if (why !== undefined)
276
- sayNotTaken(v, why, onNotice);
284
+ notTaken.set(v, why);
277
285
  return why === undefined;
278
286
  });
279
- for (const v of taken) {
280
- const holder = runtimeSuppliedHolderOf(v);
281
- if (holder !== undefined)
282
- throw Object.assign(new Error(`a credential the engine was handed is the value of ${holder}, ${CANNOT_BE_WITHHELD}; the credential is refused`), { code: "config.invalid_argument" });
287
+ try {
288
+ for (const v of taken) {
289
+ const holder = runtimeSuppliedHolderOf(v);
290
+ if (holder !== undefined)
291
+ throw Object.assign(new Error(`a credential the engine was handed is the value of ${holder}, ${CANNOT_BE_WITHHELD}; the credential is refused`), { code: "config.invalid_argument" });
292
+ }
293
+ const { held } = withheldEnvOf();
294
+ for (const v of taken)
295
+ indexAdd(held, v);
296
+ }
297
+ finally {
298
+ for (const [v, why] of notTaken)
299
+ sayNotTaken(v, why, onNotice);
283
300
  }
284
- const { held } = withheldEnvOf();
285
- for (const v of taken)
286
- indexAdd(held, v);
287
301
  }
288
302
  const AUTH_SCHEME_VALUE_RE = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+ +(\S[\s\S]*)$/;
289
303
  export function authSchemeCredentials(value) {
@@ -313,11 +327,16 @@ export function credentialHeaderValues(headers) {
313
327
  return out;
314
328
  }
315
329
  const intakeSaid = new Set();
316
- function sayNotTaken(value, why, onNotice) {
330
+ function noteIntakeSaid(value) {
317
331
  const key = valueDigest(value.trim());
318
332
  if (intakeSaid.has(key))
319
- return;
333
+ return false;
320
334
  intakeSaid.add(key);
335
+ return true;
336
+ }
337
+ function sayNotTaken(value, why, onNotice) {
338
+ if (!noteIntakeSaid(value))
339
+ return;
321
340
  try {
322
341
  deliverEngineNotice(onNotice, {
323
342
  code: "config.credential_not_withheld",
@@ -0,0 +1,108 @@
1
+ import type { ExecutionEnv, Session, SessionCheckoutCell, SessionCheckoutDeclared, SessionCheckoutRecord } from "../internal/harness-types.js";
2
+ /** One declared code source: the root it is for, the repository URL (`https` only), the full commit id the session's code
3
+ * starts from, and a display label. */
4
+ export interface WorkspaceSourceDeclaration {
5
+ /** `"taskRoot"`, or `{ directory }` naming an entry of `TaskSpec.additionalDirectories` (the same spelling). */
6
+ readonly root: "taskRoot" | {
7
+ readonly directory: string;
8
+ };
9
+ /** The repository URL. `https` only; normalized (host lowercased, a trailing `/` or `.git` dropped). A user name or password in
10
+ * it, or a query / fragment parameter whose name reads as a credential, is refused, and the refusal echoes only the origin. */
11
+ readonly remote: string;
12
+ /** The full commit id (40 or 64 lowercase hex). The engine checks it on the session's first leg. */
13
+ readonly sha: string;
14
+ /** A display / continuation label (a branch name); never resolved. */
15
+ readonly ref?: string;
16
+ }
17
+ /** `TaskSpec.workspace`: the session's workspace declaration. */
18
+ export interface WorkspaceDeclaration {
19
+ /** `"worktree"`: the session works in its own managed tree of the task root's repository, minted on its first leg. */
20
+ readonly isolation?: "worktree";
21
+ /** Where the tree starts: `"fresh"` (default — the default branch tip) or `"head"` (the current local HEAD). Only with
22
+ * `isolation`, and not with a source for the task root (the source's commit is the start). */
23
+ readonly baseRef?: "fresh" | "head";
24
+ /** The tree's managed name (the EnterWorktree name grammar); absent ⇒ derived from the session id. Only with `isolation`. */
25
+ readonly name?: string;
26
+ /** The code sources, one per repository. */
27
+ readonly sources?: readonly WorkspaceSourceDeclaration[];
28
+ }
29
+ /** Why a checkout cannot get a managed tree here — the probe's closed set. */
30
+ export declare const WORKTREE_INCAPABLE_REASONS: readonly ["git_unavailable", "not_a_repository", "bare_repository", "no_commit", "managed_parent_symlinked", "parent_not_writable", "name_in_use"];
31
+ export type WorktreeIncapableReason = (typeof WORKTREE_INCAPABLE_REASONS)[number];
32
+ /** What {@link probeWorktreeCapability} answered. `gitRoot` = the repository root the managed parent hangs at (present once
33
+ * the location is known to be a repository). */
34
+ export interface WorktreeCapability {
35
+ readonly worktreeCapable: boolean;
36
+ readonly gitRoot?: string;
37
+ readonly reason?: WorktreeIncapableReason;
38
+ /** One human sentence for the refusal; absent when capable. */
39
+ readonly detail?: string;
40
+ }
41
+ /** The release outcome of one tree. `branch` is present while the tree's branch still exists after the release. */
42
+ export interface ReleasedTree {
43
+ readonly path: string;
44
+ readonly removed: boolean;
45
+ readonly branch?: string;
46
+ readonly kept?: "dirty" | "ignored" | "commits" | "unverifiable" | "requested" | "not_owned";
47
+ readonly detail?: string;
48
+ }
49
+ /**
50
+ * THE shape judge of `TaskSpec.workspace` — `undefined` for an absent declaration, else the normalized declaration the record
51
+ * stores and every later leg is compared on. Refused (`config.session_workspace_invalid`): a non-object, an unknown key, a word
52
+ * outside a closed set, `baseRef` / `name` without `isolation`, a name outside the managed grammar, an empty or oversized
53
+ * `sources`, two sources for one root, a source for the isolated task root together with `baseRef`, a declaration that declares
54
+ * nothing.
55
+ */
56
+ export declare function screenWorkspaceDeclaration(value: unknown): SessionCheckoutDeclared | undefined;
57
+ /**
58
+ * THE capability judge of a managed tree for the checkout at `cwd`: git runs, `cwd` is inside a non-bare work tree with a
59
+ * commit, no level of the managed parent is a symlink, the managed parent can be written, and — with `name` — that name's
60
+ * directory and branch are free. The first failing check answers, in that order. Reads only (no git write); a host calls it
61
+ * before offering isolation, and a session's first leg calls it before minting.
62
+ */
63
+ export declare function probeWorktreeCapability(env: ExecutionEnv, cwd: string, opts?: {
64
+ readonly name?: string;
65
+ }): Promise<WorktreeCapability>;
66
+ export interface OpenSessionCheckoutInput {
67
+ /** The leg's hands environment (the one git runs in). */
68
+ readonly env: ExecutionEnv;
69
+ readonly session: Session;
70
+ readonly sessionId: string;
71
+ /** The leg's raw `TaskSpec.workspace`. */
72
+ readonly declaration: unknown;
73
+ /** The leg's task root as the deployment and the workspace restore settled it (the base checkout's location). */
74
+ readonly baseRoot: string;
75
+ /** The leg's `TaskSpec.additionalDirectories` (declared spellings). */
76
+ readonly additionalDirectories: readonly string[] | undefined;
77
+ }
78
+ export interface OpenedSessionCheckout {
79
+ /** The leg's task root: the task root's place in the session's tree when the task root's repository is isolated, else `baseRoot`. */
80
+ readonly taskRoot: string;
81
+ /** The session's checkout record, when it has one. */
82
+ readonly record?: SessionCheckoutRecord;
83
+ }
84
+ /**
85
+ * THE per-leg judge of a session's checkout (see the module header): reads the record, compares the leg's declaration with it,
86
+ * mints the allocation on the session's first leg, and answers the leg's task root. Throws a coded refusal; the first leg's
87
+ * allocation is all or nothing (every check runs before the mint, a tree minted for a refused allocation is removed while it is
88
+ * still clean, and the record is written only once everything succeeded — immediately, not at settle).
89
+ */
90
+ export declare function openSessionCheckout(input: OpenSessionCheckoutInput): Promise<OpenedSessionCheckout>;
91
+ /**
92
+ * Release a session's checkout — the host's door when it archives or deletes a session. Each of the session's trees is removed
93
+ * only when it is clean (no uncommitted file, no file git ignores, no commit past its base, its state readable) AND its birth record names this
94
+ * allocation; the removal itself runs without `--force`, so a write landing after the check keeps the tree. Everything else
95
+ * is kept and reported with its path and why. The tree's branch is deleted with it only while the branch still sits at the
96
+ * base commit. Then the release is recorded once (`released: true`), after which the session runs no further leg. Calling it
97
+ * again re-reports and never removes a tree another allocation took over.
98
+ *
99
+ * `onExit`: `"keep-if-dirty"` (default) | `"keep"` (keep every tree; only record the release). A discarding removal is not
100
+ * offered. A session with no checkout answers an empty list.
101
+ */
102
+ export declare function releaseSessionCheckout(env: ExecutionEnv, session: Session, opts?: {
103
+ readonly onExit?: "keep-if-dirty" | "keep";
104
+ }): Promise<{
105
+ readonly trees: readonly ReleasedTree[];
106
+ }>;
107
+ /** The frame's `session` member: the record's cells as the leg reports them (`undefined` when the session has no checkout). */
108
+ export declare function sessionFrameOf(record: SessionCheckoutRecord | undefined): ReadonlyArray<SessionCheckoutCell> | undefined;