Documentation
¶
Overview ¶
Package toolpolicy defines transport-neutral execution-policy contracts.
Index ¶
- Constants
- func CanonicalJSON(raw string, target any) (string, error)
- func Fingerprint(value string) string
- func NewOperationID() (string, error)
- func RunIDFromContext(ctx context.Context) string
- func StableID(parts ...string) string
- func WithBillableIntent(ctx context.Context, intent BillableIntent) context.Context
- func WithRunID(ctx context.Context, runID string) context.Context
- type BillableIntent
- type BillableIntentPreparer
- type UsageLedger
- type UsageReservation
Constants ¶
const ( ApprovalBillableExternal = "billable_external" CapabilityImageGenerate = "image.generate" CapabilityWebSearch = "web.search" )
Variables ¶
This section is empty.
Functions ¶
func CanonicalJSON ¶
CanonicalJSON rejects unknown fields and trailing values, and returns a stable compact encoding suitable for binding an approval to arguments.
func Fingerprint ¶
func NewOperationID ¶
NewOperationID returns a host-owned dispatch identity. Model-supplied tool call IDs are correlation labels and may repeat across turns or replays, so they must never key a durable quota journal.
func RunIDFromContext ¶
func WithBillableIntent ¶
func WithBillableIntent(ctx context.Context, intent BillableIntent) context.Context
Types ¶
type BillableIntent ¶
type BillableIntent struct {
OperationID string `json:"operation_id"`
ToolCallID string `json:"tool_call_id"`
CapabilityKey string `json:"capability_key"`
Provider string `json:"provider"`
Model string `json:"model"`
CredentialFingerprint string `json:"credential_fingerprint"`
ConfigEpoch string `json:"config_epoch"`
NormalizedArgs string `json:"normalized_args"`
Count int `json:"count"`
IdempotencyKey string `json:"idempotency_key"`
}
BillableIntent is the immutable authorization and dispatch identity for one provider operation. It is prepared from the post-hook arguments, approved, and then consumed by the tool endpoint from the same context.
func BillableIntentFromContext ¶
func BillableIntentFromContext(ctx context.Context) (BillableIntent, bool)
type BillableIntentPreparer ¶
type BillableIntentPreparer interface {
PrepareBillableIntent(ctx context.Context, argsJSON, toolCallID string) (BillableIntent, error)
}
BillableIntentPreparer is implemented by tools whose endpoint can create an externally billable side effect. The approval middleware calls it after PreToolUse rewrites and before any approval shortcut is evaluated.
type UsageLedger ¶
type UsageLedger struct {
// contains filtered or unexported fields
}
UsageLedger atomically reserves provider calls before dispatch. The durable generation journal remains the source of truth; initialDispatched is rebuilt from it whenever an agent/tool is reconstructed.
func NewUsageLedger ¶
func NewUsageLedger(maxPerRun, maxPerSession, initialDispatched int) *UsageLedger
func (*UsageLedger) Reserve ¶
func (l *UsageLedger) Reserve(runID, operationID string) (*UsageReservation, error)
func (*UsageLedger) ReserveRun ¶
func (l *UsageLedger) ReserveRun(runID, operationID string) (*UsageReservation, error)
ReserveRun protects the process-local per-turn limit while leaving the hard per-session decision to Recorder's cross-process dispatch transaction. Two processes necessarily have different in-memory ledgers, so checking a cached sessionCount here can never be the security boundary.
func (*UsageLedger) ResetSession ¶
func (l *UsageLedger) ResetSession(initialDispatched int)
ResetSession switches a transport-owned ledger to another idle session. Callers must only do this between runs (for example TUI session resume).
func (*UsageLedger) SetLimits ¶
func (l *UsageLedger) SetLimits(maxPerRun, maxPerSession int)
SetLimits updates policy limits without replacing the session-scoped ledger. Existing dispatched and reserved calls remain consumed.
type UsageReservation ¶
type UsageReservation struct {
// contains filtered or unexported fields
}
func (*UsageReservation) Commit ¶
func (r *UsageReservation) Commit()
Commit makes the reservation sticky. It is called only after the synchronous dispatch_attempted journal append succeeds.
func (*UsageReservation) Release ¶
func (r *UsageReservation) Release()
Release rolls back a pre-dispatch reservation. A committed reservation can never be released, even if the provider call later fails.
Source Files