Documentation
¶
Overview ¶
Package plugin is the framework for Arvel plugins. A vendor plugin implements Provider and Session and calls Run; a router plugin implements Router (plus PlanRouter, MessageRouter, EffortRouter, ExplainRouter as it needs) and calls RunRouter. The framework does everything the protocol asks of every plugin: the stdio transport, initialize, the _arvel/* methods, the ACP session methods, concurrency rules, permission requests, throttling, shutdown, panic recovery, error conversion and secret redaction.
A provider's main function:
func main() {
p := &myProvider{}
if err := plugin.Run(context.Background(), p, plugin.WithVersion("arvel-plugin-x", version)); err != nil {
os.Exit(1)
}
}
Run returns nil after a graceful end, so the process exits 0.
Errors a plugin returns reach the host as follows: a *protocol.RPCError built with protocol.NewError keeps its code, anything else becomes the Arvel error "provider_error", and the text of every error is scrubbed of the secrets the host sent in initialize.
Index ¶
- Constants
- Variables
- func Run(ctx context.Context, p Provider, opts ...Option) error
- func RunRouter(ctx context.Context, r Router, opts ...Option) error
- type Clock
- type ConfigOptioner
- type Discoverer
- type EffortRouter
- type ExplainRouter
- type Features
- type Host
- type HostAware
- type LoadParams
- type MessageRouter
- type Option
- func WithClock(c Clock) Option
- func WithCloseTimeout(d time.Duration) Option
- func WithIdleTimeout(d time.Duration) Option
- func WithInitTimeout(d time.Duration) Option
- func WithRouteTimeout(d time.Duration) Option
- func WithStderr(w io.Writer) Option
- func WithStdio(r io.Reader, w io.Writer) Option
- func WithVersion(name, version string) Option
- type Output
- type PermissionDecision
- type PermissionRequest
- type PlanRouter
- type Provider
- type Router
- type RouterFeatures
- type RouterHost
- type RouterHostAware
- type Session
- type SessionParams
- type Stopper
- type TurnResult
Examples ¶
Constants ¶
const ( DefaultIdleTimeout = 15 * time.Minute DefaultRouteTimeout = 2500 * time.Millisecond DefaultInitTimeout = 5 * time.Second DefaultCloseTimeout = 5 * time.Second // UsageInterval is the shortest time between two _arvel/usage_updated messages. UsageInterval = 5 * time.Second // CancelWarnAfter is how long a turn may keep running after session/cancel // before the framework logs a warning. CancelWarnAfter = 10 * time.Second )
Defaults of the framework timers.
Variables ¶
var ErrNoRouteFeature = errors.New("plugin: router implements none of PlanRouter, MessageRouter, EffortRouter, ExplainRouter")
ErrNoRouteFeature is returned by RunRouter for a router that implements none of PlanRouter, MessageRouter, EffortRouter and ExplainRouter.
Functions ¶
func Run ¶
Run serves a provider plugin on stdin and stdout until the host sends _arvel/shutdown, stdin ends, a signal arrives (SIGINT, SIGTERM or a console close on Windows) or ctx is done. It then cancels the running turns, closes every session with a deadline, shuts the provider down and returns nil, so the process can exit 0. It returns an error only for invalid arguments or a failing transport.
Example ¶
ExampleRun shows the whole main function of a provider plugin.
package main
import (
"context"
"os"
"github.com/arvel-dev/arvel-sdk/plugin"
"github.com/arvel-dev/arvel-sdk/protocol"
)
// exampleProvider is the smallest provider: it cannot run a turn.
type exampleProvider struct{}
func (exampleProvider) Initialize(context.Context, protocol.InitMeta) (plugin.Features, error) {
return plugin.Features{}, nil
}
func (exampleProvider) Status(context.Context) (protocol.Status, error) {
return protocol.Status{State: protocol.StateReady}, nil
}
func (exampleProvider) Models(context.Context, bool) (protocol.ModelsResult, error) {
return protocol.ModelsResult{}, nil
}
func (exampleProvider) Usage(context.Context) (protocol.Usage, error) {
return protocol.Usage{Source: protocol.UsageSourceUnknown, Status: protocol.UsageStatusOK}, nil
}
func (exampleProvider) Action(context.Context, string) (protocol.ActionResult, error) {
return protocol.ActionResult{Kind: protocol.ActionKindDone}, nil
}
func (exampleProvider) NewSession(context.Context, plugin.SessionParams) (plugin.Session, error) {
return nil, protocol.NewError(protocol.ErrInternal, "not implemented", nil)
}
func (exampleProvider) LoadSession(context.Context, plugin.LoadParams) (plugin.Session, error) {
return nil, protocol.NewError(protocol.ErrInternal, "not implemented", nil)
}
func (exampleProvider) Shutdown(context.Context) error { return nil }
func main() {
if err := plugin.Run(context.Background(), exampleProvider{}, plugin.WithVersion("arvel-plugin-example", "0.1.0")); err != nil {
os.Exit(1)
}
}
Output:
func RunRouter ¶
RunRouter serves a router plugin on stdin and stdout until the host sends _arvel/shutdown, stdin ends, a signal arrives or ctx is done. It answers initialize, _arvel/status, the route calls of the implemented interfaces and _arvel/shutdown; every other method, including every session/* method, gets -32601. Each route call runs under the route timeout, and its result is validated against its request before it is sent. Decisions the host ignores (auto slots, a type's lead_accept) are dropped and logged at warn.
Example ¶
ExampleRunRouter shows the whole main function of a router plugin.
package main
import (
"context"
"os"
"github.com/arvel-dev/arvel-sdk/plugin"
"github.com/arvel-dev/arvel-sdk/protocol"
)
type exampleRouter struct{}
func (exampleRouter) Initialize(context.Context, protocol.InitMeta) (plugin.RouterFeatures, error) {
return plugin.RouterFeatures{}, nil
}
func (exampleRouter) Status(context.Context) (protocol.Status, error) {
return protocol.Status{State: protocol.StateReady}, nil
}
func (exampleRouter) Shutdown(context.Context) error { return nil }
func (exampleRouter) Effort(_ context.Context, p protocol.RouteEffortParams) (protocol.RouteEffortResult, error) {
return protocol.RouteEffortResult{Effort: p.Levels[0], Confidence: 0.5}, nil
}
func main() {
if err := plugin.RunRouter(context.Background(), exampleRouter{}, plugin.WithVersion("arvel-plugin-example-router", "0.1.0")); err != nil {
os.Exit(1)
}
}
Output:
Types ¶
type Clock ¶
Clock abstracts time for the throttle, the cancel watchdog and the idle reaper, so tests can drive them without sleeping.
type ConfigOptioner ¶
type ConfigOptioner interface {
ConfigOptions() []acp.SessionConfigOption
}
ConfigOptioner is implemented by a Session that reports ACP config options (categories model and thought_level) in the session/new response.
type Discoverer ¶
type Discoverer interface {
Discover(ctx context.Context, p protocol.DiscoverParams) (protocol.DiscoverResult, error)
}
Discoverer is implemented by a Provider that supports _arvel/discover. The framework then announces the "discover" feature.
type EffortRouter ¶
type EffortRouter interface {
Effort(ctx context.Context, p protocol.RouteEffortParams) (protocol.RouteEffortResult, error)
}
EffortRouter answers _arvel/route/effort.
type ExplainRouter ¶
type ExplainRouter interface {
Explain(ctx context.Context, p protocol.RoutePlanParams) (protocol.RouteExplainResult, error)
}
ExplainRouter answers _arvel/route/explain.
type Features ¶
type Features struct {
// LoadSession announces session/load and the "resume" feature.
LoadSession bool
// Prompt content types the plugin accepts besides text and resource links.
PromptImage, PromptAudio, PromptEmbeddedContext bool
// MCP transports the plugin can hand to the vendor CLI.
MCPHTTP, MCPSSE bool
// Subagents announces the "subagents" feature.
Subagents bool
// Skills, when set, announces the "skills" feature and where the vendor CLI
// looks for project skills.
Skills *protocol.SkillsInfo
// InstructionFiles are files the vendor CLI reads from the working directory.
InstructionFiles []string
// MaxParallelSessions announces a soft limit; 0 announces none.
MaxParallelSessions int
}
Features is what Initialize reports about the plugin. The status, models, usage and actions features are always announced.
type Host ¶
type Host interface {
// StatusChanged sends _arvel/status_changed; identical consecutive
// statuses are dropped.
StatusChanged(protocol.Status)
// UsageUpdated sends _arvel/usage_updated, at most once per 5 s; the last
// value wins.
UsageUpdated(protocol.Usage)
// Logger returns the plugin logger (JSON on stderr, secrets redacted).
Logger() *slog.Logger
}
Host is the provider's handle for messages it starts itself.
type HostAware ¶
type HostAware interface{ SetHost(Host) }
HostAware is implemented by a Provider that wants its Host. SetHost is called before Initialize.
type LoadParams ¶
type LoadParams struct {
SessionID string
SessionParams
}
LoadParams are the params of session/load, or the stored params of an idle-closed session that is loaded again.
type MessageRouter ¶
type MessageRouter interface {
Message(ctx context.Context, p protocol.RouteMessageParams) (protocol.RouteMessageResult, error)
}
MessageRouter answers _arvel/route/message.
type Option ¶
type Option func(*options)
Option configures Run and RunRouter.
func WithCloseTimeout ¶
WithCloseTimeout sets the deadline for closing sessions, running turns at shutdown and Provider.Shutdown (default 5 s).
func WithIdleTimeout ¶
WithIdleTimeout sets how long a session may be idle before it is closed (default 15 min). Non-positive values keep the default.
func WithInitTimeout ¶
WithInitTimeout sets the deadline of Initialize (default 5 s).
func WithRouteTimeout ¶
WithRouteTimeout sets the deadline of a route call (default 2.5 s).
func WithStderr ¶
WithStderr replaces stderr as the log destination, for tests.
func WithVersion ¶
WithVersion sets the plugin name and version: the "plugin" attribute of every log line and the agentInfo of the initialize result.
type Output ¶
type Output interface {
// Update sends a session/update notification. meta carries the Arvel
// per-update metadata (subagent) and may be nil.
Update(u acp.SessionUpdate, meta *protocol.UpdateMeta) error
// RequestPermission asks the host and blocks until it answers, the session
// is cancelled (then the decision has Cancelled set) or ctx ends. There is
// no timeout (PROTOCOL §7.3).
RequestPermission(ctx context.Context, req PermissionRequest) (PermissionDecision, error)
}
Output is what a turn writes to.
type PermissionDecision ¶
type PermissionDecision struct {
// OptionID is the chosen option; empty when Cancelled.
OptionID string
// Cancelled is set when the session was cancelled, the host cancelled the
// request, or the answer was unusable. Treat it as a rejection.
Cancelled bool
}
PermissionDecision is the host's answer.
type PermissionRequest ¶
type PermissionRequest struct {
ToolCall acp.ToolCallUpdate
Options []acp.PermissionOption
Meta protocol.PermissionMeta
}
PermissionRequest is a request for the host's decision.
type PlanRouter ¶
type PlanRouter interface {
Plan(ctx context.Context, p protocol.RoutePlanParams) (protocol.RoutePlanResult, error)
}
PlanRouter answers _arvel/route/plan.
type Provider ¶
type Provider interface {
// Initialize is called once. It must return in under 5 s and must not use
// the network; slow checks belong in Status.
Initialize(ctx context.Context, in protocol.InitMeta) (Features, error)
// Status answers _arvel/status.
Status(ctx context.Context) (protocol.Status, error)
// Models answers _arvel/models; refresh asks for a fresh list.
Models(ctx context.Context, refresh bool) (protocol.ModelsResult, error)
// Usage answers _arvel/usage.
Usage(ctx context.Context) (protocol.Usage, error)
// Action runs one of the actions announced in the status.
Action(ctx context.Context, id string) (protocol.ActionResult, error)
// NewSession creates a session for session/new.
NewSession(ctx context.Context, p SessionParams) (Session, error)
// LoadSession resumes a session for session/load and after an idle close.
// It is only called when Features.LoadSession is true.
LoadSession(ctx context.Context, p LoadParams) (Session, error)
// Shutdown is called once at the end, after every session was closed.
Shutdown(ctx context.Context) error
}
Provider is what a vendor plugin implements. Every method that returns a *protocol.RPCError (built with protocol.NewError) reaches the host with that code; any other error becomes the Arvel error "provider_error" with its text redacted.
type Router ¶
type Router interface {
// Initialize is called once. It must return in under 5 s and must not use
// the network.
Initialize(ctx context.Context, in protocol.InitMeta) (RouterFeatures, error)
// Status answers _arvel/status.
Status(ctx context.Context) (protocol.Status, error)
// Shutdown is called once at the end.
Shutdown(ctx context.Context) error
}
Router is what a router plugin implements (PROTOCOL §14). The route.* features it announces are the optional interfaces it also implements: PlanRouter, MessageRouter, EffortRouter and ExplainRouter.
type RouterFeatures ¶
type RouterFeatures struct{}
RouterFeatures is what Router.Initialize returns. The route.* features follow from the optional interfaces the router implements, so the struct is empty; fields can be added without breaking existing routers.
type RouterHost ¶
type RouterHost interface {
// StatusChanged sends _arvel/status_changed; identical consecutive statuses
// are dropped.
StatusChanged(protocol.Status)
// Logger returns the plugin logger (JSON on stderr, secrets redacted).
Logger() *slog.Logger
}
RouterHost is a router's handle for messages it starts itself.
type RouterHostAware ¶
type RouterHostAware interface{ SetHost(RouterHost) }
RouterHostAware is implemented by a Router that wants its RouterHost. SetHost is called before Initialize.
type Session ¶
type Session interface {
// ID is the ACP session id; it must not change.
ID() string
// Prompt runs one turn. It streams through out and returns when the turn
// ends. It must honour ctx, which ends at shutdown or when the connection
// ends; a session/cancel does not cancel ctx but calls Cancel.
Prompt(ctx context.Context, blocks []acp.ContentBlock, out Output) (TurnResult, error)
// SetOption changes a config option. The change applies from the next turn
// and must not interrupt a running turn (PROTOCOL §7.5).
SetOption(ctx context.Context, id, value string) ([]acp.SessionConfigOption, error)
// Cancel asks the running turn to stop gracefully. It must not block and
// must be idempotent. The provider owns killing a stuck vendor process.
Cancel()
// Close releases the session. It is called once, with a deadline.
Close(ctx context.Context) error
}
Session is one ACP session.
type SessionParams ¶
type SessionParams struct {
CWD string
MCPServers []acp.McpServer
// Meta is the decoded _meta.arvel; the zero value when absent.
Meta protocol.SessionMeta
}
SessionParams are the params of session/new.
type Stopper ¶
type Stopper = interface{ Stop() bool }
Stopper stops a timer started by Clock.AfterFunc. It is an alias of an anonymous interface so test clocks can satisfy Clock without importing this package.
type TurnResult ¶
type TurnResult struct {
// StopReason must be one of the ACP stop reasons.
StopReason acp.StopReason
// Usage and Stop are sent in _meta.arvel of the session/prompt result.
Usage *protocol.TurnUsage
Stop *protocol.StopDetail
}
TurnResult is the outcome of a turn.