126 lines
6.0 KiB
Markdown
126 lines
6.0 KiB
Markdown
# ATLAS Cockpit — Source Patterns: Adopted, Adapted, and Rejected
|
||
|
||
**Issue:** [#1695](https://forge.alexanderwhitestone.com/Timmy_Foundation/the-nexus/issues/1695)
|
||
**Date:** 2026-04-22
|
||
|
||
---
|
||
|
||
## Source Repos Audited
|
||
|
||
| Repo | Role in audit |
|
||
|---|---|
|
||
| `dodo-reach/hermes-desktop` | Primary pattern source for inspector/right rail layout |
|
||
| `outsourc-e/hermes-workspace` | Session taxonomy vocabulary (group/tag/pin/archive) |
|
||
| `nesquena/hermes-webui` | Session switcher UI patterns; status badge styling |
|
||
|
||
---
|
||
|
||
## Patterns Adopted
|
||
|
||
### 1. Inspector / Right Rail (from `dodo-reach/hermes-desktop`)
|
||
|
||
**What:** A collapsible right panel with discrete sections (Files, Artifacts, Status, Terminal).
|
||
Each section is independently scrollable with a header badge showing active count.
|
||
|
||
**How we adopted it:**
|
||
- `cockpit-inspector.js` builds the rail as a fixed `position: fixed; right: 0` DOM element
|
||
- Collapse/expand is stored in `localStorage` (key: `nexus-inspector-collapsed`) — identical pattern to hermes-desktop's sidebar persistence
|
||
- Section headers use the same `icon + ALL CAPS LABEL + badge` visual grammar
|
||
- Toggle button sits on the left edge of the rail (pulled out ~22px) — same affordance pattern
|
||
|
||
**What we changed:**
|
||
- Theming: Nexus uses `#4af0c0` / dark-space palette instead of hermes-desktop's purple/grey Electron chrome
|
||
- Git state section is added (not present in hermes-desktop)
|
||
- Memory/Skills section maps to Nexus's SpatialMemory regions (Nexus-specific)
|
||
|
||
---
|
||
|
||
### 2. Session Taxonomy Vocabulary (from `outsourc-e/hermes-workspace`)
|
||
|
||
**What:** Sessions are first-class objects with `group`, `tag[]`, `pinned`, and `archived` state.
|
||
Pinned sessions always sort first. Archived sessions are hidden from default lists.
|
||
|
||
**How we adopted it:**
|
||
- `session-manager.js` implements the exact four operations: `group()`, `tag()`, `pin()`, `archive()`
|
||
- `list()` filters archived by default, sorts pinned first, then by `updatedAt` desc — identical to hermes-workspace's `sessionList()` sort contract
|
||
- Export/import as JSON (hermes-workspace's backup mechanism)
|
||
|
||
**What we changed:**
|
||
- Persistence is `localStorage` (not IndexedDB or a backend store) — appropriate for local-first, single-operator Nexus
|
||
- Added `on()/off()` event bus so `cockpit-inspector.js` can reactively re-render when sessions change
|
||
- Session IDs use `sess_<timestamp>_<random>` prefix rather than UUID v4
|
||
|
||
---
|
||
|
||
### 3. Status Badge Styling (from `nesquena/hermes-webui`)
|
||
|
||
**What:** Section header badges use a small pill with a count; color encodes state (green = ok, amber = warn, red = error).
|
||
|
||
**How we adopted it:**
|
||
- `.ci-section-badge`, `.badge-warn`, `.badge-ok` classes in `style.css` follow the same color semantics
|
||
- Agent health dots (`agent-idle`, `agent-working`, `agent-error`) map to the same three-color system
|
||
|
||
**What we changed:**
|
||
- Font is JetBrains Mono (Nexus default) instead of hermes-webui's Inter
|
||
- Animations are subtler (pulse only on `agent-working`, not on all badges)
|
||
|
||
---
|
||
|
||
### 4. xterm.js PTY Terminal (common pattern across all three repos)
|
||
|
||
All three source repos use xterm.js as the browser terminal component. The transport varies:
|
||
- hermes-desktop: IPC bridge to a native Node.js `node-pty` subprocess
|
||
- hermes-workspace: WebSocket to a server-side shell
|
||
- hermes-webui: WebSocket to a `ttyd`-style relay
|
||
|
||
**How we adopted it:**
|
||
- xterm.js 5.3.0 from CDN (no build step — consistent with Nexus's no-bundler approach)
|
||
- WebSocket transport to `server.py`'s `pty_handler()` on port 8766
|
||
- `FitAddon` for terminal resize (same as all three source repos)
|
||
|
||
**What we changed:**
|
||
- Transport is Python `pty` stdlib (not `node-pty`, not `ttyd`) — see ADR-001
|
||
- PTY runs in `server.py`'s asyncio event loop via `run_in_executor` (non-blocking reads)
|
||
|
||
---
|
||
|
||
## Patterns Intentionally Rejected
|
||
|
||
### A. Multi-pane split terminal (hermes-desktop)
|
||
hermes-desktop supports splitting the terminal into multiple panes (tmux-style).
|
||
**Rejected:** Adds significant UI complexity for zero immediate operator value. The Nexus operator uses native terminal splits in their OS. One PTY pane is sufficient.
|
||
|
||
### B. Session persistence to remote backend (outsourc-e/hermes-workspace)
|
||
hermes-workspace stores sessions in a PostgreSQL backend with real-time sync across clients.
|
||
**Rejected:** The Nexus is local-first and single-operator. `localStorage` is sufficient and adds zero infrastructure.
|
||
|
||
### C. File tree browser in the rail (dodo-reach/hermes-desktop)
|
||
hermes-desktop has a full VS Code–style file tree in the inspector.
|
||
**Rejected:** The Nexus 3D world is not a code editor. Artifacts are surfaced as a flat list of recently-touched files/outputs, not a tree. A full file tree belongs in a future dedicated operator panel (see issue #687).
|
||
|
||
### D. Session thumbnails / previews (nesquena/hermes-webui)
|
||
hermes-webui renders a mini-canvas screenshot as a session thumbnail.
|
||
**Rejected:** The Nexus Three.js canvas is expensive to snapshot. Thumbnails would require canvas-capture overhead. Deferred to a future issue.
|
||
|
||
### E. Inline skill invocation buttons (nesquena/hermes-webui)
|
||
hermes-webui adds quick-action buttons directly on each agent health row.
|
||
**Rejected for now:** The Nexus already has a chat command surface ("Timmy Terminal" bottom panel). Duplicating invocation paths would fragment the operator model. The inspector rail is read-focused; actions flow through chat.
|
||
|
||
---
|
||
|
||
## Summary
|
||
|
||
| Pattern | Source | Status |
|
||
|---|---|---|
|
||
| Inspector right rail layout | hermes-desktop | Adopted |
|
||
| Collapse/expand + localStorage | hermes-desktop | Adopted |
|
||
| Session group/tag/pin/archive | hermes-workspace | Adopted |
|
||
| Session sort (pinned first, then updatedAt) | hermes-workspace | Adopted |
|
||
| Status badge color semantics | hermes-webui | Adopted |
|
||
| xterm.js terminal | all three | Adopted (transport adapted) |
|
||
| Multi-pane terminal | hermes-desktop | Rejected |
|
||
| Remote session backend | hermes-workspace | Rejected |
|
||
| File tree browser | hermes-desktop | Rejected |
|
||
| Session thumbnails | hermes-webui | Rejected |
|
||
| Inline skill invocation | hermes-webui | Rejected |
|