Installation

rulvar is published on the npm registry as a set of scoped packages under @rulvar/* (Apache-2.0). All packages release in lockstep at the same version, currently 1.1.0; the single exception is @rulvar/compat, which is versioned independently so that frozen compatibility profiles never force a release of everything else.

One line install

pnpm add @rulvar/rulvar gives you everything most applications need: the engine, the Anthropic and OpenAI adapters, the JSONL file store, and the terminal progress renderer, behind one import path.

Requirements

• Node.js 22.12.0 or newer. Every package declares engines: { "node": ">=22.12.0" }. The floor is exactly 22.12.0 because it is the first 22.x release where require(esm) works without a flag, which the module format below relies on.
• ESM only. All packages ship "type": "module" with no CommonJS artifacts. ESM projects import them; CommonJS projects on Node 22.12 or newer can plain require() them and receive the same module instance. rulvar deliberately never dual publishes: two module instances of the engine would fork the per engine registries and break content addressed replay identity, so the hazard is removed by construction.
• TypeScript recommended. The API is typed end to end and every package ships rolled up .d.ts files; plain JavaScript works, but workflow signatures, tool schemas, and budget options lose their compile time checks. Types resolve through the exports map only (there is no legacy types field), so set moduleResolution to nodenext, node16, or bundler in your tsconfig.json.

Any of pnpm, npm, or yarn installs the published packages; the examples below use pnpm first.

The umbrella package

For applications, install the batteries included umbrella:

pnpm add @rulvar/rulvar

npm install @rulvar/rulvar

yarn add @rulvar/rulvar

One import path then covers the common surface:

Surface	What you get
Everything from @rulvar/core	createEngine, defineWorkflow, the journal kernel, the agent runtime, the model router, the tool system, the orchestrator, InMemoryStore and JsonlFileStore
anthropic(), ANTHROPIC_MODELS	The Anthropic adapter and its model catalog
openai(), OPENAI_MODELS	The OpenAI adapter and its model catalog
renderProgress()	Terminal progress renderer over a run's event stream
recommendedDefaults	Routing defaults and quality floors that pin orchestrate and plan work to strong models

recommendedDefaults is data, not engine semantics, and it lives here on purpose: @rulvar/core never names a concrete model. Drop it into createEngine and override freely; see Model routing.

One thing the umbrella deliberately does not pass through is the openaiCompatible factory. If you target an OpenAI compatible endpoint (Ollama, vLLM, a gateway), add @rulvar/openai as a direct dependency and import the factory from there; see Providers.

Picking individual packages

If you would rather not carry adapters you never construct, compose the pieces yourself. The minimum useful set is the core plus one adapter:

pnpm add @rulvar/core @rulvar/anthropic

This works because the dependency rules are strict: @rulvar/core has zero provider SDK dependencies, adapters import only core types and never each other, and every other package builds exclusively on the public API. Mixing and matching cannot pull in a provider SDK you did not ask for.

When you mix individual packages, keep every @rulvar/* dependency at the same version. They release in lockstep, and cross package contracts are only exercised at identical versions.

The full package list

Package	One line
@rulvar/rulvar	The umbrella: the full core API plus the Anthropic and OpenAI adapters, the file store, and the terminal progress renderer. The single install path.
@rulvar/core	The engine: journal kernel, ctx primitives, agent runtime, model router, tool system and MCP bus, dynamic orchestrator, InMemoryStore and JsonlFileStore, the event stream. Zero provider SDK dependencies.
@rulvar/anthropic	Anthropic adapter over @anthropic-ai/sdk: thinking block replay with signatures, cache hints, typed refusal outcomes, usage normalization.
@rulvar/openai	OpenAI adapter over the Responses API (reasoning items, strict JSON schema output) plus the openaiCompatible factory for Chat Completions style endpoints.
@rulvar/bridge-ai-sdk	Wraps any Vercel AI SDK LanguageModelV4 in a ProviderAdapter for the long tail of providers.
@rulvar/store-sqlite	SqliteStore: a journal store with worker leasing and fencing epochs on the node:sqlite driver built into Node. The reference for community stores.
@rulvar/store-conformance	Executable conformance kit for store authors: atomicity, ordering, fencing, and the decide once oracle, runnable under Vitest.
@rulvar/compat	Frozen key derivation profiles that let a current engine read journals written under retired hash versions. The one package outside lockstep.
@rulvar/plan	Plan and execute orchestration: the planRunner extension factory, the run ledger, escalation extensions, model ladder configuration.
@rulvar/planner	The flagship hybrid: a plan agent that writes workflow scripts, compileScript with an import allowlist, and the WorkerSandboxRunner.
@rulvar/testing	createTestEngine, FakeAdapter, VCR cassettes with secret redaction, replay strict runs, matchers for Vitest and Jest.
@rulvar/evals	Eval cases, golden outputs, rubric and judge graders through the engine, matrix sweeps, the canary fingerprint.
@rulvar/cli	The rulvar binary: run, resume, runs, inspect, plan, and kb commands, TUI progress, createServer and createWorker, the OpenTelemetry exporter.
eslint-plugin-rulvar	Determinism lint rules for workflow modules, with structured JSON diagnostics. Lockstep despite the unscoped name npm requires for ESLint plugins.

The Packages reference expands each line; Versioning explains the lockstep policy and the @rulvar/compat exemption.

Provider SDK dependencies

Installing an adapter package brings its provider SDK along as a regular dependency; there is nothing extra to install:

Adapter	Provider SDK it installs	Key source when apiKey is omitted
@rulvar/anthropic	@anthropic-ai/sdk	ANTHROPIC_API_KEY
@rulvar/openai	openai	OPENAI_API_KEY
@rulvar/bridge-ai-sdk	@ai-sdk/provider (interface types only)	Whatever the wrapped model uses

The bridge is the one case where you bring a package yourself: install the concrete AI SDK provider for your target (for example @ai-sdk/google) and hand its model object to the bridge. See Providers.

Both adapter factories accept apiKey and baseURL options and disable the SDK's internal retries: the engine owns retries, budgets, and wall clock.

Two smaller dependency notes:

• @rulvar/store-sqlite has no native driver dependency. It uses the node:sqlite module that ships with Node, so installs never compile anything.
• @rulvar/cli declares @opentelemetry/api as an optional peer. Install it only if you use the OpenTelemetry exporter; every other command works without it.

The unscoped npm name

Only a pointer

The bare npm name rulvar is a pointer package: it does nothing but depend on @rulvar/rulvar and pass its exports through, and it exists so nobody can squat the name. Do not depend on it. Install commands and package.json dependencies must always use the scoped form @rulvar/<name>; the scoped packages are the real releases, and everything in this documentation refers to them.

Verifying the install

Create verify.mjs next to your package.json:

// 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);

node verify.mjs

engine ready: true
journal hash version: 2

No API key is required: constructing an engine performs no network calls, and an empty adapter list is valid right up until you route a model call.

Default store

An engine created without stores.journal runs on InMemoryStore: runs work, but resume is disabled and the engine warns loudly. Configure JsonlFileStore or @rulvar/store-sqlite before you rely on durability; see Stores.

From here, the Quickstart takes you from this empty engine to a budgeted multi agent run in a few dozen lines.

From source

For contributors to rulvar itself:

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

The workspace pins its pnpm version through the packageManager field, which corepack enable picks up automatically; development targets Node 24 while CI tests the Node 22 floor. See the Contributing guide for the full workflow.