zeitlich 0.2.45 → 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?
 
@@ -103,6 +103,8 @@ npm install zeitlich ioredis \
 - `@langchain/core` >= 1.0.0 (optional — only when using the LangChain adapter)
 - `@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
@@ -666,6 +668,113 @@ const continuedSession = await createSession({
 
 `getShortId()` produces compact, workflow-deterministic IDs (~12 base-62 chars) that are more token-efficient than UUIDs.
 
+#### Tiered Thread Storage (Redis hot + S3 cold)
+
+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                                    |
+
+The session wiring is fully automatic:
+
+- On entry — `mode: "continue"` and `mode: "fork"` call `hydrateThread`, which restores the latest cold-tier snapshot into Redis if Redis is cold. Idempotent (safe for Temporal activity retries).
+- In `finally{}` — every exit path calls `flushThread` after `saveThreadState`, which writes the current Redis contents to the cold tier and (by default) deletes the Redis keys. A near-immediate `continue` re-hydrates in a single `GetObject`.
+
+##### Wiring the built-in S3 cold store
+
+```typescript
+import { S3Client } from "@aws-sdk/client-s3";
+import { createS3ColdStore } from "zeitlich";
+import { createAnthropicAdapter } from "zeitlich/adapters/thread/anthropic";
+
+const coldStore = createS3ColdStore({
+  s3: new S3Client({ region: "us-east-1" }),
+  bucket: "my-threads",
+  prefix: "prod/threads",
+  // gzip: true (default) — message lists compress well
+});
+
+const adapter = createAnthropicAdapter({
+  redis,
+  client: anthropic,
+  model: "claude-sonnet-4-20250514",
+  coldStore,
+  // Recommended: drop the Redis TTL to a small window when cold tiering
+  // is enabled. The cold tier is the source of truth.
+  ttlSeconds: 60 * 60 * 24, // 24h
+});
+```
+
+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:
+
+```typescript
+interface ColdThreadStore {
+  read(threadKey: string, threadId: string): Promise<ThreadSnapshot | null>;
+  write(
+    threadKey: string,
+    threadId: string,
+    snapshot: ThreadSnapshot
+  ): Promise<void>;
+  delete(threadKey: string, threadId: string): Promise<void>;
+}
+```
+
+Any backend that can satisfy these three calls — Cloudflare R2, Google Cloud Storage, Postgres, the local filesystem — can plug into the same tiered manager. `ThreadSnapshot` is one JSON-friendly blob per thread; round-trip it however you like.
+
+##### Trade-offs
+
+- **Cold writes are session-boundary only.** No per-append S3 traffic. Long-running sessions are durable via Temporal workflow history + Redis TTL.
+- **Single-writer assumed.** Two sessions started simultaneously on the same `threadId` would race on flush. Use distinct `threadId`s or coordinate at a layer above zeitlich.
+- **`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:
@@ -770,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.
@@ -983,16 +1103,22 @@ Safe for use in Temporal workflow files:
 
 Framework-agnostic utilities for activities, worker setup, and Node.js code:
 
-| Export                    | Description                                                                                                        |
-| ------------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| `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                         |
-| `createThreadManager`     | Generic Redis-backed thread manager factory                                                                        |
-| `toTree`                  | Generate file tree string from an `IFileSystem` instance                                                           |
-| `withSandbox`             | Wraps a handler to auto-resolve sandbox from context (pairs with `withAutoAppend`)                                 |
-| `NodeFsSandboxFileSystem` | `node:fs` adapter for `SandboxFileSystem` — read skills from the worker's local disk                               |
-| `FileSystemSkillProvider` | Load skills from a directory following the agentskills.io layout                                                   |
-| Tool handlers             | `bashHandler`, `editHandler`, `globHandler`, `readFileHandler`, `writeFileHandler`, `createAskUserQuestionHandler` |
+| Export                      | Description                                                                                                        |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `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`                                            |
+| `encodeSnapshot`            | Low-level helper that builds a `ThreadSnapshot` from the hot-tier Redis state                                      |
+| `applySnapshot`             | Low-level helper that restores a `ThreadSnapshot` into Redis (idempotent)                                          |
+| `clearHotTier`              | Low-level helper that deletes every Redis key the thread manager wrote for a given `(threadKey, threadId)`         |
+| `toTree`                    | Generate file tree string from an `IFileSystem` instance                                                           |
+| `withSandbox`               | Wraps a handler to auto-resolve sandbox from context (pairs with `withAutoAppend`)                                 |
+| `NodeFsSandboxFileSystem`   | `node:fs` adapter for `SandboxFileSystem` — read skills from the worker's local disk                               |
+| `FileSystemSkillProvider`   | Load skills from a directory following the agentskills.io layout                                                   |
+| Tool handlers               | `bashHandler`, `editHandler`, `globHandler`, `readFileHandler`, `writeFileHandler`, `createAskUserQuestionHandler` |
 
 ### Thread Adapter Entry Points
 

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

@@ -1,7 +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-CdALEF3z.cjs';
-import { T as ThreadManagerHooks, P as ProviderThreadManager } from './types-C66-BVBr.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 */
@@ -20,6 +21,12 @@ interface GoogleGenAIThreadManagerConfig {
     /** Thread key, defaults to 'messages' */
     key?: string;
     hooks?: GoogleGenAIThreadManagerHooks;
+    /**
+     * Override the default thread TTL (90 days). When pairing the
+     * adapter with a durable cold tier, a shorter TTL (hours) is
+     * typically more appropriate.
+     */
+    ttlSeconds?: number;
 }
 /** Prepared payload ready to send to the Google GenAI API */
 interface GoogleGenAIInvocationPayload {
@@ -45,6 +52,19 @@ interface GoogleGenAIAdapterConfig {
     /** Default model name (e.g. 'gemini-2.5-flash'). If omitted, use `createModelInvoker()` */
     model?: string;
     hooks?: GoogleGenAIThreadManagerHooks;
+    /**
+     * Optional durable cold tier (e.g. S3, R2, GCS). When provided,
+     * the session hydrates the thread on entry (`continue`/`fork`) and
+     * flushes it 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). When pairing the
+     * adapter with a `coldStore`, a shorter TTL (hours) is typically
+     * more appropriate.
+     */
+    ttlSeconds?: number;
 }
 /**
  * Tool response type accepted by the Google GenAI adapter.

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

@@ -1,7 +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-ChAy_jSP.js';
-import { T as ThreadManagerHooks, P as ProviderThreadManager } from './types-BkX4HLzi.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 */
@@ -20,6 +21,12 @@ interface GoogleGenAIThreadManagerConfig {
     /** Thread key, defaults to 'messages' */
     key?: string;
     hooks?: GoogleGenAIThreadManagerHooks;
+    /**
+     * Override the default thread TTL (90 days). When pairing the
+     * adapter with a durable cold tier, a shorter TTL (hours) is
+     * typically more appropriate.
+     */
+    ttlSeconds?: number;
 }
 /** Prepared payload ready to send to the Google GenAI API */
 interface GoogleGenAIInvocationPayload {
@@ -45,6 +52,19 @@ interface GoogleGenAIAdapterConfig {
     /** Default model name (e.g. 'gemini-2.5-flash'). If omitted, use `createModelInvoker()` */
     model?: string;
     hooks?: GoogleGenAIThreadManagerHooks;
+    /**
+     * Optional durable cold tier (e.g. S3, R2, GCS). When provided,
+     * the session hydrates the thread on entry (`continue`/`fork`) and
+     * flushes it 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). When pairing the
+     * adapter with a `coldStore`, a shorter TTL (hours) is typically
+     * more appropriate.
+     */
+    ttlSeconds?: number;
 }
 /**
  * Tool response type accepted by the Google GenAI adapter.