tools

package
v0.9.0 Latest Latest
Warning

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

 Go to latest Published: May 16, 2026 License: AGPL-3.0 Imports: 56 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// ReadMediaToolName is the tool name that the agent decoration layer
	// matches on to intercept image payloads. After the merge this is "read".
	ReadMediaToolName = "read"
)

Variables

View Source 
var ErrWatchdogTimedOut = errors.New("subagent watchdog: no activity within timeout")

ErrWatchdogTimedOut is returned when the subagent watchdog fires (no activity within the timeout period).

Functions

func BoolArg 

func BoolArg(arguments map[string]any, key string) (bool, bool, error)

func FirstStringArg 

func FirstStringArg(arguments map[string]any, keys ...string) string

func IntArg 

func IntArg(arguments map[string]any, key string) (int, bool, error)

func StringArg 

func StringArg(arguments map[string]any, key string) string

Types

type Attachment added in v0.7.0 

type Attachment struct {
	Type        string         `json:"type"`
	Path        string         `json:"path,omitempty"`
	URL         string         `json:"url,omitempty"`
	Base64      string         `json:"base64,omitempty"`
	PlatformKey string         `json:"platform_key,omitempty"`
	Mime        string         `json:"mime,omitempty"`
	Name        string         `json:"name,omitempty"`
	ContentHash string         `json:"content_hash,omitempty"`
	Size        int64          `json:"size,omitempty"`
	Metadata    map[string]any `json:"metadata,omitempty"`
}

Attachment describes a file reference emitted by a tool.

type BrowserProvider 

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

func NewBrowserProvider 

func NewBrowserProvider(log *slog.Logger, settingsSvc *settings.Service, containers bridge.Provider, displayWorkspace displaypkg.Workspace, dataRoot string) *BrowserProvider

func (*BrowserProvider) Tools 

func (p *BrowserProvider) Tools(ctx context.Context, session SessionContext) ([]sdk.Tool, error)

type ContactsProvider 

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

func NewContactsProvider 

func NewContactsProvider(log *slog.Logger, routeService route.Service) *ContactsProvider

func (*ContactsProvider) Tools 

func (p *ContactsProvider) Tools(_ context.Context, session SessionContext) ([]sdk.Tool, error)

type ContainerProvider 

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

func NewContainerProvider 

func NewContainerProvider(log *slog.Logger, clients bridge.Provider, bgManager *background.Manager, execWorkDir string) *ContainerProvider

func (*ContainerProvider) Tools 

func (p *ContainerProvider) Tools(ctx context.Context, session SessionContext) ([]sdk.Tool, error)

type EmailProvider 

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

func NewEmailProvider 

func NewEmailProvider(log *slog.Logger, service *email.Service, manager *email.Manager) *EmailProvider

func (*EmailProvider) Tools 

func (p *EmailProvider) Tools(_ context.Context, session SessionContext) ([]sdk.Tool, error)

type FederationProvider 

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

FederationProvider adapts a mcp.ToolSource (federated MCP connections) into the ToolProvider interface so the agent can load external MCP tools alongside built-in tools.

func NewFederationProvider 

func NewFederationProvider(log *slog.Logger, source mcp.ToolSource) *FederationProvider

func (*FederationProvider) Tools 

func (f *FederationProvider) Tools(ctx context.Context, session SessionContext) ([]sdk.Tool, error)

type HistoryProvider 

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

HistoryProvider exposes list_sessions and search_messages tools.

func NewHistoryProvider 

func NewHistoryProvider(log *slog.Logger, sessions SessionLister, queries dbstore.Queries) *HistoryProvider

func (*HistoryProvider) Tools 

func (p *HistoryProvider) Tools(_ context.Context, sess SessionContext) ([]sdk.Tool, error)

type ImageGenProvider added in v0.7.0 

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

func NewImageGenProvider added in v0.7.0 

func NewImageGenProvider(
	log *slog.Logger,
	settingsSvc *settings.Service,
	modelsSvc *models.Service,
	queries dbstore.Queries,
	containers bridge.Provider,
	dataMount string,
) *ImageGenProvider

func (*ImageGenProvider) Tools added in v0.7.0 

func (p *ImageGenProvider) Tools(ctx context.Context, session SessionContext) ([]sdk.Tool, error)

type MemoryProvider 

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

func NewMemoryProvider 

func NewMemoryProvider(log *slog.Logger, registry *memprovider.Registry, settingsSvc MemorySettingsReader) *MemoryProvider

func (*MemoryProvider) Tools 

func (p *MemoryProvider) Tools(ctx context.Context, session SessionContext) ([]sdk.Tool, error)

type MemorySettingsReader 

type MemorySettingsReader interface {
	GetBot(ctx context.Context, botID string) (settings.Settings, error)
}

MemorySettingsReader returns bot settings for memory provider resolution.

type MessageProvider 

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

func NewMessageProvider 

func NewMessageProvider(log *slog.Logger, sender messaging.Sender, reactor messaging.Reactor, resolver messaging.ChannelTypeResolver, assetResolver messaging.AssetResolver) *MessageProvider

func (*MessageProvider) Tools 

func (p *MessageProvider) Tools(_ context.Context, session SessionContext) ([]sdk.Tool, error)

type ModelCreator 

type ModelCreator func(modelID, clientType, apiKey, codexAccountID, baseURL string, httpClient *http.Client) *sdk.Model

ModelCreator creates an sdk.Model from provider config. Set via SetModelCreator.

type Reaction added in v0.7.0 

type Reaction struct {
	Emoji     string `json:"emoji"`
	MessageID string `json:"message_id"`
	Remove    bool   `json:"remove,omitempty"`
}

Reaction describes an emoji reaction emitted by a tool.

type ReadMediaToolOutput 

type ReadMediaToolOutput struct {
	Public         ReadMediaToolResult
	ImageBase64    string
	ImageMediaType string
}

ReadMediaToolOutput is the internal execution result used by the agent to inject the image into the next Twilight AI step while keeping the visible tool result lightweight.

func ReadImageFromContainer added in v0.7.0 

func ReadImageFromContainer(ctx context.Context, client *bridge.Client, path string, maxBytes int64) ReadMediaToolOutput

ReadImageFromContainer reads a binary file through the bridge client, validates that it is a supported image format, and returns a ReadMediaToolOutput ready for the agent decoration pipeline.

It reads only a small header first to sniff the MIME type, avoiding buffering large non-image binaries just to reject them.

type ReadMediaToolResult 

type ReadMediaToolResult struct {
	OK    bool   `json:"ok"`
	Path  string `json:"path,omitempty"`
	Mime  string `json:"mime,omitempty"`
	Size  int    `json:"size,omitempty"`
	Error string `json:"error,omitempty"`
}

ReadMediaToolResult is the public result returned to the model.

type ScheduleProvider 

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

func NewScheduleProvider 

func NewScheduleProvider(log *slog.Logger, service Scheduler) *ScheduleProvider

func (*ScheduleProvider) Tools 

func (p *ScheduleProvider) Tools(_ context.Context, session SessionContext) ([]sdk.Tool, error)

type Scheduler 

type Scheduler interface {
	List(ctx context.Context, botID string) ([]sched.Schedule, error)
	Get(ctx context.Context, id string) (sched.Schedule, error)
	Create(ctx context.Context, botID string, req sched.CreateRequest) (sched.Schedule, error)
	Update(ctx context.Context, id string, req sched.UpdateRequest) (sched.Schedule, error)
	Delete(ctx context.Context, id string) error
}

Scheduler is the interface for schedule CRUD operations.

type SessionContext 

type SessionContext struct {
	BotID              string
	ChatID             string
	SessionID          string
	SessionType        string
	ChannelIdentityID  string
	SessionToken       string //nolint:gosec // carries session credential material at runtime
	CurrentPlatform    string
	ReplyTarget        string
	SupportsImageInput bool
	IsSubagent         bool
	Skills             map[string]SkillDetail
	TimezoneLocation   *time.Location
	Emitter            StreamEmitter
}

SessionContext carries request-scoped identity for tool execution.

func (SessionContext) FormatTime 

func (s SessionContext) FormatTime(t time.Time) string

FormatTime formats a time.Time using the session timezone (falls back to UTC).

func (SessionContext) IsSameConversation added in v0.7.0 

func (s SessionContext) IsSameConversation(platform, target string) bool

IsSameConversation reports whether the given platform+target pair refers to the conversation that the agent is currently replying to.

type SessionLister 

type SessionLister interface {
	ListByBot(ctx context.Context, botID string) ([]session.Session, error)
}

SessionLister is the minimal interface for listing sessions.

type SkillDetail 

type SkillDetail struct {
	Description string
	Content     string
	Path        string
}

SkillDetail holds the description and content of a loadable skill.

type SkillProvider 

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

func NewSkillProvider 

func NewSkillProvider(log *slog.Logger) *SkillProvider

func (*SkillProvider) Tools 

func (*SkillProvider) Tools(_ context.Context, session SessionContext) ([]sdk.Tool, error)

type SpawnAgent 

type SpawnAgent interface {
	Generate(ctx context.Context, cfg SpawnRunConfig) (*SpawnResult, error)
	GenerateWithWatchdog(ctx context.Context, cfg SpawnRunConfig, touchFn func()) (*SpawnResult, error)
}

SpawnAgent is the interface the spawn tool uses to run subagent tasks. It is satisfied by *agent.Agent and avoids an import cycle.

type SpawnIdentity 

type SpawnIdentity struct {
	BotID             string
	ChatID            string
	SessionID         string
	ChannelIdentityID string
	CurrentPlatform   string
	SessionToken      string //nolint:gosec // #nosec G117 -- session identifier, not a secret
	IsSubagent        bool
}

SpawnIdentity mirrors agent.SessionContext fields needed by spawn.

type SpawnLoopConfig 

type SpawnLoopConfig struct {
	Enabled bool
}

SpawnLoopConfig mirrors agent.LoopDetectionConfig.

type SpawnProvider 

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

SpawnProvider exposes a "spawn" tool that runs one or more subagent tasks concurrently and returns results to the parent agent.

func NewSpawnProvider 

func NewSpawnProvider(
	log *slog.Logger,
	settingsSvc *settings.Service,
	modelsSvc *models.Service,
	queries dbstore.Queries,
	sessionService *sessionpkg.Service,
) *SpawnProvider

NewSpawnProvider creates a SpawnProvider. The agent must be injected later via SetAgent to avoid a dependency cycle.

func (*SpawnProvider) SetAgent 

func (p *SpawnProvider) SetAgent(a SpawnAgent)

SetAgent injects the agent after construction (breaking the DI cycle).

func (*SpawnProvider) SetMessageService 

func (p *SpawnProvider) SetMessageService(w messagepkg.Writer)

SetMessageService injects an optional message writer for persisting subagent conversation history.

func (*SpawnProvider) SetModelCreator 

func (p *SpawnProvider) SetModelCreator(fn ModelCreator)

SetModelCreator injects the function used to create SDK models (typically agent.CreateModel wrapped to match the signature).

func (*SpawnProvider) SetSystemPromptFunc 

func (p *SpawnProvider) SetSystemPromptFunc(fn func(sessionType string) string)

SetSystemPromptFunc injects the function used to generate the system prompt (typically agent.GenerateSystemPrompt).

func (*SpawnProvider) Tools 

func (p *SpawnProvider) Tools(_ context.Context, session SessionContext) ([]sdk.Tool, error)

type SpawnResult 

type SpawnResult struct {
	Messages []sdk.Message
	Text     string
	Usage    *sdk.Usage
}

SpawnResult mirrors agent.GenerateResult.

type SpawnRunConfig 

type SpawnRunConfig struct {
	Model           *sdk.Model
	System          string
	Query           string
	SessionType     string
	Identity        SpawnIdentity
	LoopDetection   SpawnLoopConfig
	Messages        []sdk.Message
	ReasoningEffort string
	PromptCacheTTL  string
}

SpawnRunConfig mirrors agent.RunConfig fields needed by spawn.

type Speech added in v0.7.0 

type Speech struct {
	Text string `json:"text"`
}

Speech describes a TTS speech request emitted by a tool.

type StreamEmitter added in v0.7.0 

type StreamEmitter func(ToolStreamEvent)

StreamEmitter pushes a side-effect event into the current agent stream. Nil when no stream is available (e.g. subagent or non-streaming contexts where the caller collects events after generation).

type StreamEventType added in v0.7.0 

type StreamEventType string

StreamEventType identifies the kind of stream event emitted by tools. 

const (
	StreamEventAttachment     StreamEventType = "attachment"
	StreamEventReaction       StreamEventType = "reaction"
	StreamEventSpeech         StreamEventType = "speech"
	StreamEventSpawnHeartbeat StreamEventType = "spawn_heartbeat"
)

type SubagentWatchdog added in v0.7.0 

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

SubagentWatchdog implements an activity-based timeout for subagent execution. It is "touched" (fed/reset) on each activity signal from the LLM or tools. If no touch occurs within the configured timeout, it fires by cancelling its associated context.

Lifecycle:

  1. Call NewSubagentWatchdog to create a watchdog context.
  2. Call Touch() on each activity signal.
  3. Call Stop() when the watched operation completes normally.

The watchdog respects parent context cancellation: if the parent context is cancelled, the watchdog's context is also cancelled immediately.

func NewSubagentWatchdog added in v0.7.0 

func NewSubagentWatchdog(parentCtx context.Context, timeout time.Duration, logger *slog.Logger) (context.Context, *SubagentWatchdog)

NewSubagentWatchdog creates a watchdog that cancels the returned context after timeout of inactivity. The returned context is derived from parentCtx. If parentCtx is cancelled, the watchdog context is also cancelled.

func (*SubagentWatchdog) Stop added in v0.7.0 

func (w *SubagentWatchdog) Stop()

Stop terminates the watchdog goroutine and releases resources. Call this when the watched operation completes normally.

func (*SubagentWatchdog) Touch added in v0.7.0 

func (w *SubagentWatchdog) Touch()

Touch resets the watchdog timer. It is non-blocking and safe to call from any goroutine.

type TTSChannelResolver 

type TTSChannelResolver interface {
	ParseChannelType(raw string) (channel.ChannelType, error)
}

TTSChannelResolver parses platform name to channel type.

type TTSProvider 

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

func NewTTSProvider 

func NewTTSProvider(log *slog.Logger, settingsSvc *settings.Service, audioSvc *audiopkg.Service, sender TTSSender, resolver TTSChannelResolver) *TTSProvider

func (*TTSProvider) Tools 

func (p *TTSProvider) Tools(ctx context.Context, session SessionContext) ([]sdk.Tool, error)

type TTSSender 

type TTSSender interface {
	Send(ctx context.Context, botID string, channelType channel.ChannelType, req channel.SendRequest) error
}

TTSSender sends outbound messages through the channel manager.

type ToolProvider 

type ToolProvider interface {
	Tools(ctx context.Context, session SessionContext) ([]sdk.Tool, error)
}

ToolProvider supplies a set of tools for the agent. Tools() is called per-request; implementations may return different tool sets based on session context (e.g. subagent restrictions, bot settings).

type ToolStreamEvent added in v0.7.0 

type ToolStreamEvent struct {
	Type        StreamEventType
	Attachments []Attachment
	Reactions   []Reaction
	Speeches    []Speech
}

ToolStreamEvent is a side-effect event emitted by a tool targeting the current conversation (e.g. inline attachment, reaction, or TTS speech). The agent framework converts these into the appropriate wire-level events.

type TranscriptionProvider added in v0.7.1 

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

func NewTranscriptionProvider added in v0.7.1 

func NewTranscriptionProvider(log *slog.Logger, settingsSvc *settings.Service, audioSvc *audiopkg.Service, mediaSvc *media.Service) *TranscriptionProvider

func (*TranscriptionProvider) Tools added in v0.7.1 

func (p *TranscriptionProvider) Tools(ctx context.Context, session SessionContext) ([]sdk.Tool, error)

type WebFetchProvider 

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

func NewWebFetchProvider 

func NewWebFetchProvider(log *slog.Logger) *WebFetchProvider

func (*WebFetchProvider) Tools 

func (p *WebFetchProvider) Tools(_ context.Context, _ SessionContext) ([]sdk.Tool, error)

type WebProvider 

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

func NewWebProvider 

func NewWebProvider(log *slog.Logger, settingsSvc *settings.Service, searchSvc *searchproviders.Service) *WebProvider

func (*WebProvider) Tools 

func (p *WebProvider) Tools(_ context.Context, session SessionContext) ([]sdk.Tool, error)

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.