# 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)