libfx 0.0.13 → 0.0.14

package/browser.js

@@ -1,6 +1,11 @@
+import { createDurableAgentFactory, memory } from "./durable.js";
+import { fxHarness } from "./fx-harness.js";
 import {
-  createFxAgent as createWasmAgent,
+  createFxEngine as createWasmAgent,
   createFxTerminal as createWasmTerminal,
+  createMemoryPersistence,
+  FxFencedError,
+  FxJournalVersionError,
   encodeXtermKeyEvent,
   fxSdkApiVersion,
   listModels,
@@ -8,16 +13,25 @@ import {
   xtermAdapter,
 } from "./fx-sdk.js";
 
-export { encodeXtermKeyEvent, fxSdkApiVersion, listModels, supportsJspi, xtermAdapter };
-export const libfxApiVersion = 2;
+export { createMemoryPersistence, encodeXtermKeyEvent, FxFencedError, FxJournalVersionError, fxSdkApiVersion, listModels, memory, supportsJspi, xtermAdapter };
+export const libfxApiVersion = 3;
 
 const defaultCoreWasm = new URL("./fx-core.wasm", import.meta.url).href;
 const defaultTermWasm = new URL("./fx-term.wasm", import.meta.url).href;
 
-export function createFxAgent(options = {}) {
+/** One fx session on WebAssembly, with no durability of its own. */
+export function createFxEngine(options = {}) {
   return createWasmAgent({ ...options, wasm: options.wasm ?? defaultCoreWasm });
 }
 
+/** An agent whose sessions live in this page unless `durability` says otherwise. */
+export const createFxAgent = createDurableAgentFactory({
+  name: "createFxAgent",
+  label: "fx agent",
+  defaultDurability: async () => memory(),
+  harness: fxHarness({ createEngine: createFxEngine }),
+});
+
 export function createFxTerminal(options = {}) {
   return createWasmTerminal({ ...options, wasm: options.wasm ?? defaultTermWasm });
 }

package/chatgpt-sign-in.js

@@ -0,0 +1,141 @@
+// `libfx/chatgpt`: sign in with ChatGPT for a Codex agent. Two flows, both
+// plain data between steps so a website can start in one request and finish in
+// another:
+//
+// - Paste the address: the user signs in on OpenAI, lands on a page at
+//   localhost:1455 that does not load, and pastes its address back.
+// - Device code: the user enters a short code on OpenAI's page. ChatGPT
+//   workspaces and accounts must turn device code sign-in on first.
+import { chatgptClientId, chatgptIssuer, normalizeChatgptCredentials, refreshChatgptCredentials } from "./chatgpt.js";
+import { hostFetch, pkceChallenge, randomSecret, readSignInAddress, signInError, wait } from "./oauth.js";
+
+const redirectUri = "http://localhost:1455/auth/callback";
+const deviceRedirectUri = `${chatgptIssuer}/deviceauth/callback`;
+const scope = "openid profile email offline_access api.connectors.read api.connectors.invoke";
+const deviceCodeLifetimeMs = 15 * 60 * 1000;
+
+/** Starts a sign-in. Keep the result on the server: `verifier` is secret. */
+export async function startSignIn() {
+  const verifier = randomSecret();
+  const state = randomSecret();
+  const challenge = await pkceChallenge(verifier);
+  const url = new URL(`${chatgptIssuer}/oauth/authorize`);
+  for (const [key, value] of Object.entries({
+    response_type: "code",
+    client_id: chatgptClientId,
+    redirect_uri: redirectUri,
+    scope,
+    code_challenge: challenge,
+    code_challenge_method: "S256",
+    id_token_add_organizations: "true",
+    codex_cli_simplified_flow: "true",
+    state,
+    originator: "fx",
+  })) url.searchParams.set(key, value);
+  return { url: url.href, state, verifier };
+}
+
+async function exchangeCode({ code, verifier, redirect, fetch, signal }) {
+  const response = await hostFetch(fetch)(`${chatgptIssuer}/oauth/token`, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({ grant_type: "authorization_code", client_id: chatgptClientId, code, code_verifier: verifier, redirect_uri: redirect }).toString(),
+    signal,
+  });
+  if (response.status === 400 || response.status === 401) {
+    await response.body?.cancel().catch(() => {});
+    throw signInError("LIBFX_CHATGPT_SIGN_IN_EXPIRED", "This sign-in expired or was already used. Start again.", { status: response.status });
+  }
+  if (!response.ok) {
+    await response.body?.cancel().catch(() => {});
+    throw signInError("LIBFX_CHATGPT_SIGN_IN_FAILED", `OpenAI could not finish the sign-in (HTTP ${response.status}).`, { status: response.status });
+  }
+  const tokens = await response.json();
+  return normalizeChatgptCredentials({
+    accessToken: tokens.access_token,
+    refreshToken: tokens.refresh_token,
+    ...(Number.isFinite(tokens.expires_in) ? { expiresAt: Date.now() + tokens.expires_in * 1000 } : {}),
+  });
+}
+
+/** Finishes a sign-in from the address the user pasted. */
+export async function finishSignIn(signIn, address, { fetch, signal } = {}) {
+  if (!signIn || typeof signIn.state !== "string" || typeof signIn.verifier !== "string") {
+    throw new TypeError("finishSignIn() needs the object startSignIn() returned");
+  }
+  const { code, state } = readSignInAddress(address, { prefix: "LIBFX_CHATGPT", issuer: "OpenAI", redirectUri });
+  if (state !== signIn.state) {
+    throw signInError("LIBFX_CHATGPT_SIGN_IN_STATE_MISMATCH", "That address is from a different sign-in. Start again and paste the address from this one.");
+  }
+  return exchangeCode({ code, verifier: signIn.verifier, redirect: redirectUri, fetch, signal });
+}
+
+/** Starts a device code sign-in. Show `userCode` and `verificationUrl`. */
+export async function startDeviceSignIn({ fetch, signal } = {}) {
+  const response = await hostFetch(fetch)(`${chatgptIssuer}/api/accounts/deviceauth/usercode`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ client_id: chatgptClientId }),
+    signal,
+  });
+  if (!response.ok) {
+    await response.body?.cancel().catch(() => {});
+    throw signInError("LIBFX_CHATGPT_DEVICE_CODE_UNAVAILABLE", `OpenAI did not issue a device code (HTTP ${response.status}).`, { status: response.status });
+  }
+  const body = await response.json();
+  const userCode = body.user_code ?? body.usercode;
+  if (typeof userCode !== "string" || typeof body.device_auth_id !== "string") {
+    throw signInError("LIBFX_CHATGPT_DEVICE_CODE_UNAVAILABLE", "OpenAI returned a device code response libfx does not understand.");
+  }
+  const interval = Number(body.interval);
+  return {
+    verificationUrl: `${chatgptIssuer}/codex/device`,
+    userCode,
+    deviceAuthId: body.device_auth_id,
+    intervalMs: Math.max(Number.isFinite(interval) ? interval : 5, 1) * 1000,
+    expiresAt: Date.now() + deviceCodeLifetimeMs,
+  };
+}
+
+/** Checks a device sign-in once: credentials when the user has entered the code, otherwise null. */
+export async function pollDeviceSignIn(device, { fetch, signal } = {}) {
+  if (!device || typeof device.deviceAuthId !== "string" || typeof device.userCode !== "string") {
+    throw new TypeError("pollDeviceSignIn() needs the object startDeviceSignIn() returned");
+  }
+  if (Date.now() > device.expiresAt) {
+    throw signInError(
+      "LIBFX_CHATGPT_DEVICE_CODE_EXPIRED",
+      "The code expired before it was entered. If OpenAI's page said device code sign-in is off, turn it on in ChatGPT's security settings, or ask your workspace admin.",
+    );
+  }
+  const response = await hostFetch(fetch)(`${chatgptIssuer}/api/accounts/deviceauth/token`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ device_auth_id: device.deviceAuthId, user_code: device.userCode }),
+    signal,
+  });
+  if (response.status === 403 || response.status === 404) {
+    await response.body?.cancel().catch(() => {});
+    return null;
+  }
+  if (!response.ok) {
+    await response.body?.cancel().catch(() => {});
+    throw signInError("LIBFX_CHATGPT_SIGN_IN_FAILED", `OpenAI could not finish the sign-in (HTTP ${response.status}).`, { status: response.status });
+  }
+  const grant = await response.json();
+  return exchangeCode({ code: grant.authorization_code, verifier: grant.code_verifier, redirect: deviceRedirectUri, fetch, signal });
+}
+
+/** Waits until the user enters the code, polling at OpenAI's interval. */
+export async function completeDeviceSignIn(device, { fetch, signal } = {}) {
+  for (;;) {
+    const credentials = await pollDeviceSignIn(device, { fetch, signal });
+    if (credentials) return credentials;
+    await wait(device.intervalMs, signal);
+  }
+}
+
+/** Refreshes credentials. Codex agents refresh on their own; this is for hosts. */
+export function refreshCredentials(credentials, { fetch, signal } = {}) {
+  return refreshChatgptCredentials(normalizeChatgptCredentials(credentials), { fetch, signal });
+}

package/chatgpt.js

@@ -0,0 +1,69 @@
+// ChatGPT (Codex) credentials for libfx agents: the Codex endpoints, how a
+// ChatGPT plan's credentials are checked and refreshed, and the headers that
+// carry them. `subscription.js` adds them at the fetch edge. TLA+ model:
+// `tests/tla/sdk/ProviderAuth.tla`.
+import { normalizeCredentials } from "./subscription.js";
+
+export const chatgptIssuer = "https://auth.openai.com";
+export const chatgptClientId = "app_EMoamEEZ73f0CkXaXp7hrann";
+
+const codexOrigin = "https://chatgpt.com";
+const codexPaths = new Set(["/backend-api/codex/responses", "/backend-api/codex/models"]);
+const authClaim = "https://api.openai.com/auth";
+
+/** True only for the exact Codex endpoints the engine calls. */
+export function isCodexRequest(url) {
+  let parsed;
+  try { parsed = new URL(String(url)); } catch { return false; }
+  return parsed.origin === codexOrigin && codexPaths.has(parsed.pathname);
+}
+
+/**
+ * Validates credentials from the host. The account id and expiry default to
+ * the access token's own claims. Returns a new object.
+ */
+export function normalizeChatgptCredentials(value) {
+  return normalizeCredentials(value, { label: "ChatGPT", accountClaim: (claims) => claims?.[authClaim]?.chatgpt_account_id });
+}
+
+/**
+ * Exchanges a refresh token at OpenAI. Keeps the old refresh token when the
+ * response does not rotate it.
+ */
+export async function refreshChatgptCredentials(credentials, { fetch, signal } = {}) {
+  if (credentials.refreshToken === undefined) throw new TypeError("ChatGPT credentials have no refreshToken");
+  const doFetch = fetch ?? globalThis.fetch?.bind(globalThis);
+  const response = await doFetch(`${chatgptIssuer}/oauth/token`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ client_id: chatgptClientId, grant_type: "refresh_token", refresh_token: credentials.refreshToken }),
+    signal,
+  });
+  if (!response.ok) {
+    await response.body?.cancel().catch(() => {});
+    const error = new Error(`ChatGPT token refresh failed with HTTP ${response.status}`);
+    error.code = "LIBFX_CHATGPT_REFRESH_FAILED";
+    error.status = response.status;
+    throw error;
+  }
+  const tokens = await response.json();
+  const next = normalizeChatgptCredentials({
+    accessToken: tokens.access_token,
+    refreshToken: tokens.refresh_token ?? credentials.refreshToken,
+    ...(Number.isFinite(tokens.expires_in) ? { expiresAt: Date.now() + tokens.expires_in * 1000 } : {}),
+  });
+  return next.accountId === credentials.accountId ? next : { ...next, accountId: credentials.accountId };
+}
+
+/** Codex on a ChatGPT plan, for `createSubscriptionAuthorizer()`. */
+export const codexSubscription = {
+  provider: "codex",
+  matches: isCodexRequest,
+  sessionId: (headers) => headers.get("session-id"),
+  normalize: normalizeChatgptCredentials,
+  refresh: refreshChatgptCredentials,
+  authorize(headers, _endpoint, credentials) {
+    headers.set("authorization", `Bearer ${credentials.accessToken}`);
+    headers.set("chatgpt-account-id", credentials.accountId);
+  },
+};

package/custom-provider.js

@@ -0,0 +1,123 @@
+// A custom provider for libfx agents: any server that speaks OpenAI Chat
+// Completions, such as a local model server or a router. The engine sends its
+// requests through the host's fetch without credentials; when the host has an
+// API key, this module adds it at the fetch edge, to that provider's chat URL
+// only. The key never enters the engine or a session's saved records.
+
+import { tokenString } from "./subscription.js";
+
+const encoder = new TextEncoder();
+const reservedNames = new Set(["gateway", "codex", "grok"]);
+const namePattern = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+const loopbackHosts = new Set(["localhost", "127.0.0.1", "[::1]"]);
+const providerFields = new Set(["name", "baseUrl", "models"]);
+// libfx option names to the CLI's settings names, which the engine parses.
+const modelFields = {
+  contextWindow: "context_window",
+  maxOutputTokens: "max_output_tokens",
+  supportsToolUse: "supports_tool_use",
+  supportsVision: "supports_vision",
+};
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function chatUrlOf(baseUrl) {
+  if (typeof baseUrl !== "string") throw new TypeError("provider.baseUrl must be a string");
+  let url;
+  try {
+    url = new URL(`${baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl}/chat/completions`);
+  } catch {
+    throw new TypeError("provider.baseUrl must be an absolute URL");
+  }
+  if (url.username || url.password || url.search || url.hash) {
+    throw new TypeError("provider.baseUrl must not carry credentials, a query or a fragment");
+  }
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && loopbackHosts.has(url.hostname))) {
+    throw new TypeError("provider.baseUrl must use https, or http on localhost");
+  }
+  // The same form the fetch edge compares requests in.
+  return `${url.origin}${url.pathname}`;
+}
+
+// The engine's limits (configured_provider.zig), checked here so both engines
+// report a mistake the same way.
+const maxModels = 256;
+const maxModelIdBytes = 1024;
+const maxLimit = 2 ** 32 - 1;
+
+function modelMetadata(models) {
+  if (!isPlainObject(models)) throw new TypeError("provider.models must be an object keyed by model id");
+  const entries = Object.entries(models);
+  if (entries.length > maxModels) throw new RangeError(`provider.models lists more than ${maxModels} models`);
+  const metadata = {};
+  for (const [id, model] of entries) {
+    if (id.length === 0 || id.trim() !== id || /[\u0000-\u001f\u007f]/.test(id) || encoder.encode(id).length > maxModelIdBytes) {
+      throw new TypeError(`provider.models has an invalid model id "${id}"`);
+    }
+    if (!isPlainObject(model)) throw new TypeError(`provider.models["${id}"] must be an object`);
+    const entry = {};
+    for (const [field, value] of Object.entries(model)) {
+      const name = modelFields[field];
+      if (name === undefined) throw new TypeError(`provider.models["${id}"] has unknown field ${field}`);
+      const limit = field === "contextWindow" || field === "maxOutputTokens";
+      if (limit ? !(Number.isInteger(value) && value > 0 && value <= maxLimit) : typeof value !== "boolean") {
+        throw new TypeError(`provider.models["${id}"].${field} must be ${limit ? "a positive integer" : "a boolean"}`);
+      }
+      entry[name] = value;
+    }
+    if (model.contextWindow !== undefined && model.maxOutputTokens !== undefined && model.maxOutputTokens >= model.contextWindow) {
+      throw new RangeError(`provider.models["${id}"].maxOutputTokens must be less than contextWindow`);
+    }
+    metadata[id] = entry;
+  }
+  return metadata;
+}
+
+/**
+ * Checks a custom provider `{ name, baseUrl, models? }` and returns its name,
+ * the chat URL its key may go to, and the settings-style JSON the engine
+ * parses. The engine applies the CLI's complete rules; these checks only catch
+ * mistakes early with a clearer message.
+ */
+export function customProviderDefinition(provider) {
+  if (!isPlainObject(provider)) throw new TypeError("a custom provider must be an object { name, baseUrl, models? }");
+  for (const field of Object.keys(provider)) {
+    if (!providerFields.has(field)) throw new TypeError(`a custom provider has unknown field ${field}`);
+  }
+  const { name, baseUrl, models } = provider;
+  if (typeof name !== "string" || !namePattern.test(name) || reservedNames.has(name.toLowerCase())) {
+    throw new TypeError("provider.name must be a letter followed by letters, digits, _ or -, at most 64 characters, and not gateway, codex or grok");
+  }
+  const chatUrl = chatUrlOf(baseUrl);
+  const definition = {
+    protocol: "openai-chat-completions",
+    base_url: baseUrl,
+    // The host adds the key, so the engine's copy has none.
+    auth: { type: "none" },
+    ...(models === undefined ? {} : { model_metadata: modelMetadata(models) }),
+  };
+  return { name, chatUrl, json: JSON.stringify({ [name]: definition }) };
+}
+
+/**
+ * The custom provider's spec for `createSubscriptionAuthorizer()`: the host's
+ * API key as a bearer token, on the provider's chat URL only. `sessionId()`
+ * names the agent's session. A key has no refresh token, so it is never
+ * refreshed, and a rejected request returns as it is.
+ */
+export function customProviderSpec({ name, chatUrl }, sessionId) {
+  return {
+    provider: name,
+    matches: (endpoint) => endpoint === chatUrl,
+    sessionId: () => sessionId(),
+    normalize(value) {
+      if (!isPlainObject(value)) throw new TypeError("credentials() must return { apiKey } for a custom provider");
+      return { accessToken: tokenString(value.apiKey, "apiKey", true, `provider "${name}"`) };
+    },
+    authorize(headers, _endpoint, credentials) {
+      headers.set("authorization", `Bearer ${credentials.accessToken}`);
+    },
+  };
+}