Rulvar API reference / @rulvar/rulvar / AgentResult
Interface: AgentResult<T>
Defined in: packages/core/dist/index.d.ts
Type Parameters
| Type Parameter |
|---|
T |
Properties
| Property | Type | Description | Defined in |
|---|---|---|---|
abortClass? | AbortClass | The dedicated first-class abort class (M3-T08): present on the engine-decided no-progress abort (status 'limit'), never on user cancellation or ordinary cap hits. | packages/core/dist/index.d.ts |
artifacts? | Artifact[] | - | packages/core/dist/index.d.ts |
costBasis | CostBasis | The fold behind costUsd (RV702): 'per-call' when every usage slice (restored included) is covered by per-request records priced individually, exactly the settled fold's basis; 'aggregate-estimate' when a restored checkpoint left usage no record backs, in which case the aggregate-priced number is kept (never silently dropped) and labeled. | packages/core/dist/index.d.ts |
costUsd | number | - | packages/core/dist/index.d.ts |
error? | AgentError | - | packages/core/dist/index.d.ts |
errorMessage? | string | Human-readable detail behind error (provider message, first schema issue): feeds the journaled WireError message. An additive field; never part of identity. | packages/core/dist/index.d.ts |
escalation? | EscalationReport | Present if and only if status === 'escalated'. | packages/core/dist/index.d.ts |
escalationRequest? | EscalationRequest | Engine-internal: the accepted escalate request before the runtime fills costToDate and salvage into the full report. The ctx layer consumes and removes it; consumers read escalation. | packages/core/dist/index.d.ts |
evidence? | { met: boolean; minEntries: number; recordedEntries: number; } | The evidence verdict under a DECLARED evidence contract (RV806): the window-derived count of successful record_evidence executions (the same counting rule as the enforce-refuse floor), the declared floor, and whether the count met it, stamped on EVERY terminal status so the orchestrator's acceptance summary can report each child's evidence as met, unmet, or waived by salvage. Absent without a declared contract: those results stay byte-identical. Live-window derived like partial: a checkpointless restore that lost the window reports what the restored window shows. | packages/core/dist/index.d.ts |
evidence.met | boolean | - | packages/core/dist/index.d.ts |
evidence.minEntries | number | - | packages/core/dist/index.d.ts |
evidence.recordedEntries | number | - | packages/core/dist/index.d.ts |
evidenceEntries? | { citation?: string; claim: string; }[] | The recorded evidence entry CONTENT (the RV1501 entries plumbing): each successful record_evidence execution's claim plus its file or file:lines citation, in record order, bounded at collection (40 entries, 400 chars per claim). Present whenever the window carries at least one successful execution, contract or not; the ctx layer journals it on the terminal and replay restores it, so the orchestrator's claim pools pair the draft against what the child actually recorded on live and resumed runs alike. | packages/core/dist/index.d.ts |
evidenceFloor? | { minEntries: number; recordedEntries: number; } | The evidence floor refusal detail (RV507): present ONLY when an enforced contract refused an otherwise-ok settle. The ctx layer folds it into the journaled terminal error data and memoizes the outcome (the refusal is deterministic from the paid transcript, so a rerun would only re-pay the same bounded failure). | packages/core/dist/index.d.ts |
evidenceFloor.minEntries | number | - | packages/core/dist/index.d.ts |
evidenceFloor.recordedEntries | number | - | packages/core/dist/index.d.ts |
exploration? | ExplorationSummary | The exploration guard counters (RV-210): present whenever any of the exploration limits (toolBudgetNotices, maxRepeatedToolSignature, maxNoNewEvidenceCalls) was configured. Journaled inside the terminal error payload (and restored on replay) only for the guard's own abort (abortClass 'exploration'); otherwise live telemetry like transportRetries. | packages/core/dist/index.d.ts |
output | T | null | - | packages/core/dist/index.d.ts |
partial? | ProgressReport | The structured terminal partial (RV-210 close-out): the LAST successful report_progress call of the invocation, present only on a 'limit' terminal (cap expiry or an engine-decided abort) whose transcript recorded at least one report. Derived deterministically from the message window: live from the loop's own history (a final boundary checkpoint is written so the window is durable), on replay from the terminal checkpoint, so both read the same bytes. This is what lets a caller salvage a limit child's collected work instead of seeing a bare 'terminal status limit'. | packages/core/dist/index.d.ts |
providerCalls? | ProviderCallRecord[] | The per-dispatch reconciliation ledger (P1.3): one record per live provider call this invocation made, failed and retried attempts included, each with its own usage and the provider's response id when the adapter surfaced one. Journaled on the terminal entry and restored verbatim on replay, so a live result and its replayed one read the same ledger; invoiceFromJournal folds the same records into the invoice export. Absent when the invocation made no wire call (a fully replayed invocation). | packages/core/dist/index.d.ts |
quotaDenials? | { recovered: number; requests: number; tokens: number; total: number; } | Pre-wire quota-limiter denials, split by dimension, with the recovered count (RV1510). A denial never reached the provider and never billed; conflating it with transportRetries misread the seventeenth comparison benchmark's telemetry. Live telemetry only, exactly like transportRetries: never journaled, absent on a replayed result, absent means "zero or unknown". | packages/core/dist/index.d.ts |
quotaDenials.recovered | number | - | packages/core/dist/index.d.ts |
quotaDenials.requests | number | - | packages/core/dist/index.d.ts |
quotaDenials.tokens | number | - | packages/core/dist/index.d.ts |
quotaDenials.total | number | - | packages/core/dist/index.d.ts |
rateLimitObservations? | RateLimitObservation[] | Provider-reported rate limits observed on this invocation's 429s (the v1.71 experiment review, P0.5): one entry per (provider, model), the latest observation winning, parsed by the adapters into WireError.data.reportedLimits. Live telemetry only, exactly like transportRetries: never journaled, absent on a replayed result; the ctx layer holds it against quota.declaredRules and journals the drift verdicts, which ARE durable. | packages/core/dist/index.d.ts |
schemaRecoveredTerminalExchanges? | number | Terminal-tool exchanges whose near-JSON ARGUMENTS the unparsed second chance (v1.75.1) RECOVERED into a schema-valid call (the sixth comparison experiment; the judge's P1.5): the recovery used to leave only a warn log behind, invisible on the outcome. A live process counter like transportRetries (pure telemetry: nothing downstream feeds on it), so a resumed segment counts only its own recoveries; absent when zero. | packages/core/dist/index.d.ts |
schemaRejectedTerminalExchanges? | number | Terminal-tool exchanges whose ARGUMENTS died at the schema gate (the unparsed second chance included, when it did not recover): the v1.74 experiment lost six finish payloads to exactly this class, and nothing outside the transcript said so (host validation rejections, by contrast, journal decision entries). Derived from the message window like the repair-reserve grants, so live and resumed segments count the same total; absent when zero. | packages/core/dist/index.d.ts |
servedBy | `${string}:${string}` | The model that actually served the loop phase at the end (M4-T04): differs from the requested spec only under transport failover. | packages/core/dist/index.d.ts |
status | AgentStatus | - | packages/core/dist/index.d.ts |
toolBudget? | ToolBudgetSummary | The tool budget pressure snapshot (RV304): present live whenever maxToolCalls, toolUnits, or toolBudgetExtension is configured. Live telemetry only, exactly like transportRetries: never journaled, absent on a replayed result. | packages/core/dist/index.d.ts |
transcriptRef | string | - | packages/core/dist/index.d.ts |
transportRetries? | number | Transport retries across the span's phase activations, present only when greater than zero. Counts retries of DISPATCHED attempts only (RV1601): a pre-wire quota denial never increments it, so this number can be read against the provider ledger without correction (the eighteenth comparison benchmark exported 21 denials under this name over an invoice with zero provider error rows). Live telemetry only: the ctx layer surfaces it as agent:end retryCount; it is never journaled, so a replayed result omits it (absent means "zero or unknown"). | packages/core/dist/index.d.ts |
turns | number | - | packages/core/dist/index.d.ts |
usage | Usage | - | packages/core/dist/index.d.ts |
usageByModel? | UsageSlice[] | Present only when the call spanned MORE THAN ONE (invocation role, serving model) pair (the loop, extract, finalize, and summarize roles resolve independently): usage split per (role, model), so costUsd and every cost bucket price each slice at its own rate and CostReport.byRole attributes each phase to its own bucket (v1.19.0 review P1-2). Absent for a single-phase single-model call, which (usage, servedBy) already describes exactly. | packages/core/dist/index.d.ts |