posture

package
v0.30.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 31, 2026 License: MIT Imports: 12 Imported by: 0

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

View Source
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.

func NewRegistry

func NewRegistry() Registry

NewRegistry returns an empty in-memory registry.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL