Documentation
¶
Overview ¶
Package sdk provides a thin Go SDK for writing Overkill plugins.
A minimal plugin looks like:
func main() {
p := sdk.New(sdk.Manifest{
Name: "hello", Version: "0.1.0",
})
p.OnTool("greet", func(ctx context.Context, args json.RawMessage) (any, error) {
return map[string]string{"text": "hi!"}, nil
})
p.RegisterTool(sdk.ToolDecl{Name: "greet", Description: "say hi"})
p.Run()
}
The SDK speaks JSON-RPC 2.0 over stdio. It mirrors the wire format used by internal/plugin in the host so plugin authors don't need to read the host source.
Index ¶
- type CommandDecl
- type CommandHandler
- type ContextHandler
- type ContextSnippet
- type EventHandler
- type Manifest
- type Permissions
- type Plugin
- func (p *Plugin) Config(ctx context.Context, key string) (any, error)
- func (p *Plugin) OnCommand(id string, h CommandHandler)
- func (p *Plugin) OnContext(h ContextHandler)
- func (p *Plugin) OnEvent(h EventHandler)
- func (p *Plugin) OnTool(name string, h ToolHandler)
- func (p *Plugin) RegisterCommand(c CommandDecl)
- func (p *Plugin) RegisterTool(t ToolDecl)
- func (p *Plugin) Run() error
- func (p *Plugin) Session(ctx context.Context) (SessionInfo, error)
- func (p *Plugin) Subscribe(event string)
- func (p *Plugin) Toast(ctx context.Context, kind, text string) error
- type SessionInfo
- type ToolDecl
- type ToolHandler
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CommandDecl ¶
type CommandDecl struct {
ID string `json:"id"`
Title string `json:"title"`
Description string `json:"description,omitempty"`
}
CommandDecl is the schema sent via host.register_command.
type CommandHandler ¶
CommandHandler runs a /command invocation.
type ContextHandler ¶
type ContextHandler func(ctx context.Context, promptSoFar, sessionID string) []ContextSnippet
ContextHandler is called before each prompt to provide context snippets.
type ContextSnippet ¶
ContextSnippet is one item returned from a context provider.
type EventHandler ¶
type EventHandler func(payload json.RawMessage)
EventHandler is called when the host fires a subscribed event.
type Manifest ¶
type Manifest struct {
Name string `json:"name"`
Version string `json:"version"`
Description string `json:"description,omitempty"`
Permissions Permissions `json:"permissions"`
}
Manifest is what the plugin returns from plugin.initialize.
type Permissions ¶
type Permissions struct {
ConfigKeys []string `json:"config_keys,omitempty"`
ToolsCall []string `json:"tools_call,omitempty"`
Events []string `json:"events,omitempty"`
}
Permissions is the declared scope of host capabilities the plugin needs.
type Plugin ¶
type Plugin struct {
// contains filtered or unexported fields
}
Plugin is the public type plugin authors interact with.
func (*Plugin) OnCommand ¶
func (p *Plugin) OnCommand(id string, h CommandHandler)
func (*Plugin) OnContext ¶
func (p *Plugin) OnContext(h ContextHandler)
OnContext registers a context provider.
func (*Plugin) OnEvent ¶
func (p *Plugin) OnEvent(h EventHandler)
func (*Plugin) OnTool ¶
func (p *Plugin) OnTool(name string, h ToolHandler)
func (*Plugin) RegisterCommand ¶
func (p *Plugin) RegisterCommand(c CommandDecl)
RegisterCommand declares a slash-command. Pair with OnCommand.
func (*Plugin) RegisterTool ¶
RegisterTool declares a tool. Pair with OnTool to handle invocations.
func (*Plugin) Session ¶
func (p *Plugin) Session(ctx context.Context) (SessionInfo, error)
Session fetches the current session info from the host.
type SessionInfo ¶
type SessionInfo struct {
ID string `json:"id"`
Title string `json:"title"`
MessageCount int `json:"message_count"`
}
SessionInfo is what host.session_get returns.
type ToolDecl ¶
type ToolDecl struct {
Name string `json:"name"`
Description string `json:"description,omitempty"`
ArgsSchema json.RawMessage `json:"args_schema,omitempty"`
RiskLevel string `json:"risk_level,omitempty"`
}
ToolDecl is the schema sent via host.register_tool.
type ToolHandler ¶
ToolHandler runs a tool invocation. Return either the result value or an error; the SDK serializes both.
Source Files