agents

package
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: May 30, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// ReservedAgentName is the only disallowed reusable agent slug in v1.
	ReservedAgentName = "productize"
	// ReservedMCPServerName is the host-owned MCP server name that agents may not override.
	ReservedMCPServerName = "productize"
)
View Source 
const (
	// DefaultMaxNestedDepth bounds recursive child-agent execution.
	DefaultMaxNestedDepth = 3
	// RunAgentContextEnvVar carries the host-owned nested execution context into
	// the reserved `productize` MCP server process.
	RunAgentContextEnvVar = "PRODUCTIZE_RUN_AGENT_CONTEXT"
)

Variables

View Source 
var (
	// ErrAgentNotFound indicates that no resolved agent matched the requested name.
	ErrAgentNotFound = errors.New("agent not found")
	// ErrInvalidAgentName indicates that an agent directory name failed slug validation.
	ErrInvalidAgentName = errors.New("invalid agent name")
	// ErrReservedAgentName indicates that an agent directory uses a reserved slug.
	ErrReservedAgentName = errors.New("reserved agent name")
	// ErrMissingAgentDefinition indicates that an agent directory does not contain `AGENT.md`.
	ErrMissingAgentDefinition = errors.New("missing AGENT.md")
	// ErrMalformedFrontmatter indicates that `AGENT.md` frontmatter could not be parsed.
	ErrMalformedFrontmatter = errors.New("malformed AGENT.md front matter")
	// ErrUnsupportedMetadataField indicates that `AGENT.md` declares a deferred field.
	ErrUnsupportedMetadataField = errors.New("unsupported agent metadata field")
	// ErrInvalidRuntimeDefaults indicates that agent runtime defaults are invalid.
	ErrInvalidRuntimeDefaults = errors.New("invalid agent runtime defaults")
	// ErrMalformedMCPConfig indicates that `mcp.json` is invalid.
	ErrMalformedMCPConfig = errors.New("malformed mcp.json")
	// ErrMissingEnvironmentVariable indicates that a placeholder referenced an unset environment variable.
	ErrMissingEnvironmentVariable = errors.New("missing environment variable")
	// ErrReservedMCPServerName indicates that `mcp.json` attempted to declare the host-owned server.
	ErrReservedMCPServerName = errors.New("reserved MCP server name")
)

Functions

func BlockedReasonForError 

func BlockedReasonForError(err error) (kinds.ReusableAgentBlockedReason, bool)

BlockedReasonForError classifies reusable-agent errors into the stable machine-readable blocked-reason vocabulary used by runtime signals and nested-agent failures.

func BuildSessionMCPServers 

func BuildSessionMCPServers(
	execution *ExecutionContext,
	ctx SessionMCPContext,
) ([]model.MCPServer, error)

BuildSessionMCPServers returns the reserved `productize` MCP server plus the selected agent's own MCP servers, in deterministic order.

func IsValidationError 

func IsValidationError(err error) bool

IsValidationError reports whether the provided error describes an invalid reusable-agent definition or MCP configuration.

Types

type Catalog 

type Catalog struct {
	Agents   []ResolvedAgent
	Problems []Problem
}

Catalog contains all successfully resolved agents plus non-fatal per-agent problems.

func (Catalog) Resolve 

func (c Catalog) Resolve(name string) (ResolvedAgent, error)

Resolve returns one agent from the catalog or the matching validation problem.

type ExecutionContext 

type ExecutionContext struct {
	Agent       ResolvedAgent
	Catalog     Catalog
	BaseRuntime NestedBaseRuntime
}

ExecutionContext captures the resolved reusable-agent inputs needed by the execution pipeline after runtime precedence has been applied.

func ResolveExecutionContext 

func ResolveExecutionContext(ctx context.Context, cfg *model.RuntimeConfig) (*ExecutionContext, error)

ResolveExecutionContext resolves the selected reusable agent, applies its runtime defaults using the documented precedence rules, and returns the reusable prompt-assembly context. When no agent is selected, it returns nil.

func (*ExecutionContext) SystemPrompt 

func (c *ExecutionContext) SystemPrompt(baseSystemPrompt string) string

SystemPrompt assembles the canonical system prompt for a selected reusable agent. When no execution context is present, it preserves the existing base system prompt unchanged.

type MCPConfig 

type MCPConfig struct {
	Path    string
	Servers []MCPServer
}

MCPConfig contains the resolved contents of `mcp.json`.

type MCPServer 

type MCPServer struct {
	Name    string
	Command string
	Args    []string
	Env     map[string]string
}

MCPServer describes one agent-local MCP server declaration.

type Metadata 

type Metadata struct {
	Title       string
	Description string
}

Metadata contains the human-facing fields from `AGENT.md`.

type NestedBaseRuntime 

type NestedBaseRuntime struct {
	WorkspaceRoot          string                     `json:"workspace_root,omitempty"`
	IDE                    string                     `json:"ide,omitempty"`
	Model                  string                     `json:"model,omitempty"`
	AddDirs                []string                   `json:"add_dirs,omitempty"`
	ReasoningEffort        string                     `json:"reasoning_effort,omitempty"`
	AccessMode             string                     `json:"access_mode,omitempty"`
	ExplicitRuntime        model.ExplicitRuntimeFlags `json:"explicit_runtime,omitempty"`
	Timeout                time.Duration              `json:"timeout,omitempty"`
	MaxRetries             int                        `json:"max_retries,omitempty"`
	RetryBackoffMultiplier float64                    `json:"retry_backoff_multiplier,omitempty"`
}

NestedBaseRuntime captures the pre-agent runtime defaults that child-agent resolution must inherit from the parent host, without leaking prompt input.

func (NestedBaseRuntime) RuntimeConfig 

func (r NestedBaseRuntime) RuntimeConfig() model.RuntimeConfig

RuntimeConfig materializes the child-runtime base config used before agent defaults are applied during nested execution.

type NestedExecutionContext 

type NestedExecutionContext struct {
	Depth            int      `json:"depth"`
	MaxDepth         int      `json:"max_depth"`
	ParentRunID      string   `json:"parent_run_id,omitempty"`
	ParentAgentName  string   `json:"parent_agent_name,omitempty"`
	ParentAccessMode string   `json:"parent_access_mode,omitempty"`
	AgentPath        []string `json:"agent_path,omitempty"`
}

NestedExecutionContext is the host-owned recursion state propagated to the reserved `productize` MCP server. Tool callers do not control these values.

type Option 

type Option func(*Registry)

Option configures a Registry.

func WithHomeDir 

func WithHomeDir(fn func() (string, error)) Option

WithHomeDir overrides how the registry resolves the global agent root.

func WithLookupEnv 

func WithLookupEnv(fn func(string) (string, bool)) Option

WithLookupEnv overrides how environment variables are resolved during placeholder expansion.

type Problem 

type Problem struct {
	Name   string
	Source Source
	Err    error
}

Problem records a non-fatal discovery or validation failure for one agent directory.

func (Problem) Error 

func (p Problem) Error() string

Error implements the error interface.

func (Problem) Unwrap 

func (p Problem) Unwrap() error

Unwrap exposes the underlying validation failure.

type Registry 

type Registry struct {
	// contains filtered or unexported fields
}

Registry discovers, parses, validates, and resolves reusable agents.

func New 

func New(opts ...Option) *Registry

New constructs a reusable agent registry with optional test hooks.

func (*Registry) Discover 

func (r *Registry) Discover(ctx context.Context, workspaceRoot string) (Catalog, error)

Discover scans workspace and global scopes, applying whole-directory workspace overrides.

func (*Registry) Resolve 

func (r *Registry) Resolve(ctx context.Context, workspaceRoot, name string) (ResolvedAgent, error)

Resolve discovers the current catalog and returns one resolved agent.

type ReservedServerRuntimeContext 

type ReservedServerRuntimeContext struct {
	BaseRuntime NestedBaseRuntime      `json:"base_runtime"`
	Nested      NestedExecutionContext `json:"nested"`
}

ReservedServerRuntimeContext is serialized into the reserved server environment so future nested tool calls can recreate the child host context.

type ResolvedAgent 

type ResolvedAgent struct {
	Name     string
	Metadata Metadata
	Runtime  RuntimeDefaults
	Prompt   string
	Source   Source
	MCP      *MCPConfig
}

ResolvedAgent is the canonical reusable agent definition consumed by later tasks.

type RuntimeDefaults 

type RuntimeDefaults struct {
	IDE             string
	Model           string
	ReasoningEffort string
	AccessMode      string
}

RuntimeDefaults contains the runtime defaults declared in `AGENT.md`.

type Scope 

type Scope string

Scope identifies where an agent definition was discovered. 

const (
	// ScopeWorkspace identifies agents discovered from `.productize/agents`.
	ScopeWorkspace Scope = "workspace"
	// ScopeGlobal identifies agents discovered from `~/.productize/agents`.
	ScopeGlobal Scope = "global"
)

type SessionMCPContext 

type SessionMCPContext struct {
	RunID                string
	ParentAgentName      string
	EffectiveAccessMode  string
	NestedDepth          int
	MaxNestedDepth       int
	AgentPath            []string
	ReservedServerBinary string
	ReservedServerArgs   []string
	BaseRuntime          *model.RuntimeConfig
}

SessionMCPContext describes the host-owned session metadata needed to build the merged MCP server list for one reusable-agent-backed ACP session.

type Source 

type Source struct {
	Scope          Scope
	RootDir        string
	Dir            string
	DefinitionPath string
	MCPConfigPath  string
}

Source describes the filesystem origin of a resolved or invalid agent.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.