Documentation
¶
Overview ¶
Package dsl defines the compozy.loop/v1 authoring document.
Package dsl defines the compozy.loop/v1 authoring document.
Index ¶
- Constants
- func DeriveGoalHandle(nodeID NodeID, label string, itemIndex int) (string, error)
- func IsKnownControlKind(kind string) bool
- func IsKnownParentClosePolicy(value ParentClosePolicy) bool
- func IsKnownSourceKind(kind string) bool
- func IsKnownTerminalState(value TerminalState) bool
- func IsKnownWaitAheadArrival(value WaitAheadArrival) bool
- func IsReservedActionKind(kind string) bool
- func Serialize(def Definition) ([]byte, error)
- type ACPOptionSelection
- func CanonicalACPOptionSelections(selections []ACPOptionSelection) []ACPOptionSelection
- func CloneACPOptionSelections(selections []ACPOptionSelection) []ACPOptionSelection
- func MergeACPOptionSelections(base []ACPOptionSelection, overlay []ACPOptionSelection) ([]ACPOptionSelection, []string)
- func NormalizeACPOptionSelections(selections []ACPOptionSelection) ([]ACPOptionSelection, error)
- func NormalizeACPOptionSelectionsAt(path string, selections []ACPOptionSelection) ([]ACPOptionSelection, error)
- type ActionKind
- type AskParams
- type BackoffSpec
- type Budget
- type BudgetExceeded
- type CatalogMeta
- type ConcurrencyPolicy
- type Contract
- type ContractLifecycleState
- type ControlKind
- type CriterionType
- type Definition
- type DefinitionExtensionState
- type Edge
- type EffectSpec
- type EmitSpec
- type EntityKind
- type EnvironmentMode
- type EnvironmentSpec
- type ErrorPolicy
- type EvalErrorPolicy
- type EventSubscription
- type FileParseKind
- type GateCriterion
- type GoalParams
- type Graph
- type GraphDocument
- type HarvestSpec
- type Input
- type InputRef
- type InputRefKind
- type InputType
- type Meta
- type MetricDirection
- type MetricSpec
- type MissingPolicy
- type NoProgress
- type Node
- type NodeClass
- type NodeID
- type NodeLifecycleState
- type NodeParams
- type ParentClosePolicy
- type RejectPolicy
- type ResponderAgentPolicy
- type ResponderSpec
- type ResultContract
- type RetrySpec
- type ReviewDecision
- type ReviewSpec
- type ReviewedWorktreeCandidate
- type RouteSpec
- type RunAgentParams
- type RunLoopMode
- type RunLoopParams
- type RuntimeDefaults
- type RuntimeMatch
- type RuntimeRule
- type RuntimeSpec
- type Schema
- type SessionSpec
- type SourceKind
- type StartBinding
- type StartKind
- type StopWhenSpec
- type StrategyKind
- type StrategySpec
- type StrategyThreshold
- type TerminalEffects
- type TerminalState
- type ThresholdKind
- type TransformMapping
- type TransformParams
- type TriggerEffects
- type VerdictPolicy
- type WaitAheadArrival
- type WaitExpiry
- type WaitParams
Constants ¶
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" )
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 )
const ReviewedWorktreeInput = "reviewed_worktree"
Variables ¶
This section is empty.
Functions ¶
func DeriveGoalHandle ¶
DeriveGoalHandle returns the fixed persisted binding identity for one Goal node item.
func IsKnownControlKind ¶
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 ¶
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 ¶
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,omitempty" yaml:"responders,omitempty"`
Expires *WaitExpiry `json:"expires,omitempty" 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,omitempty" 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.
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,omitempty" 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,omitempty" 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,omitempty" 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,omitempty" 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.
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,omitempty" yaml:"required,omitempty"`
Description string `json:"description,omitempty" yaml:"description,omitempty"`
Ref *InputRef `json:"ref,omitempty" 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" )
type Meta ¶
type Meta struct {
Name string `json:"name" yaml:"name"`
Version int `json:"version,omitempty" 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,omitempty" 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,omitempty" yaml:"session,omitempty"`
Timeout string `json:"timeout,omitempty" yaml:"timeout,omitempty"`
Retry *RetrySpec `json:"retry,omitempty" yaml:"retry,omitempty"`
Review *ReviewSpec `json:"review,omitempty" yaml:"review,omitempty"`
*NodeLifecycleState ` yaml:",inline"`
Harvest *HarvestSpec `json:"harvest,omitempty" 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,omitempty" yaml:"batch_size,omitempty"`
MaxParallel int `json:"max_parallel,omitempty" yaml:"max_parallel,omitempty"`
MaxFanOut int `json:"max_fan_out,omitempty" yaml:"max_fan_out,omitempty"`
Strategy *StrategySpec `json:"strategy,omitempty" 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,omitempty" yaml:"max_revisions,omitempty"`
Expires *WaitExpiry `json:"expires,omitempty" yaml:"expires,omitempty"`
Body *Graph `json:"body,omitempty" yaml:"body,omitempty"`
Contract *Contract `json:"contract,omitempty" 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.
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 NodeLifecycleState ¶
type NodeLifecycleState struct {
Deadline string `json:"deadline,omitempty" yaml:"deadline,omitempty"`
ResultContract *ResultContract `json:"result_contract,omitempty" yaml:"result_contract,omitempty"`
OnError *ErrorPolicy `json:"on_error,omitempty" 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 ¶
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,omitempty" yaml:"max_attempts,omitempty"`
OnFailure string `json:"on_failure,omitempty" yaml:"on_failure,omitempty"`
Backoff *BackoffSpec `json:"backoff,omitempty" 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,omitempty" yaml:"responders,omitempty"`
OnReject *RejectPolicy `json:"on_reject,omitempty" yaml:"on_reject,omitempty"`
Expires *WaitExpiry `json:"expires,omitempty" 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 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,omitempty" 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 SessionSpec ¶
type SessionSpec struct {
Handle string `json:"handle,omitempty" yaml:"handle,omitempty"`
Isolated bool `json:"isolated,omitempty" 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,omitempty" 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,omitempty" 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,omitempty" yaml:"expires,omitempty"`
Extra map[string]any `json:"-" yaml:",inline"`
}
WaitParams declares exactly one timer, timestamp, or event wait.