@axlsdk/axl 0.27.0 → 0.27.2

package/dist/index.js

@@ -348,7 +348,7 @@ var sharedGuard = typeof installedGuard === "object" && installedGuard !== null
 var buildPath = typeof __AXL_BUILD_PATH__ === "string" ? __AXL_BUILD_PATH__ : "<source>";
 var thisCopy = {
   path: buildPath.startsWith("file:") ? fileURLToPath(buildPath) : buildPath,
-  version: true ? "0.27.0" : "unknown"
+  version: true ? "0.27.2" : "unknown"
 };
 function warnCrossCopy(other, joined) {
   if (other === thisCopy) return;
@@ -17026,7 +17026,7 @@ ${appendedSchemaText}`;
         `ctx.checkpoint name "${name}" is reserved \u2014 names starting with "__auto/" (case-insensitive) are used by the runtime for ask/spawn/race/parallel/map auto-checkpointing.`
       );
     }
-    return this._checkpoint(name, fn);
+    return this._checkpoint(name, fn, { saveRequired: true });
   }
   /**
    * Internal checkpoint implementation shared by both the public
@@ -17056,7 +17056,17 @@ ${appendedSchemaText}`;
       return saved;
     }
     const result = await fn();
-    await this.stateStore.saveCheckpoint(this.executionId, name, result);
+    if (!options?.saveRequired && this.autoCheckpointCounters.saveFailed) return result;
+    try {
+      await this.stateStore.saveCheckpoint(this.executionId, name, result);
+    } catch (err) {
+      if (options?.saveRequired) throw err;
+      this.autoCheckpointCounters.saveFailed = true;
+      console.error(
+        `[axl] Failed to save checkpoint "${name}" for executionId=${this.executionId}; a replay would run this step and later ones again: ${err instanceof Error ? err.message : String(err)}`
+      );
+      return result;
+    }
     this.emitEvent({
       type: "checkpoint_save",
       ...agentStamp,
@@ -18804,6 +18814,21 @@ function codePointRank(unit) {
 import { writeFileSync, readFileSync, existsSync, mkdirSync, unlinkSync } from "fs";
 import { join } from "path";
 import { tmpdir } from "os";
+
+// src/state/session-update.ts
+async function updateSessionThroughOverrides(store, storeName, sessionId, update) {
+  warnDiagnosticOnce(
+    `session_update_overridden\0${storeName}`,
+    `${storeName}: this subclass overrides saveSession or getSession, so session turns go through them, and overlapping turns from different instances can overwrite each other. Override updateSession too to keep that protection.`,
+    void 0,
+    "docs/api-reference.md#several-app-instances-sharing-a-session"
+  );
+  const stored = await store.getSession(sessionId);
+  const next = update(stored.length > 0 ? stored : null);
+  if (next !== null) await store.saveSession(sessionId, next);
+}
+
+// src/state/memory.ts
 function compareOldestFirst(a, b) {
   return compareExecutionsNewestFirst(b, a);
 }
@@ -18820,7 +18845,7 @@ function resolveMaxExecutions(value) {
 }
 var AWAIT_HUMAN_TEMP_DIR = join(tmpdir(), "axl-memory-store");
 var AWAIT_HUMAN_TEMP_FILE = join(AWAIT_HUMAN_TEMP_DIR, "await-human-state.json");
-var MemoryStore = class {
+var MemoryStore = class _MemoryStore {
   checkpoints = /* @__PURE__ */ new Map();
   sessions = /* @__PURE__ */ new Map();
   sessionMeta = /* @__PURE__ */ new Map();
@@ -18872,6 +18897,14 @@ var MemoryStore = class {
   async saveSession(sessionId, history) {
     this.sessions.set(sessionId, structuredClone(normalizePersistedSessionHistory(history)));
   }
+  async updateSession(sessionId, update) {
+    if (this.saveSession !== _MemoryStore.prototype.saveSession || this.getSession !== _MemoryStore.prototype.getSession) {
+      return updateSessionThroughOverrides(this, "MemoryStore", sessionId, update);
+    }
+    const stored = this.sessions.get(sessionId);
+    const next = update(stored ? structuredClone(stored) : null);
+    if (next !== null) await this.saveSession(sessionId, next);
+  }
   async getSession(sessionId) {
     const history = this.sessions.get(sessionId);
     return history ? structuredClone(history) : [];
@@ -19295,7 +19328,7 @@ function rowToExecutionInfo(row) {
   }
   return normalizeStoredExecution(info);
 }
-var SQLiteStore = class {
+var SQLiteStore = class _SQLiteStore {
   db;
   ttls;
   now;
@@ -19529,6 +19562,17 @@ var SQLiteStore = class {
     );
     stmt.run(sessionId, JSON.stringify(normalizePersistedSessionHistory(history)));
   }
+  async updateSession(sessionId, update) {
+    if (this.saveSession !== _SQLiteStore.prototype.saveSession || this.getSession !== _SQLiteStore.prototype.getSession) {
+      return updateSessionThroughOverrides(this, "SQLiteStore", sessionId, update);
+    }
+    this.db.transaction(() => {
+      const row = this.db.prepare("SELECT history FROM sessions WHERE session_id = ?").get(sessionId);
+      const next = update(row ? safeJsonParse(row.history) ?? [] : null);
+      if (next === null) return;
+      this.db.prepare("INSERT OR REPLACE INTO sessions (session_id, history) VALUES (?, ?)").run(sessionId, JSON.stringify(normalizePersistedSessionHistory(next)));
+    }).immediate();
+  }
   async getSession(sessionId) {
     const stmt = this.db.prepare("SELECT history FROM sessions WHERE session_id = ?");
     const row = stmt.get(sessionId);
@@ -19863,10 +19907,10 @@ var Session = class _Session {
     );
   }
   async sendImpl(workflowName, input, signal, events) {
-    const { history, metadata } = await this.prepareHistory(input);
+    const { history, metadata, base } = await this.prepareHistory(input);
     try {
       const result = await this.runtime.execute(workflowName, input, { metadata, signal, events });
-      await this.commitHistory(history, result);
+      await this.commitHistory(history, base, result);
       return result;
     } finally {
       clearSessionInput(history);
@@ -19882,6 +19926,8 @@ var Session = class _Session {
   async prepareHistory(input) {
     const preparedInput = prepareSessionInput(input);
     const history = await this.store.getSession(this.sessionId);
+    const storedJson = JSON.stringify(history);
+    const hadHistory = history.length > 0;
     let cachedSummary = await this.store.getSessionMeta(this.sessionId, "summaryCache");
     const maxMessages = this.options.history?.maxMessages;
     if (maxMessages && history.length > maxMessages) {
@@ -19896,13 +19942,17 @@ var Session = class _Session {
           summaryModel,
           cachedSummary ? { previousSummary: cachedSummary } : void 0
         );
-        await this.store.saveSessionMeta(this.sessionId, "summaryCache", summary);
+        const stored = JSON.stringify(await this.store.getSession(this.sessionId));
+        if (stored === storedJson) {
+          await this.store.saveSessionMeta(this.sessionId, "summaryCache", summary);
+        }
         cachedSummary = summary;
       }
       const trimmed = history.slice(-maxMessages);
       history.length = 0;
       history.push(...trimmed.map(withoutAnthropicThinking));
     }
+    const base = { storedJson, hadHistory, firstOwnMessage: history.length };
     const userMessage = { role: "user", content: preparedInput.content };
     history.push(userMessage);
     if (this.options.deduplicateInput !== false && preparedInput.normalizedInput !== void 0) {
@@ -19916,13 +19966,13 @@ var Session = class _Session {
       // agent-scoped ask-summary records the runtime would otherwise cache.
       ...this.options.persist === false ? { sessionPersist: false } : {}
     };
-    return { history, metadata };
+    return { history, metadata, base };
   }
   /** Push the assistant reply (if `executeAgentCall` didn't already) and
    *  persist. Shared by `sendImpl` and `streamImpl`. The fallback assistant
    *  push has no agent context and so leaves `agent` undefined — see the
    *  `ChatMessage.agent` field doc. */
-  async commitHistory(history, result) {
+  async commitHistory(history, base, result) {
     const lastMsg = history[history.length - 1];
     if (!(lastMsg && lastMsg.role === "assistant")) {
       history.push({
@@ -19930,8 +19980,35 @@ var Session = class _Session {
         content: typeof result === "string" ? result : JSON.stringify(result)
       });
     }
-    if (this.options.persist !== false) {
+    if (this.options.persist === false) return;
+    if (!this.store.updateSession) {
       await this.store.saveSession(this.sessionId, history);
+      return;
+    }
+    let outcome = "saved";
+    await this.store.updateSession(this.sessionId, (current) => {
+      if (current === null) {
+        outcome = base.hadHistory ? "discarded" : "saved";
+        return base.hadHistory ? null : history;
+      }
+      if (JSON.stringify(current) === base.storedJson) {
+        outcome = "saved";
+        return history;
+      }
+      outcome = "merged";
+      return [...current, ...history.slice(base.firstOwnMessage).map(withoutAnthropicThinking)];
+    });
+    if (outcome === "merged") this.notify("session_turns_merged");
+    else if (outcome === "discarded") this.notify("session_turn_discarded");
+  }
+  /** The turn is already saved, so a listener that throws can't be allowed to fail it. */
+  notify(event) {
+    try {
+      this.runtime.emit(event, { sessionId: this.sessionId });
+    } catch (err) {
+      console.error(
+        `[axl] A ${event} listener failed: ${err instanceof Error ? err.message : String(err)}`
+      );
     }
   }
   async stream(workflowName, input, options) {
@@ -19959,10 +20036,12 @@ var Session = class _Session {
   }
   async streamImpl(workflowName, input, resolveReady, rejectReady, signal, events) {
     let history;
+    let base;
     let axlStream;
     try {
       const prepared = await this.prepareHistory(input);
       history = prepared.history;
+      base = prepared.base;
       axlStream = this.runtime.stream(workflowName, input, {
         metadata: prepared.metadata,
         signal,
@@ -19976,12 +20055,19 @@ var Session = class _Session {
     resolveReady(axlStream);
     try {
       const completion = axlStream.promise.then(
-        (result) => this.commitHistory(history, result).catch((err) => {
-          this.runtime.emit("error", {
-            type: "session_history_save_failed",
-            sessionId: this.sessionId,
-            error: err instanceof Error ? err.message : String(err)
-          });
+        (result) => this.commitHistory(history, base, result).catch((err) => {
+          const error = err instanceof Error ? err.message : String(err);
+          try {
+            this.runtime.emit("error", {
+              type: "session_history_save_failed",
+              sessionId: this.sessionId,
+              error
+            });
+          } catch {
+            console.error(
+              `[axl] Failed to save session history for sessionId=${this.sessionId}: ${error}`
+            );
+          }
         }),
         () => void 0
       );
@@ -22057,7 +22143,11 @@ var AxlRuntime = class extends EventEmitter2 {
         observation
       });
       if (this.stateStore.deleteCheckpoints) {
-        await this.stateStore.deleteCheckpoints(execInfo.executionId);
+        await this.stateStore.deleteCheckpoints(execInfo.executionId).catch((err) => {
+          console.error(
+            `[axl] Failed to delete checkpoints for executionId=${execInfo.executionId}: ` + (err instanceof Error ? err.message : String(err))
+          );
+        });
       }
       span?.setAttribute("axl.workflow.cost", execInfo.totalCost);
       span?.setAttribute("axl.workflow.duration", execInfo.duration);
@@ -22129,7 +22219,10 @@ var AxlRuntime = class extends EventEmitter2 {
       const chain = this.stateStore.saveExecution(snapshot).then(() => {
         return this.streamingFlusher?.finalize(id).catch(() => {
         });
-      }).catch(() => {
+      }).catch((err) => {
+        console.error(
+          `[axl] Failed to save execution history for executionId=${id}: ` + (err instanceof Error ? err.message : String(err))
+        );
       }).then(() => void 0);
       this.persistInflight.add(chain);
       const pending = { snapshot, settled: chain };
@@ -24521,6 +24614,7 @@ async function* stringStreamFromEvents(source, opts) {
 }
 
 // src/state/redis.ts
+import { createHash as createHash2 } from "crypto";
 var PRUNE_HISTORY_INDEX_SCRIPT = `
 local now = tonumber(ARGV[1])
 local removed = 0
@@ -24540,6 +24634,34 @@ for i = 2, #ARGV do
 end
 return removed
 `;
+var PRUNE_SESSION_IDS_SCRIPT = `
+local removed = {}
+for i, id in ipairs(ARGV) do
+  if redis.call('EXISTS', KEYS[i * 2]) == 0 then
+    redis.call('SREM', KEYS[1], id)
+    redis.call('DEL', KEYS[i * 2 + 1])
+    removed[#removed + 1] = id
+  end
+end
+return removed
+`;
+var SESSION_ID_BATCH = 100;
+var SESSION_SWEEP_COUNT = 50;
+var UPDATE_SESSION_SCRIPT = `
+local stored = redis.call('GET', KEYS[1])
+local actual = stored and redis.sha1hex(stored) or ''
+if actual ~= ARGV[1] then
+  return 0
+end
+if ARGV[3] ~= '' then
+  redis.call('SET', KEYS[1], ARGV[2], 'EX', ARGV[3])
+else
+  redis.call('SET', KEYS[1], ARGV[2])
+end
+redis.call('SADD', KEYS[2], ARGV[4])
+return 1
+`;
+var UPDATE_SESSION_ATTEMPTS = 10;
 function compareMembers(a, b) {
   return Buffer.compare(Buffer.from(a, "utf8"), Buffer.from(b, "utf8"));
 }
@@ -24552,12 +24674,222 @@ function warnIfRedisExecutionRetentionUnset(opts) {
     warnExecutionRetentionUnset("RedisStore");
   }
 }
+var CLOSE_TIMEOUT_MS = 2e3;
+function reconnectDelayMs(retries) {
+  return Math.min(2 ** retries * 50, 2e3) + Math.floor(Math.random() * 200);
+}
+function abandonConnection(client) {
+  try {
+    client.destroy?.();
+  } catch {
+  }
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function connectionEventReporter(client, onConnectionEvent) {
+  if (onConnectionEvent) {
+    const reportFailure = (error) => console.error(`[axl] RedisStore: onConnectionEvent failed: ${errorMessage(error)}`);
+    return (event) => {
+      try {
+        Promise.resolve(onConnectionEvent(event)).catch(reportFailure);
+      } catch (error) {
+        reportFailure(error);
+      }
+    };
+  }
+  let outageLogged = false;
+  return (event) => {
+    if (event.type === "reconnected") {
+      outageLogged = false;
+      console.warn("[axl] RedisStore: reconnected to Redis.");
+    } else if (!outageLogged) {
+      outageLogged = client.isReady === false;
+      console.warn(
+        `[axl] RedisStore: Redis connection lost (${event.error.message}). Store calls fail until it reconnects, which happens automatically.`
+      );
+    }
+  };
+}
+var LOOP_STALL_TOLERANCE_MS = 100;
+var LOOP_STALL_GRACE_MS = 1e3;
+function watchResponses(client, timeoutMs, reportConnectionEvent) {
+  const checkEveryMs = timeoutMs / 3;
+  let timer;
+  let stopped = false;
+  const schedule = (run, delayMs) => {
+    timer = setTimeout(run, delayMs);
+    timer.unref?.();
+  };
+  const check = () => {
+    if (client.isReady === false) {
+      schedule(check, checkEveryMs);
+      return;
+    }
+    let settled = false;
+    const onReply = () => {
+      if (settled || stopped) return;
+      settled = true;
+      clearTimeout(timer);
+      schedule(check, checkEveryMs);
+    };
+    const expireAfter = (delayMs, mayWaitForBlockedLoop) => {
+      const dueAt = Date.now() + delayMs;
+      schedule(() => {
+        if (settled || stopped) return;
+        if (mayWaitForBlockedLoop && Date.now() - dueAt > LOOP_STALL_TOLERANCE_MS) {
+          expireAfter(LOOP_STALL_GRACE_MS, false);
+          return;
+        }
+        reset();
+      }, delayMs);
+    };
+    const reset = () => {
+      settled = true;
+      if (client.isReady === false) {
+        schedule(check, checkEveryMs);
+        return;
+      }
+      client.destroy?.();
+      client.connect().catch(() => {
+      });
+      reportConnectionEvent({
+        type: "error",
+        error: new Error(`Redis did not answer within ${timeoutMs}ms; reconnecting.`)
+      });
+      schedule(check, checkEveryMs);
+    };
+    client.ping().then(onReply, onReply);
+    expireAfter(timeoutMs, true);
+  };
+  schedule(check, checkEveryMs);
+  return () => {
+    stopped = true;
+    clearTimeout(timer);
+  };
+}
+async function connectWithin(connecting, timeoutMs) {
+  let timer;
+  try {
+    await Promise.race([
+      connecting,
+      new Promise((_resolve, reject) => {
+        timer = setTimeout(
+          () => reject(
+            new AxlError(
+              "REDIS_UNAVAILABLE",
+              `RedisStore: Redis did not finish connecting within ${timeoutMs}ms.`
+            )
+          ),
+          timeoutMs
+        );
+      })
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function connectClient(createClient, opts) {
+  const inBackground = opts.waitForConnection === false;
+  let established = inBackground;
+  let everFailed = false;
+  const responseTimeoutMs = opts.responseTimeoutMs;
+  const client = createClient({
+    ...opts.url ? { url: opts.url } : {},
+    // A command accepted just before a drop rejects instead of waiting for
+    // the reconnect.
+    disableOfflineQueue: true,
+    socket: {
+      reconnectStrategy: (retries) => established ? reconnectDelayMs(retries) : false,
+      // Bounds a reconnect's handshake, where the response watch doesn't run.
+      // Twice the timeout so that on an open connection the watch acts first:
+      // this timer fires after any long event-loop block, which the watch allows for.
+      ...responseTimeoutMs !== void 0 ? { socketTimeout: responseTimeoutMs * 2 } : {}
+    }
+  });
+  const reportConnectionEvent = connectionEventReporter(client, opts.onConnectionEvent);
+  client.on("error", (error) => {
+    if (!established || client.isOpen === false) return;
+    everFailed = true;
+    reportConnectionEvent({
+      type: "error",
+      error: error instanceof Error ? error : new Error(String(error))
+    });
+  });
+  client.on("connect", () => {
+    if (client.isOpen === false) client.unref?.();
+  });
+  client.on("ready", () => {
+    if (!established) {
+      established = true;
+    } else if (client.isOpen !== false && (!inBackground || everFailed)) {
+      reportConnectionEvent({ type: "reconnected" });
+    }
+  });
+  if (inBackground) {
+    client.connect().catch(() => {
+    });
+    return {
+      client,
+      stopResponseWatch: watchResponses(client, responseTimeoutMs, reportConnectionEvent)
+    };
+  }
+  if (responseTimeoutMs === void 0) {
+    await client.connect();
+    return { client };
+  }
+  try {
+    await connectWithin(client.connect(), responseTimeoutMs);
+  } catch (error) {
+    abandonConnection(client);
+    throw error;
+  }
+  return {
+    client,
+    stopResponseWatch: watchResponses(client, responseTimeoutMs, reportConnectionEvent)
+  };
+}
 var RedisStore = class _RedisStore {
-  constructor(client, keyPrefix, ttls) {
-    this.client = client;
+  constructor(connection, keyPrefix, ttls) {
+    this.connection = connection;
     this.keyPrefix = keyPrefix;
     this.ttls = ttls;
   }
+  /** Set when `close()` starts, while the connection is still open. */
+  closing = false;
+  /** Where the next save's check of listed sessions picks up. */
+  sessionSweepCursor = "0";
+  /** Overlapping saves would all check the same page, so only one checks at a time. */
+  sessionSweepRunning = false;
+  /**
+   * Whether the store can send commands right now, for a health check or for
+   * telling an outage from other failures when a call rejects. `false` while
+   * reconnecting and after `close()`.
+   */
+  get isConnected() {
+    return !this.closing && this.connection.isOpen !== false && this.connection.isReady !== false;
+  }
+  /**
+   * The client for sending a command, failing immediately while disconnected.
+   *
+   * Every command goes through here because node-redis's `disableOfflineQueue`
+   * rejects single commands but not `multi().exec()`, which would wait for a
+   * reconnect attempt to fail or succeed. Nothing may `await` between
+   * `client.multi()` and `.exec()`, or a transaction could get past this check.
+   *
+   * A closed store isn't "unavailable": it falls through to node-redis's own
+   * "The client is closed" rejection.
+   */
+  get client() {
+    if (this.closing) throw new Error("The client is closed");
+    if (this.connection.isOpen !== false && this.connection.isReady === false) {
+      throw new AxlError(
+        "REDIS_UNAVAILABLE",
+        "RedisStore: not connected to Redis, so the command was not sent. The store reconnects automatically; retry once Redis is back."
+      );
+    }
+    return this.connection;
+  }
   /**
    * History kinds with a prune running in this process. A save skips its
    * prune while another one of the same kind is in flight: the running one
@@ -24565,6 +24897,8 @@ var RedisStore = class _RedisStore {
    * instance needs no constructor state.
    */
   prunesInFlight;
+  /** Stops the `responseTimeoutMs` health checks; unset when the option is off. */
+  stopResponseWatch;
   /**
    * Supports `listExecutions(limit, { cursor })`. A getter rather than a
    * field so it lives on the prototype.
@@ -24614,6 +24948,17 @@ var RedisStore = class _RedisStore {
         'RedisStore: keyPrefix cannot be empty string. Omit it for the default "axl:" prefix.'
       );
     }
+    const responseTimeoutMs = opts.responseTimeoutMs;
+    if (responseTimeoutMs !== void 0 && !(Number.isFinite(responseTimeoutMs) && responseTimeoutMs > 0)) {
+      throw new Error(
+        `RedisStore: responseTimeoutMs must be a positive number of milliseconds, got ${responseTimeoutMs}.`
+      );
+    }
+    if (opts.waitForConnection === false && responseTimeoutMs === void 0) {
+      throw new Error(
+        "RedisStore: waitForConnection: false requires responseTimeoutMs, so a server that accepts the connection but never answers cannot leave it connecting forever."
+      );
+    }
     let createClient;
     try {
       const mod = __require("redis");
@@ -24627,8 +24972,7 @@ var RedisStore = class _RedisStore {
       if (err instanceof Error && err.message.includes("createClient")) throw err;
       throw new Error("redis is required for RedisStore. Install it with: npm install redis");
     }
-    const client = opts.url ? createClient({ url: opts.url }) : createClient();
-    await client.connect();
+    const { client, stopResponseWatch } = await connectClient(createClient, opts);
     const resolveCategory = (override) => {
       if (override === null) return null;
       if (typeof override === "number") return override;
@@ -24650,13 +24994,48 @@ var RedisStore = class _RedisStore {
       streamingEvents: resolveStreamingEvents(opts.ttls?.streamingEvents)
     };
     const store = new _RedisStore(client, keyPrefix, effectiveTtls);
+    store.stopResponseWatch = stopResponseWatch;
     warnIfRedisExecutionRetentionUnset(opts);
+    if (opts.waitForConnection === false) {
+      if (!opts.skipMigration) store.backfillOnceConnected(client);
+      return store;
+    }
     if (!opts.skipMigration) {
-      await store.backfillExecutionIndex();
-      await store.backfillEvalIndex();
+      try {
+        await store.backfillExecutionIndex();
+        await store.backfillEvalIndex();
+      } catch (error) {
+        stopResponseWatch?.();
+        abandonConnection(client);
+        throw error;
+      }
     }
     return store;
   }
+  /**
+   * Run the startup backfill when a connection becomes ready, until it succeeds.
+   * Nothing is waiting on it, and listings work without it, so a failure is
+   * reported and the next connection tries again.
+   */
+  backfillOnceConnected(client) {
+    let state = "waiting";
+    client.on("ready", () => {
+      if (state !== "waiting") return;
+      state = "running";
+      this.backfillExecutionIndex().then(() => this.backfillEvalIndex()).then(
+        () => {
+          state = "done";
+        },
+        (err) => {
+          state = "waiting";
+          if (client.isReady === false || client.isOpen === false) return;
+          console.warn(
+            `[axl] RedisStore: the startup index backfill failed (${errorMessage(err)}). Listings stay correct meanwhile.`
+          );
+        }
+      );
+    });
+  }
   /**
    * Backfill the execution-history sorted-set from the legacy ID set.
    * Idempotent — runs only if the ZSET is missing entries the SET has.
@@ -24664,36 +25043,30 @@ var RedisStore = class _RedisStore {
    * `skipMigration: true`.
    */
   async backfillExecutionIndex() {
-    await this.backfillHistoryIndex(
-      this.execHistorySetKey(),
-      this.execHistoryZsetKey(),
-      (id) => this.execHistoryKey(id),
-      (raw) => {
-        const exec = JSON.parse(raw);
-        return typeof exec.startedAt === "number" ? { score: exec.startedAt, value: exec.executionId } : null;
-      },
-      "execution-history"
-    );
+    await this.backfillHistoryIndex(this.historyIndex("execution"), (raw) => {
+      const exec = JSON.parse(raw);
+      return typeof exec.startedAt === "number" ? { score: exec.startedAt, value: exec.executionId } : null;
+    });
   }
   /** Backfill the eval-history sorted-set. Symmetric to `backfillExecutionIndex`. */
   async backfillEvalIndex() {
-    await this.backfillHistoryIndex(
-      this.evalHistorySetKey(),
-      this.evalHistoryZsetKey(),
-      (id) => this.evalHistoryKey(id),
-      (raw) => {
-        const entry = JSON.parse(raw);
-        return typeof entry.timestamp === "number" ? { score: entry.timestamp, value: entry.id } : null;
-      },
-      "eval-history"
-    );
+    await this.backfillHistoryIndex(this.historyIndex("eval"), (raw) => {
+      const entry = JSON.parse(raw);
+      return typeof entry.timestamp === "number" ? { score: entry.timestamp, value: entry.id } : null;
+    });
   }
   /**
    * Shared implementation for both backfill paths. Reads SET members,
    * batch-MGETs their data blobs in chunks, and ZADDs each into the new
    * sorted-set inside a single MULTI per chunk.
+   *
+   * Ids with no data blob are removed from the id set. Left there, the set stays
+   * larger than the sorted set, so every startup repeats this walk and listing
+   * stays on its slow path.
    */
-  async backfillHistoryIndex(setKey, zsetKey, dataKey, scoreOf, label) {
+  async backfillHistoryIndex(index, scoreOf) {
+    const setKey = index.ids;
+    const zsetKey = index.time;
     const [setSize, zsetSize] = await Promise.all([
       this.client.sCard(setKey),
       this.client.zCard(zsetKey)
@@ -24704,9 +25077,10 @@ var RedisStore = class _RedisStore {
     const CHUNK_SIZE = 500;
     let migrated = 0;
     let skipped = 0;
+    const missing = [];
     for (let i = 0; i < allIds.length; i += CHUNK_SIZE) {
       const chunk = allIds.slice(i, i + CHUNK_SIZE);
-      const dataKeys = chunk.map((id) => dataKey(id));
+      const dataKeys = chunk.map((id) => index.dataKey(id));
       const raws = await this.client.mGet(dataKeys);
       const tx = this.client.multi();
       let queuedInChunk = 0;
@@ -24714,6 +25088,7 @@ var RedisStore = class _RedisStore {
         const raw = raws[j];
         if (raw == null) {
           skipped++;
+          missing.push(chunk[j]);
           continue;
         }
         try {
@@ -24731,9 +25106,14 @@ var RedisStore = class _RedisStore {
       }
       if (queuedInChunk > 0) await tx.exec();
     }
+    if (missing.length > 0) {
+      await this.runPruneScript(index, missing).catch(
+        (err) => this.warnPruneFailed(index, err)
+      );
+    }
     if (migrated > 0 || skipped > 0) {
       console.log(
-        `[axl] RedisStore: backfilled ${migrated} ${label} entries into sorted-set index` + (skipped > 0 ? ` (${skipped} skipped \u2014 missing or malformed)` : "")
+        `[axl] RedisStore: backfilled ${migrated} ${index.label} entries into sorted-set index` + (skipped > 0 ? ` (${skipped} skipped \u2014 missing or malformed)` : "")
       );
     }
   }
@@ -24859,6 +25239,51 @@ var RedisStore = class _RedisStore {
       JSON.stringify(normalizePersistedSessionHistory(history)),
       setOptions
     ).sAdd(this.sessionIdsKey(), sessionId).exec();
+    await this.sweepSessionIds();
+  }
+  async updateSession(sessionId, update) {
+    if (this.saveSession !== _RedisStore.prototype.saveSession || this.getSession !== _RedisStore.prototype.getSession) {
+      return updateSessionThroughOverrides(this, "RedisStore", sessionId, update);
+    }
+    const key = this.sessionKey(sessionId);
+    const ttl = this.ttlFor("session");
+    for (let attempt = 0; attempt < UPDATE_SESSION_ATTEMPTS; attempt++) {
+      const raw = await this.client.get(key);
+      const next = update(raw ? JSON.parse(raw) : null);
+      if (next === null) return;
+      let written;
+      try {
+        written = await this.client.eval(UPDATE_SESSION_SCRIPT, {
+          keys: [key, this.sessionIdsKey()],
+          arguments: [
+            raw === null ? "" : createHash2("sha1").update(raw).digest("hex"),
+            JSON.stringify(normalizePersistedSessionHistory(next)),
+            ttl === void 0 ? "" : String(ttl),
+            sessionId
+          ]
+        });
+      } catch (err) {
+        if (!errorMessage(err).includes("NOPERM")) throw err;
+        warnDiagnosticOnce(
+          "redis_update_session_denied",
+          "RedisStore: saving a session turn safely runs a Lua script, which this Redis user may not run, so it was saved without that protection. Overlapping turns from different instances can overwrite each other until the user may run EVAL.",
+          void 0,
+          "docs/api-reference.md#concurrency-and-races"
+        );
+        await this.saveSession(sessionId, next);
+        return;
+      }
+      if (Number(written) === 1) {
+        await this.sweepSessionIds();
+        return;
+      }
+      const backoffMs = Math.min(20 * 2 ** attempt, 200);
+      await new Promise((resolve2) => setTimeout(resolve2, Math.random() * backoffMs));
+    }
+    throw new AxlError(
+      "SESSION_CONFLICT",
+      `RedisStore: gave up saving session "${sessionId}" after ${UPDATE_SESSION_ATTEMPTS} conflicting writes from other instances.`
+    );
   }
   async getSession(sessionId) {
     const raw = await this.client.get(this.sessionKey(sessionId));
@@ -24922,7 +25347,7 @@ var RedisStore = class _RedisStore {
       }
     }
     if (dead.length > 0) {
-      this.client.sRem(this.pendingExecSetKey(), dead).catch((err) => {
+      this.connection.sRem(this.pendingExecSetKey(), dead).catch((err) => {
         console.error(
           `[axl] RedisStore: failed to prune ${dead.length} stale pending-exec ids: ` + (err instanceof Error ? err.message : String(err))
         );
@@ -24968,7 +25393,7 @@ var RedisStore = class _RedisStore {
     }
     const ttl = this.ttlFor("memory");
     if (ttl !== void 0) {
-      this.client.expire(this.memoryKey(scope), ttl).catch((err) => {
+      this.connection.expire(this.memoryKey(scope), ttl).catch((err) => {
         console.error(
           `[axl] RedisStore: failed to set TTL on migrated memory key ${this.memoryKey(scope)}: ` + (err instanceof Error ? err.message : String(err))
         );
@@ -25260,16 +25685,20 @@ var RedisStore = class _RedisStore {
     try {
       await this.pruneHistory(index);
     } catch (err) {
-      warnDiagnosticOnce(
-        `redis_history_prune_failed\0${index.kind}`,
-        `RedisStore: removing expired ${index.label} index entries failed (${err instanceof Error ? err.message : String(err)}). The record was saved; the next save retries the cleanup. Listings stay correct meanwhile. The cleanup runs a Lua script, so the Redis user needs permission to run EVAL.`,
-        void 0,
-        "docs/api-reference.md#redisstore-options"
-      );
+      this.warnPruneFailed(index, err);
     } finally {
       inFlight.delete(index.kind);
     }
   }
+  warnPruneFailed(index, err) {
+    if (!this.isConnected) return;
+    warnDiagnosticOnce(
+      `redis_history_prune_failed\0${index.kind}`,
+      `RedisStore: removing expired ${index.label} index entries failed (${err instanceof Error ? err.message : String(err)}). The cleanup is tried again later, and listings stay correct meanwhile. The cleanup runs a Lua script, so the Redis user needs permission to run EVAL.`,
+      void 0,
+      "docs/api-reference.md#redisstore-options"
+    );
+  }
   async pruneHistory(index) {
     const candidates = await this.client.zRange(index.expiry, "-inf", Date.now(), {
       BY: "SCORE",
@@ -25424,7 +25853,69 @@ var RedisStore = class _RedisStore {
   }
   // ── Sessions (Studio introspection) ────────────────────────────────────
   async listSessions() {
-    return this.client.sMembers(this.sessionIdsKey());
+    const live = /* @__PURE__ */ new Set();
+    let cursor = "0";
+    do {
+      const page = await this.client.sScan(this.sessionIdsKey(), cursor, {
+        COUNT: SESSION_ID_BATCH
+      });
+      cursor = page.cursor;
+      const removed = new Set(await this.pruneSessionIds(page.members));
+      for (const id of page.members) if (!removed.has(id)) live.add(id);
+    } while (cursor !== "0");
+    return [...live];
+  }
+  /**
+   * Check a few listed sessions after a save, so ids of expired sessions go
+   * away for apps that never list. Sessions without a TTL don't expire, so
+   * there's nothing to do. The save has already succeeded, so failing here
+   * can't fail it.
+   */
+  async sweepSessionIds() {
+    if (this.ttlFor("session") === void 0 || this.sessionSweepRunning) return;
+    this.sessionSweepRunning = true;
+    try {
+      const page = await this.client.sScan(this.sessionIdsKey(), this.sessionSweepCursor, {
+        COUNT: SESSION_SWEEP_COUNT
+      });
+      this.sessionSweepCursor = page.cursor;
+      await this.pruneSessionIds(page.members);
+    } catch (err) {
+      this.warnSessionPruneFailed(err);
+    } finally {
+      this.sessionSweepRunning = false;
+    }
+  }
+  /** Returns the ids removed. Without permission to run the script, removes none and warns. */
+  async pruneSessionIds(ids) {
+    const removed = [];
+    for (let start = 0; start < ids.length; start += SESSION_ID_BATCH) {
+      const batch = ids.slice(start, start + SESSION_ID_BATCH);
+      try {
+        const result = await this.client.eval(PRUNE_SESSION_IDS_SCRIPT, {
+          keys: [
+            this.sessionIdsKey(),
+            ...batch.flatMap((id) => [this.sessionKey(id), this.sessionMetaKey(id)])
+          ],
+          arguments: batch
+        });
+        removed.push(...result);
+      } catch (err) {
+        if (!errorMessage(err).includes("NOPERM")) throw err;
+        this.warnSessionPruneFailed(err);
+        return removed;
+      }
+    }
+    return removed;
+  }
+  warnSessionPruneFailed(err) {
+    if (!this.isConnected) return;
+    warnDiagnosticOnce(
+      "redis_session_ids_prune_failed",
+      `RedisStore: removing expired session ids failed (${errorMessage(err)}), so listSessions can return sessions that have expired. The cleanup runs a Lua script, so the Redis user needs permission to run EVAL.`,
+      void 0,
+      "docs/api-reference.md#redisstore-options"
+    );
   }
   // ── Streaming events (for state.persist: 'streaming') ──────────────────
   async appendStreamingEvents(executionId, events) {
@@ -25464,10 +25955,34 @@ var RedisStore = class _RedisStore {
    * must not get a rejected promise for it. `MemoryStore.close()` and
    * better-sqlite3's `close()` are both no-ops the second time; node-redis
    * instead rejects with "The client is closed", so absorb that here.
+   *
+   * Bounded, so a shutdown can't hang on Redis. Replies arrive in order, so a
+   * reply to this PING means every earlier command has finished.
+   *
+   * Not `quit()`: it marks the client closed before the server answers, and
+   * `destroy()` then throws without touching the socket, so a stalled server's
+   * socket could never be closed. There's no other public way to close it. A
+   * closed socket is all Redis needs to clean up, so nothing is lost.
    */
   async close() {
-    if (this.client.isOpen === false) return;
-    await this.client.quit();
+    this.closing = true;
+    this.stopResponseWatch?.();
+    if (this.connection.isOpen === false) return;
+    if (this.connection.isReady !== false) {
+      let timer;
+      try {
+        await Promise.race([
+          this.connection.ping(),
+          new Promise((_resolve, reject) => {
+            timer = setTimeout(() => reject(new Error("PING timed out")), CLOSE_TIMEOUT_MS);
+          })
+        ]);
+      } catch {
+      } finally {
+        clearTimeout(timer);
+      }
+    }
+    abandonConnection(this.connection);
   }
   async deleteCheckpoints(executionId) {
     await this.client.del(this.checkpointKey(executionId));