Architecture

type AgentInstance struct {
    ID             string                    // Unique agent identifier
    Name           string                    // Human-readable name
    Model          string                    // Primary LLM model
    Fallbacks      []string                  // Fallback model list
    Workspace      string                    // Agent workspace directory
    MaxIterations  int                       // Max tool use iterations
    MaxTokens      int                       // Context window size
    Temperature    float64                   // LLM sampling temperature
    Provider       providers.LLMProvider     // LLM provider interface
    Sessions       *session.SessionManager   // Conversation history
    ContextBuilder *ContextBuilder           // System prompt builder
    Tools          *tools.ToolRegistry       // Available tools
    Subagents      *config.SubagentsConfig   // Subagent permissions
    SkillsFilter   []string                  // Enabled skills
    Candidates     []providers.FallbackCandidate // Fallback chain
}

┌─────────────────────────────────────────────────────┐
│                   Message Bus                       │
│              (Inbound/Outbound)                     │
└──────────────────┬──────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────┐
│                 AgentLoop.Run()                     │
│  • Consumes messages from bus                       │
│  • Routes to appropriate agent                      │
│  • Manages LLM iteration loop                       │
└──────────────────┬──────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────┐
│            runAgentLoop(agent, opts)                │
│  1. Update tool contexts (channel/chatID)           │
│  2. Build messages (system + history + user)        │
│  3. Run LLM iteration loop                          │
│  4. Save conversation to session                    │
│  5. Trigger summarization if needed                 │
└──────────────────┬──────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────┐
│          runLLMIteration (Tool Loop)                │
│  Loop until MaxIterations or no tool calls:         │
│  1. Call LLM with messages + tool definitions       │
│  2. Handle reasoning output                         │
│  3. If no tool calls → return final response        │
│  4. Execute each tool call                          │
│  5. Append tool results to messages                 │
│  6. Continue to next iteration                      │
└─────────────────────────────────────────────────────┘

type LLMProvider interface {
    Chat(
        ctx context.Context,
        messages []Message,
        tools []ToolDefinition,
        model string,
        options map[string]any,
    ) (*LLMResponse, error)
    GetDefaultModel() string
}

Config → resolveProviderSelection() → Provider Type
         ↓
    Model prefix or explicit provider name
         ↓
    ┌────────────────────┐
    │ HTTP Compatible?   │ → HTTPProvider
    │ Claude Auth?       │ → ClaudeProvider
    │ Codex Auth?        │ → CodexProvider
    │ GitHub Copilot?    │ → GitHubCopilotProvider
    └────────────────────┘

type FallbackCandidate struct {
    Provider string
    Model    string
}

// Configured in model_list or fallbacks
candidates := []FallbackCandidate{
    {Provider: "openai", Model: "gpt-5.2"},
    {Provider: "anthropic", Model: "claude-sonnet-4.6"},
    {Provider: "zhipu", Model: "glm-4.7"},
}

type ToolRegistry struct {
    tools map[string]Tool
    mu    sync.RWMutex
}

// Core methods
func (r *ToolRegistry) Register(tool Tool)
func (r *ToolRegistry) Execute(ctx context.Context, name string, args map[string]any) *ToolResult
func (r *ToolRegistry) ToProviderDefs() []providers.ToolDefinition

~/.picoclaw/workspace/
├── sessions/
│   ├── main.json           # Default session
│   ├── telegram-123.json   # Channel-specific
│   └── agent:worker.json   # Agent-scoped
├── memory/
│   └── MEMORY.md          # Long-term memory
└── state/
    └── state.json         # Last channel, etc.

┌──────────────┐     Inbound      ┌──────────────┐
│   Channels   │ ─────────────────→│ Message Bus  │
│  (Telegram,  │                   │              │
│   Discord,   │     Outbound      │  - Inbound   │
│   etc.)      │←───────────────── │  - Outbound  │
└──────────────┘                   │  - Media     │
                                   └──────┬───────┘
                                          │
                                          ▼
                                   ┌──────────────┐
                                   │  AgentLoop   │
                                   └──────────────┘

1. User sends message via Telegram
   ↓
2. Telegram channel → MessageBus.PublishInbound()
   ↓
3. AgentLoop.Run() consumes message
   ↓
4. Route to appropriate agent (based on channel/guild/peer)
   ↓
5. Build context (system + history + user message)
   ↓
6. Call LLM with tools
   ↓
7. LLM returns tool calls
   ↓
8. Execute tools (e.g., web_search, exec)
   ↓
9. Append tool results to messages
   ↓
10. Call LLM again (loop continues)
    ↓
11. LLM returns final text response
    ↓
12. Save to session
    ↓
13. MessageBus.PublishOutbound() → Telegram
    ↓
14. User receives response

restrict_to_workspace: true  // Default

{
  "tools": {
    "allow_read_paths": ["^/etc/hosts$"],
    "allow_write_paths": []
  }
}

Environment Variables
    ↓ (override)
config.json
    ↓ (defaults)
Hardcoded Defaults