libfx 0.0.12 → 0.0.13

package/node.cjs

@@ -198,7 +198,12 @@ var maxUnreadEventBytes = 1024 * 1024;
 var maxUnreadEvents = 256;
 var maxPromptImages = 8;
 var maxPromptImageDataBytes = 5 * 1024 * 1024;
-var maxPromptImagesBytes = 8 * 1024 * 1024;
+var maxPromptImagesDataBytes = 8 * 1024 * 1024;
+var maxPromptImageBytes = maxPromptImageDataBytes / 4 * 3;
+var maxPromptImagesBytes = maxPromptImagesDataBytes / 4 * 3;
+var maxPendingAttachments = 8;
+var maxOutboundAttachments = 4;
+var maxCheckpointBytes = 4 * 1024 * 1024;
 var maxPromptFrameBytes = 8 * 1024 * 1024;
 var promptFrameEnvelopeBytes = 128;
 var maxSteeringMessageBytes = 64 * 1024;
@@ -255,6 +260,14 @@ function normalizeFast(value) {
   }
   return value;
 }
+function normalizeUltrafast(value) {
+  if (value === undefined)
+    return;
+  if (typeof value !== "boolean") {
+    throw new TypeError("ultrafast must be a boolean");
+  }
+  return value;
+}
 function normalizeAgentOptions(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     throw new TypeError("createFxAgent() options must be an object");
@@ -265,24 +278,29 @@ 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;
 }
 function agentEnvironment(options) {
@@ -291,13 +309,14 @@ 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 }
   };
 }
 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) && typeof data.model === "string" && data.capability === (data.code === "LIBFX_MODEL_UNSUPPORTED_FAST" ? "fast" : "effort")) {
+  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;
@@ -660,6 +679,9 @@ function createRuntime(options) {
   const steering = [];
   let steeringBytes = 0;
   let steeringOpen = false;
+  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 || []];
@@ -983,6 +1005,37 @@ function createRuntime(options) {
     steeringBytes -= value.length;
     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;
+    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 === 2147483647 ? 1 : id + 1;
+    outboundAttachments.set(id, input.slice());
+    return id;
+  }
   let pendingHostToolResult = null;
   function hostToolCall(namePtr, nameLen, argumentsPtr, argumentsLen, outputPtr, outputCap, statusPtr) {
     pendingHostToolResult = null;
@@ -1446,6 +1499,9 @@ function createRuntime(options) {
       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),
@@ -1476,6 +1532,15 @@ function createRuntime(options) {
     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();
     },
@@ -1659,45 +1724,122 @@ function blobByteLength(value) {
     return null;
   }
 }
-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);
+}
+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;
+}
+var base64Alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+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]) & 15) === 0 ? groups * 3 - 2 : -1;
+  }
+  if (value.endsWith("=")) {
+    return (base64Alphabet.indexOf(value[value.length - 2]) & 3) === 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`);
+  }
+}
+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 };
+}
+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")
@@ -1714,52 +1856,89 @@ 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, 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: 4294967295 } } }
+  });
+  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`);
+  }
 }
-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 };
+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 }
   });
-  return encoder.encode(JSON.stringify({ sessionId: "", prompt: projected })).length + blobDataBytes + promptFrameEnvelopeBytes;
 }
-async function materializePromptBlobs(blocks, isCancelled) {
-  const encoded = [];
+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}`);
+  }
+  return { bytes: bytes.slice(), mimeType: value.mimeType };
+}
+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);
-      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);
+    const block = blocks[index];
+    if (block.type !== "image" || block.data === undefined) {
+      prepared.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;
     }
-    imageBytes += encodedLength;
+    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) {
-      throw new RangeError(`prompt images exceed the ${maxPromptImagesBytes} byte libfx frame limit`);
+      prepared = omitReferencedImageData(prepared);
+      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) {
   const blocks = normalizePromptInput(input);
@@ -1846,18 +2025,31 @@ 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)
+    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 };
   }
@@ -1880,13 +2072,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 += 32768) {
-    binary += String.fromCharCode(...value.subarray(offset, offset + 32768));
-  }
-  return btoa(binary);
-}
 function base64ToBytes(value) {
   const binary = atob(value);
   const bytes = new Uint8Array(binary.length);
@@ -1899,6 +2084,9 @@ async function createFxAgent(options = {}) {
   const hostTools = normalizeHostTools(options.tools);
   const instructions = normalizeInstructions(options.instructions);
   const initialCheckpoint = checkpointBytes(options.checkpoint);
+  if (initialCheckpoint && initialCheckpoint.byteLength > maxCheckpointBytes) {
+    throw new Error("libfx checkpoint is too large");
+  }
   const pending = new Map;
   let nextId = 1;
   let sessionId = null;
@@ -2061,11 +2249,49 @@ async function createFxAgent(options = {}) {
       reject(error);
     }
   });
+  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 === 2147483647 ? 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();
@@ -2105,6 +2331,10 @@ 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 };
       }
@@ -2130,10 +2360,8 @@ 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;
@@ -2156,15 +2384,20 @@ async function createFxAgent(options = {}) {
         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() {
+      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) {
@@ -2288,11 +2521,12 @@ async function createFxAgent(options = {}) {
     return { inputTruncated: true, inputPreview: decoder.decode(utf8Prefix(bytes, maxToolStartInputBytes)) };
   }
   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);
+    const asyncImages = hasPixels && (resizeImage !== undefined || normalized.some((block) => block.type === "image" && block.source === "blob"));
+    checkPromptFrameSize(normalized, resizeImage === undefined);
+    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");
@@ -2304,10 +2538,10 @@ 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) => {
+    const promptStarted = asyncImages ? new Promise((resolve) => {
       resolvePromptStart = resolve;
     }) : null;
     let pendingSteeringCount = 0;
@@ -2348,10 +2582,10 @@ async function createFxAgent(options = {}) {
       get cancelled() {
         return cancelled;
       },
-      failPendingBlob(error) {
-        rejectBlobRead?.(error);
-        rejectBlobRead = null;
-        cancelBlobRead = null;
+      failImagePrep(error) {
+        rejectImagePrep?.(error);
+        rejectImagePrep = null;
+        cancelImagePrep = null;
       },
       promptWritten() {
         resolvePromptStart?.(true);
@@ -2404,9 +2638,9 @@ async function createFxAgent(options = {}) {
         if (finished || cancelled)
           return;
         cancelled = true;
-        cancelBlobRead?.();
-        cancelBlobRead = null;
-        rejectBlobRead = null;
+        cancelImagePrep?.();
+        cancelImagePrep = null;
+        rejectImagePrep = null;
         resolvePromptStart?.(false);
         resolvePromptStart = null;
         runtime.closeSteering?.();
@@ -2455,31 +2689,37 @@ 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;
-      if (coreExitError && !cancelled)
-        throw coreExitError;
-      if (encodedPrompt === 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`);
+    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);
       }
-      return request("session/prompt", { sessionId, prompt: encodedPrompt });
-    }) : request("session/prompt", { sessionId, prompt });
+    }
     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")
@@ -2513,7 +2753,7 @@ async function createFxAgent(options = {}) {
 
 // sdk/node.js
 var libfxApiVersion = 2;
-var nativeCoreApiVersion = 3;
+var nativeCoreApiVersion = 4;
 var fetchOperationStale = 0;
 var fetchOperationApplied = 1;
 var fetchOperationBackpressure = 2;
@@ -2804,7 +3044,12 @@ async function getBackendInfo(value = {}) {
   }
 }
 function createNativeCoreRuntime(addon, options) {
-  const { apiKey, model, effort, fast, gatewayChatUrl } = options;
+  const { apiKey, model, effort, fast, ultrafast, gatewayChatUrl } = options;
+  if (ultrafast !== undefined && addon.supportsUltrafast !== true) {
+    const error = new Error("native addon does not support the ultrafast option");
+    error.code = "LIBFX_NATIVE_CAPABILITY_UNAVAILABLE";
+    throw error;
+  }
   const core = addon.createCore({
     apiKey,
     home: options.home ?? import_node_os.homedir(),
@@ -2812,6 +3057,7 @@ function createNativeCoreRuntime(addon, options) {
     ...model === undefined ? {} : { model },
     ...effort === undefined ? {} : { effort },
     ...fast === undefined ? {} : { fast },
+    ...ultrafast === undefined ? {} : { ultrafast },
     ...gatewayChatUrl === undefined ? {} : { gatewayChatUrl }
   });
   let readyFd;
@@ -2858,7 +3104,7 @@ function createNativeCoreRuntime(addon, options) {
     readySocket.destroy();
     readyClosed.then(() => exitedResolve(code));
   };
-  const pumpFetch = async (request) => {
+  const pumpFetch = async (request, body) => {
     const controller = new AbortController;
     const state = { handle: request.handle, controller };
     fetchState = state;
@@ -2866,7 +3112,7 @@ function createNativeCoreRuntime(addon, options) {
       const response = await (options.fetch ?? globalThis.fetch)(request.url, {
         method: request.method,
         headers: new Headers(JSON.parse(request.headers).map(({ name, value }) => [name, value])),
-        body: request.body?.length ? Buffer.from(request.body, "base64") : undefined,
+        body: body.length ? body : undefined,
         signal: controller.signal
       });
       const started = addon.startCoreFetchResponse(core, state.handle, response.status);
@@ -2923,7 +3169,7 @@ function createNativeCoreRuntime(addon, options) {
       } else {
         const fetchRequest = addon.takeCoreFetch(core);
         if (fetchRequest)
-          pumpFetch(JSON.parse(fetchRequest.toString("utf8")));
+          pumpFetch(JSON.parse(fetchRequest.request.toString("utf8")), fetchRequest.body);
       }
       if (addon.coreExitCode(core) !== 0) {
         finish(1, new Error("native output delivery failed"));
@@ -2984,6 +3230,15 @@ function createNativeCoreRuntime(addon, options) {
     write(data) {
       addon.writeCore(core, Buffer.from(data));
     },
+    writeAttachment(id, bytes) {
+      addon.writeCoreAttachment(core, id, Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength));
+    },
+    takeAttachment(id) {
+      return addon.takeCoreAttachment(core, id);
+    },
+    discardAttachments() {
+      addon.discardCoreAttachments(core);
+    },
     closeStdin() {
       addon.closeCore(core);
     },