Rulvar API reference / @rulvar/planner
@rulvar/planner
The flagship Rulvar hybrid mode: a planner model writes a workflow script against the sanctioned ctx dialect; the package lints and repairs it from structured diagnostics, compiles it with an import allowlist, and executes it deterministically in the worker sandbox with seeded, journaled globals. Exports plan, runPlanned, compileScript, WorkerSandboxRunner, and apiCard.
The one-line mnemonic against its sibling: @rulvar/planner plans before the run (it writes the script); @rulvar/plan replans during the run (it revises the task plan).
Part of Rulvar, an embeddable TypeScript engine for durable, budget-bounded multi-agent LLM workflows, where a completed LLM call is never paid for twice. Full documentation: docs.rulvar.com.
Install
bash
pnpm add @rulvar/core @rulvar/plannerDocumentation
License
Classes
| Class | Description |
|---|---|
| WorkerSandboxRunner | Accepts CompiledWorkflow ONLY: feeding a closure is a type error. |
Interfaces
| Interface | Description |
|---|---|
| CompileScriptOptions | @rulvar/planner: Rulvar flagship hybrid mode: plan agent, compileScript, WorkerSandboxRunner, self-repair loop (https://docs.rulvar.com/guide/planner). The surface lands across M6. |
| M6CassetteFixture | The cassette file shape shared with the M3 sets. |
| PlanDiagnostic | One repair-loop diagnostic: lint and compile findings share the shape. |
| PlanOptions | - |
| PlanResult | - |
| RunPlannedOptions | - |
| ScriptDiagnostic | One machine-readable compileScript diagnostic (carried by ScriptRejected). |
| WorkerSandboxRunnerOptions | - |
Variables
| Variable | Description |
|---|---|
| DEFAULT_SANDBOX_MEMORY_MB | - |
| DEFAULT_SANDBOX_TIMEOUT_MS | - |
| SANDBOX_DETERMINISM_RUN_ID | - |
| SANDBOX_DETERMINISM_SOURCE | A script exercising agents, parallel, step, and every seeded shim. |
| SANDBOX_GLOBALS | The exact curated sandbox global set, in canonical order. The worker binds the ctx methods as bare globals under these names and the API card teaches exactly this list. |
| SELF_REPAIR_BAD_DRAFT | The failing first draft: bare Date.now trips rulvar/no-bare-date. |
| SELF_REPAIR_GOAL | - |
| SELF_REPAIR_GOOD_DRAFT | The repaired draft the fake planner returns once diagnostics arrive. |
| SELF_REPAIR_RUN_ID | - |
Functions
| Function | Description |
|---|---|
| apiCard | Renders the sandbox-dialect API card; pure and byte-stable. |
| compileScript | @rulvar/planner: Rulvar flagship hybrid mode: plan agent, compileScript, WorkerSandboxRunner, self-repair loop (https://docs.rulvar.com/guide/planner). The surface lands across M6. |
| extractScript | The model may fence the script; the extractor takes the first fenced block when one exists, else the whole reply, and is deterministic. |
| lintScript | Lints a script BODY with the workflows preset plus compileScript. The body is wrapped in an async function for parsing (top-level return/await are legal in the dialect); reported lines shift back so they index into the body source. |
| normalizeCassetteEntries | The M3-convention cassette normalization: wall clock and spans only. |
| plan | - |
| planRunIdOf | The deterministic planner runId: one goal, one journal. |
| runPlanned | plan-then-run in one call (amended during M6-T05: the composition is async because planning itself is a run). options.plan bounds the planning conversation, options.run bounds the generated workflow's execution; the two ceilings are independent, and the bare form without options runs BOTH legs unbounded, as before. |
| runPlannerSelfRepair | One planner-self-repair run: the first draft fails lint, the JSON diagnostics ride the repair prompt, the second draft compiles. Returns the normalized planning journal plus the plan result. |
| runSandboxDeterminism | One fresh sandbox-determinism run on a fresh store; two invocations with the same worker produce byte-identical normalized journals (the cassette assertion). The adapter factory keeps @rulvar/testing out of the planner's dependency graph. |
| scriptDiagnosticsOf | @rulvar/planner: Rulvar flagship hybrid mode: plan agent, compileScript, WorkerSandboxRunner, self-repair loop (https://docs.rulvar.com/guide/planner). The surface lands across M6. |