@axlsdk/axl 0.17.6 → 0.17.7

package/dist/index.js

@@ -5914,8 +5914,31 @@ ${summaryResponse.content}`
       type: "await_human",
       data: { channel: options.channel, prompt: options.prompt }
     });
-    const decision = await new Promise((resolve2) => {
+    const makeAbortError = (reason) => {
+      if (typeof DOMException !== "undefined") {
+        return new DOMException(
+          typeof reason === "string" ? reason : "awaitHuman aborted",
+          "AbortError"
+        );
+      }
+      const err = new Error(typeof reason === "string" ? reason : "awaitHuman aborted");
+      err.name = "AbortError";
+      return err;
+    };
+    const decision = await new Promise((resolve2, reject) => {
+      if (this.signal?.aborted) {
+        reject(makeAbortError(this.signal.reason));
+        return;
+      }
       this.pendingDecisions.set(this.executionId, resolve2);
+      const onAbort = () => {
+        const current = this.pendingDecisions.get(this.executionId);
+        if (current === resolve2) {
+          this.pendingDecisions.delete(this.executionId);
+        }
+        reject(makeAbortError(this.signal?.reason));
+      };
+      this.signal?.addEventListener("abort", onAbort, { once: true });
     });
     this.emitEvent({
       type: "await_human_resolved",
@@ -6540,6 +6563,16 @@ var MemoryStore = class {
     const result = limit ? sorted.slice(0, limit) : sorted;
     return result.map((e) => structuredClone(e));
   }
+  async deleteExecution(executionId) {
+    const removed = this.executionHistory.delete(executionId);
+    this.checkpoints.delete(executionId);
+    this.executionStates.delete(executionId);
+    this.streamingEvents.delete(executionId);
+    if (this.decisions.delete(executionId)) {
+      this.persistAwaitHumanState();
+    }
+    return removed;
+  }
   // ── Eval History ──────────────────────────────────────────────────
   async saveEvalResult(entry) {
     this.evalHistory.set(entry.id, structuredClone(entry));
@@ -6556,6 +6589,30 @@ var MemoryStore = class {
   async listSessions() {
     return [...this.sessions.keys()];
   }
+  // ── Streaming events (for state.persist: 'streaming') ────────────────
+  //
+  // MemoryStore's raison d'être is in-process / ephemeral. We implement
+  // the streaming methods so tests and dev workflows behave correctly,
+  // but on a process crash these buffers are lost — same as the rest of
+  // MemoryStore's state. For real crash-survival, use RedisStore or
+  // SQLiteStore.
+  streamingEvents = /* @__PURE__ */ new Map();
+  async appendStreamingEvents(executionId, events) {
+    if (events.length === 0) return;
+    const existing = this.streamingEvents.get(executionId) ?? [];
+    existing.push(...events.map((e) => structuredClone(e)));
+    this.streamingEvents.set(executionId, existing);
+  }
+  async finalizeStreamingEvents(executionId) {
+    this.streamingEvents.delete(executionId);
+  }
+  async listStreamingExecutions() {
+    return [...this.streamingEvents.keys()];
+  }
+  async getStreamingEvents(executionId) {
+    const events = this.streamingEvents.get(executionId) ?? [];
+    return events.map((e) => structuredClone(e));
+  }
   // ── Lifecycle ──────────────────────────────────────────────────────
   async close() {
   }
@@ -6612,7 +6669,7 @@ function safeJsonParse(data) {
   }
 }
 function rowToExecutionInfo(row) {
-  return {
+  const info = {
     executionId: row.execution_id,
     workflow: row.workflow,
     status: row.status,
@@ -6623,6 +6680,13 @@ function rowToExecutionInfo(row) {
     error: row.error ?? void 0,
     events: safeJsonParse(row.events) ?? []
   };
+  if (row.metadata != null) {
+    const parsed = safeJsonParse(row.metadata);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      info.metadata = parsed;
+    }
+  }
+  return info;
 }
 var SQLiteStore = class {
   db;
@@ -6658,6 +6722,10 @@ var SQLiteStore = class {
    *   numeric step values become stringified names ("0", "1", …) to
    *   preserve replay continuity for in-flight executions across the
    *   upgrade boundary.
+   * - v3 (ExecutionInfo.metadata): add `execution_history.metadata`
+   *   column (TEXT, nullable, JSON-serialized) so caller-supplied
+   *   `ExecuteOptions.metadata` round-trips through history. Existing
+   *   rows get `NULL`, deserialized as `metadata: undefined`.
    *
    * Applied BEFORE `initTables()` so the subsequent `CREATE TABLE
    * IF NOT EXISTS` runs against the post-migration column name. Fresh
@@ -6675,7 +6743,7 @@ var SQLiteStore = class {
    * transactional re-read costs nothing.
    */
   migrate() {
-    const TARGET_VERSION = 2;
+    const TARGET_VERSION = 3;
     const current = this.db.pragma("user_version", { simple: true });
     if (current >= TARGET_VERSION) return;
     this.db.exec("BEGIN IMMEDIATE");
@@ -6697,6 +6765,12 @@ var SQLiteStore = class {
           this.db.exec("ALTER TABLE checkpoints RENAME COLUMN step TO name");
         }
       }
+      if (committed < 3) {
+        const cols = this.db.pragma("table_info(execution_history)");
+        if (cols.length > 0 && !cols.some((c) => c.name === "metadata")) {
+          this.db.exec("ALTER TABLE execution_history ADD COLUMN metadata TEXT");
+        }
+      }
       this.db.pragma(`user_version = ${TARGET_VERSION}`);
       this.db.exec("COMMIT");
     } catch (err) {
@@ -6759,7 +6833,8 @@ var SQLiteStore = class {
         completed_at INTEGER,
         duration INTEGER NOT NULL DEFAULT 0,
         error TEXT,
-        events TEXT NOT NULL
+        events TEXT NOT NULL,
+        metadata TEXT
       );
 
       CREATE TABLE IF NOT EXISTS eval_history (
@@ -6880,7 +6955,7 @@ var SQLiteStore = class {
   // ── Execution History ────────────────────────────────────────────────────
   async saveExecution(execution) {
     this.db.prepare(
-      "INSERT OR REPLACE INTO execution_history (execution_id, workflow, status, total_cost, started_at, completed_at, duration, error, events) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)"
+      "INSERT OR REPLACE INTO execution_history (execution_id, workflow, status, total_cost, started_at, completed_at, duration, error, events, metadata) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)"
     ).run(
       execution.executionId,
       execution.workflow,
@@ -6890,7 +6965,8 @@ var SQLiteStore = class {
       execution.completedAt ?? null,
       execution.duration,
       execution.error ?? null,
-      JSON.stringify(execution.events)
+      JSON.stringify(execution.events),
+      execution.metadata !== void 0 ? JSON.stringify(execution.metadata) : null
     );
   }
   async getExecution(executionId) {
@@ -6902,6 +6978,16 @@ var SQLiteStore = class {
     const rows = limit ? this.db.prepare(sql).all(limit) : this.db.prepare(sql).all();
     return rows.map(rowToExecutionInfo);
   }
+  async deleteExecution(executionId) {
+    const tx = this.db.transaction(() => {
+      const result = this.db.prepare("DELETE FROM execution_history WHERE execution_id = ?").run(executionId);
+      this.db.prepare("DELETE FROM checkpoints WHERE execution_id = ?").run(executionId);
+      this.db.prepare("DELETE FROM execution_state WHERE execution_id = ?").run(executionId);
+      this.db.prepare("DELETE FROM decisions WHERE execution_id = ?").run(executionId);
+      return result.changes > 0;
+    });
+    return tx();
+  }
   // ── Eval History ────────────────────────────────────────────────────────
   async saveEvalResult(entry) {
     this.db.prepare(
@@ -7780,6 +7866,7 @@ var MemoryManager = class {
     if (stateStore.saveMemory) {
       await stateStore.saveMemory(storeScope, key, value);
     } else {
+      warnMissingMemoryMethodsOnce(stateStore);
       const storeKey = `memory:${storeScope}:${key}`;
       await stateStore.saveSessionMeta(storeKey, "value", value);
       if (options?.metadata) {
@@ -7882,6 +7969,14 @@ var MemoryManager = class {
     }
   }
 };
+var _warnedStoresMissingMemory = /* @__PURE__ */ new WeakSet();
+function warnMissingMemoryMethodsOnce(stateStore) {
+  if (_warnedStoresMissingMemory.has(stateStore)) return;
+  _warnedStoresMissingMemory.add(stateStore);
+  console.warn(
+    "[axl] ctx.remember() against a StateStore without saveMemory/getMemory/getAllMemory/deleteMemory \u2014 falling back to a sessionMeta-based path that drops metadata and is not enumerable. Implement the four optional memory methods on your StateStore for full fidelity. This warning fires once per offending store."
+  );
+}
 
 // src/telemetry/noop.ts
 var NOOP_SPAN = {
@@ -7923,11 +8018,141 @@ function hashInput(input) {
   return (hash >>> 0).toString(16);
 }
 var DEFAULT_MAX_EVENTS_PER_EXECUTION = 5e4;
+var DEFAULT_STREAMING_BATCH_SIZE = 100;
+var DEFAULT_STREAMING_BATCH_INTERVAL = 1e3;
+var RECOVERED_UNKNOWN_WORKFLOW = "__axl/recovered";
+var STREAMING_EXCLUDED_TYPES = /* @__PURE__ */ new Set([
+  "token",
+  "partial_object",
+  "string_delta"
+]);
+var INTERNAL_METADATA_KEYS = /* @__PURE__ */ new Set([
+  "sessionId",
+  "sessionHistory",
+  "resumeMode"
+]);
+function liftPersistedMetadata(metadata) {
+  if (!metadata) return void 0;
+  const filtered = {};
+  let hasAny = false;
+  for (const [k, v] of Object.entries(metadata)) {
+    if (INTERNAL_METADATA_KEYS.has(k)) continue;
+    filtered[k] = v;
+    hasAny = true;
+  }
+  if (!hasAny) return void 0;
+  try {
+    return structuredClone(filtered);
+  } catch {
+    return { ...filtered };
+  }
+}
+var StreamingFlusher = class {
+  constructor(store, batchSize, batchInterval) {
+    this.store = store;
+    this.batchSize = batchSize;
+    this.batchInterval = batchInterval;
+  }
+  buffers = /* @__PURE__ */ new Map();
+  timers = /* @__PURE__ */ new Map();
+  /**
+   * Tracks the most recent in-flight `appendStreamingEvents` per execution
+   * so `finalize` can await it. Without this, a size-triggered fire-and-
+   * forget flush whose RPUSH lands AFTER `finalize`'s DEL would resurrect
+   * the buffer + re-register the execution in the streaming-exec-ids set
+   * — a phantom orphan that recoverIncompleteStreams would later mis-recover.
+   */
+  inflight = /* @__PURE__ */ new Map();
+  append(executionId, event) {
+    if (STREAMING_EXCLUDED_TYPES.has(event.type)) return;
+    let buffer = this.buffers.get(executionId);
+    if (!buffer) {
+      buffer = [];
+      this.buffers.set(executionId, buffer);
+    }
+    buffer.push(event);
+    if (buffer.length >= this.batchSize) {
+      void this.flush(executionId);
+      return;
+    }
+    if (!this.timers.has(executionId)) {
+      const timer = setTimeout(() => {
+        this.timers.delete(executionId);
+        void this.flush(executionId);
+      }, this.batchInterval);
+      if (typeof timer === "object" && timer !== null && "unref" in timer) {
+        timer.unref?.();
+      }
+      this.timers.set(executionId, timer);
+    }
+  }
+  /** Flush this execution's buffer immediately. Awaits any prior in-flight
+   *  flush for the same execution so writes land in order. */
+  async flush(executionId) {
+    const buffer = this.buffers.get(executionId);
+    if (!buffer || buffer.length === 0) return;
+    this.buffers.set(executionId, []);
+    const timer = this.timers.get(executionId);
+    if (timer) {
+      clearTimeout(timer);
+      this.timers.delete(executionId);
+    }
+    const prior = this.inflight.get(executionId) ?? Promise.resolve();
+    const next = prior.then(async () => {
+      try {
+        await this.store.appendStreamingEvents?.(executionId, buffer);
+      } catch (err) {
+        console.error(
+          `[axl] StreamingFlusher: failed to append ${buffer.length} events for executionId=${executionId}: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    });
+    this.inflight.set(executionId, next);
+    next.finally(() => {
+      if (this.inflight.get(executionId) === next) {
+        this.inflight.delete(executionId);
+      }
+    });
+    return next;
+  }
+  /** Finalize an execution — flush remaining buffer + release store-side buffer.
+   *  Critically, awaits the most recent in-flight `appendStreamingEvents` BEFORE
+   *  calling `finalizeStreamingEvents`, so a late-landing RPUSH can't resurrect
+   *  the buffer after we've deleted it. */
+  async finalize(executionId) {
+    await this.flush(executionId);
+    const pending = this.inflight.get(executionId);
+    if (pending) {
+      await pending;
+      this.inflight.delete(executionId);
+    }
+    this.buffers.delete(executionId);
+    const timer = this.timers.get(executionId);
+    if (timer) {
+      clearTimeout(timer);
+      this.timers.delete(executionId);
+    }
+    try {
+      await this.store.finalizeStreamingEvents?.(executionId);
+    } catch (err) {
+      console.error(
+        `[axl] StreamingFlusher: failed to finalize executionId=${executionId}: ` + (err instanceof Error ? err.message : String(err))
+      );
+    }
+  }
+  /** Best-effort drain of every pending buffer. Called from `runtime.shutdown()`. */
+  async flushAll() {
+    const ids = [...this.buffers.keys()];
+    await Promise.all(ids.map((id) => this.flush(id)));
+    const pendings = [...this.inflight.values()];
+    await Promise.allSettled(pendings);
+  }
+};
 function isAbortError(err) {
   return typeof err === "object" && err !== null && err.name === "AbortError";
 }
 function pushEventBounded(execInfo, event, cap) {
-  if (event.type === "token" || event.type === "partial_object") return;
+  if (STREAMING_EXCLUDED_TYPES.has(event.type)) return;
   if (cap === Infinity || execInfo.events.length < cap) {
     execInfo.events.push(event);
     return;
@@ -7948,6 +8173,36 @@ function pushEventBounded(execInfo, event, cap) {
     };
   }
 }
+function sanitizeMetadataForPersist(metadata) {
+  const cleaned = {};
+  for (const [k, v] of Object.entries(metadata)) {
+    try {
+      cleaned[k] = structuredClone(v);
+    } catch {
+    }
+  }
+  return cleaned;
+}
+function boundRecoveredEvents(events, cap) {
+  if (cap === Infinity || events.length <= cap) return events;
+  const truncated = events.slice(0, cap);
+  const last = truncated[truncated.length - 1];
+  const alreadyTruncated = last?.type === "log" && typeof last.data === "object" && last.data !== null && last.data.event === "events_truncated";
+  if (!alreadyTruncated) {
+    truncated[truncated.length - 1] = {
+      type: "log",
+      executionId: events[0]?.executionId ?? "",
+      step: last?.step ?? 0,
+      timestamp: Date.now(),
+      data: {
+        event: "events_truncated",
+        cap,
+        message: `Recovered ExecutionInfo.events truncated at ${cap} entries. Original streaming buffer had ${events.length} events. Raise via config.state.maxEventsPerExecution.`
+      }
+    };
+  }
+  return truncated;
+}
 var costScopeStorage = new AsyncLocalStorage2();
 function forwardAbortSignal(external, internal) {
   if (!external) return () => {
@@ -7994,6 +8249,30 @@ var AxlRuntime = class extends EventEmitter2 {
    *  `events` field — keeps the log to one line per row instead of one per
    *  rebuild tick. */
   warnedMalformedExecutions = /* @__PURE__ */ new Set();
+  /** Streaming-mode flusher. `undefined` when persist === 'terminal'
+   *  (back-compat default — no buffering overhead, no batching timer). */
+  streamingFlusher;
+  /** Execution IDs that are eligible for streaming-buffer durability —
+   *  populated by `execute()` / `stream()`. `createContext()` flows are
+   *  deliberately NOT added: ad-hoc contexts (tool tests, Studio playground,
+   *  evals) have no terminal `persistExecution` path that would finalize the
+   *  streaming buffer, so allowing them to write would leave phantom orphan
+   *  buffers that `recoverIncompleteStreams()` later mis-recovers as failed
+   *  executions. Membership is removed in `persistExecution` once the
+   *  canonical save + finalize chain has been scheduled. */
+  streamableExecutionIds = /* @__PURE__ */ new Set();
+  /** Execution IDs deleted by `runtime.deleteExecution()` while still in
+   *  flight. `persistExecution` skips its save + cache write when the
+   *  executionId is in this set — preventing a workflow that completes after
+   *  a delete from resurrecting the (intentionally-removed) row. Entries are
+   *  removed once the would-be persist has been short-circuited. */
+  pendingDeletedExecutions = /* @__PURE__ */ new Set();
+  /** In-flight `persistExecution` chains (save → finalize). `shutdown()`
+   *  awaits these before closing the StateStore so a workflow whose abort
+   *  triggers a persist-during-shutdown isn't racing a closed connection.
+   *  The Set is mutated by the chain's own `.finally` so entries clear as
+   *  soon as the work settles. */
+  persistInflight = /* @__PURE__ */ new Set();
   constructor(config) {
     super();
     this.config = resolveConfig(config ?? {});
@@ -8017,6 +8296,19 @@ var AxlRuntime = class extends EventEmitter2 {
         embedder: this.config.memory.embedder
       });
     }
+    if (this.config.state?.persist === "streaming") {
+      if (this.stateStore.appendStreamingEvents) {
+        this.streamingFlusher = new StreamingFlusher(
+          this.stateStore,
+          this.config.state.streamingBatchSize ?? DEFAULT_STREAMING_BATCH_SIZE,
+          this.config.state.streamingBatchInterval ?? DEFAULT_STREAMING_BATCH_INTERVAL
+        );
+      } else {
+        console.warn(
+          `[axl] config.state.persist === 'streaming' but the configured StateStore does not implement appendStreamingEvents. Streaming durability is disabled. Use RedisStore for crash-survival, or implement the optional streaming methods on your custom StateStore.`
+        );
+      }
+    }
   }
   /**
    * Whether `config.trace.redact` is enabled on this runtime. A narrow
@@ -8140,14 +8432,49 @@ var AxlRuntime = class extends EventEmitter2 {
   /**
    * Persist a completed/failed execution to the state store (fire-and-forget)
    * and move it from the active executions map to the historical cache.
+   *
+   * Resurrection guard: if `runtime.deleteExecution(id)` was called while
+   * this execution was still running, the id will be in
+   * `pendingDeletedExecutions`. In that case we skip the save AND the
+   * historical-cache write, and finalize the streaming buffer (if any) so
+   * the buffer doesn't outlive the delete.
    */
   persistExecution(execInfo) {
-    const snapshot = structuredClone(execInfo);
+    const id = execInfo.executionId;
+    this.streamableExecutionIds.delete(id);
+    if (this.pendingDeletedExecutions.has(id)) {
+      this.pendingDeletedExecutions.delete(id);
+      this.executions.delete(id);
+      if (this.streamingFlusher) {
+        this.streamingFlusher.finalize(id).catch(() => {
+        });
+      }
+      return;
+    }
+    let snapshot;
+    try {
+      snapshot = structuredClone(execInfo);
+    } catch {
+      snapshot = {
+        ...execInfo,
+        events: [...execInfo.events],
+        metadata: execInfo.metadata ? sanitizeMetadataForPersist(execInfo.metadata) : void 0
+      };
+    }
     if (this.stateStore.saveExecution) {
-      this.stateStore.saveExecution(snapshot).catch(() => {
+      const chain = this.stateStore.saveExecution(snapshot).then(() => {
+        return this.streamingFlusher?.finalize(id).catch(() => {
+        });
+      }).catch(() => {
+      }).then(() => void 0);
+      this.persistInflight.add(chain);
+      chain.finally(() => this.persistInflight.delete(chain));
+    } else if (this.streamingFlusher) {
+      const chain = this.streamingFlusher.finalize(id).catch(() => {
       });
+      this.persistInflight.add(chain);
+      chain.finally(() => this.persistInflight.delete(chain));
     }
-    const id = execInfo.executionId;
     this.historicalExecutions.set(id, snapshot);
     this.executions.delete(id);
   }
@@ -8387,6 +8714,9 @@ var AxlRuntime = class extends EventEmitter2 {
     this.abortControllers.set(executionId, controller);
     const cleanupAbortForwarder = forwardAbortSignal(options?.signal, controller);
     this.registerWithCostScope(executionId);
+    if (this.streamingFlusher) {
+      this.streamableExecutionIds.add(executionId);
+    }
     const execInfo = {
       executionId,
       workflow: name,
@@ -8394,7 +8724,8 @@ var AxlRuntime = class extends EventEmitter2 {
       events: [],
       totalCost: 0,
       startedAt: Date.now(),
-      duration: 0
+      duration: 0,
+      metadata: liftPersistedMetadata(options?.metadata)
     };
     this.executions.set(executionId, execInfo);
     const sessionHistory = options?.metadata?.sessionHistory ?? void 0;
@@ -8410,6 +8741,9 @@ var AxlRuntime = class extends EventEmitter2 {
       onTrace: (event) => {
         pushEventBounded(execInfo, event, this.maxEventsPerExecution);
         execInfo.totalCost += eventCostContribution(event);
+        if (this.streamableExecutionIds.has(executionId)) {
+          this.streamingFlusher?.append(executionId, event);
+        }
         this.emit("trace", event);
         this.outputAxlEvent(event);
         if (event.type === "handoff_start") {
@@ -8488,6 +8822,9 @@ var AxlRuntime = class extends EventEmitter2 {
       const validated = workflow2.inputSchema.parse(input);
       const sessionHistory = options?.metadata?.sessionHistory ?? void 0;
       this.registerWithCostScope(executionId);
+      if (this.streamingFlusher) {
+        this.streamableExecutionIds.add(executionId);
+      }
       execInfo = {
         executionId,
         workflow: name,
@@ -8495,7 +8832,8 @@ var AxlRuntime = class extends EventEmitter2 {
         events: [],
         totalCost: 0,
         startedAt: Date.now(),
-        duration: 0
+        duration: 0,
+        metadata: liftPersistedMetadata(options?.metadata)
       };
       this.executions.set(executionId, execInfo);
       const wfCtx = new WorkflowContext({
@@ -8516,6 +8854,9 @@ var AxlRuntime = class extends EventEmitter2 {
         onTrace: (event) => {
           pushEventBounded(execInfo, event, this.maxEventsPerExecution);
           execInfo.totalCost += eventCostContribution(event);
+          if (this.streamableExecutionIds.has(executionId)) {
+            this.streamingFlusher?.append(executionId, event);
+          }
           this.emit("trace", event);
           this.outputAxlEvent(event);
           axlStream._push(event);
@@ -8655,6 +8996,15 @@ var AxlRuntime = class extends EventEmitter2 {
         errors.push(new Error(`${label}: ${err instanceof Error ? err.message : String(err)}`));
       }
     };
+    if (this.streamingFlusher) {
+      await safeClose("streamingFlusher", () => this.streamingFlusher.flushAll());
+    }
+    if (this.persistInflight.size > 0) {
+      await safeClose(
+        "persistInflight",
+        () => Promise.allSettled([...this.persistInflight]).then(() => void 0)
+      );
+    }
     if (this.mcpManager) await safeClose("mcpManager", () => this.mcpManager.shutdown());
     if (this.memoryManager) await safeClose("memoryManager", () => this.memoryManager.close());
     if (this.stateStore.close) await safeClose("stateStore", () => this.stateStore.close());
@@ -8665,6 +9015,81 @@ var AxlRuntime = class extends EventEmitter2 {
       );
     }
   }
+  /**
+   * Recover executions whose process died mid-run when `state.persist:
+   * 'streaming'` was configured. Synthesizes a partial `ExecutionInfo`
+   * from the streaming buffer for each — `status: 'failed'`, error
+   * `'process terminated'` — registers them in the historical cache so
+   * they show up in `getExecutions()`, persists them via the store's
+   * `saveExecution`, and finalizes the streaming buffer.
+   *
+   * Idempotent — if the streaming buffer is already gone (or
+   * `listStreamingExecutions` is empty), this is a no-op. Returns the
+   * list of recovered `ExecutionInfo`s for caller introspection.
+   *
+   * Wire this into your process startup AFTER `runtime.getExecutions()`
+   * has lazy-loaded the historical cache. Order matters: completed
+   * executions already in the store should not be overwritten by a
+   * stale streaming buffer that the previous process didn't get to
+   * finalize. The implementation checks the historical store before
+   * synthesizing, so a re-run is safe.
+   */
+  async recoverIncompleteStreams() {
+    if (!this.stateStore.listStreamingExecutions || !this.stateStore.getStreamingEvents) {
+      return [];
+    }
+    const ids = await this.stateStore.listStreamingExecutions();
+    if (ids.length === 0) return [];
+    await this.getExecutions();
+    const recovered = [];
+    for (const id of ids) {
+      if (this.executions.has(id) || this.streamableExecutionIds.has(id)) {
+        continue;
+      }
+      const existing = this.historicalExecutions.get(id);
+      if (existing) {
+        await this.stateStore.finalizeStreamingEvents?.(id);
+        continue;
+      }
+      const events = await this.stateStore.getStreamingEvents(id);
+      if (events.length === 0) {
+        await this.stateStore.finalizeStreamingEvents?.(id);
+        continue;
+      }
+      const boundedEvents = boundRecoveredEvents(events, this.maxEventsPerExecution);
+      const workflowStartEvent = boundedEvents.find((e) => e.type === "workflow_start");
+      const lastEvent = boundedEvents[boundedEvents.length - 1];
+      const startedAt = workflowStartEvent?.timestamp ?? boundedEvents[0]?.timestamp ?? Date.now();
+      const completedAt = lastEvent.timestamp ?? startedAt;
+      const workflowName = workflowStartEvent?.workflow ?? RECOVERED_UNKNOWN_WORKFLOW;
+      const totalCost = boundedEvents.reduce((sum, e) => sum + eventCostContribution(e), 0);
+      const synthesized = {
+        executionId: id,
+        workflow: workflowName,
+        status: "failed",
+        events: boundedEvents,
+        totalCost,
+        startedAt,
+        completedAt,
+        duration: completedAt - startedAt,
+        error: "process terminated (recovered from streaming buffer)"
+      };
+      if (this.stateStore.saveExecution) {
+        try {
+          await this.stateStore.saveExecution(synthesized);
+        } catch (err) {
+          console.error(
+            `[axl] recoverIncompleteStreams: failed to save synthesized execution ${id}: ${err instanceof Error ? err.message : String(err)}. Streaming buffer left in place for next recovery attempt.`
+          );
+          continue;
+        }
+      }
+      this.historicalExecutions.set(id, synthesized);
+      await this.stateStore.finalizeStreamingEvents?.(id);
+      recovered.push(synthesized);
+    }
+    return recovered;
+  }
   /** Abort a running execution by its ID. */
   abort(executionId) {
     const controller = this.abortControllers.get(executionId);
@@ -8697,15 +9122,85 @@ var AxlRuntime = class extends EventEmitter2 {
     }
     this.emit("eval_result", entry);
   }
+  /**
+   * Delete an execution from history by id. Removes from the active map (if
+   * still running), the historical cache, the configured StateStore, AND
+   * any execution-scoped side state — pending awaitHuman decisions,
+   * resolver maps, streaming buffer registration, in-flight abort controller.
+   * Returns true if an entry was actually removed from any of the three
+   * primary surfaces (active map, historical cache, store).
+   *
+   * In-flight handling: if the execution is still running, this method
+   * **aborts** it (via the registered abort controller) AND marks the id for
+   * skip-on-persist so the workflow's eventual `workflow_end` doesn't
+   * resurrect the row. The workflow itself terminates normally — callers
+   * iterating the returned `AxlStream` will see the abort flow through. If
+   * you need a hard hand-off (delete completes before the workflow tears
+   * down), call `runtime.abort(id)` and `await` the stream/execute promise
+   * before calling this. `streamableExecutionIds` is cleared eagerly so
+   * events emitted during the wind-down don't re-create the streaming
+   * buffer in the store after the deleteExecution-issued DEL.
+   *
+   * Audit trail: emits `execution_deleted` on the runtime's `EventEmitter`
+   * with `{ executionId, wasActive, hadPendingDecision }` so compliance
+   * apps can subscribe via `runtime.on('execution_deleted', ...)` for a
+   * "who deleted what when" log without wrapping this method. Fires
+   * regardless of whether the id was actually present.
+   *
+   * Use cases: GDPR right-to-be-forgotten, operator-driven cleanup of
+   * specific runs (e.g. a workflow that recorded PII the user requested
+   * scrubbed). For bulk eviction by age, use a `RedisStore` TTL instead
+   * (`defaultTtl` / `ttls.executionHistory`).
+   */
+  async deleteExecution(id) {
+    const wasActive = this.executions.has(id);
+    const hadPendingDecision = this.pendingDecisionResolvers.has(id);
+    if (wasActive) {
+      this.pendingDeletedExecutions.add(id);
+      this.streamableExecutionIds.delete(id);
+      const controller = this.abortControllers.get(id);
+      if (controller) {
+        controller.abort();
+      }
+    }
+    if (hadPendingDecision) {
+      this.pendingDecisionResolvers.delete(id);
+    }
+    const existing = await this.getExecution(id);
+    const workflow2 = existing?.workflow;
+    const removedFromActive = this.executions.delete(id);
+    const removedFromHistorical = this.historicalExecutions.delete(id);
+    let removedFromStore = false;
+    if (this.stateStore.deleteExecution) {
+      removedFromStore = await this.stateStore.deleteExecution(id);
+    }
+    this.emit("execution_deleted", {
+      executionId: id,
+      workflow: workflow2,
+      wasActive,
+      hadPendingDecision,
+      removed: removedFromActive || removedFromHistorical || removedFromStore
+    });
+    return removedFromActive || removedFromHistorical || removedFromStore;
+  }
   /**
    * Delete an eval history entry by id. Removes from in-memory cache and
    * the configured StateStore. Returns true if an entry was actually removed.
    *
    * Ensures lazy-loaded history is loaded first so the in-memory cache and
    * the store can't drift apart on the deletion path.
+   *
+   * Emits `eval_deleted` on the runtime's `EventEmitter` with
+   * `{ id, eval, removed }`. Fires on every call — including attempts
+   * against unknown ids (`removed: false`) — symmetric to `execution_deleted`.
+   * Studio's eval-trends aggregator subscribes to this event so deleted
+   * runs don't linger in the trends panel for up to 5 minutes (until the
+   * next periodic rebuild).
    */
   async deleteEvalResult(id) {
     await this.getEvalHistory();
+    const existing = this.evalHistory.find((e) => e.id === id);
+    const evalName = existing?.eval;
     const beforeLength = this.evalHistory.length;
     this.evalHistory = this.evalHistory.filter((e) => e.id !== id);
     const removedFromMemory = this.evalHistory.length < beforeLength;
@@ -8713,7 +9208,13 @@ var AxlRuntime = class extends EventEmitter2 {
     if (this.stateStore.deleteEvalResult) {
       removedFromStore = await this.stateStore.deleteEvalResult(id);
     }
-    return removedFromMemory || removedFromStore;
+    const removed = removedFromMemory || removedFromStore;
+    this.emit("eval_deleted", {
+      id,
+      eval: evalName,
+      removed
+    });
+    return removed;
   }
   /** Get eval result history (most recent first). */
   async getEvalHistory() {
@@ -9303,15 +9804,53 @@ async function* stringStreamFromEvents(source, opts) {
 
 // src/state/redis.ts
 var RedisStore = class _RedisStore {
-  constructor(client) {
+  constructor(client, keyPrefix, ttls) {
     this.client = client;
+    this.keyPrefix = keyPrefix;
+    this.ttls = ttls;
+  }
+  /**
+   * Resolve the TTL for a given storage category. Returns `undefined` when
+   * no TTL applies (category is `null` in resolved config, the value is
+   * non-positive — Redis EXPIRE 0 immediately deletes, which is almost
+   * never intended — or the value is non-finite).
+   *
+   * Non-finite values (`NaN`, `±Infinity`) defensively map to `undefined`
+   * rather than being passed to Redis, where they'd surface as a wire-level
+   * protocol error at the worst possible time (first write under load).
+   */
+  ttlFor(category) {
+    const resolved = this.ttls[category];
+    if (resolved === null) return void 0;
+    if (!Number.isFinite(resolved) || resolved <= 0) return void 0;
+    return Math.floor(resolved);
   }
   /**
    * Create a connected RedisStore instance.
    *
-   * @param url - Redis connection URL (e.g. `redis://localhost:6379`). Defaults to `redis://localhost:6379`.
+   * Accepts either a URL string (back-compat) or a {@link RedisStoreOptions}
+   * object. The object form is required to set a custom `keyPrefix`.
+   *
+   * @example
+   * ```ts
+   * // Default prefix 'axl:'
+   * const store = await RedisStore.create('redis://localhost:6379');
+   *
+   * // Custom prefix for shared-cluster deployments
+   * const store = await RedisStore.create({
+   *   url: 'redis://localhost:6379',
+   *   keyPrefix: 'axl:prod:',
+   * });
+   * ```
    */
-  static async create(url) {
+  static async create(options) {
+    const opts = typeof options === "string" ? { url: options } : options ?? {};
+    const keyPrefix = opts.keyPrefix ?? "axl:";
+    if (keyPrefix === "") {
+      throw new Error(
+        'RedisStore: keyPrefix cannot be empty string. Omit it for the default "axl:" prefix.'
+      );
+    }
     let createClient;
     try {
       const mod = __require("redis");
@@ -9325,44 +9864,197 @@ 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 = url ? createClient({ url }) : createClient();
+    const client = opts.url ? createClient({ url: opts.url }) : createClient();
     await client.connect();
-    return new _RedisStore(client);
+    const resolveCategory = (override) => {
+      if (override === null) return null;
+      if (typeof override === "number") return override;
+      return typeof opts.defaultTtl === "number" ? opts.defaultTtl : null;
+    };
+    const resolveStreamingEvents = (override) => {
+      if (override === null || override === void 0) return null;
+      if (typeof override === "number") return override;
+      return null;
+    };
+    const effectiveTtls = {
+      session: resolveCategory(opts.ttls?.session),
+      sessionMeta: resolveCategory(opts.ttls?.sessionMeta),
+      checkpoint: resolveCategory(opts.ttls?.checkpoint),
+      executionState: resolveCategory(opts.ttls?.executionState),
+      executionHistory: resolveCategory(opts.ttls?.executionHistory),
+      evalHistory: resolveCategory(opts.ttls?.evalHistory),
+      memory: resolveCategory(opts.ttls?.memory),
+      streamingEvents: resolveStreamingEvents(opts.ttls?.streamingEvents)
+    };
+    const store = new _RedisStore(client, keyPrefix, effectiveTtls);
+    if (!opts.skipMigration) {
+      await store.backfillExecutionIndex();
+      await store.backfillEvalIndex();
+    }
+    return store;
+  }
+  /**
+   * Backfill the execution-history sorted-set from the legacy ID set.
+   * Idempotent — runs only if the ZSET is missing entries the SET has.
+   * Safe to call manually if you constructed the store with
+   * `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"
+    );
+  }
+  /** 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"
+    );
+  }
+  /**
+   * 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.
+   */
+  async backfillHistoryIndex(setKey, zsetKey, dataKey, scoreOf, label) {
+    const [setSize, zsetSize] = await Promise.all([
+      this.client.sCard(setKey),
+      this.client.zCard(zsetKey)
+    ]);
+    if (zsetSize >= setSize) return;
+    const allIds = await this.client.sMembers(setKey);
+    if (allIds.length === 0) return;
+    const CHUNK_SIZE = 500;
+    let migrated = 0;
+    let skipped = 0;
+    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 raws = await this.client.mGet(dataKeys);
+      const tx = this.client.multi();
+      let queuedInChunk = 0;
+      for (let j = 0; j < chunk.length; j++) {
+        const raw = raws[j];
+        if (raw == null) {
+          skipped++;
+          continue;
+        }
+        try {
+          const entry = scoreOf(raw);
+          if (entry == null) {
+            skipped++;
+            continue;
+          }
+          tx.zAdd(zsetKey, entry);
+          queuedInChunk++;
+          migrated++;
+        } catch {
+          skipped++;
+        }
+      }
+      if (queuedInChunk > 0) await tx.exec();
+    }
+    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)` : "")
+      );
+    }
   }
   // ── Key helpers ──────────────────────────────────────────────────────
   checkpointKey(executionId) {
-    return `axl:checkpoint:${executionId}`;
+    return `${this.keyPrefix}checkpoint:${executionId}`;
   }
   sessionKey(sessionId) {
-    return `axl:session:${sessionId}`;
+    return `${this.keyPrefix}session:${sessionId}`;
   }
   sessionMetaKey(sessionId) {
-    return `axl:session-meta:${sessionId}`;
+    return `${this.keyPrefix}session-meta:${sessionId}`;
+  }
+  sessionIdsKey() {
+    return `${this.keyPrefix}session-ids`;
   }
   decisionsKey() {
-    return "axl:decisions";
+    return `${this.keyPrefix}decisions`;
   }
   executionStateKey(executionId) {
-    return `axl:exec-state:${executionId}`;
+    return `${this.keyPrefix}exec-state:${executionId}`;
   }
   pendingExecSetKey() {
-    return "axl:pending-executions";
+    return `${this.keyPrefix}pending-executions`;
   }
   execHistoryKey(executionId) {
-    return `axl:exec-history:${executionId}`;
-  }
+    return `${this.keyPrefix}exec-history:${executionId}`;
+  }
+  // NOTE for future implementer of #3 (TTL config): when the executionHistory
+  // and evalHistory data blobs gain TTLs, eviction MUST be driven by
+  // ZREMRANGEBYSCORE on the ZSET below — NOT by SREM on these legacy ID sets.
+  // The slow-path fallback (`listHistoryByZset`) reads from the SET when
+  // `zsetCard < setCard`, so SET-based eviction would race with the fallback
+  // and surface dead IDs whose data has been TTL'd away. ZSET eviction +
+  // dual-write `SREM` is the clean path; doc the assumption then.
   execHistorySetKey() {
-    return "axl:exec-history-ids";
+    return `${this.keyPrefix}exec-history-ids`;
+  }
+  /**
+   * Sorted-set index for execution history, scored by `startedAt`. Drives
+   * the O(log N) `listExecutions` fast path; the legacy SET above is kept
+   * as a fallback for users running with `skipMigration: true` before
+   * they've called `backfillExecutionIndex()` manually.
+   */
+  execHistoryZsetKey() {
+    return `${this.keyPrefix}exec-history-z`;
   }
   evalHistoryKey(id) {
-    return `axl:eval-history:${id}`;
+    return `${this.keyPrefix}eval-history:${id}`;
   }
   evalHistorySetKey() {
-    return "axl:eval-history-ids";
+    return `${this.keyPrefix}eval-history-ids`;
+  }
+  /** Sorted-set index for eval history, scored by `timestamp`. See above. */
+  evalHistoryZsetKey() {
+    return `${this.keyPrefix}eval-history-z`;
+  }
+  memoryKey(scope) {
+    return `${this.keyPrefix}memory:${scope}`;
+  }
+  // ── Streaming event buffer (for `state.persist: 'streaming'`) ─────────
+  // Layout:
+  //   `{prefix}exec-events:{id}` — a Redis list. Events are RPUSH'd as
+  //     JSON-serialized AxlEvent objects, in batches. The runtime LRANGEs
+  //     the whole list on recovery and deletes it via `finalizeStreamingEvents`
+  //     once the canonical `executionHistory` blob has been written at
+  //     terminal exit.
+  //   `{prefix}streaming-exec-ids` — a Redis set tracking which executions
+  //     have an active streaming buffer. Used by `listStreamingExecutions`
+  //     to find runs whose process died mid-flight (no corresponding
+  //     `executionHistory` blob).
+  streamingEventsKey(executionId) {
+    return `${this.keyPrefix}exec-events:${executionId}`;
+  }
+  streamingIdsKey() {
+    return `${this.keyPrefix}streaming-exec-ids`;
   }
   // ── Checkpoints ──────────────────────────────────────────────────────
   async saveCheckpoint(executionId, name, data) {
-    await this.client.hSet(this.checkpointKey(executionId), name, JSON.stringify(data));
+    const ttl = this.ttlFor("checkpoint");
+    if (ttl === void 0) {
+      await this.client.hSet(this.checkpointKey(executionId), name, JSON.stringify(data));
+      return;
+    }
+    await this.client.multi().hSet(this.checkpointKey(executionId), name, JSON.stringify(data)).expire(this.checkpointKey(executionId), ttl, "NX").exec();
   }
   async getCheckpoint(executionId, name) {
     const raw = await this.client.hGet(this.checkpointKey(executionId), name);
@@ -9370,20 +10062,24 @@ var RedisStore = class _RedisStore {
   }
   // ── Sessions ─────────────────────────────────────────────────────────
   async saveSession(sessionId, history) {
-    await this.client.set(this.sessionKey(sessionId), JSON.stringify(history));
-    await this.client.sAdd("axl:session-ids", sessionId);
+    const ttl = this.ttlFor("session");
+    const setOptions = ttl !== void 0 ? { EX: ttl } : void 0;
+    await this.client.multi().set(this.sessionKey(sessionId), JSON.stringify(history), setOptions).sAdd(this.sessionIdsKey(), sessionId).exec();
   }
   async getSession(sessionId) {
     const raw = await this.client.get(this.sessionKey(sessionId));
     return raw ? JSON.parse(raw) : [];
   }
   async deleteSession(sessionId) {
-    await this.client.del(this.sessionKey(sessionId));
-    await this.client.del(this.sessionMetaKey(sessionId));
-    await this.client.sRem("axl:session-ids", sessionId);
+    await this.client.multi().del(this.sessionKey(sessionId)).del(this.sessionMetaKey(sessionId)).sRem(this.sessionIdsKey(), sessionId).exec();
   }
   async saveSessionMeta(sessionId, key, value) {
-    await this.client.hSet(this.sessionMetaKey(sessionId), key, JSON.stringify(value));
+    const ttl = this.ttlFor("sessionMeta");
+    if (ttl === void 0) {
+      await this.client.hSet(this.sessionMetaKey(sessionId), key, JSON.stringify(value));
+      return;
+    }
+    await this.client.multi().hSet(this.sessionMetaKey(sessionId), key, JSON.stringify(value)).expire(this.sessionMetaKey(sessionId), ttl).exec();
   }
   async getSessionMeta(sessionId, key) {
     const raw = await this.client.hGet(this.sessionMetaKey(sessionId), key);
@@ -9403,64 +10099,222 @@ var RedisStore = class _RedisStore {
   }
   // ── Execution State ──────────────────────────────────────────────────
   async saveExecutionState(executionId, state) {
-    await this.client.set(this.executionStateKey(executionId), JSON.stringify(state));
+    const ttl = this.ttlFor("executionState");
+    const setOptions = ttl !== void 0 ? { EX: ttl } : void 0;
+    const tx = this.client.multi().set(this.executionStateKey(executionId), JSON.stringify(state), setOptions);
     if (state.status === "waiting") {
-      await this.client.sAdd(this.pendingExecSetKey(), executionId);
+      tx.sAdd(this.pendingExecSetKey(), executionId);
     } else {
-      await this.client.sRem(this.pendingExecSetKey(), executionId);
+      tx.sRem(this.pendingExecSetKey(), executionId);
     }
+    await tx.exec();
   }
   async getExecutionState(executionId) {
     const raw = await this.client.get(this.executionStateKey(executionId));
     return raw ? JSON.parse(raw) : null;
   }
   async listPendingExecutions() {
-    return this.client.sMembers(this.pendingExecSetKey());
+    const ids = await this.client.sMembers(this.pendingExecSetKey());
+    if (ids.length === 0) return ids;
+    const keys = ids.map((id) => this.executionStateKey(id));
+    const raws = await this.client.mGet(keys);
+    const live = [];
+    const dead = [];
+    for (let i = 0; i < ids.length; i++) {
+      if (raws[i] != null) {
+        live.push(ids[i]);
+      } else {
+        dead.push(ids[i]);
+      }
+    }
+    if (dead.length > 0) {
+      this.client.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))
+        );
+      });
+    }
+    return live;
+  }
+  // ── Memory ──────────────────────────────────────────────────────────
+  //
+  // Layout: `{prefix}memory:{scope}` is a hash. Fields are user-supplied
+  // keys; values are JSON-serialized. Hash-per-scope keeps related entries
+  // together (good cohesion for TTL eviction once #3 lands) and bounds the
+  // keyspace to O(scopes) instead of O(scopes × keys).
+  //
+  // Pre-this-patch, RedisStore had no memory methods, so MemoryManager fell
+  // back to writing memory at synthetic sessionMeta keys
+  // (`{prefix}session-meta:memory:{scope}:{key}` hash field `value`). To
+  // preserve user data on upgrade, `getMemory` checks the legacy location on
+  // miss and migrates forward; `deleteMemory` also cleans the legacy entry.
+  // No legacy support on `getAllMemory` — that method didn't exist before,
+  // so no user can depend on it returning legacy data.
+  async saveMemory(scope, key, value) {
+    const ttl = this.ttlFor("memory");
+    if (ttl === void 0) {
+      await this.client.hSet(this.memoryKey(scope), key, JSON.stringify(value));
+      return;
+    }
+    await this.client.multi().hSet(this.memoryKey(scope), key, JSON.stringify(value)).expire(this.memoryKey(scope), ttl).exec();
+  }
+  async getMemory(scope, key) {
+    const raw = await this.client.hGet(this.memoryKey(scope), key);
+    if (raw != null) return JSON.parse(raw);
+    const legacyRaw = await this.client.hGet(
+      this.sessionMetaKey(`memory:${scope}:${key}`),
+      "value"
+    );
+    if (legacyRaw == null) return null;
+    const inserted = await this.client.hSetNX(this.memoryKey(scope), key, legacyRaw);
+    if (inserted === 0 || inserted === false) {
+      const winner = await this.client.hGet(this.memoryKey(scope), key);
+      if (winner != null) return JSON.parse(winner);
+      return null;
+    }
+    const ttl = this.ttlFor("memory");
+    if (ttl !== void 0) {
+      this.client.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))
+        );
+      });
+    }
+    return JSON.parse(legacyRaw);
+  }
+  async getAllMemory(scope) {
+    const all = await this.client.hGetAll(this.memoryKey(scope));
+    if (!all) return [];
+    return Object.entries(all).map(([key, raw]) => ({ key, value: JSON.parse(raw) }));
+  }
+  async deleteMemory(scope, key) {
+    await this.client.multi().hDel(this.memoryKey(scope), key).hDel(this.sessionMetaKey(`memory:${scope}:${key}`), "value").exec();
   }
   // ── Execution History ────────────────────────────────────────────────
   async saveExecution(execution) {
-    await this.client.sAdd(this.execHistorySetKey(), execution.executionId);
-    await this.client.set(this.execHistoryKey(execution.executionId), JSON.stringify(execution));
+    const ttl = this.ttlFor("executionHistory");
+    const setOptions = ttl !== void 0 ? { EX: ttl } : void 0;
+    await this.client.multi().sAdd(this.execHistorySetKey(), execution.executionId).set(this.execHistoryKey(execution.executionId), JSON.stringify(execution), setOptions).zAdd(this.execHistoryZsetKey(), {
+      score: execution.startedAt,
+      value: execution.executionId
+    }).exec();
   }
   async getExecution(executionId) {
     const raw = await this.client.get(this.execHistoryKey(executionId));
     return raw ? JSON.parse(raw) : null;
   }
   async listExecutions(limit) {
-    const ids = await this.client.sMembers(this.execHistorySetKey());
-    if (ids.length === 0) return [];
-    const entries = [];
-    for (const id of ids) {
-      const raw = await this.client.get(this.execHistoryKey(id));
-      if (raw) entries.push(JSON.parse(raw));
-    }
-    entries.sort((a, b) => b.startedAt - a.startedAt);
-    return limit ? entries.slice(0, limit) : entries;
+    return this.listHistoryByZset(
+      this.execHistorySetKey(),
+      this.execHistoryZsetKey(),
+      (id) => this.execHistoryKey(id),
+      (a, b) => b.startedAt - a.startedAt,
+      limit
+    );
+  }
+  async deleteExecution(executionId) {
+    const [, deletedCount] = await this.client.multi().sRem(this.execHistorySetKey(), executionId).del(this.execHistoryKey(executionId)).zRem(this.execHistoryZsetKey(), executionId).del(this.checkpointKey(executionId)).del(this.executionStateKey(executionId)).sRem(this.pendingExecSetKey(), executionId).del(this.streamingEventsKey(executionId)).sRem(this.streamingIdsKey(), executionId).hDel(this.decisionsKey(), executionId).exec();
+    const deleted = typeof deletedCount === "number" ? deletedCount : 0;
+    return deleted > 0;
   }
   // ── Eval History ────────────────────────────────────────────────────
   async saveEvalResult(entry) {
-    await this.client.sAdd(this.evalHistorySetKey(), entry.id);
-    await this.client.set(this.evalHistoryKey(entry.id), JSON.stringify(entry));
+    const ttl = this.ttlFor("evalHistory");
+    const setOptions = ttl !== void 0 ? { EX: ttl } : void 0;
+    await this.client.multi().sAdd(this.evalHistorySetKey(), entry.id).set(this.evalHistoryKey(entry.id), JSON.stringify(entry), setOptions).zAdd(this.evalHistoryZsetKey(), { score: entry.timestamp, value: entry.id }).exec();
   }
   async listEvalResults(limit) {
-    const ids = await this.client.sMembers(this.evalHistorySetKey());
+    return this.listHistoryByZset(
+      this.evalHistorySetKey(),
+      this.evalHistoryZsetKey(),
+      (id) => this.evalHistoryKey(id),
+      (a, b) => b.timestamp - a.timestamp,
+      limit
+    );
+  }
+  async deleteEvalResult(id) {
+    const [, deletedCount] = await this.client.multi().sRem(this.evalHistorySetKey(), id).del(this.evalHistoryKey(id)).zRem(this.evalHistoryZsetKey(), id).exec();
+    const deleted = typeof deletedCount === "number" ? deletedCount : 0;
+    return deleted > 0;
+  }
+  /**
+   * Shared list-by-sorted-set implementation. Uses ZREVRANGEBYSCORE +
+   * MGET when the ZSET is populated (post-migration). Falls back to the
+   * legacy SET + N×GET + JS-sort path when the ZSET is empty or smaller
+   * than the SET (covers users that constructed with `skipMigration: true`
+   * before calling backfill).
+   */
+  async listHistoryByZset(setKey, zsetKey, dataKey, sortCmp, limit) {
+    const setSize = await this.client.sCard(setKey);
+    if (setSize === 0) return [];
+    const zsetSize = await this.client.zCard(zsetKey);
+    if (zsetSize >= setSize) {
+      const fetchCount = limit !== void 0 ? Math.max(limit * 2, limit + 5) : void 0;
+      const ids2 = await this.client.zRange(zsetKey, "+inf", "-inf", {
+        BY: "SCORE",
+        REV: true,
+        ...fetchCount !== void 0 ? { LIMIT: { offset: 0, count: fetchCount } } : {}
+      });
+      if (ids2.length === 0) return [];
+      const keys = ids2.map(dataKey);
+      const raws = await this.client.mGet(keys);
+      const entries2 = [];
+      for (const raw of raws) {
+        if (raw == null) continue;
+        try {
+          entries2.push(JSON.parse(raw));
+        } catch {
+        }
+        if (limit !== void 0 && entries2.length >= limit) break;
+      }
+      return entries2;
+    }
+    const ids = await this.client.sMembers(setKey);
     if (ids.length === 0) return [];
     const entries = [];
     for (const id of ids) {
-      const raw = await this.client.get(this.evalHistoryKey(id));
-      if (raw) entries.push(JSON.parse(raw));
+      const raw = await this.client.get(dataKey(id));
+      if (raw == null) continue;
+      try {
+        entries.push(JSON.parse(raw));
+      } catch {
+      }
     }
-    entries.sort((a, b) => b.timestamp - a.timestamp);
+    entries.sort(sortCmp);
     return limit ? entries.slice(0, limit) : entries;
   }
-  async deleteEvalResult(id) {
-    await this.client.sRem(this.evalHistorySetKey(), id);
-    const deleted = await this.client.del(this.evalHistoryKey(id));
-    return deleted > 0;
-  }
   // ── Sessions (Studio introspection) ────────────────────────────────────
   async listSessions() {
-    return this.client.sMembers("axl:session-ids");
+    return this.client.sMembers(this.sessionIdsKey());
+  }
+  // ── Streaming events (for state.persist: 'streaming') ──────────────────
+  async appendStreamingEvents(executionId, events) {
+    if (events.length === 0) return;
+    const serialized = events.map((e) => JSON.stringify(e));
+    const ttl = this.ttlFor("streamingEvents");
+    const tx = this.client.multi().rPush(this.streamingEventsKey(executionId), serialized).sAdd(this.streamingIdsKey(), executionId);
+    if (ttl !== void 0) {
+      tx.expire(this.streamingEventsKey(executionId), ttl, "NX");
+    }
+    await tx.exec();
+  }
+  async finalizeStreamingEvents(executionId) {
+    await this.client.multi().del(this.streamingEventsKey(executionId)).sRem(this.streamingIdsKey(), executionId).exec();
+  }
+  async listStreamingExecutions() {
+    return this.client.sMembers(this.streamingIdsKey());
+  }
+  async getStreamingEvents(executionId) {
+    const raws = await this.client.lRange(this.streamingEventsKey(executionId), 0, -1);
+    if (raws.length === 0) return [];
+    const events = [];
+    for (const raw of raws) {
+      try {
+        events.push(JSON.parse(raw));
+      } catch {
+      }
+    }
+    return events;
   }
   /** Close the Redis connection. */
   async close() {