PicoBot/AGENTS.md

PicoBot

Maintenance

• Update this file on any architectural change — module boundaries, data flow, key constraints, or build/test commands must be reflected here

Build & Run

• cargo build — build the binary
• cargo run -- gateway — start gateway server (binds 127.0.0.1:19876 by default)
• cargo run -- chat — connect to gateway as CLI client (default ws://127.0.0.1:19876/ws)

Config

• Config file: ~/.picobot/config.json or ./config.json (fallback order)
• .env is loaded and env var placeholders <VAR_NAME> are substituted into config
• Config example: config.example.json

Tests

• cargo test --lib — run unit tests (FAILS: src/session/session.rs:657 missing workspace_dir field in test helper)
• cargo test --test test_integration -- --ignored — run integration tests (requires tests/test.env with API keys)

Reference

• reference/ — third-party reference implementations (nanobot, Mini-Agent, zeroclaw); not part of this project; use for similar functionality patterns

Architecture

Modes

• Gateway mode (cargo run -- gateway): HTTP/WebSocket server; owns GatewayState which holds all services
• Client mode (cargo run -- chat): TUI chat client; connects to gateway via WebSocket, purely for user interaction

Core Data Flow

Channel → MessageBus → SessionManager → AgentLoop → (tools) → SessionManager → MessageBus → OutboundDispatcher → Channel
                    ↑
              ControlChannel ──→ SessionManager (dialog ops: create/switch/archive/delete)

Modules

Module	Responsibility	Key Types
gateway	Server lifecycle, HTTP/WS endpoints, owns GatewayState	GatewayState, run()
client	TUI rendering, WebSocket client for CLI chat	App, run()
channels	External integrations (Feishu, CLI chat)	ChannelManager, Channel trait
bus	Async message queue (inbound/outbound/control channels)	MessageBus, InboundMessage, OutboundMessage, ControlMessage
session	Conversation session lifecycle, dialog operations	SessionManager, Session
agent	LLM call loop, tool execution, context compression	AgentLoop
providers	LLM API clients (OpenAI-compatible, Anthropic)	LLMProvider trait, factory create_provider()
tools	Agent tools (bash, file operations, http, web)	ToolRegistry, Tool trait

Functional Boundaries

• Channels only send/receive messages via MessageBus; they know nothing about sessions or LLM
• MessageBus is a pure async queue; it routes nothing, just passes messages
• SessionManager owns session state and dialog operations; it does NOT call LLM directly
• AgentLoop receives dialog events from SessionManager, calls LLM via providers, executes tools, returns text responses
• Providers are pure HTTP clients; no bus/session/channel awareness
• Tools are executed by AgentLoop; they receive raw arguments and return string results

Key Constraints

• Gateway changes working directory to workspace on startup (src/gateway/mod.rs:31)
• ChannelManager owns the MessageBus and all channel instances
• OutboundDispatcher routes outbound messages to the correct channel via ChannelManager

Known Issues

• src/session/session.rs:657 — LLMProviderConfig struct requires workspace_dir but test helper at line 656-669 doesn't provide it; test code needs workspace_dir: PathBuf::new() added