agent-tool-forge 0.3.0 → 0.4.3

package/lib/handlers/chat-resume.js

@@ -20,6 +20,16 @@ import { reactLoop } from '../react-engine.js';
 import { readBody, sendJson, loadPromotedTools, extractJwt } from '../http-utils.js';
 import { insertChatAudit } from '../db.js';
 
+async function auditLog(ctx, row) {
+  if (ctx.chatAuditStore) {
+    await ctx.chatAuditStore.insertChatAudit(row).catch(() => {});
+  } else if (ctx.db) {
+    try { insertChatAudit(ctx.db, row); } catch { /* non-fatal */ }
+  } else {
+    process.stderr.write('[audit] No audit store available — row dropped\n');
+  }
+}
+
 /**
  * @param {import('http').IncomingMessage} req
  * @param {import('http').ServerResponse} res
@@ -41,15 +51,11 @@ export async function handleChatResume(req, res, ctx) {
   // 1. Authenticate
   const authResult = auth.authenticate(req);
   if (!authResult.authenticated) {
-    if (db) {
-      try {
-        insertChatAudit(db, {
-          session_id: '', user_id: 'anon', route: '/agent-api/chat/resume',
-          status_code: 401, duration_ms: Date.now() - startTime,
-          error_message: authResult.error ?? 'Unauthorized'
-        });
-      } catch { /* non-fatal */ }
-    }
+    await auditLog(ctx, {
+      session_id: '', user_id: 'anon', route: '/agent-api/chat/resume',
+      status_code: 401, duration_ms: Date.now() - startTime,
+      error_message: authResult.error ?? 'Unauthorized'
+    });
     sendJson(res, 401, { error: authResult.error ?? 'Unauthorized' });
     return;
   }
@@ -61,15 +67,11 @@ export async function handleChatResume(req, res, ctx) {
     const rlResult = await ctx.rateLimiter.check(authResult.userId, '/agent-api/chat/resume');
     if (!rlResult.allowed) {
       res.setHeader?.('Retry-After', String(rlResult.retryAfter ?? 60));
-      if (db) {
-        try {
-          insertChatAudit(db, {
-            session_id: '', user_id: userId, route: '/agent-api/chat/resume',
-            status_code: 429, duration_ms: Date.now() - startTime,
-            error_message: 'Rate limit exceeded'
-          });
-        } catch { /* non-fatal */ }
-      }
+      await auditLog(ctx, {
+        session_id: '', user_id: userId, route: '/agent-api/chat/resume',
+        status_code: 429, duration_ms: Date.now() - startTime,
+        error_message: 'Rate limit exceeded'
+      });
       sendJson(res, 429, { error: 'Rate limit exceeded', retryAfter: rlResult.retryAfter });
       return;
     }
@@ -80,28 +82,20 @@ export async function handleChatResume(req, res, ctx) {
   try {
     body = await readBody(req);
   } catch (err) {
-    if (db) {
-      try {
-        insertChatAudit(db, {
-          session_id: '', user_id: userId, route: '/agent-api/chat/resume',
-          status_code: 413, duration_ms: Date.now() - startTime,
-          error_message: err.message
-        });
-      } catch { /* non-fatal */ }
-    }
+    await auditLog(ctx, {
+      session_id: '', user_id: userId, route: '/agent-api/chat/resume',
+      status_code: 413, duration_ms: Date.now() - startTime,
+      error_message: err.message
+    });
     sendJson(res, 413, { error: err.message });
     return;
   }
   if (!body.resumeToken) {
-    if (db) {
-      try {
-        insertChatAudit(db, {
-          session_id: '', user_id: userId, route: '/agent-api/chat/resume',
-          status_code: 400, duration_ms: Date.now() - startTime,
-          error_message: 'resumeToken is required'
-        });
-      } catch { /* non-fatal */ }
-    }
+    await auditLog(ctx, {
+      session_id: '', user_id: userId, route: '/agent-api/chat/resume',
+      status_code: 400, duration_ms: Date.now() - startTime,
+      error_message: 'resumeToken is required'
+    });
     sendJson(res, 400, { error: 'resumeToken is required' });
     return;
   }
@@ -112,30 +106,22 @@ export async function handleChatResume(req, res, ctx) {
     // (not resuming) is the same whether the token was valid or expired.
     // Clients that need to distinguish "cancelled" from "token not found"
     // should do a GET /hitl/status check before cancelling.
-    if (db) {
-      try {
-        insertChatAudit(db, {
-          session_id: '', user_id: userId, route: '/agent-api/chat/resume',
-          status_code: 200, duration_ms: Date.now() - startTime,
-          error_message: null
-        });
-      } catch { /* non-fatal */ }
-    }
+    await auditLog(ctx, {
+      session_id: '', user_id: userId, route: '/agent-api/chat/resume',
+      status_code: 200, duration_ms: Date.now() - startTime,
+      error_message: null
+    });
     sendJson(res, 200, { message: 'Cancelled' });
     return;
   }
 
   // 4. Check hitlEngine exists (only needed for actual resume)
   if (!hitlEngine) {
-    if (db) {
-      try {
-        insertChatAudit(db, {
-          session_id: '', user_id: userId, route: '/agent-api/chat/resume',
-          status_code: 501, duration_ms: Date.now() - startTime,
-          error_message: 'HITL engine not available'
-        });
-      } catch { /* non-fatal */ }
-    }
+    await auditLog(ctx, {
+      session_id: '', user_id: userId, route: '/agent-api/chat/resume',
+      status_code: 501, duration_ms: Date.now() - startTime,
+      error_message: 'HITL engine not available'
+    });
     sendJson(res, 501, { error: 'HITL engine not available' });
     return;
   }
@@ -143,15 +129,11 @@ export async function handleChatResume(req, res, ctx) {
   // 5. NOW consume the pause state
   const pausedState = await hitlEngine.resume(body.resumeToken);
   if (!pausedState) {
-    if (db) {
-      try {
-        insertChatAudit(db, {
-          session_id: '', user_id: userId, route: '/agent-api/chat/resume',
-          status_code: 404, duration_ms: Date.now() - startTime,
-          error_message: 'Resume token not found or expired'
-        });
-      } catch { /* non-fatal */ }
-    }
+    await auditLog(ctx, {
+      session_id: '', user_id: userId, route: '/agent-api/chat/resume',
+      status_code: 404, duration_ms: Date.now() - startTime,
+      error_message: 'Resume token not found or expired'
+    });
     sendJson(res, 404, { error: 'Resume token not found or expired' });
     return;
   }
@@ -164,7 +146,7 @@ export async function handleChatResume(req, res, ctx) {
 
   let agent = null;
   if (agentRegistry && pausedState.agentId) {
-    agent = agentRegistry.resolveAgent(pausedState.agentId);
+    agent = await agentRegistry.resolveAgent(pausedState.agentId);
     // If agent no longer exists/disabled, fall back to base config (graceful degradation)
   }
 
@@ -177,17 +159,13 @@ export async function handleChatResume(req, res, ctx) {
 
   // Pre-validate API key
   if (!effective.apiKey) {
-    if (db) {
-      try {
-        insertChatAudit(db, {
-          session_id: auditSessionId ?? '', user_id: userId,
-          agent_id: auditAgentId ?? null, route: '/agent-api/chat/resume',
-          status_code: 500, duration_ms: Date.now() - startTime,
-          model: auditModel ?? null,
-          error_message: `No API key configured for provider "${effective.provider}"`
-        });
-      } catch { /* non-fatal */ }
-    }
+    await auditLog(ctx, {
+      session_id: auditSessionId ?? '', user_id: userId,
+      agent_id: auditAgentId ?? null, route: '/agent-api/chat/resume',
+      status_code: 500, duration_ms: Date.now() - startTime,
+      model: auditModel ?? null,
+      error_message: `No API key configured for provider "${effective.provider}"`
+    });
     sendJson(res, 500, {
       error: `No API key configured for provider "${effective.provider}". Set the appropriate environment variable.`
     });
@@ -313,22 +291,18 @@ export async function handleChatResume(req, res, ctx) {
     sse.send('error', { type: 'error', message: err.message });
   } finally {
     sse.close();
-    if (db) {
-      try {
-        insertChatAudit(db, {
-          session_id: auditSessionId ?? '',
-          user_id: auditUserId,
-          agent_id: auditAgentId ?? null,
-          route: '/agent-api/chat/resume',
-          status_code: auditStatusCode,
-          duration_ms: Date.now() - startTime,
-          model: auditModel ?? null,
-          tool_count: auditToolCount,
-          hitl_triggered: auditHitlTriggered,
-          warnings_count: auditWarningsCount,
-          error_message: auditErrorMessage ?? null
-        });
-      } catch { /* audit failure is non-fatal */ }
-    }
+    await auditLog(ctx, {
+      session_id: auditSessionId ?? '',
+      user_id: auditUserId,
+      agent_id: auditAgentId ?? null,
+      route: '/agent-api/chat/resume',
+      status_code: auditStatusCode,
+      duration_ms: Date.now() - startTime,
+      model: auditModel ?? null,
+      tool_count: auditToolCount,
+      hitl_triggered: auditHitlTriggered,
+      warnings_count: auditWarningsCount,
+      error_message: auditErrorMessage ?? null
+    });
   }
 }

package/lib/handlers/chat-sync.js

@@ -21,6 +21,16 @@ import { reactLoop } from '../react-engine.js';
 import { readBody, sendJson, loadPromotedTools, extractJwt } from '../http-utils.js';
 import { insertChatAudit } from '../db.js';
 
+async function auditLog(ctx, row) {
+  if (ctx.chatAuditStore) {
+    await ctx.chatAuditStore.insertChatAudit(row).catch(() => {});
+  } else if (ctx.db) {
+    try { insertChatAudit(ctx.db, row); } catch { /* non-fatal */ }
+  } else {
+    process.stderr.write('[audit] No audit store available — row dropped\n');
+  }
+}
+
 /**
  * @param {import('http').IncomingMessage} req
  * @param {import('http').ServerResponse} res
@@ -33,15 +43,11 @@ export async function handleChatSync(req, res, ctx) {
   // 1. Authenticate
   const authResult = auth.authenticate(req);
   if (!authResult.authenticated) {
-    if (db) {
-      try {
-        insertChatAudit(db, {
-          session_id: '', user_id: 'anon', route: '/agent-api/chat-sync',
-          status_code: 401, duration_ms: Date.now() - startTime,
-          error_message: authResult.error ?? 'Unauthorized'
-        });
-      } catch { /* non-fatal */ }
-    }
+    await auditLog(ctx, {
+      session_id: '', user_id: 'anon', route: '/agent-api/chat-sync',
+      status_code: 401, duration_ms: Date.now() - startTime,
+      error_message: authResult.error ?? 'Unauthorized'
+    });
     sendJson(res, 401, { error: authResult.error ?? 'Unauthorized' });
     return;
   }
@@ -53,15 +59,11 @@ export async function handleChatSync(req, res, ctx) {
     const rlResult = await ctx.rateLimiter.check(userId, '/agent-api/chat-sync');
     if (!rlResult.allowed) {
       res.setHeader?.('Retry-After', String(rlResult.retryAfter ?? 60));
-      if (db) {
-        try {
-          insertChatAudit(db, {
-            session_id: '', user_id: userId, route: '/agent-api/chat-sync',
-            status_code: 429, duration_ms: Date.now() - startTime,
-            error_message: 'Rate limit exceeded'
-          });
-        } catch { /* non-fatal */ }
-      }
+      await auditLog(ctx, {
+        session_id: '', user_id: userId, route: '/agent-api/chat-sync',
+        status_code: 429, duration_ms: Date.now() - startTime,
+        error_message: 'Rate limit exceeded'
+      });
       sendJson(res, 429, { error: 'Rate limit exceeded', retryAfter: rlResult.retryAfter });
       return;
     }
@@ -72,28 +74,20 @@ export async function handleChatSync(req, res, ctx) {
   try {
     body = await readBody(req);
   } catch (err) {
-    if (db) {
-      try {
-        insertChatAudit(db, {
-          session_id: '', user_id: userId, route: '/agent-api/chat-sync',
-          status_code: 413, duration_ms: Date.now() - startTime,
-          error_message: err.message
-        });
-      } catch { /* non-fatal */ }
-    }
+    await auditLog(ctx, {
+      session_id: '', user_id: userId, route: '/agent-api/chat-sync',
+      status_code: 413, duration_ms: Date.now() - startTime,
+      error_message: err.message
+    });
     sendJson(res, 413, { error: err.message });
     return;
   }
   if (!body.message) {
-    if (db) {
-      try {
-        insertChatAudit(db, {
-          session_id: '', user_id: userId, route: '/agent-api/chat-sync',
-          status_code: 400, duration_ms: Date.now() - startTime,
-          error_message: 'message is required'
-        });
-      } catch { /* non-fatal */ }
-    }
+    await auditLog(ctx, {
+      session_id: '', user_id: userId, route: '/agent-api/chat-sync',
+      status_code: 400, duration_ms: Date.now() - startTime,
+      error_message: 'message is required'
+    });
     sendJson(res, 400, { error: 'message is required' });
     return;
   }
@@ -102,17 +96,13 @@ export async function handleChatSync(req, res, ctx) {
   const requestedAgentId = body.agentId || null;
   let agent = null;
   if (agentRegistry) {
-    agent = agentRegistry.resolveAgent(requestedAgentId);
+    agent = await agentRegistry.resolveAgent(requestedAgentId);
     if (requestedAgentId && !agent) {
-      if (db) {
-        try {
-          insertChatAudit(db, {
-            session_id: '', user_id: userId, route: '/agent-api/chat-sync',
-            status_code: 404, duration_ms: Date.now() - startTime,
-            error_message: `Agent "${requestedAgentId}" not found or disabled`
-          });
-        } catch { /* non-fatal */ }
-      }
+      await auditLog(ctx, {
+        session_id: '', user_id: userId, route: '/agent-api/chat-sync',
+        status_code: 404, duration_ms: Date.now() - startTime,
+        error_message: `Agent "${requestedAgentId}" not found or disabled`
+      });
       sendJson(res, 404, { error: `Agent "${requestedAgentId}" not found or disabled` });
       return;
     }
@@ -126,15 +116,11 @@ export async function handleChatSync(req, res, ctx) {
 
   // 6. Pre-validate API key
   if (!effective.apiKey) {
-    if (db) {
-      try {
-        insertChatAudit(db, {
-          session_id: '', user_id: userId, route: '/agent-api/chat-sync',
-          status_code: 500, duration_ms: Date.now() - startTime,
-          error_message: `No API key configured for provider "${effective.provider}"`
-        });
-      } catch { /* non-fatal */ }
-    }
+    await auditLog(ctx, {
+      session_id: '', user_id: userId, route: '/agent-api/chat-sync',
+      status_code: 500, duration_ms: Date.now() - startTime,
+      error_message: `No API key configured for provider "${effective.provider}"`
+    });
     sendJson(res, 500, {
       error: `No API key configured for provider "${effective.provider}". Set the appropriate environment variable.`
     });
@@ -301,11 +287,7 @@ export async function handleChatSync(req, res, ctx) {
     auditMeta.status_code = 500;
     auditMeta.error_message = err.message;
   } finally {
-    if (db) {
-      try {
-        insertChatAudit(db, { ...auditMeta, duration_ms: Date.now() - startTime });
-      } catch { /* audit failure is non-fatal */ }
-    }
+    await auditLog(ctx, { ...auditMeta, duration_ms: Date.now() - startTime });
   }
 
   // Persist assistant message + respond

package/lib/handlers/chat.js

@@ -17,6 +17,16 @@ import { reactLoop } from '../react-engine.js';
 import { readBody, sendJson, loadPromotedTools, extractJwt } from '../http-utils.js';
 import { insertChatAudit } from '../db.js';
 
+async function auditLog(ctx, row) {
+  if (ctx.chatAuditStore) {
+    await ctx.chatAuditStore.insertChatAudit(row).catch(() => {});
+  } else if (ctx.db) {
+    try { insertChatAudit(ctx.db, row); } catch { /* non-fatal */ }
+  } else {
+    process.stderr.write('[audit] No audit store available — row dropped\n');
+  }
+}
+
 /**
  * @param {import('http').IncomingMessage} req
  * @param {import('http').ServerResponse} res
@@ -38,15 +48,11 @@ export async function handleChat(req, res, ctx) {
   // 1. Authenticate
   const authResult = auth.authenticate(req);
   if (!authResult.authenticated) {
-    if (db) {
-      try {
-        insertChatAudit(db, {
-          session_id: '', user_id: 'anon', route: '/agent-api/chat',
-          status_code: 401, duration_ms: Date.now() - startTime,
-          error_message: authResult.error ?? 'Unauthorized'
-        });
-      } catch { /* non-fatal */ }
-    }
+    await auditLog(ctx, {
+      session_id: '', user_id: 'anon', route: '/agent-api/chat',
+      status_code: 401, duration_ms: Date.now() - startTime,
+      error_message: authResult.error ?? 'Unauthorized'
+    });
     sendJson(res, 401, { error: authResult.error ?? 'Unauthorized' });
     return;
   }
@@ -59,15 +65,11 @@ export async function handleChat(req, res, ctx) {
     const rlResult = await ctx.rateLimiter.check(userId, '/agent-api/chat');
     if (!rlResult.allowed) {
       res.setHeader?.('Retry-After', String(rlResult.retryAfter ?? 60));
-      if (db) {
-        try {
-          insertChatAudit(db, {
-            session_id: '', user_id: userId, route: '/agent-api/chat',
-            status_code: 429, duration_ms: Date.now() - startTime,
-            error_message: 'Rate limit exceeded'
-          });
-        } catch { /* non-fatal */ }
-      }
+      await auditLog(ctx, {
+        session_id: '', user_id: userId, route: '/agent-api/chat',
+        status_code: 429, duration_ms: Date.now() - startTime,
+        error_message: 'Rate limit exceeded'
+      });
       sendJson(res, 429, { error: 'Rate limit exceeded', retryAfter: rlResult.retryAfter });
       return;
     }
@@ -78,28 +80,20 @@ export async function handleChat(req, res, ctx) {
   try {
     body = await readBody(req);
   } catch (err) {
-    if (db) {
-      try {
-        insertChatAudit(db, {
-          session_id: '', user_id: userId, route: '/agent-api/chat',
-          status_code: 413, duration_ms: Date.now() - startTime,
-          error_message: err.message
-        });
-      } catch { /* non-fatal */ }
-    }
+    await auditLog(ctx, {
+      session_id: '', user_id: userId, route: '/agent-api/chat',
+      status_code: 413, duration_ms: Date.now() - startTime,
+      error_message: err.message
+    });
     sendJson(res, 413, { error: err.message });
     return;
   }
   if (!body.message) {
-    if (db) {
-      try {
-        insertChatAudit(db, {
-          session_id: '', user_id: userId, route: '/agent-api/chat',
-          status_code: 400, duration_ms: Date.now() - startTime,
-          error_message: 'message is required'
-        });
-      } catch { /* non-fatal */ }
-    }
+    await auditLog(ctx, {
+      session_id: '', user_id: userId, route: '/agent-api/chat',
+      status_code: 400, duration_ms: Date.now() - startTime,
+      error_message: 'message is required'
+    });
     sendJson(res, 400, { error: 'message is required' });
     return;
   }
@@ -108,17 +102,13 @@ export async function handleChat(req, res, ctx) {
   const requestedAgentId = body.agentId || null;
   let agent = null;
   if (agentRegistry) {
-    agent = agentRegistry.resolveAgent(requestedAgentId);
+    agent = await agentRegistry.resolveAgent(requestedAgentId);
     if (requestedAgentId && !agent) {
-      if (db) {
-        try {
-          insertChatAudit(db, {
-            session_id: '', user_id: userId, route: '/agent-api/chat',
-            status_code: 404, duration_ms: Date.now() - startTime,
-            error_message: `Agent "${requestedAgentId}" not found or disabled`
-          });
-        } catch { /* non-fatal */ }
-      }
+      await auditLog(ctx, {
+        session_id: '', user_id: userId, route: '/agent-api/chat',
+        status_code: 404, duration_ms: Date.now() - startTime,
+        error_message: `Agent "${requestedAgentId}" not found or disabled`
+      });
       sendJson(res, 404, { error: `Agent "${requestedAgentId}" not found or disabled` });
       return;
     }
@@ -132,15 +122,11 @@ export async function handleChat(req, res, ctx) {
 
   // 6. Pre-validate API key before starting SSE
   if (!effective.apiKey) {
-    if (db) {
-      try {
-        insertChatAudit(db, {
-          session_id: '', user_id: userId, route: '/agent-api/chat',
-          status_code: 500, duration_ms: Date.now() - startTime,
-          error_message: `No API key configured for provider "${effective.provider}"`
-        });
-      } catch { /* non-fatal */ }
-    }
+    await auditLog(ctx, {
+      session_id: '', user_id: userId, route: '/agent-api/chat',
+      status_code: 500, duration_ms: Date.now() - startTime,
+      error_message: `No API key configured for provider "${effective.provider}"`
+    });
     sendJson(res, 500, {
       error: `No API key configured for provider "${effective.provider}". Set the appropriate environment variable.`
     });
@@ -298,23 +284,19 @@ export async function handleChat(req, res, ctx) {
     sse.send('error', { type: 'error', message: err.message });
   } finally {
     sse.close();
-    if (db) {
-      try {
-        insertChatAudit(db, {
-          session_id: auditSessionId,
-          user_id: auditUserId,
-          agent_id: auditAgentId,
-          route: '/agent-api/chat',
-          status_code: auditStatusCode,
-          duration_ms: Date.now() - startTime,
-          model: auditModel,
-          message_text: body?.message?.slice(0, 500) ?? null,
-          tool_count: auditToolCount,
-          hitl_triggered: auditHitlTriggered,
-          warnings_count: auditWarningsCount,
-          error_message: auditErrorMessage
-        });
-      } catch { /* audit failure is non-fatal */ }
-    }
+    await auditLog(ctx, {
+      session_id: auditSessionId,
+      user_id: auditUserId,
+      agent_id: auditAgentId,
+      route: '/agent-api/chat',
+      status_code: auditStatusCode,
+      duration_ms: Date.now() - startTime,
+      model: auditModel,
+      message_text: body?.message?.slice(0, 500) ?? null,
+      tool_count: auditToolCount,
+      hitl_triggered: auditHitlTriggered,
+      warnings_count: auditWarningsCount,
+      error_message: auditErrorMessage
+    });
   }
 }

package/lib/hitl-engine.js

@@ -76,20 +76,55 @@ export class HitlEngine {
 
     // Postgres table creation is deferred to first use (_ensurePgTable)
     this._pgTableReady = false;
+    this._pgTableEnsurePromise = null;
+    this._pgCleanupTimer = null;
   }
 
   /** @private */
-  async _ensurePgTable() {
-    if (this._pgTableReady) return;
-    await this._pgPool.query(`
+  _ensurePgTable() {
+    if (this._pgTableReady) return Promise.resolve();
+    if (this._pgTableEnsurePromise) return this._pgTableEnsurePromise;
+    this._pgTableEnsurePromise = this._pgPool.query(`
       CREATE TABLE IF NOT EXISTS hitl_pending (
         resume_token TEXT PRIMARY KEY,
         state_json TEXT NOT NULL,
         expires_at TEXT NOT NULL,
         created_at TEXT NOT NULL
       )
-    `);
-    this._pgTableReady = true;
+    `).then(() => {
+      this._pgTableReady = true;
+      // Cleanup expired Postgres HITL rows every 5 minutes
+      this._pgCleanupTimer = setInterval(async () => {
+        try {
+          await this._pgPool.query(
+            'DELETE FROM hitl_pending WHERE expires_at < $1',
+            [new Date().toISOString()]
+          );
+        } catch { /* non-fatal */ }
+      }, 5 * 60 * 1000);
+      this._pgCleanupTimer.unref();
+    });
+    return this._pgTableEnsurePromise;
+  }
+
+  /**
+   * Release background timers and pooled resources held by this engine.
+   * Call this when the engine is no longer needed to avoid keeping the
+   * Node.js event loop alive.
+   */
+  destroy() {
+    if (this._cleanupTimer) {
+      clearInterval(this._cleanupTimer);
+      this._cleanupTimer = null;
+    }
+    if (this._sqliteCleanupTimer) {
+      clearInterval(this._sqliteCleanupTimer);
+      this._sqliteCleanupTimer = null;
+    }
+    if (this._pgCleanupTimer) {
+      clearInterval(this._pgCleanupTimer);
+      this._pgCleanupTimer = null;
+    }
   }
 
   /**
@@ -172,11 +207,8 @@ export class HitlEngine {
   async resume(resumeToken) {
     if (this._redis) {
       const key = REDIS_KEY_PREFIX + resumeToken;
-      // Atomic get-and-delete: use a pipeline or multi/exec
-      // For simplicity, GET then DEL — race window is acceptable for HITL
-      const stateJson = await this._redis.get(key);
+      const stateJson = await this._redis.getDel(key);
       if (!stateJson) return null;
-      await this._redis.del(key);
       try {
         return JSON.parse(stateJson);
       } catch {
@@ -187,19 +219,12 @@ export class HitlEngine {
     if (this._pgPool) {
       await this._ensurePgTable();
       const { rows } = await this._pgPool.query(
-        'SELECT * FROM hitl_pending WHERE resume_token = $1',
+        'DELETE FROM hitl_pending WHERE resume_token = $1 RETURNING *',
         [resumeToken]
       );
       if (rows.length === 0) return null;
-
       const row = rows[0];
-      // Delete regardless (one-time use)
-      await this._pgPool.query(
-        'DELETE FROM hitl_pending WHERE resume_token = $1',
-        [resumeToken]
-      );
-
-      // Check expiry
+      // Check expiry AFTER the atomic delete (expired token is gone either way)
       if (new Date(row.expires_at) < new Date()) return null;
 
       try {