@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
@@ -166,7 +166,7 @@ export async function admitUserAttachmentImages(screened) {
166
166
  case "mime_unsupported":
167
167
  throw userAttachmentRefusal(memberRef(imageAt, "mimeType"), `must be one of ${ADMITTED_IMAGE_MIME_TYPES.join(", ")}.`);
168
168
  case "magic_mismatch":
169
- throw userAttachmentRefusal(memberRef(imageAt, "data"), `does not begin with a ${a.mimeType} signature (empty, mis-declared, or not base64) — refused rather than sent.`);
169
+ throw userAttachmentRefusal(memberRef(imageAt, "data"), `does not open with a valid ${a.mimeType} header (empty, truncated, mis-declared, not base64, or a variant such as an Apple-optimized PNG that model APIs cannot read) — refused rather than sent.`);
170
170
  case "raw_too_large":
171
171
  throw userAttachmentRefusal(memberRef(imageAt, "data"), `${admitted.rawBytes} bytes, over the ${admitted.cap}-byte cap.`);
172
172
  case "base64_too_large":
@@ -24,7 +24,7 @@ import { type PermissionMode } from "./ask-origin.js";
24
24
  import type { RunnerDeps, TaskSpec } from "./types.js";
25
25
  import { type StoreDurability } from "./checkpoint-store.js";
26
26
  import type { ModAdmissionRecord } from "./mods/kernel/index.js";
27
- import type { McpDelivered, McpFailureKind, McpServerLiveness } from "./mcp-failure.js";
27
+ import type { McpAuthorization, McpDelivered, McpFailureKind, McpServerLiveness } from "./mcp-failure.js";
28
28
  import type { WriteProtectionTargetView } from "./write-protect.js";
29
29
  import type { OnAsk } from "./tool-policy.js";
30
30
  import { type RunOrigin } from "./run-origin.js";
@@ -114,8 +114,8 @@ export interface AutoModeArmFact {
114
114
  * One declared MCP server's materialization result for THIS leg — the per-server connection-state
115
115
  * read face on {@link WiringManifest.mcp}. `status` is the connect-time verdict of this leg's
116
116
  * materialize (a snapshot, never a heartbeat — the same semantics as `MaterializedMcp.statuses`,
117
- * which it is projected from): `connected` (tools listed; `toolCount` = see the field), `failed` (the connect or the tool listing threw — `errorCode`/`delivered`/`httpStatus` are the
118
- * failure record spread flat (see the MCP failure vocabulary's `McpFailure`), `error` the
117
+ * which it is projected from): `connected` (tools listed; `toolCount` = see the field), `failed` (the connect or the tool listing threw — `errorCode`/`delivered`/`httpStatus`/`authorization` are the
118
+ * failure record spread flat (see the MCP failure vocabulary's `McpFailure` and `failureFields`), `error` the
119
119
  * neutralized, length-bounded remote text), `skipped` (declared on the spec but this leg produced no
120
120
  * status for it — the materialization did not reach it). `source` is the DECLARING side's own label
121
121
  * (`McpServerSpec.source`: plugin / user / project / local, or anything the deployment writes),
@@ -129,6 +129,9 @@ export interface WiringManifestMcpEntry {
129
129
  errorCode?: McpFailureKind;
130
130
  delivered?: McpDelivered;
131
131
  httpStatus?: number;
132
+ /** The `unauthorized` failure's authorization fact (`McpAuthorization`): present iff `errorCode === "unauthorized"`, copied whole
133
+ * from the status record (`authorizeUrl` the deployment seat's, `resourceMetadataUrl` the endpoint's own UNTRUSTED claim). */
134
+ authorization?: McpAuthorization;
132
135
  error?: string;
133
136
  /** How many of the server's tools the roster the row is read against holds: a run's roster (the valve and the deployment's
134
137
  * `toolFaces` overlay applied — a tool either one leaves off is not counted), or, for `probeMcpServers` (no run, so no lists),
@@ -583,10 +583,36 @@ function createSummarizationOptions(model, maxTokens, apiKey, headers, signal, t
583
583
  return options;
584
584
  }
585
585
  async function completeSummarization(model, context, options, streamFn, runtime) {
586
- if (streamFn) {
587
- return (await streamFn(model, context, options)).result();
586
+ const call = async () => streamFn ? (await streamFn(model, context, options)).result() : await resolveAgentCoreCompleteFn(runtime)(model, context, options);
587
+ const signal = options.signal;
588
+ if (signal === undefined)
589
+ return await call();
590
+ if (signal.aborted)
591
+ return summaryCallAborted(model);
592
+ let release = () => undefined;
593
+ const cut = new Promise((resolve) => {
594
+ const onAbort = () => resolve(summaryCallAborted(model));
595
+ signal.addEventListener("abort", onAbort, { once: true });
596
+ release = () => signal.removeEventListener("abort", onAbort);
597
+ });
598
+ try {
599
+ return await Promise.race([cut, call()]);
600
+ }
601
+ finally {
602
+ release();
588
603
  }
589
- return await resolveAgentCoreCompleteFn(runtime)(model, context, options);
604
+ }
605
+ function summaryCallAborted(model) {
606
+ return {
607
+ role: "assistant",
608
+ content: [],
609
+ api: model.api,
610
+ provider: model.provider,
611
+ model: model.id,
612
+ usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
613
+ stopReason: "aborted",
614
+ timestamp: Date.now(),
615
+ };
590
616
  }
591
617
  const SUMMARY_REASONING_FLOOR = 2048;
592
618
  const SUMMARY_MAX_ESCALATIONS = 2;
@@ -93,8 +93,8 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
93
93
  get withheldEnv(): readonly SecretEnvFinding[];
94
94
  /** The environment the next shell child would receive, for a READ (the scrub seat is the reader's collector or a
95
95
  * no-op: a read announces nothing). `undefined` when no child would be spawned at all — the policy is refused against
96
- * the own credentials declared since construction, and every spawn throws that reason — so a reader sees "the child
97
- * gets none", never a throw. */
96
+ * the own credentials declared since construction, or `shellEnv` is no grant, and every spawn throws that reason — so
97
+ * a reader sees "the child gets none", never a throw. Composed once: the refusal is the composition's own. */
98
98
  private childEnvForRead;
99
99
  private shellPath?;
100
100
  private shellEnv?;
@@ -118,7 +118,8 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
118
118
  shellEnv?: NodeJS.ProcessEnv;
119
119
  /** VENDORED EDIT (D1, security): how much of `process.env` the shell child inherits. Default `"scrub"` =
120
120
  * fail-closed (drop secret-pattern keys, keep PATH/build/locale). `"all"` = full inherit (trusted env);
121
- * `string[]` = strict allowlist. `shellEnv`/per-exec `env` always pass through. Any other value — an unknown
121
+ * `string[]` = strict allowlist. `shellEnv`/per-exec `env` always pass through (`hostChildEnv`'s grants: one that is
122
+ * not a map of variable names to strings throws here and at the spawn). Any other value — an unknown
122
123
  * word, a non-string, a list entry that is not a variable name — throws here (`inheritEnvPolicyProblem`'s
123
124
  * reason), the same judgment the oracle gate's `inheritEnv` meets. Whatever the policy, the deployment's own
124
125
  * credentials (`declareWithheldEnv`: by name, and by a value equal to a declared or engine-held credential value)
@@ -7,7 +7,7 @@ import { dirname, isAbsolute, join, sep } from "node:path";
7
7
  import { createInterface } from "node:readline";
8
8
  import { ExecutionError, err, FileError, ok, toError, } from "../harness/types.js";
9
9
  import { killProcessTree, shutdownDebug } from "./kill-tree.js";
10
- import { __resetSecretEnvScrubNoticeAnnouncement, announceSecretEnvScrub, inheritEnvPolicyProblem, inheritedHostEnv } from "../../core/secret-env.js";
10
+ import { __resetSecretEnvScrubNoticeAnnouncement, announceSecretEnvScrub, hostChildEnv, hostChildEnvProblem, inheritedHostEnv } from "../../core/secret-env.js";
11
11
  import { physicalPathOfAsync } from "../../core/physical-path.js";
12
12
  import { posixModeBitsMeaningful } from "../../core/posix-mode-face.js";
13
13
  import { anchorAtLinkDir, walkSymlinkChain } from "./symlink-chain.js";
@@ -248,9 +248,7 @@ export function __resetSecretScrubAnnouncement() {
248
248
  __resetSecretEnvScrubNoticeAnnouncement();
249
249
  }
250
250
  function getShellEnv(inheritEnv, baseEnv, extraEnv, onScrub, onNotice) {
251
- const scrubbed = [];
252
- const inherited = inheritedHostEnv(inheritEnv, scrubbed);
253
- const findings = scrubbed.filter((f) => baseEnv?.[f.key] === undefined && extraEnv?.[f.key] === undefined);
251
+ const { env, withheld: findings } = hostChildEnv(inheritEnv, baseEnv, extraEnv);
254
252
  if (findings.length > 0) {
255
253
  if (typeof onScrub === "function") {
256
254
  try {
@@ -275,11 +273,7 @@ function getShellEnv(inheritEnv, baseEnv, extraEnv, onScrub, onNotice) {
275
273
  announceSecretEnvScrub(onNotice, findings);
276
274
  }
277
275
  }
278
- return {
279
- ...inherited,
280
- ...baseEnv,
281
- ...extraEnv,
282
- };
276
+ return env;
283
277
  }
284
278
  const EXIT_SETTLE_DRAIN_MS = 500;
285
279
  const EXEC_SPOOL_PUMP_MS = 200;
@@ -333,9 +327,12 @@ export class NodeExecutionEnv {
333
327
  return withheld;
334
328
  }
335
329
  childEnvForRead(collect = () => { }) {
336
- if (inheritEnvPolicyProblem(this.inheritEnv) !== undefined)
330
+ try {
331
+ return getShellEnv(this.inheritEnv, this.shellEnv, undefined, collect);
332
+ }
333
+ catch {
337
334
  return undefined;
338
- return getShellEnv(this.inheritEnv, this.shellEnv, undefined, collect);
335
+ }
339
336
  }
340
337
  shellPath;
341
338
  shellEnv;
@@ -353,7 +350,7 @@ export class NodeExecutionEnv {
353
350
  this.cwd = options.cwd;
354
351
  this.shellPath = options.shellPath;
355
352
  this.shellEnv = options.shellEnv;
356
- const inheritEnvProblem = inheritEnvPolicyProblem(options.inheritEnv);
353
+ const inheritEnvProblem = hostChildEnvProblem(options.inheritEnv, options.shellEnv);
357
354
  if (inheritEnvProblem !== undefined)
358
355
  throw new Error(`NodeExecutionEnv: ${inheritEnvProblem}`);
359
356
  this.inheritEnv = Array.isArray(options.inheritEnv) ? [...options.inheritEnv] : (options.inheritEnv ?? "scrub");
@@ -1,5 +1,6 @@
1
1
  import type { ActorAssertion, AssistantMessage, ImageContent, Model, TextContent, UserMessage, UserMessageAttachment } from "../llm/index.js";
2
2
  import { type ToolTurnRepair } from "../llm/index.js";
3
+ import { type RejectedImageRemoval } from "../llm/rejected-images.js";
3
4
  import { runToolCall, type ExecutedToolCallOutcome } from "../loop/agent-loop.js";
4
5
  import type { HaltRemainingDirective } from "../loop/types.js";
5
6
  import type { AgentMessage, AgentTool, AgentToolCall, LoopMalformedToolUseRecovery, LoopThinkingOnlyRecovery, LoopTruncatedOutputRecovery, QueueMode, ThinkingLevel } from "../loop/types.js";
@@ -214,6 +215,13 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
214
215
  * with every request view that needed one (the transcript is never rewritten, so a broken turn is repaired, and
215
216
  * reported, on each request; the sink owns its dedup). Advisory: a throwing sink never breaks the request. */
216
217
  onToolTurnRepaired?: (repairs: readonly ToolTurnRepair[]) => void;
218
+ /** Runner-set sink for the images a provider refused in THIS run ({@link removeRejectedImages}) — a refusal recorded
219
+ * before the run began is not reported. Every request re-reads the transcript, so the sink owns its dedup (by
220
+ * `refusalAt`). Advisory: a throwing sink never breaks the request. */
221
+ onImagesRemoved?: (removals: readonly RejectedImageRemoval[]) => void;
222
+ /** The image refusals standing in the transcript when the current run began, by their identity
223
+ * ({@link RejectedImageRemoval.refusalAt}): the run that met them announced them. */
224
+ private priorImageRefusals?;
217
225
  /** The assistant messages standing in the transcript when the current run began — what the request view reads as
218
226
  * "before this run" (a message is the run's own unless it is in here). */
219
227
  private runHistory?;
@@ -222,10 +230,16 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
222
230
  * hands ENGINE payloads back for redelivery; user inputs have no redelivery semantics (a steer
223
231
  * aimed at a finished run must not silently fire at the next one), so their loss is ANNOUNCED
224
232
  * instead — the runner surfaces it as an operator notice, closing the "accepted then silently
225
- * dropped" window the #257 contract could only document. */
233
+ * dropped" window the #257 contract could only document. The second argument hands over the OPAQUE park records of the
234
+ * counted inputs that carried one, per lane in service order — the order the queue would serve them, so an
235
+ * `immediate`-class input leads the ones accepted before it (never interpreted here; the runner reads which input each
236
+ * is) — a lane's list shorter than its count means some counted input had none. */
226
237
  onUndrainedUserInputs?: (counts: {
227
238
  steer: number;
228
239
  followUp: number;
240
+ }, parkRecords?: {
241
+ steer: readonly unknown[];
242
+ followUp: readonly unknown[];
229
243
  }) => void;
230
244
  /** design/176 — runner-set sink fired at the CONSUMPTION boundary, once per engine-note payload,
231
245
  * in consumption order (steer/followUp drain and the turn-open nextTurn splice — the two points
@@ -262,6 +276,9 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
262
276
  * minted it. */
263
277
  engineInjectionsHeld?: () => boolean;
264
278
  /** The provider boundary's tool-turn law: the repaired view goes to the brain, the repairs to the runner's sink. */
279
+ /** The request view of `messages` under the provider's image refusals they hold ({@link removeRejectedImages}), and
280
+ * the removals this run met handed to {@link onImagesRemoved}. */
281
+ private imageRefusalView;
265
282
  private holdToolTurnLaw;
266
283
  /** RB-30 R2 belt-and-braces: runner-callable idempotent recovery for exit paths that reach
267
284
  * neither agent_end nor abort() (a pre-prompt throw after prepare). Swept entries are removed,
@@ -281,6 +298,7 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
281
298
  * frames are excluded, and the IN-FLIGHT slot counts (a frame spliced out of a queue and never injected
282
299
  * is as pending as one that never left it).
283
300
  */
301
+ private pendingUserInputFramesByLane;
284
302
  private pendingUserInputsByLane;
285
303
  /**
286
304
  * Is a PERSON's input waiting for this run's NEXT TURN BOUNDARY? The live read face over
@@ -637,11 +655,16 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
637
655
  * on a checkpoint, so their live frames leave the queues (identity-matched on the sidecar). Dropping
638
656
  * them here is what keeps the terminal `#259` account honest — a migrated instruction is not "accepted
639
657
  * then lost", and one this is never called for (a failed commit) still gets its loud undrained notice.
640
- * Returns the per-lane drop counts so the caller can subtract them from an account already taken.
658
+ * Returns the per-lane drop counts so the caller can subtract them from an account already taken, and the dropped
659
+ * records themselves per lane (opaque, in the order the queues held them) so it can subtract by identity too.
641
660
  */
642
661
  dropParkedUserInputs(records: readonly unknown[]): {
643
662
  steer: number;
644
663
  followUp: number;
664
+ records: {
665
+ steer: unknown[];
666
+ followUp: unknown[];
667
+ };
645
668
  };
646
669
  /**
647
670
  * backlog #389 (`control_request:"interrupt"`) — an interrupt does
@@ -1,4 +1,5 @@
1
1
  import { createAssistantMessageEventStream, ensureToolTurnInvariants, findToolByName, snapshotActorAssertion, stripEngineMetadata, userAttachmentOf } from "../llm/index.js";
2
+ import { imageRefusalAt, isImageRefusal, removeRejectedImages } from "../llm/rejected-images.js";
2
3
  import { finalizeToolOutcome, isBatchSafeToolCall, runAgentLoop, runToolCall } from "../loop/agent-loop.js";
3
4
  import { resolveAgentCoreStreamFn } from "../loop/runtime-deps.js";
4
5
  import { normalizeEngineSegments } from "../../core/untrusted-text.js";
@@ -224,12 +225,26 @@ export class AgentHarness {
224
225
  thinkingLevel;
225
226
  onUndrainedEngineNotes;
226
227
  onToolTurnRepaired;
228
+ onImagesRemoved;
229
+ priorImageRefusals;
227
230
  runHistory;
228
231
  onUndrainedUserInputs;
229
232
  onEngineNoteConsumed;
230
233
  onUserInputConsumed;
231
234
  onFrameCommitted;
232
235
  engineInjectionsHeld;
236
+ imageRefusalView(messages) {
237
+ const view = removeRejectedImages(messages);
238
+ const met = view.removals.filter((r) => this.priorImageRefusals?.has(r.refusalAt) !== true);
239
+ if (met.length > 0) {
240
+ try {
241
+ this.onImagesRemoved?.(met);
242
+ }
243
+ catch {
244
+ }
245
+ }
246
+ return view.messages;
247
+ }
233
248
  holdToolTurnLaw(messages) {
234
249
  const view = ensureToolTurnInvariants(messages, this.runHistory);
235
250
  if (view.repairs.length > 0) {
@@ -264,13 +279,17 @@ export class AgentHarness {
264
279
  }
265
280
  }
266
281
  }
267
- pendingUserInputsByLane() {
268
- const inFlight = (lane) => this.drainedPendingInjection.filter((m) => !engineAuthoredInjections.has(m) && drainedFromLane.get(m) === lane).length;
282
+ pendingUserInputFramesByLane() {
283
+ const inFlight = (lane) => this.drainedPendingInjection.filter((m) => !engineAuthoredInjections.has(m) && drainedFromLane.get(m) === lane);
269
284
  return {
270
- steer: this.steerQueue.filter((m) => !engineAuthoredInjections.has(m)).length + inFlight("steer"),
271
- followUp: this.followUpQueue.filter((m) => !engineAuthoredInjections.has(m)).length + inFlight("followUp"),
285
+ steer: [...inFlight("steer"), ...this.steerQueue.filter((m) => !engineAuthoredInjections.has(m))],
286
+ followUp: [...inFlight("followUp"), ...this.followUpQueue.filter((m) => !engineAuthoredInjections.has(m))],
272
287
  };
273
288
  }
289
+ pendingUserInputsByLane() {
290
+ const frames = this.pendingUserInputFramesByLane();
291
+ return { steer: frames.steer.length, followUp: frames.followUp.length };
292
+ }
274
293
  hasPendingUserInput() {
275
294
  if (this.aborting)
276
295
  return false;
@@ -280,7 +299,12 @@ export class AgentHarness {
280
299
  const counts = this.pendingUserInputsByLane();
281
300
  if ((counts.steer > 0 || counts.followUp > 0) && this.onUndrainedUserInputs) {
282
301
  try {
283
- this.onUndrainedUserInputs(counts);
302
+ const frames = this.pendingUserInputFramesByLane();
303
+ const records = (lane) => lane.flatMap((m) => {
304
+ const r = userInputParkRecords.get(m);
305
+ return r !== undefined ? [r] : [];
306
+ });
307
+ this.onUndrainedUserInputs(counts, { steer: records(frames.steer), followUp: records(frames.followUp) });
284
308
  }
285
309
  catch {
286
310
  }
@@ -671,17 +695,19 @@ export class AgentHarness {
671
695
  shouldStopAfterTurn: () => this.consultStopLatch("post_turn"),
672
696
  shouldHaltBeforeTurn: () => this.consultStopLatch("pre_turn"),
673
697
  transformContext: async (messages, signal) => {
674
- const result = await this.emitHook({ type: "context", messages: [...messages], ...(signal !== undefined ? { signal } : {}) });
698
+ const view = this.imageRefusalView(messages);
699
+ const result = await this.emitHook({ type: "context", messages: [...view], ...(signal !== undefined ? { signal } : {}) });
675
700
  if (result?.adoptSessionRebuild !== true) {
676
- return result?.messages ?? messages;
701
+ return result?.messages ?? view;
677
702
  }
678
703
  await this.flushPendingSessionWrites();
679
704
  const nextTurnState = await this.createTurnState();
680
705
  setTurnState(nextTurnState);
681
706
  const rebuiltContext = this.createContext(nextTurnState, runPromptOverride);
682
- const recheck = await this.emitHook({ type: "context", messages: [...rebuiltContext.messages], ...(signal !== undefined ? { signal } : {}), recheck: true });
707
+ const rebuiltView = this.imageRefusalView(rebuiltContext.messages);
708
+ const recheck = await this.emitHook({ type: "context", messages: [...rebuiltView], ...(signal !== undefined ? { signal } : {}), recheck: true });
683
709
  return {
684
- messages: recheck?.messages ?? rebuiltContext.messages,
710
+ messages: recheck?.messages ?? rebuiltView,
685
711
  adoptedContext: {
686
712
  messages: rebuiltContext.messages,
687
713
  systemPrompt: rebuiltContext.systemPrompt,
@@ -830,7 +856,7 @@ export class AgentHarness {
830
856
  usageMissing: true,
831
857
  stopReason: "error",
832
858
  ...(typeof errorMessage === "string" ? { errorMessage } : {}),
833
- ...(errorKind === "length_empty" || errorKind === "degenerate" || errorKind === "input_too_long" ? { errorKind } : {}),
859
+ ...(errorKind === "length_empty" || errorKind === "degenerate" || errorKind === "input_too_long" || errorKind === "image_unprocessable" ? { errorKind } : {}),
834
860
  timestamp: failure.timestamp,
835
861
  };
836
862
  try {
@@ -920,6 +946,7 @@ export class AgentHarness {
920
946
  this.promptReceipt = options?.onCommitted !== undefined ? { message: userMessage, commit: options.onCommitted } : undefined;
921
947
  const trailingMessages = (options?.trailing ?? []).map(createTrailingMessage);
922
948
  this.runHistory = new WeakSet(turnState.messages.filter((m) => m.role === "assistant"));
949
+ this.priorImageRefusals = new Set(turnState.messages.filter(isImageRefusal).map(imageRefusalAt));
923
950
  const beforeResult = await this.emitHook({
924
951
  type: "before_agent_start",
925
952
  prompt: text,
@@ -1430,7 +1457,7 @@ export class AgentHarness {
1430
1457
  return out;
1431
1458
  }
1432
1459
  dropParkedUserInputs(records) {
1433
- const dropped = { steer: 0, followUp: 0 };
1460
+ const dropped = { steer: 0, followUp: 0, records: { steer: [], followUp: [] } };
1434
1461
  if (records.length === 0)
1435
1462
  return dropped;
1436
1463
  const migrated = new Set(records);
@@ -1445,8 +1472,10 @@ export class AgentHarness {
1445
1472
  userInputParkRecords.delete(frame);
1446
1473
  q.splice(i, 1);
1447
1474
  i--;
1448
- if (lane !== undefined)
1475
+ if (lane !== undefined) {
1449
1476
  dropped[lane] += 1;
1477
+ dropped.records[lane].push(record);
1478
+ }
1450
1479
  }
1451
1480
  }
1452
1481
  return dropped;
@@ -26,5 +26,7 @@ export declare const NORMALIZED_CONTENT_PREFIX = "[invalid content block normali
26
26
  * `convertToLlm` (provider leg) and `serializeConversation` (compaction leg) — one helper, two mouths.
27
27
  */
28
28
  export declare function normalizeLlmMessageContent<T extends Message>(message: T): T;
29
- /** Convert harness transcript messages into the LLM-facing message sequence. */
29
+ /** Convert harness transcript messages into the LLM-facing message sequence. A provider's image refusal (live or its
30
+ * record) removes the images it refused ({@link removeRejectedImages}) for every leg — provider and compaction alike;
31
+ * the request leg applies it earlier, where its view starts, so there this pass is the identity. */
30
32
  export declare function convertToLlm(messages: AgentMessage[]): Message[];
@@ -1,4 +1,5 @@
1
1
  import { isSyntheticApiErrorMessage } from "./types.js";
2
+ import { removeRejectedImages } from "../llm/rejected-images.js";
2
3
  import { parseSessionTimestampMs, requireSessionTimestampMs } from "../session/timestamps.js";
3
4
  export function asAgentMessage(message) {
4
5
  return message;
@@ -107,8 +108,8 @@ export function normalizeLlmMessageContent(message) {
107
108
  return changed ? { ...message, content: blocks } : message;
108
109
  }
109
110
  export function convertToLlm(messages) {
110
- return messages
111
- .map((m) => {
111
+ return removeRejectedImages(messages)
112
+ .messages.map((m) => {
112
113
  const message = m;
113
114
  switch (message.role) {
114
115
  case "bashExecution":
@@ -340,6 +340,14 @@ export interface ExecutionEnvExecOptions {
340
340
  * behavior. Envs without detach support ignore this (opt-in, backward compatible).
341
341
  */
342
342
  autoBackgroundOnTimeout?: boolean;
343
+ /** VENDORED EDIT (the byte floor) — the read-deny table in force for the call starting this command ({@link ReadFloor}); what its processes OPEN is the environment's to keep. */
344
+ readFloor?: ReadFloor;
345
+ }
346
+ /** The read-deny table one command start carries ({@link ExecutionEnvExecOptions.readFloor}); what an environment keeps of it is INTEGRATION-CORE §11.1. */
347
+ export interface ReadFloor {
348
+ readonly rows: readonly string[];
349
+ /** The row denying an absolute path in this environment's namespace, or `null`: the read station's own judgment. Never throws. */
350
+ denies(absolutePath: string): string | null;
343
351
  }
344
352
  /**
345
353
  * Filesystem capability used by the harness.
@@ -0,0 +1,46 @@
1
+ /**
2
+ * The request view's reading of a provider's image refusal — restored on the way to the brain, never in the transcript.
3
+ *
4
+ * A turn the provider failed with `errorKind: "image_unprocessable"` (an image in the request could not be processed;
5
+ * classified at the brain boundary off the provider's envelope) is a MARKER, live in the loop's context and persisted
6
+ * as the transcript's API-failure record alike. Reading the messages in order, each marker:
7
+ * - replaces every image of the NEWEST earlier message that still carries one (a user message, a tool result, a
8
+ * custom message — never an assistant's) by a text block saying which image was removed and why;
9
+ * - leaves the view itself (a failure is not model output).
10
+ * An earlier marker has already emptied its carrier, so a second marker reaches the next older one: the request that
11
+ * failed loses one carrier's images per refusal, and a provider that names no position is still answered (the newest
12
+ * carrier is the one the failed request added last). Nothing else moves; messages without a marker before them are
13
+ * the same objects, and a view with no marker is the same array — the same transcript yields the same request bytes.
14
+ *
15
+ * The transcript keeps the images: a later reader of the session sees what was read, and every request built from it
16
+ * — the next turn, a resumed session, a compaction summary — reads the same record and removes the same images.
17
+ */
18
+ /** The `errorKind` a provider's image refusal carries (`AssistantMessage.errorKind`). */
19
+ export declare const IMAGE_REFUSAL_KIND = "image_unprocessable";
20
+ /** The text that stands in for the `ordinal`-th image (1-based) of a carrier the provider refused an image of. */
21
+ export declare function rejectedImagePlaceholder(ordinal: number): string;
22
+ /** Is this message a turn the provider failed because an image in the request could not be processed — the live
23
+ * failure or its persisted record? */
24
+ export declare function isImageRefusal(message: unknown): boolean;
25
+ /** One carrier whose images a marker removed: the marker, the carrier (both the view's input objects), how many, and
26
+ * the refusal's own time — the one identity a refusal keeps across its live failure, its persisted record and every
27
+ * rebuilt copy of either (the record is minted with the failure's timestamp). */
28
+ export interface RejectedImageRemoval {
29
+ readonly marker: object;
30
+ readonly carrier: object;
31
+ readonly images: number;
32
+ readonly refusalAt: number;
33
+ }
34
+ /** A refusal's identity ({@link RejectedImageRemoval.refusalAt}). */
35
+ export declare function imageRefusalAt(message: unknown): number;
36
+ /**
37
+ * The request view of `messages` under every image refusal they hold ({@link isImageRefusal}): each marker removed and
38
+ * the images of its carrier replaced. `removals` lists, in order, the carriers emptied — empty when no marker found
39
+ * an image to remove.
40
+ */
41
+ export declare function removeRejectedImages<T>(messages: readonly T[]): {
42
+ messages: T[];
43
+ removals: RejectedImageRemoval[];
44
+ };
45
+ /** Does `marker`, standing in `messages`, remove images in their request view — was there a carrier left for it? */
46
+ export declare function imageRefusalRemoves(messages: readonly unknown[], marker: object): boolean;
@@ -0,0 +1,54 @@
1
+ export const IMAGE_REFUSAL_KIND = "image_unprocessable";
2
+ export function rejectedImagePlaceholder(ordinal) {
3
+ return `[image ${ordinal} removed: rejected by provider: ${IMAGE_REFUSAL_KIND}]`;
4
+ }
5
+ export function isImageRefusal(message) {
6
+ const m = message;
7
+ return m?.role === "assistant" && m.isApiErrorMessage === true && m.errorKind === IMAGE_REFUSAL_KIND;
8
+ }
9
+ export function imageRefusalAt(message) {
10
+ const at = message?.timestamp;
11
+ return typeof at === "number" ? at : Number.NaN;
12
+ }
13
+ function imageCount(message) {
14
+ const m = message;
15
+ if (m === null || m === undefined || m.role === "assistant" || !Array.isArray(m.content))
16
+ return 0;
17
+ let n = 0;
18
+ for (const block of m.content)
19
+ if (block?.type === "image")
20
+ n++;
21
+ return n;
22
+ }
23
+ function withoutImages(message) {
24
+ let ordinal = 0;
25
+ const content = message.content.map((block) => block?.type === "image" ? { type: "text", text: rejectedImagePlaceholder(++ordinal) } : block);
26
+ return { ...message, content };
27
+ }
28
+ export function removeRejectedImages(messages) {
29
+ if (!messages.some(isImageRefusal))
30
+ return { messages: messages, removals: [] };
31
+ const out = [];
32
+ const carriers = [];
33
+ const removals = [];
34
+ for (const m of messages) {
35
+ if (!isImageRefusal(m)) {
36
+ out.push(m);
37
+ carriers.push(undefined);
38
+ continue;
39
+ }
40
+ for (let j = out.length - 1; j >= 0; j--) {
41
+ const images = imageCount(out[j]);
42
+ if (images === 0)
43
+ continue;
44
+ removals.push({ marker: m, carrier: (carriers[j] ?? out[j]), images, refusalAt: imageRefusalAt(m) });
45
+ carriers[j] = (carriers[j] ?? out[j]);
46
+ out[j] = withoutImages(out[j]);
47
+ break;
48
+ }
49
+ }
50
+ return { messages: out, removals };
51
+ }
52
+ export function imageRefusalRemoves(messages, marker) {
53
+ return removeRejectedImages(messages).removals.some((r) => r.marker === marker);
54
+ }
@@ -73,7 +73,8 @@ export type DropsTableCoversEveryForm = AssertAllKeysHandled<Exclude<ToolTurnRep
73
73
  * view of facts the model is already told in the turn itself. Closed:
74
74
  * · `truncated` — calls whose argument bytes were cut before they parsed: dropped, the model asked to re-issue them;
75
75
  * · `unnamed` — calls that arrived with no tool name: dropped the same way;
76
- * · `bad_frame` — provider stream frames that were not valid JSON: dropped, so the response may be missing content;
76
+ * · `bad_frame` — provider stream frames that were not valid JSON, or held members in no shape the stream defines:
77
+ * what could not be read was dropped, so the response may be missing content;
77
78
  * · `missing_result_synthesized` — a call with no recorded result, closed in the request view as interrupted with its
78
79
  * outcome unknown (the `missing_result` repair).
79
80
  * The first three are a brain's stream facts ({@link StreamDropCause}), stamped on the turn's own message; the fourth is
@@ -601,8 +601,15 @@ export interface AssistantMessage {
601
601
  * twin). The loop's prompt-too-long recovery reads THIS seat first; the historic prose regex
602
602
  * over `errorMessage` remains as the fallback for brains that do not stamp it (additive — the
603
603
  * stamping obligation above extends to this member for cuts a Brain can classify structurally,
604
- * but unlike the two cut kinds there is no retired fallback: prose detection still works). */
605
- errorKind?: "length_empty" | "degenerate" | "input_too_long";
604
+ * but unlike the two cut kinds there is no retired fallback: prose detection still works).
605
+ *
606
+ * `"image_unprocessable"`: the provider refused the request because an image in it could not be processed
607
+ * (it does not decode, its type does not match its bytes, its pixels exceed the model's limit) — classified at the
608
+ * brain boundary off the provider's envelope (`brain/provider-dialect.ts`, `IMAGE_UNPROCESSABLE_RE`). Such a turn —
609
+ * live, or as the transcript's persisted record of it — is the request view's instruction to remove the images of
610
+ * the newest earlier message still carrying any (`engine/llm/rejected-images.ts`, at `convertToLlm`); the loop
611
+ * re-sends the turn without them. */
612
+ errorKind?: "length_empty" | "degenerate" | "input_too_long" | "image_unprocessable";
606
613
  /** The AUTHORITATIVE-NEGATIVE twin of `errorKind: "input_too_long"`: the brain's provenance-checked
607
614
  * classifier RAN and ruled this failure NOT input-too-long (wrong status family, or the provider's
608
615
  * own envelope states a different error). The loop's prompt-too-long recovery treats it as a hard
@@ -631,8 +638,9 @@ export interface AssistantMessage {
631
638
  * trailing call was already dropped by the finalize malformed path). Additive — absent everywhere else.
632
639
  */
633
640
  partialFinalized?: true;
634
- /** A stream-end word (`finish_reason`) outside the set the brain reads, in the echo shape (`?` past it): the turn
635
- * is kept, the Runner announces it (`route.finish_reason_unknown`), a completed run states it on `terminal.detail`. */
641
+ /** A stream-end word (`finish_reason`) outside the set the brain reads, in the echo shape (`?` past it, and `?` for an
642
+ * ending seat — `finish_reason` / `stop_reason` — that held no word at all): the turn is kept, the Runner announces it
643
+ * (`route.finish_reason_unknown`), a completed run states it on `terminal.detail`. */
636
644
  finishReasonUnknown?: string;
637
645
  /** Frames after the stream's first terminal statement (which decided this turn) that were not acted on — a later
638
646
  * ending (finish / stop reason), error or content — announced by the Runner (`route.stream_end_ignored`): the
@@ -1040,12 +1048,15 @@ export interface ImagesModel<TApi extends ImagesApi = ImagesApi> extends Omit<Mo
1040
1048
  /** The resolved credential a request would carry, tagged with its source (see {@link RouteCredentialSource}). */
1041
1049
  export interface RouteCredential {
1042
1050
  source: RouteCredentialSource;
1043
- /** The key itself, when the credential rides the apiKey knob. An EMPTY string is a present (per-call)
1044
- * credential that fails closed at emit time — presence, not truthiness (the degraded-secret contract). */
1051
+ /** The key the request carries in its lane's key header, when the credential rides the apiKey knob — never blank as
1052
+ * `resolveRouteCredential` resolves it. A BLANK key handed over (the empty string, or white space only —
1053
+ * `isBlankCredential`) is the keyless door: its source keeps its rank, so a lower source's credential never rides in
1054
+ * its place, and the resolved credential has no `apiKey` (`{ source: "per-model" }` carries nothing). */
1045
1055
  apiKey?: string;
1046
1056
  /** True when the credential rides (also) as credential HEADERS (`isCredentialHeaderName`: `authorization`,
1047
1057
  * `x-api-key`, `api-key`, a gateway's `Helicone-Auth`, …, any case) — alone, or beside the apiKey knob when one
1048
- * source sets both. The winning bag is named by {@link RouteCredential.carrierBag}. */
1058
+ * source sets both — and one of them holds a value that is not blank (a bag of blank credential headers keeps its
1059
+ * rank and rides nothing). The winning bag is named by {@link RouteCredential.carrierBag}. */
1049
1060
  headersBorne?: boolean;
1050
1061
  /** Which header bag carries a headers-borne credential (resolution precedence: options > model > config, one rank
1051
1062
  * per source; within the hook's answer (`options`) and within the deployment config (`config`) the knob and the
@@ -36,6 +36,8 @@ export type LoopContinueReason =
36
36
  | "follow_up_injected"
37
37
  /** ④b recovery: a prompt-too-long failure was recovered (compacted context) and retried in-turn. */
38
38
  | "reactive_compact_retry"
39
+ /** The provider refused an image; the request view removed it and the turn was re-sent in-turn. */
40
+ | "image_refusal_retry"
39
41
  /** ④b recovery: a `length`-stopped answer triggered a synthetic continue nudge for another turn. */
40
42
  | "max_output_tokens_recovery"
41
43
  /** S2 recovery (design/119): a `toolUse` stop with ZERO parseable tool calls got a retry nudge. */
@@ -172,11 +174,17 @@ export declare function isBatchSafeToolCall(tool: AgentTool | undefined, toolCal
172
174
  export type ExecutedToolCallOutcome = {
173
175
  result: AgentToolResult<unknown>;
174
176
  isError: boolean;
177
+ /** Present (`true`) exactly when the call's body never started: the run was aborted between the gate and the body, or the host's
178
+ * execution station ({@link AgentLoopConfig.executeTool}) settled the call without running it. Rides the end event as
179
+ * `notExecuted`, like {@link ImmediateToolCallOutcome.notExecuted}. */
180
+ notExecuted?: true;
175
181
  };
176
182
  type FinalizedToolCallOutcome = {
177
183
  toolCall: AgentToolCall;
178
184
  result: AgentToolResult<unknown>;
179
185
  isError: boolean;
186
+ /** The loop's own mark that the call settled without its body starting (see {@link ImmediateToolCallOutcome.notExecuted}); rides the end event. */
187
+ notExecuted?: true;
180
188
  };
181
189
  /**
182
190
  * THE reading a value gets on its way to becoming a call's arguments: the tool's own preparation (`prepareArguments` —