libfx 0.0.11 → 0.0.13

package/fx-sdk.js

@@ -19,11 +19,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,7 +93,15 @@ function normalizeFast(value) {
   return value;
 }
 
-function normalizeAgentOptions(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");
   }
@@ -93,10 +110,30 @@ function normalizeAgentOptions(value) {
     throw new TypeError("createFxAgent() does not accept env; pass apiKey and model directly");
   }
   options.apiKey = boundedString(options.apiKey, "apiKey", maxApiKeyBytes, true);
-  options.model = boundedString(options.model, "model", maxModelBytes, false);
-  options.effort = normalizeEffort(options.effort);
-  options.fast = normalizeFast(options.fast);
+  if (options.model !== null && typeof options.model === "object" && !Array.isArray(options.model)) {
+    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" && 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;
 }
 
@@ -106,20 +143,20 @@ 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 }),
   };
 }
 
-// The kernel rejects an unsupported effort or fast lane during initialize;
-// these messages originate only from that validation, so the rejection is
-// safe to retype.
-function agentBootstrapError(error) {
-  if (error instanceof Error &&
-    (error.message === "Invalid reasoning effort" || error.message.startsWith("Reasoning effort"))) {
-    error.code ??= "LIBFX_UNSUPPORTED_EFFORT";
-  }
-  if (error instanceof Error && error.message.startsWith("Fast mode")) {
-    error.code ??= "LIBFX_UNSUPPORTED_FAST";
+function agentRpcError(response) {
+  const error = new Error(response.message);
+  const data = response.data;
+  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" : data.code === "LIBFX_MODEL_UNSUPPORTED_ULTRAFAST" ? "ultrafast" : "effort")) {
+    error.code = data.code;
+    error.model = data.model;
+    error.capability = data.capability;
   }
   return error;
 }
@@ -451,6 +488,11 @@ function createRuntime(options) {
   const steering = [];
   let steeringBytes = 0;
   let steeringOpen = false;
+  // 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 workspaceExecs = new Set();
   const workspace = prepareWorkspaceAdapter(options.workspace);
   const args = ["fx", ...(options.args || [])];
@@ -747,6 +789,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;
@@ -1118,6 +1192,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),
@@ -1144,6 +1221,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; },
@@ -1276,32 +1360,137 @@ export async function createFxTerminal(options) {
   };
 }
 
-function normalizePromptInput(input) {
+function blobByteLength(value) {
+  if (typeof Blob === "undefined" || value == null) return null;
+  try {
+    return Object.getOwnPropertyDescriptor(Blob.prototype, "size").get.call(value);
+  } catch {
+    return null;
+  }
+}
+
+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") {
-      if (typeof block.data !== "string" || block.data.length === 0) {
-        throw new TypeError(`image prompt block ${index} requires base64 data`);
-      }
-      if (typeof block.mimeType !== "string" || block.mimeType.length === 0 || block.mimeType.length > 128) {
-        throw new TypeError(`image prompt block ${index} requires a mimeType`);
-      }
-      if (block.data.length > 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 += block.data.length;
-      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: block.mimeType };
+      return image;
     }
     if (block.type === "text") {
       if (typeof block.text !== "string") throw new TypeError(`text prompt block ${index} requires text`);
@@ -1315,6 +1504,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;
+}
+
+// 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 +
+    encodedImageBytes + promptFrameEnvelopeBytes;
+}
+
+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 (let index = 0; index < blocks.length; index++) {
+    if (isCancelled()) return null;
+    const block = blocks[index];
+    if (block.type !== "image" || block.data === undefined) {
+      prepared.push(block);
+      continue;
+    }
+    let image = block.source === "blob"
+      ? { mimeType: block.mimeType, bytes: new Uint8Array(await block.data.arrayBuffer()) }
+      : preparePromptImages([block])[0];
+    if (isCancelled()) return null;
+    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];
+    }
+    checkImageByteLength(image.bytes?.byteLength ?? 0, index);
+    imageBytes += image.bytes?.byteLength ?? 0;
+    prepared.push(image);
+    if (imageBytes > maxPromptImagesBytes) {
+      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);
+    }
+    checkPromptImagesByteLength(imageBytes);
+  }
+  if (promptFrameSize(prepared) > maxPromptFrameBytes) prepared = omitReferencedImageData(prepared);
+  checkPromptFrameSize(prepared, true);
+  return prepared;
 }
 
 function normalizeSteeringInput(input) {
@@ -1389,17 +1675,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 };
@@ -1418,14 +1715,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);
@@ -1438,11 +1727,17 @@ 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;
   let activeTurn = null;
   let closing = false;
+  let coreExitError = null;
   const isCurrentTurn = (turn) => turn && activeTurn === turn && !turn.cancelled && !closing;
   const emit = (type, detail = {}) => {
     try { options.onEvent?.({ type, timestamp: performance.now(), ...detail }); } catch {}
@@ -1572,19 +1867,59 @@ export async function createFxAgent(options = {}) {
   const send = (message) => {
     if (closing) throw new Error("fx agent is closing");
     emit("acp.send", { message });
+    if (message.method === "session/prompt" && activeTurn?.cancelled) throw new Error("Cancelled");
     runtime.write(`${JSON.stringify(message)}\n`);
+    if (message.method === "session/prompt") activeTurn?.promptWritten();
   };
   const request = (method, params = {}) => new Promise((resolve, reject) => {
     const id = nextId++;
     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) => {
-    emit("runtime.exit", { code });
     closing = true;
     const error = runtime.error ?? new Error(`fx-core exited with code ${code} before completing the ACP request`);
+    coreExitError = error;
+    activeTurn?.failImagePrep(error);
     for (const waiter of pending.values()) waiter.reject(error);
     pending.clear();
+    emit("runtime.exit", { code });
   });
   runtime.setLineHandler((message, size) => {
     emit("acp.receive", { message });
@@ -1616,6 +1951,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 };
       }
@@ -1623,7 +1962,7 @@ export async function createFxAgent(options = {}) {
       return;
     }
     const waiter = pending.get(message.id); if (!waiter) return; pending.delete(message.id);
-    if (message.error) waiter.reject(new Error(message.error.message)); else waiter.resolve(message.result);
+    if (message.error) waiter.reject(agentRpcError(message.error)); else waiter.resolve(message.result);
   }
   try {
     await request("initialize", {
@@ -1638,17 +1977,15 @@ 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;
     try { runtime.abortHostEffects(); } catch {}
     try { runtime.closeStdin(); } catch {}
     try { await runtime.exited; } catch {}
-    throw agentBootstrapError(error);
+    throw error;
   }
 
   const agent = {
@@ -1657,12 +1994,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; }
@@ -1764,10 +2110,18 @@ export async function createFxAgent(options = {}) {
   }
 
   function startTurn(input, promptOptions) {
-    const prompt = normalizePromptInput(input);
-    if (encoder.encode(JSON.stringify({ sessionId: "", prompt })).length + promptFrameEnvelopeBytes > 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 = [];
@@ -1778,6 +2132,12 @@ export async function createFxAgent(options = {}) {
     let terminalError;
     let reportedPressure = false;
     let discardedBytes = 0;
+    let cancelImagePrep = null;
+    let rejectImagePrep = null;
+    let resolvePromptStart = null;
+    const promptStarted = asyncImages ? new Promise((resolve) => { resolvePromptStart = resolve; }) : null;
+    let pendingSteeringCount = 0;
+    let pendingSteeringBytes = 0;
     const toolControllers = new Set();
     let finished = false;
     let cancelled = false;
@@ -1802,34 +2162,63 @@ export async function createFxAgent(options = {}) {
       transportBytes: 0,
       lastTransportActivityAt: null,
       get cancelled() { return cancelled; },
+      failImagePrep(error) {
+        rejectImagePrep?.(error);
+        rejectImagePrep = null;
+        cancelImagePrep = null;
+      },
+      promptWritten() {
+        resolvePromptStart?.(true);
+        resolvePromptStart = null;
+      },
       steer(text) {
         if (finished || cancelled || activeTurn !== turn) {
           return Promise.reject(new Error("no prompt is running"));
         }
-        let accepted;
-        try {
-          if (typeof runtime.steer === "function") {
-            runtime.steer(text);
-            void turn.push({
-              sessionUpdate: "user_message_chunk",
-              content: { type: "text", text },
-            });
-            accepted = Promise.resolve();
-          } else {
-            accepted = request("libfx/steer", { sessionId, text });
+        if (closing) return Promise.reject(coreExitError ?? new Error("fx agent is closing"));
+        const apply = () => {
+          if (finished || cancelled || activeTurn !== turn) {
+            return Promise.reject(new Error("no prompt is running"));
+          }
+          if (closing) return Promise.reject(coreExitError ?? new Error("fx agent is closing"));
+          try {
+            if (typeof runtime.steer === "function") {
+              runtime.steer(text);
+              void turn.push({
+                sessionUpdate: "user_message_chunk",
+                content: { type: "text", text },
+              });
+              return Promise.resolve();
+            }
+            return request("libfx/steer", { sessionId, text });
+          } catch (error) {
+            return Promise.reject(error);
           }
-        } catch (error) {
-          return Promise.reject(error);
+        };
+        if (!resolvePromptStart) return apply();
+        const bytes = encoder.encode(text).length;
+        if (pendingSteeringCount >= maxSteeringMessages || bytes > maxSteeringQueueBytes - pendingSteeringBytes) {
+          return Promise.reject(new Error("steering queue is full"));
         }
-        return accepted;
+        pendingSteeringCount++;
+        pendingSteeringBytes += bytes;
+        return promptStarted.then((started) => {
+          if (coreExitError && !cancelled) throw coreExitError;
+          return started === true ? apply() : Promise.reject(started instanceof Error ? started : new Error("no prompt is running"));
+        }).finally(() => { pendingSteeringCount--; pendingSteeringBytes -= bytes; });
       },
       cancel() {
         if (finished || cancelled) return;
         cancelled = true;
+        cancelImagePrep?.();
+        cancelImagePrep = null;
+        rejectImagePrep = null;
+        resolvePromptStart?.(false);
+        resolvePromptStart = null;
         runtime.closeSteering?.();
         resumeOutput?.();
         resumeOutput = null;
-        send({ jsonrpc: "2.0", method: "session/cancel", params: { sessionId } });
+        if (!closing) send({ jsonrpc: "2.0", method: "session/cancel", params: { sessionId } });
         for (const controller of toolControllers) controller.abort();
         runtime.abortHostEffects();
       },
@@ -1854,6 +2243,8 @@ export async function createFxAgent(options = {}) {
       },
     };
     if (signal?.aborted) {
+      resolvePromptStart?.(false);
+      resolvePromptStart = null;
       finished = true;
       turn.result = Promise.resolve({ stopReason: "cancelled" });
       return turn;
@@ -1862,10 +2253,37 @@ export async function createFxAgent(options = {}) {
     runtime.openSteering?.();
     const abort = () => turn.cancel();
     signal?.addEventListener("abort", abort, { once: true });
-    turn.result = request("session/prompt", { sessionId, prompt })
-      .then((response) => ({ stopReason: cancelled ? "cancelled" : response.stopReason, usage: response.usage }))
+    const imagePrepCancelled = asyncImages ? new Promise((resolve, reject) => {
+      cancelImagePrep = () => resolve(null);
+      rejectImagePrep = reject;
+    }) : 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 (prepared === null || cancelled || closing) {
+          resolvePromptStart?.(false);
+          resolvePromptStart = null;
+          return { stopReason: "cancelled" };
+        }
+        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) => {
-        if (error.message === "Cancelled") return { stopReason: "cancelled" };
+        cancelImagePrep = null;
+        rejectImagePrep = null;
+        resolvePromptStart?.(error);
+        resolvePromptStart = null;
+        if (cancelled && error.message === "Cancelled") return { stopReason: "cancelled" };
         terminalError = error;
         throw error;
       })