FrostAgent Architecture: How Components Fit Together

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/GuaiZai233/FrostAgent/llms.txt

Use this file to discover all available pages before exploring further.

​

High-Level Message Flow

​

Core Packages

​

Core Interfaces

// LLMProvider defines the interface for LLM API calls.
type LLMProvider interface {
    Chat(ctx context.Context, req ChatRequest) (*ChatResponse, error)
}

// AgentService defines the interface for agent message handling.
type AgentService interface {
    Handle(ctx context.Context, input IncomingMessage) ([]OutgoingMessage, error)
}

// MessageAdapter defines the interface for platform-specific message sending.
type MessageAdapter interface {
    Send(ctx context.Context, msg OutgoingMessage) error
    ID() string
}

// MessageDispatcher routes core-layer outputs to the correct adapter.
type MessageDispatcher interface {
    RegisterAdapter(adapter MessageAdapter)
    Dispatch(ctx context.Context, platform string, msg OutgoingMessage) error
}

// ToolRegistry defines the interface for tool registration and lookup.
type ToolRegistry interface {
    Register(t Tool)
    GetTool(name string) (Tool, bool)
    GetExecutor(name string) (func(args string) (string, error), bool)
    ListTools() []Tool
    Execute(name, args string) (string, error)
}

// Session defines a single conversation session.
type Session interface {
    ID() string
    AddMessage(msg ChatMessage)
    Messages() []ChatMessage
    Clear()
}

// SessionStore manages all active sessions.
type SessionStore interface {
    Get(sessionID string) (Session, bool)
    Create(sessionID string) Session
    Delete(sessionID string)
}

​

Message Flow (Step by Step)

1. Upgrade — HandleWS upgrades the raw HTTP request to a WebSocket connection and wraps it in a wsConnection to serialise writes with a sync.Mutex.
2. Read loop — The goroutine reads frames in a blocking loop; heartbeat frames are silently dropped.
3. Dispatch goroutine — Each non-heartbeat event spawns go processEvent(wsConn, event, engine).
4. Parse — processEvent unmarshals the OneBot message segments and checks whether the bot was @-mentioned (group chats only).
5. Session lookup — engine.SessionManager.GetOrCreate(sessionID) returns or creates a SessionContext; session.Snapshot() deep-copies the history.
6. Prompt assembly — User text and a JSON system context block are combined into a single prompt string.
7. History append — The user message is appended to the session via session.AddMessage.
8. RunMessages — engine.RunMessages(messages) starts the agentic loop.
9. LLM call — Provider.Chat is called; the response is checked for tool calls.
10. Tool execution — Each requested tool is located in ToolRegistry and executed; the JSON result is appended as a role: "tool" message.
11. SendHook — If the tool is send_message, SendHook fires immediately, sending the message to the user before returning control to the LLM.
12. Final answer — When the LLM responds with no tool calls, RunMessages returns the content string.
13. History trim — The updated message slice is trimmed to MaxHistory messages (preserving the system prompt and tool-call chains) and written back to the session.
14. Reply — The adapter serialises the final answer into an OneBot action and writes it to the WebSocket.

​

Concurrency Model

• Per-connection goroutine — Each WebSocket connection runs its own read loop. The gorilla/websocket library is not concurrency-safe for writes, so all writes go through wsConnection.writeMu (sync.Mutex).
• Per-event goroutine — processEvent is always called with go, so slow LLM calls on one event cannot block receipt of the next.
• Session mutex — SessionContext.mu (sync.Mutex) protects History and UpdatedAt. RunWithSession holds the lock for the full duration of the agentic loop; external callers use Lock() / Unlock() explicitly. Snapshot() and ReplaceMessages() acquire the lock internally.
• SessionManager RWMutex — SessionManager.mu (sync.RWMutex) guards the session map, allowing concurrent reads while serialising writes (create / delete / cleanup).
• DefaultDispatcher RWMutex — Similarly guards the adapter map with sync.RWMutex.