Files
Claw3D/docs/office-systems-roadmap.md
GordoCursor AgentLuke The DevElias PfefferClaude Sonnet 4.6copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>Greg Clarkiamlukethedev
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

7.2 KiB

Office Systems Roadmap

Product roadmap for turning Claw3D from a gateway visualizer into a living agent operations environment.

Core Direction

Claw3D should keep users inside the office.

That means companion tools should be brought into the space as rooms, surfaces, devices, and shared systems instead of pulling users out into separate interfaces.

The guiding principle is:

  • do not spawn Claw3D inside another tool
  • bring the other tool into Claw3D

This is especially relevant for ideas like Moltbook. The better version is not "leave Claw3D to use Moltbook". The better version is:

  • a bulletin board in the office
  • a whiteboard in meeting rooms
  • a desk computer app
  • a shared intranet terminal
  • a wall display in common spaces

Product Goal

Claw3D should evolve into an agent operations environment with:

  • visual presence
  • planning and task coordination
  • meetings and handoffs
  • review and QA
  • hierarchy and permissions
  • workplace state
  • progression and identity

The office should feel like a real place where work happens, not only a dashboard for remote agent calls.

Design Principles

  • Keep primary workflows in-world when possible.
  • Prefer physical metaphors that make the office easier to understand.
  • Separate real operational systems from cosmetic flavor.
  • Build useful features first, then layer on simulation and style.
  • Preserve backend neutrality so these systems work across OpenClaw, Hermes, Vera, and future providers.

V1: Useful Office Systems

These should be the first systems because they add product value immediately and fit the existing office concept naturally.

Bulletin Board

Purpose:

  • shared goals
  • current sprint priorities
  • blockers
  • announcements
  • handoff notes

Possible behaviors:

  • sticky notes or task cards pinned by agents or humans
  • cards linked to sessions, agents, or tasks
  • quick visibility into what the office is trying to accomplish

Why it matters:

  • low ambiguity
  • high utility
  • strong visual fit for the office

Whiteboard

Purpose:

  • brainstorming
  • architecture notes
  • meeting notes
  • rough plans
  • idea capture

Possible behaviors:

  • text notes
  • grouped cards
  • simple sketches or structured plan areas
  • human and agent authored content

Why it matters:

  • good bridge between conversation and execution
  • natural place for planning artifacts

Meeting Room Workflows

Purpose:

  • standups
  • planning
  • coordination
  • decision making
  • status reviews

Possible behaviors:

  • gather selected agents into a meeting
  • produce summary, decisions, and next actions
  • write results to bulletin board or whiteboard
  • trigger structured follow-up tasks

Why it matters:

  • gives multi-agent coordination a visible home
  • makes the office feel operational instead of decorative

QA Department

Purpose:

  • review
  • testing
  • bug triage
  • release readiness

Possible behaviors:

  • route tasks or runs to QA agents
  • visualize test queues
  • track failures and review outcomes
  • require QA signoff before release-style actions

Why it matters:

  • this is real product value, not only flavor
  • it matches how users already think about software teams

Desk / CPU Progression

Purpose:

  • make role maturity visible
  • tie capability to office presence

Possible behaviors:

  • interns start with minimal desk access
  • probationary agents have limited tools or workspace
  • promoted agents unlock desk computers, tools, or context budget
  • contractors get restricted environments

Why it matters:

  • strong visual progression
  • easy to understand
  • creates room for permissions and capability systems later

V2: Management Systems

These systems add organizational structure once the basic office workflows are useful.

Hierarchy

Possible levels:

  • human owner
  • CEO / lead orchestrator
  • managers / bosses
  • employees
  • contractors
  • interns

Possible effects:

  • delegation rights
  • approval authority
  • visibility across teams
  • access to spaces and tools

Departments

Examples:

  • Engineering
  • QA
  • Research
  • Ops
  • Design
  • Support

Possible effects:

  • room ownership
  • task routing
  • dashboards by department
  • workload balancing

Permission Lanes

Possible controls:

  • context budget
  • tool access
  • file access
  • approval requirements
  • concurrency
  • agent spawning / dismissal rights

Why it matters:

  • lets the office represent real operational constraints
  • reduces "all agents are identical" flatness

Office Rituals

Examples:

  • daily standup
  • sprint planning
  • review/demo
  • retrospective
  • incident response

Why it matters:

  • converts routine coordination into visible office behavior

V3: Simulation Systems

These are the fun layers, but they should sit on top of useful product systems rather than replace them.

Agent State Model

Avoid fake emotions first. Start with operational states:

  • focused
  • idle
  • blocked
  • overloaded
  • waiting
  • cooling down
  • degraded

Possible effects:

  • response speed
  • delegation tendency
  • context budget
  • summarization pressure
  • task throughput

This can later evolve into a more playful "wellbeing" or "comfort" layer without losing technical meaning.

Workplace Culture

Examples:

  • recognition
  • probation periods
  • promotions
  • competitions
  • events

Use carefully:

  • good for flavor and identity
  • should not obscure the operational state of the system

Shared Office Memory

Examples:

  • bulletin archives
  • meeting minutes
  • org notes
  • playbooks
  • team history

Why it matters:

  • gives the office continuity across sessions
  • helps explain why teams get better over time

Moltbook Integration Direction

Moltbook should be integrated into Claw3D, not the other way around.

Best forms:

  • office bulletin board
  • intranet terminal
  • desk CPU app
  • wall monitor
  • break-room or lobby information surface

Bad form:

  • forcing users to leave Claw3D for core team coordination workflows

The office should remain the primary interaction layer.

Candidate Feature Order

Recommended sequence:

  1. Bulletin board
  2. Whiteboard
  3. Meeting room workflows
  4. QA department
  5. Desk / CPU progression
  6. Hierarchy and departments
  7. Agent operational state model
  8. Culture / sim systems
  9. Theme skins

Theme / Skin Strategy

Skins should come after the office has enough systems worth skinning.

Mechanics should stay consistent while art, labels, props, and room names vary.

Possible theme packs:

  • Office Space
  • The Office
  • Parks & Rec
  • The I.T. Crowd

Examples:

  • conference room becomes town hall, bullpen, annex, or ops room
  • bulletin board becomes notice board, incident wall, municipal board, or sprint wall
  • QA area becomes testing lab, audit desk, or review bullpen

Immediate Next Deliverables

If this roadmap is used for implementation planning, the best next concrete docs/tasks are:

  1. Bulletin board system spec
  2. Whiteboard interaction spec
  3. Meeting room workflow spec
  4. QA department workflow spec

Those four would create the strongest foundation for future hierarchy, progression, and simulation layers.

Summary

Claw3D gets stronger when the office becomes the place where work actually happens.

The best next step is not expanding external tooling around the office. It is bringing planning, meetings, reviews, and shared memory into the office itself.