git clone with no target dir creates ./Claw3D (matching the repo
name), so `cd claw3d` fails on case-sensitive filesystems.
Co-authored-by: A A <aa@As-MacBook-Pro.local>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Running `npm install` against the existing lockfile added a `"dev": true`
flag to the fsevents entry. Committed so the lockfile matches a clean
install on Node 20.
Co-authored-by: zozni-douzone <hjcho1027@douzone.com>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
* fix(office): unblock Hermes adapter integration (Phase 2 Claw3D)
Two bugs prevent the Hermes adapter from auto-connecting on /office:
1. useSearchParams() at OfficeScreen root suspends during hydration in
Next.js dev mode, keeping the parent Suspense fallback stuck on
"Loading..." indefinitely. Replace with sync useMemo reading
window.location.search so debugEnabled is stable across renders.
2. hasLastKnownGoodState only became true when
gateway.lastKnownGood.adapterType matched the currently selected
adapter. Switching to Hermes never auto-connected because
lastKnownGood was still "openclaw" from the prior OpenClaw session.
Allow auto-connect for auto-managed adapters (hermes/openclaw/demo)
when a persisted URL exists for the selected adapter, regardless of
lastKnownGood.
E2E pipeline validated via node WS shell:
- ws://127.0.0.1:3030/api/gateway/ws receives connect.challenge
- connect frame returns hello-ok with adapterType=hermes + full method list
- Upstream chain: proxy(:3030) → adapter(:18790) → Hermes API(:8642)
* fix(office,gateway,coordinator): stop persistence loops causing PUT /api/studio spam
Three distinct bugs caused the persistence layer to schedule patches on
every render after the OfficeScreen mounted, generating PUT /api/studio
~1/second indefinitely and triggering React "Maximum update depth
exceeded" warnings:
1. GatewayClient.ts:1102 — schedulePatch effect compared against a
stale baseline (`loadedGatewaySettings.current` frozen at boot).
After a valid adapter switch (e.g. to Hermes), each render still
saw the state as "dirty" and re-scheduled the same patch. Fix: add
a snapshot ref + update the baseline after scheduling.
2. useTaskBoardController.ts:833 — taskBoard effect persisted on every
`state.cards` reference change without semantic equality check. Fix:
add a JSON-snapshot ref guard.
3. useTaskBoardController.ts:1154 — dedupe effect dispatched archive
marks for duplicate cards, which mutated `state.cards` and re-ran
the effect. Fix: snapshot ref so a structurally-identical card set
doesn't re-enter dedupe.
4. coordinator.ts:354 — `mergeStudioPatch` `!current` branch missed
copying `taskBoard`, allowing the merged patch to drop persisted
task-board state on first write.
Validated via Playwright + dev server logs:
- Before: ~1 PUT /api/studio per second
- After: 0 PUT in a 30s steady-state window post-mount
- React "Maximum update depth" warnings reduced from ~3-4/30s to ≤1/30s
OpenClaw ≥ 2026.3.x bumped the required gateway protocol version from v3 to
v4. Both GatewayBrowserClient and nodeGatewayClient were advertising
maxProtocol: 3, so OpenClaw rejected every connect attempt with
INVALID_REQUEST: "protocol mismatch". Widening the range to maxProtocol: 4
restores compatibility while keeping minProtocol: 3 for backwards compat with
older instances.
A second issue compounded this for SSH-tunnel users: the 75 ms fallback timer
in queueConnect() fired before the connect.challenge nonce arrived through the
tunnel (typical SSH RTT is 100-300 ms). The gateway proxy saw a device payload
with no nonce, treated device auth as incomplete (hasDevice=false), and silently
downgraded the client from openclaw-control-ui to webchat-ui — which only
supports protocol v3, producing the same misleading "protocol mismatch" error.
The fallback timer is now 5 000 ms when device auth is active; the challenge
handler cancels it immediately on arrival, so low-latency connections
(Tailscale, LAN) are not affected.
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(gateway): don't surface protocol-mismatch hint when server rejects origin/auth
The heuristic that flags INVALID_REQUEST errors mentioning minProtocol
or maxProtocol as a possible protocol mismatch can fire on any schema
validation error that happens to mention those field names, including
rejections whose real cause is origin allowlist, missing device
identity, or upstream policy.
Prefer the structured details.code when the gateway provides one, and
treat known non-protocol codes (CONTROL_UI_ORIGIN_NOT_ALLOWED,
CONTROL_UI_DEVICE_IDENTITY_REQUIRED, UPSTREAM_NOT_ALLOWED) as
non-mismatches so the UI does not send operators down the wrong
diagnostic path.
* fix(server): log explicit warning when gateway proxy rejects an upstream
Previously isUpstreamAllowed returned false silently when
UPSTREAM_ALLOWLIST was empty in production, when the upstream host
was not in the allowlist, or when the URL could not be parsed. The
caller closes the connection without forwarding anything to the
browser, which sees an opaque 'WebSocket closed before the
connection is established' and the server logs contain no hint of
what happened.
Emit a console.warn in each of the three rejection branches with an
actionable message that names the missing env var or the rejected
hostname, so operators can diagnose the rejection from the server
logs without reading the proxy source.
* fix(gateway): don't bias the local-timeout hint toward a protocol mismatch
formatGatewayError unconditionally appended a hint suggesting the user
upgrade OpenClaw or switch to the Hermes adapter whenever the browser
reported a generic "timed out connecting to the gateway" Error. That
Error is raised by a local Promise.race timeout, so it carries no
information about why the upstream did not respond. Common real causes
are network reachability, nginx idle timeouts, origin allowlist,
missing UPSTREAM_ALLOWLIST in production, or credential mismatches —
none of which are addressed by upgrading the gateway.
Replace the biased suggestion with a neutral pointer to the likely
diagnostic paths so the hint helps in the common cases without
misleading away from origin/auth/policy issues.
---------
Co-authored-by: Jose Antonio Martinez <257598434+jamartineztelecoengineer84-dotcom@users.noreply.github.com>
* fix(gateway): coerce profile url/token to strings to prevent office crash
The security hardening that stripped upstream tokens from the public
settings API left a typing lie behind: StudioGatewayProfile.token is
declared `string`, but at runtime the resolver propagated `undefined`
from the sanitized response into selectedProfile.token. That made
useState's `token` undefined and crashed the office on
`token.trim()` inside useGatewayConnection.
Coerce url/token to "" at the resolver boundary so the type contract
holds at runtime, and add ?? "" guards on the consumer .trim() calls
so a malformed profile can never crash the office again.
Also resync package-lock.json (was still pinned at 0.1.0 with the
removed @vercel/otel entry) so the lockfile matches package.json at
0.1.4.
Made-with: Cursor
* Make building directory collapsible
---------
Co-authored-by: iamlukethedev <lucas.guilherme@smartwayslfl.com>
Co-authored-by: iamlukethedev <iamlukethedev@users.noreply.github.com>
* 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>
* Added docker-ignore
* ops(docker): publish Claw3D images from main.
Add a GHCR publishing workflow and expose a health endpoint so Fly deployments can build and pass runtime health checks.
Made-with: Cursor
* ops(docker): publish branch preview images.
Tag non-main branch builds with the branch name so test deployments can use GHCR images before merging to main.
Made-with: Cursor
---------
Co-authored-by: iamlukethedev <iamlukethedev@users.noreply.github.com>
Co-authored-by: iamlukethedev <lucas.guilherme@smartwayslfl.com>
* 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>
---------
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Luke The Dev <iamlukethedev@users.noreply.github.com>
Relax the proxy frame limiter to allow normal startup traffic while preserving abuse protection, and slow reconnect retries after policy-violation disconnects so remote gateways can recover cleanly.
Made-with: Cursor
Co-authored-by: iamlukethedev <lucas.guilherme@smartwayslfl.com>
* 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>
* feat(kanban): add Kanban board with task-manager skill, modal UI, and desk clutter
Implement a full Kanban board system for tracking agent tasks:
- Add task-manager skill with shared JSON task store for persistence
- Render board as a floating modal over the live 3D office (not immersive)
- Auto-create tasks from actionable user messages with heuristic filtering
- Sync task status through OpenClaw agent lifecycle events
- Collapse task details panel by default, expand on card click
- Add dynamic desk clutter (papers, folders, etc.) reflecting active task count
- Exclude done tasks from desk clutter count
- Extract KANBAN_CLUTTER_OFFSET for easy positioning adjustment
- Add install flow with progress bar for the task-manager skill
- Include unit and e2e test coverage
Made-with: Cursor
* feat(kanban): production-harden task board with AI-free classification, resilient persistence, and modal UX
- Harden shared task store with atomic writes, payload size limits, and server-side enum validation
- Add client resilience: request timeouts (AbortController), exponential backoff retries, poll deduplication
- Implement optimistic UI with rollback on all card mutations (update, move, archive)
- Add modal accessibility: focus trap, Escape to close, aria-modal, keyboard card navigation
- Trust OpenClaw agent lifecycle phase=start as task classification signal instead of regex heuristics
- Keep regex heuristic only as lightweight filter for direct chat events (conversational noise)
- Expand verb recognition with typo tolerance and broader action vocabulary
- Create tasks from agent runs even when no chat event is received (external channel support)
- Merge dual header bars into single bar; reposition close button outside modal corner
- Exclude done tasks from desk clutter count; make clutter position configurable via KANBAN_CLUTTER_OFFSET
- Update default furniture layout to match user configuration
- Ensure kanban_board furniture persists in local storage across sessions
- Add comprehensive test coverage for store, API route, and controller logic
Made-with: Cursor
---------
Co-authored-by: iamlukethedev <lucas.guilherme@smartwayslfl.com>
- desk_cubicle now has blocksNavigation: true with navPadding: 0
(tight blocking, no inflation — aisles stay clear)
- buildNavGrid reads per-item navPadding from ITEM_METADATA
- getDeskLocations targets y-5 (chair position, above desk blocked zone)
- Agents route AROUND desks instead of through them
- Chair stays passable so agents can reach their sitting position
Fixes object passthrough for desks. Other large passable items
(doors, lamps) unchanged — they remain non-blocking by design.
Co-authored-by: Neo (subagent) <neo@openclaw.local>
Co-authored-by: Luke The Dev <252071647+iamlukethedev@users.noreply.github.com>
Harden the SSH agent-state and skill-removal paths to match the local security model, and avoid rejecting valid local workspace skill removals.
Made-with: Cursor
Co-authored-by: iamlukethedev <lucas.guilherme@smartwayslfl.com>
The embedded SOUNDCLAW_SKILL_MD string in packaged.ts was missing the
'OpenClaw Gateway Skill Contract' section that was added to the asset
source file in #67. Re-synced the packaged constant from the canonical
assets/skills/soundclaw/SKILL.md.
Co-authored-by: Neo (subagent) <neo@openclaw.local>
Fixes#57 — NEXT_PUBLIC_GATEWAY_URL is a build-time variable that gets
baked into the client bundle. Changing it in .env and restarting has no
effect without a rebuild.
- normalizeLocalGatewayDefaults now accepts the sanitized public form
({url, tokenConfigured}) from /api/studio
- When no saved gateway URL exists, prefer runtime localGatewayDefaults
(from openclaw.json or CLAW3D_GATEWAY_URL env var) over the
potentially stale build-time NEXT_PUBLIC_GATEWAY_URL
- loadLocalGatewayDefaults falls back to CLAW3D_GATEWAY_URL/TOKEN env
vars when openclaw.json is absent
- Added runtime env vars documentation to .env.example and README
Co-authored-by: robotica4us-collab <neo@openclaw.ai>
Made-with: Cursor
- Revert next.config.ts: remove hardcoded Cloudflare tunnel URL from
allowedDevOrigins (dev artifact, not part of the voice upload fix).
- Rewrite voice transcribe tests to use mock request objects instead of
real Request/FormData/Blob instances that cause formData() to hang
indefinitely in vitest's Node environment. All 9 tests now pass.
Made-with: Cursor
* fix(voice): enforce upload size limit before buffering (issue #7)
The previous implementation called request.formData() and audio.arrayBuffer()
before checking MAX_VOICE_UPLOAD_BYTES, meaning oversized uploads were fully
buffered into memory before rejection — a DoS/OOM risk.
Changes:
- Check Content-Length header early and return 413 if it exceeds the limit,
preventing any request body from being read into memory for oversized uploads
- Export MAX_VOICE_UPLOAD_BYTES for use in tests
- Switch from instanceof File to duck-typing (checking .arrayBuffer method)
to avoid cross-realm failures in jsdom test environments
- Return HTTP 413 Payload Too Large for oversized uploads (was 400 before)
- Retain a secondary post-buffer size check to catch missing/spoofed
Content-Length headers
Tests added (tests/unit/voiceTranscribe.test.ts):
- Content-Length exceeding limit → 413 before any buffering
- Content-Length at exactly the limit → proceeds normally
- No Content-Length header, small file → proceeds normally (200)
- No Content-Length header, oversized body → 413 after buffering
- Missing audio field → 400
- Empty audio file (0 bytes) → 400
- Malformed Content-Length header → falls through gracefully
Fixes: issue #7
* fix(issue-7): account for multipart overhead in Content-Length early check
The early Content-Length guard was comparing total multipart request size
against MAX_VOICE_UPLOAD_BYTES, but multipart/form-data includes boundary
and header overhead (~200-500 bytes). A valid file at exactly the 20 MB
limit was being rejected with 413.
Fix: add a 1 KB MULTIPART_OVERHEAD_ALLOWANCE to the early check threshold.
The post-buffer check remains the authoritative limit and measures actual
audio bytes. Updated tests to reflect the corrected early-check boundary.
---------
Co-authored-by: Neo (subagent) <neo@openclaw.local>
Co-authored-by: Neo <neo@openclaw.ai>
The test expected [] for same-cell targets, but the code correctly
returns [{ x: ex, y: ey }] so the movement layer can make the final
fine-grained adjustment to the exact pixel.
Made-with: Cursor
* fix(navigation): astar() returns [] on failure instead of raw destination
Issue #3: When A* could not find a route, it returned [{x: endX, y: endY}]
(the raw destination) as a one-element path. The movement layer treated
this as a valid waypoint and steered agents in a straight line toward the
target, letting them pass through walls and furniture.
Changes:
- navigation.ts: Both failure exits in astar() now return [] instead of
[{x: ex, y: ey}]. This applies to:
* findFree() returning null (start or end hopelessly blocked)
* start and end resolving to the same free cell (already arrived)
* open list exhausted with no route to the end
- RetroOffice3D.tsx: Movement-layer waypoint fallback changed from
agent.targetX/Y to agent.x/agent.y when path is empty. An agent with
no route now stays put rather than walking through obstacles.
Tests added (tests/unit/navigation.astarFallback.test.ts):
- astar returns [] for an unreachable destination (thick wall barrier)
- astar returns [] when the entire grid is blocked (findFree fails)
- astar returns a valid path for reachable destinations (regression)
- astar returns [] when start and end snap to the same grid cell
- movement-layer simulation: empty path keeps agent at current position
* fix(navigation): preserve final waypoint for same-cell reachable targets
astar() was returning [] for both true pathfinding failures and same-cell
reachable targets, causing the movement layer to treat both cases identically
(agent stays put). A destination within the same nav cell is still reachable
— the agent should take the final fine-grained step to the exact pixel.
Fix: return [{ x: ex, y: ey }] for same-cell case so the movement layer
can settle the agent onto the exact interaction point.
---------
Co-authored-by: Neo (subagent) <neo@openclaw.local>
Co-authored-by: Neo <neo@openclaw.ai>
* fix(issue-13): remove impossible TS2367 comparison in skillGymDirective guard
OfficeGymDirective is defined as the literal type 'gym' (deskDirectives.ts:9).
The condition at eventTriggers.ts:1136
if (skillGymDirective.directive !== 'release')
compared it against 'release', which TypeScript correctly flags as an
impossible comparison (TS2367), blocking the build.
The check was copy-pasted from the desk/github/qa patterns where 'release'
is a valid directive value. For the gym skill path there is no 'release'
directive — gym hold is released via the isAgentRunning guard in
reduceOfficeGymHoldState (deskDirectives.ts). Any non-null skillGymDirective
should therefore unconditionally set skillGymHoldByAgentId.
Fix: remove the dead guard and set the hold directly, with an explanatory
comment. Verified with npm run typecheck (exits 0).
* test(eventTriggers): add gym directive hold unit tests (issue #13)
Tests for the skillGymHold logic in reconcileOfficeAnimationTriggerState:
- Verify gym directive sets skillGymHoldByAgentId unconditionally (no release guard)
- Verify gym directive via transcript entry triggers hold
- Verify prior hold persists when no new directive is present
- Verify no hold entry when neither directive nor prior hold exists
- Verify multiple agents are handled independently
* fix(issue-13): handle release directive in skillGym hold reconciliation
OfficeGymDirective = 'gym' | 'release'. The previous unconditional
skillGymHoldByAgentId[agentId] = true would silently ignore a release
directive and keep the agent in gym-hold state indefinitely.
Fix: only set the hold when directive === 'gym'. A release directive
now skips the assignment, clearing the hold as intended.
Context: reconcileOfficeAnimationTriggerState tracks the skill-source
gym path (resolveOfficeGymDirective, source: 'skill'). The manual/command
release path (source: 'manual') is handled separately by buildOfficeAnimationState
→ reduceOfficeGymHoldState, which was already correct.
Tests updated: corrected the file-level doc comment, renamed the 'gym'
test for clarity, added a regression test confirming a release-pattern
message does not set the hold.
---------
Co-authored-by: Neo (subagent) <neo@openclaw.local>
Co-authored-by: Neo <neo@openclaw.ai>
Co-authored-by: Luke The Dev <252071647+iamlukethedev@users.noreply.github.com>
* feat: add company builder wizard with AI-powered org generation
Adds a new "Build Your Company" step to the onboarding wizard that lets
users describe their business and generates a full agent org structure
using OpenClaw's AI. Includes company plan generation, role deduplication,
agent bootstrap with main-agent reuse, org chart preview, confetti on
success, CSS voxel running-avatar loader, amber theme unification, and
best-effort SSH workspace cleanup.
Made-with: Cursor
* fix: resolve lint errors in CompanyBuilderModal
Replace setState-in-effect pattern with a direct callback, escape
apostrophes in JSX text, and derive org chart hover state without
side effects.
Made-with: Cursor
---------
Co-authored-by: iamlukethedev <lucas.guilherme@smartwayslfl.com>
Add the office jukebox flow so Spotify can be controlled from the SOUNDCLAW skill, manual jukebox UI, and local browser auth bridge during development.
Made-with: Cursor
* Remote openclaw connection enabled and agent added
* 2 worlds connected
* Performance improvement
* Performance improvements
* Added documentation
* feat(office): add multi-agent beta remote office support
Add a second-office beta that can mirror remote Claw3D presence or derive remote gateway presence so teams can visualize and message agents across instances. Harden the new remote flows, document setup, and keep the branch green with full validation.
Made-with: Cursor
---------
Co-authored-by: iamlukethedev <iamlukethedev@users.noreply.github.com>
Co-authored-by: iamlukethedev <lucas.guilherme@smartwayslfl.com>
The isWithinHome() check used path.relative() which is purely string-based
and does not follow symlinks. A symlink inside the home directory pointing
to an external path would bypass the containment check, allowing directory
listing of arbitrary filesystem locations.
Now uses fs.realpathSync() to resolve symlinks before the containment
comparison, ensuring the real filesystem path is validated.
Co-authored-by: ThankNIXlater <ThankNIXlater@users.noreply.github.com>
Agent Bus is an open-source event routing system that bridges AI coding
agents (Claude Code, Gemini, Codex) to Claw3D's 3D office. It includes
an OpenClaw-compatible gateway at :18789 that speaks the same protocol —
no Claw3D code changes needed, just point GATEWAY_URL.
Zero inference cost, works with any agent that can HTTP POST.
* feat(ui): improve visual polish, responsiveness, and UX consistency
- GatewayConnectScreen: replace hardcoded text-white* with semantic
foreground/muted-foreground tokens so the connect form is readable
in both light and dark modes
- HeaderBar: show gateway status chip for "connected" state in addition
to "connecting", giving users clear visual feedback once connected
- FleetSidebar: add aria-label and aria-pressed to agent row buttons
for screen-reader accessibility
- HQSidebar: add role=tablist/tab/tabpanel, aria-selected, aria-controls,
and aria-labelledby to the headquarters panel tabs
- OfficePage: replace Suspense fallback={null} with a themed spinner
so users see feedback instead of a blank screen during initial load
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(office): widen agent nameplate to prevent name truncation
- Expand background plane from 0.68 to 1.1 width
- Increase maxWidth from 0.56 to 1.0
- Slightly reduce fontSize 0.1 to 0.09 for better fit
- Add whiteSpace nowrap to prevent wrapping
- Truncate names >14 chars with ellipsis for very long agent names
---------
Co-authored-by: Claw3D UI Bot <ui-improvements@claw3d.local>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(issue-17): add onboarding wizard for new users
Adds a step-based onboarding wizard that guides new users through their
first Claw3D setup: welcome, prerequisites, gateway connection, agent
discovery, and a completion screen.
Architecture:
src/features/onboarding/ (new feature module):
- types.ts: Step definitions, navigation helpers (getNextStep/getPrevStep)
- useOnboardingState.ts: localStorage-backed persistence hook
- index.ts: Barrel exports for clean imports
- components/OnboardingWizard.tsx: Main wizard container with step
navigation, progress bar, and modal overlay
- components/WelcomeStep.tsx: Feature highlights grid
- components/PrerequisitesStep.tsx: Checklist with links/commands
- components/ConnectStep.tsx: Compact gateway connection form
- components/AgentsStep.tsx: Agent discovery feedback
- components/CompleteStep.tsx: Final screen with CTA
Design decisions:
- Modular step system: new steps can be added by extending
OnboardingStepId and registering a component in the switch
- localStorage persistence: wizard shows once per browser, resettable
from settings (future: wire into Studio settings API)
- Connect step gates forward navigation: users cannot skip connection
- Follows Claw3D conventions: feature-first module, no shared state
pollution, Tailwind utility classes, lucide-react icons
- Does NOT modify existing routes or components — zero-risk integration
(parent wiring left to maintainer preference)
Integration guide (for maintainer):
1. Import { OnboardingWizard, useOnboardingState } from the module
2. Add useOnboardingState() to the root layout or agents page
3. Render <OnboardingWizard /> when showOnboarding is true
4. Pass gateway connection props from existing store
tests/unit/onboardingTypes.test.ts (13 tests):
- Step structure validation, navigation helpers, ordering
tests/unit/onboardingState.test.ts (5 tests):
- localStorage persistence, show/hide/reset lifecycle
Addresses #17
* fix(onboarding): wire wizard launch into office UI
Mount the onboarding wizard in OfficeScreen and add a settings action that can re-open it so the new-user flow is reachable and testable.
Made-with: Cursor
---------
Co-authored-by: Neo <neo@openclaw.ai>
Co-authored-by: iamlukethedev <lucas.guilherme@smartwayslfl.com>
* fix(issue-5): add collision-aware pathfinding to Phaser office viewer
Agents in the Phaser office viewer previously moved in straight lines toward
zone anchors, ignoring walls, furniture, and collision geometry. This made
agents walk through rendered map obstacles.
Changes:
src/lib/office/pathfinding.ts (new):
- Shared 2D A* pathfinding module for OfficeMap surfaces
- Builds a nav grid from map objects (walls/furniture layers) and
collision polygons with configurable cell size and padding
- Diagonal corner-cutting prevention (checks both orthogonal neighbors)
- Returns empty path on failure instead of raw destination fallback
- Point-in-polygon rasterisation for collision polygon support
- Intentionally placed in src/lib/office/ for reuse across office stacks
src/features/office/phaser/systems/AgentEffectsSystem.ts:
- Computes A* waypoint paths when agent targets change
- Follows waypoints sequentially instead of linear interpolation
- Caches nav grid and invalidates on map identity change
- Agents stay put when no valid path exists (no wall clipping)
tests/unit/officePathfinding.test.ts (new):
- 12 unit tests covering grid construction, A* routing, corner-cutting
prevention, collision polygon support, blocked-start recovery, and
starter map integration
Fixes#5
* fix(test): remove unused NavGrid2D type import
---------
Co-authored-by: Neo <neo@openclaw.ai>
* fix(issue-4): add missing solid floor props to BLOCKING_TYPES
Audited all furniture types defined in furnitureDefaults.ts and
geometry.ts (ITEM_FOOTPRINT) against BLOCKING_TYPES in navigation.ts.
Added five previously missing solid floor props:
- water_cooler: freestanding floor appliance, agents pathfound through it
- server_terminal: floor-standing terminal in the server room
- dishwasher: floor appliance in the kitchen area
- easel: floor-standing art-room prop
- beanbag: floor seat large enough to obstruct walking paths
Also adds a unit test asserting every newly-added type is correctly
blocked in the nav grid, and that non-solid desk decorations (keyboard)
remain free.
* refactor(nav): replace hardcoded BLOCKING_TYPES with metadata-driven ITEM_METADATA
Previously, buildNavGrid() maintained a hardcoded BLOCKING_TYPES set in
navigation.ts. The issue #4 fix added the five missing solid props directly
to that set, but this approach is brittle — every new furniture type requires
a separate PR touching navigation.ts to stay correct.
This rework introduces ITEM_METADATA in geometry.ts (alongside the existing
ITEM_FOOTPRINT record) as the single source of truth for per-type navigation
properties:
export const ITEM_METADATA: Record<string, { blocksNavigation: boolean }>
Each item type explicitly declares blocksNavigation: true/false. The five
props fixed in issue #4 (water_cooler, server_terminal, dishwasher, easel,
beanbag) retain their blocking status. Unknown types default to false, so
future decorative items never accidentally block navigation.
Changes:
- geometry.ts: add ITEM_METADATA export (64 type entries)
- navigation.ts: remove BLOCKING_TYPES set; add itemBlocksNavigation() helper
that reads ITEM_METADATA[type]?.blocksNavigation ?? false; update buildNavGrid()
to call it
- tests/unit/navigation.navBlockers.test.ts: retain original 5 solid-prop tests;
add metadata-driven test suite covering: all blocking types from metadata,
all non-blocking types from metadata, runtime-added type with blocksNavigation:true,
and unknown-type safe fallback
All 10 tests pass; lint clean; only pre-existing TS2367 (issue #13) remains.
* test(navigation): add extended nav blocker tests (issue #4)
Additional tests for buildNavGrid and astar pathfinding:
- Adjacent blocking items create a continuous impassable wall
- Blocking item near grid edge/boundary causes no out-of-bounds errors
- Full pathfinding integration: astar routes AROUND a cabinet placed between
start and end (not just that cells are blocked)
- desk_cubicle explicitly does NOT block — confirmed via ITEM_METADATA
- door explicitly does NOT block — agents must walk through doors
---------
Co-authored-by: Neo (subagent) <neo@openclaw.local>
* fix(issue-6): prevent A* diagonal corner-cutting through blocked cells
The A* neighbor loop previously checked only whether the destination cell
was free. For diagonal moves this allows agents to clip through the corner
of a blocked cell — the two orthogonal neighbours (e.g. N and E for a NE
move) were never validated.
Fix: after confirming the diagonal destination is free, additionally check
both orthogonal intermediary cells. If either is blocked, the diagonal
expansion is skipped and the agent must route around the obstacle.
Adds three unit tests covering:
- a path that would clip a single corner (rejected after fix)
- a path through open space (diagonals still used freely)
- a path around a multi-cell wall segment (no cells in the wall visited)
* chore: remove unused imports from diagonal corner test (lint cleanup)
* test(navigation): add expanded diagonal corner-cutting tests (issue #6)
Additional tests for astar diagonal corner-cutting prevention:
- All 4 diagonal directions (NE, NW, SE, SW): block orthogonal neighbour,
verify path avoids the blocked cell in each direction
- Both orthogonal sides blocked: verify no diagonal move is taken from start
- L-shaped wall: verify agent navigates around entire L without clipping any segment
- Dense grid stress test: maze-like layout verifying valid path found and no
waypoint lands on a blocked cell
---------
Co-authored-by: Neo (subagent) <neo@openclaw.local>
* Fix WS auth: wire accessGate.allowUpgrade via verifyClient
The allowWs callback was never actually calling accessGate.allowUpgrade
during the WS handshake - the ws library passes (info) not (req), and
verifyClient must be set on the WebSocketServer constructor options.
Fix: pass verifyClient to WebSocketServer constructor and wrap
allowUpgrade to extract info.req.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Fix TypeScript error and add gym release directive support
Add "release" value to OfficeGymDirective type for symmetry with
OfficeQaDirective ("qa_lab" | "release"). Previously OfficeGymDirective
was only "gym" with no release state, making the "!== 'release'"
check in eventTriggers.ts dead code that TypeScript flagged as an
unintentional comparison.
Changes:
- deskDirectives.ts: add "release" to OfficeGymDirective type
- deskDirectives.ts: add gym release patterns to skill and command
directive resolvers (e.g. "leave the gym", "done with skills")
- eventTriggers.ts: change !== "release" to === "gym" for clarity
and consistency with reduceOfficeGymHoldState pattern
This fixes: https://github.com/iamlukethedev/Claw3D/issues/15
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
