RFC: migrate hermes agent from stdout parsing to ACP protocol #398

New Issue

2026-05-22T11:38:14Z

xiaoju commented

2026-05-22 11:38:14 +00:00

Background

Current workflow-agent-hermes spawns hermes chat --quiet and parses session_id from stdout/stderr. This has a known race condition (#380) — Node.js pipe buffers may be empty on process exit.

The root cause is fundamental: mixing structured data (session_id) with unstructured output is inherently fragile.

Solution

Replace stdout/stderr parsing with ACP (Agent Communication Protocol) — a structured JSON-RPC protocol Hermes supports natively via hermes acp.

Phase Breakdown

Phase 1: ACP Client Library

Create HermesAcpClient class in workflow-agent-hermes
Implement JSON-RPC over stdin/stdout (line-delimited)
Handle initialize → initialized handshake
Send tasks via tasks/send, poll until completed
Extract output from task artifacts
Testing issue: TBD

Phase 2: Replace `spawnHermes` with ACP Client

Wire HermesAcpClient into runHermes / continueHermes
Remove spawnHermes, spawnHermesChat, spawnHermesResume, parseSessionId
Remove parseSessionIdFromStdout (no longer needed)
Keep buildHermesPrompt, buildResultFromSession unchanged
Testing issue: TBD

Phase 3: Session Management via ACP

Use ACP session capabilities to retrieve session details
Eliminate filesystem-based session loading as primary path
Keep as fallback if needed
Testing issue: TBD

Completion Criteria

All Phase testing issues closed
#380 race condition eliminated
Existing workflow runs still work (solve-issue, etc.)

Ref

Supersedes #380

## Background Current `workflow-agent-hermes` spawns `hermes chat --quiet` and parses session_id from stdout/stderr. This has a known race condition (#380) — Node.js pipe buffers may be empty on process exit. The root cause is fundamental: mixing structured data (session_id) with unstructured output is inherently fragile. ## Solution Replace stdout/stderr parsing with ACP (Agent Communication Protocol) — a structured JSON-RPC protocol Hermes supports natively via `hermes acp`. ## Phase Breakdown ### Phase 1: ACP Client Library - Create `HermesAcpClient` class in `workflow-agent-hermes` - Implement JSON-RPC over stdin/stdout (line-delimited) - Handle `initialize` → `initialized` handshake - Send tasks via `tasks/send`, poll until `completed` - Extract output from task artifacts - **Testing issue:** TBD ### Phase 2: Replace `spawnHermes` with ACP Client - Wire `HermesAcpClient` into `runHermes` / `continueHermes` - Remove `spawnHermes`, `spawnHermesChat`, `spawnHermesResume`, `parseSessionId` - Remove `parseSessionIdFromStdout` (no longer needed) - Keep `buildHermesPrompt`, `buildResultFromSession` unchanged - **Testing issue:** TBD ### Phase 3: Session Management via ACP - Use ACP session capabilities to retrieve session details - Eliminate filesystem-based session loading as primary path - Keep as fallback if needed - **Testing issue:** TBD ## Completion Criteria - [ ] All Phase testing issues closed - [ ] #380 race condition eliminated - [ ] Existing workflow runs still work (solve-issue, etc.) ## Ref Supersedes #380

xiaoju changed title from ~~refactor: migrate hermes agent integration from stdout parsing to ACP protocol~~ to RFC: migrate hermes agent from stdout parsing to ACP protocol

2026-05-22 12:05:51 +00:00

xiaoju referenced this issue

2026-05-22 12:11:19 +00:00

Phase 1 Testing: HermesAcpClient class (RFC #398) #399