@sema-agent/core 7.57.0 → 7.59.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 (399) hide show
  1. package/CHANGELOG.md +1161 -0
  2. package/README.md +6 -4
  3. package/dist/agents/cc-peer-directory.js +8 -8
  4. package/dist/agents/child-model-seat.d.ts +4 -2
  5. package/dist/agents/child-model-seat.js +5 -3
  6. package/dist/agents/peer-directory.d.ts +9 -0
  7. package/dist/agents/peer-directory.js +6 -2
  8. package/dist/agents/send-message-tool.js +21 -12
  9. package/dist/agents/subagent-steps.js +2 -4
  10. package/dist/agents/subagent.js +33 -34
  11. package/dist/brain/anthropic.js +161 -45
  12. package/dist/brain/errors.d.ts +9 -3
  13. package/dist/brain/errors.js +7 -1
  14. package/dist/brain/failover.js +2 -1
  15. package/dist/brain/open-responses.js +3 -3
  16. package/dist/brain/openai.js +103 -53
  17. package/dist/brain/provider-dialect.d.ts +11 -0
  18. package/dist/brain/provider-dialect.js +5 -2
  19. package/dist/brain/reasoning-request.js +5 -4
  20. package/dist/brain/reasoning.d.ts +19 -0
  21. package/dist/brain/reasoning.js +17 -2
  22. package/dist/brain/request-route.d.ts +4 -1
  23. package/dist/brain/request-route.js +4 -1
  24. package/dist/brain/route-adjudicator.d.ts +84 -18
  25. package/dist/brain/route-adjudicator.js +89 -22
  26. package/dist/brain/route-conformance.js +1 -1
  27. package/dist/brain/stream-engine.js +84 -49
  28. package/dist/brain/stream-shared.d.ts +30 -0
  29. package/dist/brain/stream-shared.js +34 -1
  30. package/dist/brain/timeout.d.ts +62 -5
  31. package/dist/brain/timeout.js +93 -6
  32. package/dist/core/a2a.d.ts +2 -1
  33. package/dist/core/a2a.js +23 -10
  34. package/dist/core/account-row.d.ts +61 -0
  35. package/dist/core/account-row.js +51 -0
  36. package/dist/core/advisor-verdict.d.ts +2 -1
  37. package/dist/core/advisor-verdict.js +1 -1
  38. package/dist/core/allow-entry.d.ts +20 -7
  39. package/dist/core/allow-entry.js +18 -9
  40. package/dist/core/approval-object.d.ts +29 -15
  41. package/dist/core/approval-object.js +47 -19
  42. package/dist/core/ask-origin.d.ts +21 -2
  43. package/dist/core/ask-origin.js +5 -1
  44. package/dist/core/auto-compaction.d.ts +4 -0
  45. package/dist/core/auto-compaction.js +2 -2
  46. package/dist/core/auto-mode-directive.d.ts +29 -5
  47. package/dist/core/auto-mode-directive.js +38 -8
  48. package/dist/core/background-agent-store.d.ts +16 -3
  49. package/dist/core/checkpoint-requirements.d.ts +19 -1
  50. package/dist/core/checkpoint-requirements.js +5 -1
  51. package/dist/core/checkpoint-store.d.ts +85 -23
  52. package/dist/core/checkpoint-store.js +31 -9
  53. package/dist/core/child-clamp-seats.d.ts +29 -0
  54. package/dist/core/child-clamp-seats.js +56 -1
  55. package/dist/core/compliance.d.ts +2 -2
  56. package/dist/core/compliance.js +1 -1
  57. package/dist/core/effective-path-target.d.ts +8 -2
  58. package/dist/core/effective-path-target.js +8 -3
  59. package/dist/core/engine-notice.d.ts +99 -9
  60. package/dist/core/engine-notice.js +19 -5
  61. package/dist/core/fs-write-gate-policy.d.ts +4 -2
  62. package/dist/core/fs-write-gate-policy.js +7 -3
  63. package/dist/core/gate-fold.js +7 -4
  64. package/dist/core/gate-lanes.js +19 -6
  65. package/dist/core/gate-outcome.d.ts +32 -3
  66. package/dist/core/gate-outcome.js +19 -1
  67. package/dist/core/git-worktree-env.d.ts +53 -11
  68. package/dist/core/git-worktree-env.js +96 -12
  69. package/dist/core/governance-codes.d.ts +9 -1
  70. package/dist/core/governance-codes.js +13 -0
  71. package/dist/core/hooks.d.ts +35 -4
  72. package/dist/core/hooks.js +17 -11
  73. package/dist/core/human-input-projection.d.ts +1 -0
  74. package/dist/core/human-input-projection.js +3 -0
  75. package/dist/core/image-admission.d.ts +6 -5
  76. package/dist/core/image-admission.js +18 -14
  77. package/dist/core/locked-config.d.ts +20 -3
  78. package/dist/core/locked-config.js +40 -3
  79. package/dist/core/mailbox-store.d.ts +45 -1
  80. package/dist/core/mailbox-store.js +53 -9
  81. package/dist/core/mcp-call-meta.d.ts +66 -0
  82. package/dist/core/mcp-call-meta.js +103 -0
  83. package/dist/core/mcp-connection-pool.d.ts +3 -1
  84. package/dist/core/mcp-connection-pool.js +3 -1
  85. package/dist/core/mcp-failure.d.ts +117 -15
  86. package/dist/core/mcp-failure.js +71 -3
  87. package/dist/core/mcp-probe.d.ts +4 -0
  88. package/dist/core/mcp-probe.js +1 -1
  89. package/dist/core/mcp-server-link.d.ts +27 -3
  90. package/dist/core/mcp-server-link.js +25 -1
  91. package/dist/core/mcp-server-spec.d.ts +46 -18
  92. package/dist/core/mcp-server-spec.js +1 -18
  93. package/dist/core/mcp.d.ts +16 -20
  94. package/dist/core/mcp.js +112 -55
  95. package/dist/core/memory-engine/consolidation-driver.d.ts +2 -4
  96. package/dist/core/memory-engine/consolidation-driver.js +3 -3
  97. package/dist/core/memory-engine/consolidation.d.ts +4 -0
  98. package/dist/core/memory-engine/consolidation.js +1 -0
  99. package/dist/core/memory-engine/delegation-settlement.js +5 -12
  100. package/dist/core/memory-engine/distiller.js +2 -2
  101. package/dist/core/memory-engine/dual-root.d.ts +50 -1
  102. package/dist/core/memory-engine/dual-root.js +44 -1
  103. package/dist/core/memory-engine/engine.d.ts +67 -14
  104. package/dist/core/memory-engine/engine.js +384 -212
  105. package/dist/core/memory-engine/export-bundle.d.ts +23 -0
  106. package/dist/core/memory-engine/export-bundle.js +23 -4
  107. package/dist/core/memory-engine/file-backend.d.ts +128 -55
  108. package/dist/core/memory-engine/file-backend.js +290 -117
  109. package/dist/core/memory-engine/index.d.ts +1 -1
  110. package/dist/core/memory-engine/layout.d.ts +59 -11
  111. package/dist/core/memory-engine/layout.js +190 -40
  112. package/dist/core/memory-engine/memory-backend-contract.d.ts +1 -1
  113. package/dist/core/memory-engine/memory-backend-contract.js +39 -2
  114. package/dist/core/memory-engine/scope-contract.d.ts +45 -4
  115. package/dist/core/memory-engine/scope-contract.js +80 -11
  116. package/dist/core/memory-engine/sync-client.d.ts +9 -1
  117. package/dist/core/memory-engine/sync-client.js +31 -8
  118. package/dist/core/memory-engine/sync.d.ts +5 -0
  119. package/dist/core/memory-engine/types.d.ts +6 -0
  120. package/dist/core/mode-policy.d.ts +8 -5
  121. package/dist/core/mode-policy.js +5 -4
  122. package/dist/core/mods/classic-events.d.ts +5 -1
  123. package/dist/core/mods/host.js +1 -1
  124. package/dist/core/mods/kernel/dispatch.d.ts +3 -0
  125. package/dist/core/mods/kernel/dispatch.js +12 -9
  126. package/dist/core/mods/kernel/events.d.ts +6 -1
  127. package/dist/core/mods/kernel/events.js +2 -2
  128. package/dist/core/mods/kernel/registration.d.ts +9 -1
  129. package/dist/core/mods/kernel/registration.js +3 -0
  130. package/dist/core/mods/kernel/site-rules.d.ts +3 -0
  131. package/dist/core/mods/kernel/site-rules.js +10 -0
  132. package/dist/core/mods/package.d.ts +23 -0
  133. package/dist/core/mods/package.js +118 -0
  134. package/dist/core/mods/stations.d.ts +33 -12
  135. package/dist/core/mods/stations.js +45 -11
  136. package/dist/core/mods/tool-call.d.ts +5 -1
  137. package/dist/core/mods/tool-call.js +13 -4
  138. package/dist/core/parent-spec-seat.d.ts +8 -3
  139. package/dist/core/parent-spec-seat.js +2 -0
  140. package/dist/core/park-selfcheck.js +6 -0
  141. package/dist/core/path-guard-rows.d.ts +20 -0
  142. package/dist/core/path-guard-rows.js +11 -0
  143. package/dist/core/peer-seat.d.ts +248 -0
  144. package/dist/core/peer-seat.js +439 -0
  145. package/dist/core/permission-rule-consent.js +10 -4
  146. package/dist/core/permission-rule-model.d.ts +16 -0
  147. package/dist/core/permission-rule-model.js +1 -1
  148. package/dist/core/present-plan-tool.d.ts +20 -3
  149. package/dist/core/present-plan-tool.js +48 -4
  150. package/dist/core/protocol-http-auth.d.ts +40 -29
  151. package/dist/core/protocol-http-auth.js +30 -32
  152. package/dist/core/redaction-marks.d.ts +16 -0
  153. package/dist/core/redaction-marks.js +16 -0
  154. package/dist/core/redaction-passes.js +8 -9
  155. package/dist/core/resume-startup-cause.js +1 -0
  156. package/dist/core/retention.d.ts +41 -15
  157. package/dist/core/retention.js +59 -12
  158. package/dist/core/rewrite-rejudge.d.ts +38 -0
  159. package/dist/core/rewrite-rejudge.js +42 -2
  160. package/dist/core/roles.d.ts +34 -2
  161. package/dist/core/roles.js +43 -4
  162. package/dist/core/run-origin.d.ts +40 -0
  163. package/dist/core/run-origin.js +37 -0
  164. package/dist/core/runner/advertised-writable-dirs.d.ts +57 -38
  165. package/dist/core/runner/advertised-writable-dirs.js +126 -0
  166. package/dist/core/runner/announce-once-ledger.d.ts +5 -4
  167. package/dist/core/runner/announce-once-ledger.js +4 -2
  168. package/dist/core/runner/call-hook-stations.js +2 -2
  169. package/dist/core/runner/compaction-restate.d.ts +15 -6
  170. package/dist/core/runner/compaction-restate.js +28 -2
  171. package/dist/core/runner/contracts.d.ts +33 -21
  172. package/dist/core/runner/credential-origin-seat.js +4 -3
  173. package/dist/core/runner/cwd-alignment-probe.d.ts +20 -0
  174. package/dist/core/runner/cwd-alignment-probe.js +21 -0
  175. package/dist/core/runner/decide-continuation.d.ts +2 -2
  176. package/dist/core/runner/gate-exit.d.ts +30 -8
  177. package/dist/core/runner/gate-exit.js +15 -8
  178. package/dist/core/runner/image-removed-seat.d.ts +12 -0
  179. package/dist/core/runner/image-removed-seat.js +19 -0
  180. package/dist/core/runner/inline-image.js +1 -1
  181. package/dist/core/runner/memory-consolidation-driver.js +3 -3
  182. package/dist/core/runner/park-commit.d.ts +1 -1
  183. package/dist/core/runner/park-commit.js +3 -0
  184. package/dist/core/runner/prepare-ask-lane.d.ts +1 -1
  185. package/dist/core/runner/prepare-ask-lane.js +2 -1
  186. package/dist/core/runner/prepare-boundary-parks.js +2 -2
  187. package/dist/core/runner/prepare-caps-and-workflow.d.ts +5 -5
  188. package/dist/core/runner/prepare-caps-and-workflow.js +3 -1
  189. package/dist/core/runner/prepare-config-doors.d.ts +8 -5
  190. package/dist/core/runner/prepare-config-doors.js +14 -10
  191. package/dist/core/runner/prepare-context-lane.js +2 -0
  192. package/dist/core/runner/prepare-delegation-surface.d.ts +8 -0
  193. package/dist/core/runner/prepare-delegation-surface.js +16 -18
  194. package/dist/core/runner/prepare-gate-stations.js +1 -1
  195. package/dist/core/runner/prepare-hands-readface.d.ts +11 -3
  196. package/dist/core/runner/prepare-hands-readface.js +9 -1
  197. package/dist/core/runner/prepare-inherited-gate.d.ts +1 -3
  198. package/dist/core/runner/prepare-inherited-gate.js +14 -27
  199. package/dist/core/runner/prepare-memory.d.ts +3 -0
  200. package/dist/core/runner/prepare-memory.js +26 -37
  201. package/dist/core/runner/prepare-park-ask.d.ts +1 -1
  202. package/dist/core/runner/prepare-park-ask.js +2 -1
  203. package/dist/core/runner/prepare-policy-chain.d.ts +7 -7
  204. package/dist/core/runner/prepare-policy-chain.js +18 -15
  205. package/dist/core/runner/prepare-project-context.d.ts +2 -2
  206. package/dist/core/runner/prepare-project-context.js +2 -2
  207. package/dist/core/runner/prepare-prompt-inputs.d.ts +1 -1
  208. package/dist/core/runner/prepare-prompt-inputs.js +8 -19
  209. package/dist/core/runner/prepare-protocol-tools.d.ts +4 -2
  210. package/dist/core/runner/prepare-protocol-tools.js +11 -3
  211. package/dist/core/runner/prepare-run-refs.d.ts +2 -3
  212. package/dist/core/runner/prepare-run-refs.js +4 -1
  213. package/dist/core/runner/prepare-suspend-saga.d.ts +2 -0
  214. package/dist/core/runner/prepare-suspend-saga.js +2 -1
  215. package/dist/core/runner/prepare-task.js +28 -13
  216. package/dist/core/runner/prepare-wiring-manifest.d.ts +2 -1
  217. package/dist/core/runner/prepare-wiring-manifest.js +4 -3
  218. package/dist/core/runner/prepare-workspace-restore.d.ts +3 -0
  219. package/dist/core/runner/prepare-workspace-restore.js +4 -4
  220. package/dist/core/runner/reply-pricing.d.ts +30 -0
  221. package/dist/core/runner/reply-pricing.js +19 -0
  222. package/dist/core/runner/resume-admission.js +5 -3
  223. package/dist/core/runner/resume-apply.js +6 -1
  224. package/dist/core/runner/resume-checkpoint-screen.js +2 -0
  225. package/dist/core/runner/resume-policy-outcome.js +5 -5
  226. package/dist/core/runner/role-seat-defaulted.d.ts +44 -0
  227. package/dist/core/runner/role-seat-defaulted.js +40 -0
  228. package/dist/core/runner/run-brain-sinks.js +2 -0
  229. package/dist/core/runner/run-harness-handlers.d.ts +3 -4
  230. package/dist/core/runner/run-harness-handlers.js +1 -8
  231. package/dist/core/runner/run-identity-wiring.d.ts +2 -5
  232. package/dist/core/runner/run-identity-wiring.js +6 -4
  233. package/dist/core/runner/run-leg.d.ts +2 -0
  234. package/dist/core/runner/run-leg.js +42 -29
  235. package/dist/core/runner/run-notification-lane.js +3 -0
  236. package/dist/core/runner/run-stop-and-final-verify.js +2 -2
  237. package/dist/core/runner/run-terminal-adoption.d.ts +2 -5
  238. package/dist/core/runner/run-terminal-adoption.js +9 -3
  239. package/dist/core/runner/run-turn-boundary.js +77 -70
  240. package/dist/core/runner/runtask.d.ts +1 -1
  241. package/dist/core/runner/runtask.js +2 -2
  242. package/dist/core/runner/side-call-account.d.ts +1 -1
  243. package/dist/core/runner/side-call-account.js +3 -18
  244. package/dist/core/runner/sub-agent-deny-lists.d.ts +24 -0
  245. package/dist/core/runner/sub-agent-deny-lists.js +10 -0
  246. package/dist/core/runner/terminal-account.js +3 -3
  247. package/dist/core/runner/tool-end-body.js +2 -1
  248. package/dist/core/runner/tool-occurrence.d.ts +5 -2
  249. package/dist/core/runner/tool-occurrence.js +4 -3
  250. package/dist/core/runner/turn-attachments.d.ts +26 -22
  251. package/dist/core/runner/turn-attachments.js +24 -26
  252. package/dist/core/runner/write-protection-station.d.ts +8 -2
  253. package/dist/core/runner/write-protection-station.js +2 -0
  254. package/dist/core/runner-deps.d.ts +3 -3
  255. package/dist/core/secret-env.d.ts +32 -2
  256. package/dist/core/secret-env.js +65 -3
  257. package/dist/core/sensitive-path-policy.js +9 -10
  258. package/dist/core/session-log-transfer.d.ts +24 -0
  259. package/dist/core/session-log-transfer.js +166 -0
  260. package/dist/core/session-policy-store.d.ts +3 -1
  261. package/dist/core/session-policy-store.js +13 -9
  262. package/dist/core/session-store.d.ts +86 -24
  263. package/dist/core/session-store.js +162 -24
  264. package/dist/core/session.d.ts +92 -1
  265. package/dist/core/shell-read-silence.js +1 -0
  266. package/dist/core/side-query.d.ts +11 -1
  267. package/dist/core/side-query.js +9 -0
  268. package/dist/core/skill-grant-binding.d.ts +31 -2
  269. package/dist/core/skill-grant-binding.js +31 -1
  270. package/dist/core/skill-grant.d.ts +8 -5
  271. package/dist/core/skill-grant.js +6 -6
  272. package/dist/core/steer-replay.d.ts +4 -2
  273. package/dist/core/steer-replay.js +2 -1
  274. package/dist/core/store-contracts/background-agent-store-contract.js +27 -0
  275. package/dist/core/store-contracts/checkpoint-store-contract.js +20 -2
  276. package/dist/core/store-contracts/mailbox-store-contract.js +31 -1
  277. package/dist/core/store-contracts/session-repo-contract.js +112 -5
  278. package/dist/core/store-contracts/session-store-contract.d.ts +4 -1
  279. package/dist/core/store-contracts/session-store-contract.js +236 -2
  280. package/dist/core/synthetic-read-verdict.js +2 -1
  281. package/dist/core/task-event.d.ts +92 -8
  282. package/dist/core/task-notification.js +16 -10
  283. package/dist/core/task-registry-agent.js +1 -0
  284. package/dist/core/task-registry-shared.d.ts +7 -1
  285. package/dist/core/task-spec.d.ts +49 -1
  286. package/dist/core/task-stream.d.ts +2 -1
  287. package/dist/core/terminal-cause.d.ts +11 -1
  288. package/dist/core/tool-catalog-entries.js +1 -0
  289. package/dist/core/tool-check-reading.d.ts +1 -0
  290. package/dist/core/tool-check-reading.js +3 -3
  291. package/dist/core/tool-policy.d.ts +16 -0
  292. package/dist/core/tool-result-store.d.ts +17 -10
  293. package/dist/core/tool-result-store.js +3 -1
  294. package/dist/core/tool-roster.d.ts +112 -5
  295. package/dist/core/tool-roster.js +42 -1
  296. package/dist/core/tool-spec.d.ts +3 -1
  297. package/dist/core/types.d.ts +3 -3
  298. package/dist/core/types.js +1 -1
  299. package/dist/core/untrusted-egress.d.ts +0 -2
  300. package/dist/core/untrusted-egress.js +10 -14
  301. package/dist/core/user-attachment.js +1 -1
  302. package/dist/core/wiring-manifest.d.ts +18 -6
  303. package/dist/core/wiring-manifest.js +4 -3
  304. package/dist/core/workspace-snapshot.d.ts +44 -0
  305. package/dist/core/workspace-snapshot.js +34 -0
  306. package/dist/core/write-protect.d.ts +43 -3
  307. package/dist/core/write-protect.js +43 -16
  308. package/dist/engine/compaction/compaction.js +29 -3
  309. package/dist/engine/execution-env/node-execution-env.d.ts +4 -3
  310. package/dist/engine/execution-env/node-execution-env.js +24 -23
  311. package/dist/engine/execution-env/symlink-chain.d.ts +7 -5
  312. package/dist/engine/harness/agent-harness.d.ts +30 -2
  313. package/dist/engine/harness/agent-harness.js +43 -12
  314. package/dist/engine/harness/messages.d.ts +3 -1
  315. package/dist/engine/harness/messages.js +3 -2
  316. package/dist/engine/harness/types.d.ts +56 -7
  317. package/dist/engine/harness/types.js +5 -1
  318. package/dist/engine/llm/rejected-images.d.ts +46 -0
  319. package/dist/engine/llm/rejected-images.js +54 -0
  320. package/dist/engine/llm/tool-turns.d.ts +2 -1
  321. package/dist/engine/llm/types.d.ts +30 -10
  322. package/dist/engine/llm/types.js +1 -1
  323. package/dist/engine/loop/agent-loop.d.ts +8 -0
  324. package/dist/engine/loop/agent-loop.js +52 -15
  325. package/dist/engine/loop/types.d.ts +3 -1
  326. package/dist/engine/session/import-validate.js +3 -0
  327. package/dist/engine/session/memory-repo.d.ts +17 -9
  328. package/dist/engine/session/memory-repo.js +44 -34
  329. package/dist/engine/session/path-to-root.d.ts +38 -0
  330. package/dist/engine/session/path-to-root.js +39 -0
  331. package/dist/engine/session/repo-utils.d.ts +22 -4
  332. package/dist/engine/session/repo-utils.js +49 -1
  333. package/dist/engine/session/storage-base.d.ts +10 -1
  334. package/dist/engine/session/storage-base.js +11 -22
  335. package/dist/index.d.ts +29 -16
  336. package/dist/index.js +21 -11
  337. package/dist/internal/harness-types.d.ts +2 -2
  338. package/dist/internal/harness.d.ts +3 -2
  339. package/dist/internal/harness.js +2 -2
  340. package/dist/internal/llm.d.ts +1 -0
  341. package/dist/orchestration/workflow-observe.d.ts +17 -1
  342. package/dist/orchestration/workflow-observe.js +20 -0
  343. package/dist/orchestration/workflow-types.d.ts +32 -7
  344. package/dist/orchestration/workflow.js +739 -489
  345. package/dist/shell/counting-pass.d.ts +50 -0
  346. package/dist/shell/counting-pass.js +502 -0
  347. package/dist/shell/lex.d.ts +4 -2
  348. package/dist/shell/lex.js +93 -34
  349. package/dist/shell/shell-words.d.ts +1 -1
  350. package/dist/shell/shell-words.js +7 -6
  351. package/dist/stores/file/index.d.ts +4 -1
  352. package/dist/stores/file/index.js +4 -1
  353. package/dist/stores/file/mailbox-store.js +6 -10
  354. package/dist/stores/file/session-store.d.ts +15 -8
  355. package/dist/stores/file/session-store.js +28 -13
  356. package/dist/tools/fs/fs-bash.d.ts +6 -0
  357. package/dist/tools/fs/fs-bash.js +6 -3
  358. package/dist/tools/fs/fs-write.d.ts +6 -3
  359. package/dist/tools/fs/fs-write.js +8 -7
  360. package/dist/tools/fs/index.d.ts +3 -0
  361. package/dist/tools/fs/index.js +7 -3
  362. package/dist/tools/fs/program-read-model.d.ts +13 -0
  363. package/dist/tools/fs/program-read-model.js +15 -0
  364. package/dist/tools/fs/program-read-model.rows.js +1 -1
  365. package/dist/tools/fs/read-deny.d.ts +13 -10
  366. package/dist/tools/fs/read-deny.js +25 -5
  367. package/dist/tools/fs/read-floor.d.ts +19 -0
  368. package/dist/tools/fs/read-floor.js +23 -0
  369. package/dist/tools/fs/safety.js +40 -8
  370. package/dist/tools/fs/search.js +6 -24
  371. package/dist/tools/fs/shell-read-check.d.ts +9 -2
  372. package/dist/tools/fs/shell-read-check.js +61 -16
  373. package/dist/tools/fs/shell-read-establish.js +2 -1
  374. package/dist/tools/fs/shell-read-identity.js +1 -1
  375. package/dist/tools/fs/shell-read-judge.d.ts +26 -9
  376. package/dist/tools/fs/shell-read-judge.js +10 -6
  377. package/dist/tools/fs/shell-read-plan.d.ts +6 -1
  378. package/dist/tools/fs/shell-read-plan.js +22 -15
  379. package/dist/tools/fs/shell-read-start.js +1 -0
  380. package/dist/tools/fs/shell-reentry-text.d.ts +15 -1
  381. package/dist/tools/fs/shell-reentry-text.js +25 -3
  382. package/dist/tools/monitor.d.ts +4 -0
  383. package/dist/tools/monitor.js +2 -0
  384. package/dist/tools/worktree.d.ts +42 -15
  385. package/dist/tools/worktree.js +60 -32
  386. package/package.json +5 -2
  387. package/test/export-surface.snapshot.json +149 -1
  388. package/wire-changes/core-stores-sql@7.58.0.json +29 -0
  389. package/wire-changes/core-stores-sql@7.59.0.json +29 -0
  390. package/wire-changes/core@7.58.0.json +2188 -0
  391. package/wire-changes/core@7.59.0.json +2459 -0
  392. package/wire-changes/mods-kernel@7.58.0.json +81 -0
  393. package/wire-changes/mods-kernel@7.59.0.json +29 -0
  394. package/wire-changes/primitives@7.58.0.json +29 -0
  395. package/wire-changes/primitives@7.59.0.json +29 -0
  396. package/dist/primitives/credential-ref.d.ts +0 -89
  397. package/dist/primitives/credential-ref.js +0 -125
  398. package/dist/primitives/index.d.ts +0 -2
  399. package/dist/primitives/index.js +0 -1
@@ -15,12 +15,14 @@
15
15
  * sources — **a credential has exactly one root** — differing only in where that root comes from:
16
16
  * - `per-model` → a per-model credential (auth hook or a credential header on `Model.headers`) is bound to the
17
17
  * ORIGIN (scheme + host + port) of the first request the engine SENT carrying it, in the engine's one
18
- * credential-origin table ({@link credentialOriginTable}) — written only by a brain's request gate when the request
19
- * goes out ({@link admitRouteRequest}), read by every judgment; a request carrying it to another origin is
18
+ * credential-origin table ({@link credentialOriginTable}) — written by a brain's request gate when the request
19
+ * goes out ({@link admitRouteRequest}) and moved by nothing but the host's explicit rebind
20
+ * ({@link rebindCredentialOrigin}), read by every judgment; a request carrying it to another origin is
20
21
  * refused (`route.credential_origin_mismatch`), a request to another path of the same origin is not. An
21
22
  * entry whose `baseUrl` moves to another host while its credential stays the same therefore sends
22
- * nothing: the credential belongs to the host it was first sent to, and a NEW credential (the entry's
23
- * credential reference changed with its address) is a new binding. The binding lasts for the process. Before any
23
+ * nothing: the credential belongs to the host it was first sent to (or the host rebound it to), and a NEW credential (the entry's
24
+ * credential reference changed with its address) is a new binding. The binding lasts for the process, unless the
25
+ * host rebinds it; nothing a request or a catalog carries moves it. Before any
24
26
  * origin is read, a per-model credential is ONE value per header: a request whose per-call `apiKey` is set beside a
25
27
  * header of the very name its lane writes that key in carries two values for one header, and is refused
26
28
  * (`route.credential_answer_conflict`) wherever it is going.
@@ -47,6 +49,9 @@
47
49
  * Each is a VERDICT, one shape for every caller of the law ({@link adjudicateModelRoute}, which throws on garbage
48
50
  * alone): the request gate, a pre-flight, the read face and a failover chain read the same refusal.
49
51
  * - absence — `route.credential_missing` with the fix hint, exactly where absence is a hole.
52
+ * - blank — an `apiKey`, or a credential header's value, with nothing but white space in it is the keyless door
53
+ * ({@link keyCarriedBy}), one reading for every source: its source keeps its rank (no other source's credential
54
+ * rides in its place), and nothing of it rides or is bound.
50
55
  * - misplacement — a credential in the URL, or a non-http(s) root: {@link assertServableRequestRoot}.
51
56
  */
52
57
  import type { Model } from "../internal/llm.js";
@@ -138,17 +143,27 @@ export declare function resolveRequestRootOf(modelBaseUrl: string | undefined, c
138
143
  * `Cookie`, …), the same reading the withheld-value intake keeps. */
139
144
  export declare function hasAuthCarrier(headers: Record<string, string> | undefined): boolean;
140
145
  /** Test seam: empties the process's credential-origin table — every per-model credential is unbound again, as at a
141
- * process start. Never called by production code (a binding lasts as long as the process; restarting rebinds). A test
146
+ * process start. Never called by production code (a deployment moves one credential with {@link rebindCredentialOrigin}, and a restart empties the table). A test
142
147
  * suite that sends one fixture credential to two local mock upstreams (two `listen(0)` ports are two origins) calls it
143
148
  * between cases, or gives each case its own fixture credential. */
144
149
  export declare function __resetCredentialOriginBindings(): void;
150
+ /**
151
+ * The key a request carries in its lane's key header — THE one reading of which `apiKey` (the per-call one, or the
152
+ * brain's construction-time one) writes that header: the key itself when it is not blank ({@link isBlankCredential}),
153
+ * else `undefined`. A blank key (the empty string, or white space only) is the keyless door: its source keeps its rank,
154
+ * and the credential {@link resolveRouteCredential} resolves carries no `apiKey` — so no lane writes a key header, no
155
+ * identity is bound and no header of the request's own conflicts with it. Read where a credential is resolved, and by
156
+ * the route a request states ({@link import("./request-route.js").requestRouteOf}); a host that sends a request itself
157
+ * reads the resolved credential's `apiKey`, as the lanes do.
158
+ */
159
+ export declare function keyCarriedBy(apiKey: string | undefined): string | undefined;
145
160
  /**
146
161
  * Resolve WHICH credential a request would carry, tagged with its source — the input half of the
147
162
  * adjudication. One rank per SOURCE, most-specific wins; within a rank the apiKey knob and the rank's
148
163
  * credential headers are ONE credential (they ride together and are bound together):
149
- * 1. the per-model auth hook's answer — `options.apiKey` (presence, not truthiness: an empty string
150
- * is a present credential that fails closed at emit — no key header, no fallback to the
151
- * deployment's) and/or a credential header ({@link hasAuthCarrier}) in `options.headers` (a
164
+ * 1. the per-model auth hook's answer — `options.apiKey` (presence, not truthiness: a blank key is
165
+ * the keyless door, {@link keyCarriedBy} — it keeps this rank, so no key header goes out and the
166
+ * deployment's never rides in its place) and/or a credential header ({@link hasAuthCarrier}) in `options.headers` (a
152
167
  * gateway's own `Helicone-Auth` beside the key, or the key spelled as a header — not both: an `apiKey`
153
168
  * beside a header of the very name the lane writes the key in (`keyHeader`) is resolved all the same, with
154
169
  * that conflict recorded beside it for the law to refuse). The bag MUST be
@@ -161,7 +176,10 @@ export declare function __resetCredentialOriginBindings(): void;
161
176
  * documented gateway dual-auth shape, both riding as they always have; the pairing gate judges
162
177
  * the pair as one deployment credential),
163
178
  * 4. absent.
164
- * 1–2 are `per-model`; 3 is `deployment-config`. A per-model credential that carries a secret leaves
179
+ * 1–2 are `per-model`; 3 is `deployment-config`. The rank is the source's presence; the returned credential is what of
180
+ * it rides: a blank key ({@link keyCarriedBy}) is no `apiKey` and a bag whose credential headers are all blank is no
181
+ * `headersBorne` — the keyless door, at that rank (`{ source: "per-model" }` carries nothing, and no lower source
182
+ * rides in its place). A per-model credential that carries a secret leaves
165
183
  * here with its identity beside it (a digest, held by this module and never a member of the returned
166
184
  * object), which {@link adjudicateModelRoute} reads against the origin table and {@link admitRouteRequest}
167
185
  * binds when its request is sent. Resolution does not judge the route: what it found — an identity, a key beside
@@ -180,6 +198,10 @@ export declare function resolveRouteCredential(input: {
180
198
  * conflict is recorded and none is refused. */
181
199
  keyHeader?: string;
182
200
  }): RouteCredential;
201
+ /** The no-credential exit of a credential-origin refusal, in the one wording its fix hint and the run's announcement share.
202
+ * An empty `apiKey` is a per-model answer with no secret, so it binds nothing and never falls back to the brain's own key or
203
+ * root; leaving the answer out reaches the same place only where the brain has neither. A placeholder word is a credential. */
204
+ export declare const KEYLESS_EXIT = "hand it none \u2014 answer an empty apiKey and no credential header (this works under any brain; a brain configured with neither a baseUrl nor a credential of its own also accepts no apiKey at all), because a placeholder word handed in its place is still a credential and binds like any other";
183
205
  /**
184
206
  * The pairing law (module note above). A READ: it judges against the engine's credential-origin table and writes
185
207
  * nothing, so a pre-flight, the read face ({@link routePairingStatus}) and any consumer may call it freely — same
@@ -187,9 +209,9 @@ export declare function resolveRouteCredential(input: {
187
209
  * its own header is refused first (`route.credential_answer_conflict`, both header names in the fix — wherever the
188
210
  * request goes, since the request itself is contradictory); otherwise it is judged against the origin it is bound to
189
211
  * (refused when that is another one); one not bound yet, or built by hand (no resolution facts — the published corpus
190
- * is such input), is servable. Every refusal is a verdict: the law throws on garbage alone. The table is written by one
191
- * seat only: a first-party brain's request gate ({@link admitRouteRequest}), when the engine commits the request to be
192
- * sent. The verdict reports nothing either: the request gate's refusal is {@link routeRefusalError}.
212
+ * is such input), is servable. Every refusal is a verdict: the law throws on garbage alone. The table is written by a first-party brain's request gate ({@link admitRouteRequest}), when the engine commits the request to be sent, and by the
213
+ * host's explicit rebind ({@link rebindCredentialOrigin}) — never by a judgment. The verdict reports nothing either: the
214
+ * request gate's refusal is {@link routeRefusalError}.
193
215
  */
194
216
  export declare function adjudicateModelRoute(model: Pick<Model, "id" | "baseUrl">, credential: RouteCredential, config: RoutePairingConfig): RouteAdjudication;
195
217
  /** Render a refusal as the one-line detail text the brains put in their thrown error (the machine
@@ -205,7 +227,9 @@ export declare function routeRefusalError(verdict: Extract<RouteAdjudication, {
205
227
  ok: false;
206
228
  }>): BrainError;
207
229
  /**
208
- * THE request gate of a first-party brain — the one seat that writes the credential-origin table. Judged while the
230
+ * THE request gate of a first-party brain — the seat that binds a credential where it is first SENT (the table's other
231
+ * writer is the host's explicit rebind, {@link rebindCredentialOrigin}, which sets a credential's origin by the host's
232
+ * word). Judged while the
209
233
  * request is built ({@link adjudicateModelRoute}, the same law the pre-flight and the read face read): a refusal is
210
234
  * thrown here ({@link routeRefusalError}) before the body is built, and binds nothing — every refusal the law rules,
211
235
  * a key beside its own header included, leaves as that one error (`<code>: <fix>`); the gate rules nothing of its
@@ -215,7 +239,7 @@ export declare function routeRefusalError(verdict: Extract<RouteAdjudication, {
215
239
  * synchronous step; refused (the credential went out to another origin since the build — caller code runs while a body
216
240
  * is built), the same refusal is thrown there, before anything is sent. A request built speculatively and declined (the
217
241
  * context-overflow recovery's candidate), or one whose build fails after the gate, never reaches its admission and binds
218
- * nothing. A credential is bound to the origin it was first SENT to, never to one it was only judged for. The request's
242
+ * nothing. A request binds a credential to the origin it is SENT to, never to one it was only judged for. The request's
219
243
  * halves (the entry's id and root, the brain's root and lane default) are read ONCE, here: both judgments and the binding
220
244
  * are of the request this build is sending, whatever the caller's objects say by the time it is committed.
221
245
  *
@@ -226,6 +250,46 @@ export declare function routeRefusalError(verdict: Extract<RouteAdjudication, {
226
250
  * first-party brain throws for the same request. {@link adjudicateModelRoute} stays the read: it judges and binds nothing.
227
251
  */
228
252
  export declare function admitRouteRequest(model: Pick<Model, "id" | "baseUrl">, credential: RouteCredential, config: RoutePairingConfig): () => void;
253
+ /** What {@link rebindCredentialOrigin} did: the origin the credential is bound to now, the other origins it was bound to
254
+ * before (both in display spelling — never a credential or a digest of one), and whether the table changed. */
255
+ export interface CredentialRebind {
256
+ readonly origin: string;
257
+ /** The origins one of the credential's secrets was bound to before, other than {@link CredentialRebind.origin}, each
258
+ * once; empty when none was bound elsewhere. */
259
+ readonly previous: readonly string[];
260
+ /** `false` ⇒ every secret the credential carries was already bound to `origin`: nothing was written, nothing announced. */
261
+ readonly changed: boolean;
262
+ }
263
+ /**
264
+ * The host's explicit rebind — the one way a per-model credential's binding MOVES inside a process. The credential is
265
+ * resolved here, from the entry and the per-model hook's answer for it, by the request's own resolution
266
+ * ({@link resolveRouteCredential}: the answer's key and credential headers when it answers one, else the entry's own
267
+ * credential headers — never the brain's deployment credential), so the secrets bound are the ones that request carries,
268
+ * read off the bags once. Every one of them is bound to the origin the entry's request goes to, read as a first-party
269
+ * brain reads it: its root through the brains' own root judge ({@link resolveRequestRootOf} — the entry's root, else the
270
+ * brain's declared root, else the lane default) and its origin as the request gate folds it. From then on a request
271
+ * carrying that credential to any other origin is refused, whichever entry it rides: a credential has one root, so an
272
+ * entry still pointing at the old host is refused as well. A request the gate judged before the rebind and commits after
273
+ * it is judged again at its commit and refused there. Nothing else moves a binding: a request, a catalog swap or an
274
+ * entry's own members never do, and a restart empties the table.
275
+ *
276
+ * Hand the entry as it is in force now and the hook's answer the request will get: the target is that entry's origin
277
+ * today, so a call made from a stale copy rebinds to a stale host. A hook that answers a new value on every call has
278
+ * nothing to rebind (each value binds where it is first sent). A call that changed the table announces
279
+ * `route.credential_rebound` (operator) once, to `onNotice` (else the notice throat's `console.warn` arm), naming the
280
+ * entry, the new origin and the previous ones — announced just before the write, so a console that throws there leaves the
281
+ * table as it was; a call that found every secret already there writes and announces nothing. What the call did is also
282
+ * its return value — the notice is the engine's account of its table, the record of
283
+ * who asked is the host's. Refused, with nothing written (`config.invalid_argument`), two arms: no secret of the entry's
284
+ * own to bind (no per-model credential — the deployment credential's one root is its brain's declared root, so it has no
285
+ * binding to move — or an answer through the keyless door), and an entry whose request has no servable root (the lane
286
+ * default the host hands is judged like the entry's and the brain's roots). A non-string
287
+ * id, URL half or key throws a `TypeError`, as for every caller of the law.
288
+ */
289
+ export declare function rebindCredentialOrigin(model: Pick<Model, "id" | "baseUrl" | "headers">, perModelAuth: {
290
+ apiKey?: string;
291
+ headers?: Record<string, string>;
292
+ } | undefined, config: RoutePairingConfig, onNotice?: (notice: EngineNotice) => void): CredentialRebind;
229
293
  /**
230
294
  * Enforce "the resolved credential is the request's ONLY credential" on an already-merged header
231
295
  * bag — one source's credential rides, the other sources' credential headers do not:
@@ -240,10 +304,12 @@ export declare function admitRouteRequest(model: Pick<Model, "id" | "baseUrl">,
240
304
  * would have let win. A credential header from any OTHER bag (the entry's under a hook answer, the
241
305
  * deployment's under either) never rides beside a per-model credential. Whether a header is stripped
242
306
  * is decided by its SOURCE, not its name.
243
- * - DEPLOYMENT-CONFIG winner → untouched. A header-only config keeps its own spelling, and a config
244
- * carrying BOTH the apiKey knob and an auth header is the documented gateway dual-auth shape — the
245
- * knob's lock write plus the surviving header, both on the wire.
246
- * - absent → untouched (no carriers exist).
307
+ * - DEPLOYMENT-CONFIG winner → its own headers kept. A header-only config keeps its own spelling, and a
308
+ * config carrying BOTH the apiKey knob and an auth header is the documented gateway dual-auth shape —
309
+ * the knob's lock write plus the surviving header, both on the wire.
310
+ * - absent → nothing to strip (no carriers exist).
311
+ * Whatever the source, a credential header whose value is blank ({@link isBlankCredential}) is no credential and does
312
+ * not ride — the header half of the keyless door the blank key is ({@link keyCarriedBy}).
247
313
  */
248
314
  export declare function applyRouteCredentialHeaders(merged: Record<string, string>, credential: RouteCredential): void;
249
315
  /** A brain's construction config, received ONCE by the engine's receipt law for caller objects
@@ -2,9 +2,12 @@ import { createHash } from "node:crypto";
2
2
  import { BrainError } from "./errors.js";
3
3
  import { reportCredentialOriginRefusal } from "./status-sink.js";
4
4
  import { receiptRefusal, receiveOwnProperties } from "../core/own-property-receipt.js";
5
- import { credentialHeaderValues, holdOwnCredentialValues, isCredentialHeaderName, isSchemedCredentialHeader } from "../core/secret-env.js";
5
+ import { credentialHeaderValues, holdOwnCredentialValues, isBlankCredential, isCredentialHeaderName, isSchemedCredentialHeader } from "../core/secret-env.js";
6
+ import { deliverEngineNotice } from "../core/engine-notice.js";
7
+ import { uuidv7 } from "../engine/session/uuid.js";
8
+ import { REDACTION_MARKS } from "../core/redaction-marks.js";
6
9
  const REDACTED_VALUE = "«redacted»";
7
- const REDACTED_CREDENTIALS = "[redacted-credentials]";
10
+ const REDACTED_CREDENTIALS = REDACTION_MARKS.credentials;
8
11
  function servableParse(raw) {
9
12
  let u;
10
13
  try {
@@ -195,6 +198,9 @@ export function hasAuthCarrier(headers) {
195
198
  return false;
196
199
  return Object.keys(headers).some((name) => isCredentialHeaderName(name));
197
200
  }
201
+ function credentialHeadersCarried(headers) {
202
+ return Object.entries(headers ?? {}).some(([name, value]) => isCredentialHeaderName(name) && typeof value === "string" && !isBlankCredential(value));
203
+ }
198
204
  function routeOriginOf(rootKey) {
199
205
  if (rootKey === "")
200
206
  return "";
@@ -217,18 +223,19 @@ export function __resetCredentialOriginBindings() {
217
223
  const resolvedCredentialFacts = new WeakMap();
218
224
  const HEADER_VALUE_ENDS = /^[\t\n\r ]+|[\t\n\r ]+$/g;
219
225
  const AUTH_SCHEME_CREDENTIALS = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+[\t ]+(\S[\s\S]*)$/;
220
- function perModelCredential(credential, apiKey, bag, conflict) {
226
+ function perModelCredential(base, apiKey, bag, conflict) {
221
227
  const headers = {};
222
- for (const [name, value] of Object.entries(bag ?? {})) {
228
+ for (const [name, value] of Object.entries(bag?.headers ?? {})) {
223
229
  if (isCredentialHeaderName(name) && typeof value === "string")
224
230
  headers[name] = value;
225
231
  }
232
+ const credential = bag !== undefined && Object.values(headers).some((value) => !isBlankCredential(value)) ? { ...base, headersBorne: true, carrierBag: bag.from } : base;
226
233
  const headerValues = Object.entries(headers).map(([name, value]) => {
227
234
  const wire = value.replace(HEADER_VALUE_ENDS, "");
228
235
  return isSchemedCredentialHeader(name) ? (AUTH_SCHEME_CREDENTIALS.exec(wire)?.[1] ?? wire) : wire;
229
236
  });
230
237
  const values = apiKey !== undefined ? [apiKey, ...headerValues] : headerValues;
231
- const secrets = [...new Set(values.map((v) => v.replace(HEADER_VALUE_ENDS, "")).filter((v) => v !== ""))];
238
+ const secrets = [...new Set(values.map((v) => v.replace(HEADER_VALUE_ENDS, "")).filter((v) => !isBlankCredential(v)))];
232
239
  if (secrets.length === 0 && Object.keys(headers).length === 0 && conflict === undefined)
233
240
  return credential;
234
241
  const proof = Object.freeze(credential);
@@ -261,8 +268,11 @@ function routeHalves(model, config) {
261
268
  const deploymentRoot = declared || routeKeyOf(config.laneDefault);
262
269
  return { entry, declared, deploymentRoot, request: entry || deploymentRoot };
263
270
  }
271
+ export function keyCarriedBy(apiKey) {
272
+ return apiKey !== undefined && !isBlankCredential(apiKey) ? apiKey : undefined;
273
+ }
264
274
  function keyHeaderConflict(apiKey, headers, keyHeader) {
265
- if (apiKey === undefined || apiKey === "" || keyHeader === undefined || headers === undefined)
275
+ if (apiKey === undefined || keyHeader === undefined || headers === undefined)
266
276
  return undefined;
267
277
  const fold = keyHeader.toLowerCase();
268
278
  const written = Object.keys(headers).find((name) => name.toLowerCase() === fold);
@@ -275,27 +285,26 @@ export function resolveRouteCredential(input) {
275
285
  if (optionsApiKey !== undefined || answerHeadersBorne) {
276
286
  if (optionsApiKey !== undefined && typeof optionsApiKey !== "string")
277
287
  throw new TypeError(`route pairing: apiKey must be a string (got ${typeof optionsApiKey})`);
278
- return perModelCredential({
279
- source: "per-model",
280
- ...(optionsApiKey !== undefined ? { apiKey: optionsApiKey } : {}),
281
- ...(answerHeadersBorne ? { headersBorne: true, carrierBag: "options" } : {}),
282
- }, optionsApiKey, answerHeadersBorne ? optionsHeaders : undefined, keyHeaderConflict(optionsApiKey, optionsHeaders, keyHeader));
288
+ const key = keyCarriedBy(optionsApiKey);
289
+ return perModelCredential({ source: "per-model", ...(key !== undefined ? { apiKey: key } : {}) }, key, answerHeadersBorne ? { from: "options", headers: optionsHeaders } : undefined, keyHeaderConflict(key, optionsHeaders, keyHeader));
283
290
  }
284
291
  if (hasAuthCarrier(modelHeaders))
285
- return perModelCredential({ source: "per-model", headersBorne: true, carrierBag: "model" }, undefined, modelHeaders);
292
+ return perModelCredential({ source: "per-model" }, undefined, { from: "model", headers: modelHeaders });
286
293
  const configHeadersBorne = hasAuthCarrier(configHeaders);
287
294
  if (configApiKey !== undefined || configHeadersBorne) {
288
295
  if (configApiKey !== undefined && typeof configApiKey !== "string") {
289
296
  throw new TypeError(`route pairing: apiKey must be a string (got ${typeof configApiKey})`);
290
297
  }
298
+ const key = keyCarriedBy(configApiKey);
291
299
  return {
292
300
  source: "deployment-config",
293
- ...(configApiKey !== undefined ? { apiKey: configApiKey } : {}),
294
- ...(configHeadersBorne ? { headersBorne: true, carrierBag: "config" } : {}),
301
+ ...(key !== undefined ? { apiKey: key } : {}),
302
+ ...(credentialHeadersCarried(configHeaders) ? { headersBorne: true, carrierBag: "config" } : {}),
295
303
  };
296
304
  }
297
305
  return { source: "absent" };
298
306
  }
307
+ export const KEYLESS_EXIT = "hand it none — answer an empty apiKey and no credential header (this works under any brain; a brain configured with neither a baseUrl nor a credential of its own also accepts no apiKey at all), because a placeholder word handed in its place is still a credential and binds like any other";
299
308
  export function adjudicateModelRoute(model, credential, config) {
300
309
  const { entry, declared, deploymentRoot, request } = routeHalves(model, config);
301
310
  const entryShown = displayUrlOf(entry);
@@ -338,9 +347,12 @@ export function adjudicateModelRoute(model, credential, config) {
338
347
  boundOrigin: boundShown,
339
348
  requestOrigin: requestOriginShown,
340
349
  fixHint: `model "${model.id}" targets ${requestShown} (origin ${requestOriginShown}) but its own credential is bound to ${boundShown}, ` +
341
- `the origin it was first sent to — a credential does not follow its entry to another host: change the entry's credential ` +
342
- `reference in the same step as its baseUrl (a new credential is a new binding), or point the entry back at ${boundShown}; ` +
343
- `a binding lasts as long as the engine process, so a provider that only moved domains and accepts the same credential there needs a restart`,
350
+ `the origin it was first sent to or the host rebound it to — a credential does not follow its entry to another host: change ` +
351
+ `the entry's credential reference in the same step as its baseUrl (a new credential is a new binding), or point the entry ` +
352
+ `back at ${boundShown}; ` +
353
+ `if the endpoint takes no credential, ${KEYLESS_EXIT}; ` +
354
+ `a provider that only moved domains and accepts the same credential there needs the host's ` +
355
+ `explicit rebind (rebindCredentialOrigin) where the host offers one, otherwise an engine restart`,
344
356
  },
345
357
  };
346
358
  }
@@ -412,14 +424,69 @@ export function admitRouteRequest(model, credential, config) {
412
424
  bindCredentialOrigin(identities, requestOrigin);
413
425
  };
414
426
  }
427
+ function rebindRefusal(modelId, why) {
428
+ return Object.assign(new Error(`rebindCredentialOrigin: model "${modelId}" — ${why}; nothing was rebound`), { code: "config.invalid_argument" });
429
+ }
430
+ export function rebindCredentialOrigin(model, perModelAuth, config, onNotice) {
431
+ const judged = { id: model.id, baseUrl: model.baseUrl };
432
+ if (typeof judged.id !== "string")
433
+ throw new TypeError(`rebindCredentialOrigin: model.id must be a string (got ${typeof judged.id})`);
434
+ const givenModelHeaders = model.headers;
435
+ const givenAnswerHeaders = perModelAuth?.headers;
436
+ const answerKey = perModelAuth?.apiKey;
437
+ const modelHeaders = givenModelHeaders === undefined ? undefined : { ...givenModelHeaders };
438
+ const answerHeaders = givenAnswerHeaders === undefined ? undefined : { ...givenAnswerHeaders };
439
+ const { baseUrl, laneDefault } = config;
440
+ const pairing = { ...(baseUrl !== undefined ? { baseUrl } : {}), ...(laneDefault !== undefined ? { laneDefault } : {}) };
441
+ const request = routeHalves(judged, pairing).request;
442
+ let root;
443
+ try {
444
+ const chosen = resolveRequestRootOf(judged.baseUrl, pairing.baseUrl, pairing.laneDefault);
445
+ root = chosen.root;
446
+ if (chosen.origin === "lane-default" && root !== "")
447
+ judgeRequestRoot(pairing.laneDefault, "config.laneDefault");
448
+ }
449
+ catch (e) {
450
+ if (e instanceof BrainError)
451
+ throw rebindRefusal(judged.id, e.message.replace(/^\[[a-z_]+\] /, ""));
452
+ throw e;
453
+ }
454
+ if (root === "")
455
+ throw rebindRefusal(judged.id, "it targets no root (the entry's baseUrl and the brain's root are both unset)");
456
+ const identities = resolvedCredentialFacts.get(resolveRouteCredential({ optionsApiKey: answerKey, optionsHeaders: answerHeaders, modelHeaders }))?.identities ?? [];
457
+ if (identities.length === 0) {
458
+ throw rebindRefusal(judged.id, "neither the hook's answer nor the entry carries a secret of its own (no per-model credential, or the keyless door) — only a per-model credential is bound to an origin");
459
+ }
460
+ const origin = routeOriginOf(request);
461
+ const table = credentialOriginTable();
462
+ const before = identities.map((id) => table.get(id));
463
+ const changed = before.some((bound) => bound !== origin);
464
+ const previous = [...new Set(before.filter((bound) => bound !== undefined && bound !== origin))].map(displayUrlOf);
465
+ const outcome = Object.freeze({ origin: displayUrlOf(origin), previous: Object.freeze(previous), changed });
466
+ if (!changed)
467
+ return outcome;
468
+ deliverEngineNotice(onNotice, {
469
+ code: "route.credential_rebound",
470
+ message: `The host rebound the credential of model "${judged.id}" to ${outcome.origin}` +
471
+ `${previous.length > 0 ? ` (it was bound to ${previous.join(", ")})` : ""}: a request carrying it is sent to ${outcome.origin} only — ` +
472
+ `any other entry that carries the same credential and still targets another host is refused.`,
473
+ detail: { modelId: judged.id, origin: outcome.origin, previous: [...previous], occurrenceId: uuidv7() },
474
+ });
475
+ bindCredentialOrigin(identities, origin);
476
+ return outcome;
477
+ }
415
478
  export function applyRouteCredentialHeaders(merged, credential) {
416
- if (credential.source !== "per-model")
417
- return;
418
- for (const k of Object.keys(merged)) {
419
- if (isCredentialHeaderName(k))
479
+ if (credential.source === "per-model") {
480
+ for (const k of Object.keys(merged)) {
481
+ if (isCredentialHeaderName(k))
482
+ delete merged[k];
483
+ }
484
+ Object.assign(merged, resolvedCredentialFacts.get(credential)?.headers);
485
+ }
486
+ for (const [k, value] of Object.entries(merged)) {
487
+ if (isCredentialHeaderName(k) && isBlankCredential(value))
420
488
  delete merged[k];
421
489
  }
422
- Object.assign(merged, resolvedCredentialFacts.get(credential)?.headers);
423
490
  }
424
491
  export function brainConfigSnapshot(given, subject) {
425
492
  const words = { subject, unit: "member", moment: "at construction" };
@@ -25,7 +25,7 @@ export const ROUTE_ADJUDICATION_CONFORMANCE_CORPUS = [
25
25
  },
26
26
  {
27
27
  name: "per-model-empty-string-key",
28
- intent: "an empty-string per-model key is a PRESENT credential (fails closed at emit, never falls to the deployment key)",
28
+ intent: "an empty-string per-model key is the keyless door: it keeps the per-model rank (never falls to the deployment key) and no key header is written for it",
29
29
  model: { id: "m-degraded", baseUrl: "https://third-party.example.net" },
30
30
  credential: { source: "per-model", apiKey: "" },
31
31
  config: { baseUrl: "https://gw.example.com" },
@@ -255,6 +255,14 @@ async function sleepAnnouncingRetry(totalMs, signal, frame) {
255
255
  return;
256
256
  }
257
257
  }
258
+ function suspendedFailure(wait, sleptMs) {
259
+ return {
260
+ kind: "suspended",
261
+ wait,
262
+ sleptMs,
263
+ err: new BrainError("network", `the host was suspended for ${Math.round(sleptMs / 1000)}s during the ${wait} wait; the connection it was waiting on was abandoned`, undefined, { apiError: true }),
264
+ };
265
+ }
258
266
  const RETRY_PHASE_OF_ERR_CLASS = {
259
267
  connect_refused: "reconnecting",
260
268
  transport: "reconnecting",
@@ -267,6 +275,9 @@ const RETRY_PHASE_OF_ERR_CLASS = {
267
275
  Object.freeze(RETRY_PHASE_OF_ERR_CLASS);
268
276
  const TRANSPORT_RETRY_DETAIL = "connection lost, reconnecting";
269
277
  function retryAnnouncement(failure) {
278
+ if (failure.kind === "suspended") {
279
+ return { errClass: "stall", detail: `the host was suspended for ${Math.round(failure.sleptMs / 1000)}s during the ${failure.wait} wait, reconnecting on a fresh connection`, sleptMs: failure.sleptMs };
280
+ }
270
281
  if (failure.kind !== "stalled")
271
282
  return { errClass: "transport", detail: TRANSPORT_RETRY_DETAIL };
272
283
  const knob = failure.allowanceMs !== undefined && failure.allowanceMs > 0
@@ -326,7 +337,7 @@ export function runStreamingBrain(args) {
326
337
  if (failure.code !== undefined) {
327
338
  if (failure.errorKind !== undefined)
328
339
  errorMsg.errorKind = failure.errorKind;
329
- else if (failure.inputTooLongRuledOut === true)
340
+ if (failure.inputTooLongRuledOut === true)
330
341
  errorMsg.inputTooLongRuledOut = true;
331
342
  if (readMember(err, "errorBodyIncomplete") === true)
332
343
  errorMsg.errorBodyIncomplete = true;
@@ -396,7 +407,7 @@ export function runStreamingBrain(args) {
396
407
  const firstTokenTimeoutMs = resolveWatchdogMs(config.firstTokenTimeoutMs, stallTimeouts?.firstTokenMs, STALL_FIRST_TOKEN_MS, "firstTokenTimeoutMs");
397
408
  const idleTimeoutMs = resolveWatchdogMs(config.idleTimeoutMs, stallTimeouts?.idleMs, STALL_IDLE_MS, "idleTimeoutMs");
398
409
  const firstByteRetryBudget = resolveFirstByteRetries(config.firstByteRetries);
399
- const armWaitDisclosure = (ceilingMs) => {
410
+ const armWaitDisclosure = (ceilingMs, waitSegment) => {
400
411
  if (!(ceilingMs >= WAITING_FIRST_TOKEN_AFTER_MS))
401
412
  return { stop: () => undefined, expire: () => undefined };
402
413
  const startedAt = Date.now();
@@ -407,7 +418,7 @@ export function runStreamingBrain(args) {
407
418
  const disclose = () => {
408
419
  disclosed = true;
409
420
  announcedWait = true;
410
- emitWaitFrame({ phase: "waiting_first_token", detail: "waiting for the first token", elapsedMs: Date.now() - startedAt, timeoutMs: ceilingMs });
421
+ emitWaitFrame({ phase: "waiting_first_token", detail: "waiting for the first token", elapsedMs: Date.now() - startedAt, timeoutMs: ceilingMs, waitSegment });
411
422
  };
412
423
  const schedule = (delayMs) => {
413
424
  timer = setTimeout(() => {
@@ -434,6 +445,20 @@ export function runStreamingBrain(args) {
434
445
  },
435
446
  };
436
447
  };
448
+ const waitAnnouncingRetry = async (announcement, lane) => {
449
+ emitBrainTelemetry({ kind: "retry", attempt: lane.attempt, phase: lane.phase, errClass: announcement.errClass, nextDelayMs: lane.delayMs });
450
+ announcedRetry = true;
451
+ await sleepAnnouncingRetry(lane.delayMs, signal, (remainingMs) => ({
452
+ phase: RETRY_PHASE_OF_ERR_CLASS[announcement.errClass],
453
+ detail: announcement.detail,
454
+ retryInSec: Math.ceil(remainingMs / 1000),
455
+ retryInMs: remainingMs,
456
+ attempt: lane.attempt,
457
+ maxRetries: lane.maxRetries,
458
+ errClass: announcement.errClass,
459
+ ...(announcement.sleptMs !== undefined ? { sleptMs: announcement.sleptMs } : {}),
460
+ }));
461
+ };
437
462
  let attempt = 0;
438
463
  let thinkingRetries = 0;
439
464
  let firstByteStalls = 0;
@@ -449,11 +474,12 @@ export function runStreamingBrain(args) {
449
474
  throw e;
450
475
  }
451
476
  const window = firstByteWindow(firstByteTimeoutMs, Buffer.byteLength(req.body), firstByteStalls);
452
- const headerWait = armWaitDisclosure(window.windowMs);
477
+ const headerWait = armWaitDisclosure(window.windowMs, "response_headers");
453
478
  const cc = createAttemptController(window.windowMs, signal);
454
479
  let r;
455
480
  let netErr;
456
481
  let firstByteStall;
482
+ let suspendedAtHeaders;
457
483
  requestIdSeen = undefined;
458
484
  attemptPartial = undefined;
459
485
  attemptOutput = undefined;
@@ -477,11 +503,20 @@ export function runStreamingBrain(args) {
477
503
  requestIdSeen = undefined;
478
504
  firstByteStall = stalledAtFirstByte();
479
505
  }
506
+ else if (cc.suspendedMs() !== undefined) {
507
+ discardResponseBody(r);
508
+ r = undefined;
509
+ requestIdSeen = undefined;
510
+ suspendedAtHeaders = suspendedFailure("response-header", cc.suspendedMs());
511
+ }
480
512
  }
481
513
  catch (e) {
482
514
  if (cc.timedOut()) {
483
515
  firstByteStall = stalledAtFirstByte();
484
516
  }
517
+ else if (cc.suspendedMs() !== undefined && !signal?.aborted) {
518
+ suspendedAtHeaders = suspendedFailure("response-header", cc.suspendedMs());
519
+ }
485
520
  else if (isAbortError(e) || signal?.aborted) {
486
521
  cc.dispose();
487
522
  throw e;
@@ -515,25 +550,24 @@ export function runStreamingBrain(args) {
515
550
  }
516
551
  cc.clearTimer();
517
552
  try {
553
+ if (suspendedAtHeaders !== undefined) {
554
+ if (attempt >= maxRetries)
555
+ throw suspendedAtHeaders.err;
556
+ const delayMs = retryBackoffMs(baseDelay, attempt);
557
+ attempt++;
558
+ cc.abort();
559
+ cc.dispose();
560
+ await waitAnnouncingRetry(retryAnnouncement(suspendedAtHeaders), { phase: "connect", attempt, maxRetries, delayMs });
561
+ continue;
562
+ }
518
563
  if (firstByteStall !== undefined) {
519
564
  if (firstByteStalls >= firstByteRetryBudget)
520
565
  throw firstByteStall.err;
521
566
  firstByteStalls++;
522
- const announcement = retryAnnouncement(firstByteStall);
523
567
  const delayMs = retryBackoffMs(baseDelay, firstByteStalls - 1);
524
- emitBrainTelemetry({ kind: "retry", attempt: firstByteStalls, phase: "connect", errClass: announcement.errClass, nextDelayMs: delayMs });
525
- announcedRetry = true;
526
568
  cc.abort();
527
569
  cc.dispose();
528
- await sleepAnnouncingRetry(delayMs, signal, (remainingMs) => ({
529
- phase: RETRY_PHASE_OF_ERR_CLASS[announcement.errClass],
530
- detail: announcement.detail,
531
- retryInSec: Math.ceil(remainingMs / 1000),
532
- retryInMs: remainingMs,
533
- attempt: firstByteStalls,
534
- maxRetries: firstByteRetryBudget,
535
- errClass: announcement.errClass,
536
- }));
570
+ await waitAnnouncingRetry(retryAnnouncement(firstByteStall), { phase: "connect", attempt: firstByteStalls, maxRetries: firstByteRetryBudget, delayMs });
537
571
  continue;
538
572
  }
539
573
  let errorBody;
@@ -661,6 +695,7 @@ export function runStreamingBrain(args) {
661
695
  throw new BrainError(classifyHttp(status), `${httpLabel} HTTP ${status || "ERR"}: ${detail.slice(0, 500)}${overflowDeclineNote}`, status, {
662
696
  apiError: true,
663
697
  ...(itl === "yes" ? { inputTooLong: true } : itl === "no" ? { inputTooLongRuledOut: true } : {}),
698
+ ...(terminalVerdict?.imageUnprocessable === true ? { imageUnprocessable: true } : {}),
664
699
  ...(providerCode !== undefined ? { providerCode } : {}),
665
700
  ...(terminalVerdict !== undefined ? { verdict: { condition: terminalVerdict.condition, source: terminalVerdict.source, ...(terminalVerdict.resetAtMs !== undefined ? { resetAtMs: terminalVerdict.resetAtMs } : {}) } } : {}),
666
701
  ...(errorBody !== undefined && !errorBody.endedNormally ? { errorBodyIncomplete: true } : {}),
@@ -684,9 +719,19 @@ export function runStreamingBrain(args) {
684
719
  let firedFirstTokenDeadlineMs;
685
720
  let ftTimer;
686
721
  let firstTokenWait = { stop: () => undefined, expire: () => undefined };
722
+ const streamSuspend = connect.suspend;
723
+ let suspendedInStream;
724
+ const cutOnSuspend = (wait) => (sleptMs) => {
725
+ suspendedInStream = suspendedFailure(wait, sleptMs);
726
+ void reader.cancel().catch(() => undefined);
727
+ };
687
728
  if (firstTokenTimeoutMs && firstTokenTimeoutMs > 0) {
688
- firstTokenWait = armWaitDisclosure(firstTokenTimeoutMs);
729
+ firstTokenWait = armWaitDisclosure(firstTokenTimeoutMs, "first_token");
730
+ streamSuspend.arm(firstTokenTimeoutMs, cutOnSuspend("first-token"));
689
731
  ftTimer = setTimeout(() => {
732
+ if (streamSuspend.check())
733
+ return;
734
+ streamSuspend.disarm();
690
735
  firedFirstTokenDeadlineMs = firstTokenTimeoutMs;
691
736
  firstTokenWait.expire();
692
737
  void reader.cancel().catch(() => undefined);
@@ -698,25 +743,32 @@ export function runStreamingBrain(args) {
698
743
  if (!idleTimeoutMs || idleTimeoutMs <= 0)
699
744
  return;
700
745
  firedIdleDeadlineMs = undefined;
746
+ suspendedInStream = undefined;
701
747
  if (idleTimer)
702
748
  clearTimeout(idleTimer);
749
+ streamSuspend.arm(idleTimeoutMs, cutOnSuspend("stream idle"));
703
750
  idleTimer = setTimeout(() => {
751
+ if (streamSuspend.check())
752
+ return;
753
+ streamSuspend.disarm();
704
754
  firedIdleDeadlineMs = idleTimeoutMs;
705
755
  void reader.cancel().catch(() => undefined);
706
756
  }, idleTimeoutMs);
707
757
  };
708
758
  const sawContentToken = () => {
709
- bumpIdle();
710
- if (firstTokenSeen)
711
- return;
712
- firstTokenSeen = true;
713
- firstTokenArrived = true;
714
- firedFirstTokenDeadlineMs = undefined;
715
- if (ftTimer) {
716
- clearTimeout(ftTimer);
717
- ftTimer = undefined;
759
+ if (!firstTokenSeen) {
760
+ firstTokenSeen = true;
761
+ firstTokenArrived = true;
762
+ firedFirstTokenDeadlineMs = undefined;
763
+ suspendedInStream = undefined;
764
+ if (ftTimer) {
765
+ clearTimeout(ftTimer);
766
+ ftTimer = undefined;
767
+ }
768
+ firstTokenWait.stop();
769
+ streamSuspend.disarm();
718
770
  }
719
- firstTokenWait.stop();
771
+ bumpIdle();
720
772
  };
721
773
  cleanup = () => {
722
774
  if (ftTimer) {
@@ -806,6 +858,9 @@ export function runStreamingBrain(args) {
806
858
  clearTimeout(idleTimer);
807
859
  idleTimer = undefined;
808
860
  }
861
+ streamSuspend.disarm();
862
+ if (!failure && suspendedInStream !== undefined)
863
+ failure = suspendedInStream;
809
864
  if (!failure && firedFirstTokenDeadlineMs !== undefined) {
810
865
  failure = {
811
866
  kind: "stalled",
@@ -855,34 +910,14 @@ export function runStreamingBrain(args) {
855
910
  thinkingRetries++;
856
911
  parser.sealForRetry();
857
912
  const delayMs = 100 * thinkingRetries;
858
- emitBrainTelemetry({ kind: "retry", attempt: thinkingRetries, phase: "midstream", errClass: announcement.errClass, nextDelayMs: delayMs });
859
- announcedRetry = true;
860
- await sleepAnnouncingRetry(delayMs, signal, (remainingMs) => ({
861
- phase: RETRY_PHASE_OF_ERR_CLASS[announcement.errClass],
862
- detail: announcement.detail,
863
- retryInSec: Math.ceil(remainingMs / 1000),
864
- retryInMs: remainingMs,
865
- attempt: thinkingRetries,
866
- maxRetries: THINKING_RETRY_BUDGET,
867
- errClass: announcement.errClass,
868
- }));
913
+ await waitAnnouncingRetry(announcement, { phase: "midstream", attempt: thinkingRetries, maxRetries: THINKING_RETRY_BUDGET, delayMs });
869
914
  continue;
870
915
  }
871
916
  if (attempt >= maxRetries)
872
917
  throw failure.err;
873
918
  const delayMs = retryBackoffMs(baseDelay, attempt);
874
919
  attempt++;
875
- emitBrainTelemetry({ kind: "retry", attempt, phase: "midstream", errClass: announcement.errClass, nextDelayMs: delayMs });
876
- announcedRetry = true;
877
- await sleepAnnouncingRetry(delayMs, signal, (remainingMs) => ({
878
- phase: RETRY_PHASE_OF_ERR_CLASS[announcement.errClass],
879
- detail: announcement.detail,
880
- retryInSec: Math.ceil(remainingMs / 1000),
881
- retryInMs: remainingMs,
882
- attempt,
883
- maxRetries,
884
- errClass: announcement.errClass,
885
- }));
920
+ await waitAnnouncingRetry(announcement, { phase: "midstream", attempt, maxRetries, delayMs });
886
921
  }
887
922
  }
888
923
  }