API reference

Scope: the export surface. How to use it is Build on moose-tracevals. Source of truth: src/index.ts.

import { runEvals, parseTraceFile, registerGrader } from "moose-tracevals";

ESM-only, Node.js 24+, types shipped. ★ marks an intended entry point. The rest is exported because the CLI is built from it and it is useful for tests. The starred ones are where to start.

Subpath exports

Specifier	What it is
`moose-tracevals`	The API below.
`moose-tracevals/schemas/artifact-evals-1.0.0-proposal.1.json`	The current evals-block schema.

Engine

Export	Notes
★ `runEvals(options)`	Runs the whole pipeline, returns `RunReport`. Needs a `judge` unless `deterministicOnly`.
`EngineOptions`	`tracePath`, `projectDir?`, `env?`, `config`, `judge?`, `deterministicOnly?`.

Commands

The CLI’s four commands, callable directly. Each pairs a runner with a renderer.

Export	Notes
`runRun`, `RunCommandOptions`, `RunCommandResult`	`run`, one trace. `RunCommandOptions.judge` injects a judge.
`prepareRun`, `runOne`, `RunContext`, `RunSharedOptions`	The seams a batch reuses. Build the judge, config, and plugins once, then evaluate one trace.
`runBatch`, `resolveBatchTraces`, `parseSince`, `BatchCommandOptions`, `BatchCommandResult`	`run` over many traces. `BatchCommandResult.outcomes` pairs each file with its report, errors included.
`runCalibrate`, `CalibrateCommandOptions`, `CalibrateCommandResult`	`calibrate`. Accepts the same judge injection through `RunSharedOptions`.
`runFill`, `renderFill`, `FillOptions`, `FillReport`, `FillArtifactResult`, `FillRun`, `FillStatus`, `SharpeningNote`	`fill`. `FillOptions.providerInstance` injects a provider.
`runList`, `renderList`, `ListOptions`, `ListRun`	`list`.

Traces

Export	Notes
★ `parseTraceFile(path)`	Detect the format and parse, returning `Trace`.
`parseTraceContent(text)`	The same from a string.
`detectFormat(path)`, `detectContentFormat(text)`	Format sniffing on its own.
★ `discoverTraces(options)`	Scan the session store. Returns `TraceListing[]`, newest first.
`homeDir(env?)`	Resolves `MOOSE_TRACEVALS_HOME`, falling back to the OS home.
`slugFor(cwd)`	The project-slug rule: every non-alphanumeric character to `-`.
`pickTrace(options, promptFn?)`	The interactive picker. `promptFn` makes it testable.
`DiscoverOptions`, `TraceListing`, `PickerChoice`, `PromptFn`
`availableAt(entries, index)`	Filter an availability list to the entries offered at that ordinal.
`offeredNames(entries)`	Every distinct name that was offered at any point.
`joinDescriptions(content, names)`	Parse a listing’s `- name: description` lines onto its names. Handles `plugin:skill` and wrapped descriptions.
`newAvailability()`	An empty roster, for a synthetic `Trace`.
(all of `trace/types`)	`Trace`, `TraceSource`, `TraceFormat`, `FileAccess`, `TraceUsage`, the event types, and `TraceAvailability` / `AvailabilityEntry`.

Artifacts

Export	Notes
★ `resolveArtifacts(trace, options)`	Trace-driven resolution. Returns artifacts, coverage, warnings.
`discoverArtifacts(options)`	Static, project-only scan. What `fill` uses.
`PROJECT_RULES_FILENAMES`	`["CLAUDE.md", "AGENTS.md", "GEMINI.md"]`.
`coverAvailability(trace, coverage, options)`	Classify coverage rows as offered-and-used, offered-not-used, or not-offered, and count the roster.
`ResolveOptions`, `DiscoverArtifactsOptions`, `DiscoveredArtifact`, `DiscoveryResult`, `AvailabilityCoverage`, `AvailabilityOptions`
`findGitRoot`, `findInTree`, `listInTree`, `safeRead`, `safeMtime`, `PRUNED_DIRS`	Filesystem helpers the resolvers share. All degrade to `null`/empty rather than throwing.
(all of `artifacts/types`)	`ResolvedArtifact`, `CoverageEntry`, `ArtifactType`, `ResolvedArtifacts`, `ArtifactAvailability`, `AvailabilityReport`, `AvailabilityCounts`.

Evals

Export	Notes
`extractCriteria(artifact)`	Read and validate a `metadata.evals` block.
`appendArtifactCriteria(...)`	Append evals to frontmatter. The one write path.
`ARTIFACT_EVALS_SCHEMA_ID`, `artifactEvalsSchemaPath`	The published schema’s `$id` and on-disk path.
`Eval`, `CriterionType`, `ExtractedCriteria`, `Severity`, `NewCriterion`

Planning and graders

Export	Notes
`planEvals(artifacts)`	Turn artifacts into `EvalPlan[]`.
`IMPLICIT_EVAL_NAME`	`"adheres-to-artifact"`.
★ `registerGrader(grader)`	Add a kind at runtime. See Custom graders.
`graderFor(kind)`, `listGraderKinds()`
`BUILTIN_GRADER_KINDS`	The kinds this package ships, frozen before anything can register over them.
`loadGraderPlugins({ plugins, configDir })`	Import grader plugins the way `run` and `fill` do, with the same resolution and the same warnings. Throws `TracevalsError` on a specifier that will not load.
`GraderPluginApi`, `GraderPluginRegister`, `LoadGraderPluginsOptions`, `LoadedGraderPlugins`
`EvalPlan`
(all of `graders/types`)	`TraceGrader`, `GradeResult`, `Finding`, `TraceGraderContext`.
`windowFor(trace, plan)`	The slice of the trace that plan’s artifact governed. A custom grader that counts events should read this rather than the trace.
`skippedWindow(window)`	The `GradeResult` for an empty window: a skip carrying its reason, never a pass.
`TraceWindow`
`validateWhen(options)`, `evaluateWhen(options, window)`	The conditional trigger contract, shared so a custom grader implements it identically.
`matchesGlob(path, glob)`, `globToRegExp(glob)`	The path glob `when.file-access` uses.
`WHEN_CONDITIONS`, `WhenCondition`, `TriggerResult`

Judge

Export	Notes
`makeTraceJudge(options)`	Build the ensemble judge.
`makeJudgeProvider(...)`, `providerSpecFor(...)`	Provider construction. `providerSpecFor` resolves identity without constructing, so a fully cached run needs no API key.
`renderTrace(trace, options?, plan?)`	The transcript as the judge sees it, redacted. With a `plan`, only that artifact’s window.
`makeRedactor(extra?)`	The scrubber `renderTrace` applies. Built-in shapes plus any extra sources, which add to them.
`REDACTION_PATTERNS`, `CUSTOM_PLACEHOLDER`	The built-in shapes with their labels, and the placeholder a configured pattern produces.
`compileRedactPatterns(sources)`	Compile-check pattern sources up front; throws `TracevalsError` on one that will not compile.
`RedactionPattern`, `Redactor`
`JUDGE_SYSTEM_PROMPT`, `buildUserContent(plan, rendered)`	The prompts.
`PROMPT_VERSION`	Cache-key component. Bump on any prompt change.
`cacheKey(...)`, `sha256(...)`
`TraceJudge`, `JudgedEval`, `TraceJudgeOptions`, `RenderOptions`, `MockResponse`

Configuration

Export	Notes
★ `loadConfig(dir?)`	Read `moose.config.yaml` from `dir`, take its `tracevals` section, validate, and fully populate defaults.
`parseConfig(raw)`	The same from an object. `raw` is the section, not the whole file. Pass what sits under `tracevals:`.
`DEFAULT_CONFIG_FILENAME`	`"moose.config.yaml"`, the config file shared by the moose family.
`CONFIG_SECTION_KEY`	`"tracevals"`, the top-level key in that file holding this tool’s settings.
`TracevalsConfig`, `ProviderConfig`, `Pricing`

Downstream code always receives a fully-populated config, so there is no need to re-apply defaults.

Reporting and history

Export	Notes
★ `render(report, format)`	`"human"`, `"json"`, or `"markdown"`.
`renderBatch(report, format)`, `renderBatchHuman`, `renderBatchMarkdown`	The aggregate shape.
`renderCalibration(report, format)`, `renderCalibrationHuman`, `renderCalibrationMarkdown`	The calibration shape.
`aggregate(outcomes, options)`, `BatchOutcome`	Fold per-trace reports into rates. Pure.
`ReportFormat`
`appendHistory(file, report)`, `loadHistory(file)`, `compareToLast(...)`, `entryFor(report)`
`HistoryEntry`, `HistoryEval`, `HistoryComparison`
(all of `types`)	`TracevalsError`, `RunReport`, `EvalResult`, `RunSummary`, `Outcome`, `BatchReport`, `AggregateRow`, `BatchTraceEntry`, `BatchSummary`.
(all of `calibrate/types`)	`CalibrationReport`, `CalibrationCounts`, `Disagreement`, `SweepCell`, `CalibrationGate`, `JudgeSetting`, `JoinKind`, `EvalLabel`, `LabelOutcome`.
`loadLabels`, `parseLabels`, `labelKey`, `DEFAULT_LABELS_FILE`	The labels sidecar. `parseLabels(text, file)` resolves trace paths against `file`’s directory.
`joinLabels`, `score`, `rescore`, `classify`	Pure calibration arithmetic. `rescore` re-applies zones and ensemble depth to a result’s cached runs, with no provider involved.

TracevalsError is the operational-failure type. The CLI maps it to exit 2; catch it if you want to distinguish “the tool could not run” from “a check failed”.

`fill` internals

Exported so the authoring path is testable and extensible. Most consumers will not need these.

Export	Notes
`gateProposals(...)`, `GateOptions`, `GateResult`	The gate, in order.
`ALLOWED_GRADERS`	Per-artifact-type grader allowlist.
`ProposedCriterion`, `Rejection`, `RejectionReason`, `Vocabulary`
`PROPOSAL_SCHEMA`, `isValidProposal(...)`	The shape a proposal must match.
`systemPromptFor(type)`, `buildFillUser(...)`
`FILL_PROMPT_VERSION`, `MAX_BODY_CHARS`	Cache-key components.
`FillCache`, `fillCacheKey`, `FillCacheKeyParts`	Separate from the judge cache.
`artifactFacts(...)`, `ArtifactFacts`	Grounding inputs, not evals.
`buildVocabulary(...)`, `BUILTIN_TOOLS`
`mockFillProposal`	The canned proposal `--provider mock` returns.