Koder Bot — services/ai/bot/app

• *rea:*Intelligence
• *ath:*core/bot-server
• *ind:*Go service — multi-channel AI agent backend
• *inary:*koder-bot
• *tatus:*v1.x in production at s.forge (LXC 129)

Role in the stack

Koder Bot Server is the backend platform that powers Kode — Koder's AI agent. It provides a unified runtime for multiple communication channels (Telegram, WhatsApp, WebChat), routing messages to an AI agent that can use tools, integrate with Koder services, and maintain persistent context per user session.

It is the server-side counterpart of the Kode Flutter app and the platform that makes @koder_kode_bot work on Telegram.

Architecture overview

Telegram (long poll)  ──┐
WhatsApp (whatsmeow)  ──┤──→  Gateway  ──→  Agent Runtime  ──→  Claude API
WebChat (WebSocket)   ──┘         │               │
                                  │               ├── Tools (Mail, Drive, Sign, Flow, Web)
                                  ▼               └── Memory & Skills
                              PostgreSQL

All inbound messages (regardless of channel) are normalized into InboundMessage structs and processed by a single Gateway, which manages sessions and delegates to the agent runtime.

Components

Channels (internal/channel/)

*elegram channel behavior:*

• Private chats: forwards every message to the agent
• Groupssupergroups: only forwards when message starts with `, replies to the bot, or contains @botUsername`
• Commands handled at channel level: /setavatar, /keyboard, /clear
• Per-chat reply keyboards persisted in PostgreSQL

*hatsApp channel behavior:*

• Requires initial QR pairing (device is persisted via whatsmeow SQLite store)
• Ignores messages sent by the bot itself (IsFromMe)
• Reconnects automatically on disconnect

Gateway (internal/gateway/)

The gateway is the central message bus:

1. Reads from the inbound channel (buffered, cap 256)
2. Intercepts /model command to switch AI model preference
3. FindOrCreate session keyed by (userID, channelType, remoteID)
4. Loads user's PreferredModel from the database
5. Calls agent.runtime.Process() to generate a response
6. Routes the response back to the originating channel
7. Broadcasts typing indicators and responses to any open WebSocket (/ws/chat)

Agent Runtime (internal/agent/)

Wraps the Claude API (Anthropic SDK) with:

• *ool registry*— Mail, Drive, Sign, Flow, Web search, Calendar, Image generation, System info, Remote node invocation
• *ontext builder*— injects SOUL.md (system prompt), USER.md, MEMORY.md, and active skill files before each request
• *ax tool iterations*— configurable cap on tool-use rounds per message (default: 10)
• *ax context messages*— sliding window of conversation history (default: 50)

User & Auth (internal/web/, internal/service/user.go)

Authentication has two flows:

*IDC (for dashboard/WebChat):*

1. /auth/login → redirect to Koder ID (https://id.koder.dev)
2. /auth/callback → exchange code for ID token, GetOrCreate user, issue JWT cookie
3. JWT validated by AuthMiddleware on all `apiv1