effects

package
v0.10.0 Latest Latest
Warning

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

Go to latest
Published: Oct 30, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Package effects implements the recorded-effect outbox (docs/durable-execution-design.md, "Recorded-effect outbox"): the runtime guard that makes mutating-tool re-execution ambiguity visible and blocking instead of silent, under mast's declared at-least-once contract.

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.

The guard ships as an ADK runner plugin so it sits at the one seam every tool execution crosses (Flow.callTool wraps MCP, builtin, and federation tools alike). All history reads happen once per turn in BeforeRun, off the invocation context's session — the per-call tool context structurally has no session access (its Session() is unconditionally nil in ADK v2.1.0), so the per-call checks consult the turn-start snapshot instead. The permission gate's runtime wiring will share this layer, with the outbox check running first (a replayed result performs no new effect and needs no fresh approval).

Index

Constants

This section is empty.

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. Such a name is ambiguous in the session log: ADK emits both a task delegation and a genuine tool call as a FunctionCall bearing the name, and the dangling scan excludes every FunctionCall named after a sub-agent (delegations are engine control flow, not effects — see Config.SubAgentNames). A real mutating tool sharing a sub-agent's name is therefore invisible to the outbox: a fail-open durability hole (gate finding N2). No scan-time heuristic can resolve the ambiguity — by name alone a delegation and a tool call are indistinguishable — so the collision must be fixed in the composition: rename the specialist or the tool. Both cmd/mast and the mast library entrypoints call this at construction and refuse on a non-empty result; a caller wiring its own root and outbox should do the same before New.

Only mutating/spawning tools matter: a read-only tool named after a sub-agent never dangles (scanHistory keeps only mutating/spawning unpaired calls), so a collision with one is harmless and is not reported.

Coverage is bounded by what is known by name at construction: mast's builtins, and the tool names an operator declared in tool_catalog.tools (classified through pred, so a nil-override entry still counts mutating by default-deny). tool_catalog.tools is an OVERRIDE list, not a tool inventory — its idiomatic use is to un-gate read-only tools, so a mutating tool an operator never listed there (the common case for MCP verbs) is not enumerable here and its collision is NOT caught. This reliably guards builtins and explicitly-declared tools; for everything else the authoring rule stands: do not name a specialist after a mutating tool. The returned names are sorted for a stable message.

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 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 (the audit-logged requirement from the mutation predicate's definition). Later entries win on duplicate names; the workload loader rejects duplicates so that only matters for hand-built maps.

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. The root's own name is included (harmless: a FunctionCall can never be named after the agent issuing it).

Types

type Class

type Class int

Class is a tool's effect classification under the mutation predicate (docs/orchestration-design.md, hitl_policy.on_mutation).

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 — and, until #447, that meant
	// every MCP tool: ADK's mcptoolset drops MCP's annotations
	// (convertTool copies name/description/schemas only), which was read
	// as making any other stance unimplementable.
	//
	// It was not. The annotations reach mast before that conversion, on
	// the tools/list response, and internal/mcp.Annotations captures them
	// there; a tool whose server published readOnlyHint=true is now
	// classified read-only through NewPredicateWithHints. The default is
	// unchanged for everything that stays unclassified, and operators
	// still pin either way with the workload tool_catalog override —
	// which is checked first, because an annotation is the far end of
	// the wire describing itself.
	ClassMutating

	// ClassSpawning tools start sub-runs whose inner tool calls this
	// process cannot individually guard from the spawn site (the
	// planner dispatch runner is a separate in-memory-session runner;
	// run_shape_* likewise when implemented). They carry no records of
	// their own but are refused in ambiguous-effect mode when they
	// arrive through the tool-execution seam. Note the containment
	// boundary: ADK's coordinator re-dispatch of an already-recorded
	// task delegation bypasses that seam — there, containment holds at
	// the inner-call level instead (the sub-run inherits the invocation
	// ID, so its own mutating tool calls are refused individually).
	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). ADK's coordinator emits task
	// delegations as FunctionCalls NAMED AFTER THE SUB-AGENT, and
	// deliberately leaves them unresolved across user turns (a
	// specialist asking a clarifying question, a HITL pause inside a
	// node) — engine control flow, not effects. Without this exclusion
	// the scan wedges mast's default composition on its happy path.
	SubAgentNames map[string]bool

	// ExternalDangling returns intents this process recorded for the
	// session OUTSIDE its event log — in practice the mutating calls a
	// planner dispatch made on its private sub-runner, which the outbox
	// plugin never saw and the log therefore never carried (#235; see
	// subrun.go). Merged into the turn snapshot before the ack filter, so
	// an operator's ack clears them the same way it clears the log's own.
	// Optional; nil means this host records none.
	ExternalDangling func(ctx context.Context, sessionID string) []DanglingIntent

	// AckedAt returns the operator's effects-acknowledgement watermark
	// for a session, if one exists (pkg/transcript reads it from the
	// companion ops row). Dangling intents at or before the watermark
	// are considered operator-acknowledged and do not trip
	// ambiguous-effect mode. 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 is the 0-based position of the carrying event among log
	// events with non-nil Content, in log order. It lets a consumer group
	// dangling calls by the event that raised them — the auto-resume
	// repair path (cmd/mast, #41) answers only the calls of a single
	// (the last) function-call event, ADK's single-call-event validation
	// constraint. The outbox itself ignores it.
	EventIndex int
}

DanglingIntent is a durable mutating (or spawning) FunctionCall from a prior attempt with no completion in the log — the call may or may not have executed, and the window between an external effect committing and its completion event persisting cannot be closed, only detected.

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.

The exclusions are pairScan's, for the same reasons and so the two cannot drift: an empty call ID cannot be keyed or paired, a long-running park is a pause rather than an effect, engine control calls are control flow, and a FunctionCall named after a composed agent is a task delegation.

Unlike pairScan this reads ONE event with no history behind it, which is all a sink ever has. Pairing across events is the store's job.

type DanglingScan

type DanglingScan struct {
	// Mutating are unpaired mutating- or spawning-class calls: their
	// effect may or may not have committed, so a session with ANY of them
	// is ineligible for auto-resume and is left for an operator ack
	// (regardless of the effects ack watermark — an ack suppresses the
	// outbox refusal but does not pair the call, and synthesizing a
	// response would falsely assert the effect did not happen).
	Mutating []DanglingIntent
	// Repairable are unpaired ordinary read-only calls (a read-only tool
	// cut off mid-execution). They carry no external effect, so the
	// daemon may answer them with a synthetic error FunctionResponse to
	// make the history provider-valid before re-running.
	Repairable []DanglingIntent
	// Deferred are unpaired excluded calls (sub-agent task delegations,
	// and defensively any control/long-running call): engine-reconstruct
	// or operator territory. The daemon must not synthesize responses for
	// these; a candidate carrying any is skipped in slice-1.
	Deferred []DanglingIntent
	// LastCallEventIndex is the EventIndex of the last event carrying any
	// FunctionCall (paired or not), or -1 if none. Repair is only clean
	// when every Repairable call sits in this event (ADK validates a
	// repair message against the latest function-call event).
	LastCallEventIndex int
}

DanglingScan splits a session's unpaired FunctionCalls into the three buckets the boot-time auto-resume pass acts on (cmd/mast, #41). It is the once-and-only-once eligibility gate's single source of truth.

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. It shares pairScan with the outbox, so the two can never drift on what "dangling" means.

func (DanglingScan) WithExternal

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

WithExternal folds intents recorded outside this session's event log into a scan — the dispatched mutations of #235, which by construction are absent from the log ScanDangling read.

They join Mutating unconditionally, never Repairable: an external intent is only ever recorded for a mutating- or spawning-class call, and the repair path must not synthesize a response for one. Synthetic answers are also structurally impossible here — the call was made by a model in a sub-session that no longer exists, so there is nothing left to answer.

type IntentStore

type IntentStore interface {
	// RecordSubRunIntents durably records intents raised by one
	// specialist inside sessionID. It must return an error if the
	// records are not durable, because the caller treats that as a
	// reason not to let the call proceed.
	RecordSubRunIntents(ctx context.Context, sessionID, specialist string, intents []DanglingIntent) error

	// CompleteSubRunIntents marks previously recorded intents paired.
	// Unknown call IDs are not an error: a completion whose intent was
	// never recorded is a call this recorder did not classify mutating.
	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.

Both methods take the OUTER session's ID. The sub-run's own session is a throwaway nobody can name afterwards, so filing anything under it would be filing it where no operator and no boot pass will look.

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 from the workload bundle decide next; mast 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).

The order of the last two is the load-bearing part. An annotation is the far end of the wire describing itself, so the audited workload override is checked first and still wins — an operator who does not want to take a server's word for it pins the tool with tool_catalog.tools[].mutating and nothing downstream can unpin it. Builtins come before it too: those are mast's own tools, whose implementation is in this repo, and no MCP server has standing to reclassify one that happens to share a name.

hint may be nil, and its annotated=false answer is the same as being nil for any given tool, so a caller never has to distinguish "no annotations configured" from "no annotation for this tool".

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, which is the case the shape has to carry: MCP's readOnlyHint is a plain bool, so "the server said false" and "the server said nothing" are otherwise the same value, and only the second one should fall through to default-deny-unknown.

internal/mcp.Annotations.ReadOnly is the implementation; the indirection keeps this package free of an MCP dependency it otherwise has no use for.

type SubRunRecorder

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

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

Not safe for concurrent use, and it does not need to be: a recorder belongs to one dispatch, and one dispatch is one sub-runner's stream.

func NewSubRunRecorder

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

NewSubRunRecorder builds the recording half of the dispatch seam.

The result is one CONSUMER of planner.SubRunSink, not an implementation of it: its Observe has the sink's signature, and a host composes it into a sink of its own alongside the metering and watchdog halves, which is what both cmd/mast and the library build do. It carried a no-op Close and a claim to satisfy the interface structurally until #452 gave Close a parameter; the claim went rather than the leaf, because this package not importing internal/planner is the property worth keeping and a no-op Close was never the reason the seam worked.

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.

A failed intent write stops the dispatch

The returned error stops the sub-run and hands the planner a labelled partial (planner.SubRunSink). That is a stronger posture than the other consumers on this seam take — a metering hiccup is swallowed — and it is deliberate for three reasons. This path is the one #235 exists about, and it was judged fail-open enough to refuse a startup over. The stop is the mildest one available: one dispatch, not the session, and the planner can route around it. And under `on_mutation: apply` there is no gate at all, so the record is the only control this call has; a control that fails open is not one.

A failed COMPLETION write is logged and swallowed, because by then the call has happened and refusing cannot un-happen it. What it leaves behind is an intent that stays dangling, which errs toward ambiguous-effect mode — the safe direction, and one an operator ack clears.

Why recording is the last thing this seam does

cmd/mast's sink observes metrics first, on the rule that the call which crossed a ceiling still cost money. Recording inverts that rule on purpose: an intent record is a claim that a mutating call is ABOUT to happen, and every consumer ahead of it can still stop the sub-run before it does. Recording first would leave a dangling intent for a call a watchdog trip or a budget ceiling prevented — a session wedged into ambiguous-effect mode over a mutation that never occurred.

type SubRunRecorderConfig

type SubRunRecorderConfig struct {
	// Store is where records land; required.
	Store IntentStore

	// SessionID is the OUTER session the dispatch belongs to; required.
	// A recorder built with an empty one refuses every event rather than
	// filing spend and effects under a session named "".
	SessionID string

	// Specialist is the roster name being dispatched, for attribution.
	Specialist string

	// Predicate classifies tools; required.
	Predicate Predicate

	// SubAgentNames excludes task delegations named after a composed
	// agent, exactly as the log scan does. Optional.
	SubAgentNames map[string]bool

	// Logger records completion-write failures, which are swallowed.
	// Optional.
	Logger *slog.Logger
}

SubRunRecorderConfig configures a recorder.

type ToolPolicy

type ToolPolicy struct {
	Name     string
	Mutating *bool
}

ToolPolicy mirrors workload.ToolPolicy without importing pkg/workload (which would drag the YAML loader into every library embed that only wants the guard). The daemon and library root convert.

Jump to

Keyboard shortcuts

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