diff --git a/docs/hermes-communication-patterns.md b/docs/hermes-communication-patterns.md new file mode 100644 index 0000000..9bf2766 --- /dev/null +++ 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="") # Check status +process(action="log", session_id="") # View output +process(action="submit", session_id="", data="continue...") # Send input +process(action="kill", session_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: <YOUR_GITEA_TOKEN> +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 <YOUR_GITEA_TOKEN>" \ + -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 <YOUR_GITEA_TOKEN>" \ + -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 <YOUR_GITEA_TOKEN>" \ + -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