@kb-labs/workflow-engine 2.94.0 → 2.98.0

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 import { WorkflowSpec, RunTrigger, IdempotencyKey, ConcurrencyGroup, WorkflowRun, JobRun, StepRun, RetryPolicy, ArtifactMergeConfig } from '@kb-labs/workflow-contracts';
-import { ILogger, ICache, IEventBus, IAnalytics, Unsubscribe, ICronManager, IJobScheduler, JobDefinition, JobHandle, CronExpression, JobFilter } from '@kb-labs/core-platform';
+import { ILogger, ICache, IEventBus, IAnalytics, ISnapshotManager, Unsubscribe, IJobScheduler, JobDefinition, JobHandle, CronExpression, JobFilter } from '@kb-labs/core-platform';
 import { JobPriority, WorkflowEventName } from '@kb-labs/workflow-constants';
 import { ArtifactClient } from '@kb-labs/workflow-artifacts';
 import { IEntityRegistry } from '@kb-labs/core-registry';
-import { PlatformServices, JobHandlerDecl, PluginContextDescriptor } from '@kb-labs/plugin-contracts';
+import { PlatformServices, JobHandlerDecl, WorkflowHandlerDecl, CronDecl, PluginContextDescriptor } from '@kb-labs/plugin-contracts';
 import { IExecutionBackend } from '@kb-labs/core-contracts';
 
 /**
@@ -182,16 +182,6 @@ declare class RunSnapshotStorage {
     deleteSnapshot(runId: string): Promise<void>;
 }
 
-interface SnapshotManagerClient {
-    restoreSnapshot(request: {
-        snapshotId: string;
-        workspaceId?: string;
-        environmentId?: string;
-        targetPath?: string;
-        overwrite?: boolean;
-        metadata?: Record<string, unknown>;
-    }): Promise<unknown>;
-}
 interface WorkflowEngineOptions {
     scheduler?: SchedulerOptions;
     concurrency?: AcquireOptions;
@@ -206,7 +196,7 @@ interface WorkflowEngineOptions {
     /** Platform analytics adapter (OPTIONAL) */
     analytics?: IAnalytics;
     /** Platform snapshot manager (OPTIONAL - for infra snapshot restore in replay) */
-    snapshotManager?: SnapshotManagerClient;
+    snapshotManager?: ISnapshotManager;
     /** Workspace root (monorepo root) - used for plugin execution context */
     workspaceRoot?: string;
 }
@@ -240,6 +230,12 @@ declare class WorkflowEngine {
      * Implements exponential/linear backoff retry logic.
      */
     markJobFailed(runId: string, jobId: string, error: Error, shouldRetry?: boolean): Promise<void>;
+    /**
+     * Recursively cancel jobs blocked on a failed/cancelled upstream job, so the
+     * DAG does not leave dependents stuck in 'queued'. Cancellation cascades:
+     * a cancelled job also cancels its own dependents.
+     */
+    private cancelDownstreamJobs;
     /**
      * Mark job as interrupted (e.g., during graceful shutdown).
      * Interrupted jobs will be retried on next daemon startup.
@@ -253,6 +249,12 @@ declare class WorkflowEngine {
      * Mark job as completed successfully.
      */
     markJobCompleted(runId: string, jobId: string): Promise<void>;
+    /** Build a minimal ExpressionContext from run state (for job-level if evaluation). */
+    private buildExpressionContext;
+    /** Evaluate a job-level `if:` expression. Strips ${{ }} wrapper if present. */
+    private evaluateJobIf;
+    /** Mark a job as skipped (success) and release any jobs blocked on it. */
+    private skipJob;
     /**
      * Check if all jobs in a run are completed and update run status accordingly.
      */
@@ -309,9 +311,27 @@ declare class WorkflowEngine {
     /**
      * Move permanently failed job to Dead Letter Queue.
      */
-    private moveToDLQ;
+    /**
+     * Record a dead-letter entry for a job that exhausted its retries. This is an
+     * observability artifact only — it does NOT change the run status. The run
+     * outcome is decided by checkRunCompletion (→ 'failed'). 'dlq' as a run status
+     * is reserved for infrastructure failures and is no longer set here (B-029).
+     */
+    private deadLetterJob;
     updateRun(runId: string, mutator: (run: WorkflowRun) => WorkflowRun | void): Promise<WorkflowRun | null>;
     finalizeRun(runId: string, status: WorkflowRun['status'], context?: Partial<RunContext>): Promise<WorkflowRun | null>;
+    /**
+     * Persist a snapshot for a run that just reached a terminal state, so it
+     * can be replayed from any step later (`replayRun`, used by both
+     * `workflow runs restart --from-step` and `rerun --failed-only`). Only
+     * 'success'/'failed' carry meaningful step output data worth snapshotting.
+     *
+     * Shared by finalizeRun() and checkRunCompletion() — checkRunCompletion is
+     * the run-completion path actually driven by the worker in production, so
+     * without this call here, no snapshot is ever created outside of tests
+     * that call finalizeRun() directly (issue #263).
+     */
+    private snapshotTerminalRun;
     nextJob(): Promise<JobQueueEntry | null>;
     rescheduleJob(entry: JobQueueEntry, delayMs: number): Promise<void>;
     publishRunEvent(type: WorkflowEventName, run: WorkflowRun): Promise<void>;
@@ -325,7 +345,7 @@ declare class WorkflowEngine {
         lineNo: number;
         timestamp: string;
         meta?: Record<string, unknown>;
-    }): Promise<void>;
+    }, stepName?: string): Promise<void>;
     /**
      * Create a snapshot of the current run state
      */
@@ -464,6 +484,8 @@ interface WorkflowStats {
  */
 interface WorkflowRuntime {
     id: string;
+    /** Discriminator for workflow kind. Enables type-safe routing in consumers. */
+    kind?: 'workflow' | 'job' | 'cron';
     source: 'manifest' | 'standalone' | 'plugin';
     pluginId?: string;
     manifestPath?: string;
@@ -484,6 +506,10 @@ interface WorkflowRuntime {
         required?: boolean;
         default?: unknown;
     }>;
+    /** Semantic version from workflow spec (e.g. "6.6.0") */
+    version?: string;
+    /** ISO timestamp of last modification */
+    updatedAt?: string;
 }
 /**
  * Options for ManifestScanner
@@ -505,25 +531,16 @@ declare class ManifestScanner {
     private readonly cliApi;
     private readonly platform;
     private readonly cacheTtlMs;
+    private readonly converter;
     constructor(options: ManifestScannerOptions);
     /**
      * Scan all installed plugins for workflows and jobs.
+     * Purpose: listing — populates the REST API GET /api/v1/workflows catalog.
+     * (CronDiscovery in daemon handles scheduling — different output, different consumer.)
      *
      * Returns unified WorkflowRuntime representations.
      */
     scanPlugins(): Promise<WorkflowRuntime[]>;
-    /**
-     * Convert workflow handler declaration to WorkflowRuntime.
-     */
-    private convertWorkflowHandler;
-    /**
-     * Convert job handler declaration to WorkflowRuntime.
-     */
-    private convertJobHandler;
-    /**
-     * Convert cron schedule declaration to WorkflowRuntime.
-     */
-    private convertCronSchedule;
     /**
      * Scan all installed plugins for job handlers only.
      *
@@ -548,6 +565,21 @@ declare class ManifestScanner {
     watchPlugins(callback?: (workflows: WorkflowRuntime[]) => void): () => void;
 }
 
+/**
+ * @module @kb-labs/workflow-engine/manifest-converter
+ *
+ * Pure conversion utilities for plugin manifest declarations → WorkflowRuntime.
+ * No I/O, no caching, no platform dependency — testable in isolation.
+ *
+ * Used by ManifestScanner which handles fetch + cache responsibilities.
+ */
+
+declare class ManifestConverter {
+    convertWorkflowHandler(pluginId: string, handler: WorkflowHandlerDecl, pluginRoot: string): WorkflowRuntime;
+    convertJobHandler(pluginId: string, handler: JobHandlerDecl, pluginRoot: string): WorkflowRuntime;
+    convertCronSchedule(pluginId: string, cronDecl: CronDecl, pluginRoot: string): WorkflowRuntime;
+}
+
 /**
  * @module @kb-labs/workflow-engine/workflow-repository
  *
@@ -733,6 +765,13 @@ declare class WorkflowService {
     listAll(options?: WorkflowServiceListOptions): Promise<WorkflowRuntime[]>;
     /**
      * Get workflow by ID (from either source).
+     *
+     * Lookup order:
+     * 1. Standalone by filename-derived id (canonical, fast path)
+     * 2. Standalone by `name:` field — allows `--workflow-id=dev-cycle` even
+     *    when the file is named `03-dev-cycle.yml` (F8 ergonomics fix)
+     * 3. Manifest-based by id
+     * 4. Manifest-based by name field
      */
     get(id: string): Promise<WorkflowRuntime | null>;
     /**
@@ -780,121 +819,6 @@ declare class WorkflowService {
     refreshManifests(): Promise<void>;
 }
 
-/**
- * @module @kb-labs/workflow-engine/workflow-schedule-manager
- *
- * Manages scheduled workflow execution via CronManager.
- *
- * ## Features
- * - Registers scheduled workflows with CronManager
- * - Executes workflows on cron triggers
- * - Tracks next/last run times
- * - Supports both manifest-based jobs and standalone workflows
- *
- * ## Usage
- * ```typescript
- * const scheduleManager = new WorkflowScheduleManager({
- *   cronManager,
- *   workflowService,
- *   executor,
- *   platform,
- * });
- *
- * await scheduleManager.registerAll();
- * ```
- */
-
-/**
- * Workflow executor interface.
- * Executes workflows (will be implemented by workflow engine).
- */
-interface WorkflowExecutor {
-    /**
-     * Execute workflow by ID.
-     */
-    execute(request: {
-        workflowId: string;
-        trigger: 'manual' | 'schedule' | 'webhook' | 'push';
-        input?: Record<string, unknown>;
-    }): Promise<{
-        runId: string;
-    }>;
-}
-/**
- * Options for WorkflowScheduleManager
- */
-interface WorkflowScheduleManagerOptions {
-    /** CronManager instance */
-    cronManager: ICronManager;
-    /** WorkflowService for discovering workflows */
-    workflowService: WorkflowService;
-    /** Workflow executor */
-    executor: WorkflowExecutor;
-    /** Platform services */
-    platform: PlatformServices;
-}
-/**
- * Workflow Schedule Manager
- *
- * Integrates workflows with CronManager for scheduled execution.
- */
-declare class WorkflowScheduleManager {
-    private readonly cronManager;
-    private readonly workflowService;
-    private readonly executor;
-    private readonly platform;
-    constructor(options: WorkflowScheduleManagerOptions);
-    /**
-     * Register all scheduled workflows with CronManager.
-     *
-     * Scans both manifest-based jobs and standalone workflows with schedules.
-     */
-    registerAll(): Promise<void>;
-    /**
-     * Register single workflow schedule.
-     */
-    register(workflow: WorkflowRuntime): Promise<void>;
-    /**
-     * Unregister workflow schedule.
-     */
-    unregister(workflowId: string): Promise<void>;
-    /**
-     * Re-register all schedules (refresh).
-     *
-     * Useful after workflow changes or service restart.
-     */
-    refresh(): Promise<void>;
-    /**
-     * Get next run time for scheduled workflow.
-     */
-    getNextRun(workflowId: string): Date | null;
-    /**
-     * Get last run time for scheduled workflow.
-     */
-    getLastRun(workflowId: string): Date | null;
-    /**
-     * Pause scheduled workflow.
-     */
-    pause(workflowId: string): void;
-    /**
-     * Resume paused workflow schedule.
-     */
-    resume(workflowId: string): void;
-    /**
-     * List all scheduled workflows.
-     */
-    listScheduled(): Array<{
-        workflowId: string;
-        schedule: string;
-        status: 'active' | 'paused';
-        lastRun?: Date;
-        nextRun?: Date;
-        runCount: number;
-    }>;
-    private getCronId;
-    private getWorkflowId;
-}
-
 interface WorkflowRegistryEntry {
     id: string;
     name: string;
@@ -1056,4 +980,4 @@ declare class JobManager implements IJobScheduler {
     private jobRecordToHandle;
 }
 
-export { type AcquireOptions, ArtifactMerger, type ArtifactMergerOptions, ConcurrencyManager, type CreateRunInput, type EngineLogger, EnvSecretProvider, type EnvSecretProviderOptions, EventBusBridge, JobManager, type JobManagerConfig, type JobQueueEntry, ManifestScanner, type ManifestScannerOptions, type RetryDecision, type RunContext, RunCoordinator, type RunCoordinatorOptions, type RunSnapshot, RunSnapshotStorage, Scheduler, type SchedulerOptions, type SecretProvider, StateStore, type ValidationResult, WorkflowEngine, type WorkflowEngineOptions, type WorkflowEvent, type WorkflowExecutor, type WorkflowHandlerInfo, type WorkflowListOptions, WorkflowLoader, type WorkflowLoaderOptions, type WorkflowLoaderResult, WorkflowRegistry, type WorkflowRegistryEntry, type WorkflowRegistryOptions, WorkflowRepository, type WorkflowRepositoryOptions, type WorkflowRuntime, type WorkflowSchedule, WorkflowScheduleManager, type WorkflowScheduleManagerOptions, WorkflowService, type WorkflowServiceListOptions, type WorkflowServiceOptions, type WorkflowStats, type WorkflowTrigger, type WorkflowTriggerType, calculateBackoff, createDefaultSecretProvider, shouldRetry };
+export { type AcquireOptions, ArtifactMerger, type ArtifactMergerOptions, ConcurrencyManager, type CreateRunInput, type EngineLogger, EnvSecretProvider, type EnvSecretProviderOptions, EventBusBridge, JobManager, type JobManagerConfig, type JobQueueEntry, ManifestConverter, ManifestScanner, type ManifestScannerOptions, type RetryDecision, type RunContext, RunCoordinator, type RunCoordinatorOptions, type RunSnapshot, RunSnapshotStorage, Scheduler, type SchedulerOptions, type SecretProvider, StateStore, type ValidationResult, WorkflowEngine, type WorkflowEngineOptions, type WorkflowEvent, type WorkflowHandlerInfo, type WorkflowListOptions, WorkflowLoader, type WorkflowLoaderOptions, type WorkflowLoaderResult, WorkflowRegistry, type WorkflowRegistryEntry, type WorkflowRegistryOptions, WorkflowRepository, type WorkflowRepositoryOptions, type WorkflowRuntime, type WorkflowSchedule, WorkflowService, type WorkflowServiceListOptions, type WorkflowServiceOptions, type WorkflowStats, type WorkflowTrigger, type WorkflowTriggerType, calculateBackoff, createDefaultSecretProvider, shouldRetry };