first commit

pigo/internal/plugin/manifest.go

@@ -0,0 +1,111 @@
+// 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"`
+}