extensions

import "github.com/goppydae/sharur/extensions"

Index

func LoadErrors

func LoadErrors(errs []error) error

LoadErrors joins all errors from a Load call into a single error, or nil if there were none.

func Serve

func Serve(impl Plugin)

Serve starts a gRPC server on the Unix socket path provided via SHARUR_SOCKET_PATH. This is the entry point for extension binaries.

type AgentState

AgentState is the mutable prompt state passed to BeforePrompt.

type AgentState struct {
    SystemPrompt  string
    Model         string
    Provider      string
    ThinkingLevel string
}

type GRPCClient

GRPCClient is an implementation of agent.Extension that talks over RPC. It runs on the host side when a plugin binary is loaded.

If Name() or Tools() fail, the client is marked degraded and all subsequent tool executions return an error rather than silently doing nothing.

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

func (*GRPCClient) AfterCompact

func (m *GRPCClient) AfterCompact(ctx context.Context, freedTokens int)

func (*GRPCClient) AfterProviderResponse

func (m *GRPCClient) AfterProviderResponse(ctx context.Context, content string, numToolCalls int)

func (*GRPCClient) AfterToolCall

func (m *GRPCClient) AfterToolCall(ctx context.Context, call *agent.ToolCall, result *tools.ToolResult) *tools.ToolResult

func (*GRPCClient) AgentEnd

func (m *GRPCClient) AgentEnd(ctx context.Context)

func (*GRPCClient) AgentStart

func (m *GRPCClient) AgentStart(ctx context.Context)

func (*GRPCClient) BeforeCompact

func (m *GRPCClient) BeforeCompact(ctx context.Context, prep agent.CompactionPrep) *agent.CompactionResult

func (*GRPCClient) BeforePrompt

func (m *GRPCClient) BeforePrompt(ctx context.Context, state *agent.AgentState) *agent.AgentState

func (*GRPCClient) BeforeProviderRequest

func (m *GRPCClient) BeforeProviderRequest(ctx context.Context, req *llm.CompletionRequest) *llm.CompletionRequest

func (*GRPCClient) BeforeToolCall

func (m *GRPCClient) BeforeToolCall(ctx context.Context, call *agent.ToolCall, args json.RawMessage) (*tools.ToolResult, bool)

func (*GRPCClient) Degraded

func (m *GRPCClient) Degraded() (bool, error)

Degraded reports whether the extension failed to initialise. Callers can surface this to the user rather than letting the failure be silent.

func (*GRPCClient) ModifyContext

func (m *GRPCClient) ModifyContext(ctx context.Context, messages []types.Message) []types.Message

func (*GRPCClient) ModifyInput

func (m *GRPCClient) ModifyInput(ctx context.Context, text string) agent.InputResult

func (*GRPCClient) ModifySystemPrompt

func (m *GRPCClient) ModifySystemPrompt(prompt string) string

func (*GRPCClient) Name

func (m *GRPCClient) Name() string

func (*GRPCClient) SessionEnd

func (m *GRPCClient) SessionEnd(ctx context.Context, sessionID string, reason agent.SessionEndReason)

func (*GRPCClient) SessionStart

func (m *GRPCClient) SessionStart(ctx context.Context, sessionID string, reason agent.SessionStartReason)

func (*GRPCClient) Tools

func (m *GRPCClient) Tools() []tools.Tool

Tools queries the extension process for its tool definitions and returns RemoteTool wrappers that execute each tool over the ExecuteTool RPC.

func (*GRPCClient) TurnEnd

func (m *GRPCClient) TurnEnd(ctx context.Context)

func (*GRPCClient) TurnStart

func (m *GRPCClient) TurnStart(ctx context.Context)

type GRPCServer

GRPCServer is the gRPC server that runs inside the plugin binary. It adapts the Plugin interface to the proto service.

type GRPCServer struct {
    proto.UnimplementedExtensionServer
    Impl Plugin
}

func (*GRPCServer) AfterCompact

func (m *GRPCServer) AfterCompact(ctx context.Context, req *proto.AfterCompactRequest) (*proto.Empty, error)

func (*GRPCServer) AfterProviderResponse

func (m *GRPCServer) AfterProviderResponse(ctx context.Context, req *proto.AfterProviderResponseRequest) (*proto.Empty, error)

func (*GRPCServer) AfterToolCall

func (m *GRPCServer) AfterToolCall(ctx context.Context, req *proto.AfterToolCallRequest) (*proto.AfterToolCallResponse, error)

func (*GRPCServer) AgentEnd

func (m *GRPCServer) AgentEnd(ctx context.Context, _ *proto.Empty) (*proto.Empty, error)

func (*GRPCServer) AgentStart

func (m *GRPCServer) AgentStart(ctx context.Context, _ *proto.Empty) (*proto.Empty, error)

func (*GRPCServer) BeforeCompact

func (m *GRPCServer) BeforeCompact(ctx context.Context, req *proto.BeforeCompactRequest) (*proto.BeforeCompactResponse, error)

func (*GRPCServer) BeforePrompt

func (m *GRPCServer) BeforePrompt(ctx context.Context, req *proto.BeforePromptRequest) (*proto.BeforePromptResponse, error)

func (*GRPCServer) BeforeProviderRequest

func (m *GRPCServer) BeforeProviderRequest(ctx context.Context, req *proto.BeforeProviderRequestRequest) (*proto.BeforeProviderRequestResponse, error)

func (*GRPCServer) BeforeToolCall

func (m *GRPCServer) BeforeToolCall(ctx context.Context, req *proto.BeforeToolCallRequest) (*proto.BeforeToolCallResponse, error)

func (*GRPCServer) ExecuteTool

func (m *GRPCServer) ExecuteTool(ctx context.Context, req *proto.ExecuteToolRequest) (*proto.ExecuteToolResponse, error)

func (*GRPCServer) ModifyContext

func (m *GRPCServer) ModifyContext(ctx context.Context, req *proto.ModifyContextRequest) (*proto.ModifyContextResponse, error)

func (*GRPCServer) ModifyInput

func (m *GRPCServer) ModifyInput(ctx context.Context, req *proto.ModifyInputRequest) (*proto.ModifyInputResponse, error)

func (*GRPCServer) ModifySystemPrompt

func (m *GRPCServer) ModifySystemPrompt(ctx context.Context, req *proto.ModifySystemPromptRequest) (*proto.ModifySystemPromptResponse, error)

func (*GRPCServer) Name

func (m *GRPCServer) Name(ctx context.Context, _ *proto.Empty) (*proto.NameResponse, error)

func (*GRPCServer) SessionEnd

func (m *GRPCServer) SessionEnd(ctx context.Context, req *proto.SessionEndRequest) (*proto.Empty, error)

func (*GRPCServer) SessionStart

func (m *GRPCServer) SessionStart(ctx context.Context, req *proto.SessionStartRequest) (*proto.Empty, error)

func (*GRPCServer) Tools

func (m *GRPCServer) Tools(ctx context.Context, _ *proto.Empty) (*proto.ToolsResponse, error)

func (*GRPCServer) TurnEnd

func (m *GRPCServer) TurnEnd(ctx context.Context, _ *proto.Empty) (*proto.Empty, error)

func (*GRPCServer) TurnStart

func (m *GRPCServer) TurnStart(ctx context.Context, _ *proto.Empty) (*proto.Empty, error)

type Loader

Loader discovers and loads extensions (executable binaries and scripts).

type Loader struct {
    Dirs       []string
    PythonPath string
    // contains filtered or unexported fields
}

func NewLoader

func NewLoader(dirs []string, pythonPath string) *Loader

NewLoader creates a new extension loader.

func (*Loader) Cleanup

func (l *Loader) Cleanup()

Cleanup kills all running extension subprocesses and removes their socket files.

func (*Loader) Load

func (l *Loader) Load() ([]agent.Extension, []error)

Load discovers extensions, starts them as subprocesses, and returns gRPC client interfaces. Extensions that fail to load are logged and skipped; the returned error accumulates all failures so callers can distinguish “nothing loaded” from “everything succeeded”.

func (*Loader) LoadOrLog

func (l *Loader) LoadOrLog() []agent.Extension

LoadOrLog calls Load and logs any errors, returning only the successfully loaded extensions.

type NoopPlugin

NoopPlugin is a base Plugin implementation with no-op defaults. Embed it in your Plugin struct and override only what you need.

type NoopPlugin struct {
    NameStr string
}

func (*NoopPlugin) AfterCompact

func (n *NoopPlugin) AfterCompact(_ context.Context, _ int)

func (*NoopPlugin) AfterProviderResponse

func (n *NoopPlugin) AfterProviderResponse(_ context.Context, _ string, _ int)

func (*NoopPlugin) AfterToolCall

func (n *NoopPlugin) AfterToolCall(_ context.Context, _ ToolCall, result ToolResult) ToolResult

func (*NoopPlugin) AgentEnd

func (n *NoopPlugin) AgentEnd(_ context.Context)

func (*NoopPlugin) AgentStart

func (n *NoopPlugin) AgentStart(_ context.Context)

func (*NoopPlugin) BeforeCompact

func (n *NoopPlugin) BeforeCompact(_ context.Context, _ agent.CompactionPrep) *agent.CompactionResult

func (*NoopPlugin) BeforePrompt

func (n *NoopPlugin) BeforePrompt(_ context.Context, state AgentState) AgentState

func (*NoopPlugin) BeforeProviderRequest

func (n *NoopPlugin) BeforeProviderRequest(_ context.Context, requestJSON string) string

func (*NoopPlugin) BeforeToolCall

func (n *NoopPlugin) BeforeToolCall(_ context.Context, _ ToolCall, _ json.RawMessage) (ToolResult, bool)

func (*NoopPlugin) ExecuteTool

func (n *NoopPlugin) ExecuteTool(_ context.Context, name string, _ json.RawMessage) ToolResult

func (*NoopPlugin) ModifyContext

func (n *NoopPlugin) ModifyContext(_ context.Context, messagesJSON string) string

func (*NoopPlugin) ModifyInput

func (n *NoopPlugin) ModifyInput(_ context.Context, _ string) agent.InputResult

func (*NoopPlugin) ModifySystemPrompt

func (n *NoopPlugin) ModifySystemPrompt(prompt string) string

func (*NoopPlugin) Name

func (n *NoopPlugin) Name() string

func (*NoopPlugin) SessionEnd

func (n *NoopPlugin) SessionEnd(_ context.Context, _ string, _ agent.SessionEndReason)

func (*NoopPlugin) SessionStart

func (n *NoopPlugin) SessionStart(_ context.Context, _ string, _ agent.SessionStartReason)

func (*NoopPlugin) Tools

func (n *NoopPlugin) Tools() []ToolDefinition

func (*NoopPlugin) TurnEnd

func (n *NoopPlugin) TurnEnd(_ context.Context)

func (*NoopPlugin) TurnStart

func (n *NoopPlugin) TurnStart(_ context.Context)

type Plugin

Plugin is the interface that standalone gRPC extension binaries implement. Embed NoopPlugin and override only the methods you need.

type Plugin interface {
    Name() string
    Tools() []ToolDefinition
    ExecuteTool(ctx context.Context, name string, args json.RawMessage) ToolResult
    BeforePrompt(ctx context.Context, state AgentState) AgentState
    BeforeToolCall(ctx context.Context, call ToolCall, args json.RawMessage) (ToolResult, bool)
    AfterToolCall(ctx context.Context, call ToolCall, result ToolResult) ToolResult
    ModifySystemPrompt(prompt string) string

    SessionStart(ctx context.Context, sessionID string, reason agent.SessionStartReason)
    SessionEnd(ctx context.Context, sessionID string, reason agent.SessionEndReason)
    AgentStart(ctx context.Context)
    AgentEnd(ctx context.Context)
    TurnStart(ctx context.Context)
    TurnEnd(ctx context.Context)
    ModifyInput(ctx context.Context, text string) agent.InputResult
    ModifyContext(ctx context.Context, messagesJSON string) string
    BeforeProviderRequest(ctx context.Context, requestJSON string) string
    AfterProviderResponse(ctx context.Context, content string, numToolCalls int)
    BeforeCompact(ctx context.Context, prep agent.CompactionPrep) *agent.CompactionResult
    AfterCompact(ctx context.Context, freedTokens int)
}

type RemoteTool

RemoteTool is a tools.Tool that executes over the extension’s ExecuteTool gRPC.

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

func (*RemoteTool) Description

func (t *RemoteTool) Description() string

func (*RemoteTool) Execute

func (t *RemoteTool) Execute(ctx context.Context, args json.RawMessage, update tools.ToolUpdate) (*tools.ToolResult, error)

func (*RemoteTool) IsReadOnly

func (t *RemoteTool) IsReadOnly() bool

func (*RemoteTool) Name

func (t *RemoteTool) Name() string

func (*RemoteTool) Schema

func (t *RemoteTool) Schema() json.RawMessage

type SkillLoader

SkillLoader discovers and loads Markdown-based skills.

type SkillLoader struct {
    Dirs []string
}

func NewSkillLoader

func NewSkillLoader(dirs []string) *SkillLoader

NewSkillLoader creates a new loader for Markdown skills.

func (*SkillLoader) Load

func (l *SkillLoader) Load() ([]agent.Extension, error)

Load finds all skills and returns a SkillsMetadataExtension.

type SkillTool

SkillTool implements tools.Tool for a single Markdown-based skill.

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

func (*SkillTool) Description

func (s *SkillTool) Description() string

func (*SkillTool) Execute

func (s *SkillTool) Execute(ctx context.Context, args json.RawMessage, update tools.ToolUpdate) (*tools.ToolResult, error)

func (*SkillTool) IsReadOnly

func (s *SkillTool) IsReadOnly() bool

func (*SkillTool) Name

func (s *SkillTool) Name() string

func (*SkillTool) Schema

func (s *SkillTool) Schema() json.RawMessage

type SkillsMetadataExtension

SkillsMetadataExtension lists all available skills in the system prompt.

type SkillsMetadataExtension struct {
    agent.NoopExtension
    // contains filtered or unexported fields
}

func NewSkillsMetadataExtension

func NewSkillsMetadataExtension(allSkills []*skills.Skill) *SkillsMetadataExtension

NewSkillsMetadataExtension creates an extension that adds skill metadata to the prompt.

func (*SkillsMetadataExtension) ModifySystemPrompt

func (s *SkillsMetadataExtension) ModifySystemPrompt(prompt string) string

ModifySystemPrompt injects a brief list of skills into the system prompt. This tells the agent it can call these skills (as tools) when needed.

func (*SkillsMetadataExtension) Tools

func (s *SkillsMetadataExtension) Tools() []tools.Tool

Tools returns a SkillTool for each loaded skill.

type ToolCall

ToolCall describes a tool invocation passed to Plugin hook methods.

type ToolCall struct {
    Name string
    Args json.RawMessage
}

type ToolDefinition

ToolDefinition describes a tool contributed by a Plugin.

type ToolDefinition struct {
    Name        string
    Description string
    Schema      json.RawMessage
    IsReadOnly  bool
}

type ToolResult

ToolResult is the outcome of a tool call or an interception.

type ToolResult struct {
    Content string
    IsError bool
}

Generated by gomarkdoc