@rulvar/core 1.85.0 → 1.86.0

package/dist/index.d.ts

@@ -3547,6 +3547,42 @@ interface ExplorationSummary {
   toolUnitsUsed?: number;
 }
 /**
+* The tool budget pressure snapshot (RV304, the seventh comparison
+* experiment): how close one agent invocation came to its tool budget,
+* visible BEFORE the terminal 'limit' a starved worker would settle
+* with. Attached to the full AgentResult and to the live `agent:end`
+* event whenever maxToolCalls, toolUnits, or toolBudgetExtension is
+* configured. Live telemetry only, exactly like transportRetries: never
+* journaled, absent on a replayed result.
+*/
+interface ToolBudgetSummary {
+  /** Executed tool calls (the loop's own counter). */
+  used: number;
+  /**
+  * The effective executed-call cap at the end: maxToolCalls plus every
+  * granted extension. Absent when only toolUnits bounds the loop.
+  */
+  cap?: number;
+  /** Weighted units spent; present when toolUnits is configured. */
+  unitsUsed?: number;
+  /** The weighted budget; present when toolUnits is configured. */
+  unitsMax?: number;
+  /**
+  * Extension grants used, restored grants included; present exactly
+  * when toolBudgetExtension is configured (RV301).
+  */
+  extensionsGranted?: number;
+  /**
+  * Notice thresholds (fractions of the cap) whose notices entered the
+  * conversation; present when at least one fired.
+  */
+  noticesFired?: number[];
+  /** Present and true when the finalization reserve summary turn ran. */
+  finalizationReserveUsed?: boolean;
+  /** The tool budget limiter that ended the loop, on that 'limit' only. */
+  limiter?: "maxToolCalls" | "toolUnits";
+}
+/**
 * Agent lifecycle. One logical agent dispatch emits EXACTLY ONE
 * `agent:start`/`agent:end` pair on its span (the start carries the
 * primary role), and each model invocation phase inside the span
@@ -3632,6 +3668,12 @@ type AgentEvents = {
   * terminal error payload.
   */
   exploration?: ExplorationSummary;
+  /**
+  * The tool budget pressure snapshot (RV304). Present live whenever
+  * a tool budget limiter or the extension was configured; live
+  * telemetry only, absent on replay.
+  */
+  toolBudget?: ToolBudgetSummary;
 } | {
   type: "agent:error";
   agentType: string;
@@ -4041,6 +4083,29 @@ interface UsageLimits {
   finalizationReserve?: {
     maxOutputTokens?: number;
   };
+  /**
+  * The adaptive tool budget (RV301, the seventh comparison experiment):
+  * when maxToolCalls expires but the run still has money and the agent
+  * still makes progress, the runtime grants `increment` more executed
+  * calls instead of ending the invocation, up to `maxExtensions` grants.
+  * A grant is admitted only when the remaining chain budget (the same
+  * arithmetic the per-turn output clamp reads) is above zero, or above
+  * `minHeadroomUsd` when declared, and, unless `requireNewEvidence` is
+  * set to false, only when at least one novel tool result digest arrived
+  * since the previous grant (the exploration guard's evidence chain).
+  * Each grant is announced to the model as a plain user message with the
+  * exact new counts, so pacing stays possible; on resume the grants
+  * re-derive conservatively from the restored executed-call count.
+  * Extends maxToolCalls only, never toolUnits. Off by default: the
+  * grant notices enter the conversation, so enabling it changes
+  * recorded model requests.
+  */
+  toolBudgetExtension?: {
+    /** Executed calls added per grant. */increment: number; /** Hard bound on grants per invocation. */
+    maxExtensions: number; /** Grant only at or above this remaining chain headroom, in USD. */
+    minHeadroomUsd?: number; /** Default true: a grant needs new evidence since the last one. */
+    requireNewEvidence?: boolean;
+  };
 }
 declare const DEFAULT_MAX_TURNS = 32;
 declare const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 12e4;
@@ -4064,6 +4129,12 @@ interface EffectiveUsageLimits {
   finalizationReserve?: {
     maxOutputTokens?: number;
   };
+  toolBudgetExtension?: {
+    increment: number;
+    maxExtensions: number;
+    minHeadroomUsd?: number;
+    requireNewEvidence?: boolean;
+  };
 }
 /**
 * Limits merge per spawn: AgentOpts.limits over profile limits over engine
@@ -4196,6 +4267,13 @@ interface AgentResult<T> {
   */
   exploration?: ExplorationSummary;
   /**
+  * 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.
+  */
+  toolBudget?: ToolBudgetSummary;
+  /**
   * 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
@@ -4270,6 +4348,13 @@ interface BudgetHooks {
   * or free output).
   */
   maxAffordableOutputTokens?: (servedBy: ModelRef, estimatedInputTokens: number) => number | undefined;
+  /**
+  * The remaining chain headroom in USD (RV301): the same arithmetic
+  * the output bound above reads, before pricing. Undefined = no
+  * ceiling anywhere on the chain. The tool budget extension admits a
+  * grant against it.
+  */
+  remainingUsd?: () => number | undefined;
   /** Live usage accounting; layer 3 may respond by aborting `signal`. */
   onUsage(usage: Usage, servedBy: ModelRef): void;
   /** Layer 3: the ceiling AbortSignal. */
@@ -5122,6 +5207,14 @@ declare class RunBudget {
   * onUsage covers that hole), or when output is free. Zero or negative
   * means the turn cannot be dispatched within the budget.
   */
+  /**
+  * The tightest chain headroom of `accountScope` in plain USD (RV301):
+  * exactly the remaining money the output clamp below prices, before
+  * any pricing. Undefined when every account on the chain is uncapped;
+  * never negative. The tool budget extension admits a grant against
+  * this number.
+  */
+  remainingUsd(accountScope?: string): number | undefined;
   maxAffordableOutputTokens(servedBy: ModelRef, estimatedInputTokens: number, accountScope?: string): number | undefined;
   /**
   * Live accounting; spend propagates from `accountScope` to every
@@ -9766,6 +9859,11 @@ interface AgentInvocationRow {
   costUsd: number;
   usageApprox: boolean;
   retryCount: number;
+  /**
+  * The tool budget pressure snapshot (RV304), carried through from the
+  * live agent:end. Absent on replayed rows and unbounded loops.
+  */
+  toolBudget?: ToolBudgetSummary;
   replayed: boolean;
   /** True when the span's agent:end never arrived. */
   open: boolean;
@@ -9889,4 +9987,4 @@ interface SandboxBridge {
 declare const SANDBOX_AGENT_OPT_KEYS: readonly string[];
 declare function createSandboxBridge(ctx: Ctx<never>, options: SandboxBridgeOptions): SandboxBridge;
 //#endregion
-export { AWAIT_SCHEMA, AbandonAttempt, AbandonFold, AbandonPayload, AbandonedSpendView, AbortClass, type AdaptiveEvents, AdmissionController, AdmissionDecision, AdmissionRejectedError, AdmissionStatsBefore, AdmitLineage, AdmitRejectReason, AdmitSpec, AdmitVerdict, AgentCallError, AgentError, type AgentEvents, AgentIdentityInput, type AgentInvocationRow, AgentOpts, AgentProfile, AgentProfilePermissions, AgentProfileTemplateOptions, AgentResult, AgentResultMeta, AgentStatus, ApproachSignatureInputs, ApprovalDecision, ApprovalIdentityInput, Artifact, AttemptOutcomeClass, AuditCategory, AuditRecord, AuditRunsOptions, BUDGET_ABORT_REASON, BaseAppend, BriefOpts, BudgetAccountView, BudgetDefaults, BudgetExhaustedError, BudgetExhaustionDiagnostics, BudgetHooks, BudgetReserve, type Bytes, CANCEL_AGENT_SCHEMA, CHECKPOINT_FORMAT_V1, CLAIM_STATEMENT_MAX_CHARS, CLAIM_TTL_DAYS, COMPACTION_SUMMARY_PREFIX, CURRENT_HASH_VERSION, CacheHint, CacheTtl, CanUseTool, CanonicalId, CanonicalIdentity, CanonicalLadderSpec, CanonicalModelSpec, ChatEvent, ChatRequest, CheckpointState, ChildArtifactPage, ChildIdentityInput, ChildResultPage, type ClaimClass, type ClaimOp, type ClaimStatus, ClaimValidationOptions, CollectOpts, CollectedTurn, CompactionConfig, CompiledPermissionChain, CompiledWorkflow, ConfigError, type CoreEvents, CostAttribution, CostAttributionFacts, CostReport, CreateEngineOptions, type CriticalPath, Ctx, DEFAULT_CHILD_BUDGET_FRACTION, DEFAULT_CHILD_RESULT_PAGE_CHARS, DEFAULT_CITATION_PATTERN, DEFAULT_CITATION_SAMPLE, DEFAULT_COMPACTION_THRESHOLD, DEFAULT_ESCALATION_LIMITS, DEFAULT_EVIDENCE_MIN_SHARE, DEFAULT_FINISH_MAX_REPAIRS, DEFAULT_FLAT_RESERVE_USD, DEFAULT_MAX_CHILDREN_PER_NODE, DEFAULT_MAX_DEPTH, DEFAULT_MAX_OSCILLATIONS_PER_KEY, DEFAULT_MAX_PINNED_WORKTREES, DEFAULT_MAX_REVISIONS_PER_RUN, DEFAULT_MAX_TOTAL_SPAWNS, DEFAULT_MAX_TURNS, DEFAULT_MODEL_RETRY_ATTEMPTS, DEFAULT_NO_PROGRESS_TURNS, DEFAULT_PER_RUN_CONCURRENCY, DEFAULT_RETRY_POLICY, DEFAULT_STREAM_IDLE_TIMEOUT_MS, DEFAULT_SYNTHESIS_MAX_TURNS, DEFAULT_SYNTHESIS_NOTE_MAX_TURNS, DataKeyProvider, DebitResult, DeclaredLadder, DedupIndex, DedupNote, DedupedClaims, DerivedKey, DeriverRegistry, type DeterminismConfig, DeterminismError, type DeterminismEvents, type DeterminismMode, DispositionRule, DispositionTable, DonorCandidate, DonorRef, DroppedItem, EMIT_RESULT_TOOL, EMPTY_SCHEMA_HASH, EMPTY_TOOLSET_HASH, ESCALATE_TOOL_NAME, ESCALATION_REPORT_SCHEMA, ESCALATION_REQUEST_SCHEMA, EVENT_SEGMENT_STRIDE, EffectiveUsageLimits, Effort, Engine, EngineDefaults, EngineQuotaConfig, EngineQuotaRuntime, EntryKind, EntryRef, EntryStatus, EnvelopeEncryption, EnvelopeEncryptionOptions, ErrorClass, ErrorCode, ErrorPolicy, EscalatedResult, EscalationDecision, EscalationDecisionAbortedError, EscalationDigest, EscalationKind, EscalationLimits, EscalationOptions, EscalationReport, EscalationRequest, EventBus, type EvidenceRef, type ExecutorRegistry, type ExplorationSummary, ExtensionAppendInput, ExtensionDispatchSpec, ExternalIdentityInput, ExternalRegistry, ExtractNecessityInput, FINALIZE_SYNTHESIS_INSTRUCTION, FINISH_SCHEMA, FINISH_TOOL_NAME, FailRunError, FailoverTarget, FailoverTrigger, FallbackField, FallbackTrigger, FencedCodeMode, FileModelKnowledgeStore, FileModelKnowledgeStoreOptions, FileTranscriptStore, FinishContract, FinishContractCitations, FinishContractGoldenReject, FinishContractManifest, FinishInfo, FinishSelfTestFailure, FinishSelfTestFixtures, FinishSelfTestReport, FinishValidationChild, FinishValidationInput, FinishValidationSpec, FinishValidationVerdict, FinishValidator, GET_CHILD_RESULT_SCHEMA, GET_CHILD_RESULT_TOOL_NAME, Gate, GateAudit, type GateRecord, GitWorktreeProvider, GitWorktreeProviderOptions, GraftBoot, HashVersion, HookVerdict, IMPLEMENTATION_PROFILE_LIMITS, INBOX_PROPOSAL_TTL_DAYS, IdentityInput, InMemoryStore, InMemoryTranscriptStore, InProcessRunner, IncrementalSynthesisResult, InvalidResolutionError, InvocationRole, type InvocationTable, InvoiceExport, InvoiceReconciliation, InvoiceRow, type IsolatedExecContext, type IsolatedExecRequest, type IsolatedExecutorTag, type IsolationProvider, type IsolationSpec, Issue$1 as Issue, JOURNAL_ENVELOPE_MARKER, JournalCompatSubCode, JournalCompatibilityError, JournalEntry, JournalMatcher, JournalMissError, JournalOperation, JournalOrderViolation, JournalSerializationContext, JournalSerializationHook, type JournalStore, type Json, JsonSchema, JsonlFileStore, KB_ACTIVE_CLAIMS_CAP, KB_CARD_RENDER_BUDGET_CHARS, type KbProposal, type KbProposalTrigger, KeyDeriver, KeyRing, KeyedLimiter, KnowledgeCasError, type KnowledgeSnapshot, LARGE_VALUE_WARN_BYTES, LEGACY_LTID_PREFIX, LEGACY_SIGNATURE_INPUTS, LINEAGE_SIG_VERSION, LadderSpec, type LeasableStore, type Lease, LeaseHeldError, Ledger, LineageCounters, LineageIndex, LineageRef, LineageRelation, LineageStats, LogicalTaskId, MASKED_SECRET, MAX_CHILD_RESULT_PAGE_CHARS, MAX_DEPTH_CEILING, MatchResult, McpConfig, McpToolSource, MechanicalGateProfile, MechanicalGateVerdict, MemoryQuotaLimiter, type MetaLookupStore, type ModelCaps, ModelChoice, type ModelClaim, ModelEpochInputs, type ModelKnowledgeHandle, type ModelKnowledgeStore, ModelListConstraint, ModelRef, ModelRetry, ModelSpec, Msg, NoProgressDetector, NodeId, NodeLinkValue, NonSerializableValueError, ORCHESTRATE_WORKFLOW_NAME, OnEscalation, OperationDisposition, OrchestrateAcceptance, OrchestrateOptions, OrchestrateSynthesis, OrchestrateSynthesisSkipReason, OrchestratorBudgetSpec, OrchestratorCapConfigError, OrchestratorExtension, OrchestratorExtensionIO, OrchestratorRuntime, Out, PARALLEL_AGENTS_SCHEMA, PROGRESS_REPORT_TOOL_NAME, ParallelSiteCounter, Part, PendingExternal, PendingToolTurn, PermissionConfig, PermissionGate, PermissionHook, PermissionPreset, PermissionRule, PermissionVerdict, type PhaseRow, PhaseTarget, PipelineCollected, PipelineOpts, PlanInvariantError, PreflightAdmissionRow, PreflightFinding, PreflightInput, PreflightOrchestratorSpec, PreflightReport, PreflightSpawnReport, PreflightSpawnSpec, PreflightToolCeiling, PriceTable, PricedUsage, type Pricing, type PricingTier, ProgressReport, type ProviderAdapter, ProviderCallRecord, QUOTA_WINDOW_MS, QualityFloors, QuotaCounters, type QuotaDecision, type QuotaEstimate, type QuotaLimiter, type QuotaReservationRequest, QuotaRule, QuotaWindowSnapshot, READ_CHILD_ARTIFACT_SCHEMA, READ_CHILD_ARTIFACT_TOOL_NAME, RESEARCH_PROFILE_LIMITS, REVIEW_PROFILE_LIMITS, ROLE_EFFORT_DEFAULTS, ROOT_ACCOUNT, ROOT_SCOPE, RUN_PROFILES, RUN_SETTLE_DECISION_TYPE, RandIdentityInput, RandPayload, RateLimitObservation, ReconcileOptions, ReconcileResult, RefEntryAppender, RefEntryClassification, RefusalInfo, RepeatedClaim, ReplayDisposition, ReplayMode, ReplayPlanHashMismatch, Replayer, RepositoryResearchToolset, RepositoryResearchToolsetOptions, ResearchAgentProfileOptions, ResearchAgentProfileResult, ResearchEvidenceEntry, ResolutionArbiter, ResolutionAttempt, ResolutionBy, ResolutionFold, ResolutionLayer, ResolutionOutcome, ResolutionPayload, ResolvedInvocation, ResolvedToolset, ResumeHandle, ResumeOptions, ResumePreview, ResumeReport, RetryClass, RetryPolicy, ReuseConfig, RiskRuleValue, Role, RulvarError, RulvarErrorCode, RunAgentOptions, RunAuditVerdict, RunBudget, RunEventSink, RunExport, type RunFilter, RunHandle, RunInternals, type RunMeta, RunOptions, RunOutcome, RunProfile, RunStateAudit, RunStatus, RuntimeEventSink, SANDBOX_AGENT_OPT_KEYS, SPAWN_AGENT_SCHEMA, SandboxBridge, SandboxBridgeOptions, SandboxError, SandboxHostToWorker, SandboxMethod, SandboxWorkerToHost, SchemaPair, SchemaSpec, SchemaValidationResult, ScopeSegment, ScriptRejected, ScriptRunner, ScrubNote, SecretMasker, SectionMatchMode, Semaphore, SerializationHook, Settled, SettlementError, ShellPatternRules, ShellSegment, ShellVerdict, SinglePhaseAppend, SpanMinter, SpanRegistry, SpawnAdmissionValue, SpawnAgentParams, SpawnKey, SpawnLineage, SpawnLineageOpt, SpawnOrigin, SpawnRecord, Spend, Stage, type StandardJSONSchemaV1, type StandardSchemaV1, StepIdentityInput, StructuredOutputTier, SuspendedAppend, SuspensionState, TOOL_NAME_PATTERN, type TaskClass, TaskDigest, TaskSpec, TerminalPatch, TerminationAccount, TerminationAccountSnapshot, TerminationDeniedValue, TerminationDeniedWriter, TerminationInitValue, TerminationLimits, TerminationResource, ToolCallRequest, ToolChoice, type ToolContext, ToolContextSeed, ToolContract, type ToolDef, type ToolEvents, type ToolExecutor, type ToolExecutorProvider, ToolInit, type ToolRisk, ToolRuntime, type ToolSource, type ToolSourceSession, ToolsOption, TranscriptSerializationHook, type TranscriptStore, TriggerClass, TtlState, Usage, UsageLimits, UsageSlice, VerifiedRecommendation, WAIT_FOR_EVENTS_SCHEMA, WAIT_FOR_EVENTS_TOOL_NAME, WAKE_SUMMARY_RENDER_BUDGET_CHARS, WakeBudgetBlock, WakeDigest, WakeTrigger, WireError, Workflow, WorkflowCallOpts, type WorkflowEvent, type WorkflowEventBody, WorkflowRegistry, admissionReserveUsd, affordableOutputTokens, agentErrorFromWire, agentErrorToWire, agentResultWire, agentScope, applyClaimOps, applyStructuredOutputTier, approachSigCoarse, approachSigOf, archiveDeprecatedModelOps, assertFencedWrites, atCompactionThreshold, auditRun, auditRuns, buildAbandonFold, buildAdapterRegistry, buildCostReport, buildDeriverRegistry, buildOrchestratorTools, buildTerminationInitValue, buildToolContext, canRideLoopTurn, canonicalIsolationTag, canonicalizeLadder, canonicalizeSchema, capIssues, capsHashOf, checkFloors, checkpointRefFor, childCoveragePrefix, claimExpired, claimExpiry, claimIssues, claimOpIssues, classifyAgentError, classifyAttemptOutcome, collectDeclaredLadders, compactMessages, compilePermissionChain, compilePermissionPreset, compileSecretMasker, compileVerifiedLayer, constantTimeEqual, costReportFromJournal, countsAgainstLimit, createCanonicalIdMinter, createCtx, createEngine, createEnvelopeEncryption, createSandboxBridge, currentOnlyKeyRing, decodeCheckpoint, dedupeRepeatedClaims, defineWorkflow, deriveContentKey, deriverV1, deriverV2, digestOf, dispatchProjectionReserveUsd, dispositionHook, emptyDigestBlocks, emptyToolset, encodeCheckpoint, entryUsageSlices, escalateTool, evaluatePermission, evaluateReuse, evidencePreservedValidator, executeWorkflow, exhaustionCodeOf, extractCandidate, failoverTriggerOf, fallbackTriggerOf, filterClaimsForRun, finalizeFires, finishContract, foldTermination, formatRePrompt, formatScopePath, hasFencedWrites, hasMetaLookup, hashRunArgs, hashRunOutput, hashWorkflowBody, hashWorkflowSource, headingStructureValidator, identityJcs, implementationAgentProfile, invoiceFromJournal, isEscalated, isSchemaPairSpec, isStandardSchemaSpec, isStrictCompatibleSchema, kMaxOf, knowledgeHash, ladderLengthOf, ladderRungChoice, lastRunSettle, latestProgressReport, lexShellCommand, liftRetainedParts, lineageWeightOf, localKeyProvider, makeOrchestratorWorkflow, maskSecrets, maskSecretsDeep, maskSecretsJson, matchArgvPattern, matchShellCommand, mcp, memoryQuotaLimiter, mergeQuotaDenial, mergeUsageLimits, metaMatchesFilter, minMatchesValidator, modelEpochOf, modelKnowledgeCard, modelSpecIdentity, needsSeparateExtract, nextFailover, nodeLinkKey, normalizeApproachTag, normalizeEntry, normalizeFallbacks, orchestrate, orchestratorAdmissionEstCostUsd, parallelScope, parseModelRef, parseScopePath, phiInitialOf, pipelineScope, planNodeScope, preflightEstimate, priceEntryUsage, priceUsdOf, profileCard, profileRegistrySnapshotHash, progressReportTool, projectHistory, projectIdentity, projectToJsonSchema, proposalStatement, providerOf, quotaActualTokens, quotaEstimateTokens, quotaRuleAdmission, quotaRuleMatches, readRunMeta, readTerminationInit, reconcileRunMeta, reduceAuditTrail, reduceCriticalPath, reduceInvocationTable, registryKeyRing, remeasureQueue, replayDisposition, repositoryResearchToolset, requiredFieldsValidator, requiredSectionsValidator, researchAgentProfile, resolveModelInvocation, resolvePricing, resolveToolset, retryClassOf, retryDelayMs, reviewAgentProfile, roleConfiguredInRouting, roundOneDisposition, runAgent, runProfile, sanitizeTerminalText, sanitizeTokenCount, sanitizeUsage, sanitizeUsageDelta, scanJournalCompatibility, schemaHash, schemaHashOfSpec, sectionCitationsValidator, selectStructuredOutputTier, selfTestFinishValidation, shouldCompact, snapshotUsage, spawnDepthOf, stripFencedBlocks, summarizeInstruction, summarizeOutput, terminationConfigDrift, tierWithinCaps, toApprovalDecision, toJournalValue, tool, toolContract, toolsetHash, ttlState, usageViolations, validateEditorialCommit, validateEngineQuotaConfig, validateEntryShape, validateEscalationLimits, validateEscalationReport, validateQuotaRules, validateRetryPolicy, validateSchemaSpec, validateTerminationLimits, validateUsageLimits, wordCountValidator, workflowScope, workflowSourceRef, wrapJournalStore, wrapTranscriptStore };
+export { AWAIT_SCHEMA, AbandonAttempt, AbandonFold, AbandonPayload, AbandonedSpendView, AbortClass, type AdaptiveEvents, AdmissionController, AdmissionDecision, AdmissionRejectedError, AdmissionStatsBefore, AdmitLineage, AdmitRejectReason, AdmitSpec, AdmitVerdict, AgentCallError, AgentError, type AgentEvents, AgentIdentityInput, type AgentInvocationRow, AgentOpts, AgentProfile, AgentProfilePermissions, AgentProfileTemplateOptions, AgentResult, AgentResultMeta, AgentStatus, ApproachSignatureInputs, ApprovalDecision, ApprovalIdentityInput, Artifact, AttemptOutcomeClass, AuditCategory, AuditRecord, AuditRunsOptions, BUDGET_ABORT_REASON, BaseAppend, BriefOpts, BudgetAccountView, BudgetDefaults, BudgetExhaustedError, BudgetExhaustionDiagnostics, BudgetHooks, BudgetReserve, type Bytes, CANCEL_AGENT_SCHEMA, CHECKPOINT_FORMAT_V1, CLAIM_STATEMENT_MAX_CHARS, CLAIM_TTL_DAYS, COMPACTION_SUMMARY_PREFIX, CURRENT_HASH_VERSION, CacheHint, CacheTtl, CanUseTool, CanonicalId, CanonicalIdentity, CanonicalLadderSpec, CanonicalModelSpec, ChatEvent, ChatRequest, CheckpointState, ChildArtifactPage, ChildIdentityInput, ChildResultPage, type ClaimClass, type ClaimOp, type ClaimStatus, ClaimValidationOptions, CollectOpts, CollectedTurn, CompactionConfig, CompiledPermissionChain, CompiledWorkflow, ConfigError, type CoreEvents, CostAttribution, CostAttributionFacts, CostReport, CreateEngineOptions, type CriticalPath, Ctx, DEFAULT_CHILD_BUDGET_FRACTION, DEFAULT_CHILD_RESULT_PAGE_CHARS, DEFAULT_CITATION_PATTERN, DEFAULT_CITATION_SAMPLE, DEFAULT_COMPACTION_THRESHOLD, DEFAULT_ESCALATION_LIMITS, DEFAULT_EVIDENCE_MIN_SHARE, DEFAULT_FINISH_MAX_REPAIRS, DEFAULT_FLAT_RESERVE_USD, DEFAULT_MAX_CHILDREN_PER_NODE, DEFAULT_MAX_DEPTH, DEFAULT_MAX_OSCILLATIONS_PER_KEY, DEFAULT_MAX_PINNED_WORKTREES, DEFAULT_MAX_REVISIONS_PER_RUN, DEFAULT_MAX_TOTAL_SPAWNS, DEFAULT_MAX_TURNS, DEFAULT_MODEL_RETRY_ATTEMPTS, DEFAULT_NO_PROGRESS_TURNS, DEFAULT_PER_RUN_CONCURRENCY, DEFAULT_RETRY_POLICY, DEFAULT_STREAM_IDLE_TIMEOUT_MS, DEFAULT_SYNTHESIS_MAX_TURNS, DEFAULT_SYNTHESIS_NOTE_MAX_TURNS, DataKeyProvider, DebitResult, DeclaredLadder, DedupIndex, DedupNote, DedupedClaims, DerivedKey, DeriverRegistry, type DeterminismConfig, DeterminismError, type DeterminismEvents, type DeterminismMode, DispositionRule, DispositionTable, DonorCandidate, DonorRef, DroppedItem, EMIT_RESULT_TOOL, EMPTY_SCHEMA_HASH, EMPTY_TOOLSET_HASH, ESCALATE_TOOL_NAME, ESCALATION_REPORT_SCHEMA, ESCALATION_REQUEST_SCHEMA, EVENT_SEGMENT_STRIDE, EffectiveUsageLimits, Effort, Engine, EngineDefaults, EngineQuotaConfig, EngineQuotaRuntime, EntryKind, EntryRef, EntryStatus, EnvelopeEncryption, EnvelopeEncryptionOptions, ErrorClass, ErrorCode, ErrorPolicy, EscalatedResult, EscalationDecision, EscalationDecisionAbortedError, EscalationDigest, EscalationKind, EscalationLimits, EscalationOptions, EscalationReport, EscalationRequest, EventBus, type EvidenceRef, type ExecutorRegistry, type ExplorationSummary, ExtensionAppendInput, ExtensionDispatchSpec, ExternalIdentityInput, ExternalRegistry, ExtractNecessityInput, FINALIZE_SYNTHESIS_INSTRUCTION, FINISH_SCHEMA, FINISH_TOOL_NAME, FailRunError, FailoverTarget, FailoverTrigger, FallbackField, FallbackTrigger, FencedCodeMode, FileModelKnowledgeStore, FileModelKnowledgeStoreOptions, FileTranscriptStore, FinishContract, FinishContractCitations, FinishContractGoldenReject, FinishContractManifest, FinishInfo, FinishSelfTestFailure, FinishSelfTestFixtures, FinishSelfTestReport, FinishValidationChild, FinishValidationInput, FinishValidationSpec, FinishValidationVerdict, FinishValidator, GET_CHILD_RESULT_SCHEMA, GET_CHILD_RESULT_TOOL_NAME, Gate, GateAudit, type GateRecord, GitWorktreeProvider, GitWorktreeProviderOptions, GraftBoot, HashVersion, HookVerdict, IMPLEMENTATION_PROFILE_LIMITS, INBOX_PROPOSAL_TTL_DAYS, IdentityInput, InMemoryStore, InMemoryTranscriptStore, InProcessRunner, IncrementalSynthesisResult, InvalidResolutionError, InvocationRole, type InvocationTable, InvoiceExport, InvoiceReconciliation, InvoiceRow, type IsolatedExecContext, type IsolatedExecRequest, type IsolatedExecutorTag, type IsolationProvider, type IsolationSpec, Issue$1 as Issue, JOURNAL_ENVELOPE_MARKER, JournalCompatSubCode, JournalCompatibilityError, JournalEntry, JournalMatcher, JournalMissError, JournalOperation, JournalOrderViolation, JournalSerializationContext, JournalSerializationHook, type JournalStore, type Json, JsonSchema, JsonlFileStore, KB_ACTIVE_CLAIMS_CAP, KB_CARD_RENDER_BUDGET_CHARS, type KbProposal, type KbProposalTrigger, KeyDeriver, KeyRing, KeyedLimiter, KnowledgeCasError, type KnowledgeSnapshot, LARGE_VALUE_WARN_BYTES, LEGACY_LTID_PREFIX, LEGACY_SIGNATURE_INPUTS, LINEAGE_SIG_VERSION, LadderSpec, type LeasableStore, type Lease, LeaseHeldError, Ledger, LineageCounters, LineageIndex, LineageRef, LineageRelation, LineageStats, LogicalTaskId, MASKED_SECRET, MAX_CHILD_RESULT_PAGE_CHARS, MAX_DEPTH_CEILING, MatchResult, McpConfig, McpToolSource, MechanicalGateProfile, MechanicalGateVerdict, MemoryQuotaLimiter, type MetaLookupStore, type ModelCaps, ModelChoice, type ModelClaim, ModelEpochInputs, type ModelKnowledgeHandle, type ModelKnowledgeStore, ModelListConstraint, ModelRef, ModelRetry, ModelSpec, Msg, NoProgressDetector, NodeId, NodeLinkValue, NonSerializableValueError, ORCHESTRATE_WORKFLOW_NAME, OnEscalation, OperationDisposition, OrchestrateAcceptance, OrchestrateOptions, OrchestrateSynthesis, OrchestrateSynthesisSkipReason, OrchestratorBudgetSpec, OrchestratorCapConfigError, OrchestratorExtension, OrchestratorExtensionIO, OrchestratorRuntime, Out, PARALLEL_AGENTS_SCHEMA, PROGRESS_REPORT_TOOL_NAME, ParallelSiteCounter, Part, PendingExternal, PendingToolTurn, PermissionConfig, PermissionGate, PermissionHook, PermissionPreset, PermissionRule, PermissionVerdict, type PhaseRow, PhaseTarget, PipelineCollected, PipelineOpts, PlanInvariantError, PreflightAdmissionRow, PreflightFinding, PreflightInput, PreflightOrchestratorSpec, PreflightReport, PreflightSpawnReport, PreflightSpawnSpec, PreflightToolCeiling, PriceTable, PricedUsage, type Pricing, type PricingTier, ProgressReport, type ProviderAdapter, ProviderCallRecord, QUOTA_WINDOW_MS, QualityFloors, QuotaCounters, type QuotaDecision, type QuotaEstimate, type QuotaLimiter, type QuotaReservationRequest, QuotaRule, QuotaWindowSnapshot, READ_CHILD_ARTIFACT_SCHEMA, READ_CHILD_ARTIFACT_TOOL_NAME, RESEARCH_PROFILE_LIMITS, REVIEW_PROFILE_LIMITS, ROLE_EFFORT_DEFAULTS, ROOT_ACCOUNT, ROOT_SCOPE, RUN_PROFILES, RUN_SETTLE_DECISION_TYPE, RandIdentityInput, RandPayload, RateLimitObservation, ReconcileOptions, ReconcileResult, RefEntryAppender, RefEntryClassification, RefusalInfo, RepeatedClaim, ReplayDisposition, ReplayMode, ReplayPlanHashMismatch, Replayer, RepositoryResearchToolset, RepositoryResearchToolsetOptions, ResearchAgentProfileOptions, ResearchAgentProfileResult, ResearchEvidenceEntry, ResolutionArbiter, ResolutionAttempt, ResolutionBy, ResolutionFold, ResolutionLayer, ResolutionOutcome, ResolutionPayload, ResolvedInvocation, ResolvedToolset, ResumeHandle, ResumeOptions, ResumePreview, ResumeReport, RetryClass, RetryPolicy, ReuseConfig, RiskRuleValue, Role, RulvarError, RulvarErrorCode, RunAgentOptions, RunAuditVerdict, RunBudget, RunEventSink, RunExport, type RunFilter, RunHandle, RunInternals, type RunMeta, RunOptions, RunOutcome, RunProfile, RunStateAudit, RunStatus, RuntimeEventSink, SANDBOX_AGENT_OPT_KEYS, SPAWN_AGENT_SCHEMA, SandboxBridge, SandboxBridgeOptions, SandboxError, SandboxHostToWorker, SandboxMethod, SandboxWorkerToHost, SchemaPair, SchemaSpec, SchemaValidationResult, ScopeSegment, ScriptRejected, ScriptRunner, ScrubNote, SecretMasker, SectionMatchMode, Semaphore, SerializationHook, Settled, SettlementError, ShellPatternRules, ShellSegment, ShellVerdict, SinglePhaseAppend, SpanMinter, SpanRegistry, SpawnAdmissionValue, SpawnAgentParams, SpawnKey, SpawnLineage, SpawnLineageOpt, SpawnOrigin, SpawnRecord, Spend, Stage, type StandardJSONSchemaV1, type StandardSchemaV1, StepIdentityInput, StructuredOutputTier, SuspendedAppend, SuspensionState, TOOL_NAME_PATTERN, type TaskClass, TaskDigest, TaskSpec, TerminalPatch, TerminationAccount, TerminationAccountSnapshot, TerminationDeniedValue, TerminationDeniedWriter, TerminationInitValue, TerminationLimits, TerminationResource, type ToolBudgetSummary, ToolCallRequest, ToolChoice, type ToolContext, ToolContextSeed, ToolContract, type ToolDef, type ToolEvents, type ToolExecutor, type ToolExecutorProvider, ToolInit, type ToolRisk, ToolRuntime, type ToolSource, type ToolSourceSession, ToolsOption, TranscriptSerializationHook, type TranscriptStore, TriggerClass, TtlState, Usage, UsageLimits, UsageSlice, VerifiedRecommendation, WAIT_FOR_EVENTS_SCHEMA, WAIT_FOR_EVENTS_TOOL_NAME, WAKE_SUMMARY_RENDER_BUDGET_CHARS, WakeBudgetBlock, WakeDigest, WakeTrigger, WireError, Workflow, WorkflowCallOpts, type WorkflowEvent, type WorkflowEventBody, WorkflowRegistry, admissionReserveUsd, affordableOutputTokens, agentErrorFromWire, agentErrorToWire, agentResultWire, agentScope, applyClaimOps, applyStructuredOutputTier, approachSigCoarse, approachSigOf, archiveDeprecatedModelOps, assertFencedWrites, atCompactionThreshold, auditRun, auditRuns, buildAbandonFold, buildAdapterRegistry, buildCostReport, buildDeriverRegistry, buildOrchestratorTools, buildTerminationInitValue, buildToolContext, canRideLoopTurn, canonicalIsolationTag, canonicalizeLadder, canonicalizeSchema, capIssues, capsHashOf, checkFloors, checkpointRefFor, childCoveragePrefix, claimExpired, claimExpiry, claimIssues, claimOpIssues, classifyAgentError, classifyAttemptOutcome, collectDeclaredLadders, compactMessages, compilePermissionChain, compilePermissionPreset, compileSecretMasker, compileVerifiedLayer, constantTimeEqual, costReportFromJournal, countsAgainstLimit, createCanonicalIdMinter, createCtx, createEngine, createEnvelopeEncryption, createSandboxBridge, currentOnlyKeyRing, decodeCheckpoint, dedupeRepeatedClaims, defineWorkflow, deriveContentKey, deriverV1, deriverV2, digestOf, dispatchProjectionReserveUsd, dispositionHook, emptyDigestBlocks, emptyToolset, encodeCheckpoint, entryUsageSlices, escalateTool, evaluatePermission, evaluateReuse, evidencePreservedValidator, executeWorkflow, exhaustionCodeOf, extractCandidate, failoverTriggerOf, fallbackTriggerOf, filterClaimsForRun, finalizeFires, finishContract, foldTermination, formatRePrompt, formatScopePath, hasFencedWrites, hasMetaLookup, hashRunArgs, hashRunOutput, hashWorkflowBody, hashWorkflowSource, headingStructureValidator, identityJcs, implementationAgentProfile, invoiceFromJournal, isEscalated, isSchemaPairSpec, isStandardSchemaSpec, isStrictCompatibleSchema, kMaxOf, knowledgeHash, ladderLengthOf, ladderRungChoice, lastRunSettle, latestProgressReport, lexShellCommand, liftRetainedParts, lineageWeightOf, localKeyProvider, makeOrchestratorWorkflow, maskSecrets, maskSecretsDeep, maskSecretsJson, matchArgvPattern, matchShellCommand, mcp, memoryQuotaLimiter, mergeQuotaDenial, mergeUsageLimits, metaMatchesFilter, minMatchesValidator, modelEpochOf, modelKnowledgeCard, modelSpecIdentity, needsSeparateExtract, nextFailover, nodeLinkKey, normalizeApproachTag, normalizeEntry, normalizeFallbacks, orchestrate, orchestratorAdmissionEstCostUsd, parallelScope, parseModelRef, parseScopePath, phiInitialOf, pipelineScope, planNodeScope, preflightEstimate, priceEntryUsage, priceUsdOf, profileCard, profileRegistrySnapshotHash, progressReportTool, projectHistory, projectIdentity, projectToJsonSchema, proposalStatement, providerOf, quotaActualTokens, quotaEstimateTokens, quotaRuleAdmission, quotaRuleMatches, readRunMeta, readTerminationInit, reconcileRunMeta, reduceAuditTrail, reduceCriticalPath, reduceInvocationTable, registryKeyRing, remeasureQueue, replayDisposition, repositoryResearchToolset, requiredFieldsValidator, requiredSectionsValidator, researchAgentProfile, resolveModelInvocation, resolvePricing, resolveToolset, retryClassOf, retryDelayMs, reviewAgentProfile, roleConfiguredInRouting, roundOneDisposition, runAgent, runProfile, sanitizeTerminalText, sanitizeTokenCount, sanitizeUsage, sanitizeUsageDelta, scanJournalCompatibility, schemaHash, schemaHashOfSpec, sectionCitationsValidator, selectStructuredOutputTier, selfTestFinishValidation, shouldCompact, snapshotUsage, spawnDepthOf, stripFencedBlocks, summarizeInstruction, summarizeOutput, terminationConfigDrift, tierWithinCaps, toApprovalDecision, toJournalValue, tool, toolContract, toolsetHash, ttlState, usageViolations, validateEditorialCommit, validateEngineQuotaConfig, validateEntryShape, validateEscalationLimits, validateEscalationReport, validateQuotaRules, validateRetryPolicy, validateSchemaSpec, validateTerminationLimits, validateUsageLimits, wordCountValidator, workflowScope, workflowSourceRef, wrapJournalStore, wrapTranscriptStore };

package/dist/index.js

@@ -9021,6 +9021,8 @@ function mergeUsageLimits(call, profile, engine) {
 	if (toolUnits !== void 0) merged.toolUnits = toolUnits;
 	const finalizationReserve = pick("finalizationReserve");
 	if (finalizationReserve !== void 0) merged.finalizationReserve = finalizationReserve;
+	const toolBudgetExtension = pick("toolBudgetExtension");
+	if (toolBudgetExtension !== void 0) merged.toolBudgetExtension = toolBudgetExtension;
 	return merged;
 }
 /**
@@ -9066,6 +9068,15 @@ function validateUsageLimits(limits, site) {
 		const { maxOutputTokens } = reserve;
 		if (maxOutputTokens !== void 0) requirePositiveInteger(maxOutputTokens, `${site}.finalizationReserve.maxOutputTokens`);
 	}
+	if (limits.toolBudgetExtension !== void 0) {
+		const extension = limits.toolBudgetExtension;
+		if (typeof extension !== "object" || extension === null || Array.isArray(extension)) throw new ConfigError(`${site}.toolBudgetExtension must be { increment, maxExtensions, minHeadroomUsd?, requireNewEvidence? }`);
+		const { increment, maxExtensions, minHeadroomUsd, requireNewEvidence } = extension;
+		requirePositiveInteger(increment, `${site}.toolBudgetExtension.increment`);
+		requirePositiveInteger(maxExtensions, `${site}.toolBudgetExtension.maxExtensions`);
+		if (minHeadroomUsd !== void 0 && (typeof minHeadroomUsd !== "number" || !Number.isFinite(minHeadroomUsd) || minHeadroomUsd < 0)) throw new ConfigError(`${site}.toolBudgetExtension.minHeadroomUsd must be a finite nonnegative USD amount, got ${typeof minHeadroomUsd === "number" ? String(minHeadroomUsd) : typeof minHeadroomUsd}`);
+		if (requireNewEvidence !== void 0 && typeof requireNewEvidence !== "boolean") throw new ConfigError(`${site}.toolBudgetExtension.requireNewEvidence must be a boolean; got ${typeof requireNewEvidence}`);
+	}
 }
 //#endregion
 //#region src/model/failover.ts
@@ -9646,9 +9657,13 @@ const DEFAULT_MODEL_RETRY_ATTEMPTS = 2;
 */
 /** The docs anchor cited by guard denials and the guard abort. */
 const GUARD_DOCS_URL = "https://docs.rulvar.com/guide/agents#exploration-guards";
-/** True when any exploration guard field asks for tracking. */
+/**
+* True when any exploration guard field asks for tracking. The tool
+* budget extension (RV301) counts too: its requireNewEvidence admission
+* reads the guard's evidence chain.
+*/
 function explorationTrackingEnabled(limits) {
-	return limits.maxRepeatedToolSignature !== void 0 || limits.maxNoNewEvidenceCalls !== void 0 || limits.toolBudgetNotices === true || limits.maxCallsPerTool !== void 0 || limits.toolUnits !== void 0;
+	return limits.maxRepeatedToolSignature !== void 0 || limits.maxNoNewEvidenceCalls !== void 0 || limits.toolBudgetNotices === true || limits.maxCallsPerTool !== void 0 || limits.toolUnits !== void 0 || limits.toolBudgetExtension !== void 0;
 }
 function digestOf$1(value) {
 	try {
@@ -9775,6 +9790,16 @@ var ExplorationGuard = class {
 	unitsExhausted() {
 		return this.config.toolUnits !== void 0 && this.unitsUsed >= this.config.toolUnits.max;
 	}
+	/**
+	* Distinct successful result digests seen this invocation: the
+	* extension's requireNewEvidence admission compares snapshots of this
+	* count (RV301). A result JCS cannot digest never counts, so a grant
+	* fails closed there, unlike the guards, which fail open: a denied
+	* grant only restores the pre-extension expiry.
+	*/
+	evidenceCount() {
+		return this.seenDigests.size;
+	}
 	/** The abort message for a tripped no-new-evidence guard. */
 	describeTrip() {
 		return `exploration guard: ${String(this.noNewEvidenceStreak)} consecutive tool calls returned no new evidence (maxNoNewEvidenceCalls ${String(this.config.maxNoNewEvidenceCalls ?? this.noNewEvidenceStreak)}; every result was already seen this invocation). The executed work is kept; narrow the scope, vary the queries, or raise the limit (${GUARD_DOCS_URL}).`;
@@ -9813,6 +9838,15 @@ function toolBudgetNoticeText(used, max) {
 	const remaining = Math.max(0, max - used);
 	return `Tool budget notice: ${String(used)} of ${String(max)} tool calls used; ${String(remaining)} remaining. Prioritize the highest value calls and finish with what you have.`;
 }
+/**
+* The model-visible extension notice (RV301): announces one grant with
+* the exact new counts. Deterministic for given counts, like the budget
+* notice above.
+*/
+function toolBudgetExtensionNoticeText(grant, maxExtensions, used, cap) {
+	const remaining = Math.max(0, cap - used);
+	return `Tool budget extended: grant ${String(grant)} of ${String(maxExtensions)}; ${String(used)} of ${String(cap)} tool calls used, ${String(remaining)} remaining. The budget headroom permits continued work; prioritize the highest value calls.`;
+}
 //#endregion
 //#region src/runtime/no-progress.ts
 /**
@@ -10601,13 +10635,32 @@ async function runAgent(options) {
 	const noProgress = new NoProgressDetector(limits.noProgressTurns);
 	const guard = explorationTrackingEnabled(limits) ? new ExplorationGuard(limits) : void 0;
 	/**
+	* The adaptive tool budget (RV301, the seventh comparison experiment):
+	* the run that motivated it starved two mandatory workers at a fixed
+	* 84-call cap while 38% of the USD ceiling sat unspent. A grant at the
+	* expiry converts that headroom into `increment` more executed calls,
+	* bounded by `maxExtensions`, admitted only with money remaining and
+	* (by default) new evidence since the last grant. Grants re-derive
+	* conservatively from the restored executed-call count on resume, so
+	* nothing new is journaled or checkpointed.
+	*/
+	const extension = limits.toolBudgetExtension;
+	let extensionGrants = 0;
+	let extensionEvidenceAtLastGrant = 0;
+	const pendingExtensionNotices = [];
+	const effectiveMaxToolCalls = () => limits.maxToolCalls === void 0 ? void 0 : extension === void 0 ? limits.maxToolCalls : limits.maxToolCalls + extensionGrants * extension.increment;
+	/** The limiter that ended the loop; rides the RV304 pressure snapshot. */
+	let limitLimiter;
+	/** True once the finalization reserve summary turn actually ran. */
+	let reserveSummaryRan = false;
+	/**
 	* The exact limiter behind a tool-budget expiry, with its counts: the
 	* wording rides the finalization-reserve instruction and the 'limit'
 	* terminal's errorMessage (P1.1 criterion: the terminal names the
 	* limiter, never a bare status).
 	*/
 	const toolBudgetDetail = (limiter) => {
-		if (limiter === "maxToolCalls") return `maxToolCalls (${String(toolCallsUsed)}/${String(limits.maxToolCalls ?? 0)})`;
+		if (limiter === "maxToolCalls") return `maxToolCalls (${String(toolCallsUsed)}/${String(effectiveMaxToolCalls() ?? 0)})`;
 		const max = limits.toolUnits?.max ?? 0;
 		const used = guard === void 0 ? max : guard.summary(toolCallsUsed).toolUnitsUsed ?? max;
 		return `toolUnits (${String(used)}/${String(max)})`;
@@ -10639,6 +10692,44 @@ async function runAgent(options) {
 			}]
 		});
 	};
+	/**
+	* One extension grant (RV301), attempted exactly at a maxToolCalls
+	* expiry inside the dispatch walk. The notice text is queued rather
+	* than pushed: a user message may not interleave a tool batch, so the
+	* queue flushes with the budget notices after the batch's results
+	* join the history.
+	*/
+	const tryToolBudgetGrant = () => {
+		if (extension === void 0 || limits.maxToolCalls === void 0) return false;
+		if (extensionGrants >= extension.maxExtensions) return false;
+		if (extension.requireNewEvidence !== false) {
+			if ((guard?.evidenceCount() ?? 0) <= extensionEvidenceAtLastGrant) return false;
+		}
+		const remaining = options.budget?.remainingUsd?.();
+		if (remaining !== void 0) {
+			const floor = extension.minHeadroomUsd ?? 0;
+			if (floor > 0 ? remaining < floor : remaining <= 0) return false;
+		}
+		extensionGrants += 1;
+		extensionEvidenceAtLastGrant = guard?.evidenceCount() ?? 0;
+		const cap = limits.maxToolCalls + extensionGrants * extension.increment;
+		pendingExtensionNotices.push(toolBudgetExtensionNoticeText(extensionGrants, extension.maxExtensions, toolCallsUsed, cap));
+		events?.emit({
+			type: "log",
+			level: "info",
+			msg: `tool budget extended (grant ${String(extensionGrants)}/${String(extension.maxExtensions)}): maxToolCalls now ${String(cap)}`
+		});
+		return true;
+	};
+	const flushExtensionNotices = () => {
+		for (const text of pendingExtensionNotices.splice(0)) messages.push({
+			role: "user",
+			parts: [{
+				type: "text",
+				text
+			}]
+		});
+	};
 	const modelRetryCounts = /* @__PURE__ */ new Map();
 	let lastTurnUsage = {
 		inputTokens: 0,
@@ -10671,6 +10762,10 @@ async function runAgent(options) {
 		});
 		guard?.restore(messages);
 		if (limits.toolBudgetNotices === true && limits.maxToolCalls !== void 0) for (const threshold of crossedNoticeThresholds(toolCallsUsed, limits.maxToolCalls)) firedNotices.add(threshold);
+		if (extension !== void 0 && limits.maxToolCalls !== void 0 && toolCallsUsed > limits.maxToolCalls) {
+			extensionGrants = Math.min(extension.maxExtensions, Math.ceil((toolCallsUsed - limits.maxToolCalls) / extension.increment));
+			extensionEvidenceAtLastGrant = guard?.evidenceCount() ?? 0;
+		}
 	}
 	const usageSlices = () => [...usageByPhaseModel.values()].map(({ role, servedBy: sliceServedBy, usage }) => ({
 		servedBy: sliceServedBy,
@@ -10757,7 +10852,12 @@ async function runAgent(options) {
 		};
 		let terminalAdmitted = false;
 		for (const [index, call] of calls.entries()) {
-			const expiredLimiter = limits.maxToolCalls !== void 0 && toolCallsUsed >= limits.maxToolCalls ? "maxToolCalls" : guard !== void 0 && guard.unitsExhausted() ? "toolUnits" : void 0;
+			const expiryOf = () => {
+				const cap = effectiveMaxToolCalls();
+				return cap !== void 0 && toolCallsUsed >= cap ? "maxToolCalls" : guard !== void 0 && guard.unitsExhausted() ? "toolUnits" : void 0;
+			};
+			let expiredLimiter = expiryOf();
+			if (expiredLimiter === "maxToolCalls" && call.name !== options.terminalTool?.name && tryToolBudgetGrant()) expiredLimiter = expiryOf();
 			if (expiredLimiter !== void 0) {
 				const tail = calls.slice(index);
 				const terminalName = options.terminalTool?.name;
@@ -11012,6 +11112,7 @@ async function runAgent(options) {
 			await saveBoundary();
 		} else if (limitHit) {
 			status = "limit";
+			if (limiter !== void 0) limitLimiter = limiter;
 			if (guardTrip === true && guard !== void 0) {
 				abortClass = "exploration";
 				agentError = {
@@ -11031,6 +11132,7 @@ async function runAgent(options) {
 				};
 			}
 		} else {
+			flushExtensionNotices();
 			maybePushBudgetNotice();
 			await saveBoundary();
 		}
@@ -11474,6 +11576,7 @@ async function runAgent(options) {
 			}
 			if (limitHit) {
 				status = "limit";
+				if (limiter !== void 0) limitLimiter = limiter;
 				if (guardTrip === true && guard !== void 0) {
 					abortClass = "exploration";
 					agentError = {
@@ -11494,6 +11597,7 @@ async function runAgent(options) {
 				}
 				break;
 			}
+			flushExtensionNotices();
 			maybePushBudgetNotice();
 			if (options.summarize !== void 0 && !compactionDisabled && shouldCompact({
 				lastTurnUsage,
@@ -11741,6 +11845,7 @@ async function runAgent(options) {
 				});
 			}
 			if (reserveDispatch !== void 0) {
+				reserveSummaryRan = true;
 				const { outcome, target: reserveTarget } = reserveDispatch;
 				servedBy = reserveTarget.resolved.ref;
 				usageApprox = usageApprox || outcome.usageApprox;
@@ -12043,6 +12148,20 @@ async function runAgent(options) {
 	if (abortClass !== void 0) result.abortClass = abortClass;
 	if (errorMessage !== void 0) result.errorMessage = errorMessage;
 	if (guard !== void 0) result.exploration = guard.summary(toolCallsUsed);
+	if (limits.maxToolCalls !== void 0 || limits.toolUnits !== void 0 || extension !== void 0) {
+		const toolBudget = { used: toolCallsUsed };
+		const cap = effectiveMaxToolCalls();
+		if (cap !== void 0) toolBudget.cap = cap;
+		if (limits.toolUnits !== void 0) {
+			toolBudget.unitsUsed = guard?.summary(toolCallsUsed).toolUnitsUsed ?? 0;
+			toolBudget.unitsMax = limits.toolUnits.max;
+		}
+		if (extension !== void 0) toolBudget.extensionsGranted = extensionGrants;
+		if (firedNotices.size > 0) toolBudget.noticesFired = [...firedNotices].sort((a, b) => a - b);
+		if (reserveSummaryRan) toolBudget.finalizationReserveUsed = true;
+		if (limitLimiter !== void 0) toolBudget.limiter = limitLimiter;
+		result.toolBudget = toolBudget;
+	}
 	if (limitPartial !== void 0) result.partial = limitPartial;
 	const terminalName = options.terminalTool?.name;
 	const schemaRejectedTerminalExchanges = terminalName === void 0 ? 0 : messages.reduce((count, message) => count + message.parts.filter((part) => part.type === "tool-result" && part.name === terminalName && part.isError === true && part.result?.error === terminalSchemaRejectionMessage(terminalName)).length, 0);
@@ -12449,17 +12568,28 @@ var RunBudget = class {
 	* onUsage covers that hole), or when output is free. Zero or negative
 	* means the turn cannot be dispatched within the budget.
 	*/
-	maxAffordableOutputTokens(servedBy, estimatedInputTokens, accountScope = "run") {
-		const pricing = this.pricingOf?.(servedBy);
-		if (pricing === void 0) return;
-		let remainingUsd;
+	/**
+	* The tightest chain headroom of `accountScope` in plain USD (RV301):
+	* exactly the remaining money the output clamp below prices, before
+	* any pricing. Undefined when every account on the chain is uncapped;
+	* never negative. The tool budget extension admits a grant against
+	* this number.
+	*/
+	remainingUsd(accountScope = "run") {
+		let remaining;
 		for (const account of this.chainOf(accountScope)) {
 			if (account.ceilingUsd === void 0) continue;
 			const headroom = account.ceilingUsd - account.spentUsd - account.synthesisReserveUsd;
-			remainingUsd = remainingUsd === void 0 ? headroom : Math.min(remainingUsd, headroom);
+			remaining = remaining === void 0 ? headroom : Math.min(remaining, headroom);
 		}
+		return remaining === void 0 ? void 0 : Math.max(0, remaining);
+	}
+	maxAffordableOutputTokens(servedBy, estimatedInputTokens, accountScope = "run") {
+		const pricing = this.pricingOf?.(servedBy);
+		if (pricing === void 0) return;
+		const remainingUsd = this.remainingUsd(accountScope);
 		if (remainingUsd === void 0) return;
-		return affordableOutputTokens(pricing, Math.max(0, remainingUsd), estimatedInputTokens);
+		return affordableOutputTokens(pricing, remainingUsd, estimatedInputTokens);
 	}
 	/**
 	* Live accounting; spend propagates from `accountScope` to every
@@ -14177,6 +14307,7 @@ function createCtx(internals, rootWorkflow) {
 			budget: {
 				beforeTurn: () => internals.budget.beforeTurn(budgetAccount),
 				maxAffordableOutputTokens: (servedBy, estimatedInputTokens) => internals.budget.maxAffordableOutputTokens(servedBy, estimatedInputTokens, budgetAccount),
+				remainingUsd: () => internals.budget.remainingUsd(budgetAccount),
 				onUsage: (usage, servedBy) => internals.budget.onUsage(usage, servedBy, budgetAccount),
 				signal: budgetAccount === "run" ? internals.budget.signal : AbortSignal.any([internals.budget.signal, internals.budget.signalOf(budgetAccount)].filter((signal) => signal !== void 0))
 			},
@@ -14428,7 +14559,8 @@ function createCtx(internals, rootWorkflow) {
 			entryRef: terminal.seq,
 			...resultUsageApprox ? { usageApprox: true } : {},
 			...result.transportRetries !== void 0 && result.transportRetries > 0 ? { retryCount: result.transportRetries } : {},
-			...result.exploration === void 0 ? {} : { exploration: result.exploration }
+			...result.exploration === void 0 ? {} : { exploration: result.exploration },
+			...result.toolBudget === void 0 ? {} : { toolBudget: result.toolBudget }
 		}, spanId);
 		if (result.status === "escalated" && result.escalation !== void 0) {
 			let decision = flavorBDecision;
@@ -18003,9 +18135,20 @@ function orchestrate(engine, goal, opts, runOptions) {
 * regardless of mix. A free tool (unit cost 0) lifts the units bound
 * entirely for calls of that tool.
 */
+/**
+* maxToolCalls at the fully extended cap (RV301): the projections
+* assume every grant lands, because quota demand and the checkpoint
+* loss window must hold at the worst case, not the base cap.
+*/
+function extendedMaxToolCalls(limits) {
+	if (limits.maxToolCalls === void 0) return;
+	const extension = limits.toolBudgetExtension;
+	return extension === void 0 ? limits.maxToolCalls : limits.maxToolCalls + extension.maxExtensions * extension.increment;
+}
 function overallExecutedCeiling(limits, toolCeilings) {
 	const overall = toolCeilings.reduce((best, row) => row.ceiling === null ? best : best === null ? row.ceiling : Math.max(best, row.ceiling), null);
-	return limits.maxToolCalls !== void 0 && (overall === null || limits.maxToolCalls < overall) ? limits.maxToolCalls : overall;
+	const callCap = extendedMaxToolCalls(limits);
+	return callCap !== void 0 && (overall === null || callCap < overall) ? callCap : overall;
 }
 /**
 * The provider-call ceiling of one whole loop: maxTurns bounded by the
@@ -18054,9 +18197,10 @@ function toolCeilingsOf(limits) {
 				ceiling: Math.floor(limits.toolUnits.max / cost)
 			});
 		}
-		if (limits.maxToolCalls !== void 0) terms.push({
+		const callCap = extendedMaxToolCalls(limits);
+		if (callCap !== void 0) terms.push({
 			boundBy: "maxToolCalls",
-			ceiling: limits.maxToolCalls
+			ceiling: callCap
 		});
 		if (terms.length === 0) {
 			rows.push({
@@ -18289,6 +18433,21 @@ function preflightEstimate(input) {
 			message: `spawn '${label}': the whole executed-call budget (${String(executedToolCallCeiling)} calls) fits into one parallel tool batch, and checkpoints write once per completed tool turn: the cap can be reached before any checkpoint exists, and a kill mid-batch re-pays every executed call on resume`,
 			spawn: label
 		});
+		if (limits.toolBudgetExtension !== void 0) if (limits.maxToolCalls === void 0) say({
+			severity: "warning",
+			code: "inert-tool-budget-extension",
+			message: `spawn '${label}' sets toolBudgetExtension without maxToolCalls: the extension only ever raises the executed-call cap, so there is nothing to extend`,
+			spawn: label
+		});
+		else {
+			const { increment, maxExtensions } = limits.toolBudgetExtension;
+			say({
+				severity: "info",
+				code: "tool-budget-extension-exposure",
+				message: `spawn '${label}': toolBudgetExtension can raise maxToolCalls ${String(limits.maxToolCalls)} by up to ${String(maxExtensions * increment)} extra calls (${String(maxExtensions)} grants of ${String(increment)}); every grant is admitted only under remaining budget headroom, and the projections already assume the fully extended cap`,
+				spawn: label
+			});
+		}
 		if (limits.finalizationReserve !== void 0 && limits.maxToolCalls === void 0 && limits.toolUnits === void 0) say({
 			severity: "warning",
 			code: "inert-finalization-reserve",
@@ -19183,6 +19342,7 @@ function reduceInvocationTable(events) {
 			row.costUsd = event.costUsd;
 			row.usageApprox = event.usageApprox === true;
 			row.retryCount = event.retryCount ?? 0;
+			if (event.toolBudget !== void 0) row.toolBudget = event.toolBudget;
 			totalCostUsd += event.costUsd;
 			break;
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/core",
-  "version": "1.85.0",
+  "version": "1.86.0",
   "description": "Rulvar core: L0 contracts, journal kernel, ctx primitives, agent runtime, model router, tool system, dynamic orchestrator, InMemory and JSONL stores, event stream.",
   "type": "module",
   "license": "Apache-2.0",