agent

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Jul 5, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package agent assembles agent prompt bundles and configuration metadata.

Index

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.

func (*Bundle) Sharded added in v0.2.0

func (b *Bundle) Sharded() bool

Sharded reports whether this bundle opts into sharded (per-file) execution.

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

func LoadManifest(agentPath string) (*Manifest, error)

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

func (m *Manifest) IsComposed() bool

IsComposed reports whether the manifest declares a composed agent (has stages rather than an entrypoint).

func (*Manifest) IsInlinePrompt

func (m *Manifest) IsInlinePrompt() bool

IsInlinePrompt reports whether the manifest uses the inline `prompt:` form instead of separate entrypoint+wrapper files.

func (*Manifest) IsRemoteOnly

func (m *Manifest) IsRemoteOnly() bool

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.

func (*Manifest) Sharded added in v0.2.0

func (m *Manifest) Sharded() bool

Sharded reports whether this manifest opts into sharded execution.

func (*Manifest) Validate

func (m *Manifest) Validate() error

Validate checks the manifest for structural errors. Composed manifests (with stages) must not have entrypoint/wrapper. Leaf manifests (with entrypoint) must not have stages.

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

type TemplateData struct {
	Mode     string
	Vars     map[string]string
	AgentDir string
}

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"}}

Jump to

Keyboard shortcuts

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