feat(desktop): add IDE workspace switcher with recent folders

Expose GET /api/workspaces and POST /api/workspaces/open so users can switch
between on-disk project folders like VS Code/Cursor, with persisted recents
and Nexus-inspired topbar UI including browser and pywebview open-folder flows.

Author: jravenel

libs/naas-abi/naas_abi/apps/desktop/AGENTS.md

@@ -99,7 +99,9 @@ desktop/
 
 ## API surface (localhost only)
 
-- `GET/PUT /api/settings` — workspace root, harness (`opencode` | `pi`), binaries, default model, agents, doctor dismissed, **active_org**, **active_model**
+- `GET/PUT /api/settings` — workspace root, harness (`opencode` | `pi`), binaries, default model, agents, doctor dismissed, **active_org**, **active_model**, **recent_workspaces**
+- `GET /api/workspaces` — active workspace + recent folders `{ active, recent: [{path, name, exists}] }`
+- `POST /api/workspaces/open` — `{ path }` opens an existing writable folder, sets active workspace, updates recent list
 - `GET /api/workspace/env` — `.env` / `.env.remote` presence and key names in workspace root
 - `GET /api/workspace/status` — git branch, workspace name, harness health, agents, default model (status bar)
 - `GET /api/workspace/orgs` — org folders under workspace root + active org/model
@@ -118,6 +120,19 @@ desktop/
 - `GET /api/graph/overview` — vis.js graph payload: nodes, edges, SQLite table snapshots
 - `POST /api/router/suggest` — intent-aware model suggestions from `instances.ttl` BFO7 realizabilities
 
+## Workspace switcher (IDE folder semantics)
+
+A workspace is a **folder on disk** (VS Code / Cursor semantics), not a Nexus tenant.
+
+- **UI**: topbar-left button (logo + basename + chevron) opens a Nexus-inspired dropdown (square corners). Shows the current path (dimmed), recent workspaces, and **Open Folder…**.
+- **Switch / open**: `POST /api/workspaces/open` or `PUT /api/settings` with a new `workspace_root`. Triggers `ensure_workspace`, harness restart, terminal reconnect, file index refresh, org/model context reload, and graph rescaffold.
+- **Recent list**: `recent_workspaces` setting (JSON array, max 10 paths). Updated on every open/switch.
+- **First run**: `maybe_upgrade_workspace_setting()` auto-detects `~/abi` (git + `.env`) when still on the factory default.
+- **Open Folder**:
+  - **Browser dev** (`--browser-only`): modal with absolute path input; server validates the folder exists and is writable.
+  - **pywebview app**: same modal plus **Browse…** calling `pywebview.api.pick_workspace_folder()` (native `FOLDER_DIALOG` via `main.py` `DesktopApi` bridge).
+- **Nexus reference**: `apps/nexus/apps/web/src/components/shell/sidebar/index.tsx` (workspace logo menu, glass dropdown portal).
+
 ## Org/model workspace layout
 
 Canonical context path under the workspace root::
@@ -267,7 +282,7 @@ Canonical command (pytest + coverage KPI):
 make test-desktop
 ```
 
-Expected footer: `237 passed, 0 failed` and `TOTAL coverage 90%` (approximate; run the script for the current number). CI one-liner: `scripts/coverage-kpi.sh` → `desktop_coverage=90.0 pass=237 fail=0`.
+Expected footer: `244 passed, 0 failed` and `TOTAL coverage 90%` (approximate; run the script for the current number). CI one-liner: `scripts/coverage-kpi.sh` → `desktop_coverage=90.0 pass=244 fail=0`.
 
 See [README.md](README.md) for prerequisites, quick start, and folder map.
 

libs/naas-abi/naas_abi/apps/desktop/README.md

@@ -27,6 +27,8 @@ uv run python libs/naas-abi/naas_abi/apps/desktop/run.py --browser-only
 
 Open [http://127.0.0.1:54242](http://127.0.0.1:54242). Override the port with `ABI_DESKTOP_PORT` if needed.
 
+Use the **workspace switcher** (top-left: logo + folder name + chevron) to open or switch IDE workspaces. Each workspace is a folder on disk (e.g. `~/abi`). In browser dev, **Open Folder…** accepts a typed path; in the pywebview app, **Browse…** opens the native folder picker.
+
 Useful flags:
 
 ```bash
@@ -67,7 +69,7 @@ make test-desktop
 Expected output ends with:
 
 ```
-237 passed, 0 failed
+244 passed, 0 failed
 TOTAL coverage 90%
 ```
 
@@ -80,7 +82,7 @@ CI one-liner (after `test.sh`):
 
 ```bash
 ./libs/naas-abi/naas_abi/apps/desktop/scripts/coverage-kpi.sh
-# desktop_coverage=90.0 pass=237 fail=0
+# desktop_coverage=90.0 pass=244 fail=0
 ```
 
 Single file or keyword runs pass through to pytest:

libs/naas-abi/naas_abi/apps/desktop/api/server.py

@@ -46,10 +46,15 @@
     DB_PATH,
     GRAPH_DIR,
     WORKSPACE_ROOT_VISIBLE,
+    add_recent_workspace,
     build_shell_env_source,
     ensure_dirs,
     ensure_workspace,
     maybe_upgrade_workspace_setting,
+    parse_recent_workspaces,
+    serialize_recent_workspaces,
+    validate_workspace_dir,
+    workspace_entry,
     workspace_env_report,
 )
 from ..core.doctor import OpencodeProbe, run_doctor
@@ -116,6 +121,10 @@ def _git_branch(workspace_root: str | Path) -> str | None:
     return None
 
 
+class OpenWorkspaceRequest(BaseModel):
+    path: str
+
+
 class SettingsUpdate(BaseModel):
     workspace_root: str | None = None
     active_org: str | None = None
@@ -427,6 +436,83 @@ async def workspace_status() -> dict[str, Any]:
         }
         return payload
 
+    def _workspaces_payload() -> dict[str, Any]:
+        settings = store.get_settings()
+        active_root = settings.get("workspace_root") or ""
+        active = workspace_entry(active_root) if active_root else None
+        recent_paths = parse_recent_workspaces(settings.get("recent_workspaces"))
+        recent = [workspace_entry(path) for path in recent_paths]
+        return {"active": active, "recent": recent}
+
+    async def _restart_harness_for_workspace(
+        updated: dict[str, str],
+        prior: dict[str, str],
+        values: dict[str, str],
+    ) -> None:
+        nonlocal harness
+        harness_keys = ("workspace_root", "harness", "opencode_bin", "pi_bin")
+        if not any(key in values for key in harness_keys):
+            return
+        ensure_workspace(Path(updated["workspace_root"]))
+        if "harness" in values and values["harness"] != prior.get("harness"):
+            await harness.stop()
+            harness = create_harness(updated)
+            app.state.harness = harness
+        else:
+            binary = (
+                updated.get("opencode_bin")
+                if (updated.get("harness") or "opencode") == "opencode"
+                else updated.get("pi_bin")
+            )
+            try:
+                await harness.restart(
+                    workspace_root=updated.get("workspace_root"),
+                    binary=binary,
+                )
+            except HarnessUnavailableError:
+                pass
+
+    async def _reload_workspace_context(updated: dict[str, str]) -> None:
+        workspace = Path(updated["workspace_root"]).resolve()
+        org = updated.get("active_org") or DEFAULT_ORG
+        model = updated.get("active_model") or DEFAULT_MODEL
+        scaffold_org_model(workspace, org, model)
+        try:
+            _reload_active_context()
+        except Exception:
+            pass
+
+    @app.get("/api/workspaces")
+    def list_workspaces() -> dict[str, Any]:
+        return _workspaces_payload()
+
+    @app.post("/api/workspaces/open")
+    async def open_workspace(body: OpenWorkspaceRequest) -> dict[str, Any]:
+        nonlocal harness
+        try:
+            resolved = validate_workspace_dir(body.path)
+        except ValueError as exc:
+            raise HTTPException(400, str(exc)) from exc
+        prior = store.get_settings()
+        recent = add_recent_workspace(
+            parse_recent_workspaces(prior.get("recent_workspaces")),
+            resolved,
+        )
+        updated = store.update_settings(
+            {
+                "workspace_root": str(resolved),
+                "recent_workspaces": serialize_recent_workspaces(recent),
+            }
+        )
+        await _restart_harness_for_workspace(
+            updated, prior, {"workspace_root": str(resolved)}
+        )
+        await _reload_workspace_context(updated)
+        return {
+            "settings": updated,
+            "workspaces": _workspaces_payload(),
+        }
+
     @app.put("/api/settings")
     async def put_settings(update: SettingsUpdate) -> dict[str, str]:
         nonlocal harness
@@ -436,41 +522,23 @@ async def put_settings(update: SettingsUpdate) -> dict[str, str]:
             values["active_org"] = sanitize_segment(values["active_org"])
         if "active_model" in values:
             values["active_model"] = sanitize_segment(values["active_model"])
+        if "workspace_root" in values:
+            recent = add_recent_workspace(
+                parse_recent_workspaces(prior.get("recent_workspaces")),
+                values["workspace_root"],
+            )
+            values["recent_workspaces"] = serialize_recent_workspaces(recent)
         updated = store.update_settings(values)
         harness_keys = ("workspace_root", "harness", "opencode_bin", "pi_bin")
         if any(key in values for key in harness_keys):
-            ensure_workspace(Path(updated["workspace_root"]))
-            if "harness" in values and values["harness"] != prior.get("harness"):
-                await harness.stop()
-                harness = create_harness(updated)
-                app.state.harness = harness
-            else:
-                binary = (
-                    updated.get("opencode_bin")
-                    if (updated.get("harness") or "opencode") == "opencode"
-                    else updated.get("pi_bin")
-                )
-                try:
-                    await harness.restart(
-                        workspace_root=updated.get("workspace_root"),
-                        binary=binary,
-                    )
-                except HarnessUnavailableError:
-                    pass
+            await _restart_harness_for_workspace(updated, prior, values)
         context_changed = (
             "workspace_root" in values
             or "active_org" in values
             or "active_model" in values
         )
         if context_changed:
-            workspace = Path(updated["workspace_root"]).resolve()
-            org = updated.get("active_org") or DEFAULT_ORG
-            model = updated.get("active_model") or DEFAULT_MODEL
-            scaffold_org_model(workspace, org, model)
-            try:
-                _reload_active_context()
-            except Exception:
-                pass
+            await _reload_workspace_context(updated)
         return updated
 
     @app.get("/api/workspace/orgs")

libs/naas-abi/naas_abi/apps/desktop/api/server_test.py

@@ -201,6 +201,62 @@ def test_workspace_env_preview_uses_query_param(
     assert "ANTHROPIC_API_KEY" in payload["provider_keys"]
 
 
+def test_workspaces_list_returns_active_and_recent(
+    client: TestClient, workspace: Path, tmp_path: Path
+) -> None:
+    other = tmp_path / "other-project"
+    other.mkdir()
+    client.put("/api/settings", json={"workspace_root": str(workspace)})
+    client.post("/api/workspaces/open", json={"path": str(other)})
+
+    payload = client.get("/api/workspaces").json()
+    assert payload["active"]["path"] == str(other.resolve())
+    assert payload["active"]["name"] == "other-project"
+    assert payload["active"]["exists"] is True
+    recent_paths = [item["path"] for item in payload["recent"]]
+    assert str(other.resolve()) in recent_paths
+    assert str(workspace.resolve()) in recent_paths
+
+
+def test_workspaces_open_sets_active_and_adds_recent(
+    client: TestClient, workspace: Path, tmp_path: Path, opencode: StubOpencode
+) -> None:
+    target = tmp_path / "opened"
+    target.mkdir()
+    (target / "marker.txt").write_text("ok")
+
+    response = client.post("/api/workspaces/open", json={"path": str(target)})
+    assert response.status_code == 200
+    body = response.json()
+    assert body["settings"]["workspace_root"] == str(target.resolve())
+    assert body["workspaces"]["active"]["name"] == "opened"
+    assert opencode.restarts[-1]["workdir"] == str(target.resolve())
+
+
+def test_workspaces_open_invalid_path_400(client: TestClient) -> None:
+    response = client.post(
+        "/api/workspaces/open", json={"path": "/no/such/workspace/folder"}
+    )
+    assert response.status_code == 400
+
+
+def test_workspaces_switch_updates_file_listing_root(
+    client: TestClient, workspace: Path, tmp_path: Path
+) -> None:
+    other = tmp_path / "listing-root"
+    other.mkdir()
+    (other / "only-here.txt").write_text("x")
+    (workspace / "only-here.txt").write_text("y")
+
+    client.post("/api/workspaces/open", json={"path": str(other)})
+    listing = client.get("/api/files").json()
+    names = [entry["name"] for entry in listing["entries"]]
+    assert "only-here.txt" in names
+    assert client.get("/api/files/content", params={"path": "only-here.txt"}).json()[
+        "content"
+    ] == "x"
+
+
 def test_workspace_status_reports_git_and_harness(
     client: TestClient, workspace: Path, opencode: StubOpencode
 ) -> None: