libfx 0.0.9 → 0.0.10-dev.1203.gdf2292744991

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
@@ -95,7 +111,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,6 +10,8 @@ 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;
@@ -44,6 +46,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 +77,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 +87,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();
@@ -1490,7 +1531,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 = {

package/node.cjs

@@ -188,6 +188,7 @@ 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;
@@ -227,6 +228,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 +255,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 +264,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();
@@ -1902,7 +1933,7 @@ async function createFxAgent(options = {}) {
     try {
       await runtime.exited;
     } catch {}
-    throw error;
+    throw agentBootstrapError(error);
   }
   const agent = {
     prompt(input, promptOptions = {}) {
@@ -2439,12 +2470,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.1203.gdf2292744991",
   "description": "Embed fx agents and terminals in JavaScript hosts",
   "type": "module",
   "repository": {