zeitlich 0.2.45 → 0.2.46

package/dist/cold-store-CFHwemBJ.d.ts

@@ -0,0 +1,117 @@
+import { P as PersistedThreadState } from './types-CwN6_tAL.js';
+
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+interface ThreadSnapshot {
+    v: 1;
+    messages: string[];
+    state: PersistedThreadState | null;
+    dedupIds: string[];
+}
+/** Pluggable cold archive for thread snapshots. */
+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.
+ */
+interface S3LikeClient {
+    send<TInput, TOutput>(command: {
+        input: TInput;
+    } & object): Promise<TOutput>;
+}
+/** Configuration for the built-in S3 cold store. */
+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;
+}
+/**
+ * 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",
+ * });
+ * ```
+ */
+declare function createS3ColdStore(config: S3ColdStoreConfig): ColdThreadStore;
+
+export { type ColdThreadStore as C, type S3ColdStoreConfig as S, type ThreadSnapshot as T, type S3LikeClient as a, createS3ColdStore as c };

package/dist/index.cjs

@@ -5,6 +5,8 @@ var z14 = require('zod');
 var crypto = require('crypto');
 var common = require('@temporalio/common');
 var path = require('path');
+var zlib = require('zlib');
+var clientS3 = require('@aws-sdk/client-s3');
 var activity = require('@temporalio/activity');
 var fs = require('fs');
 
@@ -1038,7 +1040,9 @@ async function createSession(config) {
     appendAgentMessage,
     forkThread,
     loadThreadState,
-    saveThreadState
+    saveThreadState,
+    hydrateThread,
+    flushThread
   } = threadOps;
   const plugins = [];
   let destroySubagentSandboxes;
@@ -1182,10 +1186,12 @@ async function createSession(config) {
         });
       };
       if (threadMode === "fork" && sourceThreadId) {
+        await hydrateThread(sourceThreadId, threadKey);
         await forkThread(sourceThreadId, threadId, threadKey);
         const forkedSlice = await loadThreadState(threadId, threadKey);
         if (forkedSlice) rehydrateFromSlice(forkedSlice);
       } else if (threadMode === "continue") {
+        await hydrateThread(threadId, threadKey);
         const continuedSlice = await loadThreadState(threadId, threadKey);
         if (continuedSlice) rehydrateFromSlice(continuedSlice);
       } else {
@@ -1367,6 +1373,15 @@ async function createSession(config) {
             error: persistError instanceof Error ? persistError.message : String(persistError)
           });
         }
+        try {
+          await flushThread(threadId, threadKey);
+        } catch (flushError) {
+          workflow.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) {
           switch (resolvedShutdown) {
@@ -1450,6 +1465,9 @@ function getThreadMetaKey(threadKey, threadId) {
 function getThreadStateKey(threadKey, threadId) {
   return `${threadKey}:state:thread:${threadId}`;
 }
+function getThreadDedupKey(threadId, dedupId) {
+  return `dedup:${dedupId}:thread:${threadId}`;
+}
 
 // src/lib/types.ts
 function isTerminalStatus(status) {
@@ -2594,9 +2612,6 @@ redis.call('EXPIRE', KEYS[2], tonumber(ARGV[1]))
 redis.call('SET', KEYS[1], '1', 'EX', tonumber(ARGV[1]))
 return 1
 `;
-function getDedupKey(threadId, id) {
-  return `dedup:${id}:thread:${threadId}`;
-}
 function createThreadManager(config) {
   const {
     redis,
@@ -2604,11 +2619,13 @@ function createThreadManager(config) {
     key = "messages",
     serialize = (m) => JSON.stringify(m),
     deserialize = (raw) => JSON.parse(raw),
-    idOf
+    idOf,
+    ttlSeconds = THREAD_TTL_SECONDS
   } = config;
   const redisKey = getThreadListKey(key, threadId);
   const metaKey = getThreadMetaKey(key, threadId);
   const stateKey = getThreadStateKey(key, threadId);
+  const dedupKey = (id) => getThreadDedupKey(threadId, id);
   async function assertThreadExists() {
     const exists = await redis.exists(metaKey);
     if (!exists) {
@@ -2618,7 +2635,7 @@ function createThreadManager(config) {
   return {
     async initialize() {
       await redis.del(redisKey);
-      await redis.set(metaKey, "1", "EX", THREAD_TTL_SECONDS);
+      await redis.set(metaKey, "1", "EX", ttlSeconds);
     },
     async load() {
       await assertThreadExists();
@@ -2630,18 +2647,17 @@ function createThreadManager(config) {
       await assertThreadExists();
       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);
       }
     },
     async fork(newThreadId) {
@@ -2656,11 +2672,11 @@ function createThreadManager(config) {
       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;
     },
@@ -2675,15 +2691,13 @@ function createThreadManager(config) {
       const existingIds = existing.map((raw) => idOf(deserialize(raw))).filter((id) => 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() {
       await redis.del(redisKey, metaKey, stateKey);
@@ -2695,12 +2709,7 @@ function createThreadManager(config) {
     },
     async saveState(state) {
       await assertThreadExists();
-      await redis.set(
-        stateKey,
-        JSON.stringify(state),
-        "EX",
-        THREAD_TTL_SECONDS
-      );
+      await redis.set(stateKey, JSON.stringify(state), "EX", ttlSeconds);
     },
     async deleteState() {
       await redis.del(stateKey);
@@ -2729,19 +2738,202 @@ function createThreadManager(config) {
       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);
       }
       if (removedIds.length > 0) {
-        await redis.del(
-          ...removedIds.map((id) => getDedupKey(threadId, id))
+        await redis.del(...removedIds.map(dedupKey));
+      }
+    }
+  };
+}
+function joinKey(parts) {
+  return parts.map((p) => p.replace(/^\/+|\/+$/g, "")).filter((p) => p.length > 0).join("/");
+}
+function buildKey(prefix, threadKey, threadId, gzip) {
+  const ext = gzip ? "json.gz" : "json";
+  return joinKey([
+    prefix ?? "threads",
+    threadKey,
+    `${threadId}.${ext}`
+  ]);
+}
+async function streamToBuffer(body) {
+  if (body == null) return Buffer.alloc(0);
+  if (body instanceof Uint8Array) return Buffer.from(body);
+  if (typeof body.transformToByteArray === "function") {
+    const bytes = await body.transformToByteArray();
+    return Buffer.from(bytes);
+  }
+  if (typeof body.arrayBuffer === "function") {
+    const ab = await body.arrayBuffer();
+    return Buffer.from(ab);
+  }
+  const chunks = [];
+  for await (const chunk of body) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks);
+}
+function createS3ColdStore(config) {
+  const { s3, bucket, prefix, gzip = true } = config;
+  const contentType = config.contentType ?? (gzip ? "application/gzip" : "application/json");
+  return {
+    async read(threadKey, threadId) {
+      const Key = buildKey(prefix, threadKey, threadId, gzip);
+      try {
+        const resp = await s3.send(
+          new clientS3.GetObjectCommand({ Bucket: bucket, Key })
         );
+        const buf = await streamToBuffer(resp.Body);
+        const json = gzip ? zlib.gunzipSync(buf).toString("utf8") : buf.toString("utf8");
+        return JSON.parse(json);
+      } catch (err) {
+        if (isNotFound(err)) return null;
+        throw err;
       }
+    },
+    async write(threadKey, threadId, snapshot) {
+      const Key = buildKey(prefix, threadKey, threadId, gzip);
+      const json = JSON.stringify(snapshot);
+      const body = gzip ? zlib.gzipSync(Buffer.from(json, "utf8")) : json;
+      await s3.send(
+        new clientS3.PutObjectCommand({
+          Bucket: bucket,
+          Key,
+          Body: body,
+          ContentType: contentType
+        })
+      );
+    },
+    async delete(threadKey, threadId) {
+      const Key = buildKey(prefix, threadKey, threadId, gzip);
+      await s3.send(new clientS3.DeleteObjectCommand({ Bucket: bucket, Key }));
     }
   };
 }
+function isNotFound(err) {
+  if (typeof err !== "object" || err === null) return false;
+  const e = err;
+  return e.name === "NoSuchKey" || e.Code === "NoSuchKey" || e.code === "NoSuchKey" || e.name === "NotFound" || e.$metadata?.httpStatusCode === 404;
+}
+
+// src/lib/thread/snapshot.ts
+async function encodeSnapshot(config) {
+  const { redis, threadKey, threadId, idOf } = config;
+  const metaKey = getThreadMetaKey(threadKey, threadId);
+  if (await redis.exists(metaKey) === 0) {
+    return null;
+  }
+  const listKey = getThreadListKey(threadKey, threadId);
+  const stateKey = getThreadStateKey(threadKey, threadId);
+  const messages = await redis.lrange(listKey, 0, -1);
+  const stateRaw = await redis.get(stateKey);
+  const state = stateRaw == null ? null : JSON.parse(stateRaw);
+  const dedupIds = idOf ? messages.map(idOf) : [];
+  return { v: 1, messages, state, dedupIds };
+}
+async function applySnapshot(config) {
+  const {
+    redis,
+    threadKey,
+    threadId,
+    snapshot,
+    ttlSeconds = THREAD_TTL_SECONDS
+  } = config;
+  const metaKey = getThreadMetaKey(threadKey, threadId);
+  if (await redis.exists(metaKey) === 1) {
+    return;
+  }
+  const listKey = getThreadListKey(threadKey, threadId);
+  const stateKey = getThreadStateKey(threadKey, threadId);
+  await redis.del(listKey, stateKey);
+  const pipeline = redis.pipeline();
+  if (snapshot.messages.length > 0) {
+    pipeline.rpush(listKey, ...snapshot.messages);
+    pipeline.expire(listKey, ttlSeconds);
+  }
+  if (snapshot.state != null) {
+    pipeline.set(stateKey, JSON.stringify(snapshot.state), "EX", ttlSeconds);
+  }
+  for (const id of snapshot.dedupIds) {
+    pipeline.set(getThreadDedupKey(threadId, id), "1", "EX", ttlSeconds);
+  }
+  const results = await pipeline.exec();
+  if (results) {
+    const firstErr = results.find(([err]) => err)?.[0] ?? null;
+    if (firstErr) {
+      await redis.del(
+        listKey,
+        stateKey,
+        ...snapshot.dedupIds.map((id) => getThreadDedupKey(threadId, id))
+      ).catch(() => void 0);
+      throw firstErr;
+    }
+  }
+  await redis.set(metaKey, "1", "EX", ttlSeconds);
+}
+async function clearHotTier(config) {
+  const { redis, threadKey, threadId, dedupIds = [] } = config;
+  const keys = [
+    getThreadListKey(threadKey, threadId),
+    getThreadMetaKey(threadKey, threadId),
+    getThreadStateKey(threadKey, threadId),
+    ...dedupIds.map((id) => getThreadDedupKey(threadId, id))
+  ];
+  await redis.del(...keys);
+}
+
+// src/lib/thread/tiered.ts
+function createTieredThreadManager(config) {
+  const {
+    redis,
+    threadId,
+    key = "messages",
+    coldStore,
+    idOf,
+    deserialize = (raw) => JSON.parse(raw),
+    ttlSeconds = THREAD_TTL_SECONDS
+  } = config;
+  const base = createThreadManager(config);
+  const rawIdOf = idOf ? (raw) => idOf(deserialize(raw)) : void 0;
+  return Object.assign(base, {
+    async hydrate() {
+      if (!coldStore) return;
+      const snapshot = await coldStore.read(key, threadId);
+      if (!snapshot) return;
+      await applySnapshot({
+        redis,
+        threadKey: key,
+        threadId,
+        snapshot,
+        ttlSeconds
+      });
+    },
+    async flush(opts) {
+      if (!coldStore) return;
+      const snapshot = await encodeSnapshot({
+        redis,
+        threadKey: key,
+        threadId,
+        ...rawIdOf ? { idOf: rawIdOf } : {}
+      });
+      if (!snapshot) return;
+      await coldStore.write(key, threadId, snapshot);
+      const deleteHot = opts?.deleteHot ?? true;
+      if (deleteHot) {
+        await clearHotTier({
+          redis,
+          threadKey: key,
+          threadId,
+          dedupIds: snapshot.dedupIds
+        });
+      }
+    }
+  });
+}
 function getActivityContext() {
   try {
     const ctx = activity.Context.current();
@@ -3685,10 +3877,12 @@ exports.SandboxNotFoundError = SandboxNotFoundError;
 exports.SandboxNotSupportedError = SandboxNotSupportedError;
 exports.THREAD_TTL_SECONDS = THREAD_TTL_SECONDS;
 exports.VirtualFileSystem = VirtualFileSystem;
+exports.applySnapshot = applySnapshot;
 exports.applyVirtualTreeMutations = applyVirtualTreeMutations;
 exports.askUserQuestionTool = askUserQuestionTool;
 exports.bashHandler = bashHandler;
 exports.bashTool = bashTool;
+exports.clearHotTier = clearHotTier;
 exports.composeHooks = composeHooks;
 exports.createAgentStateManager = createAgentStateManager;
 exports.createAskUserQuestionHandler = createAskUserQuestionHandler;
@@ -3697,12 +3891,14 @@ exports.createObservabilityHooks = createObservabilityHooks;
 exports.createReadSkillHandler = createReadSkillHandler;
 exports.createReadSkillTool = createReadSkillTool;
 exports.createRunAgentActivity = createRunAgentActivity;
+exports.createS3ColdStore = createS3ColdStore;
 exports.createSession = createSession;
 exports.createTaskCreateHandler = createTaskCreateHandler;
 exports.createTaskGetHandler = createTaskGetHandler;
 exports.createTaskListHandler = createTaskListHandler;
 exports.createTaskUpdateHandler = createTaskUpdateHandler;
 exports.createThreadManager = createThreadManager;
+exports.createTieredThreadManager = createTieredThreadManager;
 exports.createToolRouter = createToolRouter;
 exports.createVirtualFsActivities = createVirtualFsActivities;
 exports.defineSubagent = defineSubagent;
@@ -3711,12 +3907,15 @@ exports.defineTool = defineTool;
 exports.defineWorkflow = defineWorkflow;
 exports.editHandler = editHandler;
 exports.editTool = editTool;
+exports.encodeSnapshot = encodeSnapshot;
 exports.filesWithMimeType = filesWithMimeType;
 exports.formatVirtualFileTree = formatVirtualFileTree;
 exports.getActivityContext = getActivityContext;
 exports.getShortId = getShortId;
+exports.getThreadDedupKey = getThreadDedupKey;
 exports.getThreadListKey = getThreadListKey;
 exports.getThreadMetaKey = getThreadMetaKey;
+exports.getThreadStateKey = getThreadStateKey;
 exports.globHandler = globHandler;
 exports.globTool = globTool;
 exports.grepTool = grepTool;