eve/dist/src/compiled/@workflow/core/runtime/start.d.ts

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

import type { RunRetention, World } from '#compiled/@workflow/world/index.js';
import { Run } from './run.js';
/**
 * Reset the `deploymentId: 'latest'` no-op warn-once guard. Test-only,
 * exported so unit tests can exercise the warn path across `start()` calls.
 *
 * @internal
 */
export declare function _resetLatestNoOpWarnForTests(): void;
export interface StartOptionsBase {
    /**
     * The world to use for the workflow run creation,
     * by default the world is inferred from the environment variables.
     */
    world?: World;
    /**
     * The spec version to use for the workflow run. Defaults to the latest version.
     */
    specVersion?: number;
    /**
     * Optional region identifier for the new run. Currently consumed only
     * by `@workflow/world-vercel`, which embeds the region into the tagged
     * run ID and routes the initial workflow message to the matching
     * regional queue. When omitted, the world falls back to its own
     * default (for `world-vercel`: the `VERCEL_REGION` environment
     * variable, then the server-side default region `iad1`; a concrete,
     * routable region is always chosen).
     *
     * Worlds without a regional dimension ignore this field.
     */
    region?: string;
    /**
     * Plaintext attributes to seed on the run as it is created.
     *
     * Available for native-attributes runs (spec version 4 and later).
     */
    attributes?: Record<string, string>;
    /**
     * Permit reserved `$`-prefixed keys in `attributes`. The `$` namespace
     * is reserved for framework/library code built on top of the workflow
     * SDK (telemetry, agent metadata, platform-emitted tags, etc.); user
     * code MUST NOT write keys in it, and validation rejects them so
     * accidental collisions with tooling-owned keys can't slip through.
     *
     * Only flip this to `true` if your caller is itself a framework or
     * library that owns a `$`-prefixed sub-namespace and knows the
     * conventions of any other tools writing into it. Same semantics as
     * the `setAttributes` option of the same name.
     */
    allowReservedAttributes?: boolean;
    /**
     * Set a preference for data retention after run completion.
     *
     * **Experimental.** Both the unit and the set of accepted values are expected
     * to change.
     *
     * Worlds control the retention of user data (event payloads and stream
     * chunks), the event log, and any analytics data. Options are:
     * - `'default'`: same as omission, the World will decide. On Vercel, this
     *   is based on your team's plan.
     * - `0`: data is deleted as soon as your run completes or fails. On
     *   Vercel, user data is deleted, but metadata may persist for your plan's
     *   default retention period.
     *
     * The value is a duration, with zero being the only valid option currently.
     *
     * **Known limitation at `0`.** The purge races your own read of the run's
     * result and generally wins, so `await run.returnValue` on a
     * `experimental_retention: 0` run usually throws `RunExpiredError` rather
     * than resolving. If you need the result, return it through a channel you
     * control, e.g. a step that writes it to external storage.
     *
     * Recorded on the run as the reserved `$retention` attribute, so it
     * requires a World implementing spec version 4 or later. `'default'` is
     * not written at all, keeping it exactly equivalent to omitting the
     * option. Retention is enforced by the World: the first-party Worlds
     * (Vercel, Local, Postgres) implement it, and a World that does not
     * recognize the value keeps the data.
     */
    experimental_retention?: RunRetention;
    /**
     * The ID of an existing run this run is being replayed from, if any.
     *
     * Recorded on the new run's `executionContext` as `replayedFromRunId` so
     * tooling (e.g. the dashboard runs list) can show that a run originated as
     * a replay and link back to its source. Set automatically by
     * {@link recreateRunFromExisting}; there's usually no reason to pass it
     * directly.
     *
     * Must be a run ID: `wrun_` followed by a 26-char ULID. It's a foreign key
     * to the source run, so `start()` validates the exact shape and rejects
     * anything else rather than persist a lineage link that points at garbage.
     */
    replayedFromRunId?: string;
    /**
     * Queue namespace of the target deployment. Scopes the workflow queue
     * topic to `__{namespace}_wkf_workflow_*` (e.g. `'eve'`) instead of the
     * default `__wkf_workflow_*`, and is also used for the cross-deployment
     * capability probe. Falls back to `WORKFLOW_QUEUE_NAMESPACE` in the
     * calling process.
     *
     * Within a deployment the env fallback is correct. Cross-context callers
     * (e.g. the observability dashboard replaying a run) must pass the
     * TARGET deployment's namespace explicitly: the env fallback resolves in
     * the caller's process, and a run enqueued to a topic the target has no
     * consumer for is never picked up.
     */
    namespace?: string;
}
export interface StartOptionsWithDeploymentId extends StartOptionsBase {
    /**
     * The deployment ID to use for the workflow run.
     *
     * By default, this is automatically inferred from environment variables
     * when deploying to Vercel.
     *
     * Set to `'latest'` to automatically resolve the most recent deployment
     * for the current environment (same production target or git branch).
     * This is only meaningful in worlds with atomic, immutable deployments
     * (currently Vercel). In other worlds (local dev, Postgres) there is no
     * notion of multiple deployments to resolve between, so `'latest'` has no
     * effect: a warning is logged and the run targets the current deployment.
     *
     * **Note:** When `deploymentId` is provided, the argument and return types become `unknown`
     * since there is no guarantee the types will be consistent across deployments.
     */
    deploymentId: 'latest' | (string & {});
}
export interface StartOptionsWithoutDeploymentId extends StartOptionsBase {
    deploymentId?: undefined;
}
/**
 * Options for starting a workflow run.
 */
export type StartOptions = StartOptionsWithDeploymentId | StartOptionsWithoutDeploymentId;
/**
 * Represents an imported workflow function.
 */
export type WorkflowFunction<TArgs extends unknown[], TResult> = (...args: TArgs) => Promise<TResult>;
/**
 * Represents the generated metadata of a workflow function.
 */
export type WorkflowMetadata = {
    workflowId: string;
};
/**
 * Starts a workflow run.
 *
 * @param workflow - The imported workflow function to start.
 * @param args - The arguments to pass to the workflow (optional).
 * @param options - The options for the workflow run (optional).
 * @returns The unique run ID for the newly started workflow invocation.
 */
export declare function start<TArgs extends unknown[], TResult>(workflow: WorkflowFunction<TArgs, TResult> | WorkflowMetadata, args: unknown[], options: StartOptionsWithDeploymentId): Promise<Run<unknown>>;
export declare function start<TResult>(workflow: WorkflowFunction<[], TResult> | WorkflowMetadata, options: StartOptionsWithDeploymentId): Promise<Run<unknown>>;
export declare function start<TArgs extends unknown[], TResult>(workflow: WorkflowFunction<TArgs, TResult> | WorkflowMetadata, args: TArgs, options?: StartOptionsWithoutDeploymentId): Promise<Run<TResult>>;
export declare function start<TResult>(workflow: WorkflowFunction<[], TResult> | WorkflowMetadata, options?: StartOptionsWithoutDeploymentId): Promise<Run<TResult>>;
//# sourceMappingURL=start.d.ts.map