libfx 0.0.13-dev.1472.g2c7a4f83f06f → 0.0.13-dev.1510.ga878d4900a6a

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/fx-core.wasm CHANGED
Binary file
package/fx-harness.js CHANGED
@@ -5,6 +5,9 @@ import { coreAnswered, engineInternals, journalMarksWanted, normalizeInstruction
5
5
  import { createCredentialMemory, credentialMemory } from "./subscription.js";
6
6
 
7
7
  const encoder = new TextEncoder();
8
+ // Every worker reads each record since the session's last checkpoint, so a
9
+ // durable session checkpoints far sooner than the engine's default.
10
+ const durableCheckpointAfterBytes = 64 * 1024;
8
11
 
9
12
  /**
10
13
  * The fx harness for `createDurableAgentFactory`. `createEngine(options)`
@@ -36,9 +39,11 @@ export function fxHarness({ createEngine, defaultApiKey = async () => undefined
36
39
  // The core folds the session from the marks on each record.
37
40
  persistence: { ...store, [journalMarksWanted]: true },
38
41
  inputsDurable: true,
39
- // A checkpoint at every turn end; where a turn yields the core
40
- // saves one itself before it lets the session go.
41
- checkpointAfterBytes: 0,
42
+ // A turn's end saves a checkpoint once the records since the last
43
+ // one reach this many bytes, so a short turn writes none and a
44
+ // worker reads back little; where a turn yields, the core saves
45
+ // one itself before it lets the session go.
46
+ checkpointAfterBytes: durableCheckpointAfterBytes,
42
47
  ...(context === undefined || context === null ? {} : { toolContext: context }),
43
48
  });
44
49
  return fxSession(engine, idempotent);
@@ -172,9 +177,20 @@ function claimedTools(tools, ready) {
172
177
  return tools;
173
178
  }
174
179
 
180
+ // The tools whose cut-off calls run again. Every tool the host runs must say
181
+ // whether that is safe, so the choice is never a default: `idempotent: true`
182
+ // when running a call twice is harmless, `false` when it is not. A tool that
183
+ // is not an object is left for the engine to refuse.
175
184
  function idempotentTools(tools) {
176
185
  const names = new Set();
177
- for (const tool of toolEntries(tools)) if (tool?.idempotent === true && typeof tool.name === "string") names.add(tool.name);
186
+ for (const [index, tool] of toolEntries(tools).entries()) {
187
+ if (!tool || typeof tool !== "object" || tool.providerExecuted === true) continue;
188
+ if (typeof tool.idempotent !== "boolean") {
189
+ const name = typeof tool.name === "string" ? tool.name : index;
190
+ throw new TypeError(`tool ${name} must set idempotent: true if running a call twice is safe, or idempotent: false if it is not`);
191
+ }
192
+ if (tool.idempotent && typeof tool.name === "string") names.add(tool.name);
193
+ }
178
194
  return names;
179
195
  }
180
196
 
package/fx-sdk.js CHANGED
@@ -24,6 +24,9 @@ const maxModelBytes = 1024;
24
24
  // Matches the kernel's ReasoningEffort.max_name_bytes.
25
25
  const maxEffortBytes = 64;
26
26
  const maxUrlBytes = 16 * 1024;
27
+ // The answer a resumed turn gives a call its crash left running; matches
28
+ // unfinished_tool_output in session_adapter.zig.
29
+ const unfinishedToolOutput = "fx stopped while this tool was running, so it may have partly run. Check its effects before running it again.";
27
30
  const maxModelCatalogBytes = 4 * 1024 * 1024;
28
31
  const maxModelCatalogEntries = 10_000;
29
32
  const streamReadsPerTaskYield = 32;
@@ -230,7 +233,7 @@ export class FxFencedError extends Error {
230
233
  }
231
234
  }
232
235
 
233
- /** The journal was written by a newer libfx than this one. */
236
+ /** The journal, or the `checkpoint` option, was written by a newer libfx. */
234
237
  export class FxJournalVersionError extends Error {
235
238
  constructor(message) {
236
239
  super(message);
@@ -311,17 +314,28 @@ function journalAppendError(cause) {
311
314
  return error;
312
315
  }
313
316
 
314
- // Restoring an open turn needs only its newest progress, so an older one's
315
- // state is left out of a load (data: null). A load then grows with the
316
- // session's committed turns, not with every step of every turn.
317
+ // Restoring an open turn needs only its newest progress, and the ones it
318
+ // extends when it carries only what is new back to one that carries all of
319
+ // it, and the results of calls no progress has answered yet. So an older
320
+ // progress's state, and an answered call's result, are left out of a load
321
+ // (data: null). A load then grows with the session's committed turns, not
322
+ // with every step of every turn.
317
323
  function withoutSupersededProgress(events) {
318
324
  const kept = new Array(events.length);
319
325
  let superseded = false;
326
+ let answered = false;
320
327
  for (let index = events.length - 1; index >= 0; index -= 1) {
321
328
  const event = events[index];
322
329
  const type = event?.type;
323
- kept[index] = superseded && type === "turn_progress" && event.data != null ? { ...event, data: null } : event;
324
- if (type === "turn_progress" || type === "turn_committed" || type === "turn_progress_cleared") superseded = true;
330
+ const dropped = event?.data != null && ((type === "turn_progress" && superseded) || (type === "tool_result" && answered));
331
+ kept[index] = dropped ? { ...event, data: null } : event;
332
+ if (type === "turn_committed" || type === "turn_progress_cleared") {
333
+ superseded = true;
334
+ answered = true;
335
+ } else if (type === "turn_progress") {
336
+ answered = true;
337
+ if (event.base === undefined) superseded = true;
338
+ }
325
339
  }
326
340
  return kept;
327
341
  }
@@ -444,8 +458,9 @@ function journalMarks(events) {
444
458
  for (const event of events) {
445
459
  if (event?.type === "turn_progress") {
446
460
  if (typeof event.turnId === "string") marks.push({ start: event.turnId });
447
- const steps = event.data?.execution?.tool_steps;
448
- if (Array.isArray(steps)) marks.push({ step: `${steps.length}:${String(event.data.tool_state ?? "none")}` });
461
+ // A progress that carries only what is new counts all the turn's steps.
462
+ const steps = Number.isSafeInteger(event.steps) ? event.steps : event.data?.execution?.tool_steps?.length;
463
+ if (Number.isSafeInteger(steps)) marks.push({ step: `${steps}:${String(event.data?.tool_state ?? "none")}` });
449
464
  } else if (event?.type === "turn_committed" || event?.type === "turn_progress_cleared") marks.push({ end: true });
450
465
  else if (event?.type === "turn_yielded") marks.push({ yield: true });
451
466
  else if (event?.type === "input_accepted" && typeof event.data?.id === "string") marks.push({ accepted: event.data.id });
@@ -2088,8 +2103,10 @@ function normalizeHostTools(value) {
2088
2103
  description,
2089
2104
  inputSchema: schema,
2090
2105
  ...(writes === undefined ? {} : { writes }),
2091
- // The engine does not read `idempotent`, but it stays in the shape a
2092
- // checkpoint records, so a change to it counts as a changed tool set.
2106
+ // The engine reads `idempotent`: such a tool runs beside others unless
2107
+ // it `writes`, and one that does not write starts before its intent is
2108
+ // stored. It is also in the shape a checkpoint records, so a change to
2109
+ // it counts as a changed tool set.
2093
2110
  ...(idempotent === true ? { idempotent: true } : {}),
2094
2111
  });
2095
2112
  executors.set(name, execute);
@@ -2217,12 +2234,15 @@ export async function createFxEngine(options = {}) {
2217
2234
  let closing = false;
2218
2235
  let coreExitError = null;
2219
2236
  const isCurrentTurn = (turn) => turn && activeTurn === turn && !turn.cancelled && !closing;
2220
- // Events go to the store in the order the core sends them: events that
2221
- // arrive together become one record, and each record's append names the
2222
- // cursor of the one before it, so a store refuses a write that does not
2223
- // continue what it holds. The core waits for a record only before an
2224
- // action others can see: a model request or a tool call.
2237
+ // Events go to the store in the order the core sends them, one append at
2238
+ // a time: events that arrive together become one record, and so do all
2239
+ // the events that arrive while an append is in flight. Each record's append
2240
+ // names the cursor of the one before it, so a store refuses a write that
2241
+ // does not continue what it holds, and says with `barrier` whether anyone
2242
+ // waits for it: the core before an action others can see, such as a tool
2243
+ // call with effects, or a caller for its input.
2225
2244
  const persistence = options.persistence ?? null;
2245
+ const wantsMarks = persistence?.marks === true || persistence?.[journalMarksWanted] === true;
2226
2246
  const checkpointAfterBytes = options.checkpointAfterBytes ?? defaultCheckpointAfterBytes;
2227
2247
  // The store's last cursor, and the last seq its records hold.
2228
2248
  let journalHead = null;
@@ -2233,13 +2253,13 @@ export async function createFxEngine(options = {}) {
2233
2253
  // One per agent, so a store can tell a repeated write from another writer's.
2234
2254
  const writerId = crypto.randomUUID();
2235
2255
  const journal = persistence && {
2236
- append(events) {
2256
+ append(events, barrier) {
2237
2257
  const data = encodeJournalRecord(events);
2238
2258
  const lastSeq = events.at(-1)?.seq;
2239
2259
  // A store that tracks turns without reading records asks for marks.
2240
- const marks = persistence[journalMarksWanted] === true ? { marks: journalMarks(events) } : {};
2260
+ const marks = wantsMarks ? { marks: journalMarks(events) } : {};
2241
2261
  const appended = appendTail.then(async () => {
2242
- const result = await persistence.append({ expected: journalHead, idempotencyKey: `${writerId}:${events[0]?.seq}`, data, ...marks });
2262
+ const result = await persistence.append({ expected: journalHead, idempotencyKey: `${writerId}:${events[0]?.seq}`, data, barrier, ...marks });
2243
2263
  if (!validCursor(result?.cursor)) throw new TypeError("persistence.append() must resolve to { cursor }");
2244
2264
  journalHead = result.cursor;
2245
2265
  if (Number.isSafeInteger(lastSeq)) appendedSeq = lastSeq;
@@ -2255,17 +2275,26 @@ export async function createFxEngine(options = {}) {
2255
2275
  // ended, so a retried prompt continues or skips its turn.
2256
2276
  let openTurnId = null;
2257
2277
  let lastTurnId = null;
2258
- // The calls the open turn left running: `{ id, name, arguments }`.
2278
+ // The calls the open turn left running: `{ id, name, arguments }`, and
2279
+ // what the resume tells the model about each one it does not run again.
2259
2280
  let ambiguousCalls = [];
2260
- // Asks `onAmbiguous` about each of them, once, and returns the ids of the
2261
- // calls to run again; the resume answers the rest as possibly run.
2262
- const rerunIds = (onAmbiguous) => {
2281
+ // Asks `onAmbiguous` about each of them, once. Returns the ids of the
2282
+ // calls to run again, and the rest, which the resume answers as possibly
2283
+ // run.
2284
+ const settleAmbiguous = (onAmbiguous) => {
2263
2285
  const calls = ambiguousCalls;
2264
2286
  ambiguousCalls = [];
2265
- if (onAmbiguous === undefined) return [];
2266
- return calls
2267
- .filter((call) => onAmbiguous({ executionId: call.id, name: call.name, input: parsedToolInput(call.arguments) }) === "rerun")
2268
- .map((call) => call.id);
2287
+ const rerun = onAmbiguous === undefined
2288
+ ? []
2289
+ : calls.filter((call) => onAmbiguous({ executionId: call.id, name: call.name, input: parsedToolInput(call.arguments) }) === "rerun").map((call) => call.id);
2290
+ return { rerun, answered: calls.filter((call) => !rerun.includes(call.id)) };
2291
+ };
2292
+ // Continues the open turn: the calls it left running run again or are
2293
+ // answered as possibly run, and each answered one ends for the turn's
2294
+ // viewers as it does for the model.
2295
+ const resumeOpenTurn = (promptOptions) => {
2296
+ const { rerun, answered } = settleAmbiguous(promptOptions.onAmbiguous);
2297
+ return normalizeTurn(startTurn(null, { ...promptOptions, [resumeTurn]: true, [rerunCallIds]: rerun }), answered);
2269
2298
  };
2270
2299
  // Follow-ups waiting for the turn ahead of them, oldest first.
2271
2300
  const followUps = [];
@@ -2289,6 +2318,10 @@ export async function createFxEngine(options = {}) {
2289
2318
  let journalQueue = [];
2290
2319
  let journalFlushScheduled = false;
2291
2320
  const journalPending = new Set();
2321
+ // The append in flight, and whether anyone waits for the events queued
2322
+ // behind it.
2323
+ let journalInFlight = null;
2324
+ let journalBarrier = false;
2292
2325
  let journalFailure = null;
2293
2326
  // Set by `turn.cancel({ reason: "handoff" })`: the journal keeps the open
2294
2327
  // turn for another agent, so this one stores nothing more.
@@ -2328,7 +2361,8 @@ export async function createFxEngine(options = {}) {
2328
2361
  journalFailureReported = true;
2329
2362
  return journalFailure;
2330
2363
  };
2331
- const queueJournalEvents = (events) => {
2364
+ // `barrier`: the core waits for these events before it goes on.
2365
+ const queueJournalEvents = (events, barrier = false) => {
2332
2366
  if (journalFailure || !Array.isArray(events) || events.length === 0) return;
2333
2367
  if (handedOff) {
2334
2368
  // The agent that opens the session next decides about these inputs.
@@ -2339,6 +2373,8 @@ export async function createFxEngine(options = {}) {
2339
2373
  return;
2340
2374
  }
2341
2375
  journalQueue.push(...events);
2376
+ // A caller waits for its steer or withdrawal to be stored.
2377
+ if (barrier || events.some((event) => event?.type === "input_accepted" || event?.type === "input_withdrawn")) journalBarrier = true;
2342
2378
  // A turn notes a new config right before its first progress, a barrier:
2343
2379
  // the two go out in one write instead of two in a row.
2344
2380
  if (events.every((event) => event?.type === "session_config")) return;
@@ -2346,15 +2382,20 @@ export async function createFxEngine(options = {}) {
2346
2382
  journalFlushScheduled = true;
2347
2383
  queueMicrotask(flushJournal);
2348
2384
  };
2385
+ // Sends the queued events as one record, unless an append is in flight:
2386
+ // then they wait for it, with any that arrive meanwhile, and go out
2387
+ // together once it lands.
2349
2388
  function flushJournal() {
2350
2389
  journalFlushScheduled = false;
2351
- if (journalFailure || journalQueue.length === 0) return;
2390
+ if (journalFailure || journalInFlight || journalQueue.length === 0) return;
2352
2391
  const batch = journalQueue;
2353
2392
  journalQueue = [];
2354
- emit("journal.append", { events: batch.length });
2393
+ const barrier = journalBarrier;
2394
+ journalBarrier = false;
2395
+ emit("journal.append", { events: batch.length, barrier });
2355
2396
  let appended;
2356
2397
  try {
2357
- appended = Promise.resolve(journal.append(batch));
2398
+ appended = Promise.resolve(journal.append(batch, barrier));
2358
2399
  } catch (error) {
2359
2400
  appended = Promise.reject(error);
2360
2401
  }
@@ -2370,7 +2411,12 @@ export async function createFxEngine(options = {}) {
2370
2411
  // Nothing the turn does from here can be saved, and after a fence the
2371
2412
  // session has another owner: stop the turn and its effects now.
2372
2413
  activeTurn?.cancel();
2373
- }).finally(() => journalPending.delete(settled));
2414
+ }).finally(() => {
2415
+ journalPending.delete(settled);
2416
+ journalInFlight = null;
2417
+ flushJournal();
2418
+ });
2419
+ journalInFlight = settled;
2374
2420
  journalPending.add(settled);
2375
2421
  }
2376
2422
  // The journal's own work, such as a heartbeat, ends with the agent: once,
@@ -2382,6 +2428,8 @@ export async function createFxEngine(options = {}) {
2382
2428
  }
2383
2429
  async function journalSettled() {
2384
2430
  for (;;) {
2431
+ // This caller waits for every event queued so far.
2432
+ if (journalQueue.length > 0) journalBarrier = true;
2385
2433
  if (journalFlushScheduled || journalQueue.length > 0) flushJournal();
2386
2434
  if (journalPending.size === 0) break;
2387
2435
  await Promise.all([...journalPending]);
@@ -2652,7 +2700,7 @@ export async function createFxEngine(options = {}) {
2652
2700
  emit("acp.receive", { message });
2653
2701
  if (message.method === "libfx/journal_append") {
2654
2702
  if (journal && message.params?.sessionId === sessionId) {
2655
- queueJournalEvents(message.params.events);
2703
+ queueJournalEvents(message.params.events, message.params.barrier === true);
2656
2704
  }
2657
2705
  return;
2658
2706
  }
@@ -2724,7 +2772,10 @@ export async function createFxEngine(options = {}) {
2724
2772
  sessionId = sessionResult.sessionId;
2725
2773
  if (initialCheckpoint) {
2726
2774
  const [checkpointAttachment] = attachBytes([initialCheckpoint]);
2727
- const restored = await request("libfx/restore", { sessionId, checkpointAttachment });
2775
+ const restored = await request("libfx/restore", { sessionId, checkpointAttachment }).catch((error) => {
2776
+ if (/newer fx/.test(error?.message ?? "")) throw new FxJournalVersionError(error.message);
2777
+ throw error;
2778
+ });
2728
2779
  compareCheckpointMeta(restored?.checkpointMeta);
2729
2780
  }
2730
2781
  if (journal) {
@@ -2816,7 +2867,7 @@ export async function createFxEngine(options = {}) {
2816
2867
  if (turnId !== undefined && journal) {
2817
2868
  if (resumable && turnId === openTurnId) {
2818
2869
  resumable = false;
2819
- return normalizeTurn(startTurn(null, { ...promptOptions, [resumeTurn]: true, [rerunCallIds]: rerunIds(promptOptions.onAmbiguous) }));
2870
+ return resumeOpenTurn(promptOptions);
2820
2871
  }
2821
2872
  if (turnId === lastTurnId) return endedTurn(turnId);
2822
2873
  }
@@ -2840,7 +2891,7 @@ export async function createFxEngine(options = {}) {
2840
2891
  checkOnAmbiguous(promptOptions.onAmbiguous);
2841
2892
  if (resumable) {
2842
2893
  resumable = false;
2843
- return normalizeTurn(startTurn(null, { ...promptOptions, [resumeTurn]: true, [rerunCallIds]: rerunIds(promptOptions.onAmbiguous) }));
2894
+ return resumeOpenTurn(promptOptions);
2844
2895
  }
2845
2896
  // With no open turn, the follow-ups the journal held are the work left.
2846
2897
  const next = followUps.find((entry) => entry.held);
@@ -2944,7 +2995,9 @@ export async function createFxEngine(options = {}) {
2944
2995
  };
2945
2996
  return agent;
2946
2997
 
2947
- function normalizeTurn(rawTurn) {
2998
+ // `answered`: calls a resumed turn answers as possibly run before it goes
2999
+ // on, whose `tool_end` comes first.
3000
+ function normalizeTurn(rawTurn, answered = []) {
2948
3001
  const toolNames = new Map();
2949
3002
  const started = new Set();
2950
3003
  const eventFor = (update) => {
@@ -2999,6 +3052,9 @@ export async function createFxEngine(options = {}) {
2999
3052
  withdraw(id) { return rawTurn.withdraw(id); },
3000
3053
  [Symbol.asyncIterator]() {
3001
3054
  const iterator = (async function* () {
3055
+ for (const call of answered) {
3056
+ yield { type: "tool_end", id: call.id, name: call.name, content: unfinishedToolOutput, isError: true };
3057
+ }
3002
3058
  for await (const update of rawTurn) {
3003
3059
  const event = eventFor(update);
3004
3060
  if (event) yield event;
package/fx-term.wasm CHANGED
Binary file
Binary file
Binary file
Binary file
Binary file
package/mcp.js CHANGED
@@ -67,6 +67,9 @@ export async function createMcpAdapter(client, options = {}) {
67
67
  name,
68
68
  description: tool.description || "MCP tool",
69
69
  inputSchema: tool.inputSchema ?? { type: "object", properties: {} },
70
+ // The server's hints are not trusted: a call is never run twice on its
71
+ // own. A host that knows a tool is safe to repeat can set this to true.
72
+ idempotent: false,
70
73
  async execute(input, { signal }) {
71
74
  const result = await client.callTool({ name: tool.name, arguments: input }, undefined, { signal });
72
75
  const text = resultText(result);