2570a04cc6
- Identify delegate_task() (max 3) vs terminal(opencode run) (no cap) - Document Gitea as async communication hub - PM ↔ Coding Agent communication protocols - Practical examples for each pattern - Issue state machine and known limitations
308 lines
10 KiB
Markdown
308 lines
10 KiB
Markdown
# 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: https://git.fbrns.co
|
|
Token: 4c85c4c92637b33230a1f550287e63a0d1cef7a0
|
|
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 "https://git.fbrns.co/api/v1/repos/shoko/kugetsu/issues/4/comments" \
|
|
-H "Authorization: token 4c85c4c92637b33230a1f550287e63a0d1cef7a0" \
|
|
-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 "https://git.fbrns.co/api/v1/repos/shoko/kugetsu/issues/3/comments" \
|
|
-H "Authorization: token 4c85c4c92637b33230a1f550287e63a0d1cef7a0" \
|
|
-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 "https://git.fbrns.co/api/v1/repos/shoko/kugetsu/pulls" \
|
|
-H "Authorization: token 4c85c4c92637b33230a1f550287e63a0d1cef7a0" \
|
|
-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
|