Documentation
¶
Overview ¶
Package posture defines the AgentPosture configuration type that the sub-agent invocation primitive consumes, together with an in-memory registry that nexus.agent.postures populates from on-disk YAML.
A posture is a named, versioned configuration describing how a sub-agent should run: which system prompt, which subset of tools, which model, and what resource budget. Postures are the contract that parent agents reference when they delegate work — see Session.Delegate in the engine.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNotFound = errors.New("posture: not found")
ErrNotFound is returned by Get/Remove when the requested posture is absent.
Functions ¶
func HashPosture ¶
func HashPosture(p AgentPosture) string
HashPosture computes the version hash for a posture from its content. The loader assigns this to Version when installing from YAML; consumers should treat it as opaque.
Types ¶
type AgentPosture ¶
type AgentPosture struct {
// Name is the registry key parent agents reference when delegating.
Name string `yaml:"name" json:"name"`
// Description is human-facing copy used for agent introspection prompts.
Description string `yaml:"description" json:"description"`
// SystemPrompt is the sub-agent's system prompt — the core of the
// posture's behavior shaping.
SystemPrompt string `yaml:"system_prompt" json:"system_prompt"`
// AllowedTools is the closed list of tool names the sub-agent may
// invoke. Tools outside this list are filtered before dispatch.
AllowedTools []string `yaml:"allowed_tools" json:"allowed_tools"`
// OutputSchema names a registered schema the sub-agent's final output
// is validated against. Optional — leave empty for free-form output.
OutputSchema string `yaml:"output_schema,omitempty" json:"output_schema,omitempty"`
// Model describes which model tier the sub-agent runs on.
Model ModelConfig `yaml:"model" json:"model"`
// DefaultBudget is the resource budget applied when the caller omits
// per-invocation overrides.
DefaultBudget ResourceBudget `yaml:"default_budget" json:"default_budget"`
// MaxRecursionDepth caps how deep this posture may be nested. Zero
// falls back to the registry-wide default.
MaxRecursionDepth int `yaml:"max_recursion_depth,omitempty" json:"max_recursion_depth,omitempty"`
// Version is a content-hash assigned by the registry when a posture is
// installed. Callers should treat it as opaque. Cache keys include this
// so a posture edit invalidates previously-cached delegate results.
Version string `yaml:"-" json:"version,omitempty"`
}
AgentPosture is the registered, named configuration a sub-agent runs under. Postures are loaded from YAML at startup (or hot-reloaded via fsnotify) and keyed by Name. Two postures with the same Name but different content are a version conflict — the registry tracks Version (a content hash) so cache keys can include it and stale results invalidate on edits.
func LoadDir ¶
func LoadDir(dir string) (postures []AgentPosture, errs []error)
LoadDir scans dir for *.yaml / *.yml files and decodes each into an AgentPosture. Returns the parsed postures in alphabetical filename order so repeated calls are stable. Files that fail to parse are surfaced in errs; successful entries still come back in postures, so a single malformed file does not block the rest from registering.
func LoadFile ¶
func LoadFile(path string) (AgentPosture, error)
LoadFile decodes a single posture YAML file.
type Change ¶
type Change struct {
Name string
Kind ChangeKind
Posture *AgentPosture
}
Change is a registry notification delivered on the channel returned by Watch. Posture is nil for ChangeRemoved.
type ChangeKind ¶
type ChangeKind int
ChangeKind classifies registry change notifications.
const ( ChangeAdded ChangeKind = iota ChangeModified ChangeRemoved )
type ModelConfig ¶
type ModelConfig struct {
ModelRole string `yaml:"model_role,omitempty" json:"model_role,omitempty"`
Provider string `yaml:"provider,omitempty" json:"provider,omitempty"`
Model string `yaml:"model,omitempty" json:"model,omitempty"`
Temperature float64 `yaml:"temperature,omitempty" json:"temperature,omitempty"`
MaxTokens int `yaml:"max_tokens,omitempty" json:"max_tokens,omitempty"`
}
ModelConfig selects the LLM the sub-agent uses. ModelRole resolves through the engine's model registry; Provider/Model are an explicit override taking precedence when set.
type Registry ¶
type Registry interface {
// Register installs (or replaces) a posture. Returns an error when the
// posture is invalid (missing Name, conflicting model config).
Register(p AgentPosture) error
// Get returns the posture by name. Returns ErrNotFound when absent.
Get(name string) (*AgentPosture, error)
// List returns a sorted snapshot of all installed postures.
List() []AgentPosture
// Remove deletes the posture by name. Returns ErrNotFound when absent.
Remove(name string) error
// Watch returns a channel that receives changes. The returned channel
// closes when ctx is cancelled. Multiple watchers fan-in to independent
// channels — buffer is small (8); slow consumers drop events with a log
// from the registry implementation.
Watch(ctx context.Context) <-chan Change
}
Registry is the lookup surface sub-agent runtimes use to resolve a posture name. Implementations must be safe for concurrent reads from any goroutine.
type ResourceBudget ¶
type ResourceBudget struct {
Timeout time.Duration `yaml:"timeout,omitempty" json:"timeout,omitempty"`
MaxTokens int `yaml:"max_tokens,omitempty" json:"max_tokens,omitempty"`
MaxToolCalls int `yaml:"max_tool_calls,omitempty" json:"max_tool_calls,omitempty"`
}
ResourceBudget bounds a sub-agent's resource use. Zero fields mean unlimited for that dimension — but at least one of Timeout / MaxTokens / MaxToolCalls should be set to prevent unbounded loops.