Rulvar

https://docs.rulvar.com
Admin
Rulvar is a system for adaptive orchestration that manages LLM interactions, offering unified...
Tokens:259,932
Snippets:3,372
Trust Score:4.5
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install @rulvar/planner

Source: https://docs.rulvar.com/api/%40rulvar/planner

Install the core and planner packages using pnpm.

```bash
pnpm add @rulvar/core @rulvar/planner
```

--------------------------------

### Install @rulvar/compat

Source: https://docs.rulvar.com/api/%40rulvar/compat

Install the compatibility package using pnpm.

```bash
pnpm add @rulvar/compat
```

--------------------------------

### Run Rulvar examples

Source: https://docs.rulvar.com/guide/examples

Commands to clone the repository and execute the integration tests for the example patterns.

```bash
git clone https://github.com/o-stepper/rulvar.git
cd rulvar
pnpm install
pnpm build
pnpm vitest run examples/src
```

--------------------------------

### Install @rulvar/plan

Source: https://docs.rulvar.com/api/%40rulvar/plan

Install the required packages to use the plan extension in a Rulvar project.

```bash
pnpm add @rulvar/core @rulvar/plan
```

--------------------------------

### Install @rulvar/bridge-ai-sdk

Source: https://docs.rulvar.com/api/%40rulvar/bridge-ai-sdk

Install the bridge package along with the core Rulvar library.

```bash
pnpm add @rulvar/core @rulvar/bridge-ai-sdk
```

--------------------------------

### Install @rulvar/cli

Source: https://docs.rulvar.com/guide/cli

Install the CLI package using pnpm.

```bash
pnpm add @rulvar/cli
```

--------------------------------

### Install and verify Rulvar CLI

Source: https://docs.rulvar.com/api/%40rulvar/cli

Install the package using pnpm and verify the installation by displaying the help menu.

```bash
pnpm add @rulvar/cli
pnpm exec rulvar --help
```

--------------------------------

### Install Rulvar dependencies

Source: https://docs.rulvar.com/guide/planner

Install the core, planner, and Anthropic adapter packages via pnpm.

```bash
pnpm add @rulvar/core @rulvar/planner @rulvar/anthropic
```

--------------------------------

### Install @rulvar/store-conformance

Source: https://docs.rulvar.com/api/%40rulvar/store-conformance

Add the conformance kit as a development dependency to your project.

```bash
pnpm add -D @rulvar/store-conformance
```

--------------------------------

### Install @rulvar/store-sqlite

Source: https://docs.rulvar.com/api/%40rulvar/store-sqlite

Install the core Rulvar package and the SQLite store implementation using pnpm.

```bash
pnpm add @rulvar/core @rulvar/store-sqlite
```

--------------------------------

### Install Rulvar core packages

Source: https://docs.rulvar.com/guide/installation

Installs the primary Rulvar engine and standard adapters using pnpm.

```bash
pnpm add @rulvar/rulvar
```

--------------------------------

### Vitest Usage Example

Source: https://docs.rulvar.com/api/%40rulvar/store-conformance/functions/makeSuite

Example of how to register a conformance suite within a Vitest testing environment.

```typescript
const suite = journalStoreConformance(() => new MyStore()); registerConformance(suite, { describe, it });
```

--------------------------------

### Initialize Rulvar Project

Source: https://docs.rulvar.com/guide/llms

Install necessary dependencies and configure the environment for ESM and API access.

```bash
pnpm add @rulvar/rulvar zod
npm pkg set type=module   # the file uses top-level await, so the project must be ESM
export ANTHROPIC_API_KEY="your-api-key"
```

--------------------------------

### Install the Rulvar umbrella package

Source: https://docs.rulvar.com/guide/installation

Install the full Rulvar suite using your preferred package manager.

```bash
pnpm add @rulvar/rulvar
```

```bash
npm install @rulvar/rulvar
```

```bash
yarn add @rulvar/rulvar
```

--------------------------------

### Install Rulvar packages

Source: https://docs.rulvar.com/guide/orchestration-modes

Install the necessary packages for different orchestration modes.

```bash
pnpm add @rulvar/core @rulvar/anthropic   # mode (a): human scripts
pnpm add @rulvar/planner                  # mode (b): the flagship hybrid
pnpm add @rulvar/plan                     # mode (c) extension: PlanRunner
```

--------------------------------

### Install Testing Dependencies

Source: https://docs.rulvar.com/guide/testing

Add the required testing and core packages to your project.

```bash
pnpm add -D @rulvar/testing @rulvar/core
```

--------------------------------

### Install Rulvar OpenAI adapter

Source: https://docs.rulvar.com/api/%40rulvar/openai

Use this command to add the necessary packages to your project.

```bash
pnpm add @rulvar/core @rulvar/openai
```

--------------------------------

### Install @rulvar/testing

Source: https://docs.rulvar.com/api/%40rulvar/testing

Add the testing package as a development dependency to your project.

```bash
pnpm add -D @rulvar/testing
```

--------------------------------

### Install SQLite store package

Source: https://docs.rulvar.com/guide/stores

Command to add the SQLite storage implementation to your project.

```bash
pnpm add @rulvar/store-sqlite
```

--------------------------------

### Install @rulvar/core

Source: https://docs.rulvar.com/api/%40rulvar/core

Use this command to add the core engine package to your project.

```bash
pnpm add @rulvar/core
```

--------------------------------

### Install Rulvar packages

Source: https://docs.rulvar.com/reference/packages

Use pnpm to install either the full umbrella package or specific individual components.

```bash
# Batteries included: core, both first-class adapters, the progress renderer
pnpm add @rulvar/rulvar

# A la carte: engine, one adapter, a durable store
pnpm add @rulvar/core @rulvar/anthropic @rulvar/store-sqlite
```

--------------------------------

### Install @rulvar/anthropic

Source: https://docs.rulvar.com/api/%40rulvar/anthropic

Install the required packages to use the Anthropic adapter in a Rulvar project.

```bash
pnpm add @rulvar/core @rulvar/anthropic
```

--------------------------------

### Install Rulvar dependencies

Source: https://docs.rulvar.com/guide/adaptive-orchestration

Install the core Rulvar packages and necessary adapters for Anthropic and SQLite storage.

```bash
pnpm add @rulvar/core @rulvar/anthropic @rulvar/plan @rulvar/store-sqlite
```

--------------------------------

### Install Rulvar dependencies

Source: https://docs.rulvar.com/guide/quickstart

Install the core Rulvar package and Zod for schema validation.

```bash
pnpm add @rulvar/rulvar zod
```

--------------------------------

### Configure JsonlFileStore

Source: https://docs.rulvar.com/guide/stores

Example of initializing a Rulvar engine with JSONL file storage for journals and transcripts.

```typescript
import { createEngine, FileTranscriptStore, JsonlFileStore } from '@rulvar/core';
import { anthropic } from '@rulvar/anthropic';

const engine = createEngine({
  adapters: [anthropic()],
  stores: {
    journal: new JsonlFileStore({ dir: './runs' }),
    transcripts: new FileTranscriptStore({ dir: './runs' }),
  },
});
```

--------------------------------

### startSpan()

Source: https://docs.rulvar.com/api/%40rulvar/cli/interfaces/TracerLike

Starts a new span with the specified name, optional attributes, start time, and context.

```APIDOC
## startSpan(name, options?, context?)

### Description
Starts a new span for tracing purposes. Returns a SpanLike object representing the started span.

### Parameters
- **name** (string) - Required - The name of the span.
- **options** (object) - Optional - Configuration options for the span.
  - **attributes** (Record<string, string | number | boolean>) - Optional - Key-value pairs to attach to the span.
  - **startTime** (number) - Optional - The start time of the span.
- **context** (unknown) - Optional - The context in which the span is created.

### Returns
- **SpanLike** - The created span object.
```

--------------------------------

### Install Bridge AI SDK dependencies

Source: https://docs.rulvar.com/guide/providers

Install the bridge package and the required Vercel AI SDK provider package.

```bash
pnpm add @rulvar/bridge-ai-sdk @ai-sdk/google
```

--------------------------------

### Install OpenAI Adapter

Source: https://docs.rulvar.com/guide/providers

Adds the OpenAI provider package to the project dependencies.

```bash
pnpm add @rulvar/openai
```

--------------------------------

### Initialize the Anthropic adapter

Source: https://docs.rulvar.com/guide/providers

Basic setup for the Anthropic adapter using an API key from environment variables.

```javascript
const adapter = openai({
  apiKey: process.env.OPENAI_API_KEY, // optional; the SDK reads the variable itself
});
```

--------------------------------

### start()

Source: https://docs.rulvar.com/api/%40rulvar/cli/interfaces/Worker

Begins the sweeping process on the poll cadence. This method is idempotent.

```APIDOC
## start()

### Description
Begins sweeping on the poll cadence. Idempotent.

### Returns
- **void**
```

--------------------------------

### Install OpenTelemetry dependencies

Source: https://docs.rulvar.com/guide/observability

Install the required CLI package and OpenTelemetry API peer dependency to enable trace exporting.

```bash
pnpm add @rulvar/cli @opentelemetry/api
```

--------------------------------

### engine.run(wf, args, opts?)

Source: https://docs.rulvar.com/guide/workflows

Starts a new workflow run and returns a RunHandle for monitoring and interaction.

```APIDOC
## engine.run(wf, args, opts?)

### Description
Starts a workflow execution and returns a RunHandle immediately. The run can be configured with a specific runId, budget, deadline, and execution limits.

### Parameters
- **wf** (Workflow) - Required - The workflow definition to execute.
- **args** (Object) - Required - Arguments passed to the workflow.
- **opts** (Object) - Optional - Configuration options including runId (string), budgetUsd (number), deadlineAt (string), and limits (Object).
```

--------------------------------

### POST /runs

Source: https://docs.rulvar.com/guide/cli

Starts a new run of a registered workflow.

```APIDOC
## POST /runs

### Description
Starts a run of a registered workflow.

### Method
POST

### Endpoint
/runs

### Request Body
- **workflow** (string) - Required - The workflow identifier
- **args** (object) - Optional - Arguments for the workflow
- **options** (object) - Optional - Configuration including runId, budgetUsd, name, tags, deadlineAt

### Response
#### Success Response (201)
- **runId** (string) - The ID of the created run
- **status** (string) - The initial status of the run
- **workflow** (string) - The workflow identifier
```

--------------------------------

### Configure Engine with SqliteStore

Source: https://docs.rulvar.com/guide/stores

Full engine setup using SqliteStore for journal persistence with lease support.

```typescript
import { createEngine, FileTranscriptStore, LeaseHeldError, type Lease } from '@rulvar/core';
import { SqliteStore } from '@rulvar/store-sqlite';
import { anthropic } from '@rulvar/anthropic';
import { review } from './workflows/review.js';

const store = new SqliteStore({ path: './rulvar.db' });
const engine = createEngine({
  adapters: [anthropic()],
  stores: { journal: store, transcripts: new FileTranscriptStore({ dir: './blobs' }) },
});
```

--------------------------------

### Install @rulvar/evals

Source: https://docs.rulvar.com/api/%40rulvar/evals

Use this command to add the evaluation framework to your project dependencies.

```bash
pnpm add -D @rulvar/evals
```

--------------------------------

### Install the evals package

Source: https://docs.rulvar.com/guide/evals

Use pnpm to add the @rulvar/evals package to your project.

```bash
pnpm add @rulvar/evals
```

--------------------------------

### Configure a file-backed test engine

Source: https://docs.rulvar.com/guide/testing

Use this setup to persist fake engine runs to disk for inspection via the CLI.

```typescript
import { createEngine, JsonlFileStore } from '@rulvar/core';
import { FakeAdapter, FAKE_MODEL_REF } from '@rulvar/testing';

const engine = createEngine({
  adapters: [new FakeAdapter({ agents: { '*': 'stub text' } })],
  stores: { journal: new JsonlFileStore({ dir: './fake-runs' }) },
  // The roles this page's workflows exercise; route others the same way.
  defaults: { routing: { loop: FAKE_MODEL_REF, extract: FAKE_MODEL_REF } },
});
```

--------------------------------

### Verify Rulvar Installation

Source: https://docs.rulvar.com/guide/installation

Create a verification script to confirm the engine initializes correctly and the hash version is accessible.

```javascript
// verify.mjs
import { createEngine, CURRENT_HASH_VERSION } from "@rulvar/rulvar";

const engine = createEngine({ adapters: [] });

console.log("engine ready:", typeof engine.run === "function");
console.log("journal hash version:", CURRENT_HASH_VERSION);
```

```bash
node verify.mjs
```

```text
engine ready: true
journal hash version: 2
```

--------------------------------

### emptyPlan()

Source: https://docs.rulvar.com/api/%40rulvar/plan/functions/emptyPlan

Returns the initial TaskPlan object used as the starting point for every fold.

```APIDOC
## emptyPlan()

### Description
Returns the empty plan that every fold starts from.

### Signature
`function emptyPlan(): TaskPlan;`

### Returns
- **TaskPlan** - The initial task plan object.
```

--------------------------------

### Verify package provenance

Source: https://docs.rulvar.com/reference/versioning

Use this command to verify the signatures and provenance of installed packages.

```bash
npm audit signatures
```

--------------------------------

### ToolEvents start member

Source: https://docs.rulvar.com/api/%40rulvar/core/type-aliases/ToolEvents

Represents the start event structure for a tool.

```typescript
{
  risk?: Json;
  toolName: string;
  type: "tool:start";
}
```

--------------------------------

### assembleEngine(options)

Source: https://docs.rulvar.com/api/%40rulvar/cli/functions/assembleEngine

Initializes the CLI engine with the specified configuration, working directory, and optional module or profile settings.

```APIDOC
## assembleEngine(options)

### Description
Assembles the CLI engine using the provided configuration and environment parameters.

### Signature
`function assembleEngine(options): AssembledCli;`

### Parameters
- **options** (object) - Required
  - **config** (CliConfig) - Required - The CLI configuration object.
  - **cwd** (string) - Required - The current working directory.
  - **module** (LoadedWorkflowModule) - Optional - The loaded workflow module.
  - **profile** (string) - Optional - The profile identifier.
  - **storePath** (string) - Optional - The path to the store.

### Returns
- **AssembledCli** - The assembled CLI instance.
```

--------------------------------

### engineWith(adapter, store, profiles, extras?)

Source: https://docs.rulvar.com/api/%40rulvar/plan/functions/engineWith

Initializes a new Engine instance with the specified configuration parameters.

```APIDOC
## engineWith(adapter, store, profiles, extras?)

### Description
Initializes and returns an Engine instance using the provided provider adapter, journal store, profiles, and optional configuration extras.

### Parameters
- **adapter** (ProviderAdapter) - Required - The provider adapter to use.
- **store** (JournalStore) - Required - The journal store instance.
- **profiles** (Record<string, unknown>) - Required - A record of profiles.
- **extras** (Object) - Optional - Additional configuration options.
  - **isolation** (unknown) - Optional
  - **knowledge** (unknown) - Optional - ModelKnowledge store for the M10 kb cassettes.
  - **lineage** (Record<string, number>) - Optional
  - **schemas** (Record<string, unknown>) - Optional

### Returns
- **Engine** - The initialized engine instance.
```

--------------------------------

### createTestEngine(options)

Source: https://docs.rulvar.com/api/%40rulvar/testing/functions/createTestEngine

Initializes and returns a TestEngine instance using the specified options.

```APIDOC
## createTestEngine(options)

### Description
Creates a new test engine instance to facilitate testing operations.

### Signature
`createTestEngine(options: CreateTestEngineOptions): TestEngine`

### Parameters
- **options** (CreateTestEngineOptions) - Required - Configuration options for the test engine.

### Returns
- **TestEngine** - An instance of the test engine.
```

--------------------------------

### Define a planner-written script

Source: https://docs.rulvar.com/guide/planner

Example of an async function body using sandbox globals like agent and parallel to perform research and writing tasks.

```typescript
const sources = await parallel([
  () => agent("Find primary sources on LSM tree compaction", { agentType: "researcher" }),
  () => agent("Find primary sources on B-tree write amplification", { agentType: "researcher" }),
]);

const draft = await agent(
  "Write a comparison from these notes:\n" + sources.join("\n"),
  { agentType: "writer", onError: "null" },
);

if (draft === null) {
  log("warn", "draft agent failed; returning raw notes");
  return { notes: sources };
}
return { report: draft };
```

--------------------------------

### createEngine(options)

Source: https://docs.rulvar.com/api/%40rulvar/core/functions/createEngine

Initializes a new engine instance using the specified configuration options.

```APIDOC
## createEngine(options)

### Description
Initializes and returns an Engine instance. This function is the primary entry point for creating an engine within the @rulvar/core package.

### Signature
`function createEngine(options: CreateEngineOptions): Engine;`

### Parameters
- **options** (CreateEngineOptions) - Required - Configuration object used to initialize the engine.

### Returns
- **Engine** - Returns an instance of the Engine class.
```

--------------------------------

### run<A, R>(wf, args, opts?)

Source: https://docs.rulvar.com/api/%40rulvar/core/interfaces/Engine

Initiates a new workflow execution.

```APIDOC
## run<A, R>(wf, args, opts?)

### Description
Starts a new workflow execution with the provided arguments and options.

### Parameters
- **wf** (Workflow<A, R> | CompiledWorkflow) - Required - The workflow definition or compiled workflow to execute.
- **args** (A) - Required - The input arguments for the workflow.
- **opts** (RunOptions) - Optional - Configuration options for the run.

### Returns
- **RunHandle<R>** - A handle to the running workflow.
```

--------------------------------

### createServer(options)

Source: https://docs.rulvar.com/api/%40rulvar/cli/functions/createServer

Initializes and returns a RulvarServer instance.

```APIDOC
## createServer(options)

### Description
Initializes a new Rulvar server instance using the provided configuration options.

### Signature
`function createServer(options: CreateServerOptions): RulvarServer`

### Parameters
- **options** (CreateServerOptions) - Required - Configuration options for the server.

### Returns
- **RulvarServer** - An instance of the Rulvar server.
```

--------------------------------

### Build Rulvar from Source

Source: https://docs.rulvar.com/guide/installation

Commands to clone the repository and build the project using pnpm and corepack.

```bash
git clone https://github.com/o-stepper/rulvar.git
cd rulvar
corepack enable
pnpm install --frozen-lockfile
pnpm build
pnpm test
```

--------------------------------

### new JsonlFileStore(options)

Source: https://docs.rulvar.com/api/%40rulvar/core/classes/JsonlFileStore

Creates a new instance of JsonlFileStore.

```APIDOC
### Constructor

`new JsonlFileStore(options: { dir: string })`

Initializes a new file store instance using the specified directory.
```

--------------------------------

### get(ref)

Source: https://docs.rulvar.com/api/%40rulvar/rulvar/interfaces/TranscriptStore

Retrieves a transcript blob by its reference.

```APIDOC
## get(ref)

### Description
Retrieves a blob by its reference.

### Parameters
- **ref** (string) - The reference of the blob to retrieve.

### Returns
- **Promise<Bytes | null>**
```

--------------------------------

### createEngine

Source: https://docs.rulvar.com/api/%40rulvar/rulvar

Initializes a new Rulvar engine instance with specified adapters and configuration defaults.

```APIDOC
## createEngine(config)

### Description
Creates and configures a new Rulvar engine instance. This is the primary entry point for setting up the workflow environment.

### Parameters
- **config** (object) - Required - Configuration object containing adapters and defaults.
  - **adapters** (array) - Required - List of LLM adapters (e.g., anthropic(), openai()).
  - **defaults** (object) - Required - Default routing and role floor configurations.

### Request Example
```typescript
import { createEngine, anthropic, openai, recommendedDefaults } from '@rulvar/rulvar';

const engine = createEngine({
  adapters: [anthropic(), openai()],
  defaults: {
    routing: recommendedDefaults.routing,
    roleFloors: recommendedDefaults.floors,
  },
});
```
```

--------------------------------

### get(ref)

Source: https://docs.rulvar.com/api/%40rulvar/rulvar/classes/FileTranscriptStore

Retrieves a blob from the store by its reference.

```APIDOC
## Method: get

### Description
Retrieves the content of a blob identified by the provided reference.

### Parameters
- **ref** (string) - Required - The reference identifier of the blob.

### Returns
- **Promise<Bytes | null>** - The blob content as Bytes, or null if not found.
```

--------------------------------

### Install eslint-plugin-rulvar

Source: https://docs.rulvar.com/api/eslint-plugin-rulvar

Add the plugin as a development dependency to your project.

```bash
pnpm add -D eslint-plugin-rulvar
```

--------------------------------

### GET /runs/:id/cost

Source: https://docs.rulvar.com/guide/cli

Retrieves the cost report for a run.

```APIDOC
## GET /runs/:id/cost

### Description
Returns the CostReport for a run, including per-phase and per-agent-type attribution if available.

### Method
GET

### Endpoint
/runs/:id/cost

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique run identifier
```

--------------------------------

### Get Current Time

Source: https://docs.rulvar.com/api/%40rulvar/rulvar/interfaces/Ctx

Returns the current timestamp as a number.

```typescript
now(): number;
```

--------------------------------

### buildPlanTools(runtime)

Source: https://docs.rulvar.com/api/%40rulvar/plan/functions/buildPlanTools

Builds the PlanRunner tools required for the system.

```APIDOC
## buildPlanTools(runtime)

### Description
Builds the PlanRunner tools that are appended to the mode (c) toolset.

### Signature
`function buildPlanTools(runtime: PlanToolRuntime): ToolDef<SchemaSpec<unknown>>[]`

### Parameters
- **runtime** (PlanToolRuntime) - Required - The runtime environment configuration for the plan tools.

### Returns
- **ToolDef<SchemaSpec<unknown>>[]** - An array of tool definitions.
```

--------------------------------

### GET /runs/:id/events

Source: https://docs.rulvar.com/guide/cli

Establishes an SSE event stream for a run.

```APIDOC
## GET /runs/:id/events

### Description
Provides an SSE event stream for the specified run. Supports reconnection via the Last-Event-ID header.

### Method
GET

### Endpoint
/runs/:id/events

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique run identifier
```

--------------------------------

### GET /runs/:id

Source: https://docs.rulvar.com/guide/cli

Retrieves the status and metadata of a specific run.

```APIDOC
## GET /runs/:id

### Description
Retrieves the status of a run. Reports live outcome for runs tracked in the current process or stored metadata for others.

### Method
GET

### Endpoint
/runs/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique run identifier
```

--------------------------------

### Get lineage

Source: https://docs.rulvar.com/api/%40rulvar/rulvar/classes/AdmissionController

Retrieves the lineage counter folds over the run journal.

```typescript
lineage(): 
  | LineageIndex
  | undefined;
```

--------------------------------

### new SqliteStore(options)

Source: https://docs.rulvar.com/api/%40rulvar/store-sqlite/classes/SqliteStore

Creates a new instance of the SqliteStore.

```APIDOC
## Constructor

### Description
Initializes a new SqliteStore instance with the provided configuration options.

### Signature
`new SqliteStore(options: SqliteStoreOptions): SqliteStore`
```

--------------------------------

### Get Plan View

Source: https://docs.rulvar.com/api/%40rulvar/plan/interfaces/PlanToolRuntime

Retrieves the rendered view of the current plan.

```ts
planView(): PlanViewRender;
```

--------------------------------

### Get Pin Count

Source: https://docs.rulvar.com/api/%40rulvar/plan/classes/PinLedger

Retrieves the current number of pinned worktrees.

```typescript
get count(): number;
```

--------------------------------

### Define boot method

Source: https://docs.rulvar.com/api/%40rulvar/core/interfaces/OrchestratorExtension

Executes before the orchestrator agent's first entry and during state reconstruction from the journal.

```typescript
optional boot(io): void | Promise<void>;
```

--------------------------------

### Initialize Engine and Define Workflow

Source: https://docs.rulvar.com/guide/architecture

Construct the engine with adapters and storage, then define a workflow using parallel agent execution.

```typescript
import { createEngine, defineWorkflow } from "@rulvar/core";
import { anthropic } from "@rulvar/anthropic";
import { openai } from "@rulvar/openai";
import { SqliteStore } from "@rulvar/store-sqlite";

const engine = createEngine({
  adapters: [anthropic(), openai()],
  stores: { journal: new SqliteStore({ path: ".rulvar/journal.db" }) },
  defaults: {
    routing: { summarize: "anthropic:claude-haiku-4-5" },
  },
});

const review = defineWorkflow({ name: "review-pr" }, async (ctx, args: { pr: number }) => {
  const [code, tests] = await ctx.parallel([
    () => ctx.agent(`Review the diff of PR ${args.pr}`),
    () => ctx.agent(`Assess the test coverage of PR ${args.pr}`),
  ]);
  return { code, tests };
});

const handle = engine.run(review, { pr: 42 }, { budgetUsd: 5 });
const outcome = await handle.result;
```

--------------------------------

### Get open suspensions

Source: https://docs.rulvar.com/api/%40rulvar/core/classes/ResolutionFold

Returns all currently open suspended entries.

```typescript
openSuspensions(): JournalEntry[];
```

--------------------------------

### Configure MCP Transports

Source: https://docs.rulvar.com/guide/mcp

Demonstrates how to initialize MCP servers using different transport mechanisms: stdio, streamable-http, and inprocess.

```typescript
import { mcp } from '@rulvar/core';

const filesystem = mcp({
  transport: 'stdio',
  command: 'mcp-server-filesystem',
  args: ['--root', './workspace'],
});

const search = mcp({
  transport: 'streamable-http',
  url: 'https://mcp.example.com/v1',
});

const embedded = mcp({
  transport: 'inprocess',
  server: myInMemoryServer, // an in-memory server instance
});
```

--------------------------------

### Initialize AdmissionController

Source: https://docs.rulvar.com/api/%40rulvar/core/classes/AdmissionController

Instantiate a new AdmissionController with the required budget and optional configuration parameters.

```typescript
new AdmissionController(options): AdmissionController;
```

--------------------------------

### new RunBudget(options)

Source: https://docs.rulvar.com/api/%40rulvar/core/classes/RunBudget

Initializes a new RunBudget instance with configuration for USD ceilings, event sinks, and initial seed data.

```APIDOC
## Constructor

### Description
Creates a new RunBudget instance. The budget tracks spend per instance and can be seeded from a ledger fold.

### Parameters
- **options** (object) - Required
  - **ceilingUsd** (number) - Optional: Immutable USD ceiling.
  - **events** (RuntimeEventSink) - Optional
  - **lifetimeSpawnCap** (number) - Optional
  - **priceUsd** (function) - Optional: (servedBy, usage) => number
  - **pricingOf** (function) - Optional: (servedBy) => Pricing
  - **seed** (object) - Optional: Resume ledger fold data.
    - **agentsSpawned** (number)
    - **usage** (Usage)
    - **usd** (number)
```

--------------------------------

### runKbPinReplay()

Source: https://docs.rulvar.com/api/%40rulvar/plan/functions/runKbPinReplay

Executes the pin at admission and the repin at the wake, with card bytes embedded and model names withheld.

```APIDOC
## runKbPinReplay()

### Description
Executes the pin at admission and the repin at the wake, with card bytes embedded and model names withheld.

### Signature
`function runKbPinReplay(): Promise<JournalEntry[]>`

### Returns
- **Promise<JournalEntry[]>** - A promise that resolves to an array of journal entries.
```

--------------------------------

### Example journal state

Source: https://docs.rulvar.com/guide/durability

A representation of the journal entries on disk during a workflow execution.

```text
seq  scope    kind   key      status   notes
0    (root)   step   3b7e...  running  fetch-diff dispatched
1    (root)   step   3b7e...  ok       terminal for seq 0; value: the diff
2    par:0:0  agent  8f2a...  running  correctness reviewer dispatched
3    par:0:1  agent  c41d...  running  security reviewer dispatched
4    par:0:0  agent  8f2a...  ok       terminal for seq 2; usage and servedBy recorded

     <- process dies here
```

--------------------------------

### openai(options?)

Source: https://docs.rulvar.com/api/%40rulvar/openai/functions/openai

Creates the first-class OpenAI adapter (id 'openai') with the specified options.

```APIDOC
## openai(options?)

### Description
Creates the first-class OpenAI adapter (id 'openai') with a default maxRetries of 0.

### Signature
`function openai(options?): ProviderAdapter;`

### Parameters
- **options** (OpenAiAdapterOptions) - Optional - Configuration options for the OpenAI adapter.

### Returns
- **ProviderAdapter** - An instance of the OpenAI provider adapter.
```

--------------------------------

### Get Pending Tasks

Source: https://docs.rulvar.com/api/%40rulvar/core/classes/Semaphore

Retrieve the current number of tasks waiting for a slot.

```typescript
get pending(): number;
```

--------------------------------

### Initialize SqliteStore

Source: https://docs.rulvar.com/guide/stores

Basic configuration for the SQLite store, including path and lease TTL settings.

```typescript
import { SqliteStore } from '@rulvar/store-sqlite';

const store = new SqliteStore({
  path: './rulvar.db', // or ':memory:' for an in-process store
  ttlMs: 60_000,       // lease ttl; 60000 ms is the default
});
```

--------------------------------

### Configure and execute a planned workflow

Source: https://docs.rulvar.com/guide/planner

Initialize the engine with Anthropic adapters and a sandbox runner, then use the planner to generate and execute a workflow.

```typescript
import { createEngine } from "@rulvar/core";
import { anthropic } from "@rulvar/anthropic";
import { WorkerSandboxRunner, plan, runPlanned } from "@rulvar/planner";

const engine = createEngine({
  adapters: [anthropic()],
  defaults: {
    routing: {
      plan: "anthropic:claude-opus-4-8",   // writes the script
      loop: "anthropic:claude-sonnet-5",   // runs the spawned agents
    },
    profiles: {
      researcher: { description: "Finds and cites primary sources." },
      writer: { description: "Turns research notes into prose." },
    },
  },
  runners: { sandbox: new WorkerSandboxRunner() },
});

const planned = await plan(engine, "Compare three storage engines and draft a recommendation", {
  run: { budgetUsd: 1 }, // the planning conversation's own immutable ceiling
});
console.log(planned.source); // the frozen script: read it before you pay for execution
console.log(planned.lint);   // advisories on the accepted draft; never errors

const handle = engine.run(planned.workflow, {}, { budgetUsd: 10 });
const outcome = await handle.result;

// Or compose plan-then-run in one call, with the two ceilings set
// independently: `plan.run` bounds the planning conversation, `run`
// bounds the generated workflow's execution.
const direct = await runPlanned(engine, "Compare three storage engines and draft a recommendation", null, {
  plan: { run: { budgetUsd: 1 } },
  run: { budgetUsd: 10 },
});

// The bare legacy forms still work and are UNBOUNDED: without options,
// neither the planning run nor the execution run has a dollar ceiling.
```

--------------------------------

### new AdmissionController(options)

Source: https://docs.rulvar.com/api/%40rulvar/core/classes/AdmissionController

Constructs a new AdmissionController instance with the specified budget, lineage, and spawn constraints.

```APIDOC
## Constructor

### Description
Creates a new instance of the AdmissionController.

### Signature
`new AdmissionController(options: AdmissionOptions)`

### Parameters
- **options** (Object) - Required
  - **budget** (RunBudget) - Required
  - **childBudgetFraction** (number) - Optional
  - **flatReserveUsd** (number) - Optional
  - **lineage** (Object) - Optional
    - **journalView** (Function) - Required
    - **limits** (Object) - Optional
  - **maxChildrenPerNode** (number) - Optional
  - **maxDepth** (number) - Optional
  - **maxTotalSpawns** (number) - Optional
  - **mintId** (Function) - Optional
```

--------------------------------

### run()

Source: https://docs.rulvar.com/api/%40rulvar/store-conformance/interfaces/ConformanceSuite

Executes all conformance checks sequentially. Throws an error upon the first violation encountered.

```APIDOC
## run()

### Description
Runs every check sequentially; throws on the first violation.

### Signature
`run(): Promise<void>;`

### Returns
- **Promise<void>** - A promise that resolves when all checks pass, or rejects if a violation occurs.
```

--------------------------------

### Iterate Events

Source: https://docs.rulvar.com/api/%40rulvar/core/classes/EventBus

Retrieve an asynchronous iterable of workflow events starting from the subscription point.

```typescript
iterate(): AsyncIterable<WorkflowEvent>;
```

--------------------------------

### Get suspension state

Source: https://docs.rulvar.com/api/%40rulvar/core/classes/ResolutionFold

Retrieves the suspension state for a given target sequence number.

```typescript
suspensionState(target): SuspensionState;
```

--------------------------------

### Initialize Engine with createEngine

Source: https://docs.rulvar.com/api/%40rulvar/core/functions/createEngine

Use this function to instantiate an engine with the required configuration options.

```typescript
function createEngine(options): Engine;
```

--------------------------------

### Get Lineage Index

Source: https://docs.rulvar.com/api/%40rulvar/core/classes/AdmissionController

Retrieves the lineage counter which folds over the run journal lazily.

```typescript
lineage(): LineageIndex | undefined;
```

--------------------------------

### run(wf, args, opts?)

Source: https://docs.rulvar.com/api/%40rulvar/testing/interfaces/TestEngine

Executes a workflow test run.

```APIDOC
## run(wf, args, opts?)

### Description
Initiates a new test run for the provided workflow with the specified arguments.

### Parameters
- **wf** (Workflow<A, R>) - Required - The workflow to execute.
- **args** (A) - Required - The arguments for the workflow.
- **opts** (RunOptions) - Optional - Execution options.

### Returns
- **TestRunHandle<R>**
```

--------------------------------

### Retrieve Wire ID

Source: https://docs.rulvar.com/api/%40rulvar/anthropic/classes/IdMap

Get the wire identifier corresponding to a given canonical identifier.

```typescript
wireFor(canonicalId): string;
```

--------------------------------

### Retrieve Canonical ID

Source: https://docs.rulvar.com/api/%40rulvar/anthropic/classes/IdMap

Get the canonical identifier corresponding to a given wire identifier.

```typescript
canonicalFor(wireId): string;
```

--------------------------------

### Initialize OpenAI Adapter

Source: https://docs.rulvar.com/api/%40rulvar/openai/functions/openai

Creates the first-class OpenAI adapter with the specified options.

```typescript
function openai(options?): ProviderAdapter;
```

--------------------------------

### Install Anthropic Provider

Source: https://docs.rulvar.com/guide/providers

Use this command to add the Anthropic provider package to your project dependencies.

```bash
pnpm add @rulvar/anthropic
```

--------------------------------

### run()

Source: https://docs.rulvar.com/api/%40rulvar/store-conformance/interfaces/ConformanceCheck

Executes the conformance check. This method returns a promise that resolves on success or rejects with a descriptive Error if a violation is detected.

```APIDOC
## run()

### Description
Executes the conformance check. This method returns a promise that resolves on success or rejects with a descriptive Error if a violation is detected.

### Signature
`run(): Promise<void>;`

### Returns
- **Promise<void>** - A promise that resolves when the check completes successfully.
```

--------------------------------

### orchestratorScope method

Source: https://docs.rulvar.com/api/%40rulvar/core/interfaces/OrchestratorExtensionIO

Retrieves the orchestrator's child scope; throws if called before the loop starts.

```typescript
orchestratorScope(): string;
```

--------------------------------

### execute<A, R>(wf, ctx, args)

Source: https://docs.rulvar.com/api/%40rulvar/planner/classes/WorkerSandboxRunner

Executes a compiled workflow within the sandbox.

```APIDOC
## Method: execute

### Description
Executes a provided CompiledWorkflow with the given context and arguments.

### Signature
`execute<A, R>(wf: CompiledWorkflow, ctx: Ctx<never>, args: A): Promise<R>`

### Parameters
- **wf** (CompiledWorkflow) - Required - The compiled workflow to execute.
- **ctx** (Ctx<never>) - Required - The execution context.
- **args** (A) - Required - The arguments for the workflow execution.

### Returns
- **Promise<R>** - A promise that resolves with the result of the workflow execution.
```

--------------------------------

### Execute a new workflow run

Source: https://docs.rulvar.com/api/%40rulvar/core/interfaces/Engine

Starts a new workflow execution with the provided arguments and options.

```typescript
run<A, R>(
   wf, 
   args, 
opts?): RunHandle<R>;
```

--------------------------------

### Initialize and execute a Rulvar workflow

Source: https://docs.rulvar.com/guide/durability

Configures the engine with stores and adapters, then executes a workflow using engine.run.

```typescript
import {
  createEngine,
  defineWorkflow,
  FileTranscriptStore,
  JsonlFileStore,
} from '@rulvar/core';
import { anthropic } from '@rulvar/anthropic';

const engine = createEngine({
  adapters: [anthropic()],
  stores: {
    journal: new JsonlFileStore({ dir: './runs' }),
    transcripts: new FileTranscriptStore({ dir: './runs' }),
  },
});

const review = defineWorkflow({ name: 'review' }, async (ctx, pr: number) => {
  const diff = await ctx.step('fetch-diff', () => fetchDiff(pr));
  const findings = await ctx.parallel([
    () => ctx.agent(`Review this diff for correctness:\n${diff}`, { agentType: 'reviewer' }),
    () => ctx.agent(`Review this diff for security:\n${diff}`, { agentType: 'reviewer' }),
  ]);
  return ctx.agent(`Merge these findings into one report:\n${findings.join('\n---\n')}`);
});

const handle = engine.run(review, 4242, { runId: 'review-pr-4242', budgetUsd: 10 });
await handle.result;
```

--------------------------------

### Start worker sweeping

Source: https://docs.rulvar.com/api/%40rulvar/cli/interfaces/Worker

Initiates the sweeping process on the configured poll cadence. This method is idempotent.

```typescript
start(): void;
```

--------------------------------

### runKbProposeQuarantine()

Source: https://docs.rulvar.com/api/%40rulvar/plan/functions/runKbProposeQuarantine

Executes the quarantine proposal process for the knowledge base.

```APIDOC
## runKbProposeQuarantine()

### Description
Executes a process to propose quarantine for knowledge base entries. Injected garbage in a proposal is treated as inert, and no commits are performed during the run.

### Signature
`function runKbProposeQuarantine(): Promise<JournalEntry[]>`

### Returns
- **Promise<JournalEntry[]>** - A promise that resolves to an array of JournalEntry objects.
```

--------------------------------

### Get Allowance Headroom

Source: https://docs.rulvar.com/api/%40rulvar/rulvar/classes/RunBudget

Calculates the minimum remainder across child-allowance accounts for a given scope.

```ts
allowanceHeadroomOf(scope): number | undefined;
```

--------------------------------

### new FakeAdapter(options)

Source: https://docs.rulvar.com/api/%40rulvar/testing/classes/FakeAdapter

Constructs a new instance of the FakeAdapter.

```APIDOC
## Constructor

### Description
Creates a new FakeAdapter instance to be used for testing engine interactions.

### Signature
`new FakeAdapter(options: FakeAdapterOptions): FakeAdapter`

### Parameters
- **options** (FakeAdapterOptions) - Required - Configuration options for the fake adapter.
```

--------------------------------

### Get invalid resolutions

Source: https://docs.rulvar.com/api/%40rulvar/core/classes/ResolutionFold

Returns a list of invalid offline resolutions found during the resume report.

```typescript
invalidResolutions(): {
  detail: string;
  seq: number;
}[];
```

--------------------------------

### Initialize PlanRunner engine

Source: https://docs.rulvar.com/guide/adaptive-orchestration

Configure the Rulvar engine with Anthropic and SQLite adapters, then execute an orchestration task using the PlanRunner extension.

```typescript
import { createEngine, orchestrate } from '@rulvar/core';
import { anthropic } from '@rulvar/anthropic';
import { SqliteStore } from '@rulvar/store-sqlite';
import { planRunner } from '@rulvar/plan';

const engine = createEngine({
  adapters: [anthropic()],
  stores: { journal: new SqliteStore({ path: './runs.db' }) },
  defaults: {
    routing: {
      orchestrate: 'anthropic:claude-opus-4-8',
      loop: 'anthropic:claude-sonnet-5',
    },
    profiles: {
      researcher: { description: 'Finds and cites primary sources.' },
      migrator: {
        description: 'Applies one codemod to one package.',
        escalation: { flavor: 'A' },
      },
    },
  },
});

const handle = orchestrate(engine, 'Migrate all 40 packages to the new config format', {
  budget: { capUsd: 2, finalizeTurns: 2 },
  extension: planRunner({
    maxRevisionsPerRun: 32,
    limits: { maxTotalSpawns: 64, maxDepth: 1 },
    guards: { fallback: 'finish-with-partial' },
  }),
});

const outcome = await handle.result;
```

--------------------------------

### Implement Lease Release

Source: https://docs.rulvar.com/guide/store-authors

Example of a release method implementation for a store, ensuring fencing is asserted before deletion.

```typescript
  async release(l: Lease): Promise<void> {
    this.assertFencing(l);
    this.leases.delete(l.runId);
  }
}
```

--------------------------------

### leasableStoreConformance(mk, options?)

Source: https://docs.rulvar.com/api/%40rulvar/store-conformance/functions/leasableStoreConformance

Generates a conformance suite for a LeasableStore. The function accepts a store factory and optional configuration parameters.

```APIDOC
## leasableStoreConformance(mk, options?)

### Description
Generates a ConformanceSuite for validating LeasableStore implementations.

### Signature
`function leasableStoreConformance(mk: StoreFactory<LeasableStore>, options?: { ttlMs?: number }): ConformanceSuite`

### Parameters
- **mk** (StoreFactory<LeasableStore>) - Required - The store factory instance.
- **options** (Object) - Optional - Configuration options.
  - **ttlMs** (number) - Optional - The store's configured lease TTL, which enables wall-clock expiry and renew-keeps-held checks.

### Returns
- **ConformanceSuite** - The resulting conformance suite object.
```

--------------------------------

### Configure OpenAI adapter

Source: https://docs.rulvar.com/guide/quickstart

Initializes the Rulvar engine with OpenAI adapters and file-based stores for journals and transcripts.

```typescript
import { createEngine, openai, JsonlFileStore, FileTranscriptStore } from '@rulvar/rulvar';

const engine = createEngine({
  adapters: [openai()], // reads OPENAI_API_KEY
  stores: {
    journal: new JsonlFileStore({ dir: '.rulvar/journal' }),
    transcripts: new FileTranscriptStore({ dir: '.rulvar/transcripts' }),
  },
  defaults: {
    routing: {
      loop: 'openai:gpt-5.4',
      // Schema-bearing ctx.agent calls resolve the extract role, so
      // any engine that serves them must route it.
      extract: { model: 'openai:gpt-5.4-mini', effort: 'low' },
    },
  },
});
```

--------------------------------

### Get Exhaustion Diagnostics

Source: https://docs.rulvar.com/api/%40rulvar/rulvar/classes/RunBudget

Retrieves diagnostic information identifying the account that caused a budget ceiling error.

```ts
exhaustionDiagnostics(scope): BudgetExhaustionDiagnostics;
```

--------------------------------

### buildAdapterRegistry(adapters)

Source: https://docs.rulvar.com/api/%40rulvar/rulvar/functions/buildAdapterRegistry

Creates a strictly per-engine adapter registry. Duplicate adapter IDs will result in a ConfigError.

```APIDOC
## buildAdapterRegistry(adapters)

### Description
Creates a per-engine adapter registry from an array of provider adapters. This registry is strictly per-engine and does not support global mutable state.

### Signature
`function buildAdapterRegistry(adapters: ProviderAdapter[]): ReadonlyMap<string, ProviderAdapter>`

### Parameters
- **adapters** (ProviderAdapter[]) - Required - An array of provider adapters to be registered.

### Returns
- **ReadonlyMap<string, ProviderAdapter>** - A read-only map containing the registered adapters keyed by their ID.
```

--------------------------------

### Get Lineage Statistics

Source: https://docs.rulvar.com/api/%40rulvar/core/classes/LineageIndex

Retrieves the LineageStats object for a logical task ID, optionally pinned to a sequence.

```typescript
statsOf(logicalTaskId, uptoSeq?): LineageStats;
```
Tokens:
Raw