@vellumai/assistant 0.12.2-dev.202609210049.b9f03ca → 0.12.2-dev.202609210132.d52247f

package/docs/desktop-browser-cli.md

@@ -58,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.202609210049.b9f03ca",
+  "version": "0.12.2-dev.202609210132.d52247f",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/desktop/desktop-dependencies.ts

@@ -44,16 +44,21 @@ const DESKTOP_BINARIES = {
   sessionBus: ["dbus-daemon"],
   clipboard: ["tigervncconfig", "vncconfig"],
   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",
@@ -129,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") &&

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

@@ -34,6 +34,8 @@ test("initializes the dock and preserves user changes across restarts", () => {
     chromiumPath: "/opt/chrome-v1/chrome",
     chromiumProfileDir: profileDir,
     terminalPath: "/usr/bin/wezterm",
+    fileManagerPath: "/usr/bin/thunar",
+    workspaceDir: workspace,
   };
   writeDesktopPanelConfig(request);
   const settingsPath = join(configDir, "glib-2.0", "settings", "keyfile");
@@ -94,6 +96,8 @@ test("initialization recovers partial pin creation", () => {
     chromiumPath: "/opt/chrome/chrome",
     chromiumProfileDir: join(workspace, "data", "desktop-profile"),
     terminalPath: "/usr/bin/wezterm",
+    fileManagerPath: "/usr/bin/thunar",
+    workspaceDir: workspace,
   });
   expect(readFileSync(join(pinsDir, "chrome.dockitem"), "utf8")).toBe(
     "existing pin",
@@ -116,6 +120,8 @@ test("a failed settings write leaves initialization retryable", () => {
     chromiumPath: "/opt/chrome/chrome",
     chromiumProfileDir: join(workspace, "data", "desktop-profile"),
     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

@@ -42,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;
 }
 
@@ -92,6 +94,7 @@ ${TERMINAL_HEADER_CONFIG}  font_size = 11,
   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,
@@ -133,6 +136,37 @@ ${TERMINAL_HEADER_CONFIG}  font_size = 11,
     }),
   );
 
+  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 });
@@ -142,13 +176,14 @@ ${TERMINAL_HEADER_CONFIG}  font_size = 11,
     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'",
@@ -164,7 +199,15 @@ function dockItem(launcher: string): string {
 
 function desktopCommand(args: string[]): string {
   return args
-    .map((arg) => `"${arg.replace(/[\\"`$]/g, "\\$&").replace(/%/g, "%%")}"`)
+    .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(" ");
 }
 

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

@@ -230,6 +230,7 @@ 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",

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

@@ -15,7 +15,7 @@ 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 {
@@ -645,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) {
@@ -876,7 +876,8 @@ export class DesktopSessionManager {
       }
     }
     env.DISPLAY = DESKTOP_DISPLAY;
-    // D-Bus-activated window matching must see the same launchers as Plank.
+    // 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";

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,
 ];