From 2570a04cc687e57308ba4dac8b993e6d27f999d9 Mon Sep 17 00:00:00 2001 From: shokollm <270575765+shokollm@users.noreply.github.com> Date: Mon, 30 Mar 2026 14:38:16 +0000 Subject: [PATCH 1/3] docs #4: Document Hermes Communication Patterns MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- docs/hermes-communication-patterns.md | 307 ++++++++++++++++++++++++++ 1 file changed, 307 insertions(+) create mode 100644 docs/hermes-communication-patterns.md diff --git a/docs/hermes-communication-patterns.md b/docs/hermes-communication-patterns.md new file mode 100644 index 0000000..c3d0aa4 --- /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: 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 From b22a7da7107323b59f3c2941473d12f674daaaa6 Mon Sep 17 00:00:00 2001 From: shokollm <270575765+shokollm@users.noreply.github.com> Date: Tue, 31 Mar 2026 03:25:34 +0000 Subject: [PATCH 2/3] security: redact exposed Gitea credentials in documentation --- docs/hermes-communication-patterns.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/hermes-communication-patterns.md b/docs/hermes-communication-patterns.md index c3d0aa4..e401de6 100644 --- a/docs/hermes-communication-patterns.md +++ b/docs/hermes-communication-patterns.md @@ -154,8 +154,8 @@ Steps: 4. cat /tmp/findings-4.md 5. Post findings as Gitea issue comment -Gitea: https://git.fbrns.co -Token: 4c85c4c92637b33230a1f550287e63a0d1cef7a0 +Gitea: <GITEA_URL> +Token: <YOUR_GITEA_TOKEN> Repo: shoko/kugetsu Issue: #4""", context="Focus on: delegate_task() vs terminal(opencode), Gitea hub pattern", @@ -193,8 +193,8 @@ 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" \ +curl -X POST "<GITEA_URL>/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 \ @@ -207,8 +207,8 @@ curl -X POST "https://git.fbrns.co/api/v1/repos/shoko/kugetsu/issues/4/comments" ```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" \ +curl -X POST "<GITEA_URL>/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" @@ -227,8 +227,8 @@ git checkout -b fix/issue-3-capacity-test main 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" \ +curl -X POST "<GITEA_URL>/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", From 905e76e654c0c3c1025f11ebdd19befe418cecad Mon Sep 17 00:00:00 2001 From: shokollm <270575765+shokollm@users.noreply.github.com> Date: Tue, 31 Mar 2026 03:40:59 +0000 Subject: [PATCH 3/3] docs: use git.example.com as placeholder URL per review --- docs/hermes-communication-patterns.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/hermes-communication-patterns.md b/docs/hermes-communication-patterns.md index e401de6..9bf2766 100644 --- a/docs/hermes-communication-patterns.md +++ b/docs/hermes-communication-patterns.md @@ -154,7 +154,7 @@ Steps: 4. cat /tmp/findings-4.md 5. Post findings as Gitea issue comment -Gitea: <GITEA_URL> +Gitea: git.example.com Token: <YOUR_GITEA_TOKEN> Repo: shoko/kugetsu Issue: #4""", @@ -193,7 +193,7 @@ All agent communication flows through Gitea issues/PRs as the async record. EOF # Post as issue comment -curl -X POST "<GITEA_URL>/api/v1/repos/shoko/kugetsu/issues/4/comments" \ +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" \ @@ -207,7 +207,7 @@ curl -X POST "<GITEA_URL>/api/v1/repos/shoko/kugetsu/issues/4/comments" \ ```bash # PM posts task assignment as issue comment -curl -X POST "<GITEA_URL>/api/v1/repos/shoko/kugetsu/issues/3/comments" \ +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 '{ @@ -227,7 +227,7 @@ git checkout -b fix/issue-3-capacity-test main git push -u origin fix/issue-3-capacity-test # Create PR via API -curl -X POST "<GITEA_URL>/api/v1/repos/shoko/kugetsu/pulls" \ +curl -X POST "git.example.com/api/v1/repos/shoko/kugetsu/pulls" \ -H "Authorization: token <YOUR_GITEA_TOKEN>" \ -H "Content-Type: application/json" \ -d '{