Documentation
¶
Overview ¶
Package runs manages governed runs — the identity, budget, and lifecycle around a governor.Run. It is the shared state used by both the OpenAI-compatible proxy (Surface 1) and the public /v1/runs API.
Runs are held in memory for fast live enforcement (the governor is the source of truth for limits) and written through to a storage.Store so they are durable and auditable, and so a crashed run can be resumed (step 5). Persistence is best-effort: a write failure is logged but never fails the user's call, because enforcement has already happened in memory. Persistence writes use a background context, never the run's context (which is cancelled on halt).
Index ¶
- type Call
- type CreateOptions
- type Manager
- func (m *Manager) Checkpoint(runID, name string, payload map[string]any) error
- func (m *Manager) Create(opts CreateOptions) *Run
- func (m *Manager) Get(rid string) (*Run, bool)
- func (m *Manager) GetOrCreate(rid string) *Run
- func (m *Manager) List() []View
- func (m *Manager) Reload(ctx context.Context) (int, error)
- func (m *Manager) Store() storage.Store
- func (m *Manager) WithStore(store storage.Store, log *slog.Logger) *Manager
- type Run
- type View
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Call ¶
type Call struct {
StepIndex int32
Provider string
Model string
PromptTokens int64
CompletionTokens int64
Dollars float64
Priced bool
ResponseID string
}
Call is a completed model call to record against a run — meters the governor and appends an auditable cost-ledger entry.
type CreateOptions ¶
type CreateOptions struct {
ID string // optional; a UUID is minted when empty
Name string
Budget *governor.Budget // nil → manager default
PolicyRef string // optional policy bundle name applied to this run
Metadata map[string]string
}
CreateOptions configures a new run.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager owns the set of live runs. Safe for concurrent use.
func NewManager ¶
NewManager constructs an in-memory Manager. defaultBudget is applied to runs created without an explicit budget. Attach durability with WithStore.
func (*Manager) Checkpoint ¶
Checkpoint records a crash-resumable checkpoint for a run with an opaque payload (used by the SDK's runtime.checkpoint). The usage snapshot is taken from the governor; the payload is persisted verbatim.
func (*Manager) Create ¶
func (m *Manager) Create(opts CreateOptions) *Run
Create starts a new governed run and registers it.
func (*Manager) GetOrCreate ¶
GetOrCreate returns the run with the given id, lazily creating it under the default budget if unknown. This is the proxy path: a client groups calls into a run by sending a stable run-id header; the first call materializes the run.
On a cache miss it first consults the store: a run with that id may already exist there — e.g. one that halted before a restart (Reload restores only running runs). Such a run is restored as-is, so a terminal/over-budget run stays halted and keeps refusing work instead of being handed a fresh, default-budget run for the reused id. Only a genuinely unknown id mints a new run. (#29)
func (*Manager) Reload ¶
Reload restores non-terminal ("running") runs from the store into memory, reconstructing each governor with the usage it had already spent. This is crash-resume: after a SIGKILL and restart, a run keeps enforcing against its accumulated budget instead of starting fresh. Returns the number reloaded.
type Run ¶
type Run struct {
ID string
Name string
Budget governor.Budget
PolicyRef string // name of the policy bundle this run was created under ("" = none)
Metadata map[string]string
// contains filtered or unexported fields
}
Run is a governed run: identity and metadata wrapped around a live governor.
func (*Run) BeginStep ¶
BeginStep registers a new loop iteration (enforcing loop + time budgets) and returns the 1-based step index. Returns a *governor.HaltError if the run can't start another step.
func (*Run) CanProceed ¶
CanProceed enforces the hard ceiling immediately before a model/tool call.
func (*Run) HaltReason ¶
func (r *Run) HaltReason() governor.HaltReason
HaltReason returns the current halt reason (HaltNone if running).
func (*Run) RecordCall ¶
RecordCall meters a completed model call in the governor and writes through to the cost ledger + step + run rows. Returns a *governor.HaltError if this call crossed a budget.
type View ¶
type View struct {
ID string
Name string
Status string
PolicyRef string
Budget governor.Budget
Usage governor.Usage
HaltReason governor.HaltReason
CreatedAt time.Time
UpdatedAt time.Time
Metadata map[string]string
}
View is an immutable snapshot of a run for reporting / API serialization.
Source Files