xiaoju
aaadab4445
When frontmatter validation fails, the step is never written to CAS, so isFirstVisit remains true on the next run. Both agent-claude-code and agent-hermes gated session cache lookup behind !isFirstVisit, which caused them to start a fresh session (and a new worktree) instead of resuming the one that already has all the work done. Changes: - Remove the isFirstVisit guard from both adapters so they always check the session cache. - When isFirstVisit + cache hit (frontmatter-only failure), send a minimal correction prompt via buildFrontmatterRetryPrompt() instead of re-sending the full initial prompt — the session already has full context, we just need the agent to re-output correctly formatted frontmatter. - Add buildFrontmatterRetryPrompt to util-agent with tests. Fixes #139
@united-workforce/agent-hermes
uwf-hermes — an agent adapter that bridges the uwf workflow engine and the Hermes CLI.
Overview
uwf-hermes is an adapter (not the Hermes CLI itself). The uwf engine speaks a generic agent protocol (stdin/stdout frontmatter contract); uwf-hermes translates that protocol into Hermes ACP (Agent Client Protocol) calls. Other adapters (e.g. uwf-claude-code, uwf-cursor) do the same for their respective CLIs.
On first visit to a role it sends a composed prompt (role definition, task, history, edge prompt); on continuation it resumes the cached session. Session transcripts and raw output are stored as CAS detail nodes.
Dependencies: @ocas/core, @united-workforce/util-agent, @united-workforce/protocol, @united-workforce/util
Installation
Included as the uwf-hermes binary when you install @united-workforce/agent-hermes:
bun add -g @united-workforce/agent-hermes
Requires the hermes CLI on PATH.
Hermes must write session JSON snapshots so uwf-hermes can load structured tool calls from disk. Add this to ~/.hermes/config.yaml:
sessions:
write_json_snapshots: true
Session files are stored at ~/.hermes/sessions/session_{sessionId}.json.
CLI Usage
Invoked by uwf thread step (not typically run directly):
uwf-hermes <thread-id> <role>
Environment variables set by the engine:
| Variable | Purpose |
|---|---|
UWF_EDGE_PROMPT |
Moderator edge instruction for this step |
Configure as the default agent via uwf setup --agent hermes.
Override per step:
uwf thread step <thread-id> --agent uwf-hermes
API
All exports come from src/index.ts.
Agent factory
function createHermesAgent(): () => Promise<void>
function buildHermesPrompt(ctx: AgentContext): string
ACP client
class HermesAcpClient {
// Spawns hermes, handles JSON-RPC over stdio
}
Usage (library)
import { createHermesAgent, buildHermesPrompt } from "@united-workforce/agent-hermes";
// CLI entry (src/cli.ts):
const main = createHermesAgent();
void main();
Internal Structure
src/
├── index.ts
├── cli.ts Binary entrypoint
├── hermes.ts createHermesAgent, buildHermesPrompt
├── acp-client.ts HermesAcpClient — ACP JSON-RPC over stdio
├── session-cache.ts Session ID cache (re-exports kit helpers + isResumeDisabled)
├── session-detail.ts Parse Hermes session JSON, store CAS detail nodes
├── schemas.ts Hermes detail CAS schemas
└── types.ts HermesSessionJson, HermesSessionMessage
Configuration
Uses workflow config from ~/.uwf/config.yaml (via agent-kit). Hermes session files are stored under the workflow storage root (see session-detail.ts).
Set UWF_HERMES_NO_RESUME=1 to disable session resume (see isResumeDisabled in session-cache.ts).