approval

package
v0.30.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 31, 2026 License: MIT Imports: 9 Imported by: 0

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

View Source
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

func RequestApproval(ctx context.Context, req Request) (events.HITLResponse, bool, error)

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL