zeitlich 0.2.38 → 0.2.40

package/src/lib/subagent/workflow.ts

@@ -12,6 +12,7 @@ import type {
   SubagentSessionInput,
 } from "./types";
 import type { SubagentSandboxShutdown } from "../lifecycle";
+import type { SandboxSnapshot } from "../sandbox/types";
 import { childSandboxReadySignal } from "./signals";
 
 /**
@@ -50,6 +51,8 @@ import { childSandboxReadySignal } from "./signals";
  *     });
  *
  *     const { finalMessage, threadId } = await session.runSession({ stateManager });
+ *     // `sandboxId`, `snapshot`, and `baseSnapshot` are auto-forwarded
+ *     // from the session — no need to thread them through manually.
  *     return { toolResponse: finalMessage ?? "No response", data: null, threadId };
  *   },
  * );
@@ -125,23 +128,47 @@ export function defineSubagentWorkflow(
     }
     const parentHandle = getExternalWorkflowHandle(parent.workflowId);
 
+    let capturedSandboxId: string | undefined;
+    let capturedSnapshot: SandboxSnapshot | undefined;
+    let capturedBaseSnapshot: SandboxSnapshot | undefined;
+    let capturedThreadId: string | undefined;
     const sessionInput: SubagentSessionInput = {
       agentName: config.name,
       sandboxShutdown: effectiveShutdown,
       ...(workflowInput.thread && { thread: workflowInput.thread }),
       ...(workflowInput.sandbox && { sandbox: workflowInput.sandbox }),
-      onSandboxReady: (sandboxId: string) => {
+      onSandboxReady: ({ sandboxId, baseSnapshot }) => {
+        capturedBaseSnapshot = baseSnapshot;
         const isReuse = workflowInput.sandbox?.mode === "continue";
         if (!isReuse) {
           void parentHandle.signal(childSandboxReadySignal, {
             childWorkflowId: workflowInfo().workflowId,
             sandboxId,
+            ...(baseSnapshot && { baseSnapshot }),
           });
         }
       },
+      onSessionExit: ({ sandboxId, snapshot, threadId }) => {
+        capturedSandboxId = sandboxId;
+        capturedSnapshot = snapshot;
+        capturedThreadId = threadId;
+      },
     };
 
-    return fn(prompt, sessionInput, context ?? {});
+    const result = await fn(prompt, sessionInput, context ?? {});
+
+    // Auto-forward sandbox outputs captured from the session so user code
+    // never has to thread them through manually. Explicit values on the fn
+    // result take precedence.
+    return {
+      ...result,
+      ...(capturedThreadId !== undefined && { threadId: capturedThreadId }),
+      ...(capturedSandboxId !== undefined && { sandboxId: capturedSandboxId }),
+      ...(capturedSnapshot !== undefined && { snapshot: capturedSnapshot }),
+      ...(capturedBaseSnapshot !== undefined && {
+        baseSnapshot: capturedBaseSnapshot,
+      }),
+    };
   };
 
   // for temporal workflow name

package/src/lib/thread/index.ts

@@ -1,5 +1,10 @@
 export { createThreadManager } from "./manager";
 export { createThreadOpsProxy } from "./proxy";
+export {
+  THREAD_TTL_SECONDS,
+  getThreadListKey,
+  getThreadMetaKey,
+} from "./keys";
 
 export type {
   ThreadManagerConfig,

package/src/lib/thread/keys.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  getThreadListKey,
+  getThreadMetaKey,
+  THREAD_TTL_SECONDS,
+} from "./keys";
+import { createThreadManager } from "./manager";
+
+describe("thread keys (public helpers)", () => {
+  it("getThreadListKey matches the internal list-key format", () => {
+    expect(getThreadListKey("messages", "abc")).toBe("messages:thread:abc");
+    expect(getThreadListKey("myScope", "xyz")).toBe("myScope:thread:xyz");
+  });
+
+  it("getThreadMetaKey matches the internal meta-key format", () => {
+    expect(getThreadMetaKey("messages", "abc")).toBe(
+      "messages:meta:thread:abc"
+    );
+    expect(getThreadMetaKey("myScope", "xyz")).toBe("myScope:meta:thread:xyz");
+  });
+
+  it("THREAD_TTL_SECONDS is 90 days", () => {
+    expect(THREAD_TTL_SECONDS).toBe(60 * 60 * 24 * 90);
+  });
+});
+
+describe("createThreadManager ↔ public key helpers round-trip", () => {
+  it("writes and reads via the exact keys returned by the public helpers", async () => {
+    const store = new Map<string, string[]>();
+    const meta = new Map<string, string>();
+
+    const writtenListExpires = new Map<string, number>();
+    const writtenMetaExpires = new Map<string, number>();
+
+    const redis = {
+      exists: vi.fn(async (k: string) => (meta.has(k) ? 1 : 0)),
+      set: vi.fn(
+        async (k: string, v: string, _ex: string, ttl: number) => {
+          meta.set(k, v);
+          writtenMetaExpires.set(k, ttl);
+          return "OK";
+        }
+      ),
+      del: vi.fn(async (...keys: string[]) => {
+        let n = 0;
+        for (const k of keys) {
+          if (store.delete(k)) n++;
+          if (meta.delete(k)) n++;
+        }
+        return n;
+      }),
+      rpush: vi.fn(async (k: string, ...values: string[]) => {
+        const list = store.get(k) ?? [];
+        list.push(...values);
+        store.set(k, list);
+        return list.length;
+      }),
+      lrange: vi.fn(async (k: string) => store.get(k) ?? []),
+      llen: vi.fn(async (k: string) => (store.get(k) ?? []).length),
+      ltrim: vi.fn(async () => "OK"),
+      expire: vi.fn(async (k: string, ttl: number) => {
+        if (store.has(k)) writtenListExpires.set(k, ttl);
+        if (meta.has(k)) writtenMetaExpires.set(k, ttl);
+        return 1;
+      }),
+      eval: vi.fn(async () => 1),
+    };
+
+    const threadKey = "messages";
+    const threadId = "t1";
+    const tm = createThreadManager<{ id: string }>({
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      redis: redis as any,
+      threadId,
+      key: threadKey,
+      idOf: (m) => m.id,
+    });
+
+    await tm.initialize();
+
+    const expectedList = getThreadListKey(threadKey, threadId);
+    const expectedMeta = getThreadMetaKey(threadKey, threadId);
+
+    expect(meta.has(expectedMeta)).toBe(true);
+    expect(writtenMetaExpires.get(expectedMeta)).toBe(THREAD_TTL_SECONDS);
+
+    // Append uses rpush (idOf set → eval path; bypass eval for this check by
+    // calling rpush path via no-idOf manager)
+    const tm2 = createThreadManager<{ id: string }>({
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      redis: redis as any,
+      threadId,
+      key: threadKey,
+    });
+    await tm2.append([{ id: "m1" }]);
+
+    expect(store.has(expectedList)).toBe(true);
+    expect(store.get(expectedList)).toEqual([JSON.stringify({ id: "m1" })]);
+    expect(writtenListExpires.get(expectedList)).toBe(THREAD_TTL_SECONDS);
+  });
+});

package/src/lib/thread/keys.ts

@@ -0,0 +1,94 @@
+/**
+ * Public helpers for zeitlich's Redis thread storage layout.
+ *
+ * These are the exact string-building primitives zeitlich's internal thread
+ * manager uses for every adapter. Downstream consumers that need to read a
+ * persisted thread (for evaluation, observability, admin tooling, etc.)
+ * should use these helpers rather than reconstructing the key layout by
+ * hand — the layout is versioned with this module, so upgrading zeitlich
+ * keeps the consumer in sync.
+ *
+ * The layout is adapter-agnostic: every thread adapter stores messages the
+ * same way.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   getThreadListKey,
+ *   getThreadMetaKey,
+ *   THREAD_TTL_SECONDS,
+ * } from 'zeitlich';
+ *
+ * const listKey = getThreadListKey('messages', threadId);
+ * const metaKey = getThreadMetaKey('messages', threadId);
+ * const ttl = await redis.ttl(listKey); // <= THREAD_TTL_SECONDS
+ * ```
+ */
+
+/**
+ * TTL (in seconds) applied to every thread list and thread meta key that
+ * zeitlich's {@link createThreadManager} writes. Exposed so downstream
+ * consumers can size their Redis retention / query windows to match.
+ *
+ * Current value: 90 days.
+ */
+export const THREAD_TTL_SECONDS = 60 * 60 * 24 * 90;
+
+/**
+ * Build the Redis list key that holds a thread's serialized messages.
+ *
+ * Mirrors the exact key used internally by zeitlich's thread manager,
+ * so a consumer calling `redis.lrange(getThreadListKey(key, id), 0, -1)`
+ * sees the same data the writer wrote.
+ *
+ * @param threadKey - Thread key (defaults to `"messages"` inside the
+ *                    thread manager, but downstream adapters may pass
+ *                    their own value).
+ * @param threadId  - Thread id as provided to the thread manager.
+ */
+export function getThreadListKey(
+  threadKey: string,
+  threadId: string
+): string {
+  return `${threadKey}:thread:${threadId}`;
+}
+
+/**
+ * Build the Redis key that stores a thread's existence marker / metadata.
+ *
+ * Zeitlich treats the presence of this key as "thread has been
+ * initialized"; append/load/fork/truncate operations fail when it is
+ * missing. Consumers can use it as a cheap existence probe without
+ * scanning the message list.
+ *
+ * @param threadKey - Thread key (defaults to `"messages"` inside the
+ *                    thread manager, but downstream adapters may pass
+ *                    their own value).
+ * @param threadId  - Thread id as provided to the thread manager.
+ */
+export function getThreadMetaKey(
+  threadKey: string,
+  threadId: string
+): string {
+  return `${threadKey}:meta:thread:${threadId}`;
+}
+
+/**
+ * Build the Redis key that stores a thread's persisted state slice
+ * (tasks + custom state) written by zeitlich's session loop on every
+ * exit path.
+ *
+ * Consumers can read this key with `redis.get(getThreadStateKey(key, id))`
+ * and `JSON.parse` the result into a {@link PersistedThreadState}.
+ *
+ * @param threadKey - Thread key (defaults to `"messages"` inside the
+ *                    thread manager, but downstream adapters may pass
+ *                    their own value).
+ * @param threadId  - Thread id as provided to the thread manager.
+ */
+export function getThreadStateKey(
+  threadKey: string,
+  threadId: string
+): string {
+  return `${threadKey}:state:thread:${threadId}`;
+}

package/src/lib/thread/manager.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, it, beforeEach } from "vitest";
+import type Redis from "ioredis";
+import { createThreadManager } from "./manager";
+import type { PersistedThreadState } from "../state/types";
+
+/**
+ * Minimal in-memory Redis stub exposing just the commands used by
+ * `createThreadManager`'s state methods (get/set/del/exists/expire) plus
+ * the list helpers needed for `initialize`.
+ */
+function createFakeRedis(): Redis {
+  const store = new Map<string, string>();
+
+  const redis = {
+    async get(key: string): Promise<string | null> {
+      return store.has(key) ? (store.get(key) as string) : null;
+    },
+    async set(key: string, value: string): Promise<"OK"> {
+      store.set(key, String(value));
+      return "OK";
+    },
+    async del(...keys: string[]): Promise<number> {
+      let removed = 0;
+      for (const k of keys) {
+        if (store.delete(k)) removed++;
+      }
+      return removed;
+    },
+    async exists(...keys: string[]): Promise<number> {
+      return keys.reduce((acc, k) => acc + (store.has(k) ? 1 : 0), 0);
+    },
+    async expire(_key: string, _ttl: number): Promise<number> {
+      return 1;
+    },
+    async lrange(): Promise<string[]> {
+      return [];
+    },
+    async rpush(): Promise<number> {
+      return 0;
+    },
+    _store: store,
+  } as unknown as Redis & { _store: Map<string, string> };
+
+  return redis;
+}
+
+const baseSlice: PersistedThreadState = {
+  tasks: [
+    [
+      "t1",
+      {
+        id: "t1",
+        subject: "do a thing",
+        description: "do it",
+        activeForm: "doing a thing",
+        status: "pending",
+        metadata: {},
+        blockedBy: [],
+        blocks: [],
+      },
+    ],
+  ],
+  custom: { counter: 7, label: "hello" },
+};
+
+describe("createThreadManager state persistence", () => {
+  let redis: Redis & { _store: Map<string, string> };
+
+  beforeEach(() => {
+    redis = createFakeRedis() as Redis & { _store: Map<string, string> };
+  });
+
+  async function initThread(threadId: string): Promise<void> {
+    const tm = createThreadManager({ redis, threadId });
+    await tm.initialize();
+  }
+
+  it("loadState returns null when nothing has been saved", async () => {
+    await initThread("thread-1");
+    const tm = createThreadManager({ redis, threadId: "thread-1" });
+    expect(await tm.loadState()).toBeNull();
+  });
+
+  it("saveState writes a round-trippable JSON slice", async () => {
+    await initThread("thread-1");
+    const tm = createThreadManager({ redis, threadId: "thread-1" });
+    await tm.saveState(baseSlice);
+
+    const loaded = await tm.loadState();
+    expect(loaded).toEqual(baseSlice);
+  });
+
+  it("saveState throws if the thread was never initialized", async () => {
+    const tm = createThreadManager({ redis, threadId: "missing" });
+    await expect(tm.saveState(baseSlice)).rejects.toThrow(/does not exist/);
+  });
+
+  it("fork copies the persisted state slice to the new thread", async () => {
+    await initThread("source");
+    const src = createThreadManager({ redis, threadId: "source" });
+    await src.saveState(baseSlice);
+
+    const dst = await src.fork("target");
+
+    expect(await dst.loadState()).toEqual(baseSlice);
+  });
+
+  it("fork leaves the new thread's slice null when source has none", async () => {
+    await initThread("source");
+    const src = createThreadManager({ redis, threadId: "source" });
+
+    const dst = await src.fork("target");
+
+    expect(await dst.loadState()).toBeNull();
+  });
+
+  it("deleteState removes only the state key", async () => {
+    await initThread("thread-1");
+    const tm = createThreadManager({ redis, threadId: "thread-1" });
+    await tm.saveState(baseSlice);
+
+    await tm.deleteState();
+
+    expect(await tm.loadState()).toBeNull();
+    const keys = Array.from(redis._store.keys());
+    expect(keys.some((k) => k.includes(":meta:"))).toBe(true);
+    expect(keys.some((k) => k.includes(":state"))).toBe(false);
+  });
+
+  it("delete removes messages + meta + state together", async () => {
+    await initThread("thread-1");
+    const tm = createThreadManager({ redis, threadId: "thread-1" });
+    await tm.saveState(baseSlice);
+
+    await tm.delete();
+
+    expect(redis._store.size).toBe(0);
+  });
+});

package/src/lib/thread/manager.ts

@@ -1,6 +1,11 @@
+import type { PersistedThreadState } from "../state/types";
 import type { ThreadManagerConfig, BaseThreadManager } from "./types";
-
-const THREAD_TTL_SECONDS = 60 * 60 * 24 * 90; // 90 days
+import {
+  THREAD_TTL_SECONDS,
+  getThreadListKey,
+  getThreadMetaKey,
+  getThreadStateKey,
+} from "./keys";
 
 /**
  * Lua script for atomic idempotent append.
@@ -23,8 +28,8 @@ redis.call('SET', KEYS[1], '1', 'EX', tonumber(ARGV[1]))
 return 1
 `;
 
-function getThreadKey(threadId: string, key: string): string {
-  return `${key}:thread:${threadId}`;
+function getDedupKey(threadId: string, id: string): string {
+  return `dedup:${id}:thread:${threadId}`;
 }
 
 /**
@@ -42,8 +47,9 @@ export function createThreadManager<T>(
     deserialize = (raw: string): T => JSON.parse(raw) as T,
     idOf,
   } = config;
-  const redisKey = getThreadKey(threadId, key);
-  const metaKey = getThreadKey(threadId, `${key}:meta`);
+  const redisKey = getThreadListKey(key, threadId);
+  const metaKey = getThreadMetaKey(key, threadId);
+  const stateKey = getThreadStateKey(key, threadId);
 
   async function assertThreadExists(): Promise<void> {
     const exists = await redis.exists(metaKey);
@@ -70,7 +76,7 @@ export function createThreadManager<T>(
 
       if (idOf) {
         const dedupId = messages.map(idOf).join(":");
-        const dedupKey = getThreadKey(threadId, `dedup:${dedupId}`);
+        const dedupKey = getDedupKey(threadId, dedupId);
         await redis.eval(
           APPEND_IDEMPOTENT_SCRIPT,
           2,
@@ -88,21 +94,70 @@ export function createThreadManager<T>(
     async fork(newThreadId: string): Promise<BaseThreadManager<T>> {
       await assertThreadExists();
       const data = await redis.lrange(redisKey, 0, -1);
+      const stateRaw = await redis.get(stateKey);
       const forked = createThreadManager({
         ...config,
         threadId: newThreadId,
       });
       await forked.initialize();
       if (data.length > 0) {
-        const newKey = getThreadKey(newThreadId, key);
+        const newKey = getThreadListKey(key, newThreadId);
         await redis.rpush(newKey, ...data);
         await redis.expire(newKey, THREAD_TTL_SECONDS);
       }
+      if (stateRaw != null) {
+        const newStateKey = getThreadStateKey(key, newThreadId);
+        await redis.set(newStateKey, stateRaw, "EX", THREAD_TTL_SECONDS);
+      }
       return forked;
     },
 
+    async replaceAll(messages: T[]): Promise<void> {
+      await assertThreadExists();
+      if (!idOf) {
+        throw new Error(
+          "replaceAll requires the thread manager to be configured with `idOf`"
+        );
+      }
+      const existing = await redis.lrange(redisKey, 0, -1);
+      const existingIds = existing
+        .map((raw) => idOf(deserialize(raw)))
+        .filter((id): id is string => typeof id === "string");
+      await redis.del(redisKey);
+      if (existingIds.length > 0) {
+        await redis.del(
+          ...existingIds.map((id) => getDedupKey(threadId, id))
+        );
+      }
+      if (messages.length > 0) {
+        await redis.rpush(redisKey, ...messages.map(serialize));
+        await redis.expire(redisKey, THREAD_TTL_SECONDS);
+      }
+      await redis.expire(metaKey, THREAD_TTL_SECONDS);
+    },
+
     async delete(): Promise<void> {
-      await redis.del(redisKey, metaKey);
+      await redis.del(redisKey, metaKey, stateKey);
+    },
+
+    async loadState(): Promise<PersistedThreadState | null> {
+      const raw = await redis.get(stateKey);
+      if (raw == null) return null;
+      return JSON.parse(raw) as PersistedThreadState;
+    },
+
+    async saveState(state: PersistedThreadState): Promise<void> {
+      await assertThreadExists();
+      await redis.set(
+        stateKey,
+        JSON.stringify(state),
+        "EX",
+        THREAD_TTL_SECONDS
+      );
+    },
+
+    async deleteState(): Promise<void> {
+      await redis.del(stateKey);
     },
 
     async length(): Promise<number> {
@@ -110,17 +165,40 @@ export function createThreadManager<T>(
       return redis.llen(redisKey);
     },
 
-    async truncate(length: number): Promise<void> {
+    async truncateFromId(messageId: string): Promise<void> {
       await assertThreadExists();
-      if (length <= 0) {
+      if (!idOf) {
+        throw new Error(
+          "truncateFromId requires the thread manager to be configured with `idOf`"
+        );
+      }
+      const data = await redis.lrange(redisKey, 0, -1);
+      let idx = -1;
+      const removedIds: string[] = [];
+      for (let i = 0; i < data.length; i++) {
+        const raw = data[i];
+        if (raw === undefined) continue;
+        const id = idOf(deserialize(raw));
+        if (idx === -1 && id === messageId) idx = i;
+        if (idx !== -1) removedIds.push(id);
+      }
+      if (idx === -1) return;
+      if (idx === 0) {
         await redis.del(redisKey);
         await redis.expire(metaKey, THREAD_TTL_SECONDS);
       } else {
-        await redis.ltrim(redisKey, 0, length - 1);
+        await redis.ltrim(redisKey, 0, idx - 1);
         await redis.expire(redisKey, THREAD_TTL_SECONDS);
       }
-      // Dedup keys for removed messages are left to expire via their TTL.
-      // Post-truncate appends use fresh ids so collisions do not occur in practice.
+      // Clear dedup markers for the removed messages so that a rewind
+      // retry which reuses the same ids (e.g. the same assistantId) can
+      // re-append without the idempotent-append Lua script treating it
+      // as a duplicate.
+      if (removedIds.length > 0) {
+        await redis.del(
+          ...removedIds.map((id) => getDedupKey(threadId, id))
+        );
+      }
     },
   };
 }

package/src/lib/thread/proxy.ts

@@ -54,5 +54,7 @@ export function createThreadOpsProxy(
     appendSystemMessage: acts[p("appendSystemMessage")],
     forkThread: acts[p("forkThread")],
     truncateThread: acts[p("truncateThread")],
+    loadThreadState: acts[p("loadThreadState")],
+    saveThreadState: acts[p("saveThreadState")],
   } as ActivityInterfaceFor<ThreadOps>;
 }

package/src/lib/thread/types.ts

@@ -1,5 +1,5 @@
 import type Redis from "ioredis";
-import type { JsonValue } from "../state/types";
+import type { JsonValue, PersistedThreadState } from "../state/types";
 export interface ThreadManagerConfig<T> {
   redis: Redis;
   threadId: string;
@@ -34,17 +34,50 @@ export interface BaseThreadManager<T> {
    * forks — each call creates an independent copy.
    */
   fork(newThreadId: string): Promise<BaseThreadManager<T>>;
+  /**
+   * Atomically replace the entire contents of the thread with `messages`.
+   * The existing list is cleared, the new messages are appended in order,
+   * and dedup markers from prior appends are cleared so future idempotent
+   * appends with ids that were removed aren't silently skipped.
+   *
+   * Requires the thread manager to be configured with `idOf`.
+   */
+  replaceAll(messages: T[]): Promise<void>;
   /** Delete the thread */
   delete(): Promise<void>;
   /** Get the number of stored messages currently in the thread */
   length(): Promise<number>;
   /**
-   * Truncate the thread to the given length (inclusive). Any messages
-   * beyond `length` are removed. When `length` is 0 the thread ends up
-   * empty (but still exists). Also clears any dedup markers so that
-   * subsequent appends with the same ids replay correctly.
+   * Truncate the thread starting at the message with id `messageId`.
+   * That message and every message after it are removed. If `messageId`
+   * is not present in the thread this is a no-op — useful as the
+   * "truncate on entry" step of the `runAgent` activity, which becomes a
+   * no-op on the first attempt and a cleanup on Temporal workflow reset
+   * or in-workflow rewind retries.
+   *
+   * Dedup markers for removed single-message appends are also cleared so
+   * that appending the same id again (e.g. the same assistant message id
+   * on a rewind retry) is not silently skipped.
+   *
+   * Requires the thread manager to be configured with `idOf`.
+   */
+  truncateFromId(messageId: string): Promise<void>;
+  /**
+   * Load the persisted state slice associated with this thread, or
+   * `null` if none has been saved yet. Safe to call on any thread —
+   * treats a missing slice as a non-error.
    */
-  truncate(length: number): Promise<void>;
+  loadState(): Promise<PersistedThreadState | null>;
+  /**
+   * Overwrite the persisted state slice for this thread. The thread
+   * itself must already exist (same TTL as the message list).
+   *
+   * Note: {@link BaseThreadManager.fork} already copies the slice to
+   * the new thread, so there's no separate `forkState` method.
+   */
+  saveState(state: PersistedThreadState): Promise<void>;
+  /** Delete just the persisted state slice, leaving messages intact. */
+  deleteState(): Promise<void>;
 }
 
 /**
@@ -81,6 +114,27 @@ export interface ThreadManagerHooks<TStored, TPrepared = TStored> {
     index: number,
     messages: readonly TPrepared[]
   ) => TPrepared;
+  /**
+   * One-shot list-level pre-pass applied once when a thread is forked with
+   * `transform: true`. Runs before {@link onForkTransform}. May filter,
+   * compact, prepend, or otherwise rewrite the whole forked thread — so the
+   * returned length need not match the input length. Async, so implementations
+   * may call an LLM or other I/O.
+   */
+  onForkPrepareThread?: (
+    messages: readonly TStored[]
+  ) => TStored[] | Promise<TStored[]>;
+  /**
+   * Per-message final pass applied once when a thread is forked with
+   * `transform: true`. Runs after {@link onForkPrepareThread}. Pure 1:1 map —
+   * must return a value for every input message; length cannot change. Same
+   * shape as {@link onPreparedMessage}.
+   */
+  onForkTransform?: (
+    message: TStored,
+    index: number,
+    messages: readonly TStored[]
+  ) => TStored;
 }
 
 export interface ProviderThreadManager<