manifest

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Oct 27, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Package manifest loads and validates arvel.json, the manifest of an Arvel plugin (docs/PROTOCOL.md §3.2, §4, §14.1, §16).

Index

Constants

View Source
const MaxInstructionsSize = 16 * 1024

MaxInstructionsSize is the largest role instruction file (PROTOCOL §16.2).

Variables

This section is empty.

Functions

func HasErrors

func HasErrors(ps []Problem) bool

HasErrors reports whether any problem has error severity.

func Platforms

func Platforms() []string

Platforms returns the six os-arch keys every official plugin supports.

Types

type BranchMode

type BranchMode string

BranchMode is the default branch mode of a task type (PROTOCOL §16.3).

const (
	BranchNew      BranchMode = "new"
	BranchContinue BranchMode = "continue"
	BranchView     BranchMode = "view"
	BranchAsk      BranchMode = "ask"
)

func AllBranchModes

func AllBranchModes() []BranchMode

AllBranchModes returns every defined BranchMode value in protocol order.

func (BranchMode) Valid

func (v BranchMode) Valid() bool

Valid reports whether v is a defined BranchMode value.

type Capabilities

type Capabilities struct {
	Usage        string              `json:"usage,omitempty"`
	Subagents    bool                `json:"subagents,omitempty"`
	Resume       bool                `json:"resume,omitempty"`
	ModelSwitch  string              `json:"modelSwitch,omitempty"`
	EffortSwitch string              `json:"effortSwitch,omitempty"`
	Router       *RouterCapabilities `json:"router,omitempty"`
}

Capabilities are static hints for the UI.

type ConfigProperty

type ConfigProperty struct {
	Type        string   `json:"type"`
	Title       string   `json:"title,omitempty"`
	Description string   `json:"description,omitempty"`
	Default     any      `json:"default,omitempty"`
	Enum        []string `json:"enum,omitempty"`
	Pattern     string   `json:"pattern,omitempty"`
	Minimum     *int64   `json:"minimum,omitempty"`
	Maximum     *int64   `json:"maximum,omitempty"`
}

ConfigProperty is one form field: boolean, string or integer.

type ConfigSchema

type ConfigSchema struct {
	Type        string                    `json:"type,omitempty"`
	Title       string                    `json:"title,omitempty"`
	Description string                    `json:"description,omitempty"`
	Properties  map[string]ConfigProperty `json:"properties,omitempty"`
}

ConfigSchema is the JSON Schema subset of a connection's settings form.

type Connection

type Connection struct {
	Kind        string           `json:"kind"`
	Label       string           `json:"label"`
	Billing     protocol.Billing `json:"billing"`
	Description string           `json:"description,omitempty"`
	Config      ConfigSchema     `json:"config,omitzero"`
	Secrets     []Secret         `json:"secrets,omitempty"`
}

Connection is one connection kind.

type Contributes

type Contributes struct {
	Roles      []RoleSpec      `json:"roles,omitempty"`
	TaskTypes  []TaskTypeSpec  `json:"taskTypes,omitempty"`
	MCPServers []MCPServerSpec `json:"mcpServers,omitempty"`
	Skills     []SkillSpec     `json:"skills,omitempty"`
}

Contributes is the "contributes" block of a team or integration plugin (PROTOCOL §16.1).

type Entry

type Entry struct {
	Asset   string   `json:"asset,omitempty"`
	Bin     string   `json:"bin,omitempty"`
	Command []string `json:"command,omitempty"`
}

Entry is how to start the plugin on one platform: a release asset and the binary inside it, or a command (generic ACP agent).

type EntrySpec

type EntrySpec struct {
	Platforms map[string]Entry
	Command   []string
}

EntrySpec is the "entry" member: a map from "os-arch" to a release asset, or a single command entry that is valid on every platform.

func (EntrySpec) IsCommand

func (e EntrySpec) IsCommand() bool

IsCommand reports whether the entry is a command entry.

func (EntrySpec) MarshalJSON

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

MarshalJSON writes the shape that was loaded.

func (*EntrySpec) UnmarshalJSON

func (e *EntrySpec) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts both shapes of "entry".

type Localized

type Localized map[string]string

Localized maps a language tag to a text. "en" is required and "ru" optional (PROTOCOL §16.5).

type MCPServerSpec

type MCPServerSpec struct {
	Name    string   `json:"name"`
	Command []string `json:"command,omitempty"`
	URL     string   `json:"url,omitempty"`
	Tools   []string `json:"tools,omitempty"`
}

MCPServerSpec is an MCP server of an integration plugin (PROTOCOL §16.4): either a stdio server started from the plugin's own binary ("{bin}" first in Command) or an HTTP URL.

type Manifest

type Manifest struct {
	Schema       string           `json:"$schema,omitempty"`
	ID           string           `json:"id"`
	Name         string           `json:"name"`
	Type         PluginType       `json:"type"`
	Version      string           `json:"version"`
	PluginAPI    string           `json:"pluginApi"`
	Description  string           `json:"description,omitempty"`
	Homepage     string           `json:"homepage,omitempty"`
	License      string           `json:"license,omitempty"`
	Entry        EntrySpec        `json:"entry,omitzero"`
	Checksums    string           `json:"checksums,omitempty"`
	Requires     []Requirement    `json:"requires,omitempty"`
	Permissions  Permissions      `json:"permissions"`
	Sandbox      *ManifestSandbox `json:"sandbox,omitempty"`
	Connections  []Connection     `json:"connections,omitempty"`
	Capabilities Capabilities     `json:"capabilities,omitzero"`
	Contributes  *Contributes     `json:"contributes,omitempty"`
	// contains filtered or unexported fields
}

Manifest mirrors arvel.json. Unknown fields are ignored when loading.

func Load

func Load(r io.Reader) (*Manifest, error)

Load decodes a manifest from r. It does not validate it; call Validate.

func LoadFile

func LoadFile(path string) (*Manifest, error)

LoadFile reads a manifest from a file.

func (*Manifest) EntryFor

func (m *Manifest) EntryFor(goos, goarch string) (Entry, bool)

EntryFor returns the entry to use on goos/goarch. A command entry is valid on every platform.

func (*Manifest) Validate

func (m *Manifest) Validate() []Problem

Validate checks the manifest against the JSON Schema and the semantic rules of the protocol, treating it as a third-party plugin. See ValidateWith.

func (*Manifest) ValidateFiles

func (m *Manifest) ValidateFiles(dir string) []Problem

ValidateFiles checks the files a team or integration manifest points at, in the unpacked package directory dir: every role instruction file exists, is a regular file and is at most MaxInstructionsSize bytes, and every skill folder holds a SKILL.md (PROTOCOL §16.2, §16.4, §16.5). Paths that Validate already rejected are skipped. Files are never read, only inspected; a path that escapes dir (also through a symbolic link) is a problem.

func (*Manifest) ValidateWith

func (m *Manifest) ValidateWith(opts Options) []Problem

ValidateWith returns schema problems first (sorted), then semantic problems in a fixed order. The result is deterministic for identical input.

The schema is checked against the document given to Load, so edits made to the struct afterwards are seen by the semantic rules only. Validate a manifest you built by hand (without Load) and the struct is marshalled first.

type ManifestSandbox

type ManifestSandbox = protocol.ManifestSandbox

ManifestSandbox is the "sandbox" block (PROTOCOL §3.2, §15).

type Options

type Options struct {
	// Official makes a missing platform an error. Third-party plugins get a
	// warning, because only official plugins must ship all six platforms.
	Official bool
}

Options tunes Validate.

type PermissionDiff

type PermissionDiff struct {
	AddedSpawn       []string
	AddedNetwork     []string
	AddedVendorHosts []string
	AddedVendorPaths protocol.VendorPaths
	KeychainAdded    bool
	FilesChanged     bool
	OldFiles         string
	NewFiles         string
}

PermissionDiff lists what an updated manifest asks for beyond the old one. Removals are not reported: the host only warns about increases.

func DiffPermissions

func DiffPermissions(old, new Permissions, oldSandbox, newSandbox *ManifestSandbox) PermissionDiff

DiffPermissions compares the permissions and sandbox blocks of two versions of a manifest. A nil sandbox means nothing was allowed.

func (PermissionDiff) AsksForMore

func (d PermissionDiff) AsksForMore() bool

AsksForMore reports whether the update needs the user's attention.

type Permissions

type Permissions struct {
	Spawn   []string `json:"spawn,omitempty"`
	Network []string `json:"network,omitempty"`
	Files   string   `json:"files,omitempty"`
}

Permissions is what the plugin may do (PROTOCOL §3.2).

type Placement

type Placement struct {
	After  string `json:"after,omitempty"`
	OnCall bool   `json:"onCall,omitempty"`
}

Placement says where a plugin role runs: right after a slot, or only on call. Exactly one of the two is set.

type PluginType

type PluginType string

PluginType is the "type" of a manifest.

const (
	TypeProvider    PluginType = "provider"
	TypeRouter      PluginType = "router"
	TypeTeam        PluginType = "team"
	TypeIntegration PluginType = "integration"
)

func (PluginType) Declarative

func (t PluginType) Declarative() bool

Declarative reports whether the plugin is data only (PROTOCOL §16): a team or integration plugin.

func (PluginType) Valid

func (t PluginType) Valid() bool

Valid reports whether t is a plugin type this SDK handles.

type Problem

type Problem struct {
	Severity Severity `json:"severity"`
	Path     string   `json:"path"`
	Code     string   `json:"code"`
	Message  string   `json:"message"`
}

Problem is one finding of Validate. Path is a JSON pointer into arvel.json ("/connections/1/kind"), Code a stable slug, Message text for people.

func (Problem) String

func (p Problem) String() string

String formats the problem for terminals.

type Requirement

type Requirement struct {
	Binary      string            `json:"binary"`
	MinVersion  string            `json:"minVersion,omitempty"`
	VersionArgs []string          `json:"versionArgs,omitempty"`
	Install     map[string]string `json:"install,omitempty"`
}

Requirement is an external program the plugin drives.

type ResultMode

type ResultMode string

ResultMode is what a task type produces (PROTOCOL §16.3).

const (
	ResultCode     ResultMode = "code"
	ResultReport   ResultMode = "report"
	ResultSubtasks ResultMode = "subtasks"
)

func AllResultModes

func AllResultModes() []ResultMode

AllResultModes returns every defined ResultMode value in protocol order.

func (ResultMode) Valid

func (v ResultMode) Valid() bool

Valid reports whether v is a defined ResultMode value.

type RoleSpec

type RoleSpec struct {
	ID           string                `json:"id"`
	Name         Localized             `json:"name"`
	Description  Localized             `json:"description"`
	Kind         protocol.RoleKind     `json:"kind"`
	Placement    Placement             `json:"placement"`
	Instructions Localized             `json:"instructions"` // language -> Markdown file in the package
	Permissions  *protocol.Permissions `json:"permissions,omitempty"`
	Icon         string                `json:"icon,omitempty"`
}

RoleSpec is a role added by a plugin (PROTOCOL §16.2). The host stores its id as "<pluginId>:<id>".

type RouterCapabilities

type RouterCapabilities struct {
	Features     []string `json:"features,omitempty"`
	MaxLatencyMs int      `json:"maxLatencyMs,omitempty"`
}

RouterCapabilities are the router hints of a manifest.

type Secret

type Secret struct {
	ID       string `json:"id"`
	Label    string `json:"label"`
	Pattern  string `json:"pattern,omitempty"`
	Required bool   `json:"required,omitempty"`
}

Secret is a value the host keeps in the keychain and passes in initialize.

type Severity

type Severity string

Severity of a Problem.

const (
	SeverityError   Severity = "error"
	SeverityWarning Severity = "warning"
)

type SkillSpec

type SkillSpec struct {
	Name string `json:"name"`
	Path string `json:"path"`
}

SkillSpec is an Agent Skills folder inside the release archive.

type TaskTypeSpec

type TaskTypeSpec struct {
	ID          string                        `json:"id"`
	Name        Localized                     `json:"name"`
	Description Localized                     `json:"description"`
	Roles       map[string]protocol.SlotState `json:"roles"`
	Branch      BranchMode                    `json:"branch"`
	Result      ResultMode                    `json:"result"`
}

TaskTypeSpec is a task type added by a plugin (PROTOCOL §16.3).

Jump to

Keyboard shortcuts

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