libfx 0.0.14 → 0.0.15

package/node.cjs

@@ -225,14 +225,103 @@ function leaseEnd(backend, deadline) {
 }
 var recentIdsKept = 256;
 var maxBackstopSeconds = 300;
+var base64Letters = encoder.encode("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/");
 var toBase64 = (bytes) => {
-  let text = "";
-  for (let index = 0;index < bytes.length; index += 32768) {
-    text += String.fromCharCode(...bytes.subarray(index, index + 32768));
-  }
-  return btoa(text);
+  if (typeof bytes.toBase64 === "function")
+    return bytes.toBase64();
+  const letters = new Uint8Array(Math.ceil(bytes.length / 3) * 4);
+  const whole = bytes.length - bytes.length % 3;
+  let at = 0;
+  for (let index = 0;index < whole; index += 3) {
+    const group = bytes[index] << 16 | bytes[index + 1] << 8 | bytes[index + 2];
+    letters[at] = base64Letters[group >> 18];
+    letters[at + 1] = base64Letters[group >> 12 & 63];
+    letters[at + 2] = base64Letters[group >> 6 & 63];
+    letters[at + 3] = base64Letters[group & 63];
+    at += 4;
+  }
+  if (whole < bytes.length) {
+    const two = whole + 1 < bytes.length;
+    const group = bytes[whole] << 16 | (two ? bytes[whole + 1] << 8 : 0);
+    letters[at] = base64Letters[group >> 18];
+    letters[at + 1] = base64Letters[group >> 12 & 63];
+    letters[at + 2] = two ? base64Letters[group >> 6 & 63] : 61;
+    letters[at + 3] = 61;
+  }
+  return decoder.decode(letters);
 };
-var fromBase64 = (text) => Uint8Array.from(atob(text), (char) => char.charCodeAt(0));
+var fromBase64 = (text) => {
+  if (typeof Uint8Array.fromBase64 === "function")
+    return Uint8Array.fromBase64(text);
+  const binary = atob(text);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0;index < binary.length; index += 1)
+    bytes[index] = binary.charCodeAt(index);
+  return bytes;
+};
+async function imageName(bytes) {
+  const digest = new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", bytes));
+  let name = "";
+  for (const byte of digest)
+    name += byte.toString(16).padStart(2, "0");
+  return name;
+}
+var base64url = (text) => toBase64(encoder.encode(text)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+var persistenceImages = Symbol.for("libfx.persistenceImages");
+var byteView = (value) => value instanceof ArrayBuffer ? new Uint8Array(value) : ArrayBuffer.isView(value) ? new Uint8Array(value.buffer, value.byteOffset, value.byteLength) : null;
+function promptInputForLog(input, { named = false } = {}) {
+  let images = false;
+  const blocks = [];
+  for (let index = 0;index < input.length; index += 1) {
+    const block = input[index];
+    if (block?.type !== "image") {
+      blocks.push(block);
+      continue;
+    }
+    const image = { ...block };
+    if (image.data !== undefined && typeof image.data !== "string")
+      throw new TypeError("a durable prompt carries image data as a base64 string");
+    if (typeof image.data === "string")
+      images = named;
+    blocks.push(image);
+  }
+  return { input: blocks, images };
+}
+async function storePromptImages(images, input) {
+  const blocks = [];
+  for (const block of input) {
+    if (block?.type !== "image" || block.data === undefined) {
+      blocks.push(block);
+      continue;
+    }
+    const { data, ...rest } = block;
+    const bytes = fromBase64(data);
+    const sha256 = await imageName(bytes);
+    if (images)
+      await images.put(sha256, bytes);
+    blocks.push({ ...rest, data: { sha256 } });
+  }
+  return blocks;
+}
+async function resolvePromptImages(images, input) {
+  if (!Array.isArray(input))
+    return { input };
+  const blocks = [];
+  for (const block of input) {
+    const name = block?.type === "image" ? block.data?.sha256 : undefined;
+    if (typeof name !== "string") {
+      blocks.push(block);
+      continue;
+    }
+    const bytes = await images.get(name);
+    if (!bytes)
+      return { missing: name };
+    if (await imageName(bytes) !== name)
+      return { missing: name, corrupt: true };
+    blocks.push({ ...block, data: toBase64(bytes) });
+  }
+  return { input: blocks };
+}
 function memory({ maxDurationMs, reserveMs } = {}) {
   checkDurations("memory", { maxDurationMs, reserveMs });
   let backend = null;
@@ -519,7 +608,7 @@ function createMemoryBackend({ maxDurationMs, reserveMs } = {}) {
   const sessionFor = (id) => {
     let session = sessions.get(id);
     if (!session) {
-      session = { entries: [], head: null, ui: [], uiWaiters: new Set, watchers: new Set };
+      session = { entries: [], head: null, ui: [], uiWaiters: new Set, watchers: new Set, images: new Map };
       sessions.set(id, session);
     }
     return session;
@@ -605,6 +694,15 @@ function createMemoryBackend({ maxDurationMs, reserveMs } = {}) {
           session.watchers.add(fn);
           return () => session.watchers.delete(fn);
         },
+        images: {
+          async put(name, bytes) {
+            if (!session.images.has(name))
+              session.images.set(name, bytes.slice());
+          },
+          async get(name) {
+            return session.images.get(name)?.slice();
+          }
+        },
         ui: {
           async write(lines) {
             session.ui.push(...lines);
@@ -660,6 +758,7 @@ function createMemoryBackend({ maxDurationMs, reserveMs } = {}) {
 }
 var logStep = "fx.log";
 var uiStreamOf = (runId) => `${runId.replace(/^wrun_/, "strm_")}_user_bGliZngtdWk`;
+var imageStreamOf = (runId, name) => `${runId.replace(/^wrun_/, "strm_")}_user_${base64url(`libfx-image-${name}`)}`;
 var queuePrefix = "__libfx_wkf_workflow_";
 var defaultAgentName = "default";
 var agentNameRule = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
@@ -705,6 +804,31 @@ var missingRun = (error) => error?.status === 404 || /not found|does not exist|E
 var streamReadRetries = 5;
 var missingStreamPollMs = 50;
 var missingStreamFastMs = 2000;
+var maxLogViews = 32;
+var maxLogViewChars = 32 * 1024 * 1024;
+var gapless = (read) => read.listed === 0 || read.newest - read.lowest + 1 === read.listed;
+var firstEventSlot = 1;
+var listedDownTo = (read, floor) => read.lowest === floor || read.through !== null && read.lowest <= read.through;
+function extendLogView(view, newer) {
+  const combined = [...view.entries, ...newer];
+  let through = view.through;
+  for (let index = combined.length - 1;index >= 0; index -= 1) {
+    const entry = combined[index].entry;
+    if (entry?.k === "checkpoint") {
+      through = entry.through === null || entry.through === undefined ? 0 : Number(entry.through);
+      break;
+    }
+  }
+  if (through < view.through)
+    return null;
+  const entries = combined.filter((item) => Number(item.cursor) > through);
+  let head = null;
+  for (let index = entries.length - 1;index >= 0 && head === null; index -= 1) {
+    if (chainedKind(entries[index].entry?.k))
+      head = entries[index].cursor;
+  }
+  return { entries, through, head: head ?? (through ? String(through) : "null") };
+}
 var firstPageEvents = 10;
 var laterPageEvents = 100;
 var listenersOf = new WeakMap;
@@ -804,6 +928,32 @@ function createWorldBackend(world, durability) {
     for (const watcher of watchers.get(runId) ?? [])
       watcher();
   };
+  const logViews = new Map;
+  let logViewChars = 0;
+  const forgetView = (runId) => {
+    const view = logViews.get(runId);
+    if (!view)
+      return;
+    logViewChars -= view.text.length;
+    logViews.delete(runId);
+  };
+  const rememberView = (runId, entries, known, through) => {
+    forgetView(runId);
+    const text = JSON.stringify(entries);
+    if (text.length > maxLogViewChars)
+      return;
+    logViews.set(runId, { text, known, through });
+    logViewChars += text.length;
+    for (const oldest of logViews.keys()) {
+      if (logViews.size <= maxLogViews && logViewChars <= maxLogViewChars)
+        break;
+      forgetView(oldest);
+    }
+  };
+  const viewOf = (runId) => {
+    const view = logViews.get(runId);
+    return view && { entries: JSON.parse(view.text), known: view.known, through: view.through };
+  };
   let handler = null;
   const route = typeof world.registerHandler !== "function";
   const listEvents = (runId, cursor, limit) => world.events.list({
@@ -885,6 +1035,7 @@ function createWorldBackend(world, durability) {
     },
     async session(runId) {
       let known = 0;
+      const storedImages = new Set;
       const inBandAt = new Map;
       let inBand = world.capabilities?.inBandFence === true;
       const noteInBand = (cursor, count) => {
@@ -935,9 +1086,12 @@ function createWorldBackend(world, durability) {
         let through = null;
         let snapshot;
         let newestChained;
+        let newest = stopBelow;
+        let lowest = Infinity;
+        let listed = 0;
         const done = (head) => {
           noteSnapshot(snapshot, newestChained ?? head);
-          return { events, through };
+          return { events, through, snapshot, newest, lowest, listed };
         };
         for (let cursor, limit = firstPageEvents;; limit = laterPageEvents) {
           let page;
@@ -948,7 +1102,7 @@ function createWorldBackend(world, durability) {
               throw error;
             if (stopBelow === 0)
               noteSnapshot({ seq: 0, seqInBand: inBandAtRunCreation }, "null");
-            return { events, through };
+            return { events, through, newest, lowest, listed, missing: true };
           }
           snapshot ??= page.snapshot;
           for (const event of page.data) {
@@ -957,6 +1111,11 @@ function createWorldBackend(world, durability) {
               known = slot;
             if (slot <= stopBelow)
               return done(undefined);
+            if (slot > newest)
+              newest = slot;
+            if (slot < lowest)
+              lowest = slot;
+            listed += 1;
             if (through !== null && slot <= through)
               return done(through === 0 ? "null" : String(through));
             const entry = logEntryOf(event);
@@ -975,10 +1134,41 @@ function createWorldBackend(world, durability) {
           cursor = page.cursor;
         }
       };
+      let covered = null;
+      const fullRead = async () => {
+        const read = await newestFirst(0, true);
+        const entries = read.events.reverse();
+        if (!read.missing && listedDownTo(read, firstEventSlot) && gapless(read)) {
+          rememberView(runId, entries, read.newest, read.through ?? 0);
+          covered = read.newest;
+        } else {
+          forgetView(runId);
+          covered = null;
+        }
+        return entries;
+      };
       return {
+        newest: () => covered,
         async read() {
-          const { events } = await newestFirst(0, true);
-          return events.reverse();
+          const view = viewOf(runId);
+          if (!view)
+            return fullRead();
+          if (view.known > known)
+            known = view.known;
+          const since = await newestFirst(view.known, true);
+          if (since.missing) {
+            forgetView(runId);
+            covered = null;
+            return [];
+          }
+          const reaches = since.listed === 0 || listedDownTo(since, view.known + 1);
+          const next = reaches && gapless(since) ? extendLogView(view, since.events.reverse()) : null;
+          if (!next)
+            return fullRead();
+          noteSnapshot(since.snapshot, next.head);
+          rememberView(runId, next.entries, since.newest, next.through);
+          covered = since.newest;
+          return next.entries;
         },
         async readSince(cursor) {
           const { events } = await newestFirst(Number(cursor), false);
@@ -1055,6 +1245,44 @@ function createWorldBackend(world, durability) {
           set.add(fn);
           return () => set.delete(fn);
         },
+        images: {
+          async put(name, bytes) {
+            if (storedImages.has(name))
+              return;
+            if (typeof world.streams.getChunks !== "function")
+              throw new TypeError("a World needs streams.getChunks() to keep a session's images");
+            await ensureRun();
+            const stream = imageStreamOf(runId, name);
+            let present = false;
+            try {
+              present = Number((await world.streams.getInfo(runId, stream))?.tailIndex ?? -1) >= 0;
+            } catch (error) {
+              if (!missingRun(error))
+                throw error;
+            }
+            if (!present)
+              await world.streams.write(runId, stream, bytes);
+            storedImages.add(name);
+          },
+          async get(name) {
+            let page;
+            try {
+              page = await world.streams.getChunks(runId, imageStreamOf(runId, name), { limit: 8 });
+            } catch (error) {
+              if (missingRun(error))
+                return;
+              throw error;
+            }
+            for (const chunk of page?.data ?? []) {
+              const bytes = byteView(chunk?.data);
+              if (bytes && bytes.byteLength > 0 && await imageName(bytes) === name) {
+                storedImages.add(name);
+                return bytes.slice();
+              }
+            }
+            return;
+          }
+        },
         ui: {
           async write(lines) {
             await ensureRun();
@@ -1253,9 +1481,19 @@ async function recordMessage(log, state, message) {
   if (idInUse(state, message))
     throw messageIdInUse(message);
   const entries = messageEntries(state, message);
+  const appended = [];
   for (const entry of entries)
-    await log.append(entry);
-  return entries.length;
+    appended.push({ cursor: await log.append(entry), entry });
+  return appended;
+}
+function handoffEntries(read, newestSeen, appended) {
+  if (!Number.isSafeInteger(newestSeen) || appended.length === 0)
+    return null;
+  for (const [index, item] of appended.entries()) {
+    if (Number(item.cursor) !== newestSeen + index + 1)
+      return null;
+  }
+  return [...read, ...appended.map(({ cursor, entry }) => ({ cursor, entry: JSON.parse(JSON.stringify(entry)) }))];
 }
 function earlyStart(entries, state, message, fold) {
   const writes = messageEntries(state, message);
@@ -1301,9 +1539,9 @@ class SessionWorker {
   fold(entries, delivery = null) {
     return foldSessionLog(entries, { now: Date.now(), alive: (lease) => this.backend.alive(lease, delivery) });
   }
-  async consume(message, delivery = null) {
-    const log = await this.backend.session(this.sessionId);
-    let entries = await log.read();
+  async consume(message, delivery = null, handoff = null) {
+    const log = handoff?.log ?? await this.backend.session(this.sessionId);
+    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" });
@@ -1467,6 +1705,7 @@ class SessionWorker {
     }
     const ui = uiWriter(log, (error) => agent.emit("ui.error", { sessionId: this.sessionId, error: error?.name ?? "Error" }), lease.epoch);
     let leaseExpiresAt = lease.expiresAt;
+    let imageReadFailed = null;
     const store = {
       load: async () => ({
         ...state.checkpoint?.data ? { checkpoint: { through: state.checkpoint.through ?? "0", data: fromBase64(state.checkpoint.data) } } : {},
@@ -1474,6 +1713,17 @@ class SessionWorker {
         head: head ?? state.head
       }),
       append: ({ idempotencyKey, data, marks }) => chained({ k: "record", key: idempotencyKey, data: toBase64(data), marks }).then((cursor) => ({ cursor })),
+      [persistenceImages]: {
+        put: (name, bytes) => log.images.put(name, bytes),
+        get: async (name) => {
+          try {
+            return await log.images.get(name);
+          } catch (error) {
+            imageReadFailed = error;
+            throw error;
+          }
+        }
+      },
       saveCheckpoint: async ({ through, data }) => {
         const now = this.fold(await log.read());
         const kept = [...now.unconsumed, ...now.held].filter((input) => input.cursor <= Number(through)).sort((a, b) => a.cursor - b.cursor);
@@ -1545,6 +1795,8 @@ class SessionWorker {
         harnessRun = runOf(state.openTurn ?? state.pending[0]);
         harness = await agent.openHarness(this.sessionId, store, harnessRun, ready);
       } catch (error) {
+        if (imageReadFailed)
+          throw imageReadFailed;
         const waiting = state.openTurn && !state.openFailed ? state.openTurn.id : state.pending[0]?.messageId;
         if (waiting) {
           const summary = errorSummary(error);
@@ -1607,8 +1859,17 @@ class SessionWorker {
             harness = await agent.openHarness(this.sessionId, store, wanted, ready);
             harnessRun = wanted;
           }
+          const withImages = await resolvePromptImages(log.images, next.input);
+          if (withImages.missing) {
+            await log.append({ k: "ended", messageId });
+            const message = withImages.corrupt ? `the session's image store holds other bytes under image ${withImages.missing}` : `the session's image store does not hold image ${withImages.missing}`;
+            ui.push({ type: "turn_end", messageId, stopReason: "error", usage: {}, error: { name: "Error", message } });
+            await ui.settle();
+            state = this.fold(await log.read());
+            continue;
+          }
           try {
-            turn = harness.prompt(next.input ?? "", { turnId: messageId, yieldAt });
+            turn = harness.prompt(withImages.input ?? "", { turnId: messageId, yieldAt });
           } catch (error) {
             await log.append({ k: "stopped", messageId });
             return unusable(error);
@@ -2114,14 +2375,14 @@ function createDurableAgentFactory({ harness, defaultDurability, defaultShared =
     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);
-    const receive = (created, message, delivery, { inRequest = false } = {}) => {
+    const receive = (created, message, delivery, { inRequest = false, handoff = null } = {}) => {
       let worker = workers.get(message.sessionId);
       if (!worker) {
         worker = new SessionWorker(agent, created, message.sessionId);
         workers.set(message.sessionId, worker);
       }
       worker.deliveries += 1;
-      let work = worker.consume(message, delivery);
+      let work = worker.consume(message, delivery, handoff);
       if (inRequest) {
         work = work.then(async (result) => {
           if (Number.isFinite(result?.timeoutSeconds)) {
@@ -2178,7 +2439,9 @@ function createDurableAgentFactory({ harness, defaultDurability, defaultShared =
         };
         const full = { ...message, ...extra, agent: agentName, sessionId };
         const log = await created.session(sessionId);
-        await recordMessage(log, foldSessionLog(await log.read()), full);
+        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) {
@@ -2189,7 +2452,9 @@ function createDurableAgentFactory({ harness, defaultDurability, defaultShared =
             const { messageId: backstop } = await created.queue.send(queued, { idempotencyKey, delaySeconds }) ?? {};
             seeded = true;
             const delivery = backstop ? { messageId: backstop, attempt: 0 } : null;
-            const work = receive(created, queued, delivery, { inRequest: true }).then(() => {}, () => {});
+            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;
           }
@@ -2197,7 +2462,8 @@ function createDurableAgentFactory({ harness, defaultDurability, defaultShared =
         await created.queue.send(queued, { idempotencyKey });
         seeded = true;
       };
-      const startTurn = (type, messageId, input, retried = false, aborted = false) => {
+      let storing = null;
+      const startTurn = (type, messageId, input, retried = false, aborted = () => false, ready = null, progress = null) => {
         let accept;
         const accepted = new Promise((resolve, reject) => {
           accept = { resolve, reject };
@@ -2208,15 +2474,23 @@ function createDurableAgentFactory({ harness, defaultDurability, defaultShared =
           resumeRequest: type === "resume" ? messageId : null,
           start: async () => {
             try {
+              const read = input === undefined || ready === null || aborted() ? input : await ready();
+              const message = { type, messageId, ...input === undefined ? {} : { input: read } };
+              const queue = () => {
+                if (progress)
+                  progress.sent = true;
+                return send(message, { inRequest: type === "prompt" });
+              };
               const { created, id: sessionId } = await resolved;
               const log = await created.session(sessionId);
               let attaching = type === "resume";
               let from = null;
-              if (retried && !aborted) {
+              if (retried)
                 from = await log.ui.length();
+              if (retried && !aborted()) {
                 const [state] = await Promise.all([
                   log.read().then(foldSessionLog),
-                  send({ type, messageId, ...input === undefined ? {} : { input } }, { inRequest: type === "prompt" }).then(() => accept.resolve({ messageId, sessionId }))
+                  queue().then(() => accept.resolve({ messageId, sessionId }))
                 ]);
                 const outcome = await retryOutcome(log, state, messageId, from, { sent: true });
                 if (outcome.settled)
@@ -2226,7 +2500,6 @@ function createDurableAgentFactory({ harness, defaultDurability, defaultShared =
                 return { log, from, attaching: outcome.follow === true };
               }
               if (retried) {
-                from = await log.ui.length();
                 const outcome = await retryOutcome(log, foldSessionLog(await log.read()), messageId, from, { sent: false });
                 if (outcome.follow)
                   attaching = true;
@@ -2237,12 +2510,14 @@ function createDurableAgentFactory({ harness, defaultDurability, defaultShared =
                   return { log, from, attaching: true, endWithinMs: retryEndWaitMs };
                 }
               }
-              if (aborted && !attaching) {
+              from ??= await log.ui.length();
+              if (aborted()) {
                 accept.resolve({ messageId, sessionId });
-                return { settled: { messageId, stopReason: "cancelled", usage: {} } };
+                if (!attaching)
+                  return { settled: { messageId, stopReason: "cancelled", usage: {} } };
+                return { log, from, attaching };
               }
-              from ??= await log.ui.length();
-              await send({ type, messageId, ...input === undefined ? {} : { input } }, { inRequest: type === "prompt" });
+              await queue();
               accept.resolve({ messageId, sessionId });
               return { log, from, attaching };
             } catch (error) {
@@ -2265,17 +2540,64 @@ function createDurableAgentFactory({ harness, defaultDurability, defaultShared =
             throw new TypeError(`messageId must be ${idRule}`);
           if (typeof input !== "string" && !Array.isArray(input))
             throw new TypeError("prompt input must be a string or an array of content blocks");
-          if (Array.isArray(input) && input.some((block) => block?.type === "image" && block.data !== undefined && typeof block.data !== "string")) {
-            throw new TypeError("a durable prompt carries image data as a base64 string");
-          }
-          admit(input);
           const signal = promptOptions.signal;
           if (signal !== undefined && typeof signal?.addEventListener !== "function")
             throw new TypeError("prompt signal must be an AbortSignal");
-          const turn = startTurn("prompt", messageId, input, promptOptions.messageId !== undefined, signal?.aborted === true);
+          const aborted = signal?.aborted === true;
+          const retried = promptOptions.messageId !== undefined;
+          const named = !aborted;
+          const stored = Array.isArray(input) ? promptInputForLog(input, { named }) : { input, images: false };
+          admit(stored.input);
+          plugged.checkPrompt?.(stored.input);
+          const before = storing;
+          const ready = before || stored.images ? async () => {
+            let release = () => {};
+            const abortion = signal === undefined ? null : new Promise((resolve) => {
+              signal.addEventListener("abort", resolve, { once: true });
+              release = () => signal.removeEventListener("abort", resolve);
+            });
+            const unlessAborted = (promise) => {
+              if (abortion === null)
+                return promise;
+              promise.catch(() => {});
+              return Promise.race([promise, abortion]);
+            };
+            try {
+              await unlessAborted(before ?? Promise.resolve());
+              if (signal?.aborted)
+                return null;
+              let read = stored.input;
+              if (stored.images) {
+                const { created, id: sessionId } = await resolved;
+                const log = await created.session(sessionId);
+                const known = retried && knownMessage(foldSessionLog(await log.read()), { type: "prompt", messageId });
+                if (signal?.aborted)
+                  return null;
+                read = await unlessAborted(storePromptImages(known ? null : log.images, read));
+                if (signal?.aborted)
+                  return null;
+              }
+              if (closed)
+                throw new Error(`${label} is closed`);
+              return read;
+            } finally {
+              release();
+            }
+          } : null;
+          const progress = { sent: false };
+          const turn = startTurn("prompt", messageId, stored.input, retried, () => signal?.aborted === true, ready, progress);
+          if (stored.images && !aborted) {
+            const settled = Promise.all([before, turn.accepted.then(() => {}, () => {})]).then(() => {});
+            storing = settled;
+            settled.then(() => {
+              if (storing === settled)
+                storing = null;
+            });
+          }
           if (signal !== undefined && !signal.aborted) {
             const stop = () => {
-              send({ type: "cancel", messageId: newId("cnl"), target: messageId }).catch(() => {});
+              if (progress.sent)
+                send({ type: "cancel", messageId: newId("cnl"), target: messageId }).catch(() => {});
             };
             signal.addEventListener("abort", stop, { once: true });
             turn.result.finally(() => signal.removeEventListener("abort", stop)).catch(() => {});
@@ -2373,7 +2695,14 @@ function createDurableAgentFactory({ harness, defaultDurability, defaultShared =
           if (!validId(messageId))
             throw new TypeError(`messageId must be ${idRule}`);
           admit(input);
-          await send({ type: "steer", messageId, input });
+          let named = input;
+          if (Array.isArray(input) && input.some((block) => block?.type === "image" && typeof block.data === "string")) {
+            const { created, id: sessionId } = await resolved;
+            named = await storePromptImages((await created.session(sessionId)).images, input);
+            if (closed)
+              throw new Error(`${label} is closed`);
+          }
+          await send({ type: "steer", messageId, input: named });
           return { messageId };
         },
         async cancel() {
@@ -2391,6 +2720,12 @@ function createDurableAgentFactory({ harness, defaultDurability, defaultShared =
             }),
             append: async () => {
               throw new Error("a checkpoint reads the session without changing it");
+            },
+            [persistenceImages]: {
+              get: (name) => log.images.get(name),
+              put: async () => {
+                throw new Error("a checkpoint reads the session without changing it");
+              }
             }
           };
           const harness = await agent.openHarness(sessionId, readOnly, null);
@@ -3102,6 +3437,7 @@ var maxPromptImagesDataBytes = 8 * 1024 * 1024;
 var maxPromptImageBytes = maxPromptImageDataBytes / 4 * 3;
 var maxPromptImagesBytes = maxPromptImagesDataBytes / 4 * 3;
 var maxPendingAttachments = 8;
+var maxPendingAttachmentBytes = 8 * 1024 * 1024;
 var maxOutboundAttachments = 4;
 var maxCheckpointBytes = 4 * 1024 * 1024;
 var maxJournalBytes = 4 * 1024 * 1024;
@@ -3249,6 +3585,9 @@ function normalizeAgentOptions(value) {
   Object.assign(options, normalizeModelChoice(options));
   if (custom && options.model === undefined)
     throw new TypeError("a custom provider needs a model");
+  if (subscription && options.model === undefined) {
+    throw new TypeError(`provider "${options.provider}" needs a model; fx's default model is an AI Gateway id`);
+  }
   validateGatewayChatUrl(options.gatewayChatUrl);
   if (options.resizeImage !== undefined && typeof options.resizeImage !== "function") {
     throw new TypeError("resizeImage must be a function");
@@ -3278,6 +3617,8 @@ function normalizeAgentOptions(value) {
 }
 var engineInternals = Symbol.for("libfx.engineInternals");
 var journalMarksWanted = Symbol.for("libfx.journalMarks");
+var persistenceImages2 = Symbol.for("libfx.persistenceImages");
+var imageWindowLimits = Symbol.for("libfx.imageWindow");
 var coreAnswered = Symbol.for("libfx.coreAnswered");
 
 class FxFencedError extends Error {
@@ -3304,8 +3645,23 @@ var journalOpenErrorCodes = new Map([
   ["Invalid libfx journal", "FX_JOURNAL_INVALID"],
   ["libfx journal events are out of order", "FX_JOURNAL_INVALID"],
   ["libfx journal is too large", "FX_JOURNAL_TOO_LARGE"],
-  ["libfx journal holds more than 1024 turns", "FX_JOURNAL_TOO_LARGE"]
+  ["libfx journal holds more than 1024 turns", "FX_JOURNAL_TOO_LARGE"],
+  ["libfx journal images are too large", "FX_JOURNAL_TOO_LARGE"],
+  ["Invalid libfx journal images", "FX_JOURNAL_INVALID"],
+  ["libfx image does not match its name", "FX_JOURNAL_IMAGE_MISSING"]
 ]);
+async function imageName2(bytes) {
+  const digest = new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", bytes));
+  let name = "";
+  for (const byte of digest)
+    name += byte.toString(16).padStart(2, "0");
+  return name;
+}
+function imageMissingError(name, cause) {
+  const error = journalLoadError(`libfx journal names an image the store does not hold: ${name}`, "FX_JOURNAL_IMAGE_MISSING", cause);
+  error.image = name;
+  return error;
+}
 function createMemoryPersistence() {
   const records = [];
   let checkpoint = null;
@@ -3341,6 +3697,7 @@ function createMemoryPersistence() {
 var resumeTurn = Symbol("libfx.resume");
 var followUpInput = Symbol("libfx.followUp");
 var rerunCallIds = Symbol("libfx.rerun");
+var resumeOutputShown = Symbol.for("libfx.resumeOutputShown");
 function journalAppendError(cause) {
   const error = new Error("libfx journal append failed", { cause });
   error.code = "FX_JOURNAL_APPEND_FAILED";
@@ -3466,6 +3823,7 @@ async function loadPersistence(persistence) {
   }
   return { checkpoint, events, head, tailBytes: bytes, lastSeq: events.at(-1)?.seq ?? covered };
 }
+var waitedForEvents = new Set(["input_accepted", "input_withdrawn", "turn_committed", "turn_progress_cleared", "turn_yielded"]);
 function journalMarks(events) {
   const marks = [];
   for (const event of events) {
@@ -5027,7 +5385,7 @@ function promptImageDataBytes(prompt) {
     return total + Math.ceil(byteLength / 3) * 4;
   }, 0);
 }
-function byteView(value) {
+function byteView2(value) {
   if (value instanceof ArrayBuffer)
     return new Uint8Array(value);
   if (ArrayBuffer.isView(value))
@@ -5088,7 +5446,7 @@ function normalizePromptImage(block, index) {
       throw new TypeError(`image prompt block ${index} requires canonical base64 data`);
     return { type: "image", source: "base64", data: block.data, mimeType: block.mimeType, byteLength, ...reference };
   }
-  const bytes = typeof block.data === "string" ? null : byteView(block.data);
+  const bytes = typeof block.data === "string" ? null : byteView2(block.data);
   if (!bytes || bytes.byteLength === 0) {
     throw new TypeError(`image prompt block ${index} requires base64 data, bytes, or a Blob`);
   }
@@ -5146,6 +5504,52 @@ function normalizePromptInput(input, { deferImageLimits = false } = {}) {
   }
   return prompt;
 }
+var imageSignatures = [
+  ["image/png", 0, [137, 80, 78, 71, 13, 10, 26, 10]],
+  ["image/jpeg", 0, [255, 216, 255]],
+  ["image/gif", 0, [71, 73, 70, 56, 55, 97]],
+  ["image/gif", 0, [71, 73, 70, 56, 57, 97]],
+  ["image/webp", 0, [82, 73, 70, 70]]
+];
+var imageTypes = new Set(imageSignatures.map(([type]) => type));
+var webpMarker = [87, 69, 66, 80];
+function imageTypeOf(bytes) {
+  const startsWith = (offset, signature) => bytes.length >= offset + signature.length && signature.every((byte, index) => bytes[offset + index] === byte);
+  for (const [type, offset, signature] of imageSignatures) {
+    if (!startsWith(offset, signature))
+      continue;
+    if (type === "image/webp" && !startsWith(8, webpMarker))
+      continue;
+    return type;
+  }
+  return null;
+}
+function checkImageBytesType(bytes, mimeType, index) {
+  const type = imageTypeOf(bytes);
+  if (type === null)
+    throw new TypeError(`image prompt block ${index} is not a PNG, JPEG, GIF or WebP image`);
+  if (type !== mimeType)
+    throw new TypeError(`image prompt block ${index} holds ${type} data, not ${mimeType}`);
+}
+function checkPromptInput(input, { resizeImage } = {}) {
+  const resized = resizeImage !== undefined;
+  const normalized = normalizePromptInput(input, { deferImageLimits: resized });
+  if (!normalized.some((block) => block.type === "image" || block.type === "text" && block.text.length > 0)) {
+    throw new TypeError("prompt is empty");
+  }
+  checkPromptFrameSize(normalized, !resized);
+  normalized.forEach((block, index) => {
+    if (block.type !== "image" || resized && block.data !== undefined)
+      return;
+    if (!imageTypes.has(block.mimeType))
+      throw new TypeError(`image prompt block ${index} mimeType must be image/png, image/jpeg, image/gif or image/webp`);
+    if (block.source === "bytes")
+      checkImageBytesType(block.data, block.mimeType, index);
+    else if (block.source === "base64")
+      checkImageBytesType(base64ToBytes(block.data.slice(0, 16)), block.mimeType, index);
+  });
+  return normalized;
+}
 function promptFrameSize(prompt, countImages = true) {
   const encodedImageBytes = countImages ? promptImageDataBytes(prompt) : 0;
   const projected = prompt.map((block) => block.type !== "image" ? block : {
@@ -5170,7 +5574,7 @@ function preparePromptImages(blocks) {
   });
 }
 function resizedPromptImage(value, index) {
-  const bytes = byteView(value?.bytes);
+  const bytes = byteView2(value?.bytes);
   if (!bytes || bytes.byteLength === 0 || typeof value.mimeType !== "string" || value.mimeType.length === 0 || value.mimeType.length > 128) {
     throw new TypeError(`resizeImage must return non-empty bytes and a mimeType for image prompt block ${index}`);
   }
@@ -5217,6 +5621,10 @@ async function materializePromptImages(blocks, isCancelled, resizeImage) {
   if (promptFrameSize(prepared) > maxPromptFrameBytes)
     prepared = omitReferencedImageData(prepared);
   checkPromptFrameSize(prepared, true);
+  prepared.forEach((image, index) => {
+    if (image.type === "image" && image.bytes !== undefined)
+      checkImageBytesType(image.bytes, image.mimeType, index);
+  });
   return prepared;
 }
 function normalizeSteeringInput(input) {
@@ -5257,8 +5665,6 @@ function normalizeHostTools(value) {
   } else {
     throw new TypeError("tools must be an array or an object");
   }
-  if (entries.length > 64)
-    throw new RangeError("tools cannot contain more than 64 entries");
   const descriptors = [];
   const executors = new Map;
   const names = new Set;
@@ -5351,7 +5757,7 @@ function normalizeInstructions(value) {
   }
   return instructions;
 }
-function hostToolContent(value) {
+function hostToolContent(value, stored = null) {
   if (value?.type === "libfx.tool-result") {
     if (typeof value.text !== "string" || !Array.isArray(value.images) || value.images.length > 8) {
       throw new TypeError("invalid typed tool result");
@@ -5364,11 +5770,13 @@ function hostToolContent(value) {
       if (!referenceOnly && typeof image.data !== "string" || typeof image.mimeType !== "string" || image.mimeType.length === 0 || image.mimeType.length > 128 || image.data?.length > maxPromptImageDataBytes && sourceRef === undefined) {
         throw new TypeError("invalid tool image");
       }
+      const data = !referenceOnly && image.data.length <= maxPromptImageDataBytes ? image.data : undefined;
       return {
         type: "image",
-        ...!referenceOnly && image.data.length <= maxPromptImageDataBytes ? { data: image.data } : {},
+        ...data === undefined ? {} : { data },
         mimeType: image.mimeType,
-        ...sourceRef === undefined ? {} : { sourceRef }
+        ...sourceRef === undefined ? {} : { sourceRef },
+        ...data !== undefined && stored?.has(data) ? { stored: stored.get(data) } : {}
       };
     });
     if (promptImageDataBytes(images) > maxPromptImagesDataBytes)
@@ -5382,7 +5790,7 @@ function hostToolContent(value) {
     }
     if (encoder4.encode(content).length > maxPromptImagesDataBytes)
       throw new RangeError("typed tool result exceeds the result limit");
-    return { content, rich: true, isError: value.isError === true };
+    return { content, rich: true, isError: value.isError === true, images };
   }
   if (typeof value === "string")
     return { content: value, rich: false };
@@ -5483,6 +5891,8 @@ async function createFxEngine(options = {}) {
   let coreExitError = null;
   const isCurrentTurn = (turn) => turn && activeTurn === turn && !turn.cancelled && !closing;
   const persistence = options.persistence ?? null;
+  const imageStorage = persistence?.[persistenceImages2] ?? null;
+  const imageStore = imageStorage !== null;
   const wantsMarks = persistence?.marks === true || persistence?.[journalMarksWanted] === true;
   const checkpointAfterBytes = options.checkpointAfterBytes ?? defaultCheckpointAfterBytes;
   let journalHead = null;
@@ -5593,7 +6003,7 @@ async function createFxEngine(options = {}) {
       return;
     }
     journalQueue.push(...events);
-    if (barrier || events.some((event) => event?.type === "input_accepted" || event?.type === "input_withdrawn"))
+    if (barrier || events.some((event) => waitedForEvents.has(event?.type)))
       journalBarrier = true;
     if (events.every((event) => event?.type === "session_config"))
       return;
@@ -5759,6 +6169,28 @@ async function createFxEngine(options = {}) {
     }
     throw new Error("transport retry exhausted");
   };
+  const storedToolContent = async (value) => {
+    const normalized = hostToolContent(value);
+    if (!imageStore || !normalized.images?.some((image) => image.data !== undefined))
+      return normalized;
+    const stored = new Map;
+    for (const image of normalized.images) {
+      if (image.data === undefined || stored.has(image.data))
+        continue;
+      let bytes;
+      try {
+        bytes = base64ToBytes(image.data);
+      } catch {
+        continue;
+      }
+      const name = await imageName2(bytes);
+      try {
+        await imageStorage.put(name, bytes);
+        stored.set(image.data, name);
+      } catch {}
+    }
+    return stored.size ? hostToolContent(value, stored) : normalized;
+  };
   const executeHostTool = async (name, input, requestedSessionId, toolCallId) => {
     const execute = hostTools.executors.get(name);
     const issuerSessionId = requestedSessionId ?? sessionId;
@@ -5792,7 +6224,7 @@ async function createFxEngine(options = {}) {
       });
       const value = await Promise.race([execution, aborted]);
       if (!controller.signal.aborted) {
-        const normalized = hostToolContent(value);
+        const normalized = await storedToolContent(value);
         content = normalized.content;
         rich = normalized.rich;
         isError = normalized.isError === true;
@@ -5801,7 +6233,7 @@ async function createFxEngine(options = {}) {
       isError = true;
       if (error?.toolResult?.type === "libfx.tool-result") {
         try {
-          const normalized = hostToolContent(error.toolResult);
+          const normalized = await storedToolContent(error.toolResult);
           content = normalized.content;
           rich = normalized.rich;
         } catch {
@@ -5891,10 +6323,27 @@ async function createFxEngine(options = {}) {
       throw new Error("fx returned an invalid checkpoint");
     return new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
   }
-  const sendPrompt = (blocks, resuming = false, followUp = null, turnId = null, rerun = [], yieldAt = undefined) => {
+  async function storePromptImages(blocks, stopped) {
+    const named = [];
+    for (const block of blocks) {
+      if (block.type !== "image" || block.bytes === undefined) {
+        named.push(block);
+        continue;
+      }
+      const name = await imageName2(block.bytes);
+      if (stopped())
+        return null;
+      await imageStorage.put(name, block.bytes);
+      if (stopped())
+        return null;
+      named.push({ ...block, stored: name });
+    }
+    return named;
+  }
+  const sendPrompt = (blocks, resuming = false, followUp = null, turnId = null, rerun = [], yieldAt = undefined, outputShown = false) => {
     const stopAt = journal && yieldAt !== undefined ? { yieldAt } : {};
     if (resuming) {
-      return request("session/prompt", { sessionId, prompt: [], _meta: { fx: { continueRecovery: true, ...rerun.length ? { rerun } : {}, ...stopAt } } });
+      return request("session/prompt", { sessionId, prompt: [], _meta: { fx: { continueRecovery: true, ...outputShown ? {} : { freshOutput: true }, ...rerun.length ? { rerun } : {}, ...stopAt } } });
     }
     const images = blocks.filter((block) => block.type === "image" && block.bytes !== undefined);
     const ids = images.length ? attachBytes(images.map((block) => block.bytes)) : [];
@@ -5903,7 +6352,7 @@ async function createFxEngine(options = {}) {
       type: "image",
       mimeType: block.mimeType,
       ...block.sourceRef === undefined ? {} : { sourceRef: block.sourceRef },
-      ...block.bytes === undefined ? {} : { _meta: { fx: { attachment: ids[next++] } } }
+      ...block.bytes === undefined ? {} : { _meta: { fx: { attachment: ids[next++], ...block.stored === undefined ? {} : { stored: block.stored } } } }
     });
     const fx = {
       ...followUp ? { inputId: followUp.id, inputAccepted: followUp.accepted } : {},
@@ -6031,21 +6480,10 @@ async function createFxEngine(options = {}) {
     }
     if (journal) {
       const { events, checkpoint } = loaded;
-      const params = { sessionId, ...options.inputsDurable === true ? { inputsDurable: true } : {} };
-      const attachments = [];
-      if (events.length > 0) {
-        const bytes = encoder4.encode(JSON.stringify(withoutSupersededProgress(events)));
-        if (bytes.byteLength > maxJournalBytes)
-          throw journalLoadError("libfx journal is too large", "FX_JOURNAL_TOO_LARGE");
-        attachments.push(["journalAttachment", bytes]);
-      }
-      if (checkpoint)
-        attachments.push(["snapshotAttachment", checkpoint]);
-      const ids = attachments.length ? attachBytes(attachments.map(([, bytes]) => bytes)) : [];
-      attachments.forEach(([name], index) => {
-        params[name] = ids[index];
-      });
-      const opened = await request("libfx/journal_open", params).catch((error) => {
+      const journalBytes = events.length > 0 ? encoder4.encode(JSON.stringify(withoutSupersededProgress(events))) : null;
+      if (journalBytes && journalBytes.byteLength > maxJournalBytes)
+        throw journalLoadError("libfx journal is too large", "FX_JOURNAL_TOO_LARGE");
+      const openFailed = (error) => {
         const message = error?.message ?? "";
         if (/newer fx/.test(message))
           throw new FxJournalVersionError(message);
@@ -6053,7 +6491,56 @@ async function createFxEngine(options = {}) {
         if (code)
           throw journalLoadError(message, code, error);
         throw error;
-      });
+      };
+      const openOnce = () => {
+        const params = {
+          sessionId,
+          ...options.inputsDurable === true ? { inputsDurable: true } : {},
+          ...imageStore ? { imageStore: true } : {},
+          ...imageStore && options[imageWindowLimits] ? { imageWindow: options[imageWindowLimits] } : {}
+        };
+        const attachments = [];
+        if (journalBytes)
+          attachments.push(["journalAttachment", journalBytes]);
+        if (checkpoint)
+          attachments.push(["snapshotAttachment", checkpoint]);
+        const ids = attachments.length ? attachBytes(attachments.map(([, bytes]) => bytes)) : [];
+        attachments.forEach(([name], index) => {
+          params[name] = ids[index];
+        });
+        return request("libfx/journal_open", params).catch(openFailed);
+      };
+      const stageImages = async (names) => {
+        let batch = [];
+        let batchBytes = 0;
+        const flush = async () => {
+          if (batch.length === 0)
+            return;
+          const ids = attachBytes(batch.map(({ bytes }) => bytes));
+          const images = batch.map(({ name }, index) => ({ name, attachment: ids[index] }));
+          batch = [];
+          batchBytes = 0;
+          await request("libfx/journal_images", { sessionId, images }).catch(openFailed);
+        };
+        for (const name of new Set(names.map(String))) {
+          const stored = imageStore ? await imageStorage.get(name) : undefined;
+          if (stored === undefined || stored === null)
+            throw imageMissingError(name);
+          const bytes = persistenceBytes(stored, "an image the image store returns");
+          if (batch.length === maxPendingAttachments || batchBytes + bytes.byteLength > maxPendingAttachmentBytes)
+            await flush();
+          batch.push({ name, bytes });
+          batchBytes += bytes.byteLength;
+        }
+        await flush();
+      };
+      let opened = await openOnce();
+      if (Array.isArray(opened?.imagesNeeded)) {
+        await stageImages(opened.imagesNeeded);
+        opened = await openOnce();
+        if (Array.isArray(opened?.imagesNeeded))
+          throw imageMissingError(String(opened.imagesNeeded[0]));
+      }
       compareCheckpointMeta(opened?.checkpointMeta);
       resumable = opened?.resumable === true;
       openTurnId = resumable && validTurnId(opened?.openTurnId) ? opened.openTurnId : null;
@@ -6375,10 +6862,9 @@ async function createFxEngine(options = {}) {
     const resizeImage = options.resizeImage;
     const resuming = promptOptions[resumeTurn] === true;
     const followUp = promptOptions[followUpInput] ?? null;
-    const normalized = resuming ? [] : normalizePromptInput(input, { deferImageLimits: resizeImage !== undefined });
+    const normalized = resuming ? [] : checkPromptInput(input, { resizeImage });
     const hasPixels = normalized.some((block) => block.type === "image" && block.data !== undefined);
-    const asyncImages = hasPixels && (resizeImage !== undefined || normalized.some((block) => block.type === "image" && block.source === "blob"));
-    checkPromptFrameSize(normalized, resizeImage === undefined);
+    const asyncImages = hasPixels && (resizeImage !== undefined || imageStore || normalized.some((block) => block.type === "image" && block.source === "blob"));
     const prompt = asyncImages ? normalized.map((block) => block.type === "image" && block.source === "bytes" ? { ...block, data: block.data.slice() } : block) : preparePromptImages(normalized);
     const signal = promptOptions.signal;
     if (signal !== undefined && (typeof signal?.addEventListener !== "function" || typeof signal?.removeEventListener !== "function"))
@@ -6611,8 +7097,9 @@ async function createFxEngine(options = {}) {
     }) : null;
     let response;
     if (asyncImages) {
+      const stopped = () => cancelled || closing;
       response = Promise.race([
-        Promise.resolve().then(() => materializePromptImages(prompt, () => cancelled || closing, resizeImage)),
+        Promise.resolve().then(() => materializePromptImages(prompt, stopped, resizeImage)).then((prepared) => prepared && imageStore ? storePromptImages(prepared, stopped) : prepared),
         imagePrepCancelled
       ]).then((prepared) => {
         cancelImagePrep = null;
@@ -6628,12 +7115,14 @@ async function createFxEngine(options = {}) {
       });
     } else {
       try {
-        response = sendPrompt(prompt, resuming, followUp, turn.id, promptOptions[rerunCallIds] ?? [], yieldAt);
+        response = sendPrompt(prompt, resuming, followUp, turn.id, promptOptions[rerunCallIds] ?? [], yieldAt, promptOptions[resumeOutputShown] === true);
       } catch (error) {
         response = Promise.reject(error);
       }
     }
-    turn.result = response.then((value) => {
+    turn.result = response.then(async (value) => {
+      if (journal)
+        await journalSettled().catch(() => {});
       if (journalFailure)
         throw reportJournalFailure();
       if (value.stopReason === "yielded" && !cancelled) {
@@ -6713,6 +7202,9 @@ function fxHarness({ createEngine, defaultApiKey = async () => {
     return {
       ...checkpoint === undefined ? {} : { seed: snapshotOf(checkpointBytesOf(checkpoint)) },
       settings: sessionSettings,
+      checkPrompt(input) {
+        checkPromptInput(input, { resizeImage: engineOptions.resizeImage });
+      },
       async open({ sessionId, store, context, settings, durability, ready }) {
         const apiKey = engineOptions.apiKey ?? await defaultApiKey(durability);
         const engine = await createEngine({
@@ -6811,7 +7303,7 @@ function fxSession(engine, idempotent) {
         throw error;
       }
     },
-    resume: ({ rerun = true, ...options } = {}) => fxTurn(engine.resume({ ...options, onAmbiguous: (call) => rerun && idempotent.has(call.name) ? "rerun" : undefined }), internals.exited),
+    resume: ({ rerun = true, ...options } = {}) => fxTurn(engine.resume({ ...options, [resumeOutputShown]: true, onAmbiguous: (call) => rerun && idempotent.has(call.name) ? "rerun" : undefined }), internals.exited),
     get openTurn() {
       return internals.openTurn;
     },