zeitlich 0.2.24 → 0.2.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zeitlich",
-  "version": "0.2.24",
+  "version": "0.2.26",
   "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/bedrock/filesystem.ts

@@ -67,8 +67,39 @@ export class BedrockSandboxFileSystem implements SandboxFileSystem {
     this.workspaceBase = posix.resolve("/", workspaceBase);
   }
 
+  /**
+   * Resolve a caller-supplied path to an absolute path within the workspace.
+   * Used for shell commands that need full paths.
+   */
   private normalisePath(path: string): string {
-    return posix.resolve(this.workspaceBase, path);
+    if (
+      posix.isAbsolute(path) &&
+      !path.startsWith(this.workspaceBase + "/") &&
+      path !== this.workspaceBase
+    ) {
+      path = path.replace(/^\/+/, "");
+    }
+    const resolved = posix.resolve(this.workspaceBase, path);
+    if (
+      !resolved.startsWith(this.workspaceBase + "/") &&
+      resolved !== this.workspaceBase
+    ) {
+      throw new Error(
+        `Invalid file path: "${resolved}" escapes workspace "${this.workspaceBase}"`
+      );
+    }
+    return resolved;
+  }
+
+  /**
+   * Return a workspace-relative path for Bedrock tool invocations
+   * (`writeFiles`, `readFiles`, `listFiles`, `removeFiles`), which
+   * reject absolute paths as "path traversal".
+   */
+  private toToolPath(path: string): string {
+    const abs = this.normalisePath(path);
+    const prefix = this.workspaceBase + "/";
+    return abs.startsWith(prefix) ? abs.slice(prefix.length) : abs;
   }
 
   private async invoke(
@@ -103,9 +134,9 @@ export class BedrockSandboxFileSystem implements SandboxFileSystem {
   }
 
   async readFile(path: string): Promise<string> {
-    const norm = this.normalisePath(path);
+    const rel = this.toToolPath(path);
     const result = await this.invoke("readFiles" as ToolNameType, {
-      paths: [norm],
+      paths: [rel],
     });
 
     for (const block of result.content ?? []) {
@@ -116,9 +147,9 @@ export class BedrockSandboxFileSystem implements SandboxFileSystem {
   }
 
   async readFileBuffer(path: string): Promise<Uint8Array> {
-    const norm = this.normalisePath(path);
+    const rel = this.toToolPath(path);
     const result = await this.invoke("readFiles" as ToolNameType, {
-      paths: [norm],
+      paths: [rel],
     });
 
     for (const block of result.content ?? []) {
@@ -132,12 +163,12 @@ export class BedrockSandboxFileSystem implements SandboxFileSystem {
   }
 
   async writeFile(path: string, content: string | Uint8Array): Promise<void> {
-    const norm = this.normalisePath(path);
+    const rel = this.toToolPath(path);
     const isText = typeof content === "string";
     const result = await this.invoke("writeFiles" as ToolNameType, {
       content: [
         {
-          path: norm,
+          path: rel,
           ...(isText
             ? { text: content as string }
             : { blob: content as Uint8Array }),
@@ -203,9 +234,9 @@ export class BedrockSandboxFileSystem implements SandboxFileSystem {
   }
 
   async readdir(path: string): Promise<string[]> {
-    const norm = this.normalisePath(path);
+    const rel = this.toToolPath(path);
     const result = await this.invoke("listFiles" as ToolNameType, {
-      directoryPath: norm,
+      directoryPath: rel,
     });
 
     const names: string[] = [];
@@ -215,6 +246,7 @@ export class BedrockSandboxFileSystem implements SandboxFileSystem {
 
     if (names.length > 0) return names;
 
+    const norm = this.normalisePath(path);
     const { stdout, exitCode, stderr } = await this.execShell(
       `ls -1A "${norm}"`
     );
@@ -264,8 +296,9 @@ export class BedrockSandboxFileSystem implements SandboxFileSystem {
       return;
     }
 
+    const rel = this.toToolPath(path);
     const result = await this.invoke("removeFiles" as ToolNameType, {
-      paths: [norm],
+      paths: [rel],
     });
     if (result.isError) {
       const msg =

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,223 @@
+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,
+} 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;
+}
+
+/**
+ * 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 }
+        : {}),
+    };
+    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,124 @@
+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 } 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;
+}
+
+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,
+}: AnthropicModelInvokerConfig) {
+  return async function invokeAnthropicModel(
+    config: ModelInvokerConfig,
+  ): Promise<AgentResponse<Anthropic.Messages.Message>> {
+    const { threadId, threadKey, state } = config;
+
+    const thread = createAnthropicThreadManager({ redis, threadId, key: threadKey });
+    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,
+  config,
+}: {
+  redis: Redis;
+  client: Anthropic;
+  model: string;
+  maxTokens?: number;
+  config: ModelInvokerConfig;
+}): Promise<AgentResponse<Anthropic.Messages.Message>> {
+  const invoker = createAnthropicModelInvoker({
+    redis,
+    client,
+    model,
+    maxTokens,
+  });
+  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>>;
+}