zeitlich 0.2.45 → 0.2.46

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

@@ -0,0 +1,250 @@
+/**
+ * Pluggable cold-tier interface for thread archives.
+ *
+ * Zeitlich's thread manager is a Redis-backed hot tier optimized for
+ * the duration of a workflow run. A `ColdThreadStore` provides the
+ * durable archive: each thread is serialized to a single
+ * {@link ThreadSnapshot} blob (messages + persisted state slice +
+ * dedup-id ledger) at session-exit time, and restored at session-entry
+ * time when the workflow is resumed or forked.
+ *
+ * The contract is intentionally minimal — one read, one write, one
+ * delete keyed by `(threadKey, threadId)`. Any storage backend that
+ * can satisfy these three calls (S3, R2, GCS, Postgres, the local
+ * filesystem, etc.) can plug into the same tiered manager.
+ *
+ * Concurrency assumption: zeitlich assumes a single active session
+ * per `(threadKey, threadId)` at a time, so cold writes are
+ * last-writer-wins; no compare-and-swap is required.
+ */
+
+import { gzipSync, gunzipSync } from "node:zlib";
+import type { PersistedThreadState } from "../state/types";
+import { DeleteObjectCommand, GetObjectCommand, PutObjectCommand } from "@aws-sdk/client-s3";
+
+/**
+ * Serialized form of a thread that can be written to and read from a
+ * {@link ColdThreadStore}.
+ *
+ * `messages` is the list of raw-serialized message strings exactly as
+ * they were stored in the Redis list — keeping the cold tier opaque
+ * to the adapter-specific message envelope. `state` is the
+ * {@link PersistedThreadState} that the session writes via
+ * `saveThreadState` on every exit path, or `null` if none has been
+ * written yet. `dedupIds` lets the tiered manager re-prime the
+ * idempotent-append dedup markers when restoring, so a rewind retry
+ * after a continue cannot accidentally re-append a message.
+ */
+export interface ThreadSnapshot {
+  v: 1;
+  messages: string[];
+  state: PersistedThreadState | null;
+  dedupIds: string[];
+}
+
+/** Pluggable cold archive for thread snapshots. */
+export interface ColdThreadStore {
+  /**
+   * Read the latest snapshot for `(threadKey, threadId)`, or return
+   * `null` if no snapshot has ever been written.
+   */
+  read(
+    threadKey: string,
+    threadId: string
+  ): Promise<ThreadSnapshot | null>;
+  /**
+   * Persist `snapshot` as the latest archive for `(threadKey,
+   * threadId)`. Overwrites any prior snapshot in place.
+   */
+  write(
+    threadKey: string,
+    threadId: string,
+    snapshot: ThreadSnapshot
+  ): Promise<void>;
+  /**
+   * Permanently remove the archive for `(threadKey, threadId)`.
+   * No-op if no snapshot exists.
+   */
+  delete(threadKey: string, threadId: string): Promise<void>;
+}
+
+/**
+ * Compact, duck-typed shape of an S3 client. Zeitlich only needs the
+ * `send(...)` method; declaring this locally avoids forcing
+ * `@aws-sdk/client-s3` to be installed when the consumer is using a
+ * different cold-store backend.
+ */
+export interface S3LikeClient {
+  send<TInput, TOutput>(
+    command: { input: TInput } & object
+  ): Promise<TOutput>;
+}
+
+/** Configuration for the built-in S3 cold store. */
+export interface S3ColdStoreConfig {
+  /** An `@aws-sdk/client-s3` `S3Client` (or duck-typed equivalent). */
+  s3: S3LikeClient;
+  /** S3 bucket that holds the archive. */
+  bucket: string;
+  /**
+   * Optional key prefix applied to every object. The final key layout
+   * is `${prefix}/${threadKey}/${threadId}.json[.gz]` with leading
+   * slashes stripped. Defaults to `"threads"`.
+   */
+  prefix?: string;
+  /**
+   * Gzip the JSON payload before uploading and assume gzip on read.
+   * Defaults to `true` — message lists are highly compressible.
+   */
+  gzip?: boolean;
+  /**
+   * Optional `Content-Type` override. Defaults to
+   * `application/json` (or `application/gzip` when `gzip: true`).
+   */
+  contentType?: string;
+}
+
+function joinKey(parts: string[]): string {
+  return parts
+    .map((p) => p.replace(/^\/+|\/+$/g, ""))
+    .filter((p) => p.length > 0)
+    .join("/");
+}
+
+function buildKey(
+  prefix: string | undefined,
+  threadKey: string,
+  threadId: string,
+  gzip: boolean
+): string {
+  const ext = gzip ? "json.gz" : "json";
+  return joinKey([
+    prefix ?? "threads",
+    threadKey,
+    `${threadId}.${ext}`,
+  ]);
+}
+
+async function streamToBuffer(
+  body: unknown
+): Promise<Buffer> {
+  if (body == null) return Buffer.alloc(0);
+  if (body instanceof Uint8Array) return Buffer.from(body);
+  if (typeof (body as { transformToByteArray?: () => Promise<Uint8Array> })
+    .transformToByteArray === "function") {
+    const bytes = await (
+      body as { transformToByteArray: () => Promise<Uint8Array> }
+    ).transformToByteArray();
+    return Buffer.from(bytes);
+  }
+  if (typeof (body as { arrayBuffer?: () => Promise<ArrayBuffer> })
+    .arrayBuffer === "function") {
+    const ab = await (
+      body as { arrayBuffer: () => Promise<ArrayBuffer> }
+    ).arrayBuffer();
+    return Buffer.from(ab);
+  }
+  // Node.js Readable stream fallback
+  const chunks: Buffer[] = [];
+  for await (const chunk of body as AsyncIterable<Buffer | Uint8Array>) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks);
+}
+
+/**
+ * Build an S3-backed {@link ColdThreadStore}.
+ *
+ * One object per thread at
+ * `${prefix}/${threadKey}/${threadId}.json[.gz]`, JSON-encoded and
+ * gzip-compressed by default. The consumer owns the `S3Client`
+ * instance, so credentials, region, and endpoint configuration live
+ * outside zeitlich.
+ *
+ * @example
+ * ```typescript
+ * import { S3Client } from "@aws-sdk/client-s3";
+ * import { createS3ColdStore } from "zeitlich";
+ *
+ * const coldStore = createS3ColdStore({
+ *   s3: new S3Client({ region: "us-east-1" }),
+ *   bucket: "my-threads",
+ *   prefix: "prod/threads",
+ * });
+ * ```
+ */
+export function createS3ColdStore(
+  config: S3ColdStoreConfig
+): ColdThreadStore {
+  const { s3, bucket, prefix, gzip = true } = config;
+  const contentType =
+    config.contentType ?? (gzip ? "application/gzip" : "application/json");
+
+  return {
+    async read(
+      threadKey: string,
+      threadId: string
+    ): Promise<ThreadSnapshot | null> {
+      const Key = buildKey(prefix, threadKey, threadId, gzip);
+
+      try {
+        const resp = (await s3.send(
+          new GetObjectCommand({ Bucket: bucket, Key })
+        )) as { Body?: unknown };
+        const buf = await streamToBuffer(resp.Body);
+        const json = gzip
+          ? gunzipSync(buf).toString("utf8")
+          : buf.toString("utf8");
+        return JSON.parse(json) as ThreadSnapshot;
+      } catch (err) {
+        if (isNotFound(err)) return null;
+        throw err;
+      }
+    },
+
+    async write(
+      threadKey: string,
+      threadId: string,
+      snapshot: ThreadSnapshot
+    ): Promise<void> {
+      const Key = buildKey(prefix, threadKey, threadId, gzip);
+      const json = JSON.stringify(snapshot);
+      const body = gzip ? gzipSync(Buffer.from(json, "utf8")) : json;
+
+      await s3.send(
+        new PutObjectCommand({
+          Bucket: bucket,
+          Key,
+          Body: body,
+          ContentType: contentType,
+        })
+      );
+    },
+
+    async delete(
+      threadKey: string,
+      threadId: string
+    ): Promise<void> {
+      const Key = buildKey(prefix, threadKey, threadId, gzip);
+
+      await s3.send(new DeleteObjectCommand({ Bucket: bucket, Key }));
+    },
+  };
+}
+
+function isNotFound(err: unknown): boolean {
+  if (typeof err !== "object" || err === null) return false;
+  const e = err as {
+    name?: string;
+    Code?: string;
+    code?: string;
+    $metadata?: { httpStatusCode?: number };
+  };
+  return (
+    e.name === "NoSuchKey" ||
+    e.Code === "NoSuchKey" ||
+    e.code === "NoSuchKey" ||
+    e.name === "NotFound" ||
+    e.$metadata?.httpStatusCode === 404
+  );
+}

package/src/lib/thread/index.ts

@@ -4,6 +4,8 @@ export {
   THREAD_TTL_SECONDS,
   getThreadListKey,
   getThreadMetaKey,
+  getThreadStateKey,
+  getThreadDedupKey,
 } from "./keys";
 
 export type {
@@ -12,3 +14,33 @@ export type {
   ProviderThreadManager,
   ThreadManagerHooks,
 } from "./types";
+
+// Cold-tier (S3-style) thread archive
+export { createS3ColdStore } from "./cold-store";
+export type {
+  ColdThreadStore,
+  ThreadSnapshot,
+  S3LikeClient,
+  S3ColdStoreConfig,
+} from "./cold-store";
+
+// Tiered (Redis hot + pluggable cold) thread manager
+export { createTieredThreadManager } from "./tiered";
+export type {
+  TieredThreadManager,
+  TieredThreadManagerConfig,
+  FlushOptions,
+} from "./tiered";
+
+// Low-level snapshot helpers (advanced — for custom cold stores or
+// admin tooling that mirrors zeitlich's hot↔cold transitions).
+export {
+  encodeSnapshot,
+  applySnapshot,
+  clearHotTier,
+} from "./snapshot";
+export type {
+  EncodeSnapshotConfig,
+  ApplySnapshotConfig,
+  ClearHotTierConfig,
+} from "./snapshot";

package/src/lib/thread/keys.ts

@@ -92,3 +92,23 @@ export function getThreadStateKey(
 ): string {
   return `${threadKey}:state:thread:${threadId}`;
 }
+
+/**
+ * Build the Redis key that guards an idempotent append against a
+ * duplicate write of the message (or message batch) identified by
+ * `dedupId`. Zeitlich's thread manager writes one of these per
+ * single-message append (and one per batch for multi-message appends),
+ * keyed by the message id returned by the configured `idOf`.
+ *
+ * Note: the key layout intentionally does **not** include the
+ * `threadKey` prefix — the dedup namespace is shared across thread
+ * keys for a given `threadId`, mirroring the original internal
+ * implementation.
+ *
+ * @param threadId - Thread id as provided to the thread manager.
+ * @param dedupId  - Joined message ids (single message id for the
+ *                   common single-append case).
+ */
+export function getThreadDedupKey(threadId: string, dedupId: string): string {
+  return `dedup:${dedupId}:thread:${threadId}`;
+}

package/src/lib/thread/manager.ts

@@ -5,6 +5,7 @@ import {
   getThreadListKey,
   getThreadMetaKey,
   getThreadStateKey,
+  getThreadDedupKey,
 } from "./keys";
 
 /**
@@ -28,10 +29,6 @@ redis.call('SET', KEYS[1], '1', 'EX', tonumber(ARGV[1]))
 return 1
 `;
 
-function getDedupKey(threadId: string, id: string): string {
-  return `dedup:${id}:thread:${threadId}`;
-}
-
 /**
  * Creates a generic thread manager for handling conversation state in Redis.
  * Framework-agnostic — works with any serializable message type.
@@ -46,10 +43,12 @@ export function createThreadManager<T>(
     serialize = (m: T): string => JSON.stringify(m),
     deserialize = (raw: string): T => JSON.parse(raw) as T,
     idOf,
+    ttlSeconds = THREAD_TTL_SECONDS,
   } = config;
   const redisKey = getThreadListKey(key, threadId);
   const metaKey = getThreadMetaKey(key, threadId);
   const stateKey = getThreadStateKey(key, threadId);
+  const dedupKey = (id: string): string => getThreadDedupKey(threadId, id);
 
   async function assertThreadExists(): Promise<void> {
     const exists = await redis.exists(metaKey);
@@ -61,7 +60,7 @@ export function createThreadManager<T>(
   return {
     async initialize(): Promise<void> {
       await redis.del(redisKey);
-      await redis.set(metaKey, "1", "EX", THREAD_TTL_SECONDS);
+      await redis.set(metaKey, "1", "EX", ttlSeconds);
     },
 
     async load(): Promise<T[]> {
@@ -76,18 +75,17 @@ export function createThreadManager<T>(
 
       if (idOf) {
         const dedupId = messages.map(idOf).join(":");
-        const dedupKey = getDedupKey(threadId, dedupId);
         await redis.eval(
           APPEND_IDEMPOTENT_SCRIPT,
           2,
-          dedupKey,
+          dedupKey(dedupId),
           redisKey,
-          String(THREAD_TTL_SECONDS),
+          String(ttlSeconds),
           ...messages.map(serialize)
         );
       } else {
         await redis.rpush(redisKey, ...messages.map(serialize));
-        await redis.expire(redisKey, THREAD_TTL_SECONDS);
+        await redis.expire(redisKey, ttlSeconds);
       }
     },
 
@@ -103,11 +101,11 @@ export function createThreadManager<T>(
       if (data.length > 0) {
         const newKey = getThreadListKey(key, newThreadId);
         await redis.rpush(newKey, ...data);
-        await redis.expire(newKey, THREAD_TTL_SECONDS);
+        await redis.expire(newKey, ttlSeconds);
       }
       if (stateRaw != null) {
         const newStateKey = getThreadStateKey(key, newThreadId);
-        await redis.set(newStateKey, stateRaw, "EX", THREAD_TTL_SECONDS);
+        await redis.set(newStateKey, stateRaw, "EX", ttlSeconds);
       }
       return forked;
     },
@@ -125,15 +123,13 @@ export function createThreadManager<T>(
         .filter((id): id is string => typeof id === "string");
       await redis.del(redisKey);
       if (existingIds.length > 0) {
-        await redis.del(
-          ...existingIds.map((id) => getDedupKey(threadId, id))
-        );
+        await redis.del(...existingIds.map(dedupKey));
       }
       if (messages.length > 0) {
         await redis.rpush(redisKey, ...messages.map(serialize));
-        await redis.expire(redisKey, THREAD_TTL_SECONDS);
+        await redis.expire(redisKey, ttlSeconds);
       }
-      await redis.expire(metaKey, THREAD_TTL_SECONDS);
+      await redis.expire(metaKey, ttlSeconds);
     },
 
     async delete(): Promise<void> {
@@ -148,12 +144,7 @@ export function createThreadManager<T>(
 
     async saveState(state: PersistedThreadState): Promise<void> {
       await assertThreadExists();
-      await redis.set(
-        stateKey,
-        JSON.stringify(state),
-        "EX",
-        THREAD_TTL_SECONDS
-      );
+      await redis.set(stateKey, JSON.stringify(state), "EX", ttlSeconds);
     },
 
     async deleteState(): Promise<void> {
@@ -185,19 +176,17 @@ export function createThreadManager<T>(
       if (idx === -1) return;
       if (idx === 0) {
         await redis.del(redisKey);
-        await redis.expire(metaKey, THREAD_TTL_SECONDS);
+        await redis.expire(metaKey, ttlSeconds);
       } else {
         await redis.ltrim(redisKey, 0, idx - 1);
-        await redis.expire(redisKey, THREAD_TTL_SECONDS);
+        await redis.expire(redisKey, ttlSeconds);
       }
       // Clear dedup markers for the removed messages so that a rewind
       // retry which reuses the same ids (e.g. the same assistantId) can
       // re-append without the idempotent-append Lua script treating it
       // as a duplicate.
       if (removedIds.length > 0) {
-        await redis.del(
-          ...removedIds.map((id) => getDedupKey(threadId, id))
-        );
+        await redis.del(...removedIds.map(dedupKey));
       }
     },
   };

package/src/lib/thread/proxy.ts

@@ -56,5 +56,7 @@ export function createThreadOpsProxy(
     truncateThread: acts[p("truncateThread")],
     loadThreadState: acts[p("loadThreadState")],
     saveThreadState: acts[p("saveThreadState")],
+    hydrateThread: acts[p("hydrateThread")],
+    flushThread: acts[p("flushThread")],
   } as ActivityInterfaceFor<ThreadOps>;
 }