eve 0.5.4 → 0.6.0-beta.3

package/dist/src/compiled/@workflow/core/private.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Utils used by the bundler when transforming code
+ */
+import type { CryptoKey } from './encryption.js';
+import type { EventsConsumer } from './events-consumer.js';
+import type { QueueItem } from './global.js';
+import type { Serializable } from './schemas.js';
+export type StepFunction<Args extends Serializable[] = any[], Result extends Serializable | unknown = unknown> = ((...args: Args) => Promise<Result>) & {
+    maxRetries?: number;
+    stepId?: string;
+};
+/**
+ * Register a step function to be served in the server bundle.
+ * Also sets the stepId property on the function for serialization support.
+ *
+ * Note: The SWC compiler plugin no longer generates calls to this function.
+ * Step registration is now inlined as a self-contained IIFE that writes
+ * directly to the global Map at Symbol.for("@workflow/core//registeredSteps").
+ * This function is kept for internal/test use only.
+ */
+export declare function registerStepFunction(stepId: string, stepFn: StepFunction): void;
+/**
+ * Find a registered step function by name
+ */
+export declare function getStepFunction(stepId: string): StepFunction | undefined;
+export interface WorkflowOrchestratorContext {
+    runId: string;
+    encryptionKey: CryptoKey | undefined;
+    globalThis: typeof globalThis;
+    eventsConsumer: EventsConsumer;
+    /**
+     * Map of pending invocations keyed by correlationId.
+     * Using Map instead of Array for O(1) lookup/delete operations.
+     */
+    invocationsQueue: Map<string, QueueItem>;
+    onWorkflowError: (error: Error) => void;
+    generateUlid: () => string;
+    generateNanoid: () => string;
+    /**
+     * Sequential promise queue that ensures all event-driven promise resolutions
+     * (step results, hook payloads, failures, suspensions) happen in event log
+     * order. Every resolve, reject, or workflow error is chained through this
+     * queue so that even if individual operations take variable time (e.g.,
+     * async decryption), promises resolve deterministically.
+     */
+    promiseQueue: Promise<void>;
+    /**
+     * Counter of in-flight async data delivery operations (step result
+     * hydration, hook payload hydration). Suspensions must wait for this
+     * to reach 0 before firing, to avoid preempting data delivery.
+     */
+    pendingDeliveries: number;
+    /**
+     * Ordered registry of in-flight "branch-deciding" deliveries — the
+     * resolutions a workflow typically `Promise.race`s on: buffered hook
+     * payloads (`hook_received`) and wait completions (`wait_completed`).
+     * Keyed by the delivery's position (index) in the consumed event log.
+     *
+     * The problem: a buffered hook payload is observed via the async hook
+     * iterator (`yield await this`), costing extra microtask hops, while a
+     * `wait_completed` resolves with fewer hops — and a reused sleep can
+     * resolve in an entirely earlier loop iteration. Either way, the
+     * resolution that the committed event log ordered first can lose a
+     * `Promise.race` to a faster- or already-resolved competitor, diverging
+     * from the log and surfacing as `CorruptedEventLogError`.
+     *
+     * The fix is a strict, deterministic delivery order anchored on
+     * event-log position: a delivery does not resolve to the workflow until
+     * every earlier-in-log delivery of the OPPOSITE kind has been delivered.
+     * (Opposite kind only: sequential same-kind hook payloads must not block
+     * one another, and a wait need not wait behind a later wait.) Because the
+     * gate is "the earlier delivery resolved", not "won a timing race", the
+     * outcome is independent of microtask hops, hydration/decryption time,
+     * and `Promise.race` argument order.
+     *
+     * Index is used rather than the `eventId` string because `eventId` is an
+     * opaque, world-assigned value not guaranteed to sort in creation order
+     * (only the bundled ULID worlds happen to).
+     *
+     * Optional so older/out-of-tree contexts (and lightweight test harnesses)
+     * that do not initialize it degrade gracefully to the previous behavior.
+     */
+    pendingDeliveryBarriers?: Map<number, DeliveryBarrierEntry>;
+}
+/** The kind of branch-deciding delivery a barrier represents. */
+export type DeliveryKind = 'hook' | 'wait';
+interface DeliveryBarrierEntry {
+    kind: DeliveryKind;
+    /** Resolves once this delivery has resolved to the workflow. */
+    delivered: Promise<void>;
+}
+/**
+ * Awaits, in strict event-log order, every still-registered delivery whose
+ * index is earlier than `eventIndex` AND whose kind is in `deferBehindKinds`,
+ * so that this resolution is handed to the workflow only after all relevant
+ * earlier-in-log deliveries have been. This is what keeps a `Promise.race`
+ * deterministic and aligned with the committed event log, independent of
+ * microtask-hop counts, hydration time, or race-argument order.
+ *
+ * `deferBehindKinds` is the opposite kind(s): a hook defers behind earlier
+ * WAITS (not earlier hooks — those are sequential same-entity payloads), a
+ * wait defers behind earlier HOOKS.
+ */
+export declare function awaitEarlierDeliveries(ctx: WorkflowOrchestratorContext, eventIndex: number | undefined, deferBehindKinds: readonly DeliveryKind[]): Promise<void>;
+/** Handle for a registered branch-deciding delivery barrier. */
+export interface DeliveryBarrier {
+    /**
+     * Mark this delivery as delivered to the workflow. Resolves its
+     * `delivered` promise so any later-in-log opposite-kind delivery gated on
+     * it (via {@link awaitEarlierDeliveries}) may proceed, and removes it from
+     * the registry. Idempotent.
+     */
+    markDelivered: () => void;
+}
+/**
+ * Register a branch-deciding delivery at its event-log index so that later
+ * opposite-kind deliveries can be ordered strictly after it. Returns an inert
+ * handle when `pendingDeliveryBarriers` is not initialized.
+ *
+ * To guarantee a later delivery gated on this one can never hang when this
+ * delivery is abandoned (the workflow took a different branch or is
+ * suspending and never observes it), the barrier auto-resolves at idle.
+ */
+export declare function registerDeliveryBarrier(ctx: WorkflowOrchestratorContext, eventIndex: number | undefined, kind: DeliveryKind): DeliveryBarrier;
+/**
+ * Schedule a callback to fire only after all pending data deliveries
+ * (step results, hook payloads) and async deserialization have completed.
+ * Uses a polling loop: setTimeout(0) → check pendingDeliveries →
+ * if > 0, wait for promiseQueue → repeat. This handles the multi-round
+ * delivery pattern where each hook payload delivery cycle appends new
+ * async work to the promiseQueue.
+ */
+export declare function scheduleWhenIdle(ctx: WorkflowOrchestratorContext, fn: () => void): void;
+export {};
+//# sourceMappingURL=private.d.ts.map

package/dist/src/compiled/@workflow/core/private.js

@@ -0,0 +1 @@
+import{a as e}from"../../_chunks/workflow/dist-D0jyrm7a.js";const t=Symbol.for(`@workflow/core//registeredSteps`),n=globalThis,r=n[t]??=new Map,i=new Set([`__builtin_response_array_buffer`,`__builtin_response_json`,`__builtin_response_text`]);function a(e){let t=e.split(`//`);if(t.length!==3||t[0]!==`step`)return[];let n=t[1],r=t[2],i=new Set,a=e=>{e!==n&&i.add(e)};if(n.startsWith(`./workflows/`)){let e=n.slice(2);a(`./example/${e}`),a(`./src/${e}`)}else if(n.startsWith(`./example/workflows/`)){let e=n.slice(10);a(`./${e}`),a(`./src/${e}`)}else if(n.startsWith(`./src/workflows/`)){let e=n.slice(6);a(`./${e}`),a(`./example/${e}`)}return Array.from(i,e=>`step//${e}//${r}`)}function o(e){if(i.has(e)){for(let[t,n]of r.entries())if(t.endsWith(`//${e}`))return n}}function s(e,t){r.set(e,t),t.stepId=e}function c(e){let t=r.get(e);if(t)return t;for(let t of a(e)){let e=r.get(t);if(e)return e}let n=o(e);if(n)return n}async function l(e,t,n){if(t===void 0||!e.pendingDeliveryBarriers||e.pendingDeliveryBarriers.size===0)return;let r=[];for(let[i,a]of e.pendingDeliveryBarriers)i<t&&n.includes(a.kind)&&r.push(a.delivered);r.length>0&&await Promise.all(r)}function u(t,n,r){let i=t.pendingDeliveryBarriers;if(!i||n===void 0)return{markDelivered:()=>{}};let a=!1,{promise:o,resolve:s}=e(),c={kind:r,delivered:o};i.set(n,c);let l=()=>{a||(a=!0,i.get(n)===c&&i.delete(n),s())};return d(t,l),{markDelivered:l}}function d(e,t){let n=()=>{e.pendingDeliveries>0?e.promiseQueue.then(()=>{setTimeout(n,0)}):t()};setTimeout(n,0)}export{l as awaitEarlierDeliveries,c as getStepFunction,u as registerDeliveryBarrier,s as registerStepFunction,d as scheduleWhenIdle};

package/dist/src/compiled/@workflow/core/runtime/constants.d.ts

@@ -0,0 +1,52 @@
+export declare const MAX_QUEUE_DELIVERIES = 48;
+/**
+ * Default maximum time allowed for the *replay* portion of a single workflow
+ * handler invocation (in ms). This budget only covers deterministic-replay
+ * and workflow-VM execution between step boundaries — inline step bodies
+ * (`"use step"` functions invoked via `executeStep`) do NOT count against
+ * it. Step bodies are bounded separately by the platform's function
+ * `maxDuration` (e.g. 800s on Vercel Pro Fluid) and `NO_INLINE_REPLAY_AFTER_MS`.
+ *
+ * If the non-step ("replay") time within a single invocation exceeds this
+ * budget, the handler exits so the queue can retry. After
+ * `REPLAY_TIMEOUT_MAX_RETRIES` exhausted attempts the run is failed with
+ * `RUN_ERROR_CODES.REPLAY_TIMEOUT`.
+ *
+ * Note that on Vercel Hobby (standard functions), the platform `maxDuration`
+ * is 60s — well below this budget, so the platform SIGTERM will fire first
+ * and the queue will re-deliver until the visibility window expires. With
+ * Fluid Compute on Hobby the per-function ceiling rises to 300s, still
+ * under the default budget.
+ *
+ * Override via the `WORKFLOW_REPLAY_TIMEOUT_MS` env var (clamped to
+ * `MIN_REPLAY_TIMEOUT_MS`..`MAX_REPLAY_TIMEOUT_MS`).
+ */
+export declare const REPLAY_TIMEOUT_MS = 240000;
+/** Lower bound for the replay-timeout env var override. */
+export declare const MIN_REPLAY_TIMEOUT_MS = 30000;
+/**
+ * Upper bound for the replay-timeout env var override. 780s leaves ≥20s of
+ * headroom under Vercel Pro Fluid's 800s function ceiling so the handler
+ * can write `run_failed` before SIGTERM.
+ */
+export declare const MAX_REPLAY_TIMEOUT_MS = 780000;
+/**
+ * Resolve the effective replay-timeout budget for the current process.
+ *
+ * Reads `process.env.WORKFLOW_REPLAY_TIMEOUT_MS` lazily so tests and
+ * deployments can override per invocation. Invalid / out-of-range values
+ * fall back to a safe value (no throw — the env var is an escape hatch,
+ * not a hard requirement) and emit a one-time warning so misconfiguration
+ * is observable.
+ */
+export declare function getReplayTimeoutMs(): number;
+/**
+ * Reset the warn-once cache. Test-only — exported so unit tests can
+ * exercise the warn path repeatedly without sharing state.
+ *
+ * @internal
+ */
+export declare function _resetReplayTimeoutWarnCacheForTests(): void;
+export declare const REPLAY_TIMEOUT_MAX_RETRIES = 3;
+export declare const REPLAY_DIVERGENCE_MAX_RETRIES = 3;
+//# sourceMappingURL=constants.d.ts.map

package/dist/src/compiled/@workflow/core/runtime/get-port-lazy.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Lazy loader for getPort that prevents bundlers (Turbopack, esbuild)
+ * from statically tracing @workflow/utils/get-port and its filesystem
+ * operations (readdir, readFile, readlink) into the flow route bundle.
+ *
+ * Uses createRequire with a dynamically constructed specifier so the
+ * dependency is invisible to bundler static analysis.
+ */
+export declare function getPortLazy(): Promise<number | undefined>;
+//# sourceMappingURL=get-port-lazy.d.ts.map

package/dist/src/compiled/@workflow/core/runtime/get-world-lazy.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Lazy accessor for the World singleton via globalThis symbols.
+ *
+ * This module exists to break the static import chain from step-side
+ * modules (serialization, run, helpers, start) to world.ts. Without it,
+ * esbuild bundles world.ts (and its transitive deps: world-local,
+ * world-vercel, process.cwd(), etc.) into the step registrations bundle,
+ * which triggers Turbopack NFT tracing errors in the V2 combined flow route.
+ *
+ * Resolution order, in priority:
+ *
+ * 1. `globalThis[WorldCacheKey]` — populated by a successful prior
+ *    `getWorld()` call. This is the steady-state hot path.
+ * 2. `globalThis[GetWorldFnKey]` — populated by the module-load side
+ *    effect at the bottom of `./world.ts`. Fires on every server bundle
+ *    that reaches this file via `workflow/api` (which imports
+ *    `./world-init.ts` for its side effect; see that file for the full
+ *    rationale). This is the cold-start path for routes that consume
+ *    `start` without any prior workflow run.
+ * 3. Dynamic `import('./world.js')` — last-resort fallback for
+ *    environments where neither (1) nor (2) is available (CJS test
+ *    runners, scripts that import deeply into `@workflow/core` without
+ *    going through `workflow/api`, future bundlers we haven't validated).
+ *    The specifier is built at runtime so esbuild can't trace it into
+ *    step bundles. Note: this branch is unreliable in webpack-bundled
+ *    routes because webpack inlines this module into the route file and
+ *    the relative path resolves against the bundle location — paths (1)
+ *    and (2) cover those cases instead.
+ */
+import type { World } from '#compiled/@workflow/world/index.js';
+export declare function getWorldLazy(): Promise<World>;
+//# sourceMappingURL=get-world-lazy.d.ts.map

package/dist/src/compiled/@workflow/core/runtime/helpers.d.ts

@@ -0,0 +1,105 @@
+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): 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): 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

package/dist/src/compiled/@workflow/core/runtime/replay-budget.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Per-invocation accounting of the *non-step* portion of a workflow
+ * handler run: deterministic event-log replay, workflow-VM execution
+ * between step boundaries, suspension handling, queue round-trips, etc.
+ * Inline step bodies (`"use step"` functions invoked via `executeStep`)
+ * are intentionally excluded — they are bounded by the platform's
+ * function `maxDuration` and the `NO_INLINE_REPLAY_AFTER_MS` early-return
+ * guard.
+ *
+ * Usage:
+ *
+ * ```ts
+ * const budget = new ReplayBudget();
+ * // …non-step work happens here, accumulates against the budget…
+ * budget.pause();
+ * try {
+ *   await executeStep(...); // not charged
+ * } finally {
+ *   budget.resume();
+ * }
+ * // back to charging
+ * if (budget.isExhausted()) { ... }
+ * ```
+ *
+ * Implementation notes:
+ *
+ * - `pause()` and `resume()` are idempotent: calling `pause()` while
+ *   already paused (or `resume()` while already resumed) is a no-op.
+ *   This protects against double-counting in future refactors that nest
+ *   step execution or take an early-return path between a `pause()` and
+ *   the matching `resume()`.
+ * - `isExhausted()` is checked at loop boundaries by the caller — the
+ *   budget itself does not arm any timers. This means an in-flight
+ *   pathological `runWorkflow` call (e.g. a huge event-log replay) can
+ *   overshoot the budget by up to one iteration's worth of work before
+ *   the next check fires. In practice the 20s headroom built into
+ *   `MAX_REPLAY_TIMEOUT_MS` (and the function `maxDuration` ceiling)
+ *   gives us slack; the old `setTimeout`-based approach also ultimately
+ *   relied on the platform SIGTERM as the hard backstop.
+ */
+export declare class ReplayBudget {
+    private readonly limitMs;
+    private elapsedMs;
+    private intervalStart;
+    constructor(limitMs?: number);
+    /**
+     * The configured replay-timeout limit, in ms. Useful for log messages.
+     */
+    get configuredLimitMs(): number;
+    /**
+     * Total non-step time accumulated so far, in ms. Includes the
+     * currently-active interval if the budget is not paused.
+     */
+    elapsed(): number;
+    /**
+     * Stop counting elapsed time toward the budget. Idempotent — safe to
+     * call multiple times in a row; subsequent calls are no-ops until
+     * `resume()` reopens an interval.
+     */
+    pause(): void;
+    /**
+     * Resume counting elapsed time toward the budget. Idempotent — safe to
+     * call multiple times in a row; subsequent calls re-anchor the
+     * interval start to `now()`, which is fine because no time accrues
+     * between back-to-back `resume()` calls.
+     */
+    resume(): void;
+    /**
+     * True if the budget has been exhausted (`elapsed() >= limitMs`).
+     * Callers should invoke `handleExhausted(...)` afterward and return
+     * from the handler.
+     */
+    isExhausted(): boolean;
+}
+/**
+ * Fail the run (or retry, on early attempts) when the replay budget is
+ * exhausted. The handling depends on whether the underlying World
+ * supports `process.exit(1)` as a queue redelivery signal (see
+ * `World.processExitTriggersQueueRedelivery`):
+ *
+ * - **Managed-platform Worlds** (`world-vercel`): on attempts <=
+ *   `REPLAY_TIMEOUT_MAX_RETRIES` exit the process so the platform fails
+ *   the invocation and the queue redelivers; on the next attempt write
+ *   `run_failed` with `RUN_ERROR_CODES.REPLAY_TIMEOUT` and exit.
+ *
+ * - **In-process Worlds** (`world-local`, dev servers): calling
+ *   `process.exit()` would terminate the host (e.g. `pnpm dev`), so
+ *   instead log a warning, write `run_failed` best-effort, and return.
+ *   The framework completes the request normally.
+ */
+export declare function handleReplayBudgetExhausted(args: {
+    runId: string;
+    workflowName: string;
+    requestId: string | undefined;
+    attempt: number;
+    limitMs: number;
+}): Promise<void>;
+//# sourceMappingURL=replay-budget.d.ts.map

package/dist/src/compiled/@workflow/core/runtime/resume-hook.d.ts

@@ -0,0 +1,77 @@
+import { type Hook } from '#compiled/@workflow/world/index.js';
+import { type CryptoKey } from '../encryption.js';
+/**
+ * Get the hook by token to find the associated workflow run,
+ * and hydrate the `metadata` property if it was set from within
+ * the workflow run.
+ *
+ * @param token - The unique token identifying the hook
+ */
+export declare function getHookByToken(token: string): Promise<Hook>;
+/**
+ * Resumes a workflow run by sending a payload to a hook identified by its token.
+ *
+ * This function is called externally (e.g., from an API route or server action)
+ * to send data to a hook and resume the associated workflow run.
+ *
+ * @param tokenOrHook - The unique token identifying the hook, or the hook object itself
+ * @param payload - The data payload to send to the hook
+ * @returns Promise resolving to the hook
+ * @throws Error if the hook is not found or if there's an error during the process
+ *
+ * @example
+ *
+ * ```ts
+ * // In an API route
+ * import { resumeHook } from '@workflow/core/runtime';
+ *
+ * export async function POST(request: Request) {
+ *   const { token, data } = await request.json();
+ *
+ *   try {
+ *     const hook = await resumeHook(token, data);
+ *     return Response.json({ runId: hook.runId });
+ *   } catch (error) {
+ *     return new Response('Hook not found', { status: 404 });
+ *   }
+ * }
+ * ```
+ */
+export declare function resumeHook<T = any>(tokenOrHook: string | Hook, payload: T, encryptionKeyOverride?: CryptoKey): Promise<Hook>;
+/**
+ * Resumes a webhook by sending a {@link https://developer.mozilla.org/en-US/docs/Web/API/Request | Request}
+ * object to a hook identified by its token.
+ *
+ * This function is called externally (e.g., from an API route or server action)
+ * to send a request to a webhook and resume the associated workflow run.
+ *
+ * @param token - The unique token identifying the hook
+ * @param request - The request to send to the hook
+ * @returns Promise resolving to the response
+ * @throws Error if the hook is not found or if there's an error during the process
+ *
+ * @example
+ *
+ * ```ts
+ * // In an API route
+ * import { resumeWebhook } from '@workflow/core/runtime';
+ *
+ * export async function POST(request: Request) {
+ *   const url = new URL(request.url);
+ *   const token = url.searchParams.get('token');
+ *
+ *   if (!token) {
+ *     return new Response('Missing token', { status: 400 });
+ *   }
+ *
+ *   try {
+ *     const response = await resumeWebhook(token, request);
+ *     return response;
+ *   } catch (error) {
+ *     return new Response('Webhook not found', { status: 404 });
+ *   }
+ * }
+ * ```
+ */
+export declare function resumeWebhook(token: string, request: Request): Promise<Response>;
+//# sourceMappingURL=resume-hook.d.ts.map

package/dist/src/compiled/@workflow/core/runtime/run.d.ts

@@ -0,0 +1,134 @@
+import { WORKFLOW_DESERIALIZE, WORKFLOW_SERIALIZE } from '../_workflow-serde.js';
+import { type WorkflowRunStatus } from '#compiled/@workflow/world/index.js';
+import { type StopSleepOptions, type StopSleepResult } from './runs.js';
+/**
+ * A `ReadableStream` extended with workflow-specific helpers.
+ */
+export type WorkflowReadableStream<R = any> = ReadableStream<R> & {
+    /**
+     * Returns the tail index (index of the last known chunk, 0-based) of the
+     * underlying workflow stream. Useful for resolving a negative `startIndex`
+     * into an absolute position — for example, when building reconnection
+     * endpoints that need to inform the client where the stream starts.
+     *
+     * Returns `-1` when no chunks have been written yet.
+     */
+    getTailIndex(): Promise<number>;
+};
+/**
+ * Options for configuring a workflow's readable stream.
+ */
+export interface WorkflowReadableStreamOptions {
+    /**
+     * An optional namespace to distinguish between multiple streams associated
+     * with the same workflow run.
+     */
+    namespace?: string;
+    /**
+     * The index number of the starting chunk to begin reading the stream from.
+     * Negative values start from the end (e.g. -3 reads the last 3 chunks).
+     */
+    startIndex?: number;
+    /**
+     * Any asynchronous operations that need to be performed before the execution
+     * environment is paused / terminated
+     * (i.e. using [`waitUntil()`](https://developer.mozilla.org/docs/Web/API/ExtendableEvent/waitUntil) or similar).
+     */
+    ops?: Promise<any>[];
+    /**
+     * The global object to use for hydrating types from the global scope.
+     *
+     * Defaults to {@link [`globalThis`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/globalThis)}.
+     */
+    global?: Record<string, any>;
+}
+/**
+ * A handler class for a workflow run.
+ */
+export declare class Run<TResult> {
+    #private;
+    static [WORKFLOW_SERIALIZE](instance: Run<unknown>): {
+        runId: string;
+        resilientStart: boolean;
+    };
+    static [WORKFLOW_DESERIALIZE](data: {
+        runId: string;
+        resilientStart?: boolean;
+    }): Run<unknown>;
+    /**
+     * The ID of the workflow run.
+     */
+    runId: string;
+    constructor(runId: string, opts?: {
+        resilientStart?: boolean;
+    });
+    /**
+     * Interrupts pending `sleep()` calls, resuming the workflow early.
+     *
+     * @param options - Optional settings to target specific sleep calls by correlation ID.
+     *   If not provided, all pending sleep calls will be interrupted.
+     * @returns A {@link StopSleepResult} object containing the number of sleep calls that were interrupted.
+     */
+    wakeUp(options?: StopSleepOptions): Promise<StopSleepResult>;
+    /**
+     * Cancels the workflow run.
+     */
+    cancel(): Promise<void>;
+    /**
+     * Whether the workflow run exists.
+     */
+    get exists(): Promise<boolean>;
+    /**
+     * The status of the workflow run.
+     */
+    get status(): Promise<WorkflowRunStatus>;
+    /**
+     * The return value of the workflow run.
+     * Polls the workflow return value until it is completed.
+     */
+    get returnValue(): Promise<TResult>;
+    /**
+     * The name of the workflow.
+     */
+    get workflowName(): Promise<string>;
+    /**
+     * The timestamp when the workflow run was created.
+     */
+    get createdAt(): Promise<Date>;
+    /**
+     * The timestamp when the workflow run started execution.
+     * Returns undefined if the workflow has not started yet.
+     */
+    get startedAt(): Promise<Date | undefined>;
+    /**
+     * The timestamp when the workflow run completed.
+     * Returns undefined if the workflow has not completed yet.
+     */
+    get completedAt(): Promise<Date | undefined>;
+    /**
+     * The readable stream of the workflow run.
+     */
+    get readable(): WorkflowReadableStream;
+    /**
+     * Retrieves the workflow run's default readable stream, which reads chunks
+     * written to the corresponding writable stream {@link getWritable}.
+     *
+     * The returned stream has an additional {@link WorkflowReadableStream.getTailIndex | getTailIndex()}
+     * helper that returns the index of the last known chunk. This is useful when
+     * building reconnection endpoints that need to inform clients where the
+     * stream starts.
+     *
+     * @param options - The options for the readable stream.
+     * @returns A `WorkflowReadableStream` for the workflow run.
+     */
+    getReadable<R = any>(options?: WorkflowReadableStreamOptions): WorkflowReadableStream<R>;
+}
+/**
+ * Retrieves a `Run` object for a given run ID.
+ *
+ * @param runId - The workflow run ID obtained from {@link start}.
+ * @returns A `Run` object.
+ * @throws WorkflowRunNotFoundError if the run ID is not found.
+ */
+export declare function getRun<TResult>(runId: string): Run<TResult>;
+//# sourceMappingURL=run.d.ts.map