eve
Version:
Filesystem-first framework for durable backend AI agents that run anywhere.
107 lines • 4.99 kB
TypeScript
import type { Event, HealthCheckPayload, ValidQueueName, WorkflowRun, World } from '#compiled/@workflow/world/index.js';
import { type CryptoKey } from '../encryption.js';
/**
* Validates a workflow name and returns the corresponding queue name.
* Ensures the workflow name only contains safe characters before
* interpolating it into the queue name string.
*/
export declare function getWorkflowQueueName(workflowName: string, namespace?: string): ValidQueueName;
/**
* Result of a health check operation.
*/
export interface HealthCheckResult {
healthy: boolean;
/** Error message if health check failed */
error?: string;
/** Latency if the health check was successful */
latencyMs?: number;
/** Spec version of the responding deployment */
specVersion?: number;
/**
* `@workflow/core` version of the responding deployment, used for
* capability detection (see `getRunCapabilities`). Omitted when the
* responding deployment did not provide the field as a string —
* for example, an older `@workflow/core` that predates this field,
* or a non-JSON plain-text health response.
*/
workflowCoreVersion?: string;
}
/**
* Checks if the given message is a health check payload.
* If so, returns the parsed payload. Otherwise returns undefined.
*/
export declare function parseHealthCheckPayload(message: unknown): HealthCheckPayload | undefined;
/**
* Handles a health check message by writing the result to the world's stream.
* The caller can listen to this stream to get the health check response.
*
* @param healthCheck - The parsed health check payload
* @param endpoint - Which endpoint is responding ('workflow' or 'step')
*/
export declare function handleHealthCheckMessage(healthCheck: HealthCheckPayload, endpoint: 'workflow' | 'step', worldSpecVersion?: number): Promise<void>;
export type HealthCheckEndpoint = 'workflow' | 'step';
export interface HealthCheckOptions {
/** Timeout in milliseconds to wait for health check response. Default: 30000 (30s) */
timeout?: number;
/** Deployment ID to send the health check to. Falls back to process.env.VERCEL_DEPLOYMENT_ID. */
deploymentId?: string;
}
export declare function healthCheck(world: World, endpoint: HealthCheckEndpoint, options?: HealthCheckOptions & {
namespace?: string;
}): Promise<HealthCheckResult>;
/**
* Loads workflow run events by iterating through all pages of paginated
* results. Events are returned in chronological (ascending) order for
* deterministic workflow replay.
*
* @param runId - The workflow run ID.
* @param afterCursor - If provided, only events after this cursor are
* returned (incremental load). If omitted, all events are returned.
* The returned cursor can be passed back in on a subsequent call for
* incremental loading.
*/
export declare function loadWorkflowRunEvents(runId: string, afterCursor?: string): Promise<{
events: Event[];
cursor: string | null;
}>;
/**
* Wraps a request/response handler and adds a health check "mode"
* based on the presence of a `__health` query parameter.
*/
export declare function withHealthCheck(handler: (req: Request) => Promise<Response>, worldSpecVersion?: number): (req: Request) => Promise<Response>;
/**
* Queues a message to the specified queue with tracing.
*/
export declare function queueMessage(world: World, ...args: Parameters<typeof world.queue>): Promise<void>;
/**
* Calculates the queue overhead time in milliseconds for a given message.
*/
export declare function getQueueOverhead(message: {
requestedAt?: Date;
}): {
[k: string]: number;
} | undefined;
/**
* Returns a memoized accessor for the per-run AES-256 encryption key.
*
* The first call resolves the key via `world.getEncryptionKeyForRun` (which
* may do HKDF derivation locally on Vercel, or a network fetch from
* external contexts) and imports it as a `CryptoKey`; subsequent calls
* await the same cached promise. If the world doesn't support encryption
* or the run has no key configured, the cached value is `undefined`.
*
* Used by step / workflow handlers to defer the (potentially expensive)
* key fetch until the first code path that actually needs it — typically
* input hydration on the success path, or error dehydration on a failure
* path. Both paths can race-call the accessor without triggering duplicate
* fetches.
*
* Errors thrown by `getEncryptionKeyForRun` propagate to every caller
* (the cached promise rejects). This is intentional: when encryption is
* configured, we never want to silently fall back to plaintext
* serialization. A propagated error in an event-emission path leaves the
* outer try/catch to log and surface the issue; the queue's redelivery
* semantics will retry the key fetch on the next attempt.
*/
export declare function memoizeEncryptionKey(world: World, runOrId: WorkflowRun | string): () => Promise<CryptoKey | undefined>;
//# sourceMappingURL=helpers.d.ts.map