240 lines
9.5 KiB
Markdown
240 lines
9.5 KiB
Markdown
# 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
|
|
|
|
1. **Telegram API vs Bot API**: Use long polling (Bot API) or MTProto (user session)?
|
|
2. **Session timeout**: How long until inactive sessions are paused?
|
|
3. **Message history**: Store in Hermes context or external database?
|
|
|
|
---
|
|
|
|
## Related Documentation
|
|
|
|
- [Telegram Setup Guide](telegram-setup.md)
|
|
- [kugetsu Architecture](kugetsu-architecture.md)
|
|
- [Subagent Workflow](SUBAGENT_WORKFLOW.md) |