feat: add runtime seam, Hermes adapter support, and demo gateway mode (#89)
* fix: include kanbanImmersive in immersiveOverlayActive calculation When Kanban board is open, HUD elements (camera preset buttons, edit toolbar, overlays) should be suppressed. The kanbanImmersive flag was defined but not included in the immersiveOverlayActive condition, causing HUD elements to remain visible. This fix adds kanbanImmersive to the immersiveOverlayActive calculation so HUD elements are properly hidden when the Kanban board is open. Co-authored-by: Luke The Dev <iamlukethedev@users.noreply.github.com> * Fix: Hide mini status bar when Kanban immersive overlay is open Wraps the bottom-left mini status bar (showing agent stats, vibe score, and control hints) with !immersiveOverlayActive check to match the behavior of other HUD elements like camera controls and toolbar. This ensures the status bar is properly hidden when the Kanban board or any other immersive overlay is active, maintaining a clean immersive experience. Co-authored-by: Luke The Dev <iamlukethedev@users.noreply.github.com> * chore: drop unrelated package-lock line from branch Co-authored-by: Luke The Dev <iamlukethedev@users.noreply.github.com> * universal-backend-plan * backend-neutral runtime seam * package.json update * feat: add Hermes gateway adapter as alternative to OpenClaw Adds a WebSocket adapter that lets Claw3D connect to a Hermes AI agent runtime without any changes to the frontend. The adapter implements the full Claw3D gateway protocol and bridges it to the Hermes HTTP API. Changes: - server/hermes-gateway-adapter.js: WebSocket bridge implementing the Claw3D gateway protocol against the Hermes HTTP API. Supports all core methods (agents, sessions, chat streaming, cron, config, files, approvals) and multi-agent orchestration via spawn_agent/delegate_task tools. Persists conversation history to ~/.hermes/clawd3d-history.json. - scripts/clawd3d-start.sh: All-in-one startup script that launches Hermes, the adapter, and the Next.js dev server with auto port conflict resolution. Alias as `claw3d` for convenience. - src/features/office/hooks/useCronAgents.ts: Hook that polls the gateway for cron-scheduled agents and surfaces them in the 3D office. - package.json: adds `hermes-adapter` npm script - .env.example: documents Hermes config vars - docs/hermes-gateway.md: setup guide and protocol reference Usage: npm run hermes-adapter # start adapter (connect to http://localhost:8642) npm run dev # start Claw3D, point browser at localhost:3000 # or: bash scripts/clawd3d-start.sh (starts everything automatically) Both OpenClaw and Hermes are supported simultaneously — the gateway URL in NEXT_PUBLIC_GATEWAY_URL determines which backend Claw3D connects to. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat: add read_agent_context tool for cross-agent coordination Agents can now read each other's conversation history via the read_agent_context tool, enabling the orchestrator to check what a sub-agent has done before re-delegating work. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat: wire Hermes office UX and role-aware runtime updates * feature update - demomode & hermes adapter * fix lint blockers * lintfix #2 * fix: stabilize retro office camera preset callbacks * Initial plan * fix: stabilize retro office overview preset hooks Agent-Logs-Url: https://github.com/gsknnft/Claw3D/sessions/9cc71555-591e-44cf-aec4-25affbdcb405 Co-authored-by: gsknnft <123185582+gsknnft@users.noreply.github.com> * feat: add truthful backend selection, Hermes adapter hardening, and demo gateway mode * fix: address bugbot review and finalize backend selection * fixed - onboarding and hermes calls * office systems roadmap * feat specs in docs * specs ready * feat: continue custom runtime seam and gateway alignment * custom lane wired * feat: add custom runtime provider path and office runtime alignment * runtime fixes * fix lukes findings * fix lukes findings #2 * stable UI & connect screen page -> overlay * better baseline for connection * stable providers & ui rendering * best launch yet * nearly no gateway on reconnect * auto reconnect last state * fix: preserve selected runtime across reconnects Keep backend selection aligned with the operator's chosen runtime instead of reviving a mismatched last-known-good adapter, and keep custom runtimes prompting for reconnect when Studio cannot auto-connect them. Made-with: Cursor --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: Luke The Dev <iamlukethedev@users.noreply.github.com> Co-authored-by: Elias Pfeffer <eliaspfeffer@gmail.com> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: iamlukethedev <lucas.guilherme@smartwayslfl.com>
This commit is contained in:
gsknnft
@@ -0,0 +1,393 @@
|
||||
# Bulletin Board Spec
|
||||
|
||||
> First concrete office-system feature for Claw3D.
|
||||
|
||||
## Goal
|
||||
|
||||
Add a shared bulletin board inside the office that acts as the visible coordination surface for:
|
||||
|
||||
- goals
|
||||
- announcements
|
||||
- blockers
|
||||
- handoff notes
|
||||
- standup outcomes
|
||||
- lightweight task cards
|
||||
|
||||
This should be the first step toward making Claw3D a real agent operations environment instead of only a gateway visualizer.
|
||||
|
||||
## Product Position
|
||||
|
||||
The bulletin board is not a replacement for the existing task board or Kanban views.
|
||||
|
||||
It is the office-native layer above them.
|
||||
|
||||
Think of it as:
|
||||
|
||||
- the most important things the office should see right now
|
||||
- the shared memory wall
|
||||
- the in-world coordination surface
|
||||
|
||||
## Why This Feature First
|
||||
|
||||
This is the best first office-system feature because it is:
|
||||
|
||||
- easy to understand
|
||||
- visually natural in the office
|
||||
- useful even before deeper simulation systems exist
|
||||
- compatible with all backends
|
||||
- able to reuse existing task and standup signals
|
||||
|
||||
It also creates a clean landing zone for future systems:
|
||||
|
||||
- whiteboards
|
||||
- meeting summaries
|
||||
- QA queues
|
||||
- hierarchy / department routing
|
||||
- shared office memory
|
||||
|
||||
## Primary Use Cases
|
||||
|
||||
### Shared Goals
|
||||
|
||||
Examples:
|
||||
|
||||
- "Ship Hermes adapter support"
|
||||
- "Fix production bug in standup flow"
|
||||
- "Prepare Friday release review"
|
||||
|
||||
### Announcements
|
||||
|
||||
Examples:
|
||||
|
||||
- "Hermes provider smoke test passed"
|
||||
- "Build is blocked on QA"
|
||||
- "Meeting starts in 5 minutes"
|
||||
|
||||
### Blockers
|
||||
|
||||
Examples:
|
||||
|
||||
- "Gateway auth broken on staging"
|
||||
- "Agent Alice waiting on review"
|
||||
- "No provider token configured"
|
||||
|
||||
### Handoffs
|
||||
|
||||
Examples:
|
||||
|
||||
- "Backend done, hand off to QA"
|
||||
- "Needs design signoff"
|
||||
- "Waiting for owner approval"
|
||||
|
||||
### Meeting Output
|
||||
|
||||
Examples:
|
||||
|
||||
- standup summary
|
||||
- decisions made
|
||||
- next actions
|
||||
- active speaker queue
|
||||
|
||||
## V1 Scope
|
||||
|
||||
V1 should stay intentionally small.
|
||||
|
||||
The board should support a few card types and simple interactions, not a full project-management suite.
|
||||
|
||||
### Card Types
|
||||
|
||||
Initial types:
|
||||
|
||||
- `goal`
|
||||
- `announcement`
|
||||
- `blocker`
|
||||
- `handoff`
|
||||
- `meeting_note`
|
||||
|
||||
### Card Fields
|
||||
|
||||
Minimum shape:
|
||||
|
||||
```ts
|
||||
type BulletinBoardCardType =
|
||||
| "goal"
|
||||
| "announcement"
|
||||
| "blocker"
|
||||
| "handoff"
|
||||
| "meeting_note";
|
||||
|
||||
type BulletinBoardCard = {
|
||||
id: string;
|
||||
type: BulletinBoardCardType;
|
||||
title: string;
|
||||
body: string;
|
||||
createdAt: string;
|
||||
updatedAt: string;
|
||||
authorType: "human" | "agent" | "system";
|
||||
authorId?: string | null;
|
||||
authorName?: string | null;
|
||||
agentId?: string | null;
|
||||
sessionKey?: string | null;
|
||||
taskId?: string | null;
|
||||
pinned: boolean;
|
||||
archived: boolean;
|
||||
priority?: "low" | "normal" | "high";
|
||||
tags?: string[];
|
||||
};
|
||||
```
|
||||
|
||||
### Basic Interactions
|
||||
|
||||
V1 interactions:
|
||||
|
||||
- create card
|
||||
- edit card
|
||||
- pin/unpin card
|
||||
- archive/unarchive card
|
||||
- filter by type
|
||||
- filter by author
|
||||
- open linked session or linked agent
|
||||
|
||||
No drag-and-drop lane system is required for V1.
|
||||
|
||||
## Visual Design
|
||||
|
||||
The bulletin board should feel like a wall-mounted coordination surface inside the office.
|
||||
|
||||
Possible visual forms:
|
||||
|
||||
- cork board
|
||||
- notice board
|
||||
- sprint wall
|
||||
- pinboard with index cards / sticky notes
|
||||
|
||||
The in-world object should have:
|
||||
|
||||
- a visible prop in the retro office
|
||||
- a click target
|
||||
- an immersive detail panel when opened
|
||||
|
||||
It should feel distinct from the existing Kanban board.
|
||||
|
||||
Suggested difference:
|
||||
|
||||
- Kanban = detailed task workflow
|
||||
- Bulletin board = office-wide signal surface
|
||||
|
||||
## Information Hierarchy
|
||||
|
||||
At a glance, the board should answer:
|
||||
|
||||
1. What is the office trying to do?
|
||||
2. What is blocked?
|
||||
3. What changed recently?
|
||||
4. What needs a human to notice?
|
||||
|
||||
Recommended layout:
|
||||
|
||||
- pinned cards first
|
||||
- blockers prominently visible
|
||||
- recent announcements grouped together
|
||||
- meeting notes grouped separately
|
||||
|
||||
## Integration Points
|
||||
|
||||
The feature should hook into systems Claw3D already has.
|
||||
|
||||
### Task Board / Kanban
|
||||
|
||||
Use the bulletin board as a summary layer over the task board, not a duplicate.
|
||||
|
||||
Examples:
|
||||
|
||||
- show a pinned goal card that links into Kanban
|
||||
- create blocker cards when a task enters a blocked state
|
||||
- create handoff cards when work moves between agents or departments
|
||||
|
||||
### Standup System
|
||||
|
||||
The standup system already exists.
|
||||
|
||||
Use it to populate:
|
||||
|
||||
- current meeting announcement
|
||||
- summary card after standup completes
|
||||
- follow-up note cards for unresolved blockers
|
||||
|
||||
### Agent Sessions
|
||||
|
||||
Cards should be linkable to:
|
||||
|
||||
- an agent
|
||||
- a session key
|
||||
- a run or task where applicable
|
||||
|
||||
That lets the user jump from "office signal" to "underlying conversation or task".
|
||||
|
||||
### Runtime-Neutral Backends
|
||||
|
||||
The board must not depend on OpenClaw-specific methods.
|
||||
|
||||
It should operate off:
|
||||
|
||||
- Claw3D state
|
||||
- local persisted office data
|
||||
- optional provider metadata when available
|
||||
|
||||
That keeps it usable with:
|
||||
|
||||
- OpenClaw
|
||||
- Hermes
|
||||
- Vera
|
||||
- Demo mode
|
||||
|
||||
## Storage Model
|
||||
|
||||
V1 storage should be local office data persisted through the same Studio settings path used by other office preferences.
|
||||
|
||||
Suggested storage location:
|
||||
|
||||
- studio office settings keyed by gateway URL
|
||||
|
||||
Example shape:
|
||||
|
||||
```ts
|
||||
type OfficePreference = {
|
||||
bulletinBoard?: {
|
||||
cards: BulletinBoardCard[];
|
||||
updatedAt?: string;
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
Why:
|
||||
|
||||
- matches existing office preference patterns
|
||||
- backend-neutral
|
||||
- fast to implement
|
||||
- easy to migrate later
|
||||
|
||||
## Authoring Rules
|
||||
|
||||
Cards may be created by:
|
||||
|
||||
- human user
|
||||
- agent action
|
||||
- system automation
|
||||
|
||||
Recommended rules:
|
||||
|
||||
- human cards should always be editable
|
||||
- system cards can be archived but not freely mutated
|
||||
- agent cards should show authorship clearly
|
||||
|
||||
That keeps provenance visible without overcomplicating the model.
|
||||
|
||||
## V1 Automation
|
||||
|
||||
Useful automations to add early:
|
||||
|
||||
- create a meeting note card after standup
|
||||
- create a blocker card from explicit blocked-state flows
|
||||
- create announcement cards for major office events
|
||||
|
||||
Keep automation conservative.
|
||||
|
||||
The board should not flood itself with noise.
|
||||
|
||||
## UI Surfaces
|
||||
|
||||
### In-World Object
|
||||
|
||||
Add a dedicated bulletin board prop to the office layout.
|
||||
|
||||
It should:
|
||||
|
||||
- be visible from the main office floor
|
||||
- support hover/click affordance
|
||||
- open an immersive board panel
|
||||
|
||||
### Sidebar / Panel Access
|
||||
|
||||
Also add a panel entry for cases where the user wants quick access without camera movement.
|
||||
|
||||
Possible placement:
|
||||
|
||||
- HQ sidebar tab
|
||||
- office control panel
|
||||
|
||||
### Agent Interaction
|
||||
|
||||
Optional for V1:
|
||||
|
||||
- agents can approach the board during meetings or handoffs
|
||||
- pinned cards can be reflected in ambient office behavior
|
||||
|
||||
This is useful but not required for first delivery.
|
||||
|
||||
## Out of Scope For V1
|
||||
|
||||
Do not include these initially:
|
||||
|
||||
- full Kanban replacement
|
||||
- freehand drawing
|
||||
- multiplayer collaborative editing
|
||||
- complicated permission lattice
|
||||
- department-specific boards
|
||||
- heavy simulation logic
|
||||
- arbitrary external integrations
|
||||
|
||||
Those belong in later systems.
|
||||
|
||||
## Implementation Strategy
|
||||
|
||||
Recommended order:
|
||||
|
||||
1. Define board card types and storage schema.
|
||||
2. Add persisted board data to office settings.
|
||||
3. Add a simple board panel UI.
|
||||
4. Add in-world bulletin board prop and open interaction.
|
||||
5. Connect standup summary output.
|
||||
6. Add simple blocker / announcement automation.
|
||||
|
||||
## Existing Code Seams
|
||||
|
||||
This feature should likely align with:
|
||||
|
||||
- task board state and controller logic in `src/features/office/tasks`
|
||||
- standup flows in `src/features/office/hooks/useOfficeStandupController.ts`
|
||||
- office settings persistence
|
||||
- retro office object interaction in `src/features/retro-office/RetroOffice3D.tsx`
|
||||
- furniture/object definitions in `src/features/retro-office/objects`
|
||||
|
||||
This is intentional.
|
||||
|
||||
The bulletin board should reuse existing office mechanics where possible.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
V1 is successful if:
|
||||
|
||||
- the user can open the board from inside the office
|
||||
- the board shows office-relevant cards, not just generic notes
|
||||
- standup or blocker information can appear on the board
|
||||
- cards can link back into agents/sessions/tasks
|
||||
- the system works with Hermes, OpenClaw, and demo mode
|
||||
|
||||
## Future Extensions
|
||||
|
||||
Once V1 is stable, this can grow into:
|
||||
|
||||
- department boards
|
||||
- QA wall
|
||||
- release wall
|
||||
- meeting room whiteboard handoff
|
||||
- agent-authored summaries
|
||||
- office-wide historical archive
|
||||
- team-specific bulletin surfaces
|
||||
|
||||
## Summary
|
||||
|
||||
The bulletin board should become the first shared memory surface inside Claw3D.
|
||||
|
||||
It is the clearest next step toward making the office itself the product.
|
||||
Reference in New Issue
Block a user