feat: add runtime seam, Hermes adapter support, and demo gateway mode (#89)
* fix: include kanbanImmersive in immersiveOverlayActive calculation When Kanban board is open, HUD elements (camera preset buttons, edit toolbar, overlays) should be suppressed. The kanbanImmersive flag was defined but not included in the immersiveOverlayActive condition, causing HUD elements to remain visible. This fix adds kanbanImmersive to the immersiveOverlayActive calculation so HUD elements are properly hidden when the Kanban board is open. Co-authored-by: Luke The Dev <iamlukethedev@users.noreply.github.com> * Fix: Hide mini status bar when Kanban immersive overlay is open Wraps the bottom-left mini status bar (showing agent stats, vibe score, and control hints) with !immersiveOverlayActive check to match the behavior of other HUD elements like camera controls and toolbar. This ensures the status bar is properly hidden when the Kanban board or any other immersive overlay is active, maintaining a clean immersive experience. Co-authored-by: Luke The Dev <iamlukethedev@users.noreply.github.com> * chore: drop unrelated package-lock line from branch Co-authored-by: Luke The Dev <iamlukethedev@users.noreply.github.com> * universal-backend-plan * backend-neutral runtime seam * package.json update * feat: add Hermes gateway adapter as alternative to OpenClaw Adds a WebSocket adapter that lets Claw3D connect to a Hermes AI agent runtime without any changes to the frontend. The adapter implements the full Claw3D gateway protocol and bridges it to the Hermes HTTP API. Changes: - server/hermes-gateway-adapter.js: WebSocket bridge implementing the Claw3D gateway protocol against the Hermes HTTP API. Supports all core methods (agents, sessions, chat streaming, cron, config, files, approvals) and multi-agent orchestration via spawn_agent/delegate_task tools. Persists conversation history to ~/.hermes/clawd3d-history.json. - scripts/clawd3d-start.sh: All-in-one startup script that launches Hermes, the adapter, and the Next.js dev server with auto port conflict resolution. Alias as `claw3d` for convenience. - src/features/office/hooks/useCronAgents.ts: Hook that polls the gateway for cron-scheduled agents and surfaces them in the 3D office. - package.json: adds `hermes-adapter` npm script - .env.example: documents Hermes config vars - docs/hermes-gateway.md: setup guide and protocol reference Usage: npm run hermes-adapter # start adapter (connect to http://localhost:8642) npm run dev # start Claw3D, point browser at localhost:3000 # or: bash scripts/clawd3d-start.sh (starts everything automatically) Both OpenClaw and Hermes are supported simultaneously — the gateway URL in NEXT_PUBLIC_GATEWAY_URL determines which backend Claw3D connects to. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat: add read_agent_context tool for cross-agent coordination Agents can now read each other's conversation history via the read_agent_context tool, enabling the orchestrator to check what a sub-agent has done before re-delegating work. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat: wire Hermes office UX and role-aware runtime updates * feature update - demomode & hermes adapter * fix lint blockers * lintfix #2 * fix: stabilize retro office camera preset callbacks * Initial plan * fix: stabilize retro office overview preset hooks Agent-Logs-Url: https://github.com/gsknnft/Claw3D/sessions/9cc71555-591e-44cf-aec4-25affbdcb405 Co-authored-by: gsknnft <123185582+gsknnft@users.noreply.github.com> * feat: add truthful backend selection, Hermes adapter hardening, and demo gateway mode * fix: address bugbot review and finalize backend selection * fixed - onboarding and hermes calls * office systems roadmap * feat specs in docs * specs ready * feat: continue custom runtime seam and gateway alignment * custom lane wired * feat: add custom runtime provider path and office runtime alignment * runtime fixes * fix lukes findings * fix lukes findings #2 * stable UI & connect screen page -> overlay * better baseline for connection * stable providers & ui rendering * best launch yet * nearly no gateway on reconnect * auto reconnect last state * fix: preserve selected runtime across reconnects Keep backend selection aligned with the operator's chosen runtime instead of reviving a mismatched last-known-good adapter, and keep custom runtimes prompting for reconnect when Studio cannot auto-connect them. Made-with: Cursor --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: Luke The Dev <iamlukethedev@users.noreply.github.com> Co-authored-by: Elias Pfeffer <eliaspfeffer@gmail.com> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: iamlukethedev <lucas.guilherme@smartwayslfl.com>
This commit is contained in:
gsknnft
@@ -0,0 +1,161 @@
|
||||
# Hermes Gateway Adapter
|
||||
|
||||
Claw3D can run against Hermes by using the bundled adapter in
|
||||
[`server/hermes-gateway-adapter.js`](../server/hermes-gateway-adapter.js).
|
||||
|
||||
This is the current production-ready Hermes path in this repository.
|
||||
It is not yet a fully native Studio-side Hermes provider. Instead, it
|
||||
uses the runtime seam in Studio while Hermes is exposed through a
|
||||
Claw3D-compatible WebSocket adapter.
|
||||
|
||||
## Architecture
|
||||
|
||||
```text
|
||||
Browser UI <-> Studio runtime/client <-> Hermes gateway adapter <-> Hermes HTTP API
|
||||
```
|
||||
|
||||
The frontend keeps using the Claw3D gateway protocol. The Hermes adapter
|
||||
translates that protocol into Hermes HTTP calls and streams the results
|
||||
back as gateway events.
|
||||
|
||||
## Quick start
|
||||
|
||||
### 1. Start Hermes
|
||||
|
||||
Start your Hermes API server. The default expected endpoint is:
|
||||
|
||||
```text
|
||||
http://localhost:8642
|
||||
```
|
||||
|
||||
### 2. Configure environment
|
||||
|
||||
Copy `.env.example` to `.env` and set the Hermes values:
|
||||
|
||||
```env
|
||||
NEXT_PUBLIC_GATEWAY_URL=ws://localhost:18789
|
||||
|
||||
HERMES_API_URL=http://localhost:8642
|
||||
HERMES_API_KEY=
|
||||
HERMES_ADAPTER_PORT=18789
|
||||
HERMES_MODEL=hermes
|
||||
HERMES_AGENT_NAME=Hermes
|
||||
```
|
||||
|
||||
### 3. Start Claw3D and the adapter
|
||||
|
||||
In separate terminals:
|
||||
|
||||
```bash
|
||||
npm run hermes-adapter
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Then open `http://localhost:3000` and connect to:
|
||||
|
||||
```text
|
||||
ws://localhost:18789
|
||||
```
|
||||
|
||||
In the connect screen, select `Hermes backend`. Claw3D will persist that
|
||||
selection in Studio settings and show `Hermes` as the active backend once
|
||||
the adapter hello response is received.
|
||||
|
||||
### 4. Optional all-in-one local startup
|
||||
|
||||
The repo also includes:
|
||||
|
||||
```bash
|
||||
bash scripts/clawd3d-start.sh
|
||||
```
|
||||
|
||||
That script now resolves the repo root dynamically from the script
|
||||
location instead of assuming a machine-specific checkout path.
|
||||
|
||||
## What this adapter supports
|
||||
|
||||
The adapter currently supports the Claw3D surfaces needed for normal
|
||||
office use:
|
||||
|
||||
- Agent listing, creation, update, and deletion
|
||||
- Session listing, preview, patch, reset, and history lookup
|
||||
- Chat send, targeted abort, and run wait
|
||||
- Config get/set/patch shims needed by the Studio UI
|
||||
- Models and skills status
|
||||
- Exec approvals surfaces used by the current UI
|
||||
- Cron list/add/remove/patch/run
|
||||
- Multi-agent orchestration tools on the Hermes side
|
||||
|
||||
## Hermes orchestration tools
|
||||
|
||||
The main Hermes agent acts as an orchestrator with these tools:
|
||||
|
||||
| Tool | Description |
|
||||
|---|---|
|
||||
| `spawn_agent` | Create a specialist sub-agent |
|
||||
| `delegate_task` | Send work to a specific agent |
|
||||
| `list_team` | List active agents, names, and roles |
|
||||
| `configure_agent` | Update agent name, role, instructions, or settings |
|
||||
| `dismiss_agent` | Remove an agent from the team |
|
||||
| `read_agent_context` | Read another agent's recent conversation history for coordination |
|
||||
|
||||
Sub-agents appear in the office as separate characters and keep their
|
||||
own conversation state.
|
||||
|
||||
## Production-readiness notes
|
||||
|
||||
This adapter includes the fixes that blocked the original Hermes PR:
|
||||
|
||||
- `chat.abort` now aborts only the requested `runId` or `sessionKey`
|
||||
instead of cancelling every active run
|
||||
- history clears from `sessions.reset`, `agents.delete`, and
|
||||
`dismiss_agent` now persist to disk immediately
|
||||
- `scripts/clawd3d-start.sh` no longer hardcodes one developer's local path
|
||||
|
||||
## ACP status
|
||||
|
||||
Hermes has a real ACP surface and that remains the preferred long-term
|
||||
integration direction.
|
||||
|
||||
This branch does not replace the adapter with ACP yet. The current
|
||||
production-ready path uses the adapter because it works with the existing
|
||||
Claw3D gateway contract today and is ready for upstream testing now.
|
||||
|
||||
The runtime seam added in Studio is what makes an ACP-backed Hermes
|
||||
provider feasible as a follow-up without reworking the whole UI again.
|
||||
|
||||
## Persistence
|
||||
|
||||
Conversation history is stored at:
|
||||
|
||||
```text
|
||||
~/.hermes/clawd3d-history.json
|
||||
```
|
||||
|
||||
It is loaded on startup and updated when conversations change.
|
||||
|
||||
## Current limitations
|
||||
|
||||
- Hermes is integrated through the adapter path today, not yet through a
|
||||
dedicated native Studio provider implementation
|
||||
- Config and approvals behavior still matches the current adapter contract,
|
||||
not a fully Hermes-native settings model
|
||||
- This path is intended to get Hermes working reliably now while the
|
||||
broader runtime-provider architecture continues to mature
|
||||
|
||||
## When to use demo mode instead
|
||||
|
||||
If you only want to see the office boot without installing Hermes or
|
||||
OpenClaw, use:
|
||||
|
||||
```bash
|
||||
npm run demo-gateway
|
||||
npm run dev
|
||||
```
|
||||
|
||||
That starts a bundled mock gateway for a no-framework Claw3D demo.
|
||||
|
||||
## Using OpenClaw instead
|
||||
|
||||
If you want the OpenClaw path, do not run the Hermes adapter. Start
|
||||
OpenClaw and point Claw3D at that gateway instead.
|
||||
Reference in New Issue
Block a user