@ezghcloud/workflows 0.0.0-stage → 1.0.0

package/dist/protocol/validate.js

@@ -0,0 +1,279 @@
+// What the engine accepts from an SDK (workflows-stack internal/protocol validate.go and
+// protocol/schemas), checked on this side: the SDK's tests run every message it sends through
+// these, against workflows-stack's vectors (protocol/vectors/messages.json). Internal.
+import { utf8Length } from "./bytes.js";
+import { parseCallbackToken } from "./callback.js";
+const MAX_RETRY_ATTEMPTS = 100;
+const MAX_RETRY_MS = 86_400_000;
+const MAX_MULTIPLIER = 10;
+const MAX_STEP_NAME_BYTES = 256;
+const MAX_STACK_BYTES = 8192;
+const MAX_ERROR_TEXT_BYTES = 8192;
+const MAX_ERROR_DATA_BYTES = 64 << 10;
+export const MAX_ERROR_DEPTH = 8;
+const MAX_VALUE_BYTES = 64 << 10;
+const MAX_DEPLOYMENT_BYTES = 256;
+export const MAX_PLANNED_STEPS = 1000;
+const MAX_POLL_TASKS = 10;
+const MAX_WORKFLOWS = 1000;
+const MAX_SDK_NAME_BYTES = 200;
+const MAX_SDK_VERSION_BYTES = 100;
+const ERROR_CODE = /^(user|workflows\.[a-z_]+)$/;
+const STEP_ID = /^[A-Za-z0-9._:-]{1,128}$/;
+const PAYLOAD_ID = /^pay_[a-z2-7]{26}$/;
+const INVOCATION_ID = /^inv_[a-z2-7]{26}$/;
+const WORKFLOW = /^[A-Za-z0-9_-]{1,64}$/;
+export const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const QUEUE = /^[a-z0-9][a-z0-9-]{0,62}$/;
+const WORKER_ID = /^[A-Za-z0-9._:-]{1,128}$/;
+const RFC3339 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
+const COMMAND_TYPES = new Set([
+    "stepStarted", "stepCompleted", "stepFailed", "valueRecorded", "sleep", "runCompleted", "runFailed",
+    "workflowNotFound", "callbackCreated", "waitForCallback", "invoke", "planParallel", "messageWaitCreated", "waitForMessage",
+]);
+// Message waits (protocol 1.2): the queue's ID, the key, and the timeout (1 s to 30 days).
+export const MESSAGE_KEY = /^[A-Za-z0-9_.:-]{1,256}$/;
+export const MIN_MESSAGE_TIMEOUT_MS = 1000;
+export const MAX_MESSAGE_TIMEOUT_MS = 2_592_000_000;
+export class InvalidMessage extends Error {
+    name = "InvalidMessage";
+}
+const fail = (msg) => { throw new InvalidMessage(msg); };
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const isInt = (v) => typeof v === "number" && Number.isInteger(v);
+const str = (v) => (typeof v === "string" ? v : "");
+const jsonBytes = (v) => utf8Length(JSON.stringify(v));
+export function validateRetry(p) {
+    if (!isObj(p))
+        fail("retry isn't an object");
+    const r = p;
+    if (!isInt(r.maxAttempts) || r.maxAttempts < 1 || r.maxAttempts > MAX_RETRY_ATTEMPTS)
+        fail(`retry.maxAttempts ${String(r.maxAttempts)}`);
+    if (!isInt(r.initialMs) || r.initialMs < 0)
+        fail(`retry.initialMs ${String(r.initialMs)}`);
+    if (!isInt(r.maxMs) || r.maxMs < 0 || r.maxMs > MAX_RETRY_MS)
+        fail(`retry.maxMs ${String(r.maxMs)}`);
+    if (typeof r.multiplier !== "number" || Number.isNaN(r.multiplier) || r.multiplier < 1 || r.multiplier > MAX_MULTIPLIER)
+        fail(`retry.multiplier ${String(r.multiplier)}`);
+}
+export function validateError(e) {
+    let cur = e;
+    for (let depth = 0; cur !== undefined; depth++) {
+        if (depth >= MAX_ERROR_DEPTH)
+            fail(`error causes nest deeper than ${MAX_ERROR_DEPTH}`);
+        if (!isObj(cur))
+            fail("error isn't an object");
+        const w = cur;
+        if (!ERROR_CODE.test(str(w.code)))
+            fail(`error code ${JSON.stringify(w.code)} isn't user or workflows.*`);
+        if (typeof w.name !== "string" || typeof w.message !== "string")
+            fail("error needs name and message");
+        if (utf8Length(str(w.name)) > MAX_ERROR_TEXT_BYTES || utf8Length(str(w.message)) > MAX_ERROR_TEXT_BYTES)
+            fail("error name or message too long");
+        if (w.stack !== undefined && (typeof w.stack !== "string" || utf8Length(w.stack) > MAX_STACK_BYTES))
+            fail("error stack too long");
+        if (w.data !== undefined && jsonBytes(w.data) > MAX_ERROR_DATA_BYTES)
+            fail("error data too long");
+        cur = w.cause;
+    }
+}
+const validName = (n) => typeof n === "string" && n !== "" && utf8Length(n) <= MAX_STEP_NAME_BYTES && !n.includes("\u0000");
+export function validateCommand(cmd) {
+    if (!isObj(cmd))
+        fail("command isn't an object");
+    const c = cmd;
+    const type = str(c.type);
+    if (!COMMAND_TYPES.has(type))
+        fail(`unknown command type ${JSON.stringify(c.type)}`);
+    if (c.stepId !== undefined && !STEP_ID.test(str(c.stepId)))
+        fail(`stepId ${JSON.stringify(c.stepId)}`);
+    if (c.name !== undefined && (typeof c.name !== "string" || utf8Length(c.name) > MAX_STEP_NAME_BYTES || c.name.includes("\u0000")))
+        fail("name");
+    if (c.causeStepId !== undefined && !STEP_ID.test(str(c.causeStepId)))
+        fail("causeStepId");
+    if (c.value !== undefined && jsonBytes(c.value) > MAX_VALUE_BYTES)
+        fail("value too long");
+    if (c.attempt !== undefined && (!isInt(c.attempt) || c.attempt < 0))
+        fail("attempt");
+    if (c.retry !== undefined)
+        validateRetry(c.retry);
+    if (c.timeoutMs !== undefined && (!isInt(c.timeoutMs) || c.timeoutMs < 0))
+        fail("timeoutMs");
+    if (c.retryAfterMs !== undefined && (!isInt(c.retryAfterMs) || c.retryAfterMs < 0))
+        fail("retryAfterMs");
+    if (c.outputRef !== undefined && !PAYLOAD_ID.test(str(c.outputRef)))
+        fail("outputRef");
+    if (c.error !== undefined)
+        validateError(c.error);
+    if (c.workflow !== undefined && !WORKFLOW.test(str(c.workflow)))
+        fail(`workflow ${JSON.stringify(c.workflow)}`);
+    if (c.token !== undefined) {
+        if (type !== "callbackCreated")
+            fail(`token on ${type}`);
+        try {
+            parseCallbackToken(str(c.token));
+        }
+        catch {
+            fail("token isn't a callback token");
+        }
+    }
+    if (c.inputRef !== undefined && !PAYLOAD_ID.test(str(c.inputRef)))
+        fail("inputRef");
+    if (c.input !== undefined && c.inputRef !== undefined)
+        fail("input and inputRef are exclusive");
+    if ((c.input !== undefined || c.inputRef !== undefined) && type !== "invoke")
+        fail(`input on ${type}`);
+    if (c.steps !== undefined && type !== "planParallel")
+        fail(`steps on ${type}`);
+    if ((c.queueId !== undefined || c.key !== undefined) && type !== "messageWaitCreated")
+        fail(`queueId or key on ${type}`);
+    const step = () => { if (!STEP_ID.test(str(c.stepId)) || !validName(c.name))
+        fail(`${type} needs stepId and name`); };
+    switch (type) {
+        case "stepStarted":
+        case "stepFailed":
+            step();
+            if (!isInt(c.attempt) || c.attempt < 1)
+                fail(`${type} needs attempt ≥ 1`);
+            if (type === "stepStarted" && c.retry === undefined)
+                fail("stepStarted needs retry");
+            if (type === "stepFailed" && (c.error === undefined || typeof c.retryable !== "boolean"))
+                fail("stepFailed needs error and retryable");
+            break;
+        case "stepCompleted":
+            step();
+            if (!("output" in c) && c.outputRef === undefined)
+                fail("stepCompleted needs output");
+            break;
+        case "valueRecorded":
+            step();
+            if (!("value" in c))
+                fail("valueRecorded needs value");
+            break;
+        case "sleep":
+            step();
+            if (!RFC3339.test(str(c.until)) || Number.isNaN(Date.parse(str(c.until))))
+                fail("sleep needs until (RFC 3339)");
+            break;
+        case "runCompleted":
+            if (!("output" in c) && c.outputRef === undefined)
+                fail("runCompleted needs output");
+            break;
+        case "runFailed":
+            if (c.error === undefined)
+                fail("runFailed needs error");
+            break;
+        case "workflowNotFound":
+            if (c.workflow === undefined)
+                fail("workflowNotFound needs workflow");
+            break;
+        case "callbackCreated":
+            step();
+            if (c.token === undefined || !isInt(c.timeoutMs) || c.timeoutMs < 1)
+                fail("callbackCreated needs token and timeoutMs ≥ 1");
+            break;
+        case "waitForCallback":
+        case "waitForMessage":
+            if (!STEP_ID.test(str(c.stepId)))
+                fail(`${type} needs stepId`);
+            break;
+        case "messageWaitCreated":
+            step();
+            if (!UUID.test(str(c.queueId)))
+                fail("messageWaitCreated needs queueId (a UUID)");
+            if (!MESSAGE_KEY.test(str(c.key)))
+                fail("messageWaitCreated needs key (^[A-Za-z0-9_.:-]{1,256}$)");
+            if (!isInt(c.timeoutMs) || c.timeoutMs < MIN_MESSAGE_TIMEOUT_MS || c.timeoutMs > MAX_MESSAGE_TIMEOUT_MS)
+                fail("messageWaitCreated needs timeoutMs from 1,000 to 2,592,000,000");
+            break;
+        case "invoke":
+            step();
+            if (c.workflow === undefined)
+                fail("invoke needs workflow");
+            break;
+        case "planParallel": {
+            const steps = c.steps;
+            if (!Array.isArray(steps) || steps.length === 0 || steps.length > MAX_PLANNED_STEPS)
+                fail(`planParallel needs 1-${MAX_PLANNED_STEPS} steps`);
+            const seen = new Set();
+            for (const [i, s] of steps.entries()) {
+                if (!isObj(s) || !STEP_ID.test(str(s.stepId)) || !validName(s.name))
+                    fail(`steps[${i}]: stepId and name`);
+                const p = s;
+                if (seen.has(str(p.stepId)))
+                    fail(`steps[${i}]: stepId twice`);
+                seen.add(str(p.stepId));
+                if (p.retry !== undefined)
+                    validateRetry(p.retry);
+                if (p.timeoutMs !== undefined && (!isInt(p.timeoutMs) || p.timeoutMs < 0))
+                    fail(`steps[${i}]: timeoutMs`);
+            }
+        }
+    }
+}
+function validateSDK(s) {
+    if (!isObj(s))
+        fail("sdk is required");
+    const sdk = s;
+    if (str(sdk.name).trim() === "" || str(sdk.version).trim() === "")
+        fail("sdk name and version are required");
+    if (utf8Length(str(sdk.name)) > MAX_SDK_NAME_BYTES || utf8Length(str(sdk.version)) > MAX_SDK_VERSION_BYTES)
+        fail("sdk name or version too long");
+}
+function validateWorkflows(ws) {
+    if (ws === undefined)
+        return;
+    if (!Array.isArray(ws) || ws.length > MAX_WORKFLOWS)
+        fail(`at most ${MAX_WORKFLOWS} workflows`);
+    const seen = new Set();
+    for (const [i, w] of ws.entries()) {
+        if (!isObj(w) || !WORKFLOW.test(str(w.name)) || seen.has(str(w.name)))
+            fail(`workflows[${i}].name is invalid or repeated`);
+        const wf = w;
+        seen.add(str(wf.name));
+        if (wf.timeoutMs !== undefined && (!isInt(wf.timeoutMs) || wf.timeoutMs < 0))
+            fail(`workflow ${str(wf.name)}: timeoutMs`);
+        if (wf.retry !== undefined)
+            validateRetry(wf.retry);
+    }
+}
+export function validateCheckpoint(cp) {
+    if (!isObj(cp))
+        fail("checkpoint isn't an object");
+    const c = cp;
+    if (!INVOCATION_ID.test(str(c.invocationId)))
+        fail("invocationId");
+    if (!isInt(c.seq) || c.seq < 1)
+        fail("seq");
+    if (!Array.isArray(c.commands))
+        fail("commands");
+    c.commands.forEach(validateCommand);
+}
+export function validateInvocationResult(r) {
+    if (!isObj(r))
+        fail("result isn't an object");
+    const res = r;
+    if (!Array.isArray(res.commands))
+        fail("commands");
+    validateSDK(res.sdk);
+    if (res.deployment !== undefined && (typeof res.deployment !== "string" || utf8Length(res.deployment) > MAX_DEPLOYMENT_BYTES || res.deployment.includes("\u0000")))
+        fail("deployment");
+    res.commands.forEach(validateCommand);
+}
+export function validatePollRequest(r) {
+    if (!isObj(r))
+        fail("poll isn't an object");
+    const p = r;
+    if (!UUID.test(str(p.app)))
+        fail(`app ${JSON.stringify(p.app)}`);
+    if (!QUEUE.test(str(p.queue)))
+        fail(`queue ${JSON.stringify(p.queue)}`);
+    if (!isInt(p.maxTasks) || p.maxTasks < 1 || p.maxTasks > MAX_POLL_TASKS)
+        fail(`maxTasks ${String(p.maxTasks)}`);
+    if (!WORKER_ID.test(str(p.workerId)))
+        fail("workerId");
+    if (!Array.isArray(p.protocolVersions) || p.protocolVersions.length === 0 || !p.protocolVersions.every((v) => /^\d+\.\d+$/.test(str(v))))
+        fail("protocolVersions");
+    validateSDK(p.sdk);
+    validateWorkflows(p.workflows);
+}

package/dist/queues.d.ts

@@ -0,0 +1,47 @@
+import type { FetchLike } from "./runtime/live.ts";
+export interface QueueMessageInput {
+    body: string;
+    attributes?: Record<string, string>;
+    delaySeconds?: number;
+    groupId?: string;
+    dedupId?: string;
+}
+export interface SentMessage {
+    messageId: string;
+    seq?: string;
+    duplicate?: boolean;
+}
+export interface SentMessages {
+    messages: SentMessage[];
+}
+export declare class QueuesApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly retryAfterSeconds?: number | undefined;
+    name: string;
+    readonly data: {
+        status: number;
+        code: string;
+    };
+    constructor(status: number, code: string, message: string, retryAfterSeconds?: number | undefined);
+}
+export interface QueuesClientOptions {
+    apiKey: string;
+    organizationId: string;
+    projectId: string;
+    baseUrl?: string;
+    fetch?: FetchLike;
+    retries?: number;
+    maxRetryDelayMs?: number;
+    timeoutMs?: number;
+}
+export declare const DEFAULT_QUEUES_BASE = "https://queues-api.ezghcloud.com";
+export declare class QueuesClient {
+    #private;
+    constructor(opts: QueuesClientOptions);
+    send(queueId: string, messages: QueueMessageInput[], opts?: {
+        idempotencyKey?: string;
+    }): Promise<SentMessages>;
+}
+export declare function sendToQueueDigest(runId: string, stepId: string): Promise<string>;
+export declare function withDedupIds(messages: QueueMessageInput[], digest: string): QueueMessageInput[];

package/dist/queues.js

@@ -0,0 +1,126 @@
+import { toHex, utf8 } from "./protocol/bytes.js";
+// An error answer from the Queues API: the HTTP status and the platform error code
+// (status 0, code "network_error" when every attempt failed in transit).
+// data ({ status, code }) is what a step failure records, so a replay's WorkflowError keeps them.
+export class QueuesApiError extends Error {
+    status;
+    code;
+    retryAfterSeconds;
+    name = "QueuesApiError";
+    data;
+    constructor(status, code, message, retryAfterSeconds) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.data = { status, code };
+    }
+}
+export const DEFAULT_QUEUES_BASE = "https://queues-api.ezghcloud.com";
+const DEFAULT_TIMEOUT_MS = 30_000;
+const IDEMPOTENCY_KEY = /^[\x21-\x7e]{1,200}$/;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const id = encodeURIComponent;
+function apiError(res, data) {
+    const e = data?.error;
+    if (res.status >= 300 && res.status < 400)
+        return new QueuesApiError(res.status, "redirect", `The Queues API answered a redirect (${res.status}); requests are never redirected, so check baseUrl`);
+    const raw = res.headers.get("Retry-After");
+    const ra = raw === null ? NaN : Number(raw);
+    return new QueuesApiError(res.status, typeof e?.code === "string" ? e.code : "unknown", typeof e?.message === "string" ? e.message : `HTTP ${res.status}`, Number.isFinite(ra) && ra >= 0 ? ra : undefined);
+}
+// resendable: answers a resend with the same Idempotency-Key may fix.
+function resendable(err) {
+    if (err.status === 429)
+        return err.code !== "quota_exceeded";
+    if (err.status === 409)
+        return err.code === "idempotency_in_progress";
+    return err.status >= 500;
+}
+// QueuesClient sends messages to EZGH Queues for one project. Pass it to step.sendToQueue, or call
+// send directly outside a workflow.
+export class QueuesClient {
+    // ES private fields: the API key never shows in console.log, util.inspect or JSON.stringify.
+    #apiKey;
+    #base;
+    #fetch;
+    #retries;
+    #maxDelay;
+    #timeout;
+    constructor(opts) {
+        if (typeof opts?.apiKey !== "string" || opts.apiKey === "")
+            throw new TypeError("QueuesClient needs an apiKey");
+        if (typeof opts.organizationId !== "string" || opts.organizationId === "")
+            throw new TypeError("QueuesClient needs an organizationId");
+        if (typeof opts.projectId !== "string" || opts.projectId === "")
+            throw new TypeError("QueuesClient needs a projectId");
+        this.#apiKey = opts.apiKey;
+        this.#base = `${(opts.baseUrl ?? DEFAULT_QUEUES_BASE).replace(/\/+$/, "")}/v1/organizations/${id(opts.organizationId)}/projects/${id(opts.projectId)}`;
+        this.#fetch = opts.fetch ?? ((u, i) => fetch(u, i));
+        this.#retries = opts.retries ?? 3;
+        this.#maxDelay = opts.maxRetryDelayMs ?? 10_000;
+        this.#timeout = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        if (!Number.isInteger(this.#retries) || this.#retries < 0)
+            throw new TypeError("retries is a whole number ≥ 0");
+        if (!Number.isFinite(this.#maxDelay) || this.#maxDelay < 0)
+            throw new TypeError("maxRetryDelayMs is a number ≥ 0");
+        if (!Number.isFinite(this.#timeout) || this.#timeout <= 0)
+            throw new TypeError("timeoutMs is a number > 0");
+    }
+    // send sends 1–10 messages to a queue (queues.messages.send) in one request: all are stored, or
+    // none. Every attempt carries the same Idempotency-Key (yours, or a random one), which the API
+    // honors for 48 hours: a resend answers the first response instead of sending again.
+    async send(queueId, messages, opts = {}) {
+        if (typeof queueId !== "string" || queueId === "")
+            throw new TypeError("send needs a queueId");
+        if (!Array.isArray(messages) || messages.length < 1 || messages.length > 10)
+            throw new TypeError("send takes 1 to 10 messages");
+        const key = opts.idempotencyKey ?? crypto.randomUUID();
+        if (typeof key !== "string" || !IDEMPOTENCY_KEY.test(key))
+            throw new TypeError("An idempotencyKey is 1–200 printable ASCII characters");
+        const headers = { Authorization: `Bearer ${this.#apiKey}`, Accept: "application/json", "Content-Type": "application/json", "Idempotency-Key": key };
+        const body = JSON.stringify({ messages });
+        const url = `${this.#base}/queues/${id(queueId)}/messages`;
+        for (let attempt = 0;; attempt++) {
+            let res;
+            try {
+                res = await this.#fetch(url, { method: "POST", headers, body, redirect: "manual", signal: AbortSignal.timeout(this.#timeout) });
+            }
+            catch (e) {
+                if (attempt >= this.#retries)
+                    throw new QueuesApiError(0, "network_error", `Sending to the queue failed in transit: ${e instanceof Error ? e.message : String(e)}`);
+                await sleep(Math.min(this.#maxDelay, 500 * 2 ** attempt));
+                continue;
+            }
+            const text = await res.text();
+            let data;
+            try {
+                data = text ? JSON.parse(text) : undefined;
+            }
+            catch {
+                data = undefined;
+            }
+            if (res.ok) {
+                if (!Array.isArray(data?.messages))
+                    throw new QueuesApiError(res.status, "invalid_response", "The Queues API answered without a messages list");
+                return data;
+            }
+            const err = apiError(res, data);
+            if (!resendable(err) || attempt >= this.#retries)
+                throw err;
+            await sleep(Math.min(this.#maxDelay, err.retryAfterSeconds !== undefined ? err.retryAfterSeconds * 1000 : 500 * 2 ** attempt));
+        }
+    }
+}
+// sendToQueueDigest is step.sendToQueue's key material: lowercase hex of
+// SHA-256(runId + ":" + stepId). The step sends Idempotency-Key "wfq_" + digest, and gives each
+// FIFO message (one with a groupId) without a dedupId the dedupId digest + ":" + its index.
+export async function sendToQueueDigest(runId, stepId) {
+    return toHex(new Uint8Array(await crypto.subtle.digest("SHA-256", utf8(`${runId}:${stepId}`))));
+}
+// withDedupIds: the messages step.sendToQueue sends, a FIFO message (one with a groupId) given the
+// dedupId digest:index unless it has its own. Standard queues refuse dedupId, so messages without
+// a groupId are sent as they are.
+export function withDedupIds(messages, digest) {
+    return messages.map((m, i) => (m && typeof m === "object" && m.groupId !== undefined && m.dedupId === undefined ? { ...m, dedupId: `${digest}:${i}` } : m));
+}

package/dist/runtime/context.d.ts

@@ -0,0 +1,82 @@
+import type { RetryPolicy } from "../protocol/index.ts";
+import type { QueueMessageInput, QueuesClient, SentMessages } from "../queues.ts";
+import type { Workflow } from "./workflow.ts";
+export type Jsonify<T> = T extends Date ? string : T extends undefined ? null : T extends (infer U)[] ? Jsonify<U>[] : T extends object ? JsonifyObject<T> : T;
+type JsonifyObject<T> = Flatten<{
+    [K in keyof T as undefined extends T[K] ? K : never]?: Jsonify<Exclude<T[K], undefined>>;
+} & {
+    [K in keyof T as undefined extends T[K] ? never : K]: Jsonify<T[K]>;
+}>;
+type Flatten<T> = {
+    [K in keyof T]: T[K];
+};
+export interface StepRunOptions {
+    retry?: Partial<RetryPolicy>;
+    timeoutMs?: number;
+    id?: string;
+}
+export interface Callback<T = unknown> {
+    readonly url: string;
+    readonly token: string;
+    wait(): Promise<Jsonify<T>>;
+}
+export interface CreateCallbackOptions {
+    timeoutMs?: number;
+    id?: string;
+}
+export interface InvokeOptions<I = unknown, O = unknown> {
+    workflow: string | Workflow<I, O>;
+    input?: I;
+    id?: string;
+}
+export interface ReceivedMessage {
+    messageId: string;
+    body: string;
+    attributes: Record<string, string>;
+    sentAt: string;
+    queueId: string;
+    groupId?: string;
+    seq?: string;
+}
+export interface WaitForMessageOptions {
+    queueId: string;
+    key: string;
+    timeoutSeconds: number;
+    id?: string;
+}
+export interface StepRunContext {
+    signal: AbortSignal;
+    attempt: number;
+    idempotencyKey: string;
+}
+export interface Step {
+    run<T>(name: string, fn: (ctx: StepRunContext) => Promise<T> | T, opts?: StepRunOptions): Promise<Jsonify<T>>;
+    sleep(name: string, duration: string | number, opts?: {
+        id?: string;
+    }): Promise<void>;
+    sleepUntil(name: string, at: Date | string, opts?: {
+        id?: string;
+    }): Promise<void>;
+    now(name: string): Promise<Date>;
+    uuid(name: string): Promise<string>;
+    createCallback<T = unknown>(name: string, opts?: CreateCallbackOptions): Promise<Callback<T>>;
+    invoke<I = unknown, O = unknown>(name: string, opts: InvokeOptions<I, O>): Promise<Jsonify<O>>;
+    sendToQueue(name: string, client: QueuesClient, queueId: string, messages: QueueMessageInput[]): Promise<SentMessages>;
+    waitForMessage(name: string, opts: WaitForMessageOptions): Promise<ReceivedMessage | null>;
+    idempotencyKey(): string;
+}
+export interface WorkflowContext<I> {
+    input: I;
+    run: {
+        id: string;
+        runKey?: string;
+        attempt: number;
+        schedule?: {
+            id: string;
+            scheduledTime: string;
+        };
+    };
+    step: Step;
+    traceparent: string;
+}
+export {};

package/dist/runtime/context.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/errors.d.ts

@@ -0,0 +1,49 @@
+import type { WireError } from "../protocol/index.ts";
+export declare class NonRetriableError extends Error {
+    name: string;
+    readonly code = "workflows.non_retriable";
+}
+export declare class RetryAfterError extends Error {
+    readonly delayMs: number;
+    name: string;
+    constructor(message: string, delayMs: number);
+}
+export declare class CancelledError extends Error {
+    name: string;
+    readonly code = "workflows.cancelled";
+}
+export declare class WorkflowError extends Error {
+    code: string;
+    data?: unknown;
+    constructor(message: string, opts?: {
+        code?: string;
+        name?: string;
+        data?: unknown;
+        cause?: unknown;
+    });
+}
+export declare class CallbackTimeout extends WorkflowError {
+    constructor(message: string, opts?: {
+        name?: string;
+        data?: unknown;
+        cause?: unknown;
+    });
+}
+export declare class ChildFailed extends WorkflowError {
+    constructor(message: string, opts?: {
+        name?: string;
+        data?: unknown;
+        cause?: unknown;
+    });
+}
+export declare class StepTimeout extends Error {
+    name: string;
+}
+export declare class DuplicateStepName extends Error {
+    name: string;
+}
+export declare class OutputTooLarge extends Error {
+    name: string;
+}
+export declare function encodeError(e: unknown, depth?: number): WireError;
+export declare function decodeError(w: WireError): Error;