runconfig

Documentation

Overview

Package runconfig loads a JSON document into a validated workflow/run runner and its tool set. The document names the machine rows, the plan steps and panels, string options, the external tool set, and the internal tools the loader builds. The loader feeds flow.New, machine.New, and run.New; it never re-runs their validation logic. See docs/history/runconfig.md.

Index

• Variables
• type Binding
• type Blocks
  • func NewBlocks() *Blocks
  • func (b *Blocks) Set(kind Kind, t tools.Tool)
• type Definition
  • func Load(data []byte) (*Definition, error)
  • func (d *Definition) Runner() (*run.Runner, error)
• type Kind

Variables

var (
	// ErrUnknownTool names an external tool absent from External.
	ErrUnknownTool = errors.New("runconfig: unknown tool")
	// ErrUnknownInternal names an internal Kind absent from Blocks.
	ErrUnknownInternal = errors.New("runconfig: unknown internal tool")
	// ErrBadDocument names any malformed or rejected document shape.
	ErrBadDocument = errors.New("runconfig: bad document")
	// ErrCallerBuilt names an internal Kind a document cannot build.
	// Load wraps it inside ErrBadDocument. Test with errors.Is.
	ErrCallerBuilt = errors.New("runconfig: internal kind stays caller-built")
)

Sentinel errors; test with errors.Is.

Types

type Binding

type Binding struct {
	// Step is the bound step's ID.
	Step string
	// Tool names the external tool. Set only when Internal is false.
	Tool string
	// Kind names the internal family. Set only when Internal is true.
	Kind Kind
	// Internal separates an internal binding from an external one.
	Internal bool
}

Binding ties one step to one tool source. Exactly one of Tool and Internal's Kind is meaningful, per Internal.

type Blocks

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

Blocks holds one tools.Tool per internal Kind. Load fills the six wireable Kinds from the document's internal section; the caller sets the caller-built Kinds, or overrides a wireable one, through Set. Last write wins. Safe for concurrent use.

func NewBlocks

func NewBlocks() *Blocks

NewBlocks returns an empty Blocks.

func (*Blocks) Set

func (b *Blocks) Set(kind Kind, t tools.Tool)

Set registers t under kind, replacing any earlier tool.

type Definition

type Definition struct {
	// Plan is the resolved step graph.
	Plan *flow.Definition
	// Machine is the resolved status model.
	Machine *machine.Definition
	// Options carries the string scalars and the caller-set Agent.
	Options run.Options
	// Tools lists the document's external tool names.
	Tools []string
	// Bindings holds one entry per bound step, in plan order.
	Bindings []Binding
	// Blocks holds the internal tool sources: the document-built
	// wireable Kinds plus caller-set entries.
	Blocks *Blocks
	// External holds the caller-set external tools by name.
	External *tools.Registry
}

Definition is the resolved document: the machine, the plan, the options, the tool set, the step bindings, and the document-built internal tools. Load fills Plan, Machine, Options, Tools, Bindings, and Blocks' wireable Kinds. Before Runner, the caller sets Options.Agent, registers the external tools on External, and adds the caller-built Kinds on Blocks. Every field is exported for inspection.

func Load

func Load(data []byte) (*Definition, error)

Load resolves one JSON document into a Definition. It rejects malformed JSON, a non-object root, a step with both bindings, a step that sets sub beside tool or internal, a step with no tool, internal, or sub binding outside a two-or-more-member panel, an empty step ID, an undeclared external tool, a blank or duplicate tool name, an unknown internal kind, an unknown when value, an internal section key a Kind constant does not name or a caller-built Kind names, an invalid internal section config, and a negative budget field. It also wraps any rejection from machine.New, flow.New, or an internal builder. It wraps every failure in ErrBadDocument. A present options.budget maps onto Options.Budget as a *budget.Limits and must pass Limits.Validate. The loader never reads the environment.

func (*Definition) Runner

func (d *Definition) Runner() (*run.Runner, error)

Runner builds a validated run.Runner from the loaded definition. The caller must first set Options.Agent, register the document's external tools on External, and ensure every bound internal Kind is on Blocks: Load sets the wireable Kinds the document's internal section declares, and the caller sets the caller-built Kinds. Runner resolves each binding, builds one tools.Registry keyed by step ID, sets Options.Machine and Options.Tools, and passes Options to run.New.

Runner also registers one pass-through tool per gated step that carries a child plan. Such a step has no binding, yet the runner confirms it, so its identifier needs a registry entry. See subParentIDs for which steps qualify.

A nil Agent yields run.ErrInvalidOptions; a missing external tool yields ErrUnknownTool; a missing internal Kind yields ErrUnknownInternal. A step identifier the registry already holds yields ErrBadDocument.

type Kind

type Kind string

Kind names one subagent internal tool family. A step's internal binding names one Kind. The document's internal section builds six wireable Kinds at Load; the caller builds the rest through the matching subagent helper and sets them on Blocks. See runconfig/internal.go for the split.

const (
	FlowKind             Kind = "flow"
	LedgerKind           Kind = "ledger"
	MemoryKind           Kind = "memory"
	RoomKind             Kind = "room"
	SchedulerKind        Kind = "scheduler"
	HeartbeatKind        Kind = "heartbeat"
	DiscoveryKind        Kind = "discovery"
	TriggerKind          Kind = "trigger"
	ChannelKind          Kind = "channel"
	ProviderKind         Kind = "provider"
	ProviderRegistryKind Kind = "providerregistry"
	AsToolKind           Kind = "astool"
)

The internal tool kinds a document may name.