web-agent-bridge 2.9.0 → 3.2.0

package/server/runtime/scheduler.js

@@ -4,15 +4,19 @@
  * WAB Runtime - Task Scheduler
  * 
  * Distributes and manages task execution with:
- * - Priority queue
+ * - External queue backend (SQLite/Redis/Memory)
+ * - Priority queue with persistent storage
  * - Retry logic with exponential backoff
  * - Timeout management
  * - Dependency resolution
  * - Concurrency control
+ * - Deterministic replay integration
+ * - Container isolation support
  */
 
 const crypto = require('crypto');
 const { bus } = require('./event-bus');
+const { createQueue } = require('./queue');
 
 // Task states
 const TaskState = {
@@ -28,10 +32,13 @@ const TaskState = {
 
 class Scheduler {
   constructor(options = {}) {
-    this._queue = [];                  // priority queue
+    this._queue = [];                  // fallback in-memory queue
+    this._externalQueue = null;        // external queue backend
     this._running = new Map();         // taskId → task
     this._completed = new Map();       // taskId → result (limited buffer)
     this._handlers = new Map();        // task type → handler function
+    this._replayEngine = null;         // optional replay integration
+    this._containerRunner = null;      // optional container isolation
     this._maxConcurrent = options.maxConcurrent || 20;
     this._maxQueueSize = options.maxQueueSize || 1000;
     this._maxCompleted = options.maxCompleted || 500;
@@ -39,6 +46,31 @@ class Scheduler {
     this._defaultTimeout = options.defaultTimeout || 30000;
     this._processing = false;
     this._stats = { submitted: 0, completed: 0, failed: 0, retried: 0, cancelled: 0, timedOut: 0 };
+
+    // Initialize external queue
+    try {
+      this._externalQueue = createQueue('scheduler', {
+        maxRetries: this._defaultRetries,
+        processTimeout: this._defaultTimeout,
+      });
+    } catch {
+      // Fallback to in-memory
+      this._externalQueue = null;
+    }
+  }
+
+  /**
+   * Attach the replay engine for deterministic recording
+   */
+  setReplayEngine(engine) {
+    this._replayEngine = engine;
+  }
+
+  /**
+   * Attach the container runner for process isolation
+   */
+  setContainerRunner(runner) {
+    this._containerRunner = runner;
   }
 
   /**
@@ -52,10 +84,6 @@ class Scheduler {
    * Submit a task to the scheduler
    */
   submit(task) {
-    if (this._queue.length >= this._maxQueueSize) {
-      throw new Error('Task queue is full');
-    }
-
     const taskEntry = {
       id: task.id || `task_${crypto.randomBytes(16).toString('hex')}`,
       type: task.type || 'general',
@@ -72,6 +100,7 @@ class Scheduler {
       retriesLeft: task.retries !== undefined ? task.retries : this._defaultRetries,
       timeout: task.timeout || this._defaultTimeout,
       deadline: task.deadline || null,
+      isolate: task.isolate || false,  // run in container if true
 
       // Dependencies
       dependsOn: task.dependsOn || [],
@@ -94,16 +123,31 @@ class Scheduler {
       checkpoints: [],
     };
 
-    // Insert by priority (higher priority = earlier in queue)
-    let inserted = false;
-    for (let i = 0; i < this._queue.length; i++) {
-      if (taskEntry.priority > this._queue[i].priority) {
-        this._queue.splice(i, 0, taskEntry);
-        inserted = true;
-        break;
+    // Add to queue (external or in-memory)
+    if (this._externalQueue) {
+      this._externalQueue.enqueue({
+        type: taskEntry.type,
+        data: taskEntry,
+        priority: taskEntry.priority,
+        maxAttempts: taskEntry.retries + 1,
+        timeoutMs: taskEntry.timeout,
+        groupId: taskEntry.agentId || null,
+      });
+    } else {
+      if (this._queue.length >= this._maxQueueSize) {
+        throw new Error('Task queue is full');
       }
+      // Insert by priority (higher priority = earlier in queue)
+      let inserted = false;
+      for (let i = 0; i < this._queue.length; i++) {
+        if (taskEntry.priority > this._queue[i].priority) {
+          this._queue.splice(i, 0, taskEntry);
+          inserted = true;
+          break;
+        }
+      }
+      if (!inserted) this._queue.push(taskEntry);
     }
-    if (!inserted) this._queue.push(taskEntry);
 
     this._stats.submitted++;
     bus.emit('task.queued', { taskId: taskEntry.id, type: taskEntry.type, priority: taskEntry.priority });
@@ -125,28 +169,43 @@ class Scheduler {
     if (this._processing) return;
     this._processing = true;
 
-    while (this._queue.length > 0 && this._running.size < this._maxConcurrent) {
-      const task = this._findNextReady();
-      if (!task) break;
-
-      // Remove from queue
-      const idx = this._queue.indexOf(task);
-      if (idx !== -1) this._queue.splice(idx, 1);
-
-      // Check deadline
-      if (task.deadline && Date.now() > task.deadline) {
-        task.state = TaskState.CANCELLED;
-        task.error = { code: 'DEADLINE_EXCEEDED', message: 'Task deadline has passed' };
-        bus.emit('task.cancelled', { taskId: task.id, reason: 'deadline' });
-        continue;
+    try {
+      while (this._running.size < this._maxConcurrent) {
+        let task = null;
+
+        if (this._externalQueue) {
+          // Dequeue from external queue
+          const item = this._externalQueue.dequeue();
+          if (!item) break;
+          task = item.data;
+          task._queueItemId = item.id;
+        } else {
+          // Dequeue from in-memory queue
+          if (this._queue.length === 0) break;
+          task = this._findNextReady();
+          if (!task) break;
+          const idx = this._queue.indexOf(task);
+          if (idx !== -1) this._queue.splice(idx, 1);
+        }
+
+        // Check deadline
+        if (task.deadline && Date.now() > task.deadline) {
+          task.state = TaskState.CANCELLED;
+          task.error = { code: 'DEADLINE_EXCEEDED', message: 'Task deadline has passed' };
+          if (this._externalQueue && task._queueItemId) {
+            this._externalQueue.fail(task._queueItemId, 'Deadline exceeded');
+          }
+          bus.emit('task.cancelled', { taskId: task.id, reason: 'deadline' });
+          continue;
+        }
+
+        // Execute
+        this._running.set(task.id, task);
+        this._executeTask(task); // fire and forget
       }
-
-      // Execute
-      this._running.set(task.id, task);
-      this._executeTask(task); // fire and forget
+    } finally {
+      this._processing = false;
     }
-
-    this._processing = false;
   }
 
   /**
@@ -174,39 +233,90 @@ class Scheduler {
 
     bus.emit('task.started', { taskId: task.id, attempt: task.attempt, type: task.type });
 
+    // Start deterministic recording
+    if (this._replayEngine) {
+      this._replayEngine.startRecording(task.id, {
+        type: task.type,
+        params: task.params,
+        objective: task.objective,
+        attempt: task.attempt,
+      });
+    }
+
     const handler = this._handlers.get(task.type);
     if (!handler) {
       task.state = TaskState.FAILED;
       task.error = { code: 'NO_HANDLER', message: `No handler for task type: ${task.type}` };
+      if (this._replayEngine) {
+        this._replayEngine.completeRecording(task.id, null, task.error);
+      }
       this._finishTask(task);
       return;
     }
 
     try {
-      const result = await _withTimeout(
-        handler(task.params, {
-          taskId: task.id,
-          agentId: task.agentId,
-          siteId: task.siteId,
-          traceId: task.traceId,
-          steps: task.steps,
-          attempt: task.attempt,
-          reportProgress: (pct, step) => {
-            task.progress = pct;
-            if (step !== undefined) task.currentStep = step;
-            bus.emit('task.progress', { taskId: task.id, progress: pct, step });
-          },
-          checkpoint: (data) => {
-            task.checkpoints.push({ data, timestamp: Date.now(), step: task.currentStep });
-          },
-        }),
-        task.timeout
-      );
+      let result;
+
+      const ctx = {
+        taskId: task.id,
+        agentId: task.agentId,
+        siteId: task.siteId,
+        traceId: task.traceId,
+        steps: task.steps,
+        attempt: task.attempt,
+        reportProgress: (pct, step) => {
+          task.progress = pct;
+          if (step !== undefined) task.currentStep = step;
+          bus.emit('task.progress', { taskId: task.id, progress: pct, step });
+        },
+        checkpoint: (data) => {
+          task.checkpoints.push({ data, timestamp: Date.now(), step: task.currentStep });
+          if (this._replayEngine) {
+            this._replayEngine.saveCheckpoint(task.id, `step-${task.currentStep}`, data);
+          }
+        },
+        recordStep: (step) => {
+          if (this._replayEngine) {
+            this._replayEngine.recordStep(task.id, step);
+          }
+        },
+        recordSideEffect: (effect) => {
+          if (this._replayEngine) {
+            this._replayEngine.recordSideEffect(task.id, effect);
+          }
+        },
+      };
+
+      // Execute in container if isolation requested
+      if (task.isolate && this._containerRunner && typeof task.params === 'object' && task.params._code) {
+        const containerResult = await this._containerRunner.runInProcess(task.id, task.params._code, {
+          params: task.params,
+          timeout: task.timeout,
+          maxMemory: task.params._maxMemory || 256 * 1024 * 1024,
+        });
+        if (!containerResult.success) {
+          throw new Error(containerResult.error || 'Container execution failed');
+        }
+        result = containerResult.result;
+      } else {
+        result = await _withTimeout(handler(task.params, ctx), task.timeout);
+      }
 
       task.state = TaskState.COMPLETED;
       task.result = result;
       task.progress = 100;
       this._stats.completed++;
+
+      // Complete recording
+      if (this._replayEngine) {
+        this._replayEngine.completeRecording(task.id, result);
+      }
+
+      // Mark complete in external queue
+      if (this._externalQueue && task._queueItemId) {
+        this._externalQueue.complete(task._queueItemId, result);
+      }
+
       bus.emit('task.completed', { taskId: task.id, duration: Date.now() - task.startedAt });
     } catch (err) {
       const isTimeout = err.message.includes('timed out');
@@ -222,7 +332,18 @@ class Scheduler {
 
         setTimeout(() => {
           this._running.delete(task.id);
-          this._queue.unshift(task); // Add back to front of queue
+          if (this._externalQueue) {
+            // Re-enqueue in external queue
+            this._externalQueue.enqueue({
+              type: task.type,
+              data: task,
+              priority: task.priority,
+              maxAttempts: task.retriesLeft + 1,
+              timeoutMs: task.timeout,
+            });
+          } else {
+            this._queue.unshift(task);
+          }
           this._processQueue();
         }, backoff);
         return;
@@ -231,6 +352,17 @@ class Scheduler {
       task.state = TaskState.FAILED;
       task.error = { code: isTimeout ? 'TIMEOUT' : 'EXECUTION_ERROR', message: err.message };
       this._stats.failed++;
+
+      // Complete recording with error
+      if (this._replayEngine) {
+        this._replayEngine.completeRecording(task.id, null, err);
+      }
+
+      // Mark failed in external queue
+      if (this._externalQueue && task._queueItemId) {
+        this._externalQueue.fail(task._queueItemId, err.message);
+      }
+
       bus.emit('task.failed', { taskId: task.id, error: err.message, attempts: task.attempt });
     }
 
@@ -347,11 +479,18 @@ class Scheduler {
    * Get scheduler stats
    */
   getStats() {
+    const queueSize = this._externalQueue
+      ? this._externalQueue.size()
+      : this._queue.length;
+
     return {
       ...this._stats,
-      queueSize: this._queue.length,
+      queueSize,
+      queueBackend: this._externalQueue ? this._externalQueue.constructor.name : 'memory',
       runningCount: this._running.size,
       completedBufferSize: this._completed.size,
+      replayEnabled: !!this._replayEngine,
+      containerEnabled: !!this._containerRunner,
     };
   }
 

package/server/services/api-key-engine.js

@@ -0,0 +1,261 @@
+/**
+ * WAB API Key Engine
+ * Authentication, authorization, rate limiting, and quota management
+ * for all WAB advanced modules.
+ *
+ * Powered by WAB — Web Agent Bridge
+ * https://www.webagentbridge.com
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+
+// ─── Plan Definitions ─────────────────────────────────────────────────────────
+const PLANS = {
+  FREE: {
+    name: 'Free',
+    price_usd: 0,
+    requests_per_day: 100,
+    requests_per_minute: 10,
+    modules_allowed: ['dark-pattern', 'price', 'protocol', 'bounty'],
+    features: {
+      agent_firewall: false, notary: false, dark_pattern: true,
+      collective_bargaining: false, gov_intelligence: false,
+      price_time_machine: true, neural: false, protocol: true,
+      bounty: true, affiliate: false,
+    },
+    support: 'community',
+    data_retention_days: 7,
+  },
+  PRO: {
+    name: 'Pro',
+    price_usd: 29,
+    requests_per_day: 10000,
+    requests_per_minute: 100,
+    modules_allowed: ['agent-firewall', 'dark-pattern', 'neural', 'bounty', 'affiliate', 'protocol', 'price', 'bargaining'],
+    features: {
+      agent_firewall: true, notary: false, dark_pattern: true,
+      collective_bargaining: true, gov_intelligence: false,
+      price_time_machine: true, neural: true, protocol: true,
+      bounty: true, affiliate: true,
+    },
+    support: 'email',
+    data_retention_days: 90,
+  },
+  BUSINESS: {
+    name: 'Business',
+    price_usd: 149,
+    requests_per_day: 100000,
+    requests_per_minute: 500,
+    modules_allowed: ['all'],
+    features: {
+      agent_firewall: true, notary: true, dark_pattern: true,
+      collective_bargaining: true, gov_intelligence: true,
+      price_time_machine: true, neural: true, protocol: true,
+      bounty: true, affiliate: true,
+    },
+    support: 'priority',
+    data_retention_days: 365,
+  },
+  ENTERPRISE: {
+    name: 'Enterprise',
+    price_usd: null,
+    requests_per_day: Infinity,
+    requests_per_minute: Infinity,
+    modules_allowed: ['all'],
+    features: {
+      agent_firewall: true, notary: true, dark_pattern: true,
+      collective_bargaining: true, gov_intelligence: true,
+      price_time_machine: true, neural: true, protocol: true,
+      bounty: true, affiliate: true,
+    },
+    support: 'dedicated',
+    data_retention_days: Infinity,
+    custom_sla: true,
+    on_premise: true,
+  },
+  INTERNAL: {
+    name: 'Internal',
+    price_usd: 0,
+    requests_per_day: Infinity,
+    requests_per_minute: Infinity,
+    modules_allowed: ['all'],
+    features: Object.fromEntries(
+      ['agent_firewall','notary','dark_pattern','collective_bargaining','gov_intelligence',
+       'price_time_machine','neural','protocol','bounty','affiliate'].map(k => [k, true])
+    ),
+    support: 'internal',
+    data_retention_days: Infinity,
+  },
+};
+
+const keyStore = new Map();
+const usageStore = new Map();
+const rateLimitStore = new Map();
+
+class WABKeyEngine {
+  constructor() {
+    this.internalKey = this._seedInternalKeys();
+  }
+
+  _seedInternalKeys() {
+    const internalKey = 'wab_internal_' + crypto.randomBytes(16).toString('hex');
+    keyStore.set(internalKey, {
+      key: internalKey, key_id: 'kid_internal_001', plan: 'INTERNAL',
+      owner: 'WAB Core Team', email: 'dev@webagentbridge.com',
+      environment: 'internal', created_at: new Date().toISOString(),
+      last_used: null, active: true, scopes: ['*'],
+    });
+    return internalKey;
+  }
+
+  generateKey(options = {}) {
+    const { plan = 'FREE', owner, email, environment = 'live', scopes = [], metadata = {} } = options;
+    if (!PLANS[plan]) throw new Error(`Invalid plan: ${plan}`);
+    if (!owner) throw new Error('owner is required');
+    if (!email) throw new Error('email is required');
+
+    const planPrefix = plan.toLowerCase().substring(0, 3);
+    const randomPart = crypto.randomBytes(20).toString('hex');
+    const apiKey = `wab_${environment}_${planPrefix}_${randomPart}`;
+    const keyId = 'kid_' + crypto.randomBytes(8).toString('hex');
+    const webhookSecret = 'whsec_' + crypto.randomBytes(24).toString('hex');
+
+    const keyRecord = {
+      key: apiKey, key_id: keyId, plan, plan_details: PLANS[plan],
+      owner, email, environment,
+      created_at: new Date().toISOString(),
+      expires_at: plan === 'FREE' ? new Date(Date.now() + 365 * 86400000).toISOString() : null,
+      last_used: null, active: true,
+      scopes: scopes.length > 0 ? scopes : this._defaultScopes(plan),
+      webhook_secret: webhookSecret, metadata, total_requests: 0,
+    };
+
+    keyStore.set(apiKey, keyRecord);
+    usageStore.set(apiKey, { today: 0, this_month: 0, total: 0, by_module: {}, by_day: {}, last_reset: new Date().toDateString() });
+
+    return {
+      api_key: apiKey, key_id: keyId, webhook_secret: webhookSecret, plan,
+      plan_details: { name: PLANS[plan].name, requests_per_day: PLANS[plan].requests_per_day, requests_per_minute: PLANS[plan].requests_per_minute, modules_allowed: PLANS[plan].modules_allowed },
+      created_at: keyRecord.created_at, expires_at: keyRecord.expires_at,
+    };
+  }
+
+  validate(apiKey, module = null) {
+    if (!apiKey) return { valid: false, error: 'API key is required', code: 'MISSING_KEY' };
+    const record = keyStore.get(apiKey);
+    if (!record) return { valid: false, error: 'Invalid API key', code: 'INVALID_KEY' };
+    if (!record.active) return { valid: false, error: 'API key has been revoked', code: 'REVOKED_KEY' };
+    if (record.expires_at && new Date(record.expires_at) < new Date()) {
+      return { valid: false, error: 'API key has expired', code: 'EXPIRED_KEY' };
+    }
+
+    if (module) {
+      const plan = PLANS[record.plan];
+      const hasAccess = plan.modules_allowed.includes('all') || plan.modules_allowed.includes(module);
+      if (!hasAccess) {
+        return { valid: false, error: `Module '${module}' not available on ${plan.name} plan`, code: 'INSUFFICIENT_PLAN',
+          upgrade_url: 'https://www.webagentbridge.com/#pricing', current_plan: plan.name, required_plan: this._getMinPlanForModule(module) };
+      }
+    }
+
+    const rateCheck = this._checkRateLimit(apiKey, record.plan);
+    if (!rateCheck.allowed) {
+      return { valid: false, error: 'Rate limit exceeded', code: 'RATE_LIMIT_EXCEEDED', retry_after_seconds: rateCheck.retry_after, limit: rateCheck.limit };
+    }
+
+    const usage = usageStore.get(apiKey);
+    this._resetDailyIfNeeded(apiKey, usage);
+    const plan = PLANS[record.plan];
+    if (usage.today >= plan.requests_per_day) {
+      return { valid: false, error: 'Daily quota exceeded', code: 'QUOTA_EXCEEDED', used: usage.today, limit: plan.requests_per_day, upgrade_url: 'https://www.webagentbridge.com/#pricing' };
+    }
+
+    this._recordUsage(apiKey, module);
+    return { valid: true, key_id: record.key_id, plan: record.plan, plan_name: plan.name, owner: record.owner, environment: record.environment, features: plan.features,
+      usage: { today: usage.today + 1, limit_today: plan.requests_per_day, remaining_today: plan.requests_per_day - usage.today - 1 } };
+  }
+
+  revoke(apiKey, reason = 'user_request') {
+    const record = keyStore.get(apiKey);
+    if (!record) return { success: false, error: 'Key not found' };
+    record.active = false; record.revoked_at = new Date().toISOString(); record.revoke_reason = reason;
+    return { success: true, message: 'Key revoked', revoked_at: record.revoked_at };
+  }
+
+  rotate(oldKey) {
+    const record = keyStore.get(oldKey);
+    if (!record) return { success: false, error: 'Key not found' };
+    this.revoke(oldKey, 'rotation');
+    return { success: true, ...this.generateKey({ plan: record.plan, owner: record.owner, email: record.email, environment: record.environment, metadata: { ...record.metadata, rotated_from: record.key_id } }) };
+  }
+
+  getUsage(apiKey) {
+    const record = keyStore.get(apiKey);
+    if (!record) return { error: 'Key not found' };
+    const usage = usageStore.get(apiKey) || {};
+    this._resetDailyIfNeeded(apiKey, usage);
+    const plan = PLANS[record.plan];
+    return { key_id: record.key_id, plan: record.plan, plan_name: plan.name, today: usage.today, this_month: usage.this_month, total: usage.total,
+      limit_per_day: plan.requests_per_day, limit_per_minute: plan.requests_per_minute, remaining_today: Math.max(0, plan.requests_per_day - usage.today),
+      by_module: usage.by_module, last_used: record.last_used, created_at: record.created_at };
+  }
+
+  listKeys(adminKey) {
+    const adminRecord = keyStore.get(adminKey);
+    if (!adminRecord || adminRecord.plan !== 'INTERNAL') return { error: 'Admin access required' };
+    return { total: keyStore.size, keys: Array.from(keyStore.values()).map(r => ({
+      key_id: r.key_id, plan: r.plan, owner: r.owner, email: r.email, environment: r.environment, active: r.active,
+      created_at: r.created_at, last_used: r.last_used, total_requests: r.total_requests || 0 })) };
+  }
+
+  getPlans() {
+    return Object.entries(PLANS).filter(([k]) => k !== 'INTERNAL').map(([key, plan]) => ({
+      id: key, name: plan.name, price_usd: plan.price_usd, requests_per_day: plan.requests_per_day,
+      requests_per_minute: plan.requests_per_minute, features: plan.features, support: plan.support }));
+  }
+
+  _checkRateLimit(apiKey, plan) {
+    const limit = PLANS[plan].requests_per_minute;
+    if (limit === Infinity) return { allowed: true };
+    const now = Date.now(); const window = 60000;
+    const rl = rateLimitStore.get(apiKey) || { count: 0, windowStart: now };
+    if (now - rl.windowStart > window) { rl.count = 0; rl.windowStart = now; }
+    if (rl.count >= limit) { return { allowed: false, retry_after: Math.ceil((rl.windowStart + window - now) / 1000), limit }; }
+    rl.count++; rateLimitStore.set(apiKey, rl);
+    return { allowed: true };
+  }
+
+  _recordUsage(apiKey, module) {
+    const record = keyStore.get(apiKey); const usage = usageStore.get(apiKey);
+    const today = new Date().toISOString().split('T')[0];
+    usage.today++; usage.this_month++; usage.total++;
+    if (module) usage.by_module[module] = (usage.by_module[module] || 0) + 1;
+    usage.by_day[today] = (usage.by_day[today] || 0) + 1;
+    record.last_used = new Date().toISOString();
+    record.total_requests = (record.total_requests || 0) + 1;
+  }
+
+  _resetDailyIfNeeded(apiKey, usage) {
+    const today = new Date().toDateString();
+    if (usage.last_reset !== today) { usage.today = 0; usage.last_reset = today; usageStore.set(apiKey, usage); }
+  }
+
+  _defaultScopes(plan) {
+    if (plan === 'FREE') return ['read'];
+    if (plan === 'PRO') return ['read', 'write'];
+    return ['read', 'write', 'admin'];
+  }
+
+  _getMinPlanForModule(module) {
+    const map = { 'agent-firewall': 'PRO', 'notary': 'BUSINESS', 'dark-pattern': 'FREE', 'bargaining': 'PRO', 'gov': 'BUSINESS', 'price': 'FREE', 'neural': 'PRO', 'protocol': 'FREE', 'bounty': 'FREE', 'affiliate': 'PRO' };
+    return map[module] || 'PRO';
+  }
+
+  _nextMidnight() {
+    const d = new Date(); d.setDate(d.getDate() + 1); d.setHours(0, 0, 0, 0); return d.toISOString();
+  }
+}
+
+module.exports = { WABKeyEngine, PLANS };

package/server/services/lfd.js

@@ -277,11 +277,10 @@ class RecipeExecutor {
       errors: [],
     };
 
-    // Variable substitution in steps
+    // Variable substitution in steps — substitute in all string fields
     if (Object.keys(execution.variables).length > 0) {
       for (const step of execution.steps) {
-        if (step.value) step.value = this._substituteVars(step.value, execution.variables);
-        if (step.url) step.url = this._substituteVars(step.url, execution.variables);
+        this._substituteStepVars(step, execution.variables);
       }
     }
 
@@ -379,6 +378,23 @@ class RecipeExecutor {
     return str.replace(/\{\{(\w+)\}\}/g, (_, key) => vars[key] !== undefined ? String(vars[key]) : `{{${key}}}`);
   }
 
+  _substituteStepVars(step, vars) {
+    if (step.value) step.value = this._substituteVars(step.value, vars);
+    if (step.url) step.url = this._substituteVars(step.url, vars);
+    if (step.selector) step.selector = this._substituteVars(step.selector, vars);
+    if (step.description) step.description = this._substituteVars(step.description, vars);
+    if (step.fallback) {
+      if (step.fallback.text) step.fallback.text = this._substituteVars(step.fallback.text, vars);
+      if (step.fallback.xpath) step.fallback.xpath = this._substituteVars(step.fallback.xpath, vars);
+      if (step.fallback.ariaLabel) step.fallback.ariaLabel = this._substituteVars(step.fallback.ariaLabel, vars);
+    }
+    if (step.options && typeof step.options === 'object') {
+      for (const k of Object.keys(step.options)) {
+        if (typeof step.options[k] === 'string') step.options[k] = this._substituteVars(step.options[k], vars);
+      }
+    }
+  }
+
   getStats() {
     const execs = [...this.executions.values()];
     return {
@@ -447,6 +463,9 @@ class LfdEngine {
   stopRecording(sessionId) {
     const session = this.sessions.get(sessionId);
     if (!session) throw new Error('Recording session not found');
+    if (session.status !== 'recording' && session.status !== 'paused') {
+      throw new Error(`Cannot stop recording in state: ${session.status}`);
+    }
     session.complete();
 
     // Auto-convert to recipe