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
- func CheckNameCollisions(subAgents map[string]bool, pred Predicate, policies []ToolPolicy) []string
- func DeriveSubSessionID(parentSessionID, subName, callID string) string
- func IsConfirmationApproved(resp map[string]any) bool
- func New(cfg Config) (*plugin.Plugin, error)
- func NewPlugin(cfg Config) (*plugin.Plugin, error)
- func Overrides(logger *slog.Logger, policies []ToolPolicy) map[string]bool
- func SubAgentNames(root agent.Agent) map[string]bool
- type Class
- type Config
- type DanglingIntent
- type DanglingScan
- type IntentStore
- type Predicate
- type ReadOnlyHint
- type SubRunRecorder
- type SubRunRecorderConfig
- type SubRunnerFunc
- type SubSessionScanner
- type ToolPolicy
Constants ¶
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 ¶
DeriveSubSessionID computes the deterministic child session ID used by synchronous subagent dispatches ("<parent>:sub:<subName>:<callID>").
func IsConfirmationApproved ¶
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 ¶
New builds the outbox as an ADK runner plugin. Attach it via runner.Config.PluginConfig at every runner construction site.
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 ¶
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 ¶
Predicate classifies a tool by name. See NewPredicate.
func NewPredicate ¶
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 ¶
ReadOnlyHint reports the `readOnlyHint` an MCP server published for toolName. annotated is false when nothing has published annotations for that name.
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.
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>") and returns any dangling mutating intents inside them.
type ToolPolicy ¶
ToolPolicy mirrors per-tool mutation policy overrides.