libfx 0.0.16 → 0.0.17

package/README.md

@@ -268,6 +268,8 @@ const agent = createFxAgent({
 
 Return a string to send it as is, or any other value to send it as JSON. A thrown error reaches the model as a failed tool result. To return images, return `{ type: "libfx.tool-result", text, images }`, with base64 image data.
 
+When the model writes a number, integer, boolean, array, or object argument as JSON text, such as `"40"` for a field that `inputSchema` types as an integer, `execute` receives it as that type. Every other value arrives as the model wrote it.
+
 Validate the input and authorize the action inside `execute`. libfx orders the calls but grants nothing itself.
 
 On the native backend, calls to idempotent tools from one model response run at the same time, up to 16 at once. A tool that isn't idempotent runs alone, and so does one marked `writes: true`. Mark a tool `writes: false` to let it overlap with others anyway. On WebAssembly, calls run one after another.
@@ -314,6 +316,8 @@ createFxAgent({ model: { id: "anthropic/claude-opus-5.5", effort: "high", fast:
 
 AI Gateway is the default. libfx uses the first credential it finds: the `apiKey` option, then `AI_GATEWAY_API_KEY`, then on Vercel the deployment's OIDC token.
 
+libfx asks AI Gateway to cache the start of each request, as the fx CLI does. Later requests in a session start with the same instructions, tools, and earlier messages, so models that support prompt caching read that part from the cache instead of processing it again.
+
 ### ChatGPT plans
 
 An agent can run on a user's ChatGPT plan through Codex. Set `provider: "codex"` and give libfx the user's credentials:

package/custom-provider.js

@@ -10,14 +10,18 @@ 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"]);
+const providerFields = new Set(["name", "baseUrl", "models", "modelDefaults", "titleModel", "visionModel"]);
 // 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",
+  outputLimitField: "output_limit_field",
+  request: "request",
+  reasoningEfforts: "reasoning_efforts",
 };
+const outputLimitFields = new Set(["max_tokens", "max_completion_tokens"]);
 
 function isPlainObject(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -47,36 +51,61 @@ const maxModels = 256;
 const maxModelIdBytes = 1024;
 const maxLimit = 2 ** 32 - 1;
 
+function validModelId(id) {
+  return typeof id === "string" && id.length > 0 && id.trim() === id && !/[\u0000-\u001f\u007f]/.test(id) && encoder.encode(id).length <= maxModelIdBytes;
+}
+
+// One model's fields, or the provider's defaults for every model, in the
+// settings' names. `where` names it in a message.
+function modelEntry(model, where) {
+  if (!isPlainObject(model)) throw new TypeError(`${where} must be an object`);
+  const entry = {};
+  for (const [field, value] of Object.entries(model)) {
+    const name = modelFields[field];
+    if (name === undefined) throw new TypeError(`${where} has unknown field ${field}`);
+    if (field === "contextWindow" || field === "maxOutputTokens") {
+      if (!(Number.isInteger(value) && value > 0 && value <= maxLimit)) throw new TypeError(`${where}.${field} must be a positive integer`);
+    } else if (field === "outputLimitField") {
+      if (!outputLimitFields.has(value)) throw new TypeError(`${where}.outputLimitField must be "max_tokens" or "max_completion_tokens"`);
+    } else if (field === "request") {
+      // The engine refuses a field it writes itself, such as messages.
+      if (!isPlainObject(value)) throw new TypeError(`${where}.request must be an object of request fields`);
+    } else if (field === "reasoningEfforts") {
+      if (!isPlainObject(value) || !Object.values(value).every(isPlainObject)) {
+        throw new TypeError(`${where}.reasoningEfforts must map each effort level to an object of request fields`);
+      }
+    } else if (typeof value !== "boolean") {
+      throw new TypeError(`${where}.${field} must be a boolean`);
+    }
+    entry[name] = value;
+  }
+  if (model.contextWindow !== undefined && model.maxOutputTokens !== undefined && model.maxOutputTokens >= model.contextWindow) {
+    throw new RangeError(`${where}.maxOutputTokens must be less than contextWindow`);
+  }
+  return entry;
+}
+
 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;
+    if (!validModelId(id)) throw new TypeError(`provider.models has an invalid model id "${id}"`);
+    metadata[id] = modelEntry(model, `provider.models["${id}"]`);
   }
   return metadata;
 }
 
+function helperModel(value, field) {
+  if (value === undefined) return {};
+  if (!validModelId(value)) throw new TypeError(`provider.${field} must be a model id`);
+  return { [field === "titleModel" ? "title_model" : "vision_model"]: value };
+}
+
 /**
- * Checks a custom provider `{ name, baseUrl, models? }` and returns its name,
+ * Checks a custom provider `{ name, baseUrl, models?, modelDefaults?,
+ * titleModel?, visionModel? }` 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.
@@ -86,7 +115,7 @@ export function customProviderDefinition(provider) {
   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;
+  const { name, baseUrl, models, modelDefaults, titleModel, visionModel } = 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");
   }
@@ -96,6 +125,9 @@ export function customProviderDefinition(provider) {
     base_url: baseUrl,
     // The host adds the key, so the engine's copy has none.
     auth: { type: "none" },
+    ...helperModel(titleModel, "titleModel"),
+    ...helperModel(visionModel, "visionModel"),
+    ...(modelDefaults === undefined ? {} : { model_defaults: modelEntry(modelDefaults, "provider.modelDefaults") }),
     ...(models === undefined ? {} : { model_metadata: modelMetadata(models) }),
   };
   return { name, chatUrl, json: JSON.stringify({ [name]: definition }) };

package/durable.js

@@ -747,6 +747,11 @@ function slotOf(event) {
   return Number(match[1]);
 }
 
+// The slot of the event a write returned, or NaN when the World returned none.
+function slotWritten(result) {
+  return Number(eventIdPattern.exec(String(result?.event?.eventId ?? ""))?.[1]);
+}
+
 function logEntryOf(event) {
   if (event?.eventType !== "step_created" || event.eventData?.stepName !== logStep) return null;
   const input = event.eventData.input;
@@ -766,6 +771,7 @@ const missingStreamFastMs = 2000;
 // may hold together, least recently read dropped first.
 const maxLogViews = 32;
 const maxLogViewChars = 32 * 1024 * 1024;
+const maxMintedIds = 1024;
 
 // Whether a newest-first listing showed every slot from the lowest it
 // listed to the newest. Pure.
@@ -1098,24 +1104,41 @@ function createWorldBackend(world, durability) {
         }
         return pending;
       };
+      // The newest slot the last read() returned every entry through, or
+      // null when that read could not show it had them all: 0 when it listed
+      // nothing, as for a run not created yet.
+      let covered = null;
+      // The run's creation events hold no entry, so a read that showed every
+      // entry through the slot before one still does through it.
+      const passOver = (slot) => {
+        if (covered !== null && slot === covered + 1) covered = slot;
+      };
+      // Resolves true when this call's own `run_created` made the run: the
+      // World creates a run only when none exists (a second one is refused,
+      // 409), and its first event takes the first slot. A run that did not
+      // exist held no event and no stream.
       const createRun = async () => {
+        let made = false;
         try {
           const deploymentId = typeof world.getDeploymentId === "function" ? await world.getDeploymentId() : "libfx";
-          await world.events.create(runId, {
+          const slot = slotWritten(await world.events.create(runId, {
             eventType: "run_created",
             ...spec,
             eventData: { deploymentId, workflowName: "libfx/session", input: encoder.encode("{}") },
-          });
+          }));
+          made = slot === firstEventSlot;
+          passOver(slot);
         } catch (error) {
           // Another worker created it first.
           if (!/exist|conflict|409|already/i.test(String(error?.message ?? "")) && error?.status !== 409) throw error;
         }
         try {
-          await world.events.create(runId, { eventType: "run_started", ...spec });
+          passOver(slotWritten(await world.events.create(runId, { eventType: "run_started", ...spec })));
         } catch (error) {
           if (!/exist|conflict|409|already|started|status/i.test(String(error?.message ?? "")) && error?.status !== 409) throw error;
         }
         created.add(runId);
+        return made;
       };
       // Events newest first, down to and excluding slot `stopBelow`.
       const newestFirst = async (stopBelow, stopAtCheckpoint) => {
@@ -1175,9 +1198,6 @@ function createWorldBackend(world, durability) {
           cursor = page.cursor;
         }
       };
-      // The newest slot the last read() returned every entry through, or
-      // null when that read could not show it had them all.
-      let covered = null;
       const fullRead = async () => {
         const read = await newestFirst(0, true);
         const entries = read.events.reverse();
@@ -1191,12 +1211,31 @@ function createWorldBackend(world, durability) {
           covered = read.newest;
         } else {
           forgetView(runId);
-          covered = null;
+          covered = read.missing || read.listed === 0 ? 0 : null;
         }
         return entries;
       };
       return {
         newest: () => covered,
+        // Creates the run, as its first append would, and resolves true only
+        // when this call's own write made it: the log was then empty and its
+        // stream had no line, as a read just before the write would have
+        // shown, so the sender need not read either. False, without writing,
+        // when this process already created the run or is creating it; false,
+        // after the same writes, when the run existed or the World cannot show
+        // which. The caller then reads as before.
+        async fresh() {
+          if (created.has(runId) || creating.has(runId)) return false;
+          // As a read that found no run leaves it, so the creation events
+          // this write lands pass it over. Of a run it did not make, this
+          // object knows nothing; the caller then reads it.
+          covered = 0;
+          const made = await ensureRun();
+          if (!made) covered = null;
+          // As a read that found no run notes it.
+          if (made) noteSnapshot({ seq: 0, seqInBand: inBandAtRunCreation }, "null");
+          return made;
+        },
         async read() {
           const view = viewOf(runId);
           if (!view) return fullRead();
@@ -1596,7 +1635,9 @@ async function recordMessage(log, state, message) {
  * The log a sender read and then extended with its own entries, as the
  * worker it starts in the same request may use it instead of reading the
  * log again. Only when the sender's read showed every entry through slot
- * `newestSeen`, and every entry the sender then wrote took the next slot:
+ * `newestSeen` (for a run it found missing, the run's creation events it
+ * then saw land hold none), and every entry the sender then wrote took the
+ * next slot:
  * then nothing landed in between, so the view holds every input that comes
  * before this message's. The sender's entries go on as the JSON the World
  * stored, not as the objects it wrote. Null otherwise. Pure.
@@ -1673,9 +1714,22 @@ class SessionWorker {
     this.sessionId = sessionId;
     // Set while this process runs the session; each run holds its own lease.
     this.running = false;
-    // Deliveries in progress for the session in this process.
+    // How many claims this worker has started. A read taken at a lower count
+    // may predate a turn that took the inputs it shows pending.
+    this.claimsStarted = 0;
+    // Deliveries in progress for the session in this process, and senders
+    // about to hand one a read (see consume).
     this.deliveries = 0;
     this.holder = null;
+    // A write-free early claim can give way to a backed delivery. Once its
+    // backstop succeeds, it is a normal claim and cannot be displaced here.
+    this.opening = null;
+  }
+
+  // Taken just before a read of the log, for consume to tell whether a turn
+  // ran here since: the claims started, or null while one runs.
+  mark() {
+    return this.running ? null : this.claimsStarted;
   }
 
   // The log folded as `delivery` judges whether a lease's holder lives.
@@ -1693,15 +1747,37 @@ class SessionWorker {
   // have the same message delivered again later.
   // `handoff` is the sender's own session object and the log it read and
   // extended, when the request that took the prompt runs it (see
-  // handoffEntries); the worker starts from them instead of reading again.
-  async consume(message, delivery = null, handoff = null) {
+  // handoffEntries), with `seen`, what mark() said before that read; the
+  // worker starts from them instead of reading again.
+  // `backstop`, from that request too, is its backstop's send still in
+  // flight, which settles with `delivery`. Until it does, the worker goes on
+  // only to an early start, which writes nothing before it (see claim). A
+  // send that failed ends the delivery; its sender fails the prompt.
+  async consume(message, delivery = null, handoff = null, backstop = null) {
     const log = handoff?.log ?? await this.backend.session(this.sessionId);
+    // The claims this worker had started when the read began, or null when
+    // one was running then, whose writes it may not show.
+    let seen = handoff ? handoff.seen : this.mark();
     let entries = handoff?.entries ?? await log.read();
     let state = this.fold(entries, delivery);
     if (!knownMessage(state, message)) {
       this.agent.emit("session.refused", { sessionId: this.sessionId, messageId: message.messageId, reason: "unknown message" });
       return undefined;
     }
+    // Folded again with the backstop's delivery, which can only end a lease
+    // that stood without it (see redelivers).
+    const awaitBackstop = async () => {
+      if (!backstop) return true;
+      try {
+        delivery = await backstop;
+      } catch {
+        return false;
+      } finally {
+        backstop = null;
+      }
+      state = this.fold(entries, delivery);
+      return true;
+    };
     await this.backend.refreshDeadline?.();
     // When this delivery's function stops, if it does.
     const deadline = this.backend.deadline() ?? (this.backend.maxDurationMs === null ? null : Date.now() + this.backend.maxDurationMs);
@@ -1710,20 +1786,48 @@ class SessionWorker {
     // to another agent's session does, goes on to it.
     const owner = state.agent ?? agentOf(message);
     if (owner !== this.agent.name) {
+      if (!(await awaitBackstop())) return undefined;
       await this.backend.queue.send(queuedMessage({ ...message, agent: owner }, this.backend.store), {
         idempotencyKey: `${message.sessionId}:${message.type}:${message.messageId}:to:${owner}`,
       });
       this.agent.emit("session.forwarded", { sessionId: this.sessionId, agent: owner });
       return undefined;
     }
+    // A turn this worker ran since the read may have run this message,
+    // which the read still shows pending; starting from it would send the
+    // turn's model request twice. A turn still running answers below.
+    const caughtUp = async () => {
+      while (!this.running && seen !== this.claimsStarted) {
+        seen = this.claimsStarted;
+        entries = await log.read();
+        state = this.fold(entries, delivery);
+      }
+    };
     for (let claims = 0; claims < 8; claims += 1) {
+      await caughtUp();
       // A session with no open turn starts its next prompt at once: the
       // first model request goes out while the lease is written, and
       // nothing else is written until it lands.
-      const early = this.running || state.lease ? null : earlyStart(entries, state, message, (items) => this.fold(items, delivery));
+      const startable = () => (this.running || state.lease ? null : earlyStart(entries, state, message, (items) => this.fold(items, delivery)));
+      let early = startable();
+      if (!early) {
+        if (!(await awaitBackstop())) return undefined;
+        // Only a write-free opener may be displaced. Never await a live
+        // claim here: its run/turn may be waiting for this delivery's steer.
+        const opening = this.opening;
+        if (opening) {
+          opening.stop();
+          await opening.stopped;
+        }
+        // Fold the durable log again after displacement: this delivery's
+        // backstop can recover earlier stored inputs too, in log order.
+        await caughtUp();
+        early = startable();
+      }
       let outcome;
       if (early) {
-        outcome = await this.claim(log, state, deadline, early, delivery);
+        outcome = await this.claim(log, state, deadline, early, delivery, backstop);
+        if (!(await awaitBackstop())) return undefined;
       } else {
         if (this.running) return { timeoutSeconds: runningBackstopSeconds };
         if (!state.hasWork) {
@@ -1752,6 +1856,7 @@ class SessionWorker {
       }
       // The turns ran, or another worker's write came before this claim:
       // read the log again.
+      seen = this.mark();
       entries = await log.read();
       state = this.fold(entries, delivery);
     }
@@ -1762,12 +1867,16 @@ class SessionWorker {
   // the chain there, and runs it. With `early`, what `earlyStart` returned,
   // the message's input is written with the lease and the next turn starts
   // before either lands. The lease names `delivery`, so a later delivery of
-  // the same message can tell it lost its holder. Returns what run()
-  // returns, or "refused" when another worker's write came before the claim.
-  async claim(log, state, deadline, early, delivery = null) {
+  // the same message can tell it lost its holder. With `backstop`, the send
+  // that names that delivery, still in flight: every write waits for it, so
+  // the lease names it, and the engine opens meanwhile. Returns what run()
+  // returns, "refused" when another worker's write came before the claim,
+  // or "unqueued" when the backstop failed or the write-free opener gave way.
+  async claim(log, state, deadline, early, delivery = null, backstop = null) {
     // Claimed before the first await, so a delivery that arrives meanwhile
     // sees the session running here.
     this.running = true;
+    this.claimsStarted += 1;
     this.holder = newId("wkr");
     const lease = {
       k: "lease",
@@ -1779,11 +1888,29 @@ class SessionWorker {
       ...(delivery ? { delivery } : {}),
     };
     this.backend.holding(this.holder, true);
+    let unqueued = false;
+    let opening = null;
+    let stopped;
+    let displaced = false;
+    const revoked = backstop ? new Error("early opener displaced by a backed delivery") : null;
+    const giveWay = backstop ? new Promise((_, reject) => {
+      opening = {
+        stopped: new Promise((resolve) => { stopped = resolve; }),
+        stop: () => { displaced = true; reject(revoked); },
+      };
+      this.opening = opening;
+    }) : null;
+    const sent = backstop ? Promise.race([backstop, giveWay]).then((delivered) => {
+      if (displaced) throw revoked;
+      this.opening = null;
+      if (delivered) lease.delivery = delivered;
+    }) : null;
+    void sent?.catch(() => { unqueued = true; });
     try {
       // Both writes go out at once and neither waits for the other; the
       // claim settles once both have, with the lease's cursor if it landed
-      // and the first failure.
-      const writes = [log.append(lease), ...(early?.writes ?? []).map((entry) => log.append(entry))];
+      // and the first failure. A failed backstop fails both unmade.
+      const writes = [lease, ...(early?.writes ?? [])].map((entry) => (sent ? sent.then(() => log.append(entry)) : log.append(entry)));
       const claimed = Promise.allSettled(writes).then(async ([leased, ...rest]) => {
         const head = leased.status === "fulfilled" ? leased.value : null;
         const error = leased.status === "rejected" ? leased.reason : rest.find((item) => item.status === "rejected")?.reason ?? null;
@@ -1802,7 +1929,7 @@ class SessionWorker {
       });
       let outcome;
       try {
-        outcome = await this.run(log, claimed, lease, deadline, early?.state ?? null);
+        outcome = await this.run(log, claimed, lease, deadline, early?.state ?? null, sent?.then(() => true, () => false));
       } catch (error) {
         if ((await claimed).error === null) throw error;
       }
@@ -1812,14 +1939,17 @@ class SessionWorker {
       // wrote nothing and showed nothing. A fenced one leaves the delivery
       // to read the log and try again; after any other failure the same
       // message runs the session again shortly, once a lease that landed is
-      // let go.
+      // let go. One whose backstop failed is its sender's to report.
       if (isFenced(settled.error)) return "refused";
+      if (unqueued) return "unqueued";
       this.agent.emit("session.error", { sessionId: this.sessionId, error: errorSummary(settled.error) });
       if (settled.head !== null) await log.append({ k: "release", a: settled.head, holder: this.holder }).catch(() => {});
       return "failed";
     } finally {
       this.backend.holding(this.holder, false);
       this.running = false;
+      if (this.opening === opening) this.opening = null;
+      stopped?.();
     }
   }
 
@@ -1835,8 +1965,9 @@ class SessionWorker {
   // over. With `early`, the state the session was read in, the first turn
   // starts before the claim lands: every write waits for it, and once it
   // failed nothing more is written and the turn stops. The caller answers
-  // for a claim that failed.
-  async run(raw, claimed, lease, deadline, early) {
+  // for a claim that failed. `backstopSent`, when given, resolves whether
+  // the backstop the lease names was sent without displacing this opener.
+  async run(raw, claimed, lease, deadline, early, backstopSent = null) {
     const agent = this.agent;
     let head = null;
     let failed = null;
@@ -2009,7 +2140,16 @@ class SessionWorker {
         // What the turn it runs first runs with: the open turn's context and
         // settings, or the next prompt's.
         harnessRun = runOf(state.openTurn ?? state.pending[0]);
-        harness = await agent.openHarness(this.sessionId, store, harnessRun, ready);
+        const opening = agent.openHarness(this.sessionId, store, harnessRun, ready);
+        // A failed backstop does not wait out a slow open: its sender fails
+        // the prompt once this worker stops. The late engine closes in the
+        // background, and the agent's close() waits for it.
+        if (backstopSent && !(await Promise.race([backstopSent, opening.then(() => true, () => true)]))) {
+          agent.track(opening.then((late) => late.close()).catch(() => {}));
+          await ready;
+          return broken();
+        }
+        harness = await opening;
       } catch (error) {
         // The image store failed to answer while the engine read the
         // session's images: as when the log can't be read, the delivery
@@ -2026,6 +2166,14 @@ class SessionWorker {
         agent.emit("session.error", { sessionId: this.sessionId, error: errorSummary(error) });
         return "done";
       }
+      // The opener is inert until its own backstop succeeds. A displaced
+      // opener closes without taking a turn or writing anything.
+      if (backstopSent && !(await backstopSent)) {
+        agent.track(harness.close().catch(() => {}));
+        harness = null;
+        await ready;
+        return broken();
+      }
       const yieldAt = deadline === null ? undefined : Math.max(1, deadline - this.backend.reserveMs);
       for (;;) {
         if (failed) return broken();
@@ -2645,6 +2793,15 @@ export function createDurableAgentFactory({ harness, defaultDurability, defaultS
     let closed = false;
     const workers = new Map();
     const active = new Set();
+    // Session ids this process minted whose first prompt has not yet tried
+    // to create their run, newest kept. Only a hint that the run may not
+    // exist: whether it did is what that prompt's own write shows.
+    const minted = new Set();
+    const mint = (id) => {
+      minted.add(id);
+      if (minted.size > maxMintedIds) minted.delete(minted.values().next().value);
+      return id;
+    };
     const backend = () => {
       if (closed) return Promise.reject(new Error(`${label} is closed`));
       backendPromise ??= (async () => {
@@ -2687,17 +2844,27 @@ export function createDurableAgentFactory({ harness, defaultDurability, defaultS
     const member = { open: backend, durability: durabilityOf, definition: definitionOf(harnessOptions), store: durability ? storeOf(durability) : unresolved, defaults: durability ? null : unresolved };
     claimName(agentName, member);
     const registered = joinGroup(agentsByName, agentName, member);
-    // One delivery of `message` to the session's worker here: from the
-    // queue, with `delivery` naming the queue's message and attempt, or with
-    // `inRequest` from the request that took the prompt.
-    const receive = (created, message, delivery, { inRequest = false, handoff = null } = {}) => {
-      let worker = workers.get(message.sessionId);
+    // The session's worker here, kept until as many letGo() calls.
+    const hold = (created, sessionId) => {
+      let worker = workers.get(sessionId);
       if (!worker) {
-        worker = new SessionWorker(agent, created, message.sessionId);
-        workers.set(message.sessionId, worker);
+        worker = new SessionWorker(agent, created, sessionId);
+        workers.set(sessionId, worker);
       }
       worker.deliveries += 1;
-      let work = worker.consume(message, delivery, handoff);
+      return worker;
+    };
+    const letGo = (worker, sessionId) => {
+      worker.deliveries -= 1;
+      // A worker lives while a delivery runs it.
+      if (worker.deliveries === 0 && !worker.running && workers.get(sessionId) === worker) workers.delete(sessionId);
+    };
+    // One delivery of `message` to the session's worker here: from the
+    // queue, with `delivery` naming the queue's message and attempt, or with
+    // `inRequest` from the request that took the prompt.
+    const receive = (created, message, delivery, { inRequest = false, handoff = null, backstop = null } = {}) => {
+      const worker = hold(created, message.sessionId);
+      let work = worker.consume(message, delivery, handoff, backstop);
       if (inRequest) {
         // No queue delivered this message, so none delivers it again: a turn
         // that must go on later continues in a fresh message. One whose
@@ -2718,9 +2885,7 @@ export function createDurableAgentFactory({ harness, defaultDurability, defaultS
         emit("session.error", { sessionId: message.sessionId, error: errorSummary(error) });
       }).finally(() => {
         active.delete(work);
-        worker.deliveries -= 1;
-        // A worker lives while a delivery runs it.
-        if (worker.deliveries === 0 && !worker.running && workers.get(message.sessionId) === worker) workers.delete(message.sessionId);
+        letGo(worker, message.sessionId);
       });
       return work;
     };
@@ -2741,14 +2906,17 @@ export function createDurableAgentFactory({ harness, defaultDurability, defaultS
       let id = requestedId ?? null;
       let seeded = seed === undefined || requestedId !== undefined;
       const resolved = backend().then((created) => {
-        id ??= created.newSessionId();
+        id ??= mint(created.newSessionId());
         if (!created.validSessionId(id)) throw new TypeError(`${created.name} durability cannot hold session id ${JSON.stringify(id)}`);
         return { created, id };
       });
       void resolved.catch(() => {});
       // With `inRequest`, a prompt runs here, in the request that took it,
       // where the durability allows (see `runInRequest`).
-      const send = async (message, { inRequest = false } = {}) => {
+      // `fresh` is the log whose own write just created the session's run, so
+      // the log is empty without reading it. That object, not a new one, goes
+      // on: it holds what the creation showed of the log.
+      const send = async (message, { inRequest = false, fresh = null } = {}) => {
         const { created, id: sessionId } = await resolved;
         const extra = {
           ...(seeded ? {} : { seed }),
@@ -2762,35 +2930,64 @@ export function createDurableAgentFactory({ harness, defaultDurability, defaultS
         // a turn runs or as whom (`tests/tla/sdk/TenantIsolation.tla`
         // OnlySentRuns), and a queue that ends with the process loses no
         // input.
-        const log = await created.session(sessionId);
-        const read = await log.read();
-        const newestSeen = log.newest?.();
-        const appended = await recordMessage(log, foldSessionLog(read), full);
-        const queued = queuedMessage(full, created.store);
-        const idempotencyKey = `${sessionId}:${message.type}:${message.messageId}`;
-        if (inRequest && created.runInRequest) {
-          await created.refreshDeadline?.();
-          const deadline = deliveryDeadline(created);
-          if (deadline !== null) {
-            // This request runs the turn, and the queue keeps the message as
-            // a backstop it delivers only after the request's deadline, by
-            // when the request has stopped. The lease names the backstop, so
-            // if the request died, the backstop takes the session over and
-            // continues the turn.
-            const delaySeconds = Math.ceil(Math.max(0, deadline - Date.now()) / 1000) + inlineBackstopMarginSeconds;
-            const { messageId: backstop } = await created.queue.send(queued, { idempotencyKey, delaySeconds }) ?? {};
-            seeded = true;
-            const delivery = backstop ? { messageId: backstop, attempt: 0 } : null;
-            // receive() reports a failure to the host; the backstop retries it.
-            const entries = handoffEntries(read, newestSeen, appended);
-            const handoff = entries ? { log, entries } : null;
-            const work = receive(created, queued, delivery, { inRequest: true, handoff }).then(() => {}, () => {});
-            created.waitUntil?.(work);
-            return;
+        const log = fresh ?? await created.session(sessionId);
+        const inline = inRequest && created.runInRequest;
+        // Held from before the read until receive() takes over, so a turn
+        // run here meanwhile is counted on the worker the handoff goes to,
+        // not on one dropped in between (see consume).
+        const worker = inline ? hold(created, sessionId) : null;
+        try {
+          // Taken before this message is written, so a turn here that could
+          // have run it counts, also when a fresh log is not read at all.
+          const seen = worker?.mark() ?? null;
+          // Fresh: the caller's own write just created the run, so its log
+          // held no entry, as a read before that write would have shown.
+          const read = fresh ? [] : await log.read();
+          const appended = await recordMessage(log, foldSessionLog(read), full);
+          // Taken after the writes, which pass it over a run they created.
+          const newestSeen = log.newest?.();
+          const queued = queuedMessage(full, created.store);
+          const idempotencyKey = `${sessionId}:${message.type}:${message.messageId}`;
+          if (inline) {
+            await created.refreshDeadline?.();
+            const deadline = deliveryDeadline(created);
+            if (deadline !== null) {
+              // This request runs the turn, and the queue keeps the message as
+              // a backstop it delivers only after the request's deadline, by
+              // when the request has stopped. The lease names the backstop, so
+              // if the request died, the backstop takes the session over and
+              // continues the turn.
+              const delaySeconds = Math.ceil(Math.max(0, deadline - Date.now()) / 1000) + inlineBackstopMarginSeconds;
+              const backstop = (async () => {
+                const { messageId: backstopId } = await created.queue.send(queued, { idempotencyKey, delaySeconds }) ?? {};
+                return backstopId ? { messageId: backstopId, attempt: 0 } : null;
+              })();
+              void backstop.catch(() => {});
+              // The worker opens its engine while the backstop is sent; its
+              // lease, its writes and its first model request wait for the
+              // send (see claim). receive() reports a failure to the host; the
+              // backstop retries it.
+              const entries = handoffEntries(read, newestSeen, appended);
+              const handoff = entries ? { log, entries, seen } : null;
+              const work = receive(created, queued, null, { inRequest: true, handoff, backstop }).then(() => {}, () => {});
+              created.waitUntil?.(work);
+              try {
+                await backstop;
+              } catch (error) {
+                // The worker has stopped, having stored nothing, before the
+                // caller hears: a retry finds no worker here, as if none ran.
+                await work;
+                throw error;
+              }
+              seeded = true;
+              return;
+            }
           }
+          await created.queue.send(queued, { idempotencyKey });
+          seeded = true;
+        } finally {
+          if (worker) letGo(worker, sessionId);
         }
-        await created.queue.send(queued, { idempotencyKey });
-        seeded = true;
       };
       // Settles once the latest prompt from this session object with images
       // to store is stored or has failed; null while none has. Each later
@@ -2812,20 +3009,26 @@ export function createDurableAgentFactory({ harness, defaultDurability, defaultS
             try {
               const read = input === undefined || ready === null || aborted() ? input : await ready();
               const message = { type, messageId, ...(input === undefined ? {} : { input: read }) };
+              const { created, id: sessionId } = await resolved;
+              const log = await created.session(sessionId);
+              // The first prompt to a session id this process minted creates
+              // its run before anything reads it. When that write made the
+              // run, the log held no entry and the stream no line: what this
+              // turn would read is known, retried or not, as reads just before
+              // the write would have returned it.
+              const fresh = type === "prompt" && !aborted() && minted.delete(sessionId) && typeof log.fresh === "function" && await log.fresh();
               const queue = () => {
                 if (progress) progress.sent = true;
-                return send(message, { inRequest: type === "prompt" });
+                return send(message, { inRequest: type === "prompt", fresh: fresh ? log : null });
               };
-              const { created, id: sessionId } = await resolved;
-              const log = await created.session(sessionId);
               let attaching = type === "resume";
-              let from = null;
+              let from = fresh ? 0 : null;
               // The viewer's start is read before the message is queued, so
               // every line this message's own turn writes comes after it, and
               // an end for this id before it can only be from a turn this id
               // already ran.
-              if (retried) from = await log.ui.length();
-              if (retried && !aborted()) {
+              if (retried && !fresh) from = await log.ui.length();
+              if (retried && !fresh && !aborted()) {
                 // The log, for that answer, is read alongside the one queue
                 // send.
                 const [state] = await Promise.all([
@@ -2841,7 +3044,7 @@ export function createDurableAgentFactory({ harness, defaultDurability, defaultS
                 if (outcome.unsure) return { log, from, attaching: true, endWithinMs: retryEndWaitMs, unsure: true };
                 return { log, from, attaching: outcome.follow === true };
               }
-              if (retried) {
+              if (retried && !fresh) {
                 // A turn this id already ran answers from the log, without
                 // queueing it again. The viewer's start was read first, so a
                 // turn that ends after it has its end in view.
@@ -3145,7 +3348,7 @@ export function createDurableAgentFactory({ harness, defaultDurability, defaultS
       },
       /** An id for a new session, before its first prompt. */
       async newSessionId() {
-        return (await backend()).newSessionId();
+        return mint((await backend()).newSessionId());
       },
       /** The agent's name: its sessions' turns run only on agents with this name. */
       get name() {

package/fetch-cleanup.js

@@ -1,6 +1,14 @@
 export const cleanupTimeoutMs = 100;
 export const cleanupByteLimit = 64 * 1024;
 
+// A response's Retry-After in whole seconds, read as native fx reads it
+// (digits only), or -1 when it has none. Both hosts pass it to fx.
+export function retryAfterSeconds(headers) {
+  const value = headers.get("retry-after")?.trim();
+  if (!value || !/^\d+$/.test(value)) return -1;
+  return Math.min(Number(value), 0x7fffffff);
+}
+
 // Policy only; the host owns the reader, clock, cancellation and teardown.
 export function fetchCleanupAction(state, maxAge = cleanupTimeoutMs, maxBytes = cleanupByteLimit) {
   if (state.eof) return "done";

package/node.js

@@ -7,7 +7,7 @@ import { isAbsolute, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { bundledAssetUrl } from "./bundled-asset.js";
 import { CoreOutput } from "./core-output.js";
-import { fetchCleanupAction, cleanupTimeoutMs, cleanupByteLimit } from "./fetch-cleanup.js";
+import { fetchCleanupAction, cleanupTimeoutMs, cleanupByteLimit, retryAfterSeconds } from "./fetch-cleanup.js";
 import { createDurableAgentFactory, memory, wakeHandler } from "./durable.js";
 import { fxHarness } from "./fx-harness.js";
 import {
@@ -471,7 +471,11 @@ function createNativeCoreRuntime(addon, options) {
       });
       const response = await wait(responseTask);
       if (settled && !state.consumed) throw new DOMException("Aborted", "AbortError");
-      const started = settled ? fetchOperationStale : addon.startCoreFetchResponse(core, state.handle, response.status);
+      const started = settled
+        ? fetchOperationStale
+        : typeof addon.startCoreFetchResponseWithRetryAfter === "function"
+          ? addon.startCoreFetchResponseWithRetryAfter(core, state.handle, response.status, retryAfterSeconds(response.headers))
+          : addon.startCoreFetchResponse(core, state.handle, response.status);
       if (started !== fetchOperationApplied && started !== fetchOperationStale) throw new Error(`invalid native fetch start result ${started}`);
       state.active = started === fetchOperationApplied;
       reader = response.body?.getReader();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libfx",
-  "version": "0.0.16",
+  "version": "0.0.17",
   "description": "Embed fx agents and terminals in JavaScript hosts",
   "type": "module",
   "repository": {
@@ -97,9 +97,9 @@
   },
   "license": "Apache-2.0",
   "optionalDependencies": {
-    "@libfx/libfx-linux-x64-gnu": "0.0.16",
-    "@libfx/libfx-linux-arm64-gnu": "0.0.16",
-    "@libfx/libfx-darwin-x64": "0.0.16",
-    "@libfx/libfx-darwin-arm64": "0.0.16"
+    "@libfx/libfx-linux-x64-gnu": "0.0.17",
+    "@libfx/libfx-linux-arm64-gnu": "0.0.17",
+    "@libfx/libfx-darwin-x64": "0.0.17",
+    "@libfx/libfx-darwin-arm64": "0.0.17"
   }
 }

package/types/libfx.d.cts

@@ -46,7 +46,7 @@ export interface FxModelOptions {
   effort?: FxEffort;
   /** Enables the fast lane for models that advertise one. */
   fast?: boolean;
-  /** Requests Ultra mode, the higher-cost service tier, for models whose metadata advertises it. Disables Fast. */
+  /** Requests Ultrafast mode, the higher-cost service tier, for models whose metadata advertises it. Disables Fast. */
   ultrafast?: boolean;
 }
 
@@ -261,8 +261,8 @@ export interface FxUsage {
   reasoningTokens?: number;
 }
 
-/** Why an engine turn ended. */
-export type FxStopReason = "end_turn" | "max_output_tokens" | "max_model_turns" | "refused" | "cancelled";
+/** Why an engine turn ended. `yielded`: it stopped at its `yieldAt` and stays open for `resume()`. */
+export type FxStopReason = "end_turn" | "max_output_tokens" | "max_model_turns" | "refused" | "cancelled" | "yielded";
 
 // ---------------------------------------------------------------------------
 // Diagnostics
@@ -304,7 +304,8 @@ export type FxEngineEvent = FxEventBase & (
   | { type: "permission.request"; request: unknown }
   | { type: "permission.resolve"; optionId: unknown }
   | { type: "journal.open"; events: number; checkpoint: boolean; turns: unknown; resumable: boolean }
-  | { type: "journal.append"; events: number }
+  /** `barrier`: the record's `barrier`, as `Persistence.append` receives it. */
+  | { type: "journal.append"; events: number; barrier: boolean }
   | { type: "journal.error"; error: string }
   | { type: "checkpoint.save"; through: string; bytes: number }
   | { type: "checkpoint.error"; error: string; message: string }
@@ -423,7 +424,7 @@ export type FxHookEvent = FxHookEnvelope & (
   | { type: "mcp.start"; data: { operationId: number | string; callId: string | null; server: string | null; tool: string; transport: string | null } }
   | { type: "mcp.request"; data: { operationId: number | string; requestId: number | string; requestIdKind: "jsonrpc" | "engine" | "correlation" } }
   | { type: "mcp.end"; data: { operationId: number | string; status: "success" | "failure" | "cancelled" | "input_required" | "unavailable" | "unknown"; error: string | null } }
-  | { type: "delegation"; data: { callId: string; childSessionId: string; workId: string; operationId: string | null; phase: "dispatched" | "completed" | "yielded" | "replayed" | "failed" | "cancelled" | "feedback_queued" | "feedback_applied" | "feedback_not_applied" } }
+  | { type: "delegation"; data: { callId: string; childSessionId: string; workId: string; operationId: string | null; phase: "dispatched" | "completed" | "replayed" | "failed" | "cancelled" | "feedback_queued" | "feedback_applied" | "feedback_not_applied" } }
   /** Emitted only after append resolves and its cursor validates. */
   | { type: "journal.commit"; data: { cursor: string; firstSeq: number | null; lastSeq: number | null; eventCount: number } }
   | { type: "journal.restore"; data: { cursor: string | null; lastSeq: number; resumable: boolean; openTurnId: string | null; lastTurnId: string | null } }
@@ -669,6 +670,12 @@ export interface FxCustomProviderModel {
   maxOutputTokens?: number;
   supportsToolUse?: boolean;
   supportsVision?: boolean;
+  /** The request field that carries the output limit. Defaults to `"max_tokens"`. */
+  outputLimitField?: "max_tokens" | "max_completion_tokens";
+  /** Fields sent in the body of every request for the model, such as `{ temperature: 0.2 }`. A field fx writes itself, such as `messages`, is refused. */
+  request?: Record<string, unknown>;
+  /** The effort levels the model offers, in order, each with the request fields that choose it, such as `{ high: { reasoning_effort: "high" } }`. A level the model does not list is not sent. */
+  reasoningEfforts?: Record<string, Record<string, unknown>>;
 }
 
 /** A server that speaks OpenAI Chat Completions, such as a local model server or a router. */
@@ -679,6 +686,12 @@ export interface FxCustomProviderDefinition {
   baseUrl: string;
   /** The models it serves, by id. */
   models?: Record<string, FxCustomProviderModel>;
+  /** Fields for every model, including one `models` does not list, where the model sets none itself. */
+  modelDefaults?: FxCustomProviderModel;
+  /** The model that names a session from its first prompt. Without it, a session keeps the title derived from the prompt. */
+  titleModel?: string;
+  /** The model that reads images for a model that cannot. Without it, the provider has no image fallback. */
+  visionModel?: string;
 }
 
 /** A custom provider's API key. */
@@ -796,8 +809,8 @@ export interface FxAccepted {
 /** How a durable turn ended. */
 export interface FxTurnResult {
   messageId: string;
-  /** `error` when the turn failed, with the reason in `error`; `unknown` when the process that ran it stopped before writing how it ended. */
-  stopReason: FxStopReason | "error" | "unknown";
+  /** `error` when the turn failed, with the reason in `error`; `unknown` when the process that ran it stopped before writing how it ended. A yielded turn continues, so it never ends `yielded`. */
+  stopReason: Exclude<FxStopReason, "yielded"> | "error" | "unknown";
   /** Absent when the result is a failure read from the session's log rather than from the turn's end. */
   usage?: FxUsage;
   error?: FxErrorSummary;
@@ -848,7 +861,7 @@ export type FxStreamLine = (
   | {
     type: "turn_end";
     messageId: string;
-    stopReason: FxStopReason | "error" | "unknown";
+    stopReason: Exclude<FxStopReason, "yielded"> | "error" | "unknown";
     usage?: FxUsage;
     error?: FxErrorSummary;
     repeated?: true;

package/wasm-runtime.js

@@ -1,6 +1,7 @@
 // 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 { retryAfterSeconds } from "./fetch-cleanup.js";
 import {
   cancelResponseBody,
   decoder,
@@ -352,6 +353,11 @@ function createRuntime(options) {
       ready ? settled() : 0);
   }
 
+  function streamRetryAfter(handle) {
+    const response = streams.get(handle)?.response;
+    return response ? retryAfterSeconds(response.headers) : -1;
+  }
+
   function streamNext(handle, outPtr, outCap) {
     const state = streams.get(handle);
     if (!state) return -1;
@@ -930,6 +936,7 @@ function createRuntime(options) {
     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_stream_retry_after: streamRetryAfter,
     fx_http_request: new WebAssembly.Suspending(httpRequest),
     fx_host_tool_call: new WebAssembly.Suspending(hostToolCall),
     fx_journal_flush: new WebAssembly.Suspending(journalFlush),