agent

package
v0.20.1 Latest Latest
Warning

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

 Go to latest Published: Aug 7, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package agent defines Callee's versioned Markdown and YAML agents.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultREPLTimeout 

func DefaultREPLTimeout() time.Duration

DefaultREPLTimeout returns the CLI operator-wait default.

func EncodeMarkdown 

func EncodeMarkdown(resource Resource) ([]byte, error)

EncodeMarkdown encodes a canonical resource with spec.body removed from frontmatter and emitted byte-for-byte after the closing delimiter.

func FuncMap 

func FuncMap() template.FuncMap

FuncMap returns a fresh positive-list-only deterministic template function map. It never exposes Sprig's environment, clock, random, network, crypto generation, or mutating dictionary helpers.

func IsDiscoverableResourceFile added in v0.20.0 

func IsDiscoverableResourceFile(source string, data []byte) (bool, error)

IsDiscoverableResourceFile reports whether source and data identify a Callee resource candidate during recursive discovery. Documentation that does not declare the current API is skipped; malformed documents are reported.

func ParseOutputTemplate 

func ParseOutputTemplate(name, body string) (*template.Template, error)

ParseOutputTemplate parses a composite output template, the only surface where Output is available. Params remains present as an empty map.

func ParseRestrictedTemplate 

func ParseRestrictedTemplate(name, body string) (*template.Template, error)

ParseRestrictedTemplate parses a state modifier or Role parameter binding, where neither Params nor Output is available.

func ParseTemplate 

func ParseTemplate(name, body string) (*template.Template, error)

ParseTemplate parses one workflow-aware template with the canonical options and helper set. The common surface exposes Params but not Output.

func RenderTemplate 

func RenderTemplate(parsed *template.Template, data TemplateData) (string, error)

RenderTemplate executes a parsed template against an immutable plain-data snapshot.

func RuntimeType 

func RuntimeType(providerType string) (string, bool)

RuntimeType maps public provider names to Norma Runtime names.

func Schema 

func Schema() []byte

Schema returns a copy of the exact embedded Draft 2020-12 schema bytes.

func SchemaForKind added in v0.17.0 

func SchemaForKind(kind Kind) ([]byte, error)

SchemaForKind returns a standalone Draft 2020-12 schema document for one supported Callee kind, derived from the embedded full schema.

func SupportedProviderTypes 

func SupportedProviderTypes() []string

SupportedProviderTypes returns public provider names in stable order.

func SupportsFile 

func SupportsFile(path string) bool

SupportsFile reports whether path has a supported lowercase agent file extension.

func ValidateRoleTemplate 

func ValidateRoleTemplate(id, body string) error

ValidateRoleTemplate enforces exactly one unconditional bare .Prompt or .Input primary insertion.

func ValidateRoleTemplateMigration 

func ValidateRoleTemplateMigration(id, body string, params map[string]string) error

ValidateRoleTemplateMigration reports legacy primary and flat parameter actions before the Go parser reduces them to generic undefined-function errors.

Types

type Child 

type Child struct {
	Ref         string            `json:"ref"                   yaml:"ref"`
	Alias       string            `json:"alias,omitempty"       yaml:"alias,omitempty"`
	CanEscalate bool              `json:"canEscalate,omitempty" yaml:"canEscalate,omitempty"`
	Route       string            `json:"route,omitempty"       yaml:"route,omitempty"`
	Default     bool              `json:"default,omitempty"     yaml:"default,omitempty"`
	Input       string            `json:"input,omitempty"       yaml:"input,omitempty"`
	State       map[string]any    `json:"state,omitempty"       yaml:"state,omitempty"`
	Params      map[string]string `json:"params,omitempty"      yaml:"params,omitempty"`
}

Child identifies one ordered child occurrence in a composite.

func (*Child) UnmarshalYAML 

func (c *Child) UnmarshalYAML(node *yaml.Node) error

UnmarshalYAML accepts either a scalar resource ID or a child mapping.

type Kind 

type Kind string

Kind is a supported agent resource kind. 

const (
	// APIVersion is the resource API understood by this Callee release.
	APIVersion = "callee.metalagman.dev/v1alpha1"

	// RoleKind identifies a provider-backed leaf agent.
	RoleKind Kind = "Role"
	// ScriptKind identifies a deterministic local validator leaf.
	ScriptKind Kind = "Script"
	// HumanKind identifies an operator-backed interactive leaf.
	HumanKind Kind = "Human"
	// SequentialKind identifies an ordered composite agent.
	SequentialKind Kind = "Sequential"
	// LoopKind identifies a bounded repeated composite agent.
	LoopKind Kind = "Loop"
	// RouterKind identifies a deterministic routed composite agent.
	RouterKind Kind = "Router"
)

type PermissionMode added in v0.15.0 

type PermissionMode string

PermissionMode controls how a Role handles ACP permission requests. 

const (
	// PermissionModeAsk prompts the operator for every ACP permission request.
	PermissionModeAsk PermissionMode = "ask"
	// PermissionModeAllow automatically selects a compatible allow option.
	PermissionModeAllow PermissionMode = "allow"
	// PermissionModeDeny automatically selects a compatible reject option.
	PermissionModeDeny PermissionMode = "deny"
)

type Permissions added in v0.15.0 

type Permissions struct {
	Mode PermissionMode `json:"mode" yaml:"mode"`
}

Permissions configures Role-level ACP permission handling.

type Provider 

type Provider struct {
	Type      string   `json:"type"                yaml:"type"`
	Cmd       string   `json:"cmd,omitempty"       yaml:"cmd,omitempty"`
	Model     string   `json:"model,omitempty"     yaml:"model,omitempty"`
	Reasoning string   `json:"reasoning,omitempty" yaml:"reasoning,omitempty"`
	Mode      string   `json:"mode,omitempty"      yaml:"mode,omitempty"`
	ExtraArgs []string `json:"extraArgs,omitempty" yaml:"extraArgs,omitempty"`
	Timeout   string   `json:"timeout,omitempty"   yaml:"timeout,omitempty"`
}

Provider configures the ACP provider used by a Role.

type Resource 

type Resource struct {
	APIVersion string `json:"apiVersion" yaml:"apiVersion"`
	Kind       Kind   `json:"kind"       yaml:"kind"`
	Spec       Spec   `json:"spec"       yaml:"spec"`

	ID     string `json:"-" yaml:"-"`
	Source string `json:"-" yaml:"-"`
}

Resource is one canonical agent resource. ID and Source are discovery data and are intentionally outside the versioned resource envelope.

func Decode 

func Decode(id, source string, data []byte) (Resource, error)

Decode decodes one agent file according to its lowercase extension.

func DecodeMarkdown 

func DecodeMarkdown(id, source string, data []byte) (Resource, error)

DecodeMarkdown decodes one resource and binds its physical Markdown body to spec.body before schema and semantic validation.

func DecodeYAML 

func DecodeYAML(id, source string, data []byte) (Resource, error)

DecodeYAML decodes one complete canonical resource from a single YAML document. Unlike Markdown, YAML must author spec.body inline.

func (Resource) EffectivePermissionMode added in v0.15.0 

func (r Resource) EffectivePermissionMode() PermissionMode

EffectivePermissionMode reports the Role permission mode, defaulting to ask.

func (Resource) ExhaustionPolicy 

func (r Resource) ExhaustionPolicy() string

ExhaustionPolicy reports the effective Loop exhaustion policy.

func (Resource) Interactive added in v0.17.0 

func (r Resource) Interactive() bool

Interactive reports the effective Role interactive multi-turn policy.

func (Resource) NonZeroPolicy added in v0.18.0 

func (r Resource) NonZeroPolicy() string

NonZeroPolicy reports the effective Script exit handling policy.

func (Resource) ProviderTimeout 

func (r Resource) ProviderTimeout() time.Duration

ProviderTimeout returns the effective per-operation provider timeout.

func (Resource) REPL 

func (r Resource) REPL() bool

REPL reports the effective Role REPL policy.

func (Resource) ScriptShell added in v0.18.0 

func (r Resource) ScriptShell() string

ScriptShell returns the effective shell used by a Script.

func (Resource) ScriptTimeout added in v0.18.0 

func (r Resource) ScriptTimeout() time.Duration

ScriptTimeout returns the effective per-script execution timeout.

func (Resource) Validate 

func (r Resource) Validate() error

Validate checks semantic constraints not expressible in the JSON Schema.

type Spec 

type Spec struct {
	Description   string            `json:"description"             yaml:"description"`
	Provider      *Provider         `json:"provider,omitempty"      yaml:"provider,omitempty"`
	Permissions   *Permissions      `json:"permissions,omitempty"   yaml:"permissions,omitempty"`
	Interactive   *bool             `json:"interactive,omitempty"   yaml:"interactive,omitempty"`
	LegacyREPL    *bool             `json:"repl,omitempty"          yaml:"repl,omitempty"`
	Params        map[string]string `json:"params,omitempty"        yaml:"params,omitempty"`
	ResponseKey   string            `json:"responseKey,omitempty"   yaml:"responseKey,omitempty"`
	Shell         string            `json:"shell,omitempty"         yaml:"shell,omitempty"`
	Cwd           string            `json:"cwd,omitempty"           yaml:"cwd,omitempty"`
	Env           map[string]string `json:"env,omitempty"           yaml:"env,omitempty"`
	Timeout       string            `json:"timeout,omitempty"       yaml:"timeout,omitempty"`
	OnNonZero     string            `json:"onNonZero,omitempty"     yaml:"onNonZero,omitempty"`
	State         map[string]any    `json:"state,omitempty"         yaml:"state,omitempty"`
	Children      []Child           `json:"children,omitempty"      yaml:"children,omitempty"`
	Route         string            `json:"route,omitempty"         yaml:"route,omitempty"`
	Body          string            `json:"body"                    yaml:"body,omitempty"`
	Output        string            `json:"output,omitempty"        yaml:"output,omitempty"`
	MaxIterations *int              `json:"maxIterations,omitempty" yaml:"maxIterations,omitempty"`
	OnExhausted   string            `json:"onExhausted,omitempty"   yaml:"onExhausted,omitempty"`
}

Spec contains kind-specific authored configuration.

func (Spec) InteractiveValue added in v0.17.0 

func (s Spec) InteractiveValue() bool

func (Spec) MarshalJSON added in v0.17.0 

func (s Spec) MarshalJSON() ([]byte, error)

func (Spec) MarshalYAML added in v0.17.0 

func (s Spec) MarshalYAML() (any, error)

type TemplateData 

type TemplateData struct {
	Prompt string
	Input  string
	Output string
	State  map[string]any
	Params map[string]string
}

TemplateData is the common immutable data root for every authored template.

Source Files

View all Source files

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.