zeitlich 0.2.46 → 0.2.47

package/README.md

@@ -8,7 +8,7 @@
 
 **Durable AI Agents for Temporal**
 
-Zeitlich is an opinionated framework for building reliable, stateful AI agents using [Temporal](https://temporal.io). It provides the building blocks for creating agents that can survive crashes, handle long-running tasks, and coordinate with other agents—all with full type safety.
+Zeitlich is an opinionated harness for building reliable, stateful AI agents using [Temporal](https://temporal.io). It provides the building blocks for creating agents that can survive crashes, handle long-running tasks, and coordinate with other agents—all with full type safety.
 
 ## Why Zeitlich?
 
@@ -104,6 +104,7 @@ npm install zeitlich ioredis \
 - `@google/genai` >= 1.0.0 (optional — only when using the Google GenAI adapter)
 - `@aws-sdk/client-bedrock-agentcore` >= 3.900.0 (optional — only when using the Bedrock adapter)
 - `@aws-sdk/client-s3` >= 3.700.0 (optional — only when using the built-in S3 cold thread tier)
+- `@aws-sdk/lib-storage` >= 3.700.0 (optional — paired with `@aws-sdk/client-s3` for multipart uploads in the S3 cold tier)
 
 > **Why peer deps?** Zeitlich's public API surfaces `@temporalio/*` types
 > (`UpdateDefinition`, `ChildWorkflowOptions`, `Duration`, etc.) directly. Peer
@@ -671,10 +672,10 @@ const continuedSession = await createSession({
 
 By default every thread lives in Redis with a 90-day TTL — both messages and the persisted state slice. For long-lived agents, that ties up hot memory for inactive conversations and ties durability to your Redis retention. Zeitlich's tiered storage moves cold threads to a durable archive (S3, R2, GCS, …) while keeping Redis as the hot tier only for the duration of a workflow run.
 
-| Tier  | Backend                | Lifetime                                          |
-| ----- | ---------------------- | ------------------------------------------------- |
-| Hot   | Redis                  | Only while a workflow run is active (configurable TTL) |
-| Cold  | Pluggable `ColdThreadStore` (built-in S3) | Durable across runs                                |
+| Tier | Backend                                   | Lifetime                                               |
+| ---- | ----------------------------------------- | ------------------------------------------------------ |
+| Hot  | Redis                                     | Only while a workflow run is active (configurable TTL) |
+| Cold | Pluggable `ColdThreadStore` (built-in S3) | Durable across runs                                    |
 
 The session wiring is fully automatic:
 
@@ -708,6 +709,30 @@ const adapter = createAnthropicAdapter({
 
 That's the only change required — `createSession`, all `ThreadInit` modes, and every adapter activity are already wired for the lifecycle. When `coldStore` is omitted, the adapter behaves identically to the Redis-only baseline.
 
+##### Anthropic prompt caching
+
+The Anthropic adapter enables 5-minute ephemeral prompt caching by default. Before each `messages.stream()` call, it adds an explicit block-level `cache_control: { type: "ephemeral", ttl: "5m" }` marker to the last cacheable message content block. Zeitlich intentionally uses the block-level shape instead of Anthropic's top-level automatic cache-control parameter so the same request body works with Anthropic direct API clients and Anthropic-on-Bedrock `InvokeModel` clients.
+
+```typescript
+const adapter = createAnthropicAdapter({
+  redis,
+  client: anthropic,
+  model: "claude-sonnet-4-20250514",
+  // Optional: 5m is the default; set explicitly if you prefer clarity.
+  promptCache: { ttl: "5m" },
+});
+
+// Disable if a model/provider route does not support prompt caching.
+const uncachedAdapter = createAnthropicAdapter({
+  redis,
+  client: anthropic,
+  model: "claude-sonnet-4-20250514",
+  promptCache: false,
+});
+```
+
+If you already provide your own `cache_control` markers, Zeitlich preserves them and skips its automatic marker when the request already has the provider maximum of four cache breakpoints.
+
 ##### Custom backends
 
 `ColdThreadStore` is intentionally minimal:
@@ -715,7 +740,11 @@ That's the only change required — `createSession`, all `ThreadInit` modes, and
 ```typescript
 interface ColdThreadStore {
   read(threadKey: string, threadId: string): Promise<ThreadSnapshot | null>;
-  write(threadKey: string, threadId: string, snapshot: ThreadSnapshot): Promise<void>;
+  write(
+    threadKey: string,
+    threadId: string,
+    snapshot: ThreadSnapshot
+  ): Promise<void>;
   delete(threadKey: string, threadId: string): Promise<void>;
 }
 ```
@@ -729,6 +758,23 @@ Any backend that can satisfy these three calls — Cloudflare R2, Google Cloud S
 - **`deleteHot: true` by default on flush.** Memory drops immediately; the next continue re-hydrates in one `GetObject`. Override per-call via the tiered manager if you want to keep the hot tier warm.
 - **`mode: "new"` overwrites the cold archive for that `threadId`.** A session entered with `mode: "new"` skips `hydrateThread`; on exit `flushThread` writes the fresh snapshot back, silently replacing any prior cold-tier blob at the same `(threadKey, threadId)`. To resume a thread, use `mode: "continue"` or `mode: "fork"` — passing a previously-used `threadId` with `mode: "new"` is destructive by design.
 
+##### Activity timeouts
+
+`hydrateThread` and `flushThread` automatically get `startToCloseTimeout: "60s"` and `heartbeatTimeout: "15s"`. The S3 cold store uses multipart `Upload` for writes and streams the `GetObject` response on reads — each part completion / stream chunk emits a heartbeat, so a stalled upload or download trips `heartbeatTimeout` (15s) rather than waiting out `startToCloseTimeout` (60s). The Redis-only ops keep the tight `10s` baseline.
+
+To override an individual op without inflating the rest:
+
+```typescript
+const threadOps = proxyGoogleGenAIThreadOps(undefined, {
+  defaults: { startToCloseTimeout: "5s" },                  // applied to every op
+  perOp: {
+    flushThread: { startToCloseTimeout: "180s" },           // overlays cold-tier defaults; heartbeatTimeout still inherited
+  },
+});
+```
+
+`perOp[op]` is layered shallow-rightmost over `defaults` and the built-in cold-tier overlays for `hydrateThread` / `flushThread` — so a partial override only replaces the fields you specify. A bare `ActivityOptions` object is also accepted and treated as `{ defaults: <that object> }`, with the cold-tier overlay still applied on top — to raise the cold-tier ceiling above `60s`, use `perOp.flushThread` / `perOp.hydrateThread`.
+
 #### Sandbox Initialization (`SandboxInit`)
 
 The `sandbox` field controls how a sandbox is created or reused:
@@ -833,6 +879,17 @@ Trade-off: cleanup is deferred to parent close (no eager GC of superseded thread
 
 The `thread` field accepts `"new"` (default), `"fork"`, or `"continue"`. When set to `"fork"` or `"continue"`, the parent agent can pass a `threadId` in a subsequent `Task` tool call to resume the conversation. The subagent returns its `threadId` in the response (surfaced as `[Thread ID: ...]`), which the parent can use for continuation.
 
+The `newThreadSource` field controls what to do when the parent's tool call omits `threadId`. It accepts `"new"` (default — start a fresh thread) or `"from-parent"` (fork/continue the parent agent's own thread). Useful when you want a subagent that inherits the parent's conversation state by default without requiring the LLM to explicitly thread the id through:
+
+```typescript
+export const researcherSubagent = defineSubagent(researcherWorkflow, {
+  thread: "fork",
+  newThreadSource: "from-parent", // no threadId → fork the parent's thread
+});
+```
+
+An explicit `threadId` from the parent's tool call always wins; `newThreadSource` only applies when none is provided. The field has no effect with `thread: "new"`.
+
 The `sandbox` field accepts `"none"` (default) or an object with `source`, `continuation`, and optional `init`/`shutdown` fields:
 
 - `source: "inherit"` — use the parent's sandbox. `continuation: "continue"` shares it directly; `"fork"` forks from it on every call.
@@ -1050,6 +1107,7 @@ Framework-agnostic utilities for activities, worker setup, and Node.js code:
 | --------------------------- | ------------------------------------------------------------------------------------------------------------------ |
 | `createRunAgentActivity`    | Wraps a handler into a scope-prefixed `RunAgentActivity` with auto-fetched parent workflow state                   |
 | `withParentWorkflowState`   | Wraps a tool handler into an `ActivityToolHandler` with auto-fetched parent workflow state                         |
+| `getActivityContext`        | Safely returns `{ heartbeat, signal }` from the current Temporal activity, or `{}` outside one                     |
 | `createThreadManager`       | Generic Redis-backed thread manager factory                                                                        |
 | `createTieredThreadManager` | Redis hot + pluggable cold tier; adds `hydrate()` / `flush()` to `BaseThreadManager<T>`                            |
 | `createS3ColdStore`         | Built-in `ColdThreadStore` backed by an `@aws-sdk/client-s3` `S3Client`                                            |

package/dist/{activities-CyeiqK_f.d.cts → activities-CPwKoUlD.d.cts}

@@ -1,8 +1,8 @@
 import Redis from 'ioredis';
 import { Part, Content, GoogleGenAI } from '@google/genai';
-import { a as ModelInvoker, b as PrefixedThreadOps, S as ScopedPrefix, R as RouterContext, c as ToolHandlerResponse, d as ActivityToolHandler } from './types-CnuN9T6t.cjs';
-import { C as ColdThreadStore } from './cold-store-BC5L5Z8A.cjs';
-import { T as ThreadManagerHooks, P as ProviderThreadManager } from './types-oxt8GN97.cjs';
+import { a as ModelInvoker, b as PrefixedThreadOps, S as ScopedPrefix, R as RouterContext, c as ToolHandlerResponse, d as ActivityToolHandler } from './types-DNEl5uxQ.cjs';
+import { C as ColdThreadStore } from './cold-store-Z2wvK2cV.cjs';
+import { T as ThreadManagerHooks, P as ProviderThreadManager } from './types-BMJrsHo0.cjs';
 import { A as ADAPTER_ID } from './adapter-id-BB-mmrts.cjs';
 
 /** SDK-native content type for Google GenAI human messages */

package/dist/{activities-Bm4TLTid.d.ts → activities-DlaBxNID.d.ts}

@@ -1,8 +1,8 @@
 import Redis from 'ioredis';
 import { Part, Content, GoogleGenAI } from '@google/genai';
-import { a as ModelInvoker, b as PrefixedThreadOps, S as ScopedPrefix, R as RouterContext, c as ToolHandlerResponse, d as ActivityToolHandler } from './types-CwN6_tAL.js';
-import { C as ColdThreadStore } from './cold-store-CFHwemBJ.js';
-import { T as ThreadManagerHooks, P as ProviderThreadManager } from './types-L5bvbF-n.js';
+import { a as ModelInvoker, b as PrefixedThreadOps, S as ScopedPrefix, R as RouterContext, c as ToolHandlerResponse, d as ActivityToolHandler } from './types-qQVZfhoT.js';
+import { C as ColdThreadStore } from './cold-store-BDgJpwLI.js';
+import { T as ThreadManagerHooks, P as ProviderThreadManager } from './types-CtdOquo3.js';
 import { A as ADAPTER_ID } from './adapter-id-BB-mmrts.js';
 
 /** SDK-native content type for Google GenAI human messages */

package/dist/adapters/thread/anthropic/index.cjs

@@ -418,6 +418,94 @@ function createAnthropicThreadManager(config) {
   };
   return manager;
 }
+
+// src/adapters/thread/anthropic/prompt-cache.ts
+var DEFAULT_MAX_CACHE_BREAKPOINTS = 4;
+var UNCACHEABLE_BLOCK_TYPES = /* @__PURE__ */ new Set(["thinking", "redacted_thinking"]);
+function resolvePromptCacheOptions(promptCache) {
+  if (promptCache === false) return void 0;
+  if (promptCache === true || promptCache === void 0) return {};
+  return promptCache;
+}
+function addPromptCacheControl(payload, options = {}) {
+  const maxBreakpoints = options.maxBreakpoints ?? DEFAULT_MAX_CACHE_BREAKPOINTS;
+  if (maxBreakpoints <= 0) return payload;
+  if (countCacheControls(payload) >= maxBreakpoints) return payload;
+  const 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, cacheControl) {
+  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,
+        cache_control: cacheControl
+      };
+      return replaceMessage(messages, messageIndex, { ...message, content });
+    }
+  }
+  return messages;
+}
+function replaceMessage(messages, index, message) {
+  const next = [...messages];
+  next[index] = message;
+  return next;
+}
+function isCacheableContentBlock(block) {
+  if (!isRecord(block)) return false;
+  const type = typeof block.type === "string" ? block.type : void 0;
+  if (type && UNCACHEABLE_BLOCK_TYPES.has(type)) return false;
+  if (type === "text" && block.text === "") return false;
+  return true;
+}
+function countCacheControls(payload) {
+  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) {
+  return isRecord(value) && value.cache_control != null;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function getActivityContext() {
   try {
     const ctx = activity.Context.current();
@@ -440,6 +528,7 @@ function createAnthropicModelInvoker({
   client,
   model,
   maxTokens = 16384,
+  promptCache,
   hooks
 }) {
   return async function invokeAnthropicModel2(config) {
@@ -452,15 +541,20 @@ function createAnthropicModelInvoker({
       hooks
     });
     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 : void 0;
+    const preparedPayload = {
+      ...prepared,
+      ...anthropicTools.length > 0 ? { tools: anthropicTools } : {}
+    };
+    const cacheOptions = resolvePromptCacheOptions(promptCache);
+    const payload = cacheOptions ? addPromptCacheControl(preparedPayload, cacheOptions) : preparedPayload;
     const params = {
       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 });
     for await (const _event of stream) {
@@ -491,6 +585,7 @@ async function invokeAnthropicModel({
   client,
   model,
   maxTokens,
+  promptCache,
   hooks,
   config
 }) {
@@ -499,6 +594,7 @@ async function invokeAnthropicModel({
     client,
     model,
     maxTokens,
+    promptCache,
     hooks
   });
   return invoker(config);
@@ -584,13 +680,14 @@ function createAnthropicAdapter(config) {
       Object.entries(threadOps).map(([k, v]) => [`${prefix}${cap(k)}`, v])
     );
   }
-  const makeInvoker = (model, maxTokens) => {
+  const makeInvoker = (model, maxTokens, promptCache) => {
     const invokerConfig = {
       redis,
       client,
       model,
       ...maxTokens !== void 0 ? { maxTokens } : {},
       ...config.maxTokens !== void 0 && maxTokens === void 0 ? { maxTokens: config.maxTokens } : {},
+      ...promptCache !== void 0 ? { promptCache } : config.promptCache !== void 0 ? { promptCache: config.promptCache } : {},
       hooks: config.hooks
     };
     return createAnthropicModelInvoker(invokerConfig);
@@ -609,9 +706,11 @@ function createAnthropicAdapter(config) {
 }
 
 exports.ADAPTER_ID = ADAPTER_ID;
+exports.addPromptCacheControl = addPromptCacheControl;
 exports.createAnthropicAdapter = createAnthropicAdapter;
 exports.createAnthropicModelInvoker = createAnthropicModelInvoker;
 exports.createAnthropicThreadManager = createAnthropicThreadManager;
 exports.invokeAnthropicModel = invokeAnthropicModel;
+exports.resolvePromptCacheOptions = resolvePromptCacheOptions;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map