zeitlich 0.2.45 → 0.2.47

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zeitlich",
-  "version": "0.2.45",
+  "version": "0.2.47",
   "description": "[EXPERIMENTAL] An opinionated AI agent implementation for Temporal",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -181,7 +181,8 @@
     "release:pr:dry": "release-please release-pr --repo-url=bead-ai/zeitlich --token=$GITHUB_TOKEN --dry-run",
     "release:github": "release-please github-release --repo-url=bead-ai/zeitlich --token=$GITHUB_TOKEN",
     "release:npm": "npm publish --access public",
-    "release:publish": "npm run release:github && npm run release:npm"
+    "release:publish": "npm run release:github && npm run release:npm",
+    "eval:edit": "node scripts/run-edit-tool-evals.mjs"
   },
   "keywords": [
     "ai",
@@ -200,7 +201,9 @@
     "node": ">=18"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "^0.93.0",
+    "@anthropic-ai/sdk": "^0.98.0",
+    "@aws-sdk/client-s3": "^3.1000.0",
+    "@aws-sdk/lib-storage": "^3.1000.0",
     "@daytonaio/sdk": "^0.171.0",
     "@e2b/code-interpreter": "^2.3.3",
     "@eslint/js": "^10.0.1",
@@ -223,6 +226,8 @@
   },
   "peerDependencies": {
     "@anthropic-ai/sdk": ">=0.50.0",
+    "@aws-sdk/client-s3": ">=3.700.0",
+    "@aws-sdk/lib-storage": ">=3.700.0",
     "@daytonaio/sdk": ">=0.153.0",
     "@e2b/code-interpreter": "^2.3.3",
     "@google/genai": "^1.43.0",
@@ -241,6 +246,12 @@
     "@anthropic-ai/sdk": {
       "optional": true
     },
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "@aws-sdk/lib-storage": {
+      "optional": true
+    },
     "@google/genai": {
       "optional": true
     },

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

@@ -13,16 +13,21 @@ import type {
   ScopedPrefix,
 } from "../../../lib/session/types";
 import type { ModelInvoker } from "../../../lib/model";
+import { createTieredThreadManager } from "../../../lib/thread/tiered";
+import type { ColdThreadStore } from "../../../lib/thread/cold-store";
 import {
   createAnthropicThreadManager,
+  storedMessageId,
   type AnthropicContent,
   type AnthropicSystemContent,
   type AnthropicThreadManagerHooks,
+  type StoredMessage,
 } from "./thread-manager";
 import {
   createAnthropicModelInvoker,
   type AnthropicModelInvokerConfig,
 } from "./model-invoker";
+import type { AnthropicPromptCacheConfig } from "./prompt-cache";
 import { ADAPTER_ID } from "./adapter-id";
 
 export type AnthropicThreadOps<TScope extends string = ""> = PrefixedThreadOps<
@@ -37,7 +42,26 @@ export interface AnthropicAdapterConfig {
   model?: string;
   /** Maximum tokens to generate. Defaults to 16384. */
   maxTokens?: number;
+  /**
+   * Controls Anthropic/Bedrock-compatible prompt caching. Defaults to enabled
+   * with an explicit 5 minute TTL. Set to `false` to disable.
+   */
+  promptCache?: AnthropicPromptCacheConfig;
   hooks?: AnthropicThreadManagerHooks;
+  /**
+   * Optional durable cold tier (e.g. S3, R2, GCS). When provided,
+   * the session will hydrate the thread from cold storage on entry
+   * (`continue`/`fork` modes) and flush it back on every exit path.
+   * When omitted, the adapter is Redis-only and `hydrateThread`/
+   * `flushThread` activities are no-ops.
+   */
+  coldStore?: ColdThreadStore;
+  /**
+   * Override the default Redis TTL (90 days) for thread keys. When
+   * pairing the adapter with a `coldStore`, a shorter TTL (hours)
+   * is typically more appropriate.
+   */
+  ttlSeconds?: number;
 }
 
 /**
@@ -58,7 +82,8 @@ export interface AnthropicAdapter {
   /** Create an invoker for a specific model name (for multi-model setups) */
   createModelInvoker(
     model: string,
-    maxTokens?: number
+    maxTokens?: number,
+    promptCache?: AnthropicPromptCacheConfig
   ): ModelInvoker<Anthropic.Messages.Message>;
   /**
    * Create prefixed thread activities for registration on the worker.
@@ -135,16 +160,41 @@ export function createAnthropicAdapter(
 ): AnthropicAdapter {
   const { redis, client } = config;
 
+  /**
+   * Common per-call config plumbed into both the provider thread
+   * manager (for message I/O) and the tiered base manager (for
+   * hot↔cold lifecycle ops). Keeping them in lockstep means a single
+   * `coldStore` / `ttlSeconds` configuration controls every Redis
+   * write the adapter does.
+   */
+  const baseExtras = {
+    ...(config.ttlSeconds !== undefined && { ttlSeconds: config.ttlSeconds }),
+  };
+
+  const makeProviderThread = (threadId: string, threadKey?: string) =>
+    createAnthropicThreadManager({
+      redis,
+      threadId,
+      key: threadKey,
+      ...baseExtras,
+    });
+
+  const makeTieredBase = (threadId: string, threadKey?: string) =>
+    createTieredThreadManager<StoredMessage>({
+      redis,
+      threadId,
+      key: threadKey,
+      idOf: storedMessageId,
+      ...baseExtras,
+      ...(config.coldStore && { coldStore: config.coldStore }),
+    });
+
   const threadOps: ThreadOps<AnthropicContent> = {
     async initializeThread(
       threadId: string,
       threadKey?: string
     ): Promise<void> {
-      const thread = createAnthropicThreadManager({
-        redis,
-        threadId,
-        key: threadKey,
-      });
+      const thread = makeProviderThread(threadId, threadKey);
       await thread.initialize();
     },
 
@@ -154,11 +204,7 @@ export function createAnthropicAdapter(
       content: AnthropicContent,
       threadKey?: string
     ): Promise<void> {
-      const thread = createAnthropicThreadManager({
-        redis,
-        threadId,
-        key: threadKey,
-      });
+      const thread = makeProviderThread(threadId, threadKey);
       await thread.appendUserMessage(id, content);
     },
 
@@ -168,21 +214,13 @@ export function createAnthropicAdapter(
       content: AnthropicSystemContent,
       threadKey?: string
     ): Promise<void> {
-      const thread = createAnthropicThreadManager({
-        redis,
-        threadId,
-        key: threadKey,
-      });
+      const thread = makeProviderThread(threadId, 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,
-      });
+      const thread = makeProviderThread(threadId, threadKey);
       await thread.appendToolResult(id, toolCallId, toolName, content);
     },
 
@@ -192,11 +230,7 @@ export function createAnthropicAdapter(
       message: Anthropic.Messages.Message,
       threadKey?: string
     ): Promise<void> {
-      const thread = createAnthropicThreadManager({
-        redis,
-        threadId,
-        key: threadKey,
-      });
+      const thread = makeProviderThread(threadId, threadKey);
       await thread.appendAssistantMessage(id, message.content);
     },
 
@@ -210,6 +244,7 @@ export function createAnthropicAdapter(
         threadId: sourceThreadId,
         key: threadKey,
         hooks: config.hooks,
+        ...baseExtras,
       });
       await thread.fork(targetThreadId);
     },
@@ -217,9 +252,9 @@ export function createAnthropicAdapter(
     async truncateThread(
       threadId: string,
       messageId: string,
-      threadKey?: string,
+      threadKey?: string
     ): Promise<void> {
-      const thread = createAnthropicThreadManager({ redis, threadId, key: threadKey });
+      const thread = makeProviderThread(threadId, threadKey);
       await thread.truncateFromId(messageId);
     },
 
@@ -227,11 +262,7 @@ export function createAnthropicAdapter(
       threadId: string,
       threadKey?: string
     ): Promise<PersistedThreadState | null> {
-      const thread = createAnthropicThreadManager({
-        redis,
-        threadId,
-        key: threadKey,
-      });
+      const thread = makeProviderThread(threadId, threadKey);
       return thread.loadState();
     },
 
@@ -240,13 +271,19 @@ export function createAnthropicAdapter(
       state: PersistedThreadState,
       threadKey?: string
     ): Promise<void> {
-      const thread = createAnthropicThreadManager({
-        redis,
-        threadId,
-        key: threadKey,
-      });
+      const thread = makeProviderThread(threadId, threadKey);
       await thread.saveState(state);
     },
+
+    async hydrateThread(threadId: string, threadKey?: string): Promise<void> {
+      if (!config.coldStore) return;
+      await makeTieredBase(threadId, threadKey).hydrate();
+    },
+
+    async flushThread(threadId: string, threadKey?: string): Promise<void> {
+      if (!config.coldStore) return;
+      await makeTieredBase(threadId, threadKey).flush();
+    },
   };
 
   function createActivities<S extends string = "">(
@@ -263,7 +300,8 @@ export function createAnthropicAdapter(
 
   const makeInvoker = (
     model: string,
-    maxTokens?: number
+    maxTokens?: number,
+    promptCache?: AnthropicPromptCacheConfig
   ): ModelInvoker<Anthropic.Messages.Message> => {
     const invokerConfig: AnthropicModelInvokerConfig = {
       redis,
@@ -273,6 +311,11 @@ export function createAnthropicAdapter(
       ...(config.maxTokens !== undefined && maxTokens === undefined
         ? { maxTokens: config.maxTokens }
         : {}),
+      ...(promptCache !== undefined
+        ? { promptCache }
+        : config.promptCache !== undefined
+          ? { promptCache: config.promptCache }
+          : {}),
       hooks: config.hooks,
     };
     return createAnthropicModelInvoker(invokerConfig);

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

@@ -45,3 +45,11 @@ export {
   invokeAnthropicModel,
   type AnthropicModelInvokerConfig,
 } from "./model-invoker";
+
+// Prompt caching helpers
+export {
+  addPromptCacheControl,
+  resolvePromptCacheOptions,
+  type AnthropicPromptCacheConfig,
+  type AnthropicPromptCacheOptions,
+} from "./prompt-cache";

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

@@ -0,0 +1,110 @@
+import { describe, expect, it, vi } from "vitest";
+import type Anthropic from "@anthropic-ai/sdk";
+import { createAnthropicModelInvoker } from "./model-invoker";
+import type { StoredMessage } from "./thread-manager";
+
+function createMockRedis(stored: StoredMessage[]) {
+  return {
+    exists: vi.fn().mockResolvedValue(1),
+    lrange: vi.fn().mockResolvedValue(stored.map((m) => JSON.stringify(m))),
+    ltrim: vi.fn().mockResolvedValue("OK"),
+    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),
+  };
+}
+
+function createMockClient() {
+  const finalMessage: Anthropic.Messages.Message = {
+    id: "msg-response",
+    type: "message",
+    role: "assistant",
+    container: null,
+    model: "claude-test",
+    content: [{ type: "text", text: "ok", citations: null }],
+    stop_details: null,
+    stop_reason: "end_turn",
+    stop_sequence: null,
+    usage: {
+      cache_creation: null,
+      cache_creation_input_tokens: null,
+      cache_read_input_tokens: null,
+      inference_geo: null,
+      input_tokens: 1,
+      output_tokens: 1,
+      server_tool_use: null,
+      service_tier: null,
+    },
+  };
+  const stream = {
+    async *[Symbol.asyncIterator]() {},
+    finalMessage: vi.fn().mockResolvedValue(finalMessage),
+  };
+  const client = {
+    messages: {
+      stream: vi.fn().mockReturnValue(stream),
+    },
+  };
+  return { client, stream };
+}
+
+describe("createAnthropicModelInvoker prompt caching", () => {
+  it("sends explicit block-level cache_control by default", async () => {
+    const redis = createMockRedis([
+      { id: "msg-1", message: { role: "user", content: "hello" } },
+    ]);
+    const { client } = createMockClient();
+    const invoker = createAnthropicModelInvoker({
+      redis: redis as never,
+      client: client as never,
+      model: "claude-test",
+    });
+
+    await invoker({
+      threadId: "thread-1",
+      assistantMessageId: "assistant-1",
+      state: { tools: [] } as never,
+      agentName: "Agent",
+    });
+
+    const params = client.messages.stream.mock.calls[0]?.[0] as
+      | Anthropic.MessageCreateParams
+      | undefined;
+    expect(params).toBeDefined();
+    expect(params).not.toHaveProperty("cache_control");
+    expect(params?.messages[0]?.content).toEqual([
+      {
+        type: "text",
+        text: "hello",
+        cache_control: { type: "ephemeral", ttl: "5m" },
+      },
+    ]);
+  });
+
+  it("can disable prompt caching", async () => {
+    const redis = createMockRedis([
+      { id: "msg-1", message: { role: "user", content: "hello" } },
+    ]);
+    const { client } = createMockClient();
+    const invoker = createAnthropicModelInvoker({
+      redis: redis as never,
+      client: client as never,
+      model: "claude-test",
+      promptCache: false,
+    });
+
+    await invoker({
+      threadId: "thread-1",
+      assistantMessageId: "assistant-1",
+      state: { tools: [] } as never,
+      agentName: "Agent",
+    });
+
+    const params = client.messages.stream.mock.calls[0]?.[0] as
+      | Anthropic.MessageCreateParams
+      | undefined;
+    expect(params?.messages[0]?.content).toBe("hello");
+  });
+});

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

@@ -6,6 +6,11 @@ import {
   createAnthropicThreadManager,
   type AnthropicThreadManagerHooks,
 } from "./thread-manager";
+import {
+  addPromptCacheControl,
+  resolvePromptCacheOptions,
+  type AnthropicPromptCacheConfig,
+} from "./prompt-cache";
 import { getActivityContext } from "../../../lib/activity";
 
 export interface AnthropicModelInvokerConfig {
@@ -14,6 +19,11 @@ export interface AnthropicModelInvokerConfig {
   model: string;
   /** Maximum tokens to generate. Defaults to 16384. */
   maxTokens?: number;
+  /**
+   * Controls Anthropic/Bedrock-compatible prompt caching. Defaults to enabled
+   * with an explicit 5 minute TTL. Set to `false` to disable.
+   */
+  promptCache?: AnthropicPromptCacheConfig;
   hooks?: AnthropicThreadManagerHooks;
 }
 
@@ -56,6 +66,7 @@ export function createAnthropicModelInvoker({
   client,
   model,
   maxTokens = 16384,
+  promptCache,
   hooks,
 }: AnthropicModelInvokerConfig) {
   return async function invokeAnthropicModel(
@@ -76,17 +87,24 @@ export function createAnthropicModelInvoker({
     // 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 prepared = await thread.prepareForInvocation();
 
     const anthropicTools = toAnthropicTools(state.tools);
-    const tools = anthropicTools.length > 0 ? anthropicTools : undefined;
+    const preparedPayload = {
+      ...prepared,
+      ...(anthropicTools.length > 0 ? { tools: anthropicTools } : {}),
+    };
+    const cacheOptions = resolvePromptCacheOptions(promptCache);
+    const payload = cacheOptions
+      ? addPromptCacheControl(preparedPayload, cacheOptions)
+      : preparedPayload;
 
     const params: Anthropic.MessageCreateParams = {
       model,
       max_tokens: maxTokens,
-      messages,
-      ...(system ? { system } : {}),
-      ...(tools ? { tools } : {}),
+      messages: payload.messages,
+      ...(payload.system ? { system: payload.system } : {}),
+      ...(payload.tools ? { tools: payload.tools } : {}),
     };
 
     const stream = client.messages.stream(params, { signal });
@@ -130,6 +148,7 @@ export async function invokeAnthropicModel({
   client,
   model,
   maxTokens,
+  promptCache,
   hooks,
   config,
 }: {
@@ -137,6 +156,7 @@ export async function invokeAnthropicModel({
   client: Anthropic;
   model: string;
   maxTokens?: number;
+  promptCache?: AnthropicPromptCacheConfig;
   hooks?: AnthropicThreadManagerHooks;
   config: ModelInvokerConfig;
 }): Promise<AgentResponse<Anthropic.Messages.Message>> {
@@ -145,6 +165,7 @@ export async function invokeAnthropicModel({
     client,
     model,
     maxTokens,
+    promptCache,
     hooks,
   });
   return invoker(config);

package/src/adapters/thread/anthropic/prompt-cache.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, it } from "vitest";
+import type Anthropic from "@anthropic-ai/sdk";
+import {
+  addPromptCacheControl,
+  resolvePromptCacheOptions,
+} from "./prompt-cache";
+
+function firstContentBlock(
+  message: Anthropic.Messages.MessageParam
+): Record<string, unknown> {
+  if (!Array.isArray(message.content)) {
+    throw new Error("Expected array content");
+  }
+  const block = message.content[0];
+  if (!block || typeof block !== "object") {
+    throw new Error("Expected content block");
+  }
+  return block as unknown as Record<string, unknown>;
+}
+
+function messageAt(
+  messages: Anthropic.Messages.MessageParam[],
+  index: number
+): Anthropic.Messages.MessageParam {
+  const message = messages[index];
+  if (!message) throw new Error(`Expected message at index ${String(index)}`);
+  return message;
+}
+
+describe("Anthropic prompt cache helpers", () => {
+  it("enables prompt caching by default", () => {
+    expect(resolvePromptCacheOptions()).toEqual({});
+  });
+
+  it("can be disabled", () => {
+    expect(resolvePromptCacheOptions(false)).toBeUndefined();
+  });
+
+  it("adds Bedrock-compatible block-level cache_control to the last message", () => {
+    const payload = {
+      messages: [{ role: "user" as const, content: "hello" }],
+    };
+
+    const result = addPromptCacheControl(payload);
+    const block = firstContentBlock(messageAt(result.messages, 0));
+
+    expect(block).toEqual({
+      type: "text",
+      text: "hello",
+      cache_control: { type: "ephemeral", ttl: "5m" },
+    });
+    expect("cache_control" in result).toBe(false);
+  });
+
+  it("supports a 1h TTL", () => {
+    const result = addPromptCacheControl(
+      {
+        messages: [
+          {
+            role: "user" as const,
+            content: [{ type: "text" as const, text: "hello" }],
+          },
+        ],
+      },
+      { ttl: "1h" }
+    );
+
+    expect(
+      firstContentBlock(messageAt(result.messages, 0)).cache_control
+    ).toEqual({
+      type: "ephemeral",
+      ttl: "1h",
+    });
+  });
+
+  it("does not add a fifth cache breakpoint", () => {
+    const cacheControl = { type: "ephemeral" as const };
+    const result = addPromptCacheControl({
+      system: [
+        { type: "text" as const, text: "system", cache_control: cacheControl },
+      ],
+      tools: [
+        {
+          name: "tool",
+          description: "A test tool",
+          input_schema: { type: "object", properties: {} },
+          cache_control: cacheControl,
+        },
+      ],
+      messages: [
+        {
+          role: "user" as const,
+          content: [
+            { type: "text" as const, text: "1", cache_control: cacheControl },
+            { type: "text" as const, text: "2", cache_control: cacheControl },
+            { type: "text" as const, text: "latest" },
+          ],
+        },
+      ],
+    });
+
+    const latest = (
+      messageAt(result.messages, 0).content as unknown as Array<
+        Record<string, unknown>
+      >
+    )[2];
+    expect(latest?.cache_control).toBeUndefined();
+  });
+
+  it("preserves an existing cache marker on the last cacheable block", () => {
+    const cacheControl = { type: "ephemeral" as const, ttl: "1h" as const };
+    const payload = {
+      messages: [
+        {
+          role: "user" as const,
+          content: [
+            {
+              type: "text" as const,
+              text: "hello",
+              cache_control: cacheControl,
+            },
+          ],
+        },
+      ],
+    };
+
+    const result = addPromptCacheControl(payload, { ttl: "5m" });
+
+    expect(result).toBe(payload);
+    expect(
+      firstContentBlock(messageAt(result.messages, 0)).cache_control
+    ).toEqual(cacheControl);
+  });
+});