Documentation
¶
Overview ¶
Package governor is RiskKernel's deterministic disposer — the headline feature. It enforces hard per-run budgets (tokens, dollars, loop iterations, wall-clock time) and a kill switch around every model and tool call. No LLM is ever in this path: the agent proposes, the governor disposes.
The contract is simple and strict:
- PreStep() is called before each loop iteration; it enforces the loop and time budgets and refuses to start an iteration the budget can't afford.
- CanProceed() is called immediately before a model/tool call; it enforces a hard ceiling — a run never STARTS work once any budget is breached.
- RecordUsage() is called after a call; it adds to the ledger and halts the run the instant a budget is crossed.
- Cancel() is the external kill switch.
Once halted, every guard method returns *HaltError and the derived Context is cancelled, interrupting any in-flight provider call. A Run is safe for concurrent use: the kill switch may fire from another goroutine while a call is in flight.
Index ¶
- type Budget
- type HaltError
- type HaltReason
- type Option
- type Run
- func (r *Run) Budget() Budget
- func (r *Run) CanProceed() error
- func (r *Run) Cancel()
- func (r *Run) Close()
- func (r *Run) Context() context.Context
- func (r *Run) Elapsed() time.Duration
- func (r *Run) Halted() bool
- func (r *Run) PreStep() error
- func (r *Run) RecordUsage(promptTokens, completionTokens int64, dollars float64) error
- func (r *Run) Status() (Usage, HaltReason)
- type Usage
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Budget ¶
type Budget struct {
Tokens int64 // max total tokens (prompt + completion)
Dollars float64 // max USD cost
Loops int32 // max loop iterations
Seconds int32 // max wall-clock seconds
}
Budget is the set of hard per-run limits. A zero value in any field means "unlimited" for that dimension. Mirrors the api/v1 Budget schema.
type HaltError ¶
type HaltError struct {
Reason HaltReason
Usage Usage
}
HaltError is returned by every guard method once a run is halted. Callers stop their loop on this error and persist final state.
type HaltReason ¶
type HaltReason string
HaltReason is the machine-readable reason a run stopped. Values mirror the api/v1 HaltReason enum so the API layer can pass them through unchanged.
const ( HaltNone HaltReason = "" HaltTokenBudget HaltReason = "token_budget_exceeded" HaltDollarBudget HaltReason = "dollar_budget_exceeded" HaltLoopBudget HaltReason = "loop_budget_exceeded" HaltTimeBudget HaltReason = "time_budget_exceeded" HaltCancelled HaltReason = "cancelled" )
type Option ¶
type Option func(*Run)
Option configures a Run.
func WithClock ¶
WithClock injects a clock for deterministic time-budget tests. Production uses time.Now. The injected clock drives the logical time-budget check; the derived Context's real-time backstop (which interrupts in-flight calls) is unaffected.
func WithRestoredHalt ¶ added in v0.5.0
func WithRestoredHalt(reason HaltReason) Option
WithRestoredHalt reconstructs a run that had already halted before a restart, so a reused run-id stays terminal — it refuses further work with its original reason instead of resuming. Crash-resume restores in-flight runs with WithRestoredUsage; this restores the ones that were already over, so a reused id can't be handed a fresh budget. A HaltNone reason is a no-op. (#29)
func WithRestoredUsage ¶
WithRestoredUsage seeds a run's accumulated usage — used by crash-resume to reconstruct a run so it keeps enforcing against the budget it already spent before the daemon restarted. The wall-clock budget restarts its clock on resume (it meters a single active session, not downtime).
type Run ¶
type Run struct {
// contains filtered or unexported fields
}
Run is the live governance state for a single governed run.
func New ¶
New starts governing a run under budget b. The returned Run derives a Context (from parent) that is cancelled on halt/cancel, and that additionally carries a real-time deadline when a time budget is set — so an in-flight provider call is interrupted, not just refused at the next checkpoint. Call Close when done.
func (*Run) CanProceed ¶
CanProceed enforces the hard ceiling immediately before a model/tool call: a run never starts work once a token, dollar, or time budget is breached. Returns *HaltError if the run cannot proceed.
func (*Run) Cancel ¶
func (r *Run) Cancel()
Cancel is the external kill switch. It halts the run (reason "cancelled") and cancels the Context, interrupting any in-flight call. Idempotent: a run already halted keeps its original reason.
func (*Run) Close ¶
func (r *Run) Close()
Close releases the context resources. Safe to call multiple times. It does not itself halt the run's accounting; use Cancel for the kill switch.
func (*Run) Context ¶
Context returns the run's context. Pass it to every provider/tool call so the kill switch and time budget can interrupt work in flight.
func (*Run) Elapsed ¶
Elapsed returns the logical wall-clock time since the run started, per the run's clock.
func (*Run) PreStep ¶
PreStep registers the start of a new loop iteration. Call it before doing the work of a step. It enforces the time and loop budgets and refuses to start an iteration the budget can't afford. Returns *HaltError if the run is (now) halted; the caller must stop the loop.
func (*Run) RecordUsage ¶
RecordUsage adds a completed call's usage to the ledger and re-evaluates budgets. Returns *HaltError if this usage crossed a token, dollar, or time budget — the run is then halted and its Context cancelled.
func (*Run) Status ¶
func (r *Run) Status() (Usage, HaltReason)
Status returns a snapshot of usage and the current halt reason (HaltNone if running).
Source Files