dsl

package
v0.4.8 Latest Latest
Warning

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

Go to latest
Published: Nov 1, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package dsl defines the compozy.loop/v1 authoring document.

Package dsl defines the compozy.loop/v1 authoring document.

Index

Constants

View Source
const (
	// SessionModeContinuous reuses one durable binding across Goal turns.
	SessionModeContinuous = "continuous"
	// RetryOnFailureFreshSession rotates a proven-not-started Goal binding attempt.
	RetryOnFailureFreshSession = "fresh_session"
	// GoalOnExhaustedHalt terminates a Goal at its effective turn limit.
	GoalOnExhaustedHalt = "halt"
	// GoalOnExhaustedEscalate requests approval at the effective turn limit.
	GoalOnExhaustedEscalate = "escalate"
)
View Source
const (
	// APIVersion is the only loop DSL version accepted by this package.
	APIVersion = "compozy.loop/v1"
	// KindLoop is the document kind for loop definitions.
	KindLoop = "Loop"
	// GateMaxRevisionsCeiling is the hard structural gate revision ceiling.
	GateMaxRevisionsCeiling = 64
)
View Source
const ReviewedWorktreeInput = "reviewed_worktree"

Variables

This section is empty.

Functions

func DeriveGoalHandle

func DeriveGoalHandle(nodeID NodeID, label string, itemIndex int) (string, error)

DeriveGoalHandle returns the fixed persisted binding identity for one Goal node item.

func IsKnownControlKind

func IsKnownControlKind(kind string) bool

IsKnownControlKind validates the closed control enum.

func IsKnownParentClosePolicy

func IsKnownParentClosePolicy(value ParentClosePolicy) bool

IsKnownParentClosePolicy reports whether value is in the closed parent-close vocabulary.

func IsKnownSourceKind

func IsKnownSourceKind(kind string) bool

IsKnownSourceKind validates the closed source enum.

func IsKnownTerminalState

func IsKnownTerminalState(value TerminalState) bool

IsKnownTerminalState reports whether value belongs to the closed terminal outcome vocabulary.

func IsKnownWaitAheadArrival

func IsKnownWaitAheadArrival(value WaitAheadArrival) bool

IsKnownWaitAheadArrival reports whether value belongs to the closed wait vocabulary.

func IsReservedActionKind

func IsReservedActionKind(kind string) bool

IsReservedActionKind reports whether kind is first-party and not a ToolID.

func Serialize

func Serialize(def Definition) ([]byte, error)

Serialize encodes one compozy.loop/v1 YAML document.

Types

type ACPOptionSelection

type ACPOptionSelection = runtimeoption.Selection

ACPOptionSelection identifies one provider-advertised ACP option value. Exactly one of ValueID or BoolValue must be set.

func CanonicalACPOptionSelections

func CanonicalACPOptionSelections(selections []ACPOptionSelection) []ACPOptionSelection

CanonicalACPOptionSelections returns a sorted ownership-safe copy.

func CloneACPOptionSelections

func CloneACPOptionSelections(selections []ACPOptionSelection) []ACPOptionSelection

CloneACPOptionSelections returns an ownership-safe copy of ACP selections.

func MergeACPOptionSelections

func MergeACPOptionSelections(
	base []ACPOptionSelection,
	overlay []ACPOptionSelection,
) ([]ACPOptionSelection, []string)

MergeACPOptionSelections overlays typed values by canonical option ID.

func NormalizeACPOptionSelections

func NormalizeACPOptionSelections(selections []ACPOptionSelection) ([]ACPOptionSelection, error)

NormalizeACPOptionSelections validates, copies, and sorts ACP selections by ID.

func NormalizeACPOptionSelectionsAt

func NormalizeACPOptionSelectionsAt(
	path string,
	selections []ACPOptionSelection,
) ([]ACPOptionSelection, error)

NormalizeACPOptionSelectionsAt validates selections while retaining their owning path.

type ActionKind

type ActionKind string

ActionKind is open except for reserved first-party kinds.

const (
	// ActionRunAgent executes an agent turn.
	ActionRunAgent ActionKind = "run-agent"
	// ActionRunLoop starts another loop definition.
	ActionRunLoop ActionKind = "run-loop"
	// ActionTransform reshapes data in daemon.
	ActionTransform ActionKind = "transform"
	// ActionGoal advances a durable convergence cycle.
	ActionGoal ActionKind = "goal"
)

func ReservedActionKinds

func ReservedActionKinds() []ActionKind

ReservedActionKinds returns the reserved first-party action kinds.

type AskParams

type AskParams struct {
	Prompt     string         `json:"prompt"              yaml:"prompt"`
	Context    map[string]any `json:"context,omitempty"   yaml:"context,omitempty"`
	Expect     Schema         `json:"expect"              yaml:"expect"`
	Responders *ResponderSpec `json:"responders,omitzero" yaml:"responders,omitempty"`
	Expires    *WaitExpiry    `json:"expires,omitzero"    yaml:"expires,omitempty"`
	Extra      map[string]any `json:"-"                   yaml:",inline"`
}

AskParams is the canonical schema for control kind ask.

type BackoffSpec

type BackoffSpec struct {
	Base string `json:"base,omitempty" yaml:"base,omitempty"`
	Max  string `json:"max,omitempty"  yaml:"max,omitempty"`
}

BackoffSpec bounds the retry delay for one action node.

type Budget

type Budget struct {
	Tokens       int32          `json:"tokens"                yaml:"tokens"`
	WallClockSec int32          `json:"wall_clock_sec"        yaml:"wall_clock_sec"`
	OnExceeded   BudgetExceeded `json:"on_exceeded,omitempty" yaml:"on_exceeded,omitempty"`
	Extra        map[string]any `json:"-"                     yaml:",inline"`
}

Budget defines opt-in hard limits.

type BudgetExceeded

type BudgetExceeded string

BudgetExceeded controls the outcome for a set budget breach.

const (
	// BudgetExceededHalt maps a breach to exhausted.
	BudgetExceededHalt BudgetExceeded = "halt"
	// BudgetExceededEscalate maps a breach to needs-approval.
	BudgetExceededEscalate BudgetExceeded = "escalate"
)

type CatalogMeta

type CatalogMeta struct {
	UseWhen  string         `json:"use_when,omitempty" yaml:"use_when,omitempty"`
	Keywords []string       `json:"keywords,omitempty" yaml:"keywords,omitempty"`
	Category string         `json:"category,omitempty" yaml:"category,omitempty"`
	Extra    map[string]any `json:"-"                  yaml:",inline"`
}

CatalogMeta is the matchable catalog projection embedded in a definition.

type ConcurrencyPolicy

type ConcurrencyPolicy string

ConcurrencyPolicy controls same-loop concurrent starts.

const (
	// ConcurrencyForbid rejects concurrent starts of the same loop.
	ConcurrencyForbid ConcurrencyPolicy = "forbid"
	// ConcurrencyAllow permits concurrent starts of the same loop.
	ConcurrencyAllow ConcurrencyPolicy = "allow"
	// ConcurrencyQueue creates a queued loop run for later promotion.
	ConcurrencyQueue ConcurrencyPolicy = "queue"
)

type Contract

type Contract struct {
	Goal                    string           `json:"goal"                      yaml:"goal"`
	DefinitionOfDone        string           `json:"definition_of_done"        yaml:"definition_of_done"`
	Constraints             []string         `json:"constraints,omitempty"     yaml:"constraints,omitempty"`
	Boundaries              []string         `json:"boundaries,omitempty"      yaml:"boundaries,omitempty"`
	StopWhen                StopWhenSpec     `json:"stop_when,omitzero"        yaml:"stop_when,omitempty"`
	Verification            []GateCriterion  `json:"verification,omitempty"    yaml:"verification,omitempty"`
	IterationCap            int              `json:"iteration_cap"             yaml:"iteration_cap"`
	NoProgress              NoProgress       `json:"no_progress"               yaml:"no_progress"`
	Budget                  Budget           `json:"budget"                    yaml:"budget"`
	RuntimeDefaults         *RuntimeDefaults `json:"runtime_defaults,omitzero" yaml:"runtime_defaults,omitempty"`
	RuntimeRules            []RuntimeRule    `json:"runtime_rules,omitempty"   yaml:"runtime_rules,omitempty"`
	*ContractLifecycleState `                                                  yaml:",inline"`
	Extra                   map[string]any `json:"-"                         yaml:",inline"`
}

Contract defines goal, verification, and stop semantics.

func (*Contract) Normalize

func (c *Contract) Normalize()

Normalize gives optional ADR-018 fields empty values when absent.

type ContractLifecycleState

type ContractLifecycleState struct {
	TerminalStates  []TerminalState `json:"terminal_states,omitempty" yaml:"terminal_states,omitempty"`
	TerminalEffects `                                                 yaml:",inline"`
}

ContractLifecycleState keeps optional terminal effects off the hot Contract value.

type ControlKind

type ControlKind string

ControlKind is the closed control-node vocabulary.

const (
	// ControlFanOut materializes a finite collection into branches.
	ControlFanOut ControlKind = "fan-out"
	// ControlCollect joins fan-out branches.
	ControlCollect ControlKind = "collect"
	// ControlBranch routes by CEL condition.
	ControlBranch ControlKind = "branch"
	// ControlRoute selects exactly one declared forward route.
	ControlRoute ControlKind = "route"
	// ControlGate evaluates criteria and routing policy.
	ControlGate ControlKind = "gate"
	// ControlSubLoop embeds an inline nested loop body.
	ControlSubLoop ControlKind = "sub-loop"
	// ControlWait parks one cell until a timer, timestamp, or event resolves.
	ControlWait ControlKind = "wait"
	// ControlAsk parks one cell until a validated answer is admitted.
	ControlAsk ControlKind = "ask"
)

type CriterionType

type CriterionType string

CriterionType is the closed gate criterion vocabulary.

const (
	// CriterionCommand runs a project command.
	CriterionCommand CriterionType = "command"
	// CriterionAgentJudge asks an agent to judge against a rubric.
	CriterionAgentJudge CriterionType = "agent-judge"
	// CriterionHuman waits for a human decision.
	CriterionHuman CriterionType = "human"
	// CriterionExtension calls an extension tool.
	CriterionExtension CriterionType = "extension"
)

type Definition

type Definition struct {
	APIVersion                string            `json:"apiVersion"            yaml:"apiVersion"`
	Kind                      string            `json:"kind"                  yaml:"kind"`
	Meta                      Meta              `json:"meta"                  yaml:"meta"`
	Concurrency               ConcurrencyPolicy `json:"concurrency,omitempty" yaml:"concurrency,omitempty"`
	Inputs                    map[string]Input  `json:"inputs,omitempty"      yaml:"inputs,omitempty"`
	Contract                  Contract          `json:"contract"              yaml:"contract"`
	Graph                     Graph             `json:"graph"                 yaml:"graph"`
	*DefinitionExtensionState `                                               yaml:",inline"`
	Extra                     map[string]any `json:"-"                     yaml:",inline"`
}

Definition is the canonical compozy.loop/v1 document.

func GraphToDefinition

func GraphToDefinition(graph *GraphDocument) Definition

GraphToDefinition merges graph edits back into the original definition.

func Parse

func Parse(data []byte) (Definition, error)

Parse decodes one compozy.loop/v1 YAML document.

func (*Definition) Normalize

func (d *Definition) Normalize()

Normalize applies document-level zero-value semantics without inventing authoring defaults.

func (Definition) ValidateHeader

func (d Definition) ValidateHeader() error

ValidateHeader checks the fixed document identity.

type DefinitionExtensionState

type DefinitionExtensionState struct {
	Start []StartBinding `json:"start,omitempty" yaml:"start,omitempty"`
}

DefinitionExtensionState keeps optional authoring extensions off the hot Definition value.

type Edge

type Edge struct {
	From  NodeID         `json:"from" yaml:"from"`
	To    NodeID         `json:"to"   yaml:"to"`
	Extra map[string]any `json:"-"    yaml:",inline"`
}

Edge declares one blocks dependency.

type EffectSpec

type EffectSpec struct {
	Emit *EmitSpec      `json:"emit,omitzero"  yaml:"emit,omitempty"`
	Tool string         `json:"tool,omitempty" yaml:"tool,omitempty"`
	With map[string]any `json:"with,omitempty" yaml:"with,omitempty"`
}

EffectSpec describes one emitted event or tool call. Lint enforces the XOR.

type EmitSpec

type EmitSpec struct {
	Kind    string         `json:"kind"              yaml:"kind"`
	Payload map[string]any `json:"payload,omitempty" yaml:"payload,omitempty"`
}

EmitSpec describes one internal event effect.

type EntityKind

type EntityKind string

EntityKind is the closed vocabulary accepted by x-compozy-kind.

const (
	EntityKindAgent     EntityKind = "agent"
	EntityKindSkill     EntityKind = "skill"
	EntityKindLoop      EntityKind = "loop"
	EntityKindWorktree  EntityKind = "worktree"
	EntityKindSession   EntityKind = "session"
	EntityKindWorkspace EntityKind = "workspace"
	EntityKindSecret    EntityKind = "secret"
)

func (EntityKind) Valid

func (k EntityKind) Valid() bool

Valid reports whether the entity kind belongs to the closed annotation vocabulary.

type EnvironmentMode

type EnvironmentMode string

EnvironmentMode selects the execution root for one agent action.

const (
	// EnvironmentRoot runs from the parent workspace root.
	EnvironmentRoot EnvironmentMode = "root"
	// EnvironmentWorktree runs from one existing ready worktree.
	EnvironmentWorktree EnvironmentMode = "worktree"
	// EnvironmentPerRun creates one worktree for the execution instance.
	EnvironmentPerRun EnvironmentMode = "per_run"
	// EnvironmentDirectory runs from a contained directory under the selected root.
	EnvironmentDirectory EnvironmentMode = "directory"
)

type EnvironmentSpec

type EnvironmentSpec struct {
	Mode        EnvironmentMode `json:"mode"                   yaml:"mode"`
	WorktreeRef string          `json:"worktree_ref,omitempty" yaml:"worktree_ref,omitempty"`
	Directory   string          `json:"directory,omitempty"    yaml:"directory,omitempty"`
}

EnvironmentSpec describes the authored execution root for an agent action.

type ErrorPolicy

type ErrorPolicy struct {
	Route     NodeID       `json:"route,omitempty"     yaml:"route,omitempty"`
	AllowFail bool         `json:"allow_fail,omitzero" yaml:"allow_fail,omitempty"`
	Effects   []EffectSpec `json:"effects,omitempty"   yaml:"effects,omitempty"`
}

ErrorPolicy combines error flow with observational effects.

type EvalErrorPolicy

type EvalErrorPolicy string

EvalErrorPolicy selects the authored outcome for a predicate evaluation error.

const (
	// EvalErrorFail turns the predicate error into a routable authoring failure.
	EvalErrorFail EvalErrorPolicy = "fail"
	// EvalErrorExit exits the current loop through its normal completion path.
	EvalErrorExit EvalErrorPolicy = "exit"
)

func (EvalErrorPolicy) Valid

func (p EvalErrorPolicy) Valid() bool

Valid reports whether the policy belongs to the closed authoring vocabulary.

type EventSubscription

type EventSubscription struct {
	Kind   string `json:"kind"             yaml:"kind"`
	Filter string `json:"filter,omitempty" yaml:"filter,omitempty"`
}

EventSubscription declares one internal watch-events subscription.

type FileParseKind

type FileParseKind string

FileParseKind is the closed file-import parse mode vocabulary.

const (
	// FileParseJSON imports JSON files.
	FileParseJSON FileParseKind = "json"
	// FileParseText imports text files.
	FileParseText FileParseKind = "text"
)

type GateCriterion

type GateCriterion struct {
	ID       string         `json:"id"                 yaml:"id"`
	Type     CriterionType  `json:"type"               yaml:"type"`
	Check    string         `json:"check,omitempty"    yaml:"check,omitempty"`
	Expect   string         `json:"expect,omitempty"   yaml:"expect,omitempty"`
	Contains string         `json:"contains,omitempty" yaml:"contains,omitempty"`
	Agent    string         `json:"agent,omitempty"    yaml:"agent,omitempty"`
	Runtime  RuntimeSpec    `json:"runtime,omitzero"   yaml:"runtime,omitempty"`
	Rubric   string         `json:"rubric,omitempty"   yaml:"rubric,omitempty"`
	Prompt   string         `json:"prompt,omitempty"   yaml:"prompt,omitempty"`
	Tool     string         `json:"tool,omitempty"     yaml:"tool,omitempty"`
	Inputs   map[string]any `json:"inputs,omitempty"   yaml:"inputs,omitempty"`
	Metric   *MetricSpec    `json:"metric,omitzero"    yaml:"metric,omitempty"`
	Extra    map[string]any `json:"-"                  yaml:",inline"`
}

GateCriterion is one typed check in a gate or verification bundle.

type GoalParams

type GoalParams struct {
	Agent        string          `json:"agent"                  yaml:"agent"`
	Objective    string          `json:"objective"              yaml:"objective"`
	Judge        []GateCriterion `json:"judge"                  yaml:"judge"`
	MaxTurns     int             `json:"max_turns"              yaml:"max_turns"`
	OnExhausted  string          `json:"on_exhausted,omitempty" yaml:"on_exhausted,omitempty"`
	OutputSchema *Schema         `json:"output_schema,omitzero" yaml:"output_schema,omitempty"`
	Environment  EnvironmentSpec `json:"environment,omitzero"   yaml:"environment,omitempty"`
	Runtime      RuntimeSpec     `json:"runtime,omitzero"       yaml:"runtime,omitempty"`
	Extra        map[string]any  `json:"-"                      yaml:",inline"`
}

GoalParams is the canonical schema for action kind goal.

type Graph

type Graph struct {
	Nodes []Node         `json:"nodes" yaml:"nodes"`
	Edges []Edge         `json:"edges" yaml:"edges"`
	Extra map[string]any `json:"-"     yaml:",inline"`
}

Graph is the acyclic loop body.

func (*Graph) Normalize

func (g *Graph) Normalize()

Normalize initializes graph slices for stable callers.

type GraphDocument

type GraphDocument struct {
	Original Definition
	Nodes    []Node
	Edges    []Edge
}

GraphDocument is the editor-facing graph plus the original definition.

func DefinitionToGraph

func DefinitionToGraph(def Definition) *GraphDocument

DefinitionToGraph extracts the graph while retaining the original definition for structural merge.

type HarvestSpec

type HarvestSpec struct {
	Kind  string         `json:"kind,omitempty" yaml:"kind,omitempty"`
	Extra map[string]any `json:"-"              yaml:",inline"`
}

HarvestSpec configures action output harvest semantics.

type Input

type Input struct {
	Type        InputType      `json:"type"                  yaml:"type"`
	Required    bool           `json:"required,omitzero"     yaml:"required,omitempty"`
	Description string         `json:"description,omitempty" yaml:"description,omitempty"`
	Ref         *InputRef      `json:"ref,omitzero"          yaml:"ref,omitempty"`
	Enum        []string       `json:"enum,omitempty"        yaml:"enum,omitempty"`
	Default     any            `json:"default,omitempty"     yaml:"default,omitempty"`
	Extra       map[string]any `json:"-"                     yaml:",inline"`
}

Input declares one named loop input.

type InputRef

type InputRef struct {
	Kind  InputRefKind   `json:"kind" yaml:"kind"`
	Extra map[string]any `json:"-"    yaml:",inline"`
}

InputRef narrows an input of type ref to one resource kind.

type InputRefKind

type InputRefKind string

InputRefKind is the closed vocabulary for ref-backed Loop inputs.

const (
	InputRefKindSkill     InputRefKind = "skill"
	InputRefKindLoop      InputRefKind = "loop"
	InputRefKindWorktree  InputRefKind = "worktree"
	InputRefKindSession   InputRefKind = "session"
	InputRefKindWorkspace InputRefKind = "workspace"
	InputRefKindSecret    InputRefKind = "secret"
)

func (InputRefKind) Valid

func (k InputRefKind) Valid() bool

Valid reports whether the ref kind belongs to the closed DSL vocabulary.

type InputType

type InputType string

InputType is the closed declared input type vocabulary.

const (
	// InputTypeString declares a string input.
	InputTypeString InputType = "string"
	// InputTypeNumber declares a numeric input.
	InputTypeNumber InputType = "number"
	// InputTypeBoolean declares a boolean input.
	InputTypeBoolean InputType = "boolean"
	// InputTypeFile declares a file input.
	InputTypeFile InputType = "file"
	// InputTypeAgent declares an agent reference input.
	InputTypeAgent InputType = "agent"
	// InputTypeRef declares a typed resource reference input.
	InputTypeRef InputType = "ref"
	// InputTypeRuntime declares a partial Loop runtime object.
	InputTypeRuntime InputType = "runtime"
)

func (InputType) Valid

func (t InputType) Valid() bool

Valid reports whether the input type belongs to the closed DSL vocabulary.

type Meta

type Meta struct {
	Name        string         `json:"name"                  yaml:"name"`
	Version     int            `json:"version,omitzero"      yaml:"version,omitempty"`
	Description string         `json:"description,omitempty" yaml:"description,omitempty"`
	Catalog     CatalogMeta    `json:"catalog"               yaml:"catalog"`
	Extra       map[string]any `json:"-"                     yaml:",inline"`
}

Meta describes a loop definition for catalog and authoring surfaces.

type MetricDirection

type MetricDirection string

MetricDirection determines whether a metric score should increase or decrease.

const (
	// MetricMaximize accepts scores that increase by the configured delta.
	MetricMaximize MetricDirection = "maximize"
	// MetricMinimize accepts scores that decrease by the configured delta.
	MetricMinimize MetricDirection = "minimize"
)

type MetricSpec

type MetricSpec struct {
	Direction MetricDirection `json:"direction" yaml:"direction"`

	// MinDelta is the optional non-negative improvement required beyond the current best score.
	// Nil accepts any strict directional improvement; zero preserves strict comparison semantics.
	MinDelta *float64 `json:"min_delta,omitzero" yaml:"min_delta,omitempty"`
}

MetricSpec declares the score contract for one machine criterion.

type MissingPolicy

type MissingPolicy string

MissingPolicy records whether incomplete coverage is author-approved.

const MissingAcceptable MissingPolicy = "acceptable"

func (MissingPolicy) Valid

func (p MissingPolicy) Valid() bool

type NoProgress

type NoProgress struct {
	Window int            `json:"window" yaml:"window"`
	Extra  map[string]any `json:"-"      yaml:",inline"`
}

NoProgress defines the generation-level progress signature.

type Node

type Node struct {
	ID                  NodeID       `json:"id"                       yaml:"id"`
	Class               NodeClass    `json:"class"                    yaml:"class"`
	Kind                string       `json:"kind"                     yaml:"kind"`
	Session             *SessionSpec `json:"session,omitzero"         yaml:"session,omitempty"`
	Timeout             string       `json:"timeout,omitempty"        yaml:"timeout,omitempty"`
	Retry               *RetrySpec   `json:"retry,omitzero"           yaml:"retry,omitempty"`
	Review              *ReviewSpec  `json:"review,omitzero"          yaml:"review,omitempty"`
	*NodeLifecycleState `                                                    yaml:",inline"`
	Harvest             *HarvestSpec        `json:"harvest,omitzero"         yaml:"harvest,omitempty"`
	Produces            Schema              `json:"produces,omitempty"       yaml:"produces,omitempty"`
	Params              NodeParams          `json:"params,omitempty"         yaml:"params,omitempty"`
	Collection          string              `json:"collection,omitempty"     yaml:"collection,omitempty"`
	Filter              string              `json:"filter,omitempty"         yaml:"filter,omitempty"`
	BatchSize           int                 `json:"batch_size,omitzero"      yaml:"batch_size,omitempty"`
	MaxParallel         int                 `json:"max_parallel,omitzero"    yaml:"max_parallel,omitempty"`
	MaxFanOut           int                 `json:"max_fan_out,omitzero"     yaml:"max_fan_out,omitempty"`
	Strategy            *StrategySpec       `json:"strategy,omitzero"        yaml:"strategy,omitempty"`
	BindAs              string              `json:"bind_as,omitempty"        yaml:"bind_as,omitempty"`
	IndexAs             string              `json:"index_as,omitempty"       yaml:"index_as,omitempty"`
	Condition           string              `json:"condition,omitempty"      yaml:"condition,omitempty"`
	OnEvalError         EvalErrorPolicy     `json:"on_eval_error,omitempty"  yaml:"on_eval_error,omitempty"`
	Routes              []RouteSpec         `json:"routes,omitempty"         yaml:"routes,omitempty"`
	Default             NodeID              `json:"default,omitempty"        yaml:"default,omitempty"`
	Criteria            []GateCriterion     `json:"criteria,omitempty"       yaml:"criteria,omitempty"`
	VerdictPolicy       VerdictPolicy       `json:"verdict_policy,omitempty" yaml:"verdict_policy,omitempty"`
	OnResult            map[string]any      `json:"on_result,omitempty"      yaml:"on_result,omitempty"`
	MaxRevisions        int                 `json:"max_revisions,omitzero"   yaml:"max_revisions,omitempty"`
	Expires             *WaitExpiry         `json:"expires,omitzero"         yaml:"expires,omitempty"`
	Body                *Graph              `json:"body,omitzero"            yaml:"body,omitempty"`
	Contract            *Contract           `json:"contract,omitzero"        yaml:"contract,omitempty"`
	InputRef            string              `json:"input_ref,omitempty"      yaml:"input_ref,omitempty"`
	Pattern             string              `json:"pattern,omitempty"        yaml:"pattern,omitempty"`
	Parse               FileParseKind       `json:"parse,omitempty"          yaml:"parse,omitempty"`
	WatchSpec           map[string]any      `json:"watch,omitempty"          yaml:"watch,omitempty"`
	Events              []EventSubscription `json:"events,omitempty"         yaml:"events,omitempty"`
	Extra               map[string]any      `json:"-"                        yaml:",inline"`
}

Node is the single envelope for every graph node.

func (*Node) Normalize

func (n *Node) Normalize()

Normalize initializes optional node extensions without inventing authored values.

type NodeClass

type NodeClass string

NodeClass is the closed node class vocabulary.

const (
	// NodeClassAction is open and resolves against reserved kinds or ToolIDs.
	NodeClassAction NodeClass = "action"
	// NodeClassControl is a closed statically-verifiable class.
	NodeClassControl NodeClass = "control"
	// NodeClassSource is a closed statically-verifiable class.
	NodeClassSource NodeClass = "source"
)

type NodeID

type NodeID string

NodeID is the stable graph node identity.

type NodeLifecycleState

type NodeLifecycleState struct {
	Deadline       string          `json:"deadline,omitempty"        yaml:"deadline,omitempty"`
	ResultContract *ResultContract `json:"result_contract,omitzero"  yaml:"result_contract,omitempty"`
	OnError        *ErrorPolicy    `json:"on_error,omitzero"         yaml:"on_error,omitempty"`
	TriggerEffects `                                                   yaml:",inline"`
	OnParentClose  ParentClosePolicy `json:"on_parent_close,omitempty" yaml:"on_parent_close,omitempty"`
}

NodeLifecycleState keeps optional reliability grammar off the hot Node value.

type NodeParams

type NodeParams map[string]any

NodeParams holds raw action params and can decode into per-kind schema types.

func (NodeParams) Decode

func (p NodeParams) Decode(dest any) error

Decode unmarshals params into a concrete per-kind schema type.

type ParentClosePolicy

type ParentClosePolicy string

ParentClosePolicy controls what happens to an awaited child when its parent closes.

const (
	// ParentCloseTerminate closes the child according to the parent's terminal outcome.
	ParentCloseTerminate ParentClosePolicy = "terminate"
	// ParentCloseAbandon leaves the child running independently.
	ParentCloseAbandon ParentClosePolicy = "abandon"
)

func NormalizeStoredParentClosePolicy

func NormalizeStoredParentClosePolicy(value ParentClosePolicy) (ParentClosePolicy, bool)

NormalizeStoredParentClosePolicy maps durable predecessor values onto the authored vocabulary.

type RejectPolicy

type RejectPolicy struct {
	Route NodeID         `json:"route" yaml:"route"`
	Extra map[string]any `json:"-"     yaml:",inline"`
}

RejectPolicy selects the forward route taken by a rejected review.

type ResponderAgentPolicy

type ResponderAgentPolicy string

ResponderAgentPolicy is the closed agent-response policy for human requests.

const (
	// ResponderAgentsDeny keeps requests human-only, the default.
	ResponderAgentsDeny ResponderAgentPolicy = "deny"
	// ResponderAgentsAllow opts capable agents into responding.
	ResponderAgentsAllow ResponderAgentPolicy = "allow"
)

func (ResponderAgentPolicy) Valid

func (p ResponderAgentPolicy) Valid() bool

Valid reports whether the policy belongs to the closed responder enum.

type ResponderSpec

type ResponderSpec struct {
	Agents ResponderAgentPolicy `json:"agents,omitempty" yaml:"agents,omitempty"`
}

ResponderSpec controls which non-human principals may answer a request.

type ResultContract

type ResultContract struct {
	FailureField string `json:"failure_field"           yaml:"failure_field"`
	MessageField string `json:"message_field,omitempty" yaml:"message_field,omitempty"`
}

ResultContract declares the payload fields that represent an application failure.

type RetrySpec

type RetrySpec struct {
	MaxAttempts  int            `json:"max_attempts,omitzero"   yaml:"max_attempts,omitempty"`
	OnFailure    string         `json:"on_failure,omitempty"    yaml:"on_failure,omitempty"`
	Backoff      *BackoffSpec   `json:"backoff,omitzero"        yaml:"backoff,omitempty"`
	NonRetryable []string       `json:"non_retryable,omitempty" yaml:"non_retryable,omitempty"`
	Extra        map[string]any `json:"-"                       yaml:",inline"`
}

RetrySpec configures node retry policy.

type ReviewDecision

type ReviewDecision string

ReviewDecision is one allowed pre-execution review outcome.

const (
	ReviewDecisionApprove ReviewDecision = "approve"
	ReviewDecisionEdit    ReviewDecision = "edit"
	ReviewDecisionReject  ReviewDecision = "reject"
	ReviewDecisionRespond ReviewDecision = "respond"
)

func (ReviewDecision) Valid

func (d ReviewDecision) Valid() bool

Valid reports whether the decision belongs to the closed review enum.

type ReviewSpec

type ReviewSpec struct {
	Decisions  []ReviewDecision `json:"decisions,omitempty" yaml:"decisions,omitempty"`
	When       string           `json:"when,omitempty"      yaml:"when,omitempty"`
	Prompt     string           `json:"prompt,omitempty"    yaml:"prompt,omitempty"`
	Responders *ResponderSpec   `json:"responders,omitzero" yaml:"responders,omitempty"`
	OnReject   *RejectPolicy    `json:"on_reject,omitzero"  yaml:"on_reject,omitempty"`
	Expires    *WaitExpiry      `json:"expires,omitzero"    yaml:"expires,omitempty"`
	Extra      map[string]any   `json:"-"                   yaml:",inline"`
}

ReviewSpec gates an action before its task run is created.

func (ReviewSpec) EffectiveDecisions

func (r ReviewSpec) EffectiveDecisions() []ReviewDecision

EffectiveDecisions returns the authored allowlist or the safe default.

type ReviewedWorktreeCandidate

type ReviewedWorktreeCandidate struct {
	WorktreeID   string   `json:"worktree_id"   yaml:"worktree_id"`
	IncludePaths []string `json:"include_paths" yaml:"include_paths"`
	Fingerprint  string   `json:"fingerprint"   yaml:"fingerprint"`
}

func DecodeReviewedWorktree

func DecodeReviewedWorktree(inputs map[string]any) (*ReviewedWorktreeCandidate, error)

type RouteSpec

type RouteSpec struct {
	When string `json:"when" yaml:"when"`
	To   NodeID `json:"to"   yaml:"to"`
}

RouteSpec is one ordered predicate-to-destination mapping on a route node.

type RunAgentParams

type RunAgentParams struct {
	Agent        string          `json:"agent"                   yaml:"agent"`
	Prompt       string          `json:"prompt"                  yaml:"prompt"`
	OutputSchema Schema          `json:"output_schema,omitempty" yaml:"output_schema,omitempty"`
	Environment  EnvironmentSpec `json:"environment,omitzero"    yaml:"environment,omitempty"`
	Runtime      RuntimeSpec     `json:"runtime,omitzero"        yaml:"runtime,omitempty"`
	AllowedTools []string        `json:"allowed_tools,omitempty" yaml:"allowed_tools,omitempty"`
	MaxTurns     int             `json:"max_turns,omitzero"      yaml:"max_turns,omitempty"`
	Extra        map[string]any  `json:"-"                       yaml:",inline"`
}

RunAgentParams is the canonical schema for action kind run-agent.

type RunLoopMode

type RunLoopMode string

RunLoopMode controls child-loop completion semantics.

const (
	// RunLoopAwait waits for a child loop terminal event.
	RunLoopAwait RunLoopMode = "await"
	// RunLoopDetach returns immediately with the child run id.
	RunLoopDetach RunLoopMode = "detach"
)

type RunLoopParams

type RunLoopParams struct {
	Loop            string         `json:"loop"                       yaml:"loop"`
	Inputs          map[string]any `json:"inputs,omitempty"           yaml:"inputs,omitempty"`
	Mode            RunLoopMode    `json:"mode,omitempty"             yaml:"mode,omitempty"`
	ConfigOverrides map[string]any `json:"config_overrides,omitempty" yaml:"config_overrides,omitempty"`
	Extra           map[string]any `json:"-"                          yaml:",inline"`
}

RunLoopParams is the canonical schema for action kind run-loop.

type RuntimeDefaults

type RuntimeDefaults struct {
	Worker RuntimeSpec `json:"worker,omitzero" yaml:"worker,omitempty" toml:"worker"`
	Judge  RuntimeSpec `json:"judge,omitzero"  yaml:"judge,omitempty"  toml:"judge"`
}

RuntimeDefaults defines worker and judge runtime defaults.

type RuntimeMatch

type RuntimeMatch struct {
	ID         string         `json:"id,omitempty"         yaml:"id,omitempty"         toml:"id"`
	Type       string         `json:"type,omitempty"       yaml:"type,omitempty"       toml:"type"`
	Complexity string         `json:"complexity,omitempty" yaml:"complexity,omitempty" toml:"complexity"`
	Extra      map[string]any `json:"-"                    yaml:",inline"`
}

RuntimeMatch selects exactly one task id, one task type, one complexity, or a type and complexity conjunction. The conjunction is AND and id is exclusive.

type RuntimeRule

type RuntimeRule struct {
	Match   RuntimeMatch `json:"match"   yaml:"match"   toml:"match"`
	Runtime RuntimeSpec  `json:"runtime" yaml:"runtime" toml:"runtime"`
}

RuntimeRule applies one field-merged runtime override to matching tasks.

type RuntimeSpec

type RuntimeSpec struct {
	Provider   string               `json:"provider,omitempty"    yaml:"provider,omitempty"    toml:"provider"`
	Model      string               `json:"model,omitempty"       yaml:"model,omitempty"       toml:"model"`
	Reasoning  string               `json:"reasoning,omitempty"   yaml:"reasoning,omitempty"   toml:"reasoning"`
	Speed      speedpkg.Speed       `json:"speed,omitempty"       yaml:"speed,omitempty"       toml:"speed"`
	ACPOptions []ACPOptionSelection `json:"acp_options,omitempty" yaml:"acp_options,omitempty" toml:"acp_options,omitempty"`
	Extra      map[string]any       `json:"-"                     yaml:",inline"`
}

RuntimeSpec selects one provider runtime without owning provider policy.

func (*RuntimeSpec) UnmarshalYAML

func (r *RuntimeSpec) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML keeps runtime authoring closed and type-safe at every YAML ingress.

type Schema

type Schema map[string]any

Schema is a JSON-schema-compatible object or the TechSpec shorthand map.

type SessionSpec

type SessionSpec struct {
	Handle   string         `json:"handle,omitempty"  yaml:"handle,omitempty"`
	Isolated bool           `json:"isolated,omitzero" yaml:"isolated,omitempty"`
	Mode     string         `json:"mode,omitempty"    yaml:"mode,omitempty"`
	Extra    map[string]any `json:"-"                 yaml:",inline"`
}

SessionSpec configures action session binding.

type SourceKind

type SourceKind string

SourceKind is the closed source-node vocabulary.

const (
	// SourceInput exposes a declared input into the graph.
	SourceInput SourceKind = "input"
	// SourceFileImport imports workspace files.
	SourceFileImport SourceKind = "file-import"
	// SourceWatchSource polls an extension watch source.
	SourceWatchSource SourceKind = "watch-source"
	// SourceWatchEvents subscribes to committed internal Compozy events.
	SourceWatchEvents SourceKind = "watch-events"
)

type StartBinding

type StartBinding struct {
	Kind         StartKind         `json:"kind"                    yaml:"kind"`
	Inputs       map[string]any    `json:"inputs,omitempty"        yaml:"inputs,omitempty"`
	InputMapping map[string]string `json:"input_mapping,omitempty" yaml:"input_mapping,omitempty"`
	Extra        map[string]any    `json:"-"                       yaml:",inline"`
}

StartBinding declares one permitted start surface.

type StartKind

type StartKind string

StartKind is the closed start-surface allowlist vocabulary.

const (
	// StartManual allows operator web/manual starts.
	StartManual StartKind = "manual"
	// StartCLI allows CLI starts.
	StartCLI StartKind = "cli"
	// StartHTTP allows HTTP starts.
	StartHTTP StartKind = "http"
	// StartUDS allows UDS starts.
	StartUDS StartKind = "uds"
	// StartTrigger allows automation trigger starts.
	StartTrigger StartKind = "trigger"
	// StartSchedule allows scheduled starts.
	StartSchedule StartKind = "schedule"
	// StartWebhook allows webhook starts.
	StartWebhook StartKind = "webhook"
	// StartExtension allows extension starts.
	StartExtension StartKind = "extension"
	// StartNativeTool allows native-tool starts.
	StartNativeTool StartKind = "native_tool"
)

type StopWhenSpec

type StopWhenSpec struct {
	Expr        string          `json:"expr"                    yaml:"expr"`
	OnEvalError EvalErrorPolicy `json:"on_eval_error,omitempty" yaml:"on_eval_error,omitempty"`
}

StopWhenSpec accepts a plain expression or an object with an error-policy override.

func (StopWhenSpec) IsZero

func (s StopWhenSpec) IsZero() bool

IsZero lets encoding callers omit an unauthored stop condition.

func (StopWhenSpec) MarshalJSON

func (s StopWhenSpec) MarshalJSON() ([]byte, error)

MarshalJSON preserves scalar JSON for the default policy.

func (StopWhenSpec) MarshalYAML

func (s StopWhenSpec) MarshalYAML() (any, error)

MarshalYAML preserves the compact scalar form when no override was authored.

func (*StopWhenSpec) UnmarshalJSON

func (s *StopWhenSpec) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes the same strict forms at JSON ingress.

func (*StopWhenSpec) UnmarshalYAML

func (s *StopWhenSpec) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML decodes the strict string-or-object authoring form.

type StrategyKind

type StrategyKind string

StrategyKind selects the completion rule for a fan-out scope.

const (
	StrategyWaitAll    StrategyKind = "wait_all"
	StrategyFailFast   StrategyKind = "fail_fast"
	StrategyBestEffort StrategyKind = "best_effort"
	StrategyRace       StrategyKind = "race"
)

func (StrategyKind) Valid

func (k StrategyKind) Valid() bool

type StrategySpec

type StrategySpec struct {
	Kind      StrategyKind       `json:"kind"               yaml:"kind"`
	Threshold *StrategyThreshold `json:"threshold,omitzero" yaml:"threshold,omitempty"`
	Missing   MissingPolicy      `json:"missing,omitempty"  yaml:"missing,omitempty"`
}

StrategySpec declares one fan-out join strategy.

func (StrategySpec) MarshalJSON

func (s StrategySpec) MarshalJSON() ([]byte, error)

func (StrategySpec) MarshalYAML

func (s StrategySpec) MarshalYAML() (any, error)

func (*StrategySpec) UnmarshalJSON

func (s *StrategySpec) UnmarshalJSON(data []byte) error

func (*StrategySpec) UnmarshalYAML

func (s *StrategySpec) UnmarshalYAML(value *yaml.Node) error

func (StrategySpec) ValidateShape

func (s StrategySpec) ValidateShape() error

type StrategyThreshold

type StrategyThreshold struct {
	Kind    ThresholdKind
	Percent int
	Count   int
}

StrategyThreshold is exactly either an integer percent string or a count object.

func (StrategyThreshold) MarshalJSON

func (t StrategyThreshold) MarshalJSON() ([]byte, error)

func (StrategyThreshold) MarshalYAML

func (t StrategyThreshold) MarshalYAML() (any, error)

func (*StrategyThreshold) UnmarshalJSON

func (t *StrategyThreshold) UnmarshalJSON(data []byte) error

func (*StrategyThreshold) UnmarshalYAML

func (t *StrategyThreshold) UnmarshalYAML(value *yaml.Node) error

func (StrategyThreshold) Validate

func (t StrategyThreshold) Validate() error

type TerminalEffects

type TerminalEffects struct {
	OnDone      []EffectSpec `json:"on_done,omitempty"      yaml:"on_done,omitempty"`
	OnNoOp      []EffectSpec `json:"on_noop,omitempty"      yaml:"on_noop,omitempty"`
	OnBlocked   []EffectSpec `json:"on_blocked,omitempty"   yaml:"on_blocked,omitempty"`
	OnFailed    []EffectSpec `json:"on_failed,omitempty"    yaml:"on_failed,omitempty"`
	OnExhausted []EffectSpec `json:"on_exhausted,omitempty" yaml:"on_exhausted,omitempty"`
	OnStalled   []EffectSpec `json:"on_stalled,omitempty"   yaml:"on_stalled,omitempty"`
	OnCanceled  []EffectSpec `json:"on_canceled,omitempty"  yaml:"on_canceled,omitempty"`
}

TerminalEffects contains the exactly-once contract terminal effect lists.

type TerminalState

type TerminalState string

TerminalState is the closed terminal outcome vocabulary.

const (
	// TerminalDone means the contract is verified.
	TerminalDone TerminalState = "done"
	// TerminalNoOp means the loop had nothing to do.
	TerminalNoOp TerminalState = "no-op"
	// TerminalBlocked means an explicit external dependency blocked progress.
	TerminalBlocked TerminalState = "blocked"
	// TerminalFailed means an unrecoverable failure occurred.
	TerminalFailed TerminalState = "failed"
	// TerminalExhausted means a hard stop limit tripped.
	TerminalExhausted TerminalState = "exhausted"
	// TerminalStalled means progress stopped.
	TerminalStalled TerminalState = "stalled"
	// TerminalCanceled means an operator canceled the run.
	TerminalCanceled TerminalState = "canceled"
)

type ThresholdKind

type ThresholdKind string
const (
	ThresholdPercent ThresholdKind = "percent"
	ThresholdCount   ThresholdKind = "count"
)

type TransformMapping

type TransformMapping struct {
	From     string         `json:"from,omitempty"     yaml:"from,omitempty"`
	Value    any            `json:"value,omitempty"    yaml:"value,omitempty"`
	Template string         `json:"template,omitempty" yaml:"template,omitempty"`
	Extra    map[string]any `json:"-"                  yaml:",inline"`
}

TransformMapping maps one output key from a namespace path, literal, or template.

type TransformParams

type TransformParams struct {
	Map   map[string]TransformMapping `json:"map" yaml:"map"`
	Extra map[string]any              `json:"-"   yaml:",inline"`
}

TransformParams is the canonical schema for action kind transform.

type TriggerEffects

type TriggerEffects struct {
	OnRetry      []EffectSpec `json:"on_retry,omitempty"      yaml:"on_retry,omitempty"`
	OnSuccess    []EffectSpec `json:"on_success,omitempty"    yaml:"on_success,omitempty"`
	OnPause      []EffectSpec `json:"on_pause,omitempty"      yaml:"on_pause,omitempty"`
	OnTimeout    []EffectSpec `json:"on_timeout,omitempty"    yaml:"on_timeout,omitempty"`
	OnCancel     []EffectSpec `json:"on_cancel,omitempty"     yaml:"on_cancel,omitempty"`
	OnQuarantine []EffectSpec `json:"on_quarantine,omitempty" yaml:"on_quarantine,omitempty"`
}

TriggerEffects contains the six node-lifecycle effect lists.

type VerdictPolicy

type VerdictPolicy string

VerdictPolicy controls how a gate reaches a verdict.

const (
	// VerdictPolicyReviseUntilClean requires an agent/human verdict source.
	VerdictPolicyReviseUntilClean VerdictPolicy = "revise_until_clean"
	// VerdictPolicyFixedPasses is command-only compatible.
	VerdictPolicyFixedPasses VerdictPolicy = "fixed_passes"
)

type WaitAheadArrival

type WaitAheadArrival string

WaitAheadArrival controls how an event observed before entry is handled.

const (
	// WaitAheadConsumeOnEntry consumes the matching event when the cell enters the wait.
	WaitAheadConsumeOnEntry WaitAheadArrival = "consume_on_entry"
	// WaitAheadReject rejects events that arrived before the cell entered the wait.
	WaitAheadReject WaitAheadArrival = "reject"
)

type WaitExpiry

type WaitExpiry struct {
	After    string         `json:"after"              yaml:"after"`
	Escalate []EffectSpec   `json:"escalate,omitempty" yaml:"escalate,omitempty"`
	Route    NodeID         `json:"route,omitempty"    yaml:"route,omitempty"`
	Extra    map[string]any `json:"-"                  yaml:",inline"`
}

WaitExpiry describes an optional expiry path for waits and human gates.

type WaitParams

type WaitParams struct {
	For          string             `json:"for,omitempty"           yaml:"for,omitempty"`
	Until        string             `json:"until,omitempty"         yaml:"until,omitempty"`
	Event        *EventSubscription `json:"event,omitzero"          yaml:"event,omitempty"`
	Expect       Schema             `json:"expect,omitempty"        yaml:"expect,omitempty"`
	AheadArrival WaitAheadArrival   `json:"ahead_arrival,omitempty" yaml:"ahead_arrival,omitempty"`
	Expires      *WaitExpiry        `json:"expires,omitzero"        yaml:"expires,omitempty"`
	Extra        map[string]any     `json:"-"                       yaml:",inline"`
}

WaitParams declares exactly one timer, timestamp, or event wait.

Directories

Path Synopsis
Package refs validates loop template and CEL references against one namespace.
Package refs validates loop template and CEL references against one namespace.

Jump to

Keyboard shortcuts

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