@sema-agent/core 7.67.3 → 7.68.1

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 (501) hide show
  1. package/CHANGELOG.md +1537 -0
  2. package/README.md +18 -9
  3. package/README.zh-CN.md +16 -8
  4. package/dist/agents/agent-definition.d.ts +1 -1
  5. package/dist/agents/agent-definition.js +4 -1
  6. package/dist/agents/cascade.d.ts +2 -2
  7. package/dist/agents/cascade.js +3 -1
  8. package/dist/agents/cumulative-stats.d.ts +2 -1
  9. package/dist/agents/cumulative-stats.js +4 -1
  10. package/dist/agents/list-agents-tool.d.ts +30 -0
  11. package/dist/agents/list-agents-tool.js +45 -3
  12. package/dist/agents/peer-admission.d.ts +2 -2
  13. package/dist/agents/peer-session-drain.d.ts +2 -0
  14. package/dist/agents/peer-session-drain.js +1 -0
  15. package/dist/agents/repair-loop.js +3 -1
  16. package/dist/agents/retain-ledger.d.ts +61 -8
  17. package/dist/agents/retain-ledger.js +25 -3
  18. package/dist/agents/roster-store.d.ts +4 -2
  19. package/dist/agents/send-message-tool.d.ts +1 -1
  20. package/dist/agents/send-message-tool.js +20 -15
  21. package/dist/agents/subagent-steps.js +2 -10
  22. package/dist/agents/subagent.d.ts +3 -0
  23. package/dist/agents/subagent.js +106 -76
  24. package/dist/agents/tool-filter.d.ts +20 -11
  25. package/dist/agents/tool-filter.js +8 -4
  26. package/dist/agents/verify.d.ts +3 -1
  27. package/dist/agents/verify.js +2 -0
  28. package/dist/brain/anthropic.js +4 -4
  29. package/dist/brain/open-responses.js +3 -1
  30. package/dist/brain/openai.js +3 -1
  31. package/dist/brain/reasoning-request.d.ts +73 -19
  32. package/dist/brain/reasoning-request.js +164 -72
  33. package/dist/brain/reasoning-stamp.d.ts +26 -0
  34. package/dist/brain/reasoning-stamp.js +10 -0
  35. package/dist/brain/reasoning.d.ts +95 -162
  36. package/dist/brain/reasoning.js +31 -86
  37. package/dist/brain/route-adjudicator.d.ts +9 -7
  38. package/dist/brain/route-adjudicator.js +12 -10
  39. package/dist/brain/status-sink.d.ts +19 -64
  40. package/dist/brain/status-sink.js +5 -21
  41. package/dist/brain/stream-engine.d.ts +11 -2
  42. package/dist/brain/stream-engine.js +10 -0
  43. package/dist/core/a2a.d.ts +17 -5
  44. package/dist/core/a2a.js +11 -3
  45. package/dist/core/allow-entry.d.ts +35 -15
  46. package/dist/core/allow-entry.js +47 -60
  47. package/dist/core/ask-headline.d.ts +68 -0
  48. package/dist/core/ask-headline.js +23 -0
  49. package/dist/core/ask-origin.d.ts +36 -8
  50. package/dist/core/ask-origin.js +17 -10
  51. package/dist/core/ask-question.d.ts +34 -7
  52. package/dist/core/ask-question.js +10 -1
  53. package/dist/core/ask-unresolvable-notice.d.ts +7 -0
  54. package/dist/core/ask-unresolvable-notice.js +9 -3
  55. package/dist/core/auto-strip.d.ts +53 -0
  56. package/dist/core/auto-strip.js +76 -0
  57. package/dist/core/background-agent-store.d.ts +45 -5
  58. package/dist/core/background-agent-store.js +69 -15
  59. package/dist/core/background-shell.d.ts +2 -2
  60. package/dist/core/caller-text.js +2 -2
  61. package/dist/core/canonical-json.d.ts +13 -0
  62. package/dist/core/canonical-json.js +7 -0
  63. package/dist/core/checkpoint-features.d.ts +66 -20
  64. package/dist/core/checkpoint-features.js +12 -1
  65. package/dist/core/checkpoint-generation.d.ts +1 -1
  66. package/dist/core/checkpoint-queries.d.ts +1 -1
  67. package/dist/core/checkpoint-queries.js +4 -1
  68. package/dist/core/checkpoint-requirements.d.ts +45 -2
  69. package/dist/core/checkpoint-requirements.js +16 -6
  70. package/dist/core/checkpoint-row-verdict.d.ts +1 -0
  71. package/dist/core/checkpoint-row-verdict.js +4 -0
  72. package/dist/core/checkpoint-store.d.ts +66 -38
  73. package/dist/core/checkpoint-store.js +15 -6
  74. package/dist/core/child-clamp-seats.d.ts +6 -0
  75. package/dist/core/child-clamp-seats.js +1 -0
  76. package/dist/core/config-refusal-codes.d.ts +1 -1
  77. package/dist/core/config-refusal-codes.js +1 -0
  78. package/dist/core/delegation-frames.d.ts +9 -12
  79. package/dist/core/delegation-frames.js +9 -8
  80. package/dist/core/engine-capabilities.d.ts +21 -8
  81. package/dist/core/engine-capabilities.js +1 -1
  82. package/dist/core/engine-notice.d.ts +147 -34
  83. package/dist/core/engine-notice.js +27 -16
  84. package/dist/core/engine-storage-backend.d.ts +2 -1
  85. package/dist/core/env-budget.js +3 -3
  86. package/dist/core/env-knob-announce.d.ts +10 -10
  87. package/dist/core/env-knob-announce.js +3 -6
  88. package/dist/core/file-history-store.d.ts +29 -4
  89. package/dist/core/file-history-store.js +13 -0
  90. package/dist/core/frame-settlement.d.ts +2 -1
  91. package/dist/core/gate-fold.js +1 -1
  92. package/dist/core/gate-lanes.js +56 -49
  93. package/dist/core/governance-codes.d.ts +39 -3
  94. package/dist/core/governance-codes.js +61 -3
  95. package/dist/core/hooks.d.ts +29 -11
  96. package/dist/core/hooks.js +5 -2
  97. package/dist/core/human-input-projection.js +3 -3
  98. package/dist/core/input-author.d.ts +17 -3
  99. package/dist/core/input-author.js +15 -3
  100. package/dist/core/leg-identity.d.ts +10 -28
  101. package/dist/core/leg-identity.js +1 -21
  102. package/dist/core/lsp.d.ts +18 -13
  103. package/dist/core/lsp.js +30 -22
  104. package/dist/core/mailbox-store.d.ts +1 -1
  105. package/dist/core/mailbox-store.js +4 -4
  106. package/dist/core/mcp-connection-pool.d.ts +93 -4
  107. package/dist/core/mcp-connection-pool.js +104 -1
  108. package/dist/core/mcp-failure.d.ts +38 -12
  109. package/dist/core/mcp-failure.js +9 -13
  110. package/dist/core/mcp-probe.d.ts +4 -3
  111. package/dist/core/mcp-server-link.d.ts +4 -2
  112. package/dist/core/mcp-server-link.js +4 -5
  113. package/dist/core/mcp-server-spec.d.ts +3 -3
  114. package/dist/core/mcp-server-unavailable-notice.d.ts +22 -8
  115. package/dist/core/mcp-server-unavailable-notice.js +18 -4
  116. package/dist/core/mcp.d.ts +40 -6
  117. package/dist/core/mcp.js +39 -13
  118. package/dist/core/memory-engine/content-origin.js +2 -2
  119. package/dist/core/memory-engine/control-objects.d.ts +2 -4
  120. package/dist/core/memory-engine/control-objects.js +2 -10
  121. package/dist/core/memory-engine/delegation-settlement.js +6 -1
  122. package/dist/core/memory-engine/dual-root.js +3 -0
  123. package/dist/core/memory-engine/engine.d.ts +6 -4
  124. package/dist/core/memory-engine/engine.js +32 -29
  125. package/dist/core/memory-engine/file-backend.d.ts +20 -5
  126. package/dist/core/memory-engine/file-backend.js +21 -31
  127. package/dist/core/memory-engine/frontmatter.d.ts +2 -0
  128. package/dist/core/memory-engine/frontmatter.js +4 -0
  129. package/dist/core/memory-engine/layout.d.ts +114 -20
  130. package/dist/core/memory-engine/layout.js +340 -22
  131. package/dist/core/memory-engine/memory-deployment.d.ts +7 -5
  132. package/dist/core/memory-engine/mount-failed-notice.d.ts +19 -7
  133. package/dist/core/memory-engine/mount-failed-notice.js +43 -10
  134. package/dist/core/memory-engine/sync-client.js +4 -5
  135. package/dist/core/model-fallbacks.d.ts +5 -1
  136. package/dist/core/model-fallbacks.js +3 -3
  137. package/dist/core/model-receipt.d.ts +2 -1
  138. package/dist/core/model-receipt.js +12 -1
  139. package/dist/core/mods/kernel/dispatch.d.ts +2 -2
  140. package/dist/core/mods/kernel/dispatch.js +14 -6
  141. package/dist/core/mods/kernel/events.d.ts +8 -5
  142. package/dist/core/mods/kernel/events.js +2 -2
  143. package/dist/core/mods/kernel/index.d.ts +1 -1
  144. package/dist/core/mods/kernel/registration.d.ts +9 -0
  145. package/dist/core/mods/package.js +1 -1
  146. package/dist/core/mods/session-append.d.ts +4 -2
  147. package/dist/core/mods/session-append.js +3 -0
  148. package/dist/core/mods/stations.d.ts +7 -11
  149. package/dist/core/mods/stations.js +4 -7
  150. package/dist/core/mods/tool-call.d.ts +10 -8
  151. package/dist/core/mods/tool-call.js +15 -18
  152. package/dist/core/mounted-mcp.d.ts +0 -4
  153. package/dist/core/mounted-mcp.js +1 -1
  154. package/dist/core/park-noun.d.ts +24 -0
  155. package/dist/core/park-noun.js +21 -0
  156. package/dist/core/park-resumability.d.ts +60 -0
  157. package/dist/core/park-resumability.js +30 -0
  158. package/dist/core/permission-rule-provider.d.ts +24 -2
  159. package/dist/core/permission-rule-provider.js +11 -8
  160. package/dist/core/permission-rule-store.d.ts +8 -1
  161. package/dist/core/permission-rule-store.js +2 -3
  162. package/dist/core/permission-rules.d.ts +2 -1
  163. package/dist/core/permission-rules.js +8 -4
  164. package/dist/core/persisted-rule-arms.d.ts +3 -0
  165. package/dist/core/persisted-rule-arms.js +2 -1
  166. package/dist/core/present-plan-tool.d.ts +47 -3
  167. package/dist/core/present-plan-tool.js +62 -4
  168. package/dist/core/principal-name.d.ts +1 -1
  169. package/dist/core/principal-name.js +5 -5
  170. package/dist/core/process-identity.js +10 -5
  171. package/dist/core/protocol-http-auth.d.ts +20 -14
  172. package/dist/core/protocol-http-auth.js +70 -50
  173. package/dist/core/read-only-shell.js +9 -5
  174. package/dist/core/redaction-marks.d.ts +4 -26
  175. package/dist/core/redaction-marks.js +9 -21
  176. package/dist/core/remote-env.d.ts +43 -16
  177. package/dist/core/remote-env.js +1 -1
  178. package/dist/core/request-copy-projection.d.ts +1 -1
  179. package/dist/core/request-copy-projection.js +40 -50
  180. package/dist/core/resume-config-judge.js +1 -1
  181. package/dist/core/resume-startup-cause.d.ts +35 -18
  182. package/dist/core/resume-startup-cause.js +13 -10
  183. package/dist/core/retention.d.ts +167 -25
  184. package/dist/core/retention.js +100 -20
  185. package/dist/core/roles.d.ts +6 -0
  186. package/dist/core/roles.js +11 -5
  187. package/dist/core/rule-lane-reads.d.ts +3 -0
  188. package/dist/core/rule-lane-reads.js +5 -1
  189. package/dist/core/rule-store-fault.d.ts +70 -0
  190. package/dist/core/rule-store-fault.js +102 -0
  191. package/dist/core/runner/advertised-writable-dirs.js +16 -31
  192. package/dist/core/runner/announce-once-ledger.d.ts +19 -2
  193. package/dist/core/runner/announce-once-ledger.js +24 -2
  194. package/dist/core/runner/assemble-result.d.ts +6 -0
  195. package/dist/core/runner/assemble-result.js +1 -1
  196. package/dist/core/runner/auto-strip-notice.d.ts +36 -0
  197. package/dist/core/runner/auto-strip-notice.js +59 -0
  198. package/dist/core/runner/branch-window.d.ts +3 -0
  199. package/dist/core/runner/branch-window.js +37 -0
  200. package/dist/core/runner/caller-roster.d.ts +8 -3
  201. package/dist/core/runner/capability-withheld-seat.js +3 -9
  202. package/dist/core/runner/clock-and-limits.d.ts +22 -1
  203. package/dist/core/runner/clock-and-limits.js +30 -0
  204. package/dist/core/runner/contracts.d.ts +58 -35
  205. package/dist/core/runner/credential-refusal-seat.d.ts +2 -0
  206. package/dist/core/runner/credential-refusal-seat.js +47 -0
  207. package/dist/core/runner/cross-boundary-lane.js +6 -4
  208. package/dist/core/runner/decide-continuation.js +1 -1
  209. package/dist/core/runner/file-history-restore.d.ts +53 -2
  210. package/dist/core/runner/file-history-restore.js +29 -10
  211. package/dist/core/runner/forward-sink.d.ts +14 -1
  212. package/dist/core/runner/forward-sink.js +14 -12
  213. package/dist/core/runner/gate-exit.d.ts +8 -7
  214. package/dist/core/runner/gate-exit.js +13 -13
  215. package/dist/core/runner/git-status-frame.js +2 -4
  216. package/dist/core/runner/initial-run-state.js +1 -1
  217. package/dist/core/runner/main-call-account.d.ts +3 -1
  218. package/dist/core/runner/main-call-account.js +5 -3
  219. package/dist/core/runner/mcp-redial.d.ts +2 -5
  220. package/dist/core/runner/mcp-redial.js +2 -2
  221. package/dist/core/runner/nested-memory-content.d.ts +7 -1
  222. package/dist/core/runner/nested-memory-content.js +73 -13
  223. package/dist/core/runner/nested-memory-lane.d.ts +44 -19
  224. package/dist/core/runner/nested-memory-lane.js +152 -76
  225. package/dist/core/runner/park-commit.js +3 -1
  226. package/dist/core/runner/permission-rule-lanes.d.ts +8 -2
  227. package/dist/core/runner/permission-rule-lanes.js +29 -3
  228. package/dist/core/runner/person-path-rows.d.ts +3 -11
  229. package/dist/core/runner/person-path-rows.js +21 -24
  230. package/dist/core/runner/prepare-acquire-reconcile.js +3 -1
  231. package/dist/core/runner/prepare-artifact.d.ts +1 -1
  232. package/dist/core/runner/prepare-artifact.js +20 -14
  233. package/dist/core/runner/prepare-ask-lane.d.ts +9 -6
  234. package/dist/core/runner/prepare-ask-lane.js +6 -5
  235. package/dist/core/runner/prepare-boundary-parks.d.ts +7 -1
  236. package/dist/core/runner/prepare-boundary-parks.js +27 -24
  237. package/dist/core/runner/prepare-caps-and-workflow.d.ts +5 -2
  238. package/dist/core/runner/prepare-caps-and-workflow.js +4 -3
  239. package/dist/core/runner/prepare-config-doors.d.ts +9 -24
  240. package/dist/core/runner/prepare-config-doors.js +58 -41
  241. package/dist/core/runner/prepare-context-lane.d.ts +2 -2
  242. package/dist/core/runner/prepare-context-lane.js +3 -5
  243. package/dist/core/runner/prepare-defer-classify.d.ts +1 -1
  244. package/dist/core/runner/prepare-defer-classify.js +1 -1
  245. package/dist/core/runner/prepare-delegation-surface.d.ts +2 -2
  246. package/dist/core/runner/prepare-delegation-surface.js +3 -2
  247. package/dist/core/runner/prepare-file-history.d.ts +62 -26
  248. package/dist/core/runner/prepare-file-history.js +117 -46
  249. package/dist/core/runner/prepare-gate-stations.d.ts +4 -0
  250. package/dist/core/runner/prepare-gate-stations.js +6 -5
  251. package/dist/core/runner/prepare-hands-readface.d.ts +9 -4
  252. package/dist/core/runner/prepare-hands-readface.js +8 -4
  253. package/dist/core/runner/prepare-inherited-gate.d.ts +11 -4
  254. package/dist/core/runner/prepare-inherited-gate.js +6 -6
  255. package/dist/core/runner/prepare-listings.d.ts +1 -1
  256. package/dist/core/runner/prepare-listings.js +1 -1
  257. package/dist/core/runner/prepare-memory.js +2 -2
  258. package/dist/core/runner/prepare-offload-wrappers.d.ts +1 -1
  259. package/dist/core/runner/prepare-offload-wrappers.js +1 -1
  260. package/dist/core/runner/prepare-park-ask.d.ts +10 -3
  261. package/dist/core/runner/prepare-park-ask.js +7 -9
  262. package/dist/core/runner/prepare-policy-chain.d.ts +18 -9
  263. package/dist/core/runner/prepare-policy-chain.js +18 -13
  264. package/dist/core/runner/prepare-project-context.d.ts +1 -1
  265. package/dist/core/runner/prepare-project-context.js +5 -3
  266. package/dist/core/runner/prepare-prompt-assembly.js +2 -1
  267. package/dist/core/runner/prepare-prompt-inputs.d.ts +2 -2
  268. package/dist/core/runner/prepare-prompt-inputs.js +1 -1
  269. package/dist/core/runner/prepare-protocol-tools.d.ts +4 -5
  270. package/dist/core/runner/prepare-protocol-tools.js +7 -7
  271. package/dist/core/runner/prepare-question-face.d.ts +4 -2
  272. package/dist/core/runner/prepare-run-refs.d.ts +7 -2
  273. package/dist/core/runner/prepare-run-refs.js +8 -7
  274. package/dist/core/runner/prepare-safety-scan.d.ts +4 -3
  275. package/dist/core/runner/prepare-suspend-saga.d.ts +3 -7
  276. package/dist/core/runner/prepare-suspend-saga.js +4 -3
  277. package/dist/core/runner/prepare-task.js +66 -53
  278. package/dist/core/runner/prepare-tool-disclosure-mount.d.ts +3 -2
  279. package/dist/core/runner/prepare-tool-disclosure-mount.js +2 -1
  280. package/dist/core/runner/prepare-turn-wiring.d.ts +3 -1
  281. package/dist/core/runner/prepare-turn-wiring.js +1 -1
  282. package/dist/core/runner/prepare-wiring-manifest.d.ts +9 -4
  283. package/dist/core/runner/prepare-wiring-manifest.js +14 -6
  284. package/dist/core/runner/prepare-workspace-restore.d.ts +4 -4
  285. package/dist/core/runner/prepare-workspace-restore.js +15 -6
  286. package/dist/core/runner/remote-env-retry.d.ts +3 -3
  287. package/dist/core/runner/restore-seat.d.ts +41 -0
  288. package/dist/core/runner/restore-seat.js +38 -0
  289. package/dist/core/runner/resume-admission.js +1 -1
  290. package/dist/core/runner/resume-apply.js +4 -3
  291. package/dist/core/runner/resume-checkpoint-screen.js +2 -1
  292. package/dist/core/runner/resume-internals-and-config.js +2 -1
  293. package/dist/core/runner/resume-preflight.js +2 -1
  294. package/dist/core/runner/rewind-files.js +22 -6
  295. package/dist/core/runner/rule-store-unreadable-notice.d.ts +8 -0
  296. package/dist/core/runner/rule-store-unreadable-notice.js +11 -0
  297. package/dist/core/runner/run-brain-sinks.d.ts +3 -6
  298. package/dist/core/runner/run-brain-sinks.js +6 -6
  299. package/dist/core/runner/run-compaction-machinery.d.ts +2 -2
  300. package/dist/core/runner/run-git-lane.d.ts +2 -0
  301. package/dist/core/runner/run-git-lane.js +2 -1
  302. package/dist/core/runner/run-harness-handlers.js +5 -4
  303. package/dist/core/runner/run-identity-wiring.js +20 -12
  304. package/dist/core/runner/run-leg.js +31 -72
  305. package/dist/core/runner/run-notification-lane.d.ts +3 -0
  306. package/dist/core/runner/run-notification-lane.js +2 -4
  307. package/dist/core/runner/run-reasoning-seat.d.ts +5 -6
  308. package/dist/core/runner/run-reasoning-seat.js +13 -18
  309. package/dist/core/runner/run-settle-and-teardown.js +13 -9
  310. package/dist/core/runner/run-terminal-adoption.js +4 -8
  311. package/dist/core/runner/run-turn-boundary.js +6 -3
  312. package/dist/core/runner/runtask.d.ts +9 -4
  313. package/dist/core/runner/runtask.js +29 -22
  314. package/dist/core/runner/session-rule-policy.d.ts +11 -1
  315. package/dist/core/runner/shell-env-withheld.js +2 -7
  316. package/dist/core/runner/side-call-account.d.ts +5 -6
  317. package/dist/core/runner/side-call-account.js +2 -2
  318. package/dist/core/runner/stream-lifecycle-verbs.d.ts +3 -0
  319. package/dist/core/runner/stream-lifecycle-verbs.js +5 -3
  320. package/dist/core/runner/stream-settle-backstop.js +4 -6
  321. package/dist/core/runner/stream-steer-verb.d.ts +1 -1
  322. package/dist/core/runner/stream-steer-verb.js +4 -4
  323. package/dist/core/runner/sub-agent-deny-lists.d.ts +8 -3
  324. package/dist/core/runner/sub-agent-deny-lists.js +7 -4
  325. package/dist/core/runner/teardown-bounded.d.ts +7 -0
  326. package/dist/core/runner/teardown-bounded.js +7 -0
  327. package/dist/core/runner/terminal-account.js +41 -13
  328. package/dist/core/runner/terminal-projection.d.ts +1 -5
  329. package/dist/core/runner/tool-end-body.d.ts +9 -3
  330. package/dist/core/runner/tool-end-body.js +6 -3
  331. package/dist/core/runner/tool-output-projection.d.ts +13 -4
  332. package/dist/core/runner/tool-output-projection.js +10 -14
  333. package/dist/core/runner/turn-attachments.d.ts +3 -2
  334. package/dist/core/runner/turn-attachments.js +12 -5
  335. package/dist/core/runner-deps.d.ts +6 -6
  336. package/dist/core/runtime-caps.d.ts +2 -1
  337. package/dist/core/secret-env.d.ts +20 -3
  338. package/dist/core/secret-env.js +13 -15
  339. package/dist/core/session-checkout.d.ts +115 -15
  340. package/dist/core/session-checkout.js +435 -136
  341. package/dist/core/session-policy-store.js +21 -3
  342. package/dist/core/session-reconcile.js +1 -0
  343. package/dist/core/session-store.js +2 -0
  344. package/dist/core/session.d.ts +11 -1
  345. package/dist/core/shell-run-candidates.d.ts +1 -0
  346. package/dist/core/shell-run-candidates.js +1 -1
  347. package/dist/core/shutdown-debug.d.ts +6 -5
  348. package/dist/core/shutdown-debug.js +5 -1
  349. package/dist/core/skill-grant.js +4 -1
  350. package/dist/core/skills-directory.js +5 -3
  351. package/dist/core/spec-contract.d.ts +1 -1
  352. package/dist/core/store-contracts/checkpoint-store-contract.js +2 -7
  353. package/dist/core/store-contracts/file-history-store-contract.js +26 -2
  354. package/dist/core/store-contracts/session-deletion-cascade-contract.js +130 -14
  355. package/dist/core/store-contracts/task-list-store-contract.d.ts +2 -1
  356. package/dist/core/store-contracts/task-list-store-contract.js +28 -1
  357. package/dist/core/task-event.d.ts +48 -27
  358. package/dist/core/task-notification.d.ts +15 -9
  359. package/dist/core/task-notification.js +12 -0
  360. package/dist/core/task-registry-agent.d.ts +24 -22
  361. package/dist/core/task-registry-agent.js +65 -46
  362. package/dist/core/task-registry-shared.d.ts +17 -5
  363. package/dist/core/task-registry.d.ts +17 -6
  364. package/dist/core/task-registry.js +6 -1
  365. package/dist/core/task-result.d.ts +71 -25
  366. package/dist/core/task-spec-members.d.ts +0 -1
  367. package/dist/core/task-spec-members.js +1 -1
  368. package/dist/core/task-spec.d.ts +60 -52
  369. package/dist/core/task-stream.d.ts +45 -12
  370. package/dist/core/terminal-cause.d.ts +45 -8
  371. package/dist/core/terminal-cause.js +5 -0
  372. package/dist/core/tool-card-bound.d.ts +32 -0
  373. package/dist/core/tool-card-bound.js +33 -0
  374. package/dist/core/tool-catalog-entries.d.ts +9 -0
  375. package/dist/core/tool-catalog-entries.js +48 -0
  376. package/dist/core/tool-errors.d.ts +4 -3
  377. package/dist/core/tool-face.d.ts +3 -3
  378. package/dist/core/tool-mount-facts.d.ts +3 -2
  379. package/dist/core/tool-mount-facts.js +1 -1
  380. package/dist/core/tool-mount-static.js +7 -5
  381. package/dist/core/tool-policy.d.ts +21 -19
  382. package/dist/core/tool-policy.js +5 -6
  383. package/dist/core/tool-registry.d.ts +3 -1
  384. package/dist/core/tool-registry.js +15 -1
  385. package/dist/core/tool-result-store.d.ts +9 -3
  386. package/dist/core/tool-result-store.js +14 -1
  387. package/dist/core/tool-roster.d.ts +18 -0
  388. package/dist/core/tool-roster.js +30 -1
  389. package/dist/core/tool-spec.d.ts +17 -8
  390. package/dist/core/trace.d.ts +35 -31
  391. package/dist/core/types.d.ts +2 -2
  392. package/dist/core/untrusted-egress.d.ts +10 -9
  393. package/dist/core/untrusted-egress.js +9 -9
  394. package/dist/core/untrusted-text.d.ts +0 -18
  395. package/dist/core/untrusted-text.js +7 -3
  396. package/dist/core/user-attachment.d.ts +9 -6
  397. package/dist/core/user-attachment.js +12 -10
  398. package/dist/core/user-row-origin.d.ts +44 -25
  399. package/dist/core/user-row-origin.js +30 -20
  400. package/dist/core/wiring-manifest.d.ts +26 -7
  401. package/dist/core/wiring-manifest.js +14 -11
  402. package/dist/core/workspace-snapshot.d.ts +3 -1
  403. package/dist/core/workspace-snapshot.js +1 -0
  404. package/dist/engine/execution-env/node-execution-env.d.ts +23 -16
  405. package/dist/engine/execution-env/node-execution-env.js +127 -67
  406. package/dist/engine/harness/agent-harness.d.ts +4 -5
  407. package/dist/engine/harness/agent-harness.js +2 -7
  408. package/dist/engine/harness/types.d.ts +51 -19
  409. package/dist/engine/harness/types.js +28 -1
  410. package/dist/engine/llm/types.d.ts +26 -14
  411. package/dist/engine/llm/types.js +2 -2
  412. package/dist/engine/loop/agent-loop.d.ts +2 -2
  413. package/dist/engine/loop/agent-loop.js +51 -275
  414. package/dist/engine/loop/types.d.ts +0 -18
  415. package/dist/engine/session/import-validate.d.ts +3 -0
  416. package/dist/engine/session/import-validate.js +34 -2
  417. package/dist/engine/session/repo-utils.d.ts +42 -4
  418. package/dist/engine/session/repo-utils.js +33 -5
  419. package/dist/engine/session/session.d.ts +41 -14
  420. package/dist/engine/session/session.js +96 -25
  421. package/dist/index.d.ts +21 -16
  422. package/dist/index.js +16 -10
  423. package/dist/orchestration/run-spec.d.ts +1 -1
  424. package/dist/orchestration/run-workflow-tool.d.ts +12 -9
  425. package/dist/orchestration/run-workflow-tool.js +15 -19
  426. package/dist/orchestration/workflow-governance.js +13 -21
  427. package/dist/orchestration/workflow-observe.d.ts +4 -3
  428. package/dist/orchestration/workflow-primitives.d.ts +1 -1
  429. package/dist/orchestration/workflow-record-artifact.d.ts +14 -0
  430. package/dist/orchestration/workflow-record-artifact.js +32 -0
  431. package/dist/orchestration/workflow-script-store.d.ts +9 -0
  432. package/dist/orchestration/workflow-script-store.js +20 -1
  433. package/dist/orchestration/workflow-types.d.ts +33 -3
  434. package/dist/orchestration/workflow.d.ts +24 -14
  435. package/dist/orchestration/workflow.js +52 -23
  436. package/dist/prompt-assembly/artifact.js +4 -8
  437. package/dist/prompt-assembly/catalog/engine.d.ts +263 -0
  438. package/dist/prompt-assembly/catalog/engine.js +30 -0
  439. package/dist/prompt-assembly/catalog/index.d.ts +1 -1
  440. package/dist/prompt-assembly/catalog/index.js +2 -2
  441. package/dist/prompt-assembly/catalog/locales/zh-Hans/engine.d.ts +1 -1
  442. package/dist/prompt-assembly/catalog/locales/zh-Hans/engine.js +29 -0
  443. package/dist/prompt-assembly/epoch.js +6 -8
  444. package/dist/prompt-assembly/turn-snapshot.js +8 -9
  445. package/dist/stores/file/background-agent-store.js +5 -6
  446. package/dist/stores/file/checkpoint-store.d.ts +0 -4
  447. package/dist/stores/file/checkpoint-store.js +7 -3
  448. package/dist/stores/file/file-history-store.d.ts +8 -0
  449. package/dist/stores/file/file-history-store.js +72 -0
  450. package/dist/stores/file/fs-atomic.js +17 -12
  451. package/dist/stores/file/index.js +11 -5
  452. package/dist/stores/file/mailbox-store.js +13 -4
  453. package/dist/stores/file/permission-rule-store.js +14 -13
  454. package/dist/stores/file/shared-ledger.d.ts +4 -0
  455. package/dist/stores/file/shared-ledger.js +4 -0
  456. package/dist/stores/file/task-list-store.js +12 -3
  457. package/dist/stores/file/workflow-run-store.js +1 -0
  458. package/dist/tools/fs/bash-program-position.d.ts +4 -2
  459. package/dist/tools/fs/bash-program-position.js +1 -1
  460. package/dist/tools/fs/bash-readonly-classifier.js +1 -1
  461. package/dist/tools/fs/bound-open.d.ts +97 -0
  462. package/dist/tools/fs/bound-open.js +103 -0
  463. package/dist/tools/fs/containment-face.d.ts +2 -2
  464. package/dist/tools/fs/fs-pdf.d.ts +7 -1
  465. package/dist/tools/fs/fs-pdf.js +31 -23
  466. package/dist/tools/fs/fs-read.d.ts +24 -17
  467. package/dist/tools/fs/fs-read.js +84 -53
  468. package/dist/tools/fs/fs-shared.d.ts +14 -12
  469. package/dist/tools/fs/fs-shared.js +5 -4
  470. package/dist/tools/fs/fs-write.d.ts +2 -2
  471. package/dist/tools/fs/fs-write.js +20 -12
  472. package/dist/tools/fs/index.d.ts +4 -4
  473. package/dist/tools/fs/index.js +2 -2
  474. package/dist/tools/fs/notebook.d.ts +1 -1
  475. package/dist/tools/fs/pdf.d.ts +12 -3
  476. package/dist/tools/fs/pdf.js +22 -9
  477. package/dist/tools/fs/read-deny-home.d.ts +3 -2
  478. package/dist/tools/fs/read-deny-home.js +8 -11
  479. package/dist/tools/fs/safety.d.ts +3 -2
  480. package/dist/tools/fs/shell-read-check.js +10 -9
  481. package/dist/tools/monitor.d.ts +6 -5
  482. package/dist/tools/task-list.d.ts +16 -6
  483. package/dist/tools/task-list.js +4 -0
  484. package/dist/tools/web.d.ts +9 -1
  485. package/dist/tools/web.js +8 -3
  486. package/dist/tools/worktree.d.ts +7 -5
  487. package/dist/tools/worktree.js +4 -3
  488. package/package.json +4 -3
  489. package/test/export-surface.snapshot.json +93 -7
  490. package/wire-changes/core-stores-sql@7.68.0.json +39 -0
  491. package/wire-changes/core-stores-sql@7.68.1.json +39 -0
  492. package/wire-changes/core@7.68.0.json +4257 -0
  493. package/wire-changes/core@7.68.1.json +95 -0
  494. package/wire-changes/mods-kernel@7.68.0.json +129 -0
  495. package/wire-changes/mods-kernel@7.68.1.json +39 -0
  496. package/wire-changes/primitives@7.68.0.json +253 -0
  497. package/wire-changes/primitives@7.68.1.json +39 -0
  498. package/wire-changes/wiki-gate@7.68.0.json +39 -0
  499. package/wire-changes/wiki-gate@7.68.1.json +39 -0
  500. package/dist/core/runner/credential-origin-seat.d.ts +0 -2
  501. package/dist/core/runner/credential-origin-seat.js +0 -20
@@ -0,0 +1,53 @@
1
+ /**
2
+ * THE AUTO STRIP's one judgment: whether auto mode stands an allow entry down — so it clears no call and the calls it names go to
3
+ * the classifier — and why. The reference implementation drops these allow rules from every source before matching in auto mode:
4
+ * the whole shell tool; a shell rule whose content is empty or all `*`; and a shell rule naming one of the programs that run
5
+ * arbitrary code ({@link AUTO_STRIPPED_PROGRAMS}) in one of five spellings — `X`, `X:*`, `X *`, `X*`, or `X -…*` (an option-led open
6
+ * tail; python's `-m dotted.module` is the one exception). Three adaptations the reference has no case for: a whole-tool entry is
7
+ * stripped when the call answers, under ANY of its names, to the shell (an alias reaches the same tool), a compound-prefix rule
8
+ * (`cd /tmp && npm run:*`) is judged by its final segment — the one left open, and a pattern rule (`node * x.js`, `nice python * y`)
9
+ * is stripped when the run it names — its program read past the launchers in front of it, by basename — could be one of those
10
+ * programs, or when that program word is itself open or cannot be read. A leg that declares `TaskSpec.classifyAllShell` widens the
11
+ * strip to EVERY shell entry — the reference's `autoMode.classifyAllShell`.
12
+ *
13
+ * Every reader takes this one function: the allow layer per call (`allow-entry.ts`, through the call's one fact it needs — does
14
+ * the call answer to the shell), and the rule read faces judged without a run (no call, no declaration) — the store's rows
15
+ * (`EffectivePermissionRule.autoStrip`) and a list entry (`allowEntryAutoStrip`). A leaf: it reads no lane and no store.
16
+ */
17
+ import type { CompiledAllowEntry } from "./allow-entry.js";
18
+ import { type PersistedRule } from "./permission-rule-model.js";
19
+ /** The programs whose open allow rule the reference implementation drops in auto mode — its interpreter / launcher table
20
+ * plus the shells and the run-anything builtins. A program that only reaches the network is not here. */
21
+ export declare const AUTO_STRIPPED_PROGRAMS: readonly ["python", "python3", "python2", "node", "deno", "tsx", "ruby", "perl", "php", "lua", "npx", "bunx", "npm run", "yarn run", "pnpm run", "bun run", "bash", "sh", "ssh", "zsh", "fish", "eval", "exec", "env", "xargs", "sudo"];
22
+ /**
23
+ * Why auto mode stands an allow entry down — the strip's three cases, named: `whole_shell` (the entry reaches every shell
24
+ * command: the whole shell tool, a shell rule whose content is empty or all `*`, a whole-tool entry the call reaches the shell
25
+ * through under another name), `code_runner` (the entry opens a program that runs whatever code it is given —
26
+ * {@link AUTO_STRIPPED_PROGRAMS}, or a pattern whose run could be one), `classify_all_shell` (the leg declared
27
+ * `TaskSpec.classifyAllShell`: every shell entry stands down, whatever it names).
28
+ */
29
+ export declare const AUTO_STRIP_REASONS: readonly ["whole_shell", "code_runner", "classify_all_shell"];
30
+ export type AutoStripReason = (typeof AUTO_STRIP_REASONS)[number];
31
+ /** The reasons a rule read face carries: judged without a run, so never the leg's declaration. */
32
+ export type AutoStripRowReason = Exclude<AutoStripReason, "classify_all_shell">;
33
+ /**
34
+ * Does auto mode stand this allow entry down, and why — `undefined` ⇒ kept. The one fact of the call it reads is whether the call
35
+ * answers to the shell under any of its names (`callAnswersToShell`; asked only where it decides, and `false` for a judgment
36
+ * without a call). `allShell`: the leg declared `TaskSpec.classifyAllShell` — every shell command rule stands down, whatever it
37
+ * names, and no entry of any kind clears a call that answers to the shell (the reference suspends every shell allow rule under that
38
+ * setting without reading its content; a path rule a shell-face tool's declared target reaches is one here).
39
+ */
40
+ export declare function autoStripReasonOf(compiled: CompiledAllowEntry, callAnswersToShell: () => boolean, allShell: boolean): AutoStripReason | undefined;
41
+ /** The run-less reading a rule read face carries: no call, no declaration — so never `classify_all_shell`. */
42
+ export declare function readFaceAutoStrip(compiled: CompiledAllowEntry): AutoStripRowReason | undefined;
43
+ /** The list entry a stored row is the twin of: a whole-tool row is the whole tool (the shell's own kind on the shell face), every
44
+ * other row the content kind of its tool's grammar. A row is stripped exactly when the entry spelling the same rule is. */
45
+ export declare function entryOfRow(rule: PersistedRule): CompiledAllowEntry | undefined;
46
+ /** Does a stored row's TEXT read as an allow rule — the rows the person's lane can grant by (one that does not grants nothing in any
47
+ * mode, so auto mode takes nothing from it)? The row as that reading reads it, else `undefined`. */
48
+ export declare function storedAllowRowRead(rule: Pick<PersistedRule, "behavior" | "rule" | "scope" | "adds">): PersistedRule | undefined;
49
+ /** The read face's reading of a person's stored row ({@link readFaceAutoStrip} over the twin of the row its text reads as): an allow
50
+ * row whose text reads as an allow rule only — a deny / ask row is never stripped, and a row that grants nothing in any mode has
51
+ * nothing for auto mode to take. Read off the text, never the row's other fields, so a malformed row a foreign backend served
52
+ * answers `undefined` instead of failing the store's read. What `EffectivePermissionRule.autoStrip` carries. */
53
+ export declare function storedRowAutoStrip(rule: PersistedRule): AutoStripRowReason | undefined;
@@ -0,0 +1,76 @@
1
+ import { commandPatternMayRun, parseRuleText, ruleToolGrammarOf } from "./permission-rule-model.js";
2
+ import { isShellFaceToolName } from "./tool-registry.js";
3
+ import { splitShellCompoundSegments } from "../tools/fs/bash-readonly-classifier.js";
4
+ export const AUTO_STRIPPED_PROGRAMS = Object.freeze([
5
+ "python", "python3", "python2", "node", "deno", "tsx", "ruby", "perl", "php", "lua", "npx", "bunx", "npm run", "yarn run", "pnpm run", "bun run", "bash", "sh", "ssh",
6
+ "zsh", "fish", "eval", "exec", "env", "xargs", "sudo",
7
+ ]);
8
+ export const AUTO_STRIP_REASONS = Object.freeze(["whole_shell", "code_runner", "classify_all_shell"]);
9
+ function shellContentStripped(content) {
10
+ if (content === undefined || content === "" || /^[\s*]+$/.test(content))
11
+ return "whole_shell";
12
+ const n = content.trim().toLowerCase();
13
+ if (n === "*")
14
+ return "whole_shell";
15
+ for (const program of AUTO_STRIPPED_PROGRAMS) {
16
+ const g = program.toLowerCase();
17
+ if (n === g || n === `${g}:*` || n === `${g} *` || n === `${g}*`)
18
+ return "code_runner";
19
+ if (n.startsWith(`${g} `) && n.endsWith("*")) {
20
+ const tail = n.slice(g.length + 1);
21
+ if (tail.startsWith("-") && !(/^python[\d.]*$/.test(g) && /^-m\s+\w+\.[\w.]+(\s*:|\s+)$/.test(tail.slice(0, -1))))
22
+ return "code_runner";
23
+ }
24
+ }
25
+ return undefined;
26
+ }
27
+ function shellRuleContent(rule) {
28
+ const split = splitShellCompoundSegments(rule.command, { trailingTerminator: "keep", redirection: "reject" });
29
+ const body = "reject" in split ? rule.command : (split.segments[split.segments.length - 1] ?? rule.command).trim();
30
+ return rule.match === "prefix" ? `${body}:*` : rule.match === "wildcard" ? `${body} *` : body;
31
+ }
32
+ export function autoStripReasonOf(compiled, callAnswersToShell, allShell) {
33
+ switch (compiled.kind) {
34
+ case "shell":
35
+ return allShell ? "classify_all_shell" : "whole_shell";
36
+ case "tool":
37
+ return callAnswersToShell() ? (allShell ? "classify_all_shell" : "whole_shell") : undefined;
38
+ case "command":
39
+ if (allShell)
40
+ return "classify_all_shell";
41
+ if (compiled.rule.match === "pattern")
42
+ return commandPatternMayRun(compiled.rule.command, AUTO_STRIPPED_PROGRAMS) ? "code_runner" : undefined;
43
+ return shellContentStripped(shellRuleContent(compiled.rule));
44
+ case "covering":
45
+ case "path":
46
+ case "name":
47
+ case "domain":
48
+ return allShell && callAnswersToShell() ? "classify_all_shell" : undefined;
49
+ default: {
50
+ const exhaustive = compiled;
51
+ return exhaustive;
52
+ }
53
+ }
54
+ }
55
+ const NO_CALL = () => false;
56
+ export function readFaceAutoStrip(compiled) {
57
+ const reason = autoStripReasonOf(compiled, NO_CALL, false);
58
+ return reason === "classify_all_shell" ? undefined : reason;
59
+ }
60
+ export function entryOfRow(rule) {
61
+ if (rule.match === "tool")
62
+ return isShellFaceToolName(rule.tool) ? { kind: "shell", name: rule.tool } : { kind: "tool", name: rule.tool };
63
+ const grammar = ruleToolGrammarOf(rule.tool);
64
+ return grammar === undefined ? undefined : { kind: grammar, rule };
65
+ }
66
+ export function storedAllowRowRead(rule) {
67
+ if (rule.behavior !== "allow" || typeof rule.rule !== "string")
68
+ return undefined;
69
+ const read = parseRuleText(rule.rule, "allow");
70
+ return "reject" in read ? undefined : { ...read.rule, scope: rule.scope, adds: rule.adds };
71
+ }
72
+ export function storedRowAutoStrip(rule) {
73
+ const read = storedAllowRowRead(rule);
74
+ const entry = read === undefined ? undefined : entryOfRow(read);
75
+ return entry === undefined ? undefined : readFaceAutoStrip(entry);
76
+ }
@@ -114,8 +114,11 @@ export interface BackgroundAgentRecord {
114
114
  * with no live handle (the store-only reconciliation, the stale-running reap) mints it through the same
115
115
  * fill-once `mintCompletionId` — one minter either way. */
116
116
  completionId?: string;
117
- /** design/144 §1.1 dedup-key continuity (LOW-15): revival cycles re-mint seq FROM the stored value,
118
- * so `task_id:status:seq` keys never collide across restarts. */
117
+ /** The row's stop-cycle number: 1 from the registration's first write, and one step past the stored value
118
+ * ({@link nextCycleSeq}) in the very write of each claim that opens a cycle — the retained wake's, the tier-3 and
119
+ * drain revivals', the parked-resume consume flip's. No other write touches it, so every lane's next cycle reads the
120
+ * number the last claim left, and `task_id:status:seq` keys never repeat for one row (across lanes and restarts).
121
+ * Absent only on a row an older version wrote before its first settle. */
119
122
  seq?: number;
120
123
  /**
121
124
  * design/153 §7.1 — the checkpoint token this row is parked ON (any gate; `status:"parked"`
@@ -157,6 +160,9 @@ export interface BackgroundAgentRecord {
157
160
  errorKind?: string;
158
161
  errorRetryAfterMs?: number;
159
162
  resultIsPartial?: boolean;
163
+ /** What the agent did NOT get done: its run's `TaskResult.refusedAsks` (asks nobody could answer, refused), written by the terminal
164
+ * settle beside `status` (a refused ask leaves the status `completed`). Present only when at least one ask was refused. */
165
+ refusedAsks?: import("./task-result.js").RefusedAsk[];
160
166
  recentSteps?: SubagentStep[];
161
167
  editedFiles?: SubagentEditedFile[];
162
168
  usage?: BackgroundAgentUsage;
@@ -210,9 +216,16 @@ export interface BackgroundAgentRecord {
210
216
  * birth floor (`policyFloor`) are in the governance group on purpose: clearing either would hand the
211
217
  * next cycle a blank slate, which is the widening each exists to prevent.
212
218
  */
213
- export declare const REVIVED_ROW_CLEARED_FIELDS: readonly ["settledAt", "stoppedBy", "completionId", "finalOutput", "finalOutputFull", "error", "errorCode", "errorRetryable", "errorKind", "errorRetryAfterMs", "resultIsPartial", "summary", "recentSteps", "editedFiles", "usage"];
219
+ export declare const REVIVED_ROW_CLEARED_FIELDS: readonly ["settledAt", "stoppedBy", "completionId", "finalOutput", "finalOutputFull", "error", "errorCode", "errorRetryable", "errorKind", "errorRetryAfterMs", "resultIsPartial", "refusedAsks", "summary", "recentSteps", "editedFiles", "usage"];
214
220
  /** Erase {@link REVIVED_ROW_CLEARED_FIELDS} from a record a revival is about to write back. */
215
221
  export declare function clearRevivedRowTerminalPayload(record: BackgroundAgentRecord): void;
222
+ /** The stop-cycle number a wake opens on a row: one past the row's, written by the claim that opens the cycle, in
223
+ * that same write (so of two claims on one row only the winner's number exists). The one place it is computed — the
224
+ * retained wake, the tier-3 and drain revivals and the parked-resume consume flip all call it; a row with no stored
225
+ * row (a store-less registration) passes its registry handle's number, which is that row. */
226
+ export declare function nextCycleSeq(row: {
227
+ readonly seq?: number;
228
+ }): number;
216
229
  /**
217
230
  * Whether a deployment's subagent transcript tier DECLARES that a finished agent's transcript outlives the process — the one tier a vanished
218
231
  * transcript contradicts. `full` makes that promise; `rows` keeps the agent's record but says transcripts follow the session store's fate (a
@@ -274,7 +287,8 @@ export declare const BACKGROUND_AGENT_ROW_MALFORMED_CODE = "agent_record.row_mal
274
287
  * THE BACKGROUND AGENT ROW'S MEMBER-SHAPE TABLE (`rowShapeReader`, row-shape.ts). `rowKey` is the file ledger's row predicate (a
275
288
  * string handle and scope: the row's key). `members` is what the readers reach for: the owner and the session anchors (the access
276
289
  * predicate and the session listing read them), the status word, the stamps, the revision and the writer's generation (the CAS
277
- * compares them and bumps them — a stored revision that is no count is refused, never incremented), the claim and park bindings,
290
+ * compares them and bumps them — a stored revision that is no count is refused, never incremented), the stop-cycle number (the
291
+ * one mint steps it — a stored `seq` that is no cycle number is refused, never stepped), the claim and park bindings,
278
292
  * the display members, and `name` — whose ABSENCE reads as the name the engine derives from the handle (`engineAgentName`; a row
279
293
  * without a name whose handle derives none does not read). `requestedBy` is read by its own reader (a value it does not read is
280
294
  * no requester). The write gate also holds a candidate to a non-empty scope (a row without one is world-readable through the
@@ -449,6 +463,25 @@ export interface BackgroundAgentStore {
449
463
  /** Retention sweep for `scope` (explicit policy, see interface notes). Returns rows deleted+flipped. */
450
464
  reap(scope: string, now: number, opts?: BackgroundAgentReapOptions): Promise<number>;
451
465
  }
466
+ /** What a parked row's approval card is, as the checkpoint store states it. `unreadable` = no read of the store could say. */
467
+ export type ParkedCardState = "pending" | "resolved" | "expired" | "missing" | "unreadable";
468
+ /** The store seat the card-state reader needs: the body read every store has, and the body-tolerant session listing a store may offer. */
469
+ export type ParkedCardStore = Pick<import("./checkpoint-store.js").CheckpointStore, "get"> & Partial<Pick<import("./checkpoint-store.js").CheckpointStore, "listBySession">>;
470
+ /**
471
+ * THE reader of a parked row's card state — both halves of the reconciliation (this module's store sweep and the registry's live sweep)
472
+ * ask it, and nothing else decides what state a card is in. The state is the store's word: the body read answers it when the body
473
+ * decodes; when the body does not (the read throws, or the card carries no state word) the store's own body-tolerant listing
474
+ * (`listBySession` — a row it cannot read is listed `unreadable` with the status as stored) answers it. A card neither read can speak for is
475
+ * `unreadable`, which the sweeps treat as "touch nothing"; it is announced once per (scope, handle) per process, as `delegation.parked_card_unreadable` on the default notice seat — a voided card
476
+ * whose body is lost never stops being unreadable, and a sweep that skips it every cadence in silence leaves the row parked for good.
477
+ * The announcement names the agent, never the card's token (a resume capability).
478
+ */
479
+ export declare function parkedCardState(store: ParkedCardStore, card: {
480
+ token: string;
481
+ handle: string;
482
+ scope: string;
483
+ sessionId: string | undefined;
484
+ }): Promise<ParkedCardState>;
452
485
  /**
453
486
  * design/153 §7.1 (r4 F-03) — the parked-row ↔ checkpoint reconciliation sweep. `parked` rows are
454
487
  * reap-exempt (their writer does not heartbeat), so WITHOUT this sweep an expired/removed approval
@@ -480,7 +513,7 @@ export interface BackgroundAgentStore {
480
513
  */
481
514
  export declare function reconcileParkedAgents(stores: {
482
515
  agentStore: BackgroundAgentStore;
483
- checkpointStore: Pick<import("./checkpoint-store.js").CheckpointStore, "get">;
516
+ checkpointStore: ParkedCardStore;
484
517
  }, scope: string, now: number, opts?: {
485
518
  staleClaimMaxAgeMs?: number;
486
519
  excludeWriterId?: string;
@@ -568,6 +601,13 @@ export declare function nextBackgroundAgentOnUpdate(live: BackgroundAgentRecord
568
601
  /** The row a stale-running sweep flips to `failed`, or `undefined` when it does not flip: not a running row of the scope, not
569
602
  * stale, or a row that does not read (told to `disclose`, and left as stored). Every backend's one reading of arm 1. */
570
603
  export declare function staleRunningFlip(live: BackgroundAgentRecord | undefined, key: string, scope: string, now: number, staleMs: number, disclose?: (sentence: string) => void): BackgroundAgentRecord | undefined;
604
+ /** The form a stale running row flips to — THE one writing of it: `failed`, stopped by the system, the shared attribution on `error`
605
+ * and `summary` (each only where the row carries none), settled and updated at `now`, and the completion identity minted
606
+ * (fill-once) — a terminal write with no live handle is where that completion is born. PURE: a copy is returned, `live` is not
607
+ * touched. It judges nothing: `live` is a row that READS and is running, and that the caller found stale. `rev` is the live
608
+ * row's own — the store places the next one (an `update` CAS does; {@link staleRunningFlip} does for the sweep that writes in
609
+ * place). A SQL twin whose staleness is a column predicate writes the flip through this instead of a hand copy. */
610
+ export declare function staleRunningFlipOf(live: BackgroundAgentRecord, now: number): BackgroundAgentRecord;
571
611
  /** A terminal-retention candidate: a terminal row of the scope whose stamps read — its key, spawn time and settle (else spawn) time. */
572
612
  export interface BackgroundAgentReapCandidate {
573
613
  readonly key: string;
@@ -2,6 +2,7 @@ import { mintCompletionId } from "./completion-id.js";
2
2
  import { receiveRetentionPolicy } from "./retention-policy.js";
3
3
  import { readExtensionRequester } from "./extension-requester.js";
4
4
  import { engineAgentName } from "./task-registry-shared.js";
5
+ import { deliverEngineNotice } from "./engine-notice.js";
5
6
  import { absentReads, isBoolean, isCount, isFiniteNumber, isRecord, isRowCorrupt, isString, isWord, optional, pair, required, rowShapeReader, takesExit, via, } from "./row-shape.js";
6
7
  export const BACKGROUND_AGENT_STATUSES = Object.freeze(["running", "parked", "completed", "failed", "killed"]);
7
8
  import { receiptRefusal } from "./own-property-receipt.js";
@@ -17,6 +18,7 @@ export const REVIVED_ROW_CLEARED_FIELDS = Object.freeze([
17
18
  "errorKind",
18
19
  "errorRetryAfterMs",
19
20
  "resultIsPartial",
21
+ "refusedAsks",
20
22
  "summary",
21
23
  "recentSteps",
22
24
  "editedFiles",
@@ -26,6 +28,9 @@ export function clearRevivedRowTerminalPayload(record) {
26
28
  for (const field of REVIVED_ROW_CLEARED_FIELDS)
27
29
  delete record[field];
28
30
  }
31
+ export function nextCycleSeq(row) {
32
+ return (row.seq ?? 1) + 1;
33
+ }
29
34
  export const declaresTranscriptDurability = (tier) => tier === "full";
30
35
  const transcriptIntegrityAnnounced = new Set();
31
36
  export function announceTranscriptIntegrityGapOnce(handle, scope, sink, tier) {
@@ -51,6 +56,7 @@ export class BackgroundAgentStoreError extends Error {
51
56
  }
52
57
  export const BACKGROUND_AGENT_ROW_MALFORMED_CODE = "agent_record.row_malformed";
53
58
  const isNonEmptyString = (v) => (typeof v === "string" && v !== "" ? undefined : "is not a non-empty string");
59
+ const isCycleNumber = (v) => (typeof v === "number" && Number.isSafeInteger(v) && v >= 1 ? undefined : "is not a stop-cycle number (a safe integer from 1)");
54
60
  export const BACKGROUND_AGENT_ROW_SHAPE = rowShapeReader({
55
61
  family: "background-agent",
56
62
  code: BACKGROUND_AGENT_ROW_MALFORMED_CODE,
@@ -70,6 +76,7 @@ export const BACKGROUND_AGENT_ROW_SHAPE = rowShapeReader({
70
76
  optional("rev", isCount),
71
77
  optional("writerId", isString),
72
78
  optional("writerEpoch", isCount),
79
+ optional("seq", isCycleNumber),
73
80
  optional("parkClaimId", isString),
74
81
  optional("parkedCheckpointToken", isString),
75
82
  optional("parkedAt", isFiniteNumber),
@@ -125,6 +132,59 @@ export const BACKGROUND_AGENT_REAP_KNOBS = Object.freeze(["maxAgeMs", "keep", "s
125
132
  export function receiveBackgroundAgentReapOptions(opts) {
126
133
  return receiveRetentionPolicy("BackgroundAgentStore.reap", opts, BACKGROUND_AGENT_REAP_KNOBS);
127
134
  }
135
+ const isCardStatus = (word) => word === "pending" || word === "resolved" || word === "expired";
136
+ async function listedCardStatus(store, token, sessionId) {
137
+ if (store.listBySession === undefined || sessionId === undefined)
138
+ return undefined;
139
+ try {
140
+ let after;
141
+ for (;;) {
142
+ const answer = await store.listBySession({ sessionId, ...(after !== undefined ? { after } : {}) });
143
+ for (const row of answer.rows) {
144
+ if ((row.kind === "row" ? row.checkpoint.token : row.token) !== token)
145
+ continue;
146
+ const word = row.kind === "row" ? row.checkpoint.status : row.status;
147
+ return isCardStatus(word) ? word : undefined;
148
+ }
149
+ const next = answer.next;
150
+ if (next === undefined || answer.rows.length === 0 || (after !== undefined && next.createdAt === after.createdAt && next.token === after.token))
151
+ return undefined;
152
+ after = next;
153
+ }
154
+ }
155
+ catch {
156
+ }
157
+ return undefined;
158
+ }
159
+ const unreadableCardAnnounced = new Set();
160
+ export async function parkedCardState(store, card) {
161
+ let threw = false;
162
+ try {
163
+ const cp = await store.get(card.token);
164
+ if (cp === null)
165
+ return "missing";
166
+ if (isCardStatus(cp.status))
167
+ return cp.status;
168
+ }
169
+ catch {
170
+ threw = true;
171
+ }
172
+ const listed = await listedCardStatus(store, card.token, card.sessionId);
173
+ if (listed !== undefined)
174
+ return listed;
175
+ const key = `${card.scope}\u0000${card.handle}`;
176
+ if (!unreadableCardAnnounced.has(key)) {
177
+ unreadableCardAnnounced.add(key);
178
+ deliverEngineNotice(undefined, {
179
+ code: "delegation.parked_card_unreadable",
180
+ message: `sema durable-agents: parked agent ${card.handle} (scope ${card.scope}) — the state of its approval card cannot be read (${threw ? "the checkpoint store could not decode the card's body" : "the card carries no state word"}, ` +
181
+ `and the store's session listing did not state its status); the row is left parked, because nothing in this sweep can tell a voided card from a pending one. ` +
182
+ `A store that lists an unreadable row with its stored status (CheckpointStore.listBySession) lets the sweep settle the row.`,
183
+ detail: { handle: card.handle, scope: card.scope, cause: threw ? "decode" : "no_state" },
184
+ });
185
+ }
186
+ return "unreadable";
187
+ }
128
188
  export async function reconcileParkedAgents(stores, scope, now, opts) {
129
189
  const out = { failed: 0, rolledBack: 0 };
130
190
  const excluded = (row) => (opts?.excludeHandles?.has(row.handle) ?? false) ||
@@ -142,17 +202,7 @@ export async function reconcileParkedAgents(stores, scope, now, opts) {
142
202
  delete next.parkedAt;
143
203
  return stores.agentStore.update(row.handle, scope, next, { rev: row.rev });
144
204
  };
145
- const checkpointState = async (token) => {
146
- try {
147
- const cp = await stores.checkpointStore.get(token);
148
- if (cp === null)
149
- return "missing";
150
- return cp.status;
151
- }
152
- catch {
153
- return "unreadable";
154
- }
155
- };
205
+ const checkpointState = (row, token) => parkedCardState(stores.checkpointStore, { token, handle: row.handle, scope, sessionId: row.sessionId });
156
206
  for (const summary of await stores.agentStore.listByScope(scope, { status: "parked" })) {
157
207
  if ("rowVerdict" in summary)
158
208
  continue;
@@ -167,7 +217,7 @@ export async function reconcileParkedAgents(stores, scope, now, opts) {
167
217
  out.failed++;
168
218
  continue;
169
219
  }
170
- const state = await checkpointState(token);
220
+ const state = await checkpointState(row, token);
171
221
  if (state === "expired" || state === "missing") {
172
222
  if (await failRow(row, `approval checkpoint ${state} while parked (reconciled)`))
173
223
  out.failed++;
@@ -196,7 +246,7 @@ export async function reconcileParkedAgents(stores, scope, now, opts) {
196
246
  }
197
247
  for (const row of staleClaims) {
198
248
  const token = row.parkedCheckpointToken;
199
- const state = token === undefined ? "missing" : await checkpointState(token);
249
+ const state = token === undefined ? "missing" : await checkpointState(row, token);
200
250
  if (row.status === "parked") {
201
251
  if (row.parkClaimId === undefined) {
202
252
  if (state === "resolved") {
@@ -349,7 +399,12 @@ export function staleRunningFlip(live, key, scope, now, staleMs, disclose) {
349
399
  const row = answer.row;
350
400
  if (now - row.updatedAt <= staleMs)
351
401
  return undefined;
352
- const next = structuredClone(row);
402
+ const next = staleRunningFlipOf(row, now);
403
+ next.rev = row.rev + 1;
404
+ return next;
405
+ }
406
+ export function staleRunningFlipOf(live, now) {
407
+ const next = structuredClone(live);
353
408
  next.status = "failed";
354
409
  next.stoppedBy = "system";
355
410
  next.summary = next.summary ?? STALE_RUNNING_REAP_ATTRIBUTION;
@@ -357,7 +412,6 @@ export function staleRunningFlip(live, key, scope, now, staleMs, disclose) {
357
412
  next.settledAt = now;
358
413
  next.updatedAt = now;
359
414
  mintCompletionId(next);
360
- next.rev = row.rev + 1;
361
415
  return next;
362
416
  }
363
417
  export function backgroundAgentReapCandidates(rows, scope, disclose) {
@@ -40,9 +40,9 @@ export declare class BackgroundShellError extends Error {
40
40
  * `spawnBackground` 的 options。后台进程只用 `cwd`/`env`/`timeout`;流式回调(`onStdout`/`onStderr`)和 `abortSignal`
41
41
  * 都对「启动后轮询」语义无意义(输出进 tail buffer 等 poll;后台进程的生命周期由 kill/timeout/dispose 管,不绑启动它
42
42
  * 的工具调用的 signal),故显式 `Omit` 以免实现者误以为传 abortSignal 能约束进程。`timeout` 在后台是**硬墙**
43
- * (到点自杀 → status `killed`,design/103 §3.6)。
43
+ * (到点自杀 → status `killed`,design/103 §3.6)。`stdinFrom` 同样 `Omit`:后台启动不带输入。
44
44
  */
45
- export type BackgroundSpawnOptions = Omit<ExecutionEnvExecOptions, "onStdout" | "onStderr" | "abortSignal">;
45
+ export type BackgroundSpawnOptions = Omit<ExecutionEnvExecOptions, "onStdout" | "onStderr" | "abortSignal" | "stdinFrom">;
46
46
  /** 一次 {@link BackgroundShellCapability.pollBackground} 的返回:自上次 poll 以来的增量 + 当前状态 + cursor 元数据。 */
47
47
  export interface BackgroundPoll {
48
48
  /** 自上次 poll 后的新增 stdout(已应用 `filter`,且 filter 先于截断 —— design/103 §3.4)。 */
@@ -1,11 +1,11 @@
1
- import { REDACTION_MARK } from "./redaction-marks.js";
1
+ import { REDACTION_MARKS } from "@sema-agent/primitives";
2
2
  export function callerText(value) {
3
3
  if (typeof value === "symbol")
4
4
  return `a symbol ${callerText(value.description ?? "")}`;
5
5
  if (typeof value !== "string")
6
6
  return dataKind(value);
7
7
  const length = [...value].length;
8
- return `${REDACTION_MARK} (${length} character${length === 1 ? "" : "s"})`;
8
+ return `${REDACTION_MARKS.bare} (${length} character${length === 1 ? "" : "s"})`;
9
9
  }
10
10
  export function dataKind(value) {
11
11
  return value === null ? "null" : value === undefined ? "undefined" : Array.isArray(value) ? "an array" : typeof value === "object" ? "a record" : `a ${typeof value}`;
@@ -68,6 +68,19 @@ export declare function boundInputHashOf(value: unknown): string;
68
68
  export declare function sha16(text: string): string;
69
69
  /** Does `value` read as a digest {@link sha16} mints — a string of exactly sixteen lowercase hex digits? */
70
70
  export declare function isSha16(value: unknown): value is string;
71
+ /**
72
+ * The text form of one string's SHA-256: `sha256:` + the lowercase hex digest of the string's UTF-8 bytes (WHATWG encoding:
73
+ * a lone surrogate encodes as U+FFFD), 71 characters, never truncated. The string is digested as it is handed in — no
74
+ * newline, whitespace or Unicode normalization — so two strings share a value only when their UTF-8 bytes are equal. Every
75
+ * `sha256:` value the package mints over a string goes through here: published prompt text, a locale row's source, an
76
+ * artifact's members, a stored rule file's checksum over its canonical form, the plan shown at a plan pause. How a
77
+ * caller builds the string it digests (a canonical form, fields joined by NUL) is the caller's; only this last step is shared.
78
+ * Unsalted on purpose: the value is comparable across processes and by a reader who holds the same text — which is also why
79
+ * a value over short private text must not reach a trace, a metric or a log line.
80
+ */
81
+ export declare function textContentHashOf(text: string): string;
82
+ /** Does `value` read as a value {@link textContentHashOf} mints — `sha256:` and exactly sixty-four lowercase hex digits? */
83
+ export declare function isTextContentHash(value: unknown): value is string;
71
84
  /**
72
85
  * THE digest an approval binds a CALL by: SHA-256 (hex) over the canonical form of the one record `{ tool, input }` — the tool's name as the
73
86
  * call spells it and the arguments in their JSON form ({@link capturedJsonOf}: a record member holding `undefined` absent), one
@@ -20,6 +20,13 @@ const SHA16_SHAPE = /^[0-9a-f]{16}$/;
20
20
  export function isSha16(value) {
21
21
  return typeof value === "string" && SHA16_SHAPE.test(value);
22
22
  }
23
+ export function textContentHashOf(text) {
24
+ return `sha256:${createHash("sha256").update(text, "utf8").digest("hex")}`;
25
+ }
26
+ const TEXT_CONTENT_HASH_SHAPE = /^sha256:[0-9a-f]{64}$/;
27
+ export function isTextContentHash(value) {
28
+ return typeof value === "string" && TEXT_CONTENT_HASH_SHAPE.test(value);
29
+ }
23
30
  export function exactBoundInputHashOf(tool, input) {
24
31
  const captured = capturedJsonOf(input);
25
32
  if (!captured.ok)