zeitlich 0.2.25 → 0.2.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zeitlich",
-  "version": "0.2.25",
+  "version": "0.2.27",
   "description": "[EXPERIMENTAL] An opinionated AI agent implementation for Temporal",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -67,6 +67,26 @@
         "default": "./dist/adapters/thread/google-genai/workflow.js"
       }
     },
+    "./adapters/thread/anthropic": {
+      "import": {
+        "types": "./dist/adapters/thread/anthropic/index.d.ts",
+        "default": "./dist/adapters/thread/anthropic/index.js"
+      },
+      "require": {
+        "types": "./dist/adapters/thread/anthropic/index.d.ts",
+        "default": "./dist/adapters/thread/anthropic/index.js"
+      }
+    },
+    "./adapters/thread/anthropic/workflow": {
+      "import": {
+        "types": "./dist/adapters/thread/anthropic/workflow.d.ts",
+        "default": "./dist/adapters/thread/anthropic/workflow.js"
+      },
+      "require": {
+        "types": "./dist/adapters/thread/anthropic/workflow.d.ts",
+        "default": "./dist/adapters/thread/anthropic/workflow.js"
+      }
+    },
     "./adapters/sandbox/inmemory": {
       "import": {
         "types": "./dist/adapters/sandbox/inmemory/index.d.ts",
@@ -190,6 +210,7 @@
     "node": ">=18"
   },
   "devDependencies": {
+    "@anthropic-ai/sdk": "^0.80.0",
     "@aws-sdk/client-bedrock-agentcore": "^3.900.0",
     "@daytonaio/sdk": "^0.149.0",
     "@e2b/code-interpreter": "^2.3.3",
@@ -210,6 +231,7 @@
     "vitest": "^4.0.18"
   },
   "peerDependencies": {
+    "@anthropic-ai/sdk": ">=0.50.0",
     "@aws-sdk/client-bedrock-agentcore": "^3.900.0",
     "@daytonaio/sdk": ">=0.153.0",
     "@e2b/code-interpreter": "^2.3.3",
@@ -225,6 +247,9 @@
     "@daytonaio/sdk": {
       "optional": true
     },
+    "@anthropic-ai/sdk": {
+      "optional": true
+    },
     "@google/genai": {
       "optional": true
     },

package/src/adapters/sandbox/virtual/with-virtual-sandbox.ts

@@ -1,6 +1,7 @@
 import type { WorkflowClient } from "@temporalio/client";
 import { queryParentWorkflowState } from "../../../lib/activity";
-import type { ActivityToolHandler } from "../../../lib/tool-router/types";
+import type { JsonValue } from "../../../lib/state/types";
+import type { ActivityToolHandler, RouterContext } from "../../../lib/tool-router/types";
 import type {
   FileEntryMetadata,
   TreeMutation,
@@ -47,17 +48,21 @@ export function withVirtualSandbox<
   TResult,
   TCtx,
   TMeta = FileEntryMetadata,
+  TToolResponse = JsonValue,
 >(
   client: WorkflowClient,
   provider: VirtualSandboxProvider<TCtx, TMeta>,
   handler: ActivityToolHandler<
     TArgs,
     TResult,
-    VirtualSandboxContext<TCtx, TMeta>
+    VirtualSandboxContext<TCtx, TMeta>,
+    TToolResponse
   >
 ): ActivityToolHandler<
   TArgs,
-  (TResult & { treeMutations: TreeMutation<TMeta>[] }) | null
+  (TResult & { treeMutations: TreeMutation<TMeta>[] }) | null,
+  RouterContext,
+  TToolResponse | string
 > {
   return async (args, context) => {
     const state =

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

@@ -0,0 +1,226 @@
+import type Redis from "ioredis";
+import type Anthropic from "@anthropic-ai/sdk";
+import type { ToolResultConfig } from "../../../lib/types";
+import type {
+  ActivityToolHandler,
+  RouterContext,
+  ToolHandlerResponse,
+} from "../../../lib/tool-router/types";
+import type {
+  ThreadOps,
+  PrefixedThreadOps,
+  ScopedPrefix,
+} from "../../../lib/session/types";
+import type { ModelInvoker } from "../../../lib/model";
+import {
+  createAnthropicThreadManager,
+  type AnthropicContent,
+  type AnthropicThreadManagerHooks,
+} from "./thread-manager";
+import {
+  createAnthropicModelInvoker,
+  type AnthropicModelInvokerConfig,
+} from "./model-invoker";
+
+const ADAPTER_PREFIX = "anthropic" as const;
+
+export type AnthropicThreadOps<TScope extends string = ""> =
+  PrefixedThreadOps<ScopedPrefix<TScope, typeof ADAPTER_PREFIX>, AnthropicContent>;
+
+export interface AnthropicAdapterConfig {
+  redis: Redis;
+  client: Anthropic;
+  /** Default model name (e.g. 'claude-sonnet-4-20250514'). If omitted, use `createModelInvoker()` */
+  model?: string;
+  /** Maximum tokens to generate. Defaults to 16384. */
+  maxTokens?: number;
+  hooks?: AnthropicThreadManagerHooks;
+}
+
+/**
+ * Tool response type accepted by the Anthropic adapter.
+ *
+ * Handlers can return:
+ * - **`string`** — plain text content for the tool result.
+ * - **`Anthropic.Messages.ToolResultBlockParam["content"]`** — array of content blocks
+ *   (e.g. `{ type: "text", text: "..." }`, `{ type: "image", source: { ... } }`).
+ *   Passed through as-is to the `tool_result` block.
+ */
+export type AnthropicToolResponse = Anthropic.Messages.ToolResultBlockParam["content"];
+
+export interface AnthropicAdapter {
+  /** Model invoker using the default model (only available when `model` was provided) */
+  invoker: ModelInvoker<Anthropic.Messages.Message>;
+  /** Create an invoker for a specific model name (for multi-model setups) */
+  createModelInvoker(
+    model: string,
+    maxTokens?: number,
+  ): ModelInvoker<Anthropic.Messages.Message>;
+  /**
+   * Create prefixed thread activities for registration on the worker.
+   *
+   * @param scope - Workflow name appended to the adapter prefix.
+   *   Use different scopes for the main agent vs subagents to avoid collisions.
+   *
+   * @example
+   * ```typescript
+   * adapter.createActivities("codingAgent")
+   * // → { anthropicCodingAgentInitializeThread, anthropicCodingAgentAppendHumanMessage, … }
+   *
+   * adapter.createActivities("researchAgent")
+   * // → { anthropicResearchAgentInitializeThread, … }
+   * ```
+   */
+  createActivities<S extends string = "">(
+    scope?: S,
+  ): AnthropicThreadOps<S>;
+
+  /**
+   * Identity wrapper that types a tool handler for this adapter.
+   * Constrains `toolResponse` to {@link AnthropicToolResponse}.
+   */
+  wrapHandler<TArgs, TResult, TContext extends RouterContext = RouterContext>(
+    handler: (
+      args: TArgs,
+      context: TContext,
+    ) => Promise<ToolHandlerResponse<TResult, AnthropicToolResponse>>,
+  ): ActivityToolHandler<TArgs, TResult, TContext, AnthropicToolResponse>;
+}
+
+/**
+ * Creates an Anthropic adapter that bundles thread operations and model
+ * invocation using the `@anthropic-ai/sdk`.
+ *
+ * Use `createActivities(scope)` to register scoped thread operations as
+ * Temporal activities on the worker. The `invoker` (or invokers created via
+ * `createModelInvoker`) should be wrapped with `createRunAgentActivity`.
+ *
+ * @example
+ * ```typescript
+ * import { createAnthropicAdapter } from 'zeitlich/adapters/thread/anthropic';
+ * import { createRunAgentActivity } from 'zeitlich';
+ * import Anthropic from '@anthropic-ai/sdk';
+ *
+ * const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+ * const adapter = createAnthropicAdapter({ redis, client, model: 'claude-sonnet-4-20250514' });
+ *
+ * export function createActivities(temporalClient: WorkflowClient) {
+ *   return {
+ *     ...adapter.createActivities("codingAgent"),
+ *     runCodingAgent: createRunAgentActivity(temporalClient, adapter.invoker),
+ *   };
+ * }
+ * ```
+ *
+ * @example Multi-agent worker (main + subagent share the adapter)
+ * ```typescript
+ * export function createActivities(temporalClient: WorkflowClient) {
+ *   return {
+ *     ...adapter.createActivities("codingAgent"),
+ *     ...adapter.createActivities("researchAgent"),
+ *     runCodingAgent: createRunAgentActivity(temporalClient, adapter.invoker),
+ *     runResearchAgent: createRunAgentActivity(
+ *       temporalClient,
+ *       adapter.createModelInvoker('claude-sonnet-4-20250514'),
+ *     ),
+ *   };
+ * }
+ * ```
+ */
+export function createAnthropicAdapter(
+  config: AnthropicAdapterConfig,
+): AnthropicAdapter {
+  const { redis, client } = config;
+
+  const threadOps: ThreadOps<AnthropicContent> = {
+    async initializeThread(threadId: string, threadKey?: string): Promise<void> {
+      const thread = createAnthropicThreadManager({ redis, threadId, key: threadKey });
+      await thread.initialize();
+    },
+
+    async appendHumanMessage(
+      threadId: string,
+      id: string,
+      content: AnthropicContent,
+      threadKey?: string,
+    ): Promise<void> {
+      const thread = createAnthropicThreadManager({ redis, threadId, key: threadKey });
+      await thread.appendUserMessage(id, content);
+    },
+
+    async appendSystemMessage(
+      threadId: string,
+      id: string,
+      content: string,
+      threadKey?: string,
+    ): Promise<void> {
+      const thread = createAnthropicThreadManager({ redis, threadId, key: threadKey });
+      await thread.appendSystemMessage(id, content);
+    },
+
+    async appendToolResult(id: string, cfg: ToolResultConfig): Promise<void> {
+      const { threadId, threadKey, toolCallId, toolName, content } = cfg;
+      const thread = createAnthropicThreadManager({ redis, threadId, key: threadKey });
+      await thread.appendToolResult(id, toolCallId, toolName, content);
+    },
+
+    async forkThread(
+      sourceThreadId: string,
+      targetThreadId: string,
+      threadKey?: string,
+    ): Promise<void> {
+      const thread = createAnthropicThreadManager({
+        redis,
+        threadId: sourceThreadId,
+        key: threadKey,
+      });
+      await thread.fork(targetThreadId);
+    },
+  };
+
+  function createActivities<S extends string = "">(
+    scope?: S,
+  ): AnthropicThreadOps<S> {
+    const prefix = scope
+      ? `${ADAPTER_PREFIX}${scope.charAt(0).toUpperCase()}${scope.slice(1)}`
+      : ADAPTER_PREFIX;
+    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]),
+    ) as AnthropicThreadOps<S>;
+  }
+
+  const makeInvoker = (
+    model: string,
+    maxTokens?: number,
+  ): ModelInvoker<Anthropic.Messages.Message> => {
+    const invokerConfig: AnthropicModelInvokerConfig = {
+      redis,
+      client,
+      model,
+      ...(maxTokens !== undefined ? { maxTokens } : {}),
+      ...(config.maxTokens !== undefined && maxTokens === undefined
+        ? { maxTokens: config.maxTokens }
+        : {}),
+      hooks: config.hooks,
+    };
+    return createAnthropicModelInvoker(invokerConfig);
+  };
+
+  const invoker: ModelInvoker<Anthropic.Messages.Message> = config.model
+    ? makeInvoker(config.model)
+    : ((() => {
+        throw new Error(
+          "No default model provided to createAnthropicAdapter. " +
+            "Either pass `model` in the config or use `createModelInvoker(model)` instead.",
+        );
+      }) as unknown as ModelInvoker<Anthropic.Messages.Message>);
+
+  return {
+    createActivities,
+    invoker,
+    createModelInvoker: makeInvoker,
+    wrapHandler: (handler) => handler,
+  };
+}

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

@@ -0,0 +1,44 @@
+/**
+ * Anthropic adapter for Zeitlich.
+ *
+ * Provides a unified adapter that bundles thread management and model
+ * invocation using the `@anthropic-ai/sdk`.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createAnthropicAdapter,
+ *   createAnthropicThreadManager,
+ * } from 'zeitlich/adapters/thread/anthropic';
+ * import Anthropic from '@anthropic-ai/sdk';
+ *
+ * const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+ * const adapter = createAnthropicAdapter({ redis, client, model: 'claude-sonnet-4-20250514' });
+ * ```
+ */
+
+// Adapter (primary API)
+export {
+  createAnthropicAdapter,
+  type AnthropicAdapter,
+  type AnthropicAdapterConfig,
+  type AnthropicThreadOps,
+  type AnthropicToolResponse,
+} from "./activities";
+
+// Thread manager
+export {
+  createAnthropicThreadManager,
+  type AnthropicThreadManager,
+  type AnthropicThreadManagerConfig,
+  type AnthropicContent,
+  type AnthropicInvocationPayload,
+  type StoredMessage,
+} from "./thread-manager";
+
+// Model invoker (for advanced use — prefer adapter.createModelInvoker)
+export {
+  createAnthropicModelInvoker,
+  invokeAnthropicModel,
+  type AnthropicModelInvokerConfig,
+} from "./model-invoker";

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

@@ -0,0 +1,129 @@
+import type Redis from "ioredis";
+import type Anthropic from "@anthropic-ai/sdk";
+import type { SerializableToolDefinition } from "../../../lib/types";
+import type { AgentResponse, ModelInvokerConfig } from "../../../lib/model";
+import { createAnthropicThreadManager, type AnthropicThreadManagerHooks } from "./thread-manager";
+import { v4 as uuidv4 } from "uuid";
+
+export interface AnthropicModelInvokerConfig {
+  redis: Redis;
+  client: Anthropic;
+  model: string;
+  /** Maximum tokens to generate. Defaults to 16384. */
+  maxTokens?: number;
+  hooks?: AnthropicThreadManagerHooks;
+}
+
+function toAnthropicTools(
+  tools: SerializableToolDefinition[],
+): Anthropic.Messages.Tool[] {
+  return tools.map((t) => ({
+    name: t.name,
+    description: t.description,
+    input_schema: t.schema as Anthropic.Messages.Tool.InputSchema,
+  }));
+}
+
+/**
+ * Creates an Anthropic model invoker that satisfies the generic
+ * `ModelInvoker<Anthropic.Messages.Message>` contract.
+ *
+ * Loads the conversation thread from Redis, invokes the Claude model via
+ * `client.messages.create`, appends the AI response, and returns
+ * a normalised AgentResponse.
+ *
+ * @example
+ * ```typescript
+ * import { createAnthropicModelInvoker } from 'zeitlich/adapters/thread/anthropic';
+ * import { createRunAgentActivity } from 'zeitlich';
+ * import Anthropic from '@anthropic-ai/sdk';
+ *
+ * const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+ * const invoker = createAnthropicModelInvoker({
+ *   redis,
+ *   client,
+ *   model: 'claude-sonnet-4-20250514',
+ * });
+ *
+ * return { runAgent: createRunAgentActivity(client, invoker) };
+ * ```
+ */
+export function createAnthropicModelInvoker({
+  redis,
+  client,
+  model,
+  maxTokens = 16384,
+  hooks,
+}: AnthropicModelInvokerConfig) {
+  return async function invokeAnthropicModel(
+    config: ModelInvokerConfig,
+  ): Promise<AgentResponse<Anthropic.Messages.Message>> {
+    const { threadId, threadKey, state } = config;
+
+    const thread = createAnthropicThreadManager({ redis, threadId, key: threadKey, hooks });
+    const { messages, system } = await thread.prepareForInvocation();
+
+    const anthropicTools = toAnthropicTools(state.tools);
+    const tools = anthropicTools.length > 0 ? anthropicTools : undefined;
+
+    const response = await client.messages.create({
+      model,
+      max_tokens: maxTokens,
+      messages,
+      ...(system ? { system } : {}),
+      ...(tools ? { tools } : {}),
+    });
+
+    await thread.appendAssistantMessage(uuidv4(), response.content);
+
+    const toolCalls = response.content.filter(
+      (block): block is Anthropic.Messages.ToolUseBlock =>
+        block.type === "tool_use",
+    );
+
+    return {
+      message: response,
+      rawToolCalls: toolCalls.map((tc) => ({
+        id: tc.id,
+        name: tc.name,
+        args: (tc.input as Record<string, unknown>) ?? {},
+      })),
+      usage: {
+        inputTokens: response.usage.input_tokens,
+        outputTokens: response.usage.output_tokens,
+        cachedWriteTokens: response.usage.cache_creation_input_tokens ?? undefined,
+        cachedReadTokens: response.usage.cache_read_input_tokens ?? undefined,
+      },
+    };
+  };
+}
+
+/**
+ * Standalone function for one-shot Anthropic model invocation.
+ * Convenience wrapper around createAnthropicModelInvoker for cases
+ * where you don't need to reuse the invoker.
+ */
+export async function invokeAnthropicModel({
+  redis,
+  client,
+  model,
+  maxTokens,
+  hooks,
+  config,
+}: {
+  redis: Redis;
+  client: Anthropic;
+  model: string;
+  maxTokens?: number;
+  hooks?: AnthropicThreadManagerHooks;
+  config: ModelInvokerConfig;
+}): Promise<AgentResponse<Anthropic.Messages.Message>> {
+  const invoker = createAnthropicModelInvoker({
+    redis,
+    client,
+    model,
+    maxTokens,
+    hooks,
+  });
+  return invoker(config);
+}

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

@@ -0,0 +1,33 @@
+/**
+ * Workflow-safe proxy for Anthropic thread operations.
+ *
+ * Import this from `zeitlich/adapters/thread/anthropic/workflow`
+ * in your Temporal workflow files.
+ *
+ * By default the scope is derived from `workflowInfo().workflowType`,
+ * so activities are automatically namespaced per workflow.
+ *
+ * @example
+ * ```typescript
+ * import { proxyAnthropicThreadOps } from 'zeitlich/adapters/thread/anthropic/workflow';
+ *
+ * // Auto-scoped to the current workflow name
+ * const threadOps = proxyAnthropicThreadOps();
+ *
+ * // Explicit scope override
+ * const threadOps = proxyAnthropicThreadOps("customScope");
+ * ```
+ */
+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";
+
+const ADAPTER_PREFIX = "anthropic";
+
+export function proxyAnthropicThreadOps(
+  scope?: string,
+  options?: Parameters<typeof createThreadOpsProxy>[2],
+): ActivityInterfaceFor<ThreadOps<AnthropicContent>> {
+  return createThreadOpsProxy(ADAPTER_PREFIX, scope, options) as ActivityInterfaceFor<ThreadOps<AnthropicContent>>;
+}

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

@@ -0,0 +1,137 @@
+import { describe, expect, it, vi } from "vitest";
+import type { StoredMessage } from "./thread-manager";
+import { createAnthropicThreadManager } from "./thread-manager";
+
+function createMockRedis(stored: StoredMessage[]) {
+  return {
+    exists: vi.fn().mockResolvedValue(1),
+    lrange: vi.fn().mockResolvedValue(stored.map((m) => JSON.stringify(m))),
+    del: vi.fn().mockResolvedValue(1),
+    set: vi.fn().mockResolvedValue("OK"),
+    rpush: vi.fn().mockResolvedValue(1),
+    expire: vi.fn().mockResolvedValue(1),
+    eval: vi.fn().mockResolvedValue(1),
+  };
+}
+
+const systemMsg: StoredMessage = {
+  id: "sys-1",
+  message: { role: "user", content: "You are helpful." },
+  isSystem: true,
+};
+
+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!" }] },
+};
+
+describe("Anthropic thread manager hooks", () => {
+  describe("onPrepareMessage", () => {
+    it("transforms stored messages before system extraction and merge", async () => {
+      const hook = vi.fn((msg: StoredMessage) => {
+        if (msg.isSystem) return msg;
+        const firstBlock = (msg.message.content as Array<{ text: string }>)[0];
+        return {
+          ...msg,
+          message: {
+            ...msg.message,
+            content: [{ type: "text" as const, text: `[modified] ${firstBlock?.text}` }],
+          },
+        };
+      });
+
+      const redis = createMockRedis([systemMsg, userMsg, assistantMsg]);
+      const tm = createAnthropicThreadManager({
+        redis: redis as never,
+        threadId: "t1",
+        hooks: { onPrepareMessage: hook },
+      });
+
+      const { messages, system } = await tm.prepareForInvocation();
+
+      expect(hook).toHaveBeenCalledTimes(3);
+      expect(hook).toHaveBeenCalledWith(systemMsg, 0, [systemMsg, userMsg, assistantMsg]);
+      expect(system).toBe("You are helpful.");
+      expect(messages[0]?.content).toEqual([{ type: "text", text: "[modified] Hello" }]);
+      expect(messages[1]?.content).toEqual([{ type: "text", text: "[modified] Hi there!" }]);
+    });
+
+    it("is not called when not configured", async () => {
+      const redis = createMockRedis([userMsg]);
+      const tm = createAnthropicThreadManager({
+        redis: redis as never,
+        threadId: "t1",
+      });
+
+      const { messages } = await tm.prepareForInvocation();
+      expect(messages).toHaveLength(1);
+    });
+  });
+
+  describe("onPreparedMessage", () => {
+    it("transforms SDK-native messages after merge", async () => {
+      const hook = vi.fn((msg) => ({
+        ...msg,
+        content: [{ type: "text" as const, text: "[post] done" }],
+      }));
+
+      const redis = createMockRedis([userMsg, assistantMsg]);
+      const tm = createAnthropicThreadManager({
+        redis: redis as never,
+        threadId: "t1",
+        hooks: { onPreparedMessage: hook },
+      });
+
+      const { messages } = await tm.prepareForInvocation();
+
+      expect(hook).toHaveBeenCalledTimes(2);
+      expect(messages[0]?.content).toEqual([{ type: "text", text: "[post] done" }]);
+    });
+
+    it("receives the full prepared messages array", async () => {
+      const hook = vi.fn((msg) => msg);
+
+      const redis = createMockRedis([userMsg, assistantMsg]);
+      const tm = createAnthropicThreadManager({
+        redis: redis as never,
+        threadId: "t1",
+        hooks: { onPreparedMessage: hook },
+      });
+
+      await tm.prepareForInvocation();
+
+      const args = hook.mock.calls[0] as unknown as [unknown, number, unknown[]];
+      expect(args[2]).toHaveLength(2);
+    });
+  });
+
+  describe("both hooks combined", () => {
+    it("runs onPrepareMessage before onPreparedMessage", async () => {
+      const order: string[] = [];
+
+      const redis = createMockRedis([userMsg]);
+      const tm = createAnthropicThreadManager({
+        redis: redis as never,
+        threadId: "t1",
+        hooks: {
+          onPrepareMessage: (msg) => {
+            order.push("pre");
+            return msg;
+          },
+          onPreparedMessage: (msg) => {
+            order.push("post");
+            return msg;
+          },
+        },
+      });
+
+      await tm.prepareForInvocation();
+      expect(order).toEqual(["pre", "post"]);
+    });
+  });
+});