@kortyx/runtime 0.18.0 → 0.20.0

package/dist/index.js

@@ -1,6 +1,8 @@
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -14,6 +16,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -22,6 +32,7 @@ __export(index_exports, {
   buildInitialGraphState: () => buildInitialGraphState,
   captureGraphSnapshot: () => captureGraphSnapshot,
   clearRegisteredNodes: () => clearRegisteredNodes,
+  createCachingFrameworkAdapter: () => createCachingFrameworkAdapter,
   createExecutionGraph: () => createExecutionGraph,
   createFileWorkflowRegistry: () => createFileWorkflowRegistry,
   createFrameworkAdapterFromEnv: () => createFrameworkAdapterFromEnv,
@@ -29,6 +40,7 @@ __export(index_exports, {
   createInMemoryPendingRequestStore: () => createInMemoryPendingRequestStore,
   createInMemorySessionCheckpointStore: () => createInMemorySessionCheckpointStore,
   createInMemoryWorkflowRegistry: () => createInMemoryWorkflowRegistry,
+  createPostgresFrameworkAdapter: () => createPostgresFrameworkAdapter,
   createRedisFrameworkAdapter: () => createRedisFrameworkAdapter,
   getCheckpointer: () => getCheckpointer,
   getRegisteredNode: () => getRegisteredNode,
@@ -187,16 +199,89 @@ function getCheckpointer(key) {
   return saver;
 }
 
+// src/framework/caching.ts
+var providers = /* @__PURE__ */ new WeakMap();
+var attachedCaches = /* @__PURE__ */ new WeakSet();
+var storageBindings = /* @__PURE__ */ new WeakMap();
+function registerFrameworkCache(adapter, cache, ttlMs) {
+  providers.set(adapter, { cache, ttlMs });
+}
+function registerFrameworkCacheStorage(adapter, bind) {
+  storageBindings.set(adapter, bind);
+}
+function validateFrameworkCacheOptions(ttlMs, timeoutMs) {
+  if (!Number.isSafeInteger(ttlMs) || ttlMs < 1)
+    throw new TypeError("cache ttlMs must be a positive safe integer.");
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 1e3)
+    throw new TypeError(
+      "cache timeoutMs must be a positive integer no greater than 1000."
+    );
+}
+function createCachingFrameworkAdapter(options) {
+  const bind = storageBindings.get(options.storage);
+  if (!bind)
+    throw new TypeError(
+      "storage must support framework payload caching (currently PostgreSQL)."
+    );
+  const provider = providers.get(options.cache);
+  if (!provider)
+    throw new TypeError(
+      "cache must provide framework payload caching (currently Redis)."
+    );
+  if (attachedCaches.has(options.cache))
+    throw new TypeError("The cache adapter already has a storage owner.");
+  const timeoutMs = options.timeoutMs ?? 25;
+  validateFrameworkCacheOptions(provider.ttlMs, timeoutMs);
+  bind(provider.cache, provider.ttlMs, timeoutMs);
+  attachedCaches.add(options.cache);
+  return options.storage;
+}
+
+// src/framework/maintenance.ts
+function resolvePruneOptions(options = {}) {
+  const now = options.now?.getTime() ?? Date.now();
+  if (!Number.isSafeInteger(now) || now < 0 || now > Date.now())
+    throw new TypeError(
+      "prune now must be a valid date no later than the current time."
+    );
+  const batchSize = options.batchSize ?? 500;
+  if (!Number.isSafeInteger(batchSize) || batchSize < 1 || batchSize > 1e3)
+    throw new TypeError(
+      "batchSize must be a positive integer no greater than 1000."
+    );
+  return { now, batchSize };
+}
+function emptyPruneResult() {
+  return {
+    skipped: false,
+    hasMore: false,
+    deleted: {
+      pendingRequests: 0,
+      sessionCheckpoints: 0,
+      graphCheckpoints: 0,
+      sessions: 0,
+      runs: 0
+    }
+  };
+}
+
 // src/framework/pending-requests.ts
 function createInMemoryPendingRequestStore() {
   const store = /* @__PURE__ */ new Map();
-  const prune = () => {
-    const t = Date.now();
+  const pruneExpired = (t, batchSize) => {
+    let deleted = 0;
     for (const [k, v] of store.entries()) {
-      if (t - v.createdAt > v.ttlMs) store.delete(k);
+      if (deleted === batchSize) break;
+      if (t - v.createdAt > v.ttlMs) {
+        store.delete(k);
+        deleted++;
+      }
     }
+    return deleted;
   };
+  const prune = () => pruneExpired(Date.now(), Number.POSITIVE_INFINITY);
   return {
+    pruneExpired,
     async list() {
       prune();
       return JSON.parse(
@@ -228,6 +313,1008 @@ function createInMemoryPendingRequestStore() {
   };
 }
 
+// src/framework/postgres/adapter.ts
+var import_node_crypto4 = require("crypto");
+var import_errors5 = require("@kortyx/core/errors");
+
+// src/framework/postgres/checkpointer.ts
+var import_errors3 = require("@kortyx/core/errors");
+var import_langgraph_checkpoint2 = require("@langchain/langgraph-checkpoint");
+
+// src/framework/postgres/store.ts
+var import_node_crypto2 = require("crypto");
+var import_errors2 = require("@kortyx/core/errors");
+var import_postgres = __toESM(require("postgres"));
+
+// src/framework/postgres/migrations/index.ts
+var import_node_crypto = require("crypto");
+var import_errors = require("@kortyx/core/errors");
+
+// src/framework/postgres/migrations/0001-initial-runtime.ts
+var initialRuntimeMigration = Object.freeze({
+  version: 1,
+  description: "Initial runtime persistence tables",
+  sql: `
+CREATE TABLE IF NOT EXISTS kortyx_runtime_sessions (
+  scope text NOT NULL, id text NOT NULL, head_id text,
+  last_activity bigint NOT NULL, next_turn bigint NOT NULL DEFAULT 0,
+  PRIMARY KEY (scope, id)
+);
+CREATE INDEX IF NOT EXISTS kortyx_runtime_sessions_activity
+  ON kortyx_runtime_sessions (scope, last_activity);
+CREATE TABLE IF NOT EXISTS kortyx_runtime_runs (
+  scope text NOT NULL, id text NOT NULL, session_id text,
+  last_activity bigint NOT NULL, revision bigint NOT NULL DEFAULT 0,
+  lease_token text, lease_until bigint NOT NULL DEFAULT 0,
+  PRIMARY KEY (scope, id)
+);
+CREATE INDEX IF NOT EXISTS kortyx_runtime_runs_activity
+  ON kortyx_runtime_runs (scope, last_activity);
+CREATE INDEX IF NOT EXISTS kortyx_runtime_runs_session
+  ON kortyx_runtime_runs (scope, session_id);
+CREATE TABLE IF NOT EXISTS kortyx_runtime_graph_checkpoints (
+  scope text NOT NULL, run_id text NOT NULL, ns text NOT NULL, id text NOT NULL,
+  position bigserial NOT NULL, record jsonb NOT NULL,
+  PRIMARY KEY (scope, run_id, ns, id),
+  FOREIGN KEY (scope, run_id) REFERENCES kortyx_runtime_runs (scope, id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS kortyx_runtime_graph_latest
+  ON kortyx_runtime_graph_checkpoints (scope, run_id, ns, position DESC);
+CREATE TABLE IF NOT EXISTS kortyx_runtime_graph_writes (
+  scope text NOT NULL, run_id text NOT NULL, ns text NOT NULL, checkpoint_id text NOT NULL,
+  task_id text NOT NULL, idx integer NOT NULL, channel text NOT NULL, value jsonb NOT NULL,
+  PRIMARY KEY (scope, run_id, ns, checkpoint_id, task_id, idx),
+  FOREIGN KEY (scope, run_id, ns, checkpoint_id)
+    REFERENCES kortyx_runtime_graph_checkpoints (scope, run_id, ns, id) ON DELETE CASCADE
+);
+CREATE TABLE IF NOT EXISTS kortyx_runtime_session_checkpoints (
+  scope text NOT NULL, id text NOT NULL, session_id text NOT NULL, run_id text NOT NULL,
+  created_at bigint NOT NULL, turn_index bigint NOT NULL, active boolean NOT NULL DEFAULT true,
+  record jsonb NOT NULL,
+  PRIMARY KEY (scope, id),
+  FOREIGN KEY (scope, session_id) REFERENCES kortyx_runtime_sessions (scope, id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS kortyx_runtime_session_history
+  ON kortyx_runtime_session_checkpoints (scope, session_id, turn_index);
+CREATE INDEX IF NOT EXISTS kortyx_runtime_session_runs
+  ON kortyx_runtime_session_checkpoints (scope, run_id);
+CREATE INDEX IF NOT EXISTS kortyx_runtime_checkpoint_age
+  ON kortyx_runtime_session_checkpoints (scope, created_at);
+CREATE TABLE IF NOT EXISTS kortyx_runtime_pending_requests (
+  scope text NOT NULL, token text NOT NULL, run_id text NOT NULL, session_id text,
+  expires_at bigint NOT NULL, record jsonb NOT NULL,
+  PRIMARY KEY (scope, token)
+);
+CREATE INDEX IF NOT EXISTS kortyx_runtime_pending_expiry
+  ON kortyx_runtime_pending_requests (scope, expires_at);
+CREATE INDEX IF NOT EXISTS kortyx_runtime_pending_runs
+  ON kortyx_runtime_pending_requests (scope, run_id);
+CREATE INDEX IF NOT EXISTS kortyx_runtime_pending_sessions
+  ON kortyx_runtime_pending_requests (scope, session_id);
+`
+});
+
+// src/framework/postgres/migrations/index.ts
+var runtimeMigrations = Object.freeze([
+  initialRuntimeMigration
+]);
+async function runRuntimeMigrations(database, migrations = runtimeMigrations) {
+  if (!migrations.length)
+    throw new TypeError("Runtime migrations must include version 1.");
+  for (const [index, migration] of migrations.entries()) {
+    if (migration.version !== index + 1 || !migration.sql.trim())
+      throw new TypeError(
+        "Runtime migrations must contain nonempty SQL with consecutive versions starting at 1."
+      );
+  }
+  const checksums = migrations.map(
+    (migration) => (0, import_node_crypto.createHash)("sha256").update(migration.sql).digest("hex")
+  );
+  for (const migration of migrations) {
+    try {
+      await database.begin("isolation level read committed", async (sql) => {
+        await sql`SELECT set_config('lock_timeout', CASE WHEN current_setting('lock_timeout')::interval = interval '0' OR current_setting('lock_timeout')::interval > interval '5 seconds' THEN '5s' ELSE current_setting('lock_timeout') END, true)`;
+        await sql`SELECT pg_advisory_xact_lock(hashtextextended('kortyx:runtime:schema', 0))`;
+        await sql`CREATE TABLE IF NOT EXISTS kortyx_runtime_migrations (version integer PRIMARY KEY, checksum text)`;
+        const checksumColumn = await sql`SELECT 1 FROM pg_attribute WHERE attrelid = 'kortyx_runtime_migrations'::regclass AND attname = 'checksum' AND NOT attisdropped`;
+        const legacyLedger = !checksumColumn.length;
+        if (legacyLedger)
+          await sql`ALTER TABLE kortyx_runtime_migrations ADD COLUMN checksum text`;
+        const applied = await sql`SELECT version, checksum FROM kortyx_runtime_migrations ORDER BY version`;
+        if (applied.some((row) => row.version > migrations.length))
+          throw new import_errors.PersistenceError(
+            "The runtime schema is newer than this SDK supports."
+          );
+        if (applied.some((row, index) => row.version !== index + 1) || applied.length < migration.version - 1)
+          throw new import_errors.PersistenceError(
+            "The runtime migration history is not a consecutive sequence starting at version 1."
+          );
+        for (const row of applied) {
+          const expected = checksums[row.version - 1];
+          if (legacyLedger && applied.length === 1 && row.version === 1) {
+            await sql`UPDATE kortyx_runtime_migrations SET checksum = ${expected} WHERE version = 1`;
+          } else if (row.checksum !== expected) {
+            throw new import_errors.PersistenceError(
+              `Runtime migration ${row.version} checksum does not match this SDK. Restore the original migration; add a new version for changes.`
+            );
+          }
+        }
+        if (migration.version <= applied.length) return;
+        await sql.unsafe(migration.sql);
+        await sql`INSERT INTO kortyx_runtime_migrations (version, checksum) VALUES (${migration.version}, ${checksums[migration.version - 1]})`;
+      });
+    } catch (cause) {
+      if (cause instanceof import_errors.PersistenceError) throw cause;
+      throw new import_errors.PersistenceError(
+        `Runtime migration ${migration.version} (${migration.description}) failed.`,
+        cause
+      );
+    }
+  }
+}
+
+// src/framework/postgres/store.ts
+var positiveInteger = (name, value) => {
+  if (!Number.isSafeInteger(value) || value <= 0)
+    throw new TypeError(`${name} must be a positive safe integer.`);
+  return value;
+};
+var clone = (value) => JSON.parse(JSON.stringify(value));
+var PostgresRuntimeStore = class {
+  constructor(connectionString, namespace, retention, cache, cacheTtlMs = 15 * 60 * 1e3, cacheTimeoutMs = 25) {
+    this.cache = cache;
+    this.cacheTtlMs = cacheTtlMs;
+    this.cacheTimeoutMs = cacheTimeoutMs;
+    const url = new URL(connectionString);
+    if (!["postgres:", "postgresql:"].includes(url.protocol))
+      throw new TypeError("connectionString must be a PostgreSQL URL.");
+    if (!namespace) throw new TypeError("namespace must not be empty.");
+    this.scope = namespace;
+    this.historyMs = positiveInteger(
+      "checkpointHistoryDays",
+      retention.checkpointHistoryDays ?? 30
+    ) * 864e5;
+    this.sessionMs = positiveInteger(
+      "inactiveSessionDays",
+      retention.inactiveSessionDays ?? 30
+    ) * 864e5;
+    positiveInteger("checkpoint history duration", this.historyMs);
+    positiveInteger("session retention duration", this.sessionMs);
+    validateFrameworkCacheOptions(cacheTtlMs, cacheTimeoutMs);
+    this.sql = (0, import_postgres.default)(connectionString, {
+      max: 10,
+      connect_timeout: 5,
+      onnotice: () => {
+      }
+    });
+    this.cachePrefix = (0, import_node_crypto2.createHash)("sha256").update(`${connectionString}\0${namespace}`).digest("hex");
+  }
+  cache;
+  cacheTtlMs;
+  cacheTimeoutMs;
+  sql;
+  scope;
+  historyMs;
+  sessionMs;
+  cachePrefix;
+  cacheRetryAfter = 0;
+  cacheClosed = false;
+  cachePopulations = /* @__PURE__ */ new Map();
+  get cacheEnabled() {
+    return Boolean(this.cache);
+  }
+  attachCache(cache, ttlMs, timeoutMs) {
+    if (this.cacheClosed)
+      throw new TypeError("Cannot configure a closed storage adapter.");
+    if (this.cache)
+      throw new TypeError("Storage already has a framework cache.");
+    validateFrameworkCacheOptions(ttlMs, timeoutMs);
+    this.cache = cache;
+    this.cacheTtlMs = ttlMs;
+    this.cacheTimeoutMs = timeoutMs;
+  }
+  async setup() {
+    await this.query(runRuntimeMigrations(this.sql));
+  }
+  async query(query) {
+    try {
+      return await query;
+    } catch (cause) {
+      if (cause instanceof import_errors2.KortyxError) throw cause;
+      throw new import_errors2.PersistenceError("PostgreSQL runtime operation failed.", cause);
+    }
+  }
+  async transaction(operation) {
+    try {
+      return await this.sql.begin(async (sql) => {
+        await sql`SELECT pg_advisory_xact_lock_shared(hashtextextended(${`kortyx:runtime:${this.scope}`}, 0))`;
+        return operation(sql);
+      });
+    } catch (cause) {
+      if (cause instanceof import_errors2.KortyxError) throw cause;
+      throw new import_errors2.PersistenceError("PostgreSQL runtime operation failed.", cause);
+    }
+  }
+  liveSession(sql, now) {
+    return sql`(s.last_activity > ${now - this.sessionMs}
+      OR EXISTS (SELECT 1 FROM kortyx_runtime_pending_requests p
+        WHERE p.scope = s.scope AND p.session_id = s.id AND p.expires_at > ${now})
+      OR EXISTS (SELECT 1 FROM kortyx_runtime_runs r
+        WHERE r.scope = s.scope AND r.session_id = s.id AND r.lease_until > ${now}))`;
+  }
+  liveCheckpoint(sql, now) {
+    return sql`(c.created_at > ${now - this.historyMs} OR s.head_id = c.id
+      OR EXISTS (SELECT 1 FROM kortyx_runtime_pending_requests p
+        WHERE p.scope = c.scope AND p.run_id = c.run_id AND p.expires_at > ${now})
+      OR EXISTS (SELECT 1 FROM kortyx_runtime_runs r
+        WHERE r.scope = c.scope AND r.id = c.run_id AND r.lease_until > ${now}))`;
+  }
+  liveRun(sql, now) {
+    return sql`(r.last_activity > ${now - this.historyMs} OR r.lease_until > ${now}
+      OR EXISTS (SELECT 1 FROM kortyx_runtime_pending_requests p
+        WHERE p.scope = r.scope AND p.run_id = r.id AND p.expires_at > ${now})
+      OR EXISTS (SELECT 1 FROM kortyx_runtime_session_checkpoints c
+        JOIN kortyx_runtime_sessions s ON s.scope = c.scope AND s.id = c.session_id
+        WHERE c.scope = r.scope AND c.run_id = r.id
+          AND ${this.liveSession(sql, now)} AND ${this.liveCheckpoint(sql, now)}))`;
+  }
+  async touchRun(sql, runId) {
+    await sql`INSERT INTO kortyx_runtime_runs (scope, id, last_activity)
+      VALUES (${this.scope}, ${runId}, ${Date.now()})
+      ON CONFLICT (scope, id) DO UPDATE SET last_activity = EXCLUDED.last_activity,
+        revision = kortyx_runtime_runs.revision + 1`;
+  }
+  async touchSession(sql, sessionId) {
+    const updated = await sql`INSERT INTO kortyx_runtime_sessions AS s (scope, id, last_activity)
+      VALUES (${this.scope}, ${sessionId}, ${Date.now()})
+      ON CONFLICT (scope, id) DO UPDATE SET last_activity = EXCLUDED.last_activity
+      WHERE ${this.liveSession(sql, Date.now())} RETURNING id`;
+    if (!updated.length)
+      throw new import_errors2.KortyxError(
+        "SESSION_EXPIRED",
+        "The runtime session has expired. Start a new session.",
+        {
+          category: "request",
+          retryable: false,
+          safeMessage: "This session has expired. Start a new session."
+        }
+      );
+  }
+  async payload(key, load) {
+    const cacheKey = `${this.cachePrefix}:${(0, import_node_crypto2.createHash)("sha256").update(JSON.stringify(key)).digest("hex")}`;
+    const cache = this.cache;
+    if (cache && !this.cacheClosed && Date.now() >= this.cacheRetryAfter) {
+      try {
+        const raw = await this.cacheCall(() => cache.get(cacheKey));
+        if (raw) return JSON.parse(raw);
+      } catch {
+        this.cacheRetryAfter = Date.now() + 5e3;
+      }
+    }
+    const value = await load();
+    if (cache && !this.cacheClosed && Date.now() >= this.cacheRetryAfter && value !== void 0 && value !== null && !this.cachePopulations.has(cacheKey) && this.cachePopulations.size < 10) {
+      const population = this.cacheCall(
+        () => cache.set(cacheKey, JSON.stringify(value), this.cacheTtlMs)
+      ).then(() => {
+      }).catch(() => {
+        this.cacheRetryAfter = Date.now() + 5e3;
+      }).finally(() => {
+        this.cachePopulations.delete(cacheKey);
+      });
+      this.cachePopulations.set(cacheKey, population);
+    }
+    return value;
+  }
+  async cacheCall(operation) {
+    let timer;
+    try {
+      return await Promise.race([
+        operation(),
+        new Promise((_resolve, reject) => {
+          timer = setTimeout(() => {
+            void this.cache?.close?.().catch(() => {
+            });
+            reject(new Error("Runtime cache operation timed out."));
+          }, this.cacheTimeoutMs);
+          timer.unref();
+        })
+      ]);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  async close() {
+    this.cacheClosed = true;
+    try {
+      await Promise.all(this.cachePopulations.values());
+      await this.cache?.close?.();
+    } finally {
+      await this.sql.end({ timeout: 5 });
+    }
+  }
+};
+
+// src/framework/postgres/checkpointer.ts
+var configFor = (runId, ns, id) => ({
+  configurable: { thread_id: runId, checkpoint_ns: ns, checkpoint_id: id }
+});
+var PostgresCheckpointSaver = class extends import_langgraph_checkpoint2.BaseCheckpointSaver {
+  constructor(store) {
+    super({
+      dumpsTyped: async (data) => [
+        "json",
+        Buffer.from(JSON.stringify(data))
+      ],
+      loadsTyped: async (_type, data) => JSON.parse(
+        typeof data === "string" ? data : Buffer.from(data).toString("utf8")
+      )
+    });
+    this.store = store;
+  }
+  store;
+  async getTuple(config) {
+    const runId = config.configurable?.thread_id;
+    if (!runId) return void 0;
+    const ns = config.configurable?.checkpoint_ns ?? "";
+    const id = (0, import_langgraph_checkpoint2.getCheckpointId)(config);
+    const { sql, scope } = this.store;
+    const rows = await this.store.query(sql`SELECT g.id, g.position, r.revision
+      FROM kortyx_runtime_graph_checkpoints g
+      JOIN kortyx_runtime_runs r ON r.scope = g.scope AND r.id = g.run_id
+      WHERE g.scope = ${scope} AND g.run_id = ${runId} AND g.ns = ${ns}
+        AND g.record ? 'checkpoint'
+        ${id ? sql`AND g.id = ${id}` : sql``}
+        AND ${this.store.liveRun(sql, Date.now())}
+      ORDER BY g.position DESC LIMIT 1`);
+    const row = rows[0];
+    if (!row) return void 0;
+    return this.store.payload(
+      ["graph", runId, ns, row.id, row.position, row.revision],
+      async () => {
+        const [records, writes] = await Promise.all([
+          this.store.query(sql`SELECT record FROM kortyx_runtime_graph_checkpoints
+        WHERE scope = ${scope} AND run_id = ${runId} AND ns = ${ns} AND id = ${row.id}`),
+          this.store.query(sql`SELECT task_id, channel, value FROM kortyx_runtime_graph_writes
+        WHERE scope = ${scope} AND run_id = ${runId} AND ns = ${ns} AND checkpoint_id = ${row.id}
+        ORDER BY task_id, idx`)
+        ]);
+        if (!records[0]) return void 0;
+        const record2 = records[0].record;
+        return {
+          config: configFor(runId, ns, row.id),
+          checkpoint: record2.checkpoint,
+          metadata: record2.metadata,
+          ...record2.parentCheckpointId ? { parentConfig: configFor(runId, ns, record2.parentCheckpointId) } : {},
+          pendingWrites: writes.map(
+            (write) => [
+              write.task_id,
+              write.channel,
+              write.value.value
+            ]
+          )
+        };
+      }
+    );
+  }
+  async *list(config, options) {
+    const { sql, scope } = this.store;
+    const runId = config.configurable?.thread_id;
+    const ns = config.configurable?.checkpoint_ns;
+    const id = (0, import_langgraph_checkpoint2.getCheckpointId)(config);
+    const before = options?.before ? (0, import_langgraph_checkpoint2.getCheckpointId)(options.before) : void 0;
+    const rows = await this.store.query(sql`SELECT g.run_id, g.ns, g.id FROM kortyx_runtime_graph_checkpoints g
+      JOIN kortyx_runtime_runs r ON r.scope = g.scope AND r.id = g.run_id
+      WHERE g.scope = ${scope} AND ${this.store.liveRun(sql, Date.now())}
+        AND g.record ? 'checkpoint'
+        ${runId ? sql`AND g.run_id = ${runId}` : sql``}
+        ${ns !== void 0 ? sql`AND g.ns = ${ns}` : sql``}
+        ${id ? sql`AND g.id = ${id}` : sql``}
+        ${before ? sql`AND g.id < ${before}` : sql``}
+        ${options?.filter ? sql`AND g.record->'metadata' @> ${sql.json(clone(options.filter))}` : sql``}
+      ORDER BY g.id DESC ${options?.limit !== void 0 ? sql`LIMIT ${options.limit}` : sql``}`);
+    for (const row of rows) {
+      const tuple = await this.getTuple(configFor(row.run_id, row.ns, row.id));
+      if (tuple) yield tuple;
+    }
+  }
+  async put(config, checkpoint, metadata, _newVersions) {
+    const runId = config.configurable?.thread_id;
+    if (!runId)
+      throw new import_errors3.PersistenceError(
+        'Failed to put checkpoint: missing "thread_id".'
+      );
+    const ns = config.configurable?.checkpoint_ns ?? "";
+    const parentCheckpointId = config.configurable?.checkpoint_id;
+    const record2 = {
+      checkpoint: (0, import_langgraph_checkpoint2.copyCheckpoint)(checkpoint),
+      metadata,
+      ...parentCheckpointId ? { parentCheckpointId } : {}
+    };
+    await this.store.transaction(async (sql) => {
+      await this.store.touchRun(sql, runId);
+      await sql`INSERT INTO kortyx_runtime_graph_checkpoints (scope, run_id, ns, id, record)
+        VALUES (${this.store.scope}, ${runId}, ${ns}, ${checkpoint.id}, ${sql.json(clone(record2))})
+        ON CONFLICT (scope, run_id, ns, id) DO UPDATE SET record = EXCLUDED.record,
+          position = EXCLUDED.position`;
+    });
+    return configFor(runId, ns, checkpoint.id);
+  }
+  async putWrites(config, writes, taskId) {
+    const runId = config.configurable?.thread_id;
+    const id = (0, import_langgraph_checkpoint2.getCheckpointId)(config);
+    if (!runId || !id)
+      throw new import_errors3.PersistenceError(
+        'Failed to put writes: missing "thread_id" or "checkpoint_id".'
+      );
+    const ns = config.configurable?.checkpoint_ns ?? "";
+    await this.store.transaction(async (sql) => {
+      await this.store.touchRun(sql, runId);
+      await sql`INSERT INTO kortyx_runtime_graph_checkpoints (scope, run_id, ns, id, record)
+        VALUES (${this.store.scope}, ${runId}, ${ns}, ${id}, ${sql.json({})})
+        ON CONFLICT (scope, run_id, ns, id) DO NOTHING`;
+      const rows = /* @__PURE__ */ new Map();
+      for (const [idx, [channel, value]] of writes.entries()) {
+        const mapped = import_langgraph_checkpoint2.WRITES_IDX_MAP[channel] ?? idx;
+        rows.set(mapped, {
+          scope: this.store.scope,
+          run_id: runId,
+          ns,
+          checkpoint_id: id,
+          task_id: taskId,
+          idx: mapped,
+          channel,
+          value: sql.json({
+            value: clone(value ?? null)
+          })
+        });
+      }
+      if (rows.size)
+        await sql`INSERT INTO kortyx_runtime_graph_writes
+        ${sql([...rows.values()], "scope", "run_id", "ns", "checkpoint_id", "task_id", "idx", "channel", "value")}
+        ON CONFLICT (scope, run_id, ns, checkpoint_id, task_id, idx)
+        DO UPDATE SET channel = EXCLUDED.channel, value = EXCLUDED.value WHERE EXCLUDED.idx < 0`;
+    });
+  }
+  async deleteThread(runId) {
+    await this.store.transaction(async (sql) => {
+      await sql`DELETE FROM kortyx_runtime_runs WHERE scope = ${this.store.scope} AND id = ${runId}`;
+    });
+  }
+  async deleteCheckpointWrites(runId, ns, id) {
+    await this.store.transaction(async (sql) => {
+      await this.store.touchRun(sql, runId);
+      await sql`DELETE FROM kortyx_runtime_graph_writes
+        WHERE scope = ${this.store.scope} AND run_id = ${runId} AND ns = ${ns} AND checkpoint_id = ${id}`;
+    });
+  }
+  async getLatestCheckpointId(runId, ns = "") {
+    return (await this.getTuple({
+      configurable: { thread_id: runId, checkpoint_ns: ns }
+    }))?.checkpoint.id;
+  }
+};
+
+// src/framework/postgres/maintenance.ts
+function createRuntimeMaintenance(store) {
+  return {
+    setup: () => store.setup(),
+    async prune(options = {}) {
+      const { now, batchSize: batch } = resolvePruneOptions(options);
+      return await store.query(
+        store.sql.begin(async (sql) => {
+          const deleted = {
+            pendingRequests: 0,
+            sessionCheckpoints: 0,
+            graphCheckpoints: 0,
+            sessions: 0,
+            runs: 0
+          };
+          const locks = await sql`SELECT pg_try_advisory_xact_lock(hashtextextended(${`kortyx:runtime:${store.scope}`}, 0)) AS acquired`;
+          if (!locks[0]?.acquired)
+            return { skipped: true, hasMore: false, deleted };
+          const pending = await sql`DELETE FROM kortyx_runtime_pending_requests WHERE (scope, token) IN (
+          SELECT scope, token FROM kortyx_runtime_pending_requests
+          WHERE scope = ${store.scope} AND expires_at <= ${now} ORDER BY expires_at LIMIT ${batch}
+        ) RETURNING token`;
+          deleted.pendingRequests = pending.length;
+          const checkpoints = await sql`DELETE FROM kortyx_runtime_session_checkpoints WHERE (scope, id) IN (
+          SELECT c.scope, c.id FROM kortyx_runtime_session_checkpoints c
+          JOIN kortyx_runtime_sessions s ON s.scope = c.scope AND s.id = c.session_id
+          WHERE c.scope = ${store.scope}
+            AND (NOT ${store.liveSession(sql, now)} OR NOT ${store.liveCheckpoint(sql, now)})
+          ORDER BY c.created_at LIMIT ${batch}
+        ) RETURNING id`;
+          deleted.sessionCheckpoints = checkpoints.length;
+          const graph = await sql`DELETE FROM kortyx_runtime_graph_checkpoints WHERE (scope, run_id, ns, id) IN (
+          SELECT g.scope, g.run_id, g.ns, g.id FROM kortyx_runtime_graph_checkpoints g
+          JOIN kortyx_runtime_runs r ON r.scope = g.scope AND r.id = g.run_id
+          WHERE g.scope = ${store.scope} AND NOT ${store.liveRun(sql, now)}
+            AND NOT EXISTS (SELECT 1 FROM kortyx_runtime_session_checkpoints c WHERE c.scope = r.scope AND c.run_id = r.id)
+          ORDER BY g.position LIMIT ${batch}
+        ) RETURNING id`;
+          deleted.graphCheckpoints = graph.length;
+          const sessions = await sql`DELETE FROM kortyx_runtime_sessions WHERE (scope, id) IN (
+          SELECT s.scope, s.id FROM kortyx_runtime_sessions s
+          WHERE s.scope = ${store.scope} AND NOT ${store.liveSession(sql, now)}
+            AND NOT EXISTS (SELECT 1 FROM kortyx_runtime_session_checkpoints c WHERE c.scope = s.scope AND c.session_id = s.id)
+            AND NOT EXISTS (SELECT 1 FROM kortyx_runtime_pending_requests p WHERE p.scope = s.scope AND p.session_id = s.id)
+          ORDER BY s.last_activity LIMIT ${batch}
+        ) RETURNING id`;
+          deleted.sessions = sessions.length;
+          const runs = await sql`DELETE FROM kortyx_runtime_runs WHERE (scope, id) IN (
+          SELECT r.scope, r.id FROM kortyx_runtime_runs r
+          WHERE r.scope = ${store.scope} AND NOT ${store.liveRun(sql, now)}
+            AND NOT EXISTS (SELECT 1 FROM kortyx_runtime_graph_checkpoints g WHERE g.scope = r.scope AND g.run_id = r.id)
+            AND NOT EXISTS (SELECT 1 FROM kortyx_runtime_session_checkpoints c WHERE c.scope = r.scope AND c.run_id = r.id)
+            AND NOT EXISTS (SELECT 1 FROM kortyx_runtime_pending_requests p WHERE p.scope = r.scope AND p.run_id = r.id)
+          ORDER BY r.last_activity LIMIT ${batch}
+        ) RETURNING id`;
+          deleted.runs = runs.length;
+          return {
+            skipped: false,
+            hasMore: Object.values(deleted).some((count) => count === batch),
+            deleted
+          };
+        })
+      );
+    }
+  };
+}
+
+// src/framework/postgres/pending-request-store.ts
+async function savePendingRequest(store, sql, record2) {
+  positiveInteger("interrupt ttlMs", record2.ttlMs);
+  const expiresAt = record2.createdAt + record2.ttlMs;
+  if (!Number.isSafeInteger(record2.createdAt) || record2.createdAt < 0 || !Number.isSafeInteger(expiresAt))
+    throw new TypeError("Interrupt timestamps must be safe integers.");
+  if (expiresAt <= Date.now()) {
+    await store.query(
+      sql`DELETE FROM kortyx_runtime_pending_requests WHERE scope = ${store.scope} AND token = ${record2.token}`
+    );
+    return;
+  }
+  if (record2.sessionId) await store.touchSession(sql, record2.sessionId);
+  await store.touchRun(sql, record2.runId);
+  await store.query(sql`INSERT INTO kortyx_runtime_pending_requests (scope, token, run_id, session_id, expires_at, record)
+    VALUES (${store.scope}, ${record2.token}, ${record2.runId}, ${record2.sessionId ?? null}, ${expiresAt},
+      ${sql.json(clone(record2))})
+    ON CONFLICT (scope, token) DO UPDATE SET run_id = EXCLUDED.run_id, session_id = EXCLUDED.session_id,
+      expires_at = EXCLUDED.expires_at, record = EXCLUDED.record`);
+}
+function createPostgresPendingRequestStore(store) {
+  return {
+    async list() {
+      const rows = await store.query(store.sql`SELECT record FROM kortyx_runtime_pending_requests
+        WHERE scope = ${store.scope} AND expires_at > ${Date.now()} ORDER BY token`);
+      return rows.map((row) => row.record);
+    },
+    async get(token) {
+      const rows = await store.query(store.sql`SELECT record FROM kortyx_runtime_pending_requests
+        WHERE scope = ${store.scope} AND token = ${token} AND expires_at > ${Date.now()}`);
+      return rows[0] ? rows[0].record : null;
+    },
+    async take(token) {
+      return store.transaction(async (sql) => {
+        const rows = await sql`DELETE FROM kortyx_runtime_pending_requests
+          WHERE scope = ${store.scope} AND token = ${token} RETURNING record, expires_at`;
+        return rows[0] && Number(rows[0].expires_at) > Date.now() ? rows[0].record : null;
+      });
+    },
+    async save(record2) {
+      await store.transaction((sql) => savePendingRequest(store, sql, record2));
+    },
+    async delete(token) {
+      await store.transaction(async (sql) => {
+        await sql`DELETE FROM kortyx_runtime_pending_requests WHERE scope = ${store.scope} AND token = ${token}`;
+      });
+    },
+    async update(token, patch) {
+      await store.transaction(async (sql) => {
+        const found = await sql`SELECT run_id, session_id FROM kortyx_runtime_pending_requests
+          WHERE scope = ${store.scope} AND token = ${token}`;
+        if (!found[0]) return;
+        if (found[0].session_id)
+          await store.touchSession(sql, found[0].session_id);
+        await store.touchRun(sql, found[0].run_id);
+        const rows = await sql`SELECT record FROM kortyx_runtime_pending_requests
+          WHERE scope = ${store.scope} AND token = ${token} AND expires_at > ${Date.now()} FOR UPDATE`;
+        if (!rows[0]) return;
+        const previous = rows[0].record;
+        await savePendingRequest(store, sql, {
+          ...previous,
+          ...patch,
+          token: previous.token,
+          runId: previous.runId,
+          sessionId: previous.sessionId,
+          createdAt: previous.createdAt,
+          ttlMs: previous.ttlMs
+        });
+      });
+    }
+  };
+}
+
+// src/framework/postgres/session-checkpoint-store.ts
+var import_node_crypto3 = require("crypto");
+var import_errors4 = require("@kortyx/core/errors");
+
+// src/framework/graph-snapshot.ts
+async function captureGraphSnapshot(saver, threadId, checkpointId) {
+  const tuple = await saver.getTuple({
+    configurable: {
+      thread_id: threadId,
+      checkpoint_ns: "",
+      ...checkpointId ? { checkpoint_id: checkpointId } : {}
+    }
+  });
+  return tuple ? JSON.parse(JSON.stringify(tuple)) : void 0;
+}
+async function restoreGraphSnapshot(saver, snapshot, threadId) {
+  const copy = JSON.parse(JSON.stringify(snapshot));
+  const config = await saver.put(
+    { configurable: { thread_id: threadId, checkpoint_ns: "" } },
+    copy.checkpoint,
+    copy.metadata,
+    copy.checkpoint.channel_versions
+  );
+  const reset = saver;
+  if (reset.deleteCheckpointWrites)
+    await reset.deleteCheckpointWrites(threadId, "", copy.checkpoint.id);
+  const writes = /* @__PURE__ */ new Map();
+  for (const [task, channel, value] of copy.pendingWrites ?? []) {
+    const group = writes.get(task) ?? [];
+    group.push([channel, value]);
+    writes.set(task, group);
+  }
+  for (const [task, group] of writes)
+    await saver.putWrites(config, group, task);
+}
+
+// src/framework/postgres/session-checkpoint-store.ts
+var unique = (values) => [
+  ...new Set(values.filter((value) => Boolean(value)))
+];
+var notFound = (id) => new import_errors4.KortyxError(
+  "NOT_FOUND",
+  `Checkpoint "${id}" was not found or has expired.`,
+  {
+    category: "request",
+    retryable: false,
+    safeMessage: "The requested checkpoint was not found or has expired."
+  }
+);
+var assertInterruptsLive = (requests) => {
+  if (requests.some((request) => request.createdAt + request.ttlMs <= Date.now()))
+    throw new import_errors4.KortyxError(
+      "INTERRUPT_EXPIRED",
+      "The checkpoint contains an expired interrupt.",
+      {
+        category: "request",
+        retryable: false,
+        safeMessage: "This checkpoint's approval or input request has expired."
+      }
+    );
+};
+function createPostgresSessionCheckpointStore(store, saver) {
+  const visible = (sql, now) => sql`c.scope = ${store.scope}
+    AND ${store.liveSession(sql, now)} AND ${store.liveCheckpoint(sql, now)}`;
+  const read = async (row) => {
+    if (!row) return null;
+    const record2 = store.cacheEnabled ? await store.payload(["session", row.id], async () => {
+      const records = await store.query(store.sql`SELECT record FROM kortyx_runtime_session_checkpoints
+        WHERE scope = ${store.scope} AND id = ${row.id}`);
+      return records[0] ? records[0].record : null;
+    }) : row.record;
+    return record2 ? {
+      ...record2,
+      branchStatus: row.active ? "active" : "abandoned"
+    } : null;
+  };
+  const get = async (id) => {
+    const { sql } = store;
+    const rows = await store.query(sql`SELECT c.id, c.active ${store.cacheEnabled ? sql`` : sql`, c.record`} FROM kortyx_runtime_session_checkpoints c
+      JOIN kortyx_runtime_sessions s ON s.scope = c.scope AND s.id = c.session_id
+      WHERE c.id = ${id} AND ${visible(sql, Date.now())}`);
+    return read(
+      rows[0]
+    );
+  };
+  const sealRequests = async (requests) => {
+    return Promise.all(
+      requests.map(async (request) => {
+        if (request.graphSnapshot) return clone(request);
+        const graphSnapshot = await captureGraphSnapshot(
+          saver,
+          request.runId,
+          request.graphCheckpointId
+        );
+        if (!graphSnapshot)
+          throw new import_errors4.KortyxError(
+            "CHECKPOINT_INCOMPLETE",
+            "A paused checkpoint needs a complete execution snapshot.",
+            {
+              category: "persistence",
+              retryable: false,
+              safeMessage: "The paused execution could not be saved completely."
+            }
+          );
+        return { ...clone(request), graphSnapshot };
+      })
+    );
+  };
+  const insert = async (sql, record2) => {
+    await store.query(sql`INSERT INTO kortyx_runtime_session_checkpoints (scope, id, session_id, run_id, created_at, turn_index, record)
+      VALUES (${store.scope}, ${record2.id}, ${record2.sessionId}, ${record2.runId}, ${record2.createdAt}, ${record2.turnIndex},
+        ${sql.json(clone(record2))})`);
+    await store.query(sql`UPDATE kortyx_runtime_sessions SET head_id = ${record2.id}, next_turn = ${record2.turnIndex + 1}
+      WHERE scope = ${store.scope} AND id = ${record2.sessionId}`);
+  };
+  return {
+    managesPendingRequests: true,
+    get,
+    async list(sessionId) {
+      const { sql } = store;
+      const rows = await store.query(sql`SELECT c.record, c.active FROM kortyx_runtime_session_checkpoints c
+        JOIN kortyx_runtime_sessions s ON s.scope = c.scope AND s.id = c.session_id
+        WHERE c.session_id = ${sessionId} AND ${visible(sql, Date.now())} ORDER BY c.turn_index`);
+      return rows.map((row) => {
+        const {
+          state: _state,
+          effects: _effects,
+          activePendingRequests: _pending,
+          runId: _runId,
+          graphCheckpointId: _graphId,
+          ...summary
+        } = row.record;
+        return {
+          ...summary,
+          branchStatus: row.active ? "active" : "abandoned"
+        };
+      });
+    },
+    async getHead(sessionId) {
+      const { sql } = store;
+      const rows = await store.query(sql`SELECT c.id, c.active ${store.cacheEnabled ? sql`` : sql`, c.record`}
+        FROM kortyx_runtime_sessions s JOIN kortyx_runtime_session_checkpoints c
+          ON c.scope = s.scope AND c.id = s.head_id
+        WHERE s.id = ${sessionId} AND ${visible(sql, Date.now())}`);
+      return read(
+        rows[0]
+      );
+    },
+    async append(args) {
+      const requests = await sealRequests(args.pendingRequests ?? []);
+      return store.transaction(async (sql) => {
+        await store.touchSession(sql, args.sessionId);
+        const sessions = await sql`SELECT head_id, next_turn FROM kortyx_runtime_sessions
+          WHERE scope = ${store.scope} AND id = ${args.sessionId} FOR UPDATE`;
+        const session = sessions[0];
+        if (!session)
+          throw new import_errors4.PersistenceError(
+            "The session disappeared during checkpoint append."
+          );
+        const record2 = {
+          id: `cp-${(0, import_node_crypto3.randomUUID)()}`,
+          sessionId: args.sessionId,
+          runId: args.runId,
+          turnIndex: Number(session.next_turn),
+          createdAt: Date.now(),
+          workflow: args.workflow,
+          state: clone(args.state),
+          nodes: unique(args.nodes ?? []),
+          effects: {
+            structuredStreamIds: unique(args.structuredStreamIds ?? []),
+            interruptTokens: unique(requests.map((request) => request.token))
+          },
+          activePendingRequests: requests,
+          ...session.head_id ? { parentCheckpointId: session.head_id } : {},
+          ...args.graphCheckpointId ? { graphCheckpointId: args.graphCheckpointId } : {},
+          ...args.label ? { label: args.label } : {},
+          ...args.workflowVersion ? { workflowVersion: args.workflowVersion } : {},
+          ...args.buildId ? { buildId: args.buildId } : {}
+        };
+        await insert(sql, record2);
+        return record2;
+      });
+    },
+    async rollbackTo(id, options) {
+      return store.transaction(async (sql) => {
+        const targets = await sql`SELECT c.record FROM kortyx_runtime_session_checkpoints c
+          JOIN kortyx_runtime_sessions s ON s.scope = c.scope AND s.id = c.session_id
+          WHERE c.id = ${id} AND ${visible(sql, Date.now())} FOR UPDATE OF s`;
+        if (!targets[0]) throw notFound(id);
+        const target = targets[0].record;
+        assertInterruptsLive(target.activePendingRequests);
+        const liveRuns = await sql`SELECT id FROM kortyx_runtime_runs
+          WHERE scope = ${store.scope} AND session_id = ${target.sessionId} AND lease_until > ${Date.now()}`;
+        if (liveRuns.length)
+          throw new import_errors4.KortyxError(
+            "SESSION_BUSY",
+            "Cannot roll back a session while execution is active.",
+            { category: "request", retryable: true }
+          );
+        const ancestry = await sql`WITH RECURSIVE ancestors(id) AS (
+          SELECT ${id}::text UNION
+          SELECT c.record->>'parentCheckpointId' FROM kortyx_runtime_session_checkpoints c
+            JOIN ancestors a ON a.id = c.id WHERE c.scope = ${store.scope} AND c.record ? 'parentCheckpointId'
+        ) SELECT id FROM ancestors`;
+        const ancestorIds = ancestry.map((row) => row.id);
+        const trailing = await sql`SELECT record FROM kortyx_runtime_session_checkpoints
+          WHERE scope = ${store.scope} AND session_id = ${target.sessionId} AND active AND id NOT IN ${sql(ancestorIds)}`;
+        const records = trailing.map(
+          (row) => row.record
+        );
+        const streams = unique(
+          records.flatMap((record2) => record2.effects.structuredStreamIds)
+        );
+        const tokens = unique(
+          records.flatMap((record2) => [
+            ...record2.effects.interruptTokens,
+            ...record2.activePendingRequests.map((request) => request.token)
+          ])
+        );
+        await sql`UPDATE kortyx_runtime_session_checkpoints SET active = (id IN ${sql(ancestorIds)})
+          WHERE scope = ${store.scope} AND session_id = ${target.sessionId}`;
+        await store.touchSession(sql, target.sessionId);
+        await sql`UPDATE kortyx_runtime_sessions SET head_id = ${id} WHERE scope = ${store.scope} AND id = ${target.sessionId}`;
+        if (tokens.length)
+          await sql`DELETE FROM kortyx_runtime_pending_requests WHERE scope = ${store.scope} AND token IN ${sql(tokens)}`;
+        const requests = clone(target.activePendingRequests);
+        options?.preparePendingRequests?.(requests);
+        for (const request of requests)
+          await savePendingRequest(store, sql, request);
+        return {
+          sessionId: target.sessionId,
+          head: id,
+          invalidatedStructuredStreamIds: streams,
+          invalidatedInterruptTokens: tokens,
+          activePendingRequests: requests
+        };
+      });
+    },
+    async fork(id, options) {
+      const source = await get(id);
+      if (!source) throw notFound(id);
+      assertInterruptsLive(source.activePendingRequests);
+      const sessionId = options?.newSessionId || `session-${(0, import_node_crypto3.randomUUID)()}`;
+      const runId = source.activePendingRequests.length ? `run-${(0, import_node_crypto3.randomUUID)()}` : source.runId;
+      const {
+        parentCheckpointId: _parent,
+        branchStatus: _branch,
+        ...sourceRecord
+      } = source;
+      const checkpoint = {
+        ...clone(sourceRecord),
+        id: `cp-${(0, import_node_crypto3.randomUUID)()}`,
+        sessionId,
+        runId,
+        createdAt: Date.now(),
+        parentSessionId: source.sessionId,
+        forkedFrom: source.id,
+        activePendingRequests: source.activePendingRequests.map((request) => ({
+          ...clone(request),
+          runId,
+          sessionId,
+          token: (0, import_node_crypto3.randomUUID)(),
+          requestId: `human-${(0, import_node_crypto3.randomUUID)()}`
+        }))
+      };
+      checkpoint.effects.interruptTokens = checkpoint.activePendingRequests.map(
+        (request) => request.token
+      );
+      options?.preparePendingRequests?.(checkpoint.activePendingRequests);
+      await store.transaction(async (sql) => {
+        const existing = await sql`SELECT id FROM kortyx_runtime_sessions WHERE scope = ${store.scope} AND id = ${sessionId}`;
+        if (existing.length)
+          throw new import_errors4.KortyxError(
+            "SESSION_EXISTS",
+            "The fork session already exists.",
+            { category: "request", retryable: false }
+          );
+        await sql`INSERT INTO kortyx_runtime_sessions (scope, id, last_activity) VALUES (${store.scope}, ${sessionId}, ${Date.now()})`;
+        await insert(sql, checkpoint);
+        for (const request of checkpoint.activePendingRequests)
+          await savePendingRequest(store, sql, request);
+      });
+      return {
+        sessionId,
+        parentSessionId: source.sessionId,
+        forkedFrom: source.id,
+        checkpoint
+      };
+    }
+  };
+}
+
+// src/framework/postgres/adapter.ts
+function createPostgresFrameworkAdapter(options) {
+  const ttlMs = positiveInteger("ttlMs", options.ttlMs ?? 15 * 60 * 1e3);
+  const store = new PostgresRuntimeStore(
+    options.connectionString,
+    options.namespace ?? "default",
+    options.retention ?? {}
+  );
+  const saver = new PostgresCheckpointSaver(store);
+  const adapter = {
+    kind: "postgres",
+    ttlMs,
+    checkpointer: saver,
+    pendingRequests: createPostgresPendingRequestStore(store),
+    sessionCheckpoints: createPostgresSessionCheckpointStore(store, saver),
+    maintenance: createRuntimeMaintenance(store),
+    // Completed runs remain available until maintenance applies retention.
+    cleanupRun: async (runId) => store.transaction((sql) => store.touchRun(sql, runId)),
+    acquireRunLease: async ({ runId, sessionId, onLost }) => {
+      const token = (0, import_node_crypto4.randomUUID)();
+      const renew = async () => {
+        await store.transaction(async (sql) => {
+          if (sessionId) await store.touchSession(sql, sessionId);
+          const rows = await sql`UPDATE kortyx_runtime_runs SET lease_until = ${Date.now() + 12e4}, last_activity = ${Date.now()}
+            WHERE scope = ${store.scope} AND id = ${runId} AND lease_token = ${token}
+              AND lease_until > ${Date.now()} RETURNING id`;
+          if (!rows.length)
+            throw new import_errors5.PersistenceError("The runtime execution lease was lost.");
+        });
+      };
+      await store.transaction(async (sql) => {
+        if (sessionId) await store.touchSession(sql, sessionId);
+        const rows = await sql`INSERT INTO kortyx_runtime_runs AS r (scope, id, last_activity, lease_token, lease_until, session_id)
+          VALUES (${store.scope}, ${runId}, ${Date.now()}, ${token}, ${Date.now() + 12e4}, ${sessionId ?? null})
+          ON CONFLICT (scope, id) DO UPDATE SET last_activity = EXCLUDED.last_activity,
+            revision = r.revision + 1, lease_token = EXCLUDED.lease_token,
+            lease_until = EXCLUDED.lease_until, session_id = EXCLUDED.session_id
+          WHERE r.lease_until <= ${Date.now()} RETURNING id`;
+        if (!rows.length)
+          throw new import_errors5.PersistenceError("This runtime run is already executing.");
+      });
+      let renewing;
+      let stopped = false;
+      let deadline;
+      const lost = (cause) => {
+        if (stopped) return;
+        stopped = true;
+        clearInterval(timer);
+        clearTimeout(deadline);
+        onLost(cause);
+      };
+      const armDeadline = () => {
+        clearTimeout(deadline);
+        deadline = setTimeout(
+          () => lost(new import_errors5.PersistenceError("Execution lease renewal timed out.")),
+          9e4
+        );
+        deadline.unref();
+      };
+      const timer = setInterval(() => {
+        if (stopped || renewing) return;
+        renewing = renew().then(() => {
+          if (!stopped) armDeadline();
+        }).catch(lost).finally(() => {
+          renewing = void 0;
+        });
+      }, 3e4);
+      timer.unref();
+      armDeadline();
+      return async () => {
+        stopped = true;
+        clearInterval(timer);
+        clearTimeout(deadline);
+        await renewing;
+        await store.transaction(async (sql) => {
+          await sql`UPDATE kortyx_runtime_runs SET lease_token = NULL, lease_until = 0, last_activity = ${Date.now()}
+            WHERE scope = ${store.scope} AND id = ${runId} AND lease_token = ${token}`;
+        });
+      };
+    },
+    close: () => store.close()
+  };
+  registerFrameworkCacheStorage(
+    adapter,
+    (cache, ttlMs2, timeoutMs) => store.attachCache(cache, ttlMs2, timeoutMs)
+  );
+  return adapter;
+}
+
 // src/framework/redis/pending-request-store.ts
 function createRedisPendingRequestStore(options) {
   const prefix = options.prefix ?? "kortyx:pending:";
@@ -267,8 +1354,8 @@ function createRedisPendingRequestStore(options) {
 }
 
 // src/framework/redis/redis-checkpointer.ts
-var import_errors = require("@kortyx/core/errors");
-var import_langgraph_checkpoint2 = require("@langchain/langgraph-checkpoint");
+var import_errors6 = require("@kortyx/core/errors");
+var import_langgraph_checkpoint3 = require("@langchain/langgraph-checkpoint");
 var utf8Bytes2 = (s) => new Uint8Array(Buffer.from(s, "utf8"));
 var utf8String2 = (u8) => typeof u8 === "string" ? u8 : Buffer.from(u8).toString("utf8");
 var jsonSerde2 = {
@@ -297,7 +1384,7 @@ function createRedisCheckpointSaver(options) {
     },
     getNextVersion(current) {
       if (typeof current === "string") {
-        throw new import_errors.PersistenceError(
+        throw new import_errors6.PersistenceError(
           "Please override this method to use string versions."
         );
       }
@@ -307,7 +1394,7 @@ function createRedisCheckpointSaver(options) {
       const threadId = config.configurable?.thread_id;
       const checkpointNs = config.configurable?.checkpoint_ns ?? "";
       if (!threadId) return void 0;
-      const requested = (0, import_langgraph_checkpoint2.getCheckpointId)(config);
+      const requested = (0, import_langgraph_checkpoint3.getCheckpointId)(config);
       const checkpointId = requested || await store.get(latestKey(threadId, checkpointNs)) || "";
       if (!checkpointId) return void 0;
       const raw = await store.get(
@@ -365,11 +1452,11 @@ function createRedisCheckpointSaver(options) {
       const threadId = config.configurable?.thread_id;
       const checkpointNs = config.configurable?.checkpoint_ns ?? "";
       if (!threadId) {
-        throw new import_errors.PersistenceError(
+        throw new import_errors6.PersistenceError(
           'Failed to put checkpoint: missing "thread_id" in config.configurable.'
         );
       }
-      const prepared = (0, import_langgraph_checkpoint2.copyCheckpoint)(checkpoint);
+      const prepared = (0, import_langgraph_checkpoint3.copyCheckpoint)(checkpoint);
       const [[, chkBytes], [, metaBytes]] = await Promise.all([
         serde.dumpsTyped(prepared),
         serde.dumpsTyped(metadata)
@@ -396,12 +1483,12 @@ function createRedisCheckpointSaver(options) {
       const checkpointNs = config.configurable?.checkpoint_ns;
       const checkpointId = config.configurable?.checkpoint_id;
       if (!threadId) {
-        throw new import_errors.PersistenceError(
+        throw new import_errors6.PersistenceError(
           'Failed to put writes: missing "thread_id" in config.configurable.'
         );
       }
       if (!checkpointId) {
-        throw new import_errors.PersistenceError(
+        throw new import_errors6.PersistenceError(
           'Failed to put writes: missing "checkpoint_id" in config.configurable.'
         );
       }
@@ -410,7 +1497,7 @@ function createRedisCheckpointSaver(options) {
       await Promise.all(
         writes.map(async ([channel, value], idx) => {
           const [, vBytes] = await serde.dumpsTyped(value);
-          const mappedIdx = import_langgraph_checkpoint2.WRITES_IDX_MAP[channel] ?? idx;
+          const mappedIdx = import_langgraph_checkpoint3.WRITES_IDX_MAP[channel] ?? idx;
           const innerKeyStr = `${taskId},${mappedIdx}`;
           const payload = {
             taskId,
@@ -443,12 +1530,12 @@ function createRedisCheckpointSaver(options) {
 }
 
 // src/framework/redis/redis-store.ts
-var import_errors3 = require("@kortyx/core/errors");
+var import_errors8 = require("@kortyx/core/errors");
 
 // src/framework/redis/redis-client.ts
 var import_node_net = require("net");
 var import_node_tls = require("tls");
-var import_errors2 = require("@kortyx/core/errors");
+var import_errors7 = require("@kortyx/core/errors");
 var encodeBulk = (s) => {
   const b = Buffer.from(s, "utf8");
   return Buffer.concat([
@@ -555,15 +1642,20 @@ function createRedisClient(options) {
       s.setNoDelay(true);
       s.setKeepAlive(true);
       s.on("data", (chunk) => {
+        if (socket !== s) return;
         buffer = Buffer.concat([buffer, chunk]);
         drainReplies();
       });
       s.on("error", (err) => {
+        if (socket !== s) return;
         ready = false;
         while (inflight.length) inflight.shift()?.reject(err);
       });
       s.on("close", () => {
+        if (socket !== s) return;
         ready = false;
+        socket = null;
+        buffer = Buffer.alloc(0);
         while (inflight.length)
           inflight.shift()?.reject(new Error("Redis socket closed"));
       });
@@ -586,7 +1678,7 @@ function createRedisClient(options) {
       if (password) {
         const r = await send("AUTH", [password]);
         if (typeof r === "object" && r && r.type === "error") {
-          throw new import_errors2.PersistenceError(
+          throw new import_errors7.PersistenceError(
             `Redis AUTH failed: ${r.message}`
           );
         }
@@ -594,7 +1686,7 @@ function createRedisClient(options) {
       if (db && Number.isFinite(db) && db > 0) {
         const r = await send("SELECT", [String(db)]);
         if (typeof r === "object" && r && r.type === "error") {
-          throw new import_errors2.PersistenceError(
+          throw new import_errors7.PersistenceError(
             `Redis SELECT failed: ${r.message}`
           );
         }
@@ -608,6 +1700,14 @@ function createRedisClient(options) {
     }
   };
   return {
+    async close() {
+      socket?.destroy();
+      socket = null;
+      buffer = Buffer.alloc(0);
+      ready = false;
+      while (inflight.length)
+        inflight.shift()?.reject(new Error("Redis socket closed"));
+    },
     async command(cmd, args = []) {
       await ensureConnected();
       return send(cmd, args);
@@ -625,20 +1725,21 @@ function createRedisFrameworkStore(options) {
       try {
         return await rawClient.command(...args);
       } catch (cause) {
-        throw new import_errors3.PersistenceError("Redis command failed.", cause);
+        throw new import_errors8.PersistenceError("Redis command failed.", cause);
       }
     }
   };
   const prefix = options.prefix ?? "kortyx:fw:";
   const k = (key) => `${prefix}${key}`;
   return {
+    close: async () => rawClient.close?.(),
     async list(prefixKey) {
       const keys = await this.scanKeys(prefixKey);
       const values = await Promise.all(
         [...new Set(keys)].map(async (key) => {
           const value = await client.command("GET", [key]);
           if (isRedisError(value))
-            throw new import_errors3.PersistenceError(`Redis GET error: ${value.message}`);
+            throw new import_errors8.PersistenceError(`Redis GET error: ${value.message}`);
           return value;
         })
       );
@@ -649,7 +1750,7 @@ function createRedisFrameworkStore(options) {
     async take(key) {
       const r = await client.command("GETDEL", [k(key)]);
       if (isRedisError(r))
-        throw new import_errors3.PersistenceError(`Redis GETDEL error: ${r.message}`);
+        throw new import_errors8.PersistenceError(`Redis GETDEL error: ${r.message}`);
       return typeof r === "string" ? r : null;
     },
     async get(key) {
@@ -657,7 +1758,7 @@ function createRedisFrameworkStore(options) {
       if (r === null) return null;
       if (typeof r === "string") return r;
       if (isRedisError(r)) {
-        throw new import_errors3.PersistenceError(`Redis GET error: ${r.message}`);
+        throw new import_errors8.PersistenceError(`Redis GET error: ${r.message}`);
       }
       return null;
     },
@@ -665,32 +1766,32 @@ function createRedisFrameworkStore(options) {
       const args = [k(key), value, "PX", String(Math.max(1, ttlMs))];
       const r = await client.command("SET", args);
       if (isRedisError(r)) {
-        throw new import_errors3.PersistenceError(`Redis SET error: ${r.message}`);
+        throw new import_errors8.PersistenceError(`Redis SET error: ${r.message}`);
       }
     },
     async del(key) {
       const r = await client.command("DEL", [k(key)]);
       if (isRedisError(r)) {
-        throw new import_errors3.PersistenceError(`Redis DEL error: ${r.message}`);
+        throw new import_errors8.PersistenceError(`Redis DEL error: ${r.message}`);
       }
     },
     async hset(key, field, value) {
       const r = await client.command("HSET", [k(key), field, value]);
       if (isRedisError(r)) {
-        throw new import_errors3.PersistenceError(`Redis HSET error: ${r.message}`);
+        throw new import_errors8.PersistenceError(`Redis HSET error: ${r.message}`);
       }
     },
     async hsetnx(key, field, value) {
       const r = await client.command("HSETNX", [k(key), field, value]);
       if (isRedisError(r)) {
-        throw new import_errors3.PersistenceError(`Redis HSETNX error: ${r.message}`);
+        throw new import_errors8.PersistenceError(`Redis HSETNX error: ${r.message}`);
       }
       return typeof r === "number" ? r : 0;
     },
     async hgetall(key) {
       const r = await client.command("HGETALL", [k(key)]);
       if (isRedisError(r)) {
-        throw new import_errors3.PersistenceError(`Redis HGETALL error: ${r.message}`);
+        throw new import_errors8.PersistenceError(`Redis HGETALL error: ${r.message}`);
       }
       if (!Array.isArray(r)) return {};
       const out = {};
@@ -707,7 +1808,7 @@ function createRedisFrameworkStore(options) {
         String(Math.max(1, ttlMs))
       ]);
       if (isRedisError(r)) {
-        throw new import_errors3.PersistenceError(`Redis PEXPIRE error: ${r.message}`);
+        throw new import_errors8.PersistenceError(`Redis PEXPIRE error: ${r.message}`);
       }
     },
     async scanKeys(prefixKey) {
@@ -723,7 +1824,7 @@ function createRedisFrameworkStore(options) {
           "200"
         ]);
         if (isRedisError(r))
-          throw new import_errors3.PersistenceError(`Redis SCAN error: ${r.message}`);
+          throw new import_errors8.PersistenceError(`Redis SCAN error: ${r.message}`);
         if (!Array.isArray(r) || r.length < 2) break;
         cursor = typeof r[0] === "string" ? r[0] : "0";
         const batch = r[1];
@@ -739,17 +1840,17 @@ function createRedisFrameworkStore(options) {
       if (keys.length === 0) return;
       const r = await client.command("DEL", keys);
       if (isRedisError(r)) {
-        throw new import_errors3.PersistenceError(`Redis DEL error: ${r.message}`);
+        throw new import_errors8.PersistenceError(`Redis DEL error: ${r.message}`);
       }
     }
   };
 }
 
 // src/framework/redis/session-checkpoint-store.ts
-var import_node_crypto = require("crypto");
-var import_errors4 = require("@kortyx/core/errors");
+var import_node_crypto5 = require("crypto");
+var import_errors9 = require("@kortyx/core/errors");
 var DEFAULT_MAX_CHECKPOINTS_PER_SESSION = 50;
-var clone = (value) => value === void 0 ? value : JSON.parse(JSON.stringify(value));
+var clone2 = (value) => value === void 0 ? value : JSON.parse(JSON.stringify(value));
 var uniqueStrings = (values) => Array.from(
   new Set(
     Array.from(values).filter(
@@ -758,9 +1859,9 @@ var uniqueStrings = (values) => Array.from(
   )
 );
 var createId = (prefix) => {
-  return `${prefix}-${(0, import_node_crypto.randomUUID)()}`;
+  return `${prefix}-${(0, import_node_crypto5.randomUUID)()}`;
 };
-var createResumeToken = () => (0, import_node_crypto.randomUUID)();
+var createResumeToken = () => (0, import_node_crypto5.randomUUID)();
 var toSummary = (record2) => ({
   id: record2.id,
   sessionId: record2.sessionId,
@@ -826,7 +1927,7 @@ function createRedisSessionCheckpointStore(options) {
     const headId = await store.get(headKey(sessionId));
     if (!headId) return null;
     const record2 = await getRecord(headId);
-    return record2 ? clone(record2) : null;
+    return record2 ? clone2(record2) : null;
   };
   return {
     async list(sessionId) {
@@ -834,7 +1935,7 @@ function createRedisSessionCheckpointStore(options) {
     },
     async get(id) {
       const record2 = await getRecord(id);
-      return record2 ? clone(record2) : null;
+      return record2 ? clone2(record2) : null;
     },
     getHead,
     async append(args) {
@@ -848,7 +1949,7 @@ function createRedisSessionCheckpointStore(options) {
         turnIndex: previousHead ? previousHead.turnIndex + 1 : 0,
         createdAt: Date.now(),
         workflow: args.workflow,
-        state: clone(args.state),
+        state: clone2(args.state),
         nodes: uniqueStrings(args.nodes ?? []),
         effects: {
           structuredStreamIds: uniqueStrings(args.structuredStreamIds ?? []),
@@ -856,7 +1957,7 @@ function createRedisSessionCheckpointStore(options) {
             pendingRequests.map((request) => request.token)
           )
         },
-        activePendingRequests: clone(pendingRequests),
+        activePendingRequests: clone2(pendingRequests),
         ...previousHead ? { parentCheckpointId: previousHead.id } : {},
         ...args.label ? { label: args.label } : {},
         ...args.workflowVersion ? { workflowVersion: args.workflowVersion } : {},
@@ -864,12 +1965,12 @@ function createRedisSessionCheckpointStore(options) {
       };
       await saveRecord(record2);
       await prune(args.sessionId);
-      return clone(record2);
+      return clone2(record2);
     },
     async rollbackTo(id) {
       const target = await getRecord(id);
       if (!target)
-        throw new import_errors4.KortyxError("NOT_FOUND", `Checkpoint "${id}" not found.`, {
+        throw new import_errors9.KortyxError("NOT_FOUND", `Checkpoint "${id}" not found.`, {
           category: "request",
           retryable: false,
           safeMessage: "The requested checkpoint was not found."
@@ -894,22 +1995,22 @@ function createRedisSessionCheckpointStore(options) {
         head: target.id,
         invalidatedStructuredStreamIds,
         invalidatedInterruptTokens,
-        activePendingRequests: clone(target.activePendingRequests)
+        activePendingRequests: clone2(target.activePendingRequests)
       };
     },
     async fork(id, options2) {
       const source = await getRecord(id);
       if (!source)
-        throw new import_errors4.KortyxError("NOT_FOUND", `Checkpoint "${id}" not found.`, {
+        throw new import_errors9.KortyxError("NOT_FOUND", `Checkpoint "${id}" not found.`, {
           category: "request",
           retryable: false,
           safeMessage: "The requested checkpoint was not found."
         });
       const sessionId = options2?.newSessionId || createId("session");
-      const { parentCheckpointId: _parentCheckpointId, ...sourceRecord } = clone(source);
+      const { parentCheckpointId: _parentCheckpointId, ...sourceRecord } = clone2(source);
       const runId = source.activePendingRequests.some(
         (request) => request.graphSnapshot
-      ) ? `run-${(0, import_node_crypto.randomUUID)()}` : source.runId;
+      ) ? `run-${(0, import_node_crypto5.randomUUID)()}` : source.runId;
       const forked = {
         ...sourceRecord,
         runId,
@@ -917,7 +2018,7 @@ function createRedisSessionCheckpointStore(options) {
         sessionId,
         parentSessionId: source.sessionId,
         forkedFrom: source.id,
-        activePendingRequests: clone(source.activePendingRequests).map(
+        activePendingRequests: clone2(source.activePendingRequests).map(
           (request) => ({
             ...request,
             runId,
@@ -932,21 +2033,21 @@ function createRedisSessionCheckpointStore(options) {
         sessionId,
         parentSessionId: source.sessionId,
         forkedFrom: source.id,
-        checkpoint: clone(forked)
+        checkpoint: clone2(forked)
       };
     }
   };
 }
 
 // src/framework/session-checkpoints.ts
-var import_node_crypto2 = require("crypto");
-var import_errors5 = require("@kortyx/core/errors");
+var import_node_crypto6 = require("crypto");
+var import_errors10 = require("@kortyx/core/errors");
 var DEFAULT_MAX_CHECKPOINTS_PER_SESSION2 = 50;
-var createCheckpointId = () => `cp-${(0, import_node_crypto2.randomUUID)()}`;
-var createSessionId = () => `session-${(0, import_node_crypto2.randomUUID)()}`;
-var createResumeToken2 = () => (0, import_node_crypto2.randomUUID)();
-var createRequestId = () => `human-${(0, import_node_crypto2.randomUUID)()}`;
-var clone2 = (value) => value === void 0 ? value : JSON.parse(JSON.stringify(value));
+var createCheckpointId = () => `cp-${(0, import_node_crypto6.randomUUID)()}`;
+var createSessionId = () => `session-${(0, import_node_crypto6.randomUUID)()}`;
+var createResumeToken2 = () => (0, import_node_crypto6.randomUUID)();
+var createRequestId = () => `human-${(0, import_node_crypto6.randomUUID)()}`;
+var clone3 = (value) => value === void 0 ? value : JSON.parse(JSON.stringify(value));
 var toSummary2 = (record2) => ({
   id: record2.id,
   sessionId: record2.sessionId,
@@ -975,7 +2076,7 @@ function createInMemorySessionCheckpointStore(options) {
   const headBySession = /* @__PURE__ */ new Map();
   const sortedRecords = (sessionId) => (bySession.get(sessionId) ?? []).map((id) => byId.get(id)).filter((record2) => Boolean(record2)).sort((a, b) => a.turnIndex - b.turnIndex || a.createdAt - b.createdAt);
   const saveRecord = (record2) => {
-    byId.set(record2.id, clone2(record2));
+    byId.set(record2.id, clone3(record2));
     const ids = bySession.get(record2.sessionId) ?? [];
     if (!ids.includes(record2.id)) ids.push(record2.id);
     bySession.set(record2.sessionId, ids);
@@ -1000,7 +2101,7 @@ function createInMemorySessionCheckpointStore(options) {
     const headId = headBySession.get(sessionId);
     if (!headId) return null;
     const record2 = byId.get(headId);
-    return record2 ? clone2(record2) : null;
+    return record2 ? clone3(record2) : null;
   };
   return {
     async list(sessionId) {
@@ -1008,7 +2109,7 @@ function createInMemorySessionCheckpointStore(options) {
     },
     async get(id) {
       const record2 = byId.get(id);
-      return record2 ? clone2(record2) : null;
+      return record2 ? clone3(record2) : null;
     },
     getHead,
     async append(args) {
@@ -1023,7 +2124,7 @@ function createInMemorySessionCheckpointStore(options) {
         turnIndex,
         createdAt: Date.now(),
         workflow: args.workflow,
-        state: clone2(args.state),
+        state: clone3(args.state),
         nodes: uniqueStrings2(args.nodes ?? []),
         effects: {
           structuredStreamIds: uniqueStrings2(args.structuredStreamIds ?? []),
@@ -1031,7 +2132,7 @@ function createInMemorySessionCheckpointStore(options) {
             pendingRequests.map((request) => request.token)
           )
         },
-        activePendingRequests: clone2(pendingRequests),
+        activePendingRequests: clone3(pendingRequests),
         ...previousHead ? { parentCheckpointId: previousHead.id } : {},
         ...args.label ? { label: args.label } : {},
         ...args.workflowVersion ? { workflowVersion: args.workflowVersion } : {},
@@ -1039,12 +2140,12 @@ function createInMemorySessionCheckpointStore(options) {
       };
       saveRecord(record2);
       prune(args.sessionId);
-      return clone2(record2);
+      return clone3(record2);
     },
     async rollbackTo(id) {
       const target = byId.get(id);
       if (!target) {
-        throw new import_errors5.KortyxError("NOT_FOUND", `Checkpoint "${id}" not found.`, {
+        throw new import_errors10.KortyxError("NOT_FOUND", `Checkpoint "${id}" not found.`, {
           category: "request",
           retryable: false,
           safeMessage: "The requested checkpoint was not found."
@@ -1070,23 +2171,23 @@ function createInMemorySessionCheckpointStore(options) {
         head: target.id,
         invalidatedStructuredStreamIds,
         invalidatedInterruptTokens,
-        activePendingRequests: clone2(target.activePendingRequests)
+        activePendingRequests: clone3(target.activePendingRequests)
       };
     },
     async fork(id, options2) {
       const source = byId.get(id);
       if (!source) {
-        throw new import_errors5.KortyxError("NOT_FOUND", `Checkpoint "${id}" not found.`, {
+        throw new import_errors10.KortyxError("NOT_FOUND", `Checkpoint "${id}" not found.`, {
           category: "request",
           retryable: false,
           safeMessage: "The requested checkpoint was not found."
         });
       }
       const sessionId = options2?.newSessionId || createSessionId();
-      const { parentCheckpointId: _parentCheckpointId, ...sourceRecord } = clone2(source);
+      const { parentCheckpointId: _parentCheckpointId, ...sourceRecord } = clone3(source);
       const runId = source.activePendingRequests.some(
         (request) => request.graphSnapshot
-      ) ? `run-${(0, import_node_crypto2.randomUUID)()}` : source.runId;
+      ) ? `run-${(0, import_node_crypto6.randomUUID)()}` : source.runId;
       const forked = {
         ...sourceRecord,
         runId,
@@ -1094,7 +2195,7 @@ function createInMemorySessionCheckpointStore(options) {
         sessionId,
         parentSessionId: source.sessionId,
         forkedFrom: source.id,
-        activePendingRequests: clone2(source.activePendingRequests).map(
+        activePendingRequests: clone3(source.activePendingRequests).map(
           (request) => ({
             ...request,
             runId,
@@ -1109,7 +2210,7 @@ function createInMemorySessionCheckpointStore(options) {
         sessionId,
         parentSessionId: source.sessionId,
         forkedFrom: source.id,
-        checkpoint: clone2(forked)
+        checkpoint: clone3(forked)
       };
     }
   };
@@ -1119,10 +2220,27 @@ function createInMemorySessionCheckpointStore(options) {
 function createInMemoryFrameworkAdapter(options) {
   const ttlMs = options?.ttlMs ?? 15 * 60 * 1e3;
   const checkpointer = createInMemoryCheckpointSaver();
+  const pendingRequests = createInMemoryPendingRequestStore();
   return {
     kind: "in-memory",
     ttlMs,
-    pendingRequests: createInMemoryPendingRequestStore(),
+    pendingRequests,
+    maintenance: {
+      setup: async () => {
+      },
+      prune: async (options2) => {
+        const { now, batchSize } = resolvePruneOptions(options2);
+        const result = emptyPruneResult();
+        result.deleted.pendingRequests = pendingRequests.pruneExpired(
+          now,
+          batchSize
+        );
+        result.hasMore = result.deleted.pendingRequests === batchSize;
+        return result;
+      }
+    },
+    close: async () => {
+    },
     sessionCheckpoints: createInMemorySessionCheckpointStore({
       ...options?.maxSessionCheckpoints !== void 0 ? { maxCheckpointsPerSession: options.maxSessionCheckpoints } : {}
     }),
@@ -1142,9 +2260,20 @@ function createRedisFrameworkAdapter(options) {
     prefix: options.prefix ?? "kortyx:fw:"
   });
   const cpPrefix = "kortyx:cp:";
-  return {
+  const adapter = {
     kind: "redis",
     ttlMs,
+    maintenance: {
+      setup: async () => {
+      },
+      prune: async (options2) => {
+        resolvePruneOptions(options2);
+        return emptyPruneResult();
+      }
+    },
+    close: async () => {
+      await store.close?.();
+    },
     pendingRequests: createRedisPendingRequestStore({
       store,
       prefix: "kortyx:pending:"
@@ -1177,53 +2306,47 @@ function createRedisFrameworkAdapter(options) {
       );
     }
   };
+  registerFrameworkCache(
+    adapter,
+    {
+      get: (key) => store.get(`kortyx:runtime-cache:${key}`),
+      set: (key, value, ttl) => store.set(`kortyx:runtime-cache:${key}`, value, ttl),
+      close: () => adapter.close()
+    },
+    ttlMs
+  );
+  return adapter;
 }
 function createFrameworkAdapterFromEnv(env = process.env) {
   const url = env.KORTYX_REDIS_URL || env.REDIS_URL || env.KORTYX_FRAMEWORK_REDIS_URL || "";
   const ttlMsRaw = env.KORTYX_FRAMEWORK_TTL_MS || env.KORTYX_TTL_MS || "";
   const ttlMs = ttlMsRaw ? Number(ttlMsRaw) : void 0;
+  if (env.KORTYX_POSTGRES_URL) {
+    const storage = createPostgresFrameworkAdapter({
+      connectionString: env.KORTYX_POSTGRES_URL,
+      ...ttlMs !== void 0 ? { ttlMs } : {}
+    });
+    return url ? createCachingFrameworkAdapter({
+      storage,
+      cache: createRedisFrameworkAdapter({ url })
+    }) : storage;
+  }
   if (url)
-    return createRedisFrameworkAdapter({ url, ...ttlMs ? { ttlMs } : {} });
-  return createInMemoryFrameworkAdapter({ ...ttlMs ? { ttlMs } : {} });
-}
-
-// src/framework/graph-snapshot.ts
-async function captureGraphSnapshot(saver, threadId, checkpointId) {
-  const tuple = await saver.getTuple({
-    configurable: {
-      thread_id: threadId,
-      checkpoint_ns: "",
-      ...checkpointId ? { checkpoint_id: checkpointId } : {}
-    }
+    return createRedisFrameworkAdapter({
+      url,
+      ...ttlMs ? { ttlMs } : {}
+    });
+  return createInMemoryFrameworkAdapter({
+    ...ttlMs ? { ttlMs } : {}
   });
-  return tuple ? JSON.parse(JSON.stringify(tuple)) : void 0;
-}
-async function restoreGraphSnapshot(saver, snapshot, threadId) {
-  const copy = JSON.parse(JSON.stringify(snapshot));
-  const config = await saver.put(
-    { configurable: { thread_id: threadId, checkpoint_ns: "" } },
-    copy.checkpoint,
-    copy.metadata,
-    copy.checkpoint.channel_versions
-  );
-  const reset = saver;
-  if (reset.deleteCheckpointWrites)
-    await reset.deleteCheckpointWrites(threadId, "", copy.checkpoint.id);
-  const writes = /* @__PURE__ */ new Map();
-  for (const [task, channel, value] of copy.pendingWrites ?? []) {
-    const group = writes.get(task) ?? [];
-    group.push([channel, value]);
-    writes.set(task, group);
-  }
-  for (const [task, group] of writes)
-    await saver.putWrites(config, group, task);
 }
 
 // src/graph/create-execution-graph.ts
 var import_promises = require("timers/promises");
 var import_core3 = require("@kortyx/core");
-var import_errors8 = require("@kortyx/core/errors");
+var import_errors13 = require("@kortyx/core/errors");
 var import_hooks2 = require("@kortyx/hooks");
+var import_internal2 = require("@kortyx/hooks/internal");
 var import_utils2 = require("@kortyx/utils");
 var import_langgraph3 = require("@langchain/langgraph");
 
@@ -1309,8 +2432,9 @@ async function resolveNodeHandler(args) {
 
 // src/graph/call-workflow.ts
 var import_core = require("@kortyx/core");
-var import_errors6 = require("@kortyx/core/errors");
+var import_errors11 = require("@kortyx/core/errors");
 var import_hooks = require("@kortyx/hooks");
+var import_internal = require("@kortyx/hooks/internal");
 var import_singletons = require("@langchain/core/singletons");
 var import_langgraph = require("@langchain/langgraph");
 function createWorkflowCallService(config, _parent, execution = {}) {
@@ -1319,26 +2443,26 @@ function createWorkflowCallService(config, _parent, execution = {}) {
       (0, import_core.throwIfExecutionAborted)(execution.abortSignal);
       const depth = (config.workflowCallDepth ?? 0) + 1;
       if (depth > 16)
-        throw new import_errors6.WorkflowContractError(
+        throw new import_errors11.WorkflowContractError(
           "Maximum child workflow depth (16) exceeded."
         );
       const workflow = await config.selectWorkflow?.(args.workflow);
       if (!workflow || workflow.id !== args.workflow)
-        throw new import_errors6.WorkflowContractError(
+        throw new import_errors11.WorkflowContractError(
           `Workflow '${args.workflow}' is not registered.`
         );
       if (!workflow.inputSchema || !workflow.outputSchema)
-        throw new import_errors6.WorkflowContractError(
+        throw new import_errors11.WorkflowContractError(
           `Callable workflow '${workflow.id}' requires inputSchema and outputSchema.`
         );
       if (args.definition && (args.definition.version !== workflow.version || args.definition.inputSchema !== workflow.inputSchema || args.definition.outputSchema !== workflow.outputSchema)) {
-        throw new import_errors6.WorkflowContractError(
+        throw new import_errors11.WorkflowContractError(
           "The typed workflow contract does not match the registered definition."
         );
       }
       const snapshot = args.snapshot;
       if (snapshot && snapshot.version !== workflow.version)
-        throw new import_errors6.WorkflowContractError(
+        throw new import_errors11.WorkflowContractError(
           `Workflow '${workflow.id}' changed since the call was suspended.`
         );
       const input = snapshot ? void 0 : workflow.inputSchema.parse(args.input);
@@ -1397,10 +2521,10 @@ function createWorkflowCallService(config, _parent, execution = {}) {
           }
           if (event === "error") {
             const failure = payload?.failure;
-            throw (0, import_errors6.isFailureDescriptor)(failure) ? (0, import_errors6.errorFromFailure)(failure) : new Error("Child workflow failed.");
+            throw (0, import_errors11.isFailureDescriptor)(failure) ? (0, import_errors11.errorFromFailure)(failure) : new Error("Child workflow failed.");
           }
           if (event === "transition")
-            throw new import_errors6.WorkflowContractError(
+            throw new import_errors11.WorkflowContractError(
               "transitionTo is not supported inside child workflows; useWorkflow returns to its caller."
             );
           const value = payload;
@@ -1455,7 +2579,7 @@ function createWorkflowCallService(config, _parent, execution = {}) {
         const checkpoint = await captureGraphSnapshot(saver, threadId).catch(
           (cause) => {
             if ((0, import_core.isExecutionLimitReached)(error))
-              throw new import_errors6.PersistenceError(
+              throw new import_errors11.PersistenceError(
                 "Cannot checkpoint a suspended child workflow.",
                 cause
               );
@@ -1492,7 +2616,7 @@ function createWorkflowCallService(config, _parent, execution = {}) {
       if (request) {
         const checkpoint = await captureGraphSnapshot(saver, threadId);
         if (!checkpoint)
-          throw new import_errors6.WorkflowContractError(
+          throw new import_errors11.WorkflowContractError(
             "Child interrupted without a graph checkpoint."
           );
         return {
@@ -1510,8 +2634,8 @@ function createWorkflowCallService(config, _parent, execution = {}) {
       try {
         data = workflow.outputSchema.parse(result.data ?? {});
       } catch (cause) {
-        if (!Array.isArray((0, import_errors6.errorProperty)(cause, "issues"))) throw cause;
-        throw new import_errors6.ValidationError(
+        if (!Array.isArray((0, import_errors11.errorProperty)(cause, "issues"))) throw cause;
+        throw new import_errors11.ValidationError(
           "INVALID_OUTPUT",
           "Child output validation failed.",
           cause
@@ -1521,11 +2645,13 @@ function createWorkflowCallService(config, _parent, execution = {}) {
       return {
         status: "completed",
         data,
+        toolObservations: result.runtime.__kortyx?.workflowState?.__kortyxToolObservations ?? [],
         usage: result.runtime.tokenUsage
       };
     };
     const trace = config.telemetry?.trace ?? config.reasonTrace;
-    return trace?.withSpan ? trace.withSpan(
+    return (0, import_internal.withSafeTraceSpan)(
+      trace,
       {
         name: "kortyx.workflow.call",
         attributes: {
@@ -1539,13 +2665,13 @@ function createWorkflowCallService(config, _parent, execution = {}) {
         }
       },
       execute
-    ) : execute();
+    );
   };
 }
 
 // src/graph/parallel-graph.ts
 var import_core2 = require("@kortyx/core");
-var import_errors7 = require("@kortyx/core/errors");
+var import_errors12 = require("@kortyx/core/errors");
 var import_utils = require("@kortyx/utils");
 var import_langgraph2 = require("@langchain/langgraph");
 var WORK = "__kortyx_parallel_work";
@@ -1553,7 +2679,7 @@ var WAIT = "__kortyx_parallel_wait";
 var FINISH = "__kortyx_parallel_finish";
 var KEY = "__kortyxParallelGraph";
 var record = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
-var clone3 = (value) => JSON.parse(JSON.stringify(value));
+var clone4 = (value) => JSON.parse(JSON.stringify(value));
 var zeroUsage = () => ({ input: 0, output: 0, total: 0 });
 function hasParallelEdges(workflow) {
   const groups = /* @__PURE__ */ new Map();
@@ -1572,7 +2698,7 @@ function addParallelGraphCoordinator(builder, workflow, config, execution, execu
   const outgoing = /* @__PURE__ */ new Map();
   for (const [from, to, condition] of workflow.edges) {
     if (from === "__end__" || to === "__start__" || from !== "__start__" && !Object.hasOwn(workflow.nodes, from) || !incoming.has(to))
-      throw new import_errors7.WorkflowContractError(
+      throw new import_errors12.WorkflowContractError(
         `Invalid parallel graph edge '${from}' \u2192 '${to}'.`
       );
     if (!incoming.get(to)?.includes(from)) incoming.get(to)?.push(from);
@@ -1589,7 +2715,7 @@ function addParallelGraphCoordinator(builder, workflow, config, execution, execu
       (id) => incoming.get(id)?.every((from) => ancestors.has(from))
     );
     if (!ready.length)
-      throw new import_errors7.KortyxError(
+      throw new import_errors12.KortyxError(
         "GRAPH_CYCLE",
         "Parallel graph back-edges are not supported: use a sequential child workflow for loops.",
         {
@@ -1611,7 +2737,7 @@ function addParallelGraphCoordinator(builder, workflow, config, execution, execu
     }
   }
   ids.splice(0, ids.length, ...ordered);
-  const failure = (code, message, node, cause) => new import_errors7.KortyxError(code, message, {
+  const failure = (code, message, node, cause) => new import_errors12.KortyxError(code, message, {
     category: "workflow",
     retryable: false,
     safeMessage: message,
@@ -1623,6 +2749,20 @@ function addParallelGraphCoordinator(builder, workflow, config, execution, execu
     for (const parent of parents) {
       for (const [key, field] of Object.entries(parent[property])) {
         const previous = Object.hasOwn(merged, key) ? merged[key] : void 0;
+        if (property === "workflowFields" && key === "__kortyxToolObservations" && previous && Array.isArray(previous.value) && Array.isArray(field.value)) {
+          const observations = /* @__PURE__ */ new Map();
+          for (const observation of [...previous.value, ...field.value]) {
+            if (record(observation) && typeof observation.attemptId === "string")
+              observations.set(observation.attemptId, observation);
+          }
+          Object.defineProperty(merged, key, {
+            value: { writer: field.writer, value: [...observations.values()] },
+            enumerable: true,
+            configurable: true,
+            writable: true
+          });
+          continue;
+        }
         if (previous && previous.writer !== field.writer) {
           if (journal.nodes[previous.writer]?.ancestors.includes(field.writer))
             continue;
@@ -1670,21 +2810,21 @@ function addParallelGraphCoordinator(builder, workflow, config, execution, execu
   const load = (state) => {
     const saved = state.runtime[KEY];
     if (saved && (config.resume === true || !config.executionRunId || saved.runId === config.executionRunId)) {
-      const journal = clone3(saved);
+      const journal = clone4(saved);
       if (journal.version !== 1 || journal.workflowVersion !== workflow.version)
-        throw new import_errors7.WorkflowContractError(
+        throw new import_errors12.WorkflowContractError(
           "Parallel workflow changed since its execution was suspended."
         );
       return journal;
     }
-    const initialRuntime = clone3(state.runtime);
+    const initialRuntime = clone4(state.runtime);
     delete initialRuntime[KEY];
     return {
       version: 1,
       runId: config.executionRunId,
       workflowVersion: workflow.version,
       initialInput: state.input,
-      initialData: clone3(state.data ?? {}),
+      initialData: clone4(state.data ?? {}),
       initialRuntime,
       nodes: Object.fromEntries(
         ids.map((id) => [
@@ -1759,9 +2899,9 @@ function addParallelGraphCoordinator(builder, workflow, config, execution, execu
         );
         privateState = {
           ...state,
-          input: nodeInput === void 0 ? void 0 : clone3(nodeInput),
-          data: clone3(data),
-          runtime: clone3({
+          input: nodeInput === void 0 ? void 0 : clone4(nodeInput),
+          data: clone4(data),
+          runtime: clone4({
             ...inheritedRuntime,
             tokenUsage: zeroUsage(),
             ...node.runtime,
@@ -1785,8 +2925,8 @@ function addParallelGraphCoordinator(builder, workflow, config, execution, execu
             throw new import_langgraph2.GraphInterrupt([]);
           },
           (nodeState) => {
-            const snapshot = clone3(journal);
-            snapshot.nodes[id].runtime = clone3(
+            const snapshot = clone4(journal);
+            snapshot.nodes[id].runtime = clone4(
               nodeState.runtime
             );
             for (const activation of Object.values(snapshot.nodes))
@@ -1853,10 +2993,10 @@ function addParallelGraphCoordinator(builder, workflow, config, execution, execu
           control ??= error;
         } else if ((0, import_core2.isExecutionCancelled)(error) || execution.abortSignal?.aborted) {
           control ??= error;
-        } else if ((0, import_errors7.serializeFailure)(error).category === "persistence")
+        } else if ((0, import_errors12.serializeFailure)(error).category === "persistence")
           control ??= error;
         else {
-          node.failure = (0, import_errors7.serializeFailure)(error);
+          node.failure = (0, import_errors12.serializeFailure)(error);
           node.failure.context = {
             ...node.failure.context,
             node: id,
@@ -1949,7 +3089,7 @@ function addParallelGraphCoordinator(builder, workflow, config, execution, execu
     const id = journal.waitingNode;
     const node = id ? journal.nodes[id] : void 0;
     if (!id || !node?.request)
-      throw new import_errors7.WorkflowContractError("Missing waiting parallel node.");
+      throw new import_errors12.WorkflowContractError("Missing waiting parallel node.");
     const request = {
       ...node.request,
       meta: {
@@ -1979,7 +3119,7 @@ function addParallelGraphCoordinator(builder, workflow, config, execution, execu
     if (failed.length) {
       const relevant = [...failed].reverse().find((id) => id !== "__end__") ?? failed[0];
       const detail = journal.nodes[relevant]?.failure;
-      const error = (0, import_errors7.errorFromFailure)({
+      const error = (0, import_errors12.errorFromFailure)({
         ...detail,
         results: failed.map((id) => ({
           status: "rejected",
@@ -2246,15 +3386,18 @@ async function createExecutionGraph(workflow, config, execution = {}) {
               ...typeof context?.tenantId === "string" ? { tenantId: context.tenantId } : {}
             },
             telemetry: {
-              metadata: {
-                ...runtimeConfig.telemetry?.metadata ?? {},
-                ...context ?? {}
-              },
+              metadata: (0, import_internal2.safeTelemetryMetadata)({
+                ...runtimeConfig.telemetry?.metadata ?? {}
+              }),
               tags: runtimeConfig.telemetry?.tags,
               captureContent: runtimeConfig.telemetry?.captureContent
             }
           };
-          const hookRun = activeTrace?.withSpan ? await activeTrace.withSpan(spanArgs, runNode) : await runNode();
+          const hookRun = await (0, import_internal2.withSafeTraceSpan)(
+            activeTrace,
+            spanArgs,
+            runNode
+          );
           nodeResult = hookRun.result;
           hookRuntimeUpdates = hookRun.runtimeUpdates;
           break;
@@ -2304,7 +3447,7 @@ async function createExecutionGraph(workflow, config, execution = {}) {
       if (res.transitionTo) {
         if (awaitInput)
           throw Object.assign(
-            new import_errors8.KortyxError(
+            new import_errors13.KortyxError(
               "GRAPH_BRANCH_HANDOFF",
               "transitionTo cannot hand off from a parallel branch; useWorkflow returns to its caller.",
               {
@@ -2450,19 +3593,19 @@ async function createExecutionGraph(workflow, config, execution = {}) {
 }
 
 // src/interrupt/tokens.ts
-var import_node_crypto3 = require("crypto");
+var import_node_crypto7 = require("crypto");
 function makeResumeToken() {
-  return (0, import_node_crypto3.randomUUID)();
+  return (0, import_node_crypto7.randomUUID)();
 }
 function makeRequestId(prefix = "req") {
-  return `${prefix}-${(0, import_node_crypto3.randomUUID)()}`;
+  return `${prefix}-${(0, import_node_crypto7.randomUUID)()}`;
 }
 
 // src/registry/file-registry.ts
 var import_promises2 = require("fs/promises");
 var import_node_path2 = require("path");
 var import_core4 = require("@kortyx/core");
-var import_errors9 = require("@kortyx/core/errors");
+var import_errors14 = require("@kortyx/core/errors");
 var DEFAULT_EXTENSIONS = [
   ".workflow.ts",
   ".workflow.mts",
@@ -2536,7 +3679,7 @@ function createFileWorkflowRegistry(options) {
     const fallback = selectOptions?.fallbackId ?? fallbackId;
     const selected = workflows[id] ?? (fallback ? workflows[fallback] : null);
     if (!selected) {
-      throw new import_errors9.KortyxError(
+      throw new import_errors14.KortyxError(
         "UNKNOWN_WORKFLOW",
         `No workflow found for id "${id}" and no fallback "${fallback}" workflow available`,
         {
@@ -2561,7 +3704,7 @@ function createFileWorkflowRegistry(options) {
 }
 
 // src/registry/in-memory-registry.ts
-var import_errors10 = require("@kortyx/core/errors");
+var import_errors15 = require("@kortyx/core/errors");
 function createInMemoryWorkflowRegistry(workflows, options) {
   const byId = /* @__PURE__ */ new Map();
   for (const wf of workflows) byId.set(wf.id, wf);
@@ -2577,7 +3720,7 @@ function createInMemoryWorkflowRegistry(workflows, options) {
       const fallback = selectOptions?.fallbackId ?? fallbackId;
       const wf = byId.get(id) ?? (fallback ? byId.get(fallback) : void 0);
       if (!wf) {
-        throw new import_errors10.KortyxError(
+        throw new import_errors15.KortyxError(
           "UNKNOWN_WORKFLOW",
           `Workflow "${id}" not found${fallback ? ` (fallback "${fallback}" missing too)` : ""}.`,
           {
@@ -2620,6 +3763,7 @@ async function buildInitialGraphState({
   buildInitialGraphState,
   captureGraphSnapshot,
   clearRegisteredNodes,
+  createCachingFrameworkAdapter,
   createExecutionGraph,
   createFileWorkflowRegistry,
   createFrameworkAdapterFromEnv,
@@ -2627,6 +3771,7 @@ async function buildInitialGraphState({
   createInMemoryPendingRequestStore,
   createInMemorySessionCheckpointStore,
   createInMemoryWorkflowRegistry,
+  createPostgresFrameworkAdapter,
   createRedisFrameworkAdapter,
   getCheckpointer,
   getRegisteredNode,