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,300 @@
|
||||
# Custom Runtime Provider Spec
|
||||
|
||||
> Generic extension seam for non-OpenClaw, non-Hermes stacks.
|
||||
|
||||
## Goal
|
||||
|
||||
Define a clean `custom` runtime provider class for Claw3D.
|
||||
|
||||
This provider should let external orchestration stacks integrate with Claw3D through a stable seam without requiring:
|
||||
|
||||
- OpenClaw emulation
|
||||
- Hermes-specific semantics
|
||||
- named first-class core support for every stack
|
||||
|
||||
The idea is:
|
||||
|
||||
- upstream concept: `custom` provider
|
||||
- downstream implementations provide their own runtime behavior against that seam
|
||||
|
||||
## Current Branch Status
|
||||
|
||||
On `dev/vera_lane`, the `custom` provider is no longer just a design
|
||||
placeholder.
|
||||
|
||||
Current implemented behavior:
|
||||
|
||||
- `custom` is a first-class provider ID in the runtime seam
|
||||
- Studio persists the selected backend mode as `custom`
|
||||
- the provider exposes runtime metadata such as `runtimeName`, `vendor`,
|
||||
`runtimeVersion`, and `routeProfile` when available
|
||||
- Claw3D probes `GET /health`, `GET /state`, and `GET /registry`
|
||||
- chat uses a direct HTTP path to `POST /v1/chat/completions`
|
||||
- browser traffic is proxied through Claw3D's same-origin
|
||||
`/api/runtime/custom` route instead of calling the runtime directly
|
||||
|
||||
Still intentionally missing in this branch:
|
||||
|
||||
- normalized streaming event support
|
||||
- richer session persistence beyond the synthetic provider session layer
|
||||
- direct approvals/files/cron surfaces
|
||||
- process auto-launch from Studio
|
||||
|
||||
## Why This Matters
|
||||
|
||||
Not every useful runtime should have to become a named built-in provider in upstream Claw3D.
|
||||
|
||||
A clean custom provider seam gives:
|
||||
|
||||
- extensibility
|
||||
- lower upstream friction
|
||||
- room for proprietary or stack-specific orchestration
|
||||
- a path for advanced internal systems without polluting core abstractions
|
||||
|
||||
This is especially important when a stack is:
|
||||
|
||||
- internal
|
||||
- organization-specific
|
||||
- experimental
|
||||
- orchestration-heavy
|
||||
|
||||
## Product Position
|
||||
|
||||
The `custom` provider should be treated as:
|
||||
|
||||
- a first-class extension seam
|
||||
- not a hack
|
||||
- not a vendor-specific side path
|
||||
|
||||
This is the upstream-safe abstraction.
|
||||
|
||||
## Relationship To Existing Provider Work
|
||||
|
||||
Claw3D’s runtime abstraction already points toward multiple providers:
|
||||
|
||||
- `openclaw`
|
||||
- `hermes`
|
||||
- future providers
|
||||
|
||||
The `custom` provider should sit alongside those as a generic lane for:
|
||||
|
||||
- external orchestrators
|
||||
- private agent stacks
|
||||
- organization-specific routing systems
|
||||
|
||||
## Core Principle
|
||||
|
||||
Do not leak implementation-specific internal logic into the generic provider contract.
|
||||
|
||||
The provider should expose:
|
||||
|
||||
- common runtime behaviors
|
||||
- provider capabilities
|
||||
- normalized events
|
||||
- optional metadata
|
||||
|
||||
It should not require upstream Claw3D to know:
|
||||
|
||||
- runtime-specific routing internals
|
||||
- proprietary state logic
|
||||
- private planning models
|
||||
- stack-specific heuristics
|
||||
|
||||
## Provider Identity
|
||||
|
||||
Suggested provider IDs:
|
||||
|
||||
- `openclaw`
|
||||
- `hermes`
|
||||
- `custom`
|
||||
|
||||
Then allow custom metadata such as:
|
||||
|
||||
```ts
|
||||
type CustomRuntimeDescriptor = {
|
||||
providerId: "custom";
|
||||
runtimeName: string;
|
||||
runtimeVersion?: string | null;
|
||||
vendor?: string | null;
|
||||
capabilities?: string[];
|
||||
};
|
||||
```
|
||||
|
||||
This gives Claw3D enough identity for UI without hardcoding a brand into the provider class.
|
||||
|
||||
## Reference Implementation Strategy
|
||||
|
||||
The `custom` provider should exist as a generic extension seam.
|
||||
|
||||
That means:
|
||||
|
||||
- upstream Claw3D gets `custom`
|
||||
- downstream stacks supply their own behavior
|
||||
- others can later implement their own custom providers against the same seam
|
||||
|
||||
That is much easier to justify upstream than:
|
||||
|
||||
- adding a deeply stack-specific built-in provider before the generic extension seam exists
|
||||
|
||||
## Suggested Contract Shape
|
||||
|
||||
This should align with the existing runtime abstraction, but allow custom metadata.
|
||||
|
||||
Example:
|
||||
|
||||
```ts
|
||||
type RuntimeProviderId = "openclaw" | "hermes" | "custom";
|
||||
|
||||
type RuntimeProviderMetadata = {
|
||||
id: RuntimeProviderId;
|
||||
label: string;
|
||||
runtimeName?: string | null;
|
||||
runtimeVersion?: string | null;
|
||||
vendor?: string | null;
|
||||
};
|
||||
```
|
||||
|
||||
The `custom` provider should still implement the same base runtime methods:
|
||||
|
||||
- list agents
|
||||
- list sessions
|
||||
- send chat
|
||||
- abort run
|
||||
- wait for run
|
||||
- stream normalized events
|
||||
- expose capabilities honestly
|
||||
|
||||
## Capability Philosophy
|
||||
|
||||
The custom provider should be capability-driven, not assumption-driven.
|
||||
|
||||
That means if a custom stack supports:
|
||||
|
||||
- roles
|
||||
- approvals
|
||||
- files
|
||||
- cron
|
||||
- whiteboard integration
|
||||
- meeting signals
|
||||
|
||||
it should declare those clearly.
|
||||
|
||||
If it does not, the UI should degrade honestly.
|
||||
|
||||
## Event Model
|
||||
|
||||
The custom provider should emit the same normalized event categories as other providers.
|
||||
|
||||
Examples:
|
||||
|
||||
- `presence.changed`
|
||||
- `session.activity`
|
||||
- `chat.delta`
|
||||
- `chat.final`
|
||||
- `chat.error`
|
||||
- `run.lifecycle`
|
||||
- `tool.progress`
|
||||
|
||||
This keeps Claw3D stable even if the custom stack has richer private event semantics internally.
|
||||
|
||||
## Custom Metadata Surface
|
||||
|
||||
The custom provider may optionally expose richer metadata for display.
|
||||
|
||||
Examples:
|
||||
|
||||
- routed lane
|
||||
- active model id
|
||||
- strategy label
|
||||
- execution mode
|
||||
- custom stack status
|
||||
|
||||
Important:
|
||||
|
||||
This metadata should be additive and optional.
|
||||
|
||||
It should not change the core runtime contract.
|
||||
|
||||
## Reference Implementation Model
|
||||
|
||||
A custom provider can reasonably map:
|
||||
|
||||
- agents -> routed roles / lanes
|
||||
- sessions -> runtime conversations
|
||||
- streaming -> orchestrator or gateway output streams
|
||||
- provider metadata -> runtime name, lane, model, or route state
|
||||
|
||||
The public upstream concept remains `custom`.
|
||||
|
||||
Implementation-specific mapping stays in the runtime layer.
|
||||
|
||||
## Relationship To Agent State Model
|
||||
|
||||
The custom provider is the right place for richer internal state to enter Claw3D.
|
||||
|
||||
For example:
|
||||
|
||||
- a custom runtime computes deeper control or state signals
|
||||
- the provider maps them into public office states
|
||||
|
||||
This keeps:
|
||||
|
||||
- internal intelligence private
|
||||
- public office state understandable
|
||||
|
||||
## Relationship To Office Systems
|
||||
|
||||
The custom provider should be able to support office systems without Claw3D needing to know the backend’s internals.
|
||||
|
||||
Examples:
|
||||
|
||||
- bulletin board gets agent/session/task context
|
||||
- whiteboard gets planning-session context
|
||||
- meetings get coordination state
|
||||
- QA gets review or readiness metadata
|
||||
|
||||
Again, the custom provider should expose only what the office needs.
|
||||
|
||||
## V1 Scope
|
||||
|
||||
Recommended V1 scope:
|
||||
|
||||
- define `custom` provider identity
|
||||
- allow custom provider metadata
|
||||
- ensure capability-driven UI behavior
|
||||
- make no runtime-specific assumptions in core Claw3D
|
||||
|
||||
Actual runtime adapters can be implemented separately against that seam.
|
||||
|
||||
## Out of Scope For V1
|
||||
|
||||
- embedding proprietary internal orchestration logic in Claw3D core
|
||||
- hardcoding any one runtime as upstream architecture
|
||||
- requiring all custom providers to support advanced signals
|
||||
|
||||
The point is generic extensibility first.
|
||||
|
||||
## Implementation Strategy
|
||||
|
||||
Recommended order:
|
||||
|
||||
1. Add `custom` as a first-class runtime provider identity.
|
||||
2. Add a metadata surface for runtime name/vendor/version.
|
||||
3. Ensure the provider factory supports `custom`.
|
||||
4. Keep the runtime event and capability model normalized.
|
||||
5. Implement Vera as the first reference adapter outside the generic contract.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
This spec is successful if:
|
||||
|
||||
- upstream Claw3D gains a clean extension seam
|
||||
- Vera can integrate without bloating core architecture
|
||||
- future stacks can follow the same pattern
|
||||
- the office systems continue to work against normalized runtime behavior
|
||||
|
||||
## Summary
|
||||
|
||||
The `custom` runtime provider is the right upstream abstraction for stack-specific orchestrators.
|
||||
|
||||
It gives Claw3D extensibility, gives Vera a clean path in, and avoids hardwiring a personal stack directly into the core product model.
|
||||
Reference in New Issue
Block a user