approval

package
v0.32.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

View Source
const DefaultTimeout = 30 * time.Minute

DefaultTimeout bounds a require_approval wait when the plugin's require_approval.timeout key is unset. Without it an unanswered prompt would hold the gated action (and, for a tool call, the turn) forever.

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 ParseTimeout added in v0.31.0

func ParseTimeout(raw any) (d time.Duration, ok bool)

ParseTimeout reads a require_approval.timeout config value and returns the wait bound the memory plugins share: unset (nil or "") is DefaultTimeout; any zero duration ("0", "0s") disables the deadline and returns 0; a positive Go duration string is used as-is. A malformed, negative or non-string value returns DefaultTimeout with ok=false so the caller can log a warning and keep booting.

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. On expiry the helper
	// emits hitl.cancel for the request so transports dismiss the prompt;
	// callers must declare "hitl.cancel" in Emissions().
	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
	// CallID, when set, is forwarded as HITLRequest.CallID: the ID of the
	// tool call the gated action belongs to, so nexus.control.hitl cancels
	// the request if that call times out. Optional.
	CallID 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