112 lines
5.0 KiB
Go
112 lines
5.0 KiB
Go
// Package plugin implements pigo's external plugin system (US-016, #132): an
|
|
// executable written in any language registers custom tools (and, later, slash
|
|
// commands) with pigo without touching pigo's source. pigo launches each plugin
|
|
// as a child process and speaks line-delimited JSON-RPC 2.0 over its stdio,
|
|
// reusing internal/jsonrpc as the transport.
|
|
//
|
|
// Protocol (client = pigo, server = plugin):
|
|
//
|
|
// - initialize → Manifest {name, version, tools[], commands[]}
|
|
// The handshake. The plugin declares everything it offers up front.
|
|
// - tools/call {name, arguments} → CallResult {content, isError}
|
|
// pigo forwards a tool invocation; the plugin runs it and returns the text.
|
|
// - event {type, data} (notification)
|
|
// pigo pushes a subscribed agent lifecycle event (US-017, #133). One-way,
|
|
// fire-and-forget: the plugin never replies and a slow plugin is isolated.
|
|
// - shutdown (notification)
|
|
// Sent on Close so a well-behaved plugin can exit before stdin EOF.
|
|
//
|
|
// A plugin that crashes or misbehaves is isolated: its Start failure is logged
|
|
// and skipped (other plugins still load), and a tool call against a dead plugin
|
|
// returns an error result rather than propagating up.
|
|
//
|
|
// This file defines the wire types exchanged during the handshake and tool call.
|
|
package plugin
|
|
|
|
import "encoding/json"
|
|
|
|
// Manifest is the plugin's self-description, returned from the initialize call.
|
|
type Manifest struct {
|
|
// Name identifies the plugin; used to namespace its tools and in diagnostics.
|
|
Name string `json:"name"`
|
|
// Version is an optional free-form version string for diagnostics.
|
|
Version string `json:"version,omitempty"`
|
|
// Tools are the tools this plugin registers with the agent.
|
|
Tools []ToolSpec `json:"tools,omitempty"`
|
|
// Commands are the slash commands this plugin registers.
|
|
Commands []CommandSpec `json:"commands,omitempty"`
|
|
// Events lists the agent lifecycle event types this plugin subscribes to
|
|
// (US-017, #133). pigo delivers only these via one-way `event` notifications;
|
|
// an empty list means the plugin observes no events. Valid values are the
|
|
// agentcore.Event* discriminants (e.g. "agent_start", "tool_execution_end").
|
|
Events []string `json:"events,omitempty"`
|
|
}
|
|
|
|
// ToolSpec declares one tool a plugin exposes. Schema is the JSON Schema for the
|
|
// tool's arguments, passed through verbatim to the agent's tool registry.
|
|
type ToolSpec struct {
|
|
Name string `json:"name"`
|
|
Description string `json:"description"`
|
|
Schema json.RawMessage `json:"schema"`
|
|
}
|
|
|
|
// CommandSpec declares one slash command a plugin exposes. Prompt is the text
|
|
// injected as the next user prompt when the command is invoked (matching the
|
|
// declarative-command convention); it may be empty if the plugin handles the
|
|
// command by other means.
|
|
type CommandSpec struct {
|
|
Name string `json:"name"`
|
|
Description string `json:"description"`
|
|
Prompt string `json:"prompt,omitempty"`
|
|
}
|
|
|
|
// CallParams is the parameter object for a tools/call request.
|
|
type CallParams struct {
|
|
Name string `json:"name"`
|
|
Arguments json.RawMessage `json:"arguments"`
|
|
}
|
|
|
|
// CallResult is the reply to a tools/call request. Content is the tool output as
|
|
// text; IsError marks a tool-level failure (distinct from a transport error).
|
|
type CallResult struct {
|
|
Content string `json:"content"`
|
|
IsError bool `json:"isError,omitempty"`
|
|
}
|
|
|
|
// CommandCallParams is the parameter object for a commands/call request. It
|
|
// mirrors CallParams' naming (name/arguments) so a plugin can decode tool and
|
|
// command invocations with the same conventions. Name is the command's name;
|
|
// Args carries its free-form arguments (e.g. the text following the slash
|
|
// command) as raw JSON, passed through verbatim to the plugin.
|
|
type CommandCallParams struct {
|
|
Name string `json:"name"`
|
|
Args json.RawMessage `json:"arguments"`
|
|
}
|
|
|
|
// CommandCallResult is the reply to a commands/call request. Prompt is the text
|
|
// injected as the next agent turn (matching the declarative-command
|
|
// convention); it may be empty if the command produces no prompt. Notifications
|
|
// are messages the plugin asks pigo to surface to the user out of band from the
|
|
// prompt.
|
|
type CommandCallResult struct {
|
|
Prompt string `json:"prompt,omitempty"`
|
|
Notifications []CommandNotification `json:"notifications,omitempty"`
|
|
}
|
|
|
|
// CommandNotification is a single message a command asks pigo to surface to the
|
|
// user. Message is the human-readable text; Type is an optional severity or
|
|
// category hint (e.g. "info", "warning", "error") that pigo may use to style
|
|
// the message.
|
|
type CommandNotification struct {
|
|
Message string `json:"message"`
|
|
Type string `json:"type,omitempty"`
|
|
}
|
|
|
|
// EventParams is the parameter object for an `event` notification. Type is the
|
|
// event discriminant (an agentcore.Event* value); Data carries a small,
|
|
// wire-safe payload for that event (never secrets — see plugin.EventData).
|
|
type EventParams struct {
|
|
Type string `json:"type"`
|
|
Data json.RawMessage `json:"data,omitempty"`
|
|
}
|