Documentation
¶
Overview ¶
Package scenariofile parses graith scenario TOML files. It is shared by the CLI (gr scenario start) and the daemon (scenario trigger action) so both build a protocol.ScenarioStartMsg from the same code.
Index ¶
- Constants
- func MemberPolicyInput(policy *MemberPolicyConfig) *protocol.ScenarioMemberPolicyInput
- func PolicyInput(policy *PolicyConfig) *protocol.ScenarioPolicyInput
- func SessionInputs(sf *File) ([]protocol.ScenarioSessionInput, error)
- func ValidateMirrorMembers(members []MirrorMember) ([]int, error)
- func ValidatePolicyContracts(policy *NormalizedPolicy, members []PolicyMember, maxTitle int) error
- func ValidateScenarioTriggers(triggers []config.TriggerConfig, roles, members map[string]bool, ...) error
- func ValidateSessionDependencies(sessions []protocol.ScenarioSessionInput) error
- type File
- type MemberPolicyConfig
- type Meta
- type MirrorMember
- type NormalizedMemberPolicy
- type NormalizedPolicy
- type PolicyConfig
- type PolicyMember
- type Result
- type Session
Constants ¶
const ( CompletionAll = "all" CompletionQuorum = "quorum" OnExhaustedWait = "wait" OnExhaustedFail = "fail" PolicyResolution = time.Second MaxRetries = 10 )
Variables ¶
This section is empty.
Functions ¶
func MemberPolicyInput ¶ added in v0.69.2
func MemberPolicyInput(policy *MemberPolicyConfig) *protocol.ScenarioMemberPolicyInput
MemberPolicyInput maps a parsed member policy into the wire shape.
func PolicyInput ¶ added in v0.69.2
func PolicyInput(policy *PolicyConfig) *protocol.ScenarioPolicyInput
PolicyInput maps a parsed scenario policy into the wire shape.
func SessionInputs ¶
func SessionInputs(sf *File) ([]protocol.ScenarioSessionInput, error)
SessionInputs maps a parsed File's sessions to protocol.ScenarioSessionInput. agent_hooks defaults to true when unset.
func ValidateMirrorMembers ¶ added in v0.69.2
func ValidateMirrorMembers(members []MirrorMember) ([]int, error)
ValidateMirrorMembers checks mirror field compatibility and returns each member's dependency depth (roots are zero, a mirror of a root is one, and so on). The daemon uses the depths as creation waves so every source exists before its readers start. References are names within this slice only.
func ValidatePolicyContracts ¶ added in v0.69.2
func ValidatePolicyContracts(policy *NormalizedPolicy, members []PolicyMember, maxTitle int) error
ValidatePolicyContracts verifies that every policy-managed member has a seedable todo result contract. maxTitle is the effective todo title limit; pass zero to check only presence.
func ValidateScenarioTriggers ¶ added in v0.68.5
func ValidateScenarioTriggers(triggers []config.TriggerConfig, roles, members map[string]bool, ownedMembersOpt ...map[string]bool) error
ValidateScenarioTriggers validates the scenario-embedded [[trigger]] blocks. Each trigger must pass the shared structural validation (config.ValidateTriggerStructure) and the scenario-specific restrictions: it may only select sessions by a `role` the scenario defines (never a `repo`), it may not set an external execution repo, and its delivery inbox may only name a scenario member (or "orchestrator"/a template) — never a session outside the scenario. See issue #1027. Returns the first error found.
func ValidateSessionDependencies ¶ added in v0.69.2
func ValidateSessionDependencies(sessions []protocol.ScenarioSessionInput) error
ValidateSessionDependencies validates the member-name DAG carried by a scenario definition. Both the CLI parser and daemon call it so a client cannot bypass unknown-member, missing-task, or cycle checks.
Types ¶
type File ¶
type File struct {
Version int `toml:"version"`
Scenario Meta `toml:"scenario"`
Sessions []Session `toml:"sessions"`
Triggers []config.TriggerConfig `toml:"trigger"`
}
File is the on-disk scenario definition.
func Parse ¶
Parse decodes and validates a scenario TOML document. Unknown fields are rejected so typos surface as errors.
func (*File) DefinedMembers ¶ added in v0.68.5
DefinedMembers returns the set of session names in the scenario (including shared members). A scenario trigger's literal inbox delivery target must be one of these (or "orchestrator", or a template) — it may not name a session outside the scenario.
func (*File) DefinedOwnedMembers ¶ added in v0.69.2
DefinedOwnedMembers returns the non-shared members that can safely supply a completion trigger's execution/mirror context.
func (*File) DefinedRoles ¶ added in v0.68.5
DefinedRoles returns the set of non-empty roles the scenario's own (non-shared) sessions declare. A scenario [[trigger]] watch may only select by one of these — a shared session keeps its original scenario identity, so a watch trigger could never bind to it, and allowing its role would validate a trigger that can never fire.
type MemberPolicyConfig ¶ added in v0.69.2
type MemberPolicyConfig struct {
Required *bool `toml:"required"`
Timeout string `toml:"timeout"`
Retries int `toml:"retries"`
}
MemberPolicyConfig is the optional [sessions.policy] TOML block.
type Meta ¶
type Meta struct {
Name string `toml:"name"`
Goal string `toml:"goal"`
Lifecycle config.ScenarioLifecycleConfig `toml:"lifecycle"`
Policy *PolicyConfig `toml:"policy"`
}
Meta is the [scenario] block.
type MirrorMember ¶ added in v0.69.2
MirrorMember is the structural subset of a scenario member needed to validate scenario-local mirror references. Keeping this independent of the CLI and protocol representations lets every scenario entry point enforce the same rules before it performs filesystem or daemon mutations.
type NormalizedMemberPolicy ¶ added in v0.69.2
NormalizedMemberPolicy is one member's resolved policy.
type NormalizedPolicy ¶ added in v0.69.2
type NormalizedPolicy struct {
Completion string
Quorum int
OnExhausted string
Members []NormalizedMemberPolicy
}
NormalizedPolicy contains defaults resolved for authoritative daemon state.
func NormalizePolicy ¶ added in v0.69.2
func NormalizePolicy(policy *PolicyConfig, members []PolicyMember) (*NormalizedPolicy, error)
NormalizePolicy validates and resolves scenario runtime policy. A nil result means neither the scenario nor any member opted into policy semantics.
type PolicyConfig ¶ added in v0.69.2
type PolicyConfig struct {
Completion string `toml:"completion"`
Quorum int `toml:"quorum"`
OnExhausted string `toml:"on_exhausted"`
}
PolicyConfig is the optional [scenario.policy] TOML block.
type PolicyMember ¶ added in v0.69.2
type PolicyMember struct {
Name string
Task string
HasRequiredResult bool
Policy *MemberPolicyConfig
}
PolicyMember is the policy-relevant subset of a scenario member.
type Result ¶ added in v0.69.2
type Result struct {
Name string `toml:"name"`
Format string `toml:"format"`
Store string `toml:"store"`
Required bool `toml:"required"`
}
Result is one [[sessions.results]] declaration. Store is relative to the scenario's shared-store result directory and may contain supported template placeholders; the daemon validates and resolves it authoritatively.
type Session ¶
type Session struct {
Name string `toml:"name"`
Repo string `toml:"repo"`
Mirror string `toml:"mirror"`
Agent string `toml:"agent"`
Model string `toml:"model"`
Base string `toml:"base"`
Role string `toml:"role"`
Task string `toml:"task"`
DependsOn []string `toml:"depends_on"`
AgentHooks *bool `toml:"agent_hooks"`
// Includes attaches extra worktrees to the session, in addition to any
// inherited from the repo's [[repos]] config. See issue #1046.
Includes []string `toml:"includes"`
// Star creates the session starred so it is protected from an accidental
// manual `gr delete` (shared = true only shields from scenario stop/delete).
Star bool `toml:"star"`
Results []Result `toml:"results"`
Policy *MemberPolicyConfig `toml:"policy"`
}
Session is one [[sessions]] entry.