Skip to content

Package plan ​

Go module github.com/bide-ai/bide; all packages.

github.com/bide-ai/bide/plan · pkg.go.dev · Stability: experimental

Package plan is rung-1 of the expression-surfaces stack: a handle-based flow builder that lowers to the journal-backed runtime and adds no new executor.

Constants

  • const ConfigVersion = 1: ConfigVersion is the one config format version this release reads.
  • const DescriptionVersion = 2: DescriptionVersion is the Version of a RegistryDescription this release writes.
  • const TopologyStep = "flow:topology": TopologyStep is the reserved journal name under which a flow run's first drive records the flow's declared Topology, as JSON (the encoding Flow.Topology's json tags define), as a StepValue just before flow:digest.

Variables

  • var ErrApprovalDenied = errors.New("approval denied"): ErrApprovalDenied is returned (wrapped, naming the node) by Flow.Run when a node's approval gate denied it: a SingleApproval gate's agent.Approve(false), or an m-of-n gate whose terminal tally did not pass.
  • var ErrApprovalExpired: ErrApprovalExpired is returned (wrapped, naming the node) by Flow.Run when a node's approval gate expired: its deadline (agent.ApprovalPolicy.Timeout) passed with no approval.
  • var ErrTaintRefused: ErrTaintRefused is returned (wrapped, naming the node) by Flow.Run when the flow's taint policy is Refuse, the run has read untrusted content, and the node can have a side effect: the node does not run, no record is written for it, and every later drive refuses it again; the run stays unfinished until it is cancelled (agent.Cancel).

Functions

  • func CompareAssertions(a, b string) string: CompareAssertions relates two assertion lines of a config, for comparing two versions of it.
  • func RenameAssertion(text string, rename func(string) string) string: RenameAssertion is the assertion line with each node name it holds replaced by rename(name) and every name written in double quotes, so two spellings of one assertion (a bare name or a quoted one, extra spaces) are the same string.
  • func TopologyDigest(t Topology) (string, error): TopologyDigest returns the v2 topology digest of t, the value Flow.Digest returns for a flow whose Topology is t: the same canonical, insertion-ordered serialization of the flow name, the boundary and node types with their package paths (the Canonical fields), every node's name, block and kind, every edge, every Switch arm with its predicate name, and every loop.
  • func Validate(data []byte, reg *Registry) error: Validate parses and checks a config against reg without producing a Flow, so config-vs-registry drift is catchable in a unit test or CI rather than only at process start.

type Arm ​

go
type Arm[M any] struct {
	// contains filtered or unexported fields
}

Arm is one branch of a Switch, produced by When, Else, or LoopBack.

Constructors and functions

  • func Else[M any](to Consumer[M]) Arm[M]: Else routes to to when no When arm matched.
  • func LoopBack[M any](max int, pred func(M) bool, head Consumer[M]) Arm[M]: LoopBack declares a BOUNDED LOOP as a Switch arm: when pred(over.Out) is true, route the switched value BACK to head (an earlier node, the loop head) and run the loop body again, up to max iterations.
  • func When[M any](pred func(M) bool, to Consumer[M]) Arm[M]: When routes to to when pred(over.Out) is true.

Methods

  • func (a Arm[M]) Named(name string) Arm[M]: Named names the arm's predicate, as RegisterPredicate names one for a config, and returns the arm.

type AssertionResult ​

go
type AssertionResult struct {
	Text string `json:"text"`

	Holds bool `json:"holds"`

	Invalid bool `json:"invalid,omitempty"`

	Vacuous bool `json:"vacuous,omitempty"`

	Undecided bool `json:"undecided,omitempty"`

	Path []string `json:"path,omitempty"`

	Message string `json:"message,omitempty"`
}

AssertionResult is the verdict on one line of a flow config's assert list.

Methods

  • func (a AssertionResult) Violated() bool: Violated reports the assertion was decided and does not hold.

type BlockDescription ​

go
type BlockDescription struct {
	Name string `json:"name"`

	Kind string `json:"kind"`

	In  string `json:"in"`
	Out string `json:"out"`

	Safety string `json:"safety"`

	Gate *GateDescription `json:"gate,omitempty"`

	Untrusted []string `json:"untrusted,omitempty"`

	Trusted string `json:"trusted,omitempty"`

	TaintExempt string `json:"taint_exempt,omitempty"`
}

BlockDescription is one registered Step, Tool or Model block.

type Builder ​

go
type Builder[In, Out any] struct {
	// contains filtered or unexported fields
}

Builder[In, Out] accumulates a flow spec.

Constructors and functions

  • func New[In, Out any](name string) *Builder[In, Out]: New constructs a flow builder whose input is In and output is Out, both pinned here so the flow boundary is checked at construction.

Methods

  • func (b *Builder[In, Out]) Build() (*Flow[In, Out], error): Build validates the accumulated spec for whole-graph coherence and freezes it into a *Flow[In, Out].
  • func (b *Builder[In, Out]) Edge[M any](from Producer[M], to Consumer[M]): Edge connects a producer to a consumer, unifying the connecting type M at the call site: the producer's output type and the consumer's input type must both be M, so a mismatch does not compile and the compiler error names the handles, not an erased spec entry.
  • func (b *Builder[In, Out]) Join2[A, B, O any](name string, a Producer[A], bb Producer[B], fn func(context.Context, A, B) (O, error), opts ...NodeOption) Handle[O, O]: Join2 registers a fixed-arity fan-in named name that consumes two upstream producers a and b and merges them with fn.
  • func (b *Builder[In, Out]) Join3[A, B, C, O any](name string, a Producer[A], bb Producer[B], cc Producer[C], fn func(context.Context, A, B, C) (O, error), opts ...NodeOption) Handle[O, O]: Join3 is Join2 for arity three: it consumes three upstream producers a, b, c and merges them with fn func(context.Context, A, B, C) (O, error).
  • func (b *Builder[In, Out]) Model[I, O any](name, prompt string, opts ...NodeOption) Handle[I, O]: Model registers a model call built from prompt as a durable step named name.
  • func (b *Builder[In, Out]) Step[I, O any](name string, fn func(context.Context, I) (O, error), opts ...NodeOption) Handle[I, O]: Step registers an arbitrary func(ctx, I) (O, error) as a durable step named name.
  • func (b *Builder[In, Out]) Switch[M any](over Producer[M], arms ...Arm[M]): Switch routes on over.Out to exactly one arm.
  • func (b *Builder[In, Out]) Tool[I, O any](name string, t agent.Tool, opts ...NodeOption) Handle[I, O]: Tool registers an agent.Tool as a durable step named name.
  • func (b *Builder[In, Out]) WithApproverVerifiers(f agent.ApproverVerifierFor) *Builder[In, Out]: WithApproverVerifiers binds the resolver of each approver's signature verifier for the flow's m-of-n approval gates, as agent.Agent.WithApproverVerifiers does for an agent's: a decision counts only if it verifies under the verifier this returns for its approver.
  • func (b *Builder[In, Out]) WithModel(m agent.Model) *Builder[In, Out]: WithModel binds an agent.Model to the flow, so a Model step can render its prompt, call the model, and decode the structured result.
  • func (b *Builder[In, Out]) WithNotifier(n agent.Notifier, trail agent.NotifyTrail, opts ...agent.NotifyOption) *Builder[In, Out]: WithNotifier tells n, at least once and with a stable ID, when a run of the flow that Run drives halts on an unknown outcome, waits at an approval gate, or is aborted: see agent.WithNotifier, whose semantics, trail requirements and options this takes.
  • func (b *Builder[In, Out]) WithStopSwitch(sw *agent.StopSwitch) *Builder[In, Out]: WithStopSwitch gives the flow a kill switch (see agent.StopSwitch and docs/guides/kill-switch.md): a run of the flow is held, as a pause (*agent.Stopped), at its start, and each node is held before its claim and, with the control run read then, after the claim and before the node's body, where a stop covers the flow (agent.StopFlow, by the flow's name), the agent that acts (an agent stop) or every run (a global stop).
  • func (b *Builder[In, Out]) WithTaintPolicy(p agent.TaintPolicy) *Builder[In, Out]: WithTaintPolicy gives the flow a taint policy, the same type an agent takes (agent.WithTaintPolicy): an escalation Gate, or Refuse, and optionally RequireProvenance.

type ConfigProblem ​

go
type ConfigProblem struct {
	Node     string `json:"node,omitempty"`
	From     string `json:"from,omitempty"`
	To       string `json:"to,omitempty"`
	Message  string `json:"message"`
	Severity string `json:"severity"`
}

ConfigProblem is one problem in a flow config.

type ConfigReport ​

go
type ConfigReport struct {
	Topology Topology

	Digest string

	Approvals map[string]agent.ApprovalPolicy

	Problems []ConfigProblem

	Findings []Finding

	Typed bool

	Safety map[string]NodeSafety

	Assertions []AssertionResult

	Gated map[string]bool

	Taint map[string]NodeTaint
}

ConfigReport is what InspectConfig finds in a flow config: the graph it declares, the digest a run of it would journal, its approval gates, and its problems, each attached to the node, edge or arm it belongs to.

Constructors and functions

  • func InspectConfig(data []byte, reg *Registry, opts ...InspectOption) (r ConfigReport): InspectConfig checks a flow config without running or building a Flow, for a viewer or a CI check.
  • func InspectConfigDescribed(data []byte, d RegistryDescription, opts ...InspectOption) ConfigReport: InspectConfigDescribed is InspectConfig for a program's registrations known only as a description: it runs the same checks (the same code) on a Registry built from d, so blocks, predicates, merges, types, safety, gates and the digest are checked without the program.
  • func InspectTopology(t Topology) ConfigReport: InspectTopology is the report of a declared Topology alone, for a tool that holds a topology and no config: the topology a run journaled (JournaledTopology), compared with the one a config declares.

Methods

  • func (r ConfigReport) Errors() bool: Errors reports whether any problem is an error.
  • func (r ConfigReport) UngatedPath(node string) []string: UngatedPath is a shortest path of node names from the entry to node that passes no approval gate, or nil when every path to node passes one (or the entry cannot reach it): the evidence behind Gatednode being false.

type Consumer ​

go
type Consumer[M any] interface {
	// contains filtered or unexported methods
}

ConsumerM is the input side of a wired step: it accepts a value of type M.

type Finding ​

go
type Finding struct {
	Kind    ProblemKind `json:"kind"`
	Names   []string    `json:"names,omitempty"`
	Got     string      `json:"got,omitempty"`
	Want    string      `json:"want,omitempty"`
	Message string      `json:"message"`
}

Finding is the structure behind one error in a ConfigReport: what kind of problem it is and the names it is about, so that a tool need not read the Message to tell problems apart.

type Flow ​

go
type Flow[In, Out any] struct {
	// contains filtered or unexported fields
}

Flow[In, Out] is a built, frozen flow: the reified topology validated by Build, ready to run durably.

Constructors and functions

  • func Load[In, Out any](data []byte, reg *Registry, opts ...LoadOption) (*Flow[In, Out], error): Load parses a rung-2 JSON config, resolves every block and predicate against reg, validates the whole topology at load time, and returns the built *Flow[In, Out].
  • func LoadReader[In, Out any](r io.Reader, reg *Registry, opts ...LoadOption) (*Flow[In, Out], error): LoadReader is Load reading the config from r (for example an *os.File or an HTTP body).

Methods

  • func (f *Flow[In, Out]) Conform(ctx context.Context, store *agent.Journal, runID string) (ok bool, diffs []string, err error): Conform checks the journaled path for runID against f's declared topology.
  • func (f *Flow[In, Out]) Digest() string: Digest returns a deterministic SHA-256 hash (hex-encoded) of this frozen flow's DECLARED topology: the flow name, every node's name, block, kind, input type and output type (each type with its full package path), every edge, and every Switch and its ordered arms with their predicate names, and every node's approval gate (written only for a gated node, so an ungated flow's digest does not depend on it).
  • func (f *Flow[In, Out]) DigestV1() string: DigestV1 returns the v1 topology digest (domain tag "bide.plan.topology.v1"), which Run recorded before v2.
  • func (f *Flow[In, Out]) FlushNotifications(ctx context.Context) error: FlushNotifications waits for the flow's notifier to finish the deliveries in flight, for every journal the flow has run against, as agent.Agent.FlushNotifications does.
  • func (f *Flow[In, Out]) RenderMermaid() string: RenderMermaid returns a Mermaid flowchart of the DECLARED topology carried by this frozen Flow, each node labelled by its journal key and its I,O types.
  • func (f *Flow[In, Out]) ResolveHalt(ctx context.Context, store *agent.Journal, ref agent.HaltRef, out agent.Outcome, opts ...agent.ResolveOption) error: ResolveHalt clears a halt of a node of this flow, as agent.ResolveHalt does, once it has checked the resolution against the flow: ref must name a node of this flow (the halt's Ref: a node key, a loop iteration's key for a node in a loop body, or the key of a Step a node's body ran), the run must be a run of this flow (its recorded start names this flow, and its recorded topology digest is this flow's), and a successful outcome's Result must decode as the node's output type, so the next Run can feed it downstream.
  • func (f *Flow[In, Out]) Run(ctx context.Context, store *agent.Journal, runID string, in In, opts ...agent.RunOption) (Out, error): Run executes the lowered flow durably for runID against store, resuming from the journal if steps already exist.
  • func (f *Flow[In, Out]) Topology() Topology: Topology returns the stable, renderer-agnostic snapshot of this frozen flow's DECLARED topology as pure, JSON-serializable data.

type GateDescription ​

go
type GateDescription struct {
	Single bool `json:"single,omitempty"`

	Need             int      `json:"need"`
	Approvers        []string `json:"approvers,omitempty"`
	ExcludePrincipal bool     `json:"exclude_principal,omitempty"`

	Timeout string `json:"timeout,omitempty"`
}

GateDescription is an approval gate declared in Go.

type Handle ​

go
type Handle[I, O any] struct {
	// contains filtered or unexported fields
}

Handle[I,O] is a compile-time name for a durable step consuming I and producing O.

Methods

  • func (h Handle[I, O]) Name() string: Name returns the durable journal-step key this handle names.

type InspectOption ​

go
type InspectOption func(*inspectOptions)

InspectOption changes what InspectConfig and InspectConfigDescribed check.

Constructors and functions

  • func AllowUnusedBlocks() InspectOption: AllowUnusedBlocks makes a registered block the config does not use no problem.
  • func InspectTaintPolicy(p agent.TaintPolicy) InspectOption: InspectTaintPolicy gives InspectConfig the taint policy of the flow, which the config cannot carry (it is Go: Builder.WithTaintPolicy).

type LoadOption ​

go
type LoadOption func(*builderCore)

LoadOption configures a flow at Load time (before Build).

Constructors and functions

  • func WithLoadedApproverVerifiers(f agent.ApproverVerifierFor) LoadOption: WithLoadedApproverVerifiers binds the resolver of each approver's signature verifier for a loaded flow's m-of-n approval gates: the loader's equivalent of Builder.WithApproverVerifiers.
  • func WithLoadedModel(m agent.Model) LoadOption: WithLoadedModel binds an agent.Model to a flow produced by Load or LoadReader, so a config that declares a Model node (a RegisterModel block) can render its prompt, call the model, and decode the structured result at run time.
  • func WithLoadedNotifier(n agent.Notifier, trail agent.NotifyTrail, opts ...agent.NotifyOption) LoadOption: WithLoadedNotifier binds a notifier to a loaded flow: the loader's equivalent of Builder.WithNotifier.
  • func WithLoadedStopSwitch(sw *agent.StopSwitch) LoadOption: WithLoadedStopSwitch binds a kill switch to a loaded flow: the loader's equivalent of Builder.WithStopSwitch.
  • func WithLoadedTaintPolicy(p agent.TaintPolicy) LoadOption: WithLoadedTaintPolicy gives a flow produced by Load or LoadReader a taint policy: the loader's equivalent of Builder.WithTaintPolicy.

type MergeDescription ​

go
type MergeDescription struct {
	Name string `json:"name"`

	Inputs []string `json:"inputs"`

	Out string `json:"out"`

	Safety string           `json:"safety"`
	Gate   *GateDescription `json:"gate,omitempty"`

	Untrusted   []string `json:"untrusted,omitempty"`
	Trusted     string   `json:"trusted,omitempty"`
	TaintExempt string   `json:"taint_exempt,omitempty"`
}

MergeDescription is one registered fan-in merge block.

type NodeOption ​

go
type NodeOption func(*node)

NodeOption configures a node at construction (Step, Tool, Model) or at registration (RegisterStep, RegisterTool, RegisterModel).

Constructors and functions

  • func Approval(p *agent.ApprovalPolicy) NodeOption: Approval gates the node on p, a human approval policy, exactly as agent.WithApproval gates a tool: Run pauses before the node runs, returning *agent.ApprovalPending, until the gate passes, and a denied gate stops the run with ErrApprovalDenied (see Flow.Run).
  • func BlockName(name string) NodeOption: BlockName names the behaviour a node built in Go runs, the way a config node names its registered block.
  • func Idempotent() NodeOption: Idempotent marks a node as idempotent: it mutates state but a repeat with the same input is a no-op downstream, so it is safe to retry.
  • func ReadOnly() NodeOption: ReadOnly marks a node as read-only: it has no external side effect, so it is always safe to re-run from the top on resume.
  • func TaintExempt(reason string) NodeOption: TaintExempt declares that the node needs no escalation gate even when the run has read untrusted content, and why (the reason is required, and follows the rules of agent.TaintExempt).
  • func Trusted(reason string) NodeOption: Trusted declares that the results of the node are the host's own, and why (the reason is required, and follows the rules of agent.Trusted).
  • func Untrusted(source string) NodeOption: Untrusted declares that the results of the node come from outside, from the named source (for example "inbound-email"): text the host did not write and an attacker may have.

type NodeSafety ​

go
type NodeSafety string

NodeSafety is how a node behaves when a crash cuts it off mid-run, as a risk map shows it.

Constants

  • const SafetyReadOnly NodeSafety = "read-only": SafetyReadOnly: no external effect; a resume re-runs the node.
  • const SafetyIdempotent NodeSafety = "idempotent": SafetyIdempotent: an effect that is safe to repeat; a resume re-runs the node.
  • const SafetySideEffect NodeSafety = "side effect": SafetySideEffect: an effect that must not fire twice; a resume after a crash mid-node halts (*agent.OutcomeUnknown) and asks for the outcome.
  • const SafetyUnknown NodeSafety = "unknown": SafetyUnknown: the structural check cannot tell (the block is not registered and the config states no safety).

Methods

  • func (s NodeSafety) RerunsOnCrash() bool: RerunsOnCrash reports whether a resume re-runs a node of this class that a crash cut off (read-only and idempotent); a side effect halts and asks for the outcome instead, and an unknown class is not known to do either.

type NodeTaint ​

go
type NodeTaint struct {
	Verdict string `json:"verdict"`

	Declares []string `json:"declares,omitempty"`

	Sources []string `json:"sources,omitempty"`

	Path []string `json:"path,omitempty"`

	Exempt string `json:"exempt,omitempty"`

	Reason string `json:"reason,omitempty"`
}

NodeTaint is the static taint verdict on one node.

type PredicateDescription ​

go
type PredicateDescription struct {
	Name string `json:"name"`

	Switched string `json:"switched"`
}

PredicateDescription is one registered Switch predicate.

type ProblemKind ​

go
type ProblemKind string

ProblemKind names the kind of a Finding.

Constants

  • const ProblemEdgeTypes ProblemKind = "edge_types": ProblemEdgeTypes: an edge joins steps of other types.
  • const ProblemArmTypes ProblemKind = "arm_types": ProblemArmTypes: a switch arm's predicate tests another type than the switched node gives.
  • const ProblemJoinInputTypes ProblemKind = "join_input_types": ProblemJoinInputTypes: a join input does not fit its merge.
  • const ProblemTerminalTypes ProblemKind = "terminal_types": ProblemTerminalTypes: a terminal step reached from the entry gives another type than the flow's output.
  • const ProblemSafetyAboveRegistration ProblemKind = "safety_above_registration": ProblemSafetyAboveRegistration: a node states a retry safety above what its block registers in Go, which a config may not claim.
  • const ProblemLoopNoExitArm ProblemKind = "loop_no_exit_arm": ProblemLoopNoExitArm: a loop's switch has no arm or else that leaves it.
  • const ProblemLoopMoreThanOneBackArm ProblemKind = "loop_more_than_one_back_arm": ProblemLoopMoreThanOneBackArm: a switch has more than one loop-back arm.
  • const ProblemLoopHeadNotAncestor ProblemKind = "loop_head_not_ancestor": ProblemLoopHeadNotAncestor: a loop-back arm targets a node that does not reach its switch.
  • const ProblemLoopBodyNotSimple ProblemKind = "loop_body_not_simple": ProblemLoopBodyNotSimple: a node lies between a loop's head and switch but is not on the loop path.
  • const ProblemLoopInnerSwitch ProblemKind = "loop_inner_switch": ProblemLoopInnerSwitch: a step inside a loop has a switch of its own.
  • const ProblemLoopEdgeLeaves ProblemKind = "loop_edge_leaves": ProblemLoopEdgeLeaves: an edge leaves a loop's body other than through its switch's exit arms.
  • const ProblemLoopEdgeEnters ProblemKind = "loop_edge_enters": ProblemLoopEdgeEnters: an edge enters a loop's body past its head.
  • const ProblemOther ProblemKind = "other": ProblemOther: every other problem.

type Producer ​

go
type Producer[M any] interface {
	// contains filtered or unexported methods
}

ProducerM is the output side of a wired step: it yields a value of type M.

type Registry ​

go
type Registry struct {
	// contains filtered or unexported fields
}

Registry maps config names to typed Go behavior, so a rung-2 config can reference blocks and predicates by name.

Constructors and functions

  • func NewRegistry() *Registry: NewRegistry returns a fresh, empty Registry.

Methods

  • func (r *Registry) Describe() RegistryDescription: Describe returns what r has registered (see RegistryDescription).
  • func (r *Registry) RegisterJoin2[A, B, O any](name string, fn func(context.Context, A, B) (O, error), opts ...NodeOption) error: RegisterJoin2 registers a fixed-arity fan-in merge func(ctx, A, B) (O, error) as a merge block named name, inferring A, B, and O from fn (the config never restates types; they flow from the registered merge).
  • func (r *Registry) RegisterJoin3[A, B, C, O any](name string, fn func(context.Context, A, B, C) (O, error), opts ...NodeOption) error: RegisterJoin3 is RegisterJoin2 for arity three: it registers a fan-in merge func(ctx, A, B, C) (O, error) as a merge block named name, inferring A, B, C, and O from fn.
  • func (r *Registry) RegisterModel[I, O any](name, prompt string, opts ...NodeOption) error: RegisterModel registers a model call built from prompt as a Model block named name.
  • func (r *Registry) RegisterPredicate[M any](name string, pred func(M) bool) error: RegisterPredicate registers a Switch predicate func(M)bool named name, capturing M via reflect.TypeForM so Load can verify M equals the switched node's output type.
  • func (r *Registry) RegisterStep[I, O any](name string, fn func(context.Context, I) (O, error), opts ...NodeOption) error: RegisterStep registers an arbitrary func(ctx, I) (O, error) as a Step block named name, inferring I and O from fn (the config never restates types; they flow from the registered block).
  • func (r *Registry) RegisterTool[I, O any](name string, t agent.Tool, opts ...NodeOption) error: RegisterTool registers an agent.Tool as a Tool block named name.

type RegistryDescription ​

go
type RegistryDescription struct {
	Version int `json:"version"`

	TaintDeclared bool `json:"taint_declared,omitempty"`

	TaintPolicy *TaintPolicyDescription `json:"taint_policy,omitempty"`

	Blocks []BlockDescription `json:"blocks"`

	Predicates []PredicateDescription `json:"predicates"`

	Merges []MergeDescription `json:"merges"`

	Errors []string `json:"errors,omitempty"`
}

RegistryDescription is what a Registry has registered, as data: names, kinds, type names, the safety and the approval gate each block declares in Go.

Methods

  • func (d RegistryDescription) Validate() error: Validate reports whether d is a description this release reads: its version, no registration errors (a program whose Registry refused something does not load), every name and type name present, printable and within bounds, every kind and safety one of the known words, every gate a policy agent.ApprovalPolicy.Validate accepts, no name twice in a namespace, and a merge of arity two or three (the arities Registry registers).

type TaintPolicyDescription ​

go
type TaintPolicyDescription struct {
	Gate *GateDescription `json:"gate,omitempty"`

	Refuse bool `json:"refuse,omitempty"`

	RequireProvenance bool `json:"require_provenance,omitempty"`

	SeparateApprovers bool `json:"separate_approvers,omitempty"`
}

TaintPolicyDescription is a flow's taint policy as data: the escalation gate a tainted node's side effects need, or Refuse, and whether provenance is required.

Constructors and functions

  • func DescribeTaintPolicy(p agent.TaintPolicy) (*TaintPolicyDescription, error): DescribeTaintPolicy is p as a TaintPolicyDescription, for RegistryDescription.TaintPolicy, or an error if p is not a policy Builder.WithTaintPolicy accepts.

type Topology ​

go
type Topology struct {
	Flow string `json:"flow"`

	Entry string `json:"entry"`

	In  string `json:"in"`
	Out string `json:"out"`

	InCanonical  string `json:"in_canonical"`
	OutCanonical string `json:"out_canonical"`

	Nodes []TopologyNode `json:"nodes"`

	Edges []TopologyEdge `json:"edges"`

	Branches []TopologyBranch `json:"branches,omitempty"`

	Joins []TopologyJoin `json:"joins,omitempty"`

	Loops []TopologyLoop `json:"loops,omitempty"`
}

Topology is the stable, renderer-agnostic view of a frozen flow's DECLARED shape: its nodes, the edges between them, its Switch branches, its bounded loops, and its fan-in joins, all as pure data (plain strings, no reflect.Type, no closures).

Constructors and functions

  • func JournaledTopology(recs []agent.Record) (t Topology, digest string, ok bool, err error): JournaledTopology reads the topology a flow run journaled (TopologyStep) from recs, the run's journal, and checks it against the run's flow:digest record: ok is false when the run has no topology record, and err is non-nil when one does not decode, or when the digest computed from it (TopologyDigest) is not the journaled digest, or the run journaled no digest.

type TopologyBranch ​

go
type TopologyBranch struct {
	Over string              `json:"over"`
	Arms []TopologyBranchArm `json:"arms"`
	Else string              `json:"else,omitempty"`
}

TopologyBranch is one declared Switch: the switched-over node and its ordered arms.

type TopologyBranchArm ​

go
type TopologyBranchArm struct {
	Target   string `json:"target"`
	Pred     string `json:"pred,omitempty"`
	Else     bool   `json:"else,omitempty"`
	LoopBack bool   `json:"loop_back,omitempty"`
	LoopMax  int    `json:"loop_max,omitempty"`
}

TopologyBranchArm is one arm of a Switch: its target node and its role.

type TopologyEdge ​

go
type TopologyEdge struct {
	From string `json:"from"`
	To   string `json:"to"`
	Type string `json:"type,omitempty"`
}

TopologyEdge is one declared connection producer.Out -> consumer.In, by node name.

type TopologyGate ​

go
type TopologyGate struct {
	Single           bool     `json:"single,omitempty"`
	Need             int      `json:"need,omitempty"`
	Approvers        []string `json:"approvers,omitempty"`
	ExcludePrincipal bool     `json:"exclude_principal,omitempty"`

	TimeoutMS int64 `json:"timeout_ms,omitempty"`
}

TopologyGate is a node's approval gate: Single for agent.SingleApproval (one decision, recorded with agent.Approve), otherwise Need signed decisions of the Approvers, in policy order (an m-of-n gate), never counting the run's requester when ExcludePrincipal is set (agent.ApprovalPolicy.ExcludePrincipal).

Methods

  • func (g *TopologyGate) TimeoutText() string: TimeoutText is the gate's deadline as a short duration ("24h", "1h30m", "90s"), or "" for a gate with none (or a nil gate).

type TopologyJoin ​

go
type TopologyJoin struct {
	Name        string   `json:"name"`
	Inputs      []string `json:"inputs"`
	InTypes     []string `json:"in_types"`
	InCanonical []string `json:"in_canonical"`
	Out         string   `json:"out"`
}

TopologyJoin is one declared fan-in: the join node's name, its ORDERED input source node names (one per merge-function parameter, in declared order), the positionally-aligned input port type names, and the join's output type name.

type TopologyLoop ​

go
type TopologyLoop struct {
	Head string   `json:"head"`
	Over string   `json:"over"`
	Body []string `json:"body"`
	Max  int      `json:"max"`
}

TopologyLoop is one bounded loop Build derived from a LoopBack arm: the loop head (the back-edge target, an earlier node re-entered each iteration), the loop switch (the node the Switch is over, which carries the back-edge arm), the ordered body region (head..switch inclusive, in forward topological order), and the iteration bound Max (> 0).

type TopologyNode ​

go
type TopologyNode struct {
	Name         string           `json:"name"`
	Kind         TopologyNodeKind `json:"kind"`
	In           string           `json:"in"`
	Out          string           `json:"out"`
	Block        string           `json:"block"`
	InCanonical  string           `json:"in_canonical"`
	OutCanonical string           `json:"out_canonical"`

	Gate *TopologyGate `json:"gate,omitempty"`
}

TopologyNode is one declared node: its journal name, its kind, and its input/output type names as reflect.Type.String renders them.

type TopologyNodeKind ​

go
type TopologyNodeKind string

TopologyNodeKind is the kind of a declared node, as Topology reports it.

Constants

  • const NodeKindStep TopologyNodeKind = "step": NodeKindStep is a Go step (Builder.Step, RegisterStep).
  • const NodeKindTool TopologyNodeKind = "tool": NodeKindTool is a node that calls an agent tool (Builder.Tool, RegisterTool).
  • const NodeKindModel TopologyNodeKind = "model": NodeKindModel is a node that calls the flow's model (Builder.Model, RegisterModel).
  • const NodeKindSwitch TopologyNodeKind = "switch": NodeKindSwitch is a journaled branch-choice node.
  • const NodeKindJoin TopologyNodeKind = "join": NodeKindJoin is a fan-in node that merges several producers' outputs.

Apache-2.0 licensed.