xiaoju
32bbea0f32
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. Remove the isFirstVisit guard from both adapters so they always check the session cache. If no cache entry exists, the behavior is unchanged (fresh session). If a cache entry exists, the agent resumes the previous session regardless of CAS step state. 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).