manifest

package
v0.6.1004-dev.1 Latest Latest
Warning

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

Go to latest
Published: Nov 1, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Overview

Package manifest implements the agent.yaml package manifest: strict parsing (closed schema, rule V1), the validation rules V1–V18, the closed capability vocabulary, and the canonical JSON form stored as agent_versions.manifest.

Two schema majors are read. Major 2 classifies a QuickAgent by the run modes it supports — autonomous, interactive, persistent — and names one instruction entrypoint. Major 1 classified by kind (skill, prompt-agent, mcp-server) and is kept readable for the archives already published under it: SupportedModes and InstructionCandidates answer the v2 questions for either major, so callers need not branch on the version. A v1 document can still be validated for publish, except that kind mcp-server is withdrawn and refused.

The API splits validation by what it needs:

  • Parse decodes one YAML 1.2 document with unknown keys rejected everywhere and the schemaVersion major checked.
  • Validate applies every rule that needs only the manifest itself.
  • ValidateInContext applies Validate plus the rules that need server-supplied context (V2, V3, V4, V6, V7, V8, V9): repo identity, git tag, existing versions, visibility, and the candidate file listing.

Validation results are []error whose elements are *Issue values carrying the rule id, a manifest path, and a severity. Warnings (for example the policy-gated "*" egress of V5) are distinguishable via IsWarning and are not blocking; Blocking filters them out.

Index

Constants

View Source
const (
	// MaxShippedPacks caps knowledge.ships.
	MaxShippedPacks = 5
	// MaxKnowledgePackBytes caps one shipped pack: its manifest.json
	// and every file of its tree, as the CLI counts a pack.
	MaxKnowledgePackBytes = 10 << 20
	// MaxKnowledgePackFiles caps the files of one shipped pack's tree, as
	// the registry's store does.
	MaxKnowledgePackFiles = 2000
	// MaxKnowledgePromptChars caps knowledge.accepts.prompt.
	MaxKnowledgePromptChars = 300
	// KnowledgePackSchema is a pack's manifest.json schema.
	KnowledgePackSchema = "knowledge/v1"
)

Limits of the knowledge block (V11) and of a shipped pack (V8).

View Source
const (
	// InterfaceClaudeSkill exports to a Claude skill directory.
	InterfaceClaudeSkill = "claude-skill"
	// InterfaceMCP exports an entry into an MCP client configuration.
	InterfaceMCP = "mcp"
	// InterfaceAgentsMD exports an AGENTS.md section.
	InterfaceAgentsMD = "agents-md"
)

Install-target interface names accepted in runtime.interfaces.

View Source
const (
	MaxRemoteURLLength    = 512
	MaxMCPScopes          = 32
	MaxMCPScopeLength     = 256
	MaxOAuthFiles         = 4
	MaxOAuthEnvEntries    = 8
	MaxOAuthTemplateBytes = 2048
)

Limits on the remote-server and oauth fields (V5).

View Source
const (
	// MemorySeedDir is the archive folder a memory is seeded from, with
	// capabilities.persistent.memory.
	MemorySeedDir = "memory"
	// SkillsDir is the archive folder of shipped skills, with
	// capabilities.persistent.skills: one Agent Skills folder per skill,
	// each with its SkillFile.
	SkillsDir = "skills"
	// SkillFile is the file that makes a folder under SkillsDir a skill.
	SkillFile = "SKILL.md"
)

The archive folders a persistent release's capabilities read.

View Source
const (
	MaxPersonaNameBytes = 64
	MaxPersonaFileBytes = 32 << 10
)

The persona's bounds, the ones a runner keeps for a person's own name and personality.

View Source
const (
	// MaxSummaryChars caps summary length in Unicode code points (V8).
	MaxSummaryChars = 140
	// MaxTags caps the number of tags (V8).
	MaxTags = 10
)

Fixed limits that are part of the manifest grammar itself (not raisable per-org entitlements).

View Source
const (
	MaxGuideOverviewBytes = 4096
	MaxGuidePrepare       = 10
	MaxGuidePrepareChars  = 200
	MaxGuideFilesChars    = 500
	MaxGuideTaskChars     = 200
	MaxGuideConnectChars  = 2000
)

The guide's bounds: it is read before a run, so each part stays the size a person reads at a glance. A key's help is markdown of up to 2,000 characters: where to create a key and which scopes to give it can take a few numbered steps and a link.

View Source
const (
	MaxMCPServerEnvEntries = 16
	MaxMCPServerEnvValue   = 512
)

MaxMCPServerEnvEntries caps the plain env entries one declared server may carry, and MaxMCPServerEnvValue the length of one value (V5, v2).

View Source
const (
	MaxMCPServerArgs   = 16
	MaxMCPServerArgLen = 256
)

MaxMCPServerArgs caps the arguments one declared package server starts with, and MaxMCPServerArgLen the length of one argument (V5, v2).

View Source
const DefaultInstructionFile = "AGENT.md"

DefaultInstructionFile is the v2 instruction entrypoint when the manifest names none.

View Source
const DefaultPersonaFile = "PERSONA.md"

DefaultPersonaFile is the persona's file when the manifest names none.

View Source
const KnowledgeDir = "knowledge"

KnowledgeDir is the archive directory shipped packs live under.

View Source
const MaxBrowserHosts = 32

MaxBrowserHosts bounds the fixed hosts one browser line may add: 32 is room for a site's CDNs, font hosts and sign-in providers, and keeps the consent list readable.

View Source
const MaxBrowserSites = 4

MaxBrowserSites bounds the run-time sites one release may name.

View Source
const MaxExecCommandLength = 64

MaxExecCommandLength caps the length of a declared exec command name (V5).

View Source
const MaxIntakeQuestions = 20

MaxIntakeQuestions bounds intake so a run's up-front form stays a form.

View Source
const MaxMCPServers = 8

MaxMCPServers caps capabilities.mcpServers entries (V5).

View Source
const MaxOpeningChars = 500

MaxOpeningChars bounds interactive.opening: it is a first message, not a second instruction file.

View Source
const MaxPersistentSecrets = 32

MaxPersistentSecrets bounds capabilities.persistent.secrets: a runner keeps at most this many stored secrets for one agent.

View Source
const MaxSubagentWhyChars = 200

MaxSubagentWhyChars bounds a dependency's why, the reason consent shows.

View Source
const MaxSubagents = 16

MaxSubagents bounds the subagents one persistent release may declare.

View Source
const MaxTargetHosts = 4

MaxTargetHosts bounds the target hosts one release may declare.

Variables

View Source
var ImageServerNames = []string{"google-workspace", "microsoft-365"}

ImageServerNames are the servers capabilities.persistent.imageServers may name, the ones a runner runs from its own pinned images.

View Source
var MailProviderNames = []string{"google", "microsoft", "fastmail"}

MailProviderNames are the mail providers capabilities.persistent.mail may name, the ones a runner carries.

Functions

func BaseExecCommands

func BaseExecCommands() []string

BaseExecCommands returns the commands every machine provides, sorted.

func Blocking

func Blocking(errs []error) []error

Blocking filters errs down to the issues that block publication (everything that is not a warning).

func CanonicalJSON

func CanonicalJSON(m *Manifest) ([]byte, error)

CanonicalJSON encodes m as deterministic JSON: object keys sorted lexicographically at every level, and null values, empty objects, and empty arrays pruned so that undeclared optional fields never appear. Two structurally identical manifests always produce byte-identical output; this form is stored as agent_versions.manifest.

The manifest carries no numeric fields, so no floating-point canonicalization concerns apply.

func ExpandOAuthEnvValue

func ExpandOAuthEnvValue(value string, vals map[string]string) (string, error)

ExpandOAuthEnvValue renders an oauth env value: `{access_token}` and `{dir}` from vals, as ExpandOAuthTemplate does.

func ExpandOAuthTemplate

func ExpandOAuthTemplate(template string, vals map[string]string) (string, error)

ExpandOAuthTemplate renders a token-folder file's template: `{access_token}`, `{expiry}` and `{expiry_ms}` from vals. A placeholder outside those, or one with no value, is an error: nothing is left half-rendered.

func IsWarning

func IsWarning(err error) bool

IsWarning reports whether err is a SeverityWarning Issue.

func KnowledgeTreeDigest

func KnowledgeTreeDigest(files map[string][]byte) (digest string, bytes int64, pages int, err error)

KnowledgeTreeDigest is a pack's tree digest, "sha256:<hex>", with its bytes and pages, over files keyed by their slash path in the pack ("wiki/index.md", "sources/a.txt"): the SHA-256 of the canonical tar agentry-cli's pkg/knowledge.TreeDigest writes and the registry's store reads (every file in byte order of its path, mode 0644, uid and gid 0, mtime 0, a PAX header only when a name needs one, two zero blocks).

func KnownSPDXException

func KnownSPDXException(id string) (canonical string, ok bool)

KnownSPDXException is KnownSPDXID for exception identifiers.

func KnownSPDXID

func KnownSPDXID(id string) (canonical string, ok bool)

KnownSPDXID reports whether id is an SPDX license identifier, matching case-insensitively, and returns the canonical spelling.

func LiteralEnvValue

func LiteralEnvValue(v string) bool

LiteralEnvValue reports whether a declared env value would reach the server as written: no `$` the gateway would expand and no `{{…}}` it would evaluate as a template. Exported so the runner's plan-time check is this rule and not a copy of it.

func NormalizeProse

func NormalizeProse(s string) string

NormalizeProse folds whitespace and case so a description that differs only in wrapping or punctuation spacing is not a contradiction.

func ParseSPDXExpression

func ParseSPDXExpression(expr string) (canonical string, ids []string, err error)

ParseSPDXExpression validates an SPDX license expression (SPDX 2.3 Annex D, the subset without LicenseRef): identifiers, an optional "+", WITH <exception>, AND / OR, and parentheses. It returns the expression with canonical spellings and the distinct license ids it names, in order of first appearance — what policy gates compare against.

func RemoteShellCommands

func RemoteShellCommands(c Capabilities) []string

RemoteShellCommands returns the commands of c's exec declaration that make a remote session themselves (ssh, scp, sftp, rsync), in declaration order, compared by program name. V14 warns on them and S1 reports them low: such a release would make its own connection, where a declared target host has the runner make it.

func Rename

func Rename(raw []byte, namespace, name string) ([]byte, error)

Rename returns raw, an agent.yaml, with its top-level namespace and name set to the given ones: the one change a fork's first commit makes to the manifest it copies, since a manifest must name the agent it is submitted to. Everything else stays as written, comments included, though the YAML is re-emitted with two-space indentation. A key that is absent is added after the last of schemaVersion, namespace and name that is present, so the file still reads in the usual order. It refuses a document that is not a single mapping.

func ShippedPackFile

func ShippedPackFile(ships []string, p string) (string, bool)

ShippedPackFile says whether p is a file of a shipped pack's tree — under knowledge/<name>/wiki/ or knowledge/<name>/sources/ for a name in ships — and which pack. A pack's manifest.json is not part of its tree.

func ShippedPacksOf

func ShippedPacksOf(manifestJSON []byte) []string

ShippedPacksOf reads the valid names of the packs a manifest ships from its canonical JSON, sorted and without repeats; none for a manifest without the block or one that does not parse. It is what the pipeline's stages and its AI Review read, and what a draft's check reads before submission, so both declare the same packs.

func StripOAuthPlaceholders

func StripOAuthPlaceholders(s string) string

StripOAuthPlaceholders removes every placeholder-shaped `{name}` from s, for a scanner that reads what an author wrote around them.

func UnsupportedOAuthPackage

func UnsupportedOAuthPackage(sourceID string) (alternative string, unsupported bool)

UnsupportedOAuthPackage reports whether a package (its SourceID) is on the unsupported list, and the alternative to declare.

func ValidExecCommand

func ValidExecCommand(cmd string) bool

ValidExecCommand reports whether cmd is a program name a manifest may declare under capabilities.exec.commands.

func ValidKnowledgePackName

func ValidKnowledgePackName(name string) bool

ValidKnowledgePackName is the CLI's rule for a pack name (agentry-cli pkg/knowledge.ValidName): 1-64 lowercase letters, digits, '.', '-' or '_', starting with a letter or a digit.

func ValidName

func ValidName(s string) bool

ValidName reports whether s is a valid agent name per the database's pattern (lowercase alphanumeric plus interior hyphens, at most 65 chars).

func ValidNamespace

func ValidNamespace(s string) bool

ValidNamespace reports whether s is a valid namespace handle per the database's pattern (at most 39 chars).

func Validate

func Validate(m *Manifest) []error

Validate applies every rule that needs only the manifest itself: the closed field grammar of V1, the semver syntax half of V3, the pattern shape half of V4, the capability vocabulary of V5 (with the "*" egress warning), the entrypoint shape half of V6, and the summary/tag quotas of V8. The returned errors are *Issue values; a manifest with only SeverityWarning issues is valid.

func ValidateInContext

func ValidateInContext(m *Manifest, ctx Context) []error

ValidateInContext applies Validate plus the context rules V2, V3, V4, V6, V7, and V8. It is the full server-side submit check; the returned errors are *Issue values and a result containing only SeverityWarning issues is a pass.

Types

type AgentDependency

type AgentDependency struct {
	// Ref is "namespace/name".
	Ref string `yaml:"ref" json:"ref"`
	// Version is a semver constraint (e.g. "^1.2"); empty means any,
	// except for a subagent.
	Version string `yaml:"version,omitempty" json:"version,omitempty"`
	// Why says what the agent uses it for, in one plain line of at most
	// MaxSubagentWhyChars, shown when the person agrees.
	Why string `yaml:"why,omitempty" json:"why,omitempty"`
}

AgentDependency references another agent by namespace/name plus a semver constraint. In a persistent release it is a subagent, and both the constraint and Why are required (V18).

func (AgentDependency) SubagentAllows added in v0.6.1002

func (d AgentDependency) SubagentAllows(version string) bool

SubagentAllows reports whether version satisfies the subagent's constraint; false when either does not parse.

type Author

type Author struct {
	// Name is required for each listed author.
	Name string `yaml:"name" json:"name"`
	// Email is optional.
	Email string `yaml:"email,omitempty" json:"email,omitempty"`
}

Author credits one manifest author.

type Browser

type Browser struct {
	// Sites names url intake questions: the person's answer to each is a
	// site the browser may open, with its subdomains.
	Sites []string `yaml:"sites,omitempty" json:"sites,omitempty"`
	// Hosts are fixed hosts the browser may also reach, each an exact
	// DNS name or a "*." suffix; no address, no port.
	Hosts []string `yaml:"hosts,omitempty" json:"hosts,omitempty"`
	// Scope is BrowserScopeSite (the default when empty) or
	// BrowserScopePublic.
	Scope BrowserScope `yaml:"scope,omitempty" json:"scope,omitempty"`
	// Secrets names declared secrets the browser may type into the
	// site's forms; each is also in capabilities.secrets or
	// optionalSecrets.
	Secrets []string `yaml:"secrets,omitempty" json:"secrets,omitempty"`
}

Browser is capabilities.browser (v2, V15).

func (*Browser) IsPublic

func (b *Browser) IsPublic() bool

IsPublic reports whether the browser may reach any public site.

type BrowserScope

type BrowserScope string

BrowserScope says how far the browser may go.

const (
	// BrowserScopeSite admits the run-time sites, their subdomains and the
	// declared hosts. It is the default.
	BrowserScopeSite BrowserScope = "site"
	// BrowserScopePublic admits any public site, on ports 80 and 443; a
	// runner allows it only under its operator's policy, and publication
	// treats it as "*" egress.
	BrowserScopePublic BrowserScope = "public"
)

Browser scopes.

type Capabilities

type Capabilities struct {
	// Network declares network capabilities.
	Network Network `yaml:"network,omitempty" json:"network,omitempty"`
	// Filesystem declares filesystem access.
	Filesystem Filesystem `yaml:"filesystem,omitempty" json:"filesystem,omitempty"`
	// Exec declares subprocess execution.
	Exec ExecCapability `yaml:"exec,omitempty" json:"exec,omitempty"`
	// Secrets lists environment variable NAMES the agent expects — never
	// values.
	Secrets []string `yaml:"secrets,omitempty" json:"secrets,omitempty"`
	// OptionalSecrets names the declared secrets — the agent's own or a
	// declared MCP server's — that the author marks as ones a run can
	// do without (v2, V5); every other declared secret is required. It
	// adds no name to the contract: each must already be declared. The
	// runner and hosted runs honour it.
	OptionalSecrets []string `yaml:"optionalSecrets,omitempty" json:"optionalSecrets,omitempty"`
	// TargetHosts names the intake questions of type host (v2, V14):
	// each is a target host, a machine the person names when the run
	// starts, that the agent may run commands on and administer through
	// the runner's host tools. The release never names the host, its
	// address, user or port; it declares only that it takes one, so
	// consent, the judge and search can read it.
	TargetHosts []string `yaml:"targetHosts,omitempty" json:"targetHosts,omitempty"`
	// Browser declares a headless browser for the run (v2, V15): the
	// sites the person names at run time, the fixed hosts its pages
	// need, its scope, and the declared secrets it may type. Absent, a
	// run has no browser (browser.go).
	Browser *Browser `yaml:"browser,omitempty" json:"browser,omitempty"`
	// Persistent declares what a persistent agent may do beyond an
	// ordinary run (v2, V16), valid only with the persistent mode; nil
	// declares nothing (persistent.go).
	Persistent *Persistent `yaml:"persistent,omitempty" json:"persistent,omitempty"`
	// DataAccess lists semantic data categories the agent touches.
	DataAccess []DataAccess `yaml:"dataAccess,omitempty" json:"dataAccess,omitempty"`
	// MCPServers lists the MCP servers this agent requires at run time.
	// The runner installs each from the operator's trusted repository —
	// npm and PyPI by default — configured for this exact release only,
	// and serves them through the per-run gateway. Versions are EXACT
	// pins (V5): they are part of the release's content, so a new agent
	// version is a new supply-chain decision by construction.
	MCPServers []MCPServer `yaml:"mcpServers,omitempty" json:"mcpServers,omitempty"`
	// Knowledge names the packs the release ships, as the contract a
	// person consents to records them (Manifest.Contract). It is never
	// written under capabilities in agent.yaml: the knowledge block is
	// where a release declares its packs.
	Knowledge []string `yaml:"-" json:"knowledge,omitempty"`
	// Subagents are a persistent release's subagents, as the contract a
	// person consents to records them (Manifest.Contract). They are never
	// written under capabilities in agent.yaml: dependencies.agents is
	// where a release declares them.
	Subagents []AgentDependency `yaml:"-" json:"subagents,omitempty"`
}

Capabilities is the closed-vocabulary security contract. It is a declaration to consumers and policy, not runtime enforcement.

func (Capabilities) IsOptionalSecret

func (c Capabilities) IsOptionalSecret(name string) bool

IsOptionalSecret reports whether the release marks the declared secret name optional (capabilities.optionalSecrets): one a run may start without. Every other declared secret is required.

type CapabilityDiff

type CapabilityDiff struct {
	// Widened lists strictly-more-permissive changes.
	Widened []string `json:"widened,omitempty"`
	// Narrowed lists strictly-less-permissive changes.
	Narrowed []string `json:"narrowed,omitempty"`
}

CapabilityDiff is the comparison between a capability contract a person accepted and the one a newer release declares. Each line is phrased for a human — "adds network egress to evil.example" — because the consent gate shows it verbatim.

The rule is the one the CLI's install state and the desktop's Prepare apply on an update; the registry applies it to an account install, so a person is asked for the capability acceptance again only when the new release may do more than the one they accepted.

func DiffCapabilities

func DiffCapabilities(old, next Capabilities) CapabilityDiff

DiffCapabilities compares the previously accepted contract with the new one.

func (CapabilityDiff) Empty

func (d CapabilityDiff) Empty() bool

Empty reports an identical contract.

func (CapabilityDiff) HasWidened

func (d CapabilityDiff) HasWidened() bool

HasWidened reports whether anything requires consent again.

type Channel

type Channel string

Channel is a release channel.

const (
	// ChannelStable is the default resolution channel.
	ChannelStable Channel = "stable"
	// ChannelBeta is the opt-in pre-release channel.
	ChannelBeta Channel = "beta"
)

Release channels (closed set). An empty channel in the manifest means ChannelStable; use Manifest.EffectiveChannel.

type Context

type Context struct {
	// Namespace is the target repo's namespace handle (V2).
	Namespace string
	// Name is the target repo's agent name (V2).
	Name string
	// TagVersion is the git tag being published (with or without the
	// leading "v"); empty skips the tag-equality check (cli-upload source).
	TagVersion string
	// ExistingVersions maps channel to the version strings already
	// published for this agent (V3). The new version must be absent from
	// every channel and greater than every version on its own channel.
	ExistingVersions map[Channel][]string
	// Public marks a public publish, which requires license metadata and
	// LICENSE/README.md files (V7).
	Public bool
	// Files lists the candidate repo files at the submitted commit.
	Files []FileInfo
	// Quotas overrides the default quotas (org entitlements); nil uses
	// DefaultQuotas.
	Quotas *Quotas
	// ReadFile returns the content of a repo-relative file at the
	// submitted commit. It feeds V9 (skill frontmatter vs manifest); nil
	// skips that rule, so callers without content access are unaffected.
	ReadFile func(path string) ([]byte, error)
}

Context is the server-supplied context for ValidateInContext. Namespace and Name identify the repo the submission targets and are always required; the other fields default to "not applicable" when zero.

type DataAccess

type DataAccess string

DataAccess is a semantic data-access category from the closed capability vocabulary.

const (
	DataAccessEmail    DataAccess = "email"
	DataAccessCalendar DataAccess = "calendar"
	DataAccessFiles    DataAccess = "files"
	DataAccessTickets  DataAccess = "tickets"
	DataAccessCode     DataAccess = "code"
	DataAccessMessages DataAccess = "messages"
	DataAccessPayments DataAccess = "payments"
	DataAccessOther    DataAccess = "other"
)

DataAccess categories (closed set).

type Dependencies

type Dependencies struct {
	// Agents lists depended-on agents.
	Agents []AgentDependency `yaml:"agents,omitempty" json:"agents,omitempty"`
}

Dependencies lists informational dependencies (v1: no auto-install).

type Egress

type Egress struct {
	// None is true when egress was declared as the scalar "none".
	None bool `json:"-"`
	// Hosts lists exact DNS hostnames; "*" means any host.
	Hosts []string `json:"-"`
}

Egress declares outbound network access: the scalar "none", or a list of exact DNS hostnames where the element "*" requests unrestricted egress (allowed but flagged for policy evaluation, V5). The scalar "*" is accepted and normalized to the single-element list.

func (Egress) IsZero

func (e Egress) IsZero() bool

IsZero reports whether egress was not declared at all.

func (Egress) MarshalJSON

func (e Egress) MarshalJSON() ([]byte, error)

MarshalJSON encodes the union back to its canonical shape.

func (*Egress) UnmarshalJSON

func (e *Egress) UnmarshalJSON(b []byte) error

UnmarshalJSON decodes the canonical JSON union shape.

func (*Egress) UnmarshalYAML

func (e *Egress) UnmarshalYAML(node *yaml.Node) error

UnmarshalYAML implements strict decoding of the egress union shape.

type Entrypoints

type Entrypoints struct {
	// Instruction is the repo-relative instruction file (v2); empty means
	// DefaultInstructionFile. A leading YAML frontmatter block is stripped
	// by consumers, so a SKILL.md-shaped file works unchanged.
	Instruction string `yaml:"instruction,omitempty" json:"instruction,omitempty"`
	// Skill is the v1 repo-relative skill file (e.g. SKILL.md).
	Skill string `yaml:"skill,omitempty" json:"skill,omitempty"`
	// MCP is the v1 mcp-server launch spec. Parsed for archives published
	// under the withdrawn kind; never valid for publish.
	MCP *MCPEntrypoint `yaml:"mcp,omitempty" json:"mcp,omitempty"`
}

Entrypoints names where the instruction lives. A v2 manifest sets only Instruction; the other two keys are v1's per-kind entrypoints and are refused in v2 (V1).

type ExecCapability

type ExecCapability struct {
	// None is true when exec was declared as the scalar "none".
	None bool `json:"-"`
	// Commands lists the allowed commands; set only for the commands form.
	Commands []string `json:"-"`
}

ExecCapability declares subprocess execution: the scalar "none" or a mapping {commands: [...]} of command names.

func (ExecCapability) IsZero

func (x ExecCapability) IsZero() bool

IsZero reports whether exec was not declared at all.

func (ExecCapability) MarshalJSON

func (x ExecCapability) MarshalJSON() ([]byte, error)

MarshalJSON encodes the union back to its canonical shape.

func (*ExecCapability) UnmarshalJSON

func (x *ExecCapability) UnmarshalJSON(b []byte) error

UnmarshalJSON decodes the canonical JSON union shape.

func (*ExecCapability) UnmarshalYAML

func (x *ExecCapability) UnmarshalYAML(node *yaml.Node) error

UnmarshalYAML implements strict decoding of the exec union shape.

type FSAccess

type FSAccess struct {
	// Mode is the declared shape; empty means not declared.
	Mode FSMode `json:"-"`
	// Paths is set only for FSModePaths.
	Paths []string `json:"-"`
}

FSAccess declares one direction of filesystem access: the scalar "none" or "workspace", or a mapping {paths: [...]} of repo-relative paths.

func (FSAccess) IsZero

func (a FSAccess) IsZero() bool

IsZero reports whether the access was not declared at all.

func (FSAccess) MarshalJSON

func (a FSAccess) MarshalJSON() ([]byte, error)

MarshalJSON encodes the union back to its canonical shape.

func (*FSAccess) UnmarshalJSON

func (a *FSAccess) UnmarshalJSON(b []byte) error

UnmarshalJSON decodes the canonical JSON union shape.

func (*FSAccess) UnmarshalYAML

func (a *FSAccess) UnmarshalYAML(node *yaml.Node) error

UnmarshalYAML implements strict decoding of the filesystem union shape.

type FSMode

type FSMode string

FSMode is the shape of a filesystem access declaration.

const (
	// FSModeNone declares no access.
	FSModeNone FSMode = "none"
	// FSModeWorkspace declares access limited to the consumer workspace.
	FSModeWorkspace FSMode = "workspace"
	// FSModePaths declares access to an explicit path list.
	FSModePaths FSMode = "paths"
)

Filesystem access modes (closed set). The empty mode means "not declared".

type FileInfo

type FileInfo struct {
	// Path is the repo-relative, slash-separated file path.
	Path string
	// Size is the file size in bytes.
	Size int64
	// Symlink marks symbolic links, which are rejected in the resolved
	// include set (V4/S1).
	Symlink bool
	// IsText marks a file the scanners read as prose (the same sniff S1
	// applies: no NUL byte in the head, not an image). V8 sums these
	// against Quotas.MaxTextBytes, the instruction-file total. A lister
	// that does not classify leaves it false and the total check does
	// not apply.
	IsText bool
}

FileInfo describes one candidate repo file for V4/V6/V7/V8. Paths are slash-separated and repo-root-relative (e.g. "prompts/system.md").

func ResolveInclude

func ResolveInclude(patterns []string, files []FileInfo) []FileInfo

ResolveInclude returns the files selected by publish.include patterns, in sorted path order. It is the shared filter between validation (V4) and the registry's archive builder, so the archive can never contain a file validation did not see. Symlinks and unsafe patterns are NOT filtered here: V4 rejects them; callers validate first.

type Filesystem

type Filesystem struct {
	// Read declares read access.
	Read FSAccess `yaml:"read,omitempty" json:"read,omitempty"`
	// Write declares write access.
	Write FSAccess `yaml:"write,omitempty" json:"write,omitempty"`
}

Filesystem declares filesystem read and write access.

type Frontmatter

type Frontmatter struct {
	Name        string
	Description string
	// Keys lists every top-level key present, for the report.
	Keys []string
}

Frontmatter is the YAML block a skill file may open with. Consuming runtimes (the claude-skill export) read `name` and `description` from it, and the exporter keeps an existing block verbatim, so whatever it says is what the consumer sees. V9 and S1 compare it against the signed manifest.

func ParseFrontmatter

func ParseFrontmatter(content []byte) (fm Frontmatter, ok bool, err error)

ParseFrontmatter extracts the leading `---` YAML block of a skill file. ok is false when the file has no frontmatter; a block that is not valid YAML returns ok=true with an error so the caller can flag it.

type Guide

type Guide struct {
	// Overview says what the QuickAgent does and returns, in markdown.
	Overview string `yaml:"overview,omitempty" json:"overview,omitempty"`
	// Prepare lists what to gather before starting, one line each.
	Prepare []string `yaml:"prepare,omitempty" json:"prepare,omitempty"`
	// Files says what files to bring to the run, in one line.
	Files string `yaml:"files,omitempty" json:"files,omitempty"`
	// Task is the placeholder for the task field.
	Task string `yaml:"task,omitempty" json:"task,omitempty"`
	// Connect is help per declared secret name (where to create the key,
	// which scopes it needs) or per server that signs in by OAuth, keyed
	// by its SourceID (how to make the OAuth client that vendor needs),
	// in markdown that may span lines. Every key must be a declared secret
	// or such a server (V10).
	Connect map[string]string `yaml:"connect,omitempty" json:"connect,omitempty"`
}

Guide is the author's own words for the run setup: clients show them before a run and derive the same steps from the rest of the manifest when a release carries none.

func (*Guide) ServerConnect

func (g *Guide) ServerConnect(srv MCPServer) string

ServerConnect is the publisher's help for signing in to srv, keyed by its SourceID; "" when the guide carries none.

type InputKind

type InputKind string

InputKind is one kind of file a QuickAgent takes.

const (
	// InputKindDocuments is prose to read: PDFs, office documents, e-books,
	// rich text.
	InputKindDocuments InputKind = "documents"
	// InputKindCode is a codebase or its files: source, markup, build and
	// configuration files, a repository.
	InputKindCode InputKind = "code"
	// InputKindData is structured data: CSV, JSON, YAML, spreadsheets, logs.
	InputKindData InputKind = "data"
	// InputKindImages is pictures: photographs, scans, screenshots,
	// diagrams.
	InputKindImages InputKind = "images"
	// InputKindAny is no particular kind, and is declared alone.
	InputKindAny InputKind = "any"
)

The closed set of input kinds (V12).

func (InputKind) Valid

func (k InputKind) Valid() bool

Valid reports whether k is one of the closed set of input kinds.

type InputView

type InputView string

InputView is the view of an input the agent reads by default.

const (
	// InputViewText points the agent at each input's decoded text, and at
	// the upload for a file that has none.
	InputViewText InputView = "text"
	// InputViewOriginal points the agent at each input as uploaded.
	InputViewOriginal InputView = "original"
	// InputViewBoth keeps each file's own default (a decoder's text where
	// one made it, anything else as uploaded) and says the agent uses both
	// views. The runner treats it exactly as an undeclared view; declaring
	// it records the author's intent for the run setup and the Drafter.
	InputViewBoth InputView = "both"
)

The closed set of input views (V12).

func (InputView) Valid

func (v InputView) Valid() bool

Valid reports whether v is one of the closed set of input views.

type Inputs

type Inputs struct {
	// Kinds are the kinds of file the QuickAgent takes; absent means any.
	Kinds []InputKind `yaml:"kinds,omitempty" json:"kinds,omitempty"`
	// View is the view the agent reads an input in by default; absent
	// means both.
	View InputView `yaml:"view,omitempty" json:"view,omitempty"`
}

Inputs is the manifest's inputs block (v2, V12).

type IntakeQuestion

type IntakeQuestion struct {
	// ID names the answer: [a-z0-9_]+, unique within the manifest (V10).
	ID string `yaml:"id" json:"id"`
	// Prompt is what the user is asked.
	Prompt string `yaml:"prompt" json:"prompt"`
	// Type is the answer shape; text when empty.
	Type IntakeType `yaml:"type,omitempty" json:"type,omitempty"`
	// Required refuses to start the run without an answer.
	Required bool `yaml:"required,omitempty" json:"required,omitempty"`
	// Choices lists the allowed answers for IntakeChoice; forbidden otherwise.
	Choices []string `yaml:"choices,omitempty" json:"choices,omitempty"`
}

IntakeQuestion is one question asked before a run starts.

type IntakeType

type IntakeType string

IntakeType is the answer shape of an intake question (closed set).

const (
	// IntakeText is a free-text answer.
	IntakeText IntakeType = "text"
	// IntakeSecret is a value that must not be echoed or recorded; the
	// runner injects it as a run-scoped secret rather than as text.
	IntakeSecret IntakeType = "secret"
	// IntakeChoice is one of Choices.
	IntakeChoice IntakeType = "choice"
	// IntakeFile is a host path the runner stages into the inputs folder.
	IntakeFile IntakeType = "file"
	// IntakeHost asks for a target host: a machine the person names when
	// the run starts, as [user@]host[:port], that the runner reaches over
	// SSH from a container of its own (V14; targethosts.go). Every host
	// question is listed in capabilities.targetHosts.
	IntakeHost IntakeType = "host"
	// IntakeRepository asks for an input source of the repository kind: an
	// https git URL and an optional ref, fetched before the run into
	// /inputs/<id>/ (V13; sources.go).
	IntakeRepository IntakeType = "repository"
	// IntakeURL asks for an input source of the url kind: one https URL,
	// fetched before the run into /inputs/<id>/ (V13; sources.go).
	IntakeURL IntakeType = "url"
)

Intake answer types.

func SourceTypes

func SourceTypes() []IntakeType

SourceTypes returns the intake types that ask for an input source. The slice is the caller's own.

func (IntakeType) IsSource

func (t IntakeType) IsSource() bool

IsSource reports whether an intake question of type t asks for an input source.

type InteractiveHints

type InteractiveHints struct {
	// Opening is the assistant's first message when no task text was given.
	Opening string `yaml:"opening,omitempty" json:"opening,omitempty"`
	// IdleTimeoutSeconds ends the session after this much silence; policy
	// caps it.
	IdleTimeoutSeconds int `yaml:"idleTimeoutSeconds,omitempty" json:"idleTimeoutSeconds,omitempty"`
}

InteractiveHints are the manifest's hints for interactive sessions. Limits here can only tighten what runner policy allows.

type Issue

type Issue struct {
	// Rule is the rule id, one of Rules().
	Rule string
	// Severity distinguishes blocking errors from flags such as the
	// policy-gated "*" egress.
	Severity Severity
	// Path locates the finding in the manifest (e.g.
	// "capabilities.network.egress[0]"); empty for whole-manifest issues.
	Path string
	// Message is the human-readable description.
	Message string
}

Issue is one validation finding. All errors returned by Validate and ValidateInContext are *Issue values.

func AsIssue

func AsIssue(err error) (*Issue, bool)

AsIssue unwraps err into an *Issue when possible.

func (*Issue) Error

func (i *Issue) Error() string

Error implements the error interface.

type Knowledge

type Knowledge struct {
	// Ships names the packs the archive carries under knowledge/<name>/.
	Ships []ShippedKnowledge `yaml:"ships,omitempty" json:"ships,omitempty"`
	// Accepts asks the person for a pack of their own: shown in the run
	// setup's Knowledge step, never to the agent.
	Accepts *KnowledgeAccepts `yaml:"accepts,omitempty" json:"accepts,omitempty"`
}

Knowledge is the manifest's knowledge block (v2, V11).

type KnowledgeAccepts

type KnowledgeAccepts struct {
	// Prompt is one plain line shown in the run setup.
	Prompt string `yaml:"prompt" json:"prompt"`
	// Required means the setup's Knowledge step cannot be skipped.
	Required bool `yaml:"required,omitempty" json:"required,omitempty"`
}

KnowledgeAccepts is what a release asks a person to attach.

type MCPAuth

type MCPAuth string

MCPAuth is how a remote MCP server is signed in to (v2).

const (
	// AuthOAuth needs the person's connection: an OAuth grant to the
	// server for this one QuickAgent version.
	AuthOAuth MCPAuth = "oauth"
	// AuthSecret sends the server's one declared secret as a bearer
	// header.
	AuthSecret MCPAuth = "secret"
	// AuthNone sends nothing.
	AuthNone MCPAuth = "none"
)

type MCPEntrypoint

type MCPEntrypoint struct {
	// Command is the executable to run (e.g. node, python).
	Command string `yaml:"command" json:"command"`
	// Args are the command arguments; args naming repo files must be
	// included in the release archive (V4).
	Args []string `yaml:"args,omitempty" json:"args,omitempty"`
	// Transport is stdio or http.
	Transport Transport `yaml:"transport" json:"transport"`
}

MCPEntrypoint launches an MCP server (kind=mcp-server, V6).

type MCPOAuth

type MCPOAuth struct {
	// Issuer is the authorization server's https:// issuer; the runner
	// reads its metadata to sign in.
	Issuer string `yaml:"issuer" json:"issuer"`
	// Scopes are what consent asks for.
	Scopes []string `yaml:"scopes,omitempty" json:"scopes,omitempty"`
	// Files are written by the runner into the server's token folder,
	// mounted read-only, each rendered by ExpandOAuthTemplate. The runner
	// writes them itself, never through the gateway, so a template's `$`
	// and braces are content, not expansions.
	Files []MCPOAuthFile `yaml:"files,omitempty" json:"files,omitempty"`
	// Env are environment variables the runner sets on the server, each
	// rendered by ExpandOAuthEnvValue: the token itself, or a path in the
	// token folder.
	Env map[string]string `yaml:"env,omitempty" json:"env,omitempty"`
}

MCPOAuth is a package server's OAuth sign-in: the authorization server a connection is made with, the scopes consent asks for, and how the access token reaches the server.

type MCPOAuthFile

type MCPOAuthFile struct {
	// Path is a plain file name in the token folder.
	Path string `yaml:"path" json:"path"`
	// Template is the file's content, with placeholders.
	Template string `yaml:"template" json:"template"`
}

MCPOAuthFile is one file of a package server's token folder.

type MCPServer

type MCPServer struct {
	// NPM is the npm package name (optionally @scope/name).
	NPM string `yaml:"npm,omitempty" json:"npm,omitempty"`
	// PyPI is the PyPI project name (PEP-503 normalized form).
	PyPI string `yaml:"pypi,omitempty" json:"pypi,omitempty"`
	// URL is a remote server's HTTPS address (v2): a public host, port
	// 443, no user information, query or fragment. Its host is the
	// server's one egress host.
	URL string `yaml:"url,omitempty" json:"url,omitempty"`
	// Auth is how a remote server is signed in to (v2, required with
	// URL).
	Auth MCPAuth `yaml:"auth,omitempty" json:"auth,omitempty"`
	// Scopes are what a remote server's OAuth consent asks for (v2, with
	// AuthOAuth only).
	Scopes []string `yaml:"scopes,omitempty" json:"scopes,omitempty"`
	// Version is the exact package version to install (V5: no ranges); a
	// remote server has none.
	Version string `yaml:"version,omitempty" json:"version,omitempty"`
	// Tools optionally restricts the server to these tool names; empty
	// grants the server's full set.
	Tools []string `yaml:"tools,omitempty" json:"tools,omitempty"`
	// Secrets lists environment variable NAMES this server needs — never
	// values. Additive to capabilities.secrets; collected into the same
	// per-signature MCP profile by the runner's guided setup.
	Secrets []string `yaml:"secrets,omitempty" json:"secrets,omitempty"`
	// Egress lists the exact hosts THIS SERVER may reach ("*" allowed,
	// policy-gated at run time like agent egress). Empty means none.
	Egress []string `yaml:"egress,omitempty" json:"egress,omitempty"`
	// Env is plain, non-secret configuration the server reads from its
	// environment (v2, V5). It lives in the manifest so it is in the
	// diff, the digest and the review, never in a policy file; a name
	// that is also a declared secret is refused, so a value is either
	// configuration in the contract or a secret from the profile.
	Env map[string]string `yaml:"env,omitempty" json:"env,omitempty"`
	// Args are the arguments a package server's command starts with (v2,
	// V5), after the package's own entry: `[mcp]` for a server that is a
	// subcommand of a larger CLI. Each is one literal word, written in the
	// manifest so it is in the diff, the digest and the review; a remote
	// server takes none.
	Args []string `yaml:"args,omitempty" json:"args,omitempty"`
	// OAuth gives a package server an OAuth sign-in (v2): the person's
	// connection's access token reaches the server through Env or
	// Files, rendered by the runner, and never a refresh token or a
	// client secret.
	OAuth *MCPOAuth `yaml:"oauth,omitempty" json:"oauth,omitempty"`
}

MCPServer is one declared MCP server requirement. Exactly one of NPM, PyPI or URL names it. A package server (NPM or PyPI) carries an exact Version, never a range; a remote server (URL, v2) runs at its vendor and carries none.

func (MCPServer) IsRemote

func (s MCPServer) IsRemote() bool

IsRemote reports whether the server is declared by address rather than as a package.

func (MCPServer) NeedsConnection

func (s MCPServer) NeedsConnection() bool

NeedsConnection reports whether a run of the server needs the person's OAuth connection: a remote server signed in to by OAuth, or a package server with an OAuth block.

func (MCPServer) RemoteHost

func (s MCPServer) RemoteHost() string

RemoteHost is a remote server's host name, its one egress host; "" for a package server or an address that does not parse.

func (MCPServer) SourceID

func (s MCPServer) SourceID() string

SourceID returns the server's qualified id ("npm:@scope/x", "pypi:name" or "url:https://…") — the duplicate-detection and store key.

type Manifest

type Manifest struct {
	// SchemaVersion is the manifest schema major ("1" or "2"); unknown
	// majors are rejected at Parse time (V1). Major() reads it.
	SchemaVersion string `yaml:"schemaVersion" json:"schemaVersion"`
	// Name must match the target repo's agent name (V2) and the
	// agents.name DDL pattern.
	Name string `yaml:"name" json:"name"`
	// Namespace must match the target repo's namespace handle (V2) and
	// the handles.handle DDL pattern.
	Namespace string `yaml:"namespace" json:"namespace"`
	// Kind is the v1 classification (skill | prompt-agent | mcp-server),
	// read for schema major 1 only; a v2 manifest must not carry it (V1).
	// Use SupportedModes rather than reading this.
	Kind string `yaml:"kind,omitempty" json:"kind,omitempty"`
	// Modes is the v2 set of run modes the release supports: required,
	// non-empty, from the closed set, no duplicates (V1). Absent in v1.
	Modes []Mode `yaml:"modes,omitempty" json:"modes,omitempty"`
	// Version is strict semver without a leading "v"; it must equal the git
	// tag and exceed every existing version on its channel (V3).
	Version string `yaml:"version" json:"version"`
	// Summary is a plain-text one-liner, at most MaxSummaryChars runes (V8).
	Summary string `yaml:"summary" json:"summary"`
	// License is an SPDX identifier; required for public publish (V7).
	License string `yaml:"license,omitempty" json:"license,omitempty"`
	// Authors optionally credits the authors.
	Authors []Author `yaml:"authors,omitempty" json:"authors,omitempty"`
	// Homepage is an optional informational URL.
	Homepage string `yaml:"homepage,omitempty" json:"homepage,omitempty"`
	// Tags carries at most MaxTags lowercase [a-z0-9-]+ tags (V8).
	Tags []string `yaml:"tags,omitempty" json:"tags,omitempty"`
	// Entrypoints names the instruction file (v2) or the v1 per-kind
	// entrypoints.
	Entrypoints Entrypoints `yaml:"entrypoints,omitempty" json:"entrypoints,omitempty"`
	// Intake lists the questions asked before a run starts, in either mode
	// (v2, V10). Answers are staged read-only for the agent by the runner.
	Intake []IntakeQuestion `yaml:"intake,omitempty" json:"intake,omitempty"`
	// Interactive carries hints for interactive sessions (v2, V10).
	// Everything else about a session is runner policy, not manifest.
	Interactive *InteractiveHints `yaml:"interactive,omitempty" json:"interactive,omitempty"`
	// Guide is what a person reads before a run: what the QuickAgent
	// does, what to gather first, what files to bring, a task
	// placeholder, and help for each declared secret (v2, V10). It is
	// shown to people only: it never reaches the agent, the run plan,
	// the capability diff or the consent.
	Guide *Guide `yaml:"guide,omitempty" json:"guide,omitempty"`
	// Knowledge names the knowledge packs the release ships in its
	// archive under knowledge/<name>/ and what a person may attach of
	// their own (v2, V11). The shipped names are part of the contract
	// (Contract); what is accepted is shown to people only.
	Knowledge *Knowledge `yaml:"knowledge,omitempty" json:"knowledge,omitempty"`
	// Inputs says what kinds of file the QuickAgent takes and which
	// view of them its agent reads by default (v2, V12). Absent, any
	// kind is taken and each file keeps its own default view; use
	// TakesKinds and DefaultInputView. It grants nothing and is outside
	// the contract.
	Inputs *Inputs `yaml:"inputs,omitempty" json:"inputs,omitempty"`
	// Runtime carries informational runtime hints and install targets.
	Runtime Runtime `yaml:"runtime,omitempty" json:"runtime,omitempty"`
	// Capabilities is the security contract (closed vocabulary, V5).
	// The zero value declares a pure-text agent.
	Capabilities Capabilities `yaml:"capabilities,omitempty" json:"capabilities,omitempty"`
	// Persona is the name and the text a persistent agent takes on (v2,
	// V17), valid only with the persistent mode.
	Persona *Persona `yaml:"persona,omitempty" json:"persona,omitempty"`
	// Dependencies lists agent dependencies: a persistent release's
	// subagents (V18), informational for any other release.
	Dependencies Dependencies `yaml:"dependencies,omitempty" json:"dependencies,omitempty"`
	// Publish controls the release archive allowlist and channel (V4).
	Publish Publish `yaml:"publish" json:"publish"`
}

Manifest is the full agent.yaml document. Field comments note the owning validation rules; zero values mean "not declared".

func Parse

func Parse(data []byte) (*Manifest, error)

Parse decodes exactly one agent.yaml document (YAML 1.2 via yaml.v3). Unknown keys anywhere are errors (closed schema, V1), trailing YAML documents are rejected, and only schemaVersion majors "1" and "2" are accepted. Field-level rules live in Validate and ValidateInContext.

func (*Manifest) Contract

func (m *Manifest) Contract() Capabilities

Contract is the capability contract a person consents to: the declared capabilities, the names of the packs the release ships and a persistent release's subagents, so that a later release shipping one more pack or naming one more subagent asks again. It is what the registry records for a version and an install, and what a client compares with DiffCapabilities.

func (*Manifest) DefaultInputView

func (m *Manifest) DefaultInputView() InputView

DefaultInputView returns the view the agent reads an input in by default: the declared view, or InputViewBoth (each file's own default) when the release declares none.

func (*Manifest) EffectiveChannel

func (m *Manifest) EffectiveChannel() Channel

EffectiveChannel returns the release channel, defaulting to ChannelStable when the manifest omits publish.channel.

func (*Manifest) HostQuestions

func (m *Manifest) HostQuestions() []IntakeQuestion

HostQuestions returns the release's intake questions of type host, in intake order.

func (*Manifest) InstructionCandidates

func (m *Manifest) InstructionCandidates() []string

InstructionCandidates returns the repo-relative files that may hold the harness instruction, in the order a caller should try them: exactly one for v2 (entrypoints.instruction, else DefaultInstructionFile) and for a v1 skill (entrypoints.skill); the closed AGENT.md-then-PROMPT.md order for a v1 prompt-agent; nothing for the withdrawn v1 mcp-server kind.

func (*Manifest) IsPersistent added in v0.6.1002

func (m *Manifest) IsPersistent() bool

IsPersistent reports whether the release supports the persistent mode.

func (*Manifest) Major

func (m *Manifest) Major() int

Major returns the schema major (1 or 2); 0 when the version is not one Parse would accept.

func (*Manifest) PersonaFile added in v0.6.1002

func (m *Manifest) PersonaFile() string

PersonaFile returns the persona's file in the archive; "" when the release ships no persona.

func (*Manifest) ShippedPacks

func (m *Manifest) ShippedPacks() []string

ShippedPacks returns the names of the packs the release ships, sorted.

func (*Manifest) Subagents added in v0.6.1002

func (m *Manifest) Subagents() []AgentDependency

Subagents returns the release's subagents: its dependencies.agents when it supports the persistent mode, nil otherwise, where the list stays informational. The slice is the caller's own.

func (*Manifest) SupportedModes

func (m *Manifest) SupportedModes() []Mode

SupportedModes returns the run modes the release supports, for either schema major: v2 returns Modes; v1 maps skill and prompt-agent to autonomous and the withdrawn mcp-server kind to nothing.

func (*Manifest) Supports

func (m *Manifest) Supports(mode Mode) bool

Supports reports whether the release can run in mode.

func (*Manifest) TakesKind

func (m *Manifest) TakesKind(k InputKind) bool

TakesKind reports whether the release takes files of kind k: it declares k or any, or declares no kinds at all.

func (*Manifest) TakesKinds

func (m *Manifest) TakesKinds() []InputKind

TakesKinds returns the kinds of file the release takes: its declared kinds, or [any] when it declares none. The slice is the caller's own.

type Mode

type Mode string

Mode is a run mode a release supports. A release declares the non-empty set it supports; a run happens in exactly one.

const (
	// ModeAutonomous runs from the source files (optionally after intake
	// questions and MCP profile authentication), writes its output and
	// receipts, and ends.
	ModeAutonomous Mode = "autonomous"
	// ModeInteractive starts from the same plan and controls, but the run is
	// a conversation with the user in the CLI TUI or the desktop.
	ModeInteractive Mode = "interactive"
	// ModePersistent is an agent the runner keeps between sessions: the
	// agent's conversation and files outlive each start and stop. A
	// persistent release may declare capabilities.persistent, a persona
	// and subagents (persistent.go).
	ModePersistent Mode = "persistent"
)

Run modes (closed set).

func (Mode) Valid

func (m Mode) Valid() bool

Valid reports whether m is a known mode.

type Network

type Network struct {
	// Egress declares outbound network access.
	Egress Egress `yaml:"egress,omitempty" json:"egress,omitempty"`
}

Network groups network capabilities (currently egress only).

type Persistent added in v0.6.1002

type Persistent struct {
	// Clock gives the agent the time on each turn, its own tasks and the
	// heartbeat that fires them.
	Clock bool `yaml:"clock,omitempty" json:"clock,omitempty"`
	// Memory gives the agent a memory wiki on its own volume, seeded from
	// the archive's memory/ folder, with compaction and recall.
	Memory bool `yaml:"memory,omitempty" json:"memory,omitempty"`
	// Skills gives the agent the archive's skills/ folder and the skills
	// the person adds.
	Skills bool `yaml:"skills,omitempty" json:"skills,omitempty"`
	// Secrets names the stored secrets the person may keep for the agent
	// in their keychain, by environment variable name.
	Secrets []string `yaml:"secrets,omitempty" json:"secrets,omitempty"`
	// SelfConfigure lets the agent change its own name and persona.
	SelfConfigure bool `yaml:"selfConfigure,omitempty" json:"selfConfigure,omitempty"`
	// Calendars lets the agent read the calendar feeds the person adds.
	Calendars bool `yaml:"calendars,omitempty" json:"calendars,omitempty"`
	// Meetings lets the agent take meeting notes the person arms.
	Meetings bool `yaml:"meetings,omitempty" json:"meetings,omitempty"`
	// Mail names the mail providers the agent may reach once the person
	// signs in, from MailProviderNames.
	Mail []string `yaml:"mail,omitempty" json:"mail,omitempty"`
	// ImageServers names the servers the runner runs from its own pinned
	// images that the agent may use once the person signs in, from
	// ImageServerNames.
	ImageServers []string `yaml:"imageServers,omitempty" json:"imageServers,omitempty"`
	// Coder gives the agent the coding toolchain: any program in the
	// runner's coding image, open web egress for its commands, a public
	// browser, a development host, ports, and git host accounts.
	Coder bool `yaml:"coder,omitempty" json:"coder,omitempty"`
	// Web gives the agent the web tools, web_search and web_fetch.
	Web bool `yaml:"web,omitempty" json:"web,omitempty"`
	// Helper gives the agent Agentry's helper tools: search the registry,
	// show, install and run QuickAgents, read their results, list what is
	// installed, keep schedules, open settings and read the docs. Each
	// install, schedule change and first run of a new version is still
	// the person's to agree to.
	Helper bool `yaml:"helper,omitempty" json:"helper,omitempty"`
	// Review gives the agent AI Review with the person's own key.
	Review bool `yaml:"review,omitempty" json:"review,omitempty"`
}

Persistent is capabilities.persistent (v2, V16). Every field is off unless declared.

func (*Persistent) Declares added in v0.6.1002

func (p *Persistent) Declares(key string) bool

Declares reports whether p declares key, one of the keys of PersistentCapabilities; a list key is declared when it names anything.

func (*Persistent) Keys added in v0.6.1002

func (p *Persistent) Keys() []string

Keys returns the keys p declares, in consent order; nil for none.

type PersistentCapability added in v0.6.1002

type PersistentCapability struct {
	// Key is the key as written in agent.yaml.
	Key string
	// Words say what the key gives the agent, for a person.
	Words string
}

PersistentCapability is one key of capabilities.persistent and what it gives, in the words consent and the report use.

func PersistentCapabilities added in v0.6.1002

func PersistentCapabilities() []PersistentCapability

PersistentCapabilities returns every key capabilities.persistent can declare, with its words, in consent order. The slice is the caller's own.

type Persona added in v0.6.1002

type Persona struct {
	// Name is the agent's name, shown to the person: one plain line of at
	// most MaxPersonaNameBytes.
	Name string `yaml:"name" json:"name"`
	// File is the persona's text in the archive, at most
	// MaxPersonaFileBytes; empty means DefaultPersonaFile.
	File string `yaml:"file,omitempty" json:"file,omitempty"`
	// Editable lets the person replace the persona's text; nil means
	// true. A locked persona can still be renamed.
	Editable *bool `yaml:"editable,omitempty" json:"editable,omitempty"`
}

Persona is the name and the text a persistent agent takes on (v2, V17). The text is a file in the archive, read by the scanners as they read the instruction; a tool it calls for needs its grant as one the instruction calls for does.

func (*Persona) IsEditable added in v0.6.1002

func (p *Persona) IsEditable() bool

IsEditable reports whether the person may replace the persona's text.

type Publish

type Publish struct {
	// Include is the archive ALLOWLIST of glob patterns; the archive
	// contains nothing else. Segments use path.Match syntax and the whole
	// segment "**" matches any number of segments (V4).
	Include []string `yaml:"include" json:"include"`
	// Channel is stable or beta; empty means stable.
	Channel Channel `yaml:"channel,omitempty" json:"channel,omitempty"`
}

Publish controls what enters the release archive and on which channel.

type Quotas

type Quotas struct {
	// MaxArchiveBytes caps the total size of the resolved include set.
	MaxArchiveBytes int64
	// MaxFiles caps the number of files in the resolved include set.
	MaxFiles int
	// MaxFileBytes caps each non-image file.
	MaxFileBytes int64
	// MaxImageFileBytes caps each image file (recognized by extension).
	MaxImageFileBytes int64
	// MaxTextBytes caps the total size of the text files
	// (FileInfo.IsText) in the resolved include set: the
	// instruction-file total, at most 1 MB of the prose S3/S4/S5 read
	// in full. Zero disables the check.
	MaxTextBytes int64
}

Quotas are the archive quotas checked by V8. The zero value is not meaningful; use DefaultQuotas and override fields per org entitlements.

func DefaultQuotas

func DefaultQuotas() Quotas

DefaultQuotas returns the default quotas: 10 MiB archive, 2000 files, 2 MiB per file, 5 MiB per image, 1 MiB of text in total.

type Ref

type Ref struct {
	Namespace string
	Name      string
	Range     string // "" = latest on channel
	Channel   string // stable | beta (from @beta shorthand or explicit param)
}

Ref is a parsed "ns/name[@range]" reference — the form the CLI, the resolve API, and install snippets all speak.

func ParseRef

func ParseRef(ref string) (Ref, error)

ParseRef parses "ns/name", "ns/name@^1.2", "ns/name@1.2.3", "ns/name@beta".

type Rule

type Rule struct {
	// ID is the rule id an Issue reports, such as "V1".
	ID string
	// Title says what the rule checks.
	Title string
}

Rule is one validation rule: the id an Issue carries and what the rule checks, in a phrase.

func Rules

func Rules() []Rule

Rules returns the rules Validate and ValidateInContext can report, in order, so a client can say which rules it ran without hard-coding the range. The slice is the caller's own.

type Runtime

type Runtime struct {
	// Models are free-form model hint patterns (informational).
	Models []string `yaml:"models,omitempty" json:"models,omitempty"`
	// Interfaces lists the install targets that may be emitted; each
	// must be one of InterfaceClaudeSkill, InterfaceMCP,
	// InterfaceAgentsMD.
	Interfaces []string `yaml:"interfaces,omitempty" json:"interfaces,omitempty"`
}

Runtime carries informational runtime hints.

type Severity

type Severity int

Severity classifies a validation Issue.

const (
	// SeverityError blocks publication.
	SeverityError Severity = iota
	// SeverityWarning is surfaced (and may be policy-gated, e.g. "*"
	// egress) but does not by itself block publication.
	SeverityWarning
)

Issue severities.

func (Severity) String

func (s Severity) String() string

String returns "error" or "warning".

type ShippedKnowledge

type ShippedKnowledge struct {
	// Name is the pack's name and its directory under knowledge/.
	Name string `yaml:"name" json:"name"`
}

ShippedKnowledge is one pack a release ships.

type Transport

type Transport string

Transport is an MCP entrypoint transport.

const (
	// TransportStdio runs the server over stdin/stdout.
	TransportStdio Transport = "stdio"
	// TransportHTTP runs the server over HTTP.
	TransportHTTP Transport = "http"
)

MCP transports (closed set).

Jump to

Keyboard shortcuts

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