rulvar API reference / @rulvar/core / RunAgentOptions
Interface: RunAgentOptions<S>
Defined in: packages/core/src/runtime/agent-loop.ts:213
Type Parameters
| Type Parameter | Default type |
|---|---|
S extends SchemaSpec | JsonSchema |
Properties
| Property | Type | Description | Defined in |
|---|---|---|---|
adapter | ProviderAdapter | - | packages/core/src/runtime/agent-loop.ts:218 |
agentType? | string | - | packages/core/src/runtime/agent-loop.ts:311 |
budget? | BudgetHooks | - | packages/core/src/runtime/agent-loop.ts:289 |
canonicalSchema? | JsonSchema | Canonicalized JSON Schema projection of schema (precomputed for identity). | packages/core/src/runtime/agent-loop.ts:217 |
checkpoint? | { load: Promise< | CheckpointState | undefined>; save: Promise<void>; } | Turn-boundary checkpointing (M3-T02). load() restores the last boundary on a dangling-dispatch resume; save() persists each boundary where the loop continues. The separate extract invocation is not checkpointed in v1: an extract-phase crash re-pays from the last loop boundary. | packages/core/src/runtime/agent-loop.ts:280 |
checkpoint.load | Promise< | CheckpointState | undefined> | - | packages/core/src/runtime/agent-loop.ts:281 |
checkpoint.save | Promise<void> | - | packages/core/src/runtime/agent-loop.ts:282 |
compaction? | { threshold?: number; } | Per-profile compaction config; threshold default 0.8 (Appendix A). | packages/core/src/runtime/agent-loop.ts:272 |
compaction.threshold? | number | - | packages/core/src/runtime/agent-loop.ts:272 |
escalation? | { minSpendUsd: number; } | Escalation opt-in (M3-T07): the loop intercepts accepted calls to the escalate tool and terminates with status 'escalated'; the in-run minSpend gate rejects early scope_bigger escalations with a "keep working" error tool result (M3-T09). | packages/core/src/runtime/agent-loop.ts:303 |
escalation.minSpendUsd | number | - | packages/core/src/runtime/agent-loop.ts:303 |
events? | RuntimeEventSink | - | packages/core/src/runtime/agent-loop.ts:290 |
extract? | PhaseTarget & { fallbacks?: PhaseTarget[]; } | Separate final extract invocation, present only when the role trigger protocol demands one: schema set AND (routing directs extract to a different model OR the loop model's caps cannot serve the required tier OR finalize is routed). Otherwise the schema rides the last loop turn (the necessity rule is decided by the ctx layer via model/roles.ts). | packages/core/src/runtime/agent-loop.ts:252 |
fallbacks? | PhaseTarget[] | Transport failover chain for the loop phase (M4-T04): resolved fallback targets tried in order on transport or rate-limit failures after retries exhaust. Failover is sticky and changes only servedBy, never the content key. | packages/core/src/runtime/agent-loop.ts:226 |
finalize? | PhaseTarget & { fallbacks?: PhaseTarget[]; } | Finalize synthesis invocation (M4-T01), present only when the role trigger protocol fires it: configured in routing AND the toolset is non-empty. Runs after tools stop with toolChoice 'none' over the full transcript; its text becomes the output for schema-less calls, and a schema-bearing call always pairs it with a separate extract (the ctx layer guarantees extract is present in that case). Like extract, the finalize invocation is not checkpointed in v1. | packages/core/src/runtime/agent-loop.ts:262 |
label? | string | - | packages/core/src/runtime/agent-loop.ts:314 |
limits | EffectiveUsageLimits | - | packages/core/src/runtime/agent-loop.ts:284 |
modelRetryAttempts? | number | Bounded ModelRetry conversions per tool call chain; default 2 (Appendix A). | packages/core/src/runtime/agent-loop.ts:296 |
now? | () => number | - | packages/core/src/runtime/agent-loop.ts:315 |
priceUsd? | (servedBy, usage) => number | undefined | - | packages/core/src/runtime/agent-loop.ts:292 |
prompt | string | - | packages/core/src/runtime/agent-loop.ts:214 |
providerSlot? | <T>(key, fn) => Promise<T> | Per-provider keyed limiter hook (M4-T07): wraps every wire dispatch under the serving adapter's key; absent = unlimited (Appendix A). | packages/core/src/runtime/agent-loop.ts:241 |
resolved | ResolvedInvocation | - | packages/core/src/runtime/agent-loop.ts:219 |
retry? | { policy?: RetryPolicy; random?: () => number; sleep?: (ms) => Promise<void>; } | Transport RetryPolicy (M4-T05): lives UNDER the journal, wired around every adapter.stream dispatch. sleep and random are injectable for tests; the core owns wall-clock. | packages/core/src/runtime/agent-loop.ts:232 |
retry.policy? | RetryPolicy | - | packages/core/src/runtime/agent-loop.ts:233 |
retry.random? | () => number | - | packages/core/src/runtime/agent-loop.ts:235 |
retry.sleep? | (ms) => Promise<void> | - | packages/core/src/runtime/agent-loop.ts:234 |
role? | "orchestrate" | "plan" | "loop" | The primary invocation role of the tool loop; default 'loop' (M6-T05). | packages/core/src/runtime/agent-loop.ts:313 |
schema? | S | - | packages/core/src/runtime/agent-loop.ts:215 |
schemaRetryAttempts? | number | Bounded schema re-prompt attempts; default 2 (Appendix A). | packages/core/src/runtime/agent-loop.ts:294 |
signal? | AbortSignal | Host or sibling cancellation. | packages/core/src/runtime/agent-loop.ts:288 |
stream? | boolean | Emits agent:stream deltas when true (telemetry only). | packages/core/src/runtime/agent-loop.ts:286 |
summarize? | PhaseTarget & { fallbacks?: PhaseTarget[]; } | Summarize invocation target for compaction (M4-T03): resolved through the chain with role 'summarize', falling back to the loop model when routing resolves nothing. Compaction is ON by default; absence of this option disables it (direct runAgent callers). | packages/core/src/runtime/agent-loop.ts:270 |
terminalTool? | { name: string; } | Terminal-tool interception (M6-T07): an accepted call to the named tool ends the loop with status ok; the call's validated result argument becomes the agent output (the orchestrator finish tool). The tool's execute never runs, mirroring escalate. | packages/core/src/runtime/agent-loop.ts:310 |
terminalTool.name | string | - | packages/core/src/runtime/agent-loop.ts:310 |
tools? | ToolRuntime | The resolved toolset; absent = no tools declared. | packages/core/src/runtime/agent-loop.ts:243 |
transcript? | { mintRef: string; put: Promise<void>; } | - | packages/core/src/runtime/agent-loop.ts:291 |
transcript.mintRef | string | - | packages/core/src/runtime/agent-loop.ts:291 |
transcript.put | Promise<void> | - | packages/core/src/runtime/agent-loop.ts:291 |