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>

PR89.md

@@ -0,0 +1,177 @@
+## Summary
+
+This PR started as the Hermes/demo/runtime seam work and has now grown into
+the main runtime stabilization branch for Claw3D.
+
+The branch now does four things:
+
+- keeps the Hermes adapter path working and easier to debug
+- makes backend selection more explicit and truthful in Studio
+- extends the runtime seam beyond OpenClaw-only assumptions
+- fixes capability mismatches that were exposing unsupported UI/actions
+
+This is now the right branch for the Hermes/runtime review path.
+
+## What Changed Since The Earlier PR Notes
+
+The earlier summary for this work is now outdated.
+
+This branch no longer only has a single OpenClaw-shaped runtime path.
+It now includes:
+
+- persisted backend selection in Studio settings
+- active backend identity surfaced in the UI
+- real provider selection across:
+  - `openclaw`
+  - `hermes`
+  - `demo`
+  - `custom`
+- Hermes/demo hello identity support
+- stronger office/runtime alignment so the office is less tightly coupled to
+  raw gateway assumptions
+- runtime and reconnect fixes discovered while exercising Hermes in the real UI
+
+## Included In This PR
+
+### 1. Hermes/runtime stability and reconnect behavior
+
+- improved Hermes adapter/runtime selection handling
+- reduced OpenClaw-specific assumptions leaking into Hermes/demo/custom paths
+- stabilized reconnect and connect-screen behavior in the office flow
+- improved local backend switching/debuggability from inside Studio
+- Studio now only auto-connects from a verified last-known-good runtime state;
+  otherwise it shows the connect overlay and waits for explicit operator choice
+- fixed a gateway connect-screen hydration bug caused by invalid HTML around the
+  inline loading avatar
+- fixed an onboarding hydration mismatch caused by reading browser storage
+  during initial render
+- kept the office mounted while gateway loading/prompt states are shown as
+  overlays instead of full page swaps
+- kept the office visible behind the runtime overlay, while making the connect
+  modal itself more opaque/readable
+- aligned Studio proxy URL resolution back to upstream `main`
+- added a small first auto-connect delay for Hermes/Demo so the initial browser
+  ws proxy attempt is less likely to race Next dev startup
+- removed destructive office camera resets that were firing on runtime-status
+  and agent-count changes
+- manual connect now cancels pending auto-connect/retry overlap before opening a
+  new Hermes/Demo attempt
+- Hermes/Demo gateway connects now allow a second internal attempt before
+  surfacing failure, which materially reduces the first-connect miss pattern in
+  local Studio testing
+
+### 2. Truthful backend selection
+
+- Studio persists the selected backend instead of only URL/token
+- the UI shows selected vs active backend
+- backend settings are now clearer and less misleading when switching between:
+  - OpenClaw
+  - Hermes
+  - Demo
+  - Custom
+
+### 3. Runtime seam expansion
+
+- provider selection is no longer effectively OpenClaw-only
+- Hermes and Demo use real provider paths
+- groundwork for direct HTTP-backed custom runtimes is included on this branch
+
+### 4. Office/runtime alignment
+
+- office bootstrap and runtime handling are less coupled to raw gateway transport
+- blank-office / reconnect edge cases were investigated and several stability
+  fixes landed during Hermes validation
+
+### 5. Luke’s findings addressed
+
+The Demo cron mismatch called out in review is fixed.
+
+Changes:
+
+- `Automations` is hidden when `supportsCapability("cron")` is false
+- cron create/run/delete now fail fast with a clear user-facing error when the
+  runtime does not support cron
+- added tests covering:
+  - no Automations tab when cron is unsupported
+  - cron mutations blocked when cron capability is unavailable
+
+## Review Follow-Up For Luke
+
+Addressed review finding:
+
+- Demo runtime no longer exposes unsupported cron mutation behavior through the
+  settings flow
+- unsupported cron actions are blocked before any RPC is sent
+
+Files directly involved in that fix:
+
+- `src/features/agents/screens/AgentsPageScreen.tsx`
+- `src/features/agents/operations/settingsSidebarTabs.ts`
+- `src/features/agents/operations/useAgentSettingsMutationController.ts`
+- `tests/unit/settingsSidebarTabs.test.ts`
+- `tests/unit/useAgentSettingsMutationController.test.ts`
+
+## Validation
+
+- [x] `npm run typecheck`
+- [x] `npx vitest run tests/unit/useGatewayConnection.test.ts tests/unit/useRuntimeConnection.test.ts`
+- [x] `npx vitest run tests/unit/useAgentSettingsMutationController.test.ts tests/unit/settingsSidebarTabs.test.ts`
+- [x] `npx vitest run tests/unit/demoGatewayAdapter.test.ts`
+
+## Scope Notes
+
+This PR still does **not** claim:
+
+- ACP-native Hermes integration
+- process launch from Studio
+- fully mature custom-runtime streaming/session semantics
+- finished office-system feature implementation
+
+## Office Systems Note
+
+The office-system roadmap/spec work exists, but it is **not** part of this
+implementation scope.
+
+That work was split into feature issue `#90`.
+
+Current docs/specs are planning artifacts only:
+
+- bulletin board
+- whiteboard
+- meeting room workflow
+- QA department
+- desk progression
+- hierarchy/teams
+
+Nothing from those office-system specs should be interpreted as already built
+in this PR.
+
+## Suggested Reviewer Focus
+
+- Hermes adapter/runtime stability in the real Studio/office flow
+- whether backend selection is now clearer and less misleading
+- whether capability claims are honest, especially for Demo
+- whether the runtime/provider seam changes remain coherent for upstream use
+
+## Remaining Follow-Up Work
+
+- ACP-backed Hermes provider as separate work
+- better Hermes profile/model visibility in settings
+- stronger reconnect persistence behavior
+- richer multi-agent Hermes flows
+- continued custom-runtime and downstream orchestrator work
+
+## Current Operator Status
+
+As of the latest local verification on April 1, 2026:
+
+- Hermes now reaches a stable connected office state without the earlier heavy
+  scene flicker/reset behavior
+- the office remains visible behind gateway loading/error overlays
+- the Demo cron capability mismatch called out in review is fixed end-to-end
+- one residual Hermes issue may still remain in some local dev sessions:
+  the first automatic connection attempt can miss once before a manual
+  `Hermes backend` + `Connect` succeeds cleanly
+
+That remaining first-attempt Hermes miss is now the only notable runtime issue
+still observed in manual browser testing for this pass.