plugin

Documentation

Overview

Package plugin defines the transport-neutral contract between Coding and one external capability process. A concrete stdio or RPC transport can implement Supervisor without leaking process management into the agent SDK.

Index

• Constants
• func Load(ctx context.Context, supervisor Supervisor, host HostInfo) (capability.Definition, error)
• type CancelRequest
• type CancelResponse
• type Content
• type ContentType
• type ExecuteRequest
• type ExecutionMode
• type HostInfo
• type InitializeRequest
• type InitializeResponse
• type ListToolsRequest
• type ListToolsResponse
• type Manifest
• type Outcome
• type OutcomeStatus
• type ProgressNotification
• type Result
• type Supervisor
• type ToolDescriptor

Constants

const ProtocolVersion = 1

ProtocolVersion is the only plugin protocol version understood by this host.

Functions

func Load

func Load(ctx context.Context, supervisor Supervisor, host HostInfo) (capability.Definition, error)

Load initializes one supervisor and adapts its advertised tools into the existing Coding capability pipeline.

Types

type CancelRequest

type CancelRequest struct {
	CallID string `json:"callId"`
}

CancelRequest asks the plugin to stop an active call.

type CancelResponse

type CancelResponse struct {
	Accepted bool `json:"accepted"`
}

CancelResponse reports whether the plugin found an active call to cancel.

type Content

type Content struct {
	Type     ContentType `json:"type"`
	Text     string      `json:"text,omitempty"`
	Data     string      `json:"data,omitempty"`
	MIMEType string      `json:"mimeType,omitempty"`
}

Content is the wire representation of text and image tool-result content.

type ContentType

type ContentType string

ContentType identifies one model-facing content block.

const (
	ContentText  ContentType = "text"
	ContentImage ContentType = "image"
)

type ExecuteRequest

type ExecuteRequest struct {
	CallID    string          `json:"callId"`
	Tool      string          `json:"tool"`
	Arguments json.RawMessage `json:"arguments"`
}

ExecuteRequest starts one validated tool call. Arguments are the validated JSON object produced by the agent engine, not the provider's original input.

type ExecutionMode

type ExecutionMode string

ExecutionMode controls whether the agent may execute a plugin tool alongside other calls from the same model turn.

const (
	ExecutionParallel   ExecutionMode = "parallel"
	ExecutionSequential ExecutionMode = "sequential"
)

type HostInfo

type HostInfo struct {
	Name    string `json:"name"`
	Version string `json:"version"`
}

HostInfo identifies the Coding host during the initialization handshake.

type InitializeRequest

type InitializeRequest struct {
	ProtocolVersion int      `json:"protocolVersion"`
	Host            HostInfo `json:"host"`
}

InitializeRequest starts a protocol-version handshake with one plugin.

type InitializeResponse

type InitializeResponse struct {
	ProtocolVersion int      `json:"protocolVersion"`
	Plugin          Manifest `json:"plugin"`
}

InitializeResponse confirms the selected protocol and plugin identity.

type ListToolsRequest

type ListToolsRequest struct{}

ListToolsRequest asks the initialized plugin for its current tool set.

type ListToolsResponse

type ListToolsResponse struct {
	Tools []ToolDescriptor `json:"tools"`
}

ListToolsResponse contains the tools contributed by one plugin.

type Manifest

type Manifest struct {
	ID      string `json:"id"`
	Name    string `json:"name,omitempty"`
	Version string `json:"version"`
}

Manifest identifies one plugin instance.

type Outcome

type Outcome struct {
	Status    OutcomeStatus   `json:"status"`
	ErrorCode string          `json:"errorCode,omitempty"`
	ExitCode  *int            `json:"exitCode,omitempty"`
	Data      json.RawMessage `json:"data,omitempty"`
}

Outcome is the wire representation of a terminal tool outcome.

type OutcomeStatus

type OutcomeStatus string

OutcomeStatus is the terminal state reported by a plugin tool.

const (
	OutcomeSuccess   OutcomeStatus = "success"
	OutcomeFailed    OutcomeStatus = "failed"
	OutcomeCancelled OutcomeStatus = "cancelled"
	OutcomeTimeout   OutcomeStatus = "timeout"
)

type ProgressNotification

type ProgressNotification struct {
	CallID  string          `json:"callId"`
	Content []Content       `json:"content,omitempty"`
	Data    json.RawMessage `json:"data,omitempty"`
}

ProgressNotification is a non-terminal update for one active call.

type Result

type Result struct {
	CallID    string    `json:"callId"`
	Content   []Content `json:"content,omitempty"`
	Outcome   Outcome   `json:"outcome"`
	Terminate bool      `json:"terminate,omitempty"`
}

Result is the unique terminal response for one ExecuteRequest.

type Supervisor

type Supervisor interface {
	Initialize(context.Context, InitializeRequest) (InitializeResponse, error)
	ListTools(context.Context, ListToolsRequest) (ListToolsResponse, error)
	Execute(context.Context, ExecuteRequest, func(ProgressNotification)) (Result, error)
	Cancel(context.Context, CancelRequest) (CancelResponse, error)
}

Supervisor owns one initialized plugin connection. Implementations are responsible for serializing concurrent calls and translating Execute context cancellation into the transport's cancel operation.

type ToolDescriptor

type ToolDescriptor struct {
	Name          string          `json:"name"`
	Description   string          `json:"description"`
	InputSchema   json.RawMessage `json:"inputSchema"`
	Label         string          `json:"label,omitempty"`
	Guidelines    []string        `json:"guidelines,omitempty"`
	ExecutionMode ExecutionMode   `json:"executionMode,omitempty"`
}

ToolDescriptor is the serializable portion of a Coding tool. Access metadata is deliberately absent in protocol v1, so adapted plugin tools take the conservative unknown-access path and require product authorization.