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
- func HasErrors(ps []Problem) bool
- func Platforms() []string
- type BranchMode
- type Capabilities
- type ConfigProperty
- type ConfigSchema
- type Connection
- type Contributes
- type Entry
- type EntrySpec
- type Localized
- type MCPServerSpec
- type Manifest
- type ManifestSandbox
- type Options
- type PermissionDiff
- type Permissions
- type Placement
- type PluginType
- type Problem
- type Requirement
- type ResultMode
- type RoleSpec
- type RouterCapabilities
- type Secret
- type Severity
- type SkillSpec
- type TaskTypeSpec
Constants ¶
const MaxInstructionsSize = 16 * 1024
MaxInstructionsSize is the largest role instruction file (PROTOCOL §16.2).
Variables ¶
This section is empty.
Functions ¶
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 ¶
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) MarshalJSON ¶
MarshalJSON writes the shape that was loaded.
func (*EntrySpec) UnmarshalJSON ¶
UnmarshalJSON accepts both shapes of "entry".
type Localized ¶
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 (*Manifest) EntryFor ¶
EntryFor returns the entry to use on goos/goarch. A command entry is valid on every platform.
func (*Manifest) Validate ¶
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 ¶
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 ¶
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.
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 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).