CL Pipelines Complete API Reference for All Exports

This page is a complete reference for every exported function, type, and error class in @claritylabs/cl-pipelines v0.1.0. For concept explanations and full examples, see the topic pages linked throughout this reference.

Core (`@claritylabs/cl-pipelines`)

Functions

runPipeline

function runPipeline<TState>(args: RunPipelineArgs<TState>): Promise<void>

Seeds a pipeline run: writes status: "running", persists the initial checkpoint, and calls scheduler.scheduleAdvance(jobId, 0). Does not execute any phase directly. Safe to call from web request handlers and UI mutation actions. See runPipeline and advancePhase.

advancePhase

function advancePhase<TState>(args: AdvancePhaseArgs<TState>): Promise<void>

Executes one phase. Reads the checkpoint, finds the matching phase by name, calls phase.run(ctx), and handles the result. Call this from your SchedulerAdapter implementation, not directly from application code.

buildAgentPhase

function buildAgentPhase<TOOLS>(opts: BuildAgentPhaseOpts<TOOLS>): Phase<AgentCheckpoint>

Returns a single Phase<AgentCheckpoint> named "turn" that runs one LLM turn per invocation. Compose with other phases manually when you need a custom graph. Pass to runPipeline via the phases array.

runAgent

function runAgent<TOOLS>(args: RunAgentArgs<TOOLS>): Promise<void>

Convenience wrapper: calls buildAgentPhase(opts) and passes the result to runPipeline. Use when you want a pure multi-turn agent loop with no custom phases around it. See Durable LLM Agent Loop.

createMemoryStorage

function createMemoryStorage<TState>(): MemoryStorage<TState>

Returns an in-memory StorageAdapter with two additional test-only methods:

_inspect(): Map<string, JobRecord<TState>> — read all stored job records
Implements all five StorageAdapter methods in memory

createMemoryScheduler

function createMemoryScheduler(): MemoryScheduler

Returns an in-memory SchedulerAdapter with two test-only methods:

_bind(fn: (jobId: string) => Promise<void>): void — register the advance handler
drain(): Promise<void> — flush all pending advances synchronously

Key types

string union

"idle" | "running" | "paused" | "complete" | "error"

string union

"resume" | "full"

object

type LogEntry = {
  timestamp: number;              // Unix ms
  message: string;
  phase?: string;                 // phase name when log was written
  level?: "info" | "warn" | "error";  // default: "info"
};

object

type Checkpoint<TState = unknown> = {
  nextPhase: string;   // name of next phase to execute
  state: TState;       // arbitrary state between phases
  createdAt: number;   // Unix ms timestamp
};

object

type Phase<TState> = {
  name: string;
  run: (ctx: PhaseContext<TState>) => Promise<PhaseResult<TState>>;
};

object

type PhaseContext<TState> = {
  jobId: string;
  checkpoint: Checkpoint<TState>;
  log: (message: string, level?: "info" | "warn" | "error") => Promise<void>;
  saveState: (state: TState) => Promise<void>;
};

union

type PhaseResult<TState> =
  | { kind: "next"; nextPhase: string; state: TState }
  | { kind: "done" }
  | { kind: "error"; error: string };

interface

type StorageAdapter<TState> = {
  getJob(jobId: string): Promise<{ status: PipelineStatus; checkpoint: Checkpoint<TState> | null; error?: string } | null>;
  setStatus(jobId: string, status: PipelineStatus, error?: string): Promise<void>;
  setCheckpoint(jobId: string, checkpoint: Checkpoint<TState> | null): Promise<void>;
  appendLog(jobId: string, entry: LogEntry): Promise<void>;
  clearLog(jobId: string): Promise<void>;
};

interface

type SchedulerAdapter = {
  scheduleAdvance(jobId: string, delayMs: number): Promise<void>;
};

object

type RunPipelineArgs<TState> = {
  jobId: string;
  phases: Phase<TState>[];
  storage: StorageAdapter<TState>;
  scheduler: SchedulerAdapter;
  retryMode?: RetryMode;
  initialState: TState;
  initialPhase?: string;
};

object

type AgentCheckpoint = {
  messages: AgentTurn[];       // full conversation history
  pendingToolCalls: [];        // reserved for v0.2, always [] in v0.1
  turn: number;                // current turn index (0-based)
};

type alias

AgentTurn = ModelMessage — re-export of ModelMessage from the Vercel AI SDK.

object

type RunAgentArgs<TOOLS> = {
  jobId: string;
  model: LanguageModel;
  tools?: TOOLS;
  system?: string;
  initialMessages: AgentTurn[];
  maxTurns?: number;             // default: 10
  storage: StorageAdapter<AgentCheckpoint>;
  scheduler: SchedulerAdapter;
  retryMode?: RetryMode;
};

Error classes

class

Extends Error. Base class for all pipeline errors.

class PipelineError extends Error {
  jobId: string;
  phase?: string;
}

class

Extends PipelineError. Thrown when a phase throws an unexpected error (not a { kind: "error" } return).

class PhaseError extends PipelineError {
  recoverable: boolean;  // true if checkpoint was preserved for resume
}

Convex (`@claritylabs/cl-pipelines/convex`)

Functions

() => object

Returns a Convex field definition object. Spread into defineTable(...) to add pipelineStatus, pipelineError, pipelineCheckpoint, and pipelineLog columns.

import { pipelineFields } from "@claritylabs/cl-pipelines/convex";

defineTable({ ...pipelineFields(), myField: v.string() })

function

function createConvexStorageAdapter<TState>({
  ctx: ActionCtx,
  mutations: ConvexPipelineMutations,
}): StorageAdapter<TState>

Creates a StorageAdapter backed by Convex mutations. Pass your five pipeline mutation references in the mutations map.

function

function createConvexSchedulerAdapter({
  ctx: ActionCtx,
  advanceAction: FunctionReference<"action">,
  jobIdArgName?: string,
}): SchedulerAdapter

Creates a SchedulerAdapter that calls ctx.scheduler.runAfter(0, advanceAction, { [jobIdArgName]: jobId }). Default jobIdArgName is "jobId".

Types

type

The type of the mutations argument passed to createConvexStorageAdapter. Import and use for type-safe wiring:

import type { ConvexPipelineMutations } from "@claritylabs/cl-pipelines/convex";

UI (`@claritylabs/cl-pipelines/ui`)

Components

compound component

Compound component for displaying job status. Renders null for "idle", "complete", and undefined status.Sub-components: StatusBanner.Root (alias: StatusBanner), StatusBanner.Indicator, StatusBanner.Title, StatusBanner.Description, StatusBanner.Actions.See Components.

component

Renders a <ul> of LogEntry items. Supports limit, latestOnly, and renderEntry customization. Renders null when entries is empty or undefined.See Components.

component

Renders resume and restart buttons. Calls onRetry("resume") or onRetry("full") on click. Fully customizable via renderButton.See Components.

Re-exported types

re-export

"resume" | "full" — re-exported from the core package for convenience in UI code.

Get Started

Phase Runner

Agent Loop

Adapters & UI

Reference

CL Pipelines Complete API Reference for All Exports

Core (`@claritylabs/cl-pipelines`)

Functions

runPipeline

advancePhase

buildAgentPhase

runAgent

createMemoryStorage

createMemoryScheduler

Key types

Error classes

Convex (`@claritylabs/cl-pipelines/convex`)

Functions

Types

UI (`@claritylabs/cl-pipelines/ui`)

Components

Re-exported types

​Core (@claritylabs/cl-pipelines)

​Functions

​runPipeline

​advancePhase

​buildAgentPhase

​runAgent

​createMemoryStorage

​createMemoryScheduler

​Key types

​Error classes

​Convex (@claritylabs/cl-pipelines/convex)

​Functions

​Types

​UI (@claritylabs/cl-pipelines/ui)

​Components

​Re-exported types

Core (`@claritylabs/cl-pipelines`)

Functions

runPipeline

advancePhase

buildAgentPhase

runAgent

createMemoryStorage

createMemoryScheduler

Key types

Error classes

Convex (`@claritylabs/cl-pipelines/convex`)

Functions

Types

UI (`@claritylabs/cl-pipelines/ui`)

Components

Re-exported types