Documentation
¶
Overview ¶
Package approval binds durable user decisions to exact coding operations.
Index ¶
- Variables
- type Choice
- type Controller
- func (c *Controller) BeforeTool(ctx context.Context, info agent.ToolCallInfo) agent.ToolDecision
- func (c *Controller) Reconcile(ctx context.Context, sink execution.Sink) (State, error)
- func (c *Controller) Resolve(ctx context.Context, resolution Resolution, sink execution.Sink) (State, error)
- func (c *Controller) SetPendingResultHook(hook PendingResultHook)
- func (c *Controller) Tool(name string) (agent.Tool, bool)
- type Error
- type Handler
- type Journal
- type Kind
- type PendingResultHook
- type PendingRunner
- type Resolution
- type Resolver
- type Review
- type State
- type Unknown
Constants ¶
This section is empty.
Variables ¶
var ( // ErrApprovalRequired means a controlled operation needs an interactive decision. ErrApprovalRequired = &Error{message: "coding approval: user approval required", code: "approval_required"} // ErrOutcomeUnknown means an earlier operation may have run and cannot be replayed automatically. ErrOutcomeUnknown = &Error{message: "coding approval: command outcome is unknown", code: "outcome_unknown"} // ErrInvalidResolution means the decision is stale or invalid for the current state. ErrInvalidResolution = &Error{message: "coding approval: invalid resolution", code: "invalid_resolution"} // ErrJournalCorrupt means approval lifecycle data failed strict replay. ErrJournalCorrupt = &Error{message: "coding approval: journal lifecycle is malformed", code: "journal_corrupt"} // ErrDenied means policy or the user rejected the operation. ErrDenied = &Error{message: "coding approval: command denied", code: "approval_denied"} )
Functions ¶
This section is empty.
Types ¶
type Controller ¶
type Controller struct {
// contains filtered or unexported fields
}
Controller owns every registerable wrapper for approval-controlled tools.
func New ¶
func New( ws workspace.Workspace, journal Journal, resolver Resolver, pending PendingRunner, policy execution.Policy, executor *execution.Executor, handlers ...Handler, ) (*Controller, error)
New constructs a controller for one durable session and workspace.
func (*Controller) BeforeTool ¶
func (c *Controller) BeforeTool(ctx context.Context, info agent.ToolCallInfo) agent.ToolDecision
BeforeTool is the agent.WithBeforeTool gate for controlled calls.
func (*Controller) Reconcile ¶
Reconcile repairs durable completions and processes pending calls until the first review or unknown barrier.
func (*Controller) Resolve ¶
func (c *Controller) Resolve( ctx context.Context, resolution Resolution, sink execution.Sink, ) (State, error)
Resolve applies a user decision to the currently displayed durable state.
func (*Controller) SetPendingResultHook ¶
func (c *Controller) SetPendingResultHook(hook PendingResultHook)
SetPendingResultHook installs the hook applied after an approval-paused controlled call executes. Call it during runtime setup, before the controller is used. Passing nil clears the hook.
type Error ¶
type Error struct {
// contains filtered or unexported fields
}
Error is a stable approval error with a coding-tool result code.
func (*Error) ToolErrorCode ¶
ToolErrorCode lets coding tools preserve the stable error class without a package dependency on approval.
type Handler ¶
type Handler interface {
Decl() ai.Tool
Operation(context.Context, agent.ToolCall) (execution.OperationSpec, error)
Render(execution.Result, error) ([]ai.Part, error)
}
Handler prepares one controlled tool and renders bounded execution results. A Handler is intentionally not an agent.Tool.
type Journal ¶
type Journal interface {
Path() []harness.Entry
Pending() ([]ai.ToolCallPart, error)
AppendCustom(string, ai.JSON) (string, error)
}
Journal is the durable session surface required by Controller.
type PendingResultHook ¶
PendingResultHook observes and may replace the result of a controlled tool call after it resumes from the approval boundary. It runs only for calls executed by executePending; direct calls are handled by the agent's normal after-tool hook chain.
type PendingRunner ¶
type PendingRunner interface {
RunPending(context.Context, agent.ToolCall, execution.Sink) ([]ai.Part, error)
}
PendingRunner executes an uncontrolled pending call with the application's immutable tool/hook snapshot.
type Resolution ¶
type Resolution struct {
RequestID string
Choice Choice
// Reason is persisted only with a denial so a durable policy decision can
// render the same model-visible result after recovery.
Reason string
}
Resolution applies one choice to the currently displayed request.
type Resolver ¶
type Resolver interface {
ResolveToolCalls(...agent.ToolResolution) error
}
Resolver durably answers selected pending calls.
type State ¶
State is one immutable projection of durable approval state.
func (State) NonInteractiveError ¶
NonInteractiveError projects a durable state into the fail-fast contract used by non-interactive callers. Interactive callers should render Review or Unknown and pass an explicit Resolution instead.
type Unknown ¶
type Unknown struct {
RequestID string
CallID string
Tool string
Fingerprint execution.Fingerprint
Attempt int
Pending bool
Reason string
Recoverable bool
}
Unknown describes an operation that may have started without a durable result. Pending false means the original arguments are unavailable.
Source Files