Documentation
¶
Overview ¶
Package agentvalidate is the store-free, deterministic check of the agents layer (.satelle/workflows/agents.toml) and each workflow's agent= node bindings.
It is the SINGLE authority three callers share (sty_93eec36d):
- `satelle agent validate` (standalone, on-demand)
- `satelle init` deployment validation
- story engagement (leaving the workflow entry state for a non-cancel target)
It deliberately does NOT re-implement structure.Doc (performing-node rubrics) or agentstep.WorkflowConsistency (unresolved gate skills / ambiguous applies_to) — those stay owned by their existing checks. This package adds only: every binding's command/timeout/env resolves, each agent's resolved grant is inspectable, every agent=<name> node has a matching binding, and orphaned named bindings are flagged.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type GateAllocation ¶ added in v0.0.198
type GateAllocation struct {
Workflow string
Node string // state name, "edge:from→to" for edge gates, or "hook:<operation>"
Skill string
Agent string // binding section that will run the gate
BindingModel string
EffectiveModel string // same as BindingModel (no DOT override)
// Operation is the lifecycle operation for a HOOK allocation (sty_ede16f51),
// empty for a DOT node or edge. Hooks fire outside the status graph, so they
// are surfaced alongside gates rather than being invisible.
Operation string
// Source records how a hook allocation was declared — wfhook.SourceHooks or
// wfhook.SourceShorthand — so a display can say whether the agent was chosen
// or defaulted. Empty for a DOT node or edge.
Source string
}
GateAllocation is one workflow gate/node's resolved binding (sty_a476a2f8). EffectiveModel is the binding's model — agents.toml owns model, not the DOT.
type Grant ¶
type Grant struct {
Name string
Backend string // in-loop | isolated:claude | isolated:grok | isolated:codex | isolated:<binary> | acp:<binary>
Interface string // command | acp (epic:agent-dispatch-transport)
// Command is the effective command template — the literal argv the operator
// can read. Surfaced as a field (not only inside Notes) so a provenance
// display can attribute it like any other resolved value (sty_c7dfeedf).
Command string
// Secondary is the rate-limit failover binding name (sty_5bf61f89), empty
// when unconfigured.
Secondary string
Tools string
Model string
Effort string // optional reasoning effort (sty_657f77b9)
Timeout string
ReadOnly bool
InjectsPrinciples bool
Role string // resolved role: reviewer | agent (sty_e21cbc08)
Principles string // resolved principles selector
RoleInferred bool // true when role was not declared in agents.toml
Notes string // non-secret notes (e.g. env key names, command ceiling hints)
// ContextChannel reports whether the grant carries a pull-context channel —
// what a DISPATCHED performer needs to reconstruct its context, and what a
// reviewer never uses (sty_87c0ef37). Inspectable so the fact is visible
// without re-deriving it from Tools.
ContextChannel bool
// Sources maps each effective field (command, tools, model, …) to the tier
// that supplied it: "repo", "profile:<name>", "global-role:<name>", or
// "embedded" (sty_c7dfeedf). Nil when the caller validated without resolving
// the machine-wide catalog. An operator reading a grant can then see not only
// WHAT the reviewer will run but WHERE that value was authored.
Sources map[string]string
}
Grant is one agent's resolved, inspectable capability surface — what validate surfaces so a preset's baked grant is visible without knowing the expansion. Env VALUES are never included (secrets); key names may appear in Notes.
type Report ¶
type Report struct {
Problems []string
Warnings []string
Grants []Grant
// Gates lists every gate edge / scoped reviewer node / named performer with
// its effective model so drift audits see per-node allocation (sty_19456622).
Gates []GateAllocation
// Provenance is the per-binding, per-field source table when the report was
// produced by ValidateEffective; nil for the catalog-free Validate.
Provenance config.Provenance
// Findings is the same set of observations as Problems/Warnings, carrying a
// STABLE identifier and remediation each (sty_e9da28e2). Problems/Warnings
// remain the prose surfaces older callers print; every finding's Detail is
// the very string that appears there, so the two cannot drift.
Findings health.Findings
}
Report is the structured result of Validate. Problems are hard failures (non-zero exit / engage refuse). Warnings are advisory (e.g. orphaned named bindings that may still be used by non-workflow verbs like `story retrospect`) — printed, not failed.
func Validate ¶
Validate checks every agents.toml binding and each workflow's agent= node allocations. vars is the [vars] KV used to resolve ${VAR} in binding env/ settings (may be nil). workflows may be empty (agent-only check). Callers that have already resolved the machine-wide catalog pass the effective layer here; ValidateEffective is the form that resolves it and reports provenance.
func ValidateEffective ¶ added in v0.0.365
func ValidateEffective(repo config.AgentsConfig, global config.GlobalAgentsConfig, repoVars map[string]string, workflows []docindex.Doc) Report
ValidateEffective resolves a repo's agents layer against the machine-wide profile catalog and validates the RESULT — the bindings that will actually run (sty_c7dfeedf). A resolution failure (missing profile, reference cycle, repo/ profile role conflict) becomes a Problem rather than an early return, so `satelle agent validate` reports the whole picture in one pass instead of stopping at the first broken reference; the un-resolved repo layer is then validated so the remaining findings still surface.
Every other check — reviewer read-only ceiling, interface, context channel, workflow allocation — runs against the merged binding, so a profile cannot smuggle a capability past a check by supplying it from the catalog.
func ValidateEffectiveWithSkills ¶ added in v0.0.428
func ValidateEffectiveWithSkills(repo config.AgentsConfig, global config.GlobalAgentsConfig, repoVars map[string]string, workflows []docindex.Doc, skills SkillBody) Report
ValidateEffectiveWithSkills is ValidateEffective plus the skill-body resolver. Surfaces that judge a whole DEPLOYED repo (doctor, and therefore `satelle init`, and `satelle agent validate`) pass one; the narrower callers do not.
type SkillBody ¶ added in v0.0.428
SkillBody reads a skill's markdown body by name, reporting whether it resolved. It is the ONE thing a caller can supply that this package cannot derive from its arguments: whether a reviewer's rubric shells `satelle`, and therefore whether a shell grant is live (sty_338a53f8).
It is OPTIONAL. A nil resolver means "no skill bodies available", and every check behaves exactly as it did before — a caller that only has the agents layer in hand keeps working, it just cannot see that evidence.
Source Files