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
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 totowhen 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 tohead(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 totowhen 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
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
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
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
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
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 Gatednodebeing false.
type Consumer
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
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
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
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
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
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
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
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
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
type NodeSafety stringNodeSafety 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
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
type PredicateDescription struct {
Name string `json:"name"`
Switched string `json:"switched"`
}PredicateDescription is one registered Switch predicate.
type ProblemKind
type ProblemKind stringProblemKind 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
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
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.TypeForMso 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
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
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
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
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
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
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
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
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
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
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
type TopologyNodeKind stringTopologyNodeKind 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.