@sema-agent/core 7.59.0 → 7.60.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 (360) hide show
  1. package/CHANGELOG.md +564 -0
  2. package/dist/agents/agent-definition.d.ts +7 -0
  3. package/dist/agents/agent-definition.js +12 -0
  4. package/dist/agents/agent-transcript-tool.d.ts +2 -1
  5. package/dist/agents/agent-transcript-tool.js +3 -1
  6. package/dist/agents/child-model-seat.js +6 -3
  7. package/dist/agents/cumulative-stats.js +0 -1
  8. package/dist/agents/inherited-tool-pool.d.ts +26 -1
  9. package/dist/agents/inherited-tool-pool.js +22 -0
  10. package/dist/agents/retain-ledger.d.ts +11 -1
  11. package/dist/agents/retain-ledger.js +13 -2
  12. package/dist/agents/roster-store.d.ts +1 -1
  13. package/dist/agents/roster-store.js +3 -1
  14. package/dist/agents/send-message-tool.d.ts +8 -19
  15. package/dist/agents/send-message-tool.js +11 -38
  16. package/dist/agents/subagent.d.ts +51 -17
  17. package/dist/agents/subagent.js +117 -78
  18. package/dist/agents/tool-filter.d.ts +1 -3
  19. package/dist/agents/tool-filter.js +4 -12
  20. package/dist/bench/metrics.d.ts +3 -5
  21. package/dist/bench/metrics.js +0 -1
  22. package/dist/brain/degrading.js +3 -1
  23. package/dist/brain/route-adjudicator.js +3 -1
  24. package/dist/brain/status-sink.d.ts +7 -1
  25. package/dist/brain/status-sink.js +6 -0
  26. package/dist/brain/timeout.d.ts +3 -1
  27. package/dist/brain/timeout.js +18 -5
  28. package/dist/core/a2a.d.ts +15 -5
  29. package/dist/core/a2a.js +34 -19
  30. package/dist/core/agent-definition.d.ts +20 -0
  31. package/dist/core/allow-entry.d.ts +2 -0
  32. package/dist/core/allow-entry.js +3 -1
  33. package/dist/core/artifact-host.d.ts +0 -2
  34. package/dist/core/artifact-host.js +0 -1
  35. package/dist/core/auto-mode-defaults.d.ts +8 -0
  36. package/dist/core/auto-mode-defaults.js +1 -0
  37. package/dist/core/auto-mode-rebuild.d.ts +2 -1
  38. package/dist/core/auto-mode.d.ts +39 -4
  39. package/dist/core/auto-mode.js +63 -12
  40. package/dist/core/background-agent-store.d.ts +10 -1
  41. package/dist/core/background-agent-store.js +3 -2
  42. package/dist/core/background-shell.d.ts +12 -1
  43. package/dist/core/background-shell.js +12 -0
  44. package/dist/core/checkpoint-store.d.ts +8 -13
  45. package/dist/core/checkpoint-store.js +4 -3
  46. package/dist/core/compliance.d.ts +1 -1
  47. package/dist/core/credential-echo.d.ts +52 -0
  48. package/dist/core/credential-echo.js +65 -0
  49. package/dist/core/credential-vocabulary.d.ts +13 -3
  50. package/dist/core/credential-vocabulary.js +12 -4
  51. package/dist/core/cross-boundary-taint.d.ts +4 -5
  52. package/dist/core/engine-notice.d.ts +58 -15
  53. package/dist/core/frame-settlement.d.ts +5 -0
  54. package/dist/core/frame-settlement.js +4 -0
  55. package/dist/core/gate-fold.js +7 -5
  56. package/dist/core/gate-lanes.js +39 -8
  57. package/dist/core/governance-codes.d.ts +9 -1
  58. package/dist/core/governance-codes.js +12 -0
  59. package/dist/core/hands-band-screen.js +0 -1
  60. package/dist/core/hands-band.d.ts +0 -3
  61. package/dist/core/hooks.d.ts +39 -56
  62. package/dist/core/hooks.js +123 -77
  63. package/dist/core/image-admission.d.ts +104 -51
  64. package/dist/core/image-admission.js +170 -46
  65. package/dist/core/image-downsample.d.ts +36 -69
  66. package/dist/core/image-downsample.js +111 -73
  67. package/dist/core/integer-option.d.ts +21 -0
  68. package/dist/core/integer-option.js +13 -0
  69. package/dist/core/locked-config.d.ts +54 -3
  70. package/dist/core/locked-config.js +81 -50
  71. package/dist/core/mcp-call-meta.d.ts +2 -2
  72. package/dist/core/mcp-call-meta.js +9 -10
  73. package/dist/core/mcp-failure.d.ts +9 -3
  74. package/dist/core/mcp-failure.js +10 -0
  75. package/dist/core/mcp-host-seat.d.ts +92 -0
  76. package/dist/core/mcp-host-seat.js +131 -0
  77. package/dist/core/mcp-probe.d.ts +7 -2
  78. package/dist/core/mcp-probe.js +7 -2
  79. package/dist/core/mcp-server-spec.d.ts +38 -9
  80. package/dist/core/mcp-server-spec.js +55 -21
  81. package/dist/core/mcp.d.ts +17 -6
  82. package/dist/core/mcp.js +67 -55
  83. package/dist/core/memory-admission.d.ts +23 -6
  84. package/dist/core/memory-admission.js +19 -9
  85. package/dist/core/memory-engine/content-origin.d.ts +13 -0
  86. package/dist/core/memory-engine/content-origin.js +21 -3
  87. package/dist/core/memory-engine/index.d.ts +2 -1
  88. package/dist/core/memory-engine/index.js +2 -1
  89. package/dist/core/memory-engine/scope-contract.d.ts +13 -3
  90. package/dist/core/memory-engine/scope-contract.js +2 -2
  91. package/dist/core/memory-engine/sync-client.d.ts +45 -11
  92. package/dist/core/memory-engine/sync-client.js +82 -11
  93. package/dist/core/memory-engine/sync-report.d.ts +103 -0
  94. package/dist/core/memory-engine/sync-report.js +119 -0
  95. package/dist/core/memory-engine/sync.d.ts +4 -2
  96. package/dist/core/mode-policy.d.ts +9 -1
  97. package/dist/core/mode-policy.js +11 -1
  98. package/dist/core/model-receipt.d.ts +39 -0
  99. package/dist/core/model-receipt.js +139 -0
  100. package/dist/core/mods/agent-stations.d.ts +65 -0
  101. package/dist/core/mods/agent-stations.js +105 -0
  102. package/dist/core/mods/kernel/dispatch.d.ts +5 -1
  103. package/dist/core/mods/kernel/dispatch.js +4 -4
  104. package/dist/core/mods/kernel/events.d.ts +10 -4
  105. package/dist/core/mods/kernel/events.js +10 -6
  106. package/dist/core/mods/kernel/receive.d.ts +5 -0
  107. package/dist/core/mods/kernel/receive.js +10 -0
  108. package/dist/core/mods/lifecycle-stations.d.ts +41 -0
  109. package/dist/core/mods/lifecycle-stations.js +35 -0
  110. package/dist/core/mods/stations.d.ts +51 -59
  111. package/dist/core/mods/stations.js +32 -42
  112. package/dist/core/mods/tool-call.d.ts +10 -4
  113. package/dist/core/mods/tool-call.js +28 -12
  114. package/dist/core/mounted-mcp.d.ts +5 -0
  115. package/dist/core/mounted-mcp.js +2 -2
  116. package/dist/core/namespaced-rule-name.d.ts +7 -1
  117. package/dist/core/namespaced-rule-name.js +13 -2
  118. package/dist/core/oracle-isolation.js +1 -1
  119. package/dist/core/own-property-receipt.d.ts +3 -0
  120. package/dist/core/own-property-receipt.js +3 -0
  121. package/dist/core/park-selfcheck.js +8 -8
  122. package/dist/core/peer-seat.d.ts +63 -8
  123. package/dist/core/peer-seat.js +179 -34
  124. package/dist/core/permission-rule-consent.d.ts +0 -21
  125. package/dist/core/permission-rule-consent.js +1 -2
  126. package/dist/core/permission-rule-model.d.ts +4 -2
  127. package/dist/core/permission-rule-model.js +7 -6
  128. package/dist/core/protocol-http-auth.d.ts +14 -2
  129. package/dist/core/protocol-http-auth.js +16 -7
  130. package/dist/core/read-face-seats.d.ts +7 -5
  131. package/dist/core/read-face-seats.js +4 -1
  132. package/dist/core/redaction-marks.d.ts +4 -3
  133. package/dist/core/redaction-marks.js +2 -2
  134. package/dist/core/remote-env.d.ts +146 -98
  135. package/dist/core/remote-env.js +113 -14
  136. package/dist/core/retention.js +37 -12
  137. package/dist/core/retired-keys.d.ts +6 -1
  138. package/dist/core/retired-keys.js +4 -1
  139. package/dist/core/rewrite-rejudge.d.ts +12 -5
  140. package/dist/core/rewrite-rejudge.js +9 -5
  141. package/dist/core/roles.d.ts +37 -3
  142. package/dist/core/roles.js +126 -78
  143. package/dist/core/rule-owner.d.ts +3 -0
  144. package/dist/core/runner/assemble-result.d.ts +0 -5
  145. package/dist/core/runner/assemble-result.js +0 -1
  146. package/dist/core/runner/call-hook-stations.d.ts +17 -10
  147. package/dist/core/runner/call-hook-stations.js +21 -10
  148. package/dist/core/runner/child-tree.d.ts +7 -8
  149. package/dist/core/runner/child-tree.js +6 -6
  150. package/dist/core/runner/classifier-ladder.d.ts +10 -2
  151. package/dist/core/runner/classifier-ladder.js +39 -8
  152. package/dist/core/runner/construction-doors.js +5 -0
  153. package/dist/core/runner/contracts.d.ts +62 -41
  154. package/dist/core/runner/cross-boundary-lane.d.ts +3 -5
  155. package/dist/core/runner/cross-boundary-lane.js +11 -2
  156. package/dist/core/runner/env-capability-census.d.ts +15 -20
  157. package/dist/core/runner/env-capability-census.js +25 -34
  158. package/dist/core/runner/file-history-request.d.ts +2 -2
  159. package/dist/core/runner/file-history-request.js +0 -8
  160. package/dist/core/runner/gate-exit.d.ts +75 -7
  161. package/dist/core/runner/gate-exit.js +20 -1
  162. package/dist/core/runner/git-status-frame.d.ts +5 -2
  163. package/dist/core/runner/git-status-frame.js +3 -4
  164. package/dist/core/runner/image.d.ts +7 -2
  165. package/dist/core/runner/image.js +14 -8
  166. package/dist/core/runner/inline-image.d.ts +10 -8
  167. package/dist/core/runner/inline-image.js +11 -9
  168. package/dist/core/runner/memory-consolidation-driver.js +4 -4
  169. package/dist/core/runner/permission-rule-lanes.js +1 -1
  170. package/dist/core/runner/prepare-boundary-parks.d.ts +2 -2
  171. package/dist/core/runner/prepare-boundary-parks.js +3 -3
  172. package/dist/core/runner/prepare-caps-and-workflow.d.ts +4 -0
  173. package/dist/core/runner/prepare-caps-and-workflow.js +4 -3
  174. package/dist/core/runner/prepare-config-doors.d.ts +6 -1
  175. package/dist/core/runner/prepare-config-doors.js +14 -9
  176. package/dist/core/runner/prepare-delegation-surface.d.ts +5 -3
  177. package/dist/core/runner/prepare-delegation-surface.js +4 -4
  178. package/dist/core/runner/prepare-file-history.d.ts +10 -12
  179. package/dist/core/runner/prepare-file-history.js +3 -12
  180. package/dist/core/runner/prepare-gate-stations.d.ts +4 -3
  181. package/dist/core/runner/prepare-gate-stations.js +4 -3
  182. package/dist/core/runner/prepare-hands-readface.d.ts +3 -1
  183. package/dist/core/runner/prepare-hands-readface.js +15 -7
  184. package/dist/core/runner/prepare-inherited-gate.d.ts +5 -4
  185. package/dist/core/runner/prepare-inherited-gate.js +9 -5
  186. package/dist/core/runner/prepare-memory-engine-session.js +1 -1
  187. package/dist/core/runner/prepare-memory.d.ts +2 -2
  188. package/dist/core/runner/prepare-memory.js +2 -2
  189. package/dist/core/runner/prepare-park-ask.d.ts +3 -5
  190. package/dist/core/runner/prepare-park-ask.js +3 -8
  191. package/dist/core/runner/prepare-policy-chain.d.ts +5 -4
  192. package/dist/core/runner/prepare-policy-chain.js +120 -108
  193. package/dist/core/runner/prepare-project-context.js +8 -5
  194. package/dist/core/runner/prepare-prompt-inputs.d.ts +4 -1
  195. package/dist/core/runner/prepare-prompt-inputs.js +3 -2
  196. package/dist/core/runner/prepare-protocol-tools.d.ts +5 -3
  197. package/dist/core/runner/prepare-protocol-tools.js +9 -2
  198. package/dist/core/runner/prepare-suspend-saga.d.ts +0 -2
  199. package/dist/core/runner/prepare-suspend-saga.js +5 -7
  200. package/dist/core/runner/prepare-task.js +41 -27
  201. package/dist/core/runner/prepare-turn-wiring.d.ts +2 -0
  202. package/dist/core/runner/prepare-turn-wiring.js +7 -2
  203. package/dist/core/runner/prepare-wiring-manifest.d.ts +4 -3
  204. package/dist/core/runner/prepare-wiring-manifest.js +32 -18
  205. package/dist/core/runner/prepare-workspace-restore.js +3 -3
  206. package/dist/core/runner/resume-checkpoint-screen.js +4 -4
  207. package/dist/core/runner/retired-runner-deps.js +4 -1
  208. package/dist/core/runner/run-attachment-seats.js +3 -3
  209. package/dist/core/runner/run-brain-sinks.js +1 -0
  210. package/dist/core/runner/run-git-lane.d.ts +3 -1
  211. package/dist/core/runner/run-git-lane.js +1 -1
  212. package/dist/core/runner/run-harness-handlers.d.ts +3 -1
  213. package/dist/core/runner/run-harness-handlers.js +3 -1
  214. package/dist/core/runner/run-identity-wiring.js +1 -1
  215. package/dist/core/runner/run-leg.js +26 -28
  216. package/dist/core/runner/run-notification-lane.d.ts +3 -1
  217. package/dist/core/runner/run-notification-lane.js +16 -10
  218. package/dist/core/runner/run-settle-and-teardown.js +5 -1
  219. package/dist/core/runner/run-stop-and-final-verify.d.ts +4 -0
  220. package/dist/core/runner/run-stop-and-final-verify.js +12 -4
  221. package/dist/core/runner/run-turn-boundary.js +12 -7
  222. package/dist/core/runner/runtask.d.ts +7 -4
  223. package/dist/core/runner/runtask.js +19 -11
  224. package/dist/core/runner/skills-seat.js +2 -2
  225. package/dist/core/runner/sub-agent-deny-lists.js +10 -7
  226. package/dist/core/runner/synthetic-tools.js +2 -2
  227. package/dist/core/runner/tool-disclosure.js +0 -2
  228. package/dist/core/runner/tool-face-overlay.d.ts +1 -1
  229. package/dist/core/runner/tool-face-overlay.js +26 -19
  230. package/dist/core/runner/tool-result-media-seat.d.ts +9 -1
  231. package/dist/core/runner/tool-result-media-seat.js +17 -1
  232. package/dist/core/runner/turn-attachments.d.ts +3 -5
  233. package/dist/core/runner/turn-attachments.js +3 -16
  234. package/dist/core/runner-deps.d.ts +31 -18
  235. package/dist/core/secret-env.d.ts +3 -2
  236. package/dist/core/session-policy-store.d.ts +9 -2
  237. package/dist/core/session-policy-store.js +16 -1
  238. package/dist/core/session-store.d.ts +3 -2
  239. package/dist/core/session-store.js +50 -11
  240. package/dist/core/skill-grant.d.ts +9 -0
  241. package/dist/core/skill-grant.js +18 -0
  242. package/dist/core/store-contracts/tool-result-store-contract.d.ts +1 -1
  243. package/dist/core/store-contracts/tool-result-store-contract.js +37 -0
  244. package/dist/core/stub-env.d.ts +5 -5
  245. package/dist/core/stub-env.js +11 -1
  246. package/dist/core/swappable-deps.d.ts +17 -43
  247. package/dist/core/swappable-deps.js +15 -5
  248. package/dist/core/synthetic-read-verdict.d.ts +1 -1
  249. package/dist/core/task-event.d.ts +18 -2
  250. package/dist/core/task-notification.d.ts +88 -5
  251. package/dist/core/task-notification.js +130 -7
  252. package/dist/core/task-registry-agent.d.ts +18 -12
  253. package/dist/core/task-registry-agent.js +18 -6
  254. package/dist/core/task-registry-monitor.d.ts +7 -0
  255. package/dist/core/task-registry-monitor.js +28 -1
  256. package/dist/core/task-registry-shared.d.ts +38 -3
  257. package/dist/core/task-registry-shared.js +21 -7
  258. package/dist/core/task-registry-workflow.js +1 -1
  259. package/dist/core/task-registry.d.ts +50 -35
  260. package/dist/core/task-registry.js +64 -23
  261. package/dist/core/task-result.d.ts +3 -12
  262. package/dist/core/task-spec.d.ts +3 -6
  263. package/dist/core/task-stream.d.ts +1 -1
  264. package/dist/core/tool-catalog-entries.js +1 -1
  265. package/dist/core/tool-face-reader.d.ts +7 -6
  266. package/dist/core/tool-face-reader.js +4 -3
  267. package/dist/core/tool-name-aliases.d.ts +19 -0
  268. package/dist/core/tool-name-aliases.js +54 -2
  269. package/dist/core/tool-policy.d.ts +5 -4
  270. package/dist/core/tool-policy.js +1 -1
  271. package/dist/core/tool-registry.d.ts +5 -5
  272. package/dist/core/tool-registry.js +2 -2
  273. package/dist/core/tool-result-store.d.ts +88 -5
  274. package/dist/core/tool-result-store.js +51 -12
  275. package/dist/core/tool-spec.d.ts +20 -4
  276. package/dist/core/trace.d.ts +0 -1
  277. package/dist/core/types.d.ts +3 -3
  278. package/dist/core/types.js +1 -1
  279. package/dist/core/untrusted-text.js +1 -1
  280. package/dist/core/user-attachment.d.ts +10 -5
  281. package/dist/core/user-attachment.js +14 -6
  282. package/dist/engine/execution-env/node-execution-env.d.ts +7 -2
  283. package/dist/engine/execution-env/node-execution-env.js +12 -1
  284. package/dist/engine/harness/agent-harness.d.ts +1 -1
  285. package/dist/engine/harness/agent-harness.js +8 -4
  286. package/dist/engine/harness/types.d.ts +112 -29
  287. package/dist/engine/loop/agent-loop.d.ts +12 -12
  288. package/dist/engine/loop/agent-loop.js +153 -21
  289. package/dist/engine/loop/types.d.ts +9 -2
  290. package/dist/engine/lsp/node-lsp-manager.d.ts +3 -3
  291. package/dist/engine/lsp/node-lsp-manager.js +32 -13
  292. package/dist/index.d.ts +22 -14
  293. package/dist/index.js +15 -10
  294. package/dist/internal/harness-types.d.ts +1 -1
  295. package/dist/orchestration/run-workflow-tool.d.ts +9 -3
  296. package/dist/orchestration/run-workflow-tool.js +59 -29
  297. package/dist/orchestration/workflow-governance.d.ts +1 -1
  298. package/dist/orchestration/workflow-governance.js +2 -1
  299. package/dist/orchestration/workflow.d.ts +4 -0
  300. package/dist/orchestration/workflow.js +25 -4
  301. package/dist/prompts/default.d.ts +1 -10
  302. package/dist/prompts/default.js +0 -2
  303. package/dist/stores/file/background-agent-store.d.ts +1 -1
  304. package/dist/stores/file/background-agent-store.js +3 -1
  305. package/dist/stores/file/checkpoint-store.d.ts +127 -2
  306. package/dist/stores/file/checkpoint-store.js +19 -14
  307. package/dist/stores/file/file-history-store.d.ts +1 -1
  308. package/dist/stores/file/file-history-store.js +3 -1
  309. package/dist/stores/file/index.d.ts +4 -3
  310. package/dist/stores/file/index.js +17 -8
  311. package/dist/stores/file/mailbox-store.d.ts +1 -1
  312. package/dist/stores/file/mailbox-store.js +3 -1
  313. package/dist/stores/file/memory-store.d.ts +1 -1
  314. package/dist/stores/file/memory-store.js +3 -1
  315. package/dist/stores/file/session-policy-store.d.ts +1 -1
  316. package/dist/stores/file/session-policy-store.js +3 -1
  317. package/dist/stores/file/session-store.d.ts +1 -1
  318. package/dist/stores/file/session-store.js +3 -1
  319. package/dist/stores/file/shared-ledger.d.ts +26 -0
  320. package/dist/stores/file/shared-ledger.js +38 -9
  321. package/dist/stores/file/tool-result-store.d.ts +20 -2
  322. package/dist/stores/file/tool-result-store.js +74 -6
  323. package/dist/stores/file/usage-window-store.d.ts +1 -1
  324. package/dist/stores/file/usage-window-store.js +3 -1
  325. package/dist/stores/file/workflow-journal-store.d.ts +1 -11
  326. package/dist/stores/file/workflow-journal-store.js +3 -2
  327. package/dist/tools/fs/containment-face.d.ts +5 -0
  328. package/dist/tools/fs/encoding.d.ts +13 -4
  329. package/dist/tools/fs/encoding.js +17 -2
  330. package/dist/tools/fs/fs-bash-background-text.d.ts +7 -0
  331. package/dist/tools/fs/fs-bash-background-text.js +1 -0
  332. package/dist/tools/fs/fs-bash.d.ts +8 -4
  333. package/dist/tools/fs/fs-bash.js +26 -35
  334. package/dist/tools/fs/fs-pdf.d.ts +2 -2
  335. package/dist/tools/fs/fs-pdf.js +26 -21
  336. package/dist/tools/fs/fs-read.d.ts +5 -4
  337. package/dist/tools/fs/fs-read.js +35 -18
  338. package/dist/tools/fs/fs-search-tools.js +4 -1
  339. package/dist/tools/fs/fs-shared.d.ts +11 -13
  340. package/dist/tools/fs/fs-shared.js +11 -7
  341. package/dist/tools/fs/fs-write.js +5 -5
  342. package/dist/tools/fs/index.d.ts +14 -8
  343. package/dist/tools/fs/index.js +8 -4
  344. package/dist/tools/fs/read-floor.d.ts +44 -1
  345. package/dist/tools/fs/read-floor.js +35 -0
  346. package/dist/tools/fs/removal-targets.d.ts +9 -4
  347. package/dist/tools/fs/removal-targets.js +17 -9
  348. package/dist/tools/fs/search.d.ts +3 -3
  349. package/dist/tools/fs/search.js +4 -4
  350. package/dist/tools/monitor.d.ts +5 -4
  351. package/dist/tools/monitor.js +15 -8
  352. package/dist/tools/scheduler-tools.js +42 -4
  353. package/dist/tools/web.d.ts +0 -10
  354. package/dist/tools/web.js +1 -4
  355. package/package.json +4 -2
  356. package/test/export-surface.snapshot.json +75 -21
  357. package/wire-changes/core-stores-sql@7.60.0.json +30 -0
  358. package/wire-changes/core@7.60.0.json +3274 -0
  359. package/wire-changes/mods-kernel@7.60.0.json +62 -0
  360. package/wire-changes/primitives@7.60.0.json +30 -0
@@ -0,0 +1,139 @@
1
+ import { types } from "node:util";
2
+ import { describeFault, receive } from "./mods/kernel/receive.js";
3
+ import { DECLARATION_RECEIPT_MODE } from "./own-property-receipt.js";
4
+ import { assertNoRetiredKeys, RETIRED_MODEL_KEYS } from "./retired-keys.js";
5
+ export function modelBindingRefusal(field, reason, message) {
6
+ const e = new Error(message);
7
+ e.code = "config.unknown_role";
8
+ e.detail = { field, reason };
9
+ return e;
10
+ }
11
+ export function isList(value) {
12
+ try {
13
+ return Array.isArray(value);
14
+ }
15
+ catch {
16
+ return false;
17
+ }
18
+ }
19
+ export function bindingShown(value) {
20
+ if (typeof value === "string")
21
+ return JSON.stringify(value.length > 80 ? `${value.slice(0, 80)}…` : value);
22
+ return value === null ? "null" : isList(value) ? "a list" : `a ${typeof value}`;
23
+ }
24
+ const MODEL_MEMBER_TABLE = {
25
+ id: true,
26
+ name: true,
27
+ api: true,
28
+ provider: true,
29
+ baseUrl: true,
30
+ reasoning: true,
31
+ defaultThinking: true,
32
+ thinkingLevelMap: true,
33
+ input: true,
34
+ cost: true,
35
+ contextWindow: true,
36
+ contextTokens: true,
37
+ autoCompactTokens: true,
38
+ charsPerToken: true,
39
+ maxTokens: true,
40
+ params: true,
41
+ extraBody: true,
42
+ headers: true,
43
+ promptTraits: true,
44
+ compat: true,
45
+ };
46
+ const MODEL_MEMBERS = new Set(Object.keys(MODEL_MEMBER_TABLE));
47
+ export const MODEL_RECEIPT_MODE = Object.freeze({ ...DECLARATION_RECEIPT_MODE, live: Object.freeze(["headers"]) });
48
+ const MINTED = new WeakSet();
49
+ const LAST = new WeakMap();
50
+ const ORIGIN = new WeakMap();
51
+ export function isModelSnapshot(value) {
52
+ return typeof value === "object" && value !== null && MINTED.has(value);
53
+ }
54
+ export function modelOriginOf(model) {
55
+ return ORIGIN.get(model)?.origin ?? model;
56
+ }
57
+ function unreadableModelRefusal(seat, what, note, fault) {
58
+ const how = fault.path.length > 0
59
+ ? describeFault(fault)
60
+ : fault.kind === "proxy"
61
+ ? "a Proxy"
62
+ : "an object of another prototype (a class instance, an `Object.create(…)` value): a Model is a plain record, its members its own";
63
+ return modelBindingRefusal(seat, "not_a_model_ref", `${seat} is ${what} that could not be read as plain data — ${how}.${note}`);
64
+ }
65
+ export function receiveModel(value, seat, what = "a Model object", note = "") {
66
+ if (isModelSnapshot(value))
67
+ return value;
68
+ if (typeof value !== "object" || value === null || isList(value)) {
69
+ throw modelBindingRefusal(seat, "not_a_model_ref", `${seat} is ${what} that is ${bindingShown(value)}, not a Model — a Model is a plain record carrying a non-empty string \`id\` and a string \`api\`.${note}`);
70
+ }
71
+ if (types.isProxy(value))
72
+ throw unreadableModelRefusal(seat, what, note, { kind: "proxy", path: [] });
73
+ const headersAt = Object.getOwnPropertyDescriptor(value, "headers");
74
+ const headers = headersAt !== undefined && !Object.hasOwn(headersAt, "value") ? headersAt.get : undefined;
75
+ const received = receive(value, MODEL_RECEIPT_MODE, MINTED);
76
+ if (!received.ok)
77
+ throw unreadableModelRefusal(seat, what, note, received.fault);
78
+ const copy = received.value;
79
+ judgeModelCopy(copy, seat, what, note);
80
+ const prior = LAST.get(value);
81
+ if (prior !== undefined && ORIGIN.get(prior)?.headers === headers && sameData(prior, copy, true))
82
+ return prior;
83
+ MINTED.add(copy);
84
+ LAST.set(value, copy);
85
+ ORIGIN.set(copy, { origin: value, headers });
86
+ return copy;
87
+ }
88
+ function judgeModelCopy(copy, seat, what, note) {
89
+ assertNoRetiredKeys(copy, RETIRED_MODEL_KEYS, "Model");
90
+ const id = copy["id"];
91
+ const api = copy["api"];
92
+ const [member, got] = typeof id !== "string" || id === "" ? ["id", id] : typeof api !== "string" ? ["api", api] : [undefined, undefined];
93
+ if (member !== undefined) {
94
+ const shown = got === undefined ? "absent" : bindingShown(got);
95
+ throw modelBindingRefusal(seat, "not_a_model_ref", `${seat} is ${what} whose \`${member}\` is ${shown} — a Model carries a non-empty string \`id\` and a string \`api\`.${note}`);
96
+ }
97
+ for (const key of Object.keys(copy)) {
98
+ if (!MODEL_MEMBERS.has(key)) {
99
+ throw modelBindingRefusal(seat, "not_a_model_ref", `${seat} is ${what} carrying ${bindingShown(key)}, which is not a member of Model — a provider's own parameters belong in \`Model.params\`.${note}`);
100
+ }
101
+ }
102
+ }
103
+ function sameData(a, b, top = false, compared = new Map()) {
104
+ if (Object.is(a, b))
105
+ return true;
106
+ if (typeof a !== "object" || typeof b !== "object" || a === null || b === null)
107
+ return false;
108
+ const partners = compared.get(a);
109
+ if (partners?.has(b) === true)
110
+ return true;
111
+ if (partners === undefined)
112
+ compared.set(a, new Set([b]));
113
+ else
114
+ partners.add(b);
115
+ if (Array.isArray(a) !== Array.isArray(b) || (Array.isArray(a) && Array.isArray(b) && a.length !== b.length))
116
+ return false;
117
+ const ka = Object.keys(a);
118
+ const kb = Object.keys(b);
119
+ if (ka.length !== kb.length)
120
+ return false;
121
+ for (let i = 0; i < ka.length; i++) {
122
+ const k = ka[i];
123
+ if (k !== kb[i])
124
+ return false;
125
+ const da = Object.getOwnPropertyDescriptor(a, k);
126
+ const db = Object.getOwnPropertyDescriptor(b, k);
127
+ const aData = Object.hasOwn(da, "value");
128
+ if (aData !== Object.hasOwn(db, "value"))
129
+ return false;
130
+ if (!aData) {
131
+ if (!top)
132
+ return false;
133
+ continue;
134
+ }
135
+ if (!sameData(da.value, db.value, false, compared))
136
+ return false;
137
+ }
138
+ return true;
139
+ }
@@ -0,0 +1,65 @@
1
+ import type { HookInvocationIdentity } from "../hooks.js";
2
+ import type { PermissionMode } from "../ask-origin.js";
3
+ import { type LegModBus } from "./stations.js";
4
+ /** One agent type as the model is offered it. */
5
+ export interface OfferedAgent {
6
+ readonly name: string;
7
+ readonly description: string;
8
+ }
9
+ /**
10
+ * The offered set — the ONE reading of "which agent types is the model offered": each type the chain does not answer
11
+ * `{ isOffered: false }`, in the order given. No handler on the bus, no dispatch: the types as given. A dispatch the engine
12
+ * itself could not raise offers the type (an observation of the offer is never what hides it).
13
+ */
14
+ export declare function offeredAgents<A extends OfferedAgent>(bus: LegModBus | undefined, agents: readonly A[], signal: AbortSignal | undefined): Promise<readonly A[]>;
15
+ /** A rendered agent listing read through the offered set: the same listing when every type is offered, else a copy with the
16
+ * types the chain hid left out — what a listing frame renders, commits and mirrors. */
17
+ export declare function offeredAgentListing<L extends {
18
+ readonly entries: readonly OfferedAgent[];
19
+ }>(bus: LegModBus | undefined, listing: L | undefined, signal: AbortSignal | undefined): Promise<L | undefined>;
20
+ /** What the delegation decided about the subagent it is about to start, as `agent.spawn` names it. */
21
+ export interface AgentSpawnFacts {
22
+ /** The delegation call this spawn belongs to. */
23
+ readonly toolCallId: string;
24
+ readonly prompt: string;
25
+ readonly description: string;
26
+ /** The resolved type (a definition's name, `general-purpose`, `fork`). */
27
+ readonly subagentType: string;
28
+ /** The model the subagent starts on, as the delegation settled it; absent when its own prepare decides (a stated tier). */
29
+ readonly model?: string;
30
+ /** The parent's own model. */
31
+ readonly parentModel?: string;
32
+ readonly background: boolean;
33
+ readonly fork: boolean;
34
+ /** The name it is addressed by (a teammate), when the call gave one. */
35
+ readonly name?: string;
36
+ readonly cwd?: string;
37
+ /** A workflow script's agent rather than a model's delegation. */
38
+ readonly workflow?: true;
39
+ }
40
+ /** What `agent.spawn` came to: the subagent may start, or the chain refused it (`by` = the registration). */
41
+ export type AgentSpawnVerdict = {
42
+ readonly go: true;
43
+ } | {
44
+ readonly go: false;
45
+ readonly by: string;
46
+ readonly reason: string;
47
+ };
48
+ /** The delegating leg's two agent stations, as its delegation tools read them (a Runner-filled seat, never a model argument). */
49
+ export interface AgentStations {
50
+ /** Whether a handler hangs on the event — a caller with nothing to raise reads none (no await on its path). */
51
+ listens(event: "agent.offer" | "agent.spawn"): boolean;
52
+ /** {@link offeredAgents} over the leg's bus. */
53
+ offered<A extends OfferedAgent>(agents: readonly A[], signal: AbortSignal | undefined): Promise<readonly A[]>;
54
+ /** Raise `agent.spawn` (no handler ⇒ nothing raised: the subagent may start). */
55
+ spawn(facts: AgentSpawnFacts, signal: AbortSignal | undefined): Promise<AgentSpawnVerdict>;
56
+ }
57
+ export interface AgentStationsInput {
58
+ readonly bus: LegModBus;
59
+ /** The delegating leg's identity (its `agentId` is the spawn's `parentAgentId`). */
60
+ readonly identity: HookInvocationIdentity | undefined;
61
+ /** The delegating leg's mode as observed at the spawn. */
62
+ readonly permissionMode: () => PermissionMode | undefined;
63
+ }
64
+ /** The leg's agent stations over its bus. */
65
+ export declare function createAgentStations(input: AgentStationsInput): AgentStations;
@@ -0,0 +1,105 @@
1
+ import { ENGINE_ORIGIN } from "./kernel/index.js";
2
+ import { isPlainRecord } from "./kernel/receive.js";
3
+ import { NEXT_IN_FLIGHT } from "./kernel/site-rules.js";
4
+ import { describeThrown } from "../tool-policy.js";
5
+ import { extensionWords } from "../untrusted-egress.js";
6
+ import { agentIdOf, failedHandlerClause } from "./stations.js";
7
+ const ENGINE_PROVIDER = Object.freeze({ plugin: ENGINE_ORIGIN.plugin, tier: ENGINE_ORIGIN.tier });
8
+ const OFFERED = Object.freeze({ isOffered: true });
9
+ function offerAnswer(answer) {
10
+ if (!isPlainRecord(answer) || typeof answer["isOffered"] !== "boolean" || Object.keys(answer).some((k) => k !== "isOffered"))
11
+ return "agent.offer takes next(e) or { isOffered: <boolean> }";
12
+ return undefined;
13
+ }
14
+ export async function offeredAgents(bus, agents, signal) {
15
+ if (bus === undefined || agents.length === 0 || !bus.hasHandlers("agent.offer"))
16
+ return agents;
17
+ const out = [];
18
+ for (const a of agents) {
19
+ let outcome;
20
+ try {
21
+ outcome = await bus.dispatch("agent.offer", { agent: a.name, description: a.description, provider: ENGINE_PROVIDER }, { bottom: () => OFFERED, checkAnswer: offerAnswer, ...(signal !== undefined ? { signal } : {}) });
22
+ }
23
+ catch {
24
+ out.push(a);
25
+ continue;
26
+ }
27
+ if (outcome.kind === "answered" && isPlainRecord(outcome.answer) && outcome.answer["isOffered"] === false)
28
+ continue;
29
+ out.push(a);
30
+ }
31
+ return out;
32
+ }
33
+ export async function offeredAgentListing(bus, listing, signal) {
34
+ if (listing === undefined)
35
+ return undefined;
36
+ const entries = await offeredAgents(bus, listing.entries, signal);
37
+ return entries === listing.entries || entries.length === listing.entries.length ? listing : { ...listing, entries };
38
+ }
39
+ const GO = Object.freeze({ go: true });
40
+ const FORM = "agent.spawn takes next(e) or { deny: <reason> } (every member is pinned: a spawn is refused, never rewritten)";
41
+ const denyOf = (a) => isPlainRecord(a) && Object.keys(a).length === 1 && typeof a["deny"] === "string" && a["deny"] !== "" ? a["deny"] : undefined;
42
+ const RANKS = Object.freeze({ of: (a) => (denyOf(a) !== undefined ? 1 : 0), top: 1 });
43
+ export function createAgentStations(input) {
44
+ return {
45
+ listens: (event) => input.bus.hasHandlers(event),
46
+ offered: (agents, signal) => offeredAgents(input.bus, agents, signal),
47
+ spawn: async (facts, signal) => {
48
+ if (!input.bus.hasHandlers("agent.spawn"))
49
+ return GO;
50
+ const parentAgentId = agentIdOf(input.identity);
51
+ const permissionMode = input.permissionMode();
52
+ const e = {
53
+ ...(input.identity !== undefined ? { identity: input.identity } : {}),
54
+ tool_use_id: facts.toolCallId,
55
+ prompt: facts.prompt,
56
+ description: facts.description,
57
+ subagentType: facts.subagentType,
58
+ provider: ENGINE_PROVIDER,
59
+ ...(facts.model !== undefined ? { model: facts.model } : {}),
60
+ ...(facts.parentModel !== undefined ? { parentModel: facts.parentModel } : {}),
61
+ ...(parentAgentId !== undefined ? { parentAgentId } : {}),
62
+ ...(permissionMode !== undefined ? { permissionMode } : {}),
63
+ background: facts.background,
64
+ fork: facts.fork,
65
+ isTeammate: facts.name !== undefined,
66
+ ...(facts.name !== undefined ? { name: facts.name } : {}),
67
+ ...(facts.cwd !== undefined ? { cwd: facts.cwd } : {}),
68
+ ...(facts.workflow === true ? { workflow: true } : {}),
69
+ };
70
+ const started = Object.freeze({ model: facts.model ?? "inherit" });
71
+ const checkAnswer = (a, _e, _by, below, ran) => {
72
+ if (a === started)
73
+ return undefined;
74
+ const reason = denyOf(a);
75
+ if (reason === undefined)
76
+ return FORM;
77
+ if (ran.bottomStarted)
78
+ return "a deny after the subagent was let start (once it starts, only its own run stands)";
79
+ if (below.includes(NEXT_IN_FLIGHT) || below.some((b) => denyOf(b) === undefined))
80
+ return "a deny while its next(e) still runs or after it was answered (deny in place of next)";
81
+ return undefined;
82
+ };
83
+ let outcome;
84
+ try {
85
+ outcome = await input.bus.dispatch("agent.spawn", e, { bottom: () => started, checkAnswer, ranks: RANKS, ...(signal !== undefined ? { signal } : {}) });
86
+ }
87
+ catch (err) {
88
+ return { go: false, by: ENGINE_ORIGIN.plugin, reason: `the agent.spawn station could not be raised (${describeThrown(err)}); no subagent was started (fail-closed)` };
89
+ }
90
+ if (outcome.kind === "aborted")
91
+ return outcome.bottomStarted === true ? GO : { go: false, by: ENGINE_ORIGIN.plugin, reason: "the delegation was cancelled before its subagent started" };
92
+ if (outcome.kind === "failed")
93
+ return { go: false, by: outcome.registration, reason: `an agent.spawn extension ${failedHandlerClause(outcome)} before the subagent started; no subagent was started (fail-closed)` };
94
+ if (outcome.answer === started)
95
+ return GO;
96
+ const by = outcome.answeredBy ?? ENGINE_ORIGIN.plugin;
97
+ const reason = denyOf(outcome.answer);
98
+ return {
99
+ go: false,
100
+ by,
101
+ reason: reason !== undefined ? `extension "${extensionWords(by, 80)}" refused this delegation before its subagent started: ${extensionWords(reason, 300)}` : `extension "${extensionWords(by, 80)}" answered this delegation in a form agent.spawn does not take; no subagent was started (fail-closed)`,
102
+ };
103
+ },
104
+ };
105
+ }
@@ -40,12 +40,16 @@ export type ModDispatchOutcome = {
40
40
  readonly answer: unknown;
41
41
  readonly answeredBy?: string;
42
42
  readonly skipped: readonly ModSkip[];
43
- } | {
43
+ }
44
+ /** `bottomStarted`: the chain's bottom had started when the handler failed — on an effect event, what it did happened, and
45
+ * its outcome is the station's to withhold. */
46
+ | {
44
47
  readonly kind: "failed";
45
48
  readonly registration: string;
46
49
  readonly cause: ModFailureCause;
47
50
  readonly reason: string;
48
51
  readonly skipped: readonly ModSkip[];
52
+ readonly bottomStarted?: true;
49
53
  }
50
54
  /** `bottomStarted`: the chain's bottom had started when the dispatch was cancelled — on an effect event, what it did is
51
55
  * not known from here. */
@@ -596,12 +596,12 @@ function createBus(side, mounted, bottoms, entries, report, records, describe, i
596
596
  throw failure.error;
597
597
  }
598
598
  const reason = caught !== undefined ? `${failure.reason}; ${caught.problem}` : failure.reason;
599
- const effectStands = st.failure === "refuse_until_run" && bottomStarted && state.last !== undefined;
600
- if (refusing && !effectStands) {
601
- if (failure.cause !== "violation")
599
+ const goAheadStands = st.failure === "refuse_until_run" && bottomStarted && state.last !== undefined;
600
+ if (refusing && !goAheadStands) {
601
+ if (failure.cause !== "violation" || bottomStarted)
602
602
  report(new Error(`${name}: ${event}: ${reason} — failed closed: the dispatch ends here`));
603
603
  traceOf(sink, i, name, h.reg.tier, "rejected", ms);
604
- finish({ kind: "failed", registration: name, cause: failure.cause, reason, skipped: Object.freeze([...skipped]) });
604
+ finish({ kind: "failed", registration: name, cause: failure.cause, reason, skipped: Object.freeze([...skipped]), ...(bottomStarted ? { bottomStarted: true } : {}) });
605
605
  throw terminal;
606
606
  }
607
607
  skipped.push(Object.freeze({ registration: name, cause: failure.cause, reason }));
@@ -26,8 +26,12 @@
26
26
  * and an admission record carries the registration's `provenance` as the host gave it and lists in `observe` only the patterns
27
27
  * on which every handler it hung watches.
28
28
  * 5: `classic.SubagentStart` has a station (a delegated leg's opening event).
29
+ * 6: `agent.offer` (a listed or named agent type, before the model is offered it), `agent.spawn` (a delegation the gate let
30
+ * go, before its subagent starts — every argument pinned, a refusal its only answer), `turn.complete` (a model turn ended)
31
+ * and `session.end` (a leg ended) have stations; `tool.call`'s failure column is `refuse` — a failure once the body has
32
+ * started withholds the result (under `refuse_until_run`, its column until 5, the result stood).
29
33
  */
30
- export declare const KERNEL_CONTRACT_VERSION = 5;
34
+ export declare const KERNEL_CONTRACT_VERSION = 6;
31
35
  /** The five tiers in run order (CC names). `builtin` and `core` are the engine's own. */
32
36
  export declare const MOD_TIERS: readonly ["prepend", "user", "append", "builtin", "core"];
33
37
  export type ModTier = (typeof MOD_TIERS)[number];
@@ -42,9 +46,11 @@ export type ModEventSide = (typeof MOD_EVENT_SIDES)[number];
42
46
  /** A bus is one side. */
43
47
  export type ModBusSide = Exclude<ModEventSide, "both">;
44
48
  /**
45
- * What a handler's failure means for the dispatch: the station's refusal (final); skip the handler; or — on an event
46
- * whose chain bottom is an effect (a tool runs) — the refusal while the bottom has not started and, once it has, what
47
- * the bottom did stands (the failure is reported beside the real result, which it never replaces).
49
+ * What a handler's failure means for the dispatch: the station's refusal (final); skip the handler; or — on an event whose
50
+ * bottom is a go-ahead the station acts on after the dispatch (`agent.spawn`: the subagent is let start) — the refusal
51
+ * while the bottom has not started and, once it has, the go-ahead stands (the failure is reported beside it). A `refuse`
52
+ * station refuses whether or not its bottom has started: on one whose bottom is an effect (`tool.call`: a tool runs), the
53
+ * dispatch's `failed` outcome says the bottom had started, and the station withholds what it produced.
48
54
  */
49
55
  export declare const MOD_FAILURE_ANSWERS: readonly ["refuse", "skip", "refuse_until_run"];
50
56
  export type ModFailureAnswer = (typeof MOD_FAILURE_ANSWERS)[number];
@@ -1,4 +1,4 @@
1
- export const KERNEL_CONTRACT_VERSION = 5;
1
+ export const KERNEL_CONTRACT_VERSION = 6;
2
2
  export const MOD_TIERS = Object.freeze(["prepend", "user", "append", "builtin", "core"]);
3
3
  export const MOD_SEATS = Object.freeze(["deployment", "task"]);
4
4
  export const MOD_EVENT_SIDES = Object.freeze(["engine", "surface", "both"]);
@@ -43,6 +43,10 @@ const surface = (s) => Object.freeze(s === undefined ? { side: "surface" } : { s
43
43
  const RENDER_PINNED = ["surface", "component", "requestId", "viewport"];
44
44
  const ELEMENT_PINNED = ["plugin", "element", "component", "requestId", "surface"];
45
45
  const PROMPT_EDIT_BUDGET_MS = 50;
46
+ const AGENT_SPAWN_PINNED = [
47
+ "tool_use_id", "name", "fork", "isTeammate", "workflow", "parentModel", "permissionMode", "parentAgentId", "provider",
48
+ "prompt", "description", "subagentType", "model", "background", "cwd", "identity",
49
+ ];
46
50
  export const MOD_EVENT_TABLE = Object.freeze({
47
51
  "classic.PreToolUse": engine(station("refuse", "immediate", ["tool", "tool_use_id", "agentId", "input"])),
48
52
  "classic.PostToolUse": engine(station("skip", "grace")),
@@ -77,7 +81,7 @@ export const MOD_EVENT_TABLE = Object.freeze({
77
81
  "classic.FileChanged": engine(),
78
82
  "classic.DirectoryAdded": engine(),
79
83
  "classic.MessageDisplay": engine(),
80
- "tool.call": engine(station("refuse_until_run", "immediate", ["tool", "tool_use_id", "agentId", "input"], { call: true })),
84
+ "tool.call": engine(station("refuse", "immediate", ["tool", "tool_use_id", "agentId", "input"], { call: true })),
81
85
  "tool.check": engine(station("refuse", "immediate", ["tool", "input", "tool_use_id", "agentId", "ceiling"])),
82
86
  "ui.render": surface(station("skip", "grace", RENDER_PINNED)),
83
87
  "ui.resolve": surface(station("skip", "grace", ["surface", "component"])),
@@ -88,8 +92,8 @@ export const MOD_EVENT_TABLE = Object.freeze({
88
92
  "ui.fault": surface(),
89
93
  "ui.scroll": surface(station("skip", "grace", ["component", "requestId", "by", "bodyRows", "contentRows", "origin", "pointer"], { call: true })),
90
94
  "ui.focus": surface(station("skip", "grace", ["component", "requestId", "plugin", "origin", "element"], { call: true })),
91
- "agent.offer": engine(),
92
- "agent.spawn": engine(),
95
+ "agent.offer": engine(station("skip", "grace", ["agent", "provider"])),
96
+ "agent.spawn": engine(station("refuse_until_run", "immediate", AGENT_SPAWN_PINNED)),
93
97
  "prompt.submit": engine(),
94
98
  "prompt.fill": surface(station("skip", "grace", ["origin", "mode"], { call: true })),
95
99
  "prompt.suggest": surface(station("skip", "grace", ["origin"], { call: true })),
@@ -117,11 +121,11 @@ export const MOD_EVENT_TABLE = Object.freeze({
117
121
  "session.attach": engine(),
118
122
  "session.detach": engine(),
119
123
  "session.measure": engine(),
120
- "session.end": engine(),
124
+ "session.end": engine(station("skip", "grace", ["reason", "sessionId", "agentId"])),
121
125
  "plugin.register": Object.freeze({ side: "both", station: station("refuse", "immediate", ["name", "seat", "tier", "uses"]) }),
122
126
  "turn.start": engine(),
123
127
  "turn.step": engine(),
124
- "turn.complete": engine(),
128
+ "turn.complete": engine(station("skip", "grace", ["answer", "agentId", "turn"])),
125
129
  "engine.create": engine(),
126
130
  "model.complete": engine(method(true)),
127
131
  "model.classify": engine(),
@@ -72,6 +72,11 @@ export interface ReceiptMode {
72
72
  readonly leaves?: "cloned";
73
73
  /** The host's Proxy probe. */
74
74
  readonly isProxy?: (value: object) => boolean;
75
+ /** Members of the received value itself (its top level only, never `wire`) that are read PER USE rather than at the receipt:
76
+ * one of them that is an own accessor is never called by the receipt — the copy carries it as an accessor whose every read
77
+ * calls the caller's getter on the caller's object, once per read (a getter that throws, throws at that read). One that is a
78
+ * data property is received like any other member. */
79
+ readonly live?: readonly string[];
75
80
  }
76
81
  /** Why a receipt was refused. `uncopyable` has two causes, and depth is neither (the walk keeps its own stack): reading
77
82
  * the value threw where none of its getters runs — a Proxy's trap, on a receipt given no Proxy probe; what it threw is
@@ -336,6 +336,16 @@ export function receive(value, mode, held) {
336
336
  if (f.list && key === "length")
337
337
  continue;
338
338
  captured = f.captured[key];
339
+ if (f.level === 0 && !f.list && mode.live?.includes(key) === true && !Object.hasOwn(captured, "value")) {
340
+ const get = Object.hasOwn(captured, "get") ? captured.get : undefined;
341
+ const holder = f.v;
342
+ const d = Object.create(null);
343
+ d.get = get === undefined ? () => undefined : () => Reflect.apply(get, holder, []);
344
+ d.enumerable = true;
345
+ d.configurable = true;
346
+ DEFINE(f.out, key, d);
347
+ continue;
348
+ }
339
349
  }
340
350
  if (key !== undefined) {
341
351
  path[path.length] = key;
@@ -0,0 +1,41 @@
1
+ /**
2
+ * A leg's two lifecycle stations over its bus, both observations (an answer changes nothing, a failure skips the handler).
3
+ * `turn.complete`: the turn's end records it ({@link noteCompletedTurn}); the next await point raises it once
4
+ * ({@link raiseCompletedTurn}) — the turn boundary after it, or the leg's settle for a turn whose boundary never ran.
5
+ * `e = { answer, reason, turn, isAborted, agentId?, usage? }`; the bottom comes up as `{ text: answer, usage? }`.
6
+ * `session.end`: a leg's terminal settled; `e = { reason, sessionId, agentId? }`, `reason` the terminal status word.
7
+ */
8
+ import type { AssistantMessage } from "../../internal/llm.js";
9
+ import type { HookInvocationIdentity } from "../hooks.js";
10
+ import { type LegModBus } from "./stations.js";
11
+ /** Why a model turn ended. */
12
+ export type CompletedTurnReason = "answer" | "aborted" | "error";
13
+ /** A model turn that ended, as `turn.complete` names it (raised once, then gone). */
14
+ export interface CompletedTurn {
15
+ readonly answer: string;
16
+ readonly reason: CompletedTurnReason;
17
+ /** The leg's turn count at the turn's end (1 = its first turn). */
18
+ readonly turn: number;
19
+ readonly usage?: {
20
+ readonly inputTokens: number;
21
+ readonly outputTokens: number;
22
+ readonly cacheReadTokens: number;
23
+ readonly cacheWriteTokens: number;
24
+ };
25
+ }
26
+ /** Where the leg keeps the turns it has not raised yet, in order (a turn can end with no boundary after it — a recovery
27
+ * re-prompt, a failure's own `turn_end` — so the next await point may find more than one). */
28
+ export interface CompletedTurnSeat {
29
+ completed?: readonly CompletedTurn[];
30
+ }
31
+ /** Record the turn that just ended for `turn.complete` (nothing when no handler hangs on it); `aborted` = the leg's cancel was
32
+ * already in force when the turn ended, `usage` absent when none was reported. */
33
+ export declare function noteCompletedTurn(bus: LegModBus, seat: CompletedTurnSeat, message: AssistantMessage | undefined, turn: number, aborted: boolean, usage: CompletedTurn["usage"] | undefined): void;
34
+ /** Raise `turn.complete` for each turn the seat holds, in order, each once (the seat is emptied first). An engine-side
35
+ * rejection is swallowed: an observation never changes what it observes. */
36
+ export declare function raiseCompletedTurn(bus: LegModBus, seat: CompletedTurnSeat, identity: HookInvocationIdentity | undefined, signal: AbortSignal | undefined): Promise<void>;
37
+ /** Raise `session.end` as the leg's terminal settles (nothing when no handler hangs on it). */
38
+ export declare function raiseSessionEnd(bus: LegModBus, identity: HookInvocationIdentity | undefined, end: {
39
+ readonly reason: string;
40
+ readonly sessionId: string;
41
+ }): Promise<void>;
@@ -0,0 +1,35 @@
1
+ import { classicEventBase } from "./stations.js";
2
+ const answerOf = (message) => (message?.content ?? []).flatMap((c) => (c.type === "text" ? [c.text] : [])).join("");
3
+ export function noteCompletedTurn(bus, seat, message, turn, aborted, usage) {
4
+ if (!bus.hasHandlers("turn.complete"))
5
+ return;
6
+ const reason = aborted || message?.stopReason === "aborted" ? "aborted" : message?.stopReason === "error" ? "error" : "answer";
7
+ const ended = Object.freeze({ answer: answerOf(message), reason, turn, ...(usage !== undefined ? { usage: Object.freeze({ inputTokens: usage.inputTokens, outputTokens: usage.outputTokens, cacheReadTokens: usage.cacheReadTokens, cacheWriteTokens: usage.cacheWriteTokens }) } : {}) });
8
+ seat.completed = Object.freeze([...(seat.completed ?? []), ended]);
9
+ }
10
+ export async function raiseCompletedTurn(bus, seat, identity, signal) {
11
+ const turns = seat.completed ?? [];
12
+ seat.completed = undefined;
13
+ if (!bus.hasHandlers("turn.complete"))
14
+ return;
15
+ for (const turn of turns) {
16
+ const e = { ...classicEventBase(identity), answer: turn.answer, reason: turn.reason, turn: turn.turn, isAborted: turn.reason === "aborted", ...(turn.usage !== undefined ? { usage: turn.usage } : {}) };
17
+ const core = Object.freeze({ text: turn.answer, ...(turn.usage !== undefined ? { usage: turn.usage } : {}) });
18
+ try {
19
+ await bus.dispatch("turn.complete", e, { bottom: () => core, ...(signal !== undefined ? { signal } : {}) });
20
+ }
21
+ catch {
22
+ }
23
+ }
24
+ }
25
+ export async function raiseSessionEnd(bus, identity, end) {
26
+ if (!bus.hasHandlers("session.end"))
27
+ return;
28
+ const e = { ...classicEventBase(identity), reason: end.reason, sessionId: end.sessionId };
29
+ const core = Object.freeze({ sessionId: end.sessionId });
30
+ try {
31
+ await bus.dispatch("session.end", e, { bottom: () => core });
32
+ }
33
+ catch {
34
+ }
35
+ }