agent

package
v0.16.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 6, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Binding 

type Binding struct {
	Pattern   string // "telegram" or "telegram:12345"
	AgentName string
}

Binding maps an adapter pattern to an agent name. Pattern is either a wildcard ("telegram") or specific ("telegram:12345").

type ChatEvent added in v0.14.0 

type ChatEvent struct {
	Type     string  `json:"type"`                  // "tool_start", "tool_end", "thinking", "usage", "tool_approval"
	Tool     string  `json:"tool,omitempty"`        // tool name
	Round    int     `json:"round,omitempty"`       // 1-based tool round
	Duration int64   `json:"duration_ms,omitempty"` // tool execution time
	Error    string  `json:"error,omitempty"`       // tool error (if any)
	Text     string  `json:"text,omitempty"`        // human-readable status message
	Tokens   int     `json:"tokens,omitempty"`      // total tokens used (usage event)
	CostUSD  float64 `json:"cost_usd,omitempty"`    // estimated cost in USD (usage event)

	// ApprovalID and ApprovalCallback are set on "tool_approval" events so
	// the adapter can render inline approve/deny buttons.
	ApprovalID       string `json:"approval_id,omitempty"`
	ApprovalCallback string `json:"approval_callback,omitempty"` // "appr:{id}" prefix

	// ApprovalStatus distinguishes pending approvals from auto-approved ones.
	// Values: "" (pending, needs user action), "auto_approved" (rule matched).
	ApprovalStatus string `json:"approval_status,omitempty"`
}

ChatEvent describes an intermediate pipeline event streamed to SSE clients.

type ChatEventFunc added in v0.14.0 

type ChatEventFunc func(ChatEvent)

ChatEventFunc is called for each intermediate pipeline event.

type ConversationInfo 

type ConversationInfo struct {
	ID           string    `db:"id"            json:"id"`
	Adapter      string    `db:"adapter"       json:"adapter"`
	ExternalID   string    `db:"external_id"   json:"external_id"`
	CreatedAt    time.Time `db:"created_at"    json:"created_at"`
	MessageCount int       `db:"message_count" json:"message_count"`
}

ConversationInfo provides metadata about a conversation.

type Dispatcher 

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

Dispatcher routes incoming messages to the correct agent Engine based on adapter bindings. It owns the adapter lifecycle and the shared incoming channel.

func NewDispatcher 

func NewDispatcher(
	agents map[string]*Engine,
	bindings []Binding,
	adapters []adapter.Adapter,
	logger *slog.Logger,
) *Dispatcher

NewDispatcher creates a Dispatcher from a set of named engines, bindings, and adapters. Bindings are processed in order; specific bindings ("telegram:12345") take priority over wildcard bindings ("telegram").

func (*Dispatcher) Agent 

func (d *Dispatcher) Agent(name string) *Engine

Agent returns the Engine for the named agent, or nil if not found.

func (*Dispatcher) Agents 

func (d *Dispatcher) Agents() []string

Agents returns the names of all registered agents.

func (*Dispatcher) Dispatch 

func (d *Dispatcher) Dispatch(ctx context.Context, agentName string, msg adapter.IncomingMessage) error

Dispatch sends a message to a specific agent by name. Used by the scheduler.

func (*Dispatcher) ListModels added in v0.15.1 

func (d *Dispatcher) ListModels(ctx context.Context) []string

ListModels returns available LLM models by querying the default agent's router.

func (*Dispatcher) Run 

func (d *Dispatcher) Run(ctx context.Context) error

Run starts all adapters and processes incoming messages until ctx is cancelled.

func (*Dispatcher) SendFor 

func (d *Dispatcher) SendFor(adapterName string) SendFunc

SendFor returns a SendFunc that routes outgoing messages through the adapter matching the incoming message's adapter name.

func (*Dispatcher) SendVia 

func (d *Dispatcher) SendVia(ctx context.Context, adapterName string, msg adapter.OutgoingMessage) error

SendVia sends a message through the adapter registered under adapterName. Returns an error if no adapter with that name is registered.

type Engine 

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

Engine is the core agent orchestrator. Each named agent gets its own Engine instance with its own persona, skills, permissions, and LLM router.

func NewEngine 

func NewEngine(
	name string,
	router *llm.Router,
	memory MemoryStore,
	sendFunc SendFunc,
	permissions *security.PermissionEngine,
	p *persona.Persona,
	fallbackPrompt string,
	skills []skill.Skill,
	tools *tool.Manager,
	approvals *approval.Manager,
	logger *slog.Logger,
) *Engine

func (*Engine) AppendSkill 

func (e *Engine) AppendSkill(s skill.Skill)

AppendSkill appends a new skill to the engine's in-memory skill list.

func (*Engine) Chat 

func (e *Engine) Chat(ctx context.Context, msg adapter.IncomingMessage) (string, error)

Chat processes a single incoming message through the full pipeline and returns the response text. It does not call the sendFunc — use this when the caller wants to receive the reply directly (e.g. the REST API). Any pending approval request is accessible via GET /api/v1/approvals.

func (*Engine) ChatWithEvents added in v0.14.0 

func (e *Engine) ChatWithEvents(ctx context.Context, msg adapter.IncomingMessage, onEvent ChatEventFunc) (string, error)

ChatWithEvents is like Chat but calls onEvent for intermediate status events (tool calls, etc.) that can be streamed to the client in real time.

func (*Engine) GetSkill added in v0.9.0 

func (e *Engine) GetSkill(name string) (skill.Skill, bool)

GetSkill returns a skill by name and true, or a zero value and false if not found.

func (*Engine) HandleMessage 

func (e *Engine) HandleMessage(ctx context.Context, msg adapter.IncomingMessage) error

HandleMessage processes a single incoming message and sends the response back via the adapter's SendFunc. It delegates to HandleMessageWithEvents with a nil event callback.

func (*Engine) HandleMessageWithEvents added in v0.15.0 

func (e *Engine) HandleMessageWithEvents(ctx context.Context, msg adapter.IncomingMessage, onEvent ChatEventFunc) error

HandleMessageWithEvents is like HandleMessage but calls onEvent for intermediate pipeline events (thinking, tool calls, usage). The Dispatcher uses this to refresh adapter typing indicators during processing.

func (*Engine) HasTools 

func (e *Engine) HasTools() bool

HasTools returns true if the agent has MCP tools configured.

func (*Engine) ListModels added in v0.15.1 

func (e *Engine) ListModels(ctx context.Context) []string

ListModels returns available LLM models from all registered providers.

func (*Engine) ModelName 

func (e *Engine) ModelName() string

ModelName returns the agent's default LLM model.

func (*Engine) Name 

func (e *Engine) Name() string

Name returns the agent's name.

func (*Engine) PermissionTier 

func (e *Engine) PermissionTier() string

PermissionTier returns the agent's default permission tier.

func (*Engine) PersonaDir 

func (e *Engine) PersonaDir() string

PersonaDir returns the directory the agent's persona was loaded from. Returns an empty string if no persona is configured.

func (*Engine) PersonaSection added in v0.10.0 

func (e *Engine) PersonaSection(section string) (content string, editable bool, agentMutable bool, ok bool)

PersonaSection returns the content, editability, and agent-mutability of a persona section. Returns ("", false, false, false) if no persona is configured or section is unknown.

func (*Engine) PersonaSections 

func (e *Engine) PersonaSections() map[string]bool

PersonaSections returns which persona sections are loaded (soul/user/memory). Returns nil if no persona is configured.

func (*Engine) RemoveSkill added in v0.9.0 

func (e *Engine) RemoveSkill(name string) bool

RemoveSkill removes a skill by name from the engine's in-memory skill list. Returns false if the skill was not found.

func (*Engine) SavePersonaSection added in v0.10.0 

func (e *Engine) SavePersonaSection(section, content string) error

SavePersonaSection writes content to the named persona section. Returns an error if no persona is configured.

func (*Engine) SetModel added in v0.11.0 

func (e *Engine) SetModel(model string)

SetModel changes the engine's default LLM model.

func (*Engine) SetPermissionTier added in v0.11.0 

func (e *Engine) SetPermissionTier(tier string) error

SetPermissionTier replaces the engine's permission engine with one for the new tier.

func (*Engine) SetScheduler 

func (e *Engine) SetScheduler(sched *scheduler.Scheduler)

SetScheduler provides a Scheduler reference so the engine can register new schedules at runtime via SCHEDULE_ADD directives. Call this after the Scheduler is initialized.

func (*Engine) SetSkillDirs 

func (e *Engine) SetSkillDirs(agentSkillsDir, globalSkillsDir string)

SetSkillDirs configures the directories used for skill creation and hot-reload. agentSkillsDir is where new skill files are written; globalSkillsDir is the shared skills directory merged on top of agent-specific skills. Call this after NewEngine, before the engine starts handling messages.

func (*Engine) Skills 

func (e *Engine) Skills() []skill.Skill

Skills returns the agent's loaded skills (global + agent-specific, merged).

func (*Engine) SkillsDir added in v0.9.0 

func (e *Engine) SkillsDir() string

SkillsDir returns the directory where agent-specific skill files are stored.

func (*Engine) ToolNames 

func (e *Engine) ToolNames() []string

ToolNames returns the names of all registered MCP tools for this agent. Returns nil if the agent has no tools configured.

func (*Engine) UpdateSkill added in v0.9.0 

func (e *Engine) UpdateSkill(name string, updated skill.Skill) bool

UpdateSkill replaces an existing skill by name in the engine's in-memory skill list. Returns false if the skill was not found.

type MemoryStore 

type MemoryStore interface {
	GetOrCreateConversation(ctx context.Context, adapter, externalID string) (string, error)
	// GetOrCreateConversationByID ensures a conversation row exists for the given
	// convID without requiring a real adapter/externalID pair. Used by the
	// scheduler for isolated sessions that are not tied to a chat channel.
	GetOrCreateConversationByID(ctx context.Context, convID string) error
	AddMessage(ctx context.Context, convID string, msg StoredMessage) error
	GetMessages(ctx context.Context, convID string, limit int) ([]StoredMessage, error)
	ListConversations(ctx context.Context) ([]ConversationInfo, error)
	// DeleteConversation removes a conversation and all its messages by ID.
	// Returns nil if the conversation does not exist (idempotent).
	DeleteConversation(ctx context.Context, convID string) error
	Close() error
}

MemoryStore defines the interface for conversation persistence.

type SQLiteMemoryStore 

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

SQLiteMemoryStore implements MemoryStore using SQLite.

func NewInMemoryStore 

func NewInMemoryStore() (*SQLiteMemoryStore, error)

NewInMemoryStore creates an in-memory SQLite store (for testing).

func NewSQLiteMemoryStore 

func NewSQLiteMemoryStore(dbPath string) (*SQLiteMemoryStore, error)

NewSQLiteMemoryStore opens or creates a SQLite database at the given path.

func (*SQLiteMemoryStore) AddMessage 

func (s *SQLiteMemoryStore) AddMessage(ctx context.Context, convID string, msg StoredMessage) error

func (*SQLiteMemoryStore) Close 

func (s *SQLiteMemoryStore) Close() error

func (*SQLiteMemoryStore) ConversationCost added in v0.7.0 

func (s *SQLiteMemoryStore) ConversationCost(ctx context.Context, convID string) (float64, error)

ConversationCost returns the total cost of all messages in a conversation.

func (*SQLiteMemoryStore) CountConversationsBefore added in v0.7.0 

func (s *SQLiteMemoryStore) CountConversationsBefore(ctx context.Context, before time.Time) (int, error)

CountConversationsBefore returns the number of conversations created before the given time.

func (*SQLiteMemoryStore) DeleteConversation 

func (s *SQLiteMemoryStore) DeleteConversation(ctx context.Context, convID string) error

func (*SQLiteMemoryStore) GetMessages 

func (s *SQLiteMemoryStore) GetMessages(ctx context.Context, convID string, limit int) ([]StoredMessage, error)

func (*SQLiteMemoryStore) GetOrCreateConversation 

func (s *SQLiteMemoryStore) GetOrCreateConversation(ctx context.Context, adapterName, externalID string) (string, error)

func (*SQLiteMemoryStore) GetOrCreateConversationByID 

func (s *SQLiteMemoryStore) GetOrCreateConversationByID(ctx context.Context, convID string) error

func (*SQLiteMemoryStore) ListConversations 

func (s *SQLiteMemoryStore) ListConversations(ctx context.Context) ([]ConversationInfo, error)

func (*SQLiteMemoryStore) PruneConversations added in v0.7.0 

func (s *SQLiteMemoryStore) PruneConversations(ctx context.Context, before time.Time) (int, error)

PruneConversations deletes all conversations (and their messages) created before the given time. Returns the number of conversations deleted.

type SendFunc 

type SendFunc func(ctx context.Context, msg adapter.OutgoingMessage) error

SendFunc is a callback for sending a response back to the originating adapter. The Dispatcher sets this when constructing each Engine.

type StoredMessage 

type StoredMessage struct {
	ID             int64     `db:"id"`
	ConversationID string    `db:"conversation_id"`
	Role           string    `db:"role"`
	Content        string    `db:"content"`
	TokensUsed     int       `db:"tokens_used"`
	Cost           float64   `db:"cost"`
	CreatedAt      time.Time `db:"created_at"`
}

StoredMessage represents a message persisted in the memory store.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.