plugin

Documentation

Overview

Package plugin provides a development kit for building external FlowCraft plugins. External plugins are standalone binaries that communicate with the host via gRPC over Unix domain socket.

Usage:

func main() {
    plugin.Serve(
        plugin.WithInfo(plugin.PluginInfo{...}),
        plugin.WithTool("my_tool", "description", nil, myHandler),
    )
}

Package plugin provides an extensible plugin system supporting both built-in (compiled-in, init() self-registration) and external (gRPC subprocess) plugins.

Index

• func Serve(opts ...Option)
• type Context
  • func (c *Context) GetVar(key string) (any, bool)
  • func (c *Context) LLMGenerate(prompt string) (string, error)
  • func (c *Context) SandboxExec(command string) (string, error)
  • func (c *Context) SetVar(key string, value any)
  • func (c *Context) Signal(signalType string, payload any) error
  • func (c *Context) StreamEmit(data string)
  • func (c *Context) ToolExecute(name, args string) (string, error)
• type DataSourcePlugin
• type HandshakeRequest
• type HandshakeResponse
• type InstalledPlugin
• type LifecycleClient
• type ModelPlugin
• type NodeCallbacks
• type NodeHandler
• type NodePlugin
• type NodeServiceClient
• type NodeSpec
• type Option
  • func WithInfo(info PluginInfo) Option
  • func WithNode(nodeType string, schema map[string]any, handler NodeHandler) Option
  • func WithTool(name string, description string, schema map[string]any, handler ToolHandler) Option
• type Plugin
• type PluginInfo
• type PluginStatus
• type PluginType
• type SchemaProvider
• type StrategyPlugin
• type ToolHandler
• type ToolPlugin
• type ToolServiceClient
• type ToolSpec

Functions

func Serve

func Serve(opts ...Option)

Serve starts the plugin gRPC server on a Unix domain socket. The socket path is provided by the host via FLOWCRAFT_SOCKET env var.

Types

type Context

type Context struct {
	// contains filtered or unexported fields
}

Context wraps host callback functions available to plugin handlers.

func (*Context) GetVar

func (c *Context) GetVar(key string) (any, bool)

GetVar reads a variable from the host board.

func (*Context) LLMGenerate

func (c *Context) LLMGenerate(prompt string) (string, error)

LLMGenerate calls the host's LLM for text generation.

func (*Context) SandboxExec

func (c *Context) SandboxExec(command string) (string, error)

SandboxExec executes a command in the host sandbox.

func (*Context) SetVar

func (c *Context) SetVar(key string, value any)

SetVar writes a variable to the host board.

func (*Context) Signal

func (c *Context) Signal(signalType string, payload any) error

Signal sends a signal to the host (e.g. broadcast to other agents).

func (*Context) StreamEmit

func (c *Context) StreamEmit(data string)

StreamEmit sends streaming data to the host.

func (*Context) ToolExecute

func (c *Context) ToolExecute(name, args string) (string, error)

ToolExecute calls a host-side tool.

type DataSourcePlugin

type DataSourcePlugin interface {
	Plugin
	DataSourceType() string
}

DataSourcePlugin extends Plugin for external data connectors.

type HandshakeRequest

type HandshakeRequest struct {
	HostVersion string `json:"host_version"`
	ProtocolVer int    `json:"protocol_version"`
}

HandshakeRequest is sent by host to plugin after connection.

type HandshakeResponse

type HandshakeResponse struct {
	PluginInfo  PluginInfo `json:"plugin_info"`
	ProtocolVer int        `json:"protocol_version"`
	Tools       []ToolSpec `json:"tools,omitempty"`
	Nodes       []NodeSpec `json:"nodes,omitempty"`
}

HandshakeResponse is returned by the plugin during handshake.

type InstalledPlugin

type InstalledPlugin struct {
	Info   PluginInfo     `json:"info"`
	Status PluginStatus   `json:"status"`
	Config map[string]any `json:"config,omitempty"`
	Error  string         `json:"error,omitempty"`
}

InstalledPlugin wraps a plugin with its runtime status.

type LifecycleClient

type LifecycleClient interface {
	Handshake(ctx context.Context, req *HandshakeRequest) (*HandshakeResponse, error)
	Initialize(ctx context.Context, config map[string]any) error
	Shutdown(ctx context.Context) error
	HealthCheck(ctx context.Context) error
}

LifecycleClient is the client-side interface for plugin lifecycle management.

type ModelPlugin

type ModelPlugin interface {
	Plugin
	ModelID() string
}

ModelPlugin extends Plugin for LLM model providers.

type NodeCallbacks

type NodeCallbacks interface {
	GetVar(key string) (any, bool)
	SetVar(key string, value any)
	LLMGenerate(ctx context.Context, prompt string) (string, error)
	ToolExecute(ctx context.Context, name string, args string) (string, error)
	StreamEmit(data string)
	SandboxExec(ctx context.Context, command string) (string, error)
	Signal(ctx context.Context, signalType string, payload any) error
}

NodeCallbacks are host callbacks available to external nodes during execution.

type NodeHandler

type NodeHandler func(ctx context.Context, callbacks NodeCallbacks) (map[string]any, error)

NodeHandler processes a node execution from the host.

type NodePlugin

type NodePlugin interface {
	Plugin
	NodeType() string
	CreateNode(id string, config map[string]any) (any, error)
}

NodePlugin extends Plugin with a custom node type.

type NodeServiceClient

type NodeServiceClient interface {
	ListNodes(ctx context.Context) ([]NodeSpec, error)
	Execute(ctx context.Context, nodeID string, config map[string]any, callbacks NodeCallbacks) (map[string]any, error)
}

NodeServiceClient is the client-side interface for external node execution.

type NodeSpec

type NodeSpec struct {
	Type   string         `json:"type"`
	Schema map[string]any `json:"schema,omitempty"`
}

NodeSpec describes a node type provided by an external plugin.

type Option

type Option func(*server)

Option configures the plugin server.

func WithInfo

func WithInfo(info PluginInfo) Option

WithInfo sets the plugin metadata.

func WithNode

func WithNode(nodeType string, schema map[string]any, handler NodeHandler) Option

WithNode registers a node handler.

func WithTool

func WithTool(name string, description string, schema map[string]any, handler ToolHandler) Option

WithTool registers a tool handler.

type Plugin

type Plugin interface {
	Info() PluginInfo
	Initialize(ctx context.Context, config map[string]any) error
	Shutdown(ctx context.Context) error
}

Plugin is the base interface for all plugins.

type PluginInfo

type PluginInfo struct {
	ID          string     `json:"id"`
	Name        string     `json:"name"`
	Version     string     `json:"version"`
	Type        PluginType `json:"type"`
	Description string     `json:"description,omitempty"`
	Author      string     `json:"author,omitempty"`
	Icon        string     `json:"icon,omitempty"`
	Homepage    string     `json:"homepage,omitempty"`
	Builtin     bool       `json:"builtin"`
	CreatedAt   time.Time  `json:"created_at"`
}

PluginInfo contains metadata about a plugin.

type PluginStatus

type PluginStatus string

PluginStatus represents the runtime state of a plugin.

const (
	StatusInstalled PluginStatus = "installed"
	StatusActive    PluginStatus = "active"
	StatusInactive  PluginStatus = "inactive"
	StatusError     PluginStatus = "error"
)

type PluginType

type PluginType string

PluginType identifies the kind of plugin.

const (
	TypeModel    PluginType = "model"
	TypeTool     PluginType = "tool"
	TypeNode     PluginType = "node"
	TypeStrategy PluginType = "agent_strategy"
	TypeData     PluginType = "data_source"
)

type SchemaProvider

type SchemaProvider interface {
	NodeSchema() map[string]any
}

SchemaProvider is an optional interface for plugins that expose UI schemas.

type StrategyPlugin

type StrategyPlugin interface {
	Plugin
	StrategyName() string
}

StrategyPlugin extends Plugin with custom agent reasoning strategy.

type ToolHandler

type ToolHandler func(ctx context.Context, arguments string) (string, error)

ToolHandler processes a tool call from the host.

type ToolPlugin

type ToolPlugin interface {
	Plugin
	Tools() []ToolSpec
	ExecuteTool(ctx context.Context, name string, arguments string) (string, error)
}

ToolPlugin extends Plugin with tool definitions and execution.

type ToolServiceClient

type ToolServiceClient interface {
	ListTools(ctx context.Context) ([]ToolSpec, error)
	Execute(ctx context.Context, name string, arguments string) (string, error)
}

ToolServiceClient is the client-side interface for external tool execution.

type ToolSpec

type ToolSpec struct {
	Name        string         `json:"name"`
	Description string         `json:"description"`
	InputSchema map[string]any `json:"input_schema"`
}

ToolSpec describes a tool provided by a ToolPlugin.