zeitlich 0.2.37 → 0.2.39

package/src/lib/subagent/types.ts

@@ -1,4 +1,5 @@
 import type { z } from "zod";
+import type { ChildWorkflowOptions } from "@temporalio/workflow";
 import type { JsonValue } from "../state/types";
 import type {
   ToolHandlerResponse,
@@ -12,22 +13,27 @@ import type {
 } from "../lifecycle";
 import type { SandboxOps, SandboxSnapshot } from "../sandbox/types";
 
+/**
+ * Subset of {@link ChildWorkflowOptions} that callers may override when a
+ * subagent is invoked. `workflowId`, `taskQueue`, and `args` are managed by
+ * the subagent handler itself and therefore cannot be set here.
+ *
+ * Configuring `workflowRunTimeout` (or `workflowExecutionTimeout`) is strongly
+ * recommended: it is the only reliable way to guarantee that a child workflow
+ * which fails during initialization or repeatedly fails workflow tasks will
+ * eventually be terminated, allowing the parent's `Subagent` tool call to fail
+ * deterministically instead of hanging forever waiting for a result.
+ */
+export type SubagentChildWorkflowOptions = Omit<
+  ChildWorkflowOptions,
+  "workflowId" | "taskQueue" | "args"
+>;
+
 /** ToolHandlerResponse with threadId required (subagents must always surface their thread) */
 export type SubagentHandlerResponse<
   TResult = null,
   TToolResponse = JsonValue,
-> = ToolHandlerResponse<TResult, TToolResponse> & {
-  threadId: string;
-  sandboxId?: string;
-  /** Snapshot captured on session exit when `sandboxShutdown === "snapshot"`. */
-  snapshot?: SandboxSnapshot;
-  /**
-   * Snapshot captured immediately after the sandbox was seeded (before the
-   * first agent turn) when `continuation === "snapshot"`. Only set on the
-   * first call that actually created the sandbox.
-   */
-  baseSnapshot?: SandboxSnapshot;
-};
+> = ToolHandlerResponse<TResult, TToolResponse>;
 
 /**
  * Raw workflow input fields passed from parent to child workflow.
@@ -124,6 +130,24 @@ export interface SubagentConfig<TResult extends z.ZodType = z.ZodType> {
   workflow: SubagentWorkflow<TResult>;
   /** Optional task queue - defaults to parent's queue if not specified */
   taskQueue?: string;
+  /**
+   * Optional child workflow options forwarded to `executeChild` when the
+   * subagent is spawned. Use this to configure timeouts, retry policies, or
+   * parent-close behavior for the child workflow.
+   *
+   * **Recommended:** configure a `workflowRunTimeout` (or
+   * `workflowExecutionTimeout`) so that a child workflow that fails to
+   * initialize — or repeatedly fails workflow tasks without ever reaching a
+   * terminal state — is eventually terminated by the Temporal server. Without
+   * such a timeout, the parent's `Subagent` tool call can hang indefinitely
+   * waiting for the child to finish. When Temporal terminates the child, the
+   * tool call fails with a structured `ChildWorkflowFailure` that the router's
+   * failure hooks can handle just like any other tool error.
+   *
+   * `workflowId`, `taskQueue`, and `args` are managed by the subagent handler
+   * and cannot be overridden here.
+   */
+  workflowOptions?: SubagentChildWorkflowOptions;
   /** Optional Zod schema to validate the child workflow's result. If omitted, result is passed through as-is. */
   resultSchema?: TResult;
   /** Optional context passed to the subagent — a static object or a function evaluated at invocation time */
@@ -214,6 +238,13 @@ export type SubagentFnResult<
 export interface ChildSandboxReadySignalPayload {
   childWorkflowId: string;
   sandboxId: string;
+  /**
+   * Present only when the session captured a seed snapshot on this run
+   * (`continuation === "snapshot"` + fresh creation). Allows the parent to
+   * publish the reusable base snapshot to concurrent waiters without
+   * blocking on the child workflow's completion.
+   */
+  baseSnapshot?: SandboxSnapshot;
 }
 
 /**
@@ -228,6 +259,24 @@ export interface SubagentSessionInput {
   sandbox?: SandboxInit;
   /** Sandbox shutdown policy (default: "destroy") */
   sandboxShutdown?: SubagentSandboxShutdown;
-  /** Called by the session as soon as the sandbox is created, before the agent loop starts. */
-  onSandboxReady?: (sandboxId: string) => void;
+  /**
+   * Called by the session as soon as the sandbox is created, before the
+   * agent loop starts. `baseSnapshot` is populated only when the session
+   * captured a seed snapshot (fresh creation + `sandboxShutdown === "snapshot"`).
+   */
+  onSandboxReady?: (args: {
+    sandboxId: string;
+    baseSnapshot?: SandboxSnapshot;
+  }) => void;
+  /**
+   * Called by the session right before `runSession` returns. Installed by
+   * `defineSubagentWorkflow` to capture sandbox outputs and auto-forward
+   * them to the subagent's final result so user code never has to thread
+   * `sandboxId` / `snapshot` manually.
+   */
+  onSessionExit?: (result: {
+    sandboxId?: string;
+    snapshot?: SandboxSnapshot;
+    threadId: string;
+  }) => void;
 }

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,111 @@ 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> {
+      await assertThreadExists();
+      return redis.llen(redisKey);
+    },
+
+    async truncateFromId(messageId: string): Promise<void> {
+      await assertThreadExists();
+      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, idx - 1);
+        await redis.expire(redisKey, THREAD_TTL_SECONDS);
+      }
+      // 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

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