Adom Hydrogen (platform base)

@@ -1,28 +1,23 @@ --- name: hydrogen-desktop-sse-description: How Hydrogen's local workspace API + SSE works (a.k.a. the workspace API) — replaces Carbon for workspace commands so the workspace's adom-cli controls Hydrogen, not cloud Hydrogen. Covers the full pipeline, routing, env vars, field format differences, port discovery, and hard-won lessons. Trigger words — Hydrogen SSE, workspace API, local API, adom-cli workspace, add-tab, move-tab, webview tab, EventSource, workspace_updated, ADOM_CARBON_URL, ADOM_HYDROGEN_URL, discovery port.+description: How Hydrogen's local workspace API + SSE works (a.k.a. the workspace API) — replaces Carbon for workspace commands so the workspace's adom-cli controls Hydrogen, not cloud Hydrogen. The workspace is the WSL2 Adom-Workspace distro. Covers the full pipeline, routing, env vars, field format differences, and hard-won lessons. Trigger words — Hydrogen SSE, workspace API, local API, adom-cli workspace, add-tab, move-tab, webview tab, EventSource, workspace_updated, ADOM_CARBON_URL, ADOM_HYDROGEN_URL. ---  # Hydrogen — Local Workspace API + SSE -> Platform note: Hydrogen runs the same local workspace API on every platform. The-> host-specific networking details (loopback forwarding, the `ports.json` location,-> the legacy runtime modes, relay port behavior) live in the platform companion —-> see **[[hydrogen-desktop-sse-windows]]** on Windows.- ## Architecture  ```-Workspace adom-cli (the local workspace)+Workspace adom-cli (the WSL2 Adom-Workspace distro)     → http://127.0.0.1:47083 (Hydrogen's proxy)     → Hydrogen handles workspace commands locally + broadcasts SSE     → Hydrogen frontend receives SSE, re-fetches workspace, renders -Cloud adom-cli (unchanged)+Cloud Docker's adom-cli (unchanged)     → carbon.adom.inc → Hydrogen web ``` -Hydrogen runs its own workspace API on port 47083 (reverse proxy, default — see PortConfig) so the workspace's adom-cli controls Hydrogen's UI, not cloud Hydrogen. No cross-talk between environments. The workspace reaches Hydrogen at `127.0.0.1:47083`.+Hydrogen runs its own workspace API on port 47083 (reverse proxy, default — see PortConfig) so the workspace's adom-cli controls Hydrogen's UI, not cloud Hydrogen. No cross-talk between environments. (Under WSL2 the workspace reaches Hydrogen at `127.0.0.1:47083` — mirrored networking shares loopback with the Windows host.)  ## Port 47083 routing (the hydrogen-proxy / reverse-proxy) @@ -33,7 +28,7 @@ All requests hit port 47083 (reverse proxy, default — see PortConfig). The rou | `/api/workspaces/editor/{owner}/{repo}/current/*` | Local workspace API | In-memory | | `/api/panels/webview/*`, `/api/panels/sandbox/*` | Local panel API | SSE broadcast | | `/containers/*` | Local container discovery | Canned response |-| `/proxy/{port}/{path}` | Workspace proxy | TCP forward to the workspace |+| `/proxy/{port}/{path}` | Workspace proxy | TCP forward to the workspace (WSL2 distro) | | Everything else (`/api/*`, etc.) | Carbon proxy | HTTPS to carbon.adom.inc |  The dev file server on port 1420 forwards `/api/*` directly to `handle_request()` (same function, not TCP — supports SSE streaming via BoxBody).@@ -68,7 +63,7 @@ NOT `{"owner": "jlauer12", "repository": "workspace"}` — adom-cli reads `conta  ## Workspace Env Vars -Set when the workspace is created:+Set by the WSL2 workspace-creation code when the distro is created:  | Var | Value | Why | |---|---|---|@@ -77,7 +72,7 @@ Set when the workspace is created: | `ADOM_HYDROGEN_URL` | `http://127.0.0.1:47083` | Workspace mutations (adom-cli sends these HERE, not to Carbon) | | `ADOM_DESKTOP_MODE` | `local` | Tells adom-cli it's a local environment | -`127.0.0.1` reaches Hydrogen on the host from inside the workspace. The canonical code-server port Hydrogen exposes on the host is 7380.+Under WSL2, `127.0.0.1` reaches the Windows host directly — mirrored networking shares loopback with the host, so the same `127.0.0.1:<port>` works from inside the distro and on Windows. The canonical code-server port Hydrogen exposes on the host is 7380.  **Also set in adom-cli config** (persists across sessions): ```bash@@ -129,7 +124,7 @@ adom-cli hydrogen workspace add-tab \   --panel-id desktop-pane-right \   --panel-type adom/a1b2c3d4-0031-4000-a000-000000000031 \   --display-name "Test Page" \-  --initial-state '{"url":"https://wiki-ufypy5dpx93o.adom.cloud/apps/shotlog"}'+  --initial-state '{"url":"https://wiki.adom.inc/adom/adom-shotlog"}'  # 4. Move tab adom-cli hydrogen workspace move-tab \@@ -189,16 +184,18 @@ Returns: } ``` -> **Relay ports:** clients discover the relay ports from `~/.adom/cli-relay-ports.json`-> (fallback 8765/8766), not from `/discover`. Relay port mapping/exposure varies by-> platform — see **[[hydrogen-desktop-sse-windows]]**.+> **Relay ports:** under the WSL2 runtime the relay listens **same-port 8765+> (WS) / 8766 (HTTP)** inside the distro and is reached same-port via mirrored+> loopback (or via `/proxy/`). There are **no host 47081/47082 listeners**.+> Clients discover the relay ports from `~/.adom/cli-relay-ports.json` (fallback+> 8765/8766), not from `/discover`.  ### Who uses it  | Client | What it discovers | How | |---|---|---| | adom-bridge-cli relay | Control API port (was hardcoded 9001) | `curl :47080/discover` → use `control` field |-| adom-cli in the workspace | Proxy + Hydrogen URL | Already set via `ADOM_CARBON_URL` env var at workspace creation |+| adom-cli in the workspace (the WSL2 distro) | Proxy + Hydrogen URL | Already set via `ADOM_CARBON_URL` env var at workspace creation | | External tools / diagnostics | Any port | Hit discovery, get the full map | | Cloud Docker (this container) | All Hydrogen ports | `curl http://<desktop-ip>:47080/discover` via relay | @@ -226,17 +223,16 @@ std::thread::spawn(move || { | Proxy | 47083 | No | n/a | | Control API | 47084 | No | n/a | | CDP | 47085 | No | n/a |-| Relay WS | (platform-dependent) | No | 8765 |-| Relay HTTP | (platform-dependent) | No | 8766 |+| Relay WS | — (same-port under WSL2) | No | 8765 |+| Relay HTTP | — (same-port under WSL2) | No | 8766 | -On first launch, defaults are written without scanning. Workspace-side ports (8080, 8765, 8766) are always fixed — only host-side ports are dynamic. The `ports.json` location and relay host mapping are platform-specific — see **[[hydrogen-desktop-sse-windows]]**.+Config stored at `%APPDATA%\hydrogen-desktop\ports.json`. On first launch, defaults are written without scanning. Workspace-side ports (8080, 8765, 8766) are always fixed — only host-side ports are dynamic. The relay (8765/8766) is reached **same-port** under WSL2 (mirrored loopback) — no host 47081/47082 mapping; discover it from `~/.adom/cli-relay-ports.json` (fallback 8765/8766).  ## Files  | File | What | |---|---| | `src-tauri/crates/hydrogen-proxy/src/lib.rs` | Workspace API, SSE, Carbon proxy, tree mutations (~1500 lines) |-| `src-tauri/crates/hydrogen-docker/src/lib.rs` | Container env vars (CARBON_URL, HYDROGEN_URL, VSCODE_PROXY_URI) | | `src-tauri/crates/hydrogen-control/src/lib.rs` | `/auth-token` endpoint, `/ports` endpoint, `/setup/*` routes | | `src-tauri/crates/hydrogen-control/src/ports.rs` | PortConfig struct, load/save/resolve, DISCOVERY_PORT constant | | `src-tauri/crates/hydrogen-app/src/lib.rs` | Discovery server on :47080, port resolution at startup |