@vellumai/assistant 0.12.2-dev.202609191615.99620e2 → 0.12.2-dev.202609210132.d52247f

package/docs/desktop-browser-cli.md

@@ -16,6 +16,10 @@ flowchart LR
   Chrome --> Stream[Existing desktop stream]
 ```
 
+The Terminal dock launcher opens [WezTerm](https://wezterm.org/), with a plain dark native title bar, minimize/maximize/close controls, a new-tab button and split panes. Use Ctrl+Shift+T for a tab, Ctrl+Shift+D to split side by side, and Ctrl+Shift+E to split top and bottom. The desktop seeds an editable `data/desktop-panel/wezterm/wezterm.lua` configuration with software rendering and a dark theme. The managed launcher keeps its stable `data/desktop-panel/applications/xterm.desktop` path so existing dock pins remain valid. Setup installs an exact-version, SHA-256-verified WezTerm package for Linux x64 or ARM64, plus its rendering libraries.
+
+Chrome and WezTerm use explicit desktop window classes shared with their launcher entries. The desktop session bus and Plank share `XDG_DATA_HOME` so the D-Bus-activated window matcher can resolve the generated launchers and group running windows under their pinned icons.
+
 Chrome and its dock launcher share the managed profile and loopback debug port. For Chrome reopened from the dock, the profile singleton lock identifies a candidate PID, validated against the installed executable, profile and loopback debug arguments. Discovery checks `/proc` socket ownership against that browser PID, refuses redirects and validates the returned browser WebSocket endpoint. The connection stays within the container. No CDP endpoint or token is exposed to the renderer.
 
 The desktop client bypasses personal-browser discovery, extension reconnect waits and backend fallback. It reuses the existing AX snapshot, DOM element resolution, mouse, keyboard, extraction and credential-fill implementations. Operation-scoped clients borrow the lease's connection; disposing one does not release the lease. `detach`, `close`, turn completion, cancellation, errors and idle expiry release control. Turn completion clears the activity indicator immediately and queues browser cleanup before the next automation session; it leaves Chrome and the current page open for the user. Only `tabs close` closes a Chrome tab.
@@ -54,3 +58,17 @@ Browser commands, user handoff, errors, and interruption require a fresh
 observation before returning to native input. Browser commands and computer use
 share session ownership, cancellation, and the user-help reservation. Use
 browser commands for page-level operations and computer use for desktop UI.
+
+## File explorer
+
+Open **Files**, between Chrome and Terminal in the virtual desktop dock, to browse the assistant workspace in
+Thunar, with a Workspace sidebar shortcut and a dark theme. It supports tabs,
+split views, search, hidden files, drag and drop,
+copy/paste, bulk renaming, and file properties. GVfs provides Trash support and
+Tumbler provides thumbnails. Use Ctrl+L to enter a path, Ctrl+T for a new tab,
+Ctrl+H to toggle hidden files, and F3 for split view.
+
+Files manages the assistant's files. Files on your personal computer must first
+be uploaded or otherwise copied into the assistant workspace. Existing desktops
+receive the Files dock shortcut once during upgrade; removing or rearranging it
+is preserved across restarts.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.12.2-dev.202609191615.99620e2",
+  "version": "0.12.2-dev.202609210132.d52247f",
   "license": "MIT",
   "type": "module",
   "exports": {

package/scripts/smoke-desktop-window-theme.ts

@@ -91,15 +91,14 @@ try {
     `<bindings xmlns="http://openbox.org/3.4/rc">${mouse}${keyboard}</bindings>`,
   );
   const configDir = join(directory, "managed & theme");
-  const config = writeDesktopWindowTheme(configDir, home, "#53b7aa");
+  const config = writeDesktopWindowTheme(configDir, home);
   const expanded = run("xmllint", "--xinclude", config);
   assert(
     expanded.includes("NextWindow") && expanded.includes("Move"),
     "Relative includes must retain the actual keyboard and mouse bindings",
   );
   assert.equal(await readFile(sourcePath, "utf8"), source);
-  writeDesktopWindowTheme(configDir, home, "#bc7799");
-  writeDesktopWindowTheme(configDir, home, "#53b7aa");
+  writeDesktopWindowTheme(configDir, home);
   assert.equal(await readFile(sourcePath, "utf8"), source);
   const blocked = join(directory, "blocked");
   await writeFile(blocked, "not a directory");

package/src/desktop/desktop-browser-endpoint.ts

@@ -4,6 +4,8 @@ import { join } from "node:path";
 
 import { shouldRestoreDesktopChromeSession } from "./desktop-chrome-session.js";
 
+export const DESKTOP_CHROME_WINDOW_CLASS = "vellum-desktop-chrome";
+
 export async function allocateDesktopDebugPort(): Promise<number> {
   const server = createServer();
   await new Promise<void>((resolve, reject) => {
@@ -129,6 +131,7 @@ export function desktopChromeArguments(
   return [
     "--no-sandbox",
     "--no-first-run",
+    `--class=${DESKTOP_CHROME_WINDOW_CLASS}`,
     "--force-renderer-accessibility",
     "--disable-dev-shm-usage",
     ...(shouldRestoreDesktopChromeSession(profileDir)

package/src/desktop/desktop-dependencies.ts

@@ -12,6 +12,17 @@ import { getLogger } from "../util/logger.js";
 import { getExternalDir } from "../util/platform.js";
 
 const log = getLogger("desktop-dependencies");
+const WEZTERM_VERSION = "20240203-110809-5046fc22";
+const WEZTERM_PACKAGES = {
+  x64: {
+    suffix: "Debian12.deb",
+    sha256: "d3a5c97093fbc0a87e8f9616e44efc4c9503cfc495fd1cfe4ffeff88578d15f8",
+  },
+  arm64: {
+    suffix: "Debian12.arm64.deb",
+    sha256: "351f8791c6e9561d687afa63834a2132de84800dad6e7c3d035cc6518d6c3744",
+  },
+} as const;
 const CHROME_VERSION = "153.0.8010.36-1";
 const CHROME_PACKAGES = {
   x64: {
@@ -32,17 +43,22 @@ const DESKTOP_BINARIES = {
   panel: ["plank"],
   sessionBus: ["dbus-daemon"],
   clipboard: ["tigervncconfig", "vncconfig"],
-  terminal: ["xterm"],
+  terminal: ["wezterm"],
+  fileManager: ["thunar"],
   wallpaper: ["feh"],
   input: ["xdotool"],
   capture: ["scrot"],
 } as const;
 
 const DESKTOP_PACKAGES = [
+  "adwaita-icon-theme",
   "at-spi2-core",
   "dbus-x11",
   "feh",
   "gnome-mines",
+  "gvfs",
+  "thunar",
+  "tumbler",
   "openbox",
   "python3",
   "python3-dbus",
@@ -54,11 +70,14 @@ const DESKTOP_PACKAGES = [
   "xauth",
   "xcompmgr",
   "xfonts-base",
+  // Preserved Openbox menus and shortcuts can invoke xterm directly.
   "xterm",
   "xdotool",
   "scrot",
   "fonts-liberation",
   "libgtk-3-0",
+  "libegl1",
+  "libgl1-mesa-dri",
   "libvulkan1",
   "libcurl4",
 ];
@@ -115,6 +134,12 @@ export class DesktopDependencyInstaller {
             existsSync(desktopChromePath() + ".ready") &&
             existsSync(desktopChromePath()) &&
             existsSync("/usr/games/gnome-mines") &&
+            existsSync(
+              "/usr/share/dbus-1/services/org.gtk.vfs.Daemon.service",
+            ) &&
+            existsSync(
+              "/usr/share/dbus-1/services/org.xfce.Tumbler.Thumbnailer1.service",
+            ) &&
             existsSync("/usr/share/fonts/X11/misc/fonts.dir") &&
             existsSync("/usr/share/dbus-1/services/org.ayatana.bamf.service") &&
             existsSync("/usr/share/dbus-1/services/org.a11y.Bus.service") &&
@@ -277,17 +302,36 @@ async function installDesktopComponents(
   await rm(desktopChromePath() + ".ready", { force: true });
   // Desktop binaries, X assets and the loader share the image root.
   await run([...apt, "update"]);
-  await run([
-    ...apt,
-    "install",
-    "-y",
-    "--no-install-recommends",
-    "--no-upgrade",
-    "--no-remove",
-    "-o",
-    "DPkg::Lock::Timeout=120",
-    ...DESKTOP_PACKAGES,
-  ]);
+  const terminal =
+    WEZTERM_PACKAGES[process.arch as keyof typeof WEZTERM_PACKAGES];
+  const terminalDownloadDir = await mkdtemp(
+    join(tmpdir(), "desktop-terminal-"),
+  );
+  try {
+    const deb = join(terminalDownloadDir, "wezterm.deb");
+    await downloadDesktopPackage(
+      `https://github.com/wezterm/wezterm/releases/download/${WEZTERM_VERSION}/wezterm-${WEZTERM_VERSION}.${terminal.suffix}`,
+      deb,
+      terminal.sha256,
+      caBundle,
+    );
+    await chmod(terminalDownloadDir, 0o755);
+    await chmod(deb, 0o644);
+    await run([
+      ...apt,
+      "install",
+      "-y",
+      "--no-install-recommends",
+      "--no-upgrade",
+      "--no-remove",
+      "-o",
+      "DPkg::Lock::Timeout=120",
+      ...DESKTOP_PACKAGES,
+      deb,
+    ]);
+  } finally {
+    await rm(terminalDownloadDir, { recursive: true, force: true });
+  }
   onStage("chrome");
   if (!existsSync(desktopChromePath())) {
     const downloadDir = await mkdtemp(join(tmpdir(), "desktop-chrome-"));
@@ -296,30 +340,12 @@ async function installDesktopComponents(
     const staging = await mkdtemp(join(installRoot, ".install-"));
     try {
       const deb = join(downloadDir, "chrome.deb");
-      await run([
-        "curl",
-        ...(caBundle ? ["--cacert", caBundle] : []),
-        "--fail",
-        "--location",
-        "--proto",
-        "=https",
-        "--proto-redir",
-        "=https",
-        "--retry",
-        "2",
-        "--max-time",
-        "300",
-        "--output",
-        deb,
+      await downloadDesktopPackage(
         `https://dl.google.com/linux/chrome/deb/pool/main/g/google-chrome-stable/google-chrome-stable_${CHROME_VERSION}_${chrome.arch}.deb`,
-      ]);
-      const hash = createHash("sha256");
-      for await (const chunk of createReadStream(deb)) {
-        hash.update(chunk);
-      }
-      if (hash.digest("hex") !== chrome.sha256) {
-        throw new Error("Chrome download checksum mismatch");
-      }
+        deb,
+        chrome.sha256,
+        caBundle,
+      );
       await run(["dpkg-deb", "--extract", deb, staging]);
       await rename(staging, join(installRoot, `chrome-${CHROME_VERSION}`));
     } finally {
@@ -330,8 +356,41 @@ async function installDesktopComponents(
     }
   }
   onStage("checking");
+  await run([resolveDesktopBinaries().terminal, "--version"]);
   await run([desktopChromePath(), "--version"]);
   await writeFile(desktopChromePath() + ".ready", "");
 }
 
+async function downloadDesktopPackage(
+  url: string,
+  destination: string,
+  sha256: string,
+  caBundle?: string,
+): Promise<void> {
+  await run([
+    "curl",
+    ...(caBundle ? ["--cacert", caBundle] : []),
+    "--fail",
+    "--location",
+    "--proto",
+    "=https",
+    "--proto-redir",
+    "=https",
+    "--retry",
+    "2",
+    "--max-time",
+    "300",
+    "--output",
+    destination,
+    url,
+  ]);
+  const hash = createHash("sha256");
+  for await (const chunk of createReadStream(destination)) {
+    hash.update(chunk);
+  }
+  if (hash.digest("hex") !== sha256) {
+    throw new Error("Desktop package download checksum mismatch");
+  }
+}
+
 export const desktopDependencyInstaller = new DesktopDependencyInstaller();

package/src/desktop/desktop-panel-config.test.ts

@@ -33,7 +33,9 @@ test("initializes the dock and preserves user changes across restarts", () => {
     configDir,
     chromiumPath: "/opt/chrome-v1/chrome",
     chromiumProfileDir: profileDir,
-    terminalPath: "/usr/bin/xterm",
+    terminalPath: "/usr/bin/wezterm",
+    fileManagerPath: "/usr/bin/thunar",
+    workspaceDir: workspace,
   };
   writeDesktopPanelConfig(request);
   const settingsPath = join(configDir, "glib-2.0", "settings", "keyfile");
@@ -59,6 +61,9 @@ test("initializes the dock and preserves user changes across restarts", () => {
   rmSync(join(pinsDir, "mines.dockitem"));
   const customSettings = settings.replace("icon-size=48", "icon-size=64");
   writeFileSync(settingsPath, customSettings);
+  const terminalConfig = join(configDir, "wezterm", "wezterm.lua");
+  const customTerminalConfig = `${readFileSync(terminalConfig, "utf8")}\n-- Custom settings\n`;
+  writeFileSync(terminalConfig, customTerminalConfig);
   writeDesktopPanelConfig({
     ...request,
     chromiumPath: "/opt/chrome-v2/chrome",
@@ -66,6 +71,7 @@ test("initializes the dock and preserves user changes across restarts", () => {
   expect(() => readFileSync(join(pinsDir, "chrome.dockitem"))).toThrow();
   expect(() => readFileSync(join(pinsDir, "mines.dockitem"))).toThrow();
   expect(readFileSync(settingsPath, "utf8")).toBe(customSettings);
+  expect(readFileSync(terminalConfig, "utf8")).toBe(customTerminalConfig);
   expect(
     readFileSync(
       join(configDir, "applications", "google-chrome.desktop"),
@@ -89,7 +95,9 @@ test("initialization recovers partial pin creation", () => {
     configDir,
     chromiumPath: "/opt/chrome/chrome",
     chromiumProfileDir: join(workspace, "data", "desktop-profile"),
-    terminalPath: "/usr/bin/xterm",
+    terminalPath: "/usr/bin/wezterm",
+    fileManagerPath: "/usr/bin/thunar",
+    workspaceDir: workspace,
   });
   expect(readFileSync(join(pinsDir, "chrome.dockitem"), "utf8")).toBe(
     "existing pin",
@@ -111,7 +119,9 @@ test("a failed settings write leaves initialization retryable", () => {
     configDir,
     chromiumPath: "/opt/chrome/chrome",
     chromiumProfileDir: join(workspace, "data", "desktop-profile"),
-    terminalPath: "/usr/bin/xterm",
+    terminalPath: "/usr/bin/wezterm",
+    fileManagerPath: "/usr/bin/thunar",
+    workspaceDir: workspace,
   };
   const write = fs.writeFileSync;
   const interrupted = spyOn(fs, "writeFileSync").mockImplementation(

package/src/desktop/desktop-panel-config.ts

@@ -3,13 +3,21 @@ import {
   existsSync,
   linkSync,
   mkdirSync,
+  readFileSync,
+  renameSync,
   rmSync,
   writeFileSync,
 } from "node:fs";
 import { dirname, join } from "node:path";
 import { pathToFileURL } from "node:url";
 
-import { desktopChromeArguments } from "./desktop-browser-endpoint.js";
+import {
+  DESKTOP_CHROME_WINDOW_CLASS,
+  desktopChromeArguments,
+} from "./desktop-browser-endpoint.js";
+
+const TERMINAL_WINDOW_CLASS = "vellum-desktop-terminal";
+const TERMINAL_HEADER_CONFIG = "  window_decorations = 'TITLE|RESIZE',\n";
 
 // Absolute icon paths work without an installed icon theme.
 const TERMINAL_ICON_BASE64 = [
@@ -34,6 +42,8 @@ export interface DesktopPanelConfigRequest {
   /** Profile the launcher shares with that browser, so it reuses the window. */
   readonly chromiumProfileDir: string;
   readonly terminalPath: string;
+  readonly fileManagerPath: string;
+  readonly workspaceDir: string;
   readonly debugPort?: number;
 }
 
@@ -50,41 +60,69 @@ export function writeDesktopPanelConfig(
     "product_logo_64.png",
   );
   writeFileSync(terminalIcon, Buffer.from(TERMINAL_ICON_BASE64, "base64"));
+  const terminalConfig = join(configDir, "wezterm", "wezterm.lua");
+  mkdirSync(dirname(terminalConfig), { recursive: true });
+  const terminalConfigContents = `local wezterm = require 'wezterm'
+return {
+  front_end = 'Software',
+  enable_wayland = false,
+  check_for_updates = false,
+  hide_tab_bar_if_only_one_tab = false,
+${TERMINAL_HEADER_CONFIG}  font_size = 11,
+  color_scheme = 'Catppuccin Mocha',
+  initial_cols = 110,
+  initial_rows = 28,
+  keys = {
+    { key = 'd', mods = 'CTRL|SHIFT', action = wezterm.action.SplitHorizontal { domain = 'CurrentPaneDomain' } },
+    { key = 'e', mods = 'CTRL|SHIFT', action = wezterm.action.SplitVertical { domain = 'CurrentPaneDomain' } },
+  },
+}
+`;
+  seedFile(terminalConfig, terminalConfigContents, [
+    terminalConfigContents.replace(TERMINAL_HEADER_CONFIG, ""),
+    ...["", "  integrated_title_buttons = { 'Maximize', 'Close' },\n"].map(
+      (buttons) =>
+        terminalConfigContents.replace(
+          TERMINAL_HEADER_CONFIG,
+          `  window_decorations = 'INTEGRATED_BUTTONS|RESIZE',\n  integrated_title_button_style = 'Gnome',\n${buttons}`,
+        ),
+    ),
+  ]);
 
   const applicationsDir = join(configDir, "applications");
   mkdirSync(applicationsDir, { recursive: true });
   const chromiumEntry = join(applicationsDir, "google-chrome.desktop");
+  // Saved dock pins reference this stable launcher path.
   const terminalEntry = join(applicationsDir, "xterm.desktop");
+  const filesEntry = join(applicationsDir, "thunar.desktop");
   const minesEntry = join(applicationsDir, "org.gnome.Mines.desktop");
   writeFileSync(
     chromiumEntry,
     desktopEntry({
       name: "Google Chrome",
-      // Chrome includes its profile path in WM_CLASS.
-      windowClass: `google-chrome (${request.chromiumProfileDir})`,
+      windowClass: DESKTOP_CHROME_WINDOW_CLASS,
       icon: browserIcon,
-      exec: [
+      exec: desktopCommand([
         request.chromiumPath,
         ...desktopChromeArguments(
           request.chromiumProfileDir,
           request.debugPort,
         ),
-      ]
-        .map(
-          (arg) => `"${arg.replace(/[\\"`$]/g, "\\$&").replace(/%/g, "%%")}"`,
-        )
-        .join(" "),
+      ]),
     }),
   );
   writeFileSync(
     terminalEntry,
     desktopEntry({
       name: "Terminal",
-      windowClass: "XTerm",
+      windowClass: TERMINAL_WINDOW_CLASS,
       icon: terminalIcon,
-      // `-fa` picks a scalable font through fontconfig; xterm otherwise falls
-      // back to the `fixed` bitmap, which is unreadable at this geometry.
-      exec: `"${request.terminalPath}" -fa Monospace -fs 11 -bg '#1c1c22' -fg '#e6e6ea' -title Terminal`,
+      exec: desktopCommand([
+        request.terminalPath,
+        "start",
+        "--new-tab",
+        `--class=${TERMINAL_WINDOW_CLASS}`,
+      ]),
     }),
   );
 
@@ -98,6 +136,37 @@ export function writeDesktopPanelConfig(
     }),
   );
 
+  writeFileSync(
+    filesEntry,
+    desktopEntry({
+      name: "Files",
+      windowClass: "Thunar",
+      icon: "/usr/share/icons/Adwaita/scalable/places/folder.svg",
+      exec: desktopCommand([request.fileManagerPath, request.workspaceDir]),
+    }),
+  );
+
+  const gtkDir = join(configDir, "gtk-3.0");
+  const xfconfDir = join(configDir, "xfce4", "xfconf", "xfce-perchannel-xml");
+  mkdirSync(gtkDir, { recursive: true });
+  mkdirSync(xfconfDir, { recursive: true });
+  seedFile(
+    join(gtkDir, "settings.ini"),
+    "[Settings]\ngtk-theme-name=Adwaita\ngtk-icon-theme-name=Adwaita\ngtk-application-prefer-dark-theme=true\ngtk-font-name=Sans 11\n",
+  );
+  seedFile(
+    join(gtkDir, "bookmarks"),
+    `${pathToFileURL(request.workspaceDir).href} Workspace\n`,
+  );
+  seedFile(
+    join(xfconfDir, "thunar.xml"),
+    `<channel name="thunar" version="1.0">
+  <property name="last-window-width" type="int" value="1000"/>
+  <property name="last-window-height" type="int" value="680"/>
+  <property name="last-view" type="string" value="ThunarDetailsView"/>
+</channel>\n`,
+  );
+
   const launchersDir = join(configDir, "plank", "dock1", "launchers");
   const settingsDir = join(configDir, "glib-2.0", "settings");
   mkdirSync(launchersDir, { recursive: true });
@@ -107,13 +176,14 @@ export function writeDesktopPanelConfig(
     return;
   }
   seedFile(join(launchersDir, "chrome.dockitem"), dockItem(chromiumEntry));
+  seedFile(join(launchersDir, "files.dockitem"), dockItem(filesEntry));
   seedFile(join(launchersDir, "terminal.dockitem"), dockItem(terminalEntry));
   seedFile(join(launchersDir, "mines.dockitem"), dockItem(minesEntry));
   seedFile(
     join(settingsDir, "keyfile"),
     [
       "[net/launchpad/plank/docks/dock1]",
-      "dock-items=['chrome.dockitem', 'terminal.dockitem', 'mines.dockitem']",
+      "dock-items=['chrome.dockitem', 'files.dockitem', 'terminal.dockitem', 'mines.dockitem']",
       "icon-size=48",
       "hide-mode='none'",
       "theme='Matte'",
@@ -127,7 +197,25 @@ function dockItem(launcher: string): string {
   return `[PlankDockItemPreferences]\nLauncher=${pathToFileURL(launcher).href}\n`;
 }
 
-function seedFile(path: string, contents: string): void {
+function desktopCommand(args: string[]): string {
+  return args
+    .map((arg) => {
+      const quoted = `"${arg.replace(/[\\"`$]/g, "\\$&").replace(/%/g, "%%")}"`;
+      // Desktop values are unescaped before Exec arguments are parsed.
+      return quoted
+        .replace(/\\/g, "\\\\")
+        .replace(/\n/g, "\\n")
+        .replace(/\r/g, "\\r")
+        .replace(/\t/g, "\\t");
+    })
+    .join(" ");
+}
+
+function seedFile(
+  path: string,
+  contents: string,
+  previousContents: readonly string[] = [],
+): void {
   const temporaryPath = `${path}.${randomUUID()}.tmp`;
   try {
     writeFileSync(temporaryPath, contents, { flush: true });
@@ -137,6 +225,12 @@ function seedFile(path: string, contents: string): void {
     if ((err as NodeJS.ErrnoException).code !== "EEXIST") {
       throw err;
     }
+    if (
+      previousContents.length > 0 &&
+      previousContents.includes(readFileSync(path, "utf8"))
+    ) {
+      renameSync(temporaryPath, path);
+    }
   } finally {
     rmSync(temporaryPath, { force: true });
   }

package/src/desktop/desktop-session-manager.test.ts

@@ -219,6 +219,7 @@ describe("DesktopSessionManager process tree", () => {
     expect(x[x.indexOf("-rfbport") + 1]).toBe(String(DESKTOP_VNC_PORT));
     expect(x[x.indexOf("-geometry") + 1]).toBe("1600x900");
     for (const role of [
+      "session-bus",
       "window-manager",
       "compositor",
       "clipboard",
@@ -229,6 +230,8 @@ describe("DesktopSessionManager process tree", () => {
         HOME: "/data",
         LANG: "C.UTF-8",
         DISPLAY: ":99",
+        XDG_CONFIG_HOME: panelConfigDir,
+        XDG_DATA_HOME: panelConfigDir,
         DBUS_SESSION_BUS_ADDRESS: h.manager.accessibilityBusAddress,
         NO_AT_BRIDGE: "0",
         GTK_A11Y: "atspi",
@@ -280,7 +283,7 @@ describe("DesktopSessionManager process tree", () => {
         "plank",
         "tigervncconfig",
         "vncconfig",
-        "xterm",
+        "wezterm",
       ],
     });
     await expect(h.manager.ensureDesktopRunning()).rejects.toThrow(
@@ -306,7 +309,7 @@ describe("DesktopSessionManager process tree", () => {
       join(panelConfigDir, "applications", "xterm.desktop"),
       "utf8",
     );
-    expect(terminal).toContain(`Exec="/usr/bin/xterm"`);
+    expect(terminal).toContain(`Exec="/usr/bin/wezterm"`);
     expect(terminal).toContain(`Icon=${join(panelConfigDir, "terminal.png")}`);
 
     const bytes = readFileSync(join(panelConfigDir, "terminal.png"));

package/src/desktop/desktop-session-manager.ts

@@ -11,13 +11,11 @@ import { mkdirSync, writeFileSync } from "node:fs";
 import { createConnection } from "node:net";
 import { join } from "node:path";
 
-import { readAvatarState } from "../avatar/avatar-manifest.js";
-import { resolveNotificationAccentHex } from "../avatar/notification-avatar.js";
 import { getIsContainerized } from "../config/env-registry.js";
 import { connectCdpWsTransport } from "../tools/browser/cdp-client/cdp-inspect/ws-transport.js";
 import { terminateProcessTree } from "../util/host-process.js";
 import { getLogger } from "../util/logger.js";
-import { getDataDir } from "../util/platform.js";
+import { getDataDir, getWorkspaceDir } from "../util/platform.js";
 import { sleep } from "../util/retry.js";
 import { DesktopBrowserClient } from "./desktop-browser-client.js";
 import {
@@ -358,11 +356,7 @@ export class DesktopSessionManager {
       ((configDir) => {
         let sourcePath: string | undefined;
         try {
-          sourcePath = writeDesktopWindowTheme(
-            configDir,
-            this.sourceEnv.HOME,
-            resolveNotificationAccentHex(readAvatarState()),
-          );
+          sourcePath = writeDesktopWindowTheme(configDir, this.sourceEnv.HOME);
         } catch (err) {
           log.warn({ err }, "Desktop window theme could not be applied");
         }
@@ -651,11 +645,11 @@ export class DesktopSessionManager {
         chromiumProfileDir: this.profileDir,
         debugPort: this.debugPort,
         terminalPath: binaries.terminal,
+        fileManagerPath: binaries.fileManager,
+        workspaceDir: getWorkspaceDir(),
       });
       this.launch("panel", [binaries.panel], {
         ...env,
-        XDG_CONFIG_HOME: this.panelConfigDir,
-        XDG_DATA_HOME: this.panelConfigDir,
         GSETTINGS_BACKEND: "keyfile",
       });
     } catch (err) {
@@ -882,6 +876,9 @@ export class DesktopSessionManager {
       }
     }
     env.DISPLAY = DESKTOP_DISPLAY;
+    // D-Bus services share app preferences and launchers.
+    env.XDG_CONFIG_HOME = this.panelConfigDir;
+    env.XDG_DATA_HOME = this.panelConfigDir;
     env.DBUS_SESSION_BUS_ADDRESS = this.accessibilityBusAddress;
     env.NO_AT_BRIDGE = "0";
     env.GTK_A11Y = "atspi";

package/src/desktop/desktop-window-theme.ts

@@ -13,24 +13,7 @@ const BUTTON_MASKS = {
   iconify: [0, 0, 0, 0, 0x3ff, 0x3ff, 0, 0, 0, 0],
 };
 
-function windowTheme(accentHex: string | null): string {
-  const tint = (base: string, amount: number): string => {
-    if (!accentHex || !/^#[\da-f]{6}$/i.test(accentHex)) {
-      return base;
-    }
-    return (
-      "#" +
-      [1, 3, 5]
-        .map((offset) => {
-          const from = parseInt(base.slice(offset, offset + 2), 16);
-          const to = parseInt(accentHex.slice(offset, offset + 2), 16);
-          return Math.round(from + (to - from) * amount)
-            .toString(16)
-            .padStart(2, "0");
-        })
-        .join("")
-    );
-  };
+function windowTheme(): string {
   return `
 border.width: 1
 padding.width: 8
@@ -47,17 +30,15 @@ window.*.grip.bg: Flat Solid
 window.*.button.*.bg: Parentrelative
 window.*.button.*.hover.bg: Flat Solid
 window.*.button.*.pressed.bg: Flat Solid
-window.active.title.bg: Flat Gradient Horizontal
-window.active.title.bg.color: ${tint("#292930", 0.28)}
-window.active.title.bg.colorTo: #292930
+window.active.title.bg.color: #292930
 window.active.border.color: #4a4a54
 window.active.title.separator.color: #202026
 window.active.label.text.color: #f0f0f4
 window.active.handle.bg.color: #292930
 window.active.grip.bg.color: #292930
 window.active.button.*.image.color: #d4d4dc
-window.active.button.*.hover.bg.color: ${tint("#45454f", 0.22)}
-window.active.button.*.pressed.bg.color: ${tint("#555561", 0.18)}
+window.active.button.*.hover.bg.color: #45454f
+window.active.button.*.pressed.bg.color: #555561
 window.active.button.*.disabled.image.color: #62626e
 window.active.button.close.hover.bg.color: #b64150
 window.active.button.close.pressed.bg.color: #963442
@@ -97,7 +78,6 @@ osd.label.text.color: #f0f0f4
 export function writeDesktopWindowTheme(
   configDir: string,
   home?: string,
-  accentHex: string | null = null,
 ): string {
   let source: string | undefined;
   let sourcePath = "";
@@ -134,7 +114,7 @@ export function writeDesktopWindowTheme(
   mkdirSync(join(themeDir, "openbox-3"), { recursive: true });
   writeFileSync(
     join(themeDir, "openbox-3", "themerc"),
-    windowTheme(accentHex).trimStart(),
+    windowTheme().trimStart(),
   );
   for (const [name, rows] of Object.entries(BUTTON_MASKS)) {
     const bytes = rows.flatMap((row) => [row & 0xff, row >> 8]);

package/src/workspace/migrations/157-add-desktop-files-launcher.ts

@@ -0,0 +1,94 @@
+import {
+  linkSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import type { WorkspaceMigration } from "./types.js";
+
+export const addDesktopFilesLauncherMigration: WorkspaceMigration = {
+  id: "157-add-desktop-files-launcher",
+  description: "Add Files to existing virtual desktop docks",
+  retryFailedCheckpoint: true,
+  run(workspaceDir): void {
+    const configDir = join(workspaceDir, "data", "desktop-panel");
+    const settingsPath = join(configDir, "glib-2.0", "settings", "keyfile");
+    let settings: string;
+    try {
+      settings = readFileSync(settingsPath, "utf8");
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        return;
+      }
+      throw err;
+    }
+
+    const section =
+      /(?:^|\n)\[net\/launchpad\/plank\/docks\/dock1\]\r?\n([^]*?)(?=\n\[|$)/;
+    const match = settings.match(section);
+    if (!match) {
+      return;
+    }
+    const pins = /^(dock-items\s*=\s*)(?:@as\s+)?\[([^\r\n]*)\](\r?)$/m;
+    const existing = match[1]!.match(pins);
+    if (existing && !existing[2]!.includes("'files.dockitem'")) {
+      const items = existing[2]!.trim();
+      let updatedItems: string;
+      if (items.includes("'chrome.dockitem'")) {
+        updatedItems = items.replace(
+          "'chrome.dockitem'",
+          "'chrome.dockitem', 'files.dockitem'",
+        );
+      } else if (items.includes("'terminal.dockitem'")) {
+        updatedItems = items.replace(
+          "'terminal.dockitem'",
+          "'files.dockitem', 'terminal.dockitem'",
+        );
+      } else {
+        updatedItems = `${items}${items ? ", " : ""}'files.dockitem'`;
+      }
+      const updated = match[0].replace(
+        pins,
+        () => `${existing[1]}[${updatedItems}]${existing[3]}`,
+      );
+      settings = settings.replace(section, () => updated);
+    } else if (!existing) {
+      settings = settings.replace(
+        section,
+        () =>
+          `${match[0]}${match[0].endsWith("\n") ? "" : "\n"}dock-items=['files.dockitem']\n`,
+      );
+    }
+
+    const launchersDir = join(configDir, "plank", "dock1", "launchers");
+    mkdirSync(launchersDir, { recursive: true });
+    const launcher = pathToFileURL(
+      join(configDir, "applications", "thunar.desktop"),
+    ).href;
+    const pinPath = join(launchersDir, "files.dockitem");
+    const pinTemporaryPath = `${pinPath}.migration.tmp`;
+    try {
+      writeFileSync(
+        pinTemporaryPath,
+        `[PlankDockItemPreferences]\nLauncher=${launcher}\n`,
+        { flush: true },
+      );
+      linkSync(pinTemporaryPath, pinPath);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "EEXIST") {
+        throw err;
+      }
+    } finally {
+      rmSync(pinTemporaryPath, { force: true });
+    }
+    const temporaryPath = `${settingsPath}.files-migration.tmp`;
+    writeFileSync(temporaryPath, settings, { flush: true });
+    renameSync(temporaryPath, settingsPath);
+  },
+  down(): void {},
+};

package/src/workspace/migrations/__tests__/156-extract-workspace-mcp-json.test.ts

@@ -3,9 +3,12 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { describe, expect, test } from "bun:test";
 
-import { extractWorkspaceMcpJsonMigration } from "../156-extract-workspace-mcp-json.js";
 import { WORKSPACE_MIGRATIONS } from "../registry.js";
 
+const extractWorkspaceMcpJsonMigration = WORKSPACE_MIGRATIONS.find(
+  (migration) => migration.id === "156-extract-workspace-mcp-json",
+)!;
+
 const MIGRATION_156_SCHEMA_URL =
   "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
 
@@ -23,15 +26,6 @@ function readJson(dir: string, name: string): Record<string, unknown> {
 }
 
 describe("156-extract-workspace-mcp-json", () => {
-  test("has the next migration id and is registered last", () => {
-    expect(extractWorkspaceMcpJsonMigration.id).toBe(
-      "156-extract-workspace-mcp-json",
-    );
-    expect(WORKSPACE_MIGRATIONS.at(-1)?.id).toBe(
-      "156-extract-workspace-mcp-json",
-    );
-  });
-
   test("moves servers into a spec-pure mcp.json and drops mcp from config", () => {
     const dir = workspaceWith({
       llm: { activeProfile: "balanced" },

package/src/workspace/migrations/__tests__/157-add-desktop-files-launcher.test.ts

@@ -0,0 +1,113 @@
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterEach, expect, test } from "bun:test";
+
+import { writeDesktopPanelConfig } from "../../../desktop/desktop-panel-config.js";
+import { WORKSPACE_MIGRATIONS } from "../registry.js";
+
+const migration = WORKSPACE_MIGRATIONS.find(
+  (entry) => entry.id === "157-add-desktop-files-launcher",
+)!;
+
+const workspaces: string[] = [];
+afterEach(() => {
+  for (const workspace of workspaces.splice(0)) {
+    rmSync(workspace, { recursive: true, force: true });
+  }
+});
+
+function setup() {
+  const workspace = mkdtempSync(join(tmpdir(), "desktop-files-migration-"));
+  workspaces.push(workspace);
+  const configDir = join(workspace, "data", "desktop-panel");
+  const settingsPath = join(configDir, "glib-2.0", "settings", "keyfile");
+  return { workspace, configDir, settingsPath };
+}
+
+test("upgrades a customized dock idempotently and respects later unpinning", () => {
+  const { workspace, configDir, settingsPath } = setup();
+  mkdirSync(dirname(settingsPath), { recursive: true });
+  const original =
+    "[unrelated]\nvalue=keep\n\n[net/launchpad/plank/docks/dock1]\ndock-items=['chrome.dockitem', 'terminal.dockitem', 'custom.dockitem']\nicon-size=64\n\n[another]\ndock-items=['other.dockitem']\n";
+  writeFileSync(settingsPath, original);
+  migration.run(workspace);
+  const upgraded = readFileSync(settingsPath, "utf8");
+  expect(upgraded).toBe(
+    original.replace(
+      "'chrome.dockitem', 'terminal.dockitem'",
+      "'chrome.dockitem', 'files.dockitem', 'terminal.dockitem'",
+    ),
+  );
+  migration.run(workspace);
+  expect(readFileSync(settingsPath, "utf8")).toBe(upgraded);
+  const pin = join(configDir, "plank", "dock1", "launchers", "files.dockitem");
+  expect(readFileSync(pin, "utf8")).toContain("/applications/thunar.desktop");
+  rmSync(pin);
+  writeFileSync(settingsPath, original);
+  writeDesktopPanelConfig({
+    configDir,
+    chromiumPath: "/opt/chrome/chrome",
+    chromiumProfileDir: join(workspace, "profile"),
+    terminalPath: "/usr/bin/wezterm",
+    fileManagerPath: "/usr/bin/thunar",
+    workspaceDir: workspace,
+  });
+  expect(existsSync(pin)).toBe(false);
+  expect(readFileSync(settingsPath, "utf8")).toBe(original);
+  expect(existsSync(join(configDir, "applications", "thunar.desktop"))).toBe(
+    true,
+  );
+});
+
+test.each(["[]", "@as []"])(
+  "upgrades an empty dock (%s) and recovers an existing pin",
+  (items) => {
+    const { workspace, configDir, settingsPath } = setup();
+    mkdirSync(dirname(settingsPath), { recursive: true });
+    writeFileSync(
+      settingsPath,
+      `[net/launchpad/plank/docks/dock1]\ndock-items=${items}\n`,
+    );
+    const pin = join(
+      configDir,
+      "plank",
+      "dock1",
+      "launchers",
+      "files.dockitem",
+    );
+    mkdirSync(dirname(pin), { recursive: true });
+    writeFileSync(pin, "user launcher");
+    migration.run(workspace);
+    expect(readFileSync(settingsPath, "utf8")).toContain(
+      "dock-items=['files.dockitem']",
+    );
+    expect(readFileSync(pin, "utf8")).toBe("user launcher");
+  },
+);
+
+test("does not initialize a desktop for workspaces without one", () => {
+  const { workspace, configDir } = setup();
+  migration.run(workspace);
+  expect(existsSync(configDir)).toBe(false);
+});
+
+test("adds an implicit dock pin list inside the correct settings section", () => {
+  const { workspace, settingsPath } = setup();
+  mkdirSync(dirname(settingsPath), { recursive: true });
+  writeFileSync(
+    settingsPath,
+    "[unrelated]\nvalue=keep\n[net/launchpad/plank/docks/dock1]\nicon-size=64\n[next]\nvalue=also-keep\n",
+  );
+  migration.run(workspace);
+  expect(readFileSync(settingsPath, "utf8")).toBe(
+    "[unrelated]\nvalue=keep\n[net/launchpad/plank/docks/dock1]\nicon-size=64\ndock-items=['files.dockitem']\n\n[next]\nvalue=also-keep\n",
+  );
+});

package/src/workspace/migrations/registry.ts

@@ -154,6 +154,7 @@ import { stripMcpPolicyFieldsMigration } from "./153-strip-mcp-policy-fields.js"
 import { repairRetiredCodexGpt54ModelIdsMigration } from "./154-repair-retired-codex-gpt-5-4-model-ids.js";
 import { moveFrontModelConfigToVoiceMigration } from "./155-move-front-model-config-to-voice.js";
 import { extractWorkspaceMcpJsonMigration } from "./156-extract-workspace-mcp-json.js";
+import { addDesktopFilesLauncherMigration } from "./157-add-desktop-files-launcher.js";
 import { migrateToWorkspaceVolumeMigration } from "./migrate-to-workspace-volume.js";
 import type { WorkspaceMigration } from "./types.js";
 
@@ -323,4 +324,5 @@ export const WORKSPACE_MIGRATIONS: WorkspaceMigration[] = [
   repairRetiredCodexGpt54ModelIdsMigration,
   moveFrontModelConfigToVoiceMigration,
   extractWorkspaceMcpJsonMigration,
+  addDesktopFilesLauncherMigration,
 ];