chore(maestro): initial scaffold and brainstorm spec
Adds .claude/linear.json for Linear-driven skills (Maestro project on team Naps62) and the brainstorm design doc covering architecture, wire protocol, session model, auth, and prototype scope boundary. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.7
@@ -0,0 +1,12 @@
|
||||
{
|
||||
"org": "naps62",
|
||||
"team": "Naps62",
|
||||
"project": "Maestro",
|
||||
"defaultBranch": "main",
|
||||
"commitScope": "maestro",
|
||||
"remoteHost": "gitea",
|
||||
"remoteBaseUrl": "https://git.naps.pt",
|
||||
"contextFiles": ["CLAUDE.md"],
|
||||
"prReviewers": [],
|
||||
"labels": []
|
||||
}
|
||||
@@ -0,0 +1,311 @@
|
||||
# Maestro — Prototype Design
|
||||
|
||||
**Date**: 2026-05-24
|
||||
**Status**: Approved (brainstorm)
|
||||
**Scope**: First-pass prototype. No production polish.
|
||||
|
||||
## What this is
|
||||
|
||||
A unified terminal-session orchestrator. One place — laptop, desktop, or phone — to see and attach to every interactive shell or agent (Claude Code, opencode, plain bash) running across every machine you care about: workstation, desktop, dev VM, always-on VMs, and small LXC containers.
|
||||
|
||||
The interface stays a terminal (xterm.js in the browser for the prototype). Sessions persist via tmux on whichever host owns them. Maestro is a thin coordination layer on top, not a terminal-emulator rewrite.
|
||||
|
||||
## Why
|
||||
|
||||
Today: Claude Code runs locally for editing the host, and inside a dev VM for project work in dangerous mode. The VM uses agent-deck to keep sessions alive. Reaching those sessions means SSH-ing in first, no unified view, no side-by-side, and no phone access. Maestro removes the SSH-in step and adds a phone client.
|
||||
|
||||
## Success criterion for the prototype
|
||||
|
||||
A working demo where:
|
||||
|
||||
1. Laptop and phone both load the maestro web UI.
|
||||
2. The session list shows tmux sessions from at least two hosts (laptop + dev VM).
|
||||
3. A new session can be spawned from the UI on a chosen host, optionally backed by a fresh git worktree.
|
||||
4. Both clients can attach to the same session concurrently and see live output.
|
||||
5. Closing a client tab doesn't kill the session; reattaching resumes it.
|
||||
|
||||
UI polish, layout/tiling, edge-case terminals — all out of scope.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌──────────────────────┐
|
||||
│ Registry │
|
||||
│ (always-on VM) │
|
||||
│ │
|
||||
│ • presence index │
|
||||
│ • session catalog │
|
||||
│ • serves web client │
|
||||
└──────┬───────────────┘
|
||||
│ WS (control only,
|
||||
│ no PTY bytes)
|
||||
┌──────────────────────────┼──────────────────────────┐
|
||||
│ │ │
|
||||
┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
|
||||
│ Daemon │ │ Daemon │ │ Daemon │
|
||||
│ (laptop) │ │ (dev VM) │ │ (LXC) │
|
||||
│ │ │ │ │ │
|
||||
│ tmux ↔ WS │ │ tmux ↔ WS │ │ tmux ↔ WS │
|
||||
└──────▲──────┘ └──────▲──────┘ └──────▲──────┘
|
||||
│ │ │
|
||||
│ WS streams (PTY bytes, peer-to-peer over Tailscale)
|
||||
│ │ │
|
||||
└──────────────┬───────────┴──────────────┬───────────┘
|
||||
│ │
|
||||
┌───────▼───────┐ ┌───────▼───────┐
|
||||
│ Web client │ │ Web client │
|
||||
│ (browser) │ │ (phone) │
|
||||
└───────────────┘ └───────────────┘
|
||||
```
|
||||
|
||||
Three components, all reachable via the user's Tailscale tailnet:
|
||||
|
||||
- **Registry** — one always-on instance. Knows who's online and what sessions exist. Serves the web client bundle. Never touches PTY bytes.
|
||||
- **Daemon (`maestrod`)** — one per host. Wraps local tmux. Streams sessions directly to clients over WebSocket.
|
||||
- **Web client** — one TS bundle. Connects to the registry for the catalog, then directly to whichever daemon owns the session being attached.
|
||||
|
||||
The registry is a phone book, not a relay. This keeps it tiny and pushes byte traffic to a direct daemon ↔ client link, which Tailscale already secures end-to-end.
|
||||
|
||||
## Components
|
||||
|
||||
### Registry
|
||||
|
||||
Responsibilities:
|
||||
|
||||
- Accept persistent WS connections from daemons (presence + session-list updates).
|
||||
- Issue short-lived JWTs to authenticated clients for daemon access.
|
||||
- Serve the web client bundle and a small HTTP API.
|
||||
- Broadcast catalog changes to connected web clients via a `/api/events` WS.
|
||||
|
||||
Non-responsibilities:
|
||||
|
||||
- No PTY bytes through this process.
|
||||
- No persistent storage in the prototype. State is in-memory; daemons re-register on reconnect.
|
||||
- No multi-user model. One shared secret, one effective user.
|
||||
|
||||
Runs as a single Rust binary on a designated VM. Default port `:8080`, bound to the Tailscale interface.
|
||||
|
||||
### Daemon (`maestrod`)
|
||||
|
||||
Responsibilities:
|
||||
|
||||
- Connect to the registry on startup, identify with the shared token, advertise its current sessions.
|
||||
- Maintain a tmux session list. Spawn / kill tmux sessions on demand.
|
||||
- Expose a per-session WS endpoint streaming PTY bytes both directions.
|
||||
- Handle git worktree creation on session create, when requested.
|
||||
- Recover existing sessions on restart by scanning tmux for names matching its naming pattern.
|
||||
|
||||
Non-responsibilities:
|
||||
|
||||
- Doesn't adopt foreign tmux sessions (only the ones it created — names prefixed `maestro-<id>`).
|
||||
- Doesn't relay to other daemons. It only knows about local tmux.
|
||||
- Doesn't manage its own auth tokens; the registry issues them.
|
||||
|
||||
Runs as a single Rust binary on every host that holds sessions. Small footprint matters because some hosts are LXC containers. Default port `:8081`, bound to the Tailscale interface.
|
||||
|
||||
### Web client
|
||||
|
||||
Responsibilities:
|
||||
|
||||
- Authenticate to the registry (cookie set on first tailnet-IP visit).
|
||||
- Render the session catalog as a tree, using each session's `metadata.label` (e.g. `personal/maestro`) to derive grouping.
|
||||
- Provide search across session names and labels.
|
||||
- Open a WS to a daemon to attach to a chosen session; render via xterm.js.
|
||||
- Support concurrent attaches (multiple tabs to the same session work).
|
||||
- Spawn a new session through a small form: pick host, working dir, command, optional worktree.
|
||||
|
||||
Non-responsibilities (prototype):
|
||||
|
||||
- No split-pane / side-by-side. One session at a time per tab — but you can open two browser tabs to two sessions, which gets you side-by-side via the OS.
|
||||
- No theming / settings UI.
|
||||
- No mobile-specific UX beyond "works in mobile Chrome at a reasonable touch size."
|
||||
|
||||
TypeScript + xterm.js. Build tool TBD in implementation (Vite is the default); frontend framework choice is non-architectural and deferred to the plan.
|
||||
|
||||
## Wire protocol
|
||||
|
||||
Three pairs of conversations. All JSON unless otherwise noted.
|
||||
|
||||
### Daemon ↔ Registry — single persistent WS, daemon-initiated
|
||||
|
||||
| Direction | Message | Purpose |
|
||||
|---|---|---|
|
||||
| D→R | `Hello { daemon_id, hostname, version, token }` | identify, auth |
|
||||
| D→R | `SessionsSnapshot { sessions: [Session] }` | full list at startup |
|
||||
| D→R | `SessionAdded { session }` | diff |
|
||||
| D→R | `SessionRemoved { id }` | diff |
|
||||
| D→R | `SessionUpdated { session }` | diff |
|
||||
| D→R | `Heartbeat` | every ~10s |
|
||||
| D→R | `CreateSessionResult { reply_to, result }` | reply to a `CreateSession` request, carries the new `Session` or an error |
|
||||
| D→R | `KillSessionResult { reply_to, result }` | reply to a `KillSession` request |
|
||||
| R→D | `Ack` / `Error { code, message }` | acks, faults |
|
||||
| R→D | `CreateSession { request, reply_to }` | registry asks daemon to spawn a session; `reply_to` correlates with the result |
|
||||
| R→D | `KillSession { id, reply_to }` | registry asks daemon to kill; `reply_to` correlates with the result |
|
||||
|
||||
The HTTP `POST /api/sessions` handler in the registry holds the client request open while it sends `CreateSession` to the chosen daemon over the WS, then completes the response when it receives the matching `CreateSessionResult`. Same pattern for `DELETE`. Each request gets a fresh `reply_to` UUID. Timeout is 10s; after that the registry returns 504 to the client.
|
||||
|
||||
### Client ↔ Registry — HTTP for queries, one WS for live updates
|
||||
|
||||
| Endpoint | Purpose |
|
||||
|---|---|
|
||||
| `GET /` | static web client bundle |
|
||||
| `GET /api/daemons` | list connected daemons |
|
||||
| `GET /api/sessions` | flat session list |
|
||||
| `POST /api/sessions` | spawn (request forwarded to chosen daemon) |
|
||||
| `DELETE /api/sessions/:id` | kill (forwarded to owning daemon) |
|
||||
| `GET /api/sessions/:id/connect-info` | returns `{ daemon_url, jwt }` for direct attach |
|
||||
| `WS /api/events` | live catalog + presence deltas |
|
||||
|
||||
Auth: the registry binds its listener exclusively to the Tailscale interface (resolved at startup from `tailscale ip --4` or equivalent), so non-tailnet packets never reach the process. On first request, it sets an httpOnly cookie signed with the shared secret; all subsequent API calls require it. The cookie is the second factor against a curious tailnet member.
|
||||
|
||||
### Client ↔ Daemon — one WS per attached session
|
||||
|
||||
`WS /sessions/:id/stream?token=<jwt>`
|
||||
|
||||
- **Text frames**: control JSON — `Resize { cols, rows }`, `Ping`, `Pong`, `Error { ... }`.
|
||||
- **Binary frames**: raw PTY bytes, bidirectional.
|
||||
|
||||
JWT is short-lived (~5 min) and validated by the daemon using the shared secret. No callback to registry.
|
||||
|
||||
Daemon broadcasts incoming PTY output to all currently-attached client WS connections for that session.
|
||||
|
||||
## Session model
|
||||
|
||||
A `Session` is the only first-class entity. The daemon is the source of truth for its own sessions.
|
||||
|
||||
```rust
|
||||
struct Session {
|
||||
id: Uuid, // maestro's id; tmux session name is `maestro-<id>`
|
||||
daemon_id: String,
|
||||
cwd: PathBuf, // resolved at create time (may be a worktree path)
|
||||
command: String,
|
||||
env: HashMap<String, String>,
|
||||
metadata: HashMap<String, Value>, // opaque; common keys: name, label
|
||||
status: SessionStatus, // Running | Dead
|
||||
created_at: DateTime<Utc>,
|
||||
}
|
||||
```
|
||||
|
||||
`metadata` is intentionally opaque to the daemon and registry. Clients use convention — e.g. `label: "personal/maestro"` becomes a tree path. The protocol doesn't enforce shape.
|
||||
|
||||
### Create options
|
||||
|
||||
`POST /api/sessions` body (forwarded to daemon as `CreateSession`):
|
||||
|
||||
```json
|
||||
{
|
||||
"daemon_id": "...",
|
||||
"cwd": "/home/naps62/projects/maestro",
|
||||
"command": "claude",
|
||||
"env": { "FOO": "bar" },
|
||||
"metadata": { "name": "maestro-impl", "label": "personal/maestro" },
|
||||
"worktree": {
|
||||
"base_repo": "/home/naps62/projects/maestro",
|
||||
"branch": "feat/foo",
|
||||
"cleanup_on_kill": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`worktree` is optional. When present, the daemon runs `git worktree add <generated-path> -b <branch>` rooted at `base_repo`, then uses the generated path as `cwd`. If `cleanup_on_kill` is true, the daemon prunes the worktree on `KillSession`. Default is false — the worktree stays on disk.
|
||||
|
||||
### Lifecycle
|
||||
|
||||
```
|
||||
Create Attach Detach Kill
|
||||
│ │ │ │
|
||||
▼ ▼ ▼ ▼
|
||||
client→registry client→daemon close WS client→daemon
|
||||
POST /sessions WS /sessions/:id (session DELETE /sessions/:id
|
||||
│ │ keeps │
|
||||
▼ ▼ running) ▼
|
||||
registry→daemon daemon attaches daemon kills
|
||||
CreateSession via tmux pipe-pane tmux session,
|
||||
│ │ optionally
|
||||
▼ ▼ prunes worktree
|
||||
daemon: (optional) bidirectional stream
|
||||
git worktree add
|
||||
│
|
||||
▼
|
||||
daemon: tmux new-session
|
||||
-d -s maestro-<id> -c <cwd> <cmd>
|
||||
│
|
||||
▼
|
||||
daemon→registry
|
||||
SessionAdded
|
||||
```
|
||||
|
||||
### Crash and restart recovery
|
||||
|
||||
- **Daemon restart**: on boot, the daemon lists tmux sessions matching `maestro-*`. For each, it reads a sidecar JSON in `~/.local/state/maestrod/sessions/<id>.json` (written at create time) to recover metadata. Sessions whose sidecars are missing are still advertised but with empty metadata. The daemon re-establishes the WS to the registry and sends a fresh `SessionsSnapshot`.
|
||||
- **Registry restart**: in-memory state is lost. Daemons hold an outbound WS with exponential-backoff retry; within seconds of registry coming back, every daemon has re-registered and the catalog is rebuilt. Clients holding direct daemon WS streams are unaffected — only catalog-listing breaks temporarily.
|
||||
- **Client disconnect**: just closes the WS. Session keeps running. Reconnecting re-attaches.
|
||||
- **Daemon dies / unreachable**: registry marks it offline after a missed heartbeat (~30s). Its sessions disappear from the catalog. When it comes back, they reappear.
|
||||
|
||||
## Auth
|
||||
|
||||
- Registry generates `MAESTRO_TOKEN` at first run, printed once, stored in `~/.config/maestro/registry.toml`.
|
||||
- Same token deployed to each daemon (config file or env var) and used in `Hello`.
|
||||
- Web client gets a cookie from the registry, scoped by tailnet IP. All registry API calls use it.
|
||||
- Per-attach JWT issued by registry, signed with the shared secret, validated locally by the daemon. ~5 min expiry; client refreshes by re-requesting `GET /api/sessions/:id/connect-info`.
|
||||
|
||||
Single-user trust model. Tailscale is the perimeter; the token is the second factor against a curious tailnet member.
|
||||
|
||||
## Repo layout
|
||||
|
||||
Cargo workspace:
|
||||
|
||||
```
|
||||
maestro/
|
||||
├── Cargo.toml # workspace
|
||||
├── crates/
|
||||
│ ├── maestro-protocol/ # message types, shared between binaries
|
||||
│ ├── maestro-registry/ # registry binary
|
||||
│ ├── maestro-daemon/ # daemon binary
|
||||
│ └── maestro-cli/ # `maestro` CLI for scripting (spawn/list/kill from shell)
|
||||
├── web/
|
||||
│ ├── src/
|
||||
│ ├── package.json
|
||||
│ └── vite.config.ts
|
||||
├── docs/superpowers/specs/ # this file, future specs
|
||||
├── .claude/
|
||||
│ └── linear.json
|
||||
└── CLAUDE.md
|
||||
```
|
||||
|
||||
`maestro-cli` is a low-priority bonus — handy for scripted spawning and for testing the registry HTTP API. Drops out of scope if it slows the plan.
|
||||
|
||||
## Out of scope (prototype)
|
||||
|
||||
| Deferred | Why |
|
||||
|---|---|
|
||||
| UI polish, themes, animations | prove it works first |
|
||||
| Side-by-side / split-pane layout in one tab | protocol supports concurrent attaches; two browser tabs is the workaround |
|
||||
| Native TUI client, Leptos/WASM client, native Android | protocol is stable; addable later |
|
||||
| Public internet (non-Tailscale) access | Tailscale assumption stands |
|
||||
| Multi-user / roles / RBAC | single user, single token |
|
||||
| Persistent registry storage | in-memory, re-derived from daemon reconnects |
|
||||
| Auto-adopting foreign tmux sessions | daemon only owns sessions it created |
|
||||
| Auto-restart of dead inner processes | tmux keeps the session; if the inner command exits, it exits |
|
||||
| Recording / replay | future |
|
||||
| File transfer / drag-drop | future |
|
||||
|
||||
## Testing strategy
|
||||
|
||||
- **`maestro-protocol`**: unit tests on every message variant, JSON round-trip, schema stability.
|
||||
- **`maestro-daemon`**: integration tests against a real `tmux` binary in a temp `$HOME` (with `TMUX_TMPDIR` set). Worktree creation tested against a tmpdir git repo (`git init`, then exercise `worktree add` + cleanup).
|
||||
- **`maestro-registry`**: tests with a mock daemon WS client. Cover register, heartbeat-timeout, session diff propagation, JWT issuance.
|
||||
- **End-to-end**: harness that spawns one registry + two daemons as subprocesses in temp dirs, then a programmatic client (using `tokio-tungstenite`) that lists, spawns, attaches, sends bytes, kills. Asserts on both daemons' tmux state and on registry catalog deltas.
|
||||
- **Web client**: smoke-only for the prototype. Manual verification in desktop Chrome and Android Chrome. A single Playwright test if it doesn't slow CI.
|
||||
|
||||
CI runs the Rust workspace; `npm run build` is gated on it succeeding.
|
||||
|
||||
## Open questions to resolve during implementation
|
||||
|
||||
These don't block the design but should be settled early in the plan:
|
||||
|
||||
- **Frontend framework**: vanilla TS, Preact, SolidJS, or Leptos-WASM from day one? Pick during the implementation plan; doesn't affect the protocol.
|
||||
- **Sidecar persistence file format**: JSON is fine; only flagged because if it grows, we'll want a single sqlite per-daemon instead.
|
||||
- **PTY backend details**: the prototype uses `tmux pipe-pane` for output capture and `tmux send-keys` for input. If pipe-pane latency or framing turns out to be unworkable, fallback is `portable-pty` wrapping `tmux attach`. This is implementation-only — no protocol impact.
|
||||
- **Registry HTTP framework**: `axum` is the default Rust choice; reconfirm at plan time.
|
||||
- **CLI scope**: keep it minimal (`maestro list`, `maestro spawn`, `maestro attach`) or fuller. Probably minimal.
|
||||
Reference in New Issue
Block a user