libfx 0.0.14-dev.1561.g1a070af32cdf → 0.0.15

package/durable.js

@@ -75,14 +75,129 @@ const recentIdsKept = 256;
 // The longest a message waits for a live holder before it is delivered again.
 const maxBackstopSeconds = 300;
 
+// Base64 of a Uint8Array: the runtime's own encoder where it has one, and
+// otherwise four letters from the table for each three bytes. Both are fast
+// enough for a large image; btoa over String.fromCharCode is not.
+const base64Letters = encoder.encode("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/");
 const toBase64 = (bytes) => {
-  let text = "";
-  for (let index = 0; index < bytes.length; index += 0x8000) {
-    text += String.fromCharCode(...bytes.subarray(index, index + 0x8000));
+  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;
   }
-  return btoa(text);
+  if (whole < bytes.length) {
+    // One or two bytes left: two or three letters, then "=" padding.
+    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);
+};
+const 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;
 };
-const fromBase64 = (text) => Uint8Array.from(atob(text), (char) => char.charCodeAt(0));
+
+// A session keeps each prompt image once, in its image store, named by the
+// lowercase hex SHA-256 of its bytes, as libfx's core names it; the log only
+// names it.
+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;
+}
+const base64url = (text) => toBase64(encoder.encode(text)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+// The key a harness's store gives its image store under, `{ put, get }`:
+// `persistenceImages` in fx-sdk.js, which engines read it from.
+const persistenceImages = Symbol.for("libfx.persistenceImages");
+
+// A view of the bytes in an ArrayBuffer or typed array, or null.
+const byteView = (value) => (value instanceof ArrayBuffer ? new Uint8Array(value)
+  : ArrayBuffer.isView(value) ? new Uint8Array(value.buffer, value.byteOffset, value.byteLength) : null);
+
+// A prompt's input as the queue and the log hold it: JSON, so image data is
+// base64 text. With `named`, the session stores each image in its image
+// store and the log names it (`storePromptImages`); `images` says whether any
+// image has data to store.
+//
+// Each image block is copied once and only the copy is read, since an
+// accessor can return something else the next time it is read, and the log
+// must hold what was checked. The blocks are walked by index for the same
+// reason: an Array subclass can make map() return anything. Pure.
+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 };
+}
+
+// Stores each image a prompt's input holds in the session's image store,
+// before the input that names it is stored, and returns the input naming
+// them: `{ type: "image", mimeType, sourceRef?, data: { sha256 } }`. An older
+// libfx refuses data it can't read, so a worker that predates names fails
+// the turn rather than run it without its images. A store that fails rejects
+// with its own error. With `images` null it only names them, for a prompt the
+// log already holds.
+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;
+}
+
+// A prompt's input with each named image read back from the session's image
+// store, as base64, which is how a harness has always received image data.
+// `missing` names the first image the store does not hold.
+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 };
+    // Bytes that aren't the ones named are not the image its caller sent.
+    if (await imageName(bytes) !== name) return { missing: name, corrupt: true };
+    blocks.push({ ...block, data: toBase64(bytes) });
+  }
+  return { input: blocks };
+}
 
 /**
  * The durability that keeps sessions in this process only. Agents given the
@@ -451,7 +566,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;
@@ -530,6 +645,14 @@ 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);
@@ -580,6 +703,9 @@ const logStep = "fx.log";
 // the run's id, then `_user_` and the base64url of the namespace
 // "libfx-ui".
 const uiStreamOf = (runId) => `${runId.replace(/^wrun_/, "strm_")}_user_bGliZngtdWk`;
+// The stream that holds an image, named as the UI stream is, with the
+// namespace "libfx-image-" and the image's name.
+const imageStreamOf = (runId, name) => `${runId.replace(/^wrun_/, "strm_")}_user_${base64url(`libfx-image-${name}`)}`;
 const queuePrefix = "__libfx_wkf_workflow_";
 // The name of an agent created without one, and of whatever a message or a
 // session from before names belonged to.
@@ -636,6 +762,49 @@ const streamReadRetries = 5;
 const missingStreamPollMs = 50;
 const missingStreamFastMs = 2000;
 
+// Runs whose log views one backend keeps, and the characters of JSON they
+// may hold together, least recently read dropped first.
+const maxLogViews = 32;
+const maxLogViewChars = 32 * 1024 * 1024;
+
+// Whether a newest-first listing showed every slot from the lowest it
+// listed to the newest. Pure.
+const gapless = (read) => read.listed === 0 || read.newest - read.lowest + 1 === read.listed;
+
+// The slot of a run's first event: a World numbers each run's events densely
+// from 1.
+const firstEventSlot = 1;
+
+// Whether a newest-first listing reached slot `floor`, or the checkpoint it
+// stopped at, which stands for every slot through its `through`. Pure.
+const listedDownTo = (read, floor) => read.lowest === floor || (read.through !== null && read.lowest <= read.through);
+
+/**
+ * A run's log view extended by the entries listed after it, as a full read
+ * returns the log: every entry after the newest checkpoint's `through`.
+ * Null when that checkpoint covers less than the view starts after, which
+ * only a full read can answer. `head` is the chain's head as a full read
+ * notes it: the newest chained entry, or the checkpoint's `through`. Pure.
+ */
+export 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") };
+}
+
 // Events a session-log read lists per page: the first page, then the rest.
 const firstPageEvents = 10;
 const laterPageEvents = 100;
@@ -782,6 +951,35 @@ function createWorldBackend(world, durability) {
   // poll.
   const watchers = new Map();
   const changed = (runId) => { for (const watcher of watchers.get(runId) ?? []) watcher(); };
+  // Each run's log as this process last read it: the entries read() returned,
+  // the newest slot seen, and the checkpoint's `through` they start after.
+  // The log only appends, so a later read lists only slots after `known`.
+  // The entries are kept as the JSON the World stores, so every read hands
+  // out its own copy, as reading the World does, and the views' size is
+  // bounded in characters as well as in runs.
+  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({
@@ -867,6 +1065,8 @@ function createWorldBackend(world, durability) {
     async session(runId) {
       // The newest slot this worker has seen.
       let known = 0;
+      // The images this worker knows the run's image store holds.
+      const storedImages = new Set();
       // Where the World has the in-band writer fence, chained entries are
       // written in-band, each expecting the World's count of in-band writes
       // at the entry it continues, so the World refuses one that continues a
@@ -925,11 +1125,17 @@ function createWorldBackend(world, durability) {
         // The newest chained entry read: the chain's head, unless the read
         // stopped before reaching any.
         let newestChained;
+        // The newest and lowest slots this read listed above `stopBelow`,
+        // entries or not, and how many. Unlike `known`, which this object's
+        // own writes also raise, these say only what the listing showed.
+        let newest = stopBelow;
+        let lowest = Infinity;
+        let listed = 0;
         // Ends the read. `head` is where the chain's head is when the read
         // found no chained entry, or undefined when the read does not show.
         const done = (head) => {
           noteSnapshot(snapshot, newestChained ?? head);
-          return { events, through };
+          return { events, through, snapshot, newest, lowest, listed };
         };
         // A session's newest checkpoint is usually among its last few
         // entries, so a read starts with a small page and fetches more only
@@ -943,13 +1149,16 @@ function createWorldBackend(world, durability) {
             if (!missingRun(error)) throw error;
             // The run's creation starts its count.
             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) {
             const slot = slotOf(event);
             if (slot > known) known = slot;
             if (slot <= stopBelow) return done(undefined);
+            if (slot > newest) newest = slot;
+            if (slot < lowest) lowest = slot;
+            listed += 1;
             // The checkpoint stands for the entries through its `through`,
             // the last of them the chain's head.
             if (through !== null && slot <= through) return done(through === 0 ? "null" : String(through));
@@ -966,10 +1175,50 @@ 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();
+        // A listing that skipped a slot may show a later write before an
+        // earlier one lands. The entries go back as they are, as every read
+        // returned them before, but no view keeps the gap for later reads.
+        // The listing must also reach the run's first event or the checkpoint
+        // it stopped at, so no slot below what it listed is missing.
+        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 [];
+          }
+          // The newer listing must have skipped no slot and must reach the
+          // view or a checkpoint that stands for what lies between; and a
+          // checkpoint covering less than the view starts after is not one
+          // the view can stand for. Otherwise read the log whole.
+          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();
+          // The in-band count at the chain's head, as a full read notes it.
+          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);
@@ -1047,6 +1296,44 @@ function createWorldBackend(world, durability) {
           set.add(fn);
           return () => set.delete(fn);
         },
+        // Each image is a stream of the run, named after it, so it is read by
+        // name wherever checkpoints fall. Two writers of one image each add
+        // its bytes once; a read takes the first chunk that matches the name.
+        images: {
+          async put(name, bytes) {
+            if (storedImages.has(name)) return;
+            // Refused here, before the prompt is stored, rather than by every
+            // worker that reads the image back.
+            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 undefined;
+              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 undefined;
+          },
+        },
         ui: {
           async write(lines) {
             await ensureRun();
@@ -1293,14 +1580,33 @@ const messageIdInUse = (message) => Object.assign(
   { code: "FX_MESSAGE_ID_IN_USE" },
 );
 
-// Writes what a message adds to its session, in order, and returns how many
-// entries it wrote. Only the sender calls it, before it queues the message.
+// Writes what a message adds to its session, in order, and returns each
+// entry it wrote with the slot it took. Only the sender calls it, before it
+// queues the message.
 // A message that reuses another input's id writes nothing and throws.
 async function recordMessage(log, state, message) {
   if (idInUse(state, message)) throw messageIdInUse(message);
   const entries = messageEntries(state, message);
-  for (const entry of entries) await log.append(entry);
-  return entries.length;
+  const appended = [];
+  for (const entry of entries) appended.push({ cursor: await log.append(entry), entry });
+  return appended;
+}
+
+/**
+ * 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:
+ * 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.
+ */
+export 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)) }))];
 }
 
 /**
@@ -1385,9 +1691,12 @@ class SessionWorker {
   // (`tests/tla/sdk/TenantIsolation.tla` OnlySentRuns). Then it runs the
   // session when no live worker holds it. Returns `{ timeoutSeconds }` to
   // have the same message delivered again later.
-  async consume(message, delivery = null) {
-    const log = await this.backend.session(this.sessionId);
-    let entries = await log.read();
+  // `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) {
+    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" });
@@ -1589,6 +1898,8 @@ class SessionWorker {
     const ui = uiWriter(log, (error) => agent.emit("ui.error", { sessionId: this.sessionId, error: error?.name ?? "Error" }), lease.epoch);
     // When the lease runs out, as this worker last renewed it.
     let leaseExpiresAt = lease.expiresAt;
+    // An image read that threw while the engine opened.
+    let imageReadFailed = null;
     const store = {
       load: async () => ({
         ...(state.checkpoint?.data ? { checkpoint: { through: state.checkpoint.through ?? "0", data: fromBase64(state.checkpoint.data) } } : {}),
@@ -1597,6 +1908,20 @@ class SessionWorker {
         head: head ?? state.head,
       }),
       append: ({ idempotencyKey, data, marks }) => chained({ k: "record", key: idempotencyKey, data: toBase64(data), marks }).then((cursor) => ({ cursor })),
+      // The engine stores each prompt image before it sends it; a prompt
+      // from the log names images already here.
+      [persistenceImages]: {
+        put: (name, bytes) => log.images.put(name, bytes),
+        get: async (name) => {
+          try {
+            return await log.images.get(name);
+          } catch (error) {
+            // The store failed to answer, which says nothing of the image.
+            imageReadFailed = error;
+            throw error;
+          }
+        },
+      },
       saveCheckpoint: async ({ through, data }) => {
         // What a fold that starts at this checkpoint would otherwise miss:
         // inputs before it that no turn took or that the open turn holds
@@ -1686,6 +2011,10 @@ class SessionWorker {
         harnessRun = runOf(state.openTurn ?? state.pending[0]);
         harness = await agent.openHarness(this.sessionId, store, harnessRun, ready);
       } 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
+        // fails and its message runs again; nothing failed the turn.
+        if (imageReadFailed) throw imageReadFailed;
         // A harness that cannot start fails the turn waiting on it, once:
         // the open turn, or after it failed, the next prompt.
         const waiting = state.openTurn && !state.openFailed ? state.openTurn.id : state.pending[0]?.messageId;
@@ -1763,8 +2092,21 @@ class SessionWorker {
             harness = await agent.openHarness(this.sessionId, store, wanted, ready);
             harnessRun = wanted;
           }
+          // A prompt names the images it stored; the engine gets their bytes.
+          const withImages = await resolvePromptImages(log.images, next.input);
+          if (withImages.missing) {
+            // A history without the image is not the one its caller sent.
+            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);
@@ -2227,6 +2569,9 @@ function turnView({ messageId, resumeRequest = null, start }) {
  *   sets over the agent's options for the turns it starts, as JSON the core
  *   stores with each prompt and passes to `open()`, or undefined for none.
  *   It throws a TypeError for options it refuses.
+ * - `checkPrompt(input)` (optional): throws a TypeError or RangeError for
+ *   a prompt input the harness would refuse. A session's `prompt()` calls it
+ *   before it stores anything, so a prompt it refuses is never stored.
  *
  * A harness session has `prompt(input, { turnId, yieldAt })` and
  * `resume({ yieldAt, rerun })`, each returning a turn, where `rerun: false`
@@ -2244,7 +2589,8 @@ function turnView({ messageId, resumeRequest = null, start }) {
  * end. Either way the steer runs as the next turn. A turn stops before a
  * model request once `yieldAt` has passed, with the stop reason `yielded`.
  *
- * An input the harness refuses is a turn that ends with an error.
+ * An input the harness refuses only once a turn runs it is a turn that ends
+ * with an error.
  * `prompt()` and `resume()` throw only when the harness cannot run a turn,
  * and a turn whose harness stopped under it rejects with a
  * `FX_HARNESS_STOPPED` code; either way the same message runs the session
@@ -2344,14 +2690,14 @@ export function createDurableAgentFactory({ harness, defaultDurability, defaultS
     // 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 } = {}) => {
+    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) {
         // No queue delivered this message, so none delivers it again: a turn
         // that must go on later continues in a fresh message. One whose
@@ -2417,7 +2763,9 @@ export function createDurableAgentFactory({ harness, defaultDurability, defaultS
         // OnlySentRuns), and a queue that ends with the process loses no
         // input.
         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) {
@@ -2434,7 +2782,9 @@ export function createDurableAgentFactory({ harness, defaultDurability, defaultS
             seeded = true;
             const delivery = backstop ? { messageId: backstop, attempt: 0 } : null;
             // receive() reports a failure to the host; the backstop retries it.
-            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;
           }
@@ -2442,7 +2792,16 @@ export function createDurableAgentFactory({ harness, defaultDurability, defaultS
         await created.queue.send(queued, { idempotencyKey });
         seeded = true;
       };
-      const startTurn = (type, messageId, input, retried = false, aborted = false) => {
+      // Settles once the latest prompt from this session object with images
+      // to store is stored or has failed; null while none has. Each later
+      // prompt waits for it, so they are stored in the order made.
+      let storing = null;
+      // `ready`, when given, resolves the input once it can be stored; only a
+      // prompt that is stored calls it.
+      // `aborted()` says whether the prompt's signal has aborted. One that
+      // aborted before the prompt's send began never stores it; `progress.sent`
+      // is set as the send begins, after which an abort cancels the prompt.
+      const startTurn = (type, messageId, input, retried = false, aborted = () => false, ready = null, progress = null) => {
         let accept;
         const accepted = new Promise((resolve, reject) => { accept = { resolve, reject }; });
         void accepted.catch(() => {});
@@ -2451,20 +2810,27 @@ export function createDurableAgentFactory({ harness, defaultDurability, defaultS
           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) {
-                // 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. The log, for that answer, is read
-                // alongside the one queue send.
-                from = await log.ui.length();
+              // 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()) {
+                // The log, for that answer, is read alongside the one queue
+                // send.
                 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 })),
                 ]);
                 // One the log does not know yet is this send's own. When the
                 // log says it ran and nothing shows how, either this send's
@@ -2477,9 +2843,8 @@ export function createDurableAgentFactory({ harness, defaultDurability, defaultS
               }
               if (retried) {
                 // A turn this id already ran answers from the log, without
-                // queueing it again. The viewer's start is read first, so a
+                // queueing it again. The viewer's start was read first, so a
                 // turn that ends after it has its end in view.
-                from = await log.ui.length();
                 const outcome = await retryOutcome(log, foldSessionLog(await log.read()), messageId, from, { sent: false });
                 if (outcome.follow) attaching = true;
                 else if (!outcome.fresh) {
@@ -2488,15 +2853,17 @@ export function createDurableAgentFactory({ harness, defaultDurability, defaultS
                   return { log, from, attaching: true, endWithinMs: retryEndWaitMs };
                 }
               }
-              if (aborted && !attaching) {
-                // A new prompt whose signal had aborted is never stored.
-                accept.resolve({ messageId, sessionId });
-                return { settled: { messageId, stopReason: "cancelled", usage: {} } };
-              }
               // The viewer starts where the stream is now, before the
               // message can produce anything.
               from ??= await log.ui.length();
-              await send({ type, messageId, ...(input === undefined ? {} : { input }) }, { inRequest: type === "prompt" });
+              if (aborted()) {
+                // A prompt whose signal aborted before its send began is never
+                // stored; a retry of one the log holds only follows its turn.
+                accept.resolve({ messageId, sessionId });
+                if (!attaching) return { settled: { messageId, stopReason: "cancelled", usage: {} } };
+                return { log, from, attaching };
+              }
+              await queue();
               accept.resolve({ messageId, sessionId });
               return { log, from, attaching };
             } catch (error) {
@@ -2513,25 +2880,83 @@ export function createDurableAgentFactory({ harness, defaultDurability, defaultS
          * Queues `input` as the session's next turn and returns a view of it.
          * With `messageId`, a retried call is the same turn: it continues a
          * turn still running and answers one that ended, without running it
-         * again.
+         * again. Each image is stored once in the session's image store and
+         * the log names it. A later prompt from this session object waits for
+         * an earlier one's images. An input the harness would refuse throws
+         * here and is never stored. A prompt whose signal aborts before it is
+         * stored is never stored either: it ends cancelled.
          */
         prompt(input, promptOptions = {}) {
           if (closed) throw new Error(`${label} is closed`);
           const messageId = promptOptions.messageId ?? newId("msg");
           if (!validId(messageId)) 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");
-          // The input travels through the queue and the log as JSON.
-          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;
+          // The input travels through the queue and the log as JSON. Its
+          // images go to the session's image store first and the log names
+          // them; a prompt aborted before the call stores nothing, so it
+          // keeps them as base64.
+          const named = !aborted;
+          const stored = Array.isArray(input) ? promptInputForLog(input, { named }) : { input, images: false };
+          // The copy the log will hold is what is checked: a getter can't
+          // show the check one value and the log another.
+          admit(stored.input);
+          plugged.checkPrompt?.(stored.input);
+          const before = storing;
+          const ready = before || stored.images ? async () => {
+            // The prompt waits for an earlier one and its image writes only
+            // until its signal aborts; what it waited for may still land, but
+            // the prompt is not stored.
+            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;
+              void 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);
+                // A retry of a prompt the log already holds is answered from
+                // the log: its images are named, not written again.
+                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;
+              }
+              // An agent closed meanwhile stores nothing more.
+              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) {
+            // A later prompt waits for this one and every one before it: one
+            // withdrawn while it waited settles before them.
+            const settled = Promise.all([before, turn.accepted.then(() => {}, () => {})]).then(() => {});
+            storing = settled;
+            void settled.then(() => { if (storing === settled) storing = null; });
+          }
           if (signal !== undefined && !signal.aborted) {
             // The prompt's own cancel: it stops this turn whether it runs or
-            // still waits, and never a later one.
-            const stop = () => { void send({ type: "cancel", messageId: newId("cnl"), target: messageId }).catch(() => {}); };
+            // still waits, and never a later one. A prompt whose send had not
+            // begun is never stored, so it needs none.
+            const stop = () => {
+              if (progress.sent) void send({ type: "cancel", messageId: newId("cnl"), target: messageId }).catch(() => {});
+            };
             signal.addEventListener("abort", stop, { once: true });
             void turn.result.finally(() => signal.removeEventListener("abort", stop)).catch(() => {});
           }
@@ -2633,7 +3058,16 @@ export function createDurableAgentFactory({ harness, defaultDurability, defaultS
           const messageId = steerOptions.messageId ?? newId("str");
           if (!validId(messageId)) throw new TypeError(`messageId must be ${idRule}`);
           admit(input);
-          await send({ type: "steer", messageId, input });
+          // A steer's images go in the session's image store before the steer
+          // that names them, as a prompt's do; storing one again under its
+          // name is harmless, so a retry needs no check.
+          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 };
         },
         /** Cancels the running turn; dropping a turn's view does not. */
@@ -2652,6 +3086,12 @@ export function createDurableAgentFactory({ harness, defaultDurability, defaultS
               head: state.head,
             }),
             append: async () => { throw new Error("a checkpoint reads the session without changing it"); },
+            // The records name the session's images; the engine reads them
+            // from its image store to export them.
+            [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);
           try {