@orbytautomation/engine 0.8.4 → 0.9.0

package/dist/core/OrbytEngine.js

@@ -82,9 +82,9 @@ import { CLIAdapter, ShellAdapter, HTTPAdapter, FSAdapter } from '../adapters/bu
 import { InternalContextBuilder } from '../execution/InternalExecutionContext.js';
 import { IntentAnalyzer } from '../execution/IntentAnalyzer.js';
 import { ExecutionStrategyResolver, ExecutionStrategyGuard } from '../execution/ExecutionStrategyResolver.js';
-import { EngineEventType, } from '../types/core-types.js';
+import { EngineEventType } from '../types/core-types.js';
 import { ExplanationGenerator, ExplanationLogger } from '../explanation/index.js';
-import { existsSync, mkdirSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { ExecutionStore } from '../storage/ExecutionStore.js';
@@ -92,6 +92,11 @@ import { WorkflowStore } from '../storage/WorkflowStore.js';
 import { ScheduleStore } from '../storage/ScheduleStore.js';
 import { WorkflowParseCache, AdapterMetadataCache } from '../cache/index.js';
 import { RuntimeArtifactStore } from '../runtime/index.js';
+import { NoOpUsageCollector } from '../usage/NoOpUsageCollector.js';
+import { FileSpoolUsageCollector, HttpUsageBatchTransport } from '../usage/FileSpoolUsageCollector.js';
+import { DistributedWorkflowOrchestrator, FileDistributedJobQueue, InMemoryDistributedJobQueue } from '../distributed/index.js';
+import { CheckpointStore } from '../storage/CheckpointStore.js';
+import { createAdapterCallEvent, createStepExecuteEvent, createTriggerFireEvent, createWorkflowRunEvent, } from '../usage/UsageEventFactory.js';
 /**
  * OrbytEngine - Main public API
  *
@@ -234,6 +239,7 @@ export class OrbytEngine {
     workflowParseCache;
     adapterMetadataCache;
     runtimeArtifactStore;
+    usageCollector;
     constructor(config = {}) {
         // Validate and apply defaults
         validateConfig(config);
@@ -275,14 +281,53 @@ export class OrbytEngine {
             maxConcurrentExecutions: this.config.maxConcurrentWorkflows,
             defaultTimeout: this.config.defaultTimeout,
             enableScheduler: this.config.enableScheduler,
+            scheduler: this.config.scheduler,
             queue: this.config.queue,
             retryPolicy: this.config.retryPolicy,
             timeoutManager: this.config.timeoutManager,
         });
         // Wire components together
         this.setupComponents();
+        // Initialize usage collector.
+        // Priority:
+        // 1) user-provided collector
+        // 2) built-in durable file spool collector (default and production-safe)
+        // 3) no-op collector (testing-only escape hatch)
+        if (this.config.usageCollector) {
+            this.usageCollector = this.config.usageCollector;
+        }
+        else {
+            const usageSpool = this.config.usageSpool;
+            const spoolEnabled = usageSpool?.enabled ?? true;
+            const spoolBaseDir = usageSpool?.baseDir ?? join(homedir(), '.orbyt', 'usage');
+            const allowNoOpForTesting = process.env.NODE_ENV === 'test' ||
+                process.env.ORBYT_ALLOW_NOOP_USAGE_COLLECTOR === '1';
+            if (spoolEnabled || !allowNoOpForTesting) {
+                if (!spoolEnabled && !allowNoOpForTesting) {
+                    this.log('warn', 'usageSpool.enabled=false ignored outside test mode; using durable spool collector');
+                }
+                const transport = usageSpool?.billingEndpoint
+                    ? new HttpUsageBatchTransport({
+                        endpoint: usageSpool.billingEndpoint,
+                        apiKey: usageSpool.billingApiKey,
+                        timeoutMs: usageSpool.requestTimeoutMs,
+                    })
+                    : undefined;
+                this.usageCollector = new FileSpoolUsageCollector({
+                    baseDir: spoolBaseDir,
+                    batchSize: usageSpool?.batchSize,
+                    flushIntervalMs: usageSpool?.flushIntervalMs,
+                    maxRetryAttempts: usageSpool?.maxRetryAttempts,
+                    transport,
+                });
+            }
+            else {
+                this.usageCollector = new NoOpUsageCollector();
+            }
+        }
         // Ensure infrastructure directories exist before any persistence/caching.
         this.bootstrapRuntimeDirectories();
+        this.ensureFirstRunConfigFile();
         // Initialise persistent stores (non-fatal — must never block engine startup)
         const storeRoot = this.config.stateDir ?? join(homedir(), '.orbyt');
         this.executionStore = new ExecutionStore(join(storeRoot, 'executions'));
@@ -360,6 +405,7 @@ export class OrbytEngine {
             orbytHome,
             this.config.stateDir,
             join(this.config.stateDir, 'executions'),
+            join(this.config.stateDir, 'checkpoints'),
             join(this.config.stateDir, 'workflows'),
             join(this.config.stateDir, 'schedules'),
             this.config.logDir,
@@ -373,6 +419,11 @@ export class OrbytEngine {
             join(orbytHome, 'plugins'),
             join(orbytHome, 'metrics'),
             join(orbytHome, 'config'),
+            join(orbytHome, 'usage'),
+            join(orbytHome, 'usage', 'events'),
+            join(orbytHome, 'usage', 'pending'),
+            join(orbytHome, 'usage', 'sent'),
+            join(orbytHome, 'usage', 'failed'),
             join(orbytHome, 'tmp'),
             join(orbytHome, 'cloud-sync'),
         ];
@@ -385,6 +436,54 @@ export class OrbytEngine {
             }
         }
     }
+    /**
+     * Ensure a first-run config file exists at ~/.orbyt/config/config.json.
+     *
+     * This file is created once and then preserved as the local runtime config
+     * snapshot for visibility and tooling introspection.
+     */
+    ensureFirstRunConfigFile() {
+        const configDir = join(homedir(), '.orbyt', 'config');
+        const configPath = join(configDir, 'config.json');
+        if (existsSync(configPath)) {
+            return;
+        }
+        try {
+            mkdirSync(configDir, { recursive: true });
+            const payload = {
+                version: 1,
+                createdAt: new Date().toISOString(),
+                source: 'orbyt-engine',
+                engine: {
+                    version: this.version,
+                    mode: this.config.mode,
+                    logLevel: this.config.logLevel,
+                    maxConcurrentWorkflows: this.config.maxConcurrentWorkflows,
+                    maxConcurrentSteps: this.config.maxConcurrentSteps,
+                    defaultTimeout: this.config.defaultTimeout,
+                    enableScheduler: this.config.enableScheduler,
+                    enableMetrics: this.config.enableMetrics,
+                    enableEvents: this.config.enableEvents,
+                    sandboxMode: this.config.sandboxMode,
+                },
+                paths: {
+                    stateDir: this.config.stateDir,
+                    logDir: this.config.logDir,
+                    cacheDir: this.config.cacheDir,
+                    runtimeDir: this.config.runtimeDir,
+                    workingDirectory: this.config.workingDirectory,
+                },
+                usageSpool: this.config.usageSpool,
+            };
+            writeFileSync(configPath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+            this.log('debug', 'Created first-run engine config file', { configPath });
+        }
+        catch (error) {
+            this.log('warn', 'Failed to create first-run engine config file', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
     /**
      * Register built-in adapters
      * These are the core adapters shipped with Orbyt
@@ -424,6 +523,14 @@ export class OrbytEngine {
         // Emit engine.stopped event
         await this.eventBus.emit(createEvent(EngineEventType.ENGINE_STOPPED, { timestamp: Date.now() }, {}));
         this.log('info', 'Orbyt Engine stopped');
+        // Best-effort collector draining/cleanup on shutdown.
+        try {
+            await this.usageCollector.flush?.();
+            await this.usageCollector.close?.();
+        }
+        catch {
+            // Non-fatal on shutdown
+        }
     }
     /**
      * Run a workflow
@@ -662,6 +769,8 @@ export class OrbytEngine {
             continueOnError: options.continueOnError,
             dryRun: options.dryRun,
             triggeredBy: options.triggeredBy,
+            resumeFromRunId: options.resumeFromRunId,
+            resumePolicy: options.resumePolicy,
             _ownershipContext: options._ownershipContext,
             _permissionPolicy: options._permissionPolicy,
         };
@@ -749,7 +858,34 @@ export class OrbytEngine {
                 },
                 continueOnError: sanitizedOptions.continueOnError,
                 triggeredBy: sanitizedOptions.triggeredBy || 'manual',
+                resumeFromRunId: sanitizedOptions.resumeFromRunId,
+                resumePolicy: sanitizedOptions.resumePolicy,
             };
+            if (execOptions.triggeredBy && execOptions.triggeredBy !== 'manual') {
+                internalContext._usage.triggerFireCount += 1;
+                this.recordUsageEvent(createTriggerFireEvent({
+                    executionId: internalContext._identity.executionId,
+                    workflowId: parsedWorkflow.name || parsedWorkflow.metadata?.name,
+                    userId: internalContext._ownership.userId,
+                    workspaceId: internalContext._ownership.workspaceId,
+                    pricingTier: internalContext._billing.pricingTierResolved,
+                    billable: internalContext._billing.isBillable,
+                    metadata: {
+                        success: true,
+                        triggeredBy: execOptions.triggeredBy,
+                    },
+                }));
+            }
+            internalContext._usage.automationCount += 1;
+            this.recordUsageEvent(createWorkflowRunEvent({
+                executionId: internalContext._identity.executionId,
+                workflowId: parsedWorkflow.name || parsedWorkflow.metadata?.name,
+                userId: internalContext._ownership.userId,
+                workspaceId: internalContext._ownership.workspaceId,
+                executionMode: isolatedRuntime ? 'parallel' : 'single',
+                pricingTier: internalContext._billing.pricingTierResolved,
+                billable: internalContext._billing.isBillable,
+            }));
             this.log('info', `Running workflow: ${parsedWorkflow.name || 'unnamed'}`);
             this.workflowStore.save(parsedWorkflow);
             // Parallel/mixed mode can execute multiple workflows concurrently via runMany().
@@ -761,10 +897,11 @@ export class OrbytEngine {
                     stepExecutor: this.stepExecutor,
                     workflowExecutor: this.workflowExecutor,
                 };
-            const result = await this.measureWorkflowExecution(parsedWorkflow.name || 'unnamed', () => runtime.workflowExecutor.execute(parsedWorkflow, execOptions));
-            internalContext._usage.stepCount = result.metadata.totalSteps;
+            const useDistributedRuntime = this.config.mode === 'distributed';
+            const result = await this.measureWorkflowExecution(parsedWorkflow.name || 'unnamed', () => useDistributedRuntime
+                ? this.executeDistributedWorkflow(parsedWorkflow, execOptions, runtime.stepExecutor)
+                : runtime.workflowExecutor.execute(parsedWorkflow, execOptions));
             internalContext._usage.durationSeconds = result.duration / 1000;
-            internalContext._usage.weightedStepCount = result.metadata.totalSteps;
             this.log('info', `Workflow completed: ${result.status}`, {
                 durationMs: result.duration,
                 steps: result.metadata.totalSteps,
@@ -772,6 +909,54 @@ export class OrbytEngine {
                 automationCount: internalContext._usage.automationCount,
                 stepCount: internalContext._usage.stepCount,
             });
+            const workflowId = parsedWorkflow.name || parsedWorkflow.metadata?.name;
+            for (const [stepId, stepResult] of result.stepResults.entries()) {
+                const stepDefinition = parsedWorkflow.steps.find((step) => step.id === stepId);
+                if (!stepDefinition)
+                    continue;
+                const success = stepResult.status === 'success';
+                const errorMessage = stepResult.error?.message;
+                const executed = stepResult.status !== 'skipped';
+                if (executed) {
+                    internalContext._usage.stepCount += 1;
+                    internalContext._usage.weightedStepCount += 1;
+                }
+                if (executed) {
+                    this.recordUsageEvent(createStepExecuteEvent({
+                        executionId: internalContext._identity.executionId,
+                        stepId,
+                        workflowId,
+                        userId: internalContext._ownership.userId,
+                        workspaceId: internalContext._ownership.workspaceId,
+                        adapterType: stepDefinition.adapter,
+                        adapterName: stepDefinition.action,
+                        durationMs: stepResult.duration,
+                        success,
+                        retries: Math.max(0, stepResult.attempts - 1),
+                        error: errorMessage,
+                        pricingTier: internalContext._billing.pricingTierResolved,
+                        billable: internalContext._billing.isBillable,
+                    }));
+                }
+                if (executed) {
+                    internalContext._usage.adapterCallCount += 1;
+                    this.recordUsageEvent(createAdapterCallEvent({
+                        executionId: internalContext._identity.executionId,
+                        stepId,
+                        adapterType: stepDefinition.adapter,
+                        adapterName: stepDefinition.action,
+                        workflowId,
+                        userId: internalContext._ownership.userId,
+                        workspaceId: internalContext._ownership.workspaceId,
+                        durationMs: stepResult.duration,
+                        success,
+                        retries: Math.max(0, stepResult.attempts - 1),
+                        error: errorMessage,
+                        pricingTier: internalContext._billing.pricingTierResolved,
+                        billable: internalContext._billing.isBillable,
+                    }));
+                }
+            }
             await this.onWorkflowBillingComplete(internalContext, result);
             return result;
         });
@@ -779,6 +964,42 @@ export class OrbytEngine {
         LoggerManager.clearWorkflowContext();
         return result;
     }
+    async executeDistributedWorkflow(workflow, execOptions, stepExecutor) {
+        const distributed = this.config.distributed;
+        const queueBackend = distributed?.queueBackend ?? 'memory';
+        const queueStateDir = distributed?.fileQueueStateDir ?? join(homedir(), '.orbyt', 'distributed-queue');
+        const workerCount = distributed?.workerCount
+            ?? this.config.scheduler?.job?.workerCount
+            ?? Math.max(1, Math.min(8, this.config.maxConcurrentSteps || 4));
+        const queue = distributed?.jobQueue
+            ?? (queueBackend === 'file'
+                ? new FileDistributedJobQueue({
+                    stateDir: queueStateDir,
+                    leaseMs: distributed?.leaseMs,
+                })
+                : new InMemoryDistributedJobQueue({
+                    leaseMs: distributed?.leaseMs,
+                }));
+        const orchestrator = new DistributedWorkflowOrchestrator({
+            queue,
+            stepExecutor,
+            workerCount,
+            pollIntervalMs: distributed?.pollIntervalMs,
+            eventBus: this.eventBus,
+            hookManager: this.hookManager,
+            executionStore: this.executionStore,
+            checkpointStore: new CheckpointStore(join(this.config.stateDir, 'checkpoints')),
+            leaseExtensionMs: distributed?.leaseExtensionMs,
+        });
+        this.log('info', '[Distributed] Executing workflow via scheduler->queue->workers runtime', {
+            workerCount,
+            queueBackend: distributed?.jobQueue
+                ? 'custom'
+                : queueBackend,
+            workflowId: workflow.name || workflow.metadata?.name,
+        });
+        return orchestrator.execute(workflow, execOptions);
+    }
     /**
      * Create isolated per-workflow execution runtime.
      *
@@ -861,6 +1082,31 @@ export class OrbytEngine {
         //   });
         // }
     }
+    /**
+     * Safe usage event recording
+     *
+     * Records a usage event through the configured collector.
+     * Failures are logged but never propagate (non-fatal).
+     * Called asynchronously and does not block execution.
+     *
+     * @param event - Usage event to record
+     */
+    recordUsageEvent(event) {
+        // Fire-and-forget: record usage asynchronously without blocking
+        process.nextTick(async () => {
+            try {
+                await this.usageCollector.record(event);
+            }
+            catch (error) {
+                // Log but don't propagate - usage tracking must never fail execution
+                this.log('debug', 'Usage collection failed (non-fatal)', {
+                    error: error instanceof Error ? error.message : String(error),
+                    eventType: event.type,
+                    executionId: event.executionId,
+                });
+            }
+        });
+    }
     /**
      * Validate a workflow without executing it
      *
@@ -1065,6 +1311,226 @@ export class OrbytEngine {
     getVersion() {
         return this.version;
     }
+    /**
+     * Query usage events from the local spool archive and return aggregated metrics.
+     */
+    async getUsage(options = {}) {
+        const now = Date.now();
+        const from = options.from ?? now - 30 * 24 * 60 * 60 * 1000;
+        const to = options.to ?? now;
+        const groupBy = options.groupBy ?? 'none';
+        if (from > to) {
+            throw new Error(`Invalid usage query range: from (${from}) must be <= to (${to})`);
+        }
+        const usageBaseDir = this.config.usageSpool?.baseDir ?? join(homedir(), '.orbyt', 'usage');
+        const eventsDir = join(usageBaseDir, 'events');
+        const filteredEvents = [];
+        if (existsSync(eventsDir)) {
+            const files = readdirSync(eventsDir)
+                .filter((name) => name.endsWith('.jsonl'))
+                .sort();
+            for (const file of files) {
+                const filePath = join(eventsDir, file);
+                let content = '';
+                try {
+                    content = readFileSync(filePath, 'utf8');
+                }
+                catch {
+                    continue;
+                }
+                if (!content.trim()) {
+                    continue;
+                }
+                const lines = content.split('\n');
+                for (const line of lines) {
+                    const trimmed = line.trim();
+                    if (!trimmed) {
+                        continue;
+                    }
+                    let event;
+                    try {
+                        event = JSON.parse(trimmed);
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (!this.matchesUsageQuery(event, options, from, to)) {
+                        continue;
+                    }
+                    filteredEvents.push(event);
+                }
+            }
+        }
+        const byType = {};
+        const byProduct = {};
+        const byAdapter = {};
+        const byWorkflow = {};
+        const byWorkspace = {};
+        const byUser = {};
+        const byTrigger = {};
+        const groupedMap = new Map();
+        let billableEvents = 0;
+        let successEvents = 0;
+        let failureEvents = 0;
+        let totalDurationMs = 0;
+        for (const event of filteredEvents) {
+            byType[event.type] = (byType[event.type] ?? 0) + 1;
+            byProduct[event.product] = (byProduct[event.product] ?? 0) + 1;
+            const adapterKey = event.adapterName || event.adapterType || 'unknown';
+            byAdapter[adapterKey] = (byAdapter[adapterKey] ?? 0) + 1;
+            const workflowKey = event.workflowId || 'unknown';
+            byWorkflow[workflowKey] = (byWorkflow[workflowKey] ?? 0) + 1;
+            const workspaceKey = event.workspaceId || 'unknown';
+            byWorkspace[workspaceKey] = (byWorkspace[workspaceKey] ?? 0) + 1;
+            const userKey = event.userId || 'unknown';
+            byUser[userKey] = (byUser[userKey] ?? 0) + 1;
+            const triggerKey = this.resolveTriggerKey(event);
+            byTrigger[triggerKey] = (byTrigger[triggerKey] ?? 0) + 1;
+            if (event.billable === true) {
+                billableEvents += 1;
+            }
+            if (event.metadata?.success === true) {
+                successEvents += 1;
+            }
+            else if (event.metadata?.success === false) {
+                failureEvents += 1;
+            }
+            const durationMs = typeof event.metadata?.durationMs === 'number'
+                ? Math.max(0, event.metadata.durationMs)
+                : 0;
+            totalDurationMs += durationMs;
+            if (groupBy !== 'none') {
+                const key = this.resolveUsageGroupKey(event, groupBy);
+                const existing = groupedMap.get(key) ?? {
+                    key,
+                    eventCount: 0,
+                    billableCount: 0,
+                    successCount: 0,
+                    failureCount: 0,
+                    totalDurationMs: 0,
+                };
+                existing.eventCount += 1;
+                if (event.billable === true) {
+                    existing.billableCount += 1;
+                }
+                if (event.metadata?.success === true) {
+                    existing.successCount += 1;
+                }
+                else if (event.metadata?.success === false) {
+                    existing.failureCount += 1;
+                }
+                existing.totalDurationMs += durationMs;
+                groupedMap.set(key, existing);
+            }
+        }
+        const normalizedLimit = typeof options.limit === 'number' && Number.isFinite(options.limit) && options.limit > 0
+            ? Math.floor(options.limit)
+            : undefined;
+        const outputEvents = options.includeEvents
+            ? (normalizedLimit ? filteredEvents.slice(-normalizedLimit) : filteredEvents)
+            : undefined;
+        return {
+            query: {
+                from,
+                to,
+                groupBy,
+                limit: normalizedLimit,
+            },
+            totalEvents: filteredEvents.length,
+            billableEvents,
+            successEvents,
+            failureEvents,
+            totalDurationMs,
+            byType,
+            byProduct,
+            byAdapter,
+            byWorkflow,
+            byWorkspace,
+            byUser,
+            byTrigger,
+            grouped: Array.from(groupedMap.values()).sort((a, b) => a.key.localeCompare(b.key)),
+            events: outputEvents?.map((event) => ({
+                id: event.id,
+                type: event.type,
+                timestamp: event.timestamp,
+                product: event.product,
+                executionId: event.executionId,
+                workflowId: event.workflowId,
+                stepId: event.stepId,
+                adapterName: event.adapterName,
+                adapterType: event.adapterType,
+                billable: event.billable,
+                metadata: event.metadata,
+            })),
+        };
+    }
+    matchesUsageQuery(event, options, from, to) {
+        if (!event || typeof event !== 'object')
+            return false;
+        if (typeof event.timestamp !== 'number')
+            return false;
+        if (event.timestamp < from || event.timestamp > to)
+            return false;
+        if (options.userId && event.userId !== options.userId)
+            return false;
+        if (options.workspaceId && event.workspaceId !== options.workspaceId)
+            return false;
+        if (options.product && event.product !== options.product)
+            return false;
+        if (options.eventType && event.type !== options.eventType)
+            return false;
+        if (options.adapterName && event.adapterName !== options.adapterName)
+            return false;
+        if (options.adapterType && event.adapterType !== options.adapterType)
+            return false;
+        return true;
+    }
+    resolveUsageGroupKey(event, groupBy) {
+        if (groupBy === 'workflow') {
+            return event.workflowId || 'unknown';
+        }
+        if (groupBy === 'adapter') {
+            return event.adapterName || event.adapterType || 'unknown';
+        }
+        if (groupBy === 'trigger') {
+            return this.resolveTriggerKey(event);
+        }
+        if (groupBy === 'product') {
+            return event.product || 'unknown';
+        }
+        if (groupBy === 'workspace') {
+            return event.workspaceId || 'unknown';
+        }
+        if (groupBy === 'user') {
+            return event.userId || 'unknown';
+        }
+        if (groupBy === 'type') {
+            return event.type || 'unknown';
+        }
+        const date = new Date(event.timestamp);
+        if (groupBy === 'hourly') {
+            return `${date.toISOString().slice(0, 13)}:00:00Z`;
+        }
+        if (groupBy === 'daily') {
+            return date.toISOString().slice(0, 10);
+        }
+        if (groupBy === 'weekly') {
+            const day = date.getUTCDay();
+            const shift = day === 0 ? -6 : 1 - day;
+            const start = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate() + shift));
+            return start.toISOString().slice(0, 10);
+        }
+        return 'all';
+    }
+    resolveTriggerKey(event) {
+        if (event.type === 'usage.trigger.fire') {
+            const triggerType = typeof event.metadata?.triggerType === 'string'
+                ? event.metadata.triggerType
+                : undefined;
+            return triggerType || 'trigger.fire';
+        }
+        return 'non-trigger';
+    }
     /**
      * Internal logging method
      *