zeitlich 0.2.44 → 0.2.46

package/src/index.ts

@@ -33,11 +33,30 @@ export * from "./workflow";
 export { FileSystemSkillProvider } from "./lib/skills/fs-provider";
 
 // Thread manager (generic, framework-agnostic)
-export { createThreadManager } from "./lib/thread";
+export {
+  createThreadManager,
+  createTieredThreadManager,
+  createS3ColdStore,
+  encodeSnapshot,
+  applySnapshot,
+  clearHotTier,
+  getThreadStateKey,
+  getThreadDedupKey,
+} from "./lib/thread";
 export type {
   BaseThreadManager,
   ProviderThreadManager,
   ThreadManagerConfig,
+  TieredThreadManager,
+  TieredThreadManagerConfig,
+  FlushOptions,
+  ColdThreadStore,
+  ThreadSnapshot,
+  S3LikeClient,
+  S3ColdStoreConfig,
+  EncodeSnapshotConfig,
+  ApplySnapshotConfig,
+  ClearHotTierConfig,
 } from "./lib/thread";
 
 // Model invoker contract (framework-agnostic)

package/src/lib/session/session-edge-cases.integration.test.ts

@@ -129,6 +129,12 @@ function createMockThreadOps() {
       log.push({ op: "saveThreadState", args: [threadId, state] });
       stateStore.set(threadId, state);
     },
+    hydrateThread: async (threadId) => {
+      log.push({ op: "hydrateThread", args: [threadId] });
+    },
+    flushThread: async (threadId) => {
+      log.push({ op: "flushThread", args: [threadId] });
+    },
   });
   return { ops, log, stateStore };
 }
@@ -824,6 +830,12 @@ describe("createSession edge cases", () => {
       saveThreadState: async (threadId, state) => {
         log.push({ op: "saveThreadState", args: [threadId, state] });
       },
+      hydrateThread: async (threadId) => {
+        log.push({ op: "hydrateThread", args: [threadId] });
+      },
+      flushThread: async (threadId) => {
+        log.push({ op: "flushThread", args: [threadId] });
+      },
     });
 
     const session = await createSession<

package/src/lib/session/session.integration.test.ts

@@ -132,6 +132,12 @@ function createMockThreadOps() {
       log.push({ op: "saveThreadState", args: [threadId, state] });
       stateStore.set(threadId, state);
     },
+    hydrateThread: async (threadId) => {
+      log.push({ op: "hydrateThread", args: [threadId] });
+    },
+    flushThread: async (threadId) => {
+      log.push({ op: "flushThread", args: [threadId] });
+    },
   });
 
   return { ops, log, stateStore };
@@ -1336,4 +1342,136 @@ describe("createSession integration", () => {
     const newThreadSlice = stateStore.get(result.threadId);
     expect(newThreadSlice?.tasks).toHaveLength(1);
   });
+
+  // --- Cold-tier lifecycle (hydrateThread + flushThread) ---
+
+  it("skips hydrateThread for mode:'new' threads but still flushes on exit", async () => {
+    const { ops, log } = createMockThreadOps();
+
+    const session = await createSession({
+      agentName: "TestAgent",
+      thread: { mode: "new", threadId: "fresh-thread" },
+      runAgent: createScriptedRunAgent([{ message: "ok", toolCalls: [] }]),
+      threadOps: ops,
+      buildContextMessage: () => "hi",
+    });
+
+    const stateManager = createAgentStateManager({
+      initialState: { systemPrompt: "system" },
+    });
+    await session.runSession({ stateManager });
+
+    expect(log.filter((l) => l.op === "hydrateThread")).toHaveLength(0);
+    const flushes = log.filter((l) => l.op === "flushThread");
+    expect(flushes).toHaveLength(1);
+    expect(at(flushes, 0).args[0]).toBe("fresh-thread");
+  });
+
+  it("hydrates the target thread before continuing it", async () => {
+    const { ops, log, stateStore } = createMockThreadOps();
+    stateStore.set("existing-thread", {
+      tasks: [],
+      custom: { previous: true },
+    });
+
+    const session = await createSession({
+      agentName: "TestAgent",
+      thread: { mode: "continue", threadId: "existing-thread" },
+      runAgent: createScriptedRunAgent([{ message: "ok", toolCalls: [] }]),
+      threadOps: ops,
+      buildContextMessage: () => "follow-up",
+    });
+
+    const stateManager = createAgentStateManager({
+      initialState: { systemPrompt: "system" },
+    });
+    await session.runSession({ stateManager });
+
+    const hydrates = log.filter((l) => l.op === "hydrateThread");
+    expect(hydrates).toHaveLength(1);
+    expect(at(hydrates, 0).args[0]).toBe("existing-thread");
+
+    // hydrate runs strictly before loadThreadState so the load sees
+    // fresh data when a cold tier is wired.
+    const hydrateIdx = log.findIndex((l) => l.op === "hydrateThread");
+    const loadIdx = log.findIndex((l) => l.op === "loadThreadState");
+    expect(hydrateIdx).toBeLessThan(loadIdx);
+  });
+
+  it("hydrates the *source* thread (not the new one) on mode:'fork'", async () => {
+    const { ops, log, stateStore } = createMockThreadOps();
+    stateStore.set("src-thread", { tasks: [], custom: {} });
+
+    const session = await createSession({
+      agentName: "TestAgent",
+      thread: { mode: "fork", threadId: "src-thread" },
+      runAgent: createScriptedRunAgent([{ message: "ok", toolCalls: [] }]),
+      threadOps: ops,
+      buildContextMessage: () => "fork me",
+    });
+
+    const stateManager = createAgentStateManager({
+      initialState: { systemPrompt: "system" },
+    });
+    const result = await session.runSession({ stateManager });
+
+    const hydrates = log.filter((l) => l.op === "hydrateThread");
+    expect(hydrates).toHaveLength(1);
+    expect(at(hydrates, 0).args[0]).toBe("src-thread");
+
+    // hydrate runs before forkThread so the source is hot before
+    // the in-Redis fork copy.
+    const hydrateIdx = log.findIndex((l) => l.op === "hydrateThread");
+    const forkIdx = log.findIndex((l) => l.op === "forkThread");
+    expect(hydrateIdx).toBeLessThan(forkIdx);
+
+    // Flush still targets the *new* thread.
+    const flushes = log.filter((l) => l.op === "flushThread");
+    expect(flushes).toHaveLength(1);
+    expect(at(flushes, 0).args[0]).toBe(result.threadId);
+    expect(at(flushes, 0).args[0]).not.toBe("src-thread");
+  });
+
+  it("flushThread runs even when the session fails", async () => {
+    const { ops, log } = createMockThreadOps();
+
+    const session = await createSession({
+      agentName: "TestAgent",
+      thread: { mode: "new", threadId: "fail-thread" },
+      runAgent: async () => {
+        throw new Error("boom");
+      },
+      threadOps: ops,
+      buildContextMessage: () => "hi",
+    });
+
+    const stateManager = createAgentStateManager({
+      initialState: { systemPrompt: "system" },
+    });
+    await expect(session.runSession({ stateManager })).rejects.toThrow(/boom/);
+
+    const flushes = log.filter((l) => l.op === "flushThread");
+    expect(flushes).toHaveLength(1);
+    expect(at(flushes, 0).args[0]).toBe("fail-thread");
+  });
+
+  it("flushThread runs after saveThreadState", async () => {
+    const { ops, log } = createMockThreadOps();
+    const session = await createSession({
+      agentName: "TestAgent",
+      thread: { mode: "new", threadId: "ordered-thread" },
+      runAgent: createScriptedRunAgent([{ message: "ok", toolCalls: [] }]),
+      threadOps: ops,
+      buildContextMessage: () => "hi",
+    });
+    const stateManager = createAgentStateManager({
+      initialState: { systemPrompt: "system" },
+    });
+    await session.runSession({ stateManager });
+
+    const saveIdx = log.findIndex((l) => l.op === "saveThreadState");
+    const flushIdx = log.findIndex((l) => l.op === "flushThread");
+    expect(saveIdx).toBeGreaterThanOrEqual(0);
+    expect(flushIdx).toBeGreaterThan(saveIdx);
+  });
 });

package/src/lib/session/session.ts

@@ -163,8 +163,7 @@ export async function createSession<
     unknown,
     SandboxCapability
   >;
-  const wideOps = (): WideSandboxOps =>
-    sandboxOps as unknown as WideSandboxOps;
+  const wideOps = (): WideSandboxOps => sandboxOps as unknown as WideSandboxOps;
   // ---------------------------------------------------------------------------
   // Thread resolution
   // ---------------------------------------------------------------------------
@@ -199,6 +198,8 @@ export async function createSession<
     forkThread,
     loadThreadState,
     saveThreadState,
+    hydrateThread,
+    flushThread,
   } = threadOps;
 
   const plugins: ToolMap[string][] = [];
@@ -276,10 +277,7 @@ export async function createSession<
       // defaults are. Both surfaces consult `resolveSessionLifecycle`
       // (or its type-level equivalent) before checking individual
       // mode/shutdown values.
-      const lifecycle = resolveSessionLifecycle(
-        sandboxInit,
-        sandboxShutdown
-      );
+      const lifecycle = resolveSessionLifecycle(sandboxInit, sandboxShutdown);
       const sandboxMode: SandboxInit["mode"] | undefined = lifecycle.mode;
       const resolvedShutdown: SubagentSandboxShutdown = lifecycle.shutdown;
       let sandboxId: string | undefined;
@@ -383,22 +381,6 @@ export async function createSession<
         });
       }
 
-      if (hooks.onSessionStart) {
-        await hooks.onSessionStart({
-          threadId,
-          agentName,
-          metadata,
-        });
-      }
-
-      log.info("session started", {
-        agentName,
-        threadId,
-        threadMode,
-        maxTurns,
-        ...(sandboxId && { sandboxId }),
-      });
-
       const sessionStartMs = Date.now();
       const systemPrompt = stateManager.getSystemPrompt();
 
@@ -411,10 +393,19 @@ export async function createSession<
       };
 
       if (threadMode === "fork" && sourceThreadId) {
+        // Pull the source thread from the cold tier into Redis (if a
+        // cold store is configured for this adapter) before the
+        // in-Redis fork copy runs. Hydrate is a no-op when the source
+        // is already hot or when no cold tier is wired.
+        await hydrateThread(sourceThreadId, threadKey);
         await forkThread(sourceThreadId, threadId, threadKey);
         const forkedSlice = await loadThreadState(threadId, threadKey);
         if (forkedSlice) rehydrateFromSlice(forkedSlice);
       } else if (threadMode === "continue") {
+        // Pull the thread from the cold tier into Redis before any
+        // appends. No-op when the thread is already hot or when no
+        // cold tier is wired.
+        await hydrateThread(threadId, threadKey);
         // "continue" — thread already exists, just append the new message
         const continuedSlice = await loadThreadState(threadId, threadKey);
         if (continuedSlice) rehydrateFromSlice(continuedSlice);
@@ -490,6 +481,22 @@ export async function createSession<
       let exitReason: SessionExitReason = "completed";
       let finalMessage: M | null = null;
 
+      if (hooks.onSessionStart) {
+        await hooks.onSessionStart({
+          threadId,
+          agentName,
+          metadata,
+        });
+      }
+
+      log.info("session started", {
+        agentName,
+        threadId,
+        threadMode,
+        maxTurns,
+        ...(sandboxId && { sandboxId }),
+      });
+
       try {
         // Per-turn assistant message id. Pre-generated in the workflow
         // so the runAgent activity can truncate the thread from this id
@@ -644,6 +651,24 @@ export async function createSession<
           });
         }
 
+        // Archive the thread to the durable cold tier (S3 / R2 / etc.)
+        // after the state slice has been written. No-op when no cold
+        // store is wired into the adapter. Best-effort — failures
+        // must not mask the original exit reason and the thread is
+        // still readable from Redis via its TTL window.
+        try {
+          await flushThread(threadId, threadKey);
+        } catch (flushError) {
+          log.warn("failed to flush thread to cold tier", {
+            agentName,
+            threadId,
+            error:
+              flushError instanceof Error
+                ? flushError.message
+                : String(flushError),
+          });
+        }
+
         await callSessionEnd(exitReason, stateManager.getTurns());
 
         if (sandboxOwned && sandboxId && sandboxOps) {

package/src/lib/session/types.ts

@@ -109,6 +109,28 @@ export interface ThreadOps<TContent = string> {
     state: PersistedThreadState,
     threadKey?: string
   ): Promise<void>;
+  /**
+   * Restore the thread's contents from the durable cold tier (if any)
+   * into Redis. Called once on session entry for `mode: "continue"`
+   * and `mode: "fork"` so the rest of the loop reads the freshest data.
+   *
+   * Adapters configured without a cold-store implementation treat this
+   * as a no-op. Implementations must be **idempotent** — Temporal
+   * retries the activity on transient failures, and a thread that is
+   * already hot must not be wiped.
+   */
+  hydrateThread(threadId: string, threadKey?: string): Promise<void>;
+  /**
+   * Archive the thread's contents to the durable cold tier and
+   * (optionally) drop the hot-tier Redis keys. Called once in the
+   * session's `finally` block on every exit path, after
+   * `saveThreadState`.
+   *
+   * Adapters configured without a cold-store implementation treat this
+   * as a no-op. Implementations must be **idempotent** — the cold
+   * tier is last-writer-wins and a retried flush must converge.
+   */
+  flushThread(threadId: string, threadKey?: string): Promise<void>;
 }
 
 /**

package/src/lib/thread/cold-store.test.ts

@@ -0,0 +1,193 @@
+import { describe, expect, it, beforeEach } from "vitest";
+import { gunzipSync, gzipSync } from "node:zlib";
+import { createS3ColdStore, type S3LikeClient } from "./cold-store";
+import type { ThreadSnapshot } from "./cold-store";
+
+interface StoredObject {
+  body: Buffer;
+  contentType?: string;
+}
+
+interface CommandInput {
+  Bucket: string;
+  Key: string;
+  Body?: Buffer | string;
+  ContentType?: string;
+}
+
+/**
+ * Minimal in-memory S3-shaped client. The `send()` method dispatches
+ * by the command's constructor name, mirroring the contract that
+ * `@aws-sdk/client-s3` exposes.
+ */
+function createFakeS3(): {
+  s3: S3LikeClient;
+  store: Map<string, StoredObject>;
+  calls: { get: number; put: number; delete: number };
+} {
+  const store = new Map<string, StoredObject>();
+  const calls = { get: 0, put: 0, delete: 0 };
+
+  const compositeKey = (bucket: string, key: string): string =>
+    `${bucket}/${key}`;
+
+  const s3: S3LikeClient = {
+    async send<TInput, TOutput>(
+      command: { input: TInput } & object
+    ): Promise<TOutput> {
+      const name = (command as { constructor: { name: string } }).constructor
+        .name;
+      const input = command.input as unknown as CommandInput;
+      const fullKey = compositeKey(input.Bucket, input.Key);
+      if (name === "GetObjectCommand") {
+        calls.get++;
+        const obj = store.get(fullKey);
+        if (!obj) {
+          const err = new Error("NoSuchKey") as Error & { name: string };
+          err.name = "NoSuchKey";
+          throw err;
+        }
+        return { Body: obj.body } as unknown as TOutput;
+      }
+      if (name === "PutObjectCommand") {
+        calls.put++;
+        const body =
+          typeof input.Body === "string"
+            ? Buffer.from(input.Body, "utf8")
+            : (input.Body as Buffer);
+        store.set(fullKey, {
+          body,
+          ...(input.ContentType && { contentType: input.ContentType }),
+        });
+        return {} as TOutput;
+      }
+      if (name === "DeleteObjectCommand") {
+        calls.delete++;
+        store.delete(fullKey);
+        return {} as TOutput;
+      }
+      throw new Error(`unknown command: ${name}`);
+    },
+  };
+
+  return { s3, store, calls };
+}
+
+const sampleSnapshot: ThreadSnapshot = {
+  v: 1,
+  messages: [JSON.stringify({ id: "m1", text: "hi" })],
+  state: null,
+  dedupIds: ["m1"],
+};
+
+describe("createS3ColdStore", () => {
+  let fake: ReturnType<typeof createFakeS3>;
+
+  beforeEach(() => {
+    fake = createFakeS3();
+  });
+
+  it("read returns null when no object exists for the thread", async () => {
+    const cold = createS3ColdStore({
+      s3: fake.s3,
+      bucket: "test-bucket",
+    });
+    expect(await cold.read("messages", "t-1")).toBeNull();
+  });
+
+  it("write then read round-trips a snapshot (gzip default)", async () => {
+    const cold = createS3ColdStore({
+      s3: fake.s3,
+      bucket: "test-bucket",
+      prefix: "prod/threads",
+    });
+    await cold.write("messages", "t-1", sampleSnapshot);
+    expect(await cold.read("messages", "t-1")).toEqual(sampleSnapshot);
+
+    // Verify the on-disk format is gzip + JSON.
+    const stored = fake.store.get("test-bucket/prod/threads/messages/t-1.json.gz");
+    expect(stored).toBeDefined();
+    if (!stored) throw new Error("expected stored object");
+    expect(stored.contentType).toBe("application/gzip");
+    const decoded = JSON.parse(gunzipSync(stored.body).toString("utf8"));
+    expect(decoded).toEqual(sampleSnapshot);
+  });
+
+  it("supports plain JSON when gzip is disabled", async () => {
+    const cold = createS3ColdStore({
+      s3: fake.s3,
+      bucket: "test-bucket",
+      gzip: false,
+    });
+    await cold.write("messages", "t-1", sampleSnapshot);
+
+    const stored = fake.store.get("test-bucket/threads/messages/t-1.json");
+    expect(stored).toBeDefined();
+    if (!stored) throw new Error("expected stored object");
+    expect(stored.contentType).toBe("application/json");
+    expect(JSON.parse(stored.body.toString("utf8"))).toEqual(sampleSnapshot);
+
+    expect(await cold.read("messages", "t-1")).toEqual(sampleSnapshot);
+  });
+
+  it("uses 'threads' as the default prefix", async () => {
+    const cold = createS3ColdStore({
+      s3: fake.s3,
+      bucket: "test-bucket",
+    });
+    await cold.write("messages", "abc", sampleSnapshot);
+    expect(fake.store.has("test-bucket/threads/messages/abc.json.gz")).toBe(true);
+  });
+
+  it("delete removes the underlying object", async () => {
+    const cold = createS3ColdStore({
+      s3: fake.s3,
+      bucket: "test-bucket",
+    });
+    await cold.write("messages", "t-1", sampleSnapshot);
+    await cold.delete("messages", "t-1");
+    expect(await cold.read("messages", "t-1")).toBeNull();
+    expect(fake.store.size).toBe(0);
+  });
+
+  it("read treats 404 errors as null (not throw)", async () => {
+    const cold = createS3ColdStore({
+      s3: {
+        async send() {
+          const err = {
+            name: "NotFound",
+            $metadata: { httpStatusCode: 404 },
+          };
+          throw err;
+        },
+      } as unknown as S3LikeClient,
+      bucket: "test-bucket",
+    });
+    expect(await cold.read("messages", "t-1")).toBeNull();
+  });
+
+  it("read rethrows non-404 errors", async () => {
+    const cold = createS3ColdStore({
+      s3: {
+        async send() {
+          throw new Error("AccessDenied");
+        },
+      } as unknown as S3LikeClient,
+      bucket: "test-bucket",
+    });
+    await expect(cold.read("messages", "t-1")).rejects.toThrow("AccessDenied");
+  });
+
+  it("falls back to gunzip when the cold object is gzip-encoded but read with gzip:true", async () => {
+    // Pre-seed the fake S3 with a gzip-encoded payload, then read.
+    const compressed = gzipSync(Buffer.from(JSON.stringify(sampleSnapshot)));
+    fake.store.set("test-bucket/threads/messages/t-1.json.gz", {
+      body: compressed,
+    });
+    const cold = createS3ColdStore({
+      s3: fake.s3,
+      bucket: "test-bucket",
+    });
+    expect(await cold.read("messages", "t-1")).toEqual(sampleSnapshot);
+  });
+});