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,423 @@
|
||||
# Hierarchy And Teams Spec
|
||||
|
||||
> Sixth concrete office-system feature for Claw3D, turning visible office roles into an actual organizational model for delegation, permissions, and team coordination.
|
||||
|
||||
## Goal
|
||||
|
||||
Add a hierarchy and teams system so the office can express:
|
||||
|
||||
- who leads
|
||||
- who reports where
|
||||
- who can delegate
|
||||
- who can approve
|
||||
- who belongs to which team
|
||||
|
||||
The goal is to move from "a group of agents in one room" to "an actual organization with structure".
|
||||
|
||||
## Product Position
|
||||
|
||||
Hierarchy and teams should not exist only as labels.
|
||||
|
||||
They should affect:
|
||||
|
||||
- delegation
|
||||
- review authority
|
||||
- meeting participation
|
||||
- bulletin/whiteboard authorship weight
|
||||
- task routing
|
||||
- desk progression meaning
|
||||
|
||||
This is the organizational layer that sits above desks and departments.
|
||||
|
||||
## Why This Feature Matters
|
||||
|
||||
Without hierarchy, all agents are peers by default.
|
||||
|
||||
That creates limits:
|
||||
|
||||
- delegation feels flat
|
||||
- responsibility is ambiguous
|
||||
- review authority is unclear
|
||||
- the office lacks believable structure
|
||||
|
||||
Hierarchy and teams solve that by giving the office:
|
||||
|
||||
- reporting lines
|
||||
- ownership boundaries
|
||||
- authority surfaces
|
||||
- coordination lanes
|
||||
|
||||
## Core Principle
|
||||
|
||||
Keep hierarchy operational, not theatrical.
|
||||
|
||||
Do not start with elaborate roleplay.
|
||||
|
||||
Start with real organizational questions:
|
||||
|
||||
- who can assign work?
|
||||
- who can review work?
|
||||
- who can call meetings?
|
||||
- who can finalize outcomes?
|
||||
- which agents belong together?
|
||||
|
||||
## Suggested Role Model
|
||||
|
||||
Recommended role classes:
|
||||
|
||||
- `owner`
|
||||
- `executive`
|
||||
- `manager`
|
||||
- `lead`
|
||||
- `member`
|
||||
- `contractor`
|
||||
- `intern`
|
||||
|
||||
These role classes are about authority and org structure.
|
||||
|
||||
They are distinct from:
|
||||
|
||||
- desk tier
|
||||
- functional specialty
|
||||
- department
|
||||
|
||||
### Owner
|
||||
|
||||
Characteristics:
|
||||
|
||||
- human-controlled top authority
|
||||
- final signoff for high-impact actions
|
||||
- can override structure
|
||||
|
||||
### Executive
|
||||
|
||||
Characteristics:
|
||||
|
||||
- broad office-level coordination
|
||||
- can set direction across teams
|
||||
|
||||
### Manager
|
||||
|
||||
Characteristics:
|
||||
|
||||
- owns a team or department lane
|
||||
- routes work
|
||||
- coordinates reviews and meetings
|
||||
|
||||
### Lead
|
||||
|
||||
Characteristics:
|
||||
|
||||
- technical or functional authority inside a team
|
||||
- can delegate and review
|
||||
|
||||
### Member
|
||||
|
||||
Characteristics:
|
||||
|
||||
- standard contributor role
|
||||
- executes work inside team scope
|
||||
|
||||
### Contractor
|
||||
|
||||
Characteristics:
|
||||
|
||||
- scoped contributor
|
||||
- limited authority outside assigned work
|
||||
|
||||
### Intern
|
||||
|
||||
Characteristics:
|
||||
|
||||
- low-authority contributor
|
||||
- learning / supervised mode
|
||||
|
||||
## Team Model
|
||||
|
||||
Teams should be explicit groups, not only emergent behavior.
|
||||
|
||||
Suggested examples:
|
||||
|
||||
- Platform
|
||||
- Frontend
|
||||
- QA
|
||||
- Research
|
||||
- Ops
|
||||
- Design
|
||||
|
||||
Suggested V1 shape:
|
||||
|
||||
```ts
|
||||
type TeamId = string;
|
||||
|
||||
type OfficeTeam = {
|
||||
id: TeamId;
|
||||
name: string;
|
||||
description?: string;
|
||||
leadAgentId?: string | null;
|
||||
managerAgentId?: string | null;
|
||||
memberAgentIds: string[];
|
||||
departmentId?: string | null;
|
||||
};
|
||||
```
|
||||
|
||||
## Hierarchy Model
|
||||
|
||||
Suggested V1 shape:
|
||||
|
||||
```ts
|
||||
type OfficeHierarchyRole =
|
||||
| "owner"
|
||||
| "executive"
|
||||
| "manager"
|
||||
| "lead"
|
||||
| "member"
|
||||
| "contractor"
|
||||
| "intern";
|
||||
|
||||
type AgentHierarchyProfile = {
|
||||
agentId: string;
|
||||
role: OfficeHierarchyRole;
|
||||
reportsToAgentId?: string | null;
|
||||
teamId?: string | null;
|
||||
departmentId?: string | null;
|
||||
canDelegate?: boolean;
|
||||
canReview?: boolean;
|
||||
canApprove?: boolean;
|
||||
canCallMeetings?: boolean;
|
||||
};
|
||||
```
|
||||
|
||||
The exact flags can be derived from role later.
|
||||
|
||||
V1 can store them explicitly for clarity if needed.
|
||||
|
||||
## Relationship To Desk Progression
|
||||
|
||||
Desk progression expresses maturity and capability in a physical way.
|
||||
|
||||
Hierarchy expresses authority and organizational position.
|
||||
|
||||
These should be related, but not identical.
|
||||
|
||||
Examples:
|
||||
|
||||
- a senior desk does not automatically make an agent a manager
|
||||
- a contractor may have a strong workstation but still limited authority
|
||||
- a lead may have more coordination authority than a senior member
|
||||
|
||||
That separation matters.
|
||||
|
||||
## Relationship To Departments
|
||||
|
||||
Departments are organizational domains.
|
||||
|
||||
Examples:
|
||||
|
||||
- Engineering
|
||||
- QA
|
||||
- Research
|
||||
- Ops
|
||||
|
||||
Teams live inside or alongside departments.
|
||||
|
||||
Examples:
|
||||
|
||||
- Engineering -> Frontend Team
|
||||
- Engineering -> Platform Team
|
||||
- QA -> Release Team
|
||||
|
||||
Hierarchy determines authority.
|
||||
Departments determine domain.
|
||||
Teams determine working group.
|
||||
|
||||
## Relationship To Meetings
|
||||
|
||||
Hierarchy should affect meetings in practical ways.
|
||||
|
||||
Examples:
|
||||
|
||||
- managers or leads can call planning meetings
|
||||
- review meetings may require a lead or manager present
|
||||
- interns may attend but not finalize decisions
|
||||
- executives may approve office-wide changes after summary
|
||||
|
||||
This gives meetings more structure without overcomplicating V1.
|
||||
|
||||
## Relationship To QA
|
||||
|
||||
Hierarchy should influence QA responsibility.
|
||||
|
||||
Examples:
|
||||
|
||||
- leads can review work
|
||||
- managers can route items into QA
|
||||
- members can request review
|
||||
- interns more often require review
|
||||
- owners/executives can override final readiness decisions when needed
|
||||
|
||||
QA should remain operationally distinct, but authority should not be flat.
|
||||
|
||||
## Relationship To Bulletin Board / Whiteboard
|
||||
|
||||
Hierarchy can shape information flow.
|
||||
|
||||
Examples:
|
||||
|
||||
- high-priority office announcements may come from leads/managers
|
||||
- planning whiteboards may identify team ownership
|
||||
- bulletin cards can show team and owner context
|
||||
|
||||
Important:
|
||||
|
||||
Do not hide information behind hierarchy.
|
||||
|
||||
Use hierarchy to improve clarity, not to make the office opaque.
|
||||
|
||||
## Delegation Model
|
||||
|
||||
Hierarchy becomes most useful when it changes delegation behavior.
|
||||
|
||||
Suggested operational rules:
|
||||
|
||||
- owners, executives, managers, and leads can delegate
|
||||
- members can hand off but not broadly route work across the org
|
||||
- contractors delegate only within limited scope
|
||||
- interns usually cannot delegate except in restricted workflows
|
||||
|
||||
This should be represented both:
|
||||
|
||||
- in UI
|
||||
- in agent-facing behavior and constraints where appropriate
|
||||
|
||||
## Visual Expression
|
||||
|
||||
Hierarchy should have visible but restrained expression in the office.
|
||||
|
||||
Examples:
|
||||
|
||||
- title/subtitle on agent nameplate
|
||||
- seat/desk placement
|
||||
- room proximity to planning areas
|
||||
- meeting table positioning
|
||||
- desk quality in combination with progression
|
||||
|
||||
The office should communicate structure without turning into a caricature.
|
||||
|
||||
## Human Interaction Model
|
||||
|
||||
The human should be able to:
|
||||
|
||||
- assign hierarchy role
|
||||
- assign team
|
||||
- set reporting line
|
||||
- move agents between teams
|
||||
- understand what organizational changes actually affect
|
||||
|
||||
This should be editable and transparent.
|
||||
|
||||
## Agent Interaction Model
|
||||
|
||||
Longer term, agents may:
|
||||
|
||||
- recommend reassignments
|
||||
- request escalation
|
||||
- request specialist support from another team
|
||||
- suggest promotions or org changes
|
||||
|
||||
V1 does not need autonomous re-org behavior.
|
||||
|
||||
V1 should focus on:
|
||||
|
||||
- clear structure
|
||||
- delegation paths
|
||||
- UI visibility
|
||||
|
||||
## V1 Scope
|
||||
|
||||
Recommended V1 scope:
|
||||
|
||||
- explicit hierarchy role per agent
|
||||
- explicit team membership
|
||||
- simple reporting line
|
||||
- visible title/subtitle
|
||||
- delegation and meeting authority rules at a lightweight level
|
||||
|
||||
Keep V1 small enough that it improves office understanding immediately.
|
||||
|
||||
## Storage Model
|
||||
|
||||
Suggested shape:
|
||||
|
||||
```ts
|
||||
type OfficePreference = {
|
||||
hierarchy?: {
|
||||
byAgentId: Record<string, AgentHierarchyProfile>;
|
||||
teams: OfficeTeam[];
|
||||
updatedAt?: string;
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
This keeps the feature local, backend-neutral, and easy to evolve.
|
||||
|
||||
## Out of Scope For V1
|
||||
|
||||
Do not include these initially:
|
||||
|
||||
- automatic org chart optimization
|
||||
- political simulation
|
||||
- compensation/economy systems
|
||||
- punitive management mechanics
|
||||
- heavy workflow bureaucracy
|
||||
|
||||
The system should clarify work, not create needless friction.
|
||||
|
||||
## Implementation Strategy
|
||||
|
||||
Recommended order:
|
||||
|
||||
1. Define hierarchy profile and team schema.
|
||||
2. Add office-level persistence.
|
||||
3. Add UI for role/team assignment.
|
||||
4. Show titles/subtitles and team membership in office/agent UI.
|
||||
5. Apply lightweight authority rules to delegation and meeting actions.
|
||||
|
||||
## Existing Code Seams
|
||||
|
||||
This feature should likely align with:
|
||||
|
||||
- role/title flow already added for agents
|
||||
- desk progression data and UI
|
||||
- meeting room workflows
|
||||
- QA routing
|
||||
- bulletin board ownership/priority metadata
|
||||
|
||||
This is important because hierarchy should unify other office systems rather than stand apart from them.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
V1 is successful if:
|
||||
|
||||
- the office can represent who leads and who belongs where
|
||||
- delegation and review paths are clearer
|
||||
- titles/teams are visible in the office
|
||||
- hierarchy affects at least a small set of real office behaviors
|
||||
- the system remains understandable and editable
|
||||
|
||||
## Future Extensions
|
||||
|
||||
Once V1 is stable, follow-up work can add:
|
||||
|
||||
- org chart views
|
||||
- department dashboards
|
||||
- automatic escalation paths
|
||||
- team-specific meeting rituals
|
||||
- richer approval chains
|
||||
- promotion recommendations
|
||||
|
||||
## Summary
|
||||
|
||||
Hierarchy and teams should give Claw3D a real organizational model.
|
||||
|
||||
That model should support delegation, ownership, and coordination without losing the clarity and playfulness of the office metaphor.
|
||||
Reference in New Issue
Block a user