Documentation
¶
Overview ¶
Package toolhook holds the hooks by which a tool wrapper in this module (audit's AttenuatingSubAgent) takes part in the agent's engine without exported API: the agent checks for these interfaces, and only packages of this module can name them.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var CallGuard func(ctx context.Context) error
CallGuard, when set, is asked before every tool call reaches its tool, with the call's context: by the agent's base handler, where an error refuses the call, recorded as a known failure, and by a plan Tool node, where it fails the node; either way the tool is never called. The audit package sets it (in init) to refuse a call made under a bound grant that has expired, so a delegation cannot act past its grant's NotAfterUnix, however long its sub-run runs.
var CheckProvenanceName func(what, s string) error
CheckProvenanceName refuses a source or reason that agent.Untrusted, Trusted and TaintExempt would refuse (empty, over-long, not UTF-8, or with a non-printing character), with an error wrapping agent.ErrConfig that begins with what. The agent package sets it in init; plan calls it so a flow declaration is held to the rules of an agent's.
var CheckTaintPolicy func(p any) error
CheckTaintPolicy refuses a policy agent.WithTaintPolicy would refuse, where p is an agent.TaintPolicy: neither a Gate nor Refuse, both, or a Gate that is not a valid approval policy. The agent package sets it in init; plan calls it for a flow's policy.
var CheckTool func(t any) error
CheckTool refuses a tool the agent's New would refuse for how it wraps another (see agent.checkWrapper): a Compensator on its Unwrap chain, a timeout or another Safety over a sub-agent, an embedded tool whose approval gate or timeout its own spec hides, or a method of the old Tool method set that disagrees with the tool's spec (agent.checkOldMethods). The agent package sets it in init; plan calls it so a flow refuses what an agent refuses.
var WithIdentity func(ctx context.Context, actor, onBehalfOf, authorityRef string) context.Context
WithIdentity binds the acting identity (actor, on behalf of whom, under what authority) to ctx for the sub-run a tool wrapper starts, as a run's WithIdentity option binds a run's: the delegation's sub-run acts as the delegate, on behalf of the parent, under the child grant. The agent package sets it in init.
Functions ¶
This section is empty.
Types ¶
type RollbackBinder ¶
type RollbackBinder interface {
BindRollback(ctx context.Context, subRunID string) (context.Context, error)
}
RollbackBinder is a tool that wraps a sub-agent and runs the sub-run under a context of its own (a narrower grant, another identity). A saga rollback that recurses into the sub-run calls BindRollback first, so the sub-run's compensations run under the authority the delegation granted, never the parent's. subRunID is the sub-run the rollback walks; the wrapper reads what that sub-run journaled. An error stops the rollback, which reports the delegation uncompensated.
type Unrecorded ¶
type Unrecorded struct{ Err error }
Unrecorded is an error a tool wrapper of this module returns for a call that must leave nothing in the journal: not a result, not a saga failure. The run stops with Err, and a re-drive calls the tool again. AttenuatingSubAgent uses it when a delegation is resumed under authority other than it began with, or the bound grant it would mint from has expired, or it would mint a grant onto a sub-run that journaled no authority: the operator can bind the right grant and drive again, and the delegation continues rather than being failed for good. It also uses it when the store fails to read or write the delegation's authority, so a resume retries. (A journaled grant that has expired is a recorded failure, not this.) It is only for a tool whose call is safe to make again (the agent refuses nothing else for it; a side effect with an attempt marker halts on the re-drive, as any call that recorded nothing does).
func (*Unrecorded) Unwrap ¶
func (e *Unrecorded) Unwrap() error
Unwrap returns Err, so errors.Is sees its category.
Source Files