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

Phase 3: Chat Integration (Telegram) #19

New Issue
Closed
opened 2026-03-30 07:11:38 +02:00 by shoko · 4 comments
shoko commented 2026-03-30 07:11:38 +02:00
Owner
Copy Link

Context

Phase 3 enables natural language interaction via chat protocols.

Architecture

Components

Component Implementation Purpose
Chat Agent Hermes (telegram session) Receives Telegram messages, handles small talk, routes to PM
PM Agent opencode session via kugetsu Manages tasks, delegates to Dev Agents, stores context locally
Dev Agents opencode sessions via kugetsu Execute tasks, post to Gitea

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)

Session Naming

  • Chat Agent: telegram session (Hermes)
  • PM Agent: pm-agent (kugetsu session)
  • Dev Agents: issue-{n} sessions (kugetsu)

Context Management

Storage

  • Primary: Kugetsu session file (local JSON)
  • Extension: Gitea comments (fetched on-demand)

Fetch Triggers

Trigger When
No context Initial load
Explicit request Agent decides to fetch more
Insufficient Local context not helpful

Context Merge

  • Default: Append new context to existing
  • Threshold: Summarize + replace at 40% of model context window (dynamic)

Message Routing

Flow

User (Telegram) → Chat Agent (Hermes)
  → Small talk: respond directly
  → Unclear intent: ask clarification
  → Task/issue/PR/repo: route to PM Agent

PM Agent Decisions

  • Small talk → respond directly
  • Task request → delegate to Dev Agent
  • Needs clarification → ask via Chat Agent → User

Output Layer

  • PM Agent → Posts to Gitea issues
  • Dev Agents → Posts to Gitea PRs
  • All decisions logged to Gitea = audit trail

PM Notification

  • Default: Notify user on task completion
  • Toggle: User can turn notifications on/off
  • Query: User can ask "status?" anytime

Implementation Plan

Phase 3a: Hermes Chat Agent

  1. Configure Hermes to receive Telegram messages
  2. Set up Chat Agent prompt (small talk, routing)

Phase 3b: PM Agent (kugetsu)

  1. Create pm-agent session via kugetsu
  2. Extend kugetsu session schema for PM context
  3. Implement context storage and merge
  4. Implement Gitea fetch on-demand

Phase 3c: Integration

  1. Connect Chat Agent → PM Agent routing
  2. PM → Dev Agent delegation via kugetsu
  3. Notification system

Open Questions

  1. Which chat protocol? Telegram
  2. Bot token creation via BotFather

Related

  • Issue #11: Phase 1: Headless/SSH Access
  • Issue #18: Phase 2: API Interface
## Context Phase 3 enables natural language interaction via chat protocols. ## Architecture ### Components | Component | Implementation | Purpose | |-----------|---------------|---------| | **Chat Agent** | Hermes (telegram session) | Receives Telegram messages, handles small talk, routes to PM | | **PM Agent** | opencode session via kugetsu | Manages tasks, delegates to Dev Agents, stores context locally | | **Dev Agents** | opencode sessions via kugetsu | Execute tasks, post to Gitea | ### 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) ### Session Naming - Chat Agent: telegram session (Hermes) - PM Agent: `pm-agent` (kugetsu session) - Dev Agents: `issue-{n}` sessions (kugetsu) ## Context Management ### Storage - **Primary**: Kugetsu session file (local JSON) - **Extension**: Gitea comments (fetched on-demand) ### Fetch Triggers | Trigger | When | |---------|------| | **No context** | Initial load | | **Explicit request** | Agent decides to fetch more | | **Insufficient** | Local context not helpful | ### Context Merge - **Default**: Append new context to existing - **Threshold**: Summarize + replace at 40% of model context window (dynamic) ## Message Routing ### Flow ``` User (Telegram) → Chat Agent (Hermes) → Small talk: respond directly → Unclear intent: ask clarification → Task/issue/PR/repo: route to PM Agent ``` ### PM Agent Decisions - Small talk → respond directly - Task request → delegate to Dev Agent - Needs clarification → ask via Chat Agent → User ## Output Layer - **PM Agent** → Posts to Gitea issues - **Dev Agents** → Posts to Gitea PRs - All decisions logged to Gitea = audit trail ## PM Notification - **Default**: Notify user on task completion - **Toggle**: User can turn notifications on/off - **Query**: User can ask "status?" anytime ## Implementation Plan ### Phase 3a: Hermes Chat Agent 1. Configure Hermes to receive Telegram messages 2. Set up Chat Agent prompt (small talk, routing) ### Phase 3b: PM Agent (kugetsu) 1. Create `pm-agent` session via kugetsu 2. Extend kugetsu session schema for PM context 3. Implement context storage and merge 4. Implement Gitea fetch on-demand ### Phase 3c: Integration 1. Connect Chat Agent → PM Agent routing 2. PM → Dev Agent delegation via kugetsu 3. Notification system ## Open Questions 1. ~~Which chat protocol?~~ **Telegram** 2. Bot token creation via BotFather ## Related - Issue #11: Phase 1: Headless/SSH Access - Issue #18: Phase 2: API Interface
shoko changed title from Phase 3: Chat Integration to Phase 3: Chat Integration (Telegram) 2026-03-30 10:55:49 +02:00
shoko commented 2026-03-30 10:58:46 +02:00
Author
Owner
Copy Link

Documentation created:

Documentation created: - [docs/kugetsu-chat.md](https://git.fbrns.co/shoko/kugetsu/src/branch/main/docs/kugetsu-chat.md) - Full Phase 3 architecture - [docs/telegram-setup.md](https://git.fbrns.co/shoko/kugetsu/src/branch/main/docs/telegram-setup.md) - Telegram bot setup - [docs/kugetsu-architecture.md](https://git.fbrns.co/shoko/kugetsu/src/branch/main/docs/kugetsu-architecture.md) - Updated with Phase 3 notes
shoko commented 2026-03-30 13:50:21 +02:00
Author
Owner
Copy Link

Documentation Created

Phase 3 architecture is now documented:

New Documentation Files

File Purpose
docs/kugetsu-chat.md Phase 3 architecture, agent types, message routing, context management
docs/kugetsu.md Overview of kugetsu system
docs/telegram-setup.md Telegram bot creation via BotFather

Key Design Decisions

  • Model B: Hermes = Chat Agent, opencode session = PM Agent
  • PM hierarchy: pm-agent (base) + pm-agent-{repo} (optional scaling)
  • Context: Kugetsu session file (local) + Gitea fetch on-demand
  • Merge strategy: Append default, summarize at 40% threshold
  • Fetch triggers: Initial, explicit, insufficient
  • Notification: Default = notify, user can toggle

See docs/kugetsu-chat.md for full architecture.

## Documentation Created Phase 3 architecture is now documented: ### New Documentation Files | File | Purpose | |------|---------| | `docs/kugetsu-chat.md` | Phase 3 architecture, agent types, message routing, context management | | `docs/kugetsu.md` | Overview of kugetsu system | | `docs/telegram-setup.md` | Telegram bot creation via BotFather | ### Key Design Decisions - **Model B**: Hermes = Chat Agent, opencode session = PM Agent - **PM hierarchy**: `pm-agent` (base) + `pm-agent-{repo}` (optional scaling) - **Context**: Kugetsu session file (local) + Gitea fetch on-demand - **Merge strategy**: Append default, summarize at 40% threshold - **Fetch triggers**: Initial, explicit, insufficient - **Notification**: Default = notify, user can toggle See [docs/kugetsu-chat.md](https://git.fbrns.co/shoko/kugetsu/src/branch/main/docs/kugetsu-chat.md) for full architecture.
shoko commented 2026-03-31 02:46:24 +02:00
Author
Owner
Copy Link

Phase 3a PR #32 - Code Review Findings

After reviewing PR #32, we discovered several architectural issues that need to be addressed for Phase 3b.

Current Architecture Problems

  1. kugetsu-helpers bypasses kugetsu CLI

    • kugetsu-helper delegate-to-pm calls opencode run --continue directly instead of going through kugetsu
    • Principle: kugetsu should be the single entrypoint for all opencode session management

  2. kugetsu-pm skill is documentation only

    • The PM Agent session created during kugetsu init only gets a simple text prompt
    • kugetsu-pm/SKILL.md (218 lines) is never actually loaded by the PM Agent
    • opencode run cannot load external skills - only built-in agents

  3. kugetsu init creates PM without proper context

    • PM Agent starts without kugetsu-pm content, without proper routing instructions

Proposed Solution for Phase 3b

1. Extend kugetsu CLI Commands

Command Purpose Replaces
kugetsu status Check initialization status kugetsu-helper check-status
kugetsu delegate <message> Send message to PM Agent kugetsu-helper delegate-to-pm
kugetsu doctor Diagnose kugetsu issues -
kugetsu doctor --fix Fix permission issues kugetsu-helper fix-permissions

2. Fix delegate command for PM Agent

Currently kugetsu continue only accepts issue-ref format (instance/user/repo#N). This should be relaxed - issue-ref is a guideline, not a hard format. Allow any session name:

kugetsu delegate "fix issue #5"
# Should continue pm-agent session, not require issue-ref format

3. Inject kugetsu-pm at init time (once), not on every delegation

During kugetsu init:

# Read kugetsu-pm/SKILL.md content
PM_CONTEXT=$(cat skills/kugetsu-pm/SKILL.md)

# Create PM session with kugetsu-pm injected
opencode run --fork --session <base-session> "You are a PM Agent. $PM_CONTEXT"

During kugetsu delegate <msg>:

# Just continue the session - kugetsu-pm is already in context
opencode run --continue --session <pm-session> "<msg>"

This way kugetsu-pm is read ONCE during init, not 10 times on 10 delegations.

4. Base PM session is immortal

  • The base pm-agent session created during kugetsu init should NEVER be deleted
  • If a specialized PM is needed (e.g., repo-specific), fork from base and close the fork when done
  • This matches the existing pattern: base session + forked issue sessions

5. Remove kugetsu-helpers

Once kugetsu CLI covers status, delegate, and doctor --fix:

  • kugetsu-helpers becomes unnecessary
  • kugetsu-chat should call kugetsu delegate instead of kugetsu-helper delegate-to-pm

6. kugetsu-pm location

Since kugetsu injects it into opencode session during init (not loaded by opencode as a skill), consider moving from skills/kugetsu-pm/ to kugetsu/pm-agent.md since it is now kugetsu's responsibility.

Summary of Changes Needed

  1. Add kugetsu status command
  2. Add kugetsu delegate <msg> command (with non-issue-ref session support)
  3. Add kugetsu doctor [--fix] command
  4. Modify kugetsu init to inject kugetsu-pm content into PM session
  5. Remove session name validation in kugetsu continue (allow any session name)
  6. Remove kugetsu-helpers (or deprecate)
  7. Update kugetsu-chat to call kugetsu delegate instead of kugetsu-helpers
  8. Optionally move kugetsu-pm to kugetsu/ directory

Questions / RFC

  • Does this architecture make sense?
  • Any concerns with the proposed approach?
## Phase 3a PR #32 - Code Review Findings After reviewing PR #32, we discovered several architectural issues that need to be addressed for Phase 3b. ### Current Architecture Problems 1. **kugetsu-helpers bypasses kugetsu CLI** - `kugetsu-helper delegate-to-pm` calls `opencode run --continue` directly instead of going through kugetsu - Principle: kugetsu should be the single entrypoint for all opencode session management 2. **kugetsu-pm skill is documentation only** - The PM Agent session created during `kugetsu init` only gets a simple text prompt - `kugetsu-pm/SKILL.md` (218 lines) is never actually loaded by the PM Agent - `opencode run` cannot load external skills - only built-in agents 3. **kugetsu init creates PM without proper context** - PM Agent starts without kugetsu-pm content, without proper routing instructions ### Proposed Solution for Phase 3b #### 1. Extend kugetsu CLI Commands | Command | Purpose | Replaces | |---------|---------|----------| | `kugetsu status` | Check initialization status | `kugetsu-helper check-status` | | `kugetsu delegate <message>` | Send message to PM Agent | `kugetsu-helper delegate-to-pm` | | `kugetsu doctor` | Diagnose kugetsu issues | - | | `kugetsu doctor --fix` | Fix permission issues | `kugetsu-helper fix-permissions` | #### 2. Fix delegate command for PM Agent Currently `kugetsu continue` only accepts issue-ref format (`instance/user/repo#N`). This should be relaxed - issue-ref is a guideline, not a hard format. Allow any session name: ```bash kugetsu delegate "fix issue #5" # Should continue pm-agent session, not require issue-ref format ``` #### 3. Inject kugetsu-pm at init time (once), not on every delegation **During `kugetsu init`:** ```bash # Read kugetsu-pm/SKILL.md content PM_CONTEXT=$(cat skills/kugetsu-pm/SKILL.md) # Create PM session with kugetsu-pm injected opencode run --fork --session <base-session> "You are a PM Agent. $PM_CONTEXT" ``` **During `kugetsu delegate <msg>`:** ```bash # Just continue the session - kugetsu-pm is already in context opencode run --continue --session <pm-session> "<msg>" ``` This way kugetsu-pm is read ONCE during init, not 10 times on 10 delegations. #### 4. Base PM session is immortal - The base pm-agent session created during `kugetsu init` should NEVER be deleted - If a specialized PM is needed (e.g., repo-specific), fork from base and close the fork when done - This matches the existing pattern: base session + forked issue sessions #### 5. Remove kugetsu-helpers Once kugetsu CLI covers status, delegate, and doctor --fix: - kugetsu-helpers becomes unnecessary - kugetsu-chat should call `kugetsu delegate` instead of `kugetsu-helper delegate-to-pm` #### 6. kugetsu-pm location Since kugetsu injects it into opencode session during init (not loaded by opencode as a skill), consider moving from `skills/kugetsu-pm/` to `kugetsu/pm-agent.md` since it is now kugetsu's responsibility. ### Summary of Changes Needed 1. Add `kugetsu status` command 2. Add `kugetsu delegate <msg>` command (with non-issue-ref session support) 3. Add `kugetsu doctor [--fix]` command 4. Modify `kugetsu init` to inject kugetsu-pm content into PM session 5. Remove session name validation in `kugetsu continue` (allow any session name) 6. Remove kugetsu-helpers (or deprecate) 7. Update kugetsu-chat to call `kugetsu delegate` instead of kugetsu-helpers 8. Optionally move kugetsu-pm to kugetsu/ directory ### Questions / RFC - Does this architecture make sense? - Any concerns with the proposed approach?
shoko commented 2026-03-31 02:56:06 +02:00
Author
Owner
Copy Link

Clarification: PR #32 Covers Whole Phase 3

PR #32 (Phase 3a) revealed architectural issues that affect both 3b and 3c. This PR will be updated to address the full Phase 3 scope:

What This PR Covers

Phase Scope Status
3a Chat Agent routing infrastructure ✅ Done
3b PM Agent with proper context, kugetsu CLI extensions (status, delegate, doctor) 🔨 In Progress
3c Full integration (Chat→PM→Dev), notifications 🔨 In Progress

Key Changes Coming

  1. kugetsu CLI extensions: status, delegate <msg>, doctor [--fix]
  2. PM Agent context: Inject kugetsu-pm at init time (once, not per-delegation)
  3. Remove kugetsu-helpers: kugetsu-chat will call kugetsu directly
  4. Fix session handling: Allow any session name in kugetsu continue, not just issue-ref

This PR now encompasses the complete Phase 3 implementation.

## Clarification: PR #32 Covers Whole Phase 3 PR #32 (Phase 3a) revealed architectural issues that affect both **3b and 3c**. This PR will be updated to address the full Phase 3 scope: ### What This PR Covers | Phase | Scope | Status | |-------|-------|--------| | **3a** | Chat Agent routing infrastructure | ✅ Done | | **3b** | PM Agent with proper context, kugetsu CLI extensions (status, delegate, doctor) | 🔨 In Progress | | **3c** | Full integration (Chat→PM→Dev), notifications | 🔨 In Progress | ### Key Changes Coming 1. **kugetsu CLI extensions**: `status`, `delegate <msg>`, `doctor [--fix]` 2. **PM Agent context**: Inject kugetsu-pm at init time (once, not per-delegation) 3. **Remove kugetsu-helpers**: kugetsu-chat will call kugetsu directly 4. **Fix session handling**: Allow any session name in `kugetsu continue`, not just issue-ref This PR now encompasses the complete Phase 3 implementation.
shoko closed this issue 2026-03-31 04:55:21 +02:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
0.2.x-only
Available only in 0.2.x, not backportable
 0.3.x-only
Available only in 0.3.x, not backportable
 backport
Backport compatible - can merge to 0.1.x
 blocked
Issue needs clarification/discussion before it can be worked on
 bug
Bug report
 critical
Critical - blocking parallel work
 feature
New feature
 foundation
Foundation work for 0.2.x
 high
High priority - workflow improvements
 meta
Meta issue tracking multiple issues
 need-review
PR needs review before merge
 parallelization
Issues related to parallelization
 ready
Issue is clear and ready to be implemented/delegated
 ready-to-merge
PR approved and ready to merge
 task-delegation
Issues related to task-delegation
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
shoko
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: shoko/kugetsu#19
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?