@xyne/workflow-sdk 1.0.0

package/dist/runtime/execution-event-bus.d.ts

@@ -0,0 +1,38 @@
+/**
+ * ExecutionEventBus — in-memory pub/sub for execution stream events.
+ *
+ * The executor emits events at state transitions (step started/completed/failed,
+ * execution paused/completed/failed). The SSE route subscribes per-executionId
+ * and streams them to the client.
+ */
+import type { ExecutionStreamEvent } from './types.js';
+type EventCallback = (event: ExecutionStreamEvent) => void;
+export declare class ExecutionEventBus {
+    private readonly listeners;
+    /**
+     * Subscribe to events for a specific execution.
+     * Returns an unsubscribe function.
+     */
+    subscribe(executionId: string, cb: EventCallback): () => void;
+    /**
+     * Emit an event to all listeners for the given execution.
+     */
+    emit(executionId: string, event: ExecutionStreamEvent): void;
+}
+/**
+ * Bridges push-based event bus callbacks to an AsyncIterable.
+ *
+ * Usage:
+ *   const ch = createEventChannel<ExecutionStreamEvent>();
+ *   const unsub = eventBus.subscribe(execId, ch.push);
+ *   for await (const event of ch) { ... }
+ *   ch.end(); // terminates the iterator
+ */
+export interface EventChannel<T> {
+    push: (value: T) => void;
+    end: () => void;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}
+export declare function createEventChannel<T>(): EventChannel<T>;
+export {};
+//# sourceMappingURL=execution-event-bus.d.ts.map

package/dist/runtime/execution-event-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-event-bus.d.ts","sourceRoot":"","sources":["../../src/runtime/execution-event-bus.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD,KAAK,aAAa,GAAG,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,CAAC;AAE3D,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyC;IAEnE;;;OAGG;IACH,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,aAAa,GAAG,MAAM,IAAI;IAgB7D;;OAEG;IACH,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,oBAAoB,GAAG,IAAI;CAW7D;AAID;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IACzB,GAAG,EAAE,MAAM,IAAI,CAAC;IAChB,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC,CAAC;CAC5C;AAED,wBAAgB,kBAAkB,CAAC,CAAC,KAAK,YAAY,CAAC,CAAC,CAAC,CA0CvD"}

package/dist/runtime/execution-event-bus.js

@@ -0,0 +1,87 @@
+/**
+ * ExecutionEventBus — in-memory pub/sub for execution stream events.
+ *
+ * The executor emits events at state transitions (step started/completed/failed,
+ * execution paused/completed/failed). The SSE route subscribes per-executionId
+ * and streams them to the client.
+ */
+export class ExecutionEventBus {
+    listeners = new Map();
+    /**
+     * Subscribe to events for a specific execution.
+     * Returns an unsubscribe function.
+     */
+    subscribe(executionId, cb) {
+        let set = this.listeners.get(executionId);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(executionId, set);
+        }
+        set.add(cb);
+        return () => {
+            set.delete(cb);
+            if (set.size === 0) {
+                this.listeners.delete(executionId);
+            }
+        };
+    }
+    /**
+     * Emit an event to all listeners for the given execution.
+     */
+    emit(executionId, event) {
+        const set = this.listeners.get(executionId);
+        if (!set)
+            return;
+        for (const cb of set) {
+            try {
+                cb(event);
+            }
+            catch {
+                // Never let a listener error break the executor
+            }
+        }
+    }
+}
+export function createEventChannel() {
+    const queue = [];
+    let resolve = null;
+    let done = false;
+    return {
+        push(value) {
+            if (done)
+                return;
+            if (resolve) {
+                const r = resolve;
+                resolve = null;
+                r({ value, done: false });
+            }
+            else {
+                queue.push(value);
+            }
+        },
+        end() {
+            done = true;
+            if (resolve) {
+                const r = resolve;
+                resolve = null;
+                r({ value: undefined, done: true });
+            }
+        },
+        [Symbol.asyncIterator]() {
+            return {
+                next() {
+                    if (queue.length > 0) {
+                        return Promise.resolve({ value: queue.shift(), done: false });
+                    }
+                    if (done) {
+                        return Promise.resolve({ value: undefined, done: true });
+                    }
+                    return new Promise((r) => {
+                        resolve = r;
+                    });
+                },
+            };
+        },
+    };
+}
+//# sourceMappingURL=execution-event-bus.js.map

package/dist/runtime/execution-event-bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-event-bus.js","sourceRoot":"","sources":["../../src/runtime/execution-event-bus.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,MAAM,OAAO,iBAAiB;IACX,SAAS,GAAG,IAAI,GAAG,EAA8B,CAAC;IAEnE;;;OAGG;IACH,SAAS,CAAC,WAAmB,EAAE,EAAiB;QAC9C,IAAI,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QAC1C,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;YAChB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;QACvC,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAEZ,OAAO,GAAG,EAAE;YACV,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACf,IAAI,GAAG,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;gBACnB,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;YACrC,CAAC;QACH,CAAC,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,IAAI,CAAC,WAAmB,EAAE,KAA2B;QACnD,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QAC5C,IAAI,CAAC,GAAG;YAAE,OAAO;QACjB,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;YACrB,IAAI,CAAC;gBACH,EAAE,CAAC,KAAK,CAAC,CAAC;YACZ,CAAC;YAAC,MAAM,CAAC;gBACP,gDAAgD;YAClD,CAAC;QACH,CAAC;IACH,CAAC;CACF;AAmBD,MAAM,UAAU,kBAAkB;IAChC,MAAM,KAAK,GAAQ,EAAE,CAAC;IACtB,IAAI,OAAO,GAAiD,IAAI,CAAC;IACjE,IAAI,IAAI,GAAG,KAAK,CAAC;IAEjB,OAAO;QACL,IAAI,CAAC,KAAQ;YACX,IAAI,IAAI;gBAAE,OAAO;YACjB,IAAI,OAAO,EAAE,CAAC;gBACZ,MAAM,CAAC,GAAG,OAAO,CAAC;gBAClB,OAAO,GAAG,IAAI,CAAC;gBACf,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YAC5B,CAAC;iBAAM,CAAC;gBACN,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACpB,CAAC;QACH,CAAC;QAED,GAAG;YACD,IAAI,GAAG,IAAI,CAAC;YACZ,IAAI,OAAO,EAAE,CAAC;gBACZ,MAAM,CAAC,GAAG,OAAO,CAAC;gBAClB,OAAO,GAAG,IAAI,CAAC;gBACf,CAAC,CAAC,EAAE,KAAK,EAAE,SAAc,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC3C,CAAC;QACH,CAAC;QAED,CAAC,MAAM,CAAC,aAAa,CAAC;YACpB,OAAO;gBACL,IAAI;oBACF,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;wBACrB,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAG,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;oBACjE,CAAC;oBACD,IAAI,IAAI,EAAE,CAAC;wBACT,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,SAAc,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;oBAChE,CAAC;oBACD,OAAO,IAAI,OAAO,CAAoB,CAAC,CAAC,EAAE,EAAE;wBAC1C,OAAO,GAAG,CAAC,CAAC;oBACd,CAAC,CAAC,CAAC;gBACL,CAAC;aACF,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/runtime/types.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Types for the WorkflowRuntime orchestrator.
+ */
+import type { PersistenceAdapter, QueueAdapter, SchedulerAdapter } from '../persistence/types.js';
+import type { StepRegistry } from '../steps/step-registry.js';
+import type { TriggerRegistry } from '../triggers/trigger-registry.js';
+import type { WorkflowExecutor, ExecutorLogger } from '../engine/workflow-executor.js';
+import type { ServiceRegistry } from '../engine/service-registry.js';
+import type { StorageAdapter } from '../storage/types.js';
+import type { ExecutionEventBus } from './execution-event-bus.js';
+export type ExecutionResult = {
+    status: 'completed';
+} | {
+    status: 'paused';
+    reason: string;
+    externalRef?: string;
+} | {
+    status: 'failed';
+    error: string;
+} | {
+    status: 'skipped';
+    reason: string;
+} | {
+    status: 'not_found';
+};
+/**
+ * Scalar runtime settings — host policy knobs grouped under one bag so the
+ * top-level constructor signature stays focused on adapters and registries.
+ *
+ * All fields optional with sensible defaults; pass an empty `{}` or omit
+ * `config` entirely to accept them.
+ */
+export interface RuntimeConfig {
+    /** Base URL for webhook URL generation (e.g. 'https://api.example.com'). Default: `''`. */
+    baseUrl?: string;
+    /**
+     * IANA timezone string applied to every cron-triggered workflow scheduled
+     * by this runtime. Cron triggers don't expose timezone to workflow authors —
+     * every cron job in a deployment runs against this single zone.
+     * Default: `'Asia/Kolkata'`.
+     */
+    defaultCronTimezone?: string;
+    /**
+     * Allow uploads of files with executable MIME types / extensions
+     * (.exe, .dll, .sh, .jar, .docm, etc). The upload route rejects them at
+     * the perimeter unless this is `true`. Default: `false`.
+     */
+    allowExecutableUploads?: boolean;
+}
+export interface RuntimeOptions<TServices extends Record<string, unknown> = Record<string, unknown>> {
+    persistence: PersistenceAdapter;
+    queue: QueueAdapter;
+    scheduler: SchedulerAdapter;
+    services: ServiceRegistry<TServices>;
+    steps: StepRegistry;
+    triggers: TriggerRegistry;
+    executor: WorkflowExecutor<TServices>;
+    /**
+     * Optional storage adapter for file attachments. Required if any workflow
+     * uses the trigger `attachments` slot or accepts attachments in resume
+     * payloads. Routes that need storage will return 501 if it's omitted.
+     */
+    storage?: StorageAdapter;
+    /** Event bus for real-time SSE streaming of execution events. */
+    eventBus?: ExecutionEventBus;
+    logger?: ExecutorLogger;
+    config?: RuntimeConfig;
+}
+export interface DispatchEventInput {
+    type: string;
+    payload: Record<string, unknown>;
+    /** Host metadata — passed to persistence.findActiveWorkflows(). */
+    metadata: Record<string, unknown>;
+}
+import type { ResumePayload } from '../common/resume-payload.js';
+export interface ResumeInput {
+    /** Resume payload submitted by the host UI. */
+    data?: ResumePayload;
+    /**
+     * If true, the execution is aborted rather than continued. Equivalent to
+     * `data: { action: 'abort' }` — kept as a top-level convenience.
+     */
+    abort?: boolean;
+}
+import type { PauseState } from '../types/pause-state.js';
+export type ExecutionStreamEvent = {
+    event: 'step_started';
+    data: {
+        stepName: string;
+        stepType: string;
+    };
+} | {
+    event: 'step_completed';
+    data: {
+        stepName: string;
+        output: Record<string, unknown>;
+    };
+} | {
+    event: 'step_failed';
+    data: {
+        stepName: string;
+        error: string;
+    };
+} | {
+    event: 'step_progress';
+    data: {
+        stepName: string;
+    } & Record<string, unknown>;
+} | {
+    event: 'execution_paused';
+    data: {
+        stepName: string;
+        pauseState: PauseState;
+    };
+} | {
+    event: 'execution_completed';
+    data: {
+        status: string;
+    };
+} | {
+    event: 'execution_failed';
+    data: {
+        error: string;
+    };
+} | {
+    event: 'execution_cancelled';
+    data: Record<string, unknown>;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/runtime/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/runtime/types.ts"],"names":[],"mappings":"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"}

package/dist/runtime/types.js

@@ -0,0 +1,5 @@
+/**
+ * Types for the WorkflowRuntime orchestrator.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/runtime/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/runtime/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/runtime/workflow-runtime.d.ts

@@ -0,0 +1,256 @@
+/**
+ * WorkflowRuntime — the central orchestrator.
+ *
+ * Ties together: persistence, queue, scheduler, executor, triggers, and steps.
+ * The host creates one runtime instance and uses it for all workflow operations:
+ *
+ * - Activate/deactivate triggers (cron, webhook)
+ * - Dispatch domain events → matching workflows
+ * - Handle incoming webhooks
+ * - Fire manual triggers
+ * - Resume paused executions
+ * - Process queued jobs (the worker loop body)
+ */
+import type { RuntimeOptions, DispatchEventInput, ResumeInput, ExecutionResult } from './types.js';
+import type { ExecutionEventBus } from './execution-event-bus.js';
+import type { WorkflowConfig } from '../types/workflow-config.js';
+import type { ValidationResult } from '../types/validation.js';
+import type { WorkflowRecord, ExecutionRecord, StepRecord, WorkflowCallbackRecord } from '../persistence/types.js';
+import type { StorageAdapter } from '../storage/types.js';
+import type { Attachment } from '../common/attachment.js';
+import type { StepRegistry } from '../steps/step-registry.js';
+import type { TriggerRegistry } from '../triggers/trigger-registry.js';
+import type { WebhookRequest } from '../triggers/webhook-trigger.js';
+export declare class WorkflowRuntime<TServices extends Record<string, unknown> = Record<string, unknown>> {
+    private readonly persistence;
+    private readonly queue;
+    private readonly scheduler;
+    private readonly services;
+    readonly steps: StepRegistry;
+    readonly triggers: TriggerRegistry;
+    private readonly executor;
+    private readonly log;
+    private readonly baseUrl;
+    /** Event bus for real-time SSE streaming. Exposed for the router. */
+    readonly eventBus?: ExecutionEventBus | undefined;
+    /** Storage adapter for file attachments. Exposed for the router. */
+    readonly storage?: StorageAdapter | undefined;
+    /** When true, the upload route accepts executable MIME types / extensions. */
+    readonly allowExecutableUploads: boolean;
+    /** IANA timezone applied to every cron-triggered workflow. */
+    readonly defaultCronTimezone: string;
+    constructor(opts: RuntimeOptions<TServices>);
+    /**
+     * Validate a workflow config before saving.
+     *
+     * The host's save handler should call this and reject the save if
+     * `result.valid` is false. Returns structured issues the frontend
+     * can render inline in the workflow builder.
+     */
+    validateConfig(config: WorkflowConfig): ValidationResult;
+    /**
+     * Activate a workflow's trigger.
+     *
+     * - WebhookTrigger: generates a unique path, stores it, calls onActivate()
+     * - CronTrigger: registers with the scheduler
+     * - EventTrigger / ManualTrigger: no activation needed (status change only)
+     */
+    activateWorkflow(workflowId: string): Promise<void>;
+    /**
+     * Deactivate a workflow's trigger.
+     */
+    deactivateWorkflow(workflowId: string): Promise<void>;
+    /**
+     * Lazy-allocate the workflow's stable wait-callback secret. Idempotent —
+     * if a secret already exists, returns the existing record.
+     *
+     * Host calls this when saving a workflow that uses wait-step webhook
+     * mode, then surfaces the URL in the UI so the author can paste it into
+     * the external system's configuration.
+     */
+    ensureWorkflowCallback(workflowId: string): Promise<WorkflowCallbackRecord>;
+    /**
+     * Rotate the workflow's wait-callback secret. The old URL stops working
+     * immediately. Author has to update external configurations.
+     */
+    rotateWorkflowCallback(workflowId: string): Promise<WorkflowCallbackRecord>;
+    /**
+     * Build the wait-callback URL template the author should paste into
+     * their external system. `{executionId}` is the placeholder the HTTP
+     * step substitutes via `{{ runtime.executionId }}`.
+     */
+    buildWaitCallbackUrl(secret: string, executionId?: string): string;
+    /**
+     * Dispatch a domain event. Finds all active workflows that match,
+     * hydrates payloads, applies filters, and enqueues executions.
+     *
+     * Returns the execution IDs that were created.
+     */
+    dispatchEvent(event: DispatchEventInput): Promise<string[]>;
+    /**
+     * Handle an incoming webhook request.
+     *
+     * Looks up the workflow by webhook path, delegates to the trigger's
+     * `handleRequest()`, and enqueues an execution.
+     */
+    handleWebhook(path: string, request: WebhookRequest): Promise<{
+        executionId: string;
+        httpResponse: {
+            status: number;
+            headers?: Record<string, string>;
+            body?: unknown;
+        };
+    }>;
+    /**
+     * Handle an incoming wait-callback at `POST /wait/callback/<secret>/<executionId>`.
+     *
+     * The `secret` is the workflow's stable callback secret (generated at
+     * workflow create). The `executionId` is the in-flight execution that
+     * paused on a wait-webhook step — the workflow's HTTP step interpolated
+     * it into the URL it gave the external system via
+     * `{{ runtime.executionId }}`.
+     *
+     * Validation:
+     * 1. Secret resolves to a workflow (404 on miss, same hash-map security
+     *    as trigger webhooks — wrong/unknown secrets are indistinguishable).
+     * 2. Execution exists, is EXTERNAL_WAIT, and belongs to that workflow
+     *    (404 otherwise; same 404 so attackers can't probe for valid
+     *    execution IDs by guessing).
+     *
+     * On success, the callback body becomes the resume payload and the
+     * execution is re-enqueued. The wait step's `onResume` sees it as
+     * `resumeData`.
+     */
+    handleWaitCallback(secret: string, executionId: string, body: unknown): Promise<{
+        status: number;
+        body: unknown;
+    }>;
+    /**
+     * Fire a workflow manually via API.
+     *
+     * `attachments` is validated against the trigger's `attachments` config
+     * (mime accept-list, maxCount, required). Validated refs are merged into
+     * the trigger payload as `context.trigger.attachments`.
+     *
+     * Returns the execution ID.
+     */
+    triggerManual(workflowId: string, payload: Record<string, unknown>, attachments?: Attachment[]): Promise<string>;
+    /**
+     * Resume a paused execution.
+     *
+     * Stores the resume payload and re-enqueues the execution.
+     */
+    resume(executionId: string, input?: ResumeInput): Promise<void>;
+    /**
+     * Rerun a workflow from a specific step, using the source execution's
+     * cached outputs for all prior steps. Creates a new execution.
+     *
+     * Used for:
+     * - "Rerun from step N" — replay downstream with same upstream data
+     * - "Modify input and rerun" — pass `configOverrides` to change the
+     *   entry step's input
+     * - Agent feedback after execution completed — pass `configOverrides`
+     *   with new `userMessage`; agent receives `priorState.messages` and
+     *   continues the conversation
+     *
+     * Returns the new execution ID.
+     */
+    rerunFromStep(sourceExecutionId: string, fromStepId: string, options?: {
+        configOverrides?: Record<string, unknown>;
+        inheritStepState?: boolean;
+    }): Promise<string>;
+    /**
+     * List all workflows visible to the given auth metadata.
+     */
+    listWorkflows(metadata: Record<string, unknown>): Promise<WorkflowRecord[]>;
+    /**
+     * Get a single workflow by ID.
+     */
+    getWorkflow(workflowId: string): Promise<WorkflowRecord | null>;
+    /**
+     * Create a new workflow definition.
+     *
+     * Validates the config, persists it, and optionally activates the trigger.
+     * Returns the created WorkflowRecord.
+     */
+    createWorkflow(input: {
+        name: string;
+        config: WorkflowConfig;
+        metadata?: Record<string, unknown>;
+    }): Promise<WorkflowRecord>;
+    /**
+     * Update an existing workflow definition.
+     *
+     * Accepts partial updates: config, metadata, or both.
+     * If config changes, validates it and updates the trigger type.
+     */
+    updateWorkflow(workflowId: string, input: {
+        name?: string;
+        config?: WorkflowConfig;
+        metadata?: Record<string, unknown>;
+    }): Promise<WorkflowRecord>;
+    /**
+     * List executions with optional filters and cursor pagination.
+     */
+    listExecutions(params: {
+        workflowId?: string;
+        status?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        items: ExecutionRecord[];
+        nextCursor?: string;
+    }>;
+    /**
+     * Get execution detail including step records.
+     */
+    getExecutionDetail(executionId: string): Promise<{
+        execution: ExecutionRecord;
+        steps: StepRecord[];
+        config?: WorkflowConfig;
+        triggerData?: Record<string, unknown>;
+    } | null>;
+    /**
+     * Cancel a running or paused execution.
+     */
+    cancelExecution(executionId: string): Promise<void>;
+    /**
+     * List credentials visible to the given auth metadata.
+     */
+    listCredentials(metadata: Record<string, unknown>): Promise<Array<{
+        name: string;
+        type: string;
+    }>>;
+    /**
+     * Store a credential.
+     */
+    createCredential(metadata: Record<string, unknown>, name: string, credential: {
+        type: string;
+        data: Record<string, unknown>;
+    }): Promise<{
+        name: string;
+        type: string;
+    }>;
+    /**
+     * Delete a credential by name.
+     */
+    deleteCredential(metadata: Record<string, unknown>, name: string): Promise<void>;
+    /**
+     * The queue consumer body. The host's queue worker calls this for each job.
+     *
+     * ```ts
+     * workflowQueue.process((job) => runtime.processJob(job.data.executionId));
+     * ```
+     */
+    processJob(executionId: string): Promise<ExecutionResult>;
+    /**
+     * Process a cron tick for a workflow.
+     *
+     * Called by the scheduler when a cron job fires. Checks poll() if available,
+     * otherwise fires unconditionally.
+     */
+    processCronTick(workflowId: string): Promise<string | null>;
+    private createAndEnqueue;
+    private resolveCredentialsForTrigger;
+}
+//# sourceMappingURL=workflow-runtime.d.ts.map

package/dist/runtime/workflow-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-runtime.d.ts","sourceRoot":"","sources":["../../src/runtime/workflow-runtime.ts"],"names":[],"mappings":"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"}