eve/dist/src/compiled/@workflow/core/runtime/lifecycle-hooks.d.ts

Filesystem-first framework for durable backend AI agents that run anywhere.

import { WorkflowRunFailedError } from '#compiled/@workflow/errors/index.js';
import type { PayloadKey } from '../serialization/encryption.js';
import { Run } from './run.js';
/**
 * Parameters passed to an {@link WorkflowLifecycleHooks.onRunCompleted}
 * handler.
 */
export interface RunCompletedHookParams {
    /** The workflow name, available without fetching the run. */
    workflowName: string;
    /**
     * The completed run. The instance hydrates lazily, so reading
     * `run.returnValue` (or any other accessor) fetches from the backend only
     * when the handler actually uses it.
     */
    run: Run<unknown>;
}
/**
 * Parameters passed to an {@link WorkflowLifecycleHooks.onRunFailed}
 * handler.
 */
export interface RunFailedHookParams {
    /** The workflow name, available without fetching the run. */
    workflowName: string;
    /**
     * The failed run. The instance hydrates lazily, so accessors fetch from
     * the backend only when the handler actually uses them.
     */
    run: Run<unknown>;
    /**
     * The failure, in the same shape `run.returnValue` rejects with: a
     * `WorkflowRunFailedError` whose `errorCode` carries the failure
     * classification (e.g. `USER_ERROR`, `RUNTIME_ERROR`) and whose `cause` is
     * the hydrated persisted value (registered Error subclass identity preserved).
     * Streams are read only when consumed; abort signals reflect their persisted
     * state without live subscriptions. If hydration fails, `cause` is a generic
     * Error, matching `run.returnValue`'s fallback.
     */
    error: WorkflowRunFailedError;
}
/**
 * Global handlers observing workflow run lifecycle transitions. Register via
 * {@link registerLifecycleHooks}.
 */
export interface WorkflowLifecycleHooks {
    /** Invoked when a workflow run completes successfully. */
    onRunCompleted?: (params: RunCompletedHookParams) => void | Promise<void>;
    /** Invoked when a workflow run fails terminally (after any retries). */
    onRunFailed?: (params: RunFailedHookParams) => void | Promise<void>;
}
/**
 * Registers global workflow lifecycle handlers, invoked by the runtime on
 * the compute that records a run's terminal transition. Useful for
 * centralized reporting (e.g. forwarding failed runs to Sentry) without
 * wrapping every workflow body.
 *
 * Register early in the process lifecycle so handlers exist before the first
 * run finishes: in Next.js, `instrumentation.ts` is the natural place; in any
 * other app, any module that loads at startup works.
 *
 * Semantics:
 * - Handlers run on the host (full Node.js), never inside the workflow VM.
 * - Handlers fire only on the invocation that actually wrote the terminal
 *   event. Transitions recorded elsewhere (e.g. a run cancelled from the
 *   CLI or dashboard) do not fire handlers in the app.
 * - Handlers are fire-and-forget: they cannot delay or change the run's
 *   outcome, and a throwing handler is logged and swallowed. On Vercel,
 *   `waitUntil` keeps the invocation alive. On other hosts handlers run
 *   detached, and freezing serverless hosts may not let them finish.
 * - Reporting is best effort: callbacks are not retried if the invocation
 *   dies before they finish. Use the event log as the system of record.
 * - Multiple registrations are allowed; handlers run in registration order.
 *
 * @returns A function that unregisters these hooks.
 */
export declare function registerLifecycleHooks(hooks: WorkflowLifecycleHooks): () => void;
/**
 * Called by the runtime after it successfully wrote a `run_completed` event.
 * Never throws.
 */
export declare function dispatchRunCompletedHooks(runId: string, workflowName: string): void;
/**
 * Called by the runtime after it successfully wrote a `run_failed` event.
 * Never throws.
 *
 * @param error - The serialized error payload stored by the terminal write.
 * @param errorCode - The classification written to the event's `errorCode`.
 */
export declare function dispatchRunFailedHooks(runId: string, workflowName: string, error: unknown, encryptionKey: PayloadKey | undefined, errorCode: string): void;
//# sourceMappingURL=lifecycle-hooks.d.ts.map