9.5 KiB
9.5 KiB
Kugetsu Chat Architecture (Phase 3)
Status: Phase 3a Implemented (Testing in Progress)
Related Issue: #19
Overview
Phase 3 adds Telegram chat interface for mobile/phone UX. Users can interact with their agent team via natural language from any device with Telegram.
Architecture: Model B (Separate Agents)
┌─────────────────────────────────────────────────────────────────┐
│ User (Phone) │
│ Telegram App │
└─────────────────────────────────────────────────────────────────┘
│
│ Telegram Protocol
▼
┌─────────────────────────────────────────────────────────────────┐
│ Hermes (Chat Agent Gateway) │
│ - Receives messages from Telegram │
│ - Interprets natural language │
│ - Routes to appropriate agent session │
│ - Maintains conversation context │
└─────────────────────────────────────────────────────────────────┘
│
┌─────────────────┴─────────────────┐
│ │
▼ ▼
┌─────────────────────────┐ ┌─────────────────────────────┐
│ Chat Agent Session │ │ PM Agent Session │
│ (opencode session) │ │ (opencode session) │
│ │ │ │
│ Session ID: chat-agent │ │ Session ID: pm-agent │
│ │ │ │
│ - Handles casual chat │ │ - Coordinates tasks │
│ - Clears context on │◄────────┼─── PM questions to user │
│ unrelated messages │ │ │
│ - Short interactions │ │ - Delegates to Dev Agents │
└─────────────────────────┘ │ - Long-running work │
└─────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ Dev Agent Sessions │
│ (opencode sessions via kugetsu) │
│ │
│ Session IDs: │
│ - issue-1-pr │
│ - issue-2-research │
│ - fix-issue-3 │
│ - ... │
│ │
│ - Work autonomously │
│ - Output to Gitea │
│ - One issue per session │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ Gitea │
│ Issues, PRs, Comments │
│ (Permanent audit trail) │
└─────────────────────────────────────────┘
Session Types
| Session | kugetsu Session ID | Purpose | Lifespan |
|---|---|---|---|
| Chat Agent | chat-agent |
User conversation (Hermes) | Persistent |
| PM Agent | pm-agent |
Task coordination | Persistent |
| PM Agent (repo-specific) | pm-agent-{repo-name} |
Extends base PM for specific repo | Optional scaling |
| Dev Agent | issue-{n}-{type} |
Issue work | Until issue resolved |
PM Agent Hierarchy
- Base PM:
pm-agent- Generic 1-way/1-door agent - Repo-specific PM:
pm-agent-{repo-name}- Extends base PM for specific repo (optional scaling)
Message Routing (Hybrid - Option 3)
Routing Rules
| User Message | Route To | Response |
|---|---|---|
| Casual chat | Chat Agent | Direct response |
| Task request | PM Agent | Task created or clarification needed |
| Status query | PM Agent | Current status |
| "PM, be silent" | PM Agent | Mode changed to silent |
| "PM, notify me" | PM Agent | Mode changed to notify |
| Clarification | PM → Chat → User | PM asks via Hermes |
Example Flows
Flow 1: Simple Task Request
User: "create a test file for issue #5"
│
▼
Hermes (Chat Gateway)
│ Routes to PM
▼
PM Agent
│ Sees clear task
│ Creates kugetsu session: kugetsu start github.com/user/repo#5 "create test"
▼
Dev Agent (issue-5-pr session)
│ Does work
│ Posts PR to Gitea
▼
PM Agent
│ Task done
│ Checks: PM mode = notify?
▼
Hermes (Chat Gateway)
│ "Issue #5 is done! PR created."
▼
User (Telegram)
Flow 2: Task with Clarification
User: "improve the thing"
│
▼
Hermes (Chat Gateway)
│ Routes to PM
▼
PM Agent
│ Unclear - what thing? which repo?
│ PM sends clarification request
▼
Hermes (Chat Gateway)
│ "Which project did you mean? github.com/user/project or git.example.com/team/core?"
▼
User (Telegram): "git.example.com/team/core"
│
▼
Hermes (Chat Gateway)
│ PM receives clarification
│ PM proceeds with task
▼
...continues as Flow 1...
Flow 3: Silent Mode
User: "work on issue #7 silently"
│
▼
Hermes (Chat Gateway)
│ Routes to PM
▼
PM Agent
│ Sets mode = silent
│ "Okay, I will work silently. Check Gitea for progress."
▼
...PM works in background...
│
▼
User checks Gitea directly
│ Sees PR, comments, progress
│
User: "status"
│
▼
Hermes → PM
│ PM responds with status
▼
User
PM Agent Modes
| Mode | Behavior | Trigger |
|---|---|---|
| Notify (default) | PM sends completion message | pm notify or default |
| Silent | PM works quietly | pm silent or pm be quiet |
Implementation Notes
Hermes as Gateway
Hermes handles:
- Telegram message reception
- Natural language interpretation
- Session routing
- Response formatting
opencode Sessions
Each agent runs in its own opencode session via kugetsu:
- Sessions persist across interactions
- kugetsu manages session lifecycle
- Each session has isolated context
Gitea Integration
All agent work outputs to Gitea:
- Issue comments for progress
- PRs for code changes
- Permanent audit trail
Context Management
Storage
- Primary: Kugetsu session file (local JSON)
- Extension: Gitea comments (fetched on-demand)
Fetch Triggers
| Trigger | When |
|---|---|
| No context | Initial load - PM fetches relevant issue/PR comments |
| Explicit request | Agent decides to fetch more context |
| Insufficient | Local context not helpful - like initial case |
Context Merge Strategy
- Default: Append new context to existing
- Threshold: Summarize + replace at 40% of model context window (dynamic based on model)
Open Questions
- Telegram API vs Bot API: Use long polling (Bot API) or MTProto (user session)?
- Session timeout: How long until inactive sessions are paused?
- Message history: Store in Hermes context or external database?