eve/dist/src/compiled/@workflow/world/queue.d.ts

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

import { z } from '#compiled/zod/index.js';
export type QueueKind = 'workflow' | 'step';
/**
 * Pattern matching valid queue prefixes:
 * - `__wkf_workflow_` / `__wkf_step_` (default, no namespace)
 * - `__{namespace}_wkf_workflow_` / `__{namespace}_wkf_step_` (namespaced)
 *
 * Namespace must be lowercase alphanumeric starting with a letter.
 */
export declare const QueuePrefix: z.ZodString;
export type QueuePrefix = z.infer<typeof QueuePrefix>;
export declare const ValidQueueName: z.ZodString;
export type ValidQueueName = z.infer<typeof ValidQueueName>;
/**
 * Resolves the active queue namespace from an explicit argument or the
 * `WORKFLOW_QUEUE_NAMESPACE` env var.
 */
export declare function resolveQueueNamespace(namespace?: string): string | undefined;
/**
 * Builds a queue topic prefix for the given kind and optional namespace.
 *
 * - `getQueueTopicPrefix('workflow')` → `'__wkf_workflow_'`
 * - `getQueueTopicPrefix('workflow', 'custom')` → `'__custom_wkf_workflow_'`
 */
export declare function getQueueTopicPrefix(kind: QueueKind, namespace?: string): QueuePrefix;
export declare function getQueuePrefixKind(prefix: QueuePrefix): QueueKind;
export declare function parseQueueName(name: ValidQueueName): {
    prefix: QueuePrefix;
    kind: QueueKind;
    id: string;
};
export declare const MessageId: z.core.$ZodBranded<z.ZodString, "MessageId", "out">;
export type MessageId = z.infer<typeof MessageId>;
/**
 * OpenTelemetry trace context for distributed tracing
 */
export declare const TraceCarrierSchema: z.ZodRecord<z.ZodString, z.ZodString>;
export type TraceCarrier = z.infer<typeof TraceCarrierSchema>;
/**
 * Run creation data carried through the queue for resilient start.
 * Only present on the first queue delivery — re-enqueues omit this.
 * When the runtime processes the message, it passes this data to the
 * run_started event so the server can create the run if it doesn't exist yet.
 */
export declare const RunInputSchema: z.ZodObject<{
    input: z.ZodUnknown;
    deploymentId: z.ZodString;
    workflowName: z.ZodString;
    specVersion: z.ZodNumber;
    executionContext: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
    attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
    allowReservedAttributes: z.ZodOptional<z.ZodLiteral<true>>;
}, z.core.$strip>;
export type RunInput = z.infer<typeof RunInputSchema>;
export declare const WorkflowInvokePayloadSchema: z.ZodObject<{
    runId: z.ZodString;
    traceCarrier: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
    requestedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
    replayDivergence: z.ZodOptional<z.ZodObject<{
        eventId: z.ZodString;
        count: z.ZodNumber;
    }, z.core.$strip>>;
    serverErrorRetryCount: z.ZodOptional<z.ZodNumber>;
    stepId: z.ZodOptional<z.ZodString>;
    stepName: z.ZodOptional<z.ZodString>;
    runInput: z.ZodOptional<z.ZodObject<{
        input: z.ZodUnknown;
        deploymentId: z.ZodString;
        workflowName: z.ZodString;
        specVersion: z.ZodNumber;
        executionContext: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
        attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
        allowReservedAttributes: z.ZodOptional<z.ZodLiteral<true>>;
    }, z.core.$strip>>;
}, z.core.$strip>;
export declare const StepInvokePayloadSchema: z.ZodObject<{
    workflowName: z.ZodString;
    workflowRunId: z.ZodString;
    workflowStartedAt: z.ZodNumber;
    stepId: z.ZodString;
    traceCarrier: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
    requestedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
}, z.core.$strip>;
export type WorkflowInvokePayload = z.infer<typeof WorkflowInvokePayloadSchema>;
export type StepInvokePayload = z.infer<typeof StepInvokePayloadSchema>;
export type HealthCheckPayload = z.infer<typeof HealthCheckPayloadSchema>;
/**
 * Health check payload - used to verify that the queue pipeline
 * can deliver messages to workflow/step endpoints.
 */
export declare const HealthCheckPayloadSchema: z.ZodObject<{
    __healthCheck: z.ZodLiteral<true>;
    correlationId: z.ZodString;
}, z.core.$strip>;
export declare const QueuePayloadSchema: z.ZodUnion<readonly [z.ZodObject<{
    runId: z.ZodString;
    traceCarrier: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
    requestedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
    replayDivergence: z.ZodOptional<z.ZodObject<{
        eventId: z.ZodString;
        count: z.ZodNumber;
    }, z.core.$strip>>;
    serverErrorRetryCount: z.ZodOptional<z.ZodNumber>;
    stepId: z.ZodOptional<z.ZodString>;
    stepName: z.ZodOptional<z.ZodString>;
    runInput: z.ZodOptional<z.ZodObject<{
        input: z.ZodUnknown;
        deploymentId: z.ZodString;
        workflowName: z.ZodString;
        specVersion: z.ZodNumber;
        executionContext: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
        attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
        allowReservedAttributes: z.ZodOptional<z.ZodLiteral<true>>;
    }, z.core.$strip>>;
}, z.core.$strip>, z.ZodObject<{
    workflowName: z.ZodString;
    workflowRunId: z.ZodString;
    workflowStartedAt: z.ZodNumber;
    stepId: z.ZodString;
    traceCarrier: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
    requestedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
}, z.core.$strip>, z.ZodObject<{
    __healthCheck: z.ZodLiteral<true>;
    correlationId: z.ZodString;
}, z.core.$strip>]>;
export type QueuePayload = z.infer<typeof QueuePayloadSchema>;
export interface QueueOptions {
    deploymentId?: string;
    idempotencyKey?: string;
    headers?: Record<string, string>;
    /** Delay message delivery by this many seconds */
    delaySeconds?: number;
    /** Spec version of the target run. Used to select the queue transport format. */
    specVersion?: number;
    /**
     * World-specific routing hint identifying the region the message should
     * be sent to (e.g. a Vercel compute region code such as `'iad1'`).
     *
     * Worlds that don't have a regional dimension ignore this field. For
     * `@workflow/world-vercel`, this overrides the region the underlying
     * `@vercel/queue` client uses to route the message; when omitted, the
     * region is resolved from the payload's tagged run ID, then from the
     * `VERCEL_REGION` environment variable, and finally defaults to `'iad1'`
     * (the pre-regional-routing behaviour).
     */
    region?: string;
}
export interface Queue {
    getDeploymentId(): Promise<string>;
    /**
     * Enqueues a message to the specified queue.
     *
     * @param queueName - The name of the queue to which the message will be sent.
     * @param message - The content of the message to be sent to the queue.
     * @param opts - Optional parameters for the queue operation.
     */
    queue(queueName: ValidQueueName, message: QueuePayload, opts?: QueueOptions): Promise<{
        messageId: MessageId | null;
    }>;
    /**
     * Creates an HTTP queue handler for processing messages from a specific queue.
     *
     * `meta.messageId` SHOULD be stable across redeliveries of the same message
     * (one ID per enqueued message, reused on every delivery attempt). The
     * runtime's inline step ownership uses it as a liveness lease: the lazy
     * `step_started` records the handling invocation's messageId, and only a
     * delivery of that same message may re-execute the step before the
     * ownership lease expires (crash recovery via queue redelivery). A World
     * whose queue mints a fresh ID per delivery degrades gracefully — owner
     * redeliveries fall back to the delayed-backstop path instead of executing
     * immediately, adding recovery latency but never wedging or duplicating.
     */
    createQueueHandler(queueNamePrefix: QueuePrefix, handler: (message: unknown, meta: {
        attempt: number;
        queueName: ValidQueueName;
        messageId: MessageId;
        requestId?: string;
    }) => Promise<void | {
        timeoutSeconds: number;
    }>): (req: Request) => Promise<Response>;
}
//# sourceMappingURL=queue.d.ts.map