libfx 0.0.9 → 0.0.10-dev.1207.g8578e5771980

package/README.md

@@ -41,9 +41,25 @@ await agent.close();
 Agent configuration uses named options; `env` is reserved for
 `createFxTerminal()`.
 
+`effort` sets the reasoning effort for models that advertise effort levels. It
+uses the same vocabulary as the fx CLI's `--effort` flag: `"default"` leaves
+the choice to the model, and named levels such as `"low"`, `"medium"`,
+`"high"`, or `"xhigh"` request a specific level. A named level is validated
+against the selected model's advertised levels at creation; an unsupported
+level rejects with an error (code `LIBFX_UNSUPPORTED_EFFORT`) naming the
+supported set. When `effort` is omitted or `"default"`, the model default
+applies.
+
+`fast` enables the fast lane for models that advertise one, matching the fx
+CLI's `--fast` flag. Enabling it is validated against the selected model at
+creation; a model without a fast path rejects with an error (code
+`LIBFX_UNSUPPORTED_FAST`). When `fast` is omitted or `false`, the model
+default applies.
+
 The host selects the model. Agent creation does not fetch the Gateway model
-catalog. Prompting can resolve model capabilities and context capacity through
-the supplied `fetch`; fx caches that metadata for the agent.
+catalog unless `effort` requests a named level or `fast` is enabled. Prompting
+can resolve model capabilities and context capacity through the supplied
+`fetch`; fx caches that metadata for the agent.
 
 `onEvent` receives runtime diagnostics separately from model output. Transport
 events report request start, response status and elapsed time, safe Gateway
@@ -52,8 +68,8 @@ request metadata, and failures. Credentials and raw headers are never included.
 libfx makes at most one automatic retry after a retryable transport failure and
 only before model output or tool effects escape. Cancellation prevents a retry.
 
-`prompt(input, { signal? })` accepts a string or text/resource blocks. It
-returns an async iterable of normalized events:
+`prompt(input, { signal? })` accepts a string or text, image, and resource
+blocks. It returns an async iterable of normalized events:
 
 - `text_delta`
 - `reasoning_delta` when supplied by the provider
@@ -82,6 +98,27 @@ that threshold when the queue is empty; an individual encoded ACP message is
 limited to 64 MiB on both backends. These are transport bounds, not a total
 answer-size limit or a bound on retained conversation history.
 
+Image blocks use ACP's content shape and carry canonical base64 (no line
+wrapping) of a PNG, JPEG, GIF, or WebP payload:
+
+```js
+const turn = agent.prompt([
+  { type: "text", text: "What does this screenshot show?" },
+  { type: "image", data: base64Png, mimeType: "image/png" },
+]);
+```
+
+A prompt may contain up to 8 images, each with up to 5 MiB of base64 data,
+with at most 8 MiB of image data per prompt; the SDK rejects larger input with
+typed `RangeError`s before any request. The kernel then validates the decoded
+bytes against the declared `mimeType` and fails the turn with
+`Invalid image prompt block` on a mismatch. Images are routed only to models
+that advertise image input; for any other model the turn fails with
+`Image prompts are unavailable for the selected model` and no image bytes
+leave the process. Prompt images are retained in checkpoints within the
+existing 4 MiB checkpoint bound, so a restored agent can refer to earlier
+images on either backend.
+
 Only one prompt may run at a time. `checkpoint()` is idle-only and returns
 opaque, bounded, versioned bytes. Restore them only when creating a fresh
 agent:
@@ -95,7 +132,10 @@ or a history change. The next prompt can run normally.
 
 The checkpoint contains conversation history and usage only. The host owns
 durable storage and must resupply models, credentials, instructions, tools,
-MCP clients, and skill records.
+MCP clients, and skill records. Reasoning effort and fast mode are
+agent-creation options and are not stored in a checkpoint: recreate the agent
+with new `effort` or `fast` values to change them, the same path as switching
+models.
 
 ## Models
 

package/fx-sdk.js

@@ -10,12 +10,24 @@ const workspaceOutputLimit = 64 * 1024;
 const maxInstructionsBytes = 64 * 1024;
 const maxApiKeyBytes = 64 * 1024;
 const maxModelBytes = 1024;
+// Matches the kernel's ReasoningEffort.max_name_bytes.
+const maxEffortBytes = 64;
 const maxUrlBytes = 16 * 1024;
 const maxModelCatalogBytes = 4 * 1024 * 1024;
 const maxModelCatalogEntries = 10_000;
 const streamReadsPerTaskYield = 32;
 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.
+const maxPromptImages = 8;
+const maxPromptImageDataBytes = 5 * 1024 * 1024;
+const maxPromptImagesBytes = 8 * 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.
+const maxPromptFrameBytes = 8 * 1024 * 1024;
+const promptFrameEnvelopeBytes = 128;
 
 function boundedString(value, name, maxBytes, required) {
   if (value === undefined && !required) return undefined;
@@ -44,6 +56,27 @@ function validateGatewayChatUrl(value) {
   }
 }
 
+// Mirrors the kernel's ReasoningEffort.parse: "auto"/"adaptive"/"default" pick
+// the model default; anything else must be a bounded effort name.
+function normalizeEffort(value) {
+  if (value === undefined) return undefined;
+  boundedString(value, "effort", maxEffortBytes, false);
+  if (!/^[A-Za-z0-9._-]+$/.test(value)) {
+    throw new TypeError('effort must use only letters, digits, ".", "-", or "_"');
+  }
+  return value;
+}
+
+// Mirrors the CLI's --fast/--no-fast toggle: a strict boolean, with undefined
+// leaving the model default in place.
+function normalizeFast(value) {
+  if (value === undefined) return undefined;
+  if (typeof value !== "boolean") {
+    throw new TypeError("fast 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");
@@ -54,6 +87,8 @@ function normalizeAgentOptions(value) {
   }
   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);
   validateGatewayChatUrl(options.gatewayChatUrl);
   return options;
 }
@@ -62,10 +97,26 @@ function agentEnvironment(options) {
   return {
     AI_GATEWAY_API_KEY: options.apiKey,
     ...(options.model === undefined ? {} : { FX_MODEL: options.model }),
+    ...(options.effort === undefined ? {} : { FX_EFFORT: options.effort }),
+    ...(options.fast === undefined ? {} : { FX_FAST: options.fast ? "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";
+  }
+  return error;
+}
+
 async function cancelResponseBody(response) {
   try {
     await response.body?.cancel();
@@ -1182,9 +1233,30 @@ export async function createFxTerminal(options) {
 function normalizePromptInput(input) {
   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) => {
     if (!block || typeof block !== "object") throw new TypeError(`prompt block ${index} must be an object`);
-    if (block.type === "image") throw new TypeError("image prompt blocks are unsupported");
+    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`);
+      }
+      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`);
+      }
+      return { type: "image", data: block.data, mimeType: block.mimeType };
+    }
     if (block.type === "text") {
       if (typeof block.text !== "string") throw new TypeError(`text prompt block ${index} requires text`);
       return { type: "text", text: block.text };
@@ -1490,7 +1562,7 @@ export async function createFxAgent(options = {}) {
     try { runtime.abortHostEffects(); } catch {}
     try { runtime.closeStdin(); } catch {}
     try { await runtime.exited; } catch {}
-    throw error;
+    throw agentBootstrapError(error);
   }
 
   const agent = {
@@ -1591,6 +1663,9 @@ 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 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 = [];

package/node.cjs

@@ -188,12 +188,18 @@ var workspaceOutputLimit = 64 * 1024;
 var maxInstructionsBytes = 64 * 1024;
 var maxApiKeyBytes = 64 * 1024;
 var maxModelBytes = 1024;
+var maxEffortBytes = 64;
 var maxUrlBytes = 16 * 1024;
 var maxModelCatalogBytes = 4 * 1024 * 1024;
 var maxModelCatalogEntries = 1e4;
 var streamReadsPerTaskYield = 32;
 var maxUnreadEventBytes = 1024 * 1024;
 var maxUnreadEvents = 256;
+var maxPromptImages = 8;
+var maxPromptImageDataBytes = 5 * 1024 * 1024;
+var maxPromptImagesBytes = 8 * 1024 * 1024;
+var maxPromptFrameBytes = 8 * 1024 * 1024;
+var promptFrameEnvelopeBytes = 128;
 function boundedString(value, name, maxBytes, required) {
   if (value === undefined && !required)
     return;
@@ -227,6 +233,23 @@ function validateGatewayChatUrl(value) {
     throw new TypeError("gatewayChatUrl must use the canonical Gateway or explicit loopback HTTP");
   }
 }
+function normalizeEffort(value) {
+  if (value === undefined)
+    return;
+  boundedString(value, "effort", maxEffortBytes, false);
+  if (!/^[A-Za-z0-9._-]+$/.test(value)) {
+    throw new TypeError('effort must use only letters, digits, ".", "-", or "_"');
+  }
+  return value;
+}
+function normalizeFast(value) {
+  if (value === undefined)
+    return;
+  if (typeof value !== "boolean") {
+    throw new TypeError("fast 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");
@@ -237,6 +260,8 @@ function normalizeAgentOptions(value) {
   }
   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);
   validateGatewayChatUrl(options.gatewayChatUrl);
   return options;
 }
@@ -244,9 +269,20 @@ function agentEnvironment(options) {
   return {
     AI_GATEWAY_API_KEY: options.apiKey,
     ...options.model === undefined ? {} : { FX_MODEL: options.model },
+    ...options.effort === undefined ? {} : { FX_EFFORT: options.effort },
+    ...options.fast === undefined ? {} : { FX_FAST: options.fast ? "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";
+  }
+  return error;
+}
 async function cancelResponseBody(response) {
   try {
     await response.body?.cancel();
@@ -1547,11 +1583,31 @@ function normalizePromptInput(input) {
     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) => {
     if (!block || typeof block !== "object")
       throw new TypeError(`prompt block ${index} must be an object`);
-    if (block.type === "image")
-      throw new TypeError("image prompt blocks are unsupported");
+    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`);
+      }
+      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`);
+      }
+      return { type: "image", data: block.data, mimeType: block.mimeType };
+    }
     if (block.type === "text") {
       if (typeof block.text !== "string")
         throw new TypeError(`text prompt block ${index} requires text`);
@@ -1902,7 +1958,7 @@ async function createFxAgent(options = {}) {
     try {
       await runtime.exited;
     } catch {}
-    throw error;
+    throw agentBootstrapError(error);
   }
   const agent = {
     prompt(input, promptOptions = {}) {
@@ -2027,6 +2083,9 @@ 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 signal = promptOptions.signal;
     if (signal !== undefined && (typeof signal?.addEventListener !== "function" || typeof signal?.removeEventListener !== "function"))
       throw new TypeError("prompt signal must be an AbortSignal");
@@ -2439,12 +2498,14 @@ async function getBackendInfo(value = {}) {
   }
 }
 function createNativeCoreRuntime(addon, options) {
-  const { apiKey, model, gatewayChatUrl } = options;
+  const { apiKey, model, effort, fast, gatewayChatUrl } = options;
   const core = addon.createCore({
     apiKey,
     home: options.home ?? import_node_os.homedir(),
     workspaceRoot: options.workspaceRoot ?? process.cwd(),
     ...model === undefined ? {} : { model },
+    ...effort === undefined ? {} : { effort },
+    ...fast === undefined ? {} : { fast },
     ...gatewayChatUrl === undefined ? {} : { gatewayChatUrl }
   });
   let readyFd;

package/node.js

@@ -345,12 +345,14 @@ export async function getBackendInfo(value = {}) {
 }
 
 function createNativeCoreRuntime(addon, options) {
-  const { apiKey, model, gatewayChatUrl } = options;
+  const { apiKey, model, effort, fast, gatewayChatUrl } = options;
   const core = addon.createCore({
     apiKey,
     home: options.home ?? homedir(),
     workspaceRoot: options.workspaceRoot ?? process.cwd(),
     ...(model === undefined ? {} : { model }),
+    ...(effort === undefined ? {} : { effort }),
+    ...(fast === undefined ? {} : { fast }),
     ...(gatewayChatUrl === undefined ? {} : { gatewayChatUrl }),
   });
   let readyFd;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libfx",
-  "version": "0.0.9",
+  "version": "0.0.10-dev.1207.g8578e5771980",
   "description": "Embed fx agents and terminals in JavaScript hosts",
   "type": "module",
   "repository": {