2026-03-31 05:50:55 +02:00
1 changed files with 307 additions and 0 deletions
--- a/docs/hermes-communication-patterns.md
+++ b/docs/hermes-communication-patterns.md
@@ -0,0 +1,307 @@
+# Hermes Communication Patterns
+
+**Date:** 2026-03-30
+**Status:** Complete
+**Related Issue:** #4
+
+## Summary
+
+Document how Hermes passes messages between agents — the mechanisms, patterns, and practical examples for PM ↔ Coding Agent coordination.
+
+---
+
+## 1. Message Passing Mechanisms
+
+Hermes has **two distinct delegation mechanisms**, each with different concurrency characteristics:
+
+### 1.1 `delegate_task()` — Native LLM Subagent
+
+Spawns an LLM-powered subagent with its own isolated context. Communication is direct (function calls).
+
+| Attribute | Value |
+|-----------|-------|
+| Concurrency | **Max 3** (hard schema limit) |
+| Context | Fresh, isolated per subagent |
+| Tools | Full Hermes toolset |
+| Best for | Reasoning-heavy research tasks |
+
+```python
+delegate_task(
+    goal="Analyze issue #4 and document findings",
+    context="Repo: ~/repositories/kugetsu, Token: ...",
+    toolsets=["terminal", "file"]
+)
+```
+
+**Limitation:** The 3-agent cap is a schema constraint. Reaching it causes "Too many active tasks" errors. For parallel workloads, use `terminal(opencode run)` instead.
+
+### 1.2 `terminal()` + OpenCode — CLI Subprocess Wrapper
+
+Spawns an OpenCode CLI process as a child. Hermes streams output via `process()`.
+
+| Attribute | Value |
+|-----------|-------|
+| Concurrency | **No hard cap** (limited by RAM/CPU) |
+| Context | OpenCode maintains its own session state |
+| Tools | OpenCode's built-in toolset |
+| Best for | Coding agents, parallel workloads |
+
+```python
+terminal(
+    command="opencode run 'Fix issue #1: add retry logic'",
+    workdir="/tmp/issue-1",
+    timeout=300
+)
+```
+
+**Monitoring background sessions:**
+```python
+process(action="poll", session_id="<id>")    # Check status
+process(action="log", session_id="<id>")     # View output
+process(action="submit", session_id="<id>", data="continue...")  # Send input
+process(action="kill", session_id="<id>")    # Terminate
+```
+
+---
+
+## 2. Kugetsu's Gitea-Based Communication Hub
+
+Since Hermes has no native agent-to-agent protocol, Kugetsu uses **Gitea as an asynchronous communication hub**. This creates a permanent, auditable record.
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│  Hermes (Orchestrator / PM)                                  │
+│  - terminal(opencode run ...) for Coding Agents              │
+│  - delegate_task() for LLM subagents (max 3)                │
+└──────────────────────────────────────────────────────────────┘
+        │ (CLI subprocess)
+        ▼
+┌──────────────────────────┐
+│  OpenCode Subagent      │
+│  - Isolated git worktree│
+│  - Posts to Gitea via   │
+│    curl                 │
+└──────────────────────────┘
+        │ (Gitea API)
+        ▼
+┌──────────────────────────────────────────────────────────────┐
+│  Gitea (Communication Hub)                                   │
+│  - Issues as task tickets                                    │
+│  - Comments as progress updates                              │
+│  - PRs as code deliverables                                   │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### Why Gitea?
+
+- **Permanent record** — All agent work is logged in issue threads
+- **Human review** — Users supervise via Gitea, not terminal
+- **No agent-to-agent protocol needed** — Async by design
+- **PR-based code delivery** — Clean merge workflow
+
+---
+
+## 3. Communication Protocols
+
+### 3.1 PM → Human
+
+| Message | Channel |
+|---------|---------|
+| Task-split plans | Gitea issue comment |
+| Final PR approval requests | Gitea PR |
+| Blockers/escalations | Gitea issue comment |
+
+### 3.2 PM → Coding Agent
+
+| Message | Channel |
+|---------|---------|
+| Task assignment | Gitea issue comment (directs agent) |
+| PR feedback | Gitea PR comment |
+| Retry/abandon instructions | Gitea issue comment |
+
+### 3.3 Coding Agent → PM
+
+| Message | Channel |
+|---------|---------|
+| Task completion | Gitea issue comment + PR |
+| PR status | Gitea PR |
+| Blockers | Gitea issue comment |
+| Findings/research | Gitea issue comment |
+
+### 3.4 Human → Coding Agent
+
+| Message | Channel |
+|---------|---------|
+| Inline PR feedback | Gitea PR comment |
+| Priority override | Gitea issue (reassign/comment) |
+| Task adjustment | Gitea issue comment |
+
+---
+
+## 4. Practical Examples
+
+### 4.1 Delegating a Research Task (delegate_task)
+
+```python
+# In Hermes session
+result = delegate_task(
+    goal="""Work on Issue #4: Document Hermes Communication Patterns
+
+Steps:
+1. Read existing docs in ~/repositories/kugetsu/docs/
+2. Identify message passing mechanisms used
+3. Write findings to /tmp/findings-4.md
+4. cat /tmp/findings-4.md
+5. Post findings as Gitea issue comment
+
+Gitea: git.example.com
+Token: &lt;YOUR_GITEA_TOKEN&gt;
+Repo: shoko/kugetsu
+Issue: #4""",
+    context="Focus on: delegate_task() vs terminal(opencode), Gitea hub pattern",
+    toolsets=["terminal", "file"]
+)
+```
+
+### 4.2 Delegating a Coding Task (terminal + opencode)
+
+```python
+# Spawn OpenCode agent for issue #1
+terminal(
+    command="opencode run 'Fix issue #1: implement retry logic in api.py'",
+    workdir="~/repositories/kugetsu",
+    timeout=300
+)
+# Returns session_id for monitoring
+```
+
+### 4.3 Posting Findings to Gitea (from subagent)
+
+```bash
+# Write findings to temp file first
+cat > /tmp/findings-4.md << 'EOF'
+# Research Findings for Issue #4
+
+## Message Passing Mechanisms Identified
+
+1. **delegate_task()** — Max 3 concurrent LLM subagents
+2. **terminal(opencode run)** — No hard cap, CLI subprocess
+
+## Gitea Hub Pattern
+
+All agent communication flows through Gitea issues/PRs as the async record.
+EOF
+
+# Post as issue comment
+curl -X POST "git.example.com/api/v1/repos/shoko/kugetsu/issues/4/comments" \
+  -H "Authorization: token &lt;YOUR_GITEA_TOKEN&gt;" \
+  -H "Content-Type: application/json" \
+  -H "User-Agent: Kugetsu-Subagent/1.0" \
+  -d @/tmp/findings-4.md \
+  --max-time 30 \
+  --retry 3 \
+  --retry-delay 5
+```
+
+### 4.4 PM Assigns Task to Coding Agent (via Gitea)
+
+```bash
+# PM posts task assignment as issue comment
+curl -X POST "git.example.com/api/v1/repos/shoko/kugetsu/issues/3/comments" \
+  -H "Authorization: token &lt;YOUR_GITEA_TOKEN&gt;" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "body": "## Task Assignment\n\nAgent: coding-agent-1\n\n1. Explore ~/repositories/kugetsu/tools/parallel-capacity-test/\n2. Run the capacity test tool\n3. Document findings in /tmp/findings-3.md\n4. Post findings here\n\nDeadline: Before next PM review cycle"
+  }'
+```
+
+### 4.5 Coding Agent Creates PR
+
+```bash
+# Create feature branch
+git checkout -b fix/issue-3-capacity-test main
+
+# ... do work ...
+
+# Push and create PR
+git push -u origin fix/issue-3-capacity-test
+
+# Create PR via API
+curl -X POST "git.example.com/api/v1/repos/shoko/kugetsu/pulls" \
+  -H "Authorization: token &lt;YOUR_GITEA_TOKEN&gt;" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "title": "fix #3: Add parallel capacity test tool",
+    "body": "## Summary\n\nImplements parallel capacity testing for Hermes/OpenCode.\n\n## Testing\n\n- [ ] Tool runs without errors\n- [ ] Output logged to /tmp/capacity-test.log",
+    "head": "fix/issue-3-capacity-test",
+    "base": "main"
+  }'
+```
+
+---
+
+## 5. Known Limitations
+
+| Limitation | Impact | Workaround |
+|------------|--------|------------|
+| `delegate_task()` max 3 cap | Can't spawn 4+ LLM subagents | Use `terminal(opencode run)` for coding agents |
+| No native agent-to-agent protocol | Must use Gitea as hub | Async communication via issues/comments |
+| OpenCode session management | Sessions can hang | Use `timeout` wrapper, kill stale sessions |
+| Gitea rate limiting | Too-frequent API calls blocked | Add delays, use `--retry` |
+
+---
+
+## 6. Issue State Machine
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Issue Lifecycle (Gitea-based async coordination)            │
+└─────────────────────────────────────────────────────────────┘
+
+OPEN ──► IN_PROGRESS (PM assigns to Coding Agent)
+              │
+              ▼
+       AWAITING_FEEDBACK (Coding Agent posted findings)
+              │
+              ▼
+         IN_PROGRESS (Human/PM replied, coding continues)
+              │
+              ▼
+        COMPLETED (Coding Agent merged, PM closes)
+```
+
+---
+
+## 7. Checklist (from Issue #4)
+
+- [x] Message passing mechanism identified
+  - `delegate_task()` for LLM subagents (max 3)
+  - `terminal(opencode run)` for parallel coding agents
+  - Gitea as async communication hub
+- [x] Agent-to-agent communication tested
+  - Hermes → OpenCode via terminal subprocess
+  - OpenCode → Gitea via curl
+- [x] PM ↔ Coding Agent communication tested
+  - PM assigns via Gitea issue comment
+  - Coding Agent reports via Gitea PR/comment
+- [x] Examples documented
+  - Research delegation (delegate_task)
+  - Coding delegation (terminal + opencode)
+  - Gitea posting patterns
+  - PR creation workflow
+
+---
+
+## References
+
+- [Hermes Setup Guide](./hermes-setup.md)
+- [Kugetsu Architecture](./kugetsu-architecture.md)
+- [Subagent Workflow](./SUBAGENT_WORKFLOW.md)
+- [Hermes Agent GitHub](https://github.com/nousresearch/hermes-agent)
+- [Hermes Agent Docs](https://hermes-agent.nousresearch.com)
+
+---
+
+## Status History
+
+- 2026-03-30: Initial documentation — addresses all checklist items from issue #4