eve
Version:
Filesystem-first framework for durable backend AI agents that run anywhere.
264 lines • 13.7 kB
TypeScript
import type { AttributeChange, ExperimentalSetAttributesResult } from './attributes.js';
import type { CreateEventParams, CreateEventRequest, Event, EventResult, GetEventParams, ListEventsByCorrelationIdParams, ListEventsParams, RunCreatedEventRequest } from './events.js';
import type { GetHookParams, Hook, ListHooksParams } from './hooks.js';
import type { Queue } from './queue.js';
import type { GetWorkflowRunParams, ListWorkflowRunsParams, WorkflowRun, WorkflowRunWithoutData } from './runs.js';
import type { GetChunksOptions, PaginatedResponse, StreamChunksResponse, StreamInfoResponse } from './shared.js';
import type { GetStepParams, ListWorkflowRunStepsParams, Step, StepWithoutData } from './steps.js';
export interface Streamer {
/**
* Override the default flush interval (in milliseconds) for buffered stream writes.
* Chunks are accumulated in a buffer and flushed together on this interval.
*
* The default is 10ms, which is appropriate for HTTP-based backends where
* each flush is a network round-trip. For backends with sub-millisecond writes
* (e.g., Redis, local filesystem), a lower value (or 0 for immediate flushing) reduces
* end-to-end stream latency.
*
* Not supported by all worlds.
*/
streamFlushIntervalMs?: number;
streams: {
write(runId: string, name: string, chunk: string | Uint8Array): Promise<void>;
/**
* Write multiple chunks to a stream in a single operation.
* This is an optional optimization for world implementations that can
* batch multiple writes efficiently (e.g., single HTTP request for world-vercel).
*
* If not implemented, the caller should fall back to sequential write() calls.
*
* @param runId - The run ID
* @param name - The stream name
* @param chunks - Array of chunks to write, in order
*/
writeMulti?(runId: string, name: string, chunks: (string | Uint8Array)[]): Promise<void>;
close(runId: string, name: string): Promise<void>;
/**
* Read from a stream starting at the given chunk index.
* Positive values skip that many chunks from the start (0-based).
* Negative values start that many chunks before the current end
* (e.g. -3 on a 10-chunk stream starts at chunk 7). Clamped to 0.
*/
get(runId: string, name: string, startIndex?: number): Promise<ReadableStream<Uint8Array>>;
list(runId: string): Promise<string[]>;
/**
* Fetch stream chunks with cursor-based pagination.
*
* Unlike `get` (which returns a live `ReadableStream` that waits
* for new chunks in real-time), `getChunks` returns a snapshot of currently
* available chunks in a standard paginated response.
*
* @param runId - The workflow run ID that owns the stream
* @param name - The stream name/ID
* @param options - Pagination options (limit defaults to 100, max 1000)
* @returns Paginated chunks with a `done` flag indicating stream completion
*/
getChunks(runId: string, name: string, options?: GetChunksOptions): Promise<StreamChunksResponse>;
/**
* Retrieve lightweight metadata about a stream.
*
* Returns the tail index (index of the last known chunk, 0-based) and
* whether the stream is complete. This is useful for resolving a negative
* `startIndex` into an absolute position before connecting to a stream.
*
* @param runId - The workflow run ID that owns the stream
* @param name - The stream name/ID
*/
getInfo(runId: string, name: string): Promise<StreamInfoResponse>;
};
}
/**
* Storage interface for workflow data.
*
* Workflow storage models an append-only event log, so all state changes are handled through `events.create()`.
* Run/Step/Hook entities provide materialized views into the current state, but entities can't be modified directly.
*
* User-originated state changes are also handled via events:
* - run_cancelled event for run cancellation
* - hook_disposed event for explicit hook disposal (optional)
*
* Note: Hooks are automatically disposed by the World implementation when a workflow
* reaches a terminal state (run_completed, run_failed, run_cancelled). This releases
* hook tokens for reuse by future workflows. The hook_disposed event is only needed
* for explicit disposal before workflow completion.
*/
export interface Storage {
runs: {
get(id: string, params: GetWorkflowRunParams & {
resolveData: 'none';
}): Promise<WorkflowRunWithoutData>;
get(id: string, params?: GetWorkflowRunParams & {
resolveData?: 'all';
}): Promise<WorkflowRun>;
get(id: string, params?: GetWorkflowRunParams): Promise<WorkflowRun | WorkflowRunWithoutData>;
list(params: ListWorkflowRunsParams & {
resolveData: 'none';
}): Promise<PaginatedResponse<WorkflowRunWithoutData>>;
list(params?: ListWorkflowRunsParams & {
resolveData?: 'all';
}): Promise<PaginatedResponse<WorkflowRun>>;
list(params?: ListWorkflowRunsParams): Promise<PaginatedResponse<WorkflowRun | WorkflowRunWithoutData>>;
/**
* Apply a batch of attribute changes to a run. Merge semantics:
* - `value: string` upserts the key
* - `value: null` removes the key
* - keys not listed in `changes` are untouched
*
* Returns the post-merge attribute snapshot on the run.
*
* Pass `options.allowReservedAttributes: true` to permit keys
* starting with the reserved `$` prefix. Default behavior rejects
* those keys so user code can't accidentally collide with
* framework / tooling namespaces; framework callers that own a
* sub-namespace flip this on.
*
* OPTIONAL. World implementations may omit this method; the SDK
* helper (`setAttributes` in `@workflow/core`) feature-detects its
* absence and no-ops with a one-time warning so third-party /
* community worlds keep working without adopting the experimental
* API.
*
* EXPERIMENTAL: this method exists as a stopgap until the
* `attr_set` event type lands in a future spec version. When that
* happens, `setAttributes` will dispatch through `events.create`
* instead, and this method is expected to be removed. See the
* `attributes-mvp` changelog entry for the migration shape.
*/
experimentalSetAttributes?(runId: string, changes: AttributeChange[], options?: {
allowReservedAttributes?: boolean;
}): Promise<ExperimentalSetAttributesResult>;
};
steps: {
get(runId: string, stepId: string, params: GetStepParams & {
resolveData: 'none';
}): Promise<StepWithoutData>;
get(runId: string, stepId: string, params?: GetStepParams & {
resolveData?: 'all';
}): Promise<Step>;
get(runId: string, stepId: string, params?: GetStepParams): Promise<Step | StepWithoutData>;
list(params: ListWorkflowRunStepsParams & {
resolveData: 'none';
}): Promise<PaginatedResponse<StepWithoutData>>;
list(params: ListWorkflowRunStepsParams & {
resolveData?: 'all';
}): Promise<PaginatedResponse<Step>>;
list(params: ListWorkflowRunStepsParams): Promise<PaginatedResponse<Step | StepWithoutData>>;
};
events: {
/**
* Create a run_created event to start a new workflow run.
* The runId may be provided by the client or left as null for the server to generate.
*
* @param runId - Client-generated runId, or null for server-generated
* @param data - The run_created event data
* @param params - Optional parameters for event creation
* @returns Promise resolving to the created event and run entity
*/
create(runId: string | null, data: RunCreatedEventRequest, params?: CreateEventParams): Promise<EventResult>;
/**
* Create an event for an existing workflow run and atomically update the entity.
* Returns both the event and the affected entity (run/step/hook).
*
* @param runId - The workflow run ID (required for all events except run_created)
* @param data - The event to create
* @param params - Optional parameters for event creation
* @returns Promise resolving to the created event and affected entity
*/
create(runId: string, data: CreateEventRequest, params?: CreateEventParams): Promise<EventResult>;
get(runId: string, eventId: string, params?: GetEventParams): Promise<Event>;
list(params: ListEventsParams): Promise<PaginatedResponse<Event>>;
listByCorrelationId(params: ListEventsByCorrelationIdParams): Promise<PaginatedResponse<Event>>;
};
hooks: {
get(hookId: string, params?: GetHookParams): Promise<Hook>;
getByToken(token: string, params?: GetHookParams): Promise<Hook>;
list(params: ListHooksParams): Promise<PaginatedResponse<Hook>>;
};
}
/**
* The "World" interface represents how Workflows are able to communicate with the outside world.
*/
export interface World extends Queue, Streamer, Storage {
/**
* The highest spec version this World supports.
*
* When set, `start()` creates runs at this version so world-specific
* features (e.g., CBOR queue transport) are enabled automatically.
* When omitted, runs default to `SPEC_VERSION_SUPPORTS_EVENT_SOURCING` (2),
* the safe baseline that all worlds — including community worlds on
* older @workflow/world versions — are expected to handle.
*/
specVersion?: number;
/**
* Whether calling `process.exit(1)` from a queue handler is observed by
* the World as a delivery failure that will be retried.
*
* Set to `true` for worlds running inside a managed serverless platform
* (e.g. `world-vercel`) where the platform fails the invocation when the
* function process exits non-zero, and the queue redelivers the message
* via a separate fresh invocation.
*
* Set to `false` (the default) for in-process worlds (e.g. `world-local`,
* dev servers) where calling `process.exit()` would terminate the host
* process — including the user's `pnpm dev` — without producing a
* redelivery. Such worlds should instead surface failures via the event
* log and return normally.
*
* The core runtime reads this when deciding how to handle an exhausted
* replay budget: when `true` it exits so the queue redelivers; when
* `false` it writes `run_failed` best-effort and returns. See
* `packages/core/src/runtime/replay-budget.ts`.
*/
processExitTriggersQueueRedelivery?: boolean;
/**
* A function that will be called to start any background tasks needed by the World implementation.
* For example, in the case of a queue backed World, this would start the queue processing.
*/
start?(): Promise<void>;
/**
* Release any resources held by the World implementation (connection pools, listeners, etc.).
* After calling `close()`, the World instance should not be used again.
*
* This is important for CLI commands and short-lived processes that need to exit cleanly
* without relying on `process.exit()`.
*/
close?(): Promise<void>;
/**
* Resolve the most recent deployment ID for the current deployment's environment.
*
* Used when `deploymentId: 'latest'` is passed to `start()`. The implementation
* determines the latest deployment that shares the same environment (e.g., same
* "production" target or same git branch for "preview" deployments) as the
* current deployment.
*
* Not all World implementations support this — it is only implemented by
* world-vercel where deployment routing is meaningful.
*/
resolveLatestDeploymentId?(): Promise<string>;
/**
* Retrieve the AES-256 encryption key for a specific workflow run.
*
* The returned key is a ready-to-use 32-byte AES-256 key. The World
* implementation handles all key retrieval and derivation internally
* (e.g., HKDF from a deployment key). The core encryption module uses
* this key directly for AES-GCM encrypt/decrypt operations.
*
* Two overloads:
*
* - `getEncryptionKeyForRun(run)` — Preferred. Pass a `WorkflowRun` when
* the run entity already exists. The World reads any context it needs
* (e.g., `deploymentId`) directly from the run.
*
* - `getEncryptionKeyForRun(runId, context?)` — Used when the run entity
* is not locally available, such as `start()` before run creation or a
* forwarded writable stream carrying its owning deployment context. The
* `context` parameter carries opaque world-specific data (e.g.,
* `{ deploymentId }` for world-vercel) needed to resolve the correct key.
* When `context` is omitted, the World assumes the current deployment.
*
* When not implemented, encryption is disabled — data is stored unencrypted.
*/
getEncryptionKeyForRun?(run: WorkflowRun): Promise<Uint8Array | undefined>;
getEncryptionKeyForRun?(runId: string, context?: Record<string, unknown>): Promise<Uint8Array | undefined>;
}
//# sourceMappingURL=interfaces.d.ts.map