@sema-agent/core 7.58.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 (284) hide show
  1. package/CHANGELOG.md +776 -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.js +33 -34
  10. package/dist/brain/anthropic.js +161 -45
  11. package/dist/brain/errors.d.ts +9 -3
  12. package/dist/brain/errors.js +7 -1
  13. package/dist/brain/failover.js +2 -1
  14. package/dist/brain/open-responses.js +3 -3
  15. package/dist/brain/openai.js +103 -53
  16. package/dist/brain/provider-dialect.d.ts +11 -0
  17. package/dist/brain/provider-dialect.js +5 -2
  18. package/dist/brain/reasoning-request.js +5 -4
  19. package/dist/brain/reasoning.d.ts +19 -0
  20. package/dist/brain/reasoning.js +17 -2
  21. package/dist/brain/request-route.d.ts +4 -1
  22. package/dist/brain/request-route.js +4 -1
  23. package/dist/brain/route-adjudicator.d.ts +84 -18
  24. package/dist/brain/route-adjudicator.js +87 -21
  25. package/dist/brain/route-conformance.js +1 -1
  26. package/dist/brain/stream-engine.js +84 -49
  27. package/dist/brain/stream-shared.d.ts +30 -0
  28. package/dist/brain/stream-shared.js +34 -1
  29. package/dist/brain/timeout.d.ts +62 -5
  30. package/dist/brain/timeout.js +93 -6
  31. package/dist/core/account-row.d.ts +61 -0
  32. package/dist/core/account-row.js +51 -0
  33. package/dist/core/advisor-verdict.d.ts +2 -1
  34. package/dist/core/advisor-verdict.js +1 -1
  35. package/dist/core/allow-entry.d.ts +18 -6
  36. package/dist/core/allow-entry.js +16 -8
  37. package/dist/core/approval-object.d.ts +29 -15
  38. package/dist/core/approval-object.js +47 -19
  39. package/dist/core/auto-compaction.js +1 -1
  40. package/dist/core/background-agent-store.d.ts +16 -3
  41. package/dist/core/checkpoint-requirements.d.ts +13 -1
  42. package/dist/core/checkpoint-requirements.js +3 -1
  43. package/dist/core/checkpoint-store.d.ts +58 -12
  44. package/dist/core/checkpoint-store.js +18 -6
  45. package/dist/core/child-clamp-seats.d.ts +29 -0
  46. package/dist/core/child-clamp-seats.js +56 -1
  47. package/dist/core/compliance.d.ts +2 -2
  48. package/dist/core/compliance.js +1 -1
  49. package/dist/core/effective-path-target.d.ts +8 -2
  50. package/dist/core/effective-path-target.js +8 -3
  51. package/dist/core/engine-notice.d.ts +98 -8
  52. package/dist/core/engine-notice.js +19 -5
  53. package/dist/core/gate-fold.js +1 -1
  54. package/dist/core/gate-lanes.js +8 -4
  55. package/dist/core/gate-outcome.d.ts +32 -3
  56. package/dist/core/gate-outcome.js +19 -1
  57. package/dist/core/governance-codes.d.ts +9 -1
  58. package/dist/core/governance-codes.js +13 -0
  59. package/dist/core/hooks.d.ts +31 -3
  60. package/dist/core/hooks.js +5 -6
  61. package/dist/core/image-admission.d.ts +6 -5
  62. package/dist/core/image-admission.js +18 -14
  63. package/dist/core/locked-config.d.ts +5 -2
  64. package/dist/core/locked-config.js +2 -1
  65. package/dist/core/mailbox-store.d.ts +45 -1
  66. package/dist/core/mailbox-store.js +53 -9
  67. package/dist/core/mcp-failure.d.ts +114 -18
  68. package/dist/core/mcp-failure.js +63 -5
  69. package/dist/core/mcp-server-link.d.ts +22 -1
  70. package/dist/core/mcp-server-link.js +25 -1
  71. package/dist/core/mcp.d.ts +12 -8
  72. package/dist/core/mcp.js +42 -25
  73. package/dist/core/memory-engine/consolidation-driver.d.ts +2 -4
  74. package/dist/core/memory-engine/consolidation-driver.js +3 -3
  75. package/dist/core/memory-engine/consolidation.d.ts +4 -0
  76. package/dist/core/memory-engine/consolidation.js +1 -0
  77. package/dist/core/memory-engine/delegation-settlement.js +5 -12
  78. package/dist/core/memory-engine/distiller.js +2 -2
  79. package/dist/core/memory-engine/dual-root.d.ts +50 -1
  80. package/dist/core/memory-engine/dual-root.js +44 -1
  81. package/dist/core/memory-engine/engine.d.ts +67 -14
  82. package/dist/core/memory-engine/engine.js +384 -212
  83. package/dist/core/memory-engine/export-bundle.d.ts +23 -0
  84. package/dist/core/memory-engine/export-bundle.js +23 -4
  85. package/dist/core/memory-engine/file-backend.d.ts +128 -55
  86. package/dist/core/memory-engine/file-backend.js +290 -117
  87. package/dist/core/memory-engine/index.d.ts +1 -1
  88. package/dist/core/memory-engine/layout.d.ts +59 -11
  89. package/dist/core/memory-engine/layout.js +190 -40
  90. package/dist/core/memory-engine/memory-backend-contract.d.ts +1 -1
  91. package/dist/core/memory-engine/memory-backend-contract.js +39 -2
  92. package/dist/core/memory-engine/sync-client.d.ts +9 -1
  93. package/dist/core/memory-engine/sync-client.js +31 -8
  94. package/dist/core/memory-engine/sync.d.ts +5 -0
  95. package/dist/core/memory-engine/types.d.ts +6 -0
  96. package/dist/core/mods/classic-events.d.ts +5 -1
  97. package/dist/core/mods/kernel/dispatch.js +2 -1
  98. package/dist/core/mods/kernel/events.d.ts +2 -1
  99. package/dist/core/mods/kernel/events.js +2 -2
  100. package/dist/core/mods/kernel/registration.d.ts +4 -0
  101. package/dist/core/mods/kernel/registration.js +3 -0
  102. package/dist/core/mods/stations.d.ts +31 -10
  103. package/dist/core/mods/stations.js +44 -10
  104. package/dist/core/mods/tool-call.js +1 -1
  105. package/dist/core/parent-spec-seat.d.ts +8 -3
  106. package/dist/core/parent-spec-seat.js +2 -0
  107. package/dist/core/park-selfcheck.js +6 -0
  108. package/dist/core/peer-seat.d.ts +70 -8
  109. package/dist/core/peer-seat.js +143 -11
  110. package/dist/core/permission-rule-consent.js +10 -4
  111. package/dist/core/permission-rule-model.d.ts +16 -0
  112. package/dist/core/permission-rule-model.js +1 -1
  113. package/dist/core/present-plan-tool.d.ts +11 -3
  114. package/dist/core/present-plan-tool.js +2 -2
  115. package/dist/core/resume-startup-cause.js +1 -0
  116. package/dist/core/rewrite-rejudge.d.ts +1 -0
  117. package/dist/core/rewrite-rejudge.js +2 -2
  118. package/dist/core/roles.d.ts +34 -2
  119. package/dist/core/roles.js +43 -4
  120. package/dist/core/runner/announce-once-ledger.d.ts +5 -4
  121. package/dist/core/runner/announce-once-ledger.js +4 -2
  122. package/dist/core/runner/call-hook-stations.js +2 -2
  123. package/dist/core/runner/contracts.d.ts +20 -16
  124. package/dist/core/runner/credential-origin-seat.js +4 -3
  125. package/dist/core/runner/cwd-alignment-probe.d.ts +20 -0
  126. package/dist/core/runner/cwd-alignment-probe.js +21 -0
  127. package/dist/core/runner/decide-continuation.d.ts +2 -2
  128. package/dist/core/runner/gate-exit.d.ts +12 -4
  129. package/dist/core/runner/gate-exit.js +10 -7
  130. package/dist/core/runner/image-removed-seat.d.ts +12 -0
  131. package/dist/core/runner/image-removed-seat.js +19 -0
  132. package/dist/core/runner/inline-image.js +1 -1
  133. package/dist/core/runner/memory-consolidation-driver.js +3 -3
  134. package/dist/core/runner/park-commit.d.ts +1 -1
  135. package/dist/core/runner/park-commit.js +3 -0
  136. package/dist/core/runner/prepare-ask-lane.d.ts +1 -1
  137. package/dist/core/runner/prepare-ask-lane.js +2 -1
  138. package/dist/core/runner/prepare-boundary-parks.js +2 -2
  139. package/dist/core/runner/prepare-caps-and-workflow.d.ts +3 -5
  140. package/dist/core/runner/prepare-caps-and-workflow.js +2 -0
  141. package/dist/core/runner/prepare-config-doors.js +2 -0
  142. package/dist/core/runner/prepare-context-lane.js +2 -0
  143. package/dist/core/runner/prepare-delegation-surface.d.ts +4 -0
  144. package/dist/core/runner/prepare-delegation-surface.js +1 -0
  145. package/dist/core/runner/prepare-hands-readface.d.ts +4 -0
  146. package/dist/core/runner/prepare-hands-readface.js +5 -0
  147. package/dist/core/runner/prepare-inherited-gate.d.ts +1 -3
  148. package/dist/core/runner/prepare-inherited-gate.js +14 -27
  149. package/dist/core/runner/prepare-memory.js +10 -17
  150. package/dist/core/runner/prepare-park-ask.d.ts +1 -1
  151. package/dist/core/runner/prepare-park-ask.js +2 -1
  152. package/dist/core/runner/prepare-policy-chain.d.ts +3 -3
  153. package/dist/core/runner/prepare-policy-chain.js +16 -13
  154. package/dist/core/runner/prepare-project-context.d.ts +2 -2
  155. package/dist/core/runner/prepare-project-context.js +2 -2
  156. package/dist/core/runner/prepare-prompt-inputs.d.ts +1 -1
  157. package/dist/core/runner/prepare-prompt-inputs.js +8 -19
  158. package/dist/core/runner/prepare-protocol-tools.js +9 -1
  159. package/dist/core/runner/prepare-run-refs.d.ts +2 -3
  160. package/dist/core/runner/prepare-run-refs.js +4 -1
  161. package/dist/core/runner/prepare-task.js +4 -2
  162. package/dist/core/runner/prepare-wiring-manifest.d.ts +1 -1
  163. package/dist/core/runner/prepare-wiring-manifest.js +2 -1
  164. package/dist/core/runner/reply-pricing.d.ts +30 -0
  165. package/dist/core/runner/reply-pricing.js +19 -0
  166. package/dist/core/runner/resume-admission.js +4 -2
  167. package/dist/core/runner/resume-apply.js +6 -1
  168. package/dist/core/runner/resume-policy-outcome.js +5 -5
  169. package/dist/core/runner/role-seat-defaulted.d.ts +44 -0
  170. package/dist/core/runner/role-seat-defaulted.js +40 -0
  171. package/dist/core/runner/run-brain-sinks.js +2 -0
  172. package/dist/core/runner/run-identity-wiring.d.ts +2 -5
  173. package/dist/core/runner/run-identity-wiring.js +5 -4
  174. package/dist/core/runner/run-leg.d.ts +2 -0
  175. package/dist/core/runner/run-leg.js +37 -28
  176. package/dist/core/runner/run-stop-and-final-verify.js +2 -2
  177. package/dist/core/runner/run-terminal-adoption.d.ts +2 -5
  178. package/dist/core/runner/run-terminal-adoption.js +9 -3
  179. package/dist/core/runner/run-turn-boundary.js +77 -70
  180. package/dist/core/runner/runtask.d.ts +1 -1
  181. package/dist/core/runner/runtask.js +2 -2
  182. package/dist/core/runner/side-call-account.d.ts +1 -1
  183. package/dist/core/runner/side-call-account.js +3 -18
  184. package/dist/core/runner/sub-agent-deny-lists.d.ts +24 -0
  185. package/dist/core/runner/sub-agent-deny-lists.js +10 -0
  186. package/dist/core/runner/tool-end-body.js +2 -2
  187. package/dist/core/runner/tool-occurrence.d.ts +1 -1
  188. package/dist/core/runner/tool-occurrence.js +2 -2
  189. package/dist/core/runner/turn-attachments.d.ts +26 -22
  190. package/dist/core/runner/turn-attachments.js +24 -26
  191. package/dist/core/runner-deps.d.ts +1 -1
  192. package/dist/core/secret-env.d.ts +32 -2
  193. package/dist/core/secret-env.js +65 -3
  194. package/dist/core/sensitive-path-policy.js +3 -3
  195. package/dist/core/session-policy-store.d.ts +3 -1
  196. package/dist/core/session-policy-store.js +13 -9
  197. package/dist/core/session-store.d.ts +2 -5
  198. package/dist/core/side-query.d.ts +11 -1
  199. package/dist/core/side-query.js +9 -0
  200. package/dist/core/skill-grant-binding.d.ts +31 -2
  201. package/dist/core/skill-grant-binding.js +31 -1
  202. package/dist/core/skill-grant.d.ts +8 -5
  203. package/dist/core/skill-grant.js +6 -6
  204. package/dist/core/store-contracts/background-agent-store-contract.js +27 -0
  205. package/dist/core/store-contracts/checkpoint-store-contract.js +3 -2
  206. package/dist/core/store-contracts/mailbox-store-contract.js +31 -1
  207. package/dist/core/synthetic-read-verdict.js +2 -1
  208. package/dist/core/task-event.d.ts +32 -8
  209. package/dist/core/task-notification.js +16 -10
  210. package/dist/core/task-registry-agent.js +1 -0
  211. package/dist/core/task-registry-shared.d.ts +5 -0
  212. package/dist/core/task-spec.d.ts +12 -1
  213. package/dist/core/terminal-cause.d.ts +10 -0
  214. package/dist/core/tool-check-reading.d.ts +1 -0
  215. package/dist/core/tool-check-reading.js +3 -3
  216. package/dist/core/tool-policy.d.ts +16 -0
  217. package/dist/core/tool-roster.d.ts +112 -5
  218. package/dist/core/tool-roster.js +42 -1
  219. package/dist/core/tool-spec.d.ts +3 -1
  220. package/dist/core/types.d.ts +2 -2
  221. package/dist/core/types.js +1 -1
  222. package/dist/core/user-attachment.js +1 -1
  223. package/dist/core/wiring-manifest.d.ts +6 -3
  224. package/dist/engine/compaction/compaction.js +29 -3
  225. package/dist/engine/execution-env/node-execution-env.d.ts +4 -3
  226. package/dist/engine/execution-env/node-execution-env.js +9 -12
  227. package/dist/engine/harness/agent-harness.d.ts +25 -2
  228. package/dist/engine/harness/agent-harness.js +41 -12
  229. package/dist/engine/harness/messages.d.ts +3 -1
  230. package/dist/engine/harness/messages.js +3 -2
  231. package/dist/engine/harness/types.d.ts +8 -0
  232. package/dist/engine/llm/rejected-images.d.ts +46 -0
  233. package/dist/engine/llm/rejected-images.js +54 -0
  234. package/dist/engine/llm/tool-turns.d.ts +2 -1
  235. package/dist/engine/llm/types.d.ts +18 -7
  236. package/dist/engine/loop/agent-loop.d.ts +8 -0
  237. package/dist/engine/loop/agent-loop.js +52 -15
  238. package/dist/engine/loop/types.d.ts +3 -1
  239. package/dist/engine/session/path-to-root.d.ts +38 -0
  240. package/dist/engine/session/path-to-root.js +39 -0
  241. package/dist/engine/session/storage-base.js +4 -21
  242. package/dist/index.d.ts +16 -10
  243. package/dist/index.js +11 -7
  244. package/dist/internal/harness-types.d.ts +1 -1
  245. package/dist/internal/harness.d.ts +1 -0
  246. package/dist/internal/llm.d.ts +1 -0
  247. package/dist/orchestration/workflow-observe.d.ts +17 -1
  248. package/dist/orchestration/workflow-observe.js +20 -0
  249. package/dist/orchestration/workflow-types.d.ts +32 -7
  250. package/dist/orchestration/workflow.js +739 -489
  251. package/dist/shell/counting-pass.d.ts +50 -0
  252. package/dist/shell/counting-pass.js +502 -0
  253. package/dist/shell/lex.d.ts +4 -2
  254. package/dist/shell/lex.js +93 -34
  255. package/dist/shell/shell-words.d.ts +1 -1
  256. package/dist/shell/shell-words.js +7 -6
  257. package/dist/stores/file/mailbox-store.js +6 -10
  258. package/dist/tools/fs/fs-bash.d.ts +6 -0
  259. package/dist/tools/fs/fs-bash.js +6 -3
  260. package/dist/tools/fs/index.js +6 -2
  261. package/dist/tools/fs/program-read-model.d.ts +13 -0
  262. package/dist/tools/fs/program-read-model.js +15 -0
  263. package/dist/tools/fs/program-read-model.rows.js +1 -1
  264. package/dist/tools/fs/read-deny.d.ts +13 -10
  265. package/dist/tools/fs/read-deny.js +25 -5
  266. package/dist/tools/fs/read-floor.d.ts +19 -0
  267. package/dist/tools/fs/read-floor.js +23 -0
  268. package/dist/tools/fs/shell-read-check.d.ts +1 -1
  269. package/dist/tools/fs/shell-read-check.js +2 -1
  270. package/dist/tools/fs/shell-read-judge.d.ts +16 -8
  271. package/dist/tools/fs/shell-read-judge.js +10 -6
  272. package/dist/tools/fs/shell-read-plan.d.ts +6 -1
  273. package/dist/tools/fs/shell-read-plan.js +22 -15
  274. package/dist/tools/fs/shell-read-start.js +1 -0
  275. package/dist/tools/fs/shell-reentry-text.d.ts +15 -1
  276. package/dist/tools/fs/shell-reentry-text.js +25 -3
  277. package/dist/tools/monitor.d.ts +4 -0
  278. package/dist/tools/monitor.js +2 -0
  279. package/package.json +3 -2
  280. package/test/export-surface.snapshot.json +87 -1
  281. package/wire-changes/core-stores-sql@7.59.0.json +29 -0
  282. package/wire-changes/core@7.59.0.json +2459 -0
  283. package/wire-changes/mods-kernel@7.59.0.json +29 -0
  284. package/wire-changes/primitives@7.59.0.json +29 -0
@@ -145,7 +145,7 @@ export type NoticeAudience = "user" | "operator";
145
145
  * the union's catalog ({@link EngineNotice.code}). The groups below say only which family a row joins,
146
146
  * so the catalog is not written a second time here and the two cannot drift.
147
147
  */
148
- export declare const ENGINE_NOTICE_CODES: readonly ["config.autocompact_window_clamped", "config.env_timeout_discarded", "config.materialize_env_discarded", "config.models_swapped", "config.context_settings_swapped", "config.read_face_swapped", "config.read_face_deployment_clamped", "config.write_face_swapped", "config.write_face_deployment_clamped", "config.read_deny_swapped", "config.tool_model_gate_removed", "config.tool_model_gate_unknown_class", "config.tool_model_gate_env_invalid", "config.artifact_host_invalid", "config.task_root_not_canonical", "config.write_protection_target_view_absent", "config.path_view_unresolved", "config.execution_env_capability_invalid", "config.tool_card_undeclared", "config.tool_face_undeclared", "config.tool_face_invalid", "config.forward_sink_failed", "config.durable_gate_unavailable", "config.peer_admission_out_of_range", "config.peer_lane_unmounted", "config.secret_env_scrubbed", "inherit_env.names_withheld", "config.credential_not_withheld", "config.cross_boundary_posture_undeclared", "config.cross_boundary_record_unwritten", "config.permission_mode_unavailable", "permission.ask_released_by_mode", "permission.read_deny_unapplied", "permission.rule_store_unavailable", "permission.rule_row_dropped", "config.session_rules_earlier_grammar", "permission.allowed_tool_not_granted", "mods.registration_refused", "peer.inbound_disposition", "peer.held_settled", "peer.idle_subscription", "classifier.denial_limit", "classifier.fallback", "classifier.role_defaulted", "classifier.contract_broken", "classifier.unavailable", "checkpoint.execution_outcome_unrecorded", "delegation.transcript_integrity", "delegation.ask_unresolvable", "mcp.injection_dropped", "mcp.revocation_probe_failed", "mcp.server_redialed", "workflow.governance_key_stripped", "workflow.agent_option_ignored", "memory.session_polluted", "memory.harvest_quarantined", "memory.delegation_static_mark_waived", "memory.content_class_declared", "memory.hold_opened", "memory.hold_released", "memory.hold_disposed", "memory.consolidation_recommended", "memory.consolidation_committed", "memory.consolidation_conflict", "memory.consolidation_incomplete", "memory.consolidation_refused", "memory.consolidation_withheld", "memory.restore_withheld", "memory.project_scope_absent", "route.fallback_to_primary", "route.classifier_unroutable", "route.seat_detached", "advisor.not_attached", "route.credential_origin_mismatch", "route.response_model_mismatch", "route.tool_call_id_folded", "route.finish_reason_unknown", "route.stream_end_ignored", "route.extra_body_reserved_dropped", "model.capability_downgraded", "context.tool_turn_repaired", "task.user_steer_undrained", "task.user_followup_undrained", "steering.parked_input_blocked", "task.turn_interrupted", "task.halt_unconsumed", "task.late_approval", "task.interrupt_unconsumed", "task.tool_turn_incomplete", "approval.read_root_granted", "approval.read_root_grant_rejected", "memory.capture_opted_out", "memory.capture_optout_unpersisted", "skills.listing_truncated", "agents.listing_truncated", "tool_result.offload_put_failed", "tool_result.media_refused", "instructions.source_changed", "session.records_skipped", "memory.layer_locked_legacy", "server.model_unreachable", "permission.entry_mode_clamped"];
148
+ export declare const ENGINE_NOTICE_CODES: readonly ["config.autocompact_window_clamped", "config.env_timeout_discarded", "config.materialize_env_discarded", "config.models_swapped", "config.context_settings_swapped", "config.read_face_swapped", "config.read_face_deployment_clamped", "config.write_face_swapped", "config.write_face_deployment_clamped", "config.read_deny_swapped", "config.tool_model_gate_removed", "config.tool_model_gate_unknown_class", "config.tool_model_gate_env_invalid", "config.artifact_host_invalid", "config.task_root_not_canonical", "config.write_protection_target_view_absent", "config.path_view_unresolved", "config.execution_env_capability_invalid", "config.tool_card_undeclared", "config.tool_face_undeclared", "config.tool_face_invalid", "config.forward_sink_failed", "config.durable_gate_unavailable", "config.peer_admission_out_of_range", "config.peer_lane_unmounted", "config.secret_env_scrubbed", "inherit_env.names_withheld", "config.credential_not_withheld", "config.cross_boundary_posture_undeclared", "config.cross_boundary_record_unwritten", "config.permission_mode_unavailable", "permission.ask_released_by_mode", "permission.read_deny_unapplied", "permission.rule_store_unavailable", "permission.rule_row_dropped", "config.session_rules_earlier_grammar", "permission.allowed_tool_not_granted", "mods.registration_refused", "peer.inbound_disposition", "peer.held_settled", "peer.idle_subscription", "classifier.denial_limit", "classifier.fallback", "classifier.role_defaulted", "classifier.contract_broken", "classifier.unavailable", "checkpoint.execution_outcome_unrecorded", "delegation.transcript_integrity", "delegation.ask_unresolvable", "mcp.injection_dropped", "mcp.revocation_probe_failed", "mcp.server_redialed", "mcp.authorization_required", "workflow.governance_key_stripped", "workflow.agent_option_ignored", "memory.session_polluted", "memory.harvest_quarantined", "memory.delegation_static_mark_waived", "memory.content_class_declared", "memory.hold_opened", "memory.hold_released", "memory.hold_disposed", "memory.consolidation_recommended", "memory.consolidation_committed", "memory.consolidation_conflict", "memory.consolidation_incomplete", "memory.consolidation_refused", "memory.consolidation_withheld", "memory.restore_withheld", "memory.project_scope_absent", "route.fallback_to_primary", "route.classifier_unroutable", "route.seat_detached", "advisor.not_attached", "route.credential_origin_mismatch", "route.credential_rebound", "route.response_model_mismatch", "route.tool_call_id_folded", "route.finish_reason_unknown", "route.stream_end_ignored", "route.extra_body_reserved_dropped", "model.capability_downgraded", "model.role_defaulted", "context.tool_turn_repaired", "context.image_removed", "task.user_steer_undrained", "task.user_followup_undrained", "steering.parked_input_blocked", "task.turn_interrupted", "task.halt_unconsumed", "task.late_approval", "task.interrupt_unconsumed", "task.tool_turn_incomplete", "approval.read_root_granted", "approval.read_root_grant_rejected", "memory.capture_opted_out", "memory.capture_optout_unpersisted", "skills.listing_truncated", "agents.listing_truncated", "tool_result.offload_put_failed", "tool_result.media_refused", "instructions.source_changed", "session.records_skipped", "memory.layer_locked_legacy", "server.model_unreachable", "permission.entry_mode_clamped"];
149
149
  /** A catalogued code (see {@link ENGINE_NOTICE_CODES}); {@link NOTICE_MINTER} says who mints it. NOT the type of
150
150
  * `EngineNotice.code`, which stays `string` — a host forwarding its own notices through the same
151
151
  * sink is a supported shape, and narrowing that field would break it. */
@@ -237,6 +237,7 @@ declare const NOTICE_AUDIENCE_TABLE: {
237
237
  readonly "mcp.injection_dropped": "user";
238
238
  readonly "mcp.revocation_probe_failed": "operator";
239
239
  readonly "mcp.server_redialed": "operator";
240
+ readonly "mcp.authorization_required": "user";
240
241
  readonly "workflow.governance_key_stripped": "operator";
241
242
  readonly "workflow.agent_option_ignored": "operator";
242
243
  readonly "memory.content_class_declared": "operator";
@@ -250,12 +251,15 @@ declare const NOTICE_AUDIENCE_TABLE: {
250
251
  readonly "route.fallback_to_primary": "operator";
251
252
  readonly "route.classifier_unroutable": "operator";
252
253
  readonly "route.seat_detached": "operator";
254
+ readonly "route.credential_rebound": "operator";
253
255
  readonly "advisor.not_attached": "user";
254
256
  readonly "route.response_model_mismatch": "operator";
255
257
  readonly "route.tool_call_id_folded": "operator";
256
258
  readonly "route.extra_body_reserved_dropped": "operator";
257
259
  readonly "model.capability_downgraded": "user";
260
+ readonly "model.role_defaulted": "operator";
258
261
  readonly "context.tool_turn_repaired": "operator";
262
+ readonly "context.image_removed": "user";
259
263
  readonly "skills.listing_truncated": "operator";
260
264
  readonly "agents.listing_truncated": "operator";
261
265
  readonly "tool_result.offload_put_failed": "operator";
@@ -343,6 +347,7 @@ declare const NOTICE_MINTER_TABLE: {
343
347
  readonly "mcp.injection_dropped": "engine";
344
348
  readonly "mcp.revocation_probe_failed": "engine";
345
349
  readonly "mcp.server_redialed": "engine";
350
+ readonly "mcp.authorization_required": "engine";
346
351
  readonly "workflow.governance_key_stripped": "engine";
347
352
  readonly "workflow.agent_option_ignored": "engine";
348
353
  readonly "memory.session_polluted": "engine";
@@ -365,13 +370,16 @@ declare const NOTICE_MINTER_TABLE: {
365
370
  readonly "route.seat_detached": "engine";
366
371
  readonly "advisor.not_attached": "engine";
367
372
  readonly "route.credential_origin_mismatch": "engine";
373
+ readonly "route.credential_rebound": "engine";
368
374
  readonly "route.response_model_mismatch": "engine";
369
375
  readonly "route.tool_call_id_folded": "engine";
370
376
  readonly "route.finish_reason_unknown": "engine";
371
377
  readonly "route.stream_end_ignored": "engine";
372
378
  readonly "route.extra_body_reserved_dropped": "engine";
373
379
  readonly "model.capability_downgraded": "engine";
380
+ readonly "model.role_defaulted": "engine";
374
381
  readonly "context.tool_turn_repaired": "engine";
382
+ readonly "context.image_removed": "engine";
375
383
  readonly "task.user_steer_undrained": "engine";
376
384
  readonly "task.user_followup_undrained": "engine";
377
385
  readonly "steering.parked_input_blocked": "engine";
@@ -15,6 +15,7 @@ export const NON_GOVERNANCE_MEMORY_CODES = new Set([
15
15
  "memory.secret_detected",
16
16
  "memory.promotable_ungated",
17
17
  "memory.announce_failed",
18
+ "memory.announcement_withheld",
18
19
  "memory.partition_adopt_failed",
19
20
  "memory.partition_split",
20
21
  "memory.layout_migrated",
@@ -175,6 +176,7 @@ export const ENGINE_NOTICE_CODES = Object.freeze([
175
176
  "mcp.injection_dropped",
176
177
  "mcp.revocation_probe_failed",
177
178
  "mcp.server_redialed",
179
+ "mcp.authorization_required",
178
180
  "workflow.governance_key_stripped",
179
181
  "workflow.agent_option_ignored",
180
182
  "memory.session_polluted",
@@ -197,13 +199,16 @@ export const ENGINE_NOTICE_CODES = Object.freeze([
197
199
  "route.seat_detached",
198
200
  "advisor.not_attached",
199
201
  "route.credential_origin_mismatch",
202
+ "route.credential_rebound",
200
203
  "route.response_model_mismatch",
201
204
  "route.tool_call_id_folded",
202
205
  "route.finish_reason_unknown",
203
206
  "route.stream_end_ignored",
204
207
  "route.extra_body_reserved_dropped",
205
208
  "model.capability_downgraded",
209
+ "model.role_defaulted",
206
210
  "context.tool_turn_repaired",
211
+ "context.image_removed",
207
212
  "task.user_steer_undrained",
208
213
  "task.user_followup_undrained",
209
214
  "steering.parked_input_blocked",
@@ -300,6 +305,7 @@ const NOTICE_AUDIENCE_TABLE = {
300
305
  "mcp.injection_dropped": "user",
301
306
  "mcp.revocation_probe_failed": "operator",
302
307
  "mcp.server_redialed": "operator",
308
+ "mcp.authorization_required": "user",
303
309
  "workflow.governance_key_stripped": "operator",
304
310
  "workflow.agent_option_ignored": "operator",
305
311
  "memory.content_class_declared": "operator",
@@ -313,12 +319,15 @@ const NOTICE_AUDIENCE_TABLE = {
313
319
  "route.fallback_to_primary": "operator",
314
320
  "route.classifier_unroutable": "operator",
315
321
  "route.seat_detached": "operator",
322
+ "route.credential_rebound": "operator",
316
323
  "advisor.not_attached": "user",
317
324
  "route.response_model_mismatch": "operator",
318
325
  "route.tool_call_id_folded": "operator",
319
326
  "route.extra_body_reserved_dropped": "operator",
320
327
  "model.capability_downgraded": "user",
328
+ "model.role_defaulted": "operator",
321
329
  "context.tool_turn_repaired": "operator",
330
+ "context.image_removed": "user",
322
331
  "skills.listing_truncated": "operator",
323
332
  "agents.listing_truncated": "operator",
324
333
  "tool_result.offload_put_failed": "operator",
@@ -387,6 +396,7 @@ const NOTICE_MINTER_TABLE = {
387
396
  "mcp.injection_dropped": "engine",
388
397
  "mcp.revocation_probe_failed": "engine",
389
398
  "mcp.server_redialed": "engine",
399
+ "mcp.authorization_required": "engine",
390
400
  "workflow.governance_key_stripped": "engine",
391
401
  "workflow.agent_option_ignored": "engine",
392
402
  "memory.session_polluted": "engine",
@@ -409,13 +419,16 @@ const NOTICE_MINTER_TABLE = {
409
419
  "route.seat_detached": "engine",
410
420
  "advisor.not_attached": "engine",
411
421
  "route.credential_origin_mismatch": "engine",
422
+ "route.credential_rebound": "engine",
412
423
  "route.response_model_mismatch": "engine",
413
424
  "route.tool_call_id_folded": "engine",
414
425
  "route.finish_reason_unknown": "engine",
415
426
  "route.stream_end_ignored": "engine",
416
427
  "route.extra_body_reserved_dropped": "engine",
417
428
  "model.capability_downgraded": "engine",
429
+ "model.role_defaulted": "engine",
418
430
  "context.tool_turn_repaired": "engine",
431
+ "context.image_removed": "engine",
419
432
  "task.user_steer_undrained": "engine",
420
433
  "task.user_followup_undrained": "engine",
421
434
  "steering.parked_input_blocked": "engine",
@@ -100,8 +100,11 @@ export interface PostToolBatchEvent extends ClassicEventBase {
100
100
  readonly injectedThisTurn?: "final_verification" | "finalize";
101
101
  }
102
102
  /**
103
- * `classic.UserPromptSubmit`'s `e` — EVERY user-lane entrance: the objective, a live steer, a wake resume's message
104
- * (pre-claim, at the verb) and a parked steer's redelivery, discriminated by {@link source}. Pinned: `source`,
103
+ * `classic.UserPromptSubmit`'s `e` — EVERY user-lane entrance: a top-level leg's objective, a live steer, a wake resume's
104
+ * message (pre-claim, at the verb) and a parked steer's redelivery, discriminated by {@link source}. A delegated child's
105
+ * objective is one only when it carries an operator's words (a retained child resumed through its steer handle);
106
+ * otherwise its delegator wrote it, the screen that can refuse it is the delegator's `classic.PreToolUse` on the call that
107
+ * delegates (its `input.prompt`), and the child opens on `classic.SubagentStart` ({@link SubagentStartEvent}). Pinned: `source`,
105
108
  * `inputId`, `actor`. A handler that blocks unconditionally therefore refuses steers too — branch on `source` (and
106
109
  * `actor`). Answer: {@link UserPromptSubmitResult}. Block per entrance: objective ⇒ the task ends `blocked`; live steer
107
110
  * ⇒ typed `steering.blocked_by_hook`; resume message ⇒ typed pre-claim refusal (the checkpoint stays pending); parked
@@ -114,7 +117,7 @@ export interface UserPromptSubmitEvent extends ClassicEventBase {
114
117
  /** The caller's text, raw. */
115
118
  readonly prompt: string;
116
119
  /**
117
- * WHICH entrance: `"objective"` (the task's opening prompt), `"steer"` (a live mid-run steer), `"resume_message"`
120
+ * WHICH entrance: `"objective"` (a top-level task's opening prompt), `"steer"` (a live mid-run steer), `"resume_message"`
118
121
  * (a wake resume's message, screened pre-claim), `"parked_redelivery"` (a parked steer re-screened on the CURRENT
119
122
  * process when any resume kind that drains parked steers redelivers it). ⚠️ DOUBLE ARRIVAL IS CONTRACTUAL: one input
120
123
  * can arrive twice (screened live as `"steer"`, parked, re-screened as `"parked_redelivery"`) — idempotency is the
@@ -140,6 +143,31 @@ export interface UserPromptSubmitEvent extends ClassicEventBase {
140
143
  */
141
144
  readonly userAttachments?: readonly import("./user-attachment.js").UserAttachmentDeclaration[];
142
145
  }
146
+ /**
147
+ * `classic.SubagentStart`'s `e` — raised on a delegated child's own leg when it opens on its objective (a first spawn,
148
+ * a revival, a retained child's next prompt; every lane — synchronous, background, fork, workflow), before its first
149
+ * request; never on a top-level leg and never on a checkpoint resume (that continues a turn it already opened). The
150
+ * child's prompt is not here: its parent's model wrote it, and the parent's `classic.PreToolUse` on the delegating call
151
+ * is where it is judged. Pinned: `agentId`, `agentType`. Context only — it NEVER keeps a subagent from starting: a
152
+ * handler that fails (throws, overruns its budget, answers what the station cannot take) is skipped and reported.
153
+ * Answer: {@link SubagentStartResult}.
154
+ */
155
+ export interface SubagentStartEvent extends ClassicEventBase {
156
+ /** The child's id (its task id) — always present on this event. */
157
+ readonly agentId: string;
158
+ /** The resolved subagent type the child was spawned as ({@link HookInvocationIdentity.agentType}; the word a handler
159
+ * matches on). Absent when the spawner threaded none (a workflow-lane agent). */
160
+ readonly agentType?: string;
161
+ }
162
+ /**
163
+ * What a `classic.SubagentStart` handler answers. There is no refusal member: an answer carrying `block` is one the
164
+ * station cannot take (the handler is skipped and reported, the child starts) — a deployment that must keep a child from
165
+ * starting denies the delegating call at `classic.PreToolUse`.
166
+ */
167
+ export interface SubagentStartResult {
168
+ /** Delivered ahead of the child's prompt in its first request (wrapped as a `<system-reminder>`). */
169
+ additionalContext?: string;
170
+ }
143
171
  /**
144
172
  * `classic.Stop`'s `e` — raised when the agent WOULD OTHERWISE END its run (no more tool calls, steering and follow-up
145
173
  * queues dry). Answer: {@link StopHookResult}; `{ block }` pushes back (the reason is injected and the run continues one
@@ -2,7 +2,7 @@ import { argsAsTheToolReads, stampArgsReading } from "./effective-path-target.js
2
2
  import { extensionAuthors, noteRewrite, screeningAuthorship } from "./rewrite-rejudge.js";
3
3
  import { abortedSeatDeny, decisionText, describeThrown, isEngineRefusal, ownArgs, ownedReading, refuseOutOfContractDecision, unaskedSeatAnswer } from "./tool-policy.js";
4
4
  import { createSettlementLedger, engineFailClosedExit, hookDenyExit, unownedArgsExit } from "./runner/gate-exit.js";
5
- import { classicEventBase, dispatchClassic, ENGINE_CORE_ANSWER, engineCore, failedHandlerClause, judgedInputOf, observePermissionDenied, recordScreeningChain } from "./mods/stations.js";
5
+ import { classicEventBase, dispatchClassic, ENGINE_CORE_ANSWER, engineCore, failedHandlerClause, judgedInputOf, observePermissionDenied, withInstallation } from "./mods/stations.js";
6
6
  import { runGateFold } from "./gate-fold.js";
7
7
  import { runGateLanes } from "./gate-lanes.js";
8
8
  export { normalizeOrgGateVerdict, normalizePersistedRuleHit } from "./rule-lane-reads.js";
@@ -141,7 +141,7 @@ export function createPreToolUseScreening(input) {
141
141
  if (outcome === undefined || outcome.kind === "aborted")
142
142
  return { kind: "refused", reason: preToolUseRefusedReason(subject, undefined) };
143
143
  if (outcome.kind === "failed")
144
- return { kind: "refused", reason: preToolUseRefusedReason(subject, outcome) };
144
+ return { kind: "refused", reason: preToolUseRefusedReason(subject, outcome), extension: outcome.registration };
145
145
  const r = screenPreToolUseResult(outcome.answer);
146
146
  const answer = r === null || r === false ? undefined : r;
147
147
  const rewrittenBy = authorship.of(outcome.answer);
@@ -195,8 +195,7 @@ export function createPreToolUseConstraintPolicy(chain, env) {
195
195
  return r.updatedInput !== undefined ? { action: "allow", updatedInput: r.updatedInput } : { action: "allow" };
196
196
  },
197
197
  }, "hook");
198
- recordScreeningChain(minted, chain);
199
- return minted;
198
+ return withInstallation(minted, chain);
200
199
  }
201
200
  export function askCarryRowMembers(carry) {
202
201
  if (carry === undefined)
@@ -258,7 +257,7 @@ export async function runToolGate(input) {
258
257
  if (screening !== undefined) {
259
258
  const screened = await screening.screen(pass.currentInput, `this call to "${toolName}"`, pass.req);
260
259
  if (screened.kind === "refused") {
261
- return await engineFailClosedExit(pass, screened.reason);
260
+ return await engineFailClosedExit(pass, screened.reason, screened.extension);
262
261
  }
263
262
  const r = screened.answer;
264
263
  if (r) {
@@ -266,7 +265,7 @@ export async function runToolGate(input) {
266
265
  pass.preToolContext.push(r.additionalContext);
267
266
  }
268
267
  if (r.action === "deny") {
269
- return hookDenyExit(pass, screening.deniedReason(r));
268
+ return hookDenyExit(pass, screening.deniedReason(r), screened.answeredBy);
270
269
  }
271
270
  if (r.updatedInput !== undefined) {
272
271
  const rewritten = argsAsTheToolReads(pass.req, r.updatedInput);
@@ -6,8 +6,9 @@
6
6
  * ① the claimed type is one the content API accepts (png / jpeg / gif / webp — the four
7
7
  * {@link imageMagicMatches} can verify);
8
8
  * ② the raw bytes are within the read cap (5 MiB without a downsampler, 64 MiB with one);
9
- * ③ the bytes carry the claimed type's signature — an empty / text / mis-named "png" would
10
- * otherwise become a malformed block that 400s the NEXT whole provider request;
9
+ * ③ the bytes open with the claimed type's header — its signature and the first structure the format requires
10
+ * ({@link IMAGE_HEADER_CHECKS}); an empty / text / mis-named "png", or an Apple-optimized PNG, would otherwise
11
+ * become a malformed block that 400s the NEXT whole provider request;
11
12
  * ④ optional downsample (when a downsampler is supplied; a processing failure keeps the original
12
13
  * bytes, CC's catch → createImageResponse(original)), then the provider's hard limit, which is on the
13
14
  * BASE64 length, not raw bytes.
@@ -38,9 +39,9 @@ export declare const MAX_IMAGE_READ_BYTES: number;
38
39
  export declare const MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES: number;
39
40
  /** Max raw size sent whole as a document block (CC `PDF_TARGET_RAW_SIZE`). */
40
41
  export declare const PDF_TARGET_RAW_SIZE: number;
41
- /** Verify the raw bytes actually ARE the image format the extension claims (magic-number sniff). Extension alone
42
- * is forgeable: a `.png` holding text / an empty file / a truncated blob would otherwise become a malformed
43
- * `ImageContent` that makes the NEXT provider request fail (400). Pure — no I/O. */
42
+ /** Verify the raw bytes actually ARE the image format the claimed type names ({@link IMAGE_HEADER_CHECKS}). Extension
43
+ * alone is forgeable: a `.png` holding text / an empty file / a truncated blob / an Apple-optimized PNG would otherwise
44
+ * become a malformed `ImageContent` that makes the NEXT provider request fail (400). Pure — no I/O. */
44
45
  export declare function imageMagicMatches(bytes: Uint8Array, mimeType: string): boolean;
45
46
  /** True when the bytes start with the `%PDF-` magic. Magic outranks extension both ways: a mis-named
46
47
  * `.pdf` without it is refused, and a non-`.pdf` file carrying it is read AS a PDF. */
@@ -4,20 +4,24 @@ import { readMember } from "./thrown-value.js";
4
4
  export const MAX_IMAGE_READ_BYTES = 5 * 1024 * 1024;
5
5
  export const MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES = 64 * 1024 * 1024;
6
6
  export const PDF_TARGET_RAW_SIZE = 20 * 1024 * 1024;
7
- export function imageMagicMatches(bytes, mimeType) {
8
- const b = bytes;
9
- switch (mimeType) {
10
- case "image/png":
11
- return b.length >= 8 && b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47 && b[4] === 0x0d && b[5] === 0x0a && b[6] === 0x1a && b[7] === 0x0a;
12
- case "image/jpeg":
13
- return b.length >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff;
14
- case "image/gif":
15
- return b.length >= 6 && b[0] === 0x47 && b[1] === 0x49 && b[2] === 0x46 && b[3] === 0x38 && (b[4] === 0x37 || b[4] === 0x39) && b[5] === 0x61;
16
- case "image/webp":
17
- return b.length >= 12 && b[0] === 0x52 && b[1] === 0x49 && b[2] === 0x46 && b[3] === 0x46 && b[8] === 0x57 && b[9] === 0x45 && b[10] === 0x42 && b[11] === 0x50;
18
- default:
7
+ const spells = (b, at, text) => {
8
+ if (b.length < at + text.length)
9
+ return false;
10
+ for (let i = 0; i < text.length; i++)
11
+ if (b[at + i] !== text.charCodeAt(i))
19
12
  return false;
20
- }
13
+ return true;
14
+ };
15
+ const u32be = (b, at) => ((b[at] << 24) >>> 0) + (b[at + 1] << 16) + (b[at + 2] << 8) + b[at + 3];
16
+ const u16le = (b, at) => b[at] + (b[at + 1] << 8);
17
+ const IMAGE_HEADER_CHECKS = {
18
+ "image/png": (b) => b.length >= 24 && spells(b, 0, "\x89PNG\r\n\x1a\n") && u32be(b, 8) === 13 && spells(b, 12, "IHDR") && u32be(b, 16) > 0 && u32be(b, 20) > 0,
19
+ "image/jpeg": (b) => b.length >= 4 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff && b[3] >= 0xc0,
20
+ "image/gif": (b) => b.length >= 13 && (spells(b, 0, "GIF87a") || spells(b, 0, "GIF89a")) && u16le(b, 6) > 0 && u16le(b, 8) > 0,
21
+ "image/webp": (b) => b.length >= 16 && spells(b, 0, "RIFF") && spells(b, 8, "WEBP") && (spells(b, 12, "VP8 ") || spells(b, 12, "VP8L") || spells(b, 12, "VP8X")),
22
+ };
23
+ export function imageMagicMatches(bytes, mimeType) {
24
+ return Object.hasOwn(IMAGE_HEADER_CHECKS, mimeType) && IMAGE_HEADER_CHECKS[mimeType](bytes);
21
25
  }
22
26
  export function pdfMagicMatches(bytes) {
23
27
  return bytes.length >= 5 && bytes[0] === 0x25 && bytes[1] === 0x50 && bytes[2] === 0x44 && bytes[3] === 0x46 && bytes[4] === 0x2d;
@@ -72,7 +76,7 @@ const REFUSAL_CLAUSE = {
72
76
  undecodable: () => "it carried no base64 payload",
73
77
  mime_unsupported: (r) => `${r.mimeType ?? "its media type"} is not a ${r.type} type the model accepts (${ADMITTED_FOR[r.type].join(", ")})`,
74
78
  raw_too_large: (r) => `its ${r.bytes} bytes exceed the ${r.limit}-byte cap`,
75
- magic_mismatch: (r) => `its ${r.bytes} bytes do not carry the ${r.mimeType} signature`,
79
+ magic_mismatch: (r) => `its ${r.bytes} bytes do not open with a valid ${r.mimeType ?? `${r.type}`} header`,
76
80
  base64_too_large: (r) => `its base64 encoding exceeds the ${r.limit}-character provider limit (${r.bytes} bytes)`,
77
81
  };
78
82
  const placeholderOf = (toolName, r) => ({
@@ -3,7 +3,7 @@ import { type ToolAxesSurface } from "./mcp-server-spec.js";
3
3
  import type { ToolPolicy } from "./tool-policy.js";
4
4
  /** The closed set of administratively lockable configuration keys. Adding a member is a deliberate
5
5
  * edit HERE (tsc forces the registry row), never a free-form string. */
6
- export type LockedKey = "mcp" | "toolPolicy" | "compliancePosture" | "retentionPolicy";
6
+ export type LockedKey = "mcp" | "a2a" | "toolPolicy" | "compliancePosture" | "retentionPolicy";
7
7
  /**
8
8
  * The closed locked-key registry: each key names the exact `TaskSpec` fields it guards. Keys whose
9
9
  * field set is EMPTY guard deployment-only surfaces (`compliancePosture` rides
@@ -18,6 +18,9 @@ export declare const LOCKED_KEY_REGISTRY: {
18
18
  readonly mcp: {
19
19
  readonly specFields: readonly ["mcp"];
20
20
  };
21
+ readonly a2a: {
22
+ readonly specFields: readonly ["a2a"];
23
+ };
21
24
  readonly toolPolicy: {
22
25
  readonly specFields: readonly ["toolPolicy", "basePolicyForResumeEdit"];
23
26
  };
@@ -48,7 +51,7 @@ export interface LockedPreflight {
48
51
  mcp: TaskSpec["mcp"];
49
52
  /** The task's A2A peers: a frozen SNAPSHOT of `spec.a2a` whose `toolAxes` were judged here by the same reader and with the same
50
53
  * disposition as an MCP server's (a declaration that does not fit refused the whole prepare), each peer carrying the reader's plain
51
- * copy; `undefined` when the spec declares no peer (absent or empty). Read once, here: the peers dialed are the peers judged. */
54
+ * copy; `undefined` when the spec declares no peer (absent or empty) or `a2a` is locked (a declared list has already been refused). Read once, here: the peers dialed are the peers judged. */
52
55
  a2a: TaskSpec["a2a"];
53
56
  /** Effective caller tool policy: the same `spec.toolPolicy ?? deps.toolPolicy` slot the gate has
54
57
  * always enforced, resolved ONCE here. With `toolPolicy` locked, the deployment's own
@@ -10,6 +10,7 @@ import { assertNoRetiredToolPolicyKeys } from "./retired-keys.js";
10
10
  import { CREDENTIALS_MEMBER, declaredCredentials, peerSeatMissing, retiredValueMember } from "./peer-seat.js";
11
11
  export const LOCKED_KEY_REGISTRY = {
12
12
  mcp: { specFields: ["mcp"] },
13
+ a2a: { specFields: ["a2a"] },
13
14
  toolPolicy: { specFields: ["toolPolicy", "basePolicyForResumeEdit"] },
14
15
  compliancePosture: { specFields: [] },
15
16
  retentionPolicy: { specFields: [] },
@@ -241,7 +242,7 @@ export function preflightLockedConfig(spec, deps, enter = ENTER_AS_IS) {
241
242
  enter(!toolPolicyLocked && task.basePolicyForResumeEdit != null ? "taskConfig" : "deps", () => assertNoRetiredToolPolicyKeys(policies.basePolicyForResumeEdit));
242
243
  const declaredServers = lockedKeys.has("mcp") ? undefined : spec.mcp;
243
244
  const mcp = declaredServers === undefined ? undefined : enter("taskConfig", () => snapshotAndValidateMcpEntries(declaredServers));
244
- const declaredPeers = spec.a2a;
245
+ const declaredPeers = lockedKeys.has("a2a") ? undefined : spec.a2a;
245
246
  const a2a = declaredPeers === undefined ? undefined : enter("taskConfig", () => snapshotAndValidateA2aEntries(declaredPeers));
246
247
  enter("taskConfig", () => {
247
248
  assertPeerSeatFor(mcp, "mcp", deps.peerSeat);
@@ -2,6 +2,8 @@
2
2
  * lease/expiry cycles (a re-leased message keeps its number — dedup/ordering key). */
3
3
  export interface MailboxMessage {
4
4
  seq: number;
5
+ /** The identity the PRODUCER gave this record ({@link MailboxAppendMessage.id}); absent = it stated none. */
6
+ id?: string;
5
7
  /** Sender display name, when the sender had one (SendMessage `senderName` — display only). */
6
8
  from?: string;
7
9
  content: string;
@@ -181,7 +183,7 @@ export declare const MAILBOX_TOMBSTONED_RECIPIENT_CODE = "mailbox.recipient_tomb
181
183
  * A backend may raise the same code with a plain `Error` carrying `.code`; consumers branch on the
182
184
  * string, not on this class (a cross-process/out-of-repo store cannot hand back an instance).
183
185
  */
184
- export type MailboxStoreErrorCode = typeof MAILBOX_TOMBSTONED_RECIPIENT_CODE | typeof MAILBOX_INVALID_PEER_META_CODE | typeof MAILBOX_CROSS_PROCESS_UNSAFE_CODE | typeof MAILBOX_INVALID_DECISION_MOVE_CODE;
186
+ export type MailboxStoreErrorCode = typeof MAILBOX_TOMBSTONED_RECIPIENT_CODE | typeof MAILBOX_INVALID_PEER_META_CODE | typeof MAILBOX_CROSS_PROCESS_UNSAFE_CODE | typeof MAILBOX_INVALID_DECISION_MOVE_CODE | typeof MAILBOX_INVALID_RECORD_ID_CODE | typeof MAILBOX_DUPLICATE_RECORD_ID_CODE;
185
187
  export declare class MailboxStoreError extends Error {
186
188
  readonly code: MailboxStoreErrorCode;
187
189
  constructor(code: MailboxStoreErrorCode, message: string);
@@ -195,6 +197,14 @@ export interface MailboxLease {
195
197
  /** REF-D18: one appended mailbox message — the SINGLE shape the interface method and both the
196
198
  * In-Memory and File implementations reference. */
197
199
  export interface MailboxAppendMessage {
200
+ /**
201
+ * The record's identity, minted by its producer — a re-park of the same message carries the same
202
+ * one. While the box HOLDS a record under this id, an append under it is that record: identical on
203
+ * every {@link MAILBOX_REPLAY_FACETS} facet ⇒ the held `seq`, nothing written; any facet different ⇒
204
+ * refused with {@link MAILBOX_DUPLICATE_RECORD_ID_CODE}. Absent = the producer states no identity and
205
+ * every append is a new record (its `seq` is all it is known by). Validated by {@link readMailboxRecordId}.
206
+ */
207
+ id?: string;
198
208
  from?: string;
199
209
  content: string;
200
210
  sentAt: number;
@@ -203,6 +213,33 @@ export interface MailboxAppendMessage {
203
213
  /** design/385 — see {@link MailboxMessage.peerMeta}; validated by {@link readMailboxPeerMeta}. */
204
214
  peerMeta?: MailboxPeerMeta;
205
215
  }
216
+ /** An `id` that is not a non-empty string of at most {@link MAILBOX_RECORD_ID_MAX_CHARS} characters. */
217
+ export declare const MAILBOX_INVALID_RECORD_ID_CODE = "mailbox.invalid_record_id";
218
+ /** An append under an `id` the box holds, whose record differs from the held one. */
219
+ export declare const MAILBOX_DUPLICATE_RECORD_ID_CODE = "mailbox.duplicate_record_id";
220
+ export declare const MAILBOX_RECORD_ID_MAX_CHARS = 1024;
221
+ /**
222
+ * What a record SAYS — the facets a repeat under one id is compared on. `sentAt` is not one of them: it
223
+ * is when a write happened, and a re-park of the same message happens later. Closed, in refusal order.
224
+ */
225
+ export declare const MAILBOX_REPLAY_FACETS: readonly ["from", "content", "hopChain", "peerMeta"];
226
+ export type MailboxReplayFacet = (typeof MAILBOX_REPLAY_FACETS)[number];
227
+ /** Validate a record id at `append`, before any side effect. `undefined` = no identity stated. */
228
+ export declare function readMailboxRecordId(raw: unknown): string | undefined;
229
+ /**
230
+ * ONE read of a caller's append: every member read once, validated (`peerMeta`, then `id`) and detached.
231
+ * A backend judges and persists THIS snapshot — never the caller's object again — so an accessor, or a
232
+ * mutation while the append waits for its lock, cannot make the record judged differ from the record stored.
233
+ */
234
+ export declare function readMailboxAppend(msg: MailboxAppendMessage): MailboxAppendMessage;
235
+ /**
236
+ * THE append-by-identity judgment, the one every backend runs inside its write critical section
237
+ * (with `msg` already validated: `id` by {@link readMailboxRecordId}, `peerMeta` by {@link readMailboxPeerMeta}).
238
+ * Returns the held record's `seq` when `msg` replays it (the caller writes nothing), `undefined` when the
239
+ * box holds no record under `msg.id` (the caller appends), and throws {@link MAILBOX_DUPLICATE_RECORD_ID_CODE}
240
+ * naming the facets when a different record claims the id. A third-party backend calls this function too.
241
+ */
242
+ export declare function judgeMailboxAppendById(held: readonly MailboxMessage[], msg: MailboxAppendMessage): number | undefined;
206
243
  /**
207
244
  * The pluggable mailbox seam (design/151 §7.1). Contract notes for implementations (file/pg):
208
245
  * - `append` is durable-first (a returned seq means the message survives a crash); seq is monotonic
@@ -250,6 +287,13 @@ export interface MailboxAppendMessage {
250
287
  * and a malformed value is REFUSED with `"mailbox.invalid_peer_meta"` before any side effect
251
288
  * (`readMailboxPeerMeta` is the one validator; bundled backends call it first). T1 cases in
252
289
  * `mailboxStoreContract` cover the pass trip, the refusal and the aliasing.
290
+ * - RECORD IDENTITY (every backend): `append` takes an optional producer-minted `id`, persists
291
+ * it and hands it back on `claimLease`. While the box holds a record under that id, an append under
292
+ * it is answered by {@link judgeMailboxAppendById} — the held `seq` for an identical record (nothing
293
+ * written), `"mailbox.duplicate_record_id"` for a different one — atomically with the seq allocation;
294
+ * a malformed id is refused with `"mailbox.invalid_record_id"` before any side effect. This is what
295
+ * makes re-asking a store whose reply was lost safe: a rejected append is not proof that nothing was
296
+ * written. The box answers for what it HOLDS — once a record is acked its id is free again.
253
297
  * - CROSS-PROCESS SAFETY (design/385, optional capability declared on the store): the session-box
254
298
  * drain shares ONE box between several OS processes. A backend that is correct under that sharing —
255
299
  * seq minted once across processes, lease/ack never crossing, one process's housekeeping never
@@ -150,6 +150,54 @@ export class MailboxStoreError extends Error {
150
150
  this.name = "MailboxStoreError";
151
151
  }
152
152
  }
153
+ export const MAILBOX_INVALID_RECORD_ID_CODE = "mailbox.invalid_record_id";
154
+ export const MAILBOX_DUPLICATE_RECORD_ID_CODE = "mailbox.duplicate_record_id";
155
+ export const MAILBOX_RECORD_ID_MAX_CHARS = 1024;
156
+ export const MAILBOX_REPLAY_FACETS = Object.freeze(["from", "content", "hopChain", "peerMeta"]);
157
+ export function readMailboxRecordId(raw) {
158
+ if (raw === undefined)
159
+ return undefined;
160
+ if (typeof raw !== "string" || raw === "" || raw.length > MAILBOX_RECORD_ID_MAX_CHARS) {
161
+ throw new MailboxStoreError(MAILBOX_INVALID_RECORD_ID_CODE, `MailboxStore.append: id must be a non-empty string of at most ${MAILBOX_RECORD_ID_MAX_CHARS} characters`);
162
+ }
163
+ return raw;
164
+ }
165
+ export function readMailboxAppend(msg) {
166
+ const peerMeta = readMailboxPeerMeta(msg.peerMeta);
167
+ const id = readMailboxRecordId(msg.id);
168
+ const from = msg.from;
169
+ const content = msg.content;
170
+ const sentAt = msg.sentAt;
171
+ const hopChain = msg.hopChain;
172
+ return {
173
+ ...(id !== undefined ? { id } : {}),
174
+ ...(from !== undefined ? { from } : {}),
175
+ content,
176
+ sentAt,
177
+ ...(hopChain !== undefined ? { hopChain: [...hopChain] } : {}),
178
+ ...(peerMeta !== undefined ? { peerMeta } : {}),
179
+ };
180
+ }
181
+ function facetSpelling(v) {
182
+ if (v === undefined || v === null)
183
+ return "-";
184
+ if (typeof v !== "object")
185
+ return JSON.stringify(v);
186
+ if (Array.isArray(v))
187
+ return `[${Array.from(v, facetSpelling).join(",")}]`;
188
+ return `{${Object.keys(v).filter((k) => v[k] !== undefined).sort().map((k) => `${JSON.stringify(k)}:${facetSpelling(v[k])}`).join(",")}}`;
189
+ }
190
+ export function judgeMailboxAppendById(held, msg) {
191
+ if (msg.id === undefined)
192
+ return undefined;
193
+ const prior = held.find((m) => m.id === msg.id);
194
+ if (prior === undefined)
195
+ return undefined;
196
+ const differs = MAILBOX_REPLAY_FACETS.filter((f) => facetSpelling(prior[f]) !== facetSpelling(msg[f]));
197
+ if (differs.length === 0)
198
+ return prior.seq;
199
+ throw new MailboxStoreError(MAILBOX_DUPLICATE_RECORD_ID_CODE, `MailboxStore.append: the box already holds a different record under this id (it differs in: ${differs.join(", ")}) — a new message takes a new id; an identical repeat would have been a replay`);
200
+ }
153
201
  export function mailboxCrossProcessMountVerdict(store) {
154
202
  const declared = store.crossProcessSafe;
155
203
  if (declared === true)
@@ -199,17 +247,13 @@ export class InMemoryMailboxStore {
199
247
  async append(scope, handle, msg) {
200
248
  if (scope === undefined || scope === "")
201
249
  throw new Error("MailboxStore.append: refusing a message without a scope");
202
- const peerMeta = readMailboxPeerMeta(msg.peerMeta);
250
+ const record = readMailboxAppend(msg);
203
251
  const b = this.box(scope, handle);
252
+ const held = judgeMailboxAppendById(b.messages, record);
253
+ if (held !== undefined)
254
+ return held;
204
255
  const seq = b.nextSeq++;
205
- b.messages.push({
206
- seq,
207
- ...(msg.from !== undefined ? { from: msg.from } : {}),
208
- content: msg.content,
209
- sentAt: msg.sentAt,
210
- ...(msg.hopChain !== undefined ? { hopChain: [...msg.hopChain] } : {}),
211
- ...(peerMeta !== undefined ? { peerMeta } : {}),
212
- });
256
+ b.messages.push({ seq, ...record });
213
257
  return seq;
214
258
  }
215
259
  async claimLease(scope, handle, owner, ttlMs, now = Date.now()) {