@segmentstream/ontology 0.0.0-stage → 0.92.0

package/dist/service/workflows.d.ts

@@ -0,0 +1,200 @@
+import { Layer, Redacted } from "effect";
+import { HttpRouter } from "effect/unstable/http";
+import { type DeploymentObservation } from "../deployment.js";
+import { type WebhookVerifier, type WebhookTokenVerifier } from "./webhooks.js";
+import type { Ontology } from "../ontology.js";
+import { type WorkflowStarter } from "../runtime/workflow-starts.js";
+import { type WorkflowFunction } from "../workflow.js";
+import { type WorkflowSdk } from "../workflow-runtime.js";
+import { type AgentTransport } from "./agent/task-start.js";
+import { type SessionExchange, type TokenVerifier } from "./authentication.js";
+import type { AfterCommitHook } from "./config.js";
+import type { ChatDeliveryFactory } from "./chat/delivery.js";
+import type { ConnectionTransportFactory } from "./connections.js";
+import { RequestId } from "./errors.js";
+import type { ApiPlan } from "./plan.js";
+import type { ReplicationKick } from "./replication.js";
+import { OntologyBackend } from "./runtime-contract.js";
+export { WorkflowStepFailed } from "./workflow-errors.js";
+import { type RuntimeTokenVerifier } from "./runtime-identity.js";
+export { MAX_LISTED_WORKFLOW_EVENTS, WORLD_PAGE_SIZE } from "./workflow-diagnostics.js";
+/** A run as the workflow routes answer it, from the Workflow SDK's run record. */
+export interface WorkflowRunRecord {
+    readonly runId: string;
+    /** The Workflow SDK's id of the workflow function: `workflow//<file>//<function>`. */
+    readonly workflowName: string;
+    readonly status: string;
+    readonly createdAt: Date | string;
+    readonly startedAt?: Date | string | undefined;
+    readonly completedAt?: Date | string | undefined;
+    readonly attributes?: Readonly<Record<string, string>> | undefined;
+    readonly deploymentId?: string;
+    readonly error?: unknown;
+}
+/** A step of a run, from the Workflow SDK's step record. */
+export interface WorkflowStepRecord {
+    readonly stepId: string;
+    readonly stepName: string;
+    readonly status: string;
+    readonly attempt?: number | undefined;
+    readonly startedAt?: Date | string | undefined;
+    readonly completedAt?: Date | string | undefined;
+    readonly error?: unknown;
+    readonly attempts?: ReadonlyArray<WorkflowAttemptRecord>;
+}
+export interface WorkflowAttemptRecord {
+    readonly attempt: number;
+    readonly status: string;
+    readonly startedAt?: Date | string;
+    readonly completedAt?: Date | string;
+    readonly error?: unknown;
+}
+export interface WorkflowDiagnostics {
+    readonly error?: unknown;
+    readonly attempts: ReadonlyMap<string, ReadonlyArray<WorkflowAttemptRecord>>;
+    readonly truncated: boolean;
+}
+export interface WorkflowEventRecord {
+    readonly runId?: string;
+    readonly eventId: string;
+    readonly eventType: string;
+    readonly correlationId?: string;
+    readonly createdAt?: Date | string;
+    readonly eventData?: {
+        readonly error?: unknown;
+        readonly attempt?: number;
+    };
+}
+export interface WorkflowPage<T> {
+    readonly data: ReadonlyArray<T>;
+    readonly cursor: string | null;
+    readonly hasMore: boolean;
+}
+/**
+ * How the service starts runs and reads their records. By default it is the Vercel Workflow SDK:
+ * `start` from `workflow/api`, and the world's `runs.list`, `runs.get` and `steps.list`.
+ */
+export interface WorkflowEngine {
+    readonly allocateRun?: WorkflowSdk["allocateRun"];
+    /** Resolve hook ownership without hydrating its payload or resuming its run. */
+    readonly getHookRunId?: (token: string) => Promise<string | undefined>;
+    readonly start: (workflow: WorkflowFunction<unknown>, args: ReadonlyArray<unknown>, options?: {
+        readonly attributes?: Readonly<Record<string, string>>;
+        readonly reservation?: import("../runtime/workflow-admission.js").WorkflowReservation;
+    }) => Promise<{
+        readonly runId: string;
+    }>;
+    readonly listRuns: (input: {
+        readonly workflowName: string;
+        readonly limit: number;
+        readonly cursor?: string | undefined;
+    }) => Promise<WorkflowPage<WorkflowRunRecord>>;
+    /** `undefined` when the world has no such run. */
+    readonly getRun: (runId: string) => Promise<WorkflowRunRecord | undefined>;
+    readonly listSteps: (runId: string, page?: {
+        readonly limit?: number;
+        readonly cursor?: string;
+    }) => Promise<WorkflowPage<WorkflowStepRecord>>;
+    readonly diagnostics?: (run: WorkflowRunRecord, steps?: ReadonlyArray<WorkflowStepRecord>) => Promise<WorkflowDiagnostics>;
+    /**
+     * Resumes the hook a workflow waits on with `payload`: `not_found` when no run waits on the token
+     * any longer. Without it, an agent task's result reaches its workflow at the task's deadline.
+     */
+    readonly resumeHook?: (token: string, payload: unknown) => Promise<"resumed" | "not_found">;
+}
+export interface WorldLike {
+    readonly hooks?: {
+        readonly getByToken: (token: string) => Promise<{
+            readonly runId: string;
+        }>;
+    };
+    readonly runs: {
+        readonly list: (params: unknown) => Promise<WorkflowPage<WorkflowRunRecord>>;
+        readonly get: (id: string, params?: unknown) => Promise<WorkflowRunRecord>;
+    };
+    readonly steps: {
+        readonly list: (params: unknown) => Promise<WorkflowPage<WorkflowStepRecord>>;
+    };
+    readonly events?: {
+        readonly list: (params: unknown) => Promise<WorkflowPage<WorkflowEventRecord>>;
+        readonly listByCorrelationId?: (params: unknown) => Promise<WorkflowPage<WorkflowEventRecord>>;
+        readonly get: (runId: string, eventId: string, params: unknown) => Promise<{
+            readonly eventData?: {
+                readonly error?: unknown;
+            };
+        }>;
+    };
+}
+/**
+ * The Workflow SDK's engine over a world: `start` from `workflow/api` on the ontology's queue, and
+ * the world's `runs.list`, `runs.get` and `steps.list`, paged within what the Vercel world accepts.
+ */
+export declare function worldWorkflowEngine(world: () => Promise<WorldLike>, begin?: WorkflowSdk["start"], hydrate?: NonNullable<WorkflowSdk["hydrateError"]>, resume?: WorkflowSdk["resumeHook"]): WorkflowEngine;
+/**
+ * The Vercel Workflow SDK as `installWorkflowRuntime()` registered it. The service imports none of
+ * the SDK itself: a process that bundles the service without serving workflows, such as the
+ * platform's backend on another SDK major, carries none of it.
+ */
+export declare const vercelWorkflowEngine: WorkflowEngine;
+/** A workflow route was served in a process that never called `installWorkflowRuntime()`. */
+export declare class WorkflowRuntimeNotInstalled extends Error {
+    constructor();
+}
+/** The Workflow SDK's id of a compiled `"use workflow"` function; `undefined` before compilation. */
+export declare function compiledWorkflowId(run: unknown): string | undefined;
+interface WorkflowsOptions {
+    readonly deployment: DeploymentObservation;
+    readonly plan: ApiPlan;
+    readonly hooks: ReadonlyMap<string, AfterCommitHook>;
+    readonly connections: ConnectionTransportFactory;
+    readonly replicate: ReplicationKick;
+    readonly chatDelivery?: ChatDeliveryFactory | undefined;
+    readonly verifyToken: TokenVerifier;
+    readonly verifyRuntime?: RuntimeTokenVerifier | undefined;
+    readonly exchangeSession?: SessionExchange | undefined;
+    readonly workspaceId: string;
+    readonly cronSecret?: Redacted.Redacted<string> | undefined;
+    readonly engine?: WorkflowEngine | undefined;
+    /** The deployment's webhook secret. Without it every webhook path answers 404. */
+    readonly webhookSecret?: Redacted.Redacted<string> | undefined;
+    /** Checks signed webhooks' signatures; required for a manifest with a signed webhook. */
+    readonly webhookVerifier?: WebhookVerifier | undefined;
+    readonly webhookTokenVerifier?: WebhookTokenVerifier | undefined;
+    /** The deployment's production origin, where `agentTask` reaches the app's agent. */
+    readonly agentOrigin?: string | undefined;
+    /** How `agentTask` calls the app's agent: `fetch` by default. */
+    readonly agentTransport?: AgentTransport | undefined;
+}
+/**
+ * Starts the runs action triggers decide, through the engine on the ontology's queue: the row's
+ * wire input decoded with the workflow's input, and `startedBy` naming the trigger, the action and,
+ * when it was evaluated per edited record, the record. The ontology service hands it to the runtime.
+ *
+ * `ensureRecovery` arms the platform's recovery run, one per process at a time: a run started at
+ * `A` first sweeps at `A + RECOVERY_FIRST_SWEEP_MS` and looks once more RECOVERY_CONFIRM_MS later,
+ * so it covers every request whose transaction deadline falls before that horizon, less a margin.
+ * Requests that arrive while a start is in flight wait for it instead of starting their own.
+ */
+export declare function workflowStarter(ontology: Ontology, engine: WorkflowEngine, clock?: () => number): WorkflowStarter["Service"];
+/** The route Vercel calls for a cron trigger: `/api/ontology/workflows/<workflow>/triggers/<trigger>`. */
+export declare function triggerPath(workflow: string, trigger: string): string;
+/** The route Vercel calls every five minutes when the manifest declares an action trigger. */
+export declare const SWEEP_PATH = "/api/ontology/workflows/sweep";
+/**
+ * The workflow routes and the in-process binding of workflow runs:
+ *
+ * - `GET /api/ontology/workflows/:workflow/triggers/:trigger`, Vercel's cron call, verified with the
+ *   project's cron secret, starts the workflow with the trigger's input;
+ * - `POST /api/ontology/workflows/:workflow/start` starts it for a member holding
+ *   `workflow:<workflow>:start`, or for the platform;
+ * - `GET /api/ontology/workflows`, `…/:workflow/runs` and `…/runs/:runId` read the declarations
+ *   and the SDK's run records for callers holding `workflow:<workflow>:read` and the platform;
+ * - `GET /api/ontology/workflows/:workflow/starts` lists the starts its action triggers decided,
+ *   pending and started, for the same callers;
+ * - `GET` and `POST /api/ontology/workflows/sweep`, verified with the cron secret, start the
+ *   starts that stayed pending.
+ *
+ * Building it installs the binding `run(effect)` uses inside steps; the flow callback, which
+ * `ontologyWorkflows()` mounts outside these routes, runs them.
+ */
+export declare function workflowsLayer(options: WorkflowsOptions): Layer.Layer<never, never, OntologyBackend | HttpRouter.HttpRouter | HttpRouter.Request<"Requires", RequestId>>;