libfx 0.0.11 → 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");
@@ -264,10 +277,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;
 }
 function agentEnvironment(options) {
@@ -276,15 +309,17 @@ 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 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;
 }
@@ -644,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 || []];
@@ -967,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;
@@ -1430,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),
@@ -1460,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();
     },
@@ -1634,35 +1715,131 @@ 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);
+}
+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") {
-      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")
@@ -1679,6 +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 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}`);
+  }
+  return { bytes: bytes.slice(), mimeType: value.mimeType };
+}
+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);
+      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) {
   const blocks = normalizePromptInput(input);
@@ -1765,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 };
   }
@@ -1799,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);
@@ -1818,11 +2084,15 @@ 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;
   let activeTurn = null;
   let closing = false;
+  let coreExitError = null;
   const isCurrentTurn = (turn) => turn && activeTurn === turn && !turn.cancelled && !closing;
   const emit = (type, detail = {}) => {
     try {
@@ -1962,8 +2232,12 @@ async function createFxAgent(options = {}) {
     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)}
 `);
+    if (message.method === "session/prompt")
+      activeTurn?.promptWritten();
   };
   const request = (method, params = {}) => new Promise((resolve, reject) => {
     const id = nextId++;
@@ -1975,13 +2249,53 @@ 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) => {
-    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 });
@@ -2017,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 };
       }
@@ -2028,7 +2346,7 @@ async function createFxAgent(options = {}) {
       return;
     pending.delete(message.id);
     if (message.error)
-      waiter.reject(new Error(message.error.message));
+      waiter.reject(agentRpcError(message.error));
     else
       waiter.resolve(message.result);
   }
@@ -2042,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;
@@ -2058,7 +2374,7 @@ async function createFxAgent(options = {}) {
     try {
       await runtime.exited;
     } catch {}
-    throw agentBootstrapError(error);
+    throw error;
   }
   const agent = {
     prompt(input, promptOptions = {}) {
@@ -2068,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) {
@@ -2200,10 +2521,12 @@ async function createFxAgent(options = {}) {
     return { inputTruncated: true, inputPreview: decoder.decode(utf8Prefix(bytes, maxToolStartInputBytes)) };
   }
   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);
+    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");
@@ -2215,6 +2538,14 @@ 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;
@@ -2251,35 +2582,72 @@ async function createFxAgent(options = {}) {
       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);
-            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);
+              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();
@@ -2311,6 +2679,8 @@ async function createFxAgent(options = {}) {
       }
     };
     if (signal?.aborted) {
+      resolvePromptStart?.(false);
+      resolvePromptStart = null;
       finished = true;
       turn.result = Promise.resolve({ stopReason: "cancelled" });
       return turn;
@@ -2319,8 +2689,40 @@ 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 })).catch((error) => {
-      if (error.message === "Cancelled")
+    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) => {
+      cancelImagePrep = null;
+      rejectImagePrep = null;
+      resolvePromptStart?.(error);
+      resolvePromptStart = null;
+      if (cancelled && error.message === "Cancelled")
         return { stopReason: "cancelled" };
       terminalError = error;
       throw error;
@@ -2351,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;
@@ -2642,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(),
@@ -2650,6 +3057,7 @@ function createNativeCoreRuntime(addon, options) {
     ...model === undefined ? {} : { model },
     ...effort === undefined ? {} : { effort },
     ...fast === undefined ? {} : { fast },
+    ...ultrafast === undefined ? {} : { ultrafast },
     ...gatewayChatUrl === undefined ? {} : { gatewayChatUrl }
   });
   let readyFd;
@@ -2696,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;
@@ -2704,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);
@@ -2761,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"));
@@ -2822,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);
     },
@@ -2848,10 +3265,11 @@ function createNativeAgent(addon, options) {
   });
 }
 async function createWithFallback(surface, nativeMethod, wasmFactory, defaultWasm, options) {
-  const { nativeAddon, backend = "auto", ...runtimeOptions } = options ?? {};
+  const { nativeAddon, backend = "auto", ...unvalidatedOptions } = options ?? {};
   if (!new Set(["auto", "native", "wasm"]).has(backend)) {
     throw new TypeError('backend must be "auto", "native", or "wasm"');
   }
+  const runtimeOptions = surface === "agent" ? normalizeAgentOptions(unvalidatedOptions) : unvalidatedOptions;
   let nativeError;
   let nativeAttempted = false;
   if (backend !== "wasm") {
@@ -2865,7 +3283,7 @@ async function createWithFallback(surface, nativeMethod, wasmFactory, defaultWas
         return await native.backend[nativeMethod](runtimeOptions);
       } catch (error) {
         nativeError = error;
-        if (backend === "native")
+        if (backend === "native" || error?.code === "LIBFX_MODEL_UNSUPPORTED_FAST" || error?.code === "LIBFX_MODEL_UNSUPPORTED_EFFORT")
           throw error;
       }
     }
@@ -2884,9 +3302,6 @@ async function createWithFallback(surface, nativeMethod, wasmFactory, defaultWas
   return wasmFactory({ ...runtimeOptions, wasm: await wasmInput(wasmSource) });
 }
 async function createFxAgent2(options = {}) {
-  if (options != null && Object.hasOwn(Object(options), "env")) {
-    throw new TypeError("createFxAgent() does not accept env; pass apiKey and model directly");
-  }
   return createWithFallback("agent", "createCore", createFxAgent, defaultCoreWasm, options);
 }
 function createFxTerminal2(options = {}) {