agentvalidate

Documentation

Overview

Package agentvalidate is the store-free, deterministic check of the agents layer (.satelle/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

• type GateAllocation
• type Grant
• type Report
  • func Validate(agents config.AgentsConfig, vars map[string]string, workflows []docindex.Doc) Report
  • func (r Report) OK() bool

Types

type GateAllocation

type GateAllocation struct {
	Workflow       string
	Node           string // state name, or "edge:from→to" for edge gates
	Skill          string
	Agent          string // binding section: reviewer | named agent
	BindingModel   string
	NodeModel      string // DOT model= when set
	EffectiveModel string // NodeModel if set, else BindingModel
}

GateAllocation is one workflow gate/node's effective model resolution (sty_19456622): binding model vs optional DOT model= override.

type Grant

type Grant struct {
	Name              string
	Backend           string // in-loop | isolated:claude | isolated:grok | isolated:<binary> | codex (unmapped)
	Tools             string
	Model             string
	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)
}

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
}

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

func Validate(agents config.AgentsConfig, vars map[string]string, workflows []docindex.Doc) Report

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).

func (Report) OK

func (r Report) OK() bool

OK reports whether the report carries no hard problems.