libfx 0.0.12 → 0.0.13-dev.1415.g607b1632fff6

package/fx-sdk.js

@@ -7,6 +7,10 @@ const strictDecoder = new TextDecoder("utf-8", { fatal: true });
 const workspaceInfoLimit = 4 * 1024;
 const workspaceCommandLimit = 64 * 1024;
 const workspaceOutputLimit = 64 * 1024;
+// Matches max_instruction_file_bytes and max_instruction_path_bytes in js_host_workspace.zig.
+const workspaceInstructionFileLimit = 1024 * 1024;
+const workspaceInstructionPathLimit = 4 * 1024;
+const workspaceReadTimeoutMs = 10_000;
 const maxInstructionsBytes = 64 * 1024;
 const maxApiKeyBytes = 64 * 1024;
 const maxModelBytes = 1024;
@@ -19,11 +23,20 @@ const streamReadsPerTaskYield = 32;
 const transportActivityIntervalMs = 250;
 const maxUnreadEventBytes = 1024 * 1024;
 const maxUnreadEvents = 256;
-// Prompt image limits mirror the host tool result image contract: the kernel
-// validates content, the SDK bounds the frame before it reaches the core.
+// Prompt images travel as raw bytes beside the ACP frame and are base64
+// encoded only in the model request. An image may use 5 MiB of encoded
+// request data, and a prompt's images 8 MiB, so the raw limits are 3/4 of that.
+// The kernel still validates content and media type.
 const maxPromptImages = 8;
 const maxPromptImageDataBytes = 5 * 1024 * 1024;
-const maxPromptImagesBytes = 8 * 1024 * 1024;
+const maxPromptImagesDataBytes = 8 * 1024 * 1024;
+const maxPromptImageBytes = (maxPromptImageDataBytes / 4) * 3;
+const maxPromptImagesBytes = (maxPromptImagesDataBytes / 4) * 3;
+// Matches the native attachment table: one prompt's images or one checkpoint.
+const maxPendingAttachments = 8;
+const maxOutboundAttachments = 4;
+// Matches the core's kernel checkpoint limit (max_checkpoint_bytes).
+const maxCheckpointBytes = 4 * 1024 * 1024;
 // The core's ACP reader drops frames over 8 MiB without a request id to answer
 // (jsonrpc frame_resource_byte_limit), so the SDK must never emit one. The
 // envelope allowance covers the method key and request id.
@@ -84,6 +97,14 @@ function normalizeFast(value) {
   return value;
 }
 
+function normalizeUltrafast(value) {
+  if (value === undefined) return undefined;
+  if (typeof value !== "boolean") {
+    throw new TypeError("ultrafast must be a boolean");
+  }
+  return value;
+}
+
 export function normalizeAgentOptions(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     throw new TypeError("createFxAgent() options must be an object");
@@ -94,24 +115,29 @@ export function normalizeAgentOptions(value) {
   }
   options.apiKey = boundedString(options.apiKey, "apiKey", maxApiKeyBytes, true);
   if (options.model !== null && typeof options.model === "object" && !Array.isArray(options.model)) {
-    if (Object.hasOwn(options, "effort") || Object.hasOwn(options, "fast")) {
-      throw new TypeError("model options cannot be mixed with top-level effort or fast");
+    if (Object.hasOwn(options, "effort") || Object.hasOwn(options, "fast") || Object.hasOwn(options, "ultrafast")) {
+      throw new TypeError("model options cannot be mixed with top-level effort, fast, or ultrafast");
     }
     const model = options.model;
     for (const name of Object.keys(model)) {
-      if (name !== "id" && name !== "effort" && name !== "fast") {
+      if (name !== "id" && name !== "effort" && name !== "fast" && name !== "ultrafast") {
         throw new TypeError(`unsupported model option: ${name}`);
       }
     }
     options.model = boundedString(model.id, "model.id", maxModelBytes, true);
     options.effort = normalizeEffort(model.effort);
     options.fast = normalizeFast(model.fast);
+    options.ultrafast = normalizeUltrafast(model.ultrafast);
   } else {
     options.model = boundedString(options.model, "model", maxModelBytes, false);
     options.effort = normalizeEffort(options.effort);
     options.fast = normalizeFast(options.fast);
+    options.ultrafast = normalizeUltrafast(options.ultrafast);
   }
   validateGatewayChatUrl(options.gatewayChatUrl);
+  if (options.resizeImage !== undefined && typeof options.resizeImage !== "function") {
+    throw new TypeError("resizeImage must be a function");
+  }
   return options;
 }
 
@@ -121,6 +147,7 @@ function agentEnvironment(options) {
     ...(options.model === undefined ? {} : { FX_MODEL: options.model }),
     ...(options.effort === undefined ? {} : { FX_EFFORT: options.effort }),
     ...(options.fast === undefined ? {} : { FX_FAST: options.fast ? "true" : "false" }),
+    ...(options.ultrafast === undefined ? {} : { FX_ULTRAFAST: options.ultrafast ? "true" : "false" }),
     ...(options.gatewayChatUrl === undefined ? {} : { FX_GATEWAY_CHAT_URL: options.gatewayChatUrl }),
   };
 }
@@ -128,9 +155,9 @@ function agentEnvironment(options) {
 function agentRpcError(response) {
   const error = new Error(response.message);
   const data = response.data;
-  if (data && ["LIBFX_MODEL_UNSUPPORTED_EFFORT", "LIBFX_MODEL_UNSUPPORTED_FAST"].includes(data.code) &&
+  if (data && ["LIBFX_MODEL_UNSUPPORTED_EFFORT", "LIBFX_MODEL_UNSUPPORTED_FAST", "LIBFX_MODEL_UNSUPPORTED_ULTRAFAST"].includes(data.code) &&
     typeof data.model === "string" &&
-    data.capability === (data.code === "LIBFX_MODEL_UNSUPPORTED_FAST" ? "fast" : "effort")) {
+    data.capability === (data.code === "LIBFX_MODEL_UNSUPPORTED_FAST" ? "fast" : data.code === "LIBFX_MODEL_UNSUPPORTED_ULTRAFAST" ? "ultrafast" : "effort")) {
     error.code = data.code;
     error.model = data.model;
     error.capability = data.capability;
@@ -230,12 +257,24 @@ function validWorkspacePath(path) {
   return path.slice(1).split("/").every((part) => part && part !== "." && part !== "..");
 }
 
+function workspacePathInside(root, path) {
+  return root === "/" ? path.startsWith("/") : path === root || path.startsWith(`${root}/`);
+}
+
+// fx only reads AGENTS.md files below the workspace root or the host home.
+function workspaceInstructionPathAllowed(info, path) {
+  return validWorkspacePath(path) && path.endsWith("/AGENTS.md") &&
+    (workspacePathInside(info.root, path) || workspacePathInside(info.home, path));
+}
+
 function prepareWorkspaceAdapter(workspace) {
   if (workspace == null) return { present: false, valid: false };
   try {
     const info = workspace.info;
     const permission = workspace.permission;
+    const readFile = workspace.readFile;
     if (!info || typeof workspace.exec !== "function" || info.version !== 1 ||
+      (readFile !== undefined && typeof readFile !== "function") ||
       !validWorkspacePath(info.root) || !validWorkspacePath(info.cwd) ||
       !validWorkspacePath(info.home) || info.cwd !== info.root ||
       info.gitAvailable !== false || info.ephemeral !== true ||
@@ -250,6 +289,7 @@ function prepareWorkspaceAdapter(workspace) {
       git: false,
       ephemeral: true,
       permission,
+      instruction_files: typeof readFile === "function",
     };
     const encoded = encoder.encode(JSON.stringify(value));
     if (encoded.length > workspaceInfoLimit) return { present: true, valid: false };
@@ -465,7 +505,12 @@ function createRuntime(options) {
   const steering = [];
   let steeringBytes = 0;
   let steeringOpen = false;
-  const workspaceExecs = new Set();
+  // Raw payloads beside ACP frames: the core copies inbound bytes into its
+  // own memory and publishes outbound bytes for the agent to take.
+  const inboundAttachments = new Map();
+  const outboundAttachments = new Map();
+  let nextOutboundAttachment = 1;
+  const workspaceOperations = new Set();
   const workspace = prepareWorkspaceAdapter(options.workspace);
   const args = ["fx", ...(options.args || [])];
   const env = Object.entries(options.env || {}).map(([key, value]) => `${key}=${value}`);
@@ -761,6 +806,38 @@ function createRuntime(options) {
     return value.length;
   }
 
+  function writeAttachment(id, data) {
+    if (inboundAttachments.size >= maxPendingAttachments) throw new Error("attachment table is full");
+    inboundAttachments.set(id, data.slice());
+  }
+
+  function attachmentSize(id) {
+    return inboundAttachments.get(id >>> 0)?.length ?? -1;
+  }
+
+  function attachmentTake(id, outputPtr, outputCap) {
+    const key = id >>> 0;
+    const value = inboundAttachments.get(key);
+    if (!value) return -1;
+    // An empty payload needs no output buffer, whose pointer may be arbitrary.
+    if (value.length > 0) {
+      const output = checkedBytes(outputPtr, outputCap);
+      if (!output || value.length > output.length) return -1;
+      output.set(value);
+    }
+    inboundAttachments.delete(key);
+    return value.length;
+  }
+
+  function attachmentPut(inputPtr, inputLen) {
+    const input = checkedBytes(inputPtr, inputLen);
+    if (!input || outboundAttachments.size >= maxOutboundAttachments) return -1;
+    const id = nextOutboundAttachment;
+    nextOutboundAttachment = id === 0x7fffffff ? 1 : id + 1;
+    outboundAttachments.set(id, input.slice());
+    return id;
+  }
+
   let pendingHostToolResult = null;
   function hostToolCall(namePtr, nameLen, argumentsPtr, argumentsLen, outputPtr, outputCap, statusPtr) {
     pendingHostToolResult = null;
@@ -987,32 +1064,13 @@ function createRuntime(options) {
     }
     if (command.includes("\0")) return Promise.resolve(-4);
 
-    const controller = new AbortController();
-    let resolveAbort;
-    const aborted = new Promise((resolve) => { resolveAbort = resolve; });
-    const state = {
-      controller,
-      status: null,
-      abort(status) {
-        if (this.status !== null) return;
-        this.status = status;
-        resolveAbort(status);
-        controller.abort(new DOMException(
-          status === -5 ? "workspace command timed out" : "workspace command aborted",
-          status === -5 ? "TimeoutError" : "AbortError",
-        ));
-      },
-    };
-    workspaceExecs.add(state);
-    const timer = setTimeout(() => state.abort(-5), timeoutMs);
-    const execution = Promise.resolve().then(() => workspace.adapter.exec({
+    return runWorkspaceOperation(timeoutMs, "workspace command", (signal) => workspace.adapter.exec({
       command,
       cwd: workspace.info.cwd,
-      signal: controller.signal,
+      signal,
       timeoutMs,
       outputLimitBytes: workspaceOutputLimit,
-    })).then((value) => {
-      if (state.status !== null) return state.status;
+    }), (value) => {
       if (!value || !Number.isInteger(value.exitCode) || value.exitCode < -0x80000000 ||
         value.exitCode > 0x7fffffff || typeof value.stdout !== "string" ||
         typeof value.stderr !== "string") return -1;
@@ -1046,6 +1104,81 @@ function createRuntime(options) {
       view.setUint32(24, stderr.length, true);
       view.setUint32(28, copied < stdout.length + stderr.length ? 1 : 0, true);
       return 0;
+    });
+  }
+
+  function workspaceReadFile(pathPtr, pathLen, outPtr, outCap, resultPtr) {
+    if (!workspace.present || (workspace.valid && typeof workspace.adapter.readFile !== "function")) {
+      return Promise.resolve(-2);
+    }
+    if (!workspace.valid) return Promise.resolve(-4);
+    const pathBytes = checkedBytes(pathPtr, pathLen);
+    if (!pathBytes || !checkedBytes(outPtr, outCap) || !checkedBytes(resultPtr, 8) ||
+      pathLen > workspaceInstructionPathLimit || outCap > workspaceInstructionFileLimit) {
+      return Promise.resolve(-4);
+    }
+    let path;
+    try {
+      path = strictDecoder.decode(pathBytes);
+    } catch {
+      return Promise.resolve(-4);
+    }
+    if (!workspaceInstructionPathAllowed(workspace.info, path)) return Promise.resolve(-4);
+
+    return runWorkspaceOperation(workspaceReadTimeoutMs, "workspace read", (signal) => workspace.adapter.readFile({
+      path,
+      signal,
+    }), (value) => {
+      if (value == null) return -6;
+      let content;
+      if (typeof value === "string") {
+        content = encoder.encode(value);
+      } else if (value instanceof ArrayBuffer || ArrayBuffer.isView(value)) {
+        content = value instanceof ArrayBuffer
+          ? new Uint8Array(value)
+          : new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+        try {
+          strictDecoder.decode(content);
+        } catch {
+          return -7;
+        }
+      } else {
+        return -1;
+      }
+      if (content.length > 0xffffffff) return -1;
+      const copied = Math.min(content.length, outCap);
+      // Reacquire views: memory may have grown while the host read was pending.
+      bytes(outPtr, copied).set(content.subarray(0, copied));
+      const view = new DataView(memory().buffer, resultPtr, 8);
+      view.setUint32(0, content.length, true);
+      view.setUint32(4, copied, true);
+      return 0;
+    });
+  }
+
+  // Runs one host workspace effect under a deadline and the shared Ctrl+C
+  // abort path. `finish` maps the host value to an ABI status.
+  function runWorkspaceOperation(timeoutMs, label, start, finish) {
+    const controller = new AbortController();
+    let resolveAbort;
+    const aborted = new Promise((resolve) => { resolveAbort = resolve; });
+    const state = {
+      status: null,
+      abort(status) {
+        if (this.status !== null) return;
+        this.status = status;
+        resolveAbort(status);
+        controller.abort(new DOMException(
+          status === -5 ? `${label} timed out` : `${label} aborted`,
+          status === -5 ? "TimeoutError" : "AbortError",
+        ));
+      },
+    };
+    workspaceOperations.add(state);
+    const timer = setTimeout(() => state.abort(-5), timeoutMs);
+    const execution = Promise.resolve().then(() => start(controller.signal)).then((value) => {
+      if (state.status !== null) return state.status;
+      return finish(value);
     }).catch((error) => {
       if (state.status !== null) return state.status;
       if (error?.name === "TimeoutError") return -5;
@@ -1054,7 +1187,7 @@ function createRuntime(options) {
     });
     return Promise.race([execution, aborted]).finally(() => {
       clearTimeout(timer);
-      workspaceExecs.delete(state);
+      workspaceOperations.delete(state);
     });
   }
 
@@ -1062,7 +1195,7 @@ function createRuntime(options) {
     pendingHostToolResult = null;
     streams.forEach((state) => state.controller.abort(abortReason));
     httpRequests.forEach((controller) => controller.abort(abortReason));
-    workspaceExecs.forEach((state) => state.abort(-3));
+    workspaceOperations.forEach((state) => state.abort(-3));
   }
 
   const unavailable = () => 52;
@@ -1117,6 +1250,7 @@ function createRuntime(options) {
     fx_workspace_available() { return workspace.present ? 1 : 0; },
     fx_workspace_info: workspaceInfo,
     fx_workspace_exec: new WebAssembly.Suspending(workspaceExec),
+    fx_workspace_read_file: new WebAssembly.Suspending(workspaceReadFile),
     fx_http_stream_open: streamOpen,
     fx_http_stream_status: new WebAssembly.Suspending(streamStatus),
     fx_http_stream_next: new WebAssembly.Suspending(streamNext),
@@ -1132,6 +1266,9 @@ function createRuntime(options) {
     fx_host_tool_result_release() { pendingHostToolResult = null; },
     fx_steering_take: steeringTake,
     fx_steering_close() { steeringOpen = false; clearSteering(); },
+    fx_attachment_size: attachmentSize,
+    fx_attachment_take: attachmentTake,
+    fx_attachment_put: attachmentPut,
     fx_open_url: new WebAssembly.Suspending(openUrl),
     fx_oauth_session_load: new WebAssembly.Suspending(oauthSessionLoad),
     fx_oauth_session_commit: new WebAssembly.Suspending(oauthSessionCommit),
@@ -1158,6 +1295,13 @@ function createRuntime(options) {
     imports: { wasi_snapshot_preview1: wasi, fx }, exited,
     setInstance(value) { instance = value; },
     write(data) { stdin.push(typeof data === "string" ? encoder.encode(data) : data); },
+    writeAttachment,
+    takeAttachment(id) {
+      const value = outboundAttachments.get(id) ?? null;
+      outboundAttachments.delete(id);
+      return value;
+    },
+    discardAttachments() { inboundAttachments.clear(); },
     wake() { stdin.wake(); },
     closeStdin() { steeringOpen = false; clearSteering(); stdin.close(); },
     openSteering() { clearSteering(); steeringOpen = true; },
@@ -1299,42 +1443,128 @@ function blobByteLength(value) {
   }
 }
 
-function normalizePromptInput(input) {
+function normalizeImageSourceRef(value, name) {
+  boundedString(value, `${name} sourceRef`, 512, false);
+  if (value !== undefined && /[\x00-\x1f\x7f\uD800-\uDFFF]/u.test(value)) {
+    throw new TypeError(`${name} sourceRef must be valid UTF-8 without ASCII controls`);
+  }
+  return value;
+}
+
+function omitReferencedImageData(blocks) {
+  return blocks.map((block) => block.type !== "image" || block.sourceRef === undefined ? block : {
+    type: "image",
+    mimeType: block.mimeType,
+    sourceRef: block.sourceRef,
+  });
+}
+
+function promptImageDataBytes(prompt) {
+  return prompt.reduce((total, block) => {
+    if (block.type !== "image") return total;
+    if (typeof block.data === "string") return total + block.data.length;
+    const byteLength = block.bytes?.byteLength ?? block.byteLength ?? blobByteLength(block.data) ?? 0;
+    return total + Math.ceil(byteLength / 3) * 4;
+  }, 0);
+}
+
+// Returns a Uint8Array view of an ArrayBuffer or typed array, or null.
+function byteView(value) {
+  if (value instanceof ArrayBuffer) return new Uint8Array(value);
+  if (ArrayBuffer.isView(value)) return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  return null;
+}
+
+const base64Alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+// Returns the decoded length of canonical, unwrapped base64, or -1.
+function canonicalBase64ByteLength(value) {
+  if (value.length === 0 || value.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(value)) return -1;
+  const groups = value.length / 4;
+  if (value.endsWith("==")) {
+    return (base64Alphabet.indexOf(value[value.length - 3]) & 0x0f) === 0 ? groups * 3 - 2 : -1;
+  }
+  if (value.endsWith("=")) {
+    return (base64Alphabet.indexOf(value[value.length - 2]) & 0x03) === 0 ? groups * 3 - 1 : -1;
+  }
+  return groups * 3;
+}
+
+function requireImageMimeType(mimeType, index) {
+  if (typeof mimeType !== "string" || mimeType.length === 0 || mimeType.length > 128) {
+    throw new TypeError(`image prompt block ${index} requires a mimeType`);
+  }
+}
+
+function checkImageByteLength(byteLength, index) {
+  if (byteLength > maxPromptImageBytes) {
+    throw new RangeError(`image prompt block ${index} exceeds the ${maxPromptImageBytes} byte per-image libfx limit`);
+  }
+}
+
+function checkPromptImagesByteLength(byteLength) {
+  if (byteLength > maxPromptImagesBytes) {
+    throw new RangeError(`prompt images exceed the ${maxPromptImagesBytes} byte libfx limit`);
+  }
+}
+
+// Pixel inputs carry a private source and byteLength until preparation;
+// reference-only inputs remain public image descriptors without pixel data.
+function normalizePromptImage(block, index) {
+  const sourceRef = normalizeImageSourceRef(block.sourceRef, `image prompt block ${index}`);
+  const reference = sourceRef === undefined ? {} : { sourceRef };
+  if (block.data === undefined && sourceRef !== undefined) {
+    requireImageMimeType(block.mimeType, index);
+    return { type: "image", mimeType: block.mimeType, ...reference };
+  }
+  const size = blobByteLength(block.data);
+  if (size !== null) {
+    const mimeType = block.data.type;
+    if (block.mimeType !== undefined && block.mimeType !== mimeType) {
+      throw new TypeError(`image prompt block ${index} mimeType disagrees with Blob.type`);
+    }
+    requireImageMimeType(mimeType, index);
+    if (!Number.isSafeInteger(size) || size <= 0) {
+      throw new TypeError(`image prompt block ${index} requires a non-empty Blob with a valid size`);
+    }
+    return { type: "image", source: "blob", data: block.data, mimeType, byteLength: size, ...reference };
+  }
+  if (typeof block.data === "string" && block.data.length > 0) {
+    requireImageMimeType(block.mimeType, index);
+    const byteLength = canonicalBase64ByteLength(block.data);
+    if (byteLength <= 0) throw new TypeError(`image prompt block ${index} requires canonical base64 data`);
+    return { type: "image", source: "base64", data: block.data, mimeType: block.mimeType, byteLength, ...reference };
+  }
+  const bytes = typeof block.data === "string" ? null : byteView(block.data);
+  if (!bytes || bytes.byteLength === 0) {
+    throw new TypeError(`image prompt block ${index} requires base64 data, bytes, or a Blob`);
+  }
+  requireImageMimeType(block.mimeType, index);
+  return { type: "image", source: "bytes", data: bytes, mimeType: block.mimeType, byteLength: bytes.byteLength, ...reference };
+}
+
+// With deferImageLimits, byte limits apply after resizeImage instead.
+function normalizePromptInput(input, { deferImageLimits = false } = {}) {
   if (typeof input === "string") return [{ type: "text", text: input }];
   if (!Array.isArray(input)) throw new TypeError("prompt input must be a string or an array of prompt blocks");
   let imageCount = 0;
   let imageBytes = 0;
-  return input.map((block, index) => {
+  let prompt = input.map((block, index) => {
     if (!block || typeof block !== "object") throw new TypeError(`prompt block ${index} must be an object`);
     if (block.type === "image") {
-      const size = blobByteLength(block.data);
-      const blob = size !== null;
-      if (!blob && (typeof block.data !== "string" || block.data.length === 0)) {
-        throw new TypeError(`image prompt block ${index} requires base64 data or a Blob`);
-      }
-      const mimeType = blob ? block.data.type : block.mimeType;
-      if (blob && block.mimeType !== undefined && block.mimeType !== mimeType) {
-        throw new TypeError(`image prompt block ${index} mimeType disagrees with Blob.type`);
-      }
-      if (typeof mimeType !== "string" || mimeType.length === 0 || mimeType.length > 128) {
-        throw new TypeError(`image prompt block ${index} requires a mimeType`);
-      }
-      if (blob && (!Number.isSafeInteger(size) || size <= 0)) {
-        throw new TypeError(`image prompt block ${index} requires a non-empty Blob with a valid size`);
-      }
-      const encodedLength = blob ? Math.ceil(size / 3) * 4 : block.data.length;
-      if (encodedLength > maxPromptImageDataBytes) {
-        throw new RangeError(`image prompt block ${index} exceeds the ${maxPromptImageDataBytes} byte per-image libfx limit`);
-      }
+      const image = normalizePromptImage(block, index);
       imageCount += 1;
       if (imageCount > maxPromptImages) {
         throw new RangeError(`prompt cannot contain more than ${maxPromptImages} images`);
       }
-      imageBytes += encodedLength;
-      if (imageBytes > maxPromptImagesBytes) {
-        throw new RangeError(`prompt images exceed the ${maxPromptImagesBytes} byte libfx frame limit`);
+      if (!deferImageLimits) {
+        if (image.byteLength > maxPromptImageBytes && image.sourceRef !== undefined) {
+          return omitReferencedImageData([image])[0];
+        }
+        checkImageByteLength(image.byteLength ?? 0, index);
+        imageBytes += image.byteLength ?? 0;
       }
-      return { type: "image", data: block.data, mimeType };
+      return image;
     }
     if (block.type === "text") {
       if (typeof block.text !== "string") throw new TypeError(`text prompt block ${index} requires text`);
@@ -1348,50 +1578,103 @@ function normalizePromptInput(input) {
     }
     throw new TypeError(`unsupported prompt block type: ${String(block.type)}`);
   });
+  if (!deferImageLimits) {
+    if (imageBytes > maxPromptImagesBytes) {
+      prompt = omitReferencedImageData(prompt);
+      imageBytes = prompt.reduce((total, block) => total + (block.type === "image" ? block.byteLength ?? 0 : 0), 0);
+    }
+    checkPromptImagesByteLength(imageBytes);
+    if (promptFrameSize(prompt) > maxPromptFrameBytes) prompt = omitReferencedImageData(prompt);
+  }
+  return prompt;
 }
 
-function promptFrameSize(prompt) {
-  let blobDataBytes = 0;
-  const projected = prompt.map((block) => {
-    if (block.type !== "image" || typeof block.data === "string") return block;
-    const size = blobByteLength(block.data);
-    if (!Number.isSafeInteger(size)) throw new TypeError("image prompt requires a valid Blob size");
-    blobDataBytes += Math.ceil(size / 3) * 4;
-    return { type: "image", data: "", mimeType: block.mimeType };
+// Image bytes travel beside the frame as attachment references, but the model
+// request carries them base64 encoded and the native host caps that request at
+// 8 MiB. Images therefore count at their encoded size, the same budget they
+// had inside the frame. With countImages false, only the frame counts.
+function promptFrameSize(prompt, countImages = true) {
+  const encodedImageBytes = countImages ? promptImageDataBytes(prompt) : 0;
+  const projected = prompt.map((block) => block.type !== "image" ? block : {
+    type: "image",
+    mimeType: block.mimeType,
+    ...(block.sourceRef === undefined ? {} : { sourceRef: block.sourceRef }),
+    ...(block.data === undefined && block.bytes === undefined ? {} : { _meta: { fx: { attachment: 0xffffffff } } }),
   });
-  return encoder.encode(JSON.stringify({ sessionId: "", prompt: projected })).length + blobDataBytes + promptFrameEnvelopeBytes;
+  return encoder.encode(JSON.stringify({ sessionId: "", prompt: projected })).length +
+    encodedImageBytes + promptFrameEnvelopeBytes;
 }
 
-async function materializePromptBlobs(blocks, isCancelled) {
-  const encoded = [];
+function checkPromptFrameSize(prompt, countImages) {
+  if (promptFrameSize(prompt, countImages) > maxPromptFrameBytes) {
+    throw new RangeError(`prompt exceeds the ${maxPromptFrameBytes} byte libfx frame limit`);
+  }
+}
+
+// Returns prompt blocks whose images carry { mimeType, bytes }. Synchronous
+// sources only: base64 is decoded and caller bytes are used in place.
+function preparePromptImages(blocks) {
+  return blocks.map((block) => block.type !== "image" || block.data === undefined ? block : {
+    type: "image",
+    mimeType: block.mimeType,
+    bytes: block.source === "base64" ? base64ToBytes(block.data) : block.data,
+    ...(block.sourceRef === undefined ? {} : { sourceRef: block.sourceRef }),
+  });
+}
+
+function resizedPromptImage(value, index) {
+  const bytes = byteView(value?.bytes);
+  if (!bytes || bytes.byteLength === 0 || typeof value.mimeType !== "string" ||
+    value.mimeType.length === 0 || value.mimeType.length > 128) {
+    throw new TypeError(`resizeImage must return non-empty bytes and a mimeType for image prompt block ${index}`);
+  }
+  // Copied because a hook may reuse its output buffer for the next image.
+  return { bytes: bytes.slice(), mimeType: value.mimeType };
+}
+
+// Reads Blob images and applies resizeImage, then checks the final byte and
+// frame limits. Returns null when the turn is cancelled first.
+async function materializePromptImages(blocks, isCancelled, resizeImage) {
+  let prepared = [];
   let imageBytes = 0;
-  for (const [index, block] of blocks.entries()) {
+  for (let index = 0; index < blocks.length; index++) {
     if (isCancelled()) return null;
-    if (block.type !== "image") {
-      encoded.push(block);
+    const block = blocks[index];
+    if (block.type !== "image" || block.data === undefined) {
+      prepared.push(block);
       continue;
     }
-    if (typeof block.data === "string") {
-      imageBytes += block.data.length;
-      if (imageBytes > maxPromptImagesBytes) {
-        throw new RangeError(`prompt images exceed the ${maxPromptImagesBytes} byte libfx frame limit`);
-      }
-      encoded.push(block);
-      continue;
-    }
-    const bytes = new Uint8Array(await block.data.arrayBuffer());
+    let image = block.source === "blob"
+      ? { mimeType: block.mimeType, bytes: new Uint8Array(await block.data.arrayBuffer()) }
+      : preparePromptImages([block])[0];
     if (isCancelled()) return null;
-    const encodedLength = Math.ceil(bytes.length / 3) * 4;
-    if (encodedLength > maxPromptImageDataBytes) {
-      throw new RangeError(`image prompt block ${index} exceeds the ${maxPromptImageDataBytes} byte per-image libfx limit`);
+    if (resizeImage) {
+      image = resizedPromptImage(await resizeImage({ bytes: image.bytes, mimeType: image.mimeType }), index);
+      if (isCancelled()) return null;
+    }
+    image = {
+      type: "image",
+      mimeType: image.mimeType,
+      bytes: image.bytes,
+      ...(block.sourceRef === undefined ? {} : { sourceRef: block.sourceRef }),
+    };
+    if (image.bytes.byteLength > maxPromptImageBytes && image.sourceRef !== undefined) {
+      image = omitReferencedImageData([image])[0];
     }
-    imageBytes += encodedLength;
+    checkImageByteLength(image.bytes?.byteLength ?? 0, index);
+    imageBytes += image.bytes?.byteLength ?? 0;
+    prepared.push(image);
     if (imageBytes > maxPromptImagesBytes) {
-      throw new RangeError(`prompt images exceed the ${maxPromptImagesBytes} byte libfx frame limit`);
+      prepared = omitReferencedImageData(prepared);
+      // Do not read more referenced Blobs after the actual aggregate overflows.
+      blocks = omitReferencedImageData(blocks);
+      imageBytes = prepared.reduce((total, entry) => total + (entry.bytes?.byteLength ?? 0), 0);
     }
-    encoded.push({ type: "image", data: bytesToBase64(bytes), mimeType: block.mimeType });
+    checkPromptImagesByteLength(imageBytes);
   }
-  return normalizePromptInput(encoded);
+  if (promptFrameSize(prepared) > maxPromptFrameBytes) prepared = omitReferencedImageData(prepared);
+  checkPromptFrameSize(prepared, true);
+  return prepared;
 }
 
 function normalizeSteeringInput(input) {
@@ -1466,17 +1749,28 @@ function hostToolContent(value) {
     if (typeof value.text !== "string" || !Array.isArray(value.images) || value.images.length > 8) {
       throw new TypeError("invalid typed tool result");
     }
-    let imageBytes = 0;
-    const images = value.images.map((image) => {
-      if (image?.type !== "image" || typeof image.data !== "string" || typeof image.mimeType !== "string" || image.mimeType.length > 128 || image.data.length > 5 * 1024 * 1024) {
+    let images = value.images.map((image) => {
+      if (image?.type !== "image") throw new TypeError("invalid tool image");
+      const sourceRef = normalizeImageSourceRef(image.sourceRef, "tool image");
+      const referenceOnly = image.data === undefined && sourceRef !== undefined;
+      if ((!referenceOnly && typeof image.data !== "string") || typeof image.mimeType !== "string" || image.mimeType.length === 0 || image.mimeType.length > 128 || (image.data?.length > maxPromptImageDataBytes && sourceRef === undefined)) {
         throw new TypeError("invalid tool image");
       }
-      imageBytes += image.data.length;
-      if (imageBytes > 8 * 1024 * 1024) throw new RangeError("tool images exceed the result limit");
-      return { type: "image", data: image.data, mimeType: image.mimeType };
+      return {
+        type: "image",
+        ...(!referenceOnly && image.data.length <= maxPromptImageDataBytes ? { data: image.data } : {}),
+        mimeType: image.mimeType,
+        ...(sourceRef === undefined ? {} : { sourceRef }),
+      };
     });
-    const content = JSON.stringify({ text: value.text, images });
-    if (new TextEncoder().encode(content).length > 8 * 1024 * 1024) throw new RangeError("typed tool result exceeds the result limit");
+    if (promptImageDataBytes(images) > maxPromptImagesDataBytes) images = omitReferencedImageData(images);
+    if (promptImageDataBytes(images) > maxPromptImagesDataBytes) throw new RangeError("tool images exceed the result limit");
+    let content = JSON.stringify({ text: value.text, images });
+    if (encoder.encode(content).length > maxPromptImagesDataBytes) {
+      images = omitReferencedImageData(images);
+      content = JSON.stringify({ text: value.text, images });
+    }
+    if (encoder.encode(content).length > maxPromptImagesDataBytes) throw new RangeError("typed tool result exceeds the result limit");
     return { content, rich: true, isError: value.isError === true };
   }
   if (typeof value === "string") return { content: value, rich: false };
@@ -1495,14 +1789,6 @@ function checkpointBytes(value) {
   throw new TypeError("checkpoint must be an ArrayBuffer or typed array");
 }
 
-function bytesToBase64(value) {
-  let binary = "";
-  for (let offset = 0; offset < value.length; offset += 0x8000) {
-    binary += String.fromCharCode(...value.subarray(offset, offset + 0x8000));
-  }
-  return btoa(binary);
-}
-
 function base64ToBytes(value) {
   const binary = atob(value);
   const bytes = new Uint8Array(binary.length);
@@ -1515,6 +1801,11 @@ export async function createFxAgent(options = {}) {
   const hostTools = normalizeHostTools(options.tools);
   const instructions = normalizeInstructions(options.instructions);
   const initialCheckpoint = checkpointBytes(options.checkpoint);
+  // Checked before the core starts, and with the core's message, so both
+  // backends report it the same way.
+  if (initialCheckpoint && initialCheckpoint.byteLength > maxCheckpointBytes) {
+    throw new Error("libfx checkpoint is too large");
+  }
   const pending = new Map();
   let nextId = 1;
   let sessionId = null;
@@ -1659,11 +1950,47 @@ export async function createFxAgent(options = {}) {
     pending.set(id, { resolve, reject });
     try { send({ jsonrpc: "2.0", id, method, params }); } catch (error) { pending.delete(id); reject(error); }
   });
+  // Raw payloads ride beside the next frame instead of inside it. Payloads
+  // left by an earlier frame that never reached the core are dropped first.
+  let nextAttachmentId = 1;
+  const attachBytes = (payloads) => {
+    if (typeof runtime.writeAttachment !== "function") throw new Error("fx runtime does not accept binary attachments");
+    runtime.discardAttachments?.();
+    return payloads.map((bytes) => {
+      const id = nextAttachmentId;
+      nextAttachmentId = id === 0x7fffffff ? 1 : id + 1;
+      runtime.writeAttachment(id, bytes);
+      return id;
+    });
+  };
+  let checkpointTail = null;
+  let pendingCheckpoints = 0;
+  async function takeCheckpoint() {
+    if (closing) throw new Error("fx agent is closed");
+    if (activeTurn) throw new Error("cannot checkpoint while a prompt is active");
+    const response = await request("libfx/checkpoint", { sessionId });
+    const id = response?.checkpointAttachment;
+    const bytes = Number.isSafeInteger(id) && id > 0 ? runtime.takeAttachment?.(id) : null;
+    if (!(bytes instanceof Uint8Array) || bytes.byteLength === 0) throw new Error("fx returned an invalid checkpoint");
+    return new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  }
+  const sendPrompt = (blocks) => {
+    const images = blocks.filter((block) => block.type === "image" && block.bytes !== undefined);
+    const ids = images.length ? attachBytes(images.map((block) => block.bytes)) : [];
+    let next = 0;
+    const prompt = blocks.map((block) => block.type !== "image" ? block : {
+      type: "image",
+      mimeType: block.mimeType,
+      ...(block.sourceRef === undefined ? {} : { sourceRef: block.sourceRef }),
+      ...(block.bytes === undefined ? {} : { _meta: { fx: { attachment: ids[next++] } } }),
+    });
+    return request("session/prompt", { sessionId, prompt });
+  };
   runtime.exited.then((code) => {
     closing = true;
     const error = runtime.error ?? new Error(`fx-core exited with code ${code} before completing the ACP request`);
     coreExitError = error;
-    activeTurn?.failPendingBlob(error);
+    activeTurn?.failImagePrep(error);
     for (const waiter of pending.values()) waiter.reject(error);
     pending.clear();
     emit("runtime.exit", { code });
@@ -1698,6 +2025,10 @@ export async function createFxAgent(options = {}) {
       );
       if (cancelled || closing) return;
       const response = { jsonrpc: "2.0", id: message.id, result: { content, isError, ...(rich ? { contentType: "rich" } : {}) } };
+      if (rich && encoder.encode(JSON.stringify(response)).length + 1 > maxPromptFrameBytes) {
+        const result = JSON.parse(content);
+        response.result.content = JSON.stringify({ ...result, images: omitReferencedImageData(result.images) });
+      }
       if (encoder.encode(JSON.stringify(response)).length + 1 > 8 * 1024 * 1024) {
         response.result = { content: "Host tool result exceeded the response frame limit", isError: true };
       }
@@ -1720,10 +2051,8 @@ export async function createFxAgent(options = {}) {
     const sessionResult = await request("libfx/new");
     sessionId = sessionResult.sessionId;
     if (initialCheckpoint) {
-      await request("libfx/restore", {
-        sessionId,
-        checkpoint: bytesToBase64(initialCheckpoint),
-      });
+      const [checkpointAttachment] = attachBytes([initialCheckpoint]);
+      await request("libfx/restore", { sessionId, checkpointAttachment });
     }
   } catch (error) {
     closing = true;
@@ -1739,12 +2068,21 @@ export async function createFxAgent(options = {}) {
       if (activeTurn) throw new Error("a prompt is already in progress for this session");
       return normalizeTurn(startTurn(input, promptOptions));
     },
-    async checkpoint() {
-      if (closing) throw new Error("fx agent is closed");
-      if (activeTurn) throw new Error("cannot checkpoint while a prompt is active");
-      const response = await request("libfx/checkpoint", { sessionId });
-      if (typeof response?.checkpoint !== "string") throw new Error("fx returned an invalid checkpoint");
-      return base64ToBytes(response.checkpoint);
+    checkpoint() {
+      // One checkpoint runs at a time: each holds an outbound attachment until
+      // it is taken, and the native table holds only a few. An idle call still
+      // sends its request before returning, ahead of a later prompt(). The slot
+      // is claimed before that send, so a call from an event handler during it
+      // still waits. The count drops before the caller's own reaction to `run`,
+      // so a call made right after awaiting the previous one is idle.
+      const previous = pendingCheckpoints > 0 ? checkpointTail : null;
+      pendingCheckpoints++;
+      let release;
+      checkpointTail = new Promise((resolve) => { release = resolve; });
+      const run = previous ? previous.then(takeCheckpoint) : takeCheckpoint();
+      const settle = () => { pendingCheckpoints--; release(); };
+      run.then(settle, settle);
+      return run;
     },
     async close() {
       if (closing) { await runtime.exited; return; }
@@ -1846,11 +2184,18 @@ export async function createFxAgent(options = {}) {
   }
 
   function startTurn(input, promptOptions) {
-    const prompt = normalizePromptInput(input);
-    const hasBlobs = prompt.some((block) => block.type === "image" && typeof block.data !== "string");
-    if (promptFrameSize(prompt) > maxPromptFrameBytes) {
-      throw new RangeError(`prompt exceeds the ${maxPromptFrameBytes} byte libfx frame limit`);
-    }
+    const resizeImage = options.resizeImage;
+    const normalized = normalizePromptInput(input, { deferImageLimits: resizeImage !== undefined });
+    const hasPixels = normalized.some((block) => block.type === "image" && block.data !== undefined);
+    // Blob reads and resizeImage run before the prompt frame is sent.
+    const asyncImages = hasPixels && (resizeImage !== undefined ||
+      normalized.some((block) => block.type === "image" && block.source === "blob"));
+    // resizeImage decides the final image sizes, so they are counted after it runs.
+    checkPromptFrameSize(normalized, resizeImage === undefined);
+    // Snapshot caller-owned bytes, which could change before an async send.
+    const prompt = asyncImages
+      ? normalized.map((block) => block.type === "image" && block.source === "bytes" ? { ...block, data: block.data.slice() } : block)
+      : preparePromptImages(normalized);
     const signal = promptOptions.signal;
     if (signal !== undefined && (typeof signal?.addEventListener !== "function" || typeof signal?.removeEventListener !== "function")) throw new TypeError("prompt signal must be an AbortSignal");
     const queue = [];
@@ -1861,10 +2206,10 @@ export async function createFxAgent(options = {}) {
     let terminalError;
     let reportedPressure = false;
     let discardedBytes = 0;
-    let cancelBlobRead = null;
-    let rejectBlobRead = null;
+    let cancelImagePrep = null;
+    let rejectImagePrep = null;
     let resolvePromptStart = null;
-    const promptStarted = hasBlobs ? new Promise((resolve) => { resolvePromptStart = resolve; }) : null;
+    const promptStarted = asyncImages ? new Promise((resolve) => { resolvePromptStart = resolve; }) : null;
     let pendingSteeringCount = 0;
     let pendingSteeringBytes = 0;
     const toolControllers = new Set();
@@ -1891,10 +2236,10 @@ export async function createFxAgent(options = {}) {
       transportBytes: 0,
       lastTransportActivityAt: null,
       get cancelled() { return cancelled; },
-      failPendingBlob(error) {
-        rejectBlobRead?.(error);
-        rejectBlobRead = null;
-        cancelBlobRead = null;
+      failImagePrep(error) {
+        rejectImagePrep?.(error);
+        rejectImagePrep = null;
+        cancelImagePrep = null;
       },
       promptWritten() {
         resolvePromptStart?.(true);
@@ -1939,9 +2284,9 @@ export async function createFxAgent(options = {}) {
       cancel() {
         if (finished || cancelled) return;
         cancelled = true;
-        cancelBlobRead?.();
-        cancelBlobRead = null;
-        rejectBlobRead = null;
+        cancelImagePrep?.();
+        cancelImagePrep = null;
+        rejectImagePrep = null;
         resolvePromptStart?.(false);
         resolvePromptStart = null;
         runtime.closeSteering?.();
@@ -1982,34 +2327,34 @@ export async function createFxAgent(options = {}) {
     runtime.openSteering?.();
     const abort = () => turn.cancel();
     signal?.addEventListener("abort", abort, { once: true });
-    const blobReadCancelled = hasBlobs ? new Promise((resolve, reject) => {
-      cancelBlobRead = () => resolve(null);
-      rejectBlobRead = reject;
+    const imagePrepCancelled = asyncImages ? new Promise((resolve, reject) => {
+      cancelImagePrep = () => resolve(null);
+      rejectImagePrep = reject;
     }) : null;
-    const response = hasBlobs
-      ? Promise.race([
-        Promise.resolve().then(() => materializePromptBlobs(prompt, () => cancelled || closing)),
-        blobReadCancelled,
-      ]).then((encodedPrompt) => {
-        cancelBlobRead = null;
-        rejectBlobRead = null;
+    let response;
+    if (asyncImages) {
+      response = Promise.race([
+        Promise.resolve().then(() => materializePromptImages(prompt, () => cancelled || closing, resizeImage)),
+        imagePrepCancelled,
+      ]).then((prepared) => {
+        cancelImagePrep = null;
+        rejectImagePrep = null;
         if (coreExitError && !cancelled) throw coreExitError;
-        if (encodedPrompt === null || cancelled || closing) {
+        if (prepared === null || cancelled || closing) {
           resolvePromptStart?.(false);
           resolvePromptStart = null;
           return { stopReason: "cancelled" };
         }
-        if (promptFrameSize(encodedPrompt) > maxPromptFrameBytes) {
-          throw new RangeError(`prompt exceeds the ${maxPromptFrameBytes} byte libfx frame limit`);
-        }
-        return request("session/prompt", { sessionId, prompt: encodedPrompt });
-      })
-      : request("session/prompt", { sessionId, prompt });
+        return sendPrompt(prepared);
+      });
+    } else {
+      try { response = sendPrompt(prompt); } catch (error) { response = Promise.reject(error); }
+    }
     turn.result = response
       .then((value) => ({ stopReason: cancelled ? "cancelled" : value.stopReason, usage: value.usage }))
       .catch((error) => {
-        cancelBlobRead = null;
-        rejectBlobRead = null;
+        cancelImagePrep = null;
+        rejectImagePrep = null;
         resolvePromptStart?.(error);
         resolvePromptStart = null;
         if (cancelled && error.message === "Cancelled") return { stopReason: "cancelled" };