admin/Claw3D

Fork 0

mirror of https://github.com/iamlukethedev/Claw3D.git synced 2026-08-14 00:58:04 +00:00

Files

T

4e552967d9 [PRIORITY][FEAT] merge runtime profiles, office systems, doctor, and vera lane convergence (#109 )

* 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

* office_sys prep

* tighten multi-floor runtime spec

* multi-floor v1 implementation

* moved floor nav

* runtime architecture specs

* claw3doctor specs

* feat: add first pass claw3doctor diagnostics

* docs: align roadmap with runtime profiles and office systems priorities

* feat: expand claw3doctor provider diagnostics and json output

* feat: improve claw3doctor formatting and multi-runtime diagnostics

* feat: formalize runtime profile resolution

* feat: expand claw3doctor profile health diagnostics

* feat: polish claw3doctor output and tunnel remediation

* feat: add claw3doctor profile scoping and failure classification

* docs: define claw3doctor v1 boundary and v2 backlog

* test: fix stale claw3doctor branch expectations

* test: fix stale expectations on claw3doctor branch

* fix(claw3doctor): scope provider-specific checks to --profile / --all-profiles flags

PR #101 finding:
- Medium: --profile <adapter> and --all-profiles only scoped the profile health
  probe loop; OpenClaw/Hermes/Demo/Custom check blocks still ran based on the
  selected adapter type in runtimeContext, making CLI output misleading.

Fix: introduce adapterInScope(adapterType, defaultBehavior) helper in main().
  - --profile <adapter>  -> only that adapter's checks run
  - --all-profiles       -> all adapter checks run
  - no flag              -> falls back to existing shouldRun* predicate (unchanged)

Also:
- Export parseDoctorArgs from claw3doctor-core.mjs (removed duplicate in script)
- Add test suites: parseDoctorArgs flag parsing (6 cases) and
  adapterInScope scoping semantics (4 cases) — 10 new tests, all green

* fix(office): persist per-floor selectedAgentId on focusLocalAgent + wire officeFloors runtime state

PR #96 findings:
- Medium #1: focusLocalAgent now writes selectedAgentId back to floorRosterCache
  so handleSelectFloor restores the agent the user last picked on each floor
  rather than snapping back to the hydration-time suggestion.
- Medium #2: Add useEffect that calls settingsCoordinator.schedulePatch with
  officeFloors[activeFloorId] patch on every status/gatewayUrl change, writing
  status, gatewayUrl, lastKnownGoodAt, lastErrorCode, and lastErrorMessage so
  the persisted floor runtime state actually tracks live connection transitions.

* fix unkept changes

* fix audit findings - cross-floor misattribution & officefloors silent drops

* pushed changes

* multi-agentic runtime & chat bubble fix

* partial parity with office-sys-next

* claw3doctor parity

* partial parity with v_lane

* merged feat/office-systems-next -> merge_sys

* parity across PR branches

* rm *.orig postmerge

* full parity across unmerged PRs & main

* fix lukes findings

* fix findings - bigger chatbox

* real local upload path

* fixed file upload, MIME integgration

* minor fix

* fix lukess findings

* deleted *.orig

* three bugs fixed - gatewayclient, coord, claw3doctor

* address findings

* fix lukes findings

* fix findings #2

* fix: ignore temporary skill-agent names during identity recovery

* fix: preserve stable identity names during temp-name recovery

* fix(gateway): correct disconnect race and token-blanking on adapter switch

- disconnect() now checks actual connection status rather than selectedAdapterType,
  which may already reflect the target adapter when the effect fires. Prevents stale
  WebSocket clients from persisting after switching to local/claw3d/custom backends.
- setSelectedAdapterType() falls back to loadedGatewaySettings.current.profiles token
  when the in-memory adapterProfiles entry has an empty token (sanitized API form).
  Prevents saved tokens from being cleared when switching between backends.

Closes Luke findings: High (stale gateway on floor switch), Medium (token blanking).

Authored-By: GSKNNFT

* feat(gateway): loopback bypass, control-ui remap, operator.read scope, 75ms connect

Cherry-picked clean additions from pr/gsknnft-2 (fix/reduce-gateway-connect-delay):

- proxy-url.ts: resolveStudioProxyGatewayUrl() now accepts optional upstreamGatewayUrl;
  loopback hosts (localhost/127.0.0.1/::1) bypass the Studio proxy and connect directly
- gateway-proxy.js: remap unauthenticated openclaw-control-ui connections to webchat-ui
  client ID so OpenClaw doesn't reject them as unknown clients
- GatewayBrowserClient.ts + nodeGatewayClient.ts: add operator.read scope to both
  browser and Node gateway clients for expanded access control
- GatewayBrowserClient.ts: reduce socket open→connect delay from 750ms to 75ms

GatewayClient.ts rewrites from that PR were intentionally excluded — they would
regress our disconnect-race fix, token-blanking fix, broken-regex fix, local/claw3d
adapter support, adapterProfiles type export, and private envelope path.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(floor-nav): show only available floors per active adapter; block hang on unconfigured runtime

- floors.ts: add paperclip to FloorProvider; add listAvailableFloorsForAdapter() —
  lobby always visible, runtime floors only shown when their provider matches the
  active adapter, so demo-only users only see Lobby
- OfficeFloorNav: accept activeAdapterType prop, filter floor list via
  listAvailableFloorsForAdapter(); fall back displayActiveFloorId to lobby if current
  floor is no longer in the available set
- OfficeScreen: pass selectedAdapterType to OfficeFloorNav; add guard in
  handleSelectFloor — bail back to lobby immediately when a runtime floor has no
  gateway URL configured, preventing the connect-hang limbo state

Authored-By: GSKNNFT

* hardening: drop unsafe-eval in production CSP; add TRUSTED_PROXY IP resolution

next.config.ts:
- unsafe-eval removed from production script-src (Next.js dev/HMR needs it, but
  production build does not; React and Three.js make no use of eval)
- connect-src intentionally kept broad with note: gateway URLs are user-configured
  at runtime, cannot be enumerated at build time

server/access-gate.js:
- Add resolveClientIp() helper: when TRUSTED_PROXY=1 env var is set, prefer the
  first value of X-Forwarded-For for rate-limiter keying (correct behavior behind
  nginx/Caddy/Vercel edge). Without the flag, remoteAddress is used (safe default
  for direct exposure — prevents X-Forwarded-For spoofing by untrusted clients).

Authored-By: GSKNNFT

* fix(security): remove upstream tokens from browser API; propagate abort to custom runtime

HIGH — /api/studio: strip gatewayPrivate and localGatewayDefaultsPrivate from GET and
PUT responses. Upstream tokens must not cross the browser API boundary. The Studio
proxy (server/gateway-proxy.js) already injects the server-side token into connect
frames when the browser sends an empty token, so the browser never needed raw tokens.
GatewayClient.ts and OfficeScreen.tsx updated to work from sanitized public settings only.

MEDIUM — /api/runtime/custom route: pass request.signal to the upstream fetch() call.
Client abort (e.g. hitting Stop) now cancels the upstream runtime request instead of
leaving it running after the browser fetch resolves.

Authored By: GSKNNFT

* fix(security): preserve stored token through empty-token UI state; handle non-JSON health responses

GatewayClient.ts — autosave effects no longer overwrite persisted gateway tokens with
empty strings. When the in-memory token is empty (proxy handles auth server-side),
the patch omits the token field (undefined) so mergeGatewaySettings/mergeGatewayProfiles
treats it as "leave unchanged". adapterProfiles updater also preserves the existing
stored token when the new token is empty, preventing floor-switch from erasing tokens.

runtime/custom/http.ts — requestCustomRuntime() checks the response Content-Type before
calling response.json(). Non-JSON responses (e.g. plain-text /health "OK") are returned
as-is instead of throwing a JSON parse error, making the custom/local/claw3d health
probe path reliable for runtimes that return plain text.

Authored By: GSKNNFT

* fix(bug): avoid overwriting stored tokens with an empty UI value

GatewayClient.ts:944 → token: "" || undefined = undefined → omitted from patch
mergeGatewayConnectionState: patch.token === undefined → patchedToken = undefined → nextToken = undefined || current?.token ?? "" = "abc123" ✓

scenarionn- user explicitly clears token (empty string patch):

mergeGatewayConnectionState: patchedToken = "" → nextToken = "" || current?.token ?? "" = falls back to existing stored token

Authored By: GSKNNFT

* fix ongoing findings issue

* test: update gateway connection persistence expectations

Co-authored-by: Luke The Dev <iamlukethedev@users.noreply.github.com>

* fix: tighten ts.net hostname matching in doctor

Co-authored-by: Luke The Dev <iamlukethedev@users.noreply.github.com>

* chore(release): prepare v0.1.4

Pin in-repo app version to 0.1.4 to match the planned GitHub release
tag, and document the convergence release in CHANGELOG.md with verified
0.1.3 and 0.1.4 entries covering runtime profiles, multi-floor offices,
remote messaging/handoffs, file uploads, security hardening, and the
claw3doctor diagnostics CLI.

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: Greg Clark <greg.clark@gmail.com>
Co-authored-by: iamlukethedev <lucas.guilherme@smartwayslfl.com>

2026-04-23 18:29:20 -05:00

6.4 KiB

Raw Blame History

Claw3Doctor Spec

First-pass diagnostics plan for Claw3D deployments so users stop chasing the same setup failures manually.

Goal

Provide a single diagnostics surface for the common "Claw3D cannot connect" or "runtime support looks broken" cases.

The intent is similar to:

openclaw doctor
hermes doctor

but focused on Claw3D's integration points across providers.

Primary Outcomes

claw3doctor should:

identify the selected runtime profile/provider
verify the gateway is reachable
identify common auth/config mistakes
surface provider-specific hints without making the whole app provider-specific
reduce issue-thread back-and-forth

First-Pass Scope

Claw3D Settings / Environment

Checks:

current runtime profile selection
gateway URL presence
token presence when required
adapter/provider selection
obvious .env misconfiguration

Outputs:

selected provider/profile
missing env or token warnings
suspicious profile precedence warnings

Gateway Reachability

Checks:

can the configured gateway URL be reached?
can Studio proxy the selected gateway?
does the endpoint respond like a Claw3D-compatible gateway?

Outputs:

reachable / unreachable
timeout / refused / bad handshake
wrong backend contract warning

OpenClaw Checks

Checks:

OpenClaw version
pairing/device-approval state hints
common remote secure-context failures
common 1008, 1011, 1012 patterns

Outputs:

version found / not found
device approval guidance
remote/Tailscale/public tunnel guidance

Hermes Checks

Checks:

Hermes adapter running
Hermes API reachable
Hermes model present
auth key configured if required
adapter env loaded correctly

Outputs:

adapter found / missing
API reachable / unreachable
401 / bad model / bad URL hints

Auth / Token Checks

Checks:

missing Studio access token
gateway token missing
invalid API key patterns
profile says tokened backend but token is absent

Outputs:

precise missing-token messages
auth mismatch guidance

WebSocket / Origin / Secure-Context Checks

Checks:

localhost vs remote
secure-context expectations
browser/origin hints for public/tunneled deployments
Cloudflare/ngrok/reverse-proxy warning patterns

Outputs:

websocket handshake guidance
origin/secure-context notes
public tunnel caution notes

Recommended Output Shape

claw3doctor should produce:

short headline result
categorized checks
pass / warn / fail per item
copy-pasteable next actions

Example:

Claw3Doctor: WARN

[pass] Runtime profile: OpenClaw Default
[pass] Gateway URL reachable: ws://localhost:18789
[warn] OpenClaw version: 2026.4.2
[fail] Device approval required for remote browser
[warn] Secure-context mismatch for public remote setup

Suggested next actions:
1. openclaw devices approve --latest
2. retry from an approved browser/device
3. if using a public tunnel, test local/LAN direct first

Runtime-Profile Awareness

claw3doctor should be designed against the runtime-profile model:

provider
runtime profile
floor binding

That means the doctor should never assume:

one backend
one port
one global runtime mode

Instead it should inspect the currently selected profile and run the appropriate checks for that provider.

Provider-Specific Guidance Rules

OpenClaw

Focus on:

pairing
device identity
remote websocket setup
public/tunnel secure-context issues

Hermes

Focus on:

adapter process
Hermes API reachability
model/config correctness
auth key presence

Custom Runtime

Focus on:

gateway contract compatibility
reachability
auth
profile configuration

Suggested Implementation Order

PR 1: CLI / Script Scaffold

Add:

doctor command entrypoint or script
report formatter
shared result types

PR 2: Runtime Profile Checks

Add:

selected profile inspection
settings/env parsing
gateway URL/token checks

PR 3: Provider Checks

Add:

OpenClaw checks
Hermes checks
custom runtime checks

PR 4: Common Failure Classifiers

Add:

websocket close-code guidance
secure-context/origin hints
reverse-proxy/tunnel notes

Relationship To Office Systems

claw3doctor should land before more runtime complexity because it will make debugging:

multi-runtime support
floor-to-profile binding
public remote deployment

much less painful.

This is why it is sequenced ahead of deeper Office Systems feature work.

V1 Delivery Boundary

claw3doctor v1 should be considered complete when it provides:

selected-profile diagnostics with optional per-profile probing
grouped terminal output with clear pass / warn / fail results
JSON output for automation and issue reporting
provider-aware checks for OpenClaw, Hermes, demo, and custom runtimes
common failure classification for transport and auth problems
concrete remediation for local, remote, tunneled, and adapter-backed setups

This keeps v1 reviewable as deployment diagnostics rather than letting it turn into a full runtime orchestration project.

V2 Expansion Backlog

After v1 lands, the next doctor-specific expansion should focus on better diagnosis depth and better operator ergonomics rather than broader scope.

Higher-Signal Runtime Heuristics

deeper OpenClaw pairing and device-approval detection
stronger close-code interpretation from real-world failures
provider-specific contract validation for demo and custom runtimes
better wrong-model / wrong-adapter mismatch detection

Tunnel / Proxy Guidance

Cloudflare-specific websocket and origin remediation
Tailscale-specific remote deployment guidance
reverse-proxy fingerprinting and likely-misconfiguration hints
public-host checks when auth or secure-context expectations are missing

Output / Workflow Improvements

richer terminal presentation
issue-template or bundle-friendly export
in-app diagnostics panel later, reusing the same JSON report
optional doctor autofix for safe configuration repairs

Runtime-Profile Follow-Through

claw3doctor v2 should also benefit from the separate runtime-profile work:

simultaneous runtime profile visibility
per-profile health history
floor-to-profile diagnosis once Office Systems binding is live

Follow-Up Docs

After this spec, the next planning doc should be:

floor schema and builder plan

That doc should define the metadata model before any admin-side floor builder is implemented.

6.4 KiB Raw Blame History

Claw3Doctor Spec

Goal

Primary Outcomes

First-Pass Scope

Claw3D Settings / Environment

Gateway Reachability

OpenClaw Checks

Hermes Checks

Auth / Token Checks

WebSocket / Origin / Secure-Context Checks

Recommended Output Shape

Runtime-Profile Awareness

Provider-Specific Guidance Rules

OpenClaw

Hermes

Custom Runtime

Suggested Implementation Order

PR 1: CLI / Script Scaffold

PR 2: Runtime Profile Checks

PR 3: Provider Checks

PR 4: Common Failure Classifiers

Relationship To Office Systems

V1 Delivery Boundary

V2 Expansion Backlog

Higher-Signal Runtime Heuristics

Tunnel / Proxy Guidance

Output / Workflow Improvements

Runtime-Profile Follow-Through

Follow-Up Docs

6.4 KiB

Raw Blame History