libfx 0.0.7-dev.607.ga90fc3585568 → 0.0.7-dev.617.g49fc251a51aa

package/README.md

@@ -19,7 +19,8 @@ filesystem read when imported.
 import { createFxAgent } from "libfx";
 
 const agent = await createFxAgent({
-  env: { AI_GATEWAY_API_KEY: process.env.AI_GATEWAY_API_KEY },
+  apiKey: process.env.AI_GATEWAY_API_KEY,
+  model: "google/gemini-2.5-flash-lite",
 });
 
 const turn = agent.prompt("Explain this project.");
@@ -33,6 +34,10 @@ const checkpoint = await agent.checkpoint();
 await agent.close();
 ```
 
+`apiKey` is required. `model` is optional and defaults to fx's built-in model.
+Agent configuration uses named options; `env` is reserved for
+`createFxTerminal()`.
+
 `prompt(input, { signal? })` accepts a string or text/resource blocks. It
 returns an async iterable of normalized events:
 
@@ -46,7 +51,7 @@ opaque, bounded, versioned bytes. Restore them only when creating a fresh
 agent:
 
 ```js
-const restored = await createFxAgent({ checkpoint, env });
+const restored = await createFxAgent({ apiKey, model, checkpoint });
 ```
 
 The checkpoint contains conversation history and usage only. The host owns
@@ -57,6 +62,8 @@ MCP clients, and skill records.
 
 ```js
 const agent = await createFxAgent({
+  apiKey,
+  model,
   instructions: "Keep answers concise.",
   tools: [{
     name: "lookup",
@@ -70,7 +77,6 @@ const agent = await createFxAgent({
       return database.get(input.key, { signal });
     },
   }],
-  env,
 });
 ```
 
@@ -94,9 +100,10 @@ const mcp = await createMcpAdapter(client, {
 });
 
 const agent = await createFxAgent({
+  apiKey,
+  model,
   tools: mcp.tools,
   instructions: mcp.instructions,
-  env,
 });
 
 // ...
@@ -115,15 +122,15 @@ import { createSkillsAdapter } from "libfx/skills";
 
 const record = await loadSkillFile("./skills/review/SKILL.md");
 const skills = createSkillsAdapter([record]);
-const agent = await createFxAgent({ ...skills, env });
+const agent = await createFxAgent({ apiKey, model, ...skills });
 ```
 
 ## Backends
 
 ```js
-await createFxAgent({ backend: "auto" });   // native, then Wasm fallback
-await createFxAgent({ backend: "native" }); // require N-API
-await createFxAgent({ backend: "wasm" });   // require Wasm + JSPI
+await createFxAgent({ apiKey, backend: "auto" });   // native, then Wasm fallback
+await createFxAgent({ apiKey, backend: "native" }); // require N-API
+await createFxAgent({ apiKey, backend: "wasm" });   // require Wasm + JSPI
 ```
 
 Within one JavaScript realm, libfx compiles each stable Wasm source once and
@@ -156,7 +163,7 @@ stores remain terminal-only host integrations.
 
 ## Security
 
-Treat `nativeAddon` and `env.FX_GATEWAY_CHAT_URL` as trusted host
+Treat `nativeAddon` and `gatewayChatUrl` as trusted host
 configuration. Do not embed long-lived credentials in public browser code.
 Host tool functions, MCP clients, and skill loaders retain their own authority;
 libfx validates and sequences them but does not grant operating-system access.

package/fx-sdk.js

@@ -5,8 +5,59 @@ const workspaceInfoLimit = 4 * 1024;
 const workspaceCommandLimit = 64 * 1024;
 const workspaceOutputLimit = 64 * 1024;
 const maxInstructionsBytes = 64 * 1024;
+const maxApiKeyBytes = 64 * 1024;
+const maxModelBytes = 1024;
+const maxUrlBytes = 16 * 1024;
 const streamReadsPerTaskYield = 32;
 
+function boundedString(value, name, maxBytes, required) {
+  if (value === undefined && !required) return undefined;
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${name} ${required ? "is required and " : ""}must be a non-empty string`);
+  }
+  if (encoder.encode(value).length > maxBytes) {
+    throw new RangeError(`${name} exceeds the ${maxBytes} byte libfx limit`);
+  }
+  return value;
+}
+
+function validateGatewayChatUrl(value) {
+  if (value === undefined) return;
+  boundedString(value, "gatewayChatUrl", maxUrlBytes, false);
+  let url;
+  try { url = new URL(value); } catch { throw new TypeError("gatewayChatUrl must be a valid URL"); }
+  if (url.username || url.password || url.hash) {
+    throw new TypeError("gatewayChatUrl must not contain credentials or a fragment");
+  }
+  if (url.href === "https://ai-gateway.vercel.sh/v3/ai/language-model") return;
+  const loopback = url.hostname === "127.0.0.1" || url.hostname === "[::1]" || url.hostname === "localhost";
+  if (url.protocol !== "http:" || !loopback || !url.port) {
+    throw new TypeError("gatewayChatUrl must use the canonical Gateway or explicit loopback HTTP");
+  }
+}
+
+function normalizeAgentOptions(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError("createFxAgent() options must be an object");
+  }
+  const options = { ...value };
+  if (Object.hasOwn(options, "env")) {
+    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);
+  validateGatewayChatUrl(options.gatewayChatUrl);
+  return options;
+}
+
+function agentEnvironment(options) {
+  return {
+    AI_GATEWAY_API_KEY: options.apiKey,
+    ...(options.model === undefined ? {} : { FX_MODEL: options.model }),
+    ...(options.gatewayChatUrl === undefined ? {} : { FX_GATEWAY_CHAT_URL: options.gatewayChatUrl }),
+  };
+}
+
 function validWorkspacePath(path) {
   if (typeof path !== "string" || !path.startsWith("/") || path.includes("\0")) return false;
   if (strictDecoder.decode(encoder.encode(path)) !== path) return false;
@@ -1014,7 +1065,7 @@ function base64ToBytes(value) {
 }
 
 export async function createFxAgent(options = {}) {
-  options = { ...options };
+  options = normalizeAgentOptions(options);
   const hostTools = normalizeHostTools(options.tools);
   const instructions = normalizeInstructions(options.instructions);
   const initialCheckpoint = checkpointBytes(options.checkpoint);
@@ -1047,7 +1098,12 @@ export async function createFxAgent(options = {}) {
     return { content, isError, cancelled: controller.signal.aborted };
   };
   emit("runtime.start");
-  const runtimeOptions = { ...options, args: ["acp"], hostToolExecutor: executeHostTool };
+  const runtimeOptions = {
+    ...options,
+    args: ["acp"],
+    env: agentEnvironment(options),
+    hostToolExecutor: executeHostTool,
+  };
   const runtime = options.runtimeFactory
     ? await options.runtimeFactory(runtimeOptions)
     : await instantiate(runtimeOptions);

package/node.js

@@ -67,9 +67,8 @@ function validateNativeBackend(backend) {
     const actualVersion = backend.libfxApiVersion ?? "missing";
     throw new Error(`native addon API version ${actualVersion} is incompatible with libfx API version ${libfxApiVersion}`);
   }
-  if (typeof backend.createFxAgent !== "function" && typeof backend.createCore !== "function" &&
-    typeof backend.createFxTerminal !== "function") {
-    throw new Error("native addon must export createFxAgent(), createCore(), or createFxTerminal()");
+  if (typeof backend.createCore !== "function" && typeof backend.createFxTerminal !== "function") {
+    throw new Error("native addon must export createCore() or createFxTerminal()");
   }
   return backend;
 }
@@ -120,26 +119,8 @@ function wasmBytes(input) {
   return pending;
 }
 
-function validateGatewayChatUrl(value) {
-  if (value === undefined) return;
-  if (typeof value !== "string") throw new TypeError("FX_GATEWAY_CHAT_URL must be a string");
-  let url;
-  try { url = new URL(value); } catch { throw new TypeError("FX_GATEWAY_CHAT_URL must be a valid URL"); }
-  if (url.username || url.password || url.hash) {
-    throw new TypeError("FX_GATEWAY_CHAT_URL must not contain credentials or a fragment");
-  }
-  if (url.href === "https://ai-gateway.vercel.sh/v3/ai/language-model") return;
-  const loopback = url.hostname === "127.0.0.1" || url.hostname === "[::1]" || url.hostname === "localhost";
-  if (url.protocol !== "http:" || !loopback || !url.port) {
-    throw new TypeError("FX_GATEWAY_CHAT_URL must use the canonical Gateway or explicit loopback HTTP");
-  }
-}
-
 function createNativeCoreRuntime(addon, options) {
-  const apiKey = options.env?.AI_GATEWAY_API_KEY;
-  const model = options.env?.FX_MODEL;
-  const gatewayChatUrl = options.env?.FX_GATEWAY_CHAT_URL;
-  validateGatewayChatUrl(gatewayChatUrl);
+  const { apiKey, model, gatewayChatUrl } = options;
   const core = addon.createCore({
     apiKey,
     home: options.home ?? homedir(),
@@ -258,7 +239,6 @@ function createNativeAgent(addon, options) {
 
 async function createWithFallback(surface, nativeMethod, wasmFactory, defaultWasm, options) {
   const { nativeAddon, backend = "auto", ...runtimeOptions } = options ?? {};
-  validateGatewayChatUrl(runtimeOptions.env?.FX_GATEWAY_CHAT_URL);
   if (!new Set(["auto", "native", "wasm"]).has(backend)) {
     throw new TypeError('backend must be "auto", "native", or "wasm"');
   }
@@ -268,14 +248,11 @@ async function createWithFallback(surface, nativeMethod, wasmFactory, defaultWas
   if (backend !== "wasm") {
     const native = await resolveNativeBackend(nativeAddon);
     nativeError = native.error;
-    if (typeof native.backend?.[nativeMethod] === "function" ||
-      (surface === "agent" && typeof native.backend?.createCore === "function")) {
+    if (typeof native.backend?.[nativeMethod] === "function") {
       nativeAttempted = true;
       try {
-        if (typeof native.backend?.[nativeMethod] === "function") {
-          return await native.backend[nativeMethod](runtimeOptions);
-        }
-        return await createNativeAgent(native.backend, runtimeOptions);
+        if (surface === "agent") return await createNativeAgent(native.backend, runtimeOptions);
+        return await native.backend[nativeMethod](runtimeOptions);
       } catch (error) {
         nativeError = error;
         if (backend === "native") throw error;
@@ -298,8 +275,17 @@ async function createWithFallback(surface, nativeMethod, wasmFactory, defaultWas
   });
 }
 
-export function createFxAgent(options = {}) {
-  return createWithFallback("agent", "createFxAgent", createWasmAgent, defaultCoreWasm, options);
+export async function createFxAgent(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",
+    createWasmAgent,
+    defaultCoreWasm,
+    options,
+  );
 }
 
 export function createFxTerminal(options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libfx",
-  "version": "0.0.7-dev.607.ga90fc3585568",
+  "version": "0.0.7-dev.617.g49fc251a51aa",
   "description": "Embed fx agents and terminals in JavaScript hosts",
   "type": "module",
   "repository": {