effects

package
v3.1.0-dev.3 Latest Latest
Warning

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

Go to latest
Published: Nov 3, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

Documentation

Overview

Package effects implements the recorded-effect outbox (docs/durable-write-gate-design.md): the runtime guard that makes mutating-tool re-execution ambiguity visible and blocking instead of silent.

The session event log IS the outbox — a durable FunctionCall event is the intent record, its paired FunctionResponse the completion record, both keyed by (session, invocation, function-call ID). This package adds no storage; it only reads history and refuses or replays calls.

Index

Constants

View Source
const SyntheticRepairMetadataKey = "core_agent_synthetic_repair"

SyntheticRepairMetadataKey marks synthetic FunctionResponse events appended by pkg/agent/tail_repair.go so pairScan never mistakes LLM transcript repair for a completed mutating tool call (#1400).

Variables

This section is empty.

Functions

func CheckNameCollisions

func CheckNameCollisions(subAgents map[string]bool, pred Predicate, policies []ToolPolicy) []string

CheckNameCollisions reports composed sub-agent names that also name a mutating- or spawning-class tool.

func DeriveSubSessionID

func DeriveSubSessionID(parentSessionID, subName, callID string) string

DeriveSubSessionID computes the deterministic child session ID used by synchronous subagent dispatches ("<parent>:sub:<subName>:<callID>").

func IsBuiltinOrControl

func IsBuiltinOrControl(name string) bool

IsBuiltinOrControl reports whether name is an engine control-flow call or a registered built-in/harness tool (as opposed to a namespaced MCP tool).

func IsConfirmationApproved

func IsConfirmationApproved(resp map[string]any) bool

IsConfirmationApproved reports whether an adk_request_confirmation FunctionResponse.Response map represents an operator approval (accounting for both top-level {"confirmed": true, "payload": ...} and JSON-string wrapped {"response": "{\"confirmed\":true,\"payload\":...}"} shapes, and rejecting when payload.verdict == "reject").

func New

func New(cfg Config) (*plugin.Plugin, error)

New builds the outbox as an ADK runner plugin. Attach it via runner.Config.PluginConfig at every runner construction site.

func NewPlugin

func NewPlugin(cfg Config) (*plugin.Plugin, error)

NewPlugin is an alias for New.

func Overrides

func Overrides(logger *slog.Logger, policies []ToolPolicy) map[string]bool

Overrides flattens workload tool_catalog per-tool policies into the override map NewPredicate consumes, logging each applied override.

func SubAgentNames

func SubAgentNames(root agent.Agent) map[string]bool

SubAgentNames walks the agent tree from root and returns every composed agent's name — the delegation-call exclusion set for Config.SubAgentNames.

Types

type Class

type Class int

Class is a tool's effect classification under the mutation predicate.

const (
	// ClassReadOnly tools never pay the outbox check.
	ClassReadOnly Class = iota

	// ClassMutating tools get intent/completion records in the log and
	// are refused in ambiguous-effect mode. It is the default for an
	// unknown tool (default-deny-unknown).
	ClassMutating

	// ClassSpawning tools start sub-runs whose inner tool calls are
	// governed by the sub-run's own outbox or inspected via
	// SubSessionScanner.
	ClassSpawning
)

type Config

type Config struct {
	// Predicate classifies tools; required.
	Predicate Predicate

	// SubAgentNames is the set of agent names composed under the
	// runner's root (see SubAgentNames).
	SubAgentNames map[string]bool

	// ExternalDangling returns intents this process recorded for the
	// session outside its event log. Optional.
	ExternalDangling func(ctx context.Context, sessionID string) []DanglingIntent

	// SubSessionScanner inspects deterministic child sessions for
	// dangling ClassSpawning calls. Optional; nil fails closed on any
	// dangling spawn.
	SubSessionScanner SubSessionScanner

	// AckedAt returns the operator's effects-acknowledgement watermark
	// for a session, if one exists. Optional; nil means no acks.
	AckedAt func(ctx context.Context, sessionID string) (time.Time, bool)

	// Logger for refusals, replays, and mode transitions. Optional.
	Logger *slog.Logger
}

Config configures the outbox plugin.

type DanglingIntent

type DanglingIntent struct {
	ToolName     string
	CallID       string
	InvocationID string
	Timestamp    time.Time
	EventIndex   int
}

DanglingIntent is a durable mutating (or spawning) FunctionCall from a prior attempt with no completion in the log.

func MutatingCalls

func MutatingCalls(ev *session.Event, pred Predicate, subAgents map[string]bool) (raised []DanglingIntent, completed []string)

MutatingCalls splits one event into the mutating- or spawning-class FunctionCalls it raises and the call IDs its FunctionResponses complete.

type DanglingScan

type DanglingScan struct {
	Mutating           []DanglingIntent
	Repairable         []DanglingIntent
	Deferred           []DanglingIntent
	LastCallEventIndex int
}

DanglingScan splits a session's unpaired FunctionCalls into the three buckets the boot-time auto-resume pass acts on.

func ScanDangling

func ScanDangling(events session.Events, pred Predicate, subAgents map[string]bool) DanglingScan

ScanDangling classifies a session's unpaired FunctionCalls for the auto-resume eligibility and repair decisions.

func (DanglingScan) Unacked

func (d DanglingScan) Unacked(ackedAt time.Time) []DanglingIntent

Unacked returns the Mutating intents whose Timestamp is strictly after ackedAt.

func (DanglingScan) WithExternal

func (s DanglingScan) WithExternal(external []DanglingIntent) DanglingScan

WithExternal folds intents recorded outside this session's event log into a scan.

type IntentStore

type IntentStore interface {
	RecordSubRunIntents(ctx context.Context, sessionID, specialist string, intents []DanglingIntent) error
	CompleteSubRunIntents(ctx context.Context, sessionID string, callIDs []string) error
}

IntentStore persists a sub-run's mutating intents somewhere the workload's own session can be scanned for them later.

type Predicate

type Predicate func(toolName string) Class

Predicate classifies a tool by name. See NewPredicate.

func NewPredicate

func NewPredicate(overrides map[string]bool) Predicate

NewPredicate builds the mutation predicate with no annotation source: every MCP tool is unclassified and takes the default-deny-unknown answer. See NewPredicateWithHints for the wired form.

func NewPredicateWithHints

func NewPredicateWithHints(overrides map[string]bool, hint ReadOnlyHint) Predicate

NewPredicateWithHints builds the mutation predicate. In order: control surfaces are read-only; per-tool overrides decide next; builtins use their registered class; an MCP tool its server annotated is classified by that annotation; and everything left over defaults to mutating (default-deny-unknown).

type ReadOnlyHint

type ReadOnlyHint func(toolName string) (readOnly, annotated bool)

ReadOnlyHint reports the `readOnlyHint` an MCP server published for toolName. annotated is false when nothing has published annotations for that name.

type ReadOnlyPredicate

type ReadOnlyPredicate = Predicate

ReadOnlyPredicate is an alias for Predicate used by auto-resume and auto-continue configuration structs.

type SubRunRecorder

type SubRunRecorder struct {
	// contains filtered or unexported fields
}

SubRunRecorder writes one dispatch's mutating intents and completions to an IntentStore.

func NewSubRunRecorder

func NewSubRunRecorder(cfg SubRunRecorderConfig) (*SubRunRecorder, error)

NewSubRunRecorder builds the recording half of the dispatch seam.

func (*SubRunRecorder) Observe

func (r *SubRunRecorder) Observe(ev *session.Event) error

Observe records the mutating intents an event raises and pairs the ones it completes.

type SubRunRecorderConfig

type SubRunRecorderConfig struct {
	Store         IntentStore
	SessionID     string
	Specialist    string
	Predicate     Predicate
	SubAgentNames map[string]bool
	Logger        *slog.Logger
}

SubRunRecorderConfig configures a recorder.

type SubRunnerFunc

type SubRunnerFunc func(ctx context.Context, userID, sessionID string, msg *genai.Content, cfg agent.RunConfig, opts ...runner.RunOption) iter.Seq2[*session.Event, error]

SubRunnerFunc is the execution signature of runner.Runner.Run.

func WrapADKRunner

func WrapADKRunner(r *runner.Runner, rec *SubRunRecorder) SubRunnerFunc

WrapADKRunner wraps *runner.Runner.Run with rec.

func WrapSubRunner

func WrapSubRunner(run SubRunnerFunc, rec *SubRunRecorder) SubRunnerFunc

WrapSubRunner wraps a sub-runner's Run method so any mutating intent and completion emitted by the sub-runner is recorded via rec.

type SubSessionScanner

type SubSessionScanner func(ctx context.Context, parentSessionID string, spawn DanglingIntent) (dangling []DanglingIntent, inspected bool)

SubSessionScanner inspects a deterministic child session for a dangling ClassSpawning call and returns any dangling mutating calls inside that child session. When inspected is true, the parent's dangling spawn is replaced by the returned child intents; when false, the parent spawn fails closed as dangling itself.

func SubSessionScannerFor

func SubSessionScannerFor(svc session.Service, appName, userID string, pred Predicate, subAgents map[string]bool) SubSessionScanner

SubSessionScannerFor builds a SubSessionScanner over svc that locates deterministic child sessions ("<parentSID>:sub:<subName>:<callID>", "<parentSID>:sub:<subName>", or "<parentSID>:sub:bg.<bgID>" for background spawns) and returns any dangling mutating intents inside them.

type ToolPolicy

type ToolPolicy struct {
	Name     string
	Mutating *bool
}

ToolPolicy mirrors per-tool mutation policy overrides.

Jump to

Keyboard shortcuts

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