palaryn 0.1.0 → 0.3.2

package/src/storage/redis.ts

@@ -0,0 +1,835 @@
+import Redis from 'ioredis';
+import { BudgetState } from '../types/budget';
+import { AuditEvent, EventType } from '../types/events';
+import {
+  BudgetStore,
+  AuditStore,
+  ApprovalStore,
+  ApprovalRecord,
+  RateLimitStore,
+  IdempotencyStore,
+} from './interfaces';
+import { ToolResult } from '../types/tool-result';
+
+/** Helper to log Redis errors with a descriptive operation name */
+function logRedisError(op: string) {
+  return (err: unknown) => console.error(`[redis] ${op} failed:`, err);
+}
+
+/**
+ * Redis-backed rate limit store using sorted sets for sliding window counters.
+ *
+ * Because the RateLimitStore interface is synchronous, this implementation
+ * maintains an in-memory cache for immediate reads and fires off Redis
+ * operations asynchronously to persist state. On hit(), the local cache
+ * is updated first (synchronous return), then Redis is updated in the
+ * background. This gives the sync interface while still benefiting from
+ * Redis persistence across process restarts.
+ *
+ * Redis data structure per key: sorted set where each member is a unique
+ * hit ID and the score is the timestamp (ms).
+ */
+export class RedisRateLimitStore implements RateLimitStore {
+  private redis: Redis;
+  private prefix: string;
+  private localWindows = new Map<string, number[]>();
+  private hitCounter = 0;
+  private _pendingWrites: Promise<void>[] = [];
+
+  constructor(redis: Redis, prefix: string = 'rl:') {
+    this.redis = redis;
+    this.prefix = prefix;
+  }
+
+  hit(
+    key: string,
+    windowMs: number,
+    maxRequests: number,
+  ): { allowed: boolean; current: number; limit: number; resetAt: number } {
+    const now = Date.now();
+    const cutoff = now - windowMs;
+
+    // Update local cache (synchronous path)
+    let timestamps = this.localWindows.get(key) || [];
+    timestamps = timestamps.filter(t => t > cutoff);
+    timestamps.push(now);
+    this.localWindows.set(key, timestamps);
+
+    const current = timestamps.length;
+    const allowed = current <= maxRequests;
+    const resetAt = timestamps.length > 0 ? timestamps[0] + windowMs : now + windowMs;
+
+    // Track Redis pipeline as a pending write so callers can await consistency
+    const redisKey = this.prefix + key;
+    const hitId = `${now}:${++this.hitCounter}`;
+    const pipeline = this.redis.pipeline();
+    pipeline.zremrangebyscore(redisKey, '-inf', cutoff);
+    pipeline.zadd(redisKey, now, hitId);
+    pipeline.zcard(redisKey);
+    // Set a TTL on the key so it auto-expires after the window passes
+    pipeline.pexpire(redisKey, windowMs);
+    this._pendingWrites.push(
+      pipeline.exec().then(() => {}).catch(logRedisError('RateLimitStore.hit pipeline')),
+    );
+
+    return { allowed, current, limit: maxRequests, resetAt };
+  }
+
+  /** Wait for all pending Redis pipeline writes to complete. */
+  async flush(): Promise<void> {
+    const writes = this._pendingWrites;
+    this._pendingWrites = [];
+    await Promise.all(writes);
+  }
+
+  reset(): void {
+    this.localWindows.clear();
+
+    // Scan and delete all keys matching the prefix pattern in the background
+    this._scanAndDelete().catch(logRedisError('RateLimitStore.reset scanAndDelete'));
+  }
+
+  /**
+   * Uses SCAN to iteratively find and delete all keys matching the prefix.
+   * SCAN is preferred over KEYS to avoid blocking Redis on large keyspaces.
+   */
+  private async _scanAndDelete(): Promise<void> {
+    const pattern = this.prefix + '*';
+    let cursor = '0';
+
+    do {
+      const [nextCursor, keys] = await this.redis.scan(cursor, 'MATCH', pattern, 'COUNT', 100);
+      cursor = nextCursor;
+      if (keys.length > 0) {
+        await this.redis.del(...keys);
+      }
+    } while (cursor !== '0');
+  }
+
+  /**
+   * Bulk-hydrate local cache from all Redis sorted set keys matching the prefix.
+   * Call once at startup to restore rate limit state after a process restart.
+   */
+  async hydrateAll(): Promise<void> {
+    try {
+      const pattern = this.prefix + '*';
+      let cursor = '0';
+      do {
+        const [nextCursor, keys] = await this.redis.scan(cursor, 'MATCH', pattern, 'COUNT', 100);
+        cursor = nextCursor;
+        for (const redisKey of keys) {
+          const localKey = redisKey.slice(this.prefix.length);
+          // Read all members with scores; prune nothing (callers apply windowMs on hit)
+          const members = await this.redis.zrangebyscore(redisKey, '-inf', '+inf', 'WITHSCORES');
+          const timestamps: number[] = [];
+          for (let i = 1; i < members.length; i += 2) {
+            timestamps.push(Number(members[i]));
+          }
+          timestamps.sort((a, b) => a - b);
+          if (timestamps.length > 0) {
+            this.localWindows.set(localKey, timestamps);
+          }
+        }
+      } while (cursor !== '0');
+    } catch (err: any) {
+      console.error('[RedisRateLimitStore] hydrateAll failed:', err.message);
+    }
+  }
+
+  /**
+   * Hydrate the local cache from Redis for a given key.
+   * Useful after a process restart to restore sliding window state.
+   * This is an async helper -- call it during startup if needed.
+   */
+  async hydrate(key: string, windowMs: number): Promise<void> {
+    const redisKey = this.prefix + key;
+    const cutoff = Date.now() - windowMs;
+
+    // Prune and fetch remaining entries
+    await this.redis.zremrangebyscore(redisKey, '-inf', cutoff);
+    const members = await this.redis.zrangebyscore(redisKey, cutoff, '+inf', 'WITHSCORES');
+
+    // members is [member1, score1, member2, score2, ...]
+    const timestamps: number[] = [];
+    for (let i = 1; i < members.length; i += 2) {
+      timestamps.push(Number(members[i]));
+    }
+    timestamps.sort((a, b) => a - b);
+    this.localWindows.set(key, timestamps);
+  }
+}
+
+/**
+ * Redis-backed idempotency store for tool call deduplication.
+ *
+ * Like the rate limit store, this maintains a local in-memory cache for
+ * synchronous access (required by the IdempotencyStore interface) and
+ * persists to Redis asynchronously. Redis SET with PX expiry handles TTL
+ * automatically, while the local cache mirrors the same expiry behavior.
+ *
+ * On get(), the local cache is checked first. If the entry is missing or
+ * expired locally, it will be a cache miss for this call, but a background
+ * fetch from Redis populates the local cache for subsequent calls.
+ */
+export class RedisIdempotencyStore implements IdempotencyStore {
+  private redis: Redis;
+  private prefix: string;
+  private localCache = new Map<string, { result: ToolResult; expiresAt: number }>();
+  private _pendingWrites: Promise<void>[] = [];
+
+  constructor(redis: Redis, prefix: string = 'idem:') {
+    this.redis = redis;
+    this.prefix = prefix;
+  }
+
+  async get(toolCallId: string): Promise<ToolResult | undefined> {
+    // Check local cache first
+    const entry = this.localCache.get(toolCallId);
+    if (entry) {
+      if (Date.now() > entry.expiresAt) {
+        this.localCache.delete(toolCallId);
+        return undefined;
+      }
+      return entry.result;
+    }
+
+    // Local miss — fetch from Redis synchronously
+    try {
+      const redisKey = this.prefix + toolCallId;
+      const raw = await this.redis.get(redisKey);
+      if (raw !== null) {
+        const parsed = JSON.parse(raw);
+        const ttl = await this.redis.pttl(redisKey);
+        if (ttl > 0) {
+          this.localCache.set(toolCallId, {
+            result: parsed,
+            expiresAt: Date.now() + ttl,
+          });
+        }
+        return parsed;
+      }
+    } catch (err) {
+      console.error('[redis] IdempotencyStore.get fetch failed:', err);
+    }
+    return undefined;
+  }
+
+  set(toolCallId: string, result: ToolResult, ttlMs: number): void {
+    // Update local cache immediately
+    this.localCache.set(toolCallId, {
+      result,
+      expiresAt: Date.now() + ttlMs,
+    });
+
+    // Evict expired local entries when the cache grows large
+    if (this.localCache.size > 10000) {
+      const now = Date.now();
+      for (const [key, val] of this.localCache) {
+        if (now > val.expiresAt) this.localCache.delete(key);
+      }
+    }
+
+    // Persist to Redis with millisecond TTL
+    const redisKey = this.prefix + toolCallId;
+    const serialized = JSON.stringify(result);
+    this._pendingWrites.push(
+      this.redis.set(redisKey, serialized, 'PX', ttlMs).then(() => {}).catch(logRedisError('IdempotencyStore.set write')),
+    );
+  }
+
+  async has(toolCallId: string): Promise<boolean> {
+    return (await this.get(toolCallId)) !== undefined;
+  }
+
+  async flush(): Promise<void> {
+    const writes = this._pendingWrites;
+    this._pendingWrites = [];
+    await Promise.all(writes);
+  }
+
+  clear(): void {
+    this.localCache.clear();
+
+    // Scan and delete all keys matching the prefix pattern in the background
+    this._scanAndDelete().catch(logRedisError('IdempotencyStore.clear scanAndDelete'));
+  }
+
+  /**
+   * Uses SCAN to iteratively find and delete all keys matching the prefix.
+   * SCAN is preferred over KEYS to avoid blocking Redis on large keyspaces.
+   */
+  private async _scanAndDelete(): Promise<void> {
+    const pattern = this.prefix + '*';
+    let cursor = '0';
+
+    do {
+      const [nextCursor, keys] = await this.redis.scan(cursor, 'MATCH', pattern, 'COUNT', 100);
+      cursor = nextCursor;
+      if (keys.length > 0) {
+        await this.redis.del(...keys);
+      }
+    } while (cursor !== '0');
+  }
+
+  /**
+   * Hydrate the local cache from Redis for a given tool call ID.
+   * Useful after a process restart to restore cached results.
+   * This is an async helper -- call it during startup if needed.
+   */
+  async hydrate(toolCallId: string): Promise<void> {
+    const redisKey = this.prefix + toolCallId;
+    const raw = await this.redis.get(redisKey);
+    if (raw !== null) {
+      try {
+        const parsed = JSON.parse(raw);
+        const ttl = await this.redis.pttl(redisKey);
+        if (ttl > 0) {
+          this.localCache.set(toolCallId, {
+            result: parsed,
+            expiresAt: Date.now() + ttl,
+          });
+        }
+      } catch {
+        // Swallow parse errors
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// RedisBudgetStore
+// ---------------------------------------------------------------------------
+
+/**
+ * Redis-backed budget store using the write-through cache pattern.
+ *
+ * All BudgetStore interface methods are synchronous (in-memory cache),
+ * with fire-and-forget Redis persistence for cross-process durability.
+ *
+ * Redis data structures:
+ *   - Task states:  HSET {prefix}task:{taskId} field value  (one hash per task)
+ *   - Counters:     HSET {prefix}counters {key} {value}     (single hash)
+ *   - Retry counts: HSET {prefix}retries {toolCallId} {count} (single hash)
+ */
+export class RedisBudgetStore implements BudgetStore {
+  private redis: Redis;
+  private prefix: string;
+  private taskStates = new Map<string, BudgetState>();
+  private counters = new Map<string, number>();
+  private retryCounts = new Map<string, number>();
+  private _pendingWrites: Promise<void>[] = [];
+
+  constructor(redis: Redis, prefix: string = 'budget:') {
+    this.redis = redis;
+    this.prefix = prefix;
+  }
+
+  // -- Interface implementation -------------------------------------------
+
+  getTaskState(taskId: string): BudgetState | undefined {
+    return this.taskStates.get(taskId);
+  }
+
+  setTaskState(taskId: string, state: BudgetState): void {
+    this.taskStates.set(taskId, state);
+
+    const redisKey = this.prefix + 'task:' + taskId;
+    this._pendingWrites.push(
+      this.redis
+        .hset(
+          redisKey,
+          'task_id', state.task_id,
+          'workspace_id', state.workspace_id,
+          'actor_id', state.actor_id,
+          'spent_usd', String(state.spent_usd),
+          'steps', String(state.steps),
+          'started_at', state.started_at,
+        )
+        .then(() => {})
+        .catch((err) => {
+          console.error(`[redis] BudgetStore.setTaskState hset failed:`, err);
+        }),
+    );
+  }
+
+  getCounter(key: string): number {
+    return this.counters.get(key) ?? 0;
+  }
+
+  incrementCounter(key: string, amount: number): void {
+    const newVal = (this.counters.get(key) ?? 0) + amount;
+    this.counters.set(key, newVal);
+
+    const redisKey = this.prefix + 'counters';
+    this._pendingWrites.push(
+      this.redis.hset(redisKey, key, String(newVal)).then(() => {}).catch((err) => {
+        console.error(`[redis] BudgetStore.incrementCounter hset failed:`, err);
+      }),
+    );
+  }
+
+  getRetryCount(toolCallId: string): number {
+    return this.retryCounts.get(toolCallId) ?? 0;
+  }
+
+  incrementRetryCount(toolCallId: string): number {
+    const count = (this.retryCounts.get(toolCallId) ?? 0) + 1;
+    this.retryCounts.set(toolCallId, count);
+
+    const redisKey = this.prefix + 'retries';
+    this._pendingWrites.push(
+      this.redis.hset(redisKey, toolCallId, String(count)).then(() => {}).catch((err) => {
+        console.error(`[redis] BudgetStore.incrementRetryCount hset failed:`, err);
+      }),
+    );
+
+    return count;
+  }
+
+  async flush(): Promise<void> {
+    const writes = this._pendingWrites;
+    this._pendingWrites = [];
+    await Promise.all(writes);
+  }
+
+  reset(): void {
+    this.taskStates.clear();
+    this.counters.clear();
+    this.retryCounts.clear();
+
+    // Delete Redis keys in the background
+    this._scanAndDelete().catch(logRedisError('BudgetStore.reset scanAndDelete'));
+  }
+
+  getAllTaskStates(): Map<string, BudgetState> { return new Map(this.taskStates); }
+  getAllCounters(): Map<string, number> { return new Map(this.counters); }
+  getAllRetryCounts(): Map<string, number> { return new Map(this.retryCounts); }
+
+  // -- Hydrate from Redis -------------------------------------------------
+
+  /**
+   * Loads all budget data from Redis into the local cache.
+   * Call once at startup to restore state after a process restart.
+   */
+  async hydrate(): Promise<void> {
+    try {
+      // Hydrate counters
+      const countersKey = this.prefix + 'counters';
+      const countersData = await this.redis.hgetall(countersKey);
+      for (const [key, value] of Object.entries(countersData)) {
+        this.counters.set(key, Number(value));
+      }
+
+      // Hydrate retry counts
+      const retriesKey = this.prefix + 'retries';
+      const retriesData = await this.redis.hgetall(retriesKey);
+      for (const [key, value] of Object.entries(retriesData)) {
+        this.retryCounts.set(key, Number(value));
+      }
+
+      // Hydrate task states by scanning for task keys
+      const pattern = this.prefix + 'task:*';
+      let cursor = '0';
+      do {
+        const [nextCursor, keys] = await this.redis.scan(cursor, 'MATCH', pattern, 'COUNT', 100);
+        cursor = nextCursor;
+        for (const key of keys) {
+          const data = await this.redis.hgetall(key);
+          if (data && data.task_id) {
+            const state: BudgetState = {
+              task_id: data.task_id,
+              workspace_id: data.workspace_id,
+              actor_id: data.actor_id,
+              spent_usd: Number(data.spent_usd),
+              steps: Number(data.steps),
+              started_at: data.started_at,
+            };
+            this.taskStates.set(data.task_id, state);
+          }
+        }
+      } while (cursor !== '0');
+    } catch (err: any) {
+      console.error('[RedisBudgetStore] hydrate failed:', err.message);
+    }
+  }
+
+  // -- Private helpers ----------------------------------------------------
+
+  private async _scanAndDelete(): Promise<void> {
+    const pattern = this.prefix + '*';
+    let cursor = '0';
+    do {
+      const [nextCursor, keys] = await this.redis.scan(cursor, 'MATCH', pattern, 'COUNT', 100);
+      cursor = nextCursor;
+      if (keys.length > 0) {
+        await this.redis.del(...keys);
+      }
+    } while (cursor !== '0');
+  }
+}
+
+// ---------------------------------------------------------------------------
+// RedisAuditStore
+// ---------------------------------------------------------------------------
+
+/**
+ * Redis-backed audit event store using the write-through cache pattern.
+ *
+ * All AuditStore interface methods are synchronous (in-memory array),
+ * with fire-and-forget Redis persistence for cross-process durability.
+ *
+ * Redis data structures:
+ *   - Event data:      HSET {prefix}data {eventId} {json}
+ *   - Task index:      ZADD {prefix}task:{taskId} {timestamp} {eventId}
+ *   - Tool call index: ZADD {prefix}toolcall:{toolCallId} {timestamp} {eventId}
+ *   - Type index:      ZADD {prefix}type:{eventType} {timestamp} {eventId}
+ */
+export class RedisAuditStore implements AuditStore {
+  private redis: Redis;
+  private prefix: string;
+  private events: AuditEvent[] = [];
+  private _pendingWrites: Promise<void>[] = [];
+
+  constructor(redis: Redis, prefix: string = 'audit:') {
+    this.redis = redis;
+    this.prefix = prefix;
+  }
+
+  // -- Interface implementation -------------------------------------------
+
+  append(event: AuditEvent): void {
+    this.events.push(event);
+
+    const json = JSON.stringify(event);
+    const timestamp = new Date(event.timestamp).getTime();
+
+    // Store event data + update indices via tracked pending writes
+    const dataKey = this.prefix + 'data';
+    const taskKey = this.prefix + 'task:' + event.task_id;
+    const toolCallKey = this.prefix + 'toolcall:' + event.tool_call_id;
+    const typeKey = this.prefix + 'type:' + event.event_type;
+
+    const pipeline = this.redis.pipeline();
+    pipeline.hset(dataKey, event.event_id, json);
+    pipeline.zadd(taskKey, timestamp, event.event_id);
+    pipeline.zadd(toolCallKey, timestamp, event.event_id);
+    pipeline.zadd(typeKey, timestamp, event.event_id);
+
+    this._pendingWrites.push(
+      pipeline.exec().then(() => {}).catch(logRedisError('AuditStore.append pipeline')),
+    );
+  }
+
+  getByTaskId(taskId: string): AuditEvent[] {
+    return this.events
+      .filter(e => e.task_id === taskId)
+      .sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+  }
+
+  getByToolCallId(toolCallId: string): AuditEvent[] {
+    return this.events
+      .filter(e => e.tool_call_id === toolCallId)
+      .sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+  }
+
+  getByEventType(eventType: EventType): AuditEvent[] {
+    return this.events.filter(e => e.event_type === eventType);
+  }
+
+  getAll(): AuditEvent[] {
+    return [...this.events];
+  }
+
+  /** Wait for all pending Redis writes to complete. */
+  async flush(): Promise<void> {
+    const writes = this._pendingWrites;
+    this._pendingWrites = [];
+    await Promise.all(writes);
+  }
+
+  deleteByTaskId(taskId: string): void {
+    // Collect event IDs to remove from Redis data hash
+    const removed = this.events.filter(e => e.task_id === taskId);
+    this.events = this.events.filter(e => e.task_id !== taskId);
+
+    if (removed.length > 0) {
+      const dataKey = this.prefix + 'data';
+      const taskKey = this.prefix + 'task:' + taskId;
+      const pipeline = this.redis.pipeline();
+      for (const e of removed) {
+        pipeline.hdel(dataKey, e.event_id);
+        pipeline.zrem(this.prefix + 'toolcall:' + e.tool_call_id, e.event_id);
+        pipeline.zrem(this.prefix + 'type:' + e.event_type, e.event_id);
+      }
+      pipeline.del(taskKey);
+      pipeline.exec().catch(logRedisError('AuditStore.deleteByTaskId pipeline'));
+    }
+  }
+
+  deleteBySessionId(sessionId: string): void {
+    const removed = this.events.filter(e => e.session_id === sessionId);
+    this.events = this.events.filter(e => e.session_id !== sessionId);
+
+    if (removed.length > 0) {
+      const dataKey = this.prefix + 'data';
+      const pipeline = this.redis.pipeline();
+      for (const e of removed) {
+        pipeline.hdel(dataKey, e.event_id);
+        pipeline.zrem(this.prefix + 'task:' + e.task_id, e.event_id);
+        pipeline.zrem(this.prefix + 'toolcall:' + e.tool_call_id, e.event_id);
+        pipeline.zrem(this.prefix + 'type:' + e.event_type, e.event_id);
+      }
+      pipeline.exec().catch(logRedisError('AuditStore.deleteBySessionId pipeline'));
+    }
+  }
+
+  clear(): void {
+    this.events = [];
+
+    // Delete Redis keys in the background
+    this._scanAndDelete().catch(logRedisError('AuditStore.clear scanAndDelete'));
+  }
+
+  // -- Hydrate from Redis -------------------------------------------------
+
+  /**
+   * Loads all audit events from Redis into the local cache.
+   * Call once at startup to restore state after a process restart.
+   */
+  async hydrate(): Promise<void> {
+    try {
+      const dataKey = this.prefix + 'data';
+      const allData = await this.redis.hgetall(dataKey);
+
+      const events: AuditEvent[] = [];
+      for (const [, json] of Object.entries(allData)) {
+        try {
+          events.push(JSON.parse(json));
+        } catch {
+          // Skip unparseable entries
+        }
+      }
+
+      // Sort by timestamp for consistent ordering
+      events.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+      this.events = events;
+    } catch (err: any) {
+      console.error('[RedisAuditStore] hydrate failed:', err.message);
+    }
+  }
+
+  // -- Private helpers ----------------------------------------------------
+
+  private async _scanAndDelete(): Promise<void> {
+    const pattern = this.prefix + '*';
+    let cursor = '0';
+    do {
+      const [nextCursor, keys] = await this.redis.scan(cursor, 'MATCH', pattern, 'COUNT', 100);
+      cursor = nextCursor;
+      if (keys.length > 0) {
+        await this.redis.del(...keys);
+      }
+    } while (cursor !== '0');
+  }
+}
+
+// ---------------------------------------------------------------------------
+// RedisApprovalStore
+// ---------------------------------------------------------------------------
+
+/**
+ * Redis-backed approval store using the write-through cache pattern.
+ *
+ * All ApprovalStore interface methods are synchronous (in-memory Maps),
+ * with fire-and-forget Redis persistence for cross-process durability.
+ *
+ * Redis data structures:
+ *   - Approval data:    HSET {prefix}data {approvalId} {json}
+ *   - Token index:      HSET {prefix}tokens {token} {approvalId}
+ *   - Pending set:      SADD/SREM {prefix}pending {approvalId}
+ *   - Workspace index:  HSET {prefix}workspace:{wsId} {approvalId} 1
+ *   - Tool call index:  HSET {prefix}toolcall {toolCallId} {approvalId}
+ */
+export class RedisApprovalStore implements ApprovalStore {
+  private redis: Redis;
+  private prefix: string;
+  private approvals = new Map<string, ApprovalRecord>();
+  private tokenIndex = new Map<string, string>();
+  private _pendingWrites: Promise<void>[] = [];
+
+  constructor(redis: Redis, prefix: string = 'approvals:') {
+    this.redis = redis;
+    this.prefix = prefix;
+  }
+
+  // -- Interface implementation -------------------------------------------
+
+  save(approvalId: string, approval: ApprovalRecord): void {
+    const json = JSON.stringify(approval);
+    const dataKey = this.prefix + 'data';
+    const pendingKey = this.prefix + 'pending';
+
+    const pipeline = this.redis.pipeline();
+    pipeline.hset(dataKey, approvalId, json);
+
+    // Manage pending set
+    if (approval.status === 'pending') {
+      pipeline.sadd(pendingKey, approvalId);
+    } else {
+      pipeline.srem(pendingKey, approvalId);
+    }
+
+    // Workspace index
+    if (approval.workspace_id) {
+      const wsKey = this.prefix + 'workspace:' + approval.workspace_id;
+      pipeline.hset(wsKey, approvalId, '1');
+    }
+
+    // Tool call index
+    if (approval.tool_call_id) {
+      const tcKey = this.prefix + 'toolcall';
+      pipeline.hset(tcKey, approval.tool_call_id, approvalId);
+    }
+
+    // Critical store: await Redis write, update memory cache only on success
+    this._pendingWrites.push(
+      pipeline.exec().then(() => {
+        this.approvals.set(approvalId, approval);
+      }).catch((err) => {
+        // Still update memory cache as fallback, but log the error
+        this.approvals.set(approvalId, approval);
+        console.error(`[redis] ApprovalStore.save pipeline failed:`, err);
+      }),
+    );
+
+    // Eagerly set in memory for synchronous reads (will be overwritten by pipeline result)
+    this.approvals.set(approvalId, approval);
+  }
+
+  getById(approvalId: string): ApprovalRecord | undefined {
+    return this.approvals.get(approvalId);
+  }
+
+  getByToken(token: string): ApprovalRecord | undefined {
+    const id = this.tokenIndex.get(token);
+    return id ? this.approvals.get(id) : undefined;
+  }
+
+  getByToolCallId(toolCallId: string): ApprovalRecord | undefined {
+    for (const approval of this.approvals.values()) {
+      if (approval.tool_call_id === toolCallId) return approval;
+    }
+    return undefined;
+  }
+
+  findPending(workspaceId?: string): ApprovalRecord[] {
+    const results: ApprovalRecord[] = [];
+    for (const approval of this.approvals.values()) {
+      if (approval.status !== 'pending') continue;
+      if (workspaceId && approval.workspace_id !== workspaceId) continue;
+      results.push(approval);
+    }
+    return results;
+  }
+
+  indexToken(token: string, approvalId: string): void {
+    this.tokenIndex.set(token, approvalId);
+
+    const tokensKey = this.prefix + 'tokens';
+    this._pendingWrites.push(
+      this.redis.hset(tokensKey, token, approvalId).then(() => {}).catch((err) => {
+        console.error(`[redis] ApprovalStore.indexToken hset failed:`, err);
+      }),
+    );
+  }
+
+  async flush(): Promise<void> {
+    const writes = this._pendingWrites;
+    this._pendingWrites = [];
+    await Promise.all(writes);
+  }
+
+  clear(): void {
+    this.approvals.clear();
+    this.tokenIndex.clear();
+
+    // Delete Redis keys in the background
+    this._scanAndDelete().catch(logRedisError('ApprovalStore.clear scanAndDelete'));
+  }
+
+  // -- Hydrate from Redis -------------------------------------------------
+
+  /**
+   * Loads all approval data from Redis into the local cache.
+   * Call once at startup to restore state after a process restart.
+   */
+  async hydrate(): Promise<void> {
+    try {
+      // Hydrate approvals
+      const dataKey = this.prefix + 'data';
+      const allData = await this.redis.hgetall(dataKey);
+      for (const [approvalId, json] of Object.entries(allData)) {
+        try {
+          this.approvals.set(approvalId, JSON.parse(json));
+        } catch {
+          // Skip unparseable entries
+        }
+      }
+
+      // Hydrate token index
+      const tokensKey = this.prefix + 'tokens';
+      const tokenData = await this.redis.hgetall(tokensKey);
+      for (const [token, approvalId] of Object.entries(tokenData)) {
+        this.tokenIndex.set(token, approvalId);
+      }
+    } catch (err: any) {
+      console.error('[RedisApprovalStore] hydrate failed:', err.message);
+    }
+  }
+
+  // -- Private helpers ----------------------------------------------------
+
+  private async _scanAndDelete(): Promise<void> {
+    const pattern = this.prefix + '*';
+    let cursor = '0';
+    do {
+      const [nextCursor, keys] = await this.redis.scan(cursor, 'MATCH', pattern, 'COUNT', 100);
+      cursor = nextCursor;
+      if (keys.length > 0) {
+        await this.redis.del(...keys);
+      }
+    } while (cursor !== '0');
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Factory function
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates all Redis store instances with a shared prefix namespace.
+ * Since Redis is schemaless, no initialization (table creation) is needed.
+ *
+ * Usage:
+ *   const redis = new Redis('redis://localhost:6379');
+ *   const stores = createRedisStores(redis, 'myapp:');
+ *   await stores.budgetStore.hydrate();
+ *   await stores.auditStore.hydrate();
+ *   await stores.approvalStore.hydrate();
+ */
+export function createRedisStores(redis: Redis, prefix?: string): {
+  budgetStore: RedisBudgetStore;
+  auditStore: RedisAuditStore;
+  approvalStore: RedisApprovalStore;
+  rateLimitStore: RedisRateLimitStore;
+  idempotencyStore: RedisIdempotencyStore;
+} {
+  const p = prefix || '';
+  return {
+    budgetStore: new RedisBudgetStore(redis, p + 'budget:'),
+    auditStore: new RedisAuditStore(redis, p + 'audit:'),
+    approvalStore: new RedisApprovalStore(redis, p + 'approvals:'),
+    rateLimitStore: new RedisRateLimitStore(redis, p + 'rl:'),
+    idempotencyStore: new RedisIdempotencyStore(redis, p + 'idem:'),
+  };
+}