zeitlich 0.2.38 → 0.2.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zeitlich",
-  "version": "0.2.38",
+  "version": "0.2.40",
   "description": "[EXPERIMENTAL] An opinionated AI agent implementation for Temporal",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -27,6 +27,16 @@
         "default": "./dist/workflow.js"
       }
     },
+    "./adapters/thread": {
+      "import": {
+        "types": "./dist/adapters/thread/index.d.ts",
+        "default": "./dist/adapters/thread/index.js"
+      },
+      "require": {
+        "types": "./dist/adapters/thread/index.d.ts",
+        "default": "./dist/adapters/thread/index.js"
+      }
+    },
     "./adapters/thread/langchain": {
       "import": {
         "types": "./dist/adapters/thread/langchain/index.d.ts",

package/src/adapters/thread/adapter-id.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect, expectTypeOf } from "vitest";
+import { ADAPTER_ID as LANGCHAIN } from "./langchain/adapter-id";
+import { ADAPTER_ID as GOOGLE_GENAI } from "./google-genai/adapter-id";
+import { ADAPTER_ID as ANTHROPIC } from "./anthropic/adapter-id";
+import {
+  LANGCHAIN_ADAPTER_ID,
+  GOOGLE_GENAI_ADAPTER_ID,
+  ANTHROPIC_ADAPTER_ID,
+  type ThreadAdapterId,
+} from "./index";
+
+describe("thread adapter identity", () => {
+  it("langchain ADAPTER_ID is the wire-format string", () => {
+    expect(LANGCHAIN).toBe("langChain");
+    expect(LANGCHAIN_ADAPTER_ID).toBe("langChain");
+  });
+
+  it("google-genai ADAPTER_ID is the wire-format string", () => {
+    expect(GOOGLE_GENAI).toBe("googleGenAI");
+    expect(GOOGLE_GENAI_ADAPTER_ID).toBe("googleGenAI");
+  });
+
+  it("anthropic ADAPTER_ID is the wire-format string", () => {
+    expect(ANTHROPIC).toBe("anthropic");
+    expect(ANTHROPIC_ADAPTER_ID).toBe("anthropic");
+  });
+
+  it("ADAPTER_ID values narrow to string literals, not `string`", () => {
+    expectTypeOf(LANGCHAIN).toEqualTypeOf<"langChain">();
+    expectTypeOf(GOOGLE_GENAI).toEqualTypeOf<"googleGenAI">();
+    expectTypeOf(ANTHROPIC).toEqualTypeOf<"anthropic">();
+  });
+
+  it("ThreadAdapterId is the discriminated union of every built-in id", () => {
+    const allow = (_id: ThreadAdapterId): void => undefined;
+    allow(LANGCHAIN);
+    allow(GOOGLE_GENAI);
+    allow(ANTHROPIC);
+    // @ts-expect-error — arbitrary strings aren't members of the union
+    allow("someOtherAdapter");
+  });
+});

package/src/adapters/thread/anthropic/activities.ts

@@ -1,6 +1,7 @@
 import type Redis from "ioredis";
 import type Anthropic from "@anthropic-ai/sdk";
 import type { ToolResultConfig } from "../../../lib/types";
+import type { PersistedThreadState } from "../../../lib/state/types";
 import type {
   ActivityToolHandler,
   RouterContext,
@@ -22,11 +23,10 @@ import {
   createAnthropicModelInvoker,
   type AnthropicModelInvokerConfig,
 } from "./model-invoker";
-
-const ADAPTER_PREFIX = "anthropic" as const;
+import { ADAPTER_ID } from "./adapter-id";
 
 export type AnthropicThreadOps<TScope extends string = ""> = PrefixedThreadOps<
-  ScopedPrefix<TScope, typeof ADAPTER_PREFIX>,
+  ScopedPrefix<TScope, typeof ADAPTER_ID>,
   AnthropicContent
 >;
 
@@ -209,17 +209,43 @@ export function createAnthropicAdapter(
         redis,
         threadId: sourceThreadId,
         key: threadKey,
+        hooks: config.hooks,
       });
       await thread.fork(targetThreadId);
     },
 
     async truncateThread(
       threadId: string,
-      length: number,
+      messageId: string,
       threadKey?: string,
     ): Promise<void> {
       const thread = createAnthropicThreadManager({ redis, threadId, key: threadKey });
-      await thread.truncate(length);
+      await thread.truncateFromId(messageId);
+    },
+
+    async loadThreadState(
+      threadId: string,
+      threadKey?: string
+    ): Promise<PersistedThreadState | null> {
+      const thread = createAnthropicThreadManager({
+        redis,
+        threadId,
+        key: threadKey,
+      });
+      return thread.loadState();
+    },
+
+    async saveThreadState(
+      threadId: string,
+      state: PersistedThreadState,
+      threadKey?: string
+    ): Promise<void> {
+      const thread = createAnthropicThreadManager({
+        redis,
+        threadId,
+        key: threadKey,
+      });
+      await thread.saveState(state);
     },
   };
 
@@ -227,8 +253,8 @@ export function createAnthropicAdapter(
     scope?: S
   ): AnthropicThreadOps<S> {
     const prefix = scope
-      ? `${ADAPTER_PREFIX}${scope.charAt(0).toUpperCase()}${scope.slice(1)}`
-      : ADAPTER_PREFIX;
+      ? `${ADAPTER_ID}${scope.charAt(0).toUpperCase()}${scope.slice(1)}`
+      : ADAPTER_ID;
     const cap = (s: string): string => s.charAt(0).toUpperCase() + s.slice(1);
     return Object.fromEntries(
       Object.entries(threadOps).map(([k, v]) => [`${prefix}${cap(k)}`, v])

package/src/adapters/thread/anthropic/adapter-id.ts

@@ -0,0 +1,16 @@
+/**
+ * Public adapter identity for the Anthropic thread adapter.
+ *
+ * This value is wire format — it appears as the prefix for Temporal
+ * activity names (e.g. `anthropicCodingAgentInitializeThread`) and must
+ * never change, since renaming it would orphan existing persisted
+ * threads and break in-flight workflows.
+ *
+ * Re-exported from `zeitlich/adapters/thread/anthropic` so downstream
+ * consumers can use the exact same literal the adapter uses internally,
+ * typed as the narrow string literal `"anthropic"`.
+ */
+export const ADAPTER_ID = "anthropic" as const;
+
+/** Narrow string-literal type for {@link ADAPTER_ID}. */
+export type AdapterId = typeof ADAPTER_ID;

package/src/adapters/thread/anthropic/fork-transform.test.ts

@@ -0,0 +1,291 @@
+import { describe, expect, it, vi } from "vitest";
+import type { StoredMessage } from "./thread-manager";
+import { createAnthropicThreadManager } from "./thread-manager";
+
+// ---------------------------------------------------------------------------
+// Stateful in-memory Redis mock sufficient for fork / replaceAll flows.
+// Only the commands used by createThreadManager are implemented.
+// ---------------------------------------------------------------------------
+
+function createStatefulRedis() {
+  const lists = new Map<string, string[]>();
+  const strings = new Map<string, string>();
+
+  return {
+    exists: vi.fn(async (...keys: string[]) =>
+      keys.reduce(
+        (acc, k) => acc + (lists.has(k) || strings.has(k) ? 1 : 0),
+        0
+      )
+    ),
+    lrange: vi.fn(async (key: string, start: number, stop: number) => {
+      const list = lists.get(key) ?? [];
+      const end = stop === -1 ? list.length : stop + 1;
+      return list.slice(start, end);
+    }),
+    rpush: vi.fn(async (key: string, ...values: string[]) => {
+      const list = lists.get(key) ?? [];
+      list.push(...values);
+      lists.set(key, list);
+      return list.length;
+    }),
+    ltrim: vi.fn(async (key: string, start: number, stop: number) => {
+      const list = lists.get(key) ?? [];
+      const end = stop === -1 ? list.length : stop + 1;
+      lists.set(key, list.slice(start, end));
+      return "OK";
+    }),
+    del: vi.fn(async (...keys: string[]) => {
+      let removed = 0;
+      for (const k of keys) {
+        if (lists.delete(k)) removed++;
+        if (strings.delete(k)) removed++;
+      }
+      return removed;
+    }),
+    set: vi.fn(async (key: string, value: string) => {
+      strings.set(key, value);
+      return "OK";
+    }),
+    get: vi.fn(async (key: string) => strings.get(key) ?? null),
+    expire: vi.fn(async (_key: string, _ttl: number) => 1),
+    llen: vi.fn(async (key: string) => (lists.get(key) ?? []).length),
+    eval: vi.fn(
+      async (_script: string, _numKeys: number, ...args: string[]) => {
+        const [dedupKey, listKey, , ...serialised] = args;
+        if (!dedupKey || !listKey) return 0;
+        if (strings.has(dedupKey)) return 0;
+        const list = lists.get(listKey) ?? [];
+        list.push(...serialised);
+        lists.set(listKey, list);
+        strings.set(dedupKey, "1");
+        return 1;
+      }
+    ),
+    __peek: {
+      list: (key: string): string[] => [...(lists.get(key) ?? [])],
+      strings,
+    },
+  };
+}
+
+const userMsg: StoredMessage = {
+  id: "msg-1",
+  message: { role: "user", content: [{ type: "text", text: "Hello" }] },
+};
+
+const assistantMsg: StoredMessage = {
+  id: "msg-2",
+  message: {
+    role: "assistant",
+    content: [{ type: "text", text: "Hi there!" }],
+  },
+};
+
+const userMsg2: StoredMessage = {
+  id: "msg-3",
+  message: { role: "user", content: [{ type: "text", text: "Again please" }] },
+};
+
+async function seedSource(
+  redis: ReturnType<typeof createStatefulRedis>,
+  threadId: string,
+  messages: StoredMessage[]
+): Promise<void> {
+  const tm = createAnthropicThreadManager({
+    redis: redis as never,
+    threadId,
+  });
+  await tm.initialize();
+  await tm.append(messages);
+}
+
+describe("Anthropic fork + transform hooks", () => {
+  it("behaves like fork when neither onFork hook is configured", async () => {
+    const redis = createStatefulRedis();
+    await seedSource(redis, "src", [userMsg, assistantMsg]);
+
+    const tm = createAnthropicThreadManager({
+      redis: redis as never,
+      threadId: "src",
+    });
+    const forked = await tm.fork("dst");
+    const loaded = await forked.load();
+
+    expect(loaded).toEqual([userMsg, assistantMsg]);
+
+    // Source is untouched
+    const srcLoaded = await tm.load();
+    expect(srcLoaded).toEqual([userMsg, assistantMsg]);
+  });
+
+  it("applies onForkTransform alone as a per-message map", async () => {
+    const redis = createStatefulRedis();
+    await seedSource(redis, "src", [userMsg, assistantMsg, userMsg2]);
+
+    const calls: Array<{
+      idx: number;
+      id: string;
+      total: number;
+    }> = [];
+    const onForkTransform = vi.fn(
+      (msg: StoredMessage, index: number, messages: readonly StoredMessage[]) => {
+        calls.push({ idx: index, id: msg.id, total: messages.length });
+        const firstBlock = (msg.message.content as Array<{ text?: string }>)[0];
+        return {
+          ...msg,
+          message: {
+            ...msg.message,
+            content: [
+              {
+                type: "text" as const,
+                text: `[T${index}] ${firstBlock?.text ?? ""}`,
+              },
+            ],
+          },
+        };
+      }
+    );
+
+    const tm = createAnthropicThreadManager({
+      redis: redis as never,
+      threadId: "src",
+      hooks: { onForkTransform },
+    });
+    const forked = await tm.fork("dst");
+    const loaded = await forked.load();
+
+    expect(onForkTransform).toHaveBeenCalledTimes(3);
+    expect(calls).toEqual([
+      { idx: 0, id: "msg-1", total: 3 },
+      { idx: 1, id: "msg-2", total: 3 },
+      { idx: 2, id: "msg-3", total: 3 },
+    ]);
+    expect(loaded).toHaveLength(3);
+    expect(loaded[0]?.message.content).toEqual([
+      { type: "text", text: "[T0] Hello" },
+    ]);
+    expect(loaded[1]?.message.content).toEqual([
+      { type: "text", text: "[T1] Hi there!" },
+    ]);
+    expect(loaded[2]?.message.content).toEqual([
+      { type: "text", text: "[T2] Again please" },
+    ]);
+
+    // Source is unchanged.
+    const srcLoaded = await tm.load();
+    expect(srcLoaded.map((m) => m.id)).toEqual(["msg-1", "msg-2", "msg-3"]);
+  });
+
+  it("applies onForkPrepareThread alone and may change list length", async () => {
+    const redis = createStatefulRedis();
+    await seedSource(redis, "src", [userMsg, assistantMsg, userMsg2]);
+
+    const onForkPrepareThread = vi.fn(
+      async (messages: readonly StoredMessage[]) =>
+        // Drop first message and prepend a summary.
+        [
+          {
+            id: "summary-1",
+            message: {
+              role: "user" as const,
+              content: [{ type: "text" as const, text: "[summary]" }],
+            },
+          },
+          ...messages.slice(1),
+        ]
+    );
+
+    const tm = createAnthropicThreadManager({
+      redis: redis as never,
+      threadId: "src",
+      hooks: { onForkPrepareThread },
+    });
+    const forked = await tm.fork("dst");
+    const loaded = await forked.load();
+
+    expect(onForkPrepareThread).toHaveBeenCalledTimes(1);
+    expect(loaded.map((m) => m.id)).toEqual(["summary-1", "msg-2", "msg-3"]);
+  });
+
+  it("runs onForkPrepareThread before onForkTransform and passes prepared list as messages", async () => {
+    const redis = createStatefulRedis();
+    await seedSource(redis, "src", [userMsg, assistantMsg, userMsg2]);
+
+    const order: string[] = [];
+    const indicesSeen: Array<{ idx: number; total: number; id: string }> = [];
+
+    const onForkPrepareThread = vi.fn(
+      async (messages: readonly StoredMessage[]) => {
+        order.push("prepare");
+        // Drop the last message (length changes).
+        return messages.slice(0, -1);
+      }
+    );
+
+    const onForkTransform = vi.fn(
+      (
+        msg: StoredMessage,
+        index: number,
+        messages: readonly StoredMessage[]
+      ) => {
+        order.push("transform");
+        indicesSeen.push({ idx: index, total: messages.length, id: msg.id });
+        return {
+          ...msg,
+          message: {
+            ...msg.message,
+            content: [{ type: "text" as const, text: `[x${index}]` }],
+          },
+        };
+      }
+    );
+
+    const tm = createAnthropicThreadManager({
+      redis: redis as never,
+      threadId: "src",
+      hooks: { onForkPrepareThread, onForkTransform },
+    });
+    const forked = await tm.fork("dst");
+    const loaded = await forked.load();
+
+    // prepare runs once, transform once per survivor.
+    expect(order).toEqual(["prepare", "transform", "transform"]);
+    expect(indicesSeen).toEqual([
+      { idx: 0, total: 2, id: "msg-1" },
+      { idx: 1, total: 2, id: "msg-2" },
+    ]);
+    expect(loaded).toHaveLength(2);
+    expect(loaded[0]?.message.content).toEqual([{ type: "text", text: "[x0]" }]);
+    expect(loaded[1]?.message.content).toEqual([{ type: "text", text: "[x1]" }]);
+  });
+
+  it("leaves dedup markers cleared so the transformed thread can accept replays", async () => {
+    const redis = createStatefulRedis();
+    await seedSource(redis, "src", [userMsg, assistantMsg]);
+
+    const onForkTransform = vi.fn(
+      (msg: StoredMessage) => ({
+        ...msg,
+        message: {
+          ...msg.message,
+          content: [{ type: "text" as const, text: "[replaced]" }],
+        },
+      })
+    );
+
+    const tm = createAnthropicThreadManager({
+      redis: redis as never,
+      threadId: "src",
+      hooks: { onForkTransform },
+    });
+    await tm.fork("dst");
+
+    // After replaceAll, dedup markers from the pre-replacement writes must be
+    // gone — otherwise an append with the same id would be silently skipped.
+    const lingering = Array.from(redis.__peek.strings.keys()).filter((k) =>
+      k.startsWith("messages:thread:dst:dedup:")
+    );
+    expect(lingering).toEqual([]);
+  });
+});

package/src/adapters/thread/anthropic/index.ts

@@ -17,6 +17,9 @@
  * ```
  */
 
+// Adapter identity (wire format — matches Temporal activity-name prefix)
+export { ADAPTER_ID, type AdapterId } from "./adapter-id";
+
 // Adapter (primary API)
 export {
   createAnthropicAdapter,

package/src/adapters/thread/anthropic/model-invoker.ts

@@ -61,7 +61,7 @@ export function createAnthropicModelInvoker({
   return async function invokeAnthropicModel(
     config: ModelInvokerConfig
   ): Promise<AgentResponse<Anthropic.Messages.Message>> {
-    const { threadId, threadKey, state } = config;
+    const { threadId, threadKey, state, assistantMessageId } = config;
     const { heartbeat, signal } = getActivityContext();
 
     const thread = createAnthropicThreadManager({
@@ -70,8 +70,13 @@ export function createAnthropicModelInvoker({
       key: threadKey,
       hooks,
     });
-    const { messages, system, storedLength } =
-      await thread.prepareForInvocation();
+    // Truncate the thread starting at the id the assistant message
+    // will be stored under. On the happy path this is a no-op; on a
+    // rewind retry or a Temporal workflow reset it wipes the prior
+    // attempt's assistant + tool results so the LLM sees the same
+    // pre-call state that it saw originally.
+    await thread.truncateFromId(assistantMessageId);
+    const { messages, system } = await thread.prepareForInvocation();
 
     const anthropicTools = toAnthropicTools(state.tools);
     const tools = anthropicTools.length > 0 ? anthropicTools : undefined;
@@ -111,7 +116,6 @@ export function createAnthropicModelInvoker({
           response.usage.cache_creation_input_tokens ?? undefined,
         cachedReadTokens: response.usage.cache_read_input_tokens ?? undefined,
       },
-      threadLengthAtCall: storedLength,
     };
   };
 }

package/src/adapters/thread/anthropic/proxy.ts

@@ -22,15 +22,16 @@ import { type ActivityInterfaceFor } from "@temporalio/workflow";
 import type { ThreadOps } from "../../../lib/session/types";
 import type { AnthropicContent } from "./thread-manager";
 import { createThreadOpsProxy } from "../../../lib/thread/proxy";
+import { ADAPTER_ID } from "./adapter-id";
 
-const ADAPTER_PREFIX = "anthropic";
+export { ADAPTER_ID, type AdapterId } from "./adapter-id";
 
 export function proxyAnthropicThreadOps(
   scope?: string,
   options?: Parameters<typeof createThreadOpsProxy>[2]
 ): ActivityInterfaceFor<ThreadOps<AnthropicContent>> {
   return createThreadOpsProxy(
-    ADAPTER_PREFIX,
+    ADAPTER_ID,
     scope,
     options
   ) as ActivityInterfaceFor<ThreadOps<AnthropicContent>>;

package/src/adapters/thread/anthropic/thread-manager.ts

@@ -41,8 +41,6 @@ export interface AnthropicThreadManagerConfig {
 export interface AnthropicInvocationPayload {
   messages: Anthropic.Messages.MessageParam[];
   system?: string | Anthropic.Messages.TextBlockParam[];
-  /** Number of stored messages loaded from Redis before preparation. */
-  storedLength: number;
 }
 
 /** Thread manager with Anthropic MessageParam convenience helpers */
@@ -222,10 +220,35 @@ export function createAnthropicThreadManager(
           ? messages.map((msg, i) => onPreparedMessage(msg, i, messages))
           : messages,
         ...(system ? { system } : {}),
-        storedLength: stored.length,
       };
     },
   };
 
-  return Object.assign(base, helpers);
+  const manager = Object.assign(base, helpers);
+
+  const originalFork = manager.fork.bind(manager);
+  manager.fork = async (
+    newThreadId: string
+  ): Promise<AnthropicThreadManager> => {
+    await originalFork(newThreadId);
+    const forked = createAnthropicThreadManager({
+      ...config,
+      threadId: newThreadId,
+    });
+    const { onForkPrepareThread, onForkTransform } = config.hooks ?? {};
+    if (!onForkPrepareThread && !onForkTransform) {
+      return forked;
+    }
+    let next = await forked.load();
+    if (onForkPrepareThread) {
+      next = await onForkPrepareThread(next);
+    }
+    if (onForkTransform) {
+      next = next.map((msg, i) => onForkTransform(msg, i, next));
+    }
+    await forked.replaceAll(next);
+    return forked;
+  };
+
+  return manager;
 }

package/src/adapters/thread/google-genai/activities.ts

@@ -1,6 +1,7 @@
 import type Redis from "ioredis";
 import type { GoogleGenAI, Content, Part } from "@google/genai";
 import type { ToolResultConfig } from "../../../lib/types";
+import type { PersistedThreadState } from "../../../lib/state/types";
 import type {
   ActivityToolHandler,
   RouterContext,
@@ -19,12 +20,11 @@ import {
   type GoogleGenAIThreadManagerHooks,
 } from "./thread-manager";
 import { createGoogleGenAIModelInvoker } from "./model-invoker";
-
-const ADAPTER_PREFIX = "googleGenAI" as const;
+import { ADAPTER_ID } from "./adapter-id";
 
 export type GoogleGenAIThreadOps<TScope extends string = ""> =
   PrefixedThreadOps<
-    ScopedPrefix<TScope, typeof ADAPTER_PREFIX>,
+    ScopedPrefix<TScope, typeof ADAPTER_ID>,
     GoogleGenAIContent
   >;
 
@@ -219,13 +219,14 @@ export function createGoogleGenAIAdapter(
         redis,
         threadId: sourceThreadId,
         key: threadKey,
+        hooks: config.hooks,
       });
       await thread.fork(targetThreadId);
     },
 
     async truncateThread(
       threadId: string,
-      length: number,
+      messageId: string,
       threadKey?: string,
     ): Promise<void> {
       const thread = createGoogleGenAIThreadManager({
@@ -233,7 +234,32 @@ export function createGoogleGenAIAdapter(
         threadId,
         key: threadKey,
       });
-      await thread.truncate(length);
+      await thread.truncateFromId(messageId);
+    },
+
+    async loadThreadState(
+      threadId: string,
+      threadKey?: string
+    ): Promise<PersistedThreadState | null> {
+      const thread = createGoogleGenAIThreadManager({
+        redis,
+        threadId,
+        key: threadKey,
+      });
+      return thread.loadState();
+    },
+
+    async saveThreadState(
+      threadId: string,
+      state: PersistedThreadState,
+      threadKey?: string
+    ): Promise<void> {
+      const thread = createGoogleGenAIThreadManager({
+        redis,
+        threadId,
+        key: threadKey,
+      });
+      await thread.saveState(state);
     },
   };
 
@@ -241,8 +267,8 @@ export function createGoogleGenAIAdapter(
     scope?: S
   ): GoogleGenAIThreadOps<S> {
     const prefix = scope
-      ? `${ADAPTER_PREFIX}${scope.charAt(0).toUpperCase()}${scope.slice(1)}`
-      : ADAPTER_PREFIX;
+      ? `${ADAPTER_ID}${scope.charAt(0).toUpperCase()}${scope.slice(1)}`
+      : ADAPTER_ID;
     const cap = (s: string): string => s.charAt(0).toUpperCase() + s.slice(1);
     return Object.fromEntries(
       Object.entries(threadOps).map(([k, v]) => [`${prefix}${cap(k)}`, v])

package/src/adapters/thread/google-genai/adapter-id.ts

@@ -0,0 +1,16 @@
+/**
+ * Public adapter identity for the Google GenAI thread adapter.
+ *
+ * This value is wire format — it appears as the prefix for Temporal
+ * activity names (e.g. `googleGenAICodingAgentInitializeThread`) and
+ * must never change, since renaming it would orphan existing persisted
+ * threads and break in-flight workflows.
+ *
+ * Re-exported from `zeitlich/adapters/thread/google-genai` so downstream
+ * consumers can use the exact same literal the adapter uses internally,
+ * typed as the narrow string literal `"googleGenAI"`.
+ */
+export const ADAPTER_ID = "googleGenAI" as const;
+
+/** Narrow string-literal type for {@link ADAPTER_ID}. */
+export type AdapterId = typeof ADAPTER_ID;