@agent-native/core 0.224.0-nightly-20261104110058 → 0.224.0

package/dist/action-frame.d.ts

@@ -1,7 +1,9 @@
 /**
  * The execution frame each action invocation runs in, and the evidence a
  * dispatcher vouched for that one invocation. Not in the package exports: the
- * action entry exposes no frame-evidence helpers, and request input or
+ * action entry exposes no frame-evidence helpers but `noteExternalWrite`, which
+ * can only add observed-write evidence, and `withoutWriteObservation`, which
+ * can only keep a write from being counted. Request input or
  * `ActionRunContext` fields never become evidence. Trusted server dispatcher
  * APIs (`executeAgentToolCall`, `runAgentLoop`) can still supply approval and
  * attribution. Nothing here imports `action.ts` at runtime, so `action.ts` and
@@ -36,6 +38,10 @@ export type ActionExecutionFrame = {
     writeEntered: boolean;
     /** One of those writes publishes action changes. */
     changeEntered: boolean;
+    /** This call, or one nested in it, was seen to write. */
+    writeObserved: boolean;
+    /** Which channel saw it first, for diagnostics. */
+    writeObservedChannel?: string;
     /** This call's classification, once validated arguments set it. */
     writes?: boolean;
     emitsChange?: boolean;
@@ -44,6 +50,8 @@ export type ActionExecutionFrame = {
     record?: ActionCallRecord;
     context?: ActionRunContext;
     nestedWriteEntered?: boolean;
+    /** The write was seen in a call nested in this one, not this call's own. */
+    nestedWriteObserved?: boolean;
     raised?: unknown;
     /** The dispatcher's outcome, which takes the record as it is made. */
     outcome?: ActionExecutionOutcome;
@@ -71,3 +79,29 @@ export declare function currentInvocationEvidence(): ActionInvocationEvidence |
  * another call is recorded here.
  */
 export declare function runOutsideActionInvocation<T>(fn: () => T): T;
+/**
+ * Whether a write seen now would add evidence: not outside a call, not inside
+ * bookkeeping, and not once the call has already seen one. Lets a caller skip
+ * work it would only do to classify a write.
+ */
+export declare function observingWrites(): boolean;
+/**
+ * Record that the running call, and every call it runs inside, was seen to
+ * write through `channel`. Call it before the write is sent: a write still in
+ * flight when its failure arrives must already count. Evidence is only added,
+ * never cleared.
+ */
+export declare function noteObservedWrite(channel: string): void;
+/**
+ * Run the framework's own bookkeeping, such as an audit row, a change marker or
+ * an analytics event, without it counting as a write of the call it runs
+ * inside. Scoped to that call's frame, so an action it runs still records its
+ * own writes. Use it only for bookkeeping, or for a write a retry provably
+ * cannot repeat, such as one keyed by a deterministic id or a dedup key. Never
+ * wrap a write the call exists to make: a failure after it would read as
+ * having saved nothing, and the agent would repeat it. The callback must await
+ * the work inside itself: a Drizzle query builder is a thenable that runs when
+ * awaited, after the callback returned, so `() => db.insert(t).values(v)`
+ * exempts nothing.
+ */
+export declare function withoutWriteObservation<T>(fn: () => T): T;

package/dist/action-frame.js

@@ -8,6 +8,10 @@ const ActionExecutionStorage = getAsyncLocalStorageCtor();
 export const actionExecutionStorage = ActionExecutionStorage
     ? new ActionExecutionStorage()
     : undefined;
+/** The frame whose writes are not observed, for the work that runs inside it. */
+const unobservedFrame = ActionExecutionStorage
+    ? new ActionExecutionStorage()
+    : undefined;
 /** Evidence vouched for a run, until that run opens its frame. */
 const vouched = new WeakMap();
 /** Each frame's evidence, until its invocation settles. */
@@ -53,3 +57,49 @@ export function runOutsideActionInvocation(fn) {
         return fn();
     return actionExecutionStorage.run({ failures: state.failures }, fn);
 }
+/**
+ * Whether a write seen now would add evidence: not outside a call, not inside
+ * bookkeeping, and not once the call has already seen one. Lets a caller skip
+ * work it would only do to classify a write.
+ */
+export function observingWrites() {
+    const frame = actionExecutionStorage?.getStore()?.frame;
+    return (frame !== undefined &&
+        !frame.writeObserved &&
+        unobservedFrame?.getStore() !== frame);
+}
+/**
+ * Record that the running call, and every call it runs inside, was seen to
+ * write through `channel`. Call it before the write is sent: a write still in
+ * flight when its failure arrives must already count. Evidence is only added,
+ * never cleared.
+ */
+export function noteObservedWrite(channel) {
+    const frame = actionExecutionStorage?.getStore()?.frame;
+    if (!frame || unobservedFrame?.getStore() === frame)
+        return;
+    for (let f = frame; f; f = f.parent) {
+        f.writeObserved = true;
+        f.writeObservedChannel ??= channel;
+        if (f !== frame)
+            f.nestedWriteObserved = true;
+    }
+}
+/**
+ * Run the framework's own bookkeeping, such as an audit row, a change marker or
+ * an analytics event, without it counting as a write of the call it runs
+ * inside. Scoped to that call's frame, so an action it runs still records its
+ * own writes. Use it only for bookkeeping, or for a write a retry provably
+ * cannot repeat, such as one keyed by a deterministic id or a dedup key. Never
+ * wrap a write the call exists to make: a failure after it would read as
+ * having saved nothing, and the agent would repeat it. The callback must await
+ * the work inside itself: a Drizzle query builder is a thenable that runs when
+ * awaited, after the callback returned, so `() => db.insert(t).values(v)`
+ * exempts nothing.
+ */
+export function withoutWriteObservation(fn) {
+    const frame = actionExecutionStorage?.getStore()?.frame;
+    if (!frame || !unobservedFrame)
+        return fn();
+    return unobservedFrame.run(frame, fn);
+}

package/dist/action.d.ts

@@ -1,6 +1,6 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 import { actionCallReadOnly, type ActionCallClassification } from "./action-call-classification.js";
-import { ACTION_EXECUTION_KEY, type ActionExecutionRun } from "./action-frame.js";
+import { ACTION_EXECUTION_KEY, withoutWriteObservation, type ActionExecutionRun } from "./action-frame.js";
 import { type ActionMcpOutputContract } from "./action-output-contract.js";
 import { type ActionChatUIConfig } from "./action-ui.js";
 import type { ActionTool, AgentChatAttachment, AgentChatEvent } from "./agent/types.js";
@@ -9,7 +9,7 @@ import { type ActionAccessConfig } from "./authorization/action-access-runtime.j
 import { type JsonValueWriter } from "./json-schema/json-value.js";
 export { ACTION_RECEIPT_SCHEMA_VERSION, DOMAIN_EVENT_CONTENT_TYPE, DOMAIN_EVENT_SPEC_VERSION, ActionReceiptValidationError, assertActionDomainEvent, assertActionReceipt, commitAction, createActionDomainEvent, parseActionDomainEvent, parseActionReceipt, serializeActionDomainEvent, serializeActionReceipt, } from "./action-receipt.js";
 export type { ActionAtomicAdapter, ActionAtomicContext, ActionAtomicOutcome, ActionDomainEvent, ActionDomainEventDraft, ActionDomainEventReference, ActionJsonPrimitive, ActionJsonValue, ActionReceipt, ActionReceiptProvenance, CommitActionOptions, } from "./action-receipt.js";
-export { ACTION_EXECUTION_KEY };
+export { ACTION_EXECUTION_KEY, withoutWriteObservation };
 /**
  * Records a call refused before its run, for arguments its caller found
  * invalid, as the action's own validation failure would be recorded: through
@@ -139,13 +139,14 @@ export interface ActionErrors<TCode extends string> {
 }
 export declare function defineActionErrors<const TCode extends string>(...codes: [TCode, ...TCode[]]): ActionErrors<TCode>;
 /**
- * A rejection raised before the action's first write: a missing target, an
- * edit that matches nothing, a patch identical to what is saved. A caller may
- * then retry with corrected arguments instead of treating the call as
- * possibly applied. The framework accepts the claim only for the call that
- * raised it, and only when no write action nested in that call entered its
- * handler; otherwise it reads as any other failure. It cannot see the
- * handler's own database or provider writes, so throw it before the first.
+ * A rejection raised before the action saved anything that matters, so a
+ * caller can retry with corrected arguments. The framework reads a failure
+ * from the writes it saw, so most rejections need no label. This one is an
+ * override that wins over an observed write, for example when the only thing
+ * written first is something a retry harmlessly repeats, such as uploads
+ * nobody has referenced yet. The framework accepts the claim only for the call
+ * that raised it, and only when no write action nested in that call entered
+ * its handler; otherwise it reads as any other failure.
  */
 export declare class NoWriteError extends ActionContractError {
     readonly noWrite = true;
@@ -187,6 +188,15 @@ export declare function isActionOutputContractError(error: unknown): error is Ac
  * the call changed nothing.
  */
 export declare function actionFailureEffect(error: unknown): ActionOutputEffect | undefined;
+/**
+ * Record that the running action call wrote somewhere the framework cannot
+ * watch, such as a socket, a file or a vendor SDK that does not use `fetch`, so
+ * that a later failure of the call is not read as one that saved nothing. Call
+ * it before the write is sent. It only adds evidence: nothing it records can be
+ * cleared, and outside an action call it does nothing. Database writes and
+ * `fetch` requests that are not GET, HEAD or OPTIONS need no call.
+ */
+export declare function noteExternalWrite(channel: string): void;
 /** What a dispatched call did, and whether other sessions must refresh. */
 export interface InvocationEffect {
     /** `unknown`: a write may have run that nothing confirms or rules out. */
@@ -204,6 +214,15 @@ export interface InvocationEffect {
  * declaration, which only then a receipt, `retrySafe` or a typed failure the
  * call raised itself may narrow. A refused call is settled before its error is
  * read.
+ *
+ * A recorded call that threw by itself needs a write the framework saw it
+ * send as well, not just a write handler having started: a rejection raised
+ * before anything was saved is `none`. Seeing a write only narrows what
+ * entered, so a call declared read-only that writes anyway is no more suspect
+ * than before. A call whose result never came may still be running and write
+ * later, so observing nothing proves nothing and it keeps the entered
+ * evidence alone. So does `changed`: a refresh nothing needed costs less than
+ * a missed one.
  */
 export declare function invocationEffect(entry: {
     changeEvents?: boolean;
@@ -470,6 +489,12 @@ interface DefineActionWithSchema<TSchema extends StandardSchemaV1, TReturn = any
     mcpAnnotations?: ActionMcpToolAnnotations;
     deferLoading?: boolean;
     eagerInputStreaming?: boolean;
+    /** An empty list on this action sets an option and erases nothing saved, so
+     *  a call that pads unused fields with `null` and `[]` can run as sent. Leave
+     *  this off for any action that stores a list: there, `[]` beside a padded
+     *  `null` might be a real clear or padding, so the call is refused rather
+     *  than guessed at. */
+    emptyListsEraseNothing?: boolean;
     readOnly?: boolean;
     grounding?: boolean;
     allowInPlanMode?: boolean;
@@ -576,6 +601,7 @@ interface DefineActionWithParams<TParams extends Record<string, ParameterSchema>
     mcpAnnotations?: ActionMcpToolAnnotations;
     deferLoading?: boolean;
     eagerInputStreaming?: boolean;
+    emptyListsEraseNothing?: boolean;
     readOnly?: boolean;
     grounding?: boolean;
     allowInPlanMode?: boolean;
@@ -618,6 +644,7 @@ export interface ActionDefinition<TInput, TReturn> {
     readonly mcpAnnotations?: ActionMcpToolAnnotations;
     readonly deferLoading?: boolean;
     readonly eagerInputStreaming?: boolean;
+    readonly emptyListsEraseNothing?: boolean;
     readonly readOnly?: boolean;
     readonly grounding?: boolean;
     readonly allowInPlanMode?: boolean;
@@ -681,6 +708,10 @@ export interface ActionCallEvidence {
     readonly changeEntered: boolean;
     /** One of those writes was nested in the call, not the call's own. */
     readonly nestedWriteEntered?: boolean;
+    /** The framework saw the call, or one nested in it, send a write. */
+    readonly writeObserved: boolean;
+    /** One of those observed writes was nested in the call, not the call's own. */
+    readonly nestedWriteObserved?: boolean;
     /**
      * The failure this call raised or rebuilt itself; only its typed effect
      * speaks for the call. Its own, so another call throwing it again cannot

package/dist/action.js

@@ -1,9 +1,11 @@
 import { copyActionArguments, snapshotActionArguments, } from "./action-arguments-identity.js";
 import { actionCallIsRetrySafe, actionCallReadOnly, actionOutputEffect, classifyActionCall, } from "./action-call-classification.js";
-import { ACTION_EXECUTION_KEY, actionExecutionStorage, endInvocationEvidence, holdInvocationEvidence, runOutsideActionInvocation, takeVouchedEvidence, } from "./action-frame.js";
+import { ACTION_EXECUTION_KEY, actionExecutionStorage, endInvocationEvidence, holdInvocationEvidence, noteObservedWrite, runOutsideActionInvocation, takeVouchedEvidence, withoutWriteObservation, } from "./action-frame.js";
 import { coerceGatewayStringifiedArgs } from "./action-input-coercion.js";
 import { buildActionMcpOutputContract, describeOutputContractIssue, inputSchemaToJsonSchema, maskedIssuePath, outputSchemaToJsonSchema, } from "./action-output-contract.js";
 import { normalizeActionChatUIConfig, } from "./action-ui.js";
+import { normalizeOptionalToolPlaceholders } from "./agent/optional-placeholders.js";
+import { getStrictToolInputValidator } from "./agent/strict-tool-input.js";
 import { normalizeAuditConfig, resolveAuditAttach } from "./audit/config.js";
 import { assertRegisteredActionAccess, } from "./authorization/action-access-runtime.js";
 import { writeBoundedJsonValue, } from "./json-schema/json-value.js";
@@ -12,9 +14,10 @@ import { jsonTypeOf, plainJsonSnapshot, recordInputSchemaVerdict, UninterpretedS
 import { assertUsableSchema } from "./json-schema/usable-schema.js";
 import { describeThrownForLog } from "./mcp/embed-redaction.js";
 import { parseServiceIdentityEmail } from "./org/service-identity.js";
+import { observeOutboundWrites } from "./outbound-write-observation.js";
 import { wrapRunWithActionTracking } from "./tracking/action-lifecycle.js";
 export { ACTION_RECEIPT_SCHEMA_VERSION, DOMAIN_EVENT_CONTENT_TYPE, DOMAIN_EVENT_SPEC_VERSION, ActionReceiptValidationError, assertActionDomainEvent, assertActionReceipt, commitAction, createActionDomainEvent, parseActionDomainEvent, parseActionReceipt, serializeActionDomainEvent, serializeActionReceipt, } from "./action-receipt.js";
-export { ACTION_EXECUTION_KEY };
+export { ACTION_EXECUTION_KEY, withoutWriteObservation };
 /**
  * An action's recorder for a call refused before its run, kept on its
  * execution key so every copy of the entry that carries the key keeps it, even
@@ -102,13 +105,14 @@ export function defineActionErrors(...codes) {
     return Object.freeze(errors);
 }
 /**
- * A rejection raised before the action's first write: a missing target, an
- * edit that matches nothing, a patch identical to what is saved. A caller may
- * then retry with corrected arguments instead of treating the call as
- * possibly applied. The framework accepts the claim only for the call that
- * raised it, and only when no write action nested in that call entered its
- * handler; otherwise it reads as any other failure. It cannot see the
- * handler's own database or provider writes, so throw it before the first.
+ * A rejection raised before the action saved anything that matters, so a
+ * caller can retry with corrected arguments. The framework reads a failure
+ * from the writes it saw, so most rejections need no label. This one is an
+ * override that wins over an observed write, for example when the only thing
+ * written first is something a retry harmlessly repeats, such as uploads
+ * nobody has referenced yet. The framework accepts the claim only for the call
+ * that raised it, and only when no write action nested in that call entered
+ * its handler; otherwise it reads as any other failure.
  */
 export class NoWriteError extends ActionContractError {
     noWrite = true;
@@ -209,6 +213,25 @@ function readableFailure(error) {
         return Object.assign(new Error("The call failed, and its error could not be read."), { errorCode: "error_unreadable" });
     }
 }
+/**
+ * Record that the running action call wrote somewhere the framework cannot
+ * watch, such as a socket, a file or a vendor SDK that does not use `fetch`, so
+ * that a later failure of the call is not read as one that saved nothing. Call
+ * it before the write is sent. It only adds evidence: nothing it records can be
+ * cleared, and outside an action call it does nothing. Database writes and
+ * `fetch` requests that are not GET, HEAD or OPTIONS need no call.
+ */
+export function noteExternalWrite(channel) {
+    noteObservedWrite(channel);
+}
+/**
+ * A `fetch` that cannot be wrapped hides every HTTP write, so a call that
+ * cannot be watched counts as having sent one and its failure stays `unknown`.
+ */
+function noteUnwatchedFetch(status) {
+    if (status === "fetch-unwritable")
+        noteObservedWrite("http-unwatched");
+}
 /**
  * What a dispatched call did, for every transport, from what ran in it by the
  * time it settled or was abandoned. In order: an action's entry that recorded
@@ -219,6 +242,15 @@ function readableFailure(error) {
  * declaration, which only then a receipt, `retrySafe` or a typed failure the
  * call raised itself may narrow. A refused call is settled before its error is
  * read.
+ *
+ * A recorded call that threw by itself needs a write the framework saw it
+ * send as well, not just a write handler having started: a rejection raised
+ * before anything was saved is `none`. Seeing a write only narrows what
+ * entered, so a call declared read-only that writes anyway is no more suspect
+ * than before. A call whose result never came may still be running and write
+ * later, so observing nothing proves nothing and it keeps the entered
+ * evidence alone. So does `changed`: a refresh nothing needed costs less than
+ * a missed one.
  */
 export function invocationEffect(entry, outcome, settled) {
     const { evidence, record } = outcome;
@@ -236,16 +268,24 @@ export function invocationEffect(entry, outcome, settled) {
     const typed = failed && !failed.lost && (!evidence || evidence.raised === failed.error)
         ? actionFailureEffect(failed.error)
         : undefined;
-    if (evidence?.writeEntered && (evidence.nestedWriteEntered || !record)) {
+    const enteredNested = evidence?.writeEntered && (evidence.nestedWriteEntered || !record)
+        ? evidence
+        : undefined;
+    const enteredOwn = record ? record.evidence.writeEntered : readOnly !== true;
+    const changed = enteredNested
+        ? enteredNested.changeEntered
+        : record
+            ? record.evidence.changeEntered && !(failed && typed === "none")
+            : entry.changeEvents !== false &&
+                (failed ? typed === "committed" : enteredOwn);
+    const observed = record !== undefined && failed !== undefined && !failed.lost;
+    if (enteredNested && (!observed || enteredNested.nestedWriteObserved)) {
         return {
             effect: !failed || typed === "committed" ? "committed" : "unknown",
-            changed: evidence.changeEntered,
+            changed,
         };
     }
-    const wrote = record ? record.evidence.writeEntered : readOnly !== true;
-    const changed = record
-        ? record.evidence.changeEntered && !(failed && typed === "none")
-        : entry.changeEvents !== false && (failed ? typed === "committed" : wrote);
+    const wrote = enteredOwn && (!observed || record.evidence.writeObserved);
     const effect = !failed
         ? (settled.receipt?.changed ?? wrote)
             ? "committed"
@@ -746,6 +786,9 @@ export function defineAction(options) {
         ...(typeof options.eagerInputStreaming === "boolean"
             ? { eagerInputStreaming: options.eagerInputStreaming }
             : {}),
+        ...(typeof options.emptyListsEraseNothing === "boolean"
+            ? { emptyListsEraseNothing: options.emptyListsEraseNothing }
+            : {}),
         ...(typeof readOnly === "boolean" ? { readOnly } : {}),
         ...(typeof options.grounding === "boolean"
             ? { grounding: options.grounding }
@@ -1429,6 +1472,7 @@ function wrapRunWithExecutionBoundary(run, key) {
     const boundaryRun = async (args, ctx) => {
         if (!actionExecutionStorage)
             return run(args, ctx);
+        const fetchStatus = observeOutboundWrites();
         const parent = actionExecutionStorage.getStore();
         const frame = parent?.frame?.boundaryPending &&
             (parent.frame.run === boundaryRun || parent.frame.key === key)
@@ -1440,6 +1484,7 @@ function wrapRunWithExecutionBoundary(run, key) {
                 handlerEntered: false,
                 writeEntered: false,
                 changeEntered: false,
+                writeObserved: false,
             };
         frame.key = key;
         frame.boundaryPending = false;
@@ -1449,6 +1494,7 @@ function wrapRunWithExecutionBoundary(run, key) {
             failures: parent?.failures ?? new WeakMap(),
         };
         return actionExecutionStorage.run(state, async () => {
+            noteUnwatchedFetch(fetchStatus);
             try {
                 return await run(args, ctx);
             }
@@ -1473,6 +1519,7 @@ export async function runActionWithExecutionOutcome(run, args, ctx, outcome, ent
     // so without one no row records the evidence vouched for this one.
     if (!actionExecutionStorage)
         return run(args, ctx);
+    const fetchStatus = observeOutboundWrites();
     const parent = actionExecutionStorage.getStore();
     const entryKey = entry
         ? entry[ACTION_EXECUTION_KEY]
@@ -1487,6 +1534,7 @@ export async function runActionWithExecutionOutcome(run, args, ctx, outcome, ent
         handlerEntered: true,
         writeEntered: false,
         changeEntered: false,
+        writeObserved: false,
         boundaryPending: true,
         outcome,
     };
@@ -1500,6 +1548,7 @@ export async function runActionWithExecutionOutcome(run, args, ctx, outcome, ent
         failures: parent?.failures ?? new WeakMap(),
     };
     return actionExecutionStorage.run(state, async () => {
+        noteUnwatchedFetch(fetchStatus);
         try {
             return await run(args, ctx);
         }
@@ -1620,8 +1669,14 @@ export async function actionCallIntent(entry, input) {
         : undefined;
     let snapshot;
     try {
+        const repaired = getStrictToolInputValidator(entry)
+            ? { input, error: undefined }
+            : normalizeOptionalToolPlaceholders(entry.tool?.parameters, coerceGatewayStringifiedArgs(input, entry.tool?.parameters), entry, { nullOnly: true });
+        if (repaired.error)
+            throw repaired.error;
+        args = repaired.input;
         if (schema) {
-            args = await validateActionArgs(schema, input, entry.tool?.parameters);
+            args = await validateActionArgs(schema, args, entry.tool?.parameters);
         }
         // Arguments with no exact snapshot (an accessor, a Map, a class
         // instance) are refused: a gate could not be sure it read what runs.

package/dist/adapters/cli/shell-adapter.js

@@ -1,4 +1,5 @@
 import { execFile } from "node:child_process";
+import { noteObservedWrite, withoutWriteObservation, } from "../../action-frame.js";
 export class ShellCliAdapter {
     name;
     description;
@@ -16,7 +17,7 @@ export class ShellCliAdapter {
     }
     async isAvailable() {
         try {
-            const result = await this.execute(["--version"]);
+            const result = await withoutWriteObservation(() => this.execute(["--version"]));
             return result.exitCode === 0;
         }
         catch {
@@ -24,6 +25,8 @@ export class ShellCliAdapter {
         }
     }
     execute(args) {
+        // The command is the caller's, so nothing says it only reads.
+        noteObservedWrite("cli");
         return new Promise((resolve) => {
             const child = execFile(this.command, args, {
                 env: this.env ? { ...process.env, ...this.env } : process.env,

package/dist/agent/engine/builder-engine.js

@@ -12,6 +12,7 @@ import { getBuilderGatewayRequestHeaders } from "./builder-gateway-headers.js";
 import { gatewayVisitorFacingError, LLM_MISSING_CREDENTIALS_ERROR_CODE, LLM_MISSING_CREDENTIALS_MESSAGE, } from "./credential-errors.js";
 import { BUILDER_GATEWAY_INTERNAL_ERROR_CODE, classifyTerminalErrorCode, canonicalizeBuilderGatewayErrorCode, describeErrorWithCauses, extractRetryAfterMs, isBareProviderRejectionMessage, isBuilderGatewayInternalErrorMessage, isContextOverflowCode, isContextOverflowMessage, isCreditsLimitErrorCode, isGenericInternalServerErrorMessage, isProviderConnectionErrorMessage, PROVIDER_TRANSIENT_REJECTION_ERROR_CODE, } from "./error-detail.js";
 import { FIRST_STREAM_EVENT_TIMEOUT_MS } from "./first-event-timeout.js";
+import { inlineOwnedToolResultImages } from "./inline-tool-result-images.js";
 import { limitProviderTools } from "./limit-provider-tools.js";
 import { resolveMaxOutputTokensForEngine } from "./output-tokens.js";
 import { splitSystemPromptForCache, stablePrefixCacheControl, } from "./prompt-cache.js";
@@ -192,7 +193,7 @@ class BuilderEngine {
             : requestedModel;
         const toolNameMap = createProviderToolNameMap(opts.tools, opts.messages);
         const providerTools = limitProviderTools(opts.tools);
-        const messages = engineMessagesToBuilderGatewayAnthropic(opts.messages, toolNameMap);
+        const messages = engineMessagesToBuilderGatewayAnthropic(await inlineOwnedToolResultImages(opts.messages), toolNameMap);
         const tools = engineToolsToAnthropic(providerTools, toolNameMap);
         const thinkingBudget = opts.providerOptions?.anthropic?.thinking?.budgetTokens;
         const reasoningEffort = normalizeReasoningEffortForModel(model, opts.reasoningEffort ??

package/dist/agent/engine/inline-tool-result-images.d.ts

@@ -0,0 +1,14 @@
+import type { EngineMessage } from "./types.js";
+/**
+ * Sends tool-result images we host (screenshots, exports) as bytes instead of
+ * URLs. The Builder gateway forwards a URL image unchanged: Vertex's Claude
+ * refuses it ("URL sources are not supported") and OpenAI fetches it itself,
+ * sometimes timing out. The stored tool result keeps its URL; only this
+ * request's copy carries bytes.
+ *
+ * Newest images are read first, within one request's hydration budget; URLs
+ * that are not ours do not spend it. An
+ * image that is not ours, or cannot be read or shrunk under the tool-result
+ * image limit, keeps its URL, which is what every request sent before.
+ */
+export declare function inlineOwnedToolResultImages(messages: EngineMessage[]): Promise<EngineMessage[]>;

package/dist/agent/engine/inline-tool-result-images.js

@@ -0,0 +1,165 @@
+import { normalizeImageMediaType } from "../../file-upload/attachment-bytes.js";
+import { claimOwnedAttachmentHydrationCandidate, createOwnedAttachmentHydrationBudget, hydrateOwnedImageUrl, releaseOwnedAttachmentHydrationCandidate, } from "../../file-upload/owned-attachment.js";
+import { downscaleImageToFit } from "../../ingestion/media.js";
+import { parseBase64DataUrl } from "../../shared/data-url.js";
+import { MAX_TOOL_RESULT_IMAGE_BASE64_CHARS } from "../tool-result-images.js";
+// A tool-result screenshot stays in the thread for every later model step, so
+// the same URLs are requested again each step. Entries are bounded in count,
+// encoded size, and age.
+const INLINE_IMAGE_CACHE_TTL_MS = 5 * 60 * 1000;
+const MAX_INLINE_IMAGE_CACHE_ENTRIES = 12;
+const MAX_INLINE_IMAGE_CACHE_CHARS = 16_000_000;
+const inlineImageCache = new Map();
+let inlineImageCacheChars = 0;
+function removeCachedInlineImage(url) {
+    const entry = inlineImageCache.get(url);
+    if (!entry)
+        return;
+    inlineImageCache.delete(url);
+    inlineImageCacheChars -= entry.image.data.length;
+}
+function getCachedInlineImage(url) {
+    const entry = inlineImageCache.get(url);
+    if (!entry)
+        return undefined;
+    if (entry.expiresAt <= Date.now()) {
+        removeCachedInlineImage(url);
+        return undefined;
+    }
+    // Re-insert so Map order tracks recency.
+    inlineImageCache.delete(url);
+    inlineImageCache.set(url, entry);
+    return entry.image;
+}
+function cacheInlineImage(url, image) {
+    removeCachedInlineImage(url);
+    while (inlineImageCache.size > 0 &&
+        (inlineImageCache.size >= MAX_INLINE_IMAGE_CACHE_ENTRIES ||
+            inlineImageCacheChars + image.data.length > MAX_INLINE_IMAGE_CACHE_CHARS)) {
+        removeCachedInlineImage(inlineImageCache.keys().next().value);
+    }
+    inlineImageCache.set(url, {
+        image,
+        expiresAt: Date.now() + INLINE_IMAGE_CACHE_TTL_MS,
+    });
+    inlineImageCacheChars += image.data.length;
+}
+/**
+ * Sends tool-result images we host (screenshots, exports) as bytes instead of
+ * URLs. The Builder gateway forwards a URL image unchanged: Vertex's Claude
+ * refuses it ("URL sources are not supported") and OpenAI fetches it itself,
+ * sometimes timing out. The stored tool result keeps its URL; only this
+ * request's copy carries bytes.
+ *
+ * Newest images are read first, within one request's hydration budget; URLs
+ * that are not ours do not spend it. An
+ * image that is not ours, or cannot be read or shrunk under the tool-result
+ * image limit, keeps its URL, which is what every request sent before.
+ */
+export async function inlineOwnedToolResultImages(messages) {
+    const urls = [];
+    for (const message of [...messages].reverse()) {
+        for (const part of [...message.content].reverse()) {
+            if (part.type !== "tool-result" || part.isError || !part.images) {
+                continue;
+            }
+            for (const image of part.images) {
+                if (image.url && !image.data && !urls.includes(image.url)) {
+                    urls.push(image.url);
+                }
+            }
+        }
+    }
+    if (urls.length === 0)
+        return messages;
+    // Cache hits cost no hydration slot, so take them all before the budget can
+    // end the loop; otherwise an exhausted budget strands older cached images.
+    const inlined = new Map();
+    const uncached = [];
+    for (const url of urls) {
+        const cached = getCachedInlineImage(url);
+        if (cached)
+            inlined.set(url, cached);
+        else
+            uncached.push(url);
+    }
+    const budget = createOwnedAttachmentHydrationBudget();
+    for (const url of uncached) {
+        if (!claimOwnedAttachmentHydrationCandidate(budget))
+            break;
+        const image = await readOwnedImage(url, budget);
+        if (image) {
+            inlined.set(url, image);
+            cacheInlineImage(url, image);
+        }
+    }
+    if (inlined.size === 0)
+        return messages;
+    return messages.map((message) => ({
+        ...message,
+        content: message.content.map((part) => {
+            if (part.type !== "tool-result" ||
+                !part.images?.some((image) => image.url && inlined.has(image.url))) {
+                return part;
+            }
+            return {
+                ...part,
+                images: part.images.map((image) => {
+                    const bytes = image.url ? inlined.get(image.url) : undefined;
+                    if (!bytes)
+                        return image;
+                    return { ...bytes, ...(image.label ? { label: image.label } : {}) };
+                }),
+            };
+        }),
+    }));
+}
+async function readOwnedImage(url, budget) {
+    const result = await hydrateOwnedImageUrl(url, undefined, budget);
+    // Unowned and malformed URLs are rejected before any fetch, so they must not
+    // spend a slot that an older owned screenshot needs.
+    if (result.kind === "unowned") {
+        releaseOwnedAttachmentHydrationCandidate(budget);
+        return null;
+    }
+    if (result.kind === "failed") {
+        if (result.code === "invalid-url") {
+            releaseOwnedAttachmentHydrationCandidate(budget);
+        }
+        console.warn(`[builder-engine] tool-result image sent as a URL: ${result.code}`);
+        return null;
+    }
+    const parsed = parseBase64DataUrl(result.dataUrl);
+    let data = parsed?.data;
+    let mediaType = normalizeImageMediaType(result.mediaType);
+    if (data && mediaType && data.length > MAX_TOOL_RESULT_IMAGE_BASE64_CHARS) {
+        const resized = await shrinkToToolResultLimit(data);
+        data = resized?.data;
+        mediaType = resized ? normalizeImageMediaType(resized.mediaType) : null;
+    }
+    if (!data || !mediaType || data.length > MAX_TOOL_RESULT_IMAGE_BASE64_CHARS) {
+        console.warn("[builder-engine] tool-result image sent as a URL: image-too-large");
+        return null;
+    }
+    return { data, mediaType };
+}
+async function shrinkToToolResultLimit(base64) {
+    try {
+        // Budget in decoded bytes so the re-encoded base64 fits the limit.
+        const resized = await downscaleImageToFit({
+            data: Buffer.from(base64, "base64"),
+            maxBytes: Math.floor(MAX_TOOL_RESULT_IMAGE_BASE64_CHARS / 4) * 3,
+        });
+        if (!resized)
+            return null;
+        return {
+            data: Buffer.from(resized.data).toString("base64"),
+            mediaType: resized.mimeType,
+        };
+    }
+    catch (error) {
+        // coercion-ok: a failed shrink is reported by the caller, which keeps the URL.
+        console.warn("[builder-engine] tool-result image downscale failed:", error instanceof Error ? error.message : String(error));
+        return null;
+    }
+}