{
  "id": "page:docs-hermes-research-integration-plan",
  "_kind": "Page",
  "_file": "wiki/docs/hermes-research/integration-plan.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/hermes-research/integration-plan.md",
    "sourceKind": "repo-docs",
    "title": "Hermes Integration Plan",
    "displayName": "Hermes Integration Plan",
    "slug": "docs/hermes-research/integration-plan",
    "articlePath": "wiki/docs/hermes-research/integration-plan.md",
    "article": "\n# Hermes Integration Plan\n\n## Adapter Implementation Plan\n\n### Phase 1: Upgrade adapter-hermes from shell-hook to JSON-RPC (Priority: High)\n\n**Current state:** The adapter at `packages/adapters/hooks/adapter-hermes/` operates as a `shell-hook` family adapter. It receives a single `onEvent` stdin payload, normalizes it to a unified hook event, and cannot block, deny, or mutate tool calls. This is the minimum viable integration.\n\n**Target state:** Upgrade to leverage Hermes' TUI Gateway JSON-RPC protocol for bidirectional control.\n\n**Implementation steps:**\n\n1. **Add JSON-RPC client to adapter-hermes**\n   - File: `packages/adapters/hooks/adapter-hermes/src/rpc-client.ts`\n   - Implement a JSON-RPC client that connects to Hermes' TUI Gateway (stdio or WebSocket)\n   - Support methods: `session.create`, `prompt.submit`, `session.history`, `approval.respond`, `clarify.respond`\n   - Handle events: `message.delta`, `message.complete`, `tool.start`, `tool.progress`, `tool.complete`\n\n2. **Extend adapter capabilities**\n   - File: `packages/adapters/hooks/adapter-hermes/src/adapter.ts`\n   - Upgrade `family` from `shell-hook` to `rpc-bridge`\n   - Enable `supportsBlock: true` (via approval.respond)\n   - Enable `supportsAsk: true` (via clarify.respond)\n   - Keep `supportsToolInputMutation: false` and `supportsToolResultMutation: false` (Hermes does not support these)\n\n3. **Add session management**\n   - File: `packages/adapters/hooks/adapter-hermes/src/session-manager.ts`\n   - Track active Hermes sessions and map them to babysitter run sessions\n   - Support session creation, listing, activation, and cleanup\n\n4. **Update normalizer for bidirectional events**\n   - File: `packages/adapters/hooks/adapter-hermes/src/normalizer.ts`\n   - Add normalization for all TUI Gateway event types (currently only handles `onEvent`)\n   - Map Hermes `tool.start`/`tool.progress`/`tool.complete` to unified pre/post tool events\n\n### Phase 2: Gateway bridge for messaging delivery (Priority: Medium)\n\n**Goal:** Route babysitter orchestration results to Hermes' 20+ messaging platforms.\n\n**Implementation steps:**\n\n1. **Create gateway bridge module**\n   - File: `packages/adapters/gateway/src/hermes-bridge.ts`\n   - Connect to Hermes gateway's delivery API\n   - Map babysitter run events (task completion, breakpoint hit, approval needed) to Hermes gateway `send_message` calls\n   - Support targeting specific platforms (Telegram, Discord, Slack) by chat ID\n\n2. **Add notification routing**\n   - File: `packages/adapters/gateway/src/notifications/hermes-relay.ts`\n   - Register Hermes gateway as a notification backend in our gateway\n   - Route babysitter notification events to the Hermes gateway process\n\n3. **Authorization mapping**\n   - Map our gateway auth tokens to Hermes gateway authorization\n   - Support DM pairing flow for user onboarding\n\n### Phase 3: Memory synchronization (Priority: Low)\n\n**Goal:** Bidirectional memory sync between babysitter crossRunState and Hermes memory files.\n\n**Implementation steps:**\n\n1. **Create memory sync plugin**\n   - File: `packages/adapters/extensions/src/targets/hermes/memory-sync.ts`\n   - Read Hermes' `MEMORY.md` and `USER.md` at babysitter run start\n   - Write babysitter crossRunState insights back to Hermes memory files at run end\n\n2. **Leverage Hermes memory provider hooks**\n   - If Hermes is the execution harness, hook into `on_session_end` to capture extracted memory\n   - Feed captured memory into babysitter run journal for cross-run state\n\n### Phase 4: Provider catalog bridge (Priority: Low)\n\n**Goal:** Expose Hermes' 30+ provider catalog through our adapters proxy.\n\n**Implementation steps:**\n\n1. **Add Hermes provider backend to adapters proxy**\n   - File: `packages/adapters/proxy/src/adapters_proxy/providers/hermes.py`\n   - Query Hermes' runtime resolver for available providers\n   - Map provider capabilities to our proxy's provider interface\n   - Route inference requests through Hermes when using its unique providers (Nous Portal, NovitaAI, etc.)\n\n---\n\n## Hook Wiring Plan\n\n### Event mapping (current adapter-hermes)\n\n| Hermes Native Event | Unified Phase | Direction | Notes |\n|---------------------|---------------|-----------|-------|\n| `onEvent` (tool.start) | `tool.before` | post | Cannot block |\n| `onEvent` (tool.complete) | `tool.after` | post | Cannot mutate result |\n| `onEvent` (session.start) | `session.start` | post | |\n| `onEvent` (session.end) | `session.end` | post | |\n| `onEvent` (agent.step) | `turn.after` | post | |\n\n### Planned event mapping (with JSON-RPC upgrade)\n\n| Hermes RPC Event | Unified Phase | Direction | Notes |\n|------------------|---------------|-----------|-------|\n| `tool.start` | `tool.before` | pre+post | Can block via approval |\n| `tool.progress` | `tool.during` | stream | Progress updates |\n| `tool.complete` | `tool.after` | post | Result available |\n| `message.delta` | `response.stream` | stream | Token-by-token |\n| `message.complete` | `response.complete` | post | Full response |\n| `approval_request` | `approval.request` | pre | Block and wait |\n| `clarify_request` | `clarify.request` | pre | Block and wait |\n\n### Hook lifecycle integration\n\n```\nbabysitter run start\n  |\n  +-- adapter-hermes creates Hermes session (session.create RPC)\n  |\n  +-- babysitter submits task prompt (prompt.submit RPC)\n  |\n  +-- Hermes AIAgent processes turns:\n  |     |\n  |     +-- tool.start -> unified pre-tool hook -> governance check\n  |     |\n  |     +-- approval_request -> adapter bridges to babysitter breakpoint\n  |     |\n  |     +-- tool.complete -> unified post-tool hook -> effect recording\n  |     |\n  |     +-- message.delta -> streaming renderer\n  |     |\n  |     +-- message.complete -> babysitter task result capture\n  |\n  +-- adapter-hermes captures session history\n  |\n  +-- babysitter records effects and journal entries\n```\n\n---\n\n## Test Strategy\n\n### Unit tests (adapter-hermes)\n\nLocation: `packages/adapters/hooks/adapter-hermes/src/__tests__/`\n\n| Test file | Coverage |\n|-----------|----------|\n| `adapter.test.ts` | Adapter capabilities, family assignment, capability flags |\n| `normalizer.test.ts` | Event normalization, stdin parsing, session ID extraction |\n| `mappings.test.ts` | Phase mapping table completeness |\n| `renderer.test.ts` | Output rendering for Hermes format |\n| `session-resolver.test.ts` | Session resolution from env vars |\n\n**New tests needed for Phase 1:**\n\n| Test file | Coverage |\n|-----------|----------|\n| `rpc-client.test.ts` | JSON-RPC method calls, event handling, error recovery |\n| `session-manager.test.ts` | Session lifecycle, mapping to babysitter runs |\n| `bidirectional-normalizer.test.ts` | All TUI Gateway event types |\n\n### Integration tests\n\n| Test | Description |\n|------|-------------|\n| `hermes-shell-hook-e2e` | Verify current shell-hook adapter normalizes real Hermes onEvent payloads |\n| `hermes-rpc-session-e2e` | Verify JSON-RPC session creation and prompt submission (Phase 1) |\n| `hermes-gateway-delivery-e2e` | Verify babysitter notifications route through Hermes gateway (Phase 2) |\n\n### Live-stack tests\n\n| Test | Description |\n|------|-------------|\n| `hermes-babysitter-create` | Babysitter creates a session in Hermes, submits a simple task, captures result |\n| `hermes-babysitter-resume` | Babysitter resumes a Hermes session across process restarts |\n| `hermes-approval-bridge` | Hermes approval request bridges to babysitter breakpoint and back |\n\n### Test fixtures\n\nHermes event fixtures already exist at:\n`packages/adapters/hooks/adapter-hermes/src/__tests__/fixtures/hermes-events.ts`\n\nAdditional fixtures needed:\n- TUI Gateway JSON-RPC response payloads\n- Gateway message delivery payloads\n- Memory provider hook payloads\n\n### CI integration\n\n- Hermes adapter unit tests run in the existing `npm run test:hooks-adapter` pipeline\n- Integration tests require Hermes installed as a dependency (`pip install hermes-agent`)\n- Live-stack tests require a running Hermes instance with a configured provider\n- Gate: all adapter unit tests must pass before integration tests run\n\n---\n\n## Risk Assessment\n\n| Risk | Mitigation |\n|------|------------|\n| Hermes API instability (pre-1.0) | Pin to specific version range; adapter capabilities read from atlas catalog |\n| Python/TypeScript bridge complexity | JSON-RPC is language-agnostic; stdio transport avoids FFI |\n| Session state divergence | Adapter-hermes is authoritative for session mapping; Hermes sessions are ephemeral from our perspective |\n| Gateway auth mismatch | Map our auth tokens to Hermes platform-specific auth; do not store Hermes credentials in our config |\n| Memory format drift | Schema-validate MEMORY.md/USER.md content before writing; fail-open on parse errors |\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-hermes-research",
      "to": "page:docs-hermes-research-integration-plan",
      "kind": "contains_page"
    }
  ]
}