libfx 0.0.7-dev.609.g1f98d14929a0 → 0.0.7-dev.630.gc07d0e40d42d

package/README.md

@@ -19,7 +19,11 @@ 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",
+  onEvent(event) {
+    if (event.type === "transport.response") console.log(event.elapsedMs);
+  },
 });
 
 const turn = agent.prompt("Explain this project.");
@@ -33,6 +37,20 @@ 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()`.
+
+The host selects the model. Agent creation and prompting do not fetch the
+Gateway model catalog.
+
+`onEvent` receives runtime diagnostics separately from model output. Transport
+events report request start, response status and elapsed time, safe Gateway
+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:
 
@@ -46,17 +64,36 @@ 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
 durable storage and must resupply models, credentials, instructions, tools,
 MCP clients, and skill records.
 
+## Models
+
+Model discovery is explicit and does not create an Agent or load native or Wasm
+artifacts:
+
+```js
+import { listModels } from "libfx";
+
+const models = await listModels({
+  apiKey: process.env.AI_GATEWAY_API_KEY,
+});
+```
+
+`listModels()` performs one bounded Gateway request and returns sorted, unique
+language-model IDs. It accepts the same optional `fetch` override as the Agent
+API.
+
 ## JavaScript tools and instructions
 
 ```js
 const agent = await createFxAgent({
+  apiKey,
+  model,
   instructions: "Keep answers concise.",
   tools: [{
     name: "lookup",
@@ -70,14 +107,15 @@ const agent = await createFxAgent({
       return database.get(input.key, { signal });
     },
   }],
-  env,
 });
 ```
 
 The JavaScript host is the authority for tool effects. The same descriptors,
 schemas, cancellation, results, and events are used by N-API and WebAssembly.
 Instructions are limited to 64 KiB of UTF-8 text, including text assembled by
-the MCP and skills adapters.
+the MCP and skills adapters. They are the complete host-owned system context:
+libfx adds no hidden base prompt, and omitting `instructions` sends no system
+message.
 
 ## MCP
 
@@ -94,9 +132,10 @@ const mcp = await createMcpAdapter(client, {
 });
 
 const agent = await createFxAgent({
+  apiKey,
+  model,
   tools: mcp.tools,
   instructions: mcp.instructions,
-  env,
 });
 
 // ...
@@ -115,15 +154,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 +195,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/browser.js

@@ -3,11 +3,12 @@ import {
   createFxTerminal as createWasmTerminal,
   encodeXtermKeyEvent,
   fxSdkApiVersion,
+  listModels,
   supportsJspi,
   xtermAdapter,
 } from "./fx-sdk.js";
 
-export { encodeXtermKeyEvent, fxSdkApiVersion, supportsJspi, xtermAdapter };
+export { encodeXtermKeyEvent, fxSdkApiVersion, listModels, supportsJspi, xtermAdapter };
 export const libfxApiVersion = 2;
 
 const defaultCoreWasm = new URL("./fx-core.wasm", import.meta.url).href;

package/fx-sdk.js

@@ -5,8 +5,145 @@ 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 maxModelCatalogBytes = 4 * 1024 * 1024;
+const maxModelCatalogEntries = 10_000;
 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 }),
+  };
+}
+
+async function cancelResponseBody(response) {
+  try {
+    await response.body?.cancel();
+  } catch {}
+}
+
+async function readBoundedResponseText(response, limit) {
+  const declared = Number(response.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > limit) {
+    await cancelResponseBody(response);
+    throw new RangeError(`model catalog exceeds the ${limit} byte libfx limit`);
+  }
+  if (!response.body) {
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    if (bytes.length > limit) throw new RangeError(`model catalog exceeds the ${limit} byte libfx limit`);
+    return strictDecoder.decode(bytes);
+  }
+
+  const reader = response.body.getReader();
+  const chunks = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (!value?.length) continue;
+    total += value.length;
+    if (total > limit) {
+      try {
+        await reader.cancel();
+      } catch {}
+      throw new RangeError(`model catalog exceeds the ${limit} byte libfx limit`);
+    }
+    chunks.push(value);
+  }
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return strictDecoder.decode(bytes);
+}
+
+export async function listModels(options = {}) {
+  if (!options || typeof options !== "object" || Array.isArray(options)) {
+    throw new TypeError("listModels() options must be an object");
+  }
+  const apiKey = boundedString(options.apiKey, "apiKey", maxApiKeyBytes, true);
+  const fetchModels = options.fetch ?? globalThis.fetch?.bind(globalThis);
+  if (typeof fetchModels !== "function") throw new TypeError("fetch is unavailable");
+  const response = await fetchModels("https://ai-gateway.vercel.sh/coding-agent/v1/models", {
+    method: "GET",
+    headers: { authorization: `Bearer ${apiKey}` },
+  });
+  if (!response.ok) {
+    await cancelResponseBody(response);
+    throw new Error(`model catalog request failed with HTTP ${response.status}`);
+  }
+
+  let catalog;
+  try {
+    catalog = JSON.parse(await readBoundedResponseText(response, maxModelCatalogBytes));
+  } catch (error) {
+    if (error instanceof RangeError) throw error;
+    throw new TypeError("model catalog response is malformed");
+  }
+  if (!catalog || typeof catalog !== "object" || !Array.isArray(catalog.data)) {
+    throw new TypeError("model catalog response is malformed");
+  }
+  if (catalog.data.length > maxModelCatalogEntries) {
+    throw new RangeError(`model catalog exceeds the ${maxModelCatalogEntries} entry libfx limit`);
+  }
+
+  const ids = new Set();
+  for (const entry of catalog.data) {
+    if (!entry || typeof entry !== "object") continue;
+    if (typeof entry.type === "string" && entry.type.toLowerCase() !== "language") continue;
+    if (typeof entry.id !== "string" || entry.id.length === 0) continue;
+    if (encoder.encode(entry.id).length > maxModelBytes) continue;
+    ids.add(entry.id);
+  }
+  return [...ids].sort();
+}
+
 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 +1151,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);
@@ -1026,6 +1163,49 @@ export async function createFxAgent(options = {}) {
   const emit = (type, detail = {}) => {
     try { options.onEvent?.({ type, timestamp: performance.now(), ...detail }); } catch {}
   };
+  const hostFetch = options.fetch ?? globalThis.fetch?.bind(globalThis);
+  const transportFetch = async (input, init = {}) => {
+    const method = String(init.method ?? input?.method ?? "GET").toUpperCase();
+    let endpoint = String(input?.url ?? input);
+    try {
+      const url = new URL(endpoint);
+      endpoint = `${url.origin}${url.pathname}`;
+    } catch {}
+    for (let attemptIndex = 0; attemptIndex < 2; attemptIndex++) {
+      const startedAt = performance.now();
+      const attempt = activeTurn ? ++activeTurn.transportAttempts : attemptIndex + 1;
+      emit("transport.start", { attempt, method, endpoint, model: options.model });
+      try {
+        if (!hostFetch) throw new TypeError("fetch is unavailable");
+        const response = await hostFetch(input, init);
+        const headers = response.headers;
+        emit("transport.response", {
+          attempt,
+          status: response.status,
+          elapsedMs: performance.now() - startedAt,
+          requestId: headers.get("x-vercel-id"),
+          generationId: headers.get("x-generation-id"),
+          model: headers.get("x-model-id") ?? options.model,
+          provider: headers.get("x-vercel-ai-gateway-provider") ?? headers.get("x-ai-gateway-provider"),
+        });
+        return response;
+      } catch (error) {
+        const errorName = error instanceof Error ? error.name : "Error";
+        const elapsedMs = performance.now() - startedAt;
+        emit("transport.error", { attempt, elapsedMs, error: errorName });
+        if (init.signal?.aborted) throw new DOMException("Aborted", "AbortError");
+        if (attemptIndex === 1) throw error;
+        emit("transport.retry", {
+          attempt,
+          nextAttempt: attempt + 1,
+          elapsedMs,
+          error: errorName,
+        });
+        if (init.signal?.aborted) throw new DOMException("Aborted", "AbortError");
+      }
+    }
+    throw new Error("transport retry exhausted");
+  };
   const executeHostTool = async (name, input, requestedSessionId) => {
     const execute = hostTools.executors.get(name);
     const turn = requestedSessionId === undefined || requestedSessionId === sessionId
@@ -1047,7 +1227,13 @@ 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,
+    fetch: transportFetch,
+    args: ["acp"],
+    env: agentEnvironment(options),
+    hostToolExecutor: executeHostTool,
+  };
   const runtime = options.runtimeFactory
     ? await options.runtimeFactory(runtimeOptions)
     : await instantiate(runtimeOptions);
@@ -1219,6 +1405,7 @@ export async function createFxAgent(options = {}) {
     const turn = {
       push(update) { const waiter = waiters.shift(); if (waiter) waiter({ value: update, done: false }); else queue.push(update); },
       toolControllers,
+      transportAttempts: 0,
       cancel() {
         if (finished || cancelled) return;
         cancelled = true;

package/node.js

@@ -8,11 +8,12 @@ import {
   createFxTerminal as createWasmTerminal,
   encodeXtermKeyEvent,
   fxSdkApiVersion,
+  listModels,
   supportsJspi,
   xtermAdapter,
 } from "./fx-sdk.js";
 
-export { encodeXtermKeyEvent, fxSdkApiVersion, supportsJspi, xtermAdapter };
+export { encodeXtermKeyEvent, fxSdkApiVersion, listModels, supportsJspi, xtermAdapter };
 export const libfxApiVersion = 2;
 
 const fetchOperationStale = 0;
@@ -67,9 +68,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 +120,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 +240,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 +249,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 +276,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.609.g1f98d14929a0",
+  "version": "0.0.7-dev.630.gc07d0e40d42d",
   "description": "Embed fx agents and terminals in JavaScript hosts",
   "type": "module",
   "repository": {