zeitlich 0.2.46 → 0.2.47

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zeitlich",
-  "version": "0.2.46",
+  "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,8 +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",
@@ -225,6 +227,7 @@
   "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",
@@ -246,6 +249,9 @@
     "@aws-sdk/client-s3": {
       "optional": true
     },
+    "@aws-sdk/lib-storage": {
+      "optional": true
+    },
     "@google/genai": {
       "optional": true
     },

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

@@ -27,6 +27,7 @@ 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<
@@ -41,6 +42,11 @@ 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,
@@ -76,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.
@@ -245,7 +252,7 @@ export function createAnthropicAdapter(
     async truncateThread(
       threadId: string,
       messageId: string,
-      threadKey?: string,
+      threadKey?: string
     ): Promise<void> {
       const thread = makeProviderThread(threadId, threadKey);
       await thread.truncateFromId(messageId);
@@ -268,18 +275,12 @@ export function createAnthropicAdapter(
       await thread.saveState(state);
     },
 
-    async hydrateThread(
-      threadId: string,
-      threadKey?: string
-    ): Promise<void> {
+    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> {
+    async flushThread(threadId: string, threadKey?: string): Promise<void> {
       if (!config.coldStore) return;
       await makeTieredBase(threadId, threadKey).flush();
     },
@@ -299,7 +300,8 @@ export function createAnthropicAdapter(
 
   const makeInvoker = (
     model: string,
-    maxTokens?: number
+    maxTokens?: number,
+    promptCache?: AnthropicPromptCacheConfig
   ): ModelInvoker<Anthropic.Messages.Message> => {
     const invokerConfig: AnthropicModelInvokerConfig = {
       redis,
@@ -309,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);
+  });
+});

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

@@ -0,0 +1,163 @@
+import type Anthropic from "@anthropic-ai/sdk";
+
+export interface AnthropicPromptCacheOptions {
+  /** TTL for the cache checkpoint. Defaults to 5m. */
+  ttl?: Anthropic.Messages.CacheControlEphemeral["ttl"];
+  /** Claude models support at most 4 cache breakpoints per request. */
+  maxBreakpoints?: number;
+}
+
+export type AnthropicPromptCacheConfig = boolean | AnthropicPromptCacheOptions;
+
+interface PromptCachePayload {
+  messages: Anthropic.Messages.MessageParam[];
+  system?: string | Anthropic.Messages.TextBlockParam[];
+  tools?: Anthropic.Messages.Tool[];
+}
+
+type CacheControl = Anthropic.Messages.CacheControlEphemeral;
+type CacheableRecord = Record<string, unknown> & {
+  cache_control?: CacheControl | null;
+};
+
+const DEFAULT_MAX_CACHE_BREAKPOINTS = 4;
+const UNCACHEABLE_BLOCK_TYPES = new Set(["thinking", "redacted_thinking"]);
+
+/**
+ * Resolve model-invoker prompt-cache config. Undefined means the default:
+ * enabled with an explicit 5 minute TTL.
+ */
+export function resolvePromptCacheOptions(
+  promptCache?: AnthropicPromptCacheConfig
+): AnthropicPromptCacheOptions | undefined {
+  if (promptCache === false) return undefined;
+  if (promptCache === true || promptCache === undefined) return {};
+  return promptCache;
+}
+
+/**
+ * Add an explicit `cache_control` marker to the final cacheable message block.
+ *
+ * This intentionally uses block-level cache control rather than Anthropic's
+ * top-level automatic `cache_control` field because Amazon Bedrock does not
+ * support the top-level form. The block-level shape is accepted by both the
+ * Anthropic Messages API and Bedrock InvokeModel for Anthropic Claude models.
+ */
+export function addPromptCacheControl<TPayload extends PromptCachePayload>(
+  payload: TPayload,
+  options: AnthropicPromptCacheOptions = {}
+): TPayload {
+  const maxBreakpoints =
+    options.maxBreakpoints ?? DEFAULT_MAX_CACHE_BREAKPOINTS;
+  if (maxBreakpoints <= 0) return payload;
+
+  if (countCacheControls(payload) >= maxBreakpoints) return payload;
+
+  const cacheControl: CacheControl = {
+    type: "ephemeral",
+    ttl: options.ttl ?? "5m",
+  };
+  const messages = addCacheControlToLastMessageBlock(
+    payload.messages,
+    cacheControl
+  );
+
+  if (messages === payload.messages) return payload;
+  return { ...payload, messages };
+}
+
+function addCacheControlToLastMessageBlock(
+  messages: Anthropic.Messages.MessageParam[],
+  cacheControl: CacheControl
+): Anthropic.Messages.MessageParam[] {
+  for (
+    let messageIndex = messages.length - 1;
+    messageIndex >= 0;
+    messageIndex--
+  ) {
+    const message = messages[messageIndex];
+    if (!message) continue;
+
+    if (typeof message.content === "string") {
+      if (message.content.length === 0) continue;
+      return replaceMessage(messages, messageIndex, {
+        ...message,
+        content: [
+          { type: "text", text: message.content, cache_control: cacheControl },
+        ],
+      });
+    }
+
+    if (!Array.isArray(message.content)) continue;
+
+    for (
+      let blockIndex = message.content.length - 1;
+      blockIndex >= 0;
+      blockIndex--
+    ) {
+      const block = message.content[blockIndex];
+      if (!isCacheableContentBlock(block)) continue;
+      if (hasCacheControl(block)) return messages;
+
+      const content = [...message.content];
+      content[blockIndex] = {
+        ...(block as Record<string, unknown>),
+        cache_control: cacheControl,
+      } as Anthropic.Messages.ContentBlockParam;
+      return replaceMessage(messages, messageIndex, { ...message, content });
+    }
+  }
+
+  return messages;
+}
+
+function replaceMessage(
+  messages: Anthropic.Messages.MessageParam[],
+  index: number,
+  message: Anthropic.Messages.MessageParam
+): Anthropic.Messages.MessageParam[] {
+  const next = [...messages];
+  next[index] = message;
+  return next;
+}
+
+function isCacheableContentBlock(
+  block: Anthropic.Messages.ContentBlockParam | undefined
+): block is Anthropic.Messages.ContentBlockParam & CacheableRecord {
+  if (!isRecord(block)) return false;
+  const type = typeof block.type === "string" ? block.type : undefined;
+  if (type && UNCACHEABLE_BLOCK_TYPES.has(type)) return false;
+  if (type === "text" && block.text === "") return false;
+  return true;
+}
+
+function countCacheControls(payload: PromptCachePayload): number {
+  let count = 0;
+
+  for (const tool of payload.tools ?? []) {
+    if (hasCacheControl(tool)) count++;
+  }
+
+  if (Array.isArray(payload.system)) {
+    for (const block of payload.system) {
+      if (hasCacheControl(block)) count++;
+    }
+  }
+
+  for (const message of payload.messages) {
+    if (!Array.isArray(message.content)) continue;
+    for (const block of message.content) {
+      if (hasCacheControl(block)) count++;
+    }
+  }
+
+  return count;
+}
+
+function hasCacheControl(value: unknown): value is CacheableRecord {
+  return isRecord(value) && value.cache_control != null;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

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

@@ -25,6 +25,7 @@ import { createThreadOpsProxy } from "../../../lib/thread/proxy";
 import { ADAPTER_ID } from "./adapter-id";
 
 export { ADAPTER_ID, type AdapterId } from "./adapter-id";
+export type { ThreadOpsProxyOptions } from "../../../lib/thread/proxy";
 
 export function proxyAnthropicThreadOps(
   scope?: string,

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

@@ -25,6 +25,7 @@ import { createThreadOpsProxy } from "../../../lib/thread/proxy";
 import { ADAPTER_ID } from "./adapter-id";
 
 export { ADAPTER_ID, type AdapterId } from "./adapter-id";
+export type { ThreadOpsProxyOptions } from "../../../lib/thread/proxy";
 
 export function proxyGoogleGenAIThreadOps(
   scope?: string,

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

@@ -25,6 +25,7 @@ import { createThreadOpsProxy } from "../../../lib/thread/proxy";
 import { ADAPTER_ID } from "./adapter-id";
 
 export { ADAPTER_ID, type AdapterId } from "./adapter-id";
+export type { ThreadOpsProxyOptions } from "../../../lib/thread/proxy";
 
 export function proxyLangChainThreadOps(
   scope?: string,

package/src/index.ts

@@ -93,7 +93,7 @@ export type { VirtualFsContext } from "./lib/virtual-fs/types";
 // Tool handlers (activity implementations)
 // Wrap sandbox handlers with withSandbox(manager, handler) at registration time
 export { bashHandler } from "./tools/bash/handler";
-export { editHandler } from "./tools/edit/handler";
+export { editHandler, multiEditHandler } from "./tools/edit/handler";
 export { globHandler } from "./tools/glob/handler";
 export { readFileHandler } from "./tools/read-file/handler";
 export { writeFileHandler } from "./tools/write-file/handler";

package/src/lib/subagent/define.ts

@@ -44,6 +44,7 @@ export function defineSubagent<
     enabled?: boolean | (() => boolean);
     taskQueue?: string;
     thread?: "new" | "fork" | "continue";
+    newThreadSource?: "new" | "from-parent";
     sandbox?: SubagentSandboxConfig;
   }
 ): SubagentConfig<TResult> {