protocol

package
v0.1.1 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: 12 Imported by: 0

Documentation

Overview

Package protocol defines the wire types of the Arvel Provider Protocol v1 (docs/PROTOCOL.md): the "_meta.arvel" structures, the "_arvel/*" request and result bodies, the error model and the router types.

JSON names are copied from the protocol. Decoding ignores unknown fields (PROTOCOL §12). The package imports only the standard library.

Index

Constants

View Source
const (
	CodeParseError     = -32700
	CodeInvalidRequest = -32600
	CodeMethodNotFound = -32601
	CodeInvalidParams  = -32602
	CodeInternalError  = -32603
	// CodeServerError is the ACP code carried by every Arvel error.
	CodeServerError = -32000
	// CodeBusy is used for the "busy" error (PROTOCOL §8).
	CodeBusy = -32002
)

JSON-RPC and ACP numeric error codes.

View Source
const (
	RoleLead      = "lead"
	RoleArchitect = "architect"
	RoleDeveloper = "developer"
	RoleReviewer  = "reviewer"
	RoleSecurity  = "security"
	RoleTester    = "tester"
	RoleKeeper    = "keeper"
)

Built-in role ids (PROTOCOL §7.1).

View Source
const (
	SlotLeadIntake = "lead_intake"
	SlotArchitect  = "architect"
	SlotDeveloper  = "developer"
	SlotReviewer   = "reviewer"
	SlotSecurity   = "security"
	SlotTester     = "tester"
	SlotLeadAccept = "lead_accept"
)

Slots of the fixed order (PROTOCOL §14.6).

View Source
const (
	TypeSpec     = "spec"
	TypeFeature  = "feature"
	TypeBug      = "bug"
	TypeEdit     = "edit"
	TypeReview   = "review"
	TypeAnalysis = "analysis"
)

Built-in task type ids (PROTOCOL §7.1).

View Source
const (
	MethodStatus        = "_arvel/status"
	MethodModels        = "_arvel/models"
	MethodUsage         = "_arvel/usage"
	MethodUsageUpdated  = "_arvel/usage_updated"
	MethodAction        = "_arvel/action"
	MethodStatusChanged = "_arvel/status_changed"
	MethodShutdown      = "_arvel/shutdown"
	MethodDiscover      = "_arvel/discover"
	MethodRoutePlan     = "_arvel/route/plan"
	MethodRouteMessage  = "_arvel/route/message"
	MethodRouteEffort   = "_arvel/route/effort"
	MethodRouteExplain  = "_arvel/route/explain"
)

Arvel extension methods (PROTOCOL §6, §7.9, §14).

View Source
const (
	MethodInitialize               = "initialize"
	MethodSessionNew               = "session/new"
	MethodSessionLoad              = "session/load"
	MethodSessionPrompt            = "session/prompt"
	MethodSessionCancel            = "session/cancel"
	MethodSessionSetConfigOption   = "session/set_config_option"
	MethodSessionUpdate            = "session/update"
	MethodSessionRequestPermission = "session/request_permission"
)

ACP methods used by the protocol.

View Source
const (
	FeatureStatus       = "status"
	FeatureModels       = "models"
	FeatureUsage        = "usage"
	FeatureActions      = "actions"
	FeatureSubagents    = "subagents"
	FeatureResume       = "resume"
	FeatureSkills       = "skills"
	FeatureDiscover     = "discover"
	FeatureRoutePlan    = "route.plan"
	FeatureRouteMessage = "route.message"
	FeatureRouteEffort  = "route.effort"
	FeatureRouteExplain = "route.explain"
)

Feature names listed in InitResultMeta.Features. "_arvel/interactive" and the feature "interactive" are reserved (PROTOCOL §7.8) and have no constant.

View Source
const MaxRoleDescriptionLen = 300

MaxRoleDescriptionLen is the longest role description the host sends (PROTOCOL §14.2), counted in runes.

View Source
const PluginAPI = "1"

PluginAPI is the major version of the protocol, sent as "pluginApi".

Variables

This section is empty.

Functions

func FeatureMaxParallelSessions

func FeatureMaxParallelSessions(n int) string

FeatureMaxParallelSessions returns the feature string that announces a soft limit of parallel sessions (PROTOCOL §8).

func IsOrderSlot

func IsOrderSlot(s string) bool

IsOrderSlot reports whether s is one of the seven slots of Order.

func MetaFrom

func MetaFrom[T any](meta map[string]any) (T, bool, error)

MetaFrom reads "_meta.arvel" into T. It returns false and no error when the meta map is nil or has no "arvel" member.

func Order

func Order() []string

Order returns the slots of the fixed order, first to last. Each call returns a fresh slice.

func ParseMaxParallelSessions

func ParseMaxParallelSessions(features []string) (int, bool)

ParseMaxParallelSessions returns the first well-formed positive maxParallelSessions value found in features.

func PluginSlot

func PluginSlot(pluginID, roleID string) string

PluginSlot returns the slot (and stored role) id of a role added by a plugin: "<pluginID>:<roleID>" (PROTOCOL §14.3, §16.2).

func WithMeta

func WithMeta(meta map[string]any, v any) map[string]any

WithMeta returns a copy of meta with "arvel" set to v. The argument is not modified and may be nil.

Types

type AccountInfo

type AccountInfo struct {
	Label string `json:"label,omitempty"`
	Plan  string `json:"plan,omitempty"`
}

AccountInfo describes the signed-in account.

type Action

type Action struct {
	ID    string     `json:"id"`
	Label string     `json:"label"`
	Kind  ActionKind `json:"kind"`
}

Action is something the user can run from the status card.

type ActionKind

type ActionKind string

ActionKind is the kind of an action or its result (PROTOCOL §6.4).

const (
	ActionKindTerminal ActionKind = "terminal"
	ActionKindURL      ActionKind = "url"
	ActionKindDone     ActionKind = "done"
)

func AllActionKinds

func AllActionKinds() []ActionKind

AllActionKinds returns every defined ActionKind value in protocol order.

func (ActionKind) Valid

func (v ActionKind) Valid() bool

Valid reports whether v is a defined ActionKind value.

type ActionParams

type ActionParams struct {
	ID string `json:"id"`
}

ActionParams are the params of _arvel/action.

type ActionResult

type ActionResult struct {
	Kind            ActionKind        `json:"kind"`
	Command         []string          `json:"command,omitempty"`
	Env             map[string]string `json:"env,omitempty"`
	Explain         string            `json:"explain,omitempty"`
	URL             string            `json:"url,omitempty"`
	AwaitCompletion bool              `json:"awaitCompletion,omitempty"`
	Message         string            `json:"message,omitempty"`
}

ActionResult is the result of _arvel/action, tagged by Kind.

func (ActionResult) Validate

func (a ActionResult) Validate() error

Validate checks the fields required by the result kind.

type Billing

type Billing string

Billing is the billing mode of a connection or model (PROTOCOL §4).

const (
	BillingSubscription Billing = "subscription"
	BillingAPI          Billing = "api"
	BillingMixed        Billing = "mixed"
	BillingUnknown      Billing = "unknown"
)

func AllBillings

func AllBillings() []Billing

AllBillings returns every defined Billing value in protocol order.

func (Billing) Valid

func (v Billing) Valid() bool

Valid reports whether v is a defined Billing value.

type BinaryInfo

type BinaryInfo struct {
	Name    string `json:"name"`
	Path    string `json:"path,omitempty"`
	Version string `json:"version,omitempty"`
}

BinaryInfo describes the vendor binary found on the machine.

type Budget

type Budget struct {
	MaxTurns int     `json:"maxTurns,omitempty"`
	MaxUSD   float64 `json:"maxUsd,omitempty"`
}

Budget limits a session; zero means not set.

type CommandPolicy

type CommandPolicy struct {
	Default PermissionLevel `json:"default"`
	Allow   []string        `json:"allow,omitempty"`
	Deny    []string        `json:"deny,omitempty"`
}

CommandPolicy is the policy for shell commands.

type ConnectionInfo

type ConnectionInfo struct {
	ID      string            `json:"id"`
	Kind    string            `json:"kind"`
	Config  map[string]any    `json:"config,omitempty"`
	Secrets map[string]string `json:"secrets,omitempty"`
}

ConnectionInfo describes the connection instance a process serves. Secrets are delivered here and nowhere else; String, GoString and LogValue print the secret names only, never the values.

func (ConnectionInfo) GoString

func (c ConnectionInfo) GoString() string

GoString keeps %#v from leaking secrets.

func (ConnectionInfo) LogValue

func (c ConnectionInfo) LogValue() slog.Value

LogValue implements slog.LogValuer without secret values.

func (ConnectionInfo) String

func (c ConnectionInfo) String() string

String prints the connection without secret values.

type DiscoverKind

type DiscoverKind string

DiscoverKind is a kind of discoverable item (PROTOCOL §7.9).

const (
	DiscoverKindMCP    DiscoverKind = "mcp"
	DiscoverKindSkills DiscoverKind = "skills"
)

func AllDiscoverKinds

func AllDiscoverKinds() []DiscoverKind

AllDiscoverKinds returns every defined DiscoverKind value in protocol order.

func (DiscoverKind) Valid

func (v DiscoverKind) Valid() bool

Valid reports whether v is a defined DiscoverKind value.

type DiscoverParams

type DiscoverParams struct {
	Kinds    []DiscoverKind `json:"kinds"`
	Projects []string       `json:"projects,omitempty"`
}

DiscoverParams are the params of _arvel/discover (PROTOCOL §7.9).

type DiscoverResult

type DiscoverResult struct {
	McpServers []DiscoveredMcp   `json:"mcpServers"`
	Skills     []DiscoveredSkill `json:"skills"`
}

DiscoverResult lists the MCP servers and skills found. It cannot carry a secret value: env and headers hold SecretField markers only.

func (DiscoverResult) Validate

func (r DiscoverResult) Validate() error

Validate checks names, scopes, transports and secret markers.

type DiscoverScope

type DiscoverScope string

DiscoverScope is the scope of a discovered item (PROTOCOL §7.9).

const (
	DiscoverScopeUser    DiscoverScope = "user"
	DiscoverScopeProject DiscoverScope = "project"
)

func AllDiscoverScopes

func AllDiscoverScopes() []DiscoverScope

AllDiscoverScopes returns every defined DiscoverScope value in protocol order.

func (DiscoverScope) Valid

func (v DiscoverScope) Valid() bool

Valid reports whether v is a defined DiscoverScope value.

type DiscoveredMcp

type DiscoveredMcp struct {
	Name      string                 `json:"name"`
	Scope     DiscoverScope          `json:"scope"`
	Project   string                 `json:"project,omitempty"`
	Source    string                 `json:"source,omitempty"`
	Transport McpTransport           `json:"transport"`
	Command   []string               `json:"command,omitempty"`
	URL       string                 `json:"url,omitempty"`
	Env       map[string]SecretField `json:"env,omitempty"`
	Headers   map[string]SecretField `json:"headers,omitempty"`
}

DiscoveredMcp is an MCP server definition found in the vendor configuration.

type DiscoveredSkill

type DiscoveredSkill struct {
	Name   string        `json:"name"`
	Scope  DiscoverScope `json:"scope"`
	Source string        `json:"source,omitempty"`
	Path   string        `json:"path"`
}

DiscoveredSkill is a skill folder found on the machine.

type Effort

type Effort string

Effort is a reasoning effort level (PROTOCOL §6.2).

const (
	EffortLow    Effort = "low"
	EffortMedium Effort = "medium"
	EffortHigh   Effort = "high"
	EffortXHigh  Effort = "xhigh"
	EffortMax    Effort = "max"
)

func AllEfforts

func AllEfforts() []Effort

AllEfforts returns every defined Effort value in protocol order.

func (Effort) Valid

func (v Effort) Valid() bool

Valid reports whether v is a defined Effort value.

type ErrorCode

type ErrorCode string

ErrorCode is the machine-readable Arvel error code (PROTOCOL §9).

const (
	ErrRateLimited      ErrorCode = "rate_limited"
	ErrAuthRequired     ErrorCode = "auth_required"
	ErrBinaryMissing    ErrorCode = "binary_missing"
	ErrBinaryOutdated   ErrorCode = "binary_outdated"
	ErrModelUnavailable ErrorCode = "model_unavailable"
	ErrBudgetExceeded   ErrorCode = "budget_exceeded"
	ErrContextOverflow  ErrorCode = "context_overflow"
	ErrOverloaded       ErrorCode = "overloaded"
	ErrBusy             ErrorCode = "busy"
	ErrProviderError    ErrorCode = "provider_error"
	ErrInternal         ErrorCode = "internal"
)

func AllErrorCodes

func AllErrorCodes() []ErrorCode

AllErrorCodes returns every defined ErrorCode in protocol order.

func (ErrorCode) RPCCode

func (c ErrorCode) RPCCode() int

RPCCode returns the JSON-RPC numeric code used for c.

func (ErrorCode) Valid

func (c ErrorCode) Valid() bool

Valid reports whether c is a defined ErrorCode.

type ErrorData

type ErrorData struct {
	Code              ErrorCode `json:"code"`
	Message           string    `json:"message,omitempty"`
	Retryable         bool      `json:"retryable,omitempty"`
	ResetsAt          time.Time `json:"resetsAt,omitzero"`
	WindowID          string    `json:"windowId,omitempty"`
	MinVersion        string    `json:"minVersion,omitempty"`
	FoundVersion      string    `json:"foundVersion,omitempty"`
	Model             string    `json:"model,omitempty"`
	Limit             string    `json:"limit,omitempty"` // "turns" or "usd"
	RetryAfterSeconds int       `json:"retryAfterSeconds,omitempty"`
	VendorCode        string    `json:"vendorCode,omitempty"`
}

ErrorData is the body of "error.data.arvel" and of "_meta.arvel.stop".

func (ErrorData) Validate

func (d ErrorData) Validate() error

Validate checks that the code is defined and that the fields required for it by PROTOCOL §9 are present.

type ExplainLine

type ExplainLine struct {
	Text  string  `json:"text"`
	Value float64 `json:"value"`
}

ExplainLine is one line of a route explanation.

type InitMeta

type InitMeta struct {
	PluginAPI  string         `json:"pluginApi"`
	Connection ConnectionInfo `json:"connection"`
	DataDir    string         `json:"dataDir"`
	Locale     string         `json:"locale,omitempty"`
	Platform   PlatformInfo   `json:"platform"`
	Sandbox    *SandboxInfo   `json:"sandbox,omitempty"`
}

InitMeta is "_meta.arvel" of the initialize request (PROTOCOL §5.1).

type InitResultMeta

type InitResultMeta struct {
	PluginAPI        string      `json:"pluginApi"`
	Features         []string    `json:"features"`
	InstructionFiles []string    `json:"instructionFiles,omitempty"`
	Skills           *SkillsInfo `json:"skills,omitempty"`
}

InitResultMeta is "_meta.arvel" of the initialize response.

func (InitResultMeta) Has

func (r InitResultMeta) Has(feature string) bool

Has reports whether feature is announced.

type Issue

type Issue struct {
	Kind    IssueKind
	Path    string
	Message string
}

Issue is one violation (or, for IssueIgnored, one ignored decision). Path looks like "roles[2].slot".

type IssueKind

type IssueKind string

IssueKind classifies one violation found in a router result.

const (
	IssueUnknownID       IssueKind = "unknown_id"
	IssueDuplicate       IssueKind = "duplicate"
	IssueConfidenceRange IssueKind = "confidence_range"
	IssueNotInLevels     IssueKind = "not_in_levels"
	IssueNotFinite       IssueKind = "not_finite"
	IssueEmpty           IssueKind = "empty"
	IssueIgnored         IssueKind = "ignored"
)

type MCPPolicy

type MCPPolicy struct {
	Default PermissionLevel            `json:"default"`
	Tools   map[string]PermissionLevel `json:"tools,omitempty"`
}

MCPPolicy is the policy for MCP tools.

type ManifestSandbox

type ManifestSandbox struct {
	VendorPaths   VendorPaths `json:"vendorPaths,omitempty"`
	VendorHosts   []string    `json:"vendorHosts,omitempty"`
	MacOSKeychain bool        `json:"macosKeychain,omitempty"`
}

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

type McpTransport

type McpTransport string

McpTransport is the transport of a discovered MCP server (PROTOCOL §7.9).

const (
	McpTransportStdio McpTransport = "stdio"
	McpTransportHTTP  McpTransport = "http"
	McpTransportSSE   McpTransport = "sse"
)

func AllMcpTransports

func AllMcpTransports() []McpTransport

AllMcpTransports returns every defined McpTransport value in protocol order.

func (McpTransport) Valid

func (v McpTransport) Valid() bool

Valid reports whether v is a defined McpTransport value.

type Model

type Model struct {
	ID             string   `json:"id"`
	Label          string   `json:"label"`
	Description    string   `json:"description,omitempty"`
	Aliases        []string `json:"aliases,omitempty"`
	Efforts        []Effort `json:"efforts"`
	DefaultEffort  Effort   `json:"defaultEffort,omitempty"`
	ContextWindow  int      `json:"contextWindow,omitempty"`
	Inputs         []string `json:"inputs,omitempty"`
	Billing        Billing  `json:"billing,omitempty"`
	RecommendedFor []string `json:"recommendedFor,omitempty"`
	Hidden         bool     `json:"hidden"`
}

Model is one model offered by a connection (PROTOCOL §6.2).

func (Model) MarshalJSON

func (m Model) MarshalJSON() ([]byte, error)

MarshalJSON always writes "efforts" as an array ([] means a fixed effort).

type ModelsParams

type ModelsParams struct {
	Refresh bool `json:"refresh"`
}

ModelsParams are the params of _arvel/models.

type ModelsResult

type ModelsResult struct {
	Models  []Model `json:"models"`
	Default string  `json:"default"`
}

ModelsResult is the result of _arvel/models.

func (ModelsResult) Validate

func (r ModelsResult) Validate() error

Validate checks the shape rules of PROTOCOL §6.2: unique ids, efforts inside the vocabulary, defaults that exist.

type PermissionCategory

type PermissionCategory string

PermissionCategory is the category of a permission request (PROTOCOL §7.3).

const (
	PermissionCategoryCommand PermissionCategory = "command"
	PermissionCategoryEdit    PermissionCategory = "edit"
	PermissionCategoryRead    PermissionCategory = "read"
	PermissionCategoryNetwork PermissionCategory = "network"
	PermissionCategoryMCP     PermissionCategory = "mcp"
	PermissionCategoryOther   PermissionCategory = "other"
)

func AllPermissionCategories

func AllPermissionCategories() []PermissionCategory

AllPermissionCategories returns every defined PermissionCategory value in protocol order.

func (PermissionCategory) Valid

func (v PermissionCategory) Valid() bool

Valid reports whether v is a defined PermissionCategory value.

type PermissionLevel

type PermissionLevel string

PermissionLevel is a role permission level (PROTOCOL §7.1).

const (
	PermissionLevelAllow PermissionLevel = "allow"
	PermissionLevelAsk   PermissionLevel = "ask"
	PermissionLevelDeny  PermissionLevel = "deny"
)

func AllPermissionLevels

func AllPermissionLevels() []PermissionLevel

AllPermissionLevels returns every defined PermissionLevel value in protocol order.

func (PermissionLevel) Valid

func (v PermissionLevel) Valid() bool

Valid reports whether v is a defined PermissionLevel value.

type PermissionMeta

type PermissionMeta struct {
	Category PermissionCategory `json:"category"`
	Command  string             `json:"command,omitempty"`
	Paths    []string           `json:"paths,omitempty"`
	Hosts    []string           `json:"hosts,omitempty"`
	Reason   string             `json:"reason,omitempty"`
}

PermissionMeta is "_meta.arvel" of session/request_permission (PROTOCOL §7.3).

func (PermissionMeta) Validate

func (p PermissionMeta) Validate() error

Validate checks the category.

type Permissions

type Permissions struct {
	Read     PermissionLevel `json:"read,omitempty"`
	Edit     PermissionLevel `json:"edit,omitempty"`
	Commands *CommandPolicy  `json:"commands,omitempty"`
	Network  PermissionLevel `json:"network,omitempty"`
	MCP      *MCPPolicy      `json:"mcp,omitempty"`
}

Permissions is the role's baseline policy.

type PlatformInfo

type PlatformInfo struct {
	OS     string `json:"os"`
	Arch   string `json:"arch"`
	Remote bool   `json:"remote"`
}

PlatformInfo describes the machine the host runs on.

type RPCError

type RPCError struct {
	Code    int             `json:"code"`
	Message string          `json:"message"`
	Data    json.RawMessage `json:"data,omitempty"`
}

RPCError is a JSON-RPC error object.

func NewError

func NewError(code ErrorCode, msg string, fields map[string]any) *RPCError

NewError builds a JSON-RPC error with the ACP code (-32000, or -32002 for "busy") and "data.arvel" holding the code, the message and fields. The code and message arguments win over same-named keys in fields.

NewError does not redact msg: callers pass text that is already free of secrets (the plugin framework redacts vendor text before it gets here).

func NewMethodNotFound

func NewMethodNotFound(method string) *RPCError

NewMethodNotFound builds the -32601 error for an unknown method.

func (*RPCError) Arvel

func (e *RPCError) Arvel() (ErrorData, bool)

Arvel decodes the "arvel" member of the error data. It reports false when the data is absent or malformed.

func (*RPCError) Error

func (e *RPCError) Error() string

Error implements the error interface.

type RoleDecision

type RoleDecision struct {
	Slot       string  `json:"slot"`
	Include    bool    `json:"include"`
	Confidence float64 `json:"confidence"`
}

RoleDecision is the router's decision about one slot, relative to the chosen type's defaults.

type RoleKind

type RoleKind string

RoleKind is the kind of a role (PROTOCOL §14.2; "read" is the kind of a read-only plugin role, §16.2).

const (
	RoleKindIntake    RoleKind = "intake"
	RoleKindPlan      RoleKind = "plan"
	RoleKindCode      RoleKind = "code"
	RoleKindCheck     RoleKind = "check"
	RoleKindAccept    RoleKind = "accept"
	RoleKindKnowledge RoleKind = "knowledge"
	RoleKindRead      RoleKind = "read"
)

func AllRoleKinds

func AllRoleKinds() []RoleKind

AllRoleKinds returns every defined RoleKind value in protocol order.

func (RoleKind) Valid

func (v RoleKind) Valid() bool

Valid reports whether v is a defined RoleKind value.

type RoleRef

type RoleRef struct {
	ID   string `json:"id"`
	Name string `json:"name,omitempty"`
}

RoleRef names the role a session works for.

type RouteCandidate

type RouteCandidate struct {
	RoleID      string   `json:"roleId"`
	Name        string   `json:"name"`
	Description string   `json:"description,omitempty"`
	Kind        RoleKind `json:"kind"`
}

RouteCandidate is a role that may answer a message.

type RouteEffortParams

type RouteEffortParams struct {
	Text   string   `json:"text"`
	RoleID string   `json:"roleId"`
	Kind   RoleKind `json:"kind"`
	Levels []Effort `json:"levels"`
}

RouteEffortParams are the params of _arvel/route/effort.

type RouteEffortResult

type RouteEffortResult struct {
	Effort     Effort  `json:"effort"`
	Confidence float64 `json:"confidence"`
}

RouteEffortResult is the result of _arvel/route/effort.

func (RouteEffortResult) Validate

func (r RouteEffortResult) Validate(req RouteEffortParams) error

Validate checks the result against the request (PROTOCOL §14.5): the effort is one of the offered levels; confidence is in [0, 1].

type RouteExplainResult

type RouteExplainResult struct {
	Lines []ExplainLine `json:"lines"`
}

RouteExplainResult is the result of _arvel/route/explain.

func (RouteExplainResult) MarshalJSON

func (r RouteExplainResult) MarshalJSON() ([]byte, error)

MarshalJSON always writes "lines" as an array.

func (RouteExplainResult) Validate

Validate checks that every line has text and a finite value (PROTOCOL §14.8). The request is accepted for symmetry with the other results.

type RouteMessageParams

type RouteMessageParams struct {
	Task          RouteTask        `json:"task"`
	Message       string           `json:"message"`
	CurrentRoleID string           `json:"currentRoleId,omitempty"`
	Candidates    []RouteCandidate `json:"candidates"`
}

RouteMessageParams are the params of _arvel/route/message.

type RouteMessageResult

type RouteMessageResult struct {
	RoleID        string             `json:"roleId"`
	Confidence    float64            `json:"confidence"`
	Probabilities map[string]float64 `json:"probabilities,omitempty"`
}

RouteMessageResult is the result of _arvel/route/message.

func (RouteMessageResult) Validate

Validate checks the result against the request (PROTOCOL §14.4): the role and every probability key are candidates; confidences are in [0, 1].

type RoutePlanParams

type RoutePlanParams struct {
	Task  RouteTask   `json:"task"`
	Types []RouteType `json:"types"`
	Roles []RouteRole `json:"roles"`
}

RoutePlanParams are the params of _arvel/route/plan (and route/explain).

func (RoutePlanParams) Validate

func (p RoutePlanParams) Validate() error

Validate checks the request the host builds: unique ids and slots, valid enums and description lengths (PROTOCOL §14.2, §14.3).

type RoutePlanResult

type RoutePlanResult struct {
	Type  *TypeDecision  `json:"type"`
	Roles []RoleDecision `json:"roles"`
}

RoutePlanResult is the result of _arvel/route/plan. A nil Type marshals as null ("no type fits").

func (RoutePlanResult) MarshalJSON

func (r RoutePlanResult) MarshalJSON() ([]byte, error)

MarshalJSON always writes "roles" as an array.

func (RoutePlanResult) Sanitize

Sanitize returns a copy of the result without the decisions the host ignores (PROTOCOL §14.3: auto slots and the lead_accept of a type that has it), and one IssueIgnored per dropped decision. It does not check ids or confidences; call Validate first. Neither the result nor the request is modified.

func (RoutePlanResult) Validate

func (r RoutePlanResult) Validate(req RoutePlanParams) error

Validate checks the result against the request (PROTOCOL §14.3): the type id exists, decisions name slots of the request once each, and confidences are in [0, 1]. Decisions on auto slots and on a type's lead_accept are not violations: the host ignores them (see Sanitize).

type RouteRole

type RouteRole struct {
	Slot        string   `json:"slot"`
	RoleID      string   `json:"roleId"`
	Name        string   `json:"name"`
	Description string   `json:"description,omitempty"`
	Kind        RoleKind `json:"kind"`
}

RouteRole is one role in a place of the fixed order. A role added by a plugin has the slot "<pluginId>:<roleId>".

type RouteTask

type RouteTask struct {
	Title       string   `json:"title"`
	Description string   `json:"description,omitempty"`
	Projects    []string `json:"projects,omitempty"`
	Language    string   `json:"language,omitempty"`
}

RouteTask is the task text the host sends to a router.

type RouteType

type RouteType struct {
	TypeID      string               `json:"typeId"`
	Name        string               `json:"name"`
	Description string               `json:"description,omitempty"`
	Roles       map[string]SlotState `json:"roles,omitempty"`
}

RouteType is a task type the router may choose. Roles maps a slot to its default state in this type; missing slots are "off" (PROTOCOL §14.3).

type SandboxInfo

type SandboxInfo struct {
	Mode      SandboxMode `json:"mode"`
	Proxy     string      `json:"proxy,omitempty"`
	Workspace string      `json:"workspace,omitempty"`
}

SandboxInfo is the "sandbox" member of the initialize meta (PROTOCOL §5.1, §15).

func (SandboxInfo) Validate

func (s SandboxInfo) Validate() error

Validate checks the mode and, when set, that the proxy is an http URL.

type SandboxMode

type SandboxMode string

SandboxMode is the sandbox mode of a workspace (PROTOCOL §15.1).

const (
	SandboxModeOS        SandboxMode = "os"
	SandboxModeContainer SandboxMode = "container"
	SandboxModeNone      SandboxMode = "none"
)

func AllSandboxModes

func AllSandboxModes() []SandboxMode

AllSandboxModes returns every defined SandboxMode value in protocol order.

func (SandboxMode) Valid

func (v SandboxMode) Valid() bool

Valid reports whether v is a defined SandboxMode value.

type SecretField

type SecretField struct {
	Secret bool   `json:"secret,omitempty"`
	EnvRef string `json:"envRef,omitempty"`
}

SecretField marks an env var or header: either a secret whose value stays in the plugin, or a reference to an env var by name. A literal JSON string does not decode into it, so a plugin cannot pass a value through these maps.

func (SecretField) Validate

func (s SecretField) Validate() error

Validate checks that exactly one of Secret and EnvRef is set.

type SessionMeta

type SessionMeta struct {
	Role         *RoleRef     `json:"role,omitempty"`
	Task         *TaskMeta    `json:"task,omitempty"`
	Model        string       `json:"model,omitempty"`
	Effort       Effort       `json:"effort,omitempty"`
	Instructions string       `json:"instructions,omitempty"`
	Language     string       `json:"language,omitempty"`
	Permissions  *Permissions `json:"permissions,omitempty"`
	Subagents    *Subagents   `json:"subagents,omitempty"`
	Budget       *Budget      `json:"budget,omitempty"`
	Skills       []SkillRef   `json:"skills,omitempty"`
	ResumeFrom   *string      `json:"resumeFrom,omitempty"`
}

SessionMeta is "_meta.arvel" of session/new and session/load (PROTOCOL §7.1).

func (SessionMeta) Normalize

func (m SessionMeta) Normalize() SessionMeta

Normalize applies what a plugin must do whatever the host sent: a read-only task never gets edit access (PROTOCOL §7.1). The receiver is not modified.

func (SessionMeta) Validate

func (m SessionMeta) Validate() error

Validate checks enums, skills and budget values.

type SkillInvocation

type SkillInvocation string

SkillInvocation tells whether a skill is invoked automatically (PROTOCOL §7.1).

const (
	SkillInvocationAuto   SkillInvocation = "auto"
	SkillInvocationManual SkillInvocation = "manual"
)

func AllSkillInvocations

func AllSkillInvocations() []SkillInvocation

AllSkillInvocations returns every defined SkillInvocation value in protocol order.

func (SkillInvocation) Valid

func (v SkillInvocation) Valid() bool

Valid reports whether v is a defined SkillInvocation value.

type SkillRef

type SkillRef struct {
	Name       string          `json:"name"`
	Path       string          `json:"path"`
	Invocation SkillInvocation `json:"invocation"`
}

SkillRef is an Agent Skills folder prepared by the host.

type SkillsInfo

type SkillsInfo struct {
	ProjectDirs []string `json:"projectDirs,omitempty"`
	Spec        string   `json:"spec,omitempty"`
}

SkillsInfo tells where the vendor CLI looks for project skills.

type SlotState

type SlotState string

SlotState is a role's default in a task type (PROTOCOL §14.3, §16.3).

const (
	SlotStateOn       SlotState = "on"
	SlotStateOff      SlotState = "off"
	SlotStateAuto     SlotState = "auto"
	SlotStateOptional SlotState = "optional"
)

func AllSlotStates

func AllSlotStates() []SlotState

AllSlotStates returns every defined SlotState value in protocol order.

func (SlotState) Valid

func (v SlotState) Valid() bool

Valid reports whether v is a defined SlotState value.

type Spend

type Spend struct {
	Currency   string      `json:"currency"`
	SinceStart float64     `json:"sinceStart"`
	Source     UsageSource `json:"source,omitempty"`
}

Spend is money spent since the process started.

type Status

type Status struct {
	State       StatusState  `json:"state"`
	Message     string       `json:"message,omitempty"`
	Binary      *BinaryInfo  `json:"binary,omitempty"`
	Account     *AccountInfo `json:"account,omitempty"`
	BillingNote string       `json:"billingNote,omitempty"`
	Actions     []Action     `json:"actions,omitempty"`
}

Status is the result of _arvel/status (PROTOCOL §6.1).

func (Status) Validate

func (s Status) Validate() error

Validate checks the state, the binary name and every action.

type StatusState

type StatusState string

StatusState is the state reported by _arvel/status (PROTOCOL §6.1).

const (
	StateReady        StatusState = "ready"
	StateNotInstalled StatusState = "not_installed"
	StateOutdated     StatusState = "outdated"
	StateNeedsLogin   StatusState = "needs_login"
	StateDegraded     StatusState = "degraded"
	StateError        StatusState = "error"
)

func AllStatusStates

func AllStatusStates() []StatusState

AllStatusStates returns every defined StatusState value in protocol order.

func (StatusState) Valid

func (v StatusState) Valid() bool

Valid reports whether v is a defined StatusState value.

type StopDetail

type StopDetail = ErrorData

StopDetail is the turn-level outcome in "_meta.arvel.stop"; it has the same shape as ErrorData (PROTOCOL §9).

type SubagentMeta

type SubagentMeta struct {
	ID               string `json:"id"`
	ParentToolCallID string `json:"parentToolCallId"`
	Label            string `json:"label,omitempty"`
}

SubagentMeta marks an update produced inside a subagent (PROTOCOL §7.2).

type Subagents

type Subagents struct {
	Enabled     bool   `json:"enabled"`
	Model       string `json:"model,omitempty"`
	Effort      Effort `json:"effort,omitempty"`
	MaxParallel int    `json:"maxParallel,omitempty"`
}

Subagents configures subagent use.

type TaskMeta

type TaskMeta struct {
	Number   int    `json:"number"`
	Code     string `json:"code,omitempty"`
	Type     string `json:"type"`
	ReadOnly bool   `json:"readOnly"`
}

TaskMeta is "_meta.arvel.task" of session/new (PROTOCOL §7.1). It is informative: plugins must not change behaviour by role or task type, except that ReadOnly forbids every file change.

type TurnMeta

type TurnMeta struct {
	Usage *TurnUsage  `json:"usage,omitempty"`
	Stop  *StopDetail `json:"stop,omitempty"`
}

TurnMeta is "_meta.arvel" of the session/prompt result.

type TurnUsage

type TurnUsage struct {
	InputTokens     int64       `json:"inputTokens"`
	OutputTokens    int64       `json:"outputTokens"`
	CacheReadTokens int64       `json:"cacheReadTokens,omitempty"`
	CostUSD         float64     `json:"costUsd,omitempty"`
	CostSource      UsageSource `json:"costSource,omitempty"`
}

TurnUsage is "_meta.arvel.usage" of a session/prompt result (PROTOCOL §7.2).

type TypeDecision

type TypeDecision struct {
	TypeID     string  `json:"typeId"`
	Confidence float64 `json:"confidence"`
}

TypeDecision is the router's choice of a task type.

type UpdateMeta

type UpdateMeta struct {
	Subagent *SubagentMeta `json:"subagent,omitempty"`
}

UpdateMeta is "_meta.arvel" of session/update (PROTOCOL §7.2).

type Usage

type Usage struct {
	Source    UsageSource   `json:"source"`
	Status    UsageStatus   `json:"status"`
	Windows   []UsageWindow `json:"windows,omitempty"`
	Spend     *Spend        `json:"spend,omitempty"`
	UpdatedAt time.Time     `json:"updatedAt,omitzero"`
}

Usage is the result of _arvel/usage and the body of _arvel/usage_updated.

func (Usage) Validate

func (u Usage) Validate() error

Validate checks enums, percentages and spend.

type UsageSource

type UsageSource string

UsageSource tells how exact usage numbers are (PROTOCOL §6.3).

const (
	UsageSourceExact     UsageSource = "exact"
	UsageSourceEstimated UsageSource = "estimated"
	UsageSourceUnknown   UsageSource = "unknown"
)

func AllUsageSources

func AllUsageSources() []UsageSource

AllUsageSources returns every defined UsageSource value in protocol order.

func (UsageSource) Valid

func (v UsageSource) Valid() bool

Valid reports whether v is a defined UsageSource value.

type UsageStatus

type UsageStatus string

UsageStatus is the overall usage status (PROTOCOL §6.3).

const (
	UsageStatusOK        UsageStatus = "ok"
	UsageStatusWarning   UsageStatus = "warning"
	UsageStatusExhausted UsageStatus = "exhausted"
)

func AllUsageStatuses

func AllUsageStatuses() []UsageStatus

AllUsageStatuses returns every defined UsageStatus value in protocol order.

func (UsageStatus) Valid

func (v UsageStatus) Valid() bool

Valid reports whether v is a defined UsageStatus value.

type UsageWindow

type UsageWindow struct {
	ID              string    `json:"id"`
	Label           string    `json:"label,omitempty"`
	UsedPercent     float64   `json:"usedPercent"`
	ResetsAt        time.Time `json:"resetsAt,omitzero"`
	DurationMinutes int       `json:"durationMinutes,omitempty"`
}

UsageWindow is one quota window.

type ValidationError

type ValidationError struct {
	Issues []Issue
}

ValidationError lists every violation of a router result. Decisions the host merely ignores (PROTOCOL §14.3) are not violations; see Sanitize.

func (*ValidationError) Error

func (e *ValidationError) Error() string

Error implements the error interface; it shows at most five issues.

func (*ValidationError) Has

func (e *ValidationError) Has(kind IssueKind) bool

Has reports whether any issue has the given kind.

type VendorPaths

type VendorPaths struct {
	Read  []string `json:"read,omitempty"`
	Write []string `json:"write,omitempty"`
}

VendorPaths lists the paths outside the workspace the vendor CLI needs.

Directories

Path Synopsis
Package skills delivers the Agent Skills folders the Arvel host prepares for a session (PROTOCOL §7.1 item 5a) to a vendor CLI that reads project skills from a directory inside the session's working directory.
Package skills delivers the Agent Skills folders the Arvel host prepares for a session (PROTOCOL §7.1 item 5a) to a vendor CLI that reads project skills from a directory inside the session's working directory.

Jump to

Keyboard shortcuts

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