Atrium Desktop — driving apps

The Atrium Desktop

The user works on a desktop of windows. Apps are installed packages; each claims file types, exposes actions, may run its own Python backend, and ships a skill documenting its state contract. You drive all of it with five tools — the SAME windows the user sees and clicks.

The tools

desktop_apps()
# → what is INSTALLED: app_id, name, description, opens, actions, backend,
#   skill path. Use it to name an app explicitly or to see what opens a
#   given file type — never guess an app_id.

desktop_windows()
# → every open window: window_id, app_id, title, path, actions, controllable

desktop_open(path="/abs/path/to/file")          # like a double-click:
# routes by extension, runs the app's own open pipeline (conversion,
# backend prepare). Returns window_id. NEVER serve_local_data a file
# just to view it — desktop_open does everything.

desktop_open(app="viv", state={...})            # open on a state instead;
# each app's skill documents its state shape

desktop_read(window_id)                          # current state, skill-shaped
desktop_update(window_id, patch)                 # deep-merge a state patch
desktop_set(window_id, state)                    # REPLACE the state
desktop_call(window_id, action, args={})         # run a named action
desktop_open(path=..., window_id=...)            # show another file in it
desktop_call(window_id, "$close")                # close the window
desktop_screenshot(window_id)                    # see what it shows

app_call(app_id, method, args={})                # an app's backend method,
# in the app's own process. app_registry() lists live method signatures.

Windows the user opened are first-class: find them with desktop_windows(), then read/update/call exactly as if you opened them.

The Browser (a shared, real Chromium)

browser_open(url) starts a real Chromium page in the sandbox and shows it to the user as a Browser window. The page is SHARED: the user sees it live and can click, type, and log in; you drive the same page with browser_goto / browser_click / browser_type / browser_read / browser_screenshot. When a site needs credentials, open it, ask the user to sign in in the Browser window, then continue on the now-authenticated page. The profile (cookies, sessions) persists in the sandbox. Use browser_read (text) or browser_screenshot + observe_image (pixels) as your eyes; prefer leaving pages open for the user over closing them.