> ## Documentation Index
> Fetch the complete documentation index at: https://claritylabs.inc/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CL Pipelines Complete API Reference for All Exports

> Complete API reference for all exports in @claritylabs/cl-pipelines, @claritylabs/cl-pipelines/convex, and @claritylabs/cl-pipelines/ui.

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

```typescript theme={"system"}
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](https://claritylabs.inc/docs/cl-pipelines/phase-runner/overview.md).

#### advancePhase

```typescript theme={"system"}
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

```typescript theme={"system"}
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

```typescript theme={"system"}
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](https://claritylabs.inc/docs/cl-pipelines/agent/overview.md).

#### createMemoryStorage

```typescript theme={"system"}
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

```typescript theme={"system"}
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

**PipelineStatus** `string union`

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

**RetryMode** `string union`

`"resume" | "full"`

**LogEntry** `object`

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

**Checkpoint\<TState>** `object`

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

**Phase\<TState>** `object`

```typescript theme={"system"}
type Phase<TState> = {
  name: string;
  run: (ctx: PhaseContext<TState>) => Promise<PhaseResult<TState>>;
};
```

**PhaseContext\<TState>** `object`

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

**PhaseResult\<TState>** `union`

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

**StorageAdapter\<TState>** `interface`

```typescript theme={"system"}
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>;
};
```

**SchedulerAdapter** `interface`

```typescript theme={"system"}
type SchedulerAdapter = {
  scheduleAdvance(jobId: string, delayMs: number): Promise<void>;
};
```

**RunPipelineArgs\<TState>** `object`

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

**AgentCheckpoint** `object`

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

**AgentTurn** `type alias`

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

**RunAgentArgs\<TOOLS>** `object`

```typescript theme={"system"}
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

**PipelineError** `class`

Extends `Error`. Base class for all pipeline errors.

```typescript theme={"system"}
class PipelineError extends Error {
  jobId: string;
  phase?: string;
}
```

**PhaseError** `class`

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

```typescript theme={"system"}
class PhaseError extends PipelineError {
  recoverable: boolean;  // true if checkpoint was preserved for resume
}
```

***

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

### Functions

**pipelineFields** `() =\> object`

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

```typescript theme={"system"}
import { pipelineFields } from "@claritylabs/cl-pipelines/convex";

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

**createConvexStorageAdapter** `function`

```typescript theme={"system"}
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.

**createConvexSchedulerAdapter** `function`

```typescript theme={"system"}
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

**ConvexPipelineMutations** `type`

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

```typescript theme={"system"}
import type { ConvexPipelineMutations } from "@claritylabs/cl-pipelines/convex";
```

***

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

### Components

**StatusBanner** `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](https://claritylabs.inc/docs/cl-pipelines/ui/components.md).

**ProgressLog** `component`

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

See [Components](https://claritylabs.inc/docs/cl-pipelines/ui/components.md).

**RetryButtons** `component`

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

See [Components](https://claritylabs.inc/docs/cl-pipelines/ui/components.md).

### Re-exported types

**RetryMode** `re-export`

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.