libfx 0.0.7 → 0.0.8-dev.857.gba60fd94fa57

package/fx-sdk.js

@@ -1,10 +1,153 @@
+import { CoreOutput, maxCoreMessageBytes } from "./core-output.js";
+import { loadModule } from "./wasm-module.js";
+
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
 const strictDecoder = new TextDecoder("utf-8", { fatal: true });
 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;
+const maxUnreadEventBytes = 1024 * 1024;
+const maxUnreadEvents = 256;
+
+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;
@@ -50,7 +193,7 @@ function utf8Prefix(value, limit) {
   return value.subarray(0, end);
 }
 
-export const fxSdkApiVersion = 1;
+export const fxSdkApiVersion = 2;
 
 export function supportsJspi() {
   return typeof WebAssembly.Suspending === "function" &&
@@ -92,35 +235,6 @@ export function xtermAdapter(term) {
   };
 }
 
-function createMemorySessionStore() {
-  const records = new Map();
-  let nextRevision = 1;
-  return {
-    async load(id) {
-      const record = records.get(id);
-      return record ? { bytes: record.bytes.slice(), revision: record.revision } : null;
-    },
-    async commit(id, bytes, expectedRevision) {
-      const current = records.get(id);
-      if ((current?.revision) !== expectedRevision) throw revisionConflict();
-      const revision = String(nextRevision++);
-      records.set(id, { bytes: bytes.slice(), revision, updatedAtMs: Date.now() });
-      return { revision };
-    },
-    async list() {
-      return [...records.entries()].map(([id, record]) => ({ id, updatedAtMs: record.updatedAtMs }))
-        .sort((a, b) => b.updatedAtMs - a.updatedAtMs);
-    },
-    async remove(id) { records.delete(id); },
-  };
-}
-
-function revisionConflict() {
-  const error = new Error("session revision conflict");
-  error.code = "FX_SESSION_REVISION_CONFLICT";
-  return error;
-}
-
 class ByteQueue {
   chunks = [];
   waiters = [];
@@ -176,25 +290,6 @@ class ByteQueue {
   }
 }
 
-async function loadModule(input) {
-  if (input instanceof WebAssembly.Module) return input;
-  if (typeof input === "string") input = fetch(input);
-  if (input instanceof Promise) input = await input;
-  if (input instanceof WebAssembly.Module) return input;
-  if (input instanceof Response) {
-    const contentType = input.headers.get("content-type")?.split(";", 1)[0].trim().toLowerCase();
-    if (contentType === "application/wasm" && typeof WebAssembly.compileStreaming === "function") {
-      return WebAssembly.compileStreaming(input);
-    }
-    const bytes = await input.arrayBuffer();
-    return WebAssembly.compile(bytes);
-  }
-  if (input instanceof ArrayBuffer || ArrayBuffer.isView(input)) {
-    return WebAssembly.compile(input);
-  }
-  throw new TypeError("wasm must be a URL, Response, ArrayBuffer, typed array, or WebAssembly.Module");
-}
-
 function raceWithTimeout(promise, timeoutMs, timeoutValue) {
   let timer;
   return new Promise((resolve, reject) => {
@@ -214,8 +309,11 @@ function yieldToHostTask() {
 }
 
 function createRuntime(options) {
+  // Creating this inside a Wasm call would retain that instance through the error stack.
+  const abortReason = new DOMException("This operation was aborted", "AbortError");
   const stdin = new ByteQueue();
   const streams = new Map();
+  const httpRequests = new Set();
   const workspaceExecs = new Set();
   const workspace = prepareWorkspaceAdapter(options.workspace);
   const args = ["fx", ...(options.args || [])];
@@ -225,7 +323,8 @@ function createRuntime(options) {
   let exitedResolve;
   let exitCode = null;
   let aborted = false;
-  let lineBuffer = "";
+  let coreOutput;
+  let outputError;
   const exited = new Promise((resolve) => { exitedResolve = resolve; });
   const markExited = (code) => {
     if (exitCode !== null) return;
@@ -255,7 +354,7 @@ function createRuntime(options) {
   }
 
   function emitStdout(chunk) {
-    if (options.stdout) options.stdout(chunk);
+    if (options.stdout) return options.stdout(chunk);
   }
 
   function fdWrite(fd, iovs, count, nwritten) {
@@ -265,6 +364,7 @@ function createRuntime(options) {
     for (let index = 0; index < count; index++) {
       total += view.getUint32(iovs + index * 8 + 4, true);
     }
+    if (coreOutput && total > maxCoreMessageBytes) throw new RangeError("core output message exceeds 64 MiB");
     if (fd === 1 || fd === 2) {
       const chunk = new Uint8Array(total);
       let offset = 0;
@@ -274,7 +374,13 @@ function createRuntime(options) {
         chunk.set(bytes(ptr, len), offset);
         offset += len;
       }
-      if (fd === 1) emitStdout(chunk);
+      if (fd === 1) {
+        const pending = emitStdout(chunk);
+        if (coreOutput && pending) return Promise.resolve(pending).then(() => {
+          writeU32(nwritten, total);
+          return 0;
+        });
+      }
       else if (typeof options.stderr === "function") options.stderr(chunk);
       else console.warn(decoder.decode(chunk));
     }
@@ -442,16 +548,56 @@ function createRuntime(options) {
   }
 
   function httpRequest(methodPtr, methodLen, urlPtr, urlLen, headersPtr, headersLen, bodyPtr, bodyLen, statusOut, responsePtr, responseCap) {
-    return options.fetch(text(urlPtr, urlLen), {
-      method: text(methodPtr, methodLen),
-      headers: headersFromJson(headersPtr, headersLen),
-      body: bodyLen ? bytes(bodyPtr, bodyLen).slice() : undefined,
-    }).then(async (response) => {
+    const controller = new AbortController();
+    httpRequests.add(controller);
+    let onAbort;
+    const cancelled = new Promise((resolve) => {
+      onAbort = () => resolve(-1);
+      controller.signal.addEventListener("abort", onAbort, { once: true });
+    });
+    const request = (async () => {
+      const response = await options.fetch(text(urlPtr, urlLen), {
+        method: text(methodPtr, methodLen),
+        headers: headersFromJson(headersPtr, headersLen),
+        body: bodyLen ? bytes(bodyPtr, bodyLen).slice() : undefined,
+        signal: controller.signal,
+      });
+      if (controller.signal.aborted) {
+        void cancelResponseBody(response);
+        return -1;
+      }
       const body = new Uint8Array(await response.arrayBuffer());
+      if (controller.signal.aborted) return -1;
       new DataView(memory().buffer).setUint16(statusOut, response.status, true);
       if (body.length > responseCap) return -2;
       bytes(responsePtr, body.length).set(body);
       return body.length;
+    })().catch(() => -1);
+    return Promise.race([request, cancelled]).finally(() => {
+      controller.signal.removeEventListener("abort", onAbort);
+      httpRequests.delete(controller);
+    });
+  }
+
+  let pendingHostToolResult = null;
+  function hostToolCall(namePtr, nameLen, argumentsPtr, argumentsLen, outputPtr, outputCap, statusPtr) {
+    pendingHostToolResult = null;
+    if (typeof options.hostToolExecutor !== "function") return -1;
+    if (options.traceWasi) console.error("fx host tool call start");
+    let input;
+    try { input = JSON.parse(text(argumentsPtr, argumentsLen)); } catch { return -1; }
+    return Promise.resolve(options.hostToolExecutor(text(namePtr, nameLen), input)).then((result) => {
+      if (options.traceWasi) console.error("fx host tool call settled", result.cancelled, result.isError);
+      if (result.cancelled) return -2;
+      const output = encoder.encode(result.content);
+      bytes(statusPtr, 1)[0] = (result.isError ? 1 : 0) + (result.rich ? 2 : 0);
+      if (output.length > outputCap) {
+        if (!result.rich || output.length > 8 * 1024 * 1024) return -3;
+        pendingHostToolResult = output;
+        return output.length;
+      }
+      bytes(outputPtr, output.length).set(output);
+      return output.length;
     }).catch(() => -1);
   }
 
@@ -714,7 +860,9 @@ function createRuntime(options) {
   }
 
   function abortHostEffects() {
-    streams.forEach((state) => state.controller.abort());
+    pendingHostToolResult = null;
+    streams.forEach((state) => state.controller.abort(abortReason));
+    httpRequests.forEach((controller) => controller.abort(abortReason));
     workspaceExecs.forEach((state) => state.abort(-3));
   }
 
@@ -724,7 +872,7 @@ function createRuntime(options) {
     args_get(ptrs, data) { if (options.traceWasi) console.error("wasi args_get"); writeVector(args, ptrs, data); return 0; },
     environ_sizes_get(count, size) { if (options.traceWasi) console.error("wasi environ_sizes_get"); writeU32(count, env.length); writeU32(size, env.reduce((n, v) => n + encoder.encode(v).length + 1, 0)); return 0; },
     environ_get(ptrs, data) { if (options.traceWasi) console.error("wasi environ_get"); writeVector(env, ptrs, data); return 0; },
-    fd_write: fdWrite,
+    fd_write: options.args?.[0] === "acp" ? new WebAssembly.Suspending(fdWrite) : fdWrite,
     fd_read: new WebAssembly.Suspending(fdRead),
     fd_close() { return 0; },
     fd_fdstat_get(fd, out) {
@@ -772,8 +920,16 @@ function createRuntime(options) {
     fx_http_stream_open: streamOpen,
     fx_http_stream_status: new WebAssembly.Suspending(streamStatus),
     fx_http_stream_next: new WebAssembly.Suspending(streamNext),
-    fx_http_stream_close(handle) { const state = streams.get(handle); state?.controller.abort(); streams.delete(handle); },
+    fx_http_stream_close(handle) { const state = streams.get(handle); state?.controller.abort(abortReason); streams.delete(handle); },
     fx_http_request: new WebAssembly.Suspending(httpRequest),
+    fx_host_tool_call: new WebAssembly.Suspending(hostToolCall),
+    fx_host_tool_result_read(offset, ptr, cap) {
+      if (!pendingHostToolResult || offset < 0 || offset > pendingHostToolResult.length) return -1;
+      const chunk = pendingHostToolResult.subarray(offset, offset + cap);
+      bytes(ptr, chunk.length).set(chunk);
+      return chunk.length;
+    },
+    fx_host_tool_result_release() { pendingHostToolResult = null; },
     fx_open_url: new WebAssembly.Suspending(openUrl),
     fx_oauth_session_load: new WebAssembly.Suspending(oauthSessionLoad),
     fx_oauth_session_commit: new WebAssembly.Suspending(oauthSessionCommit),
@@ -803,8 +959,10 @@ function createRuntime(options) {
     wake() { stdin.wake(); },
     closeStdin() { stdin.close(); },
     abortHostEffects,
-    abort() {
+    abort(error) {
       aborted = true;
+      outputError = error;
+      coreOutput?.close();
       abortHostEffects();
       stdin.close();
       markExited(130);
@@ -812,17 +970,12 @@ function createRuntime(options) {
     markExited,
     get aborted() { return aborted; },
     get exitCode() { return exitCode; },
+    get error() { return outputError; },
     setLineHandler(handler) {
-      options.stdout = (chunk) => {
-        lineBuffer += decoder.decode(chunk, { stream: true });
-        for (;;) {
-          const newline = lineBuffer.indexOf("\n");
-          if (newline < 0) break;
-          const line = lineBuffer.slice(0, newline); lineBuffer = lineBuffer.slice(newline + 1);
-          if (line) handler(JSON.parse(line));
-        }
-      };
+      coreOutput = new CoreOutput(handler);
+      options.stdout = (chunk) => coreOutput.write(chunk);
     },
+    finishOutput() { coreOutput?.finish(); },
   };
 }
 
@@ -834,10 +987,21 @@ async function instantiate(options) {
   runtime.setInstance(instance);
   const start = WebAssembly.promising(instance.exports._start);
   start().then(
-    () => runtime.markExited(0),
+    () => {
+      runtime.setInstance(null);
+      try { runtime.finishOutput(); runtime.markExited(0); }
+      catch (error) { runtime.abort(error); }
+    },
     (error) => {
-      if (!String(error).includes("proc_exit")) console.error(error);
-      runtime.markExited(runtime.aborted ? 130 : 1);
+      runtime.setInstance(null);
+      if (options.args?.[0] === "acp" && !String(error).includes("proc_exit")) runtime.abort(error);
+      else {
+        if (!String(error).includes("proc_exit")) {
+          runtime.abortHostEffects();
+          console.error(error);
+        }
+        runtime.markExited(runtime.aborted ? 130 : 1);
+      }
     },
   );
   return runtime;
@@ -879,13 +1043,13 @@ export async function createFxTerminal(options) {
     if (interruptKey && data.includes(interruptKey)) runtime.abortHostEffects();
     runtime.write(data);
   };
-  const unsubscribeData = options.terminal.onData(forwardData);
-  const unsubscribeKeyData = options.terminal.onKeyData?.(forwardData) ?? (() => {});
   const signalResize = () => {
     emit("terminal.resize", { cols: options.terminal.cols, rows: options.terminal.rows });
     runtime.wake();
   };
-  const unsubscribeResize = options.terminal.onResize(signalResize);
+  let unsubscribeData;
+  let unsubscribeKeyData;
+  let unsubscribeResize;
   let subscriptionsReleased = false;
   const releaseSubscriptions = () => {
     if (subscriptionsReleased) return;
@@ -898,6 +1062,17 @@ export async function createFxTerminal(options) {
     releaseSubscriptions();
     emit("runtime.exit", { surface: "terminal", code });
   });
+  try {
+    unsubscribeData = options.terminal.onData(forwardData);
+    unsubscribeKeyData = options.terminal.onKeyData?.(forwardData);
+    unsubscribeResize = options.terminal.onResize(signalResize);
+  } catch (error) {
+    // The rejected factory never transfers this promise to a caller.
+    interactive.catch(() => {});
+    releaseSubscriptions();
+    runtime.abort();
+    throw error;
+  }
   return {
     interactive,
     exited: runtime.exited,
@@ -930,20 +1105,214 @@ function normalizePromptInput(input) {
   });
 }
 
-export async function createFxAgent(options) {
-  options = { ...options, sessionStore: options.sessionStore || createMemorySessionStore() };
+function normalizeHostTools(value) {
+  if (value === undefined) return { descriptors: [], executors: new Map() };
+  if (!Array.isArray(value)) throw new TypeError("tools must be an array");
+  if (value.length > 64) throw new RangeError("tools cannot contain more than 64 entries");
+  const descriptors = [];
+  const executors = new Map();
+  for (const [index, tool] of value.entries()) {
+    if (!tool || typeof tool !== "object") throw new TypeError(`tool ${index} must be an object`);
+    const { name, description, inputSchema, execute } = tool;
+    if (typeof name !== "string" || !/^[A-Za-z0-9_-]{1,64}$/.test(name)) {
+      throw new TypeError(`tool ${index} has an invalid name`);
+    }
+    if (executors.has(name)) throw new TypeError(`duplicate tool name: ${name}`);
+    if (typeof description !== "string") throw new TypeError(`tool ${name} requires a description`);
+    if (typeof execute !== "function") throw new TypeError(`tool ${name} requires execute()`);
+    if (!inputSchema || typeof inputSchema !== "object" || Array.isArray(inputSchema)) {
+      throw new TypeError(`tool ${name} requires an object inputSchema`);
+    }
+    let schema;
+    try { schema = JSON.parse(JSON.stringify(inputSchema)); } catch {
+      throw new TypeError(`tool ${name} inputSchema must be JSON-serializable`);
+    }
+    descriptors.push({ name, description, inputSchema: schema });
+    executors.set(name, execute);
+  }
+  return { descriptors, executors };
+}
+
+function normalizeInstructions(value) {
+  let instructions;
+  if (value === undefined) instructions = "";
+  else if (typeof value === "string") instructions = value;
+  if (Array.isArray(value) && value.every((entry) => typeof entry === "string")) {
+    instructions = value.filter(Boolean).join("\n\n");
+  }
+  if (instructions === undefined) {
+    throw new TypeError("instructions must be a string or an array of strings");
+  }
+  if (encoder.encode(instructions).length > maxInstructionsBytes) {
+    throw new RangeError(`instructions exceed the ${maxInstructionsBytes} byte libfx limit`);
+  }
+  return instructions;
+}
+
+function hostToolContent(value) {
+  if (value?.type === "libfx.tool-result") {
+    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) {
+        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 };
+    });
+    const content = JSON.stringify({ text: value.text, images });
+    if (new TextEncoder().encode(content).length > 8 * 1024 * 1024) throw new RangeError("typed tool result exceeds the result limit");
+    return { content, rich: true, isError: value.isError === true };
+  }
+  if (typeof value === "string") return { content: value, rich: false };
+  if (value === undefined) return { content: "null", rich: false };
+  const encoded = JSON.stringify(value);
+  return { content: encoded === undefined ? "null" : encoded, rich: false };
+}
+
+function checkpointBytes(value) {
+  if (value === undefined) return null;
+  if (value instanceof Uint8Array) return value.slice();
+  if (value instanceof ArrayBuffer) return new Uint8Array(value.slice(0));
+  if (ArrayBuffer.isView(value)) {
+    return new Uint8Array(value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength));
+  }
+  throw new TypeError("checkpoint must be an ArrayBuffer or typed array");
+}
+
+function bytesToBase64(value) {
+  let binary = "";
+  for (let offset = 0; offset < value.length; offset += 0x8000) {
+    binary += String.fromCharCode(...value.subarray(offset, offset + 0x8000));
+  }
+  return btoa(binary);
+}
+
+function base64ToBytes(value) {
+  const binary = atob(value);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index);
+  return bytes;
+}
+
+export async function createFxAgent(options = {}) {
+  options = normalizeAgentOptions(options);
+  const hostTools = normalizeHostTools(options.tools);
+  const instructions = normalizeInstructions(options.instructions);
+  const initialCheckpoint = checkpointBytes(options.checkpoint);
   const pending = new Map();
-  const turns = new Map();
   let nextId = 1;
-  let activeSession = null;
-  let loadingSessionId = null;
-  let loadingUpdates = [];
+  let sessionId = null;
+  let activeTurn = null;
   let closing = false;
+  const isCurrentTurn = (turn) => turn && activeTurn === turn && !turn.cancelled && !closing;
   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 (activeTurn?.cancelled) {
+          runtime.abortHostEffects();
+          throw new DOMException("Aborted", "AbortError");
+        }
+        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
+      ? activeTurn
+      : null;
+    if (!isCurrentTurn(turn)) return { content: "", isError: true, cancelled: true };
+    const controller = new AbortController();
+    turn.toolControllers.add(controller);
+    let onAbort;
+    const aborted = new Promise((resolve) => { onAbort = () => resolve(); });
+    controller.signal.addEventListener("abort", onAbort, { once: true });
+    let content = "";
+    let rich = false;
+    let isError = false;
+    try {
+      if (!execute) throw new Error(`unknown host tool: ${String(name)}`);
+      const execution = Promise.resolve().then(() => {
+        if (controller.signal.aborted || !isCurrentTurn(turn)) return;
+        return execute(input, { signal: controller.signal });
+      });
+      const value = await Promise.race([execution, aborted]);
+      if (!controller.signal.aborted) {
+        const normalized = hostToolContent(value);
+        content = normalized.content;
+        rich = normalized.rich;
+        isError = normalized.isError === true;
+      }
+    } catch (error) {
+      isError = true;
+      if (error?.toolResult?.type === "libfx.tool-result") {
+        try {
+          const normalized = hostToolContent(error.toolResult);
+          content = normalized.content;
+          rich = normalized.rich;
+        } catch {
+          content = error instanceof Error ? error.message : String(error);
+        }
+      } else {
+        content = error instanceof Error ? error.message : String(error);
+      }
+    } finally {
+      controller.signal.removeEventListener("abort", onAbort);
+      turn.toolControllers.delete(controller);
+    }
+    return { content, isError, rich, cancelled: controller.signal.aborted || !isCurrentTurn(turn) };
+  };
   emit("runtime.start");
-  const runtimeOptions = { ...options, args: ["acp"] };
+  const runtimeOptions = {
+    ...options,
+    fetch: transportFetch,
+    args: ["acp"],
+    env: agentEnvironment(options),
+    hostToolExecutor: executeHostTool,
+  };
   const runtime = options.runtimeFactory
     ? await options.runtimeFactory(runtimeOptions)
     : await instantiate(runtimeOptions);
@@ -960,170 +1329,265 @@ export async function createFxAgent(options) {
   });
   runtime.exited.then((code) => {
     emit("runtime.exit", { code });
-    const error = new Error(`fx-core exited with code ${code} before completing the ACP request`);
+    closing = true;
+    const error = runtime.error ?? new Error(`fx-core exited with code ${code} before completing the ACP request`);
     for (const waiter of pending.values()) waiter.reject(error);
     pending.clear();
   });
-  runtime.setLineHandler(async (message) => {
+  runtime.setLineHandler((message, size) => {
     emit("acp.receive", { message });
     if (message.method === "session/update") {
-      const turn = turns.get(message.params.sessionId);
-      if (turn) turn.push(message.params.update);
-      else if (loadingSessionId === message.params.sessionId) loadingUpdates.push(message.params.update);
+      if (message.params.sessionId === sessionId) return activeTurn?.push(message.params.update, size);
       return;
     }
+    void handleControlMessage(message).catch((error) => runtime.abort(error));
+  });
+  async function handleControlMessage(message) {
     if (message.method === "session/request_permission") {
+      const turn = activeTurn;
+      if (!isCurrentTurn(turn)) return;
       emit("permission.request", { request: message.params });
+      if (!isCurrentTurn(turn)) return;
       let optionId = null;
       try { optionId = await options.onPermission?.(message.params); } catch {}
+      if (!isCurrentTurn(turn)) return;
       emit("permission.resolve", { optionId });
+      if (!isCurrentTurn(turn)) return;
       send({ jsonrpc: "2.0", id: message.id, result: optionId ? { outcome: { outcome: "selected", optionId } } : { outcome: { outcome: "cancelled" } } });
       return;
     }
+    if (message.method === "libfx/tool_call") {
+      const { content, isError, rich, cancelled } = await executeHostTool(
+        message.params?.name,
+        message.params?.input,
+        message.params?.sessionId,
+      );
+      if (cancelled || closing) return;
+      const response = { jsonrpc: "2.0", id: message.id, result: { content, isError, ...(rich ? { contentType: "rich" } : {}) } };
+      if (encoder.encode(JSON.stringify(response)).length + 1 > 8 * 1024 * 1024) {
+        response.result = { content: "Host tool result exceeded the response frame limit", isError: true };
+      }
+      send(response);
+      return;
+    }
     const waiter = pending.get(message.id); if (!waiter) return; pending.delete(message.id);
     if (message.error) waiter.reject(new Error(message.error.message)); else waiter.resolve(message.result);
-  });
-  await request("initialize", { protocolVersion: 1, clientCapabilities: {} });
+  }
+  try {
+    await request("initialize", {
+      protocolVersion: 1,
+      clientCapabilities: {
+        ...(hostTools.descriptors.length || instructions
+          ? { libfx: { tools: hostTools.descriptors, instructions } }
+          : {}),
+      },
+    });
+
+    const sessionResult = await request("libfx/new");
+    sessionId = sessionResult.sessionId;
+    if (initialCheckpoint) {
+      await request("libfx/restore", {
+        sessionId,
+        checkpoint: bytesToBase64(initialCheckpoint),
+      });
+    }
+  } catch (error) {
+    closing = true;
+    try { runtime.abortHostEffects(); } catch {}
+    try { runtime.closeStdin(); } catch {}
+    try { await runtime.exited; } catch {}
+    throw error;
+  }
 
   const agent = {
-    exited: runtime.exited,
-    abort() { closing = true; runtime.abort(); },
+    prompt(input, promptOptions = {}) {
+      if (closing) throw new Error("fx agent is closed");
+      if (activeTurn) 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);
+    },
     async close() {
-      if (closing) return runtime.exited;
-      if (activeSession) await activeSession.close();
+      if (closing) { await runtime.exited; return; }
+      const turn = activeTurn;
+      turn?.cancel();
+      if (turn) await turn.result.catch(() => {});
       closing = true;
       runtime.closeStdin();
-      return runtime.exited;
-    },
-    async createSession() {
-      if (activeSession) await activeSession.close();
-      const result = await request("session/new");
-      activeSession = await makeSession(result);
-      return activeSession;
-    },
-    async listSessions() {
-      return (await request("session/list")).sessions || [];
-    },
-    async openSession(id) {
-      if (activeSession) await activeSession.close();
-      loadingSessionId = id;
-      loadingUpdates = [];
-      try {
-        const result = await request("session/load", { sessionId: id });
-        activeSession = await makeSession({ sessionId: id, history: loadingUpdates, ...result });
-        return activeSession;
-      } finally {
-        loadingSessionId = null;
-        loadingUpdates = [];
-      }
+      await runtime.exited;
     },
   };
   return agent;
 
-  async function makeSession(result) {
-    let configOptions = result.configOptions || [];
-    let closed = false;
-    let activeTurn = null;
-    const assertOpen = () => {
-      if (closed) throw new Error("fx session is closed");
-      if (activeSession !== session) throw new Error("fx session is no longer active");
+  function normalizeTurn(rawTurn) {
+    const toolNames = new Map();
+    const started = new Set();
+    const eventFor = (update) => {
+      if (update.sessionUpdate === "agent_message_chunk") {
+        const delta = update.content?.text;
+        if (!delta || delta.startsWith("[context]")) return null;
+        return { type: "text_delta", delta };
+      }
+      if (update.sessionUpdate === "agent_thought_chunk") {
+        const delta = update.content?.text;
+        return delta ? { type: "reasoning_delta", delta } : null;
+      }
+      if (update.sessionUpdate === "tool_call") {
+        toolNames.set(update.toolCallId, update.name || update.toolName || update.title || "tool");
+        if (started.has(update.toolCallId)) return null;
+        started.add(update.toolCallId);
+        return {
+          type: "tool_start",
+          id: update.toolCallId,
+          name: toolNames.get(update.toolCallId),
+        };
+      }
+      if (update.sessionUpdate === "tool_call_update" &&
+        (update.status === "completed" || update.status === "failed")) {
+        const content = update.content?.find((entry) => entry.content?.type === "text")?.content?.text;
+        return {
+          type: "tool_end",
+          id: update.toolCallId,
+          name: toolNames.get(update.toolCallId) || "tool",
+          ...(content === undefined ? {} : { content }),
+          isError: update.status === "failed",
+        };
+      }
+      return null;
     };
-    const updateConfig = (response) => {
-      configOptions = response.configOptions || configOptions;
-      return configOptions;
+    const result = rawTurn.result.then((value) => ({
+      stopReason: value.stopReason,
+      usage: normalizeTurnUsage(value.usage),
+    }));
+    void result.catch(() => {});
+    return {
+      cancel() { rawTurn.cancel(); },
+      [Symbol.asyncIterator]() {
+        const iterator = (async function* () {
+          for await (const update of rawTurn) {
+            const event = eventFor(update);
+            if (event) yield event;
+          }
+        })();
+        return {
+          next(value) { return iterator.next(value); },
+          return(value) { rawTurn.cancel(); return iterator.return(value); },
+          throw(error) { rawTurn.cancel(); return iterator.throw(error); },
+          [Symbol.asyncIterator]() { return this; },
+        };
+      },
+      result,
     };
-    const session = {
-      id: result.sessionId,
-      modes: result.modes,
-      history: result.history || [],
-      get configOptions() { return configOptions; },
-      async setConfigOption(configId, value, source = "sdk") {
-        assertOpen();
-        const previousValue = configOptions.find((option) => option.id === configId)?.currentValue;
-        const updated = updateConfig(await request("session/set_config_option", { sessionId: result.sessionId, configId, value }));
-        const accepted = updated.find((option) => option.id === configId)?.currentValue;
-        if (configId === "mode" && accepted) this.modes.currentModeId = accepted;
-        if (accepted === value) {
-          if (options.configStore?.set) {
-            try { await options.configStore.set(configId, value); } catch (error) { emit("config.persist_error", { configId, error }); }
+  }
+
+  function normalizeTurnUsage(usage) {
+    const result = {};
+    if (Number.isSafeInteger(usage?.inputTokens)) result.inputTokens = usage.inputTokens;
+    if (Number.isSafeInteger(usage?.outputTokens)) result.outputTokens = usage.outputTokens;
+    if (Number.isSafeInteger(usage?.cacheReadTokens)) result.cacheReadTokens = usage.cacheReadTokens;
+    if (Number.isSafeInteger(usage?.cacheWriteTokens)) result.cacheWriteTokens = usage.cacheWriteTokens;
+    if (Number.isSafeInteger(usage?.reasoningTokens)) result.reasoningTokens = usage.reasoningTokens;
+    return result;
+  }
+
+  function startTurn(input, promptOptions) {
+    const prompt = normalizePromptInput(input);
+    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 = [];
+    const waiters = [];
+    let queuedBytes = 0;
+    let resumeOutput;
+    let iteratorTaken = false;
+    let terminalError;
+    let reportedPressure = false;
+    let discardedBytes = 0;
+    const toolControllers = new Set();
+    let finished = false;
+    let cancelled = false;
+    const turn = {
+      push(update, size = encoder.encode(JSON.stringify(update)).length) {
+        if (cancelled || finished) { discardedBytes += size; return; }
+        if (size > maxCoreMessageBytes) throw new RangeError("core output message exceeds 64 MiB");
+        if (queue.length && (queue.length >= maxUnreadEvents || size > maxUnreadEventBytes - queuedBytes)) {
+          const capacity = new Promise((resolveCapacity) => { resumeOutput = resolveCapacity; });
+          if (!reportedPressure) {
+            reportedPressure = true;
+            emit("output.backpressure", { bufferedBytes: queuedBytes, bufferedEvents: queue.length });
           }
-          emit("config.changed", { configId, previousValue, value: accepted, source });
+          return capacity.then(() => turn.push(update, size));
         }
-        return updated;
-      },
-      setModel(value) { return this.setConfigOption("model", value); },
-      setMode(value) { return this.setConfigOption("mode", value); },
-      async setConfig(config) {
-        for (const [key, value] of Object.entries(config)) await this.setConfigOption(key, value);
-        return configOptions;
+        const waiter = waiters.shift();
+        if (waiter) waiter.resolve({ value: update, done: false });
+        else { queue.push({ update, size }); queuedBytes += size; }
       },
-      async close() {
-        if (closed) return;
-        activeTurn?.cancel();
-        if (activeTurn) await activeTurn.result.catch(() => {});
-        closed = true;
-        activeTurn = null;
-        if (activeSession === session) activeSession = null;
+      toolControllers,
+      transportAttempts: 0,
+      get cancelled() { return cancelled; },
+      cancel() {
+        if (finished || cancelled) return;
+        cancelled = true;
+        resumeOutput?.();
+        resumeOutput = null;
+        send({ jsonrpc: "2.0", method: "session/cancel", params: { sessionId } });
+        for (const controller of toolControllers) controller.abort();
+        runtime.abortHostEffects();
       },
-      async remove() {
-        if (activeTurn) throw new Error("cannot remove a session while a prompt is active");
-        await request("session/remove", { sessionId: result.sessionId });
-        closed = true;
-        if (activeSession === session) activeSession = null;
-      },
-      prompt(input, promptOptions = {}) {
-        assertOpen();
-        if (activeTurn) throw new Error("a prompt is already in progress for this session");
-        const prompt = normalizePromptInput(input);
-        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 = [];
-        const waiters = [];
-        let finished = false;
-        let cancelled = false;
-        const turn = {
-          push(update) { const waiter = waiters.shift(); if (waiter) waiter({ value: update, done: false }); else queue.push(update); },
-          cancel() {
-            if (finished || cancelled) return;
-            cancelled = true;
-            send({ jsonrpc: "2.0", method: "session/cancel", params: { sessionId: result.sessionId } });
-            runtime.abortHostEffects();
+      [Symbol.asyncIterator]() {
+        if (iteratorTaken) throw new Error("a turn has only one event consumer");
+        iteratorTaken = true;
+        return {
+          next() {
+            if (queue.length) {
+              const { update, size } = queue.shift();
+              queuedBytes -= size;
+              resumeOutput?.();
+              resumeOutput = null;
+              return Promise.resolve({ value: update, done: false });
+            }
+            if (terminalError) return Promise.reject(terminalError);
+            if (finished) return Promise.resolve({ done: true });
+            return new Promise((resolve, reject) => waiters.push({ resolve, reject }));
           },
-          [Symbol.asyncIterator]() { return { next() { if (queue.length) return Promise.resolve({ value: queue.shift(), done: false }); if (finished) return Promise.resolve({ done: true }); return new Promise((resolve) => waiters.push(resolve)); } }; },
+          return() { turn.cancel(); return Promise.resolve({ done: true }); },
         };
-        turns.set(result.sessionId, turn);
-        activeTurn = turn;
-        const abort = () => turn.cancel();
-        signal?.addEventListener("abort", abort, { once: true });
-        turn.result = request("session/prompt", { sessionId: result.sessionId, prompt })
-          .then((response) => ({ stopReason: response.stopReason }))
-          .catch((error) => {
-            if (error.message === "Cancelled") return { stopReason: "cancelled" };
-            throw error;
-          })
-          .finally(() => {
-            finished = true;
-            signal?.removeEventListener("abort", abort);
-            turns.delete(result.sessionId);
-            if (activeTurn === turn) activeTurn = null;
-            waiters.splice(0).forEach((resolve) => resolve({ done: true }));
-          });
-        turn.stopReason = turn.result.then((turnResult) => turnResult.stopReason);
-        void turn.stopReason.catch(() => {});
-        if (signal?.aborted) turn.cancel();
-        return turn;
       },
     };
-    if (options.configStore?.get) {
-      activeSession = session;
-      for (const config of [...configOptions]) {
-        let value;
-        try { value = await options.configStore.get(config.id); } catch (error) { emit("config.restore_error", { configId: config.id, error }); continue; }
-        if (typeof value !== "string" || value === config.currentValue) continue;
-        try { await session.setConfigOption(config.id, value, "restore"); } catch (error) { emit("config.restore_error", { configId: config.id, error }); }
-      }
+    if (signal?.aborted) {
+      finished = true;
+      turn.result = Promise.resolve({ stopReason: "cancelled" });
+      return turn;
     }
-    session.modes.currentModeId = configOptions.find((option) => option.id === "mode")?.currentValue || session.modes.currentModeId;
-    return session;
+    activeTurn = turn;
+    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") return { stopReason: "cancelled" };
+        terminalError = error;
+        throw error;
+      })
+      .finally(() => {
+        finished = true;
+        resumeOutput?.();
+        resumeOutput = null;
+        signal?.removeEventListener("abort", abort);
+        if (activeTurn === turn) activeTurn = null;
+        toolControllers.clear();
+        if (discardedBytes) emit("output.discarded", { reason: "cancelled", bytes: discardedBytes });
+        for (const waiter of waiters.splice(0)) {
+          if (terminalError) waiter.reject(terminalError);
+          else waiter.resolve({ done: true });
+        }
+      });
+    if (signal?.aborted) turn.cancel();
+    void turn.result.catch(() => {});
+    return turn;
   }
 }