Documentation
¶
Overview ¶
Package approval is the shared human-in-the-loop wrapper used by the memory plugins (longterm, vector, compaction) that gain an opt-in require_approval config.
Each plugin owns its own match logic + payload construction. This package only handles the bus dance: subscribe to hitl.responded, emit hitl.requested, block until the matching response (or timeout) arrives, then unsubscribe and return the typed response.
Per the project rule "extract on the second real caller" — three real callers exist (one per memory plugin), so the helper is justified. It is deliberately small: no glob matching, no payload trimming, no choice list construction. Those concerns live with the caller because they vary per plugin.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var DefaultChoices = []events.HITLChoice{ {ID: "allow", Label: "Approve", Kind: events.ChoiceAllow}, {ID: "reject", Label: "Reject", Kind: events.ChoiceReject}, }
DefaultChoices is the canonical allow/reject pair memory approvals use. Callers may pass a custom slice if they want a third option (e.g. an "edit" choice), but in this PR every caller uses these two.
Functions ¶
func RequestApproval ¶
RequestApproval emits hitl.requested and blocks until a matching hitl.responded arrives, the timeout elapses, or ctx is cancelled.
The boolean return is true when the response indicates "allow" (the choice's Kind == ChoiceAllow, or — when Kind is unset on a custom choice — the choice ID is "allow"). Rejected, cancelled, and timed-out requests return false. Callers decide what to do with the result.
The error is non-nil only on internal failure (nil bus, emit failure returned by the bus). A timeout is not an error — it returns a Cancelled response with allowed=false.
Types ¶
type Request ¶
type Request struct {
// Bus is the event bus used to emit hitl.requested and observe
// hitl.responded. Required.
Bus engine.EventBus
// Logger is used for warn-level diagnostic messages (rejections,
// edited-payload warnings, deadline expiry). Required.
Logger *slog.Logger
// PluginID is the dotted ID of the requesting plugin (e.g.
// "nexus.memory.longterm"). Set as RequesterPlugin on the request.
PluginID string
// ActionKind is the dotted action discriminator (e.g.
// "memory.longterm.write"). Set verbatim on the request.
ActionKind string
// ActionRef is the opaque payload describing the pending action;
// surfaced verbatim to operators. Callers should truncate large
// content fields before passing them in.
ActionRef map[string]any
// Prompt is the literal text shown to the operator. Required.
Prompt string
// Choices is the list of options. When nil, DefaultChoices is used.
Choices []events.HITLChoice
// DefaultChoiceID is the choice picked on deadline expiry. When
// empty, no default is set; expiry resolves with Cancelled=true.
DefaultChoiceID string
// Timeout, when > 0, sets a Deadline on the request and aborts the
// in-process wait if no response arrives in time.
Timeout time.Duration
// SessionID, when set, is forwarded as HITLRequest.SessionID for
// out-of-band CLI tooling. Optional.
SessionID string
// TurnID, when set, is forwarded as HITLRequest.TurnID so turn-scoped
// transports (nexus.io.agui, nexus.io.a2a) can bind the question — and
// the run that resumes it — to the agent turn that is parked on it.
// Set it whenever the gated action came from a turn (a tool call);
// leave it empty for actions that belong to no turn. Optional.
TurnID string
}
Request is the input to RequestApproval.