# PicoBot

A multi-channel AI agent framework with a WebSocket gateway and TUI client, supporting OpenAI-compatible and Anthropic LLM providers, tool calling, session persistence, and cron-based scheduling.

## System Architecture

```mermaid
graph TB
    subgraph Clients
        TUI["🖥️ CLI Chat (TUI)"]
        FS["📱 Feishu/Lark"]
    end

    subgraph Gateway["Gateway Server (127.0.0.1:19876)"]
        HTTP["HTTP Endpoints<br/>GET /health<br/>GET /ws (WebSocket upgrade)"]
        WS["WebSocket Handler"]
        CD["ChannelManager"]
        SP["SessionManager"]
        AL["AgentLoop"]
    end

    subgraph Bus["MessageBus"]
        IB["Inbound Channel"]
        OB["Outbound Channel"]
        CC["Control Channel"]
    end

    subgraph Storage
        SQLite[("SQLite<br/>picobot.db")]
    end

    subgraph AI["AI Providers"]
        OpenAI["OpenAI / DashScope"]
        Anthropic["Anthropic Claude"]
    end

    TUI <-->|WebSocket| WS
    FS <-->|Webhook| HTTP

    CD -->|InboundMessage| IB
    IB -->|DialogEvent| SP
    CC -->|ControlMessage| SP
    SP <--> AL
    AL -->|API Call| OpenAI
    AL -->|API Call| Anthropic
    AL -->|Tool Call| Tools
    SP -->|OutboundMessage| OB
    OB --> CD
    SP --> SQLite
    Tools --> SQLite

    subgraph Tools
        Bash["Bash"]
        FileIO["File Read/Write/Edit"]
        Web["HTTP Request / Web Fetch"]
        Calc["Calculator"]
        Skill["Get Skill"]
        Msg["Send Message"]
        Cron["Cron Jobs"]
    end
```

### Core Data Flow

```mermaid
sequenceDiagram
    participant Channel as Channel<br/>(CLI/Feishu)
    participant Bus as MessageBus
    participant SM as SessionManager
    participant AL as AgentLoop
    participant LLM as LLM Provider
    participant Tool as Tools

    Channel->>Bus: InboundMessage (user input)
    Bus->>SM: DialogEvent
    SM->>SM: Load/Resolve Session
    SM->>AL: Process (session state)
    AL->>LLM: ChatCompletionRequest
    LLM-->>AL: response / tool_calls
    alt Tool Calls
        AL->>Tool: execute tool
        Tool-->>AL: result
        AL->>LLM: continue with tool result
    end
    AL-->>SM: AgentProcessResult (text + token count)
    SM->>SM: Persist to SQLite
    SM->>Bus: OutboundMessage
    Bus->>Channel: response to user
```

## Features

### Multi-Channel Support
- **CLI Chat Client** — Full TUI with session management, Markdown rendering, slash commands
- **Feishu (Lark)** — Webhook-based integration with typing indicators and media support

### Multi-Provider LLM
- OpenAI-compatible API (GPT-4, DashScope, Volcengine, etc.)
- Anthropic Messages API (Claude)
- Cross-provider JSON Schema normalization for tool calling compatibility

### Session Management
- Multi-session conversations per channel/chat
- Create, switch, rename, archive, delete dialogs via slash commands or WebSocket
- SQLite-persisted session history with automatic TTL-based cleanup
- Context compression for long conversations approaching token limits

### Tool System
| Tool | Description |
|------|-------------|
| `bash` | Execute shell commands in workspace |
| `file_read` | Read file contents |
| `file_write` | Create/overwrite files |
| `file_edit` | Precise string substitution in files |
| `http_request` | Make HTTP API requests |
| `web_fetch` | Fetch and parse web pages |
| `calculator` | Evaluate mathematical expressions |
| `get_skill` | Load agent skills from local skill files |
| `send_message` | Send messages to other channels |
| `cron_add/list/remove/enable/disable/update` | Manage scheduled jobs |

### Scheduling
- Cron-based recurring jobs with optional timezone support
- One-shot (`at`) and interval (`every`) schedules
- Jobs trigger agent processing via specified channel/chat

### Skills System
- Load Markdown skill files from `~/.picobot/skills` and `~/.agent/skills`
- Skills inject specialized system prompts for specific tasks
- Automatic hot-reload on file changes

### Observability
- Observer pattern for agent and tool telemetry
- Events: `AgentStart`, `AgentEnd`, `ToolCallStart`, `ToolCall`
- Structured JSON logging with file rotation

## Quick Start

### Prerequisites
- Rust nightly (edition 2024) — use `rustup` to install

### Build

```bash
cargo build
```

### Configure

1. Create `config.json` (or `~/.picobot/config.json`):

```json
{
    "providers": {
        "openai": {
            "type": "openai",
            "base_url": "https://api.openai.com/v1",
            "api_key": "<OPENAI_API_KEY>"
        }
    },
    "models": {
        "gpt-4o": {
            "model_id": "gpt-4o",
            "temperature": 0.7,
            "max_tokens": 4096
        }
    },
    "agents": {
        "default": {
            "provider": "openai",
            "model": "gpt-4o",
            "max_tool_iterations": 20,
            "token_limit": 128000
        }
    }
}
```

2. Set API keys via `.env` file (one `KEY=VALUE` per line):

```env
OPENAI_API_KEY=sk-xxxxx
```

### Run

**Start gateway server:**

```bash
cargo run -- gateway
```

Binds `127.0.0.1:19876` by default. Override with `--host` and `--port`.

**Connect CLI client:**

```bash
cargo run -- chat
```

Connects to `ws://127.0.0.1:19876/ws`. Override with `--gateway-url`.

## Configuration Reference

Config load order: `~/.picobot/config.json` → `./config.json` (fallback).

### Full Config Structure

```mermaid
graph LR
    Config["config.json"]
    Config --> Providers["providers<br/>ProviderConfig{}"]
    Config --> Models["models<br/>ModelConfig{}"]
    Config --> Agents["agents<br/>AgentConfig{}"]
    Config --> Gateway["gateway<br/>GatewayConfig"]
    Config --> Client["client<br/>ClientConfig"]
    Config --> Channels["channels<br/>ChannelConfig{}"]
    Config --> Workspace["workspace_dir"]

    Providers --> PT["type (openai / anthropic)<br/>base_url<br/>api_key<br/>extra_headers"]
    Models --> MT["model_id<br/>temperature<br/>max_tokens"]
    Agents --> AT["provider (ref)<br/>model (ref)<br/>max_tool_iterations<br/>token_limit"]
    Gateway --> GT["host / port<br/>session_ttl_hours<br/>cleanup_interval_minutes<br/>session_db_path<br/>scheduler"]
    Channels --> CT["feishu: app_id, app_secret<br/>allow_from, agent, media_dir"]
```

### Environment Variables

The `.env` file in the working directory is loaded manually (not via dotenv crate). Placeholders in `config.json` written as `<VAR_NAME>` are substituted at load time.

### Gateway Config

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `host` | string | `127.0.0.1` | Bind address |
| `port` | u16 | `19876` | Listen port |
| `session_ttl_hours` | number | `4` | Inactive session expiration (hours) |
| `cleanup_interval_minutes` | number | `60` | Session cleanup interval |
| `session_db_path` | string | workspace `picobot.db` | SQLite database path |
| `scheduler.enabled` | bool | `false` | Enable cron scheduler |

### Agent Config

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `provider` | string | — | Provider name (key in `providers`) |
| `model` | string | — | Model name (key in `models`) |
| `max_tool_iterations` | number | `20` | Max tool call iterations per turn |
| `token_limit` | number | `128000` | Context window token limit |

## Slash Commands

Available in CLI chat and Feishu:

| Command | Alias | Description |
|---------|-------|-------------|
| `/new` | `/刷新` | Create a new dialog |
| `/list` | `/对话列表` | List all dialogs |
| `/switch <id>` | — | Switch to a dialog |
| `/rename <title>` | — | Rename current dialog |
| `/archive` | — | Archive current dialog |
| `/delete` | — | Delete current dialog |
| `/clear` | `/清空` | Clear current dialog history |

## WebSocket Protocol

The gateway exposes a WebSocket endpoint at `/ws`. Messages use typed JSON with a `type` discriminator field.

### Client → Server (WsInbound)

| Type | Fields |
|------|--------|
| `user_input` | `content`, `channel?`, `chat_id?`, `sender_id?` |
| `create_session` | `title?` |
| `list_sessions` | `include_archived` |
| `load_session` | `session_id` |
| `rename_session` | `session_id?`, `title` |
| `archive_session` | `session_id?` |
| `delete_session` | `session_id?` |
| `clear_history` | `chat_id?`, `session_id?` |
| `get_slash_commands` | — |
| `ping` | — |

### Server → Client (WsOutbound)

| Type | Fields |
|------|--------|
| `assistant_response` | `session_id`, `response`, `tokens_used?`, `tool_calls?` |
| `session_list` | `sessions[]` |
| `session_loaded` | `session_id`, `messages[]` |
| `session_created` | `session_id`, `title` |
| `session_renamed` | `session_id`, `title` |
| `session_archived` | `session_id` |
| `session_deleted` | `session_id` |
| `slash_commands` | `commands[]` |
| `error` | `message` |
| `pong` | — |

## HTTP Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/health` | Health check — returns `{"status":"ok","version":"x.y.z"}` |
| `GET` | `/ws` | WebSocket upgrade for chat clients |

## Testing

```bash
# Unit tests (no external dependencies)
cargo test --lib

# Integration tests (require API keys)
cp tests/test.env.example tests/test.env
# Fill in your API keys in tests/test.env
cargo test --test test_integration -- --ignored
cargo test --test test_tool_calling -- --ignored
cargo test --test test_request_format -- --ignored

# Run all tests
cargo test -- --ignored
```

Integration tests are `#[ignore]` by default because they make real API calls.

## Project Structure

```
├── src/
│   ├── main.rs              # CLI entrypoint (clap-based subcommands)
│   ├── lib.rs                # Module declarations
│   ├── gateway/              # HTTP/WS server, GatewayState initialization
│   │   ├── mod.rs
│   │   ├── http.rs           # Health endpoint
│   │   └── ws.rs             # WebSocket handler
│   ├── client/               # TUI chat client
│   │   ├── mod.rs
│   │   └── tui/              # Ratatui-based terminal UI
│   ├── channels/             # Channel integrations
│   │   ├── base.rs           # Channel trait
│   │   ├── cli_chat.rs       # CLI WebSocket channel
│   │   ├── feishu.rs         # Feishu/Lark webhook channel
│   │   ├── manager.rs        # ChannelManager
│   │   └── slash_command.rs  # Slash command parser
│   ├── bus/                  # Async message bus
│   │   ├── mod.rs            # MessageBus (tokio mpsc channels)
│   │   ├── message.rs        # Message types
│   │   └── dispatcher.rs     # OutboundDispatcher
│   ├── session/              # Session & dialog management
│   │   ├── mod.rs
│   │   ├── session.rs        # Session, SessionManager
│   │   ├── session_id.rs     # UnifiedSessionId
│   │   ├── commands.rs       # SessionCommand enum
│   │   └── events.rs         # SessionEvent, DialogInfo
│   ├── agent/                # LLM interaction loop
│   │   ├── mod.rs
│   │   ├── agent_loop.rs     # AgentLoop (stateless)
│   │   ├── context_compressor.rs  # Token estimation & summarization
│   │   └── system_prompt.rs  # System prompt builder
│   ├── providers/            # LLM API clients
│   │   ├── mod.rs            # Factory: create_provider()
│   │   ├── traits.rs         # LLMProvider trait
│   │   ├── openai.rs         # OpenAI-compatible client
│   │   └── anthropic.rs      # Anthropic Messages API client
│   ├── tools/                # Agent tools
│   │   ├── mod.rs            # create_default_tools()
│   │   ├── registry.rs       # ToolRegistry
│   │   ├── traits.rs         # Tool trait, ToolResult
│   │   ├── schema.rs         # Cross-provider JSON Schema cleaner
│   │   ├── bash.rs           # Shell command execution
│   │   ├── calculator.rs     # Math expression evaluator
│   │   ├── chat_manager.rs   # Session management tool
│   │   ├── cron.rs           # Cron job management tools
│   │   ├── file_read.rs      # File reader
│   │   ├── file_write.rs     # File writer
│   │   ├── file_edit.rs      # File editor (string substitution)
│   │   ├── get_skill.rs      # Skill loader tool
│   │   ├── http_request.rs   # HTTP request tool
│   │   ├── send_message.rs   # Cross-channel messaging
│   │   └── web_fetch.rs      # Web page fetcher
│   ├── skills/               # Skills loading from markdown files
│   │   └── mod.rs            # SkillsLoader, Skill
│   ├── storage/              # SQLite persistence
│   │   ├── mod.rs            # Storage, schema init
│   │   ├── session.rs        # Session CRUD operations
│   │   ├── message.rs        # Message persistence
│   │   ├── scheduler.rs      # ScheduledJob, JobRun storage
│   │   └── error.rs          # StorageError
│   ├── scheduler/            # Cron scheduler runtime
│   │   ├── mod.rs            # Scheduler, next_run_for_schedule()
│   │   └── types.rs          # Schedule enum (At/Every/Cron)
│   ├── observability/        # Telemetry observer pattern
│   │   └── mod.rs            # Observer trait, ObserverEvent, MultiObserver
│   ├── protocol.rs           # WebSocket message types (WsInbound/WsOutbound)
│   ├── config/               # Config loading & env substitution
│   │   └── mod.rs            # Config, LLMProviderConfig, load_env_file()
│   └── logging.rs            # Tracing subscriber init with file rotation
├── tests/
│   ├── test_integration.rs   # LLM provider integration tests
│   ├── test_tool_calling.rs  # Tool calling integration tests
│   ├── test_request_format.rs # Request format tests
│   ├── test_scheduler.rs     # Scheduler unit tests
│   ├── test.env.example      # Test environment template
│   └── test.env              # Actual test keys (gitignored)
├── reference/                # Third-party reference code (do not modify)
├── config.example.json       # Full config example
└── Cargo.toml
```

## Key Dependencies

| Crate | Purpose |
|-------|---------|
| `axum` + `tokio-tungstenite` | HTTP server & WebSocket |
| `sqlx` (SQLite) | Session/Message/Job persistence |
| `reqwest` (rustls) | LLM API & external HTTP calls |
| `ratatui` + `crossterm` | Terminal UI |
| `clap` | CLI argument parsing |
| `tracing` + `tracing-subscriber` | Structured logging |
| `cron` + `chrono-tz` | Cron schedule parsing |
| `meval` | Mathematical expression evaluation |
| `uuid` | Session/Dialog ID generation |
| `dirs` | Platform config directory resolution |