@sema-agent/core 7.67.2 → 7.68.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 (505) hide show
  1. package/CHANGELOG.md +1533 -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/errors.d.ts +20 -0
  30. package/dist/brain/errors.js +114 -0
  31. package/dist/brain/open-responses.js +3 -1
  32. package/dist/brain/openai.js +3 -1
  33. package/dist/brain/provider-message.d.ts +5 -3
  34. package/dist/brain/provider-message.js +35 -8
  35. package/dist/brain/reasoning-request.d.ts +73 -19
  36. package/dist/brain/reasoning-request.js +164 -72
  37. package/dist/brain/reasoning-stamp.d.ts +26 -0
  38. package/dist/brain/reasoning-stamp.js +10 -0
  39. package/dist/brain/reasoning.d.ts +95 -162
  40. package/dist/brain/reasoning.js +31 -86
  41. package/dist/brain/route-adjudicator.d.ts +9 -7
  42. package/dist/brain/route-adjudicator.js +12 -10
  43. package/dist/brain/status-sink.d.ts +19 -64
  44. package/dist/brain/status-sink.js +5 -21
  45. package/dist/brain/stream-engine.d.ts +11 -2
  46. package/dist/brain/stream-engine.js +10 -0
  47. package/dist/core/a2a.d.ts +17 -5
  48. package/dist/core/a2a.js +11 -3
  49. package/dist/core/allow-entry.d.ts +35 -15
  50. package/dist/core/allow-entry.js +47 -60
  51. package/dist/core/ask-headline.d.ts +68 -0
  52. package/dist/core/ask-headline.js +23 -0
  53. package/dist/core/ask-origin.d.ts +36 -8
  54. package/dist/core/ask-origin.js +17 -10
  55. package/dist/core/ask-question.d.ts +34 -7
  56. package/dist/core/ask-question.js +10 -1
  57. package/dist/core/ask-unresolvable-notice.d.ts +7 -0
  58. package/dist/core/ask-unresolvable-notice.js +9 -3
  59. package/dist/core/auto-strip.d.ts +53 -0
  60. package/dist/core/auto-strip.js +76 -0
  61. package/dist/core/background-agent-store.d.ts +45 -5
  62. package/dist/core/background-agent-store.js +69 -15
  63. package/dist/core/background-shell.d.ts +2 -2
  64. package/dist/core/caller-text.js +2 -2
  65. package/dist/core/canonical-json.d.ts +13 -0
  66. package/dist/core/canonical-json.js +7 -0
  67. package/dist/core/checkpoint-features.d.ts +66 -20
  68. package/dist/core/checkpoint-features.js +12 -1
  69. package/dist/core/checkpoint-generation.d.ts +1 -1
  70. package/dist/core/checkpoint-queries.d.ts +1 -1
  71. package/dist/core/checkpoint-queries.js +4 -1
  72. package/dist/core/checkpoint-requirements.d.ts +25 -1
  73. package/dist/core/checkpoint-requirements.js +5 -1
  74. package/dist/core/checkpoint-row-verdict.d.ts +1 -0
  75. package/dist/core/checkpoint-row-verdict.js +4 -0
  76. package/dist/core/checkpoint-store.d.ts +66 -38
  77. package/dist/core/checkpoint-store.js +15 -6
  78. package/dist/core/child-clamp-seats.d.ts +6 -0
  79. package/dist/core/child-clamp-seats.js +1 -0
  80. package/dist/core/config-refusal-codes.d.ts +1 -1
  81. package/dist/core/config-refusal-codes.js +1 -0
  82. package/dist/core/delegation-frames.d.ts +9 -12
  83. package/dist/core/delegation-frames.js +9 -8
  84. package/dist/core/engine-capabilities.d.ts +21 -8
  85. package/dist/core/engine-capabilities.js +1 -1
  86. package/dist/core/engine-notice.d.ts +147 -34
  87. package/dist/core/engine-notice.js +27 -16
  88. package/dist/core/engine-storage-backend.d.ts +2 -1
  89. package/dist/core/env-budget.js +3 -3
  90. package/dist/core/env-knob-announce.d.ts +10 -10
  91. package/dist/core/env-knob-announce.js +3 -6
  92. package/dist/core/file-history-store.d.ts +29 -4
  93. package/dist/core/file-history-store.js +13 -0
  94. package/dist/core/frame-settlement.d.ts +2 -1
  95. package/dist/core/gate-fold.js +1 -1
  96. package/dist/core/gate-lanes.js +56 -49
  97. package/dist/core/governance-codes.d.ts +39 -3
  98. package/dist/core/governance-codes.js +61 -3
  99. package/dist/core/hooks.d.ts +29 -11
  100. package/dist/core/hooks.js +5 -2
  101. package/dist/core/human-input-projection.js +3 -3
  102. package/dist/core/input-author.d.ts +17 -3
  103. package/dist/core/input-author.js +15 -3
  104. package/dist/core/leg-identity.d.ts +10 -28
  105. package/dist/core/leg-identity.js +1 -21
  106. package/dist/core/lsp.d.ts +18 -13
  107. package/dist/core/lsp.js +30 -22
  108. package/dist/core/mailbox-store.d.ts +1 -1
  109. package/dist/core/mailbox-store.js +4 -4
  110. package/dist/core/mcp-connection-pool.d.ts +93 -4
  111. package/dist/core/mcp-connection-pool.js +104 -1
  112. package/dist/core/mcp-failure.d.ts +38 -12
  113. package/dist/core/mcp-failure.js +9 -13
  114. package/dist/core/mcp-probe.d.ts +4 -3
  115. package/dist/core/mcp-server-link.d.ts +4 -2
  116. package/dist/core/mcp-server-link.js +4 -5
  117. package/dist/core/mcp-server-spec.d.ts +3 -3
  118. package/dist/core/mcp-server-unavailable-notice.d.ts +22 -8
  119. package/dist/core/mcp-server-unavailable-notice.js +18 -4
  120. package/dist/core/mcp.d.ts +40 -6
  121. package/dist/core/mcp.js +39 -13
  122. package/dist/core/memory-engine/content-origin.js +2 -2
  123. package/dist/core/memory-engine/control-objects.d.ts +2 -4
  124. package/dist/core/memory-engine/control-objects.js +2 -10
  125. package/dist/core/memory-engine/delegation-settlement.js +6 -1
  126. package/dist/core/memory-engine/dual-root.js +3 -0
  127. package/dist/core/memory-engine/engine.d.ts +6 -4
  128. package/dist/core/memory-engine/engine.js +32 -29
  129. package/dist/core/memory-engine/file-backend.d.ts +20 -5
  130. package/dist/core/memory-engine/file-backend.js +21 -31
  131. package/dist/core/memory-engine/frontmatter.d.ts +2 -0
  132. package/dist/core/memory-engine/frontmatter.js +4 -0
  133. package/dist/core/memory-engine/layout.d.ts +114 -20
  134. package/dist/core/memory-engine/layout.js +340 -22
  135. package/dist/core/memory-engine/memory-deployment.d.ts +7 -5
  136. package/dist/core/memory-engine/mount-failed-notice.d.ts +19 -7
  137. package/dist/core/memory-engine/mount-failed-notice.js +43 -10
  138. package/dist/core/memory-engine/sync-client.js +4 -5
  139. package/dist/core/model-fallbacks.d.ts +5 -1
  140. package/dist/core/model-fallbacks.js +3 -3
  141. package/dist/core/model-receipt.d.ts +2 -1
  142. package/dist/core/model-receipt.js +12 -1
  143. package/dist/core/mods/kernel/dispatch.d.ts +2 -2
  144. package/dist/core/mods/kernel/dispatch.js +14 -6
  145. package/dist/core/mods/kernel/events.d.ts +8 -5
  146. package/dist/core/mods/kernel/events.js +2 -2
  147. package/dist/core/mods/kernel/index.d.ts +1 -1
  148. package/dist/core/mods/kernel/registration.d.ts +9 -0
  149. package/dist/core/mods/package.js +1 -1
  150. package/dist/core/mods/session-append.d.ts +4 -2
  151. package/dist/core/mods/session-append.js +3 -0
  152. package/dist/core/mods/stations.d.ts +7 -11
  153. package/dist/core/mods/stations.js +4 -7
  154. package/dist/core/mods/tool-call.d.ts +10 -8
  155. package/dist/core/mods/tool-call.js +15 -18
  156. package/dist/core/mounted-mcp.d.ts +0 -4
  157. package/dist/core/mounted-mcp.js +1 -1
  158. package/dist/core/park-noun.d.ts +24 -0
  159. package/dist/core/park-noun.js +21 -0
  160. package/dist/core/park-resumability.d.ts +60 -0
  161. package/dist/core/park-resumability.js +30 -0
  162. package/dist/core/permission-rule-provider.d.ts +24 -2
  163. package/dist/core/permission-rule-provider.js +11 -8
  164. package/dist/core/permission-rule-store.d.ts +8 -1
  165. package/dist/core/permission-rule-store.js +2 -3
  166. package/dist/core/permission-rules.d.ts +2 -1
  167. package/dist/core/permission-rules.js +8 -4
  168. package/dist/core/persisted-rule-arms.d.ts +3 -0
  169. package/dist/core/persisted-rule-arms.js +2 -1
  170. package/dist/core/present-plan-tool.d.ts +47 -3
  171. package/dist/core/present-plan-tool.js +62 -4
  172. package/dist/core/principal-name.d.ts +1 -1
  173. package/dist/core/principal-name.js +5 -5
  174. package/dist/core/process-identity.js +10 -5
  175. package/dist/core/protocol-http-auth.d.ts +30 -9
  176. package/dist/core/protocol-http-auth.js +113 -59
  177. package/dist/core/read-only-shell.js +9 -5
  178. package/dist/core/redaction-marks.d.ts +4 -26
  179. package/dist/core/redaction-marks.js +9 -21
  180. package/dist/core/remote-env.d.ts +43 -16
  181. package/dist/core/remote-env.js +1 -1
  182. package/dist/core/request-copy-projection.d.ts +1 -1
  183. package/dist/core/request-copy-projection.js +40 -50
  184. package/dist/core/resume-config-judge.js +1 -1
  185. package/dist/core/resume-startup-cause.d.ts +35 -18
  186. package/dist/core/resume-startup-cause.js +13 -10
  187. package/dist/core/retention.d.ts +167 -25
  188. package/dist/core/retention.js +100 -20
  189. package/dist/core/roles.d.ts +6 -0
  190. package/dist/core/roles.js +11 -5
  191. package/dist/core/rule-lane-reads.d.ts +3 -0
  192. package/dist/core/rule-lane-reads.js +5 -1
  193. package/dist/core/rule-store-fault.d.ts +70 -0
  194. package/dist/core/rule-store-fault.js +102 -0
  195. package/dist/core/runner/advertised-writable-dirs.js +16 -31
  196. package/dist/core/runner/announce-once-ledger.d.ts +19 -2
  197. package/dist/core/runner/announce-once-ledger.js +24 -2
  198. package/dist/core/runner/assemble-result.d.ts +6 -0
  199. package/dist/core/runner/assemble-result.js +1 -1
  200. package/dist/core/runner/auto-strip-notice.d.ts +36 -0
  201. package/dist/core/runner/auto-strip-notice.js +59 -0
  202. package/dist/core/runner/branch-window.d.ts +3 -0
  203. package/dist/core/runner/branch-window.js +37 -0
  204. package/dist/core/runner/caller-roster.d.ts +8 -3
  205. package/dist/core/runner/capability-withheld-seat.js +3 -9
  206. package/dist/core/runner/clock-and-limits.d.ts +22 -1
  207. package/dist/core/runner/clock-and-limits.js +30 -0
  208. package/dist/core/runner/contracts.d.ts +58 -35
  209. package/dist/core/runner/credential-refusal-seat.d.ts +2 -0
  210. package/dist/core/runner/credential-refusal-seat.js +47 -0
  211. package/dist/core/runner/cross-boundary-lane.js +6 -4
  212. package/dist/core/runner/decide-continuation.js +1 -1
  213. package/dist/core/runner/file-history-restore.d.ts +53 -2
  214. package/dist/core/runner/file-history-restore.js +29 -10
  215. package/dist/core/runner/forward-sink.d.ts +14 -1
  216. package/dist/core/runner/forward-sink.js +14 -12
  217. package/dist/core/runner/gate-exit.d.ts +8 -7
  218. package/dist/core/runner/gate-exit.js +13 -13
  219. package/dist/core/runner/git-status-frame.js +2 -4
  220. package/dist/core/runner/initial-run-state.js +1 -1
  221. package/dist/core/runner/main-call-account.d.ts +3 -1
  222. package/dist/core/runner/main-call-account.js +5 -3
  223. package/dist/core/runner/mcp-redial.d.ts +2 -5
  224. package/dist/core/runner/mcp-redial.js +2 -2
  225. package/dist/core/runner/nested-memory-content.d.ts +7 -1
  226. package/dist/core/runner/nested-memory-content.js +73 -13
  227. package/dist/core/runner/nested-memory-lane.d.ts +44 -19
  228. package/dist/core/runner/nested-memory-lane.js +152 -76
  229. package/dist/core/runner/park-commit.js +3 -1
  230. package/dist/core/runner/permission-rule-lanes.d.ts +8 -2
  231. package/dist/core/runner/permission-rule-lanes.js +29 -3
  232. package/dist/core/runner/person-path-rows.d.ts +3 -11
  233. package/dist/core/runner/person-path-rows.js +21 -24
  234. package/dist/core/runner/prepare-acquire-reconcile.js +3 -1
  235. package/dist/core/runner/prepare-artifact.d.ts +1 -1
  236. package/dist/core/runner/prepare-artifact.js +20 -14
  237. package/dist/core/runner/prepare-ask-lane.d.ts +9 -6
  238. package/dist/core/runner/prepare-ask-lane.js +6 -5
  239. package/dist/core/runner/prepare-boundary-parks.d.ts +7 -1
  240. package/dist/core/runner/prepare-boundary-parks.js +27 -24
  241. package/dist/core/runner/prepare-caps-and-workflow.d.ts +5 -2
  242. package/dist/core/runner/prepare-caps-and-workflow.js +4 -3
  243. package/dist/core/runner/prepare-config-doors.d.ts +9 -24
  244. package/dist/core/runner/prepare-config-doors.js +58 -41
  245. package/dist/core/runner/prepare-context-lane.d.ts +2 -2
  246. package/dist/core/runner/prepare-context-lane.js +3 -5
  247. package/dist/core/runner/prepare-defer-classify.d.ts +1 -1
  248. package/dist/core/runner/prepare-defer-classify.js +1 -1
  249. package/dist/core/runner/prepare-delegation-surface.d.ts +2 -2
  250. package/dist/core/runner/prepare-delegation-surface.js +3 -2
  251. package/dist/core/runner/prepare-file-history.d.ts +62 -26
  252. package/dist/core/runner/prepare-file-history.js +117 -46
  253. package/dist/core/runner/prepare-gate-stations.d.ts +4 -0
  254. package/dist/core/runner/prepare-gate-stations.js +6 -5
  255. package/dist/core/runner/prepare-hands-readface.d.ts +9 -4
  256. package/dist/core/runner/prepare-hands-readface.js +8 -4
  257. package/dist/core/runner/prepare-inherited-gate.d.ts +11 -4
  258. package/dist/core/runner/prepare-inherited-gate.js +6 -6
  259. package/dist/core/runner/prepare-listings.d.ts +1 -1
  260. package/dist/core/runner/prepare-listings.js +1 -1
  261. package/dist/core/runner/prepare-memory.js +2 -2
  262. package/dist/core/runner/prepare-offload-wrappers.d.ts +1 -1
  263. package/dist/core/runner/prepare-offload-wrappers.js +1 -1
  264. package/dist/core/runner/prepare-park-ask.d.ts +10 -3
  265. package/dist/core/runner/prepare-park-ask.js +7 -9
  266. package/dist/core/runner/prepare-policy-chain.d.ts +18 -9
  267. package/dist/core/runner/prepare-policy-chain.js +18 -13
  268. package/dist/core/runner/prepare-project-context.d.ts +1 -1
  269. package/dist/core/runner/prepare-project-context.js +5 -3
  270. package/dist/core/runner/prepare-prompt-assembly.js +2 -1
  271. package/dist/core/runner/prepare-prompt-inputs.d.ts +2 -2
  272. package/dist/core/runner/prepare-prompt-inputs.js +1 -1
  273. package/dist/core/runner/prepare-protocol-tools.d.ts +4 -5
  274. package/dist/core/runner/prepare-protocol-tools.js +7 -7
  275. package/dist/core/runner/prepare-question-face.d.ts +4 -2
  276. package/dist/core/runner/prepare-run-refs.d.ts +7 -2
  277. package/dist/core/runner/prepare-run-refs.js +8 -7
  278. package/dist/core/runner/prepare-safety-scan.d.ts +4 -3
  279. package/dist/core/runner/prepare-suspend-saga.d.ts +3 -7
  280. package/dist/core/runner/prepare-suspend-saga.js +4 -3
  281. package/dist/core/runner/prepare-task.js +66 -53
  282. package/dist/core/runner/prepare-tool-disclosure-mount.d.ts +3 -2
  283. package/dist/core/runner/prepare-tool-disclosure-mount.js +2 -1
  284. package/dist/core/runner/prepare-turn-wiring.d.ts +3 -1
  285. package/dist/core/runner/prepare-turn-wiring.js +1 -1
  286. package/dist/core/runner/prepare-wiring-manifest.d.ts +9 -4
  287. package/dist/core/runner/prepare-wiring-manifest.js +14 -6
  288. package/dist/core/runner/prepare-workspace-restore.d.ts +4 -4
  289. package/dist/core/runner/prepare-workspace-restore.js +15 -6
  290. package/dist/core/runner/remote-env-retry.d.ts +3 -3
  291. package/dist/core/runner/restore-seat.d.ts +41 -0
  292. package/dist/core/runner/restore-seat.js +38 -0
  293. package/dist/core/runner/resume-admission.js +1 -1
  294. package/dist/core/runner/resume-apply.js +4 -3
  295. package/dist/core/runner/resume-checkpoint-screen.js +2 -1
  296. package/dist/core/runner/resume-internals-and-config.js +2 -1
  297. package/dist/core/runner/resume-preflight.js +2 -1
  298. package/dist/core/runner/rewind-files.js +22 -6
  299. package/dist/core/runner/rule-store-unreadable-notice.d.ts +8 -0
  300. package/dist/core/runner/rule-store-unreadable-notice.js +11 -0
  301. package/dist/core/runner/run-brain-sinks.d.ts +3 -6
  302. package/dist/core/runner/run-brain-sinks.js +6 -6
  303. package/dist/core/runner/run-compaction-machinery.d.ts +2 -2
  304. package/dist/core/runner/run-git-lane.d.ts +2 -0
  305. package/dist/core/runner/run-git-lane.js +2 -1
  306. package/dist/core/runner/run-harness-handlers.js +5 -4
  307. package/dist/core/runner/run-identity-wiring.js +20 -12
  308. package/dist/core/runner/run-leg.js +31 -72
  309. package/dist/core/runner/run-notification-lane.d.ts +3 -0
  310. package/dist/core/runner/run-notification-lane.js +2 -4
  311. package/dist/core/runner/run-reasoning-seat.d.ts +5 -6
  312. package/dist/core/runner/run-reasoning-seat.js +13 -18
  313. package/dist/core/runner/run-settle-and-teardown.js +13 -9
  314. package/dist/core/runner/run-terminal-adoption.js +4 -8
  315. package/dist/core/runner/run-turn-boundary.js +6 -3
  316. package/dist/core/runner/runtask.d.ts +9 -4
  317. package/dist/core/runner/runtask.js +29 -22
  318. package/dist/core/runner/session-rule-policy.d.ts +11 -1
  319. package/dist/core/runner/shell-env-withheld.js +2 -7
  320. package/dist/core/runner/side-call-account.d.ts +5 -6
  321. package/dist/core/runner/side-call-account.js +2 -2
  322. package/dist/core/runner/stream-lifecycle-verbs.d.ts +3 -0
  323. package/dist/core/runner/stream-lifecycle-verbs.js +5 -3
  324. package/dist/core/runner/stream-settle-backstop.js +4 -6
  325. package/dist/core/runner/stream-steer-verb.d.ts +1 -1
  326. package/dist/core/runner/stream-steer-verb.js +4 -4
  327. package/dist/core/runner/sub-agent-deny-lists.d.ts +8 -3
  328. package/dist/core/runner/sub-agent-deny-lists.js +7 -4
  329. package/dist/core/runner/teardown-bounded.d.ts +7 -0
  330. package/dist/core/runner/teardown-bounded.js +7 -0
  331. package/dist/core/runner/terminal-account.js +41 -13
  332. package/dist/core/runner/terminal-projection.d.ts +1 -5
  333. package/dist/core/runner/tool-end-body.d.ts +9 -3
  334. package/dist/core/runner/tool-end-body.js +6 -3
  335. package/dist/core/runner/tool-output-projection.d.ts +13 -4
  336. package/dist/core/runner/tool-output-projection.js +10 -14
  337. package/dist/core/runner/turn-attachments.d.ts +3 -2
  338. package/dist/core/runner/turn-attachments.js +12 -5
  339. package/dist/core/runner-deps.d.ts +6 -6
  340. package/dist/core/runtime-caps.d.ts +2 -1
  341. package/dist/core/secret-env.d.ts +20 -3
  342. package/dist/core/secret-env.js +13 -15
  343. package/dist/core/session-checkout.d.ts +115 -15
  344. package/dist/core/session-checkout.js +435 -136
  345. package/dist/core/session-policy-store.js +21 -3
  346. package/dist/core/session-reconcile.js +1 -0
  347. package/dist/core/session-store.js +2 -0
  348. package/dist/core/session.d.ts +11 -1
  349. package/dist/core/shell-run-candidates.d.ts +1 -0
  350. package/dist/core/shell-run-candidates.js +1 -1
  351. package/dist/core/shutdown-debug.d.ts +6 -5
  352. package/dist/core/shutdown-debug.js +5 -1
  353. package/dist/core/skill-grant.js +4 -1
  354. package/dist/core/skills-directory.js +5 -3
  355. package/dist/core/spec-contract.d.ts +1 -1
  356. package/dist/core/store-contracts/checkpoint-store-contract.js +2 -7
  357. package/dist/core/store-contracts/file-history-store-contract.js +26 -2
  358. package/dist/core/store-contracts/session-deletion-cascade-contract.js +130 -14
  359. package/dist/core/store-contracts/task-list-store-contract.d.ts +2 -1
  360. package/dist/core/store-contracts/task-list-store-contract.js +28 -1
  361. package/dist/core/task-event.d.ts +48 -27
  362. package/dist/core/task-notification.d.ts +15 -9
  363. package/dist/core/task-notification.js +12 -0
  364. package/dist/core/task-registry-agent.d.ts +24 -22
  365. package/dist/core/task-registry-agent.js +65 -46
  366. package/dist/core/task-registry-shared.d.ts +17 -5
  367. package/dist/core/task-registry.d.ts +17 -6
  368. package/dist/core/task-registry.js +6 -1
  369. package/dist/core/task-result.d.ts +71 -25
  370. package/dist/core/task-spec-members.d.ts +0 -1
  371. package/dist/core/task-spec-members.js +1 -1
  372. package/dist/core/task-spec.d.ts +60 -52
  373. package/dist/core/task-stream.d.ts +45 -12
  374. package/dist/core/terminal-cause.d.ts +45 -8
  375. package/dist/core/terminal-cause.js +5 -0
  376. package/dist/core/tool-card-bound.d.ts +32 -0
  377. package/dist/core/tool-card-bound.js +33 -0
  378. package/dist/core/tool-catalog-entries.d.ts +9 -0
  379. package/dist/core/tool-catalog-entries.js +48 -0
  380. package/dist/core/tool-errors.d.ts +4 -3
  381. package/dist/core/tool-face.d.ts +3 -3
  382. package/dist/core/tool-mount-facts.d.ts +3 -2
  383. package/dist/core/tool-mount-facts.js +1 -1
  384. package/dist/core/tool-mount-static.js +7 -5
  385. package/dist/core/tool-policy.d.ts +21 -19
  386. package/dist/core/tool-policy.js +5 -6
  387. package/dist/core/tool-registry.d.ts +3 -1
  388. package/dist/core/tool-registry.js +15 -1
  389. package/dist/core/tool-result-store.d.ts +9 -3
  390. package/dist/core/tool-result-store.js +14 -1
  391. package/dist/core/tool-roster.d.ts +6 -0
  392. package/dist/core/tool-roster.js +18 -0
  393. package/dist/core/tool-spec.d.ts +17 -8
  394. package/dist/core/trace.d.ts +35 -31
  395. package/dist/core/types.d.ts +2 -2
  396. package/dist/core/untrusted-egress.d.ts +19 -7
  397. package/dist/core/untrusted-egress.js +26 -7
  398. package/dist/core/untrusted-text.d.ts +6 -18
  399. package/dist/core/untrusted-text.js +11 -4
  400. package/dist/core/user-attachment.d.ts +9 -6
  401. package/dist/core/user-attachment.js +12 -10
  402. package/dist/core/user-row-origin.d.ts +44 -25
  403. package/dist/core/user-row-origin.js +30 -20
  404. package/dist/core/wiring-manifest.d.ts +26 -7
  405. package/dist/core/wiring-manifest.js +14 -11
  406. package/dist/core/workspace-snapshot.d.ts +3 -1
  407. package/dist/core/workspace-snapshot.js +1 -0
  408. package/dist/engine/execution-env/node-execution-env.d.ts +23 -16
  409. package/dist/engine/execution-env/node-execution-env.js +127 -67
  410. package/dist/engine/harness/agent-harness.d.ts +4 -5
  411. package/dist/engine/harness/agent-harness.js +2 -7
  412. package/dist/engine/harness/types.d.ts +51 -19
  413. package/dist/engine/harness/types.js +28 -1
  414. package/dist/engine/llm/types.d.ts +26 -14
  415. package/dist/engine/llm/types.js +2 -2
  416. package/dist/engine/loop/agent-loop.d.ts +2 -2
  417. package/dist/engine/loop/agent-loop.js +51 -275
  418. package/dist/engine/loop/types.d.ts +0 -18
  419. package/dist/engine/session/import-validate.d.ts +3 -0
  420. package/dist/engine/session/import-validate.js +34 -2
  421. package/dist/engine/session/repo-utils.d.ts +42 -4
  422. package/dist/engine/session/repo-utils.js +33 -5
  423. package/dist/engine/session/session.d.ts +41 -14
  424. package/dist/engine/session/session.js +96 -25
  425. package/dist/index.d.ts +21 -16
  426. package/dist/index.js +16 -10
  427. package/dist/orchestration/run-spec.d.ts +1 -1
  428. package/dist/orchestration/run-workflow-tool.d.ts +12 -9
  429. package/dist/orchestration/run-workflow-tool.js +15 -19
  430. package/dist/orchestration/workflow-governance.js +13 -21
  431. package/dist/orchestration/workflow-observe.d.ts +4 -3
  432. package/dist/orchestration/workflow-primitives.d.ts +1 -1
  433. package/dist/orchestration/workflow-record-artifact.d.ts +14 -0
  434. package/dist/orchestration/workflow-record-artifact.js +32 -0
  435. package/dist/orchestration/workflow-script-store.d.ts +9 -0
  436. package/dist/orchestration/workflow-script-store.js +20 -1
  437. package/dist/orchestration/workflow-types.d.ts +33 -3
  438. package/dist/orchestration/workflow.d.ts +24 -14
  439. package/dist/orchestration/workflow.js +52 -23
  440. package/dist/prompt-assembly/artifact.js +4 -8
  441. package/dist/prompt-assembly/catalog/engine.d.ts +263 -0
  442. package/dist/prompt-assembly/catalog/engine.js +30 -0
  443. package/dist/prompt-assembly/catalog/index.d.ts +1 -1
  444. package/dist/prompt-assembly/catalog/index.js +2 -2
  445. package/dist/prompt-assembly/catalog/locales/zh-Hans/engine.d.ts +1 -1
  446. package/dist/prompt-assembly/catalog/locales/zh-Hans/engine.js +29 -0
  447. package/dist/prompt-assembly/epoch.js +6 -8
  448. package/dist/prompt-assembly/turn-snapshot.js +8 -9
  449. package/dist/stores/file/background-agent-store.js +5 -6
  450. package/dist/stores/file/checkpoint-store.d.ts +0 -4
  451. package/dist/stores/file/checkpoint-store.js +7 -3
  452. package/dist/stores/file/file-history-store.d.ts +8 -0
  453. package/dist/stores/file/file-history-store.js +72 -0
  454. package/dist/stores/file/fs-atomic.js +17 -12
  455. package/dist/stores/file/index.js +11 -5
  456. package/dist/stores/file/mailbox-store.js +13 -4
  457. package/dist/stores/file/permission-rule-store.js +14 -13
  458. package/dist/stores/file/shared-ledger.d.ts +4 -0
  459. package/dist/stores/file/shared-ledger.js +4 -0
  460. package/dist/stores/file/task-list-store.js +12 -3
  461. package/dist/stores/file/workflow-run-store.js +1 -0
  462. package/dist/tools/fs/bash-program-position.d.ts +4 -2
  463. package/dist/tools/fs/bash-program-position.js +1 -1
  464. package/dist/tools/fs/bash-readonly-classifier.js +1 -1
  465. package/dist/tools/fs/bound-open.d.ts +97 -0
  466. package/dist/tools/fs/bound-open.js +103 -0
  467. package/dist/tools/fs/containment-face.d.ts +2 -2
  468. package/dist/tools/fs/fs-pdf.d.ts +7 -1
  469. package/dist/tools/fs/fs-pdf.js +31 -23
  470. package/dist/tools/fs/fs-read.d.ts +24 -17
  471. package/dist/tools/fs/fs-read.js +84 -53
  472. package/dist/tools/fs/fs-shared.d.ts +14 -12
  473. package/dist/tools/fs/fs-shared.js +5 -4
  474. package/dist/tools/fs/fs-write.d.ts +2 -2
  475. package/dist/tools/fs/fs-write.js +20 -12
  476. package/dist/tools/fs/index.d.ts +4 -4
  477. package/dist/tools/fs/index.js +2 -2
  478. package/dist/tools/fs/notebook.d.ts +1 -1
  479. package/dist/tools/fs/pdf.d.ts +12 -3
  480. package/dist/tools/fs/pdf.js +22 -9
  481. package/dist/tools/fs/read-deny-home.d.ts +3 -2
  482. package/dist/tools/fs/read-deny-home.js +8 -11
  483. package/dist/tools/fs/safety.d.ts +3 -2
  484. package/dist/tools/fs/shell-read-check.js +10 -9
  485. package/dist/tools/monitor.d.ts +6 -5
  486. package/dist/tools/task-list.d.ts +16 -6
  487. package/dist/tools/task-list.js +4 -0
  488. package/dist/tools/web.d.ts +9 -1
  489. package/dist/tools/web.js +8 -3
  490. package/dist/tools/worktree.d.ts +7 -5
  491. package/dist/tools/worktree.js +4 -3
  492. package/package.json +4 -3
  493. package/test/export-surface.snapshot.json +93 -7
  494. package/wire-changes/core-stores-sql@7.67.3.json +39 -0
  495. package/wire-changes/core-stores-sql@7.68.0.json +39 -0
  496. package/wire-changes/core@7.67.3.json +65 -0
  497. package/wire-changes/core@7.68.0.json +4257 -0
  498. package/wire-changes/mods-kernel@7.67.3.json +39 -0
  499. package/wire-changes/mods-kernel@7.68.0.json +129 -0
  500. package/wire-changes/primitives@7.67.3.json +39 -0
  501. package/wire-changes/primitives@7.68.0.json +253 -0
  502. package/wire-changes/wiki-gate@7.67.3.json +39 -0
  503. package/wire-changes/wiki-gate@7.68.0.json +39 -0
  504. package/dist/core/runner/credential-origin-seat.d.ts +0 -2
  505. package/dist/core/runner/credential-origin-seat.js +0 -20
@@ -2,6 +2,7 @@ import type { DocumentContent, ImageContent, TextContent } from "../../internal/
2
2
  import type { ExecutionEnv } from "../../internal/harness-types.js";
3
3
  import { type ImageDownsampler } from "../../core/image-downsample.js";
4
4
  import { type PdfModelCapabilities } from "./pdf.js";
5
+ import type { ReadObject } from "./bound-open.js";
5
6
  import { type ReminderDisclosureEffects } from "../../core/reminder-disclosure.js";
6
7
  /** The reader's disclosure state, threaded into the PDF TEXT legs (the two `pdftotext` extraction arms —
7
8
  * the only PDF returns with a model-facing text projection of the document; the native document block and
@@ -43,5 +44,10 @@ type ReadPdfReturn = string | {
43
44
  * 3. honest placeholder explaining WHY levels 1–2 did not run + the Bash self-help.
44
45
  * Every degraded return carries `details.fallback = { level, reason }` (telemetry on the structured frame).
45
46
  * `caps` absent ⇒ fully capable (native document block; the brain placeholder still guards).
47
+ * Every poppler start reads the PDF as {@link PdfInput} says: a held object's bytes on its standard input; a poppler that
48
+ * cannot read `-` answers its own error, and the start is never retried on the path.
46
49
  */
47
- export declare function readPdfFile(env: ExecutionEnv, path: string, key: string, pages: string | undefined, signal: AbortSignal | undefined, imageProcessor: ImageDownsampler | false | undefined, cwd: string, preRead?: Uint8Array, caps?: PdfModelCapabilities, readDeny?: import("./read-deny.js").ReadDenyMatcher, disclosure?: PdfReminderDisclosure): Promise<ReadPdfReturn>;
50
+ export declare function readPdfFile(env: ExecutionEnv, path: string, pdf: {
51
+ readonly object: ReadObject;
52
+ readonly size: number;
53
+ }, pages: string | undefined, signal: AbortSignal | undefined, imageProcessor: ImageDownsampler | false | undefined, preRead?: Uint8Array, caps?: PdfModelCapabilities, readDeny?: import("./read-deny.js").ReadDenyMatcher, disclosure?: PdfReminderDisclosure): Promise<ReadPdfReturn>;
@@ -2,7 +2,7 @@ import { delimitUntrusted } from "../../core/untrusted-text.js";
2
2
  import { resolveImageProcessor } from "../../core/image-downsample.js";
3
3
  import { PDF_FALLBACK_RENDER_PAGES, PDF_INLINE_PAGE_THRESHOLD, PDF_MAX_EXTRACT_SIZE, PDF_MAX_PAGES_PER_READ, extractPdfPagesAsImages, extractPdfTextLayer, getPdfPageCount, parsePdfPageRange, pdfCutWords, } from "./pdf.js";
4
4
  import { admitImageBytes, IMAGE_ADMISSION, PDF_TARGET_RAW_SIZE, pdfMagicMatches, unprocessedSizeClause } from "../../core/image-admission.js";
5
- import { enoentMessage, MAX_READ_BYTES } from "./fs-shared.js";
5
+ import { MAX_READ_BYTES } from "./fs-shared.js";
6
6
  import { envErrorDetail } from "./env-error-detail.js";
7
7
  import { readFloorSeat } from "./read-floor.js";
8
8
  import { planReminderDisclosure, renderReminderDisclosureTrailer } from "../../core/reminder-disclosure.js";
@@ -47,28 +47,36 @@ function boundPdfExtractedText(text) {
47
47
  return { body: text, truncated: false };
48
48
  return { body: text.slice(0, MAX_READ_BYTES), truncated: true };
49
49
  }
50
- export async function readPdfFile(env, path, key, pages, signal, imageProcessor, cwd, preRead, caps, readDeny, disclosure) {
50
+ export async function readPdfFile(env, path, pdf, pages, signal, imageProcessor, preRead, caps, readDeny, disclosure) {
51
51
  const cap = caps ?? { document: true, vision: true };
52
52
  const readFloor = readFloorSeat(readDeny)?.(undefined);
53
- const meta = await env.fileInfo(key, signal);
54
- if (!meta.ok) {
55
- const ex = await env.exists(key, signal);
56
- if (ex.ok && !ex.value)
57
- return `Error (Read): ${await enoentMessage(env, key, cwd, signal, readDeny)}`;
58
- return `Error (Read): cannot stat PDF "${path}" to verify its size before reading: ${envErrorDetail(meta.error.message)}`;
59
- }
60
- const size = preRead ? preRead.byteLength : meta.value.size;
61
- if (size > PDF_MAX_EXTRACT_SIZE) {
62
- return `Error (Read): PDF "${path}" exceeds the maximum size for PDF reading (${size} bytes > ${PDF_MAX_EXTRACT_SIZE}-byte / 100 MB cap).`;
53
+ const judgedSize = preRead ? preRead.byteLength : pdf.size;
54
+ if (judgedSize > PDF_MAX_EXTRACT_SIZE) {
55
+ return `Error (Read): PDF "${path}" exceeds the maximum size for PDF reading (${judgedSize} bytes > ${PDF_MAX_EXTRACT_SIZE}-byte / 100 MB cap).`;
63
56
  }
57
+ const byName = pdf.object.byName;
58
+ const cannotRead = (bin) => `Error (Read): cannot read PDF "${path.slice(0, 300)}": ${envErrorDetail(bin.error.message)}`;
64
59
  let bytes = preRead;
65
- if (bytes === undefined && size <= PDF_TARGET_RAW_SIZE) {
66
- const bin = await env.readBinaryFile(key, signal, PDF_TARGET_RAW_SIZE + 1);
67
- if (!bin.ok)
68
- return `Error (Read): cannot read PDF "${path}": ${envErrorDetail(bin.error.message)}`;
69
- if (bin.value.byteLength <= PDF_TARGET_RAW_SIZE)
60
+ let input;
61
+ if (byName === undefined) {
62
+ if (bytes === undefined) {
63
+ const bin = await pdf.object.readBytes(PDF_MAX_EXTRACT_SIZE, signal);
64
+ if (!bin.ok)
65
+ return cannotRead(bin);
70
66
  bytes = bin.value;
67
+ }
68
+ input = { held: bytes };
69
+ }
70
+ else {
71
+ if (bytes === undefined && judgedSize <= PDF_TARGET_RAW_SIZE) {
72
+ const bin = await pdf.object.readBytes(PDF_TARGET_RAW_SIZE, signal);
73
+ if (!bin.ok)
74
+ return cannotRead(bin);
75
+ bytes = bin.value;
76
+ }
77
+ input = { byName };
71
78
  }
79
+ const size = bytes?.byteLength ?? judgedSize;
72
80
  if (bytes !== undefined && !pdfMagicMatches(bytes)) {
73
81
  return `Error (Read): "${path}" has a .pdf extension but its content is not a valid PDF (no %PDF- header; empty, truncated, or mis-named).`;
74
82
  }
@@ -80,7 +88,7 @@ export async function readPdfFile(env, path, key, pages, signal, imageProcessor,
80
88
  if (range.last !== Infinity && range.last - range.first + 1 > PDF_MAX_PAGES_PER_READ) {
81
89
  return `Error (Read): Page range "${pages}" exceeds maximum of ${PDF_MAX_PAGES_PER_READ} pages per request. Please use a smaller range.`;
82
90
  }
83
- const pageCount = await getPdfPageCount(env, key, bytes, signal, readFloor);
91
+ const pageCount = await getPdfPageCount(env, input, bytes, signal, readFloor);
84
92
  if (pageCount !== undefined && range.first > pageCount) {
85
93
  return `Error (Read): page range "${pages}" starts past the end of the PDF (${pageCount} page${pageCount === 1 ? "" : "s"}).`;
86
94
  }
@@ -88,7 +96,7 @@ export async function readPdfFile(env, path, key, pages, signal, imageProcessor,
88
96
  if (pageCount !== undefined)
89
97
  last = Math.min(last, pageCount);
90
98
  if (!cap.document && !cap.vision) {
91
- const t = await extractPdfTextLayer(env, key, { first: range.first, last }, signal, readFloor);
99
+ const t = await extractPdfTextLayer(env, input, { first: range.first, last }, signal, readFloor);
92
100
  if (t.ok) {
93
101
  const { body, truncated } = boundPdfExtractedText(t.text);
94
102
  const words = t.cut !== undefined ? pdfCutWords(t.cut) : undefined;
@@ -126,7 +134,7 @@ export async function readPdfFile(env, path, key, pages, signal, imageProcessor,
126
134
  },
127
135
  };
128
136
  }
129
- const extract = await extractPdfPagesAsImages(env, key, range.first, last, signal, readFloor);
137
+ const extract = await extractPdfPagesAsImages(env, input, range.first, last, signal, readFloor);
130
138
  if (!extract.ok) {
131
139
  if (extract.toolMissing) {
132
140
  return (`Error (Read): reading a PDF page range requires the poppler utility \`pdftoppm\`, which is not available in this environment. ` +
@@ -164,7 +172,7 @@ export async function readPdfFile(env, path, key, pages, signal, imageProcessor,
164
172
  },
165
173
  };
166
174
  }
167
- const pageCount = await getPdfPageCount(env, key, bytes, signal, readFloor);
175
+ const pageCount = await getPdfPageCount(env, input, bytes, signal, readFloor);
168
176
  if (pageCount !== undefined && pageCount > PDF_INLINE_PAGE_THRESHOLD) {
169
177
  return `Error (Read): This PDF has ${pageCount} pages, which is too many to read at once. Use the pages parameter to read specific page ranges (e.g., pages: "1-5"). Maximum ${PDF_MAX_PAGES_PER_READ} pages per request.`;
170
178
  }
@@ -173,7 +181,7 @@ export async function readPdfFile(env, path, key, pages, signal, imageProcessor,
173
181
  }
174
182
  if (!cap.document) {
175
183
  const fileCard = { type: "application/pdf", originalSize: size, ...(pageCount !== undefined ? { pageCount } : {}) };
176
- const t = await extractPdfTextLayer(env, key, undefined, signal, readFloor);
184
+ const t = await extractPdfTextLayer(env, input, undefined, signal, readFloor);
177
185
  if (t.ok) {
178
186
  const { body, truncated } = boundPdfExtractedText(t.text);
179
187
  const words = t.cut !== undefined ? pdfCutWords(t.cut) : undefined;
@@ -199,7 +207,7 @@ export async function readPdfFile(env, path, key, pages, signal, imageProcessor,
199
207
  let renderWhy;
200
208
  if (cap.vision) {
201
209
  const n = Math.min(PDF_FALLBACK_RENDER_PAGES, pageCount ?? PDF_FALLBACK_RENDER_PAGES);
202
- const extract = await extractPdfPagesAsImages(env, key, 1, n, signal, readFloor);
210
+ const extract = await extractPdfPagesAsImages(env, input, 1, n, signal, readFloor);
203
211
  if (extract.ok) {
204
212
  const blocks = await pdfPagesToImageBlocks(extract.pages, path, imageProcessor);
205
213
  if (typeof blocks !== "string") {
@@ -6,9 +6,10 @@ import { type ReadEntry, type ReadFileState, type RootsSeat } from "./safety.js"
6
6
  import { type ImageDimensions, type ImageDownsampler } from "../../core/image-downsample.js";
7
7
  import { type PdfModelCapabilities } from "./pdf.js";
8
8
  import { type CwdRef } from "./fs-shared.js";
9
+ import { type BoundOpening } from "./bound-open.js";
9
10
  import { type ReminderDisclosureCounts, type ReminderDisclosureEffects, type ReminderDisclosureVerdict } from "../../core/reminder-disclosure.js";
10
11
  import { type DirectoryListing } from "./dir-entries.js";
11
- import { FileError, type BoundFileObject, type Result } from "../../internal/harness.js";
12
+ import type { BoundFileObject, FileError, Result } from "../../internal/harness.js";
12
13
  import type { ContextRoomSeat } from "../../core/runner/context-room.js";
13
14
  /**
14
15
  * The Read tool, and the ONE read of a file for the model it is built on, split into three steps so every
@@ -43,8 +44,10 @@ import type { ContextRoomSeat } from "../../core/runner/context-room.js";
43
44
  */
44
45
  /** What happened to the file's contents. `partial` = a default read the token cap cut (the partial-view
45
46
  * marker); `not_attached` = nothing of the contents was served (a refusal, an offset past the end, a PDF whose
46
- * degradation chain bottomed out). A read of contents the request already carries is still `attached`: whether a
47
- * request sends them again is the request's own projection (`request-copy-projection.ts`), never the read's.
47
+ * degradation chain bottomed out). A read of contents the request already carries is still `attached`, never decided
48
+ * at the read: a Read result is sent as those contents on every request; an attachment frame may be sent as the
49
+ * sentence that they are not repeated beside an earlier copy (the request's own projection,
50
+ * `request-copy-projection.ts`).
48
51
  * Exported to carriers by the seat that needs it, not from the package. */
49
52
  export declare const READ_OUTCOMES: readonly ["attached", "partial", "not_attached"];
50
53
  export type ReadOutcome = (typeof READ_OUTCOMES)[number];
@@ -106,7 +109,7 @@ export type ReadNote = {
106
109
  kind: "disclosure";
107
110
  verdict: ReminderDisclosureVerdict;
108
111
  }
109
- /** A PDF read as a reference only (a bound read, {@link ReadForModelOptions.bound}): its size and page count, when known. */
112
+ /** A PDF read as a reference only ({@link ReadForModelOptions.pdfAsReference}): its size and page count, when known. */
110
113
  | {
111
114
  kind: "pdf_reference";
112
115
  bytes?: number;
@@ -145,10 +148,10 @@ export interface ReadForModelContext {
145
148
  }
146
149
  /** How a carrier other than the Read tool asks for the read. Absent members ⇒ exactly the Read tool's read. */
147
150
  export interface ReadForModelOptions {
148
- /** A BOUND read: the canonical key the carrier resolved and the object it holds open there ({@link ModelFileReader.openBound}),
149
- * the one it had judged. A path that resolves to another key is refused; the kind, the size and every byte come from the
150
- * held object, never from the path. A PDF is a reference only: its size from the held object, its page count from its
151
- * bytes up to the whole-send size (`pdf_reference` note). */
151
+ /** A read of an object the carrier holds: the canonical key the carrier resolved and the object it bound there
152
+ * ({@link ModelFileReader.openBound}), the one it had judged. A path that resolves to another key is refused; the kind,
153
+ * the size and every byte come from the bound object, never from the path — as they come from the object every read
154
+ * opens at its judged key. The carrier closes it. */
152
155
  bound?: {
153
156
  key: string;
154
157
  object: BoundFileObject;
@@ -158,7 +161,8 @@ export interface ReadForModelOptions {
158
161
  * context). */
159
162
  freshContext?: true;
160
163
  /** A carrier that presents the read as file data (an attachment frame) takes a PDF as a reference — its size and page
161
- * count, no pipeline run — since the Read projection interleaves engine text with the file's. A bound read always does. */
164
+ * count, no pipeline run — since the Read projection interleaves engine text with the file's. Nothing else makes a
165
+ * reference: a held object's PDF is read in full like any other. */
162
166
  pdfAsReference?: boolean;
163
167
  /** The canonical key the carrier's judgment of this path landed on, for a carrier that judged it without holding the
164
168
  * object (a bound read carries it as `bound.key`): a path whose final resolution is elsewhere is refused, the refusal
@@ -234,22 +238,25 @@ export interface ModelFileReader {
234
238
  refusal: ReadRefusal;
235
239
  }>;
236
240
  /** The file's text as the Read tool's text lane decodes it, with none of the Read's layout: the same resolution
237
- * (refused before anything is said about the file), the judged key held to it (`judgedKey`), one stat (`capBytes`
238
- * judged on it, never a cut), the bytes judged against the cap again, the lane's binary judgment and its decode — a
241
+ * (refused before anything is said about the file), the judged key held to it (`judgedKey`), the object opened there as
242
+ * the Read opens it (another object found there is `moved`), its size (`capBytes` judged on it, never a cut), the read
243
+ * judged against the cap again, the lane's binary judgment and its decode — a
239
244
  * body that is not UTF-8 is not text here (the write tools refuse to rewrite one). No line numbers, no window, no
240
245
  * dedup, no disclosure plan, and nothing recorded: a text read never stands for the model having read the file.
241
- * `bound`: the object the carrier holds at the key (`openBound`) — its bytes are read, with no path lookup after the judgment. */
246
+ * `opened`: the answer of the carrier's own `openBound` at the key, read as {@link BoundOpening} with no second open: held ⇒ its
247
+ * bytes are read, with no path lookup after the judgment; cannot bind ⇒ by name; refused ⇒ not read (as when this read's own open is refused). */
242
248
  readText(path: string, ctx: ReadForModelContext, opts: {
243
249
  judgedKey?: string;
244
250
  capBytes: number;
245
- bound?: {
251
+ opened?: {
246
252
  key: string;
247
- object: BoundFileObject;
253
+ opening: BoundOpening;
248
254
  };
249
255
  }): Promise<TextReading>;
250
- /** Open the object at a resolved key and hold it, for a carrier that judges and then reads that same object (the
251
- * environment's `openBound`; an environment without it cannot bind, and the answer says so). The carrier closes it. */
252
- openBound(key: string, signal?: AbortSignal): Promise<Result<BoundFileObject, FileError>>;
256
+ /** Bind a read to the object at a resolved key, for a carrier that judges and then reads that same object (the
257
+ * environment's `openBound`, read as {@link BoundOpening}: an environment with no `openBound`, or one that answers
258
+ * `not_supported` on the target, cannot bind). The carrier closes the object it is given. */
259
+ openBound(key: string, signal?: AbortSignal): Promise<BoundOpening>;
253
260
  /** One level of a held directory, every entry through the walk's per-entry read-deny judge. */
254
261
  listDirectory(bound: {
255
262
  key: string;
@@ -5,8 +5,9 @@ import { decodeTextBytes } from "./encoding.js";
5
5
  import { isNotebookPath, parseNotebookCells, renderNotebookCells, stripNotebookImageData, NOTEBOOK_IMAGE_BASE64_BUDGET } from "./notebook.js";
6
6
  import { resolveImageProcessor } from "../../core/image-downsample.js";
7
7
  import { countPdfPagesFromBytes, PDF_MAX_PAGES_PER_READ } from "./pdf.js";
8
- import { MAX_READ_BYTES, SLICED_READ_MAX_BYTES, noProcessorImageCapHint, MAX_READ_OUTPUT_CHARS, BASE_READ_TOKENS, FILE_PATH_PARAMS, countLines, enoentMessage, } from "./fs-shared.js";
8
+ import { MAX_READ_BYTES, SLICED_READ_MAX_BYTES, noProcessorImageCapHint, MAX_READ_OUTPUT_CHARS, BASE_READ_TOKENS, FILE_PATH_PARAMS, countLines, enoentMessage, witnessesAfterDelivery, } from "./fs-shared.js";
9
9
  import { envErrorDetail } from "./env-error-detail.js";
10
+ import { objectOfOpening, openBoundAt, readObjectAt, readWithin, sameKeyAgain } from "./bound-open.js";
10
11
  import { readPdfFile } from "./fs-pdf.js";
11
12
  import { seatForCall, seatReady } from "./read-deny.js";
12
13
  import { thrownText } from "../../core/thrown-value.js";
@@ -16,7 +17,6 @@ import { toolFace } from "../../core/tool-catalog-entries.js";
16
17
  import { fileArgPath } from "../../core/tool-registry.js";
17
18
  import { admitImageBytes, IMAGE_ADMISSION, imageReadCap, PDF_TARGET_RAW_SIZE, pdfMagicMatches, unprocessedSizeClause } from "../../core/image-admission.js";
18
19
  import { createEntryDenyJudge, enumerateDirectory } from "./dir-entries.js";
19
- import { FileError } from "../../internal/harness.js";
20
20
  export const READ_OUTCOMES = Object.freeze(["attached", "partial", "not_attached"]);
21
21
  function textLaneOf(bytes) {
22
22
  if (pdfMagicMatches(bytes))
@@ -31,7 +31,6 @@ function textLaneOf(bytes) {
31
31
  return { kind: "binary_content" };
32
32
  return { kind: "text", decoded };
33
33
  }
34
- const UNBINDABLE = "this environment cannot bind a read to the file that was checked, so it was not read";
35
34
  const LARGE_READ_CLAUSE = {
36
35
  read_anyway: " To read it anyway, up to what still fits in your context, call Read again with allow_large: true \u2014 only if you genuinely need all of it or the user asked for the whole file.",
37
36
  over_room: " Even with allow_large, this is more than fits in the context you have left this turn (other large reads in the same turn share that room).",
@@ -90,7 +89,17 @@ export function createModelFileReader(opts) {
90
89
  await seatReady(rootsSeat, ctx.signal);
91
90
  return resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, seatForCall(rootsSeat, ctx.toolCallId), bgOutputReadExemption === undefined ? undefined : (key) => bgOutputReadExemption(key, ctx), seatForCall(readDenySeat, ctx.toolCallId), readFace);
92
91
  };
92
+ const judgedAgain = (path, ctx, key) => sameKeyAgain((signal) => resolve(path, { ...ctx, signal: signal ?? ctx.signal }), key);
93
93
  const readForModel = async (args, ctx, opts) => {
94
+ const opened = {};
95
+ try {
96
+ return await readOnce(args, ctx, opts, opened);
97
+ }
98
+ finally {
99
+ await opened.object?.close();
100
+ }
101
+ };
102
+ const readOnce = async (args, ctx, opts, opened) => {
94
103
  const readDeny = seatForCall(readDenySeat, ctx.toolCallId);
95
104
  const { offset, limit, pages, allow_large: allowLarge } = (args ?? {});
96
105
  const optedIn = allowLarge === true;
@@ -100,20 +109,39 @@ export function createModelFileReader(opts) {
100
109
  const r = await resolve(path, ctx);
101
110
  if (!r.ok)
102
111
  return refuse(errorResult(violationText("Read", r.violation), violationDetails(r.violation)));
112
+ const moved = () => refuse(errorResult(`Error (Read): "${path.slice(0, 300)}" resolved to a different file while it was being checked, so it was not read.`, { type: "target_moved" }));
103
113
  const judgedKey = opts?.bound?.key ?? opts?.judgedKey;
104
- if (judgedKey !== undefined && r.key !== judgedKey) {
105
- return refuse(errorResult(`Error (Read): "${path.slice(0, 300)}" resolved to a different file while it was being checked, so it was not read.`, { type: "target_moved" }));
114
+ if (judgedKey !== undefined && r.key !== judgedKey)
115
+ return moved();
116
+ let info;
117
+ const sized = async (object) => {
118
+ const s = await object.size();
119
+ return s.ok ? { ok: true, value: { kind: object.kind, size: s.value, object } } : s;
120
+ };
121
+ let notOpened = false;
122
+ if (opts?.bound !== undefined)
123
+ info = await sized(opts.bound.object);
124
+ else {
125
+ const o = await readObjectAt(env, r.key, judgedAgain(path, ctx, r.key), ctx.signal);
126
+ if (!o.ok && o.error.code === "precondition_failed")
127
+ return moved();
128
+ if (o.ok)
129
+ opened.object = o.value;
130
+ else
131
+ notOpened = o.step === "open";
132
+ info = o.ok ? await sized(o.value) : o;
106
133
  }
107
- const bound = opts?.bound;
108
- const readBytes = async (key, laneCap) => {
109
- if (bound !== undefined)
110
- return bound.object.readBytes(laneCap, ctx.signal);
111
- const got = await env.readBinaryFile(key, ctx.signal, laneCap + 1);
112
- return got.ok && got.value.byteLength > laneCap
113
- ? { ok: false, error: new FileError("invalid", `The file is over the ${laneCap}-byte read cap (${got.value.byteLength} bytes or more); it was not read`, key) }
114
- : got;
134
+ const unreadImage = (r) => errorResult(`Error (Read): cannot read image "${path}": ${envErrorDetail(r.error.message)}`);
135
+ const unreadPdf = (r) => errorResult(`Error (Read): cannot read PDF "${path.slice(0, 300)}": ${envErrorDetail(r.error.message)}`);
136
+ const unreadText = (r) => errorResult(`Error (Read): cannot read "${path}": ${envErrorDetail(r.error.message)}`);
137
+ const missing = async (kind) => {
138
+ if (opts?.bound !== undefined || opened.object !== undefined)
139
+ return undefined;
140
+ const ex = await env.exists(r.key, ctx.signal);
141
+ if (!ex.ok || ex.value)
142
+ return undefined;
143
+ return refuse(errorResult(`Error (Read): ${await enoentMessage(env, r.key, cwdRef?.current ?? rootCanonical, ctx.signal, readDeny)}`), kind);
115
144
  };
116
- const info = bound === undefined ? await env.fileInfo(r.key, ctx.signal) : await bound.object.size().then((s) => (s.ok ? { ok: true, value: { kind: bound.object.kind, size: s.value } } : s));
117
145
  if (info.ok && info.value.kind === "directory") {
118
146
  return refuse(errorResult(`Error (Read): "${path}" is a directory, not a file; use glob/grep or list it with the shell.`), "directory");
119
147
  }
@@ -122,10 +150,7 @@ export function createModelFileReader(opts) {
122
150
  if (imageMime !== undefined) {
123
151
  const meta = info;
124
152
  if (!meta.ok) {
125
- const ex = await env.exists(r.key, ctx.signal);
126
- if (ex.ok && !ex.value)
127
- return refuse(errorResult(`Error (Read): ${await enoentMessage(env, r.key, cwdRef?.current ?? rootCanonical, ctx.signal, readDeny)}`), "image");
128
- return refuse(errorResult(`Error (Read): cannot stat image "${path}" to verify its size before reading: ${envErrorDetail(meta.error.message)}`), "image");
153
+ return (await missing("image")) ?? refuse(notOpened ? unreadImage(meta) : errorResult(`Error (Read): cannot stat image "${path}" to verify its size before reading: ${envErrorDetail(meta.error.message)}`), "image");
129
154
  }
130
155
  const processor = await resolveImageProcessor(imageProcessor);
131
156
  const readCap = imageReadCap(processor);
@@ -133,9 +158,9 @@ export function createModelFileReader(opts) {
133
158
  const tooLargeToRead = (bytes) => `Error (Read): image "${path}" is too large to read (${bytes} bytes > ${readCap}-byte cap).${noProcessorHint}`;
134
159
  if (meta.value.size > readCap)
135
160
  return refuse(errorResult(tooLargeToRead(meta.value.size)), "image");
136
- const bin = await readBytes(r.key, readCap);
161
+ const bin = await meta.value.object.readBytes(readCap, ctx.signal);
137
162
  if (!bin.ok)
138
- return refuse(errorResult(`Error (Read): cannot read image "${path}": ${envErrorDetail(bin.error.message)}`), "image");
163
+ return refuse(unreadImage(bin), "image");
139
164
  const admitted = await admitImageBytes(bin.value, imageMime, processor);
140
165
  if (!admitted.ok) {
141
166
  switch (admitted.reason) {
@@ -168,14 +193,14 @@ export function createModelFileReader(opts) {
168
193
  };
169
194
  }
170
195
  const pdfOf = async (preRead) => {
171
- if (bound !== undefined || opts?.pdfAsReference === true) {
196
+ if (opts?.pdfAsReference === true) {
172
197
  if (!info.ok)
173
- return refuse(errorResult(`Error (Read): cannot size PDF "${path.slice(0, 300)}": ${envErrorDetail(info.error.message)}`), "pdf");
198
+ return refuse(notOpened ? unreadPdf(info) : errorResult(`Error (Read): cannot size PDF "${path.slice(0, 300)}": ${envErrorDetail(info.error.message)}`), "pdf");
174
199
  let held = preRead;
175
200
  if (held === undefined && info.value.size <= PDF_TARGET_RAW_SIZE) {
176
- const got = await readBytes(r.key, PDF_TARGET_RAW_SIZE);
201
+ const got = await info.value.object.readBytes(PDF_TARGET_RAW_SIZE, ctx.signal);
177
202
  if (!got.ok)
178
- return refuse(errorResult(`Error (Read): cannot read PDF "${path.slice(0, 300)}": ${envErrorDetail(got.error.message)}`), "pdf");
203
+ return refuse(unreadPdf(got), "pdf");
179
204
  held = got.value;
180
205
  }
181
206
  const pageCount = held !== undefined ? countPdfPagesFromBytes(held) : undefined;
@@ -187,8 +212,11 @@ export function createModelFileReader(opts) {
187
212
  effects: NO_EFFECTS(),
188
213
  };
189
214
  }
215
+ if (!info.ok) {
216
+ return (await missing("pdf")) ?? refuse(notOpened ? unreadPdf(info) : errorResult(`Error (Read): cannot stat PDF "${path.slice(0, 300)}" to verify its size before reading: ${envErrorDetail(info.error.message)}`), "pdf");
217
+ }
190
218
  const effects = [];
191
- const out = await readPdfFile(env, path, r.key, pages, ctx.signal, imageProcessor, cwdRef?.current ?? rootCanonical, preRead, pdfCapabilities, readDeny, {
219
+ const out = await readPdfFile(env, path, { object: info.value.object, size: info.value.size }, pages, ctx.signal, imageProcessor, preRead, pdfCapabilities, readDeny, {
192
220
  mark: reminderMark,
193
221
  windows,
194
222
  key: r.key,
@@ -243,14 +271,11 @@ export function createModelFileReader(opts) {
243
271
  }
244
272
  }
245
273
  else {
246
- const ex = await env.exists(r.key, ctx.signal);
247
- if (ex.ok && !ex.value)
248
- return refuse(errorResult(`Error (Read): ${await enoentMessage(env, r.key, cwdRef?.current ?? rootCanonical, ctx.signal, readDeny)}`), "text");
249
- return refuse(errorResult(`Error (Read): cannot determine the type of "${path.slice(0, 300)}" (stat failed: ${envErrorDetail(info.error.message)}); refusing to open it — if it is a FIFO/socket/device, reading it would hang. Retry if this was transient, or inspect it with Bash (e.g. \`file\`, \`ls -l\`).`), "text");
274
+ return (await missing("text")) ?? refuse(notOpened ? unreadText(info) : errorResult(`Error (Read): cannot determine the type of "${path.slice(0, 300)}" (stat failed: ${envErrorDetail(info.error.message)}); refusing to open it — if it is a FIFO/socket/device, reading it would hang. Retry if this was transient, or inspect it with Bash (e.g. \`file\`, \`ls -l\`).`), "text");
250
275
  }
251
- const readBin = await readBytes(r.key, !isNb && limit === undefined ? wholeCap : SLICED_READ_MAX_BYTES);
276
+ const readBin = await info.value.object.readBytes(!isNb && limit === undefined ? wholeCap : SLICED_READ_MAX_BYTES, ctx.signal);
252
277
  if (!readBin.ok)
253
- return refuse(errorResult(`Error (Read): cannot read "${path}": ${envErrorDetail(readBin.error.message)}`), "text");
278
+ return refuse(unreadText(readBin), "text");
254
279
  const lane = textLaneOf(readBin.value);
255
280
  if (lane.kind === "pdf")
256
281
  return pdfOf(readBin.value);
@@ -400,41 +425,48 @@ export function createModelFileReader(opts) {
400
425
  const r = await resolve(path, ctx).catch((err) => ({ ok: false, violation: { code: "invalid", message: thrownText(err) } }));
401
426
  return r.ok ? { ok: true, key: r.key } : { ok: false, refusal: errorResult(violationText("Read", r.violation), violationDetails(r.violation)) };
402
427
  },
403
- async readText(path, ctx, { judgedKey, capBytes, bound }) {
428
+ async readText(path, ctx, { judgedKey, capBytes, opened }) {
404
429
  const r = await resolve(path, ctx).catch(() => undefined);
405
430
  if (r === undefined || !r.ok)
406
431
  return { kind: "refused" };
407
432
  if (judgedKey !== undefined && r.key !== judgedKey)
408
433
  return { kind: "moved" };
409
- if (bound !== undefined) {
410
- if (bound.key !== r.key)
411
- return { kind: "moved" };
412
- if (bound.object.kind === "directory")
434
+ if (opened !== undefined && opened.key !== r.key)
435
+ return { kind: "moved" };
436
+ if (opened?.opening.kind === "bound") {
437
+ const object = opened.opening.object;
438
+ if (object.kind === "directory")
413
439
  return { kind: "not_text" };
414
- const held = await bound.object.readBytes(capBytes, ctx.signal);
440
+ const held = await object.readBytes(capBytes, ctx.signal);
415
441
  if (!held.ok)
416
442
  return held.error.code === "invalid" ? { kind: "oversize" } : { kind: "unavailable" };
417
443
  const heldLane = textLaneOf(held.value);
418
444
  return heldLane.kind === "text" && heldLane.decoded.malformed === undefined ? { kind: "text", text: heldLane.decoded.text } : { kind: "not_text" };
419
445
  }
420
- const info = await env.fileInfo(r.key, ctx.signal);
421
- if (!info.ok) {
446
+ const rejudge = judgedAgain(path, ctx, r.key);
447
+ const o = opened !== undefined ? await objectOfOpening(env, r.key, rejudge, opened.opening, ctx.signal) : await readObjectAt(env, r.key, rejudge, ctx.signal);
448
+ if (!o.ok) {
449
+ if (o.error.code === "precondition_failed")
450
+ return { kind: "moved" };
422
451
  const ex = await env.exists(r.key, ctx.signal);
423
452
  return ex.ok && !ex.value ? { kind: "absent" } : { kind: "unavailable" };
424
453
  }
425
- if (info.value.kind === "directory")
426
- return { kind: "not_text" };
427
- if (info.value.size > capBytes)
428
- return { kind: "oversize" };
429
- const bin = await env.readBinaryFile(r.key, ctx.signal, capBytes + 1);
430
- if (!bin.ok)
431
- return { kind: "unavailable" };
432
- if (bin.value.byteLength > capBytes)
433
- return { kind: "oversize" };
434
- const lane = textLaneOf(bin.value);
435
- return lane.kind === "text" && lane.decoded.malformed === undefined ? { kind: "text", text: lane.decoded.text } : { kind: "not_text" };
454
+ try {
455
+ if (o.value.kind === "directory")
456
+ return { kind: "not_text" };
457
+ const read = await readWithin(o.value, capBytes, ctx.signal);
458
+ if (read.kind === "over")
459
+ return { kind: "oversize" };
460
+ if (read.kind === "failed")
461
+ return { kind: read.error.code === "precondition_failed" ? "moved" : "unavailable" };
462
+ const lane = textLaneOf(read.bytes);
463
+ return lane.kind === "text" && lane.decoded.malformed === undefined ? { kind: "text", text: lane.decoded.text } : { kind: "not_text" };
464
+ }
465
+ finally {
466
+ await o.value.close();
467
+ }
436
468
  },
437
- openBound: (key, signal) => (env.openBound !== undefined ? env.openBound(key, signal) : Promise.resolve({ ok: false, error: new FileError("not_supported", UNBINDABLE, key) })),
469
+ openBound: (key, signal) => openBoundAt(env, key, signal),
438
470
  listDirectory: (bound, signal) => enumerateDirectory(env, bound.key, readDenySeat !== undefined ? createEntryDenyJudge(env, readDenySeat, signal) : undefined, signal, () => bound.object.list(signal)),
439
471
  planDisclosure(segments, throttleKey) {
440
472
  const d = disclosureOf(segments, "read", throttleKey);
@@ -447,8 +479,7 @@ export function createModelFileReader(opts) {
447
479
  if (result.observation !== undefined) {
448
480
  const entry = result.observation.entry;
449
481
  const prior = state.get(result.observation.key);
450
- const sameBody = prior !== undefined && prior.hash === entry.hash && prior.view?.start === entry.view?.start && prior.view?.end === entry.view?.end && prior.isPartialView === entry.isPartialView;
451
- const witnesses = [...new Set([...(sameBody ? (prior.witnesses ?? []) : []), ...(at?.transmittedByToolCallId !== undefined ? [at.transmittedByToolCallId] : [])])];
482
+ const witnesses = witnessesAfterDelivery(prior, entry, at?.transmittedByToolCallId);
452
483
  state.set(result.observation.key, {
453
484
  ...entry,
454
485
  lastReadAt: at?.now ?? Date.now(),
@@ -237,8 +237,8 @@ export declare function bashTimeoutArgRefusal(timeoutMs: number | undefined, cap
237
237
  export declare function resolveBashTimeoutCaps(opts?: {
238
238
  bashDefaultTimeoutMs?: number;
239
239
  bashMaxTimeoutMs?: number;
240
- /** Structured seat for the discard announcements below — wired, it REPLACES their `console.warn`
241
- * (same ledger, same lines as `message`); absent, the console line prints verbatim. Threaded from
240
+ /** Structured seat for the discard announcements below — wired, it REPLACES their process line
241
+ * (same ledger, same lines as `message`); absent, the process's default seat, else the line verbatim. Threaded from
242
242
  * the toolkit assembly (ultimately `RunnerDeps.onNotice`); never a global. */
243
243
  onNotice?: (n: EngineNotice) => void;
244
244
  }): {
@@ -404,13 +404,6 @@ export declare function ipynbRedirect(toolName: string, path: string): string |
404
404
  * ends in "\n". Behavior is identical for content WITHOUT a trailing newline. Shared by read_file's
405
405
  * `total`, edit_file/write_file's "N lines" report, and the persisted ReadFileState.totalLines. */
406
406
  export declare function countLines(s: string): number;
407
- /** The sentence a request carries in place of a whole-file Read of a file this leg seeded into its system prompt,
408
- * unchanged (`request-copy-projection.ts`; the result itself stores the contents). `filePath` is the CANONICAL key (CC passes the resolved full path, matching the
409
- * `Contents of <path>` header its context seeding emits — deployments seeding files should title the
410
- * injected block the same way so the back-reference lands). Locked verbatim by test: the BODY and
411
- * close tag stay fixed; the open tag alone is rendered by the mint home and carries the session
412
- * mark when one is threaded (the recorded wire-form divergence). */
413
- export declare function seededFileUnchangedReminder(filePath: string, mark?: string): string;
414
407
  /** Pre-seed the hands' read state for a file whose FULL, disk-verbatim text was injected into the
415
408
  * model's context at startup (`seededFromContext` seeding of the memory preload; sema: the memory
416
409
  * engine's materialized index → prepare-task).
@@ -419,7 +412,8 @@ export declare function seededFileUnchangedReminder(filePath: string, mark?: str
419
412
  * `isPartialView`; sema's contract is simply "don't seed partials"). `key` is the CANONICAL path
420
413
  * (resolveKey output), so it collides correctly with real Read/Edit entries. Note the CC-faithful
421
414
  * side effect: a seeded file passes read-before-edit (the model legitimately has the full text).
422
- * Returns the hash the entry carries — the leg's seed table (the request projection's seeded sentence) records it. */
415
+ * Returns the hash the entry carries — the leg's seed table (the request projection's seeded sentence for an attachment
416
+ * frame of the file) records it. A Read of the file is its contents, as any Read. */
423
417
  export declare function seedReadFileStateFromContext(state: ReadFileState, key: string, content: string): string;
424
418
  /**
425
419
  * Seed the hands' read state from a WHOLE-file content the session transcript recorded on an earlier
@@ -437,14 +431,22 @@ export declare function seedReadFileStateFromContext(state: ReadFileState, key:
437
431
  * drops the result retires the entry; a Write's post-condition rode no result body and carries none.
438
432
  */
439
433
  export declare function seedReadFileStateFromTranscript(state: ReadFileState, key: string, content: string, lastReadAt: number, transmission?: string): void;
434
+ /**
435
+ * The witness set an entry holds once one delivery of `entry`'s body lands — the ONE joining rule every delivery that
436
+ * records a read state entry follows (a Read result, an instruction-file frame; see {@link ReadEntry.witnesses}). A delivery
437
+ * of the same contents in the same window as the `prior` entry joins its set (the older copies still carry the body:
438
+ * a trim or a clear that takes one leaves the entry standing while another stays); a delivery of anything else starts the
439
+ * set over. `transmission` absent (a delivery that carries no id) adds nothing.
440
+ */
441
+ export declare function witnessesAfterDelivery(prior: ReadEntry | undefined, entry: Pick<ReadEntry, "hash" | "truncated" | "view" | "isPartialView">, transmission: string | undefined): string[];
440
442
  /**
441
443
  * The entries a leg may carry out of ANOTHER leg's read state — the one answer every cross-leg carrier reads (the
442
444
  * same-Runner inheritance arm below, the durable resume's checkpoint seed): all of them but the seeded ones.
443
445
  *
444
446
  * `seededFromContext` claims the file's text lives in the system-prompt lane OF THAT LEG — a claim only the receiving
445
447
  * leg's own startup seeding can make. A still-declared file is seeded again on the receiving leg (no loss); one the
446
- * receiving deployment no longer declares must not keep answering a Read with an "already in your context" reminder
447
- * that is no longer true, nor keep admitting an Edit the model never saw the text for. The filter is on the READ side:
448
+ * receiving deployment no longer declares must not keep admitting an Edit the model never saw the text for. The filter is
449
+ * on the READ side:
448
450
  * a checkpoint row an earlier release wrote still carries the flag, and is one case with a new row.
449
451
  *
450
452
  * Entries are returned by REFERENCE, in the source's order (ReadEntry values are never mutated in place).
@@ -8,7 +8,6 @@ import { homeViewsOf } from "./read-deny-home.js";
8
8
  import { IMAGE_ADMISSION } from "../../core/image-admission.js";
9
9
  import { deliverEngineNotice } from "../../core/types.js";
10
10
  import { resolveEnvBudget } from "../../core/env-budget.js";
11
- import { openSystemReminder } from "../../core/reminder-mint.js";
12
11
  export const MAX_READ_BYTES = 256 * 1024;
13
12
  export const SLICED_READ_MAX_BYTES = 64 * 1024 * 1024;
14
13
  export const MAX_EDIT_BYTES = 1024 * 1024 * 1024;
@@ -326,9 +325,6 @@ export function countLines(s) {
326
325
  const n = s.split("\n").length;
327
326
  return s.endsWith("\n") ? n - 1 : n;
328
327
  }
329
- export function seededFileUnchangedReminder(filePath, mark) {
330
- return `${openSystemReminder(mark)}This file is already in your context (see "Contents of ${filePath}" above) and has not changed on disk. Use that content instead of re-reading.</system-reminder>`;
331
- }
332
328
  export function seedReadFileStateFromContext(state, key, content) {
333
329
  const hash = sha256(normalizeFileText(content));
334
330
  state.set(key, { hash, totalLines: countLines(content), truncated: false, lastReadAt: Date.now(), seededFromContext: true });
@@ -338,6 +334,11 @@ export function seedReadFileStateFromTranscript(state, key, content, lastReadAt,
338
334
  const text = normalizeFileText(content);
339
335
  state.set(key, { hash: sha256(text), totalLines: countLines(text), truncated: false, lastReadAt, ...(transmission !== undefined ? { witnesses: [transmission] } : {}) });
340
336
  }
337
+ export function witnessesAfterDelivery(prior, entry, transmission) {
338
+ const sameBody = prior !== undefined && prior.hash === entry.hash && deliveredWindow(prior) === deliveredWindow(entry);
339
+ return [...new Set([...(sameBody ? (prior.witnesses ?? []) : []), ...(transmission !== undefined ? [transmission] : [])])];
340
+ }
341
+ const deliveredWindow = (e) => e.truncated === false ? "whole" : `${e.view?.start}-${e.view?.end}:${e.isPartialView === true}`;
341
342
  export function entriesCarriedAcrossLegs(entries) {
342
343
  const kept = [];
343
344
  for (const [key, entry] of entries)
@@ -2,7 +2,7 @@ import type { AgentTool, ExecutionEnv } from "../../internal/harness-types.js";
2
2
  import type { BeforeWriteHook, FileEditedHook, TrackFileEditHook } from "../../core/types.js";
3
3
  import { type ReadFileState } from "./safety.js";
4
4
  import type { ContainmentFace } from "./containment-face.js";
5
- import { type WriteDenyMatcher } from "./read-deny.js";
5
+ import { type ReadDenyMatcher, type WriteDenyMatcher } from "./read-deny.js";
6
6
  import { type CwdRef } from "./fs-shared.js";
7
7
  import type { ToolResultStore } from "../../core/tool-result-store.js";
8
8
  /**
@@ -18,7 +18,7 @@ export type { BeforeWriteRequest, BeforeWriteResult, BeforeWriteHook, TrackEditR
18
18
  /** A write tool's primary containment root: fixed, or a getter over the leg's live write location (read once per call, so an
19
19
  * EnterWorktree switch moves where the next write may land). Canonical in both forms. */
20
20
  export type WriteRootSeat = string | (() => string);
21
- export declare function createEditFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: WriteRootSeat, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook, onEdited?: FileEditedHook, writeFace?: () => ContainmentFace, writeDeny?: WriteDenyMatcher): AgentTool;
21
+ export declare function createEditFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: WriteRootSeat, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook, onEdited?: FileEditedHook, writeFace?: () => ContainmentFace, writeDeny?: WriteDenyMatcher, readDeny?: ReadDenyMatcher): AgentTool;
22
22
  export declare function createWriteFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: WriteRootSeat, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook, onEdited?: FileEditedHook, writeFace?: () => ContainmentFace, writeDeny?: WriteDenyMatcher): AgentTool;
23
23
  /** The reads SaveToolResult makes of the run's tool-result store: the one way a ref is read (text first, then bytes). */
24
24
  export type KeptBytesReader = Pick<ToolResultStore, "get" | "bytesOf">;