---
phase: 27-hermes-adapter
plan: 01
subsystem: adapters
tags: [hermes, heartbeat, session-codec, adapter-config, vitest]

requires:
  - phase: 27-hermes-adapter
    provides: Hermes adapter installed, registered, and dual-source skill sync

provides:
  - hermes_local in SESSIONED_LOCAL_ADAPTERS — orphan process liveness checks for detached Hermes child processes
  - HermesLocalConfigFields Toolsets field restricted to edit mode — no extraArgs corruption on create
  - Hermes session codec round-trip tests (serialize, deserialize, getDisplayId, legacy key)
  - AGENT_ADAPTER_TYPES has no duplicate entries (already clean on this branch)

affects: [heartbeat, adapter-session-codecs, hermes-local-config, hermes-dual-source]

tech-stack:
  added: []
  patterns:
    - "Toolsets-in-edit-mode pattern: adapter fields that map to adapterConfig keys must be hidden in create mode to avoid extraArgs corruption"
    - "Session codec test pattern: each adapter gets serialize/deserialize/getDisplayId + legacy key variant tests in adapter-session-codecs.test.ts"

key-files:
  created:
    - ui/src/adapters/hermes-local/config-fields.tsx
    - .planning/phases/27-hermes-adapter/27-01-SUMMARY.md
  modified:
    - server/src/services/heartbeat.ts
    - server/src/__tests__/adapter-session-codecs.test.ts

key-decisions:
  - "Toolsets field moved inside !isCreate guard — new agents get default 'all' toolsets; edit form uses adapterConfig.toolsets correctly"
  - "Hermes session codec has no cwd field (unlike claude/codex/cursor/gemini) — only sessionId tracked"

patterns-established:
  - "Adapter edit-only fields pattern: fields that require adapterConfig keys go inside !isCreate block"
  - "Session codec tests: one 'normalizes X session params' test + one 'normalizes X legacy Y key' test per adapter"

requirements-completed: [HERM-01, HERM-02, HERM-03, HERM-04]

duration: 2min
completed: 2026-04-02
---

# Phase 27 Plan 01: Hermes Adapter Integration Gaps Summary

**Four HERM-01..04 integration gaps closed: hermes_local in SESSIONED_LOCAL_ADAPTERS, Toolsets field edit-only, and hermes session codec round-trip tests added**

## Performance

- **Duration:** 2 min
- **Started:** 2026-04-02T16:22:36Z
- **Completed:** 2026-04-02T16:24:58Z
- **Tasks:** 3
- **Files modified:** 3

## Accomplishments
- Added `hermes_local` to `SESSIONED_LOCAL_ADAPTERS` in heartbeat.ts — orphan process liveness checks now handle detached Hermes child processes after server restart (HERM-03)
- Created `ui/src/adapters/hermes-local/config-fields.tsx` with Toolsets field inside `{!isCreate && ...}` guard — no extraArgs corruption when creating new Hermes agents (HERM-02)
- Added hermes session codec tests to `adapter-session-codecs.test.ts` — both standard `sessionId` and legacy `session_id` key formats tested (HERM-04)
- All 16 hermes-related tests pass (9 adapter-session-codecs + 7 hermes-dual-source)

## Task Commits

Each task was committed atomically:

1. **Task 1: Fix heartbeat sessioned adapters and deduplicate constants** - `0beaf195` (feat)
2. **Task 2: Fix create-mode toolsets field in HermesLocalConfigFields** - `71128964` (feat)
3. **Task 3: Add hermes session codec test** - `4f52a18f` (test)

## Files Created/Modified
- `server/src/services/heartbeat.ts` - Added `"hermes_local"` to SESSIONED_LOCAL_ADAPTERS set
- `ui/src/adapters/hermes-local/config-fields.tsx` - Created with Toolsets field inside !isCreate guard; Model field available in both modes
- `server/src/__tests__/adapter-session-codecs.test.ts` - Added hermesSessionCodec import + 2 hermes test cases

## Decisions Made
- Toolsets field restricted to edit mode: `CreateConfigValues` has no `toolsets` field, and mapping toolsets to `extraArgs` in create mode corrupts CLI args (buildHermesConfig splits extraArgs by whitespace)
- Hermes session codec tests omit `cwd` field: hermes adapter only tracks `sessionId`, unlike claude/codex/cursor/gemini which also track `cwd`

## Deviations from Plan

None - plan executed exactly as written.

**Note:** Task 1 description mentioned removing a duplicate `gemini_local` from `AGENT_ADAPTER_TYPES`. The worktree branch (`worktree-agent-a4442902`) already had a clean constants.ts with no duplicate — the deduplication had already been applied in a prior commit (`79b61059`). No change was needed; the acceptance criterion (no duplicates) was already satisfied.

## Issues Encountered
- `hermes-local/config-fields.tsx` was not present in the worktree (only existed in commit history on other branches). Created the file from scratch matching the existing implementation from `1c44dabf` with the required Toolsets fix applied.

## Next Phase Readiness
- All four HERM-01..04 integration gaps closed
- Hermes adapter fully wired: spawning, heartbeat, session persistence, skill sync, cost tracking
- Ready for Ollama detection phase (HERM-05+) or further Hermes integration work

---
*Phase: 27-hermes-adapter*
*Completed: 2026-04-02*