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 DetachDecider
- type DetachedHandler
- type Error
- type Handler
- type Journal
- type Kind
- type PendingResultHook
- type PendingRunner
- type PreparedExecution
- 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 DetachDecider ¶ added in v0.1.9
type DetachDecider interface {
// Detaches reports whether this call takes the detached path.
Detaches(call agent.ToolCall) bool
}
DetachDecider is implemented by a DetachedHandler that detaches only for some calls. The controller consults it before taking the detached branch; a call it answers false for runs through the synchronous path, on the same prepared execution. A handler that does not implement it always detaches, which is the monitor's contract.
type DetachedHandler ¶ added in v0.1.9
type DetachedHandler interface {
Handler
// Detach owns the prepared operation: it either runs it once, from any
// goroutine, or closes it before returning. ctx is the Tool call's own
// context, which ends when the call returns; a detached run must strip its
// cancellation rather than derive from it directly.
Detach(ctx context.Context, call agent.ToolCall, prepared PreparedExecution) ([]ai.Part, error)
}
DetachedHandler is implemented by a controlled handler whose process run outlives the Tool call that started it. The controller prepares and journals the operation exactly as it does for any controlled call, then hands the prepared execution to the handler and returns the handler's receipt instead of waiting for the process.
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 PreparedExecution ¶ added in v0.1.9
type PreparedExecution interface {
Run(context.Context, execution.Sink) (execution.Result, error)
Close() error
}
PreparedExecution owns one single-use execution plan. Run consumes and closes it; Close abandons it before Run.
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.