> ## 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](/docs/cl-pipelines/phase-runner/overview).

#### 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](/docs/cl-pipelines/agent/overview).

#### 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

<ResponseField name="PipelineStatus" type="string union">
  `"idle" | "running" | "paused" | "complete" | "error"`
</ResponseField>

<ResponseField name="RetryMode" type="string union">
  `"resume" | "full"`
</ResponseField>

<ResponseField name="LogEntry" type="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"
  };
  ```
</ResponseField>

<ResponseField name="Checkpoint<TState>" type="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
  };
  ```
</ResponseField>

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

<ResponseField name="PhaseContext<TState>" type="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>;
  };
  ```
</ResponseField>

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

<ResponseField name="StorageAdapter<TState>" type="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>;
  };
  ```
</ResponseField>

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

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

<ResponseField name="AgentCheckpoint" type="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)
  };
  ```
</ResponseField>

<ResponseField name="AgentTurn" type="type alias">
  `AgentTurn = ModelMessage` — re-export of `ModelMessage` from the Vercel AI SDK.
</ResponseField>

<ResponseField name="RunAgentArgs<TOOLS>" type="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;
  };
  ```
</ResponseField>

***

### Error classes

<ResponseField name="PipelineError" type="class">
  Extends `Error`. Base class for all pipeline errors.

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

<ResponseField name="PhaseError" type="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
  }
  ```
</ResponseField>

***

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

### Functions

<ResponseField name="pipelineFields" type="() => 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() })
  ```
</ResponseField>

<ResponseField name="createConvexStorageAdapter" type="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.
</ResponseField>

<ResponseField name="createConvexSchedulerAdapter" type="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"`.
</ResponseField>

### Types

<ResponseField name="ConvexPipelineMutations" type="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";
  ```
</ResponseField>

***

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

### Components

<ResponseField name="StatusBanner" type="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](/docs/cl-pipelines/ui/components).
</ResponseField>

<ResponseField name="ProgressLog" type="component">
  Renders a `<ul>` of `LogEntry` items. Supports `limit`, `latestOnly`, and `renderEntry` customization. Renders `null` when `entries` is empty or undefined.

  See [Components](/docs/cl-pipelines/ui/components).
</ResponseField>

<ResponseField name="RetryButtons" type="component">
  Renders resume and restart buttons. Calls `onRetry("resume")` or `onRetry("full")` on click. Fully customizable via `renderButton`.

  See [Components](/docs/cl-pipelines/ui/components).
</ResponseField>

### Re-exported types

<ResponseField name="RetryMode" type="re-export">
  `"resume" | "full"` — re-exported from the core package for convenience in UI code.
</ResponseField>