Documentation
¶
Overview ¶
Package toolorch provides Codex-inspired tool orchestration helpers for autonomous runs: sampling step freeze, approval cache, and deny breakers. OS sandbox / escalate remain host responsibilities.
Index ¶
- func RememberAllow(store ApprovalStore, runID, tool string, input json.RawMessage)
- func RememberDeny(store ApprovalStore, runID, tool string, input json.RawMessage)
- func TripError(limit, count int) error
- type ApprovalKey
- type ApprovalRequest
- type ApprovalStore
- type AttemptResult
- type Decision
- type DenyBreaker
- type MemoryApprovalStore
- type SamplingStepContext
- type StoreOrchestrator
- type ToolOrchestrator
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RememberAllow ¶
func RememberAllow(store ApprovalStore, runID, tool string, input json.RawMessage)
RememberAllow caches an allow decision after successful human approval.
func RememberDeny ¶
func RememberDeny(store ApprovalStore, runID, tool string, input json.RawMessage)
RememberDeny caches a deny decision after human rejection.
Types ¶
type ApprovalKey ¶
type ApprovalKey string
ApprovalKey uniquely identifies a tool+input pair within a run/session.
func Key ¶
func Key(tool string, input json.RawMessage) ApprovalKey
Key builds a stable approval key from tool name and canonical JSON input.
type ApprovalRequest ¶
type ApprovalRequest struct {
RunID string
Tool string
Input json.RawMessage
PauseRequired bool
}
ApprovalRequest is the input to DecideApproval.
type ApprovalStore ¶
type ApprovalStore interface {
Get(runID string, key ApprovalKey) (Decision, bool)
Put(runID string, key ApprovalKey, decision Decision)
Clear(runID string)
}
ApprovalStore caches allow/deny decisions so repeated HITL prompts for the same key can be skipped within a run.
type AttemptResult ¶
type AttemptResult struct {
DeniedBySandbox bool
// EscalateRequested asks the orchestrator/host path to re-prompt for a
// higher-privilege attempt. Default library orchestrator records nothing.
EscalateRequested bool
}
AttemptResult is reported by the host after a tool attempt. Sandbox denial is host-owned; the library does not implement OS sandboxing.
type Decision ¶
type Decision string
Decision is a cached approval outcome for a tool invocation key.
type DenyBreaker ¶
type DenyBreaker struct {
// contains filtered or unexported fields
}
DenyBreaker tracks consecutive HITL/tool approval denials per run and trips when the limit is reached. Orthogonal to doom_loop_limit (tool input thrash).
func NewDenyBreaker ¶
func NewDenyBreaker(limit int) *DenyBreaker
NewDenyBreaker creates a breaker. Limit <= 0 disables tripping.
func (*DenyBreaker) Limit ¶
func (b *DenyBreaker) Limit() int
Limit returns the configured consecutive-deny threshold.
func (*DenyBreaker) RecordAllow ¶
func (b *DenyBreaker) RecordAllow(runID string)
RecordAllow resets the consecutive deny counter after a successful approval path.
func (*DenyBreaker) RecordDeny ¶
func (b *DenyBreaker) RecordDeny(runID string) (tripped bool, count int)
RecordDeny increments the consecutive deny counter. Returns true when tripped.
type MemoryApprovalStore ¶
type MemoryApprovalStore struct {
// contains filtered or unexported fields
}
MemoryApprovalStore is an in-process ApprovalStore.
func NewMemoryApprovalStore ¶
func NewMemoryApprovalStore() *MemoryApprovalStore
NewMemoryApprovalStore creates an empty store.
func (*MemoryApprovalStore) Clear ¶
func (s *MemoryApprovalStore) Clear(runID string)
Clear drops all cached decisions for runID.
func (*MemoryApprovalStore) Get ¶
func (s *MemoryApprovalStore) Get(runID string, key ApprovalKey) (Decision, bool)
Get returns a cached decision.
func (*MemoryApprovalStore) Put ¶
func (s *MemoryApprovalStore) Put(runID string, key ApprovalKey, decision Decision)
Put caches a decision. DecisionPause is ignored (not durable).
type SamplingStepContext ¶
type SamplingStepContext struct {
AdvertisedTools []string
// contains filtered or unexported fields
}
SamplingStepContext freezes the tool advertisement view for one sampling step. Tool dispatch must honor Allows so "tools the model saw" cannot drift from "tools the runtime will execute" within the same step.
func FreezeSamplingStepContext ¶
func FreezeSamplingStepContext(specs []llm.ToolSpec) SamplingStepContext
FreezeSamplingStepContext captures the advertised tool names from specs.
func (SamplingStepContext) Allows ¶
func (s SamplingStepContext) Allows(tool string) bool
Allows reports whether tool was advertised in this sampling step.
func (SamplingStepContext) Frozen ¶
func (s SamplingStepContext) Frozen() bool
Frozen reports whether a non-empty advertisement set was captured.
type StoreOrchestrator ¶
type StoreOrchestrator struct {
Store ApprovalStore
}
StoreOrchestrator is the default library orchestrator: approval cache only.
func NewStoreOrchestrator ¶
func NewStoreOrchestrator(store ApprovalStore) *StoreOrchestrator
NewStoreOrchestrator wraps an ApprovalStore.
func (*StoreOrchestrator) AfterAttempt ¶
func (o *StoreOrchestrator) AfterAttempt(ctx context.Context, runID, tool string, input json.RawMessage, result AttemptResult) error
AfterAttempt is a no-op for the store-backed orchestrator (sandbox is host-owned).
func (*StoreOrchestrator) DecideApproval ¶
func (o *StoreOrchestrator) DecideApproval(ctx context.Context, req ApprovalRequest) (Decision, error)
DecideApproval returns a cached allow/deny, or DecisionPause when HITL is still required.
type ToolOrchestrator ¶
type ToolOrchestrator interface {
DecideApproval(ctx context.Context, req ApprovalRequest) (Decision, error)
AfterAttempt(ctx context.Context, runID, tool string, input json.RawMessage, result AttemptResult) error
}
ToolOrchestrator unifies approval cache lookup before execute and optional post-attempt hooks. Nil orchestrator means the runtime uses built-in HITL only.
Source Files