shoko/kugetsu
1
0
Fork 0
Code Issues 17 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

docs: add Phase 3 chat architecture and overview documentation

Browse Source 
- Add docs/kugetsu-chat.md:
  - Model B architecture (separate Chat/PM agents)
  - Session types (chat-agent, pm-agent, pm-agent-{repo}, issue sessions)
  - Hybrid message routing
  - PM Agent modes (notify/silent)
  - Context management (local + Gitea fetch on-demand)
  - Example flows

- Add docs/kugetsu.md:
  - Overview of kugetsu system
  - Quick start guide
  - Links to all documentation

- Update docs/kugetsu-architecture.md:
  - Add Phase 3 architecture section
  - Update success criteria
  - Add Phase 3 design decisions

- Add docs/telegram-setup.md:
  - BotFather bot creation guide
  - Security notes

- Remove ssh-keygen.sh (not needed)
This commit is contained in:
shokollm
2026-03-30 11:46:12 +00:00
parent 4606c59ce8
commit 202d8ccfbb
4 changed files with 525 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

240
docs/kugetsu-chat.md Normal file
View File

@@ -0,0 +1,240 @@
# Kugetsu Chat Architecture (Phase 3)
**Status:** Planned (Not Yet Implemented)
**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.fbrns.co/team/core?"
▼
User (Telegram): "git.fbrns.co/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)