Documentation
¶
Overview ¶
Package agent assembles agent prompt bundles and configuration metadata.
Index ¶
- func ApplyMCPOverride(b *Bundle, override []mcp.ServerConfig, mode, agentDir string, ...) error
- type BudgetConfig
- type Bundle
- func BuildBundle(agentsDir, agentName, prompt, workingDir, mode string, vars map[string]string) (*Bundle, error)
- func BuildBundleInline(baseDir string, cfg *InlineAgentConfig, prompt, workingDir, mode string, ...) (*Bundle, error)
- func BuildBundleWithOptions(agentsDir, agentName, prompt, workingDir, mode string, vars map[string]string, ...) (*Bundle, error)
- type BundleOptions
- type ChildBudget
- type ComposedGate
- type ComposedPartition
- type ComposedPreGate
- type ComposedStage
- type ExecutionConfig
- type InlineAgentConfig
- type Manifest
- type ModelPreference
- type OutputConfig
- type RequiredCommand
- type RequiresConfig
- type SkillOverrides
- type SkillsConfig
- type TemplateData
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ApplyMCPOverride ¶
func ApplyMCPOverride(b *Bundle, override []mcp.ServerConfig, mode, agentDir string, vars map[string]string) error
resolveMCPServerTemplates processes template variables in MCP server configurations. ApplyMCPOverride replaces a bundle's MCP server list with the supplied override, applying the same template expansion (Var/Env/BrowserProfile/AgentDir) that BuildBundle uses. Intended for stage-scoped MCP overrides in composed agents, where a stage's mcp_servers replaces the parent manifest's list for that stage's run only.
Types ¶
type BudgetConfig ¶
type BudgetConfig struct {
// MaxTokens is the recommended output-token budget for this agent.
// If zero, inferred from whether the agent dispatches child agents.
MaxTokens int `yaml:"max_tokens,omitempty"`
// EstimatedIterations is the expected number of model iterations.
EstimatedIterations int `yaml:"estimated_iterations,omitempty"`
// Children lists child agents this orchestrator dispatches via the Task tool.
// Each entry can be a plain string (agent name) or a ChildBudget with max_cost.
Children []ChildBudget `yaml:"children,omitempty"`
// ScaleFactor describes what makes this agent's cost scale.
// Currently supported: "files" (cost scales with source file count).
ScaleFactor string `yaml:"scale_factor,omitempty"`
// FilesPerIteration is how many files the agent typically processes
// per model iteration, used when ScaleFactor is "files".
FilesPerIteration int `yaml:"files_per_iteration,omitempty"`
}
BudgetConfig provides static hints for cost estimation. These are used by --dry-run to estimate costs before running.
func (*BudgetConfig) ChildMaxCost ¶
func (b *BudgetConfig) ChildMaxCost(agentName string) float64
ChildMaxCost returns the dedicated cost cap for the named child agent. Returns 0 if no dedicated cap is configured (use remaining budget).
func (*BudgetConfig) ChildMaxIterations ¶
func (b *BudgetConfig) ChildMaxIterations(agentName string) int
ChildMaxIterations returns the iteration cap for the named child agent. Returns 0 if no cap is configured (inherit parent's cap).
func (*BudgetConfig) ChildNames ¶
func (b *BudgetConfig) ChildNames() []string
ChildNames returns the list of child agent names.
type Bundle ¶
type Bundle struct {
System string // wrapper + system prompt + references + task
User string // user request (CLI prompt or default)
Combined []byte // concatenated for --print-bundle/--bundle-out
WorkDir string
Model string // primary model override (first from models list or single model field)
Provider string // primary provider override (first from models list or single provider field)
BaseURL string // primary model's base URL override (for openai-compat)
Models []ModelPreference // ranked model preferences from manifest
Budget *BudgetConfig // budget configuration from manifest
Execution *ExecutionConfig // sharded-execution config from manifest (nil = single-loop)
Environment *executor.Config // execution environment from agent manifest
MCPServers []mcp.ServerConfig // MCP server dependencies declared in agent.yaml
DisableTask bool // when true, the Task tool is not registered for this agent
MaxIterations int // iteration cap from manifest (0 = use CLI default)
// IterationFactor is the manifest's per-model iteration multiplier; when
// set it overrides the config-level model.iteration_factor for this agent.
IterationFactor map[string]float64
EditDeadline int // stop after N iterations with no Edit calls (0 = disabled)
// RemoteOnly mirrors Manifest.IsRemoteOnly. When true, local
// filesystem tools are not registered and the runner skips
// working-dir resolution / repo-summary injection.
RemoteOnly bool
// CommentsOnly mirrors Manifest.CommentsOnly. Restricts Edit/MultiEdit
// to comment-only changes when true.
CommentsOnly bool
// ASCIIOnly mirrors Manifest.ASCIIOnly. Rejects edits that introduce
// non-ASCII characters not already present in the replaced text.
ASCIIOnly bool
// SkillEntries is the filtered set of skills surfaced in the system
// prompt's "Available skills" block. The runner uses these to build
// the Skill tool's runtime so the names the agent sees are exactly
// the names it can load via Skill(name).
SkillEntries []skill.Entry
// Requires mirrors Manifest.Requires so the runner can invoke
// Preflight() without re-reading the manifest. nil means "no
// declared external dependencies".
Requires *RequiresConfig
}
Bundle contains the assembled system, user, and combined prompt content for an agent run.
func BuildBundle ¶
func BuildBundle(agentsDir, agentName, prompt, workingDir, mode string, vars map[string]string) (*Bundle, error)
BuildBundle assembles a Bundle from the named agent in agentsDir. It loads the manifest, processes system/wrapper/task templates with the given mode and vars, resolves references and MCP server configs, and constructs the combined system and user messages. prompt becomes the user message (defaulting to "Begin." when empty).
Callers that need to overlay the agent.yaml skills config — e.g. CLI flags like --allow-skill / --skills-disabled — should use BuildBundleWithOptions instead.
func BuildBundleInline ¶
func BuildBundleInline(baseDir string, cfg *InlineAgentConfig, prompt, workingDir, mode string, vars map[string]string) (*Bundle, error)
BuildBundleInline assembles a bundle from inline agent config. baseDir is the composed agent's directory where prompt files live. Files are resolved with progressive lookup: stages/<name>/ first, then baseDir. {{include}} resolves against cfg.IncludesRoot/_includes/ when set, else baseDir/_includes/.
func BuildBundleWithOptions ¶
func BuildBundleWithOptions(agentsDir, agentName, prompt, workingDir, mode string, vars map[string]string, opts *BundleOptions) (*Bundle, error)
BuildBundleWithOptions is the full-featured constructor that also accepts per-run overrides via opts. A nil opts is equivalent to BuildBundle.
func (*Bundle) FindModel ¶
func (b *Bundle) FindModel(provider, model string) *ModelPreference
FindModel returns the ModelPreference matching the given provider and model, or nil if not found. An empty provider or model never matches.
type BundleOptions ¶
type BundleOptions struct {
// SkillOverrides applies CLI-flag overrides to the skill catalog.
SkillOverrides *SkillOverrides
// CatalogPaths are additional directories to scan as catalog-scope
// skills (lowest precedence). Typically supplied by the runner from
// source.SkillsManager.CatalogPaths().
CatalogPaths []string
}
BundleOptions carries optional inputs to BuildBundleWithOptions. A nil pointer is equivalent to a zero value — all fields are opt-in.
type ChildBudget ¶
type ChildBudget struct {
Name string `yaml:"name"`
MaxCost float64 `yaml:"max_cost,omitempty"` // dedicated cost cap in USD (0 = use remaining budget)
MaxIterations int `yaml:"max_iterations,omitempty"` // iteration cap for child (0 = inherit parent's cap)
}
ChildBudget represents a child agent with an optional dedicated cost cap.
type ComposedGate ¶
type ComposedGate struct {
After string `yaml:"after"`
Command string `yaml:"command"`
OnFailure string `yaml:"on_failure,omitempty"`
}
ComposedGate defines a regression check between composed agent stages.
type ComposedPartition ¶
type ComposedPartition struct {
By string `yaml:"by"`
Glob string `yaml:"glob"`
MaxPerPartition int `yaml:"max_per_partition"`
}
ComposedPartition configures automatic work splitting for a composed stage.
type ComposedPreGate ¶
type ComposedPreGate struct {
Command string `yaml:"command"`
Label string `yaml:"label,omitempty"`
OnError string `yaml:"on_error,omitempty"`
}
ComposedPreGate runs a command before an agent and injects output into the prompt.
type ComposedStage ¶
type ComposedStage struct {
Name string `yaml:"name"`
Agent string `yaml:"agent,omitempty"`
Agents []string `yaml:"agents,omitempty"`
DependsOn []string `yaml:"depends_on,omitempty"`
Mode string `yaml:"mode,omitempty"`
Vars map[string]string `yaml:"vars,omitempty"`
Condition string `yaml:"condition,omitempty"`
PreGates []ComposedPreGate `yaml:"pre_gates,omitempty"`
MaxCost float64 `yaml:"max_cost,omitempty"`
Partition *ComposedPartition `yaml:"partition,omitempty"`
Summarize string `yaml:"summarize,omitempty"`
SummarizePrompt string `yaml:"summarize_prompt,omitempty"`
// Inline agent fields — define the agent directly in the stage.
// When set, agent/agents must be empty.
EntryPoint string `yaml:"entrypoint,omitempty"`
Wrapper string `yaml:"wrapper,omitempty"`
Task string `yaml:"task,omitempty"`
Models []ModelPreference `yaml:"models,omitempty"`
References []string `yaml:"references,omitempty"`
// MCPServers, when non-empty, replaces the parent manifest's
// MCP server list for this stage only. Used to scope tool surface
// per stage (e.g. stage 1 has no MCP, stage 2 has chrome+gdrive).
// Empty means "inherit from the parent manifest".
MCPServers []mcp.ServerConfig `yaml:"mcp_servers,omitempty"`
}
ComposedStage defines a unit of work in a composed agent. It mirrors pipeline.Stage but lives in the agent package to avoid circular imports between agent and pipeline.
A stage can either reference external agents (agent/agents fields) or define an inline agent (entrypoint/wrapper/models fields). These are mutually exclusive.
func (ComposedStage) AgentList ¶
func (s ComposedStage) AgentList() []string
AgentList returns all agents in the stage (normalizing single vs parallel). For inline stages, the stage name is used as the agent name.
func (ComposedStage) IsInline ¶
func (s ComposedStage) IsInline() bool
IsInline reports whether the stage defines an inline agent.
type ExecutionConfig ¶ added in v0.2.0
type ExecutionConfig struct {
// ShardBy selects the partitioning unit. "" (default) = no sharding;
// "file" = one shard per file (or per ShardBatch files); "package" = one
// shard per directory, so every package's files run together in one shard
// with full intra-package context (the unit for guaranteed whole-repo
// coverage). ShardBatch does not apply to "package".
ShardBy string `yaml:"shard_by,omitempty"`
// Glob lists the patterns squad globs (relative to the working dir) to
// build the work-list. Required when ShardBy is "file" or "package".
Glob []string `yaml:"glob,omitempty"`
// Exclude lists glob patterns to drop from the work-list (vendored,
// generated, VCS dirs).
Exclude []string `yaml:"exclude,omitempty"`
// ShardBatch is how many files go in one shard. Default 1 (strict per-file).
// Ignored when ShardBy is "package" (one shard per directory).
ShardBatch int `yaml:"shard_batch,omitempty"`
// Merge controls how per-shard outputs are combined: "json" (default,
// structured aggregate + per-shard sections) or "none" (verbatim concat).
Merge string `yaml:"merge,omitempty"`
// MaxParallel bounds concurrent shards. Default 1 (sequential, v1).
MaxParallel int `yaml:"max_parallel,omitempty"`
// OnShardError is "continue" (default; aggregate failures, other shards
// proceed) or "stop" (first failure aborts the rest).
OnShardError string `yaml:"on_shard_error,omitempty"`
}
ExecutionConfig opts an agent into sharded (map/reduce) execution: squad partitions the agent's input and runs the single-agent loop once per shard with isolated context, then merges the per-shard outputs. It is intended for agents whose unit of work is independent per file (degpt, go-scrub-comments, rust-scrub-comments). Absent this block, the agent runs as a single loop — the legacy behavior, unchanged.
func (*ExecutionConfig) Validate ¶ added in v0.2.0
func (e *ExecutionConfig) Validate() error
Validate checks the execution block and fills defaults. It returns an error for misconfiguration so failures surface at bundle load, not mid-run.
type InlineAgentConfig ¶
type InlineAgentConfig struct {
Name string // stage name, used as the agent identity
EntryPoint string // path to system prompt, relative to base dir
Wrapper string // path to wrapper prompt, relative to base dir
Task string // path to task prompt, relative to base dir
Models []ModelPreference // model preferences
References []string // paths to reference files, relative to base dir
IncludesRoot string // dir holding _includes/ for {{include}}; empty = baseDir
}
InlineAgentConfig holds the configuration for an agent defined inline within a composed agent's stage.
type Manifest ¶
type Manifest struct {
Name string `yaml:"name"`
Version string `yaml:"version"`
Description string `yaml:"description,omitempty"`
// Leaf agent fields.
Models []ModelPreference `yaml:"models,omitempty"` // ranked model preferences
EntryPoint string `yaml:"entrypoint,omitempty"`
Wrapper string `yaml:"wrapper,omitempty"`
References []string `yaml:"references,omitempty"`
Task string `yaml:"task,omitempty"`
// Prompt is an inline system prompt. When set, the agent does not
// need entrypoint or wrapper files — the inline prompt becomes the
// whole system message. Useful for short single-file agents like
// scheduled remote-tool runners.
Prompt string `yaml:"prompt,omitempty"`
// WorkingDir controls whether the agent operates on a local
// filesystem. Set to "none" for agents that only call remote MCP
// tools (Google Calendar/Drive, etc.). When "none", local file
// tools (Read/Write/Edit/Glob/Grep/Bash) are not registered and
// the run executes in a per-run temp directory.
WorkingDir string `yaml:"working_dir,omitempty"`
// Composed agent fields.
Stages []ComposedStage `yaml:"stages,omitempty"`
Gates []ComposedGate `yaml:"gates,omitempty"`
// Shared fields.
Environment *executor.Config `yaml:"environment,omitempty"`
DependsOn []string `yaml:"depends_on,omitempty"`
Output *OutputConfig `yaml:"output,omitempty"`
Budget *BudgetConfig `yaml:"budget,omitempty"`
Execution *ExecutionConfig `yaml:"execution,omitempty"`
MCPServers []mcp.ServerConfig `yaml:"mcp_servers,omitempty"`
DisableTask bool `yaml:"disable_task,omitempty"`
MaxIterations int `yaml:"max_iterations,omitempty"` // iteration cap for this agent (0 = use CLI default)
// IterationFactor overrides the config-level model.iteration_factor for
// this agent, keyed by model name (a "default" key applies to any model).
// Lets an agent tune its per-model budget independently of global config.
IterationFactor map[string]float64 `yaml:"iteration_factor,omitempty"`
EditDeadline int `yaml:"edit_deadline,omitempty"` // stop after N iterations with no Edit calls (0 = disabled)
// CommentsOnly, when true, restricts Edit and MultiEdit calls to
// changes that only add or remove comment lines or blank lines.
// Edits that modify, add, or remove non-comment code are rejected.
// Use for comment-cleanup agents (e.g. go-scrub-comments) so an LLM
// hallucinating new code cannot silently break the codebase.
CommentsOnly bool `yaml:"comments_only,omitempty"`
// ASCIIOnly, when true, rejects Edit/MultiEdit calls whose replacement
// text introduces non-ASCII characters not already in the original. Use
// for de-slop agents (e.g. degpt) so a model cannot sneak in smart quotes,
// em dashes, or other typographic tells — the very things it should strip.
ASCIIOnly bool `yaml:"ascii_only,omitempty"`
// Isolation declares the recommended isolation mode: "" (none) or
// "worktree" to run inside a fresh git worktree on a new branch.
// CLI --isolate and config run.isolation override this.
Isolation string `yaml:"isolation,omitempty"`
// Skills, when non-nil, configures the Agent Skills catalog injected
// into this agent's system prompt at boot. nil means "use defaults"
// (catalog enabled, both scopes, no allow/deny). See skill package
// and PLAN.md for the progressive-disclosure model.
Skills *SkillsConfig `yaml:"skills,omitempty"`
// Requires declares external CLI dependencies the agent needs at
// runtime (e.g. gosec, bandit). The runner verifies each is on PATH
// before invoking the model and aborts with install hints on missing
// tools so failures surface in milliseconds rather than mid-run.
Requires *RequiresConfig `yaml:"requires,omitempty"`
}
Manifest represents the structure of an agent's manifest file. A manifest is either a leaf agent (has entrypoint/wrapper) or a composed agent (has stages). These are mutually exclusive; Validate() enforces this.
func LoadManifest ¶
LoadManifest reads and parses the agent manifest from the given agent directory. It validates the manifest structure, ensuring composed and leaf fields are mutually exclusive.
func (*Manifest) IsComposed ¶
IsComposed reports whether the manifest declares a composed agent (has stages rather than an entrypoint).
func (*Manifest) IsInlinePrompt ¶
IsInlinePrompt reports whether the manifest uses the inline `prompt:` form instead of separate entrypoint+wrapper files.
func (*Manifest) IsRemoteOnly ¶
IsRemoteOnly reports whether the agent has declared it does not touch the local filesystem (working_dir: none). Local file tools (Read/Write/Edit/Glob/Grep/Bash) are not registered for such agents.
func (*Manifest) PrimaryModel ¶
func (m *Manifest) PrimaryModel() ModelPreference
PrimaryModel returns the first ranked ModelPreference, or the zero value if no models are declared.
type ModelPreference ¶
type ModelPreference struct {
Model string `yaml:"model"` // model identifier (e.g. "claude-sonnet-4-6")
Provider string `yaml:"provider"` // squad provider name (e.g. "anthropic", "openai-compat")
BaseURL string `yaml:"base_url,omitempty"` // optional endpoint override; required when Provider is "openai-compat"
}
ModelPreference represents a ranked model recommendation for an agent. The first entry in a models list is the primary (preferred) model.
type OutputConfig ¶
type OutputConfig struct {
// Format is the output format: "json" or "markdown" (default: "markdown").
Format string `yaml:"format,omitempty"`
// Schema is a JSON Schema definition for the agent's output.
Schema map[string]any `yaml:"schema,omitempty"`
}
OutputConfig specifies the structured output contract for an agent. When format is "json", the agent's system prompt is augmented with instructions to emit JSON matching the declared schema.
type RequiredCommand ¶ added in v0.2.0
type RequiredCommand struct {
// Name is the binary name as it would be invoked (e.g. "gosec").
Name string `yaml:"name"`
// Install maps a package manager (or "url") to the install identifier.
// Common keys: brew, pipx, pip, npm, cargo, go, apt, dnf, pacman, url.
// Values are passed verbatim to the user as install hints; the runner
// does not execute them. An empty map is allowed but unhelpful.
Install map[string]string `yaml:"install,omitempty"`
}
RequiredCommand names a single CLI binary and how to install it.
type RequiresConfig ¶ added in v0.2.0
type RequiresConfig struct {
// Commands lists CLI binaries that must be on PATH for the agent
// to function. The runner uses exec.LookPath to verify each.
Commands []RequiredCommand `yaml:"commands,omitempty"`
}
RequiresConfig declares external dependencies an agent needs at runtime. The runner verifies these before invoking the model so a missing tool fails fast with an actionable install hint instead of mid-run.
func (*RequiresConfig) Preflight ¶ added in v0.2.0
func (r *RequiresConfig) Preflight() error
Preflight verifies every required command is on PATH. Returns nil when all are present (or when r is nil/empty). When commands are missing it returns a single error listing each missing tool with its install hints.
func (*RequiresConfig) Validate ¶ added in v0.2.0
func (r *RequiresConfig) Validate(manifestName string) error
Validate checks that the Requires block is structurally well-formed.
type SkillOverrides ¶
type SkillOverrides struct {
// Enabled, when non-nil, force-enables or disables the catalog for this
// run, overriding the manifest.
Enabled *bool
// Allow, when non-empty, replaces the manifest's Allow list for this run.
Allow []string
// Deny, when non-empty, replaces the manifest's Deny list for this run.
Deny []string
}
SkillOverrides supplies per-run adjustments to the agent's skill catalog. Each field is opt-in; an unset field defers to the agent.yaml Skills block or, if that is also unset, to the engine default.
type SkillsConfig ¶
type SkillsConfig struct {
// Enabled, when non-nil, force-enables or disables the skill catalog
// for this agent. nil means "auto-enable when any skill is discovered".
Enabled *bool `yaml:"enabled,omitempty"`
// Scopes restricts catalog assembly to this set of skill scopes. Empty
// means all scopes ("repo" + "global"). Values match skill.Scope.String().
Scopes []string `yaml:"scopes,omitempty"`
// Allow, when non-empty, is an exclusive allowlist of skill names. Wins
// over Deny and Scopes per PLAN.md.
Allow []string `yaml:"allow,omitempty"`
// Deny removes skills by name from the catalog. Applied only when Allow
// is empty.
Deny []string `yaml:"deny,omitempty"`
}
SkillsConfig controls which Agent Skills are surfaced to this agent via the system-prompt catalog. Each field is opt-in; an unset field falls through to the engine default.
type TemplateData ¶
TemplateData holds the data passed to prompt templates. Templates can use {{.Mode}}, {{.Var "KEY"}}, or {{.Vars.KEY}}.
AgentDir is the absolute path to the agent's directory on disk. Useful for MCP `command:` entries that point at scripts shipped alongside the agent — `{{.AgentDir}}/wrapper.sh` keeps the manifest portable across machines.
func (TemplateData) BrowserProfile ¶
func (td TemplateData) BrowserProfile(name string) (string, error)
BrowserProfile returns the absolute path to the named browser profile dir, creating it lazily if missing. Usage in templates:
mcp_servers:
- name: chrome
command: npx
args:
- chrome-devtools-mcp@latest
- --userDataDir={{.BrowserProfile "amazon"}}
The agent.yaml stays portable across machines — each machine maintains its own logins in its own copy of the profile dir.
func (TemplateData) Default ¶
func (td TemplateData) Default(key, defaultVal string) string
Default returns the value of a variable, or a default if not set. Usage in templates: {{.Default "COVERAGE_TARGET" "75"}}
func (TemplateData) Env ¶
func (td TemplateData) Env(key string, fallbacks ...string) string
Env returns the value of an OS environment variable, or the first non-empty fallback when unset. Distinct from Var/Default which read from squad's --var / cfg.Vars map. Usage in templates:
env:
- "GOOGLE_TOKEN={{.Env \"GOOGLE_TOKEN\"}}"
- "API_BASE={{.Env \"API_BASE\" \"https://api.example.com\"}}"
Squad's `--var KEY=VAL` flags shadow OS env when both name the same key — author your manifest to call `.Env` for ambient credentials (refresh tokens, machine-local secrets) and `.Default` / `.Var` for runtime knobs the caller is expected to set explicitly.
func (TemplateData) Var ¶
func (td TemplateData) Var(key string) string
Var returns the value of a template variable, or empty string if not set. Usage in templates: {{.Var "COVERAGE_TARGET"}}