plugin

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: 19 Imported by: 0

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

Examples

Constants

View Source
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

View Source
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

func Run(ctx context.Context, p Provider, opts ...Option) error

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)
	}
}

func RunRouter

func RunRouter(ctx context.Context, r Router, opts ...Option) error

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)
	}
}

Types

type Clock

type Clock interface {
	Now() time.Time
	AfterFunc(d time.Duration, f func()) Stopper
}

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 WithClock

func WithClock(c Clock) Option

WithClock replaces the clock, for tests.

func WithCloseTimeout

func WithCloseTimeout(d time.Duration) Option

WithCloseTimeout sets the deadline for closing sessions, running turns at shutdown and Provider.Shutdown (default 5 s).

func WithIdleTimeout

func WithIdleTimeout(d time.Duration) Option

WithIdleTimeout sets how long a session may be idle before it is closed (default 15 min). Non-positive values keep the default.

func WithInitTimeout

func WithInitTimeout(d time.Duration) Option

WithInitTimeout sets the deadline of Initialize (default 5 s).

func WithRouteTimeout

func WithRouteTimeout(d time.Duration) Option

WithRouteTimeout sets the deadline of a route call (default 2.5 s).

func WithStderr

func WithStderr(w io.Writer) Option

WithStderr replaces stderr as the log destination, for tests.

func WithStdio

func WithStdio(r io.Reader, w io.Writer) Option

WithStdio replaces stdin and stdout, for tests. It also turns off signal handling.

func WithVersion

func WithVersion(name, version string) Option

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.

Jump to

Keyboard shortcuts

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