libfx 0.0.15 → 0.0.16

package/wasm-runtime.js

@@ -0,0 +1,1049 @@
+// The WebAssembly host: WASI, fx's host imports, and starting an fx
+// WebAssembly module. Only the WebAssembly backends load it.
+import { CoreOutput, maxCoreMessageBytes } from "./core-output.js";
+import {
+  cancelResponseBody,
+  decoder,
+  encoder,
+  maxPendingAttachments,
+  maxSteeringMessageBytes,
+  maxSteeringMessages,
+  maxSteeringQueueBytes,
+  strictDecoder,
+  supportsJspi,
+  utf8Prefix,
+} from "./engine.js";
+import { loadModule } from "./wasm-module.js";
+
+const workspaceInfoLimit = 4 * 1024;
+const workspaceCommandLimit = 64 * 1024;
+const workspaceOutputLimit = 64 * 1024;
+// Matches max_instruction_file_bytes and max_instruction_path_bytes in js_host_workspace.zig.
+const workspaceInstructionFileLimit = 1024 * 1024;
+const workspaceInstructionPathLimit = 4 * 1024;
+const workspaceReadTimeoutMs = 10_000;
+const streamReadsPerTaskYield = 32;
+const maxOutboundAttachments = 4;
+
+function validWorkspacePath(path) {
+  if (typeof path !== "string" || !path.startsWith("/") || path.includes("\0")) return false;
+  if (strictDecoder.decode(encoder.encode(path)) !== path) return false;
+  if (path === "/") return true;
+  if (path.endsWith("/")) return false;
+  return path.slice(1).split("/").every((part) => part && part !== "." && part !== "..");
+}
+
+function workspacePathInside(root, path) {
+  return root === "/" ? path.startsWith("/") : path === root || path.startsWith(`${root}/`);
+}
+
+// fx only reads AGENTS.md files below the workspace root or the host home.
+function workspaceInstructionPathAllowed(info, path) {
+  return validWorkspacePath(path) && path.endsWith("/AGENTS.md") &&
+    (workspacePathInside(info.root, path) || workspacePathInside(info.home, path));
+}
+
+function prepareWorkspaceAdapter(workspace) {
+  if (workspace == null) return { present: false, valid: false };
+  try {
+    const info = workspace.info;
+    const permission = workspace.permission;
+    const readFile = workspace.readFile;
+    if (!info || typeof workspace.exec !== "function" || info.version !== 1 ||
+      (readFile !== undefined && typeof readFile !== "function") ||
+      !validWorkspacePath(info.root) || !validWorkspacePath(info.cwd) ||
+      !validWorkspacePath(info.home) || info.cwd !== info.root ||
+      info.gitAvailable !== false || info.ephemeral !== true ||
+      (permission !== "allow-sandboxed" && permission !== "prompt")) {
+      return { present: true, valid: false };
+    }
+    const value = {
+      version: 1,
+      root: info.root,
+      cwd: info.cwd,
+      home: info.home,
+      git: false,
+      ephemeral: true,
+      permission,
+      instruction_files: typeof readFile === "function",
+    };
+    const encoded = encoder.encode(JSON.stringify(value));
+    if (encoded.length > workspaceInfoLimit) return { present: true, valid: false };
+    return { present: true, valid: true, adapter: workspace, info: value, encoded };
+  } catch {
+    return { present: true, valid: false };
+  }
+}
+
+class ByteQueue {
+  chunks = [];
+  waiters = [];
+  closed = false;
+
+  push(bytes) {
+    if (this.closed) throw new Error("fx runtime stdin is closed");
+    if (!bytes.length) return;
+    this.chunks.push(bytes);
+    this.wake();
+  }
+
+  read(max) {
+    if (!this.chunks.length) return null;
+    const chunk = this.chunks[0];
+    const value = chunk.subarray(0, max);
+    if (value.length === chunk.length) this.chunks.shift();
+    else this.chunks[0] = chunk.subarray(value.length);
+    return value;
+  }
+
+  wait(timeoutMs) {
+    if (this.closed) return Promise.resolve(true);
+    return new Promise((resolve) => {
+      let settled = false;
+      let timer;
+      const waiter = () => {
+        if (settled) return;
+        settled = true;
+        if (timer !== undefined) clearTimeout(timer);
+        resolve(true);
+      };
+      this.waiters.push(waiter);
+      if (timeoutMs !== undefined) {
+        timer = setTimeout(() => {
+          if (settled) return;
+          settled = true;
+          const index = this.waiters.indexOf(waiter);
+          if (index >= 0) this.waiters.splice(index, 1);
+          resolve(false);
+        }, timeoutMs);
+      }
+    });
+  }
+
+  close() {
+    this.closed = true;
+    this.wake();
+  }
+
+  wake() {
+    this.waiters.splice(0).forEach((resolve) => resolve());
+  }
+}
+
+function raceWithTimeout(promise, timeoutMs, timeoutValue) {
+  let timer;
+  return new Promise((resolve, reject) => {
+    timer = setTimeout(() => resolve(timeoutValue), timeoutMs);
+    promise.then(
+      (value) => { clearTimeout(timer); resolve(value); },
+      (error) => { clearTimeout(timer); reject(error); },
+    );
+  });
+}
+
+function yieldToHostTask() {
+  if (typeof globalThis.setImmediate === "function") {
+    return new Promise((resolve) => globalThis.setImmediate(resolve));
+  }
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+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 steering = [];
+  let steeringBytes = 0;
+  let steeringOpen = false;
+  // A steer that cannot join the running turn waits to run next.
+  let steeringHandoff = false;
+  // Raw payloads beside ACP frames: the core copies inbound bytes into its
+  // own memory and publishes outbound bytes for the agent to take.
+  const inboundAttachments = new Map();
+  const outboundAttachments = new Map();
+  let nextOutboundAttachment = 1;
+  const workspaceOperations = new Set();
+  const workspace = prepareWorkspaceAdapter(options.workspace);
+  const args = ["fx", ...(options.args || [])];
+  const env = Object.entries(options.env || {}).map(([key, value]) => `${key}=${value}`);
+  let instance;
+  let nextHandle = 1;
+  let exitedResolve;
+  let exitCode = null;
+  let aborted = false;
+  let coreOutput;
+  let outputError;
+  const exited = new Promise((resolve) => { exitedResolve = resolve; });
+  const markExited = (code) => {
+    if (exitCode !== null) return;
+    exitCode = code;
+    exitedResolve(code);
+  };
+  const memory = () => instance.exports.memory;
+  const bytes = (ptr, len) => new Uint8Array(memory().buffer, ptr, len);
+  const text = (ptr, len) => decoder.decode(bytes(ptr, len));
+  const writeU32 = (ptr, value) => new DataView(memory().buffer).setUint32(ptr, value, true);
+  const writeU64 = (ptr, value) => new DataView(memory().buffer).setBigUint64(ptr, BigInt(value), true);
+
+  function checkedBytes(ptr, len) {
+    if (!Number.isInteger(ptr) || !Number.isInteger(len) || ptr < 0 || len < 0 ||
+      ptr > memory().buffer.byteLength || len > memory().buffer.byteLength - ptr) return null;
+    return bytes(ptr, len);
+  }
+
+  function writeVector(values, ptrs, data) {
+    let cursor = data;
+    values.forEach((value, index) => {
+      const encoded = encoder.encode(`${value}\0`);
+      writeU32(ptrs + index * 4, cursor);
+      bytes(cursor, encoded.length).set(encoded);
+      cursor += encoded.length;
+    });
+  }
+
+  function emitStdout(chunk) {
+    if (options.stdout) return options.stdout(chunk);
+  }
+
+  function fdWrite(fd, iovs, count, nwritten) {
+    if (options.traceWasi) console.error("wasi fd_write", { fd, count });
+    const view = new DataView(memory().buffer);
+    let total = 0;
+    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;
+      for (let index = 0; index < count; index++) {
+        const ptr = view.getUint32(iovs + index * 8, true);
+        const len = view.getUint32(iovs + index * 8 + 4, true);
+        chunk.set(bytes(ptr, len), offset);
+        offset += len;
+      }
+      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));
+    }
+    writeU32(nwritten, total);
+    return 0;
+  }
+
+  function fdRead(fd, iovs, count, nread) {
+    if (fd !== 0) return 8;
+    const attempt = () => {
+      const view = new DataView(memory().buffer);
+      let total = 0;
+      for (let index = 0; index < count; index++) {
+        const ptr = view.getUint32(iovs + index * 8, true);
+        const len = view.getUint32(iovs + index * 8 + 4, true);
+        const chunk = stdin.read(len);
+        if (!chunk) break;
+        bytes(ptr, chunk.length).set(chunk);
+        total += chunk.length;
+        if (chunk.length < len) break;
+      }
+      if (total) { writeU32(nread, total); return 0; }
+      return null;
+    };
+    const immediate = attempt();
+    if (immediate !== null) return immediate;
+    if (stdin.closed) { writeU32(nread, 0); return 0; }
+    return stdin.wait().then(() => {
+      const result = attempt();
+      if (result !== null) return result;
+      writeU32(nread, 0);
+      return 0;
+    });
+  }
+
+  function pollOneoff(subscriptions, events, count, nevents) {
+    const view = new DataView(memory().buffer);
+    for (let index = 0; index < count; index++) {
+      const base = subscriptions + index * 48;
+      const type = view.getUint8(base + 8);
+      if (type === 1 && stdin.chunks.length) {
+        bytes(events, 32).fill(0);
+        bytes(events, 8).set(bytes(base, 8));
+        view.setUint8(events + 10, 1);
+        writeU32(nevents, 1);
+        return 0;
+      }
+    }
+    let timeout = null;
+    for (let index = 0; index < count; index++) {
+      const base = subscriptions + index * 48;
+      if (view.getUint8(base + 8) === 0) timeout = Number(view.getBigUint64(base + 24, true) / 1000000n);
+    }
+    return stdin.wait(timeout === null ? undefined : timeout).then(() => {
+      bytes(events, 32).fill(0);
+      bytes(events, 8).set(bytes(subscriptions, 8));
+      writeU32(nevents, 1);
+      return 0;
+    });
+  }
+
+  function termPollInput(timeoutMs) {
+    options.onTerminalPoll?.();
+    if (stdin.chunks.length) return 1;
+    if (stdin.closed) return -1;
+    if (timeoutMs === 0) return 0;
+    return stdin.wait(timeoutMs >= 0 ? timeoutMs : undefined).then(() =>
+      stdin.chunks.length ? 1 : (stdin.closed ? -1 : 0));
+  }
+
+  function headersFromJson(ptr, len) {
+    const headers = new Headers();
+    for (const { name, value } of JSON.parse(text(ptr, len) || "[]")) headers.append(name, value);
+    return headers;
+  }
+
+  function streamOpen(methodPtr, methodLen, urlPtr, urlLen, headersPtr, headersLen, bodyPtr, bodyLen) {
+    const controller = new AbortController();
+    const handle = nextHandle++;
+    const state = {
+      controller,
+      reader: null,
+      leftover: new Uint8Array(),
+      response: null,
+      responseError: null,
+      responseSettled: null,
+      pendingRead: null,
+      readResult: null,
+      readError: null,
+      readsSinceTaskYield: 0,
+    };
+    streams.set(handle, state);
+    state.responseSettled = Promise.resolve().then(() => options.fetch(text(urlPtr, urlLen), {
+      method: text(methodPtr, methodLen),
+      headers: headersFromJson(headersPtr, headersLen),
+      body: bodyLen ? bytes(bodyPtr, bodyLen).slice() : undefined,
+      signal: controller.signal,
+    })).then((response) => {
+      state.response = response;
+      state.reader = response.body?.getReader() || null;
+    }).catch((error) => {
+      state.responseError = error;
+    });
+    return handle;
+  }
+
+  function streamStatus(handle, statusOut) {
+    const state = streams.get(handle);
+    if (!state) return -1;
+    const settled = () => {
+      if (state.responseError) return state.responseError?.name === "AbortError" ? -2 : -1;
+      if (!state.response) return 0;
+      new DataView(memory().buffer).setUint16(statusOut, state.response.status, true);
+      return 1;
+    };
+    const immediate = settled();
+    if (immediate !== 0) return immediate;
+    return raceWithTimeout(state.responseSettled.then(() => true), 50, false).then((ready) =>
+      ready ? settled() : 0);
+  }
+
+  function streamNext(handle, outPtr, outCap) {
+    const state = streams.get(handle);
+    if (!state) return -1;
+    const yieldAfterReadyResult = (result) => {
+      if (result <= 0) return result;
+      state.readsSinceTaskYield += 1;
+      if (state.readsSinceTaskYield < streamReadsPerTaskYield) return result;
+      state.readsSinceTaskYield = 0;
+      return yieldToHostTask().then(() => result);
+    };
+    const copy = (chunk) => {
+      const written = chunk.subarray(0, outCap);
+      bytes(outPtr, written.length).set(written);
+      state.leftover = chunk.subarray(written.length);
+      return written.length;
+    };
+    const consume = () => {
+      if (state.leftover.length) return copy(state.leftover);
+      if (state.readError) return state.readError?.name === "AbortError" ? -2 : -1;
+      if (!state.readResult) return null;
+      const { done, value } = state.readResult;
+      state.readResult = null;
+      if (done) return 0;
+      if (!value?.length) return null;
+      options.onTransportChunk?.(value.length);
+      return copy(value);
+    };
+    const immediate = consume();
+    if (immediate !== null) return yieldAfterReadyResult(immediate);
+    if (!state.reader) return 0;
+    if (!state.pendingRead) {
+      state.pendingRead = state.reader.read().then((result) => {
+        state.readResult = result;
+        state.pendingRead = null;
+      }).catch((error) => {
+        state.readError = error;
+        state.pendingRead = null;
+      });
+    }
+    return raceWithTimeout(state.pendingRead.then(() => true), 50, false).then((ready) => {
+      if (!ready) return -3;
+      const result = consume();
+      return result === null ? -3 : yieldAfterReadyResult(result);
+    });
+  }
+
+  function httpRequest(methodPtr, methodLen, urlPtr, urlLen, headersPtr, headersLen, bodyPtr, bodyLen, statusOut, responsePtr, responseCap) {
+    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);
+    });
+  }
+
+  function clearSteering() {
+    steering.length = 0;
+    steeringBytes = 0;
+    steeringHandoff = false;
+  }
+
+  function queueSteering(text, id = "") {
+    if (!steeringOpen) throw new Error("no prompt is running");
+    const value = encoder.encode(text);
+    if (value.length === 0) throw new TypeError("steering text cannot be empty");
+    if (value.length > maxSteeringMessageBytes) {
+      throw new RangeError(`steering text exceeds the ${maxSteeringMessageBytes} byte libfx limit`);
+    }
+    if (steering.length >= maxSteeringMessages || value.length > maxSteeringQueueBytes - steeringBytes) {
+      throw new Error("steering queue is full");
+    }
+    steering.push({ id, value });
+    steeringBytes += value.length;
+  }
+
+  // The core takes queued steering at a boundary; until then it can be withdrawn.
+  function withdrawSteering(id) {
+    const index = steering.findIndex((entry) => entry.id === id);
+    if (index < 0) return false;
+    steeringBytes -= steering[index].value.length;
+    steering.splice(index, 1);
+    return true;
+  }
+
+  // Each message is its input id, a newline, then the text.
+  function steeringTake(outputPtr, outputCap) {
+    const entry = steering[0];
+    if (!entry) return 0;
+    const output = checkedBytes(outputPtr, outputCap);
+    const id = encoder.encode(entry.id);
+    const length = id.length + 1 + entry.value.length;
+    if (!output || length > output.length) return -1;
+    output.set(id, 0);
+    output[id.length] = 10;
+    output.set(entry.value, id.length + 1);
+    steering.shift();
+    steeringBytes -= entry.value.length;
+    return length;
+  }
+
+  function writeAttachment(id, data) {
+    if (inboundAttachments.size >= maxPendingAttachments) throw new Error("attachment table is full");
+    inboundAttachments.set(id, data.slice());
+  }
+
+  function attachmentSize(id) {
+    return inboundAttachments.get(id >>> 0)?.length ?? -1;
+  }
+
+  function attachmentTake(id, outputPtr, outputCap) {
+    const key = id >>> 0;
+    const value = inboundAttachments.get(key);
+    if (!value) return -1;
+    // An empty payload needs no output buffer, whose pointer may be arbitrary.
+    if (value.length > 0) {
+      const output = checkedBytes(outputPtr, outputCap);
+      if (!output || value.length > output.length) return -1;
+      output.set(value);
+    }
+    inboundAttachments.delete(key);
+    return value.length;
+  }
+
+  function attachmentPut(inputPtr, inputLen) {
+    const input = checkedBytes(inputPtr, inputLen);
+    if (!input || outboundAttachments.size >= maxOutboundAttachments) return -1;
+    const id = nextOutboundAttachment;
+    nextOutboundAttachment = id === 0x7fffffff ? 1 : id + 1;
+    outboundAttachments.set(id, input.slice());
+    return id;
+  }
+
+  // Resolves once the agent's journal holds every event the core sent.
+  function journalFlush() {
+    if (typeof options.journalFlush !== "function") return -1;
+    return Promise.resolve().then(() => options.journalFlush()).then(() => 0, () => -1);
+  }
+
+  let pendingHostToolResult = null;
+  function hostToolCall(namePtr, nameLen, argumentsPtr, argumentsLen, outputPtr, outputCap, statusPtr, callIdPtr, callIdLen) {
+    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, undefined, text(callIdPtr, callIdLen))).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);
+  }
+
+  function openUrl(urlPtr, urlLen) {
+    if (typeof options.openUrl !== "function") return 0;
+    return Promise.resolve().then(() => options.openUrl(text(urlPtr, urlLen))).then((accepted) =>
+      accepted === false ? 0 : 1).catch(() => 0);
+  }
+
+  function clipboardCopy(valuePtr, valueLen) {
+    let clipboard = options.clipboard;
+    if (clipboard === undefined) {
+      try { clipboard = globalThis.navigator?.clipboard; } catch { clipboard = null; }
+    }
+    if (typeof clipboard?.writeText !== "function") return Promise.resolve(0);
+    const value = text(valuePtr, valueLen);
+    return Promise.resolve().then(() => clipboard.writeText(value)).then((accepted) => {
+      if (accepted === false) return 0;
+      options.emit?.("clipboard.copy", { length: value.length });
+      return 1;
+    }).catch((error) => {
+      options.emit?.("clipboard.copy_error", { error });
+      return 0;
+    });
+  }
+
+  function oauthSessionLoad(outPtr, outCap, revisionPtr, revisionCap, revisionLenOut) {
+    if (!options.oauthSessionStore?.load) return -1;
+    return Promise.resolve().then(() => options.oauthSessionStore.load()).then((record) => {
+      if (!record) return -2;
+      const value = record.bytes instanceof Uint8Array ? record.bytes : new Uint8Array(record.bytes);
+      if (typeof record.revision !== "string") return -1;
+      const revision = encoder.encode(record.revision);
+      if (value.length > outCap || revision.length > revisionCap) return -3;
+      bytes(outPtr, value.length).set(value);
+      bytes(revisionPtr, revision.length).set(revision);
+      writeU32(revisionLenOut, revision.length);
+      return value.length;
+    }).catch(() => -1);
+  }
+
+  function oauthSessionCommit(valuePtr, valueLen, expectedPtr, expectedLen, revisionPtr, revisionCap, revisionLenOut) {
+    if (!options.oauthSessionStore?.commit) return -1;
+    const expectedRevision = expectedLen ? text(expectedPtr, expectedLen) : undefined;
+    const value = bytes(valuePtr, valueLen).slice();
+    return Promise.resolve().then(() => options.oauthSessionStore.commit(value, expectedRevision)).then((result) => {
+      if (typeof result?.revision !== "string") return -1;
+      const revision = encoder.encode(result.revision);
+      if (revision.length > revisionCap) return -1;
+      bytes(revisionPtr, revision.length).set(revision);
+      writeU32(revisionLenOut, revision.length);
+      return 0;
+    }).catch((error) => error?.code === "FX_OAUTH_SESSION_REVISION_CONFLICT" ? -2 : -1);
+  }
+
+  function oauthSessionRemove(expectedPtr, expectedLen) {
+    if (!options.oauthSessionStore?.remove) return -1;
+    const expectedRevision = expectedLen ? text(expectedPtr, expectedLen) : undefined;
+    return Promise.resolve().then(() => options.oauthSessionStore.remove(expectedRevision)).then((result) =>
+      result === false || result === "missing" ? 1 : 0
+    ).catch((error) => error?.code === "FX_OAUTH_SESSION_REVISION_CONFLICT" ? -2 : -1);
+  }
+
+  function configGet(idPtr, idLen, outPtr, outCap) {
+    if (!options.configStore?.get) return -2;
+    const configId = text(idPtr, idLen);
+    return Promise.resolve().then(() => options.configStore.get(configId)).then((value) => {
+      if (value === null || value === undefined) return -2;
+      if (typeof value !== "string") throw new TypeError("configStore.get() must return a string or null");
+      const encoded = encoder.encode(value);
+      if (encoded.length > outCap) return -3;
+      bytes(outPtr, encoded.length).set(encoded);
+      options.emit?.("config.restore", { configId, value });
+      return encoded.length;
+    }).catch((error) => {
+      options.emit?.("config.restore_error", { configId, error });
+      return -1;
+    });
+  }
+
+  function configSet(idPtr, idLen, valuePtr, valueLen) {
+    if (!options.configStore?.set) return 0;
+    const configId = text(idPtr, idLen);
+    const value = text(valuePtr, valueLen);
+    return Promise.resolve().then(() => options.configStore.set(configId, value)).then(() => {
+      options.emit?.("config.changed", { configId, value, source: "terminal" });
+      return 0;
+    }).catch((error) => {
+      options.emit?.("config.persist_error", { configId, error });
+      return -1;
+    });
+  }
+
+  function promptHistoryLoad(workspacePtr, workspaceLen, limit, outPtr, outCap) {
+    if (!options.promptHistoryStore?.load) return -1;
+    const workspaceRoot = text(workspacePtr, workspaceLen);
+    return Promise.resolve().then(() => options.promptHistoryStore.load(workspaceRoot, limit)).then((entries) => {
+      if (!Array.isArray(entries) || entries.some((entry) => typeof entry !== "string")) {
+        throw new TypeError("promptHistoryStore.load() must return an array of strings");
+      }
+      const value = encoder.encode(JSON.stringify(entries));
+      if (value.length > outCap) return -2;
+      bytes(outPtr, value.length).set(value);
+      options.emit?.("history.restore", { workspaceRoot, count: entries.length });
+      return value.length;
+    }).catch((error) => {
+      options.emit?.("history.restore_error", { workspaceRoot, error });
+      return -1;
+    });
+  }
+
+  function promptHistoryAppend(timestampMs, workspacePtr, workspaceLen, valuePtr, valueLen) {
+    if (!options.promptHistoryStore?.append) return -1;
+    const workspaceRoot = text(workspacePtr, workspaceLen);
+    const value = text(valuePtr, valueLen);
+    return Promise.resolve().then(() => options.promptHistoryStore.append(workspaceRoot, value, Number(timestampMs))).then((result) => {
+      options.emit?.("history.append", { workspaceRoot });
+      if (result === "duplicate") return 1;
+      if (result === "record_too_large") return 2;
+      return 0;
+    }).catch((error) => {
+      options.emit?.("history.append_error", { workspaceRoot, error });
+      return -1;
+    });
+  }
+
+  function promptHistoryClear(workspacePtr, workspaceLen) {
+    if (!options.promptHistoryStore?.clear) return -1;
+    const workspaceRoot = text(workspacePtr, workspaceLen);
+    return Promise.resolve().then(() => options.promptHistoryStore.clear(workspaceRoot)).then(() => {
+      options.emit?.("history.clear", { workspaceRoot });
+      return 0;
+    }).catch((error) => {
+      options.emit?.("history.clear_error", { workspaceRoot, error });
+      return -1;
+    });
+  }
+
+  function sessionLoad(idPtr, idLen, outPtr, outCap, revisionPtr, revisionCap, revisionLenOut) {
+    if (!options.sessionStore) return -1;
+    return Promise.resolve().then(() => options.sessionStore.load(text(idPtr, idLen))).then((record) => {
+      if (!record) return -2;
+      const value = record.bytes instanceof Uint8Array ? record.bytes : new Uint8Array(record.bytes);
+      const revision = encoder.encode(record.revision);
+      if (value.length > outCap || revision.length > revisionCap) return -3;
+      bytes(outPtr, value.length).set(value);
+      bytes(revisionPtr, revision.length).set(revision);
+      writeU32(revisionLenOut, revision.length);
+      return value.length;
+    }).catch(() => -1);
+  }
+
+  function sessionCommit(idPtr, idLen, valuePtr, valueLen, expectedPtr, expectedLen, revisionPtr, revisionCap, revisionLenOut) {
+    if (!options.sessionStore) return -1;
+    const id = text(idPtr, idLen);
+    const expectedRevision = expectedLen ? text(expectedPtr, expectedLen) : undefined;
+    return Promise.resolve().then(() => options.sessionStore.commit(id, bytes(valuePtr, valueLen).slice(), expectedRevision)).then((result) => {
+      const revision = encoder.encode(result.revision);
+      if (revision.length > revisionCap) return -1;
+      bytes(revisionPtr, revision.length).set(revision);
+      writeU32(revisionLenOut, revision.length);
+      return 0;
+    }).catch((error) => error?.code === "FX_SESSION_REVISION_CONFLICT" ? -2 : -1);
+  }
+
+  function sessionList(outPtr, outCap) {
+    if (!options.sessionStore) return -1;
+    return Promise.resolve().then(() => options.sessionStore.list()).then((records) => {
+      const value = encoder.encode(JSON.stringify(records));
+      if (value.length > outCap) return -2;
+      bytes(outPtr, value.length).set(value);
+      return value.length;
+    }).catch(() => -1);
+  }
+
+  function sessionRemove(idPtr, idLen) {
+    if (!options.sessionStore) return -1;
+    return Promise.resolve().then(() => options.sessionStore.remove(text(idPtr, idLen))).then(() => 0).catch(() => -1);
+  }
+
+  function workspaceInfo(outPtr, outCap) {
+    if (!workspace.present) return -2;
+    if (!workspace.valid) return -4;
+    const output = checkedBytes(outPtr, outCap);
+    if (!output) return -4;
+    if (workspace.encoded.length > outCap) return -3;
+    output.set(workspace.encoded);
+    return workspace.encoded.length;
+  }
+
+  function workspaceExec(commandPtr, commandLen, timeoutMs, outputPtr, outputCap, resultPtr) {
+    if (!workspace.present) return Promise.resolve(-2);
+    if (!workspace.valid) return Promise.resolve(-4);
+    const commandBytes = checkedBytes(commandPtr, commandLen);
+    const output = checkedBytes(outputPtr, outputCap);
+    const resultBytes = checkedBytes(resultPtr, 32);
+    if (!commandBytes || !output || !resultBytes || commandLen > workspaceCommandLimit ||
+      outputCap > workspaceOutputLimit || !Number.isInteger(timeoutMs) ||
+      timeoutMs < 1 || timeoutMs > 30_000) return Promise.resolve(-4);
+    let command;
+    try {
+      command = strictDecoder.decode(commandBytes);
+    } catch {
+      return Promise.resolve(-4);
+    }
+    if (command.includes("\0")) return Promise.resolve(-4);
+
+    return runWorkspaceOperation(timeoutMs, "workspace command", (signal) => workspace.adapter.exec({
+      command,
+      cwd: workspace.info.cwd,
+      signal,
+      timeoutMs,
+      outputLimitBytes: workspaceOutputLimit,
+    }), (value) => {
+      if (!value || !Number.isInteger(value.exitCode) || value.exitCode < -0x80000000 ||
+        value.exitCode > 0x7fffffff || typeof value.stdout !== "string" ||
+        typeof value.stderr !== "string") return -1;
+      const stdout = encoder.encode(value.stdout);
+      const stderr = encoder.encode(value.stderr);
+      if (stdout.length > 0xffffffff || stderr.length > 0xffffffff) return -1;
+
+      let stdoutCap = stdout.length;
+      let stderrCap = stderr.length;
+      if (stdout.length + stderr.length > outputCap) {
+        stdoutCap = Math.min(stdout.length, Math.ceil(outputCap / 2));
+        stderrCap = Math.min(stderr.length, Math.floor(outputCap / 2));
+        let remaining = outputCap - stdoutCap - stderrCap;
+        const stdoutExtra = Math.min(remaining, stdout.length - stdoutCap);
+        stdoutCap += stdoutExtra;
+        remaining -= stdoutExtra;
+        stderrCap += Math.min(remaining, stderr.length - stderrCap);
+      }
+      const stdoutPreview = utf8Prefix(stdout, stdoutCap);
+      const stderrPreview = utf8Prefix(stderr, stderrCap);
+      output.set(stdoutPreview, 0);
+      output.set(stderrPreview, stdoutPreview.length);
+      const copied = stdoutPreview.length + stderrPreview.length;
+      const view = new DataView(memory().buffer, resultPtr, 32);
+      view.setInt32(0, value.exitCode, true);
+      view.setUint32(4, 0, true);
+      view.setUint32(8, stdoutPreview.length, true);
+      view.setUint32(12, stdout.length, true);
+      view.setUint32(16, stdoutPreview.length, true);
+      view.setUint32(20, stderrPreview.length, true);
+      view.setUint32(24, stderr.length, true);
+      view.setUint32(28, copied < stdout.length + stderr.length ? 1 : 0, true);
+      return 0;
+    });
+  }
+
+  function workspaceReadFile(pathPtr, pathLen, outPtr, outCap, resultPtr) {
+    if (!workspace.present || (workspace.valid && typeof workspace.adapter.readFile !== "function")) {
+      return Promise.resolve(-2);
+    }
+    if (!workspace.valid) return Promise.resolve(-4);
+    const pathBytes = checkedBytes(pathPtr, pathLen);
+    if (!pathBytes || !checkedBytes(outPtr, outCap) || !checkedBytes(resultPtr, 8) ||
+      pathLen > workspaceInstructionPathLimit || outCap > workspaceInstructionFileLimit) {
+      return Promise.resolve(-4);
+    }
+    let path;
+    try {
+      path = strictDecoder.decode(pathBytes);
+    } catch {
+      return Promise.resolve(-4);
+    }
+    if (!workspaceInstructionPathAllowed(workspace.info, path)) return Promise.resolve(-4);
+
+    return runWorkspaceOperation(workspaceReadTimeoutMs, "workspace read", (signal) => workspace.adapter.readFile({
+      path,
+      signal,
+    }), (value) => {
+      if (value == null) return -6;
+      let content;
+      if (typeof value === "string") {
+        content = encoder.encode(value);
+      } else if (value instanceof ArrayBuffer || ArrayBuffer.isView(value)) {
+        content = value instanceof ArrayBuffer
+          ? new Uint8Array(value)
+          : new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+        try {
+          strictDecoder.decode(content);
+        } catch {
+          return -7;
+        }
+      } else {
+        return -1;
+      }
+      if (content.length > 0xffffffff) return -1;
+      const copied = Math.min(content.length, outCap);
+      // Reacquire views: memory may have grown while the host read was pending.
+      bytes(outPtr, copied).set(content.subarray(0, copied));
+      const view = new DataView(memory().buffer, resultPtr, 8);
+      view.setUint32(0, content.length, true);
+      view.setUint32(4, copied, true);
+      return 0;
+    });
+  }
+
+  // Runs one host workspace effect under a deadline and the shared Ctrl+C
+  // abort path. `finish` maps the host value to an ABI status.
+  function runWorkspaceOperation(timeoutMs, label, start, finish) {
+    const controller = new AbortController();
+    let resolveAbort;
+    const aborted = new Promise((resolve) => { resolveAbort = resolve; });
+    const state = {
+      status: null,
+      abort(status) {
+        if (this.status !== null) return;
+        this.status = status;
+        resolveAbort(status);
+        controller.abort(new DOMException(
+          status === -5 ? `${label} timed out` : `${label} aborted`,
+          status === -5 ? "TimeoutError" : "AbortError",
+        ));
+      },
+    };
+    workspaceOperations.add(state);
+    const timer = setTimeout(() => state.abort(-5), timeoutMs);
+    const execution = Promise.resolve().then(() => start(controller.signal)).then((value) => {
+      if (state.status !== null) return state.status;
+      return finish(value);
+    }).catch((error) => {
+      if (state.status !== null) return state.status;
+      if (error?.name === "TimeoutError") return -5;
+      if (error?.name === "AbortError") return -3;
+      return -1;
+    });
+    return Promise.race([execution, aborted]).finally(() => {
+      clearTimeout(timer);
+      workspaceOperations.delete(state);
+    });
+  }
+
+  function abortHostEffects() {
+    pendingHostToolResult = null;
+    streams.forEach((state) => state.controller.abort(abortReason));
+    httpRequests.forEach((controller) => controller.abort(abortReason));
+    workspaceOperations.forEach((state) => state.abort(-3));
+  }
+
+  const unavailable = () => 52;
+  const wasi = {
+    args_sizes_get(count, size) { if (options.traceWasi) console.error("wasi args_sizes_get"); writeU32(count, args.length); writeU32(size, args.reduce((n, v) => n + encoder.encode(v).length + 1, 0)); return 0; },
+    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: options.args?.[0] === "acp" ? new WebAssembly.Suspending(fdWrite) : fdWrite,
+    fd_read: new WebAssembly.Suspending(fdRead),
+    fd_close() { return 0; },
+    fd_fdstat_get(fd, out) {
+      if (options.traceWasi) console.error("wasi fd_fdstat_get", fd);
+      bytes(out, 24).fill(0);
+      const view = new DataView(memory().buffer);
+      view.setUint8(out, fd <= 2 ? 2 : 0);
+      view.setBigUint64(out + 8, 0xffffffffffffffffn, true);
+      view.setBigUint64(out + 16, 0xffffffffffffffffn, true);
+      return 0;
+    },
+    fd_filestat_get: unavailable,
+    fd_filestat_set_size: unavailable,
+    fd_filestat_set_times: unavailable,
+    fd_pread: unavailable,
+    fd_prestat_get() { return 8; },
+    fd_prestat_dir_name: unavailable,
+    fd_pwrite: unavailable,
+    fd_readdir: unavailable,
+    fd_seek() { return 29; },
+    fd_sync() { return 0; },
+    clock_res_get(_id, out) { if (options.traceWasi) console.error("wasi clock_res_get"); writeU64(out, 1000000n); return 0; },
+    clock_time_get(_id, _precision, out) { if (options.traceWasi) console.error("wasi clock_time_get"); writeU64(out, BigInt(Date.now()) * 1000000n); return 0; },
+    path_create_directory: unavailable,
+    path_filestat_get: unavailable,
+    path_filestat_set_times: unavailable,
+    path_link: unavailable,
+    path_open: unavailable,
+    path_readlink: unavailable,
+    path_remove_directory: unavailable,
+    path_rename: unavailable,
+    path_symlink: unavailable,
+    path_unlink_file: unavailable,
+    random_get(ptr, len) { crypto.getRandomValues(bytes(ptr, len)); return 0; },
+    poll_oneoff: new WebAssembly.Suspending(pollOneoff),
+    proc_exit(code) { if (options.traceWasi) console.error("wasi proc_exit", code); markExited(code); throw new WebAssembly.RuntimeError(`proc_exit(${code})`); },
+  };
+
+  const fx = {
+    fx_term_poll_input: new WebAssembly.Suspending(termPollInput),
+    fx_clipboard_copy: new WebAssembly.Suspending(clipboardCopy),
+    fx_prompt_history_available() { return options.promptHistoryStore ? 1 : 0; },
+    fx_workspace_available() { return workspace.present ? 1 : 0; },
+    fx_workspace_info: workspaceInfo,
+    fx_workspace_exec: new WebAssembly.Suspending(workspaceExec),
+    fx_workspace_read_file: new WebAssembly.Suspending(workspaceReadFile),
+    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(abortReason); streams.delete(handle); },
+    fx_http_request: new WebAssembly.Suspending(httpRequest),
+    fx_host_tool_call: new WebAssembly.Suspending(hostToolCall),
+    fx_journal_flush: new WebAssembly.Suspending(journalFlush),
+    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_steering_take: steeringTake,
+    fx_steering_close() { steeringOpen = false; clearSteering(); },
+    // -1 once the turn takes no more steering, else twice how many steers
+    // wait, plus one when a handoff does.
+    fx_steering_state() { return steeringOpen ? steering.length * 2 + (steeringHandoff ? 1 : 0) : -1; },
+    fx_attachment_size: attachmentSize,
+    fx_attachment_take: attachmentTake,
+    fx_attachment_put: attachmentPut,
+    fx_open_url: new WebAssembly.Suspending(openUrl),
+    fx_oauth_session_load: new WebAssembly.Suspending(oauthSessionLoad),
+    fx_oauth_session_commit: new WebAssembly.Suspending(oauthSessionCommit),
+    fx_oauth_session_remove: new WebAssembly.Suspending(oauthSessionRemove),
+    fx_config_get: new WebAssembly.Suspending(configGet),
+    fx_config_set: new WebAssembly.Suspending(configSet),
+    fx_prompt_history_load: new WebAssembly.Suspending(promptHistoryLoad),
+    fx_prompt_history_append: new WebAssembly.Suspending(promptHistoryAppend),
+    fx_prompt_history_clear: new WebAssembly.Suspending(promptHistoryClear),
+    fx_session_load: new WebAssembly.Suspending(sessionLoad),
+    fx_session_commit: new WebAssembly.Suspending(sessionCommit),
+    fx_session_list: new WebAssembly.Suspending(sessionList),
+    fx_session_remove: new WebAssembly.Suspending(sessionRemove),
+    fx_term_size(cols, rows) {
+      const width = options.terminal?.cols || 80;
+      const height = options.terminal?.rows || 24;
+      new DataView(memory().buffer).setUint16(cols, width, true);
+      new DataView(memory().buffer).setUint16(rows, height, true);
+      options.emit?.("terminal.size", { cols: width, rows: height });
+    },
+  };
+
+  return {
+    imports: { wasi_snapshot_preview1: wasi, fx }, exited,
+    setInstance(value) { instance = value; },
+    write(data) { stdin.push(typeof data === "string" ? encoder.encode(data) : data); },
+    writeAttachment,
+    takeAttachment(id) {
+      const value = outboundAttachments.get(id) ?? null;
+      outboundAttachments.delete(id);
+      return value;
+    },
+    discardAttachments() { inboundAttachments.clear(); },
+    wake() { stdin.wake(); },
+    closeStdin() { steeringOpen = false; clearSteering(); stdin.close(); },
+    openSteering() { clearSteering(); steeringOpen = true; },
+    steer: queueSteering,
+    withdrawSteering,
+    // Ends the running turn at its next safe point; false when none runs.
+    handOffSteering() {
+      if (!steeringOpen) return false;
+      steeringHandoff = true;
+      return true;
+    },
+    closeSteering() { steeringOpen = false; clearSteering(); },
+    abortHostEffects,
+    abort(error) {
+      aborted = true;
+      outputError = error;
+      coreOutput?.close();
+      abortHostEffects();
+      stdin.close();
+      markExited(130);
+    },
+    markExited,
+    get aborted() { return aborted; },
+    get exitCode() { return exitCode; },
+    get error() { return outputError; },
+    setLineHandler(handler) {
+      coreOutput = new CoreOutput(handler);
+      options.stdout = (chunk) => coreOutput.write(chunk);
+    },
+    finishOutput() { coreOutput?.finish(); },
+  };
+}
+
+export async function instantiate(options) {
+  if (!supportsJspi()) throw new Error("fx WebAssembly requires JSPI (Chrome or Edge 137+)");
+  const runtime = createRuntime({ fetch: globalThis.fetch.bind(globalThis), ...options });
+  const module = await loadModule(options.wasm);
+  const instance = await WebAssembly.instantiate(module, runtime.imports);
+  runtime.setInstance(instance);
+  const start = WebAssembly.promising(instance.exports._start);
+  start().then(
+    () => {
+      runtime.setInstance(null);
+      try { runtime.finishOutput(); runtime.markExited(0); }
+      catch (error) { runtime.abort(error); }
+    },
+    (error) => {
+      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;
+}
+
+// The runtime factory for an engine on WebAssembly. `wasm` is the fx-core
+// module; without it, each engine's own `wasm` option names it.
+export function wasmRuntimeFactory(wasm) {
+  return (runtimeOptions) => instantiate(wasm === undefined ? runtimeOptions : { ...runtimeOptions, wasm });
+}