@kb-labs/workflow-engine 1.1.0

package/dist/index.d.ts

@@ -0,0 +1,1057 @@
+import { WorkflowSpec, WorkflowRun, JobRun, StepRun, RunTrigger, IdempotencyKey, ConcurrencyGroup, 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 { 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 { IExecutionBackend } from '@kb-labs/core-contracts';
+
+/**
+ * @deprecated Use ILogger from @kb-labs/core-platform instead.
+ * This type alias is kept for backward compatibility.
+ */
+type EngineLogger = ILogger;
+interface WorkflowLoaderResult {
+    spec: WorkflowSpec;
+    source: string;
+}
+interface RunContext {
+    run: WorkflowRun;
+    jobs: JobRun[];
+    steps: StepRun[];
+}
+interface CreateRunInput {
+    spec: WorkflowSpec;
+    trigger: RunTrigger;
+    idempotencyKey?: IdempotencyKey;
+    concurrencyGroup?: ConcurrencyGroup;
+    metadata?: Record<string, unknown>;
+    env?: Record<string, string>;
+}
+
+interface WorkflowLoaderOptions {
+    cwd?: string;
+}
+declare class WorkflowLoader {
+    private readonly logger;
+    constructor(logger: EngineLogger);
+    fromFile(filePath: string, options?: WorkflowLoaderOptions): Promise<WorkflowLoaderResult>;
+    fromInline(spec: unknown, source?: string): WorkflowLoaderResult;
+    private parse;
+    private validate;
+}
+
+declare class StateStore {
+    private readonly logger;
+    private readonly cache;
+    constructor(cache: ICache, logger: EngineLogger);
+    saveRun(run: WorkflowRun): Promise<void>;
+    getRun(runId: string): Promise<WorkflowRun | null>;
+    deleteRun(runId: string): Promise<void>;
+    getAllRunIds(): Promise<string[]>;
+    updateRun(runId: string, mutator: (draft: WorkflowRun) => WorkflowRun | void): Promise<WorkflowRun | null>;
+    updateJob(runId: string, jobId: string, mutator: (job: JobRun) => JobRun | void): Promise<JobRun | null>;
+    updateStep(runId: string, jobId: string, stepId: string, mutator: (step: StepRun) => StepRun | void): Promise<StepRun | null>;
+    releaseBlockedJobs(runId: string, completedJobName: string): Promise<JobRun[]>;
+}
+
+interface AcquireOptions {
+    ttlMs?: number;
+}
+declare class ConcurrencyManager {
+    private readonly logger;
+    private readonly cache;
+    private readonly ttlMs;
+    constructor(cache: ICache, logger: EngineLogger, options?: AcquireOptions);
+    acquire(group: ConcurrencyGroup, runId: string, options?: AcquireOptions): Promise<boolean>;
+    release(group: ConcurrencyGroup, runId: string): Promise<void>;
+    getActiveRun(group: ConcurrencyGroup): Promise<string | null>;
+}
+
+interface RunCoordinatorOptions {
+    idempotencyTtlMs?: number;
+}
+declare class RunCoordinator {
+    private readonly stateStore;
+    private readonly concurrencyManager;
+    private readonly logger;
+    private readonly cache;
+    private readonly idempotencyTtlMs;
+    constructor(cache: ICache, stateStore: StateStore, concurrencyManager: ConcurrencyManager, logger: EngineLogger, options?: RunCoordinatorOptions);
+    ensureRun(input: CreateRunInput): Promise<WorkflowRun>;
+    private buildInitialRun;
+    private registerIdempotencyKey;
+    private loadByIdempotencyKey;
+    releaseConcurrency(run: WorkflowRun): Promise<void>;
+}
+
+interface JobQueueEntry {
+    id: string;
+    runId: string;
+    jobId: string;
+    priority: JobPriority;
+    enqueuedAt: string;
+    availableAt: number;
+    jobName: string;
+}
+interface SchedulerOptions {
+    defaultPriority?: JobPriority;
+    lookAheadMs?: number;
+}
+declare class Scheduler {
+    private readonly logger;
+    private readonly cache;
+    private readonly defaultPriority;
+    private readonly lookAheadMs;
+    private readonly priorityOrder;
+    constructor(cache: ICache, logger: EngineLogger, options?: SchedulerOptions);
+    scheduleRun(run: WorkflowRun): Promise<void>;
+    enqueueJob(runId: string, job: JobRun, priority?: JobPriority): Promise<void>;
+    dequeueJob(): Promise<JobQueueEntry | null>;
+    reschedule(entry: JobQueueEntry, delayMs: number): Promise<void>;
+    private dequeueFromPriority;
+    getDefaultPriority(): JobPriority;
+}
+
+interface SecretProvider {
+    resolve(names: string[]): Promise<Record<string, string>>;
+}
+interface EnvSecretProviderOptions {
+    /**
+     * Prefix applied when looking up secrets in environment variables.
+     * Defaults to `KB_SECRET_`.
+     */
+    prefix?: string;
+    /**
+     * When true (default), check both plain and prefixed environment variable names.
+     */
+    allowPlain?: boolean;
+}
+declare class EnvSecretProvider implements SecretProvider {
+    private readonly prefix;
+    private readonly allowPlain;
+    constructor(options?: EnvSecretProviderOptions);
+    resolve(names: string[]): Promise<Record<string, string>>;
+}
+declare function createDefaultSecretProvider(): SecretProvider;
+
+interface WorkflowEvent<TPayload = Record<string, unknown>> {
+    type: WorkflowEventName;
+    runId: string;
+    jobId?: string;
+    stepId?: string;
+    payload?: TPayload;
+    timestamp?: string;
+}
+declare class EventBusBridge {
+    private readonly logger;
+    private readonly events;
+    private readonly channel;
+    constructor(events: IEventBus, logger: EngineLogger);
+    publish<TPayload = Record<string, unknown>>(event: WorkflowEvent<TPayload>): Promise<void>;
+}
+
+interface RetryDecision {
+    shouldRetry: boolean;
+    nextDelayMs?: number;
+}
+declare function calculateBackoff(attempt: number, policy?: RetryPolicy): number;
+declare function shouldRetry(attempt: number, policy?: RetryPolicy): RetryDecision;
+
+interface RunSnapshot {
+    runId: string;
+    run: WorkflowRun;
+    stepOutputs: Record<string, Record<string, unknown>>;
+    env: Record<string, string>;
+    refs?: {
+        workspaceSnapshotId?: string;
+        environmentSnapshotId?: string;
+    };
+    createdAt: string;
+    version: string;
+}
+declare class RunSnapshotStorage {
+    private readonly cache;
+    private readonly logger;
+    constructor(cache: ICache, logger: EngineLogger);
+    private getSnapshotKey;
+    createSnapshot(run: WorkflowRun, stepOutputs: Record<string, Record<string, unknown>>, env: Record<string, string>, refs?: RunSnapshot['refs']): Promise<RunSnapshot>;
+    getSnapshot(runId: string): Promise<RunSnapshot | null>;
+    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;
+    runCoordinator?: RunCoordinatorOptions;
+    maxWorkflowDepth?: number;
+    /** Platform cache adapter (REQUIRED) */
+    cache: ICache;
+    /** Platform event bus adapter (REQUIRED) */
+    events: IEventBus;
+    /** Platform logger (REQUIRED) */
+    logger: ILogger;
+    /** Platform analytics adapter (OPTIONAL) */
+    analytics?: IAnalytics;
+    /** Platform snapshot manager (OPTIONAL - for infra snapshot restore in replay) */
+    snapshotManager?: SnapshotManagerClient;
+    /** Workspace root (monorepo root) - used for plugin execution context */
+    workspaceRoot?: string;
+}
+declare class WorkflowEngine {
+    private readonly options;
+    readonly loader: WorkflowLoader;
+    readonly maxWorkflowDepth: number;
+    private readonly logger;
+    private readonly analytics?;
+    private readonly stateStore;
+    private readonly concurrency;
+    private readonly runCoordinator;
+    private readonly scheduler;
+    private readonly events;
+    private readonly snapshotStorage;
+    constructor(options: WorkflowEngineOptions);
+    dispose(): Promise<void>;
+    /**
+     * Subscribe to real-time events for a specific workflow run.
+     * Events are filtered by runId from the shared event bus channel.
+     */
+    subscribeToRunEvents(runId: string, handler: (event: WorkflowEvent) => void): Unsubscribe;
+    createRun(input: CreateRunInput): Promise<WorkflowRun>;
+    runFromSpec(spec: WorkflowSpec, input: Omit<CreateRunInput, 'spec'>): Promise<WorkflowRun>;
+    runFromFile(filePath: string, input: Omit<CreateRunInput, 'spec'>): Promise<WorkflowRun>;
+    runFromInline(spec: unknown, input: Omit<CreateRunInput, 'spec'>): Promise<WorkflowRun>;
+    getRun(runId: string): Promise<WorkflowRun | null>;
+    cancelRun(runId: string): Promise<void>;
+    /**
+     * Mark job as failed and optionally schedule retry.
+     * Implements exponential/linear backoff retry logic.
+     */
+    markJobFailed(runId: string, jobId: string, error: Error, shouldRetry?: boolean): Promise<void>;
+    /**
+     * Mark job as interrupted (e.g., during graceful shutdown).
+     * Interrupted jobs will be retried on next daemon startup.
+     */
+    markJobInterrupted(runId: string, jobId: string): Promise<void>;
+    /**
+     * Mark job as started (running).
+     */
+    markJobStarted(runId: string, jobId: string): Promise<void>;
+    /**
+     * Mark job as completed successfully.
+     */
+    markJobCompleted(runId: string, jobId: string): Promise<void>;
+    /**
+     * Check if all jobs in a run are completed and update run status accordingly.
+     */
+    private checkRunCompletion;
+    /**
+     * Mark step as started (running).
+     */
+    markStepStarted(runId: string, jobId: string, stepId: string): Promise<void>;
+    /**
+     * Mark step as completed successfully with output.
+     */
+    markStepCompleted(runId: string, jobId: string, stepId: string, output?: unknown): Promise<void>;
+    /**
+     * Mark step as failed with error.
+     */
+    markStepFailed(runId: string, jobId: string, stepId: string, error: Error, outputs?: Record<string, unknown>): Promise<void>;
+    /**
+     * Mark step as waiting for human approval.
+     */
+    markStepWaitingApproval(runId: string, jobId: string, stepId: string): Promise<void>;
+    /**
+     * Resolve a pending approval — approve or reject.
+     * On approve: marks step as success with approval outputs.
+     * On reject: marks step as failed with rejection error.
+     */
+    resolveApproval(runId: string, jobId: string, stepId: string, action: 'approve' | 'reject', data?: Record<string, unknown>, comment?: string): Promise<void>;
+    /**
+     * Get the state store for direct access (used by worker for gate restart-from).
+     */
+    getStateStore(): StateStore;
+    /**
+     * Get the scheduler for direct access (used by worker for gate re-enqueue).
+     */
+    getScheduler(): Scheduler;
+    /**
+     * Mark stale running/queued runs as failed on daemon startup.
+     * Runs that were in-flight when the daemon crashed are unrecoverable —
+     * their executor process is gone, so we mark them failed immediately.
+     */
+    cleanupStaleRuns(): Promise<void>;
+    /**
+     * Resume interrupted jobs on daemon startup.
+     * Re-queues jobs that were interrupted during previous shutdown.
+     */
+    resumeInterruptedJobs(): Promise<void>;
+    /**
+     * Determine if job should be retried based on retry policy.
+     */
+    private shouldRetryJob;
+    /**
+     * Calculate backoff delay using exponential or linear strategy.
+     */
+    private calculateBackoff;
+    /**
+     * Move permanently failed job to Dead Letter Queue.
+     */
+    private moveToDLQ;
+    updateRun(runId: string, mutator: (run: WorkflowRun) => WorkflowRun | void): Promise<WorkflowRun | null>;
+    finalizeRun(runId: string, status: WorkflowRun['status'], context?: Partial<RunContext>): Promise<WorkflowRun | null>;
+    nextJob(): Promise<JobQueueEntry | null>;
+    rescheduleJob(entry: JobQueueEntry, delayMs: number): Promise<void>;
+    publishRunEvent(type: WorkflowEventName, run: WorkflowRun): Promise<void>;
+    /**
+     * Publish a log entry for real-time streaming to Studio UI.
+     */
+    publishLog(runId: string, jobId: string, stepId: string, entry: {
+        level: string;
+        message: string;
+        stream: string;
+        lineNo: number;
+        timestamp: string;
+        meta?: Record<string, unknown>;
+    }): Promise<void>;
+    /**
+     * Create a snapshot of the current run state
+     */
+    createSnapshot(runId: string, stepOutputs: Record<string, Record<string, unknown>>, env: Record<string, string>, refs?: RunSnapshot['refs']): Promise<RunSnapshot | null>;
+    /**
+     * Get a snapshot for a run
+     */
+    getSnapshot(runId: string): Promise<RunSnapshot | null>;
+    /**
+     * Replay a run from a snapshot, optionally starting from a specific step
+     */
+    replayRun(runId: string, options?: {
+        fromStepId?: string;
+        stepOutputs?: Record<string, Record<string, unknown>>;
+        env?: Record<string, string>;
+    }): Promise<WorkflowRun | null>;
+    /**
+     * Delete a snapshot
+     */
+    deleteSnapshot(runId: string): Promise<void>;
+    /**
+     * Get all active workflow executions (running or queued).
+     * Returns array of WorkflowRun objects with status 'running' or 'queued'.
+     */
+    getActiveExecutions(): Promise<WorkflowRun[]>;
+    /**
+     * Get all workflow runs (all statuses).
+     * Returns array of all WorkflowRun objects ordered by creation time.
+     */
+    getAllRuns(): Promise<WorkflowRun[]>;
+    /**
+     * List all workflow runs.
+     * Returns array of all runs in the system.
+     * Alias for getAllRuns() - maintained for backward compatibility.
+     */
+    listRuns(): Promise<WorkflowRun[]>;
+    /**
+     * Get workflow engine metrics.
+     * Returns statistics about runs, jobs, and system health.
+     */
+    getMetrics(): Promise<{
+        runs: {
+            total: number;
+            queued: number;
+            running: number;
+            completed: number;
+            failed: number;
+            cancelled: number;
+            dlq: number;
+        };
+        jobs: {
+            total: number;
+            queued: number;
+            running: number;
+            completed: number;
+            failed: number;
+        };
+    }>;
+}
+
+interface ArtifactMergerOptions {
+    stateStore: StateStore;
+    logger: EngineLogger;
+    artifactsRoot: string;
+}
+declare class ArtifactMerger {
+    private readonly options;
+    constructor(options: ArtifactMergerOptions);
+    mergeArtifacts(config: ArtifactMergeConfig, targetArtifacts: ArtifactClient, currentRunId: string): Promise<void>;
+    private loadArtifactsFromRun;
+    private loadArtifactContent;
+    private applyMergeStrategy;
+    private mergeAppend;
+    private mergeJson;
+    private deepMerge;
+    private saveMergedArtifact;
+}
+
+/**
+ * @module @kb-labs/workflow-engine/manifest-scanner
+ *
+ * Scans plugin manifests for workflows and jobs, converting them to unified WorkflowRuntime format.
+ *
+ * ## Features
+ * - Discovers workflows from `manifest.workflows.handlers`
+ * - Discovers jobs from `manifest.jobs`
+ * - Converts to unified WorkflowRuntime representation
+ * - Caches results via Platform state for performance
+ *
+ * ## Usage
+ * ```typescript
+ * const scanner = new ManifestScanner({ cliApi, platform });
+ * const workflows = await scanner.scanPlugins();
+ * ```
+ */
+
+/**
+ * Workflow trigger type
+ */
+type WorkflowTriggerType = 'manual' | 'webhook' | 'push' | 'schedule' | 'event';
+/**
+ * Workflow trigger configuration
+ */
+interface WorkflowTrigger {
+    type: WorkflowTriggerType;
+    config?: Record<string, unknown>;
+}
+/**
+ * Schedule configuration for workflows
+ */
+interface WorkflowSchedule {
+    /** Cron expression (e.g., "0 2 * * *") */
+    cron: string;
+    /** Whether schedule is enabled */
+    enabled: boolean;
+    /** Next run time (calculated) */
+    nextRun?: Date;
+    /** Last run time */
+    lastRun?: Date;
+}
+/**
+ * Workflow runtime statistics
+ */
+interface WorkflowStats {
+    totalRuns: number;
+    successRuns: number;
+    failedRuns: number;
+    lastRunStatus?: 'success' | 'failed' | 'cancelled';
+    lastRunAt?: Date;
+    avgDurationMs?: number;
+}
+/**
+ * Unified workflow runtime representation.
+ *
+ * Used for both manifest-based and standalone workflows.
+ */
+interface WorkflowRuntime {
+    id: string;
+    source: 'manifest' | 'standalone';
+    pluginId?: string;
+    manifestPath?: string;
+    name: string;
+    description?: string;
+    tags?: string[];
+    triggers: WorkflowTrigger[];
+    handler?: string;
+    schedule?: WorkflowSchedule;
+    status: 'active' | 'paused' | 'disabled';
+    stats?: WorkflowStats;
+    permissions?: unknown;
+    input?: unknown;
+    output?: unknown;
+    inputSchema?: Record<string, {
+        type: 'string' | 'number' | 'boolean';
+        description?: string;
+        required?: boolean;
+        default?: unknown;
+    }>;
+}
+/**
+ * Options for ManifestScanner
+ */
+interface ManifestScannerOptions {
+    /** CLI API instance */
+    cliApi: IEntityRegistry;
+    /** Platform services (for state, logger, etc.) */
+    platform: PlatformServices;
+    /** Cache TTL in milliseconds (default: 60000 = 1 minute) */
+    cacheTtlMs?: number;
+}
+/**
+ * Manifest Scanner Service
+ *
+ * Discovers workflows and jobs from installed plugin manifests.
+ */
+declare class ManifestScanner {
+    private readonly cliApi;
+    private readonly platform;
+    private readonly cacheTtlMs;
+    constructor(options: ManifestScannerOptions);
+    /**
+     * Scan all installed plugins for workflows and jobs.
+     *
+     * 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.
+     *
+     * Returns information needed to register handlers in JobManager.
+     */
+    scanJobHandlers(): Promise<Array<{
+        pluginId: string;
+        pluginVersion: string;
+        pluginRoot: string;
+        handler: JobHandlerDecl;
+    }>>;
+    /**
+     * Clear cache (useful for testing or force refresh).
+     */
+    clearCache(): Promise<void>;
+    /**
+     * Watch for plugin changes and invalidate cache.
+     *
+     * @param callback Optional callback when workflows change
+     * @returns Unsubscribe function
+     */
+    watchPlugins(callback?: (workflows: WorkflowRuntime[]) => void): () => void;
+}
+
+/**
+ * @module @kb-labs/workflow-engine/workflow-repository
+ *
+ * Repository for standalone workflow definitions.
+ *
+ * ## Features
+ * - CRUD operations for user-created workflows
+ * - File-based storage via platform.storage (`.kb/workflows/*.yaml`)
+ * - Validation using WorkflowSpecSchema
+ * - Conversion to unified WorkflowRuntime format
+ *
+ * ## Usage
+ * ```typescript
+ * const repo = new WorkflowRepository({ platform });
+ * const workflow = await repo.create(spec);
+ * ```
+ */
+
+/**
+ * List options for filtering workflows
+ */
+interface WorkflowListOptions {
+    status?: 'active' | 'paused' | 'disabled';
+    tags?: string[];
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Options for WorkflowRepository
+ */
+interface WorkflowRepositoryOptions {
+    /** Platform services (for storage, logger, etc.) */
+    platform: PlatformServices;
+    /** Storage directory for workflows (default: '.kb/workflows') */
+    storageDir?: string;
+    /** Workspace root directory (default: process.cwd()) */
+    workspaceRoot?: string;
+}
+/**
+ * Workflow Repository
+ *
+ * Manages standalone workflow definitions (user-created via UI/API).
+ * Uses platform.storage for persistence.
+ */
+declare class WorkflowRepository {
+    private readonly platform;
+    private readonly storageDir;
+    private readonly workspaceRoot;
+    private readonly absoluteStorageDir;
+    constructor(options: WorkflowRepositoryOptions);
+    /**
+     * Create a new standalone workflow.
+     */
+    create(spec: WorkflowSpec): Promise<WorkflowRuntime>;
+    /**
+     * Get workflow by ID.
+     */
+    get(id: string): Promise<WorkflowRuntime | null>;
+    /**
+     * List all workflows with optional filtering.
+     */
+    list(options?: WorkflowListOptions): Promise<WorkflowRuntime[]>;
+    /**
+     * Update existing workflow.
+     */
+    update(id: string, spec: Partial<WorkflowSpec>): Promise<WorkflowRuntime>;
+    /**
+     * Delete workflow.
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Enable workflow (set status to active).
+     */
+    enable(id: string): Promise<void>;
+    /**
+     * Disable workflow.
+     */
+    disable(id: string): Promise<void>;
+    /**
+     * Pause workflow.
+     */
+    pause(id: string): Promise<void>;
+    /**
+     * Resume workflow (unpause).
+     */
+    resume(id: string): Promise<void>;
+    /**
+     * Update workflow statistics.
+     */
+    updateStats(id: string, stats: Partial<WorkflowStats>): Promise<void>;
+    private updateStatus;
+    private getWorkflowPath;
+    private saveWorkflow;
+    private loadWorkflow;
+    private listWorkflowFiles;
+    /**
+     * Convert stored workflow to WorkflowRuntime format.
+     */
+    private toRuntime;
+}
+
+/**
+ * @module @kb-labs/workflow-engine/workflow-service
+ *
+ * Unified service for managing all workflows (manifest-based + standalone).
+ *
+ * ## Features
+ * - Combines ManifestScanner and WorkflowRepository
+ * - Unified interface for listing/getting workflows from both sources
+ * - Provides available handlers for UI autocomplete
+ * - Validates workflow specs
+ *
+ * ## Usage
+ * ```typescript
+ * const service = new WorkflowService({ cliApi, platform });
+ * const allWorkflows = await service.listAll();
+ * const workflow = await service.get('release-manager/create-release');
+ * ```
+ */
+
+/**
+ * Handler information for UI autocomplete
+ */
+interface WorkflowHandlerInfo {
+    /** Handler ID (e.g., "release-manager/create-release") */
+    id: string;
+    /** Plugin ID */
+    pluginId: string;
+    /** Human-readable name */
+    name: string;
+    /** Description */
+    description?: string;
+    /** Input schema */
+    inputSchema?: unknown;
+    /** Output schema */
+    outputSchema?: unknown;
+}
+/**
+ * Validation result
+ */
+interface ValidationResult {
+    valid: boolean;
+    errors?: Array<{
+        path: string;
+        message: string;
+    }>;
+}
+/**
+ * List options for workflows
+ */
+interface WorkflowServiceListOptions extends WorkflowListOptions {
+    /** Filter by source type */
+    source?: 'manifest' | 'standalone';
+}
+/**
+ * Options for WorkflowService
+ */
+interface WorkflowServiceOptions {
+    /** CLI API for plugin manifest scanning */
+    cliApi: IEntityRegistry;
+    /** Platform services */
+    platform: PlatformServices;
+    /** Cache TTL for manifest scanner (ms) */
+    manifestCacheTtlMs?: number;
+    /** Storage directory for standalone workflows */
+    workflowStorageDir?: string;
+    /** Workspace root directory (default: process.cwd()) */
+    workspaceRoot?: string;
+}
+/**
+ * Unified Workflow Service
+ *
+ * Combines manifest-based and standalone workflows into a single interface.
+ */
+declare class WorkflowService {
+    private readonly scanner;
+    private readonly repository;
+    private readonly platform;
+    constructor(options: WorkflowServiceOptions);
+    /**
+     * List all workflows (manifest + standalone).
+     */
+    listAll(options?: WorkflowServiceListOptions): Promise<WorkflowRuntime[]>;
+    /**
+     * Get workflow by ID (from either source).
+     */
+    get(id: string): Promise<WorkflowRuntime | null>;
+    /**
+     * Create standalone workflow.
+     */
+    create(spec: WorkflowSpec): Promise<WorkflowRuntime>;
+    /**
+     * Update standalone workflow.
+     */
+    update(id: string, spec: Partial<WorkflowSpec>): Promise<WorkflowRuntime>;
+    /**
+     * Delete standalone workflow.
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Enable workflow (set status to active).
+     */
+    enable(id: string): Promise<void>;
+    /**
+     * Disable workflow.
+     */
+    disable(id: string): Promise<void>;
+    /**
+     * Pause workflow.
+     */
+    pause(id: string): Promise<void>;
+    /**
+     * Resume workflow (unpause).
+     */
+    resume(id: string): Promise<void>;
+    /**
+     * Get available workflow handlers (for UI autocomplete).
+     *
+     * Returns manifest-based handlers that can be used in standalone workflows
+     * (via `uses: "plugin:id/handler"`).
+     */
+    getAvailableHandlers(): Promise<WorkflowHandlerInfo[]>;
+    /**
+     * Validate workflow spec.
+     */
+    validate(spec: WorkflowSpec): ValidationResult;
+    /**
+     * Refresh manifest scanner cache (force re-scan).
+     */
+    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;
+    description?: string;
+    filePath: string;
+    spec: WorkflowSpec;
+    metadata?: Record<string, unknown>;
+}
+interface WorkflowRegistryOptions {
+    scanDirs: string[];
+    cwd?: string;
+    logger: ILogger;
+}
+/**
+ * WorkflowRegistry - Auto-discovery and indexing of workflow definitions
+ *
+ * Scans directories for .yml workflow files and indexes them by ID.
+ * Provides clean API for finding and running workflows.
+ */
+declare class WorkflowRegistry {
+    private readonly options;
+    private entries;
+    private loader;
+    constructor(options: WorkflowRegistryOptions);
+    /**
+     * Scan configured directories and index all workflow files
+     */
+    scan(): Promise<void>;
+    /**
+     * Index a single workflow file
+     */
+    private indexFile;
+    /**
+     * Parse workflow file (YAML format with additional fields)
+     */
+    private parseWorkflowFile;
+    /**
+     * Get workflow by ID
+     */
+    get(id: string): WorkflowRegistryEntry | undefined;
+    /**
+     * List all registered workflows
+     */
+    list(): WorkflowRegistryEntry[];
+    /**
+     * Check if workflow exists
+     */
+    has(id: string): boolean;
+    /**
+     * Get workflow spec by ID
+     */
+    getSpec(id: string): WorkflowSpec | undefined;
+    /**
+     * Clear all indexed workflows
+     */
+    clear(): void;
+}
+
+/**
+ * @module @kb-labs/workflow-engine/job-manager
+ * Job manager for background task execution with sandboxed handlers.
+ */
+
+interface JobManagerConfig {
+    /** Execution backend for sandboxed handler execution */
+    executionBackend?: IExecutionBackend<PluginContextDescriptor>;
+    /** Default job timeout in ms (default: 300000 = 5 min) */
+    defaultTimeout?: number;
+    /** Default max retries (default: 3) */
+    defaultMaxRetries?: number;
+    /** Default priority (default: 50) */
+    defaultPriority?: number;
+    /** Workspace root (monorepo root) for plugin execution context */
+    workspaceRoot?: string;
+}
+/**
+ * Job manager - handles background job execution with sandboxed handlers.
+ *
+ * Features:
+ * - Declarative job handlers from plugin manifests
+ * - Priority-based queue (0-100, higher = more important)
+ * - Retry with exponential/linear backoff
+ * - Sandboxed subprocess execution via ExecutionBackend
+ * - Progress tracking and status updates
+ * - Idempotency support
+ *
+ * Architecture:
+ * 1. Plugin declares job handlers in manifest.json
+ * 2. Plugin runtime registers handlers via registerJobHandler()
+ * 3. Plugin submits jobs via ctx.api.jobs.submit()
+ * 4. JobManager enqueues job in priority queue (platform.cache sorted sets)
+ * 5. Worker dequeues job and executes via ExecutionBackend.execute()
+ * 6. Handler runs in subprocess with JobContext
+ * 7. Results stored in cache, events emitted
+ */
+declare class JobManager implements IJobScheduler {
+    private readonly cache;
+    private readonly events;
+    private readonly logger;
+    private readonly config;
+    private handlerRegistry;
+    private readonly defaultTimeout;
+    private readonly defaultMaxRetries;
+    private readonly defaultPriority;
+    private readonly workspaceRoot;
+    constructor(cache: ICache, events: IEventBus, logger: ILogger, config?: JobManagerConfig);
+    /**
+     * Register job handler from plugin manifest.
+     *
+     * Called by plugin-runtime during plugin initialization.
+     *
+     * @param pluginId - Plugin identifier
+     * @param pluginVersion - Plugin version
+     * @param pluginRoot - Plugin root directory
+     * @param handlerDecl - Job handler declaration from manifest
+     */
+    registerJobHandler(pluginId: string, pluginVersion: string, pluginRoot: string, handlerDecl: JobHandlerDecl): void;
+    /**
+     * Submit a job for immediate execution.
+     */
+    submit(job: JobDefinition): Promise<JobHandle>;
+    /**
+     * Schedule a job for future/recurring execution.
+     */
+    schedule(job: JobDefinition, schedule: CronExpression | Date): Promise<JobHandle>;
+    /**
+     * Cancel a pending/running job.
+     */
+    cancel(jobId: string): Promise<boolean>;
+    /**
+     * Get job status.
+     */
+    getStatus(jobId: string): Promise<JobHandle | null>;
+    /**
+     * List jobs.
+     */
+    list(filter?: JobFilter): Promise<JobHandle[]>;
+    /**
+     * Execute a job (called by worker).
+     *
+     * @internal
+     */
+    executeJob(jobId: string): Promise<void>;
+    /**
+     * Update job progress.
+     *
+     * Called by job handler via ctx.updateProgress()
+     */
+    updateProgress(jobId: string, percent: number, message?: string): Promise<void>;
+    private handleJobFailure;
+    private markJobFailed;
+    private calculateBackoff;
+    private saveJobRecord;
+    private getJobRecord;
+    private enqueueJob;
+    private removeFromQueue;
+    private findByIdempotencyKey;
+    private getAllJobKeys;
+    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 };