@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
@@ -9,9 +9,21 @@
9
9
  * parent leg that ended; a shared connection cannot.
10
10
  *
11
11
  * LIFETIME. A lease is released when its leg's materialization is disposed (the leg ended, failed, was cancelled or parked); the
12
- * last holder's release closes the connection. The pool itself holds no connection between leases and dies with the run that
13
- * created it: after `close()` a tree member that asks for a connection dials one of its own (a kept child resumed hours later,
14
- * a revived one), so the DECLARATION stays the one source of truth — no handle is ever recorded anywhere.
12
+ * last holder's release closes the connection. The pool holds no connection between leases. Inside a Runner the pool is the
13
+ * SESSION's ({@link SessionMcpPools}, held for the session store, so every Runner over the store shares it: every message of a
14
+ * session, and every leg its runs spawn, leases from one pool); a leg
15
+ * prepared outside a Runner makes its own and it dies with that run: after `close()` a tree member that asks for a connection
16
+ * dials one of its own (a kept child resumed hours later, a revived one), so the DECLARATION stays the one source of truth —
17
+ * no handle is ever recorded anywhere.
18
+ *
19
+ * WHAT THE POOL REMEMBERS is the failure of a connection ATTEMPT, per key ({@link attempt}): the dial's handshake, its first
20
+ * listing, and the re-dial a 401 answered with other pieces inside it are one attempt; the attempt is opened where the dial
21
+ * begins and settled where it ends. A key whose last attempt failed is not dialed again: the next attempt is answered with that
22
+ * failure, as it was, at once — the person was told when it failed, and the server is not tried again for the pool's life
23
+ * unless its declaration changes (another key), a re-dial replaces it (`fresh`) or the host forgets it ({@link forget}). A
24
+ * live connection under the key comes before the memory: one leg's failed listing on a connection another leg holds is that
25
+ * leg's alone. What the caller does not settle as a failure is not remembered (its own stop, a refusal of the engine's own
26
+ * seats, a server that asks the person to authorize: none of them waits a bound).
15
27
  *
16
28
  * THE KEY is the server's declaration as the dial reads it (name and transport) and the principal the task runs under: a
17
29
  * different principal is a different identity at the server. A task whose isolation scope names a partition other than that
@@ -37,12 +49,32 @@ export interface McpLease {
37
49
  /** Give the hold back; the last holder's release closes the connection. Idempotent. */
38
50
  release(): Promise<void>;
39
51
  }
52
+ /** One connection attempt under a key ({@link McpConnectionPool.attempt}). `recalled`: the key's last word was a failure and no connection
53
+ * under it is live — this attempt dials nothing and answers with `recalled.reason`. Otherwise the caller dials and settles: `connected`
54
+ * clears the memory, `{ failed }` keeps it, `unkept` leaves it as it was — and only while no newer word on the key has been given.
55
+ * `settle` answers whether the pool now remembers the key's failure (the person is told "for this session" only then); a settle is read
56
+ * once, and an attempt that recalled settles nothing. */
57
+ export interface McpAttempt {
58
+ readonly recalled: {
59
+ readonly reason: unknown;
60
+ } | undefined;
61
+ settle(outcome: "connected" | "unkept" | {
62
+ readonly failed: unknown;
63
+ }): boolean;
64
+ }
40
65
  export declare class McpConnectionPool {
41
66
  private readonly entries;
42
67
  private readonly dialing;
68
+ private readonly memo;
43
69
  /** Bumped by each {@link detach}: a dial that finishes after its key was detached serves the legs already waiting on it and publishes nothing. */
44
70
  private readonly generation;
71
+ private leased;
45
72
  private shut;
73
+ /** The session this pool is held for ({@link SessionMcpPools}) — the session a failed attempt under it is told to; absent for a pool its caller made. */
74
+ readonly sessionId: string | undefined;
75
+ constructor(opts?: {
76
+ sessionId?: string;
77
+ });
46
78
  /**
47
79
  * The key a declaration leases under. `kind` is the dial's own single reading of the transport kind (the dial reads it once and threads it, so a
48
80
  * transport object that answers differently to two readers cannot split the dial from its key); every other transport member is read here.
@@ -61,7 +93,8 @@ export declare class McpConnectionPool {
61
93
  /**
62
94
  * Lease the connection for `key`, dialling it with `dial` when none is live. `fresh` replaces the pool's current connection with a new
63
95
  * dial (a re-dial): the connection it replaces lives on until its other holders release it. Resolves `undefined` once the pool is
64
- * closed — the caller dials for itself. A dial that rejects rejects every waiter of that dial, and the pool keeps nothing of it.
96
+ * closed — the caller dials for itself. A dial that rejects rejects every waiter of that dial, and no connection of it is kept (what
97
+ * is remembered of a failure is the attempt's, settled by its caller — {@link attempt}).
65
98
  *
66
99
  * `signal` is the CALLER's abort, and it is that caller's alone: it ends this caller's wait (rejecting with its reason) and leaves the dial
67
100
  * to the legs still waiting on it. The dial belongs to the pool: it is given a stop of its own, fired when the last leg waiting on it has
@@ -81,6 +114,24 @@ export declare class McpConnectionPool {
81
114
  private abandon;
82
115
  /** Make the next lease of `key` dial a new connection. */
83
116
  detach(key: string): void;
117
+ /** The dial in the air under `key` is no next lease's: it serves the legs already waiting on it and publishes nothing. */
118
+ private dropDial;
119
+ /**
120
+ * Open one connection attempt for `key` (the declaration's key, {@link keyOf}; `server` is the name it declares). The key's word is
121
+ * its newest: an attempt's settle counts only while no attempt opened after it has settled and no re-dial or forget came after it.
122
+ * `fresh` (a re-dial) is such a word — it drops the key's memory before this attempt opens. The memory answers only while no
123
+ * connection under the key is live, and a failure settled while one is live is that caller's alone (another holder's connection is
124
+ * the server's answer). A closed pool recalls and keeps nothing: its caller dials for itself.
125
+ */
126
+ attempt(key: string, server: string, opts?: {
127
+ fresh?: boolean;
128
+ }): McpAttempt;
129
+ /** Forget what this pool remembers of every attempt at the server named `server` (any key that declares it): an attempt still in
130
+ * the air settles nothing, and its dial is no next lease's — the next attempt dials. True when a failure was remembered. */
131
+ forget(server: string): boolean;
132
+ /** Whether no leg holds a lease of this pool (a detached connection's included) or waits on a dial in its table. */
133
+ get idle(): boolean;
134
+ private liveUnder;
84
135
  /** No lease is granted after this; the connections still held stay open until their holders release them — one nobody holds is closed now. */
85
136
  close(): void;
86
137
  /** How many connections the pool holds open right now (for the lifecycle pins). */
@@ -88,3 +139,41 @@ export declare class McpConnectionPool {
88
139
  private dialNew;
89
140
  private lease;
90
141
  }
142
+ /**
143
+ * The MCP pools of one session store's sessions, one per session — the same kind of seat as the Runner's per-session read-file
144
+ * states (runner/session-read-file-states.ts): the run internals carry it to the prepare, and the prepare takes the pool of its
145
+ * session. It belongs to the STORE, not to a Runner ({@link sessionMcpPoolsOf}): a session lives in its store, and the Runners a
146
+ * host builds over one store (a pair that differ only in hands, serving one session's messages in turn) read one memory. So a
147
+ * session's messages and every leg they spawn lease from one pool, and what the pool remembers of a failed attempt
148
+ * ({@link McpConnectionPool.attempt}) holds for the session — a server that failed is not dialed again by the next message, a
149
+ * child or a workflow agent, whichever Runner over the store runs it.
150
+ *
151
+ * A CACHE, never an authority: bounded (an LRU over session ids, refreshed on read), and only an idle pool (no lease held, no dial
152
+ * waited on) is let go. Letting go cuts nothing — a leg that already took the pool keeps it to its end — and costs what the
153
+ * session's next message then pays: one dial, the memory having gone with the pool. The memory does not cross processes and is
154
+ * not persisted: a new Runner dials afresh.
155
+ */
156
+ export declare class SessionMcpPools {
157
+ private readonly pools;
158
+ private static readonly CAP;
159
+ /** The session's pool (made on its first ask). */
160
+ of(sessionId: string): McpConnectionPool;
161
+ /** Forget the session's memory of every attempt at `server` ({@link McpConnectionPool.forget}); a session with no pool here remembers nothing. */
162
+ forget(sessionId: string, server: string): boolean;
163
+ }
164
+ /** The MCP pools of the sessions `store` holds — the one table every Runner over that store reads (made on its first ask). */
165
+ export declare function sessionMcpPoolsOf(store: object): SessionMcpPools;
166
+ /** The request of `Runner.forgetMcpFailure`: the session (the one its messages run under — a child's or a workflow agent's legs lease
167
+ * from the same pool) and the DECLARED name of the server. */
168
+ export interface ForgetMcpFailureRequest {
169
+ sessionId: string;
170
+ server: string;
171
+ }
172
+ /** What `Runner.forgetMcpFailure` did: `forgotten` — the session remembered a failed connection attempt at the server, and its next
173
+ * message dials it again; `none_remembered` — nothing was remembered (an attempt still in the air is no longer remembered either way). */
174
+ export interface ForgetMcpFailureResult {
175
+ server: string;
176
+ outcome: "forgotten" | "none_remembered";
177
+ }
178
+ /** The out-of-run verb's body (`Runner.forgetMcpFailure`): a request whose members are not strings is refused by name, never read as none. */
179
+ export declare function forgetSessionMcpFailure(pools: SessionMcpPools, request: ForgetMcpFailureRequest): ForgetMcpFailureResult;
@@ -5,11 +5,22 @@ const ENGINE_DIALS = new WeakMap();
5
5
  export function recordEngineDial(client, key) {
6
6
  ENGINE_DIALS.set(client, { key, entered: false });
7
7
  }
8
+ const UNPOOLED = Object.freeze({ recalled: undefined, settle: () => false });
9
+ function supersede(memo) {
10
+ memo.floor = memo.opened;
11
+ delete memo.failed;
12
+ }
8
13
  export class McpConnectionPool {
9
14
  entries = new Map();
10
15
  dialing = new Map();
16
+ memo = new Map();
11
17
  generation = new Map();
18
+ leased = 0;
12
19
  shut = false;
20
+ sessionId;
21
+ constructor(opts) {
22
+ this.sessionId = opts?.sessionId;
23
+ }
13
24
  static keyOf(spec, principal, kind, startupMs, isolationScope) {
14
25
  const rest = Object.fromEntries(Object.keys(spec.transport).filter((k) => k !== "kind").map((k) => [k, Reflect.get(spec.transport, k)]));
15
26
  const fingerprint = spec.fingerprint;
@@ -88,14 +99,67 @@ export class McpConnectionPool {
88
99
  }, () => undefined);
89
100
  }
90
101
  detach(key) {
91
- this.generation.set(key, (this.generation.get(key) ?? 0) + 1);
102
+ this.dropDial(key);
92
103
  const e = this.entries.get(key);
93
104
  if (e !== undefined) {
94
105
  e.current = false;
95
106
  this.entries.delete(key);
96
107
  }
108
+ }
109
+ dropDial(key) {
110
+ this.generation.set(key, (this.generation.get(key) ?? 0) + 1);
97
111
  this.dialing.delete(key);
98
112
  }
113
+ attempt(key, server, opts) {
114
+ if (this.shut)
115
+ return UNPOOLED;
116
+ const memo = this.memo.get(key) ?? { server, opened: 0, floor: 0 };
117
+ this.memo.set(key, memo);
118
+ if (opts?.fresh === true)
119
+ supersede(memo);
120
+ const recalled = memo.failed !== undefined && !this.liveUnder(key) ? memo.failed : undefined;
121
+ if (recalled !== undefined)
122
+ return { recalled, settle: () => false };
123
+ const place = memo.opened++;
124
+ let open = true;
125
+ return {
126
+ recalled,
127
+ settle: (outcome) => {
128
+ if (!open)
129
+ return false;
130
+ open = false;
131
+ const failed = outcome !== "connected" && outcome !== "unkept";
132
+ if (outcome === "unkept" || place < memo.floor || (failed && this.liveUnder(key)))
133
+ return failed && memo.failed !== undefined;
134
+ memo.floor = place + 1;
135
+ if (failed)
136
+ memo.failed = { reason: outcome.failed };
137
+ else
138
+ delete memo.failed;
139
+ return failed;
140
+ },
141
+ };
142
+ }
143
+ forget(server) {
144
+ let forgotten = false;
145
+ for (const [key, memo] of this.memo) {
146
+ if (memo.server !== server)
147
+ continue;
148
+ if (memo.failed !== undefined)
149
+ forgotten = true;
150
+ supersede(memo);
151
+ if (this.dialing.has(key))
152
+ this.dropDial(key);
153
+ }
154
+ return forgotten;
155
+ }
156
+ get idle() {
157
+ return this.leased === 0 && this.dialing.size === 0;
158
+ }
159
+ liveUnder(key) {
160
+ const e = this.entries.get(key);
161
+ return e !== undefined && !e.closed;
162
+ }
99
163
  close() {
100
164
  this.shut = true;
101
165
  for (const e of [...this.entries.values()])
@@ -137,6 +201,7 @@ export class McpConnectionPool {
137
201
  }
138
202
  lease(entry) {
139
203
  entry.refs++;
204
+ this.leased++;
140
205
  const mine = new Set();
141
206
  let released = false;
142
207
  const lease = {
@@ -153,6 +218,7 @@ export class McpConnectionPool {
153
218
  for (const fn of mine)
154
219
  entry.listeners.delete(fn);
155
220
  entry.refs--;
221
+ this.leased--;
156
222
  if (entry.refs > 0)
157
223
  return;
158
224
  entry.current = false;
@@ -165,3 +231,40 @@ export class McpConnectionPool {
165
231
  return lease;
166
232
  }
167
233
  }
234
+ export class SessionMcpPools {
235
+ pools = new Map();
236
+ static CAP = 1024;
237
+ of(sessionId) {
238
+ const pool = this.pools.get(sessionId) ?? new McpConnectionPool({ sessionId });
239
+ this.pools.delete(sessionId);
240
+ this.pools.set(sessionId, pool);
241
+ for (const [id, p] of this.pools) {
242
+ if (this.pools.size <= SessionMcpPools.CAP)
243
+ break;
244
+ if (id !== sessionId && p.idle)
245
+ this.pools.delete(id);
246
+ }
247
+ return pool;
248
+ }
249
+ forget(sessionId, server) {
250
+ return this.pools.get(sessionId)?.forget(server) === true;
251
+ }
252
+ }
253
+ const POOLS_OF_STORE = new WeakMap();
254
+ export function sessionMcpPoolsOf(store) {
255
+ const held = POOLS_OF_STORE.get(store);
256
+ if (held !== undefined)
257
+ return held;
258
+ const pools = new SessionMcpPools();
259
+ POOLS_OF_STORE.set(store, pools);
260
+ return pools;
261
+ }
262
+ export function forgetSessionMcpFailure(pools, request) {
263
+ for (const field of ["sessionId", "server"]) {
264
+ const value = request?.[field];
265
+ if (typeof value !== "string" || value.length === 0) {
266
+ throw Object.assign(new Error(`forgetMcpFailure: request.${field} must be a non-empty string (got ${value === null ? "null" : typeof value === "string" ? "an empty string" : typeof value}) — nothing was forgotten`), { code: "config.invalid_argument", detail: { field: `ForgetMcpFailureRequest.${field}` } });
267
+ }
268
+ }
269
+ return { server: request.server, outcome: pools.forget(request.sessionId, request.server) ? "forgotten" : "none_remembered" };
270
+ }
@@ -54,8 +54,11 @@ export type McpFailureKind = (typeof MCP_FAILURE_KINDS)[number];
54
54
  export declare const MCP_AUTHORIZATION_REASONS: readonly ["rejected", "scope", "none"];
55
55
  export type McpAuthorizationReason = (typeof MCP_AUTHORIZATION_REASONS)[number];
56
56
  /**
57
- * The authorization fact an `unauthorized` failure carries — one record, read whole by every face (the status record, the wiring
58
- * manifest row, the thrown request error's `details`, the `mcp.authorization_required` notice, the model's needs-authorization line).
57
+ * The authorization fact an `unauthorized` failure carries — one record. The live faces read it whole (the status record, the wiring
58
+ * manifest row) or by its trusted members (the `mcp.authorization_required` notice's `detail`: `reason`, `authorizeUrl`); the address
59
+ * rides those structural keys and no sentence a person or the model reads names one (the needs-authorization line and arm, the
60
+ * notice's message — {@link WHERE_TO_AUTHORIZE}). The thrown request error's `details` — the tool result card, and so the session archive —
61
+ * keeps the `reason` only: the archive is a lossless copy that no deployment disposition can edit, and the two URLs are the live faces' alone.
59
62
  * The two URLs are separate members because their trust differs:
60
63
  * · `authorizeUrl` comes ONLY from the deployment's peer seat (its `unauthorized` answer, to the send or to the re-ask after a 401) —
61
64
  * TRUSTED; the engine never makes one up;
@@ -356,27 +359,50 @@ export declare function readMcpFailure(err: unknown, at: McpFailureSite): {
356
359
  */
357
360
  export interface McpUnavailableEntry extends AnnouncedMcpFailure {
358
361
  authorization?: McpAuthorization;
362
+ /** The session's pool remembers this failure (mcp-connection-pool.ts `attempt`): the session does not try the server again, and
363
+ * the frame says "for this session". Absent: the next message tries it again, and the frame says so. Never part of the told pair. */
364
+ remembered?: true;
359
365
  }
360
- /** Where the user authorizes, as every model-facing line names it: the seat's URL when the seat gave one, else only that none was given. */
361
- export declare function whereToAuthorize(authorizeUrl: string | undefined): string;
366
+ /**
367
+ * Where the user authorizes, as every sentence a person or the model reads names it: at the host's own prompt for the server, never an
368
+ * address. The address is the record's structural `authorizeUrl` (the status record, the manifest row, the notice's `detail`), rendered
369
+ * where a host renders authorization; a sentence that spelled it too would be a second carrier a deployment's handling of the key does
370
+ * not reach.
371
+ */
372
+ export declare const WHERE_TO_AUTHORIZE = "where the host shows the server's authorization prompt";
362
373
  /**
363
374
  * The `mcp_unavailable` frame's needs-authorization arm — the servers among `entries` whose failure record carries `authorization`, or
364
375
  * `undefined` when there are none. CC 2.1.309's arm, minted as `needsAuthMcpServers` (cli309.js:265582), read back as `needsAuthMcpServers` (cli309.js:267398),
365
376
  * worded (cli309.js:267399) "The following MCP servers require authentication before their tools can be used" — ahead of the
366
377
  * failed-to-connect arm; this engine never runs an authorization flow itself, so it is always the reference's cannot-start-the-flow form.
367
- * `<where>` is the deployment seat's `authorizeUrl` when it gave one (listed beside the server), else only the fact that none was given; no error
368
- * text rides it (the fact is the record's). At most `max` servers are named, the rest counted.
378
+ * The servers are listed by name alone and the sentence points at {@link WHERE_TO_AUTHORIZE}: no address rides it, whether the record holds one or not,
379
+ * and no error text (the fact is the record's). At most `max` servers are named, the rest counted.
369
380
  */
370
381
  export declare function needsAuthorizationArm(entries: readonly McpUnavailableEntry[], max: number): string | undefined;
371
382
  /**
372
383
  * The model's line for a request refused as `unauthorized` — the call-time twin of the needs-authorization arm the `mcp_unavailable`
373
- * frame carries for a server that could not mount (turn-attachments.ts): who must act (the user), where ({@link whereToAuthorize}: the
374
- * seat's URL, or that none was given), what not to ask for, and the delivery tail (`writeTail`, the caller's write-class sentence) the verdict owes. A 401
375
- * after which the deployment answered another credential that no request has carried yet (`renewed`: the first attempt, not sent again)
376
- * may pass on a new call: the line says so, and that only a refusal of that call too is the user's — a seat that answers a fresh
377
- * credential every time still reaches the user. A re-send refused again is the plain line.
384
+ * frame carries for a server that could not mount (turn-attachments.ts): who must act (the user), where ({@link WHERE_TO_AUTHORIZE}: the host's
385
+ * own prompt, no address), what not to ask for, and the delivery tail (`writeTail`, the caller's write-class sentence) the verdict owes. The line
386
+ * reads the record's `reason` only. A 401 after which the deployment answered another credential that no request has carried yet (`renewed`:
387
+ * the first attempt, not sent again) may pass on a new call: the line says so, and that only a refusal of that call too is the user's — a seat
388
+ * that answers a fresh credential every time still reaches the user. A re-send refused again is the plain line.
389
+ */
390
+ export declare function unauthorizedLine(what: string, serverLabel: string, a: Pick<McpAuthorization, "reason">, renewed: boolean, writeTail: string): string;
391
+ /**
392
+ * The user's step and where it is taken — the one clause every sentence about an `unauthorized` failure carries: the call line
393
+ * ({@link unauthorizedLine}) and every record face's text for the class (the per-server status's `error`, the wiring manifest row's, the refresh
394
+ * result's, a listing's per-server error, the operator warning's). The record faces read the failure's text through the one mint
395
+ * (`remoteErrorText`), and for this class that mint says this clause instead of the remote's body: the body is the remote's own words, which
396
+ * may write an address (or an instruction) the engine's authorization sentences never carry; the refusal itself is the record's own members
397
+ * (`errorCode`, `authorization.reason`). It reads the reason only.
398
+ */
399
+ export declare const userMustAuthorize: (reason: McpAuthorizationReason) => string;
400
+ /**
401
+ * The authorization a thrown value says is owed, read from its structure alone — `undefined` for every other failure. The three rows that mint
402
+ * `unauthorized` (the peer seat's answer, the endpoint's refused authorization, the SDK's own 401 / 403 codes) sit ahead of every row that reads
403
+ * the site, so the class is the same at the dial and on a request and a face that has no site to hand asks here.
378
404
  */
379
- export declare function unauthorizedLine(what: string, serverLabel: string, a: McpAuthorization, renewed: boolean, writeTail: string): string;
405
+ export declare function authorizationOwed(err: unknown): McpAuthorization | undefined;
380
406
  /**
381
407
  * What a transport-level HTTP failure can be said to be, in words for a model-facing line: the
382
408
  * condition to name, and the delivery verdict. `undefined` for every failure that is NOT of the HTTP
@@ -230,33 +230,29 @@ export function readMcpFailure(err, at) {
230
230
  function authorizationOf(reason, authorizeUrl, resourceMetadataUrl) {
231
231
  return { reason, ...(authorizeUrl !== undefined ? { authorizeUrl } : {}), ...(resourceMetadataUrl !== undefined ? { resourceMetadataUrl } : {}) };
232
232
  }
233
- const NO_AUTHORIZATION_ADDRESS = "no authorization address was given";
234
- export function whereToAuthorize(authorizeUrl) {
235
- return authorizeUrl !== undefined ? `at ${authorizeUrl}` : `(${NO_AUTHORIZATION_ADDRESS})`;
236
- }
233
+ export const WHERE_TO_AUTHORIZE = "where the host shows the server's authorization prompt";
237
234
  export function needsAuthorizationArm(entries, max) {
238
235
  const named = entries.filter((f) => f.authorization !== undefined);
239
236
  if (named.length === 0)
240
237
  return undefined;
241
- const withUrl = named.filter((f) => f.authorization?.authorizeUrl !== undefined).length;
242
- const where = withUrl === named.length
243
- ? "— at the address listed beside it —"
244
- : withUrl === 0
245
- ? whereToAuthorize(undefined)
246
- : "— at the address listed beside it (a server listed without one was given no authorization address) —";
247
- const lines = named.slice(0, max).map((f) => `${f.name}${f.authorization?.authorizeUrl !== undefined ? ` — authorize ${whereToAuthorize(f.authorization.authorizeUrl)}` : ""}`);
238
+ const lines = named.slice(0, max).map((f) => f.name);
248
239
  return (`The following MCP servers require authentication before their tools can be used:\n${lines.join("\n")}${named.length > max ? `\n…and ${named.length - max} more` : ""}\n\n` +
249
240
  `You cannot start the authorization flow yourself. If the user's request depends on one of these servers (even if they didn't name it explicitly), ` +
250
- `or they ask about it, tell them that it needs to be authorized ${where} and that the capability is unavailable until they do. ` +
241
+ `or they ask about it, tell them that it needs to be authorized ${WHERE_TO_AUTHORIZE} and that the capability is unavailable until they do. ` +
251
242
  `Otherwise carry on with the request and do not mention these servers. Do not ask the user for authorization codes, tokens, or callback URLs.`);
252
243
  }
253
244
  export function unauthorizedLine(what, serverLabel, a, renewed, writeTail) {
254
- const owed = `The user needs to authorize this server${a.reason === "scope" ? " for the access this request needs" : ""} ${whereToAuthorize(a.authorizeUrl)}; its capability is unavailable until they do. Do not ask the user for authorization codes, tokens, or callback URLs.`;
245
+ const owed = `${userMustAuthorize(a.reason)}; its capability is unavailable until they do. Do not ask the user for authorization codes, tokens, or callback URLs.`;
255
246
  if (a.reason === "none")
256
247
  return `${what} was not sent to MCP server "${serverLabel}": the deployment holds no authorization of this user for it. ${owed} The request was not delivered, so the server did not execute it.`;
257
248
  const refused = `${what} on MCP server "${serverLabel}" was refused ${a.reason === "scope" ? "for insufficient scope (HTTP 403)" : "as unauthorized (HTTP 401)"}`;
258
249
  return renewed ? `${refused}; the deployment has since answered another credential, which a new call carries — this call was not sent again. If that call is refused too: ${owed}${writeTail}` : `${refused}. ${owed}${writeTail}`;
259
250
  }
251
+ export const userMustAuthorize = (reason) => `The user needs to authorize this server${reason === "scope" ? " for the access this request needs" : ""} ${WHERE_TO_AUTHORIZE}`;
252
+ export function authorizationOwed(err) {
253
+ const read = classOf(err, { phase: "request" });
254
+ return read.kind === "unauthorized" ? read.authorization : undefined;
255
+ }
260
256
  function classOf(err, at) {
261
257
  for (const rule of FAILURE_CLASSIFIER)
262
258
  if (rule.when(err, at))
@@ -50,7 +50,8 @@ export interface McpProbeOptions {
50
50
  * Default: none. The probe has no clock of its own: it dials through the entrance a task does, so each
51
51
  * startup phase (the handshake, then the initial listing) carries that server's own bound from the one
52
52
  * reader ({@link import("./mcp.js").mcpStartupTimeoutMs}: its `startupTimeoutMs`, else env `MCP_TIMEOUT`, else
53
- * the SDK's 60 000 ms) — exactly what a task allows it. */
53
+ * 30 000 ms) — exactly what a task allows it. The probe holds no pool, so it remembers nothing of a failed dial and
54
+ * reads nothing a session remembers. */
54
55
  timeoutMs?: number;
55
56
  /** Abort the whole probe. The call rejects with the signal's own reason (a bare `abort()` gives an
56
57
  * `AbortError`) AFTER every server it had opened is closed — see the residue contract on
@@ -113,8 +114,8 @@ export interface McpProbeOptions {
113
114
  * return, and NOT that the call itself is bounded. What bounds it, stated part by part rather than
114
115
  * summarised into a number that would be wrong:
115
116
  * · a dial has two REQUEST-BUDGET phases, each carrying the startup-phase bound ({@link
116
- * import("./mcp.js").mcpStartupTimeoutMs}: the server's own `startupTimeoutMs`, else env `MCP_TIMEOUT`, else the SDK's
117
- * 60 000 ms default): the handshake, one
117
+ * import("./mcp.js").mcpStartupTimeoutMs}: the server's own `startupTimeoutMs`, else env `MCP_TIMEOUT`, else
118
+ * 30 000 ms): the handshake, one
118
119
  * request; and the initial tool listing, a PAGINATED WALK whose whole budget is that same number
119
120
  * (however many pages it takes — and no request at all when the peer advertises no tools). Two
120
121
  * budgets, so twice that, not once;
@@ -22,8 +22,10 @@ import { type ProtocolRevokedRefusal } from "./protocol-revocation.js";
22
22
  * ({@link ServerHealth.owed}). Returns the record.
23
23
  */
24
24
  export declare function observedFailure(err: unknown, site: McpFailureSite, health: ServerHealth | undefined, answer: boolean): McpFailure;
25
- /** A tool call's FINAL failure (the translated error, whose `details` is the record the one reading stamped) tells the server's
26
- * announcer what the user owes — the call lane's one announcement, made once its attempts are over. */
25
+ /** A tool call's FINAL failure (the translated error: its `cause` is the refusal the request met) tells the server's announcer what the user
26
+ * owes — the call lane's one announcement, made once its attempts are over. The record is read off the refusal itself, by the one classifier
27
+ * every face reads it with: the translated error's `details` is the card the run loop copies onto the tool result (and the session keeps),
28
+ * and it carries the reason alone — the seat's address is not on it. */
27
29
  export declare function owedByAnswer(err: unknown, health: ServerHealth): void;
28
30
  /** Mutable per-server liveness flag, shared between a server's tool closures and its transport-close hook.
29
31
  * `pendingElicitations` (RB-199 FO-1 codex review): a live count of in-flight `onElicit` waits on THIS
@@ -1,4 +1,4 @@
1
- import { readMcpFailure } from "./mcp-failure.js";
1
+ import { classifyMcpFailure, readMcpFailure } from "./mcp-failure.js";
2
2
  import { UNPROVEN_GATE } from "./mcp-listing-drift.js";
3
3
  import { resendUndelivered } from "./peer-seat.js";
4
4
  import { declarerWord } from "./mcp-server-spec.js";
@@ -13,10 +13,9 @@ export function observedFailure(err, site, health, answer) {
13
13
  return failure;
14
14
  }
15
15
  export function owedByAnswer(err, health) {
16
- const details = readMember(err, "details");
17
- const a = readMember(details, "code") === "unauthorized" ? readMember(details, "authorization") : undefined;
18
- if (typeof a === "object" && a !== null)
19
- health.owed?.(a);
16
+ const owed = classifyMcpFailure(readMember(err, "cause"), { phase: "request" }).authorization;
17
+ if (owed !== undefined)
18
+ health.owed?.(owed);
20
19
  }
21
20
  export const IDLE_WATCHDOG_ABORT_REASON = Symbol("mcp-idle-watchdog-abort");
22
21
  export function armMcpIdleWatchdog(health, idleMs, outerSignal) {
@@ -180,15 +180,15 @@ export interface McpServerSpec {
180
180
  /**
181
181
  * THIS server's startup bound, in whole milliseconds: the handshake (connect + initialize) and the initial tool listing each carry it
182
182
  * (the listing as one walk, however many pages). One knob, three seats, read by one function in this order — this member, else the
183
- * process-level `MCP_TIMEOUT`, else the MCP SDK's own 60 000 ms — so a server that hangs at startup is cut on its own clock while its
184
- * siblings keep the deployment's. It bounds only that startup phase: a call's own timeout (`MCP_TOOL_TIMEOUT`) is untouched.
183
+ * process-level `MCP_TIMEOUT`, else 30 000 ms — so a server that hangs at startup is cut on its own clock while its siblings keep the
184
+ * deployment's. A server cut at startup is remembered by the session as a failed attempt and not dialed again by its later messages. It bounds only that startup phase: a call's own timeout (`MCP_TOOL_TIMEOUT`) is untouched.
185
185
  *
186
186
  * The range is the one every MCP millisecond bound keeps, 1 000 to 2 147 483 647 (a larger delay is silently rewritten to 1 ms by the
187
187
  * timer, a smaller one is a unit slip). Unlike the environment seat — a string a process may clamp and announce — a declaration is typed
188
188
  * data, so anything else (a string, a fraction, zero, a negative, NaN, `null`, a number outside the range) refuses THIS server at its
189
189
  * dial (`config.mcp_startup_timeout_invalid`; siblings mount) rather than being clamped or read as the default.
190
190
  *
191
- * The bound a dial runs under (this member, else the environment seat) is part of a pooled connection's identity: mounts under one
191
+ * The bound a dial runs under (this member, else the environment seat, else the default) is part of a pooled connection's identity: mounts under one
192
192
  * bound lease ONE connection, mounts under different bounds dial their own — so a mount is never held by another mount's clock.
193
193
  * The no-run probe has no clock of its own: each startup phase carries this same bound (a caller's `timeoutMs` is an overall ceiling beside it).
194
194
  */
@@ -1,6 +1,6 @@
1
1
  /**
2
- * The person-facing half of an MCP server that could not be reached for a leg (`mcp.server_unavailable`, audience `user`). A server that
3
- * fails to connect or to list its tools is SKIPPED (fail-open: one bad server never bricks the task), and the run completes with the other
2
+ * The person-facing half of an MCP server that could not be reached (`mcp.server_unavailable`, audience `user`). A server that fails to
3
+ * connect or to list its tools is SKIPPED (fail-open: one bad server never bricks the task), and the run completes with the other
4
4
  * servers' tools; the operator hears it on `onError` (`{ phase: "mcp" }`), the wiring manifest's row and the materialization's status read
5
5
  * `failed`, and this notice is what the session's user hears — where, before it, they heard nothing and found the server's tools missing.
6
6
  *
@@ -8,24 +8,38 @@
8
8
  * mcp.ts), where the Runner drains that lane — so the operator's line and the person's notice are one fact, and there is no second source:
9
9
  * the server is read off the warning's `server` member, never parsed out of its sentence. A server whose dial failed `unauthorized` is
10
10
  * NOT told here: `mcp.authorization_required` already tells the user that fact, with the way to fix it, and says the server's tools are
11
- * unavailable until then — two notices for one fact would be two readings. Dedup unit: once per (leg, server) — a failed dial yields one
12
- * warning per materialization, and a later leg that fails again is a new fact; never folded per session (a second server's notice must not
13
- * be hidden behind the first's).
11
+ * unavailable until then — two notices for one fact would be two readings.
14
12
  *
15
- * `detail` carries the declared server's name and the leg's session and run — never the failure's text (the server's own words are the
13
+ * Dedup unit: the connection ATTEMPT that failed (mcp-connection-pool.ts `attempt`), told on the leg that settled it — legs that share
14
+ * one dial each settle their own attempt, so each says it. A failure the session's pool keeps (`memory: "kept"`: one that waited out
15
+ * the startup bound) is not tried again by the session, so it is said with the way back (change the server's configuration, have it
16
+ * reconnected, or give a server that is only slow to start a longer startup timeout); a later leg answered from that memory
17
+ * (`memory: "recalled"`) dialed nothing and says nothing. A failure that is not kept (one that came back before the bound, or a
18
+ * refusal of the deployment's own seats) is said for the run it ended, since the next run tries again. Never folded across servers
19
+ * (a second server's notice must not be hidden behind the first's).
20
+ *
21
+ * `detail` carries the declared server's name, the session whose pool holds the attempt (`leg.sessionId` — for a child or a workflow
22
+ * agent handed its session's pool, that session) and the leg's run — never the failure's text (the server's own words are the
16
23
  * operator's) and never a URL, command or path.
17
24
  */
18
25
  import type { EngineNotice } from "./engine-notice.js";
19
26
  import type { McpServerStatus } from "./mcp.js";
20
27
  /** The warning code the materialization mints for a server it skipped, and the notice's own: one word, two faces. */
21
28
  export declare const MCP_SERVER_UNAVAILABLE: "mcp.server_unavailable";
22
- /** What `asServerWarning` mints: the operator warning, carrying the declared server it is about. */
29
+ /** What `asServerWarning` mints: the operator warning, carrying the declared server it is about, and — on a pooled dial — what the
30
+ * session's pool did with the failure: `kept` (this leg's attempt failed and the session remembers it) or `recalled` (this leg
31
+ * dialed nothing: the session's memory of an earlier attempt answered). Absent: the failure is not remembered. */
23
32
  export type McpServerWarning = Error & {
24
33
  code: typeof MCP_SERVER_UNAVAILABLE;
25
34
  server: string;
35
+ memory?: "kept" | "recalled";
26
36
  };
37
+ /** Whether the session's pool remembers `server`'s failure, read off the materialization's warnings — the one carrier of that fact
38
+ * (`memory`, kept or recalled); the model's frame asks it as the person's notice does. */
39
+ export declare function mcpFailureRemembered(warnings: readonly Error[]): (server: string) => boolean;
27
40
  /** The notice a materialization warning stands for, or `undefined` when it stands for none: a warning of another code, one that names no
28
- * server, or one about a server whose failure was an authorization (told by `mcp.authorization_required`). */
41
+ * server, one about a server whose failure was an authorization (told by `mcp.authorization_required`), or one a leg answered from the
42
+ * session's memory (told when that attempt failed). */
29
43
  export declare function mcpServerUnavailableNotice(warning: Error, statuses: readonly Pick<McpServerStatus, "name" | "authorization">[], leg: {
30
44
  sessionId: string;
31
45
  runId: string;
@@ -1,15 +1,29 @@
1
1
  import { inlineUntrusted } from "./untrusted-text.js";
2
2
  export const MCP_SERVER_UNAVAILABLE = "mcp.server_unavailable";
3
+ export function mcpFailureRemembered(warnings) {
4
+ const remembered = new Set();
5
+ for (const w of warnings) {
6
+ const { code, server, memory } = w;
7
+ if (code === MCP_SERVER_UNAVAILABLE && typeof server === "string" && memory !== undefined)
8
+ remembered.add(server);
9
+ }
10
+ return (server) => remembered.has(server);
11
+ }
3
12
  export function mcpServerUnavailableNotice(warning, statuses, leg) {
4
- const { code, server } = warning;
5
- if (code !== MCP_SERVER_UNAVAILABLE || typeof server !== "string")
13
+ const { code, server, memory } = warning;
14
+ if (code !== MCP_SERVER_UNAVAILABLE || typeof server !== "string" || memory === "recalled")
6
15
  return undefined;
7
16
  if (statuses.some((s) => s.name === server && s.authorization !== undefined))
8
17
  return undefined;
18
+ const name = inlineUntrusted(server, 160);
9
19
  return {
10
20
  code: "mcp.server_unavailable",
11
- message: `MCP server "${inlineUntrusted(server, 160)}" could not be reached for this run, so it was skipped — its tools are not available to the assistant ` +
12
- `in this run, which goes on with the tools of the servers that did connect.`,
21
+ message: memory === "kept"
22
+ ? `MCP server "${name}" did not answer within its startup timeout, so it was skipped — its tools are not available to the assistant ` +
23
+ `for the rest of this session, which goes on with the tools of the servers that did connect. It is not tried again unless its ` +
24
+ `configuration changes or it is reconnected; if it is only slow to start, give it a longer startup timeout.`
25
+ : `MCP server "${name}" could not be reached for this run, so it was skipped — its tools are not available to the assistant ` +
26
+ `in this run, which goes on with the tools of the servers that did connect.`,
13
27
  detail: { server, sessionId: leg.sessionId, runId: leg.runId },
14
28
  };
15
29
  }