agent import "github.com/goppydae/sharur/internal/agent" Package agent provides the stateful agent with transcript, tools, and events.
Index Constants func EstimateMessageTokens(m Message) int type Agent func New(provider llm.Provider, registry *tools.ToolRegistry) *Agent func (a *Agent) Abort() func (a *Agent) Compact(ctx context.Context, keepRecentTokens int) func (a *Agent) Continue(ctx context.Context) error func (a *Agent) EstimateContextTokens() int func (a *Agent) EventBus() *events.EventBus func (a *Agent) FollowUp(text string, images …Image) func (a *Agent) GetInfo() llm.ProviderInfo func (a *Agent) GetSession() *types.Session func (a *Agent) GetStats() AgentStats func (a *Agent) Idle() <-chan struct{} func (a *Agent) InvokeTool(ctx context.Context, name string, args string) error func (a *Agent) IsRunning() bool func (a *Agent) LifecycleState() string func (a *Agent) Messages() []Message func (a *Agent) Prompt(ctx context.Context, text string, images …Image) error func (a *Agent) Reset() func (a *Agent) ResetSession(id string) func (a *Agent) Session() *session.Session func (a *Agent) SetCompactionConfig(enabled bool, reserve, keepRecent int) func (a *Agent) SetDryRun(dry bool) func (a *Agent) SetExtensions(exts []Extension) func (a *Agent) SetMaxTokens(n int) func (a *Agent) SetModel(model string) func (a *Agent) SetProvider(provider llm.Provider) func (a *Agent) SetSession(mgr *session.Manager, sess *session.Session) func (a *Agent) SetSessionName(name string) func (a *Agent) SetSystemPrompt(prompt string) func (a *Agent) SetThinkingLevel(level ThinkingLevel) func (a *Agent) State() *AgentState func (a *Agent) Steer(text string, images …Image) func (a *Agent) Subscribe(fn func(Event)) func() func (a *Agent) ToolRegistry() *tools.ToolRegistry type AgentState type AgentStats type CompactionPrep type CompactionResult type Event type EventType type Extension type Image type InputAction type InputResult type LifecycleState type Message type NoopExtension func (n *NoopExtension) AfterCompact(_ context.Context, _ int) func (n *NoopExtension) AfterProviderResponse(_ context.Context, _ string, _ int) func (n *NoopExtension) AfterToolCall(_ context.Context, _ *ToolCall, result *tools.ToolResult) *tools.ToolResult func (n *NoopExtension) AgentEnd(_ context.Context) func (n *NoopExtension) AgentStart(_ context.Context) func (n *NoopExtension) BeforeCompact(_ context.Context, _ CompactionPrep) *CompactionResult func (n *NoopExtension) BeforePrompt(_ context.Context, state *AgentState) *AgentState func (n *NoopExtension) BeforeProviderRequest(_ context.Context, req *llm.CompletionRequest) *llm.CompletionRequest func (n *NoopExtension) BeforeToolCall(_ context.Context, _ *ToolCall, _ json.RawMessage) (*tools.ToolResult, bool) func (n *NoopExtension) ModifyContext(_ context.Context, messages []types.Message) []types.Message func (n *NoopExtension) ModifyInput(_ context.Context, _ string) InputResult func (n *NoopExtension) ModifySystemPrompt(prompt string) string func (n *NoopExtension) Name() string func (n *NoopExtension) SessionEnd(_ context.Context, _ string, _ SessionEndReason) func (n *NoopExtension) SessionStart(_ context.Context, _ string, _ SessionStartReason) func (n *NoopExtension) Tools() []tools.Tool func (n *NoopExtension) TurnEnd(_ context.Context) func (n *NoopExtension) TurnStart(_ context.Context) type Session type SessionEndReason type SessionStartReason type StateMachine type StateTransition type ThinkingLevel type ToolCall type ToolInfo type ToolOutput Constants
const (
ThinkingOff = types . ThinkingOff
ThinkingLow = types . ThinkingLow
ThinkingMedium = types . ThinkingMedium
ThinkingHigh = types . ThinkingHigh
)
const SUMMARIZATION_PROMPT = `The messages above are a conversation to summarize. Create a structured context checkpoint summary that another LLM will use to continue the work.
Start your response with the exact string: <!-- sharur-summary -->
Then use this EXACT format:
## Goal
[What is the user trying to accomplish? Can be multiple items if the session covers different tasks.]
## Constraints & Preferences
- [Any constraints, preferences, or requirements mentioned by user]
- [Or "(none)" if none were mentioned]
## Progress
### Done
- [x] [Completed tasks/changes]
### In Progress
- [ ] [Current work]
### Blocked
- [Issues preventing progress, if any]
## Key Decisions
- **[Decision]**: [Brief rationale]
## Next Steps
1. [Ordered list of what should happen next]
## Critical Context
- [Any data, examples, or references needed to continue]
- [Or "(none)" if not applicable]
Keep each section concise. Preserve exact file paths, function names, and error messages.`
const TURN_PREFIX_SUMMARIZATION_PROMPT = `This is the PREFIX of a turn that was too large to keep. The SUFFIX (recent work) is retained.
Summarize the prefix to provide context for the retained suffix:
## Original Request
[What did the user ask for in this turn?]
## Early Progress
- [Key decisions and work done in the prefix]
## Context for Suffix
- [Information needed to understand the retained recent work]
Be concise. Focus on what's needed to understand the kept suffix.`
const UPDATE_SUMMARIZATION_PROMPT = `The messages above are NEW conversation messages to incorporate into the existing summary provided in <previous-summary> tags.
Start your response with the exact string: <!-- sharur-summary -->
Update the existing structured summary with new information. RULES:
- PRESERVE all existing information from the previous summary
- ADD new progress, decisions, and context from the new messages
- UPDATE the Progress section: move items from "In Progress" to "Done" when completed
- UPDATE "Next Steps" based on what was accomplished
- PRESERVE exact file paths, function names, and error messages
- If something is no longer relevant, you may remove it
Use this EXACT format:
## Goal
[Preserve existing goals, add new ones if the task expanded]
## Constraints & Preferences
- [Preserve existing, add new ones discovered]
## Progress
### Done
- [x] [Include previously done items AND newly completed items]
### In Progress
- [ ] [Current work - update based on progress]
### Blocked
- [Current blockers - remove if resolved]
## Key Decisions
- **[Decision]**: [Brief rationale] (preserve all previous, add new)
## Next Steps
1. [Update based on current state]
## Critical Context
- [Preserve important context, add new if needed]
Keep each section concise. Preserve exact file paths, function names, and error messages.`
func EstimateMessageTokens func EstimateMessageTokens ( m Message ) int
type Agent Agent owns the transcript, emits events, and executes tools.
type Agent struct {
// contains filtered or unexported fields
}
func New func New ( provider llm . Provider , registry * tools . ToolRegistry ) * Agent New creates a new agent with the given provider and tools.
func (*Agent) Abort Abort signals the agent to stop the current turn.
func (*Agent) Compact func ( a * Agent ) Compact ( ctx context . Context , keepRecentTokens int ) Compact trims the transcript to stay within approximate token budgets. It implements a pi-mono style summarization and file tracking strategy.
func (*Agent) Continue func ( a * Agent ) Continue ( ctx context . Context ) error Continue asks the agent to continue generating.
func (*Agent) EstimateContextTokens func ( a * Agent ) EstimateContextTokens () int EstimateContextTokens returns the estimated total tokens in the current context.
func (*Agent) EventBus func ( a * Agent ) EventBus () * events . EventBus EventBus returns the event bus.
func (*Agent) FollowUp func ( a * Agent ) FollowUp ( text string , images ... Image ) FollowUp queues a follow-up message to be processed after the agent finishes.
func (*Agent) GetInfo func ( a * Agent ) GetInfo () llm . ProviderInfo GetInfo returns the current model’s provider info.
func (*Agent) GetSession func ( a * Agent ) GetSession () * types . Session GetSession returns a copy of the current session types.
func (*Agent) GetStats func ( a * Agent ) GetStats () AgentStats GetStats returns token usage statistics from the agent’s events.
func (*Agent) Idle func ( a * Agent ) Idle () <- chan struct {} Idle returns a channel that closes when the agent is idle.
func ( a * Agent ) InvokeTool ( ctx context . Context , name string , args string ) error InvokeTool manually triggers a tool call as if it came from the assistant. It executes the tool, records the result, and then starts the agent loop to allow the LLM to react to the invocation.
func (*Agent) IsRunning func ( a * Agent ) IsRunning () bool IsRunning reports whether the agent is currently processing.
func (*Agent) LifecycleState func ( a * Agent ) LifecycleState () string LifecycleState returns the current lifecycle state as a string.
func (*Agent) Messages func ( a * Agent ) Messages () [] Message Messages returns a copy of the conversation messages.
func (*Agent) Prompt func ( a * Agent ) Prompt ( ctx context . Context , text string , images ... Image ) error Prompt sends a user message and runs the agent loop until idle.
func (*Agent) Reset Reset clears the conversation history and queues.
func (*Agent) ResetSession func ( a * Agent ) ResetSession ( id string ) ResetSession clears messages, queues and creates a fresh session ID.
func (*Agent) Session func ( a * Agent ) Session () * session . Session Session returns the current session object.
func (*Agent) SetCompactionConfig func ( a * Agent ) SetCompactionConfig ( enabled bool , reserve , keepRecent int ) SetCompactionConfig updates the compaction settings.
func (*Agent) SetDryRun func ( a * Agent ) SetDryRun ( dry bool ) SetDryRun sets the agent’s dry-run mode.
func (*Agent) SetExtensions func ( a * Agent ) SetExtensions ( exts [] Extension ) SetExtensions sets the active extensions for the agent.
func (*Agent) SetMaxTokens func ( a * Agent ) SetMaxTokens ( n int ) SetMaxTokens sets the maximum tokens for LLM responses.
func (*Agent) SetModel func ( a * Agent ) SetModel ( model string ) SetModel sets the model name and records it in the session if manager is present.
func (*Agent) SetProvider func ( a * Agent ) SetProvider ( provider llm . Provider ) SetProvider sets the LLM provider and records it in the session if manager is present.
func (*Agent) SetSession func ( a * Agent ) SetSession ( mgr * session . Manager , sess * session . Session ) SetSession attaches a session manager and session to the agent.
func (*Agent) SetSessionName func ( a * Agent ) SetSessionName ( name string ) SetSessionName sets a human-readable name for the current session.
func (*Agent) SetSystemPrompt func ( a * Agent ) SetSystemPrompt ( prompt string ) SetSystemPrompt updates the system prompt.
func (*Agent) SetThinkingLevel func ( a * Agent ) SetThinkingLevel ( level ThinkingLevel ) SetThinkingLevel sets the thinking level and records it in the session if manager is present.
func (*Agent) State func ( a * Agent ) State () * AgentState State returns a copy of the current agent state.
func (*Agent) Steer func ( a * Agent ) Steer ( text string , images ... Image ) Steer queues a steering message to be injected as soon as the current tool execution finishes.
func (*Agent) Subscribe func ( a * Agent ) Subscribe ( fn func ( Event )) func () Subscribe registers an event listener and returns an unsubscribe function.
func ( a * Agent ) ToolRegistry () * tools . ToolRegistry ToolRegistry returns the tool registry.
type AgentState AgentState holds the full state of an agent instance.
type AgentState struct {
Session Session `json:"session"`
SystemPrompt string `json:"systemPrompt"`
Messages [] Message `json:"messages"`
SteerQueue [] Message `json:"steerQueue,omitempty"`
FollowUpQueue [] Message `json:"followUpQueue,omitempty"`
Tools [] ToolInfo `json:"tools,omitempty"`
Model string `json:"model"`
Provider string `json:"provider"`
Thinking ThinkingLevel `json:"thinkingLevel"`
MaxTokens int `json:"maxTokens,omitempty"`
Temperature float64 `json:"temperature,omitempty"`
DryRun bool `json:"dryRun,omitempty"`
Compaction struct {
Enabled bool `json:"enabled"`
ReserveTokens int `json:"reserveTokens"`
KeepRecentTokens int `json:"keepRecentTokens"`
} `json:"compaction"`
LatestCompaction * types . CompactionState `json:"latestCompaction,omitempty"`
}
type AgentStats AgentStats holds session statistics.
type AgentStats struct {
SessionID string
ParentID string
SessionFile string
Name string
CreatedAt time . Time
UpdatedAt time . Time
Model string
Provider string
Thinking string
UserMessages int
AssistantMsgs int
ToolCalls int
ToolResults int
TotalMessages int
InputTokens int
OutputTokens int
CacheRead int
CacheWrite int
TotalTokens int
ContextTokens int
ContextWindow int
Cost float64
QueuedSteer int
QueuedFollowUp int
}
type CompactionPrep CompactionPrep describes the state passed to BeforeCompact.
type CompactionPrep struct {
MessageCount int
EstimatedTokens int
PreviousSummary string
}
type CompactionResult CompactionResult can be returned by BeforeCompact to provide a custom summary and skip the default LLM-based summarization.
type CompactionResult struct {
Summary string
FirstKeptEntryID string
}
type Event Event represents an agent lifecycle event.
type Event struct {
Type EventType
Content string
ToolCall * ToolCall
Usage * llm . Usage
Error error
// ToolOutput stores the result content of a tool execution.
// Emitted when type is EventToolOutput.
ToolOutput * ToolOutput
// StateChange holds details of a lifecycle state transition.
// Emitted when type is EventStateChange.
StateChange * StateTransition
// Value stores a numeric value (e.g. token count).
// Emitted when type is EventTokens.
Value int64
}
type EventType EventType identifies the kind of agent event.
const (
EventAgentStart EventType = "agent_start"
EventTurnStart EventType = "turn_start"
EventMessageStart EventType = "message_start"
EventTextDelta EventType = "text_delta"
EventThinkingDelta EventType = "thinking_delta"
EventToolCall EventType = "tool_call"
EventToolDelta EventType = "tool_delta"
EventToolOutput EventType = "tool_output"
EventMessageEnd EventType = "message_end"
EventAgentEnd EventType = "agent_end"
EventError EventType = "error"
EventAbort EventType = "abort"
EventQueueUpdate EventType = "queue_update"
EventCompactStart EventType = "compact_start"
EventCompactEnd EventType = "compact_end"
EventStateChange EventType = "state_change"
EventTokens EventType = "tokens"
EventHeartbeat EventType = "heartbeat"
)
type Extension Extension is the unified interface for all extensions (gRPC plugins, Markdown Skills, etc.)
type Extension interface {
// Name returns the extension's unique identifier.
Name () string
// Tools returns additional tools to register with the agent.
Tools () [] tools . Tool
// BeforePrompt is called before each LLM request.
// Return a modified state to change the request.
BeforePrompt ( ctx context . Context , state * AgentState ) * AgentState
// BeforeToolCall is called before each tool execution.
// Return (result, true) to intercept and prevent the tool from running.
// Return (nil, false) to allow normal execution.
BeforeToolCall ( ctx context . Context , call * ToolCall , args json . RawMessage ) ( * tools . ToolResult , bool )
// AfterToolCall is called after each tool call completes.
// Return a modified result to change the outcome.
AfterToolCall ( ctx context . Context , call * ToolCall , result * tools . ToolResult ) * tools . ToolResult
// ModifySystemPrompt is called to augment the system prompt.
ModifySystemPrompt ( prompt string ) string
// SessionStart is called when a session is attached or the first prompt begins.
SessionStart ( ctx context . Context , sessionID string , reason SessionStartReason )
// SessionEnd is called when a session is reset or the agent is torn down.
SessionEnd ( ctx context . Context , sessionID string , reason SessionEndReason )
// AgentStart is called when the agent begins processing a user prompt.
AgentStart ( ctx context . Context )
// AgentEnd is called when the agent loop finishes (success, error, or abort).
AgentEnd ( ctx context . Context )
// TurnStart is called at the start of each LLM request turn.
TurnStart ( ctx context . Context )
// TurnEnd is called after each turn's tool calls have been processed.
TurnEnd ( ctx context . Context )
// ModifyInput is called with raw user input before it is added to the transcript.
// Return InputHandled to consume the message without further processing.
// Return InputTransform to replace the text.
// Return InputContinue (or zero value) to proceed unchanged.
ModifyInput ( ctx context . Context , text string ) InputResult
// ModifyContext is called with the message slice just before building each LLM
// request. The returned slice replaces what is sent to the LLM (not the stored
// transcript). Extensions are chained; each receives the previous result.
ModifyContext ( ctx context . Context , messages [] types . Message ) [] types . Message
// BeforeProviderRequest is called with the assembled CompletionRequest before
// it is sent to the LLM provider. Return a modified copy to alter the request.
BeforeProviderRequest ( ctx context . Context , req * llm . CompletionRequest ) * llm . CompletionRequest
// AfterProviderResponse is called after the LLM stream is fully consumed.
AfterProviderResponse ( ctx context . Context , content string , numToolCalls int )
// BeforeCompact is called before the compaction summarization LLM call.
// Return a non-nil *CompactionResult to provide a custom summary and skip the
// default LLM-based summarization entirely.
BeforeCompact ( ctx context . Context , prep CompactionPrep ) * CompactionResult
// AfterCompact is called after compaction completes.
AfterCompact ( ctx context . Context , freedTokens int )
}
type Image Image is an alias for types.Image.
InputAction controls how ModifyInput’s result is applied.
const (
// InputContinue passes the original text through unchanged.
InputContinue InputAction = "continue"
// InputTransform replaces the user text with InputResult.Text.
InputTransform InputAction = "transform"
// InputHandled marks the input as consumed; the message is not appended to the transcript.
InputHandled InputAction = "handled"
)
InputResult is returned by ModifyInput to describe how to process the user input.
type InputResult struct {
Action InputAction
Text string
}
type LifecycleState LifecycleState identifies the current operational state of the agent.
type LifecycleState string
const (
StateIdle LifecycleState = "idle"
StateThinking LifecycleState = "thinking"
StateExecuting LifecycleState = "executing"
StateCompacting LifecycleState = "compacting"
StateAborting LifecycleState = "aborting"
StateError LifecycleState = "error"
)
type Message Message is an alias for types.Message.
type Message = types . Message
type NoopExtension NoopExtension is an extension that does nothing — useful as a base embed.
type NoopExtension struct {
NameStr string
}
func (*NoopExtension) AfterCompact func ( n * NoopExtension ) AfterCompact ( _ context . Context , _ int )
func (*NoopExtension) AfterProviderResponse func ( n * NoopExtension ) AfterProviderResponse ( _ context . Context , _ string , _ int )
func ( n * NoopExtension ) AfterToolCall ( _ context . Context , _ * ToolCall , result * tools . ToolResult ) * tools . ToolResult
func (*NoopExtension) AgentEnd func ( n * NoopExtension ) AgentEnd ( _ context . Context )
func (*NoopExtension) AgentStart func ( n * NoopExtension ) AgentStart ( _ context . Context )
func (*NoopExtension) BeforeCompact func ( n * NoopExtension ) BeforeCompact ( _ context . Context , _ CompactionPrep ) * CompactionResult
func (*NoopExtension) BeforePrompt func ( n * NoopExtension ) BeforePrompt ( _ context . Context , state * AgentState ) * AgentState
func (*NoopExtension) BeforeProviderRequest func ( n * NoopExtension ) BeforeProviderRequest ( _ context . Context , req * llm . CompletionRequest ) * llm . CompletionRequest
func ( n * NoopExtension ) BeforeToolCall ( _ context . Context , _ * ToolCall , _ json . RawMessage ) ( * tools . ToolResult , bool )
func (*NoopExtension) ModifyContext func ( n * NoopExtension ) ModifyContext ( _ context . Context , messages [] types . Message ) [] types . Message
func ( n * NoopExtension ) ModifyInput ( _ context . Context , _ string ) InputResult
func (*NoopExtension) ModifySystemPrompt func ( n * NoopExtension ) ModifySystemPrompt ( prompt string ) string
func (*NoopExtension) Name func ( n * NoopExtension ) Name () string
func (*NoopExtension) SessionEnd func ( n * NoopExtension ) SessionEnd ( _ context . Context , _ string , _ SessionEndReason )
func (*NoopExtension) SessionStart func ( n * NoopExtension ) SessionStart ( _ context . Context , _ string , _ SessionStartReason )
func ( n * NoopExtension ) Tools () [] tools . Tool
func (*NoopExtension) TurnEnd func ( n * NoopExtension ) TurnEnd ( _ context . Context )
func (*NoopExtension) TurnStart func ( n * NoopExtension ) TurnStart ( _ context . Context )
type Session Session is an alias for types.Session.
type Session = types . Session
type SessionEndReason SessionEndReason identifies why a session is ending.
type SessionEndReason string
const (
SessionEndReset SessionEndReason = "reset"
)
type SessionStartReason SessionStartReason identifies why a session is starting.
type SessionStartReason string
const (
SessionStartNew SessionStartReason = "new"
SessionStartResume SessionStartReason = "resume"
)
type StateMachine StateMachine manages agent states and transitions.
type StateMachine struct {
// contains filtered or unexported fields
}
func NewStateMachine func NewStateMachine ( initial LifecycleState , onTransition func ( StateTransition )) * StateMachine NewStateMachine creates a new state machine.
func (*StateMachine) Current func ( s * StateMachine ) Current () LifecycleState Current returns the current lifecycle state.
func (*StateMachine) Transition func ( s * StateMachine ) Transition ( to LifecycleState ) error Transition moves the state machine to a new state.
type StateTransition StateTransition represents a transition between two states.
type StateTransition struct {
From LifecycleState
To LifecycleState
}
type ThinkingLevel ThinkingLevel is an alias for types.ThinkingLevel.
type ThinkingLevel = types . ThinkingLevel
ToolCall is an alias for types.ToolCall.
type ToolCall = types . ToolCall
ToolInfo is an alias for types.ToolInfo.
type ToolInfo = types . ToolInfo
ToolOutput is an alias for types.ToolOutput.
type ToolOutput = types . ToolOutput Generated by gomarkdoc
extensions import "github.com/goppydae/sharur/extensions" Index func LoadErrors(errs []error) error func Serve(impl Plugin) type AgentState type GRPCClient func (m *GRPCClient) AfterCompact(ctx context.Context, freedTokens int) func (m *GRPCClient) AfterProviderResponse(ctx context.Context, content string, numToolCalls int) func (m *GRPCClient) AfterToolCall(ctx context.Context, call *agent.ToolCall, result *tools.ToolResult) *tools.ToolResult func (m *GRPCClient) AgentEnd(ctx context.Context) func (m *GRPCClient) AgentStart(ctx context.Context) func (m *GRPCClient) BeforeCompact(ctx context.Context, prep agent.CompactionPrep) *agent.CompactionResult func (m *GRPCClient) BeforePrompt(ctx context.Context, state *agent.AgentState) *agent.AgentState func (m *GRPCClient) BeforeProviderRequest(ctx context.Context, req *llm.CompletionRequest) *llm.CompletionRequest func (m *GRPCClient) BeforeToolCall(ctx context.Context, call *agent.ToolCall, args json.RawMessage) (*tools.ToolResult, bool) func (m *GRPCClient) Degraded() (bool, error) func (m *GRPCClient) ModifyContext(ctx context.Context, messages []types.Message) []types.Message func (m *GRPCClient) ModifyInput(ctx context.Context, text string) agent.InputResult func (m *GRPCClient) ModifySystemPrompt(prompt string) string func (m *GRPCClient) Name() string func (m *GRPCClient) SessionEnd(ctx context.Context, sessionID string, reason agent.SessionEndReason) func (m *GRPCClient) SessionStart(ctx context.Context, sessionID string, reason agent.SessionStartReason) func (m *GRPCClient) Tools() []tools.Tool func (m *GRPCClient) TurnEnd(ctx context.Context) func (m *GRPCClient) TurnStart(ctx context.Context) type GRPCServer func (m *GRPCServer) AfterCompact(ctx context.Context, req *proto.AfterCompactRequest) (*proto.Empty, error) func (m *GRPCServer) AfterProviderResponse(ctx context.Context, req *proto.AfterProviderResponseRequest) (*proto.Empty, error) func (m *GRPCServer) AfterToolCall(ctx context.Context, req *proto.AfterToolCallRequest) (*proto.AfterToolCallResponse, error) func (m *GRPCServer) AgentEnd(ctx context.Context, _ *proto.Empty) (*proto.Empty, error) func (m *GRPCServer) AgentStart(ctx context.Context, _ *proto.Empty) (*proto.Empty, error) func (m *GRPCServer) BeforeCompact(ctx context.Context, req *proto.BeforeCompactRequest) (*proto.BeforeCompactResponse, error) func (m *GRPCServer) BeforePrompt(ctx context.Context, req *proto.BeforePromptRequest) (*proto.BeforePromptResponse, error) func (m *GRPCServer) BeforeProviderRequest(ctx context.Context, req *proto.BeforeProviderRequestRequest) (*proto.BeforeProviderRequestResponse, error) func (m *GRPCServer) BeforeToolCall(ctx context.Context, req *proto.BeforeToolCallRequest) (*proto.BeforeToolCallResponse, error) func (m *GRPCServer) ExecuteTool(ctx context.Context, req *proto.ExecuteToolRequest) (*proto.ExecuteToolResponse, error) func (m *GRPCServer) ModifyContext(ctx context.Context, req *proto.ModifyContextRequest) (*proto.ModifyContextResponse, error) func (m *GRPCServer) ModifyInput(ctx context.Context, req *proto.ModifyInputRequest) (*proto.ModifyInputResponse, error) func (m *GRPCServer) ModifySystemPrompt(ctx context.Context, req *proto.ModifySystemPromptRequest) (*proto.ModifySystemPromptResponse, error) func (m *GRPCServer) Name(ctx context.Context, _ *proto.Empty) (*proto.NameResponse, error) func (m *GRPCServer) SessionEnd(ctx context.Context, req *proto.SessionEndRequest) (*proto.Empty, error) func (m *GRPCServer) SessionStart(ctx context.Context, req *proto.SessionStartRequest) (*proto.Empty, error) func (m *GRPCServer) Tools(ctx context.Context, _ *proto.Empty) (*proto.ToolsResponse, error) func (m *GRPCServer) TurnEnd(ctx context.Context, _ *proto.Empty) (*proto.Empty, error) func (m *GRPCServer) TurnStart(ctx context.Context, _ *proto.Empty) (*proto.Empty, error) type Loader type NoopPlugin func (n *NoopPlugin) AfterCompact(_ context.Context, _ int) func (n *NoopPlugin) AfterProviderResponse(_ context.Context, _ string, _ int) func (n *NoopPlugin) AfterToolCall(_ context.Context, _ ToolCall, result ToolResult) ToolResult func (n *NoopPlugin) AgentEnd(_ context.Context) func (n *NoopPlugin) AgentStart(_ context.Context) func (n *NoopPlugin) BeforeCompact(_ context.Context, _ agent.CompactionPrep) *agent.CompactionResult func (n *NoopPlugin) BeforePrompt(_ context.Context, state AgentState) AgentState func (n *NoopPlugin) BeforeProviderRequest(_ context.Context, requestJSON string) string func (n *NoopPlugin) BeforeToolCall(_ context.Context, _ ToolCall, _ json.RawMessage) (ToolResult, bool) func (n *NoopPlugin) ExecuteTool(_ context.Context, name string, _ json.RawMessage) ToolResult func (n *NoopPlugin) ModifyContext(_ context.Context, messagesJSON string) string func (n *NoopPlugin) ModifyInput(_ context.Context, _ string) agent.InputResult func (n *NoopPlugin) ModifySystemPrompt(prompt string) string func (n *NoopPlugin) Name() string func (n *NoopPlugin) SessionEnd(_ context.Context, _ string, _ agent.SessionEndReason) func (n *NoopPlugin) SessionStart(_ context.Context, _ string, _ agent.SessionStartReason) func (n *NoopPlugin) Tools() []ToolDefinition func (n *NoopPlugin) TurnEnd(_ context.Context) func (n *NoopPlugin) TurnStart(_ context.Context) type Plugin type RemoteTool type SkillLoader type SkillTool type SkillsMetadataExtension type ToolCall type ToolDefinition type ToolResult
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 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 ( 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 ( 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 ( 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 ( 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 ( 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 ( m * GRPCServer ) BeforeToolCall ( ctx context . Context , req * proto . BeforeToolCallRequest ) ( * proto . BeforeToolCallResponse , error )
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 ( 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 ( 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 ( 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 ( n * NoopPlugin ) BeforeToolCall ( _ context . Context , _ ToolCall , _ json . RawMessage ) ( ToolResult , bool )
func ( n * NoopPlugin ) ExecuteTool ( _ context . Context , name string , _ json . RawMessage ) ToolResult
func (*NoopPlugin) ModifyContext func ( n * NoopPlugin ) ModifyContext ( _ context . Context , messagesJSON string ) string
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 ( 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 )
}
RemoteTool is a tools.Tool that executes over the extension’s ExecuteTool gRPC.
type RemoteTool struct {
// contains filtered or unexported fields
}
func ( t * RemoteTool ) Description () string
func ( t * RemoteTool ) Execute ( ctx context . Context , args json . RawMessage , update tools . ToolUpdate ) ( * tools . ToolResult , error )
func ( t * RemoteTool ) IsReadOnly () bool
func ( t * RemoteTool ) Name () string
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.
SkillTool implements tools.Tool for a single Markdown-based skill.
type SkillTool struct {
// contains filtered or unexported fields
}
func ( s * SkillTool ) Description () string
func ( s * SkillTool ) Execute ( ctx context . Context , args json . RawMessage , update tools . ToolUpdate ) ( * tools . ToolResult , error )
func ( s * SkillTool ) IsReadOnly () bool
func ( s * SkillTool ) Name () string
func ( s * SkillTool ) Schema () json . RawMessage
SkillsMetadataExtension lists all available skills in the system prompt.
type SkillsMetadataExtension struct {
agent . NoopExtension
// contains filtered or unexported fields
}
func NewSkillsMetadataExtension ( allSkills [] * skills . Skill ) * SkillsMetadataExtension NewSkillsMetadataExtension creates an extension that adds skill metadata to the prompt.
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 ( s * SkillsMetadataExtension ) Tools () [] tools . Tool Tools returns a SkillTool for each loaded skill.
ToolCall describes a tool invocation passed to Plugin hook methods.
type ToolCall struct {
Name string
Args json . RawMessage
}
ToolDefinition describes a tool contributed by a Plugin.
type ToolDefinition struct {
Name string
Description string
Schema json . RawMessage
IsReadOnly bool
}
ToolResult is the outcome of a tool call or an interception.
type ToolResult struct {
Content string
IsError bool
} Generated by gomarkdoc
sdk import "github.com/goppydae/sharur/sdk" Package sdk provides the public Go SDK for embedding sharur agents in your own applications.
Example:
ag, err := sdk.NewAgent(sdk.Config{
Model: "llama3",
Provider: "ollama",
Tools: sdk.DefaultTools(),
})
if err != nil {
panic(err)
}
ag.Subscribe(func(e sdk.Event) {
if e.Type == sdk.EventTextDelta {
fmt.Print(e.Content)
}
})
if err := ag.Prompt(context.Background(), "What files are in this directory?"); err != nil {
panic(err)
}
<-ag.Idle()Index Constants
const (
EventAgentStart = agent . EventAgentStart
EventTurnStart = agent . EventTurnStart
EventMessageStart = agent . EventMessageStart
EventTextDelta = agent . EventTextDelta
EventToolCall = agent . EventToolCall
EventMessageEnd = agent . EventMessageEnd
EventAgentEnd = agent . EventAgentEnd
EventError = agent . EventError
EventAbort = agent . EventAbort
)
type Agent Agent is the stateful conversation agent.
func NewAgent func NewAgent ( cfg Config ) ( * Agent , error ) NewAgent creates a new agent from the given configuration.
type CompactionPrep CompactionPrep describes the state passed to BeforeCompact.
type CompactionPrep = agent . CompactionPrep
type CompactionResult CompactionResult can be returned by BeforeCompact to provide a custom summary.
type CompactionResult = agent . CompactionResult
type Config Config holds the options for creating a new agent.
type Config struct {
// Provider selects the LLM backend: "ollama" (default), "openai", or "anthropic".
Provider string
// Model is the model name to use (e.g. "llama3", "gpt-4o", "claude-sonnet-4-6").
Model string
// OllamaURL overrides the Ollama base URL (default: http://localhost:11434).
OllamaURL string
// OpenAIURL overrides the OpenAI-compatible base URL.
OpenAIURL string
// OpenAIKey is the API key for OpenAI or any compatible provider.
OpenAIKey string
// AnthropicKey is the Anthropic API key.
AnthropicKey string
// SystemPrompt sets the agent's system prompt.
SystemPrompt string
// ThinkingLevel controls reasoning depth.
ThinkingLevel ThinkingLevel
// MaxTokens caps the response length (0 = provider default).
MaxTokens int
// DryRun mode prevents tools from performing destructive actions.
DryRun bool
// Tools registers additional tools beyond the builtins.
// Pass tools.Read{}, tools.Write{}, tools.Bash{}, etc.
Tools [] Tool
// Extensions registers active extensions (gRPC plugins or Skills).
Extensions [] Extension
}
type Event Event is an agent lifecycle event emitted to subscribers.
type EventType EventType identifies the kind of event.
type EventType = agent . EventType
type Extension Extension is the interface for agent extensions (gRPC plugins, skills, etc.).
type Extension = agent . Extension
InputAction controls how ModifyInput’s result is applied.
type InputAction = agent . InputAction
const (
InputContinue InputAction = agent . InputContinue
InputTransform InputAction = agent . InputTransform
InputHandled InputAction = agent . InputHandled
)
InputResult is returned by ModifyInput.
type InputResult = agent . InputResult
type SessionEndReason SessionEndReason identifies why a session is ending.
type SessionEndReason = agent . SessionEndReason
const (
SessionEndReset SessionEndReason = agent . SessionEndReset
)
type SessionStartReason SessionStartReason identifies why a session is starting.
type SessionStartReason = agent . SessionStartReason
const (
SessionStartNew SessionStartReason = agent . SessionStartNew
SessionStartResume SessionStartReason = agent . SessionStartResume
)
type ThinkingLevel ThinkingLevel controls how much reasoning budget the model gets.
type ThinkingLevel = types . ThinkingLevel
const (
ThinkingOff ThinkingLevel = types . ThinkingOff
ThinkingLow ThinkingLevel = types . ThinkingLow
ThinkingMedium ThinkingLevel = types . ThinkingMedium
ThinkingHigh ThinkingLevel = types . ThinkingHigh
)
Tool is the universal tool interface.
func DefaultTools () [] Tool DefaultTools returns the full built-in tool set.
ToolResult is the output of a tool execution.
type ToolResult = tools . ToolResult Generated by gomarkdoc
import "github.com/goppydae/sharur/internal/tools" Package tools provides the universal tool interface and registry.
Index
func NormalizePath func NormalizePath ( path string ) string NormalizePath strips a leading ‘@’ from a path if present.
type Bash Bash is a tool for executing shell commands.
Security note: commands are executed as-is via `bash -c`. The subprocess runs in an isolated environment containing only an explicit allowlist of variables (PATH, HOME, LANG, TERM, TMPDIR, USER, SHELL). Extra variables can be injected via EnvAllowlist. DenyPatterns blocks commands by substring match before execution.
type Bash struct {
// Cwd is the working directory for commands.
Cwd string
// Timeout for command execution.
Timeout time . Duration
// DenyPatterns is an optional list of substrings that, if found in the
// command, will cause execution to be rejected. Checked case-insensitively.
// Example: []string{"rm -rf /", "dd if=", "> /dev/sd"}
DenyPatterns [] string
// EnvAllowlist is an optional list of KEY=VALUE pairs to inject into the
// subprocess environment in addition to the default allowlist.
EnvAllowlist [] string
}
func (Bash) Description func ( Bash ) Description () string
func (Bash) Execute func ( t Bash ) Execute ( ctx context . Context , args json . RawMessage , update ToolUpdate ) ( * ToolResult , error )
func (Bash) IsReadOnly func ( Bash ) IsReadOnly () bool
func (Bash) Name func ( Bash ) Name () string
func (Bash) Schema func ( Bash ) Schema () json . RawMessage
type Edit Edit is a tool for performing search-replace edits on files.
func (Edit) Description func ( Edit ) Description () string
func (Edit) Execute func ( Edit ) Execute ( ctx context . Context , args json . RawMessage , update ToolUpdate ) ( * ToolResult , error )
func (Edit) IsReadOnly func ( Edit ) IsReadOnly () bool
func (Edit) Name func ( Edit ) Name () string
func (Edit) Schema func ( Edit ) Schema () json . RawMessage
type Find Find is a tool for finding files by glob pattern.
func (Find) Description func ( Find ) Description () string
func (Find) Execute func ( Find ) Execute ( ctx context . Context , args json . RawMessage , update ToolUpdate ) ( * ToolResult , error )
func (Find) IsReadOnly func ( Find ) IsReadOnly () bool
func (Find) Name func ( Find ) Name () string
func (Find) Schema func ( Find ) Schema () json . RawMessage
type Grep Grep is a tool for searching file contents with regex.
func (Grep) Description func ( Grep ) Description () string
func (Grep) Execute func ( Grep ) Execute ( ctx context . Context , args json . RawMessage , update ToolUpdate ) ( * ToolResult , error )
func (Grep) IsReadOnly func ( Grep ) IsReadOnly () bool
func (Grep) Name func ( Grep ) Name () string
func (Grep) Schema func ( Grep ) Schema () json . RawMessage
type Ls Ls is a tool for listing directory contents.
func (Ls) Description func ( Ls ) Description () string
func (Ls) Execute func ( Ls ) Execute ( ctx context . Context , args json . RawMessage , update ToolUpdate ) ( * ToolResult , error )
func (Ls) IsReadOnly func ( Ls ) IsReadOnly () bool
func (Ls) Name
func (Ls) Schema func ( Ls ) Schema () json . RawMessage
type Read Read is a tool for reading file contents.
func (Read) Description func ( Read ) Description () string
func (Read) Execute func ( Read ) Execute ( ctx context . Context , args json . RawMessage , update ToolUpdate ) ( * ToolResult , error )
func (Read) IsReadOnly func ( Read ) IsReadOnly () bool
func (Read) Name func ( Read ) Name () string
func (Read) Schema func ( Read ) Schema () json . RawMessage
Tool is the universal tool interface — anything the agent can do.
type Tool interface {
Name () string
Description () string
Schema () json . RawMessage // JSON Schema for parameters
Execute ( ctx context . Context , args json . RawMessage , update ToolUpdate ) ( * ToolResult , error )
IsReadOnly () bool
}
ToolCall represents a tool invocation from the LLM.
type ToolCall struct {
ID string `json:"id"`
Name string `json:"name"`
Args json . RawMessage `json:"args"`
Position int `json:"position,omitempty"`
}
ToolRegistry manages registered tools.
type ToolRegistry struct {
// contains filtered or unexported fields
}
func NewToolRegistry () * ToolRegistry NewToolRegistry creates an empty tool registry.
func ( r * ToolRegistry ) All () [] Tool All returns all registered tools.
func ( r * ToolRegistry ) Get ( name string ) ( Tool , bool ) Get retrieves a tool by name.
func ( r * ToolRegistry ) Has ( name string ) bool Has checks if a tool is registered.
func ( r * ToolRegistry ) Register ( t Tool ) Register adds a tool to the registry.
ToolResult represents the output of a tool execution.
type ToolResult struct {
Content string `json:"content"`
IsError bool `json:"isError,omitempty"`
Metadata map [ string ] any `json:"metadata,omitempty"`
}
ToolUpdate is a callback for streaming partial results.
type ToolUpdate func ( partial * ToolResult )
type Write Write is a tool for creating or overwriting files.
func (Write) Description func ( Write ) Description () string
func (Write) Execute func ( Write ) Execute ( ctx context . Context , args json . RawMessage , update ToolUpdate ) ( * ToolResult , error )
func (Write) IsReadOnly func ( Write ) IsReadOnly () bool
func (Write) Name func ( Write ) Name () string
func (Write) Schema func ( Write ) Schema () json . RawMessage Generated by gomarkdoc