reqon-dsl 0.2.0 → 0.4.0

package/dist/pause/manager.js

@@ -0,0 +1,294 @@
+/**
+ * Pause Manager - Orchestrates resource-free long pauses
+ *
+ * Handles pause creation, monitoring, and resume coordination.
+ * Integrates with webhook server for webhook-based resume triggers.
+ */
+import { createPauseState, parseDuration, isPauseExpired, getRemainingTime, formatDuration, } from './state.js';
+/**
+ * Manages resource-free long pauses
+ */
+export class PauseManager {
+    config;
+    pollTimer;
+    isRunning = false;
+    // Pause ids currently being resumed. Claimed synchronously before any await
+    // so a timeout poll and an inbound webhook can't both resume the same pause.
+    resuming = new Set();
+    // Prevents a slow resume cycle from overlapping the next poll tick.
+    isCheckingExpired = false;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Create a new pause and persist state
+     */
+    async createPause(options) {
+        const duration = parseDuration(options.duration);
+        // Build resume trigger states
+        const resumeTriggers = [];
+        // Always include timeout by default
+        const triggers = options.resumeTriggers ?? [{ type: 'timeout' }];
+        const hasTimeout = triggers.some((t) => t.type === 'timeout');
+        if (!hasTimeout) {
+            triggers.push({ type: 'timeout' });
+        }
+        for (const trigger of triggers) {
+            if (trigger.type === 'timeout') {
+                resumeTriggers.push({ type: 'timeout', active: true });
+            }
+            else if (trigger.type === 'webhook') {
+                const triggerState = {
+                    type: 'webhook',
+                    path: trigger.path,
+                    active: true,
+                };
+                // Register webhook if server available
+                if (this.config.webhookServer) {
+                    const registration = await this.registerWebhookTrigger(options.executionId, trigger.path, duration);
+                    triggerState.registrationId = registration.id;
+                }
+                resumeTriggers.push(triggerState);
+            }
+        }
+        // Create pause state
+        const pause = createPauseState(options.executionId, options.mission, duration, options.checkpoint, resumeTriggers);
+        // Persist
+        await this.config.store.save(pause);
+        this.log(`Created pause ${pause.id} for ${formatDuration(duration)}`);
+        return pause;
+    }
+    /**
+     * Resume a pause manually
+     */
+    async resumeManually(pauseId) {
+        const pause = await this.config.store.load(pauseId);
+        if (!pause) {
+            throw new Error(`Pause not found: ${pauseId}`);
+        }
+        if (pause.status !== 'waiting') {
+            throw new Error(`Pause ${pauseId} is not waiting (status: ${pause.status})`);
+        }
+        const resumed = await this.markResumed(pause, 'manual');
+        if (!resumed) {
+            // Lost a race with another resume trigger; return the resolved state.
+            const current = await this.config.store.load(pauseId);
+            if (!current)
+                throw new Error(`Pause not found: ${pauseId}`);
+            return current;
+        }
+        return resumed;
+    }
+    /**
+     * Resume a pause by execution ID
+     */
+    async resumeByExecution(executionId) {
+        const pause = await this.config.store.loadByExecution(executionId);
+        if (!pause) {
+            return null;
+        }
+        return this.resumeManually(pause.id);
+    }
+    /**
+     * Cancel a pause (without resuming execution)
+     */
+    async cancelPause(pauseId) {
+        const pause = await this.config.store.load(pauseId);
+        if (!pause) {
+            throw new Error(`Pause not found: ${pauseId}`);
+        }
+        if (pause.status !== 'waiting') {
+            return; // Already not waiting
+        }
+        await this.config.store.update(pauseId, {
+            status: 'cancelled',
+            resumedAt: new Date(),
+            resumedBy: 'cancelled',
+        });
+        // Cleanup webhook registrations
+        await this.cleanupWebhooks(pause);
+        this.log(`Cancelled pause ${pauseId}`);
+    }
+    /**
+     * Handle webhook callback for a pause
+     */
+    async handleWebhook(pauseId, payload) {
+        const pause = await this.config.store.load(pauseId);
+        if (!pause || pause.status !== 'waiting') {
+            return false;
+        }
+        // Check if this pause has an active webhook trigger
+        const webhookTrigger = pause.resumeTriggers.find((t) => t.type === 'webhook' && t.active);
+        if (!webhookTrigger) {
+            return false;
+        }
+        // Mark resumed with webhook payload; false if another trigger won the race.
+        const resumed = await this.markResumed(pause, 'webhook', payload);
+        return resumed !== null;
+    }
+    /**
+     * Start monitoring for expired pauses
+     */
+    startMonitoring() {
+        if (this.isRunning)
+            return;
+        this.isRunning = true;
+        const interval = this.config.pollInterval ?? 60000; // Default: 1 minute
+        this.pollTimer = setInterval(async () => {
+            await this.checkExpiredPauses();
+        }, interval);
+        this.log(`Started pause monitoring (interval: ${formatDuration(interval)})`);
+    }
+    /**
+     * Stop monitoring
+     */
+    stopMonitoring() {
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = undefined;
+        }
+        this.isRunning = false;
+        this.log('Stopped pause monitoring');
+    }
+    /**
+     * Check for and process expired pauses
+     */
+    async checkExpiredPauses() {
+        // Overlap guard: if a prior cycle's resume callbacks are still running when
+        // the next poll fires, skip rather than reprocessing the same pauses.
+        if (this.isCheckingExpired)
+            return [];
+        this.isCheckingExpired = true;
+        try {
+            const expired = await this.config.store.findExpired();
+            const resumed = [];
+            for (const pause of expired) {
+                const updated = await this.markResumed(pause, 'timeout');
+                // null means another trigger already resumed this pause — skip it.
+                if (updated)
+                    resumed.push(updated);
+            }
+            return resumed;
+        }
+        finally {
+            this.isCheckingExpired = false;
+        }
+    }
+    /**
+     * Get all active pauses
+     */
+    async getActivePauses() {
+        return this.config.store.listActive();
+    }
+    /**
+     * Get pause by ID
+     */
+    async getPause(pauseId) {
+        return this.config.store.load(pauseId);
+    }
+    /**
+     * Get pause status summary
+     */
+    async getStatus() {
+        const active = await this.config.store.listActive();
+        const expired = active.filter((p) => isPauseExpired(p));
+        const waiting = active.filter((p) => !isPauseExpired(p));
+        return {
+            totalActive: active.length,
+            waiting: waiting.length,
+            expired: expired.length,
+            nextExpiration: waiting.length > 0
+                ? waiting.reduce((min, p) => (p.expiresAt < min ? p.expiresAt : min), waiting[0].expiresAt)
+                : undefined,
+            pauses: active.map((p) => ({
+                id: p.id,
+                mission: p.mission,
+                executionId: p.executionId,
+                remaining: getRemainingTime(p),
+                remainingFormatted: formatDuration(getRemainingTime(p)),
+            })),
+        };
+    }
+    /**
+     * Transition a pause to `resumed` and fire `onResume` exactly once.
+     *
+     * Returns the resumed pause, or `null` if this call lost the race (another
+     * resume already claimed it, or it is no longer waiting). The claim on
+     * `this.resuming` is synchronous — taken before any `await` — so two
+     * concurrent callers (e.g. the timeout poller and an inbound webhook) can't
+     * both pass the status check and double-fire the side-effecting tail. The
+     * persisted-status re-check makes resume idempotent across poll cycles too.
+     */
+    async markResumed(pause, resumedBy, webhookPayload) {
+        if (this.resuming.has(pause.id)) {
+            return null; // another resume is already in flight for this pause
+        }
+        this.resuming.add(pause.id);
+        try {
+            // Re-read the source of truth: a prior cycle may already have resumed it.
+            const current = await this.config.store.load(pause.id);
+            if (!current || current.status !== 'waiting') {
+                return null;
+            }
+            const updates = {
+                status: 'resumed',
+                resumedAt: new Date(),
+                resumedBy,
+            };
+            if (webhookPayload !== undefined) {
+                updates.webhookPayload = webhookPayload;
+            }
+            await this.config.store.update(pause.id, updates);
+            // Cleanup webhook registrations
+            await this.cleanupWebhooks(current);
+            const updated = await this.config.store.load(pause.id);
+            if (!updated) {
+                throw new Error(`Failed to load updated pause: ${pause.id}`);
+            }
+            this.log(`Pause ${pause.id} resumed by ${resumedBy}`);
+            // Trigger callback (the side-effecting pipeline tail) exactly once.
+            if (this.config.onResume) {
+                await this.config.onResume(updated);
+            }
+            return updated;
+        }
+        finally {
+            this.resuming.delete(pause.id);
+        }
+    }
+    async registerWebhookTrigger(executionId, path, timeout) {
+        if (!this.config.webhookServer) {
+            throw new Error('Webhook server not configured for webhook triggers');
+        }
+        // Register a webhook listener that will call handleWebhook
+        const registration = await this.config.webhookServer.register(executionId, {
+            path,
+            timeout,
+            expectedEvents: 1,
+        });
+        return { id: registration.id };
+    }
+    async cleanupWebhooks(pause) {
+        if (!this.config.webhookServer)
+            return;
+        for (const trigger of pause.resumeTriggers) {
+            if (trigger.type === 'webhook' && trigger.registrationId) {
+                try {
+                    await this.config.webhookServer.unregister(trigger.registrationId);
+                }
+                catch {
+                    // Ignore cleanup errors
+                }
+            }
+        }
+    }
+    log(message) {
+        this.config.log?.(`[PauseManager] ${message}`);
+    }
+}
+/**
+ * Create a pause manager
+ */
+export function createPauseManager(config) {
+    return new PauseManager(config);
+}

package/dist/pause/state.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Pause State - Types for resource-free long pauses
+ *
+ * Supports pausing execution for extended periods (days/weeks)
+ * while persisting state and releasing resources.
+ */
+/**
+ * Persisted pause state
+ */
+export interface PauseState {
+    /** Unique pause ID */
+    id: string;
+    /** Execution ID this pause belongs to */
+    executionId: string;
+    /** Mission name */
+    mission: string;
+    /** When the pause started */
+    pausedAt: Date;
+    /** When the pause will expire (resume due to timeout) */
+    expiresAt: Date;
+    /** Original duration specified (in milliseconds) */
+    duration: number;
+    /** Current status */
+    status: 'waiting' | 'resumed' | 'expired' | 'cancelled';
+    /** How the pause was resumed (if resumed) */
+    resumedBy?: 'timeout' | 'webhook' | 'manual' | 'cancelled';
+    /** When resumed */
+    resumedAt?: Date;
+    /** Resume trigger configuration */
+    resumeTriggers: PauseResumeTriggerState[];
+    /** Checkpoint data for resuming execution */
+    checkpoint: PauseCheckpoint;
+    /** Webhook data if resumed by webhook */
+    webhookPayload?: unknown;
+}
+/**
+ * Resume trigger state
+ */
+export interface PauseResumeTriggerState {
+    type: 'timeout' | 'webhook';
+    /** For webhook: the registered path */
+    path?: string;
+    /** For webhook: registration ID */
+    registrationId?: string;
+    /** Whether this trigger is active */
+    active: boolean;
+}
+/**
+ * Checkpoint data for resuming after pause
+ */
+export interface PauseCheckpoint {
+    /** Stage index to resume from */
+    stageIndex: number;
+    /** Step index within action to resume from (after pause step) */
+    stepIndex: number;
+    /** Current action name */
+    action: string;
+    /** For loops: current item index */
+    itemIndex?: number;
+    /** Saved context variables */
+    variables: Record<string, unknown>;
+    /** Saved response value */
+    response?: unknown;
+}
+/**
+ * Generate a unique pause ID
+ */
+export declare function generatePauseId(executionId: string): string;
+/**
+ * Parse duration string to milliseconds
+ * Supports: "7d", "1d", "12h", "30m", "45s", or raw milliseconds
+ */
+export declare function parseDuration(duration: string | number): number;
+/**
+ * Format duration for display
+ */
+export declare function formatDuration(ms: number): string;
+/**
+ * Create initial pause state
+ */
+export declare function createPauseState(executionId: string, mission: string, duration: number, checkpoint: PauseCheckpoint, resumeTriggers: PauseResumeTriggerState[]): PauseState;
+/**
+ * Check if a pause has expired
+ */
+export declare function isPauseExpired(pause: PauseState): boolean;
+/**
+ * Get remaining time for a pause (in milliseconds)
+ */
+export declare function getRemainingTime(pause: PauseState): number;
+/**
+ * Get pause summary for display
+ */
+export declare function getPauseSummary(pause: PauseState): string;

package/dist/pause/state.js

@@ -0,0 +1,103 @@
+/**
+ * Pause State - Types for resource-free long pauses
+ *
+ * Supports pausing execution for extended periods (days/weeks)
+ * while persisting state and releasing resources.
+ */
+/**
+ * Generate a unique pause ID
+ */
+export function generatePauseId(executionId) {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).substring(2, 6);
+    return `pause_${executionId}_${timestamp}_${random}`;
+}
+/**
+ * Parse duration string to milliseconds
+ * Supports: "7d", "1d", "12h", "30m", "45s", or raw milliseconds
+ */
+export function parseDuration(duration) {
+    if (typeof duration === 'number') {
+        return duration;
+    }
+    const match = duration.match(/^(\d+(?:\.\d+)?)\s*(d|h|m|s|ms)?$/i);
+    if (!match) {
+        throw new Error(`Invalid duration format: ${duration}. Use "7d", "12h", "30m", "45s", or milliseconds.`);
+    }
+    const value = parseFloat(match[1]);
+    const unit = (match[2] || 'ms').toLowerCase();
+    const multipliers = {
+        ms: 1,
+        s: 1000,
+        m: 60 * 1000,
+        h: 60 * 60 * 1000,
+        d: 24 * 60 * 60 * 1000,
+    };
+    const multiplier = multipliers[unit];
+    if (multiplier === undefined) {
+        throw new Error(`Unknown duration unit: ${unit}`);
+    }
+    return Math.round(value * multiplier);
+}
+/**
+ * Format duration for display
+ */
+export function formatDuration(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    if (ms < 60 * 1000)
+        return `${(ms / 1000).toFixed(1)}s`;
+    if (ms < 60 * 60 * 1000)
+        return `${(ms / (60 * 1000)).toFixed(1)}m`;
+    if (ms < 24 * 60 * 60 * 1000)
+        return `${(ms / (60 * 60 * 1000)).toFixed(1)}h`;
+    return `${(ms / (24 * 60 * 60 * 1000)).toFixed(1)}d`;
+}
+/**
+ * Create initial pause state
+ */
+export function createPauseState(executionId, mission, duration, checkpoint, resumeTriggers) {
+    const now = new Date();
+    return {
+        id: generatePauseId(executionId),
+        executionId,
+        mission,
+        pausedAt: now,
+        expiresAt: new Date(now.getTime() + duration),
+        duration,
+        status: 'waiting',
+        resumeTriggers,
+        checkpoint,
+    };
+}
+/**
+ * Check if a pause has expired
+ */
+export function isPauseExpired(pause) {
+    return pause.status === 'waiting' && new Date() >= pause.expiresAt;
+}
+/**
+ * Get remaining time for a pause (in milliseconds)
+ */
+export function getRemainingTime(pause) {
+    if (pause.status !== 'waiting')
+        return 0;
+    const remaining = pause.expiresAt.getTime() - Date.now();
+    return Math.max(0, remaining);
+}
+/**
+ * Get pause summary for display
+ */
+export function getPauseSummary(pause) {
+    const remaining = getRemainingTime(pause);
+    if (pause.status === 'resumed') {
+        return `Pause ${pause.id}: resumed by ${pause.resumedBy} at ${pause.resumedAt?.toISOString()}`;
+    }
+    if (pause.status === 'expired') {
+        return `Pause ${pause.id}: expired at ${pause.expiresAt.toISOString()}`;
+    }
+    if (pause.status === 'cancelled') {
+        return `Pause ${pause.id}: cancelled`;
+    }
+    return `Pause ${pause.id}: waiting (${formatDuration(remaining)} remaining)`;
+}

package/dist/pause/store.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Pause Store - Persistence for pause states
+ *
+ * Stores pause state for resource-free long pauses,
+ * enabling resumption after extended periods.
+ */
+import type { PauseState } from './state.js';
+/**
+ * Pause store interface
+ */
+export interface PauseStore {
+    /** Save a pause state */
+    save(pause: PauseState): Promise<void>;
+    /** Load a pause by ID */
+    load(id: string): Promise<PauseState | null>;
+    /** Load pause by execution ID */
+    loadByExecution(executionId: string): Promise<PauseState | null>;
+    /** List all active (waiting) pauses */
+    listActive(): Promise<PauseState[]>;
+    /** List pauses for a mission */
+    listByMission(mission: string): Promise<PauseState[]>;
+    /** Delete a pause state */
+    delete(id: string): Promise<void>;
+    /** Find pauses that have expired but not yet processed */
+    findExpired(): Promise<PauseState[]>;
+    /** Update pause state (e.g., when resumed) */
+    update(id: string, updates: Partial<PauseState>): Promise<void>;
+}
+/**
+ * File-based pause store
+ */
+export declare class FilePauseStore implements PauseStore {
+    private baseDir;
+    private initialized;
+    constructor(baseDir?: string);
+    private getFilePath;
+    private deserialize;
+    save(pause: PauseState): Promise<void>;
+    load(id: string): Promise<PauseState | null>;
+    loadByExecution(executionId: string): Promise<PauseState | null>;
+    listActive(): Promise<PauseState[]>;
+    listByMission(mission: string): Promise<PauseState[]>;
+    delete(id: string): Promise<void>;
+    findExpired(): Promise<PauseState[]>;
+    update(id: string, updates: Partial<PauseState>): Promise<void>;
+}
+/**
+ * In-memory pause store (for testing)
+ */
+export declare class MemoryPauseStore implements PauseStore {
+    private pauses;
+    save(pause: PauseState): Promise<void>;
+    load(id: string): Promise<PauseState | null>;
+    loadByExecution(executionId: string): Promise<PauseState | null>;
+    listActive(): Promise<PauseState[]>;
+    listByMission(mission: string): Promise<PauseState[]>;
+    delete(id: string): Promise<void>;
+    findExpired(): Promise<PauseState[]>;
+    update(id: string, updates: Partial<PauseState>): Promise<void>;
+    clear(): void;
+}